Tasks: Spec 418 - Coverage v2 Operator Surface

Input: specs/418-coverage-v2-operator-surface/spec.md, specs/418-coverage-v2-operator-surface/plan.md, specs/418-coverage-v2-operator-surface/checklists/requirements.md Prerequisites: completed Specs 414, 415, and 417 as read-only dependency context

Tests: Required. Runtime UI/security behavior must be covered with focused Pest unit, feature, and browser tests. PostgreSQL lane is required only if migrations/indexes/constraints change.

Implementation note: The planned Unit/Feature test responsibilities were completed through repo-equivalent focused files: tests/Unit/TenantConfiguration/CoverageV2ReadinessBadgeTest.php, tests/Feature/Filament/CoverageV2ReadinessPageTest.php, and tests/Feature/TenantConfiguration/CoverageV2ReadinessGuardTest.php. The browser proof uses the planned tests/Browser/Spec418CoverageV2OperatorSurfaceSmokeTest.php name.

Test Governance Checklist

Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
New or changed tests stay in Unit/Feature/Browser lanes; any PostgreSQL or heavy-governance addition is explicit.
Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default and opt-in.
Planned validation commands cover the change without pulling unrelated lane cost.
Browser proof is required because rendered UI changes.
Human Product Sanity and Product Surface close-out are completed in the implementation report.
Material budget, baseline, trend, or escalation notes are recorded if test cost changes.

Phase 1: Preflight And Dependencies

T001 Capture branch, HEAD, and git status --short in specs/418-coverage-v2-operator-surface/implementation-report.md.
T002 Confirm specs/414-tcm-first-coverage-core-cutover/implementation-report.md, specs/415-generic-content-backed-capture/implementation-report.md, and specs/417-canonical-identity-engine/implementation-report.md are present and accepted context only; do not modify those packages.
T003 Confirm current Coverage v2 models/services exist: TenantConfigurationResourceType, TenantConfigurationSupportedScope, TenantConfigurationResource, TenantConfigurationResourceEvidence, ClaimGuard, and identity/coverage/evidence/claim/source enums.
T004 Inspect current Filament page/table/widget patterns in apps/platform/app/Filament/Pages, apps/platform/app/Filament/Resources, and apps/platform/app/Providers/Filament/AdminPanelProvider.php.
T005 Inspect current workspace/environment/provider authorization helpers and decide whether Capabilities::EVIDENCE_VIEW, Capabilities::TENANT_VIEW, or a new narrow coverage-readiness capability is the correct gate.
T006 Stop before implementation if any prerequisite from Specs 414/415/417 is missing or if implementation would need customer output, capture start, remote work, v1 adapter, old snapshot promotion, or legacy compatibility.

Phase 2: Product Surface Contract Before UI Edits

T007 Record Product Surface Impact, affected route, Decision Role, Surface Type, Native Surface classification, primary operator question, default-visible truth, diagnostics boundary, raw evidence boundary, action model, browser proof criteria, and Human Product Sanity criteria in the implementation report draft.
T008 Record the UI Action Matrix for Coverage v2 Readiness: inspect model only, no header mutation actions, no row mutation actions, no bulk actions, no destructive actions, no remote work.
T009 Document the Product Surface Contract Technical Annex surface-budget exception and spread-control rule in the implementation report; explicitly state UI-EX-001 = none if the implementation remains native Filament, or stop and name a catalogued UI-EX-001 exception before custom UI work.
T010 Update docs/ui-ux-enterprise-audit/route-inventory.md and docs/ui-ux-enterprise-audit/design-coverage-matrix.md, apply docs/product/standards/list-surface-review-checklist.md, and record the checklist result or documented exception in the implementation report.

Phase 3: Tests First - Read Model And Display Mapping

T011 Add apps/platform/tests/Unit/Support/TenantConfiguration/CoverageV2ReadinessSummaryTest.php proving summary counts derive from v2 states only.
T012 Add apps/platform/tests/Unit/Support/TenantConfiguration/CoverageV2ActivationBlockerGroupingTest.php proving blockers group by identity_conflict, missing_external_id, unsupported_identity, not_captured, permission_blocked, source_unavailable, schema_unknown, capture_failed, claim_blocked, and beta_experimental, and that top blocker ordering is deterministic by blocker priority, count descending, then stable key ascending.
T013 Add apps/platform/tests/Unit/Support/TenantConfiguration/CoverageV2ClaimGuardDisplayMapperTest.php or repo-equivalent tests proving Claim Guard results map to Claim allowed, Claim limited, Claim blocked, and Internal only without customer-ready wording, and that status-like rendered badges use BadgeCatalog/BadgeRenderer or a central BadgeDomain mapping rather than page-local color/status mapping.
T014 Add a unit or feature assertion proving old labels are not emitted by the read model or display mapper: Evidence gaps, Raw gaps, Primary gaps, ambiguous_match, policy_record_missing, foundation_not_policy_backed, and meta_fallback.

