TenantAtlas/specs/418-coverage-v2-operator-surface/spec.md

# Feature Specification: Spec 418 - Coverage v2 Operator Surface

**Feature Branch**: `418-coverage-v2-operator-surface`
**Created**: 2026-06-26
**Status**: Draft
**Input**: User-provided "Spec 418 - Coverage v2 Operator Surface" draft plus repo checks against Specs 414/415/417, roadmap, candidate queue, constitution, Product Surface Contract, TenantPilot agent skill gates, and current TenantConfiguration runtime.

## Candidate Selection

- **Selected candidate**: Spec 418 - Coverage v2 Operator Surface.
- **Source location**: User-provided prompt in this session.
- **Why selected**: The active candidate queue in `docs/product/spec-candidates.md` explicitly has no automatic next-best target, but the user directly promoted a bounded Coverage v2 follow-up. Specs 414, 415, and 417 are implemented/accepted and leave Coverage v2 inactive but inspectable only through database rows, tests, and implementation reports. The next safe step is a read-only internal operator surface that shows readiness and blockers without activating customer-facing proof.
- **Roadmap relationship**: Aligns with the roadmap themes for evidence/coverage hardening, provider-boundary discipline, workspace/managed-environment ownership, and no-legacy cutover. This package is not auto-selected from the queue; it is a user-promoted P0 Coverage v2 cutover-readiness slice.
- **Close alternatives deferred**: Management-report runtime validation, artifact lifecycle retention, provider readiness productization, cross-domain indicator follow-through, system-panel browser fixture work, and first governed AI consumer remain manual-promotion backlog items. Coverage v2 legacy cutover/removal, Intune core comparable/renderable pack, certification, pilot readiness gate, customer output, Review Pack/report conversion, Evidence Overview conversion, Baseline Compare conversion, and Restore Readiness conversion are deferred to later Coverage v2 specs.
- **Related completed-spec guardrail**: `specs/414-tcm-first-coverage-core-cutover/`, `specs/415-generic-content-backed-capture/`, and `specs/417-canonical-identity-engine/` are completed/validated dependency context only. Do not rewrite them, normalize their close-out history, or strip validation/task/browser/review history.
- **Prerequisite gate result**: PASS. Spec 414 implementation report confirms resource type registry, supported scopes, Claim Guard, and inactive kernel. Spec 415 implementation report confirms concrete resources/evidence, content-backed capture outcomes, provider scope, and no UI activation. Spec 417 implementation report confirms canonical identity state, Claim Guard identity integration, and no UI/customer activation.
- **Smallest viable implementation slice**: Add one internal `/admin` Coverage v2 Readiness surface over existing Coverage v2 tables/services. It is read-only, DB-only during render, environment-scoped for instance rows, and limited to summaries, native tables, filters, inspect/disclosure details, authorized OperationRun diagnostic links, evidence hashes, and activation blocker groups.

## Spec Candidate Check *(mandatory - SPEC-GATE-001)*

- **Problem**: Coverage v2 exists in persistence and services but operators cannot inspect readiness, supported scope, captured evidence state, identity state, claim state, provider provenance, or activation blockers in one bounded surface.
- **Today's failure**: Reviewers must inspect database rows, tests, reports, OperationRun context, and service internals. This makes false activation more likely because claim blockers, identity conflicts, beta/experimental resources, and capture blockers are not operationally visible.
- **User-visible improvement**: Operators get one internal read-only place to answer: "What prevents Coverage v2 from becoming active proof?"
- **Smallest enterprise-capable version**: One secondary operator page with a derived DB-only read model, readiness summary, resource type table, environment-filtered resource instance table, activation blockers, and disclosed diagnostics. No capture starts, no customer output, no legacy adapters, no raw payload display.
- **Explicit non-goals**: No customer-facing Coverage v2 claims, Review Pack/report output, Customer Review Workspace output, Evidence Overview conversion, Baseline Compare conversion, Restore Readiness conversion, capture start actions, TCM/Graph calls, compare/render/restore/certification, legacy runtime removal, v1-to-v2 adapter, dual writes, old snapshot migration, or technical object hub in primary navigation.
- **Permanent complexity imported**: One operator page/route, one thin derived read model or repo-equivalent query service, display mapping for existing Coverage v2 states, focused unit/feature/browser tests, and Product Surface close-out. No new persisted summary table, enum/status family, taxonomy table, or compatibility layer.
- **Why now**: Specs 414, 415, and 417 have completed the kernel, capture, and identity prerequisites. Before any cutover or customer activation, reviewers need human sanity proof that v2 readiness and blockers are visible and safe.
- **Why not local**: A scattered debug route, database query, or implementation report cannot enforce RBAC, redaction, no-legacy labels, provider scope, or Product Surface behavior. A bounded operator surface is the narrowest durable inspection point.
- **Approval class**: Core Enterprise.
- **Red flags triggered**: New surface; readiness/status presentation; report-like internal surface. Defense: it uses existing Coverage v2 states, adds no persisted UI truth, no customer output, and directly prevents unsafe cutover.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve, with strict read-only, internal-only, DB-only, no-legacy, no-customer-claim, and no-raw-payload boundaries.

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace + managed environment operator context. Resource type registry may be workspace-wide product metadata; resource instance rows require managed environment scope by default.
- **Primary Routes**: Recommended route `/admin/tenant-configuration/coverage-v2`. If repo route conventions require another internal/operator route, use the nearest `/admin` workspace/environment-scoped convention and document the deviation in the implementation report.
- **Data Ownership**: Existing Coverage v2 environment-owned rows are scoped by `workspace_id`, `managed_environment_id`, and `provider_connection_id`. Existing resource type/supported scope definition rows remain product/kernel metadata. No internal `tenant_id` ownership is allowed.
- **RBAC**: Non-member workspace access returns 404. Workspace member without managed-environment entitlement returns 404. Member with entitlement but without the chosen view capability returns 403. Implementation must verify whether `Capabilities::EVIDENCE_VIEW`, `Capabilities::TENANT_VIEW`, or a new narrow coverage-readiness view capability is the correct repo path; if a new capability is needed, it must be registry-backed and tested.

