# Implementation Plan: Spec 418 - Coverage v2 Operator Surface

**Branch**: `418-coverage-v2-operator-surface` | **Date**: 2026-06-26 | **Spec**: `specs/418-coverage-v2-operator-surface/spec.md`
**Input**: Feature specification from `/specs/418-coverage-v2-operator-surface/spec.md`

## Summary

Add one internal Coverage v2 Readiness surface for operators to inspect activation readiness without activating customer-facing proof. The implementation should build a thin DB-only read model over existing Coverage v2 resource types, supported scopes, resources, evidence, identity state, provider connection provenance, and Claim Guard state; then render it with Filament-native summary, tables, filters, badges, and disclosed diagnostics. It must remain read-only, no-legacy, no-raw-payload, no-remote-render, workspace/environment/provider-scoped, and browser-proven.

## Technical Context

**Language/Version**: PHP 8.4.x, Laravel 12.x
**Primary Dependencies**: Filament v5, Livewire v4, existing TenantConfiguration models/services, existing RBAC/capability helpers, existing OperationRun link helper
**Storage**: PostgreSQL via existing Coverage v2 tables. No new persisted summary table by default.
**Testing**: Pest 4 / PHPUnit 12 via Sail
**Validation Lanes**: fast-feedback, confidence, browser; pgsql only if indexes/constraints/migrations change
**Target Platform**: Laravel Sail locally, Dokploy/container deployment for staging/production
**Project Type**: Laravel monolith under `apps/platform`
**Performance Goals**: page render is DB-only, bounded queries, no remote calls, paginated/filterable tables
**Constraints**: read-only; no Graph/TCM/provider calls during render; no customer proof; no raw payloads; no v1/v2 adapter; no `tenant_id` ownership; no start/capture/restore/report actions
**Scale/Scope**: initial Coverage v2 registry and captured resources from Specs 414, 415, and 417; future customer/cutover work is separate

## UI / Surface Guardrail Plan

- **Guardrail scope**: new rendered operator surface.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: Coverage v2 Readiness page at `/admin/tenant-configuration/coverage-v2` or repo-equivalent; admin panel page registration/navigation; summary/widgets/tables/diagnostics; workspace/environment/provider filter state.
- **No-impact class, if applicable**: N/A.
- **Native vs custom classification summary**: Native Surface. Use Filament-native page/table/widget/infolist/section/action slide-over primitives where possible.
- **Shared-family relevance**: navigation, status messaging, evidence diagnostics, OperationRun links, provider provenance.
- **State layers in scope**: page, query/filter, table, read-only inspect/disclosure detail. No shell rewrite.
- **Audience modes in scope**: operator/MSP and support/platform diagnostics. Customer/read-only output is explicitly out of scope.
- **Decision/diagnostic/raw hierarchy plan**: readiness summary and critical v2 states visible first; diagnostics disclosed second; raw/support evidence hidden and not added unless existing safe route already exists.
- **Raw/support gating plan**: raw payloads, normalized payloads, permission context raw JSON, secrets, and provider response dumps are never displayed.
- **One-primary-action / duplicate-truth control**: one dominant action is inspect/open read-only detail. No export/capture/start/publish action. Avoid duplicate blocker summaries.
- **Handling modes by drift class or surface**: hard-stop if customer output, remote work, raw payload display, v1 adapter, old labels, or mutations appear.
- **Repository-signal treatment**: review-mandatory for route/navigation/UI registry updates; exception-required for Product Surface two-table Technical Annex budget.
- **Special surface test profiles**: standard-native-filament plus focused browser smoke.
- **Required tests or manual smoke**: unit read model/mappers, feature auth/redaction/no-legacy/no-remote/scope, browser smoke.
- **Exception path and spread control**: one Product Surface exception for two native tables on an internal Technical Annex page. No broad UI framework exception.
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage.
- **UI/Productization coverage decision**: reachable UI added. Update `docs/ui-ux-enterprise-audit/route-inventory.md` and `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`, or document a bounded registry exception.
- **Coverage artifacts to update**: route inventory and design coverage matrix expected.
- **List surface review**: apply `docs/product/standards/list-surface-review-checklist.md` for the new Read-only Registry / Report tables and record the result in the implementation report.
- **No-impact rationale**: N/A.
- **Navigation / Filament provider-panel handling**: register the page in the admin panel; any navigation entry must be secondary and must not dominate primary navigation. Provider registration remains `apps/platform/bootstrap/providers.php`.
- **Screenshot or page-report need**: no full page report required unless implementation adds custom layout or deviates from native Filament. Focused browser proof is required.