Phase 4: Tests First - Surface Authorization, Scope, Redaction, And No Remote Render

T015 Add apps/platform/tests/Feature/TenantConfiguration/Spec418CoverageV2OperatorSurfaceAuthorizationTest.php covering authorized view, non-member 404, no environment entitlement 404, and missing capability 403.
T016 Add apps/platform/tests/Feature/TenantConfiguration/Spec418CoverageV2OperatorSurfaceTest.php proving resource type registry rows, supported scope, readiness summary, resource instance states, and filters render for an authorized actor.
T017 Add apps/platform/tests/Feature/TenantConfiguration/Spec418CoverageV2OperatorSurfaceNoLegacyLabelsTest.php proving old v1 labels and customer-ready coverage claims are absent from rendered output.
T018 Add apps/platform/tests/Feature/TenantConfiguration/Spec418CoverageV2OperatorSurfaceRedactionTest.php proving raw payloads, normalized payloads, permission context raw JSON, tokens, secrets, authorization headers, raw Graph responses, exception dumps, and unredacted PII are absent.
T019 Add a feature/static guard proving the page render path does not call Graph/TCM/provider clients and no capture/start action is registered.
T020 Add a feature/static guard proving tenant_id is not introduced as Coverage v2 ownership truth or read-model query scope.
T021 Add provider connection filter tests proving cross-environment provider connections cannot reveal records or labels.
T022 Add OperationRun diagnostic link tests proving links use the canonical helper, appear only when authorized, and remain secondary diagnostics.

Phase 5: DB-Only Read Model

T023 Add apps/platform/app/Services/TenantConfiguration/CoverageV2ReadinessReadModel.php or repo-equivalent thin query service for summary counts, resource type rows, instance rows, activation blockers, and diagnostics payloads.
T024 Ensure the read model queries existing Coverage v2 tables only and does not create persisted UI summaries, denormalized readiness records, fallback readers, or v1 adapters.
T025 Ensure summary counts 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.
T026 Ensure blocker grouping derives from EvidenceState, IdentityState, ClaimState, SourceClass, SupportState, and capture outcomes rather than old gap taxonomy, with deterministic top-blocker ordering.
T027 Ensure diagnostics are sanitized to reason codes, missing/present identity fields, source class, source contract state, provider provenance, evidence hash, and authorized OperationRun link only.
T028 If query cost requires an index, add a narrow reversible migration with a documented query path and PostgreSQL validation; otherwise document no migration.

Phase 6: Filament Native Surface

T029 Add apps/platform/app/Filament/Pages/TenantConfiguration/CoverageV2Readiness.php or repo-equivalent Filament Page at /admin/tenant-configuration/coverage-v2.
T030 Add native summary widgets/tables under apps/platform/app/Filament/Widgets/TenantConfiguration/ or a repo-equivalent native Filament structure for readiness summary, activation blockers, resource types, and resource instances.
T031 Add the minimal Blade wrapper only if required by Filament page composition, e.g. apps/platform/resources/views/filament/pages/tenant-configuration/coverage-v2-readiness.blade.php; do not build fake-native request UI.
T032 Register the page in apps/platform/app/Providers/Filament/AdminPanelProvider.php or rely on existing discovery if repo conventions support it; do not move provider registration from apps/platform/bootstrap/providers.php.
T033 Add a secondary navigation entry only if it fits repo IA; it must not replace Evidence Overview, Baseline Compare, Customer Review Workspace, Review Packs, Reports, or Restore Readiness.
T034 Implement scope summary: workspace, managed environment, supported scope, provider connection filter, source class filter, and last captured/updated time.
T035 Implement readiness summary with compact counts and deterministically ordered top activation blockers.
T036 Implement resource type table columns and filters from spec.md.
T037 Implement resource instance table columns and filters from spec.md; require managed environment scope for instance rows unless safe entitled workspace-wide aggregation is implemented and tested.
T038 Implement diagnostics disclosure using native infolists/sections/slide-over where possible.
T039 Ensure each table/detail surface has exactly one inspect/open model and no redundant View action beside row click or linked primary column.
T040 Ensure empty states explain missing environment/filter/capture state and do not leak inaccessible environments or provider connections.

