# 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

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

## Phase 1: Preflight And Dependencies

- [x] T001 Capture branch, HEAD, and `git status --short` in `specs/418-coverage-v2-operator-surface/implementation-report.md`.
- [x] 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.
- [x] T003 Confirm current Coverage v2 models/services exist: `TenantConfigurationResourceType`, `TenantConfigurationSupportedScope`, `TenantConfigurationResource`, `TenantConfigurationResourceEvidence`, `ClaimGuard`, and identity/coverage/evidence/claim/source enums.
- [x] 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`.
- [x] 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.
- [x] 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

- [x] 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.
- [x] 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.
- [x] 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.
- [x] 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

- [x] T011 Add `apps/platform/tests/Unit/Support/TenantConfiguration/CoverageV2ReadinessSummaryTest.php` proving summary counts derive from v2 states only.
- [x] 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.
- [x] 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.
- [x] 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

- [x] T015 Add `apps/platform/tests/Feature/TenantConfiguration/Spec418CoverageV2OperatorSurfaceAuthorizationTest.php` covering authorized view, non-member 404, no environment entitlement 404, and missing capability 403.
- [x] 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.
- [x] T017 Add `apps/platform/tests/Feature/TenantConfiguration/Spec418CoverageV2OperatorSurfaceNoLegacyLabelsTest.php` proving old v1 labels and customer-ready coverage claims are absent from rendered output.
- [x] 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.
- [x] 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.
- [x] T020 Add a feature/static guard proving `tenant_id` is not introduced as Coverage v2 ownership truth or read-model query scope.
- [x] T021 Add provider connection filter tests proving cross-environment provider connections cannot reveal records or labels.
- [x] 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

- [x] 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.
- [x] 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.
- [x] 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`.
- [x] T026 Ensure blocker grouping derives from `EvidenceState`, `IdentityState`, `ClaimState`, `SourceClass`, `SupportState`, and capture outcomes rather than old gap taxonomy, with deterministic top-blocker ordering.
- [x] 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.
- [x] 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

- [x] T029 Add `apps/platform/app/Filament/Pages/TenantConfiguration/CoverageV2Readiness.php` or repo-equivalent Filament Page at `/admin/tenant-configuration/coverage-v2`.
- [x] 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.
- [x] 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.
- [x] 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`.
- [x] 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.
- [x] T034 Implement scope summary: workspace, managed environment, supported scope, provider connection filter, source class filter, and last captured/updated time.
- [x] T035 Implement readiness summary with compact counts and deterministically ordered top activation blockers.
- [x] T036 Implement resource type table columns and filters from `spec.md`.
- [x] 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.
- [x] T038 Implement diagnostics disclosure using native infolists/sections/slide-over where possible.
- [x] T039 Ensure each table/detail surface has exactly one inspect/open model and no redundant View action beside row click or linked primary column.
- [x] T040 Ensure empty states explain missing environment/filter/capture state and do not leak inaccessible environments or provider connections.

## Phase 7: Authorization And Scope

- [x] T041 Enforce workspace membership before rendering and return 404 for non-members.
- [x] T042 Enforce managed environment entitlement and return 404 when the actor is not entitled to the requested environment.
- [x] T043 Enforce the selected view capability and return 403 when membership and entitlement exist but capability is missing.
- [x] T044 Ensure provider connection filters and rows are same-workspace and same-managed-environment.
- [x] T045 Ensure workspace-wide mode, if implemented, aggregates only across environments the actor is entitled to view.
- [x] 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

- [x] 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.
- [x] T048 Block unscoped 100% claims and all customer-facing phrases forbidden by `spec.md`.
- [x] T049 Hide raw payload, normalized payload, permission context raw JSON, tokens, secrets, PII, raw Graph responses, raw exception messages, and stack traces.
- [x] T050 Ensure old v1 labels never appear in page, view model, diagnostics, filters, empty states, browser fixture copy, or tests as active UI truth.
- [x] T051 Ensure no Graph/TCM/provider remote call can execute during render, table columns, badges, filters, or diagnostics disclosure.
- [x] 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

- [x] T053 Add `apps/platform/tests/Browser/Spec418CoverageV2OperatorSurfaceSmokeTest.php`.
- [x] T054 Browser smoke must load the route as an authorized actor without console, Livewire, Filament, network, or 500 errors.
- [x] T055 Browser smoke must assert visible labels: `Coverage level`, `Evidence state`, `Identity state`, `Claim state`, `Source class`, and `Supported scope`.
- [x] 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.
- [x] 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

- [x] T058 Run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`.
- [x] 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`.
- [x] 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`.
- [x] T061 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec418CoverageV2OperatorSurfaceSmokeTest.php`.
- [x] T062 If migrations/indexes were added, run the focused PostgreSQL lane for affected TenantConfiguration tests.
- [x] T063 Run `git diff --check`.
- [x] 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.
- [x] 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.