TenantAtlas/specs/403-evidence-anchor-currentness-runtime-closure/plan.md

# Implementation Plan: Spec 403 - Evidence Anchor & Currentness Runtime Closure

**Branch**: `403-evidence-anchor-currentness-runtime-closure` | **Date**: 2026-06-23 | **Spec**: `specs/403-evidence-anchor-currentness-runtime-closure/spec.md`
**Input**: Feature specification from `specs/403-evidence-anchor-currentness-runtime-closure/spec.md`

## Summary

Spec 403 closes the remaining evidence-anchor and currentness product-contract gap before TenantPilot expands management-report or customer-output claims. The implementation must inventory existing evidence/currentness claims, build an Evidence/Currentness Coverage Matrix, add focused tests and browser proof, and apply only minimal runtime fixes where a claim is false, unsafe, unscoped, or unproven.

Do not start by creating a new proof framework. Use the matrix to decide whether existing `EvidenceAnchorResolver`, `EvidenceAnchorResult`, Spec 388 proof-currentness support, policies, and shared presenters already express the required truth. Extend existing paths only when the matrix proves a concrete gap.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52.0
**Primary Dependencies**: Filament 5.2.1, Livewire 4.1.4, Laravel Sail, Pest 4.3.1, PHPUnit 12.5.4
**Storage**: PostgreSQL; no schema changes allowed by default
**Testing**: Pest Unit/Feature/Filament/Browser tests
**Validation Lanes**: confidence for Feature/Filament proof; browser for representative rendered evidence/currentness proof; optional heavy-governance only if a matrix guard is implemented
**Target Platform**: TenantPilot Laravel monolith under `apps/platform`
**Project Type**: Laravel + Filament application
**Performance Goals**: No Graph/provider calls during render; no broad full-suite/browser expansion; no material test-runtime cost without report note
**Constraints**: No new product surfaces, routes, navigation, persisted truth, new status vocabulary, report runtime, provider integration, migration, asset registration, or broad runtime audit
**Scale/Scope**: Existing evidence/currentness surfaces in admin/customer/review/report/restore/baseline/finding/operation flows

## Preparation Context

- Dirty state before preparation: clean on `platform-dev` at `c5db3ea4 feat: add resource policy authorization proof matrix (#473)`.
- Spec Kit script used: `.specify/scripts/bash/create-new-feature.sh --json --number 403 --short-name evidence-anchor-currentness-runtime-closure "..."`
- Generated branch/path: `403-evidence-anchor-currentness-runtime-closure`, `specs/403-evidence-anchor-currentness-runtime-closure/`.
- Candidate source: direct user-provided Spec 403 draft, promoted after Spec 402's `PASS` close-out and recommendation.
- Active auto-prep queue: `docs/product/spec-candidates.md` reports no safe automatic next-best-prep target, so this is a manual operator-promoted candidate.
- Completed-spec guardrail: Specs 388, 393, 400, 401, and 402 are read-only context. Do not rewrite their close-out, validation, completed tasks, implementation reports, or browser evidence.

## Existing Repository Surfaces

### Evidence and currentness foundations

- `apps/platform/app/Services/Evidence/EvidenceAnchorResolver.php`
- `apps/platform/app/Services/Evidence/EvidenceAnchorResult.php`
- `apps/platform/app/Services/Evidence/EvidenceSnapshotResolver.php`
- `apps/platform/app/Services/Evidence/EvidenceSnapshotService.php`
- `apps/platform/app/Support/Evidence/EvidenceSnapshotStatus.php`
- `apps/platform/app/Support/Evidence/EvidenceCompletenessState.php`
- `apps/platform/app/Models/EvidenceSnapshot.php`
- `apps/platform/app/Models/EvidenceSnapshotItem.php`

### Existing rendered/admin/customer surfaces to inventory

- `apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php`
- `apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php`
- `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`
- `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php`
- `apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ResolveReviewPublication.php`
- `apps/platform/resources/views/filament/resources/environment-review-resource/pages/resolve-review-publication.blade.php`
- `apps/platform/app/Filament/Resources/ReviewPackResource.php`
- `apps/platform/app/Filament/Resources/StoredReportResource.php`
- `apps/platform/app/Filament/Resources/RestoreRunResource.php` and restore presenter/proof Blade views
- `apps/platform/app/Filament/Pages/BaselineCompareMatrix.php`
- `apps/platform/app/Filament/Resources/BaselineSnapshotResource.php`
- `apps/platform/app/Filament/Resources/BaselineProfileResource.php`
- `apps/platform/app/Filament/Resources/FindingResource.php`
- `apps/platform/app/Filament/Resources/FindingExceptionResource.php`
- Monitoring/Operations and OperationRun detail/link helpers where proof links are emitted

### Existing proof and output semantics

