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

---

description: "Task breakdown for Filament v5.2.1 upgrade (dependency-only)"
---

# Tasks: Filament v5.2.1 Upgrade

**Input**: Design documents from `/specs/102-filament-5-2-1-upgrade/`  
**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/, quickstart.md

**Organization**: Tasks are grouped by user story (US1–US3) so each story can be independently verified.

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Ensure the feature workspace is ready and the plan/spec artifacts are the source of truth.

- [X] T001 Verify spec artifacts exist and are consistent in `specs/102-filament-5-2-1-upgrade/{spec.md,plan.md,research.md,quickstart.md,data-model.md,contracts/README.md}`
- [X] T002 Capture current baseline dependency state by recording the pre-upgrade contents of `composer.json` and `composer.lock` (for rollback comparison)
- [X] T003 [P] Confirm local tooling entrypoints are present for verification (`vendor/bin/sail`, `package.json`, `vite.config.js`)

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Establish the verification baseline and guardrails before touching dependencies.

**⚠️ CRITICAL**: No Filament upgrade work begins until this phase completes.

- [X] T004 Ensure local environment is runnable via Sail using `docker-compose.yml` (containers up, app boots)
- [X] T005 Run Composer sanity checks before upgrading (`vendor/bin/sail composer validate`) against `composer.json`
- [X] T006 Run Node dependency install for a clean build baseline using npm (`vendor/bin/sail npm ci`) with `package-lock.json`
- [X] T007 Establish a green baseline on current mainline by running `vendor/bin/sail artisan test --compact` for `tests/` (record failures; do not proceed if baseline is red)
- [X] T008 Establish a green baseline frontend build by running `vendor/bin/sail npm run build` from `package.json` (do not proceed if baseline build fails)

**Checkpoint**: Baseline is green; dependency upgrade work can begin.

---

## Phase 3: User Story 1 — Ship the patch upgrade safely (Priority: P1) 🎯 MVP

**Goal**: Upgrade Filament to v5.2.1 (5.2.x) as a dependency-only change and keep automated verification green.

**Independent Test**: `vendor/bin/sail artisan test --compact` passes and `vendor/bin/sail npm run build` succeeds; app boots without runtime errors in Admin/System panels.

### Implementation for User Story 1

- [X] T009 [US1] Update Filament constraint to `^5.2.1` in `composer.json`
- [X] T010 [US1] Update dependencies and lockfile using Sail Composer (targeted) after `composer.json` change: `vendor/bin/sail composer update filament/filament --with-all-dependencies --no-interaction` (changes limited to `composer.json` and `composer.lock`)
- [X] T011 [US1] If Composer resolution requires it, bump Filament plugins/extensions in `composer.json` (Composer-only) and re-resolve `composer.lock`
- [ ] T012 [P] [US1] Verify the diff is dependency-only: no changes under `app/`, `config/`, `routes/`, `resources/` (excluding lockfile-related artifacts)
- [X] T013 [P] [US1] Run `vendor/bin/sail composer install` to confirm `composer.lock` is reproducible
- [X] T014 [P] [US1] Run automated regression suite: `vendor/bin/sail artisan test --compact` for `tests/`
- [X] T015 [P] [US1] Run frontend build: `vendor/bin/sail npm run build` using `package.json`
- [X] T016 [US1] If tests fail due to assertion/deprecation changes, update only the failing tests in `tests/**` (no runtime code changes) until the suite is green
- [X] T017 [US1] Confirm Filament upgrade automation did not introduce unintended code changes; if `composer.json` triggers `php artisan filament:upgrade`, ensure no modifications occurred outside dependency scope

**Checkpoint**: Filament v5.2.1 upgrade is complete and automated gate is green.

---

## Phase 4: User Story 2 — Validate core admin workflows (Priority: P2)

**Goal**: Run a short staging UI smoke that targets known risk areas from the upstream patch notes.

**Independent Test**: Complete `specs/102-filament-5-2-1-upgrade/quickstart.md` staging smoke in ≤10 minutes with 0 blocking errors.

### Implementation for User Story 2

