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.

• 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}
• T002 Capture current baseline dependency state by recording the pre-upgrade contents of composer.json and composer.lock (for rollback comparison)
• 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.

• T004 Ensure local environment is runnable via Sail using docker-compose.yml (containers up, app boots)
• T005 Run Composer sanity checks before upgrading (vendor/bin/sail composer validate) against composer.json
• T006 Run Node dependency install for a clean build baseline using npm (vendor/bin/sail npm ci) with package-lock.json
• 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)
• 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

• T009 [US1] Update Filament constraint to ^5.2.1 in composer.json
• 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)
• 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)
• T013 [P] [US1] Run vendor/bin/sail composer install to confirm composer.lock is reproducible
• T014 [P] [US1] Run automated regression suite: vendor/bin/sail artisan test --compact for tests/
• T015 [P] [US1] Run frontend build: vendor/bin/sail npm run build using package.json
• 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
• 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.

• 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
• T028 Ensure specs/102-filament-5-2-1-upgrade/research.md accurately reflects any plugin bumps that were required by Composer resolution
• 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.