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`

## Summary

Rework the existing baseline compare matrix route into an operator-density follow-up to Spec 190. The route stays workspace-scoped and fully derived, but gains adaptive presentation rules: dense multi-tenant scanning when several visible tenants are present, compact single-tenant comparison when only one visible tenant remains, and calmer filter, legend, action, and refresh surfaces.

## Technical Context

**Language/Version**: PHP 8.4.15  
**Primary Dependencies**: Laravel 12, Filament v5, Livewire v4, Pest v4, existing `BaselineCompareMatrixBuilder`, `BadgeCatalog`, `CanonicalNavigationContext`, and `UiEnforcement` patterns  
**Storage**: Existing PostgreSQL truth only; no new tables or artifacts  
**Testing**: Pest feature tests and one browser smoke path through Sail  
**Target Platform**: Laravel monolith web application under `apps/platform`  
**Project Type**: web application  
**Performance Goals**: Improve operator scan throughput without adding more data queries than Spec 190; keep heavy filter changes explicit rather than chatty  
**Constraints**: No compare-logic changes, no new persistence, no hidden-tenant leakage, no generalized UI framework, no Filament provider changes  
**Scale/Scope**: One existing matrix page, one existing view, one existing builder, and focused test coverage updates

## Constitution Check

*GATE: Passed before design. No new source-of-truth or persistence changes are expected.*

| Principle | Status | Notes |
|-----------|--------|-------|
| Inventory-first / snapshots-second | PASS | The feature changes presentation only and keeps Spec 190 truth sources intact. |
| Read/write separation | PASS | `Compare assigned tenants` remains the only mutation and already exists. |
| Workspace + tenant isolation | PASS | Visible-set-only behavior remains unchanged. |
| RBAC-UX | PASS | Existing `404` vs `403` semantics stay intact; only presentation changes. |
| Ops-UX 3-surface feedback | PASS | Refresh and polling surfaces are clarified visually without changing run semantics. |
| Proportionality / anti-bloat | PASS | No new persistence, enum, framework, or cross-domain abstraction is introduced. |
| UI semantics / few layers | PASS | Dense and compact modes reuse existing badge and compare semantics rather than inventing new status taxonomies. |
| Filament v5 / Livewire v4 compliance | PASS | Work remains on the existing Filament page and Livewire-backed route. |
| Provider registration location | PASS | No provider changes; registration remains in `bootstrap/providers.php`. |
| Global search hard rule | PASS | No new global-searchable resource or page is introduced. |
| Destructive action safety | PASS | No destructive action is added by this spec. |
| Asset strategy | PASS | No new panel assets or shared assets are required. Existing deployment use of `filament:assets` remains unchanged. |

## Filament-Specific Compliance Notes

- **Livewire v4.0+ compliance**: This plan stays on the existing Filament v5 + Livewire v4 page stack and does not introduce legacy APIs.
- **Provider registration location**: No panel/provider work is needed. Laravel 11+ provider registration remains in `bootstrap/providers.php`.
- **Global search**: This spec 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 and browser suites to cover presentation mode, density, compact controls, and non-blocking status surfaces.

## Project Structure

### Documentation

```text
specs/191-baseline-compare-operator-mode/
├── spec.md
├── plan.md
├── tasks.md
└── checklists/
    └── requirements.md
```

### Source Code

```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/
    │   ├── Filament/
    │   │   └── BaselineCompareMatrixPageTest.php
    │   └── Guards/
    │       └── ActionSurfaceContractTest.php
    └── Feature/Baselines/
        └── BaselineCompareMatrixBuilderTest.php
```

**Structure Decision**: Keep the work inside the existing Spec 190 implementation surface. This follow-up spec is a refactor of one page and its supporting builder/view behavior, not a new domain slice.

## Key Design Decisions

### D-001 — Keep the route and truth model unchanged

This spec modifies the existing `/compare-matrix` route only. No second route, second matrix artifact, or separate dense-report model is created.

### D-002 — Use adaptive presentation, not separate features

`auto` mode is the canonical default. `dense` and `compact` exist as local operator overrides, but the product concept remains one matrix page with adaptive presentation.

### D-003 — Keep dense cells state-first

Dense mode cells must prioritize compare state, trust, freshness, and attention. Detailed reasons and multiple navigation targets become secondary reveals rather than permanent default chrome.

### D-004 — Treat controls as supporting context

Filters, legends, and refresh hints remain available but must become visibly subordinate to the matrix body. The page should read as a working surface, not a form-first screen.

### D-005 — Keep single-tenant mode honest

If only one visible tenant remains, the operator should see a compact comparison surface rather than an artificially wide matrix. The page should not preserve multi-tenant structure when it no longer helps.

## Implementation Strategy

### Phase A — Presentation Mode Contract

- Add `auto`, `dense`, and `compact` mode state to the page.
- Keep override state local to the route and compatible with existing drilldown URLs.
- Reuse the current derived matrix bundle instead of adding a second persisted view model.

### Phase B — Dense Multi-Tenant Surface

- Reduce per-cell chrome and prioritize state/trust/freshness.
- Keep the subject axis sticky and readable across horizontal scroll.
- Move repeated actions into compact secondary affordances where necessary.

### Phase C — Compact Single-Tenant Surface

- Replace pseudo-matrix presentation with a shorter, calmer list optimized for one visible tenant.
- Remove repeated tenant headers and duplicated labels.
- Preserve subject focus and drilldowns.

### Phase D — Supporting Context Compression

- Convert heavy filters to an apply/reset workflow.
- Compress legends into grouped or collapsible supporting blocks.
- Clarify background polling, manual refresh, and last-updated status without using blocking loading surfaces.

### Phase E — Verification

- Extend feature coverage for mode selection and density rules.
- Extend browser coverage for one dense-mode path and one compact-mode path.
- Keep existing Spec 190 truth and RBAC guarantees intact.

## Risks & Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Dense mode becomes another framework | Medium | Low | Keep presentation logic local to the matrix page and view. |
| Compact mode hides too much drilldown value | Medium | Medium | Keep one clear follow-up path per subject and preserve existing drilldowns. |
| Apply/reset feels stale compared with live filters | Medium | Medium | Make staged filter state obvious and keep reset immediate. |
| Manual override confuses operators | Low | Medium | Keep `auto` as default and label override state clearly. |

## Test Strategy

- Extend feature tests for mode resolution based on visible tenant count.
- Add assertions for dense multi-tenant sticky subject behavior and reduced visible action noise.
- Add assertions for compact single-tenant rendering and shorter supporting chrome.
- Add coverage for explicit filter apply/reset behavior, grouped legends, and page-level last-updated messaging.
- Reuse existing browser smoke coverage and extend it for one dense path plus one compact-mode path.
- Run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` and the focused matrix-related Pest suite before sign-off.