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
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• 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)

• No-legacy posture or approved exception recorded.
• Product Surface Impact is completed or N/A is justified.
• Browser proof is required and the focused proof plan is specified for implementation close-out.
• Human Product Sanity is required and the reviewer questions/result location are specified for implementation close-out.
• Product Surface exceptions are documented or none.
• 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.