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`

**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, no new run-summary contract, and no new 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 (Presentation Seams)

**Purpose**: Prepare focused acceptance seams for adaptive presentation work.

- [ ] T001 [P] Add presentation-mode acceptance scaffolds in `apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php` and `apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php`
- [ ] T002 [P] Extend surface-contract guard coverage for calmer matrix actions in `apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php`

**Checkpoint**: The test suite has clear seams for dense mode, compact mode, and action-noise expectations.

---

## Phase 2: Foundational (Blocking Operator-Density Contract)

**Purpose**: Establish page-level presentation state and derived view metadata before reshaping the UI.

**⚠️ CRITICAL**: No story work should begin until the presentation contract is stable.

- [ ] T003 Add `auto`, `dense`, and `compact` presentation state handling plus route persistence in `apps/platform/app/Filament/Pages/BaselineCompareMatrix.php`
- [ ] T004 [P] Add derived density metadata for compact cell summaries and compact single-tenant summaries in `apps/platform/app/Support/Baselines/BaselineCompareMatrixBuilder.php`
- [ ] T005 [P] Add page-level last-updated and staged-filter metadata in `apps/platform/app/Filament/Pages/BaselineCompareMatrix.php`

**Checkpoint**: The page can resolve presentation mode and expose the supporting state required for dense and compact rendering.

---

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

- [ ] T006 [P] [US1] Add dense multi-tenant page coverage in `apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php`
- [ ] T007 [P] [US1] Extend browser smoke coverage for dense-mode scanning in `apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php`

### Implementation for User Story 1

- [ ] T008 [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`
- [ ] T009 [US1] Reduce dense-cell chrome to compact state, trust, freshness, and attention signals in `apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php`
- [ ] T010 [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`
- [ ] T011 [US1] Run focused US1 verification against `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

- [ ] T012 [P] [US2] Add compact single-tenant coverage in `apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php`

### Implementation for User Story 2

- [ ] T013 [US2] Resolve auto-to-compact presentation behavior for one visible tenant in `apps/platform/app/Filament/Pages/BaselineCompareMatrix.php`
- [ ] T014 [US2] Render the compact single-tenant compare list in `apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php`
- [ ] T015 [US2] Preserve subject focus and drilldown continuity across compact-mode state in `apps/platform/app/Filament/Pages/BaselineCompareMatrix.php`
- [ ] T016 [US2] Run focused US2 verification against `apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.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

- [ ] T017 [P] [US3] Add filter apply/reset and legend-compaction coverage in `apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.php`
- [ ] T018 [P] [US3] Add non-blocking refresh and last-updated browser coverage in `apps/platform/tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php`

### Implementation for User Story 3

- [ ] T019 [US3] Convert heavy matrix filters to a staged apply/reset workflow in `apps/platform/app/Filament/Pages/BaselineCompareMatrix.php` and `apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php`
- [ ] T020 [US3] Replace the current policy-type control with a faster compact operator-first selector in `apps/platform/app/Filament/Pages/BaselineCompareMatrix.php`
- [ ] T021 [US3] Group or collapse legends and lighten supporting context hierarchy in `apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php`
- [ ] T022 [US3] Render page-level last-updated, polling, and manual-refresh signals without blocking the matrix in `apps/platform/app/Filament/Pages/BaselineCompareMatrix.php` and `apps/platform/resources/views/filament/pages/baseline-compare-matrix.blade.php`
- [ ] T023 [US3] Run focused US3 verification against `apps/platform/tests/Feature/Filament/BaselineCompareMatrixPageTest.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.

- [ ] T024 [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`
- [ ] T025 [P] Run formatting with `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- [ ] T026 Run the focused verification pack against `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)**: starts immediately.
- **Foundational (Phase 2)**: depends on Setup and blocks presentation work.
- **US1 (Phase 3)**: depends on Phase 2 and is the MVP.
- **US2 (Phase 4)**: depends on Phase 2 and can follow US1 once the page contract is stable.
- **US3 (Phase 5)**: depends on Phase 2 and should land after dense and compact structure are in place.
- **Polish (Phase 6)**: depends on the desired user stories being complete.

### Within Each User Story

- Add or extend the story tests first.
- Land page-state changes before view-branching where possible.
- Keep each story independently shippable and verifiable.

### Parallel Opportunities

- `T001` and `T002` can run in parallel.
- `T004` and `T005` can run in parallel after `T003` defines the presentation contract.
- Within US1, `T006` and `T007` can run in parallel before `T008` through `T010`.
- Within US3, `T017` and `T018` can run in parallel before `T019` through `T022`.

## Implementation Strategy

1. Lock the presentation contract and route state first.
2. Deliver dense multi-tenant mode as the MVP operator gain.
3. Deliver compact single-tenant mode as the adaptive counterpart.
4. Compress filters, legends, and status surfaces last so they match the final page structure.
5. Finish with copy review, formatting, and the focused verification pack.