TenantAtlas/specs/393-evidence-anchor-reconciliation-v1/tasks.md

Tasks: Spec 393 - Evidence Anchor Reconciliation v1

Input: specs/393-evidence-anchor-reconciliation-v1/spec.md and plan.md Prerequisites: Spec artifacts prepared; implementation must start from repo-truth verification and must not modify completed context specs. Tests: Required. This is an evidence trust-boundary change with Unit, Feature/HTTP, Filament/Livewire, and bounded Browser proof.

Test Governance Checklist

• Lane assignment is named and narrow: Unit for resolver decisions, Feature/HTTP for route/scope/provenance, Filament/Livewire for action labels/state, Browser for final customer/dashboard trust-path proof.
• New or changed tests stay in focused families; Browser coverage is one explicit Spec 393 smoke unless existing focused browser tests are intentionally reused and named.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
• Planned validation commands cover the change without pulling unrelated heavy-governance cost.
• N+1/eager-loading risk is covered by an explicit resolver/query-shape task for affected list/detail surfaces.
• The declared surface profile is customer-safe strategic review surface + evidence/artifact detail + dashboard signal.
• Any unreachable or not-applicable surface is documented in the implementation report instead of faked.

Phase 1: Repo Truth And Evidence Anchor Inventory

Purpose: Map all current local evidence selectors before changing behavior.

• T001 Re-read specs/393-evidence-anchor-reconciliation-v1/spec.md, plan.md, tasks.md, and checklists/requirements.md.
• T002 Re-read completed context specs as read-only inputs only: specs/361-report-evidence-reconciliation, specs/372-customer-auditor-surface-safety-pass, specs/385-evidence-review-readiness, specs/386-review-publication-resolution-workflow-v1, specs/387-review-publication-resolution-decision-ux-v1, specs/388-resolution-proof-currentness-contract-v1, and specs/392-customer-output-gating-review-pack-navigation.
• T003 Confirm current branch and dirty state with git status --short --branch and git log -1 --oneline.
• T004 Inventory every evidence selector/link/action/output in apps/platform/app, apps/platform/resources, apps/platform/routes, apps/platform/tests, and localization files using the spec search terms, including shared builders/presenters ArtifactTruthPresenter, OperationRunLinks, RelatedNavigationResolver, and GovernanceDecisionRegisterBuilder.
• T005 Record the inventory in the implementation report: file, current selection logic, target route, visible label, product context, customer/internal/technical classification, and stale/partial/superseded/wrong-scope risk.
• T006 Inspect exact current behavior in apps/platform/app/Services/Evidence/EvidenceSnapshotResolver.php, apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewService.php, and apps/platform/app/Models/EvidenceSnapshot.php.
• T007 Inspect current product surfaces in apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php, apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php, apps/platform/app/Filament/Resources/EnvironmentReviewResource.php, apps/platform/app/Filament/Resources/ReviewPackResource.php, apps/platform/app/Filament/Resources/StoredReportResource.php, and apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php.
• T008 Inspect current report/review provenance in apps/platform/app/Support/ReviewPacks/ManagementReportPdfPayloadBuilder.php, rendered-report controllers/views, and apps/platform/app/Support/ReviewPublicationResolution/ReviewPublicationProofResolver.php.
• T009 Confirm no migration, package, env var, queue, scheduler, storage topology, Graph scope, panel-provider, route family, report renderer, customer portal, or broad technical annex change is required; stop and update spec/plan if false.
• T010 Confirm Filament v5 / Livewire v4.0+ compliance and no Filament v3/v4 or Livewire v3 APIs.
• T011 Confirm panel provider registration remains apps/platform/bootstrap/providers.php.
• T012 Confirm no global-search participation is added or changed.

Phase 2: Resolver Contract And Unit Tests

Purpose: Prove evidence anchor behavior before replacing product surfaces.

• T013 Add focused Unit tests for the canonical Evidence Anchor Resolver under apps/platform/tests/Unit/Services/Evidence/Spec393EvidenceAnchorResolverTest.php or the nearest existing evidence test family.
• T014 [P] Test newest valid current evidence is selected for a workspace/environment.
• T015 [P] Test superseded evidence is not selected as current.
• T016 [P] Test partial evidence is not selected as current.
• T017 [P] Test expired evidence is not selected as current.
• T018 [P] Test queued, generating, failed, missing, and stale evidence are not selected as current proof.
• T019 [P] Test wrong-workspace evidence and unauthorized workspace-wide evidence are never selected.
• T020 [P] Test wrong-environment evidence is never selected, including when no explicit environment is provided and the actor lacks entitlement.
• T021 Test no valid evidence is returned when only partial/superseded/expired evidence exists.
• T022 Test released review evidence resolves from the review/review-pack binding independently from current evidence.
• T023 Test released review evidence remains stable after newer current evidence is created.
• T024 Test draft review evidence is internal/draft and not customer-safe.
• T025 Test customer workspace resolution returns customer-safe summary without raw technical route by default.
• T026 Test actor without permission receives no technical evidence link.
• T027 Test internal/operator actor may receive technical detail link where appropriate.
• T028 Test deterministic tie-breaker when multiple valid snapshots share generated_at in a workspace-wide authorized selection set or another repo-possible multi-record set.
• T029 Implement or consolidate EvidenceAnchorResolver and result value object/array in apps/platform/app/Services/Evidence/ or the narrowest repo-consistent namespace, using derived non-persisted anchor type/state vocabulary only.
• T030 Ensure resolver result exposes the spec-required fields and maps internal states to allowed UI vocabulary without adding a persisted enum/status family.
• T031 Ensure resolver performs DB-only scoped queries, no Graph/provider calls, and explicit eager-loading or bounded query shape for relationships needed by affected UI paths.