For canonical-view specs:

- **Default filter behavior when tenant-context is active**: If a managed environment is active or supplied by `environment_id`, prefilter resource instance rows to that managed environment. If workspace-wide mode is allowed, aggregate only environments the actor is entitled to view. The initial recommended rule is to require a managed environment filter before instance rows render.
- **Explicit entitlement checks preventing cross-tenant leakage**: Provider connection filters and instance queries must join or scope through workspace + managed environment entitlement and same-scope provider connection. Wrong workspace, wrong environment, wrong provider connection, and guessed IDs must not reveal rows.

## No Legacy / No Backward Compatibility Constraint *(mandatory)*

TenantPilot is pre-production unless this spec explicitly records a compatibility exception.

- **Compatibility posture**: canonical Coverage v2 inspection surface; no compatibility exception.
- **Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?**: no.
- **Why clean replacement is safe now**: Coverage v2 remains inactive and internal. No production/customer data, shared staging migration-relevant data, or external contract requires v1/v2 compatibility. This spec must not read legacy snapshots as v2 proof, translate old gap taxonomy into v2 rows, dual-write v1/v2 data, or add fallback readers.

## UI Surface Impact *(mandatory - UI-COV-001)*

Does this spec add, remove, rename, or materially change any reachable UI surface?

- [ ] No UI surface impact
- [ ] Existing page changed
- [x] New page/route added
- [x] Navigation changed
- [x] Filament panel/provider surface changed
- [x] New modal/drawer/wizard/action added
- [x] New table/form/state added
- [ ] Customer-facing surface changed
- [ ] Dangerous action changed
- [x] Status/evidence/review presentation changed
- [x] Workspace/environment context presentation changed

## UI/Productization Coverage *(mandatory when UI Surface Impact is not "No UI surface impact"; otherwise write `N/A - no reachable UI surface impact` plus rationale)*

- **Route/page/surface**: Coverage v2 Readiness at `/admin/tenant-configuration/coverage-v2` or repo-equivalent `/admin` internal operator route.
- **Current or new page archetype**: Technical Annex Page with Read-only Registry / Report Surface behavior.
- **Design depth**: Internal/Hidden / Domain Pattern Surface. It must not become a primary daily decision surface or technical object hub.
- **Repo-truth level**: repo-verified dependencies from Specs 414, 415, and 417; new surface is spec-backed until implemented.
- **Existing pattern reused**: Filament-native `Page`, table widgets or native tables, filters, badges, infolists/sections, primary-link column inspect slideovers where needed; existing OperationRun URL helper; existing workspace/environment/provider scope helpers; existing Product Surface Contract.
- **List surface review checklist**: `docs/product/standards/list-surface-review-checklist.md` applies because this spec adds Read-only Registry / Report table surfaces. The implementation report must record the checklist result or documented exceptions.
- **New pattern required**: none. If implementation cannot express the surface with native Filament/report semantics, stop and document a Product Surface exception before custom Blade.
- **Screenshot required**: no standalone screenshot artifact required by prep, but focused browser proof is required in the implementation report.
- **Page audit required**: update `docs/ui-ux-enterprise-audit/route-inventory.md` and `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` during implementation, or document a bounded exception if that registry format cannot represent this internal surface.
- **Customer-safe review required**: yes, as a negative boundary: customer-facing claims and customer output must remain absent.
- **Dangerous-action review required**: no destructive/high-impact actions are allowed.
- **Coverage files updated or explicitly not needed**:
  - [ ] `docs/ui-ux-enterprise-audit/route-inventory.md`
  - [ ] `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`
  - [ ] `docs/ui-ux-enterprise-audit/page-reports/...`
  - [ ] `docs/ui-ux-enterprise-audit/strategic-surfaces.md`
  - [ ] `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md`
  - [ ] `docs/ui-ux-enterprise-audit/unresolved-pages.md`
  - [ ] `N/A - no reachable UI surface impact`
- **No-impact rationale when applicable**: N/A.