Phase 7: Authorization And Scope

T041 Enforce workspace membership before rendering and return 404 for non-members.
T042 Enforce managed environment entitlement and return 404 when the actor is not entitled to the requested environment.
T043 Enforce the selected view capability and return 403 when membership and entitlement exist but capability is missing.
T044 Ensure provider connection filters and rows are same-workspace and same-managed-environment.
T045 Ensure workspace-wide mode, if implemented, aggregates only across environments the actor is entitled to view.
T046 If a new capability is required, add it to apps/platform/app/Support/Auth/Capabilities.php, update role mapping in the repo-equivalent capability map, and add policy/capability tests.

Phase 8: Claim Safety, Redaction, No-Legacy, And No-Remote Guards

T047 Display Claim Guard results only as internal/operator labels: Claim allowed, Claim limited, Claim blocked, Internal only; use central badge/status primitives for status-like rendering.
T048 Block unscoped 100% claims and all customer-facing phrases forbidden by spec.md.
T049 Hide raw payload, normalized payload, permission context raw JSON, tokens, secrets, PII, raw Graph responses, raw exception messages, and stack traces.
T050 Ensure old v1 labels never appear in page, view model, diagnostics, filters, empty states, browser fixture copy, or tests as active UI truth.
T051 Ensure no Graph/TCM/provider remote call can execute during render, table columns, badges, filters, or diagnostics disclosure.
T052 Ensure no start capture, sync, restore, publish, export, certify, apply, identity re-evaluate, or manual claim override action is added.

Phase 9: Browser Smoke

T053 Add apps/platform/tests/Browser/Spec418CoverageV2OperatorSurfaceSmokeTest.php.
T054 Browser smoke must load the route as an authorized actor without console, Livewire, Filament, network, or 500 errors.
T055 Browser smoke must assert visible labels: Coverage level, Evidence state, Identity state, Claim state, Source class, and Supported scope.
T056 Browser smoke must assert absence of Evidence gaps, Raw gaps, policy_record_missing, foundation_not_policy_backed, meta_fallback, ambiguous_match, raw payload, and customer-ready coverage claims.
T057 If browser environment is unavailable, document the exact blocker and do not mark browser proof as PASS without an accepted no-browser exception.

Phase 10: Validation And Close-Out

T058 Run cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent.
T059 Run 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.
T060 Run 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.
T061 Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec418CoverageV2OperatorSurfaceSmokeTest.php.
T062 If migrations/indexes were added, run the focused PostgreSQL lane for affected TenantConfiguration tests.
T063 Run git diff --check.
T064 Complete specs/418-coverage-v2-operator-surface/implementation-report.md with candidate gate result, dirty state before/after, files changed, route/surface, Product Surface classification, UI Action Matrix, browser proof, Human Product Sanity, authorization proof, redaction proof, no remote render proof, no-tenant_id confirmation, no-legacy/no-dual-truth confirmation, tests, deployment impact, and deferred work.
T065 Confirm no completed historical spec was rewritten or stripped of close-out, validation, task, smoke, browser, or review history.

Stop Conditions

Stop and update spec.md, plan.md, and tasks.md before continuing if any of these appear:

A customer-facing Coverage v2 claim, Review Pack/report output, Customer Review Workspace output, Evidence Overview conversion, Baseline Compare conversion, or Restore Readiness conversion is needed.
A capture/start, sync, restore, apply, certify, publish, export, identity re-evaluate, or manual claim override action is needed.
Graph/TCM/provider remote work is needed during page render.
Raw payloads, normalized payloads, permission context raw JSON, tokens, secrets, PII, raw provider responses, or raw exception dumps need to render.
Old v1 gap vocabulary appears as current UI truth.
tenant_id is introduced as Coverage v2 ownership truth.
A v1-to-v2 adapter, fallback reader, old snapshot promotion, dual write, or fallback-to-latest proof path is introduced.
Provider connection filtering can reveal cross-workspace or cross-environment records.
Page-local status-like badge/color/icon semantics are introduced instead of BadgeCatalog/BadgeRenderer or central BadgeDomain mapping.
Custom UI is needed but no catalogued UI-EX-001 exception is named before implementation.
Browser proof is missing without an accepted no-browser exception.

16 KiB Raw Blame History