- [ ] T018 [US2] Deploy the upgraded artifact to staging and confirm the smoke checklist source is `specs/102-filament-5-2-1-upgrade/quickstart.md`
- [ ] T019 [US2] Smoke: login/logout and panel access for Admin (`/admin/*`) and System (`/system/*`, if present) per `specs/102-filament-5-2-1-upgrade/spec.md`
- [ ] T020 [US2] Smoke: navigate key Monitoring areas starting from `app/Filament/Clusters/Monitoring/` and confirm pages render without runtime errors
- [ ] T021 [US2] Smoke: validate tenancy behavior aligns with upstream fix (no tenancy registered when not active) using the checklist in `specs/102-filament-5-2-1-upgrade/quickstart.md` and upstream mapping in `specs/102-filament-5-2-1-upgrade/research.md`
- [ ] T022 [US2] Smoke: validate table bulk actions + “Select all” on concrete list pages that implement it: `app/Filament/Resources/InventoryItemResource/Pages/ListInventoryItems.php` and `app/Filament/Resources/RestoreRunResource/Pages/ListRestoreRuns.php` (also confirm non-selectable rows are excluded if applicable)
- [ ] T023 [US2] Smoke: validate create/edit modals and confirmation dialogs still render and complete successfully (no JS/runtime errors) per `specs/102-filament-5-2-1-upgrade/quickstart.md`

**Checkpoint**: Staging smoke passes and upgrade is go/no-go ready.

---

## Phase 5: User Story 3 — Roll back confidently if needed (Priority: P3)

**Goal**: Ensure rollback is concrete, accurate, and fast.

**Independent Test**: Another engineer can follow the rollback steps and restore the previous dependency set.

### Implementation for User Story 3

- [ ] T024 [US3] Validate rollback instructions match the actual changed files (`composer.json`, `composer.lock`) and update `specs/102-filament-5-2-1-upgrade/quickstart.md` if needed
- [ ] T025 [US3] If any plugin versions were bumped, record the exact rollback expectation (revert `composer.lock` and constraint changes) in `specs/102-filament-5-2-1-upgrade/quickstart.md`
- [ ] T026 [US3] Perform a time-boxed rollback rehearsal on staging (revert dependency set, redeploy prior artifact) and confirm the automated gate + smoke return to green per `specs/102-filament-5-2-1-upgrade/spec.md`

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: Final hygiene checks to ensure the spec/plan/tasks stay aligned with the actual upgrade outcome.

- [X] T027 [P] Re-run SpecKit prerequisites validation after tasks exist using `.specify/scripts/bash/check-prerequisites.sh` and confirm `specs/102-filament-5-2-1-upgrade/tasks.md` is detected
- [X] T028 Ensure `specs/102-filament-5-2-1-upgrade/research.md` accurately reflects any plugin bumps that were required by Composer resolution
- [X] T029 [P] Run code formatting gate via Pint using `vendor/bin/sail bin pint --dirty --format agent` (expect no runtime-code changes for this dependency-only upgrade; investigate any unexpected diffs)

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: No dependencies
- **Foundational (Phase 2)**: Depends on Setup; BLOCKS all user story work
- **US1 (Phase 3)**: Depends on Foundational; MVP scope
- **US2 (Phase 4)**: Depends on US1 (needs upgraded artifact)
- **US3 (Phase 5)**: Depends on US1; best executed after US2 confirms whether rollback is needed
- **Polish (Phase 6)**: After US1–US3 outcomes are known

### User Story Dependencies

- **US1 (P1)** → enables **US2 (P2)** and **US3 (P3)**
- **US2 (P2)** should run before deciding whether to execute **US3** rollback in practice

## Parallel Execution Examples

### US1 (After T010)

- Parallel candidates:
  - T012 (verify diff scope) and T013 (reproducible install) can run in parallel once `composer.lock` is updated.

### US2

- Parallel candidates:
  - T020 (navigation) and T022 (bulk select-all) can be split across two reviewers during the same staging session.

### US3

- Parallel candidates:
  - T024 (doc accuracy) can be done while staging verification (US2) is running.

## Implementation Strategy

### MVP First (US1 only)

1. Phase 1 → Phase 2 (baseline green)
2. Phase 3 (US1): bump Filament + lockfile, then run tests + build
3. Stop and validate: only proceed once automated gate is green

### Incremental Delivery

- After US1, run US2 staging smoke.
- If smoke fails, either fix via dependency resolution (preferred) or roll back using US3.