TenantAtlas/specs/102-filament-5-2-1-upgrade/plan.md

Implementation Plan: Filament v5.2.1 Upgrade

Branch: feat/102-filament-5-2-1-upgrade | Date: 2026-02-20 | Spec: specs/102-filament-5-2-1-upgrade/spec.md Input: Feature specification from /specs/102-filament-5-2-1-upgrade/spec.md

Summary

Upgrade Filament to v5.2.1 (or newer within 5.2.x) as a dependency-only change.

Verification gates (per spec clarifications):

• Automated: full test suite + frontend build
• Manual: staging UI smoke (Admin /admin/* + System /system/* if present)

No application feature work, no schema changes, and no new Graph calls are in scope.

Technical Context

Language/Version: PHP 8.4.x (runtime), Composer constraint php: ^8.2
Primary Dependencies: Laravel 12, Filament 5, Livewire 4
Storage: PostgreSQL (Sail), plus filesystem storage for logs/cache
Testing: Pest (via artisan test)
Target Platform: Web application (Sail locally; Dokploy containers in staging/prod)
Project Type: web
Performance Goals: N/A (dependency-only patch upgrade)
Constraints:

• Dependency-only changes (Composer-only). No application code changes for compatibility.
• Test-only changes in tests/** are allowed if needed to keep the suite green; no runtime behavior changes.
• No new panels/routes/resources. No UX/IA changes intended.
• Verification must include /admin and /system (if System panel exists).
• Staging smoke is mandatory.

Scale/Scope: N/A for this change; treat any behavior delta as regression unless it’s a documented upstream bugfix we accept.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Result: PASS

• No new Microsoft Graph calls are introduced.
• No new write/change flows, jobs, or OperationRun patterns are introduced.
• No RBAC model changes are introduced; /admin and /system planes remain separated.
• No new or modified Filament Resources/Pages/RelationManagers are introduced (dependency-only upgrade).

Project Structure

Documentation (this feature)

specs/102-filament-5-2-1-upgrade/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
└── contracts/
   └── README.md

Source Code (repository root)

app/
bootstrap/
config/
resources/
routes/
tests/

Structure Decision: Single Laravel web application (Filament panels live under app/Filament/**).

Phase 0 — Outline & Research

Goal: confirm upgrade target, identify upstream behavior changes, and map them to verification.

Deliverable:

• research.md capturing decisions + rationale + alternatives (completed)

Key research topics:

• Filament v5.2.0 → v5.2.1 release notes:
  • tenancy registration behavior when tenancy is not active
  • bulk “Select all” excluding non-selectable records
  • corrected guidance around testing assertion replacement

Phase 1 — Design & Contracts

This is a dependency-only upgrade; design outputs focus on explicitly stating “no contract changes” and providing a verification/rollback runbook.

Deliverables:

• data-model.md (completed; explicitly no schema/entity changes)
• contracts/README.md (completed; explicitly no API/Graph contract changes)
• quickstart.md (completed; verification + rollback runbook)

Agent context update (required):

• Run .specify/scripts/bash/update-agent-context.sh copilot after Phase 1 outputs exist.

Post-design constitution re-check:

• Still PASS (no new app code introduced).

Phase 2 — Implementation Task Planning (for /speckit.tasks)

Planned task breakdown (to be materialized into tasks.md via /speckit.tasks):

1. Composer upgrade tasks

• Bump filament/filament constraint to ^5.2.1
• Resolve plugin constraints (Composer-only)
• Run php artisan filament:upgrade if required by Filament upgrade guidance

2. Verification tasks (automated)

• Run vendor/bin/sail artisan test --compact
• Run vendor/bin/sail npm run build

3. Verification tasks (manual)

• Staging deploy
• Staging UI smoke (Admin + System panels)

4. Rollback tasks

• Document exact rollback steps in PR description (linked to quickstart.md)