add project ai instructions

Document Attainly-specific TDD, worktree, Laravel, database, and future Vue conventions adapted from the youngstartup workflow.

ai/backend-context.md

@@ -0,0 +1,105 @@
+# Backend context
+
+Read `ai/shared.md` first. This file covers backend-specific rules.
+
+## Project context
+
+**Stack:** PHP 8.4, Laravel 13, Inertia Laravel, PHPUnit, Larastan, Composer.
+
+**Location:** `backend/`.
+
+The application is still close to the Laravel starter structure. Do not
+introduce a domain architecture, repository layer, service layer, or other
+abstraction before the codebase and requested behavior justify it. Match
+existing Laravel conventions and inspect similar code before adding a new
+pattern.
+
+## Laravel patterns
+
+- Keep controllers thin. Put reusable business behavior in an appropriately
+  named application or domain class once the behavior warrants extraction.
+- Use dedicated request validation rather than validating substantial payloads
+  inline in controllers.
+- Let unexpected exceptions reach Laravel's exception handler. Catch only
+  exceptions that can be handled meaningfully at the current boundary.
+- Use Eloquent relationships and query scopes consistently rather than
+  duplicating query fragments.
+- Avoid speculative interfaces and abstractions with only one trivial
+  implementation.
+- Routes currently use Inertia, but the Vue client has not been scaffolded.
+  Do not add placeholder frontend assets as part of unrelated backend work.
+
+## Tests
+
+- Follow the existing PHPUnit organization under `tests/Unit/` and
+  `tests/Feature/`.
+- Prefer `PHPUnit\Framework\TestCase` when a test only exercises plain PHP.
+- Extend `Tests\TestCase` only when the test needs Laravel's container,
+  facades, database, routing, or HTTP kernel.
+- HTTP feature tests extend `Tests\TestCase`.
+- Use `RefreshDatabase` when a test reads or writes database state.
+- Assert behavior at the appropriate seam:
+  - Unit tests cover isolated business behavior and edge cases.
+  - Feature tests cover routing, middleware, validation, persistence, and
+    response shape.
+- Do not duplicate every business branch through the HTTP layer when unit
+  coverage already proves it. Feature tests should focus on wiring and the
+  public contract.
+
+## Test database
+
+- Development and runtime use PostgreSQL through the local Unix socket.
+- PHPUnit intentionally uses SQLite `:memory:` as configured in
+  `phpunit.xml`.
+- Feature tests are self-contained and do not require the process-compose
+  PostgreSQL service.
+- Never point `RefreshDatabase` tests at the development PostgreSQL database.
+- Keep mail set to the PHPUnit `array` transport unless a test explicitly
+  exercises a real mail integration.
+
+## PHP rules
+
+- Put imports at the top of the file. Do not use inline fully qualified class
+  names when a normal `use` statement is clearer.
+- Do not use arrow functions. Use regular anonymous functions.
+- Do not add default values to function or constructor parameters. Pass every
+  argument explicitly, including nullable arguments.
+- Use descriptive names for classes, methods, parameters, and local
+  variables.
+- Document exceptions with `@throws` when a caller is expected to handle
+  them.
+
+## Seeders
+
+- Keep `DatabaseSeeder` as the orchestrator.
+- Split substantial seed data into one seeder per domain concept and invoke
+  them in dependency order.
+- Do not add production repository or model APIs solely to make seeding
+  convenient.
+- Use existing lookup methods for cross-seeder relationships. When a group of
+  records only makes sense together, keep them in one seeder and retain local
+  references.
+
+## Migrations
+
+- Attainly is not in production yet.
+- While no production database exists, edit the original `create_*` migration
+  when changing a table instead of accumulating follow-up alter migrations.
+- Keep one migration file per table during this pre-production phase.
+- Rebuild the development database with:
+
+  ```sh
+  php artisan migrate:fresh --seed
+  ```
+
+- Once a production database exists, replace this policy with additive,
+  forward-only migrations.
+
+## Before completing backend work
+
+- Run the focused test during development.
+- Run `php artisan test` before completion.
+- Run the Composer lint and static-analysis scripts when their dependencies
+  are available.
+- Fix failures caused by the change. Report unrelated baseline failures
+  precisely rather than hiding them or expanding scope without authorization.