# 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)

```text
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)

```text
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`)