## Product Surface Impact *(mandatory for UI-affecting specs; otherwise write `N/A - no rendered product surface changed` plus rationale)*

Reference: `docs/product/standards/product-surface-contract.md`.

- **Product Surface Contract applies?**: yes. This is a rendered readiness/evidence/provider-state operator surface.
- **Page archetype**: Technical Annex Page.
- **Primary user question**: What prevents Coverage v2 from becoming active proof?
- **Primary action**: Inspect/open read-only details. No mutation, export, capture, publish, restore, or customer report action is allowed.
- **Surface budget result**: Product Surface Contract Technical Annex surface-budget exception documented. The relaxed budget is summary plus two native table data sets (resource types and resource instances). Reason: operators must compare registry support with concrete environment evidence to answer readiness. This is not customer/product-facing because the route is internal/operator-only, diagnostics/raw proof remain disclosed or hidden, and no customer claim is activated. Follow-up: none if default view remains readiness-first, instance rows require environment scope, diagnostics are disclosed, and no raw/customer proof appears.
- **Technical Annex / deep-link demotion**: OperationRun links, evidence hashes, source metadata, provider diagnostics, reason codes, identity fields, source contract state, and missing/present identity fields are secondary diagnostics. Raw payload, normalized payload, permission context raw JSON, tokens, secrets, raw Graph responses, stack traces, and old v1 gap codes are forbidden.
- **Canonical status vocabulary**: top-level readiness may use `Ready`, `Needs attention`, `Blocked`, and `Unknown`. Coverage v2 enum values (`coverage_level`, `evidence_state`, `identity_state`, `claim_state`, `source_class`, `support_state`) are internal diagnostic dimensions and must be labeled as internal/operator readiness, not customer proof.
- **Visible complexity impact**: neutral to reduced for operators, because scattered database/report/test inspection is compressed into one bounded read-only surface.
- **Product Surface exceptions**: one Product Surface Contract Technical Annex surface-budget exception for `Coverage v2 Readiness` as described above. **UI-EX-001 implementation exception**: none when implemented with native Filament tables/infolists/sections/actions. If implementation requires custom UI, stop before building it and name a catalogued UI-EX-001 exception type with proof.

## Browser Verification Plan *(mandatory)*

- **Browser proof required?**: yes.
- **No-browser rationale**: N/A.
- **Focused path when required**: `/admin/tenant-configuration/coverage-v2` or implemented repo-equivalent.
- **Primary interaction to execute**: load the page with an authorized operator, apply or confirm managed-environment context, inspect visible summary/table labels, open one diagnostics disclosure or row inspect model if implemented, and verify forbidden labels/raw content are absent.
- **Console, Livewire, Filament, network, and 500-error checks**: planned. Browser proof must record no console errors, no Livewire/Filament runtime errors, no 500s, and no network calls to Graph/TCM/provider endpoints during render.
- **Full-suite failure triage**: unrelated browser failures may be documented separately only if focused Spec 418 proof is green.

## Human Product Sanity Check *(mandatory)*

- **Required?**: yes.
- **No-human-sanity rationale**: N/A.
- **Reviewer questions**: Can an operator understand why Coverage v2 is or is not activation-ready? Are blockers grouped by actionable v2 states? Does the page avoid noisy technical object hub behavior? Are raw/support details hidden by default? Is there exactly one inspect model? Are old gap labels absent?
- **Planned result location**: `specs/418-coverage-v2-operator-surface/implementation-report.md`.

## Product Surface Merge Gate Checklist *(mandatory)*

- [x] No-legacy posture or approved exception recorded.
- [x] Product Surface Impact is completed or `N/A` is justified.
- [x] Browser proof is required and the focused proof plan is specified for implementation close-out.
- [x] Human Product Sanity is required and the reviewer questions/result location are specified for implementation close-out.
- [x] Product Surface exceptions are documented or `none`.
- [x] Implementation report will state Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, visible complexity outcome, and no completed-spec rewrite assertion.

## Cross-Cutting / Shared Pattern Reuse *(mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write `N/A - no shared interaction family touched`)*

- **Cross-cutting feature?**: yes.
- **Interaction class(es)**: status messaging, navigation entry point, action/deep links, evidence diagnostics, provider provenance, read-only report/table surface.
- **Systems touched**: TenantConfiguration resource type registry, supported scopes, resources, evidence, Claim Guard, identity state, provider connection provenance, OperationRun links, Filament admin panel registration, UI audit registry.
- **Existing pattern(s) to extend**: existing Filament-native page/table/widget patterns, `OperationRunLinks`, workspace/environment/provider scoping helpers, capability/policy helpers, and `BadgeCatalog`/`BadgeRenderer` for status-like badges.
- **Shared contract / presenter / builder / renderer to reuse**: `OperationRunLinks` for operation URLs; `WorkspaceContext`/managed environment access helpers; `BadgeCatalog`/`BadgeRenderer` for status-like readiness, coverage, evidence, identity, claim, source, and support values. If TenantConfiguration state badge mapping is missing, implementation must add a narrow central badge/domain mapping with tests. A page-local display mapper may format non-status text only and must not assign colors, icons, or status semantics.
- **Why the existing shared path is sufficient or insufficient**: Native Filament and existing scope/link helpers are sufficient for the surface. Existing Coverage v2 services provide truth; the missing piece is a derived operator read model and display mapping, not new domain truth.
- **Allowed deviation and why**: none for raw UI frameworks, customer output, or remote calls. The only allowed Product Surface exception is the internal Technical Annex two-table layout.
- **Consistency impact**: Keep labels aligned with existing Coverage v2 enum values and Product Surface top-level readiness vocabulary. Do not introduce parallel old gap labels.
- **Review focus**: Verify native/read-only behavior, one inspect model, no redundant View action, no raw payloads, no OperationRun default proof, no customer-safe claims, and no page-local truth that conflicts with existing v2 services.