- Spec 388 proof-currentness classes under `apps/platform/app/Support/ReviewPublicationResolution/`.
- Spec 393 evidence anchor resolver/result behavior.
- Review/report output builders and services discovered by implementation, including management-report payload builders where they are already repo-real.
- Restore readiness/safety support and baseline evidence providers.
- Existing policies for evidence, reviews, review packs, OperationRuns, findings, and restore/baseline resources.

## UI / Surface Guardrail Plan

- **Guardrail scope**: existing rendered evidence/currentness/status/proof presentation may be corrected; no new surfaces.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: exact touched surfaces named in implementation report after matrix inventory.
- **No-impact class, if applicable**: N/A because rendered evidence/status presentation may change.
- **Native vs custom classification summary**: native Filament resources/pages plus existing Blade views and shared helpers.
- **Shared-family relevance**: evidence/report viewers, status messaging, action links, OperationRun proof links, customer-safe output, readiness/proof labels.
- **State layers in scope**: page, detail, table row, report output, proof link, wizard/detail proof section, route/query context.
- **Audience modes in scope**: customer/read-only, operator-MSP, support-platform where existing surfaces permit support/raw evidence.
- **Decision/diagnostic/raw hierarchy plan**: default product surfaces show product proof state; technical proof remains secondary/internal; support/raw remains capability-gated.
- **Raw/support gating plan**: preserve or tighten existing authorization. No raw evidence links in customer-safe default views.
- **One-primary-action / duplicate-truth control**: no new primary actions; technical links remain secondary.
- **Handling modes by drift class or surface**: hard-stop for P0 false/leaking claims; review-mandatory for P1 missing proof; document-in-feature for bounded implementation choices; follow-up-spec for structural product decisions.
- **Repository-signal treatment**: review-mandatory for arbitrary latest evidence selectors, direct evidence routes in customer-safe output, OperationRun link leakage, current/released copy conflicts, stale/failed/partial proof overclaims, and cross-scope links.
- **Special surface test profiles**: shared-detail-family, monitoring-state-page, customer-safe report surface, restore wizard/detail, baseline decision surface.
- **Required tests or manual smoke**: Unit/Feature/Filament tests plus focused browser smoke.
- **Exception path and spread control**: any Product Surface exception must be in the implementation report with page, violated rule/budget, reason, and follow-up.
- **Active feature PR close-out entry**: `Guardrail / Exception / Smoke Coverage`.
- **UI/Productization coverage decision**: existing-surface evidence/currentness hardening only; route-inventory/design-matrix review or update is required if runtime UI files or reachable evidence/status semantics change.
- **Coverage artifacts to update**: review/update `docs/ui-ux-enterprise-audit/route-inventory.md` and `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` for touched existing surfaces if runtime UI files or reachable evidence/status semantics change. If existing entries already cover the final archetype/depth/safety state, record that review result in the implementation report.
- **Navigation / Filament provider-panel handling**: no panel provider or navigation change. Providers remain in `apps/platform/bootstrap/providers.php`.
- **Screenshot or page-report need**: no page-report set; focused browser proof is sufficient.

## Product Surface Contract Plan