## Product Surface Contract Plan

- **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md`.
- **No-legacy posture**: canonical Coverage v2 internal readiness; no compatibility exception.
- **Page archetype and surface budget plan**: Technical Annex Page / Read-only Registry Report. Surface budget exception for two native tables is documented because registry support and concrete instance evidence must be visible together for internal cutover readiness.
- **Technical Annex and deep-link demotion plan**: OperationRun links, evidence hashes, source metadata, source contract state, identity diagnostics, and provider provenance are secondary diagnostics. Raw payloads and raw provider output forbidden.
- **Canonical status vocabulary plan**: top-level readiness uses `Ready`, `Needs attention`, `Blocked`, `Unknown`; existing Coverage v2 enum values display as internal diagnostic dimensions with internal/operator labels.
- **Product Surface exceptions**: one Product Surface Contract Technical Annex surface-budget exception for summary plus two native tables; no customer-facing exception. UI-EX-001 implementation exception is `none` if the surface remains native Filament. If custom UI becomes necessary, implementation must stop and name a catalogued UI-EX-001 exception type before proceeding.
- **Browser verification plan**: focused route smoke, visible required labels, hidden forbidden labels/raw payloads, primary-link inspect slide-over, no console/Livewire/Filament errors, and no remote network calls.
- **Human Product Sanity plan**: implementation report answers the six Spec 418 questions.
- **Visible complexity outcome target**: neutral to reduced.
- **Implementation report target**: `specs/418-coverage-v2-operator-surface/implementation-report.md`.

## Filament / Livewire / Deployment Posture

- **Livewire v4 compliance**: Livewire v4.x confirmed. Do not introduce Livewire v3 APIs.
- **Panel provider registration location**: Laravel 12 panel providers remain registered in `apps/platform/bootstrap/providers.php`; page registration belongs in `apps/platform/app/Providers/Filament/AdminPanelProvider.php` or repo-equivalent admin panel page discovery.
- **Global search posture**: no Filament Resource should be globally searchable for this surface. If a Resource is created instead of a Page, global search must be disabled unless safe View/Edit posture exists.
- **Destructive/high-impact action posture**: none. If implementation wants any start/capture/re-evaluate/export/publish/restore action, stop and amend spec/plan/tasks or split a new spec.
- **Asset strategy**: no new assets expected; `filament:assets` not required unless implementation registers Filament assets.
- **Testing plan**: Livewire/feature tests for page authorization/render if page is a Livewire component; unit tests for read model and display mapping; browser smoke for rendered route.
- **Deployment impact**: no env vars, queues, scheduler, storage, or assets by default. Migrations only if narrow indexes are added. No queue worker change because no operations start.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched**: `TenantConfigurationResourceType`, `TenantConfigurationSupportedScope`, `TenantConfigurationResource`, `TenantConfigurationResourceEvidence`, `ClaimGuard`, `OperationRunLinks`, ProviderConnection scope, admin panel registration, UI audit registry, tests.
- **Shared abstractions reused**: existing Coverage v2 models/enums/services; existing OperationRun URL helper; existing workspace/environment/provider scope helpers; existing RBAC capability resolver/policies; `BadgeCatalog`/`BadgeRenderer` for status-like badges.
- **New abstraction introduced? why?**: one thin read model/query service and possibly a non-status display mapper. It is needed to centralize DB-only aggregate logic, blocker grouping, redaction, and no-legacy text display for tests. Status-like rendered badges must use a central BadgeDomain mapping, not page-local status semantics.
- **Why the existing abstraction was sufficient or insufficient**: Existing kernel/capture/identity services own truth but do not provide an operator-ready read model. Existing Evidence Overview/Inventory Coverage pages are v1/customer-adjacent surfaces and must not become v2 dual truth.
- **Bounded deviation / spread control**: no new persisted read model, no UI framework, no new state family, no customer output. Keep new support under TenantConfiguration or Filament page-local namespaces.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: diagnostic links only.
- **Central contract reused**: `OperationRunLinks` or current canonical helper.
- **Delegated UX behaviors**: URL resolution and authorization only; no queued toast, artifact link, run-enqueued browser event, queued DB notification, or dedupe messaging.
- **Surface-owned behavior kept local**: secondary diagnostic link visibility only.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes.
- **Provider-owned seams**: provider connection provenance, source contract metadata, Graph fallback, beta experimental source class, external provider identifiers if ever disclosed.
- **Platform-core seams**: workspace/managed-environment/provider_connection ownership, resource type, supported scope, readiness summary, coverage/evidence/identity/claim states.
- **Neutral platform terms / contracts preserved**: provider connection, managed environment, supported scope, source class, activation blocker, readiness.
- **Retained provider-specific semantics and why**: Graph/TCM labels appear only as source class or safe metadata because the initial resource types are Intune-backed.
- **Bounded extraction or follow-up path**: document-in-feature if any provider-specific display is retained; no new provider framework.

## Constitution Check

- Inventory/evidence truth: PASS. Uses existing Coverage v2 resource/evidence truth, no legacy snapshot promotion.
- Read/write separation: PASS. Read-only surface; no mutation actions.
- Graph contract path: PASS. No new Graph calls and no render-time provider calls.
- Deterministic capabilities: PASS with implementation validation for selected view capability.
- RBAC-UX: PASS with required 404/403 tests and server-side page authorization.
- Workspace isolation: PASS with required workspace/environment/provider scope tests.
- OperationRun: PASS. Diagnostic links only; no OperationRun as default proof.
- Evidence/currentness: PASS. Evidence hash allowed; raw evidence hidden; no fallback-to-latest proof.
- Customer output: PASS. No customer output, Review Pack, report, restore readiness, or customer-ready wording.
- Provider boundary: PASS with provider IDs hidden/default metadata-only.
- Product Surface: PASS with one documented Product Surface Contract Technical Annex surface-budget exception. UI-EX-001 implementation exception remains `none` if the surface is native Filament.
- Test governance: PASS. Unit/feature/browser lanes named; no broad heavy family.
- Proportionality: PASS. Thin derived read model is justified; persisted summary disallowed.
- No premature abstraction: PASS. Do not introduce UI framework or broad presenter.
- Persisted truth: PASS. No new persisted summary by default.
- Behavioral state: PASS. Uses existing v2 state families.
- No legacy / pre-production lean: PASS. No adapters, fallback readers, dual writes, old labels, or `tenant_id`.

## Test Governance Check

- **Test purpose / classification by changed surface**: Unit for read model and display mapping; Feature for authorization, rendered content, redaction, no-legacy, no-remote, and scope; Browser for Product Surface smoke.
- **Affected validation lanes**: fast-feedback, confidence, browser; pgsql only for indexes/migrations.
- **Why this lane mix is the narrowest sufficient proof**: Unit tests prove computed readiness; feature tests prove security/render boundaries; browser proves the actual Filament/Livewire surface.
- **Narrowest proving command(s)**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration/CoverageV2ReadinessSummaryTest.php tests/Unit/Support/TenantConfiguration/CoverageV2ActivationBlockerGroupingTest.php tests/Unit/Support/TenantConfiguration/CoverageV2ClaimGuardDisplayMapperTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantConfiguration/Spec418CoverageV2OperatorSurfaceTest.php tests/Feature/TenantConfiguration/Spec418CoverageV2OperatorSurfaceAuthorizationTest.php tests/Feature/TenantConfiguration/Spec418CoverageV2OperatorSurfaceNoLegacyLabelsTest.php tests/Feature/TenantConfiguration/Spec418CoverageV2OperatorSurfaceRedactionTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec418CoverageV2OperatorSurfaceSmokeTest.php`
- **Fixture / helper / factory / seed / context cost risks**: keep Spec 418 fixtures local or opt-in; do not broaden default TenantConfiguration/browser factories.
- **Expensive defaults or shared helper growth introduced?**: no expected default broadening.
- **Heavy-family additions, promotions, or visibility changes**: none.
- **Surface-class relief / special coverage rule**: standard-native-filament relief for layout; focused browser still required.
- **Closing validation and reviewer handoff**: implementation report must record exact commands/results, browser proof, Product Surface exception, and any unrelated failures.
- **Budget / baseline / trend follow-up**: none expected; document if browser fixture or feature lane cost expands materially.
- **Review-stop questions**: lane fit, hidden fixture cost, no remote render, redaction, old labels absent, customer claims absent, no `tenant_id`.
- **Escalation path**: document-in-feature for contained exception; follow-up-spec only if structural persistence or broad governance tests are required.
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage.
- **Why no dedicated follow-up spec is needed**: this is the bounded operator-readiness surface; customer/cutover actions are already deferred.

