--- 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.