# TenantPilot AI Coding Rules

Status: 2026-05-15
Use for: Codex, Claude, Cursor, Windsurf, and other AI coding agents.

## Stack

- PHP 8.4.15 runtime; Composer constraint currently `^8.2`.
- Laravel 12.52.
- Filament 5.2.1 with required upgrade target >=5.3.5 because of advisory.
- Livewire 4.1.4. Never propose Livewire v3 APIs.
- Tailwind CSS 4.2.2 with Vite 7.3.2.
- PostgreSQL 16 via Sail/Dokploy.
- Pest 4.3 and PHPUnit 12.
- Queue/cache default to database locally; Redis is available.

## Mandatory First Reads

- `AGENTS.md`
- `.specify/memory/constitution.md`
- Relevant `specs/<NNN>-<slug>/spec.md`, `plan.md`, `tasks.md`
- `docs/research/filament-v5-notes.md` for Filament uncertainty
- Relevant guideline file in `docs/*-guidelines.md`

## Forbidden APIs and Patterns

- No Filament v3/v4 APIs.
- No Livewire v3 references.
- No panel providers in `bootstrap/app.php`; Laravel 12 panel providers belong in `bootstrap/providers.php`.
- No Graph calls outside `GraphClientInterface`.
- No Graph calls during UI render.
- No destructive action without `->action(...)`, `->requiresConfirmation()`, authorization, audit, and test.
- No business-critical logic buried in Filament closures.
- No public/local uploaded filenames from `preserveFilenames()` without approved mitigation.
- No new persisted entity, enum/status family, abstraction, or taxonomy without constitution proportionality review.
- No new package without package-governance review.

## Architecture Rules

- Filament is UI composition.
- Services/actions own business behavior.
- Jobs own remote/long-running work.
- Policies/gates own authorization.
- Models own persistence relationships, casts, scopes, and small invariants.
- Migrations own integrity through constraints and indexes.
- Tenant-owned data must always be workspace- and tenant-scoped.

## Filament Rules

- Every globally searchable resource needs a View or Edit page and `$recordTitleAttribute`; otherwise disable global search.
- Tables need default sort, domain-specific empty state, and query-safe columns.
- Relationship columns require eager loading or query optimization.
- Use `UiEnforcement` or `WorkspaceUiEnforcement` for capability-aware action state.
- Prefer render hooks and CSS hook classes over publishing Filament internals.
- Add `php artisan filament:assets` to deployment when Filament assets are registered.

## Testing Rules

- Use Pest 4.
- Test pages/relation managers/widgets as Livewire components.
- Use Filament action helpers for action tests.
- Add policy tests for new policies.
- Add tenant isolation tests for tenant-owned models.
- Use PostgreSQL lane for JSONB, partial indexes, locks, composite FKs, and migrations.
- Browser tests are for critical workflows and JS/visual smoke, not every CRUD page.

## Security Rules

- Deny unauthorized workspace/tenant access as not found.
- Never log secrets, tokens, raw credential payloads, or raw sensitive Graph payloads.
- Provider credentials use encrypted storage.
- File uploads default to private disks, random names, MIME/size validation, and tamper prevention when applicable.
- Production requires `APP_DEBUG=false`.
- Dependency audits must be clean or explicitly accepted.

## Performance Rules

- Use JSONB for queryable snapshot, backup, restore, evidence, and audit payloads.
- Add indexes for proven query paths only.
- Move Graph, restore, backup, export, and report work to queues.
- Make jobs idempotent and observable through `OperationRun`.
- Honor Microsoft Graph `Retry-After`; use exponential backoff with jitter when missing.

## Response Format for AI Code Changes

Every implementation response must state:

1. Livewire v4 compliance.
2. Panel provider location if Filament panel code changed.
3. Global search status for changed resources.
4. Destructive/high-impact actions and how confirmation + authorization + audit are handled.
5. Asset strategy and whether `filament:assets` is required.
6. Tests run and tests added/updated.
7. Deployment impact: env, migrations, queues, scheduler, storage.