TenantAtlas/specs/415-generic-content-backed-capture/tasks.md

# Tasks: Spec 415 - Generic Content-Backed Capture

**Input**: Design documents from `/specs/415-generic-content-backed-capture/`
**Prerequisites**: `spec.md`, `plan.md`, `checklists/requirements.md`, completed Spec 414 context

## 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/PostgreSQL lanes; any heavy-governance or browser addition is explicit and requires spec amendment.
- [x] Shared helpers, factories, seeds, fixtures, provider setup, workspace context, membership context, and Graph fakes stay explicit and opt-in.
- [x] Planned validation commands cover the change without pulling in unrelated lane cost.
- [x] Browser proof is explicitly `N/A - no rendered UI surface changed`.
- [x] Human Product Sanity is `N/A - no product surface changed`.
- [x] Any material budget, baseline, trend, or escalation note is recorded in the implementation report.

## Phase 1: Preflight And Repo Verification

**Purpose**: Confirm the active repo truth before runtime implementation starts.

- [x] T001 Capture branch, HEAD, `git status --short`, and Spec 414 dependency status in `specs/415-generic-content-backed-capture/implementation-report.md`.
- [x] T002 Confirm `specs/414-tcm-first-coverage-core-cutover/` is completed/validated context only and do not modify any Spec 414 artifact.
- [x] T003 Inspect `apps/platform/app/Models/TenantConfigurationResourceType.php`, `apps/platform/app/Models/TenantConfigurationSupportedScope.php`, `apps/platform/app/Services/TenantConfiguration/ResourceTypeRegistry.php`, `SupportedScopeResolver.php`, and `ClaimGuard.php` to map the existing kernel dependency surface.
- [x] T004 Inspect `apps/platform/database/migrations/2026_06_25_000414_create_tenant_configuration_kernel_tables.php` for the initial resource types, source classes, supported scopes, and no-`tenant_id` kernel posture.
- [x] T005 Confirm whether `tenant_configuration_resources` / `tenant_configuration_resource_evidence` or repo-equivalent models/tables already exist; if they do, document the exact equivalent and adjust implementation without duplicate tables.
- [x] T006 Inspect `apps/platform/config/graph_contracts.php` and `apps/platform/app/Services/Graph/GraphContractRegistry.php` for explicit contracts related to the initial 414 resource types.
- [x] T007 Confirm no rendered UI surface, route, navigation entry, Filament provider/panel, review/report/evidence output, or customer-visible v2 activation is required. If it is required, stop and patch `spec.md`, `plan.md`, and `tasks.md`.

## Phase 2: Tests First - Pure Behavior

**Purpose**: Prove source resolution, normalization, hashing, redaction, and outcomes before implementation.

- [x] T008 [P] Add resolver unit tests in `apps/platform/tests/Unit/Support/TenantConfiguration/Spec415CoverageSourceContractResolverTest.php` covering explicit contract, missing contract, beta blocked by default, unsupported/out-of-scope skip, and no endpoint guessing.
- [x] T009 [P] Add normalizer/hash unit tests in `apps/platform/tests/Unit/Support/TenantConfiguration/Spec415GenericPayloadNormalizerTest.php` covering stable key ordering, configured volatile-field handling, metadata separation, and deterministic hash.
- [x] T010 [P] Add redaction unit tests in `apps/platform/tests/Unit/Support/TenantConfiguration/Spec415CoverageRedactionTest.php` covering token/secret-like keys and sanitized permission/source context.
- [x] T011 [P] Add outcome unit tests in `apps/platform/tests/Unit/Support/TenantConfiguration/Spec415CoverageCaptureOutcomeTest.php` covering allowed v2 outcomes and absence of old v1 gap vocabulary.
- [x] T012 [P] Add OperationRun summary unit/guard coverage ensuring Spec 415 uses existing `OperationSummaryKeys` keys unless a tested canonical key-list extension is explicitly implemented.

## Phase 3: Tests First - Runtime And Persistence

**Purpose**: Prove the end-to-end safety contract with fake provider calls.

