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

• Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in Unit/Feature/PostgreSQL lanes; any heavy-governance or browser addition is explicit and requires spec amendment.
• Shared helpers, factories, seeds, fixtures, provider setup, workspace context, membership context, and Graph fakes stay explicit and opt-in.
• Planned validation commands cover the change without pulling in unrelated lane cost.
• Browser proof is explicitly N/A - no rendered UI surface changed.
• Human Product Sanity is N/A - no product surface changed.
• 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.

• T001 Capture branch, HEAD, git status --short, and Spec 414 dependency status in specs/415-generic-content-backed-capture/implementation-report.md.
• T002 Confirm specs/414-tcm-first-coverage-core-cutover/ is completed/validated context only and do not modify any Spec 414 artifact.
• 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.
• 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.
• 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.
• 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.
• 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.

• 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.
• 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.
• 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.
• 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.
• 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.

• 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.
• 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.
• 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.
• 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.
• 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.
• 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.

• 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.
• 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.
• T021 Add same-scope provider-connection enforcement through database constraints where practical and service validation where cross-table constraints cannot safely express the rule.
• 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.
• 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.
• 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.

• 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.
• 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.
• T027 Add apps/platform/app/Services/TenantConfiguration/GenericPayloadNormalizer.php for deterministic generic normalization and hash input creation without semantic compare/render/restore mapping.
• 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.
• 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.

• 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.
• 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.
• 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.
• 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.
• T034 Ensure queued remote/provider work uses idempotent inputs, sanitized context, and no queued DB notification outside the central OperationRun lifecycle.
• 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.

• T036 Add apps/platform/app/Services/TenantConfiguration/GenericContentEvidenceCaptureService.php to orchestrate per-type resolution, fakeable GraphClientInterface fetch, normalization, upsert, evidence write, and outcome collection.
• 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.
• 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.
• 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.
• 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.

• 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.
• 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.
• 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.
• T044 Confirm no completed historical spec was rewritten or stripped of close-out/validation/task history.
• 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.

• T046 Run cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent.
• T047 Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration.
• T048 Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantConfiguration.
• 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.
• T050 Run git diff --check.
• 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.