TenantAtlas/specs/191-baseline-compare-operator-mode/tasks.md

Tasks: Baseline Compare Matrix: High-Density Operator Mode

Input: Design documents from /specs/191-baseline-compare-operator-mode/
Prerequisites: plan.md, spec.md, research.md, data-model.md, quickstart.md, contracts/baseline-compare-operator-mode.logical.openapi.yaml

Tests: Tests are REQUIRED. Extend Pest feature coverage and browser smoke coverage around the existing matrix route. Operations: This feature reuses existing baseline_compare run truth only. No new OperationRun type, run-summary contract, or notification channel should be introduced. RBAC: Existing workspace and tenant visibility rules from Spec 190 remain authoritative. Tasks must preserve visible-set-only aggregation and existing 404 vs 403 behavior. Operator Surfaces: The affected operator surface is the existing workspace baseline compare matrix route, with additive presentation changes only. Filament UI Action Surfaces: The matrix page keeps explicit drilldown controls and forbidden row click. No destructive action is added. Badges: Dense and compact rendering must continue to use centralized matrix state, trust, freshness, and severity semantics.

Organization: Tasks are grouped by user story so each operator-density improvement can be implemented and verified independently.

Phase 1: Setup (Spec and Acceptance Seams)

Purpose: Lock the implementation contract and acceptance seams before page behavior changes.

• T001 Finalize the UI Action Matrix, operator-surface assumptions, and measurable acceptance thresholds in specs/191-baseline-compare-operator-mode/spec.md
• T002 [P] Reconcile the staged filter and presentation-mode interaction contract in specs/191-baseline-compare-operator-mode/contracts/baseline-compare-operator-mode.logical.openapi.yaml
• T003 [P] Add acceptance scaffolds for multi-tenant, single-tenant, and staged-filter scenarios in apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php and apps/platform/tests/Feature/Baselines/BaselineCompareMatrixBuilderTest.php
• T004 [P] Extend browser and action-surface guard seams in apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php and apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php

Checkpoint: The spec contract and test seams are ready for implementation work.

---

Phase 2: Foundational (Blocking Presentation Contract)

Purpose: Establish page-level presentation state and derived read models before reshaping dense and compact layouts.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

• T005 Add requested, resolved, and manual presentation-mode query handling plus staged filter state as request-scoped-only route state in apps/platform/app/Filament/Pages/BaselineCompareMatrix.php
• T006 [P] Extend matrix bundle outputs for dense rows, compact results, support-surface state, and last-updated metadata in apps/platform/app/Support/Baselines/BaselineCompareMatrixBuilder.php
• T007 [P] Add foundational builder coverage for requested or resolved mode, filter metadata, support-surface state, and unchanged compare state, trust, freshness, and severity outputs in apps/platform/tests/Feature/Baselines/BaselineCompareMatrixBuilderTest.php
• T008 [P] Add foundational page coverage for mode resolution, route-state persistence, and derived-only non-persistence guarantees in apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php

Checkpoint: The page can resolve auto, dense, and compact mode and expose all derived state needed by the UI.

---

Phase 3: User Story 1 - Scan multi-tenant drift in dense mode (Priority: P1) 🎯 MVP

Goal: Make multi-tenant reading materially denser and faster without changing compare truth.

Independent Test: Open the matrix with multiple visible tenants and verify dense mode, sticky subject behavior, and state-first cells.

Tests for User Story 1

• T009 [P] [US1] Add dense-mode assertions for auto resolution, sticky subject behavior, and compact cell hierarchy in apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php
• T010 [P] [US1] Extend browser smoke coverage for dense-mode scanning and dense-mode drilldowns in apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php

Implementation for User Story 1

• T011 [US1] Render the dense multi-tenant matrix shell with sticky subject-column behavior in apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php
• T012 [US1] Surface condensed dense-cell state, trust, freshness, and attention summaries in apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php and apps/platform/app/Filament/Pages/BaselineCompareMatrix.php
• T013 [US1] Calm repeated cell and tenant actions into compact secondary affordances in apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php and apps/platform/app/Filament/Pages/BaselineCompareMatrix.php
• T014 [US1] Preserve focused-subject and visible-set drilldown continuity for dense mode in apps/platform/app/Filament/Pages/BaselineCompareMatrix.php
• T015 [US1] Run focused dense-mode verification in apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php and apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php

Checkpoint: Multi-tenant scanning is visibly denser and the matrix body reads as the primary working surface.

---

Phase 4: User Story 2 - Work a single visible tenant in compact mode (Priority: P2)

Goal: Replace pseudo-matrix rendering with a compact comparison surface when only one visible tenant remains.

Independent Test: Open the matrix with one visible tenant and verify compact mode in auto state plus drilldown continuity.

Tests for User Story 2

• T016 [P] [US2] Add compact single-tenant page assertions for auto-to-compact resolution, including the assigned-greater-than-visible RBAC edge case, in apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php
• T017 [P] [US2] Add compact single-tenant builder assertions for visible-set-only compact resolution and unchanged compare semantics in apps/platform/tests/Feature/Baselines/BaselineCompareMatrixBuilderTest.php

Implementation for User Story 2