## OperationRun UX Impact *(mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an `OperationRun`; otherwise write `N/A - no OperationRun start or link semantics touched`)*

- **Touches OperationRun start/completion/link UX?**: yes, diagnostic links only. No start/completion UX is allowed.
- **Shared OperationRun UX contract/layer reused**: `OperationRunLinks` or current canonical OperationRun URL helper.
- **Delegated start/completion UX behaviors**: none; no queued toast, run-enqueued event, queued DB notification, dedupe messaging, or terminal notification.
- **Local surface-owned behavior that remains**: display an authorized secondary diagnostic link only when the actor may view the referenced run.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception required?**: none.

## Provider Boundary / Platform Core Check *(mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write `N/A - no shared provider/platform boundary touched`)*

- **Shared provider/platform boundary touched?**: yes.
- **Boundary classification**: mixed.
- **Seams affected**: provider connection provenance, source class, source contract metadata, provider connection filters, and provider-owned external IDs as hidden/diagnostic metadata.
- **Neutral platform terms preserved or introduced**: workspace, managed environment, provider connection, resource type, source class, supported scope, coverage level, evidence state, identity state, claim state, activation blocker.
- **Provider-specific semantics retained and why**: Microsoft/Graph/TCM labels may appear only as source class or safe provider metadata because the initial Coverage v2 resource types are Intune-backed.
- **Why this does not deepen provider coupling accidentally**: Provider-specific identifiers stay metadata/diagnostics and never become route, ownership, or platform-core identity truth.
- **Follow-up path**: none for this slice; future resource packs can add source contracts separately.

## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)*

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Coverage v2 Readiness | yes | Native Filament preferred | status messaging, evidence diagnostics, navigation, OperationRun links | page, query/filter, table/detail/disclosure | PSC Technical Annex surface-budget exception only; UI-EX-001 none if native | Read-only internal operator surface; no customer output |

## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)*

| Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction |
|---|---|---|---|---|---|---|---|
| Coverage v2 Readiness | Secondary Context Surface | Review whether Coverage v2 can proceed to the next cutover step | selected workspace/environment, supported scope, readiness counts, critical v2 states, top activation blockers | identity diagnostics, claim guard explanation, capture blocker reason, source contract metadata, evidence hash, authorized OperationRun link | Not primary because it supports readiness inspection and cutover planning, not a daily queue or customer decision | Follows coverage cutover readiness, not storage objects | Replaces scattered DB/test/report inspection with one bounded surface |

## Audience-Aware Disclosure *(mandatory when operator-facing surfaces are changed)*

| Surface | Audience Modes In Scope | Decision-First Default-Visible Content | Operator Diagnostics | Support / Raw Evidence | One Dominant Next Action | Hidden / Gated By Default | Duplicate-Truth Prevention |
|---|---|---|---|---|---|---|---|
| Coverage v2 Readiness | operator/MSP, support/platform diagnostics only | readiness summary, resource type support, coverage/evidence/identity/claim states, top blockers | reason code, missing/present identity fields, source class, source contract state, provider provenance, evidence hash, OperationRun link | raw payloads and normalized payloads remain hidden; no support/raw route added unless existing safe route exists | Inspect read-only details | raw_payload, normalized_payload, permission_context JSON, provider response dumps, secrets/tokens, old v1 gap codes | top summary states blockers once; tables provide evidence dimensions without restating old gap taxonomy |

## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*

| Surface | Action Surface Class | Surface Type | Likely Next Operator Action | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type / Justification |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Coverage v2 Readiness | List / Table / Bulk | Read-only Registry / Report Surface | Inspect blocker or resource readiness | linked primary column opens read-only same-page slide-over | linked primary column; full-row click intentionally avoided for dense comparison tables | disclosed diagnostics/slide-over only | none | `/admin/tenant-configuration/coverage-v2` | N/A or same-page slide-over | workspace, managed environment, supported scope, provider connection filter | Coverage v2 Readiness | coverage level, evidence state, identity state, claim state, source class, supported scope | PSC Technical Annex surface-budget exception only; UI-EX-001 none unless custom UI becomes necessary |

## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*

