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

# Implementation Plan: Baseline Compare Matrix: High-Density Operator Mode

**Branch**: `191-baseline-compare-operator-mode` | **Date**: 2026-04-11 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/191-baseline-compare-operator-mode/spec.md`
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/191-baseline-compare-operator-mode/spec.md`

**Note**: This plan formalizes the existing 191 spec slice and keeps the work strictly inside the already-shipped Spec 190 matrix surface.

## Summary

Refactor the existing workspace baseline compare matrix into an adaptive operator-density surface. The route, baseline reference, visible-set-only truth, compare-start behavior, and drilldowns stay unchanged, but the page gains local presentation-mode state, dense multi-tenant scanning, compact single-tenant rendering, staged heavy-filter application, grouped legends, and clearer separation between blocking refresh, passive auto-refresh, and last-updated status.

## Technical Context

**Language/Version**: PHP 8.4.15  
**Primary Dependencies**: Laravel 12, Filament v5, Livewire v4, Pest v4, Tailwind CSS v4, existing `BaselineCompareMatrixBuilder`, `BadgeCatalog`, `CanonicalNavigationContext`, and `UiEnforcement` patterns  
**Storage**: PostgreSQL via existing baseline, assignment, compare-run, and finding tables; no new persistence planned  
**Testing**: Pest feature tests and browser smoke coverage run through Laravel Sail  
**Target Platform**: Laravel monolith web application under `apps/platform`  
**Project Type**: web application  
**Performance Goals**: Improve scan throughput without increasing query shape beyond Spec 190, keep heavy filter changes non-chatty, and preserve DB-only render-time matrix surfaces  
**Constraints**: No compare-logic change, no new persistence, no hidden-tenant leakage, no generalized density framework, no provider or panel changes, and no new asset pipeline  
**Scale/Scope**: One existing matrix page, one existing Blade view, one existing builder, one logical contract file, and focused feature plus browser regressions

## Constitution Check

*GATE: Passed before Phase 0 research. Re-checked after Phase 1 design and still passing.*

| Principle | Pre-Research | Post-Design | Notes |
|-----------|--------------|-------------|-------|
| Inventory-first / snapshots-second | PASS | PASS | The spec changes presentation only and keeps Spec 190 truth sources intact. |
| Read/write separation | PASS | PASS | `Compare assigned tenants` remains the only mutation and is unchanged. |
| Graph contract path | N/A | N/A | No new Graph behavior or contract-registry work is introduced. |
| Deterministic capabilities | PASS | PASS | Existing capabilities remain canonical and unchanged. |
| Workspace + tenant isolation | PASS | PASS | Visible-set-only aggregation and drilldown scope remain unchanged. |
| RBAC-UX authorization semantics | PASS | PASS | Existing `404` vs `403` semantics and server-side enforcement remain unchanged. |
| Run observability / Ops-UX | PASS | PASS | Compare-run truth is reused exactly as in Spec 190; this spec only clarifies the visual cues around it. |
| Data minimization | PASS | PASS | No new data copies, exports, or persisted UI artifacts are introduced. |
| Proportionality / anti-bloat | PASS | PASS | The work stays local to one page and does not add a new abstraction or stored artifact. |
| Persisted truth / behavioral state | PASS | PASS | Presentation mode and staged filter state remain request-scoped only. |
| UI semantics / few layers | PASS | PASS | Existing state, trust, freshness, and severity semantics are reused rather than redefined. |
| Filament v5 / Livewire v4 compliance | PASS | PASS | The work remains inside the existing Filament page and Livewire-backed route. |
| Provider registration location | PASS | PASS | No provider changes are required; Laravel 11+ registration remains in `bootstrap/providers.php`. |
| Global search hard rule | PASS | PASS | No new searchable resource or page is introduced. |
| Destructive action safety | PASS | PASS | No destructive action is added. Existing confirmation behavior for compare-start remains unchanged. |
| Asset strategy | PASS | PASS | No new assets are required. Existing deployment behavior for `cd apps/platform && php artisan filament:assets` remains unchanged. |

## Filament-Specific Compliance Notes

- **Livewire v4.0+ compliance**: This plan remains on Filament v5 + Livewire v4 and does not introduce legacy APIs.
- **Provider registration location**: No panel or provider changes are needed; Laravel 11+ provider registration remains in `bootstrap/providers.php`.
- **Global search**: The feature does not add a new globally searchable resource. Existing baseline-resource search behavior is unchanged.
- **Destructive actions**: No new destructive action is introduced. Existing compare-start actions remain confirmation-gated where already defined.
- **Asset strategy**: No new global or on-demand asset registration is planned. Deployment handling of `cd apps/platform && php artisan filament:assets` remains unchanged.
- **Testing plan**: Extend the existing matrix feature, builder, guard, and browser suites to cover presentation mode, staged filter application, and non-blocking status surfaces.

## Phase 0 Research