Phase 3: Current Evidence Product Surfaces

Purpose: Make dashboard/workspace/environment/evidence-overview surfaces use CURRENT_SCOPE_EVIDENCE.

• T032 Add Feature/Filament tests proving dashboard/workspace/environment current evidence link targets the valid current evidence, not older partial/superseded evidence.
• T033 Add Feature/Filament tests proving no current-evidence link appears when only partial/superseded/expired evidence exists.
• T034 Update dashboard/workspace/environment summary builders that produce evidence CTAs to use the resolver.
• T035 Update apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php to use the resolver for product-facing current evidence row/action targets.
• T036 Remove local fallback queries from affected current-state surfaces that choose arbitrary latest evidence.
• T037 Ensure non-link states use concise copy: Evidence not ready, Evidence unavailable, Evidence needs attention, or Evidence expired.
• T038 Ensure current evidence selection order is explicit and deterministic in code and tests.

Phase 4: Released Review, Review Pack, And Report Provenance

Purpose: Keep released output bound to released evidence instead of current evidence.

• T039 Add Feature tests proving released review output references evidence snapshot A after newer current evidence B is created.
• T040 Add Feature/Filament tests proving ReviewPackResource evidence labels use release-bound/review-pack evidence and do not query arbitrary current evidence.
• T041 Add Feature/Filament tests proving EnvironmentReviewResource evidence basis uses the review-bound evidence.
• T042 Add Feature tests proving rendered report, stored report, and management-report provenance use released review/review-pack evidence where in scope.
• T043 Update apps/platform/app/Filament/Resources/ReviewPackResource.php to consume released-review/review-pack anchor results for evidence basis links/labels.
• T044 Update apps/platform/app/Filament/Resources/EnvironmentReviewResource.php to consume released-review anchor results for evidence basis links/labels.
• T045 Update report provenance builders/controllers/views only where they currently infer evidence from latest/current state.
• T046 Ensure missing released evidence produces Evidence not configured, Evidence unavailable, or Review evidence needs attention instead of borrowing current evidence.

Phase 5: Customer Review Workspace Customer-Safe Evidence

Purpose: Remove raw evidence links from default customer-safe review consumption.

• T047 Add Feature/Filament tests proving Customer Review Workspace default view does not render raw EvidenceSnapshot routes, evidence IDs, source keys, detector output, OperationRun proof, fingerprints, or technical dimensions.
• T048 Add tests proving Customer Review Workspace may show customer-safe summary text such as Evidence captured for this review or Evidence current at publication.
• T049 Add tests proving authorized internal users get only a secondary/internal technical action when allowed.
• T050 Update apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php to consume CUSTOMER_SAFE_EVIDENCE_SUMMARY for default evidence state.
• T051 Update apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php to remove or demote raw evidence links by default.
• T052 Ensure any internal action uses labels such as View audit trail or View internal evidence details.
• T053 Ensure customer/read-only mode receives no raw evidence target route.

Phase 6: Technical Evidence Detail Boundary

Purpose: Preserve technical evidence access without making it product proof.

• T054 Add Feature/HTTP tests proving direct wrong-scope EvidenceSnapshot route remains deny-as-not-found.
• T055 Add tests proving technical detail requires internal/operator permission where the product surface offers a technical link.
• T056 Update apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php only where labels/context need to clarify technical/audit purpose.
• T057 Ensure product surfaces use secondary/internal labels for technical evidence detail and do not expose raw technical labels in customer-safe defaults.
• T058 Preserve existing EvidenceSnapshot technical page depth and existing destructive/high-impact action confirmation/authorization/audit behavior.

Phase 7: Deprecated Selector And Fixture Cleanup

Purpose: Remove wrong-anchor assumptions rather than compatibility-shimming them.