| Surface | Primary Persona | Decision / Operator Action Supported | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|---|
| Coverage v2 Readiness | TenantPilot operator/reviewer | Determine what blocks Coverage v2 activation | Read-only Registry / Report Surface | What prevents Coverage v2 from becoming active proof? | workspace, managed environment, supported scope, counts, resource type support, instance readiness states, top activation blockers | identity diagnostics, source contract metadata, claim guard explanation, evidence hash, authorized OperationRun link | top readiness plus coverage/evidence/identity/claim/support/source dimensions | none | inspect/open read-only detail | none |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: no. The page derives from existing Coverage v2 tables/services.
- **New persisted entity/table/artifact?**: no. New persisted summary tables and UI-only readiness records are disallowed unless implementation proves query cost cannot be solved with existing tables or narrow indexes.
- **New abstraction?**: yes, likely one thin derived read model/query service and a narrow non-status display mapper where useful. Status-like rendered badges must use `BadgeCatalog`/`BadgeRenderer` or a new central BadgeDomain mapping with tests, not page-local status semantics.
- **New enum/state/reason family?**: no. Use existing `CoverageLevel`, `EvidenceState`, `IdentityState`, `ClaimState`, `SourceClass`, `SupportState`, and existing capture outcomes.
- **New cross-domain UI framework/taxonomy?**: no.
- **Current operator problem**: Operators cannot verify v2 activation readiness or blockers without scattered technical inspection.
- **Existing structure is insufficient because**: Kernel/capture/identity services store truth but do not provide a bounded, authorized, redacted, no-legacy operator inspection surface.
- **Narrowest correct implementation**: One DB-only read model plus one read-only Filament-native page, scoped and tested.
- **Ownership cost**: Maintain the read model, central badge/status mapping, any non-status display mapping, feature/browser tests, scope/redaction/no-legacy guards, and Product Surface close-out as Coverage v2 evolves.
- **Alternative intentionally rejected**: Database inspection, implementation reports, or adding v2 claims to existing customer/report surfaces. Rejected because they either lack RBAC/redaction/product proof or would activate dual customer truth prematurely.
- **Release truth**: Current-release internal readiness inspection after Specs 414/415/417; future customer activation remains deferred.

### Compatibility posture

This feature assumes a pre-production environment. Backward compatibility, legacy aliases, migration shims, historical fixtures, v1 adapters, fallback readers, and dual writes are out of scope.

## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*

- **Test purpose / classification**: Unit for read model/mapper/blocker grouping; Feature for authorization/render/redaction/no-legacy/no-remote/scope; Browser for focused rendered UI smoke.
- **Validation lane(s)**: fast-feedback, confidence, browser. PostgreSQL only if implementation adds/changes database indexes/constraints.
- **Why this classification and these lanes are sufficient**: Read model logic is service-level; authorization/redaction/no-remote behavior requires feature tests; rendered Product Surface compliance requires browser proof.
- **New or expanded test families**: Focused `Spec418*` unit/feature/browser files only. No broad heavy-governance family.
- **Fixture / helper cost impact**: Use existing TenantConfiguration factories and workspace/environment/provider setup. Any browser fixture must be explicit and local to Spec 418.
- **Heavy-family visibility / justification**: none.
- **Special surface test profile**: standard-native-filament plus focused browser smoke.
- **Standard-native relief or required special coverage**: Native Filament relief for layout; browser proof still required because a rendered route changes.
- **Reviewer handoff**: Verify no hidden browser/heavy cost, no broad fixture defaults, no remote calls during render, no old labels, no raw payloads, and exact commands in the implementation report.
- **Budget / baseline / trend impact**: none expected; document if browser or feature fixture cost materially expands.
- **Escalation needed**: document-in-feature for the Product Surface exception; follow-up-spec only if read model/query cost requires structural persistence.
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage.
- **Planned validation commands**:
  - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
  - `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`
  - `git diff --check`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Inspect Coverage v2 Activation Readiness (Priority: P1)

As an operator or reviewer, I need one internal page that summarizes Coverage v2 readiness for a selected workspace and managed environment so I can decide what blocks the next cutover step.

**Why this priority**: This is the core value of Spec 418 and the minimum safe inspection path before cutover.

**Independent Test**: Seed Coverage v2 resource types, resources, evidence, identity states, and claim states. An authorized actor loads the page and sees summary counts and top blocker groups derived from v2 state only.

**Acceptance Scenarios**:

1. **Given** an authorized actor in a workspace with managed-environment entitlement, **When** the actor opens Coverage v2 Readiness, **Then** the page shows selected workspace, managed environment, supported scope, readiness counts, and top activation blockers.
2. **Given** identity conflicts, claim-blocked resources, beta resources, and capture failures exist, **When** the summary is rendered, **Then** blockers are grouped by v2 states such as `identity_conflict`, `claim_blocked`, `beta_experimental`, and `capture_failed`.
3. **Given** legacy v1 gap labels exist elsewhere in the codebase, **When** this page renders, **Then** it does not show `Evidence gaps`, `Raw gaps`, `ambiguous_match`, `policy_record_missing`, `foundation_not_policy_backed`, or `meta_fallback`.

### User Story 2 - Inspect Resource Type Support (Priority: P1)