- **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md`
- **No-legacy posture**: canonical current evidence/currentness behavior, no compatibility exception.
- **Page archetype and surface budget plan**: existing archetypes only; no added default OperationRun/raw evidence/source-key links.
- **Technical Annex and deep-link demotion plan**: OperationRun, evidence IDs, source keys, detectors, fingerprints, raw payloads, and technical logs remain secondary/internal.
- **Canonical status vocabulary plan**: map internal evidence states to existing canonical product states; do not introduce new top-level product states.
- **Product Surface exceptions**: none planned.
- **UI coverage registry plan**: runtime UI changes require route-inventory/design-coverage-matrix review or update for touched existing surfaces before close-out.
- **Browser verification plan**: focused paths for admin evidence, customer-safe output, released evidence, stale/missing/failed state, unauthorized/cross-scope denial, and OperationRun proof link visibility/blocking.
- **Human Product Sanity plan**: 5-15 minute review of touched customer-safe/readiness/evidence surfaces after implementation.
- **Visible complexity outcome target**: neutral or decreased.
- **Implementation report target**: `specs/403-evidence-anchor-currentness-runtime-closure/implementation-report.md`.

## Filament / Livewire / Deployment Posture

- **Livewire v4 compliance**: Livewire 4.1.4 confirmed by Laravel Boost; no Livewire v3 APIs allowed.
- **Panel provider registration location**: unchanged; Laravel 12 panel providers are registered in `apps/platform/bootstrap/providers.php`.
- **Global search posture**: no resource global-search participation is added or changed by default. If evidence/report resources are touched, confirm View/Edit pages and `$recordTitleAttribute` or global-search disabled posture.
- **Destructive/high-impact action posture**: no new destructive/high-impact action is planned. Existing restore/report/review actions keep `->action(...)`, confirmation, authorization, audit, and tests where already required.
- **Asset strategy**: no new assets. `filament:assets` is not newly required unless implementation unexpectedly registers assets, which is out of scope by default.
- **Testing plan**: focused Unit/Feature/Filament tests for evidence/currentness truth, RBAC/scope, customer-safe boundary, OperationRun proof links, current/released semantics, plus focused browser smoke.
- **Deployment impact**: no env vars, migrations, queues, scheduler, storage, assets, routes, panels, or navigation changes expected. Deployment notes should record no infrastructure impact unless implementation discovers otherwise and spec/plan are updated first.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched**: evidence anchor resolution, review/report output, OperationRun proof links, baseline/restore proof surfaces, customer-safe views, existing badges/presenters.
- **Shared abstractions reused**: `EvidenceAnchorResolver`, `EvidenceAnchorResult`, `EvidenceSnapshotStatus`, `EvidenceCompletenessState`, Spec 388 proof-currentness support, `OperationRunLinks`, policies, and existing ArtifactTruth/Badge paths.
- **New abstraction introduced? why?**: none planned.
- **Why the existing abstraction was sufficient or insufficient**: existing paths are the correct current repo truth; this spec tests and corrects usage. If insufficient, update spec/plan before adding structure.
- **Bounded deviation / spread control**: local label/link corrections are allowed for confirmed false claims; recurring semantics become follow-up spec rather than new framework inside Spec 403.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: proof/link visibility only; no new start/completion behavior.
- **Central contract reused**: existing OperationRun UX/link/policy helpers.
- **Delegated UX behaviors**: unchanged.
- **Surface-owned behavior kept local**: existing proof display only.
- **Queued DB-notification policy**: unchanged.
- **Terminal notification path**: unchanged.
- **Exception path**: none planned.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: possibly where provider freshness/permissions affect evidence claims.
- **Provider-owned seams**: provider connection/readiness/permission diagnostic detail.
- **Platform-core seams**: evidence proof, current/released status, customer-safe output, OperationRun proof, workspace/environment scope.
- **Neutral platform terms / contracts preserved**: workspace, managed environment, provider, evidence, proof, review, report, operation, current, released, historical, customer-safe.
- **Retained provider-specific semantics and why**: Microsoft/Graph/Entra terms remain in existing provider-owned diagnostics only.
- **Bounded extraction or follow-up path**: provider productization remains separate if needed.

## Constitution Check

- Inventory-first: PASS planned. The matrix starts from observed repo/runtime evidence, not speculative product concepts.
- Read/write separation: PASS planned. No new write flow; existing restore/report/review actions retain safety gates.
- Graph contract path: PASS planned. No new Graph calls; UI render remains DB-only.
- Deterministic capabilities: PASS planned. Existing capability/policy paths remain authoritative.
- RBAC-UX: PASS planned. Scope and authorization for evidence/OperationRun links are explicit; non-members remain deny-as-not-found.
- Workspace isolation: PASS planned. Cross-workspace proof denial tests are required.
- Tenant/managed-environment isolation: PASS planned. Evidence and proof references must match workspace and managed environment.
- Run observability: PASS planned. Existing OperationRun proof only; no new run type.
- OperationRun start UX: PASS planned. No new local start UX.
- Ops-UX lifecycle: PASS planned. No new status/outcome transitions.
- Data minimization: PASS planned. No secrets/raw provider payloads in customer output, tests, reports, or logs.
- Test governance: PASS planned. Confidence/browser lanes explicit; heavy-governance not hidden.
- Proportionality: PASS planned. No new persisted truth or broad framework by default.
- No premature abstraction: PASS planned. Extend existing paths only after matrix proof.
- Persisted truth: PASS. No new persistence.
- Behavioral state: PASS. No new state family.
- UI semantics: PASS. No new UI taxonomy.
- Shared pattern first: PASS. Existing evidence/proof helpers reused.
- Provider boundary: PASS. Provider-specific semantics stay bounded.
- V1 explicitness / few layers: PASS. Targeted tests and fixes only.
- Spec discipline / bloat check: PASS. One coherent closure spec instead of many micro-specs.
- Filament-native UI: PASS planned. Existing Filament surfaces remain native/shared-first.
- UI/Productization coverage: PASS planned. Existing-surface presentation hardening only.
- Product Surface Contract Gate: PASS planned. Browser proof, human sanity, no-legacy, and implementation-report fields are explicit.

## Test Governance Check

- **Test purpose / classification by changed surface**: Unit for resolver/state mapping; Feature/Filament for evidence/report/review/restore/baseline scope and display; Browser for focused rendered proof; Heavy-Governance only if a matrix/discovery guard is added explicitly.
- **Affected validation lanes**: confidence, browser, optional heavy-governance.
- **Why this lane mix is the narrowest sufficient proof**: evidence/currentness truth is business behavior plus rendered product wording; full browser audit is unnecessary and out of scope.
- **Narrowest proving command(s)**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec403`
  - `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Evidence/EvidenceOverviewPageTest.php tests/Feature/Evidence/EvidenceSnapshotResourceTest.php --compact`
  - `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/EnvironmentReview/Spec388ReviewPublicationProofCurrentnessTest.php --compact`
  - `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php --compact`
  - targeted restore/baseline/finding/report tests changed by implementation
  - focused Spec 403 browser smoke
  - `git diff --check`
  - formatter for changed PHP files