Research outcomes are captured in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/191-baseline-compare-operator-mode/research.md`.

Key decisions:

- Keep the existing matrix route and truth model and change presentation only.
- Resolve `auto`, `dense`, and `compact` mode from visible tenant count, with a route-local override only.
- Make dense mode state-first rather than action-first.
- Render single-tenant review as a compact compare list rather than a one-column matrix.
- Convert heavy filters to staged apply/reset semantics.
- Replace the long policy-type checkbox stack with a more compact operator-first selector.
- Group legends into compact support context and separate blocking refresh from passive auto-refresh and last-updated cues.
- Reuse existing drilldown and visible-set semantics unchanged.

## Phase 1 Design

Design artifacts are created under `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/191-baseline-compare-operator-mode/`:

- `research.md`: decisions and rejected alternatives for local operator-density work
- `data-model.md`: request-scoped presentation models for mode state, staged filters, dense rows, compact results, and support-surface state
- `contracts/baseline-compare-operator-mode.logical.openapi.yaml`: internal logical contract for adaptive rendering and staged filter application
- `quickstart.md`: implementation and verification sequence for the follow-up spec

Design decisions:

- `auto` remains the default requested mode and resolves to `dense` for multiple visible tenants and `compact` for exactly one visible tenant.
- Manual mode override remains route-local and must never become stored product truth.
- Dense mode reuses existing compare truth but condenses cell content to state, trust, freshness, and attention.
- Compact mode reuses the same truth but removes pseudo-matrix structure once only one visible tenant remains.
- Heavy filter inputs stage locally and apply explicitly; lightweight route-state changes may remain immediate.
- Grouped legends, passive auto-refresh, and last-updated signals become support context rather than competing top-level content.

## Project Structure

### Documentation (this feature)

```text
specs/191-baseline-compare-operator-mode/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── spec.md
├── tasks.md
├── contracts/
│   └── baseline-compare-operator-mode.logical.openapi.yaml
└── checklists/
    └── requirements.md
```

### Source Code (repository root)

```text
apps/platform/
├── app/
│   ├── Filament/
│   │   └── Pages/
│   │       └── BaselineCompareMatrix.php
│   └── Support/
│       └── Baselines/
│           └── BaselineCompareMatrixBuilder.php
├── resources/views/filament/pages/
│   └── baseline-compare-matrix.blade.php
└── tests/
    ├── Browser/
    │   └── Spec190BaselineCompareMatrixSmokeTest.php
    ├── Feature/
    │   ├── Baselines/
    │   │   └── BaselineCompareMatrixBuilderTest.php
    │   ├── Filament/
    │   │   └── BaselineCompareMatrixPageTest.php
    │   └── Guards/
    │       └── ActionSurfaceContractTest.php
    └── Unit/
        └── Badges/
```

**Structure Decision**: Keep the work inside the existing Spec 190 matrix implementation surface. This is a presentation refactor of one existing page and its supporting builder/view behavior, not a new domain slice or a new application area.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| None | N/A | The follow-up stays within the existing page, builder, and test surfaces and introduces no new structural violation. |

## Proportionality Review

- **Current operator problem**: The matrix already answers the right governance question, but not with enough density or calmness for repeated operator scanning.
- **Existing structure is insufficient because**: The current single rendering shape tries to serve both multi-tenant and single-tenant workflows, so supporting context, action repetition, and cell chrome are too heavy in both cases.
- **Narrowest correct implementation**: Keep the same route, truth sources, drilldowns, and compare semantics while adding route-local presentation state, denser rendering, and staged filter application.
- **Ownership cost created**: Additional view-state logic, a logical contract file, and focused regression coverage for mode resolution, filter workflow, and status visibility.
- **Alternative intentionally rejected**: A generalized density framework, a separate dense-report route, or a stored matrix artifact were rejected because the problem is local to the existing matrix surface.
- **Release truth**: current-release operator workflow compression

## Implementation Strategy

### Phase A — Presentation Mode Contract

- Add route-local `auto`, `dense`, and `compact` mode state.
- Resolve the active mode from visible tenant count unless manually overridden.
- Expose `lastUpdatedAt`, `hasStagedFilterChanges`, and passive auto-refresh state to the page.

### Phase B — Dense Multi-Tenant Surface

- Keep the subject column sticky during horizontal scroll.
- Condense dense cells to state, trust, freshness, and attention signals.
- Move repeated actions into compact secondary affordances without breaking drilldown continuity.

### Phase C — Compact Single-Tenant Surface

- Replace pseudo-matrix rendering with a compact subject-result list when only one visible tenant remains.
- Remove repeated tenant headers and duplicated secondary metadata.
- Preserve subject focus and the existing compare/finding/run destinations.

### Phase D — Supporting Context Compression

- Convert heavy matrix filters to staged apply/reset behavior.
- Replace the current long policy-type control with a more compact selector.
- Group or collapse legends.
- Separate blocking refresh from passive auto-refresh and last-updated status.

### Phase E — Verification

- Extend focused feature coverage for mode resolution, staged filter behavior, and support-surface state.
- Extend browser smoke coverage for one dense-mode path and one compact-mode path.
- Keep existing Spec 190 matrix truth, drilldown continuity, and RBAC guarantees green.

## Risk Assessment

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Dense mode becomes another framework | Medium | Low | Keep presentation logic local to the matrix page and avoid generalized shared abstractions. |
| Compact mode hides too much follow-up value | Medium | Medium | Preserve one clear primary drilldown per subject and keep existing follow-up destinations intact. |
| Staged filtering feels slow or unclear | Medium | Medium | Show explicit staged/applied state and keep reset obvious. |
| Manual override confuses operators | Low | Medium | Keep `auto` as the default and surface the resolved mode clearly. |
| Last-updated and auto-refresh cues drift out of sync | Medium | Low | Derive both cues from the same rendered matrix payload and active-run state. |

## Test Strategy

- Extend `BaselineCompareMatrixPageTest` for requested vs resolved mode, active filter application, compact vs dense rendering, and non-blocking refresh cues.
- Extend `BaselineCompareMatrixBuilderTest` for any new derived presentation metadata required by the page.
- Keep `ActionSurfaceContractTest` green so calmer actions do not regress the surface contract.
- Extend `Spec190BaselineCompareMatrixSmokeTest` to prove one dense-mode and one compact-mode operator path on the Livewire page.
- Run the focused Sail verification pack from `quickstart.md` and re-run `update-agent-context.sh copilot` after the plan is finalized.