TenantAtlas/specs/388-resolution-proof-currentness-contract-v1/tasks.md

Tasks: Spec 388 - Resolution Proof & Currentness Contract v1

Input: Design documents from /specs/388-resolution-proof-currentness-contract-v1/ Prerequisites: spec.md, plan.md, checklists/requirements.md Tests: Required. This feature changes runtime proof classification, step completion behavior, RBAC-sensitive proof visibility, and existing Filament proof-state display.

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for proof-currentness behavior.
• New or changed tests stay in focused Unit, Feature, Filament/Livewire, and optional Browser families.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
• Planned validation commands cover the change without pulling unrelated lane cost.
• The workflow-detail surface test profile and optional browser smoke need are explicit.
• Any browser fixture gap is documented in the active spec artifacts instead of widened through product-only setup code.

Phase 1: Preparation and Repo Truth

Purpose: Confirm Spec 388 starts from current Spec 386/387 runtime truth and avoids duplicate or generic framework work.

• T001 Confirm current branch/status and re-read specs/388-resolution-proof-currentness-contract-v1/spec.md, plan.md, and tasks.md.
• T002 Re-read specs/386-review-publication-resolution-workflow-v1/ and specs/387-review-publication-resolution-decision-ux-v1/ as completed implementation context only; do not rewrite those packages.
• T003 Inspect existing proof resolver behavior in apps/platform/app/Support/ReviewPublicationResolution/ReviewPublicationProofResolver.php.
• T004 Inspect current readiness fingerprint inputs in apps/platform/app/Support/ReviewPublicationResolution/ReviewPublicationReadinessEvaluator.php.
• T005 Inspect step completion/current-step behavior in apps/platform/app/Support/ReviewPublicationResolution/ReviewPublicationStepPlanner.php.
• T006 Inspect case sync/audit behavior in apps/platform/app/Support/ReviewPublicationResolution/ReviewPublicationResolutionService.php.
• T007 Inspect current proof fields/casts in apps/platform/app/Models/ReviewPublicationResolutionStep.php.
• T008 Inspect current UI proof disclosure in apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ResolveReviewPublication.php and apps/platform/resources/views/filament/resources/environment-review-resource/pages/resolve-review-publication.blade.php.
• T009 Confirm no migration, new proof table, generic registry, new route, navigation, global-search Resource, panel provider, provider call, or OperationRun lifecycle change is required; update spec/plan before implementation if this is false.
• T010 Confirm Filament v5 / Livewire v4.0+ compliance and panel provider registration remains apps/platform/bootstrap/providers.php.

Phase 2: Tests First - Proof Evaluation Contract

Purpose: Prove normalized proof behavior before changing resolver implementation.

• T011 [P] Add unit tests under apps/platform/tests/Unit/Support/ReviewPublicationResolution/ for missing proof returning missing/currentness unknown or not applicable, not usable, and safe summary only.
• T012 [P] Add unit tests proving running OperationRun proof is current only for matching workspace, managed environment, subject, action, and fingerprint, and remains inspection-only.
• T013 [P] Add unit tests proving failed current OperationRun proof is not usable or inspection-only.
• T014 [P] Add unit tests proving failed OperationRun proof becomes superseded/inspection-only when a newer current artifact exists.
• T015 [P] Add unit tests proving successful OperationRun without expected artifact proof cannot complete artifact-backed steps.
• T016 [P] Add unit tests proving unknown currentness fails closed as not usable.
• T017 [P] Add unit tests proving safe summaries exclude raw provider payloads, raw Graph responses, secrets/tokens, full report/evidence content, and raw exception messages.

Phase 3: Tests First - Artifact Currentness

Purpose: Prove artifact-backed proof rules for current review publication steps.

• T018 [P] Add feature/unit coverage proving current StoredReport proof matches required report key/dimension, workspace, managed environment, successful/evaluated state, and current readiness inputs.
• T019 [P] Add coverage proving zero-result evaluated StoredReport is usable proof.
• T020 [P] Add coverage proving stale StoredReport or changed required report input does not complete complete_required_reports.
• T021 [P] Add coverage proving EvidenceSnapshot becomes stale when required reports changed after collection.
• T022 [P] Add coverage proving EnvironmentReview/review-output proof is not usable when review composition is older than evidence/report inputs or readiness blockers remain.
• T023 [P] Add coverage proving ReviewPack proof becomes stale when EnvironmentReview output changes after pack generation.
• T024 [P] Add coverage proving ReviewPack proof is usable only when ready/current and matches current output/export profile.