As an operator, I need to inspect the Coverage v2 resource type registry and supported scope so I can understand which resource types are included, supported, beta/experimental, fallback-backed, and claimable.

**Why this priority**: Activation readiness depends on denominator and support posture before inspecting individual resources.

**Independent Test**: Seed the Spec 414 registry and supported scopes. The resource type table shows required columns and filters without using old gap vocabulary.

**Acceptance Scenarios**:

1. **Given** active resource type definitions exist, **When** the resource type table renders, **Then** it shows human name, canonical type, workload, source class, support state, default coverage level, supported-scope inclusion, beta, graph fallback, and claim behavior.
2. **Given** a filter is applied by workload, source class, support state, supported scope, beta, or claim behavior, **When** the table reloads, **Then** only matching registry rows are shown.
3. **Given** a row detail/inspect model is implemented, **When** an operator opens a row, **Then** there is exactly one inspect model and no redundant View action beside row click or linked primary column.

### User Story 3 - Inspect Resource Instance State Safely (Priority: P1)

As an operator, I need environment-scoped resource instance rows with critical truth visible by default so I can see what concrete captured resources block activation.

**Why this priority**: Resource type readiness without instance/evidence/identity/claim state cannot answer the cutover-readiness question.

**Independent Test**: Seed concrete resources and evidence for two managed environments and provider connections. An authorized actor sees only same-scope rows and the default visible critical state columns.

**Acceptance Scenarios**:

1. **Given** concrete Coverage v2 resources exist for the selected environment, **When** instance rows render, **Then** resource, resource type, provider connection, coverage level, evidence state, identity state, claim state, last captured time, and evidence hash are visible.
2. **Given** a provider connection filter is applied, **When** instance rows render, **Then** cross-environment provider connections do not leak rows or labels.
3. **Given** raw and normalized payloads exist in evidence storage, **When** the page and diagnostics render, **Then** raw payload, normalized payload, permission context raw JSON, tokens, secrets, authorization headers, and raw Graph response dumps are absent.

### User Story 4 - Enforce Scope, Claim Safety, And No Remote Render Work (Priority: P1)

As a security reviewer, I need the surface to enforce workspace/environment/provider isolation, claim-safety language, and DB-only rendering so the inspection page cannot become an activation or data-leak path.

**Why this priority**: Read-only pages can still leak scope, proof, or remote side effects if authorization and render boundaries are weak.

**Independent Test**: Feature tests cover non-member 404, no environment entitlement 404, missing capability 403, authorized view, no Graph/TCM calls during render, no customer-ready claims, no unscoped 100% claim, and no `tenant_id` ownership query.

**Acceptance Scenarios**:

1. **Given** a non-member guesses the route, **When** they request it, **Then** the response is 404.
2. **Given** a workspace member lacks entitlement to the selected environment, **When** they request the surface, **Then** the response is 404.
3. **Given** a member has environment entitlement but lacks the view capability, **When** they request the surface, **Then** the response is 403.
4. **Given** the page renders for an authorized actor, **When** the request completes, **Then** no Graph/TCM/provider client call occurred during render.

### Edge Cases