## Project Structure

### Documentation (this feature)

```text
specs/418-coverage-v2-operator-surface/
├── spec.md
├── plan.md
├── tasks.md
├── implementation-report.md
└── checklists/
    └── requirements.md
```

### Source Code (likely affected in later implementation)

```text
apps/platform/app/
├── Filament/
│   ├── Pages/TenantConfiguration/
│   │   └── CoverageV2Readiness.php
│   └── Widgets/TenantConfiguration/
│       ├── CoverageV2ActivationBlockersWidget.php
│       ├── CoverageV2ReadinessSummaryWidget.php
│       ├── CoverageV2ResourceInstancesTable.php
│       └── CoverageV2ResourceTypesTable.php
├── Providers/Filament/
│   └── AdminPanelProvider.php
├── Services/TenantConfiguration/
│   └── CoverageV2ReadinessReadModel.php
└── Support/TenantConfiguration/
    └── CoverageV2ClaimGuardDisplayMapper.php

apps/platform/resources/views/filament/pages/tenant-configuration/
└── coverage-v2-readiness.blade.php

apps/platform/tests/
├── Unit/Support/TenantConfiguration/
├── Feature/TenantConfiguration/
└── Browser/

docs/ui-ux-enterprise-audit/
├── route-inventory.md
└── design-coverage-matrix.md
```

