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

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.