- No managed environment selected: the page may show registry/resource type readiness but must require an environment filter before instance rows render, or redirect to the repo-standard environment selection path.
- No supported scopes exist: fail closed with `Unknown` or `Blocked` readiness and clear internal copy that supported scope is missing.
- No captured resources exist: show `not_captured` blockers and no raw debug output.
- Identity conflicts with no latest evidence: show identity and claim blockers without fabricating evidence hash.
- OperationRun reference is missing or unauthorized: omit or disable the diagnostic link without exposing the run ID.
- Beta/experimental resources are present: group separately and never label them certified or customer-ready.
- Graph fallback resources are present: show source class/fallback posture as internal readiness, not equal customer proof.
- Empty evidence hash: display as unavailable, not as proof.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-418-001**: The system MUST add exactly one bounded internal Coverage v2 Readiness operator surface.
- **FR-418-002**: The surface MUST be read-only and MUST NOT add capture, sync, restore, apply, certify, publish, export, report, review-pack, or manual claim-override actions.
- **FR-418-003**: The surface MUST use Coverage v2 data and services only: resource type registry, supported scopes, resources, evidence, identity state, and Claim Guard output.
- **FR-418-004**: The surface MUST NOT use legacy snapshots, Coverage v1 gap taxonomy, v1 subject matching, v1-to-v2 adapters, fallback readers, or dual-write paths as v2 proof.
- **FR-418-005**: The page render path MUST be DB-only and MUST NOT call Microsoft Graph, TCM, provider gateways, capture services, remote verification services, or remote clients.
- **FR-418-006**: The default route SHOULD be `/admin/tenant-configuration/coverage-v2`; any repo-equivalent route deviation MUST be documented in the implementation report.
- **FR-418-007**: The surface MUST show selected workspace, managed environment, supported scope, provider connection filter when applicable, source class filter, and last updated or last captured time.
- **FR-418-008**: Resource instance rows MUST require managed environment scope unless implementation proves workspace-wide aggregation is safe across only entitled environments.
- **FR-418-009**: The readiness summary MUST include `resource_types_total`, `resources_total`, `content_backed_count`, `identity_conflict_count`, `claim_allowed_count`, `claim_limited_count`, `claim_blocked_count`, `beta_experimental_count`, and `graph_fallback_count`.
- **FR-418-010**: Summary counts MUST derive from Coverage v2 state and MUST NOT derive from old v1 gap labels or old snapshot classifications.
- **FR-418-011**: The resource type table MUST show human name, canonical type, workload, source class, support state, default coverage level, supported-scope inclusion, beta indicator, Graph fallback indicator, and claim behavior.
- **FR-418-012**: The resource type table MUST provide filters for workload, source class, support state, supported scope, beta/non-beta, and claim behavior.
- **FR-418-013**: The resource instance table or grouped view MUST show resource, resource type, provider connection, coverage level, evidence state, identity state, claim state, last captured time, and evidence hash.
- **FR-418-014**: The resource instance table MUST provide filters for resource type, provider connection, coverage level, evidence state, identity state, claim state, and source class.
- **FR-418-015**: Critical truth MUST be visible by default: `coverage_level`, `evidence_state`, `identity_state`, and `claim_state`.
- **FR-418-016**: Activation blockers MUST be grouped by v2 states, including `identity_conflict`, `missing_external_id`, `unsupported_identity`, `not_captured`, `permission_blocked`, `source_unavailable`, `schema_unknown`, `capture_failed`, `claim_blocked`, and `beta_experimental`. Top blocker ordering MUST be deterministic: identity and claim blockers first, capture/source blockers next, beta/experimental blockers after non-beta blockers, then count descending, then stable blocker key ascending.
- **FR-418-017**: Diagnostics MAY show reason code, missing identity fields, present identity fields, source class, source contract state, authorized OperationRun link, evidence hash, and provider connection provenance.
- **FR-418-018**: Diagnostics MUST be secondary/disclosed and MUST NOT be primary visual content.
- **FR-418-019**: Raw payload, normalized payload, permission context raw JSON, access tokens, refresh tokens, ID tokens, client secrets, passwords, private keys, certificates, authorization headers, cookies, raw exception messages, stack traces, raw Graph responses, and unredacted PII MUST NOT be displayed.
- **FR-418-020**: Evidence hash MAY be displayed and copied only if safe and useful.
- **FR-418-021**: OperationRun diagnostic links MAY appear only through the canonical helper and only when the actor is authorized to view the run.
- **FR-418-022**: OperationRun links MUST be secondary diagnostics and MUST NOT be treated as default proof.
- **FR-418-023**: The surface MUST show Claim Guard results only as internal/operator readiness labels: `Claim allowed`, `Claim limited`, `Claim blocked`, or `Internal only`; when rendered as status-like badges, these labels MUST use `BadgeCatalog`/`BadgeRenderer` or a central BadgeDomain mapping, not page-local color/status mapping.
- **FR-418-024**: The surface MUST NOT produce or activate customer-facing Coverage v2 claims.
- **FR-418-025**: The surface MUST NOT show unscoped `100%` claims. Any 100% statement must be explicitly internal, scoped, and allowed by Claim Guard for the exact selected scope and level.
- **FR-418-026**: The surface MUST NOT show customer-facing phrases such as `100% Microsoft 365 coverage`, `Complete tenant coverage`, `Certified coverage`, `Restore-ready`, `Full evidence coverage`, or `Customer-ready proof`.
- **FR-418-027**: The default UI MUST NOT show old labels: `Evidence gaps`, `Raw gaps`, `Primary gaps`, `Partially complete`, `Incomplete result`, `ambiguous_match`, `policy_record_missing`, `foundation_not_policy_backed`, or `meta_fallback`.
- **FR-418-028**: The surface MUST enforce non-member workspace access as 404.
- **FR-418-029**: The surface MUST enforce workspace member without managed-environment entitlement as 404.
- **FR-418-030**: The surface MUST enforce member without the required view capability as 403 after membership and environment entitlement are established.
- **FR-418-031**: Provider connection filters MUST be same-workspace and same-managed-environment, and MUST NOT reveal cross-environment records or labels.
- **FR-418-032**: The implementation MUST NOT introduce `tenant_id` as Coverage v2 ownership truth, compatibility alias, fallback reader, dual-write target, or query scope.
- **FR-418-033**: Resource type registry rows MAY be workspace-wide product metadata, but environment-owned evidence/resources MUST be scoped and authorized by workspace and managed environment.
- **FR-418-034**: The implementation SHOULD prefer a thin derived read model over persisted summary tables.
- **FR-418-035**: New persisted UI-only summary records are disallowed unless the active spec is amended with a proportionality review and query-cost proof.
- **FR-418-036**: If query cost is high, implementation MAY add narrow indexes with a documented query path and rollback/forward migration note.
- **FR-418-037**: The surface MUST use native Filament components where possible, MUST use central badge/status primitives for status-like values, and MUST NOT ship a fake-native Blade request UI when native table/report semantics fit.
- **FR-418-038**: Each table/detail surface MUST have exactly one primary inspect/open model; redundant View actions beside row click or linked primary column are forbidden.
- **FR-418-039**: The implementation MUST update or explicitly handle UI audit registry artifacts for the new route according to UI-COV-001 and MUST apply `docs/product/standards/list-surface-review-checklist.md` for the new list/table surfaces.
- **FR-418-040**: The implementation report MUST include candidate gate result, dirty state before/after, files changed, route/surface added, Product Surface classification, UI Action Matrix, Human Product Sanity, browser proof, authorization proof, redaction proof, no remote render proof, no-tenant_id confirmation, no-legacy/no-dual-truth confirmation, tests run, and deferred work.

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Coverage v2 Readiness | `/admin/tenant-configuration/coverage-v2` or repo-equivalent Filament page | none, except neutral scope/filter reset if repo pattern requires | linked primary column opens read-only same-page slide-over | none by default; optional copy evidence hash only if safe | none | explain missing environment/filter/capture state; optional clear filters only | N/A | N/A | no mutation audit required; diagnostic open audit only if repo pattern requires | read-only internal Technical Annex; two-table Product Surface exception; no separate row action column |