- **Fixture / helper / factory / seed / context cost risks**: evidence/review/report/OperationRun/restore/baseline fixtures can become expensive. Keep new helpers opt-in and named for Spec 403 proof.
- **Expensive defaults or shared helper growth introduced?**: no by default.
- **Heavy-family additions, promotions, or visibility changes**: none planned.
- **Surface-class relief / special coverage rule**: standard-native Filament relief for unchanged resource mechanics; special coverage for customer-safe, monitoring-state, and proof-link surfaces.
- **Closing validation and reviewer handoff**: implementation report records command results, browser proof, human sanity, residual findings, and next action.
- **Budget / baseline / trend follow-up**: none expected; document if test runtime grows materially.
- **Review-stop questions**: Did every critical false-claim risk get a test? Did any customer-safe view expose raw proof? Did any current/released label conflict? Did any OperationRun link bypass authorization? Did any new abstraction slip in without updated proportionality review?
- **Escalation path**: document-in-feature for bounded residuals; follow-up-spec for structural product decisions; reject-or-split for broad audit/report/lifecycle creep.
- **Active feature PR close-out entry**: `Guardrail / Exception / Smoke Coverage`.
- **Why no dedicated follow-up spec is needed**: Spec 403 is the bounded closure package; only unresolved P0/P1 findings need remediation before Spec 404.

## Project Structure

### Documentation (this feature)

```text
specs/403-evidence-anchor-currentness-runtime-closure/
|-- spec.md
|-- plan.md
|-- tasks.md
|-- checklists/
|   `-- requirements.md
`-- implementation-report.md     # created during implementation
```

### Source Code (repository root)

Implementation may inspect and, only if confirmed by matrix/tests, minimally edit:

```text
apps/platform/app/Services/Evidence/
apps/platform/app/Support/Evidence/
apps/platform/app/Support/ReviewPublicationResolution/
apps/platform/app/Support/OpsUx/
apps/platform/app/Support/Operations/
apps/platform/app/Filament/Pages/Monitoring/
apps/platform/app/Filament/Pages/Reviews/
apps/platform/app/Filament/Resources/
apps/platform/app/Filament/Resources/*/Pages/
apps/platform/resources/views/filament/
apps/platform/app/Http/Controllers/
apps/platform/routes/                  # inspect-only for existing route authorization/scoping; route edits require spec/plan update
apps/platform/tests/
```

### Explicitly Out Of Scope

```text
database/migrations/
composer.json
package.json
apps/platform/config/
new routes/pages/navigation
new panel providers
new report/PDF runtime
new evidence providers
new governance lifecycle runtime
```

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| None planned | N/A | N/A |

## Proportionality Review

- **Current operator problem**: evidence-backed claims can mislead operators or customers if current/released/stale/missing/failed/partial/internal/customer-safe meanings drift.
- **Existing structure is insufficient because**: unknown until matrix/test inventory. Current assumption is existing structures are sufficient and need targeted usage/hardening.
- **Narrowest correct implementation**: matrix, tests, minimal existing-path fixes, focused browser proof.
- **Ownership cost created**: focused tests, implementation report, and any small helper extension.
- **Alternative intentionally rejected**: new evidence taxonomy, new proof framework, new currentness enum family, new customer output category, full browser audit, management-report runtime changes.
- **Release truth**: current-release product trust closure.

## Implementation Phases

1. Preparation and dirty-state baseline.
2. Repo truth inventory and Evidence/Currentness Coverage Matrix.
3. Gap classification and severity.
4. Tests first for current evidence, released/customer-safe evidence, OperationRun proof, and cross-scope denial.
5. Minimal runtime closure using existing helpers and surfaces.
6. Focused browser proof and human product sanity.
7. Implementation report, validation commands, residual findings, and recommended next action.

## Risk Controls

- Stop and update spec/plan before adding persistence, new routes, new product states, broad helper frameworks, provider integrations, report/PDF runtime, or lifecycle semantics.
- Stop and classify as product-decision required if existing contracts do not define customer-safe proof behavior.
- Do not claim browser proof unless focused browser tests actually run.
- Do not rewrite completed historical specs.
- Do not claim Spec 404 readiness unless Spec 403 final result allows it.