Phase 4: Tests First - Planner, RBAC, and Customer Boundary

Purpose: Prove proof currentness affects workflow behavior and disclosure safely.

• T025 Add apps/platform/tests/Feature/EnvironmentReview/Spec388ReviewPublicationProofCurrentnessTest.php covering newer StoredReport superseding old failed report run.
• T026 Add feature coverage proving stale EvidenceSnapshot keeps collect-evidence step actionable.
• T027 Add feature coverage proving stale ReviewPack keeps prepare-export step actionable.
• T028 Add feature coverage proving successful OperationRun alone does not complete artifact-backed steps.
• T029 Add feature coverage proving cross-workspace proof is not usable/visible and follows deny-as-not-found where existing policies require it.
• T030 Add feature coverage proving cross-environment proof is not usable for environment-scoped resolution actions.
• T031 Add readonly actor coverage proving limited proof display and no executable step action.
• T032 Add customer-facing regression coverage proving no OperationRun ID/link, proof fingerprint, resolution case/step key, raw reason code, or internal proof state leaks.

Phase 5: Implementation - Bounded Proof Contract

Purpose: Introduce the narrow derived proof contract under existing review-publication ownership.

• T033 Create bounded proof evaluation value objects/enums under apps/platform/app/Support/ReviewPublicationResolution/ or a review-publication-owned child namespace only.
• T034 Implement proof status values exactly for missing, available, running, succeeded, failed, cancelled, unavailable, not accessible, and unknown; update spec/plan/tasks before implementation if any value is renamed, narrowed, or merged.
• T035 Implement proof currentness values for current, stale, superseded, not applicable, and unknown.
• T036 Implement proof usability values for usable, usable with warning, not usable, and inspection only.
• T037 Implement proof visibility values for operator visible, operator limited, customer safe summary only, and hidden.
• T038 Implement safe summary sanitization helpers that reject raw payloads, raw exceptions, full report/evidence content, tokens, and secrets.
• T039 Ensure new classes are derived helpers only and do not create a new persisted proof source of truth.

Phase 6: Implementation - Resolver and Fingerprint Behavior

Purpose: Replace shallow proof references with currentness-aware evaluations.

• T040 Update ReviewPublicationProofResolver to return normalized proof evaluations for each ReviewPublicationResolutionStepKey.
• T041 Update required report proof evaluation to resolve current StoredReport-backed evidence dimensions without treating missing/stale reports as completed proof.
• T042 Update EvidenceSnapshot proof evaluation to compare snapshot state against current required report/evidence inputs.
• T043 Update EnvironmentReview/review-output proof evaluation to require current composition and resolved publication blockers.
• T044 Update ReviewPack proof evaluation to require current review output and ready/exportable pack state.
• T045 Update OperationRun proof classification so running/failed/succeeded/cancelled runs are never treated as artifact proof unless the operation type itself is the required proof.
• T046 Update fingerprint comparison helpers to use safe components only: workspace, managed environment, subject, action, blocker keys, artifact ids/timestamps, and relevant statuses.
• T047 Ensure no provider/Graph calls occur during proof evaluation or UI render.
• T048 Add or update bounded-query coverage/review for relationship-backed proof resolution so refreshing a resolution case uses explicit queries or eager-loaded relationships and does not introduce per-step unbounded query behavior.

Phase 7: Implementation - Step Planning, Audit, and UI Disclosure

Purpose: Make workflow behavior consume proof evaluation without broad UI rewrites.