• T018 [US2] Emit compact single-tenant result entries, compact drilldown metadata, and visible-set-only compact resolution when assigned tenants exceed visible tenants in apps/platform/app/Support/Baselines/BaselineCompareMatrixBuilder.php
• T019 [US2] Render the compact single-tenant compare list and reduced metadata shell in apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php
• T020 [US2] Preserve manual override, subject focus, and drilldown continuity for compact mode in apps/platform/app/Filament/Pages/BaselineCompareMatrix.php
• T021 [US2] Run focused compact-mode verification in apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php and apps/platform/tests/Feature/Baselines/BaselineCompareMatrixBuilderTest.php

Checkpoint: One-tenant viewing is materially shorter and calmer than the current matrix surface.

---

Phase 5: User Story 3 - Use filters, legends, and status surfaces without losing the matrix (Priority: P2)

Goal: Compress supporting context so it stays useful without pushing the matrix down or increasing visual noise.

Independent Test: Apply filters, inspect legends, and observe background refresh behavior without losing scanability.

Tests for User Story 3

• T022 [P] [US3] Add staged-filter, legend-compaction, refresh-cue, and zero-result empty-state assertions in apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php
• T023 [P] [US3] Add browser smoke coverage for apply/reset filters, passive auto-refresh cues, and filtered zero-result empty states in apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php

Implementation for User Story 3

• T024 [US3] Implement staged heavy-filter draft, apply, reset, and zero-result empty-state behavior in apps/platform/app/Filament/Pages/BaselineCompareMatrix.php
• T025 [US3] Replace the long policy-type control with a searchable compact selector in apps/platform/app/Filament/Pages/BaselineCompareMatrix.php
• T026 [US3] Render applied-versus-draft filter summaries, one grouped collapsed legend block, and compressed support context in apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php
• T027 [US3] Render honest manual-refresh, passive polling, and last-updated cues in apps/platform/app/Filament/Pages/BaselineCompareMatrix.php and apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php
• T028 [US3] Keep calmer actions and forbidden row-click behavior enforced in apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php
• T029 [US3] Run focused support-surface verification, including zero-result empty-state behavior, in apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php, apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php, and apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php

Checkpoint: Filters, legends, and status surfaces support the operator without visually competing with the matrix.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Finalize copy, formatting, and the focused verification pack.

• T030 [P] Review auto, dense, compact, last updated, and action-copy vocabulary in apps/platform/app/Filament/Pages/BaselineCompareMatrix.php and apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php
• T031 [P] Verify shared badge semantics remain centralized in apps/platform/app/Filament/Pages/BaselineCompareMatrix.php, apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php, and apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php
• T032 [P] Run formatting for changed implementation files in apps/platform/app/Filament/Pages/BaselineCompareMatrix.php and apps/platform/app/Support/Baselines/BaselineCompareMatrixBuilder.php
• T033 Run the focused verification pack and confirm no compare-truth or persistence regressions in apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php, apps/platform/tests/Feature/Baselines/BaselineCompareMatrixBuilderTest.php, apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php, and apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies. Start immediately.
• Foundational (Phase 2): Depends on Phase 1. Blocks all user-story implementation.
• User Story 1 (Phase 3): Depends on Phase 2. This is the MVP slice.
• User Story 2 (Phase 4): Depends on Phase 2. Can proceed after the shared presentation contract is stable.
• User Story 3 (Phase 5): Depends on Phase 2. Should land after the dense and compact layout branches exist.
• Polish (Phase 6): Depends on all desired user stories being complete.

User Story Dependencies

• US1: Independent after Phase 2 and should be delivered first.
• US2: Independent after Phase 2, but it reuses the shared presentation contract from US1-era foundational work.
• US3: Independent after Phase 2, but it should align with the final dense and compact layout structure.

Within Each User Story

• Tests for that story should be written and made to fail before implementation.
• Builder and page state updates should land before Blade branching that depends on them.
• Each story must remain independently testable when finished.

Parallel Execution Examples

User Story 1

• Run T009 and T010 in parallel because they touch separate test files.
• After T011 lands, T012 can proceed while T014 is prepared if the route-state contract is already stable.

User Story 2

• Run T016 and T017 in parallel because they cover separate test layers.
• T018 should land before T019 because the compact Blade path depends on compact result entries.

User Story 3

• Run T022 and T023 in parallel because they touch separate test files.
• T024 and T025 can be split between staged filter flow and selector compaction if coordinated on apps/platform/app/Filament/Pages/BaselineCompareMatrix.php.

Implementation Strategy

MVP First

1. Finish Setup and Foundational work.
2. Deliver US1 dense multi-tenant mode as the MVP operator gain.
3. Verify US1 independently before moving on.

Incremental Delivery

1. Add US2 compact single-tenant mode on top of the shared presentation contract.
2. Add US3 filter, legend, and refresh-surface compression once both layout branches are stable.
3. Finish with copy review, formatting, and the focused verification pack.

Validation Rule

1. Do not mark a story complete until its focused verification task passes.
2. Keep the existing Spec 190 truth, RBAC semantics, and drilldown continuity intact while implementing each story.