**Structure Decision**: Use repo-equivalent names if implementation finds a closer existing TenantConfiguration namespace. Keep the read model/service thin and DB-only. If a single Filament page with table widgets is not the best native pattern, implementation may use an equivalent native Filament page/resource-page structure while preserving the route and Product Surface contract.

## Implementation Phases

### Phase 0 - Preflight

Capture branch, HEAD, dirty state, activated skills, candidate gate, completed dependency reports, current Coverage v2 model/service names, and hard-gate stop conditions.

### Phase 1 - Inspect Existing Coverage v2 Read Paths

Inspect resource type registry, supported scopes, resources, evidence, identity states, Claim Guard, provider connection scope, OperationRun links, authorization helpers, existing Filament pages, and browser fixture patterns. Produce a dependency map in the implementation report.

### Phase 2 - Product Surface Contract Design

Lock route, surface role, surface type, native/custom classification, primary operator question, default-visible truth, diagnostics boundary, raw evidence boundary, action model, browser proof criteria, and Human Product Sanity criteria before runtime UI edits.

### Phase 3 - DB-Only Read Model

Create the derived read model/query service for readiness summary, resource type table, resource instance table, activation blockers, source class counts, and claim state counts. No remote calls, no persisted summary table.

### Phase 4 - Filament Native Surface

Add the read-only admin surface with scope summary, readiness summary, resource type table, resource instance table, activation blockers, diagnostics disclosure, empty states, filters, and one inspect model. Update admin panel/page registration and secondary navigation only if appropriate.

### Phase 5 - Authorization And Scope

Enforce workspace membership, managed environment entitlement, selected view capability, provider connection same-scope filtering, and 404/403 semantics.

### Phase 6 - Redaction, No-Remote, And No-Legacy Guards

Hide raw/normalized payloads, permission context raw JSON, secrets, raw provider details, old gap labels, customer claims, and unscoped 100% claims. Prove render path is DB-only.

### Phase 7 - Tests And Browser Smoke

Add focused unit, feature, and browser tests. Keep fixtures narrow and explicit. Run Pint dirty, focused tests, browser smoke, and `git diff --check`.

### Phase 8 - Implementation Report

Write `implementation-report.md` with candidate gate, dirty state before/after, files changed, route, Product Surface classification, UI Action Matrix, browser proof, Human Product Sanity, authorization proof, redaction proof, no remote render proof, no-tenant_id confirmation, no-legacy/no-dual-truth confirmation, tests, deployment impact, and deferred work.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| Thin read model/display mapper | Operators need one safe readiness answer from several existing v2 tables and services | Direct DB inspection or implementation reports lack RBAC/redaction/browser proof and cannot support Product Surface checks |
| Product Surface Contract Technical Annex surface-budget exception | Registry support and concrete instance evidence both block activation and must be visible together | A one-table page hides either denominator readiness or concrete capture/identity/claim blockers |

## Proportionality Review

- **Current operator problem**: v2 readiness cannot be verified safely from one product surface.
- **Existing structure is insufficient because**: Specs 414/415/417 created truth but no operator inspection path.
- **Narrowest correct implementation**: one derived DB-only read model and one read-only Filament-native surface.
- **Ownership cost created**: tests, central badge/status mapping, any non-status display mapping, browser smoke, UI registry updates, list-surface checklist close-out, and Product Surface close-out must be maintained as Coverage v2 evolves.
- **Alternative intentionally rejected**: add v2 sections to customer-facing or existing v1 surfaces. Rejected because that creates dual truth and premature customer activation.
- **Release truth**: current-release internal readiness inspection; future activation deferred.