• T049 Update ReviewPublicationStepPlanner so stale, superseded, inaccessible, unknown, not usable, or inspection-only proof cannot complete a step.
• T050 Update planner/service behavior so newer current artifact proof supersedes older failed/running runs for the same step requirement.
• T051 Update ReviewPublicationResolutionService audit metadata on proof-driven step transitions to include safe proof fields where existing audit patterns support it.
• T052 Add or update audit assertions proving proof-driven transition metadata includes only safe proof fields and excludes raw provider payloads, Graph responses, full report/evidence content, raw exception messages, tokens, and secrets.
• T053 Update ResolveReviewPublication and its Blade view only as needed to show proof labels such as current proof, operation running, action failed, outdated proof, superseded by newer result, proof missing, not available with your permissions, and proof cannot be verified.
• T054 Keep technical proof collapsed/secondary by default and ensure no proof state creates an extra competing primary action.
• T055 Keep customer-facing surfaces free of internal proof detail; update only negative leakage tests unless existing copy overclaims.
• T056 Update UI-101 page report only if rendered structure/copy materially changes; otherwise record no-new-route/no-new-archetype rationale in implementation close-out.

Phase 8: Browser / Screenshot Evidence

Purpose: Capture representative proof-state rendering if UI changes are visible.

• T057 Decide whether changed proof states require a new apps/platform/tests/Browser/Spec388ReviewPublicationProofCurrentnessSmokeTest.php or can be covered by existing Spec 387 browser smoke plus Feature/Livewire proof.
• T058 Capture or document current proof completed state under specs/388-resolution-proof-currentness-contract-v1/artifacts/screenshots/.
• T059 Capture or document running operation proof state.
• T060 Capture or document failed operation proof state.
• T061 Capture or document superseded failed proof state.
• T062 Capture or document stale/outdated proof disclosure.
• T063 Capture or document readonly limited proof state.
• T064 Capture or document customer workspace no-proof-leakage state.

Phase 9: Validation

Purpose: Prove bounded trust hardening and no scope expansion.

• T065 Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/ReviewPublicationResolution tests/Feature/EnvironmentReview/Spec388ReviewPublicationProofCurrentnessTest.php.
• T066 Run cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EnvironmentReview/Spec386ReviewPublicationResolutionWorkflowTest.php tests/Feature/EnvironmentReview/Spec387ReviewPublicationResolutionDecisionUxTest.php.
• T067 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec388ReviewPublicationProofCurrentnessSmokeTest.php if a browser file is added.
• T068 Run cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent.
• T069 Run git diff --check.
• T070 Record implementation close-out with Livewire v4 compliance, provider registration location, global search status, destructive/high-impact action handling, asset strategy, tests run, browser smoke result or documented substitution, deployment impact, and explicit no-generic-registry confirmation.

Explicit Non-Goals

• NT001 Do not modify completed Specs 385, 386, or 387 except as read-only context.
• NT002 Do not create a global proof adapter registry, workflow engine, broad Support/ResolutionProof package, or generic process manager.
• NT003 Do not add migrations, new persisted proof fields, or new proof tables unless spec/plan/tasks are updated first.
• NT004 Do not add Restore, Provider Onboarding, Governance Inbox, Report Delivery, Cross-Tenant Promotion, or AI proof adapters.
• NT005 Do not add top-level navigation, a Resource, collection route, or global search for proof evaluations.
• NT006 Do not auto-publish reviews or move Publish onto the resolution page.
• NT007 Do not expose raw provider payloads, Graph responses, tokens, secrets, full report/evidence content, raw exception messages, proof fingerprints, or internal reason codes to customer-facing surfaces.
• NT008 Do not register new Filament assets unless spec/plan are updated first.

Dependencies

• Phase 1 must complete before implementation.
• Phases 2-4 should be written before Phases 5-7 implementation.
• Phase 5 proof values are a prerequisite for resolver/planner work.
• Phase 6 resolver behavior, including bounded-query proof evaluation, is a prerequisite for Phase 7 planner/UI behavior.
• Phase 8 browser evidence depends on visible UI changes from Phase 7.
• Phase 9 runs after all implementation and artifact notes are complete.

Parallel Execution Notes

• T011-T017 can run in parallel with T018-T024 if test fixtures do not overlap.
• T029-T032 can run in parallel with artifact currentness tests once helper fixtures exist.
• T034-T038 can run in parallel after T033 creates the owning namespace/files.
• T058-T064 can be captured/documented in parallel after browser fixture decision T057.