### Key Entities *(include if feature involves data)*

- **Tenant Configuration Resource Type**: Existing Coverage v2 resource type definition with canonical type, display name, workload, source class, support state, coverage defaults, claim defaults, beta/fallback flags, and metadata.
- **Tenant Configuration Supported Scope**: Existing supported-scope denominator contract from Spec 414.
- **Tenant Configuration Resource**: Existing environment-owned concrete Coverage v2 resource observed in a workspace/managed environment/provider connection with latest evidence, identity, claim, and capture metadata.
- **Tenant Configuration Resource Evidence**: Existing append-only evidence row with payload hash, coverage/evidence state, capture outcome, captured timestamp, operation run, and redacted source/permission metadata. Raw payloads remain hidden.
- **Provider Connection**: Existing same-scope provenance and filter dimension.
- **OperationRun**: Existing execution truth for capture operations; may be linked only as secondary authorized diagnostics.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-418-001**: An authorized operator can load one Coverage v2 Readiness surface and identify the top activation blockers without inspecting database rows or implementation reports.
- **SC-418-002**: Focused feature tests prove non-member 404, no environment entitlement 404, missing capability 403, and authorized 200 behavior.
- **SC-418-003**: Focused tests prove readiness counts derive from Coverage v2 states and no old v1 gap labels are emitted.
- **SC-418-004**: Focused tests prove raw payloads, normalized payloads, permission context raw JSON, tokens, secrets, authorization headers, and raw provider responses do not render.
- **SC-418-005**: Focused tests or static guards prove no Graph/TCM/provider remote call happens during page render.
- **SC-418-006**: Browser smoke proves the rendered page shows Coverage level, Evidence state, Identity state, Claim state, Source class, and Supported scope, and does not show old gap labels, raw payload, or customer-ready coverage claims.
- **SC-418-007**: Implementation report records Product Surface classification, browser proof, Human Product Sanity, no-legacy/no-dual-truth, no-tenant_id, redaction, authorization, no remote render, and deployment impact.

## Assumptions

- Specs 414, 415, and 417 remain accepted dependency context and their implementation reports are authoritative.
- Coverage v2 remains inactive for customer claims through this spec.
- The initial resource type registry contains the eight Spec 414/415/417 resource types.
- The correct view capability will be confirmed during implementation against current RBAC patterns; no raw role-string checks are allowed.
- A native Filament Page plus native tables/widgets/infolists can satisfy the surface without custom product UI.
- There is no safe raw evidence route that must be introduced in this spec.

## Risks

| Risk | Severity | Mitigation |
|---|---:|---|
| Surface becomes technical object hub | High | Secondary Context classification; Technical Annex budget exception; readiness question first; diagnostics disclosed |
| v2 appears as active customer truth | High | internal/operator language, no customer surfaces, no output/download actions, claim safety tests |
| Old gap vocabulary leaks into UI | High | unit/feature/browser assertions |
| Raw payloads or secrets leak | High | redaction tests; no raw/default display |
| Remote work during render | High | DB-only read model; fake/failing remote client tests or static guard |
| Scope leakage across workspace/environment/provider | High | positive and negative authorization/filter tests |
| New persisted UI summary bloat | Medium | derived read model only; narrow-index fallback with proof |
| Too much browser proof | Medium | focused smoke only |

## Follow-Up Spec Candidates

- Spec 419 - Legacy Coverage Cutover and Removal.
- Spec 420 - Intune Core Comparable/Renderable Pack.
- Spec 421 - Certified Intune Core Coverage Pack.
- Spec 422 - Pilot Readiness Gate.
- Customer-facing Coverage v2 output.
- Evidence Overview v2 conversion.
- Review Pack/report v2 conversion.
- Restore Readiness v2 conversion.
- Capture start action.
- Identity re-evaluation action.
- Compare/render/restore/certification.
- Full v1 runtime removal.