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

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

Source Code

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.