- [x] T013 [P] Add persistence feature tests in `apps/platform/tests/Feature/TenantConfiguration/Spec415CoverageEvidencePersistenceTest.php` for concrete resource upsert, append-only evidence writes, JSONB raw/normalized payloads, payload hash, source metadata, and OperationRun link.
- [x] T014 [P] Add provider connection scope tests in `apps/platform/tests/Feature/TenantConfiguration/Spec415ProviderConnectionScopeTest.php` proving same workspace/environment allowed and cross-workspace or cross-environment provider connections rejected.
- [x] T015 [P] Add authorization tests in `apps/platform/tests/Feature/TenantConfiguration/Spec415CoverageCaptureAuthorizationTest.php` proving non-member 404, missing environment entitlement 404, missing capability 403, readonly denial, and authorized start.
- [x] T016 [P] Add OperationRun tests in `apps/platform/tests/Feature/TenantConfiguration/Spec415CoverageCaptureOperationRunTest.php` proving `tenant_configuration.capture` run creation/reuse, queued job dispatch, service-owned transitions, sanitized context, and numeric summary counts.
- [x] T017 [P] Add fake Graph capture tests in `apps/platform/tests/Feature/TenantConfiguration/Spec415GenericContentBackedCaptureTest.php` proving `GraphClientInterface` is used and real Graph/TCM is never called.
- [x] T018 [P] Add no-legacy/no-UI guard tests in `apps/platform/tests/Feature/TenantConfiguration/Spec415NoLegacyNoUiActivationTest.php` proving no `tenant_id` ownership field, no v1 adapter/dual-write/fallback reader/old snapshot promotion, no old gap outcomes, and no Filament resource/page/route/navigation activation.

## Phase 4: Persistence Implementation

**Purpose**: Add durable v2 resource/evidence truth only if missing.

- [x] T019 Add migration under `apps/platform/database/migrations/` for `tenant_configuration_resources` if no equivalent exists, with `workspace_id`, `managed_environment_id`, `provider_connection_id`, `resource_type_id`, source class, canonical identity fields, latest coverage/evidence/identity/claim state, timestamps, and no `tenant_id`.
- [x] T020 Add migration under `apps/platform/database/migrations/` for `tenant_configuration_resource_evidence` if no equivalent exists, with resource/workspace/environment/provider/run links, source endpoint/version/schema metadata, JSONB raw payload, JSONB normalized payload, payload hash, redacted permission context, coverage/evidence state, captured timestamp, and no `tenant_id`.
- [x] T021 Add same-scope provider-connection enforcement through database constraints where practical and service validation where cross-table constraints cannot safely express the rule.
- [x] T022 Add targeted indexes only for known query paths: ownership lookup, resource latest evidence lookup, captured timestamp lookup, and payload hash lookup. Do not add broad JSONB GIN indexes unless a real query path exists.
- [x] T023 Add models `apps/platform/app/Models/TenantConfigurationResource.php` and `apps/platform/app/Models/TenantConfigurationResourceEvidence.php` with casts, relationships, guarded/fillable convention matching sibling models, and no Filament Resource.
- [x] T024 Add factories under `apps/platform/database/factories/` for new models with explicit workspace/managed-environment/provider-connection setup only.

## Phase 5: Source Contracts, Normalization, Redaction, Outcomes

**Purpose**: Implement bounded capture mechanics without provider endpoint guessing.

- [x] T025 Add `apps/platform/app/Support/TenantConfiguration/CaptureOutcome.php` or repo-equivalent bounded result type with only `captured`, `capture_blocked_missing_contract`, `capture_blocked_permission`, `capture_blocked_beta`, `capture_blocked_unsupported`, and `capture_failed`.
- [x] T026 Add `apps/platform/app/Services/TenantConfiguration/CoverageSourceContractResolver.php` to resolve capture contracts from Coverage v2 resource types and `GraphContractRegistry`/`config/graph_contracts.php`, return an explicit contract-or-block decision for each of the 8 initial Spec 414 resource types, block beta by default, block missing contracts, and expose source metadata without hardcoding endpoints.
- [x] T027 Add `apps/platform/app/Services/TenantConfiguration/GenericPayloadNormalizer.php` for deterministic generic normalization and hash input creation without semantic compare/render/restore mapping.
- [x] T028 Add redaction handling in a focused TenantConfiguration helper or reuse an existing repo sanitizer if present; cover required secret/token keys and sanitized exception context.
- [x] T029 Add `apps/platform/app/Services/TenantConfiguration/CoverageCaptureOutcomeSummarizer.php` to map outcomes to canonical OperationRun summary keys (`total`, `processed`, `succeeded`, `skipped`, `failed`, `errors_recorded`) unless a tested `OperationSummaryKeys` extension is explicitly justified.

## Phase 6: Start Service, Authorization, Queue, OperationRun

**Purpose**: Make capture observable and authorized without rendered UI.