• T059 Search for remaining product-facing latest('generated_at'), latest('created_at'), orderByRaw('COALESCE(generated_at, created_at) DESC'), EvidenceSnapshotResource::getUrl, direct evidence_snapshot_id link composition, and shared link-builder emissions in ArtifactTruthPresenter, OperationRunLinks, RelatedNavigationResolver, and GovernanceDecisionRegisterBuilder.
• T060 Replace or remove product-facing local fallback selectors found by T059, or explicitly classify retained shared-builder links as technical/internal-only.
• T061 Update tests/fixtures that expected partial, superseded, stale, or arbitrary latest evidence to appear as current proof.
• T062 Do not add legacy aliases, compatibility redirects, fallback readers, old translation keys, or tests preserving wrong-anchor behavior.
• T063 Update localization keys only where visible labels change; remove stale keys if they preserve forbidden labels.

Phase 8: Browser Smoke

Purpose: Prove visible trust boundaries and absence of internal evidence leakage.

• T064 Add or update apps/platform/tests/Browser/Spec393EvidenceAnchorReconciliationSmokeTest.php using existing review-output/evidence fixture helpers where practical.
• T065 Browser state: current dashboard/evidence overview link opens current valid evidence, not stale/superseded evidence.
• T066 Browser state: Customer Review Workspace has no raw evidence snapshot link by default.
• T067 Browser state: Review Pack evidence label is truthful and release-bound.
• T068 Browser state: technical evidence link, if present, is secondary/internal.
• T069 Browser state: no visible Evidence #<id> style product link appears on customer-safe surfaces.
• T070 Browser state: no 500/Livewire/Filament/console errors in affected flows.
• T071 Direct URL proof: wrong/old evidence URL does not become a customer-facing proof path.

Phase 9: Validation And Close-Out

Purpose: Prove the implementation and record deployment impact clearly.

• T072 Run cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec393.
• T073 Run targeted existing regressions for Customer Review Workspace, Review Pack, Environment Review, Evidence Overview, Stored Report, and management-report provenance if those surfaces changed.
• T074 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec393EvidenceAnchorReconciliationSmokeTest.php.
• T075 Run additional affected existing browser tests named in the spec if they still exist and cover changed flows.
• T076 Update affected docs/ui-ux-enterprise-audit/page-reports/... artifacts when visible page behavior materially changed, or document explicit no-route/no-archetype/no-count-impact decisions for each touched surface in the implementation report.
• T077 Run cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent.
• T078 Run git diff --check.
• T079 Confirm no migrations, seeders, packages, env vars, queues, scheduler, storage topology, Graph contracts/calls, panel providers, new route family, customer portal, technical annex, or legacy compatibility path were added unless spec/plan were updated first.
• T080 Confirm final Livewire v4 compliance, provider registration location, global-search posture, destructive/high-impact action status, asset strategy, tests, deployment impact, UI coverage artifact/no-impact decision, current-vs-released evidence separation, Customer Review Workspace no-raw-link behavior, no UI expansion, and no legacy shim in the implementation close-out response.
• T081 Complete human product sanity check before marking Spec 393 done.

Dependencies

• Phase 1 must complete before runtime implementation.
• Phase 2 resolver tests should land before or alongside resolver implementation.
• Phase 3 current-surface replacements depend on the resolver contract.
• Phase 4 released-provenance replacements depend on release-bound resolver methods.
• Phase 5 customer workspace changes depend on customer-safe resolver summary behavior.
• Phase 8 runs after targeted tests and UI/route changes.
• Phase 9 closes the feature.

Parallel Execution Examples

• T006, T007, and T008 can be split by repo surface during inspection.
• T014-T020 can be implemented in parallel as independent resolver test cases.
• T039-T042 can be split by review/report artifact surface after the resolver API is stable.
• T047-T049 can run in parallel with T054-T055 after the result shape is stable.

Non-Goals / Stop Conditions

• Stop if implementation requires a new persisted evidence-anchor table, review release table, or broad technical annex; update spec/plan first.
• Stop if a page-local selector appears necessary for a product-facing surface; fold it into the resolver instead.
• Stop if the only way to keep an old test green is to preserve partial/superseded/latest fallback behavior.
• Stop if management-report runtime enablement or PDF renderer validation becomes necessary; that belongs to Spec 379 follow-through.
• Do not rewrite, normalize, uncheck, or remove implementation history from completed Specs 361, 372, 385, 386, 387, 388, or 392.

Required Final Report Content For Later Implementation

When implementation later completes, report:

• Files changed.
• Resolver/API created or consolidated.
• Old local evidence-selection paths removed or replaced.
• Tests added/updated.
• Browser flows run.
• Evidence that current evidence and released review evidence are separated.
• Evidence that Customer Review Workspace no longer exposes raw evidence by default.
• UI coverage artifact update or explicit no-route/no-archetype/no-count-impact decision.
• Confirmation that no legacy fallback/compatibility shim was added.
• Confirmation that visible UI complexity did not increase.
• Remaining known unrelated failures, if any.