- [x] T030 Add `tenant_configuration.capture` to `apps/platform/app/Support/OperationRunType.php` and any current repo operation catalog/config path required for operation labels/capabilities.
- [x] T031 Implement `apps/platform/app/Services/TenantConfiguration/StartTenantConfigurationCapture.php` or repo-equivalent action service that authorizes actor/scope, validates provider connection scope, creates/reuses OperationRun, dispatches the capture job, and writes safe audit metadata.
- [x] T032 Use `Capabilities::EVIDENCE_MANAGE` as the default start capability; if implementation adds a more specific capability, update `apps/platform/app/Support/Auth/Capabilities.php`, `apps/platform/app/Services/Auth/RoleCapabilityMap.php`, and related capability tests in this spec.
- [x] T033 Add `apps/platform/app/Jobs/TenantConfiguration/CaptureTenantConfigurationEvidenceJob.php` or repo-equivalent queued job that loads the OperationRun, marks it running and then terminal `completed` with the correct `OperationRunOutcome` / failure summary through `OperationRunService`, and never persists raw payloads in job-visible context.
- [x] T034 Ensure queued remote/provider work uses idempotent inputs, sanitized context, and no queued DB notification outside the central OperationRun lifecycle.
- [x] T035 Add or extend audit recording through the existing `AuditRecorder` / `AuditEventBuilder` path for capture start/completion/failure attempts, using stable action IDs `tenant_configuration.capture.started`, `tenant_configuration.capture.completed`, and `tenant_configuration.capture.failed`, with actor, workspace, managed environment, provider connection, OperationRun, resource type counts, and no raw payloads/secrets.

## Phase 7: Capture Implementation

**Purpose**: Fetch eligible payloads and write v2 evidence.

- [x] T036 Add `apps/platform/app/Services/TenantConfiguration/GenericContentEvidenceCaptureService.php` to orchestrate per-type resolution, fakeable GraphClientInterface fetch, normalization, upsert, evidence write, and outcome collection.
- [x] T037 Add `apps/platform/app/Services/TenantConfiguration/CoverageResourceUpserter.php` to upsert concrete resource rows by workspace/environment/provider/resource type/canonical key and reject display-name-only identity.
- [x] T038 Add `apps/platform/app/Services/TenantConfiguration/CoverageEvidenceWriter.php` to append evidence rows, link OperationRun, persist raw/normalized payload, hash, source metadata, redacted permission context, and coverage/evidence state.
- [x] T039 Implement source behavior for all 8 Spec 414 initial resource types only: each TCM-aligned type captured or blocked with missing-contract reason, the Graph v1 fallback type captured or blocked with contract reason, and `roleScopeTag` beta blocked by default.
- [x] T040 Ensure no old v1 gap reason (`policy_record_missing`, `foundation_not_policy_backed`, `meta_fallback`, `ambiguous_match`, `raw_gap_count`, `primary_gap_count`) appears in v2 capture outcomes.

## Phase 8: Product Surface, No-Legacy, And Report

**Purpose**: Prove the slice stayed bounded and inactive.

- [x] T041 Confirm no files under `apps/platform/app/Filament`, `apps/platform/resources/views`, route files, panel providers, navigation definitions, customer outputs, review/report/evidence pages, or restore readiness surfaces changed. If any changed, stop and amend spec/plan/tasks before continuing.
- [x] T042 Confirm any visible OperationRun completion notification or Monitoring -> Operations row uses the existing generic lifecycle path only, with no feature-local notification copy, custom run link, rendered capture control, or custom operation UI.
- [x] T043 Complete `specs/415-generic-content-backed-capture/implementation-report.md` with candidate gate, dirty state, files changed, tables/models added, source contracts used/blocked, capture eligibility matrix, OperationRun behavior, RBAC proof, redaction/log proof, no-`tenant_id`, no-legacy/no-dual-truth, tests run, browser/no-browser, deployment impact, and deferred work.
- [x] T044 Confirm no completed historical spec was rewritten or stripped of close-out/validation/task history.
- [x] T045 Confirm deployment impact: migrations yes, queue worker yes, env vars no unless discovered, scheduler no unless discovered, storage no unless discovered, assets no, `filament:assets` not required.

## Phase 9: Validation

**Purpose**: Run the narrowest proof set.

- [x] T046 Run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`.
- [x] T047 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration`.
- [x] T048 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantConfiguration`.
- [x] T049 Run `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest -c phpunit.pgsql.xml tests/Feature/TenantConfiguration` if migrations add JSONB fields, PostgreSQL checks, composite FKs, partial indexes, or same-scope provider constraints.
- [x] T050 Run `git diff --check`.
- [x] T051 Record validation results, unrelated failures if any, and final dirty state in `specs/415-generic-content-backed-capture/implementation-report.md`.

## Dependency And Ordering Notes

- T001-T007 must finish before implementation.
- T008-T018 should be written before or alongside the implementation they prove.
- T019-T024 block persistence-dependent service tests.
- T025-T029 block capture service implementation.
- T030-T035 block queue/OperationRun tests.
- T041 is a hard stop check before final validation.

## Non-Goals For Implementers

- Do not activate Coverage v2 in any customer/operator UI.
- Do not create Filament resources/pages/actions or routes.
- Do not implement compare, render, restore/apply, identity engine, full TCM catalog, legacy removal, or browser-visible proof.
- Do not read v1 snapshots as v2 evidence.
- Do not add compatibility aliases, fallback readers, dual writes, or old gap vocabulary.