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

# Feature Specification: Spec 403 - Evidence Anchor & Currentness Runtime Closure

**Feature Branch**: `403-evidence-anchor-currentness-runtime-closure`
**Created**: 2026-06-23
**Status**: Draft / Ready for implementation preparation review
**Type**: Targeted product-contract hardening / evidence proof / runtime closure spec
**Runtime posture**: Existing evidence/currentness correctness, proof display, tests, and focused browser validation only. No new surfaces, no new product vocabulary, no broad runtime audit.
**Input**: User-provided Spec 403 draft, current repo truth, Product Surface Contract, Spec 400 product-contract audit context, Spec 402 authorization proof close-out, and existing evidence/currentness runtime surfaces.

## Candidate Selection Context

- **Selected candidate**: Evidence Anchor & Currentness Runtime Closure.
- **Source location**: Direct user-provided Spec 403 draft in the 2026-06-23 request, promoted from Spec 400 evidence/currentness product-contract risk and Spec 402's recommended next action.
- **Why selected**: `docs/product/spec-candidates.md` currently reports no safe automatic next-best-prep target, but the operator supplied a direct manual candidate. Spec 402 now reports `PASS` with no P0/P1 authorization blockers and explicitly recommends proceeding to Spec 403 after review. This candidate closes the next trust gap before management-report PDF staging validation or broader customer-output claims.
- **Roadmap relationship**: Supports the current productization and governance-hardening lane by proving evidence-backed claims across existing review, report, evidence, OperationRun, baseline, restore, and customer-safe surfaces before expanding customer-output or management-report claims.
- **Close alternatives deferred**:
  - Spec 404 - Management Report PDF Staging Validation is deferred until Spec 403 returns `PASS` or acceptable `PASS WITH CONDITIONS`.
  - Governance artifact lifecycle/retention runtime remains broader P2 lifecycle work and must not be hidden inside evidence/currentness closure.
  - JSON-to-JSONB migrations and index work remain data-layer hardening, not evidence-claim truth closure.
  - Full browser/UX/runtime audit remains out of scope; this spec requires focused browser proof only.
  - Provider readiness/onboarding productization remains optional productization work unless evidence/currentness proof exposes a P0/P1 product decision blocker.
- **Completed-spec guardrail result**:
  - No `specs/403-evidence-anchor-currentness-runtime-closure/` package existed before this preparation.
  - Specs 388 and 393 carry completed checklist/task signals and are read-only context for proof/currentness and evidence anchor behavior.
  - Specs 400, 401, and 402 carry audit, implementation-report, validation, browser, or completed-task signals and are read-only historical context.
  - Related specs such as 390 and 394 are implementation/preparation context only; do not rewrite, normalize, uncheck, or remove their historical task or validation language.
  - This package must build on existing repo truth such as `EvidenceAnchorResolver`, `EvidenceAnchorResult`, `EvidenceSnapshotStatus`, `EvidenceCompletenessState`, Spec 388 proof-currentness semantics, and Spec 393 evidence anchor reconciliation rather than replacing them with a new framework.
- **Smallest viable implementation slice**: Inventory existing evidence/currentness claims; build an Evidence/Currentness Coverage Matrix; add targeted tests for stale, missing, failed, partial, released, internal-only, customer-safe, unauthorized, cross-workspace, cross-environment, and OperationRun proof states; apply only minimal runtime fixes for confirmed misleading or unsafe evidence/currentness behavior; record final results in an implementation report.
- **Feature description for Spec Kit**: Prove and minimally harden existing evidence-backed TenantPilot surfaces so admin, customer review, report, OperationRun, findings, baseline, and restore outputs distinguish current runtime evidence, stale/missing/failed/partial evidence, released review/report evidence, internal-only proof, and customer-safe proof without adding new surfaces, new product vocabulary, or a broad audit framework.

## Spec Candidate Check *(mandatory - SPEC-GATE-001)*

- **Problem**: Evidence-backed TenantPilot surfaces can imply stronger proof than the underlying evidence supports if current, stale, missing, failed, partial, released, internal-only, and customer-safe evidence states are not consistently represented at runtime.
- **Today's failure**: A future implementation can pass local tests while a customer-safe review, report receipt, evidence overview, OperationRun proof link, finding reference, baseline compare, or restore readiness surface overstates currentness, exposes internal proof, reuses stale proof, or confuses released evidence with live runtime evidence.
- **User-visible improvement**: Operators and customer reviewers see truthful evidence status, know whether proof is current or historical, and do not receive stronger claims than TenantPilot can prove for the active workspace and managed environment.
- **Smallest enterprise-capable version**: A matrix-first runtime closure over existing evidence/currentness surfaces, focused tests, focused browser proof, and minimal fixes for confirmed incorrect labels, links, scoping, or disclosure. No new route, navigation entry, customer output category, report runtime, provider model, persisted truth, or evidence taxonomy is included.
- **Explicit non-goals**: No management-report PDF staging validation, no new PDF/report template, no new customer review surface, no new evidence provider, no provider integration, no governance artifact lifecycle/retention/export/delete/hold work, no JSONB migration, no full browser/UX/runtime audit, no dashboard redesign, no new product vocabulary, no completed-spec rewrite.
- **Permanent complexity imported**: A spec-local implementation report and coverage matrix, focused feature/Filament/browser tests, and possibly small updates to existing helpers or labels. No new persisted table, source of truth, enum/status family, route family, product taxonomy, cross-domain UI framework, or broad proof registry is allowed by default.
- **Why now**: Spec 400 flagged evidence/currentness as a gating productization risk; Spec 401 closed selected high-risk action proof; Spec 402 now reports no P0/P1 authorization blockers and recommends Spec 403. This is the last bounded trust closure before management-report PDF staging validation.
- **Why not local**: A local label fix would not prove evidence overview, review packs, report receipts, customer review workspace, OperationRun proof, findings, baseline, restore, and customer/internal boundaries together. The work must be matrix-first so fixes stay targeted and evidence-backed.
- **Approval class**: Core Enterprise.
- **Red flags triggered**: Many surfaces and proof semantics. Defense: the matrix is a spec-local closure artifact, not runtime infrastructure; scope is existing behavior only; new vocabulary, new surfaces, and broad frameworks are forbidden.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve as a bounded evidence/currentness runtime closure package.

## Problem Statement

TenantPilot already has evidence snapshots, evidence anchors, review packs, stored reports, OperationRun proof links, baseline/restore proof surfaces, and customer review outputs. The remaining risk is not the absence of evidence. The risk is inconsistent or over-strong runtime claims about what that evidence proves.

This spec answers:

```text
Can TenantPilot prove that evidence-backed UI and customer-output surfaces distinguish current, stale, missing, failed, partial, released, internal-only, and customer-safe proof correctly?
```

A surface is closed only when the implementation and tests prove:

- which evidence is authoritative for the claim,
- whether that evidence is current, stale, missing, failed, partial, superseded, released, or historical,
- whether it belongs to the active workspace and managed environment,
- whether it is internal-only or customer-safe,
- whether released review/report evidence differs from current runtime evidence,
- whether missing proof is represented honestly,
- whether OperationRun proof links are authorized and scoped,
- and whether no customer-facing claim is stronger than the underlying evidence.

## Product / Business Value

TenantPilot is a governance/security-adjacent SaaS. Evidence-backed claims such as "ready", "current", "verified", "released", "complete", or "customer-safe" must be true at runtime. Closing this gap reduces false confidence, prevents customer-visible proof leakage, and gives reviewers a concrete proof matrix before management-report PDF staging validation or broader customer-output expansion.

## Primary Users / Operators

- Workspace owners, managers, and operators who use evidence/review/report/restore/baseline surfaces to make governance decisions.
- Customer reviewers consuming customer-safe review workspace and report outputs.
- Support/platform reviewers who may inspect internal proof through authorized secondary surfaces.
- Engineering reviewers and future implementation agents validating evidence/currentness truth.

## Spec Scope Fields *(mandatory)*

- **Scope**: Existing rendered and data-backed surfaces that display or depend on evidence/currentness, including evidence overview, evidence detail/anchors, review packs, customer review workspace, report receipt/output, OperationRun proof references, findings/governance references, baseline compare evidence, restore readiness/proof, and dashboard/readiness indicators where they summarize evidence state.
- **Primary Routes / Surfaces**:
  - Evidence overview: `apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php`.
  - Evidence detail/resource: `apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php` and nested pages.
  - Customer review workspace: `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`.
  - Environment reviews and publication resolution: `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php` and `ResolveReviewPublication`.
  - Review packs and review output: `apps/platform/app/Filament/Resources/ReviewPackResource.php`.
  - Stored reports/report receipt/output: `apps/platform/app/Filament/Resources/StoredReportResource.php` and report output builders/controllers discovered during implementation.
  - OperationRun proof helpers and links: `OperationRunLinks`, `OperationRunPolicy`, Monitoring/Operations detail surfaces, and linked proof surfaces.
  - Findings/governance references: finding and exception resources/pages where evidence is referenced.
  - Baseline compare/proof surfaces: `BaselineCompareMatrix`, baseline snapshot/profile resources, and baseline evidence providers.
  - Restore readiness/proof surfaces: `RestoreRunResource`, restore presenters, restore proof views, and restore readiness support classes.
- **Data Ownership**:
  - Evidence snapshots and evidence items remain workspace plus managed-environment owned.
  - Review packs, environment reviews, stored reports, findings, restore runs, baseline snapshots, and OperationRuns keep their existing ownership and source-of-truth semantics.
  - No new persisted entity/table/artifact is approved by default.
- **RBAC**:
  - Admin plane `/admin` uses authenticated `User`, workspace context, managed-environment entitlement, and existing capabilities/policies.
  - Customer-safe surfaces may show only customer-safe evidence summaries and must not expose raw internal proof by default.
  - OperationRun and evidence technical links must be authorized and scoped before rendering or serving.
  - Non-member or wrong workspace/environment remains deny-as-not-found; member missing capability remains forbidden at execution/access-check level.

For canonical-view or mixed-scope specs:

- **Default filter behavior when environment-context is active**: Existing explicit `environment_id` filters remain page-owned and must not silently choose arbitrary current evidence for a workspace-wide view.
- **Explicit entitlement checks preventing cross-tenant leakage**: All evidence, OperationRun proof, review/report, baseline, restore, and finding references must prove workspace and managed-environment entitlement before rendering or linking records.

## No Legacy / No Backward Compatibility Constraint *(mandatory)*

TenantPilot is pre-production for this product-contract closure.

- **Compatibility posture**: canonical current evidence/currentness behavior over old ambiguous labels or fallback selectors.
- **Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?**: no new compatibility path is allowed. Existing historical specs remain read-only and are not normalized.
- **Why clean replacement is safe now**: Evidence/currentness claims are trust-critical. If a label or fallback overstates proof, it must be corrected or explicitly classified as product-decision debt rather than preserved for compatibility.

## UI Surface Impact *(mandatory - UI-COV-001)*

Does this spec add, remove, rename, or materially change any reachable UI surface?

- [ ] No UI surface impact
- [x] Existing page changed
- [ ] New page/route added
- [ ] Navigation changed
- [ ] Filament panel/provider surface changed
- [ ] New modal/drawer/wizard/action added
- [ ] New table/form/state added
- [x] Customer-facing surface changed
- [ ] Dangerous action changed
- [x] Status/evidence/review presentation changed
- [x] Workspace/environment context presentation changed

Rationale: Spec 403 may alter existing labels, links, disabled/hidden proof paths, and customer-safe evidence summaries on existing pages only. It must not add new pages, routes, navigation, or actions unless the spec/plan are updated first.

## UI/Productization Coverage *(mandatory when UI Surface Impact is not "No UI surface impact")*

- **Route/page/surface**: Existing evidence overview/detail, customer review workspace, environment review detail/publication resolution, review pack detail/output, stored report detail/output, operations proof links, finding references, baseline compare, and restore readiness/proof surfaces.
- **Current or new page archetype**: Existing Receipt, Decision, Report, Search/Index, Technical Annex, Dashboard, and Wizard archetypes only. No new archetype may be introduced.
- **Design depth**: Domain Pattern Surface / Technical Annex / customer-safe Report or Review Surface depending on existing page. This spec is runtime truth closure, not redesign.
- **Repo-truth level**: repo-verified existing surfaces.
- **Existing pattern reused**: `EvidenceAnchorResolver`, `EvidenceAnchorResult`, `EvidenceSnapshotStatus`, `EvidenceCompletenessState`, Spec 388 proof-currentness helpers, existing policies, existing Product Surface Contract patterns, existing badges/shared presenters where already used.
- **New pattern required**: none by default. If implementation requires a new helper, first prove why extending existing evidence/proof paths is insufficient and update spec/plan with proportionality review.
- **Screenshot required**: no full screenshot set by default. Focused browser proof is required for critical evidence/currentness paths.
- **Page audit required**: no full page audit. Matrix and focused proof only.
- **Customer-safe review required**: yes for Customer Review Workspace, review pack/report output, and any customer-visible evidence/proof labels.
- **Dangerous-action review required**: no new dangerous action is in scope. Restore/high-impact existing actions are inspected only where proof/currentness labels may overstate readiness.
- **Coverage files updated or explicitly not needed**:
  - [x] `docs/ui-ux-enterprise-audit/route-inventory.md` - review/update touched existing surfaces if runtime UI files or reachable evidence/status semantics change.
  - [x] `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` - review/update touched existing surfaces if runtime UI files or reachable evidence/status semantics change.
  - [ ] `docs/ui-ux-enterprise-audit/page-reports/...`
  - [ ] `docs/ui-ux-enterprise-audit/strategic-surfaces.md`
  - [ ] `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md`
  - [ ] `docs/ui-ux-enterprise-audit/unresolved-pages.md`
  - [ ] `N/A - no new reachable UI surface; existing evidence/currentness presentation hardening only`
- **No-impact rationale when applicable**: N/A because existing rendered evidence/status presentation may change.

## Product Surface Impact *(mandatory for UI-affecting specs)*

Reference: `docs/product/standards/product-surface-contract.md`.

- **Product Surface Contract applies?**: yes. Evidence, reports, customer output, readiness/proof, OperationRun links, and status presentation are explicitly covered by the contract.
- **Page archetype**: existing archetypes only. Exact affected pages and archetypes are recorded in the implementation report.
- **Primary user question**: "Can I trust this evidence-backed claim for this workspace/environment and audience?"
- **Primary action**: no new primary action. Existing next actions must remain accurate and must not compete with technical proof links.
- **Surface budget result**: neutral by default. No new tables, top-level readiness model, raw technical links, or OperationRun links may be added to default product-facing views.
- **Technical Annex / deep-link demotion**: OperationRun, raw evidence IDs, source keys, detectors, fingerprints, raw provider payloads, and technical logs remain hidden, secondary, or authorized internal/audit links only.
- **Canonical status vocabulary**: touched Evidence Overview runtime proof uses `Ready`, `Needs attention`, `Blocked`, `Running`, `Failed`, `Expired`, `Not configured`, and `Historical`. Broader Product Surface Contract vocabulary still permits `Unknown` and `Superseded`, but this runtime closure must not introduce them for current Evidence Overview proof states.
- **Visible complexity impact**: neutral or decreased. Corrections should make proof meaning clearer without adding a new UI layer.
- **Product Surface exceptions**: none planned.

## Browser Verification Plan *(mandatory)*

- **Browser proof required?**: yes.
- **No-browser rationale**: N/A.
- **Focused path when required**:
  1. Admin Evidence Overview current/stale/missing/failed or partial path.
  2. Evidence detail/anchor path for current versus stale/superseded/missing proof.
  3. Customer Review Workspace or review/report output path proving customer-safe released proof.
  4. Released review/report evidence path proving released evidence is not claimed as live current runtime evidence.
  5. Unauthorized or cross-workspace/cross-environment evidence anchor path.
  6. OperationRun proof link visibility or blocked access path.
- **Primary interaction to execute**: navigate existing pages, verify labels/links/actions, test denied URLs, inspect customer-safe output, and record console/runtime/Livewire/Filament errors.
- **Console, Livewire, Filament, network, and 500-error checks**: planned.
- **Full-suite failure triage**: unrelated browser failures are documented separately; do not claim full browser audit.

## Human Product Sanity Check *(mandatory)*

- **Required?**: yes.
- **No-human-sanity rationale**: N/A.
- **Reviewer questions**: Does each touched surface immediately communicate what proof exists? Is current versus released versus stale clear? Are technical details demoted? Are customer-safe boundaries credible? Is there exactly one dominant next action? Did visible complexity stay neutral or decrease?
- **Planned result location**: `specs/403-evidence-anchor-currentness-runtime-closure/implementation-report.md`.

## Product Surface Merge Gate Checklist *(mandatory)*

- [x] No-legacy posture or approved exception recorded.
- [x] Product Surface Impact is completed for existing evidence/currentness hardening.
- [x] UI coverage registry review/update is required for touched existing surfaces when runtime UI files or reachable evidence/status semantics change.
- [x] Browser proof is required for representative rendered evidence/currentness paths.
- [x] Human Product Sanity is required for changed rendered behavior.
- [x] Product Surface exceptions are documented as `none planned`.
- [x] Implementation report will state Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, visible complexity outcome, and no completed-spec rewrite assertion.

## Cross-Cutting / Shared Pattern Reuse

- **Cross-cutting feature?**: yes.
- **Interaction class(es)**: evidence/report viewers, status messaging, action links, OperationRun proof links, customer-safe output, readiness/proof labels.
- **Systems touched**: `EvidenceAnchorResolver`, `EvidenceAnchorResult`, evidence snapshot resources, environment review/review pack/stored report resources, customer review workspace, OperationRun links/policies, baseline and restore proof surfaces, existing badges/presenters where used.
- **Existing pattern(s) to extend**: existing evidence anchor and proof-currentness paths from Specs 388 and 393, existing badge/shared presenter paths, existing policies and scoped queries.
- **Shared contract / presenter / builder / renderer to reuse**: `EvidenceAnchorResolver`, `EvidenceAnchorResult`, `EvidenceSnapshotStatus`, `EvidenceCompletenessState`, `ResolutionProof*` support where review-publication proof is involved, `OperationRunLinks`, `OperationRunPolicy`, and existing ArtifactTruth/Badge paths where already present.
- **Why the existing shared path is sufficient or insufficient**: sufficient until the coverage matrix proves a concrete gap. New runtime abstractions are out of scope by default.
- **Allowed deviation and why**: bounded local label/link correction only when existing shared path cannot express a false claim without broader changes. Any recurring structural gap becomes a follow-up spec.
- **Consistency impact**: default product surfaces must agree on current, stale, missing, failed, partial, released, internal-only, customer-safe, and unauthorized proof semantics.
- **Review focus**: no parallel proof vocabulary, no raw technical leakage, no arbitrary latest evidence fallback, no customer-facing overclaim, no completed-spec rewrite.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: link/proof visibility may be touched; no new OperationRun start/completion behavior is planned.
- **Shared OperationRun UX contract/layer reused**: existing `OperationRunLinks`, `OperationRunPolicy`, OperationRun Start UX Contract, and Monitoring -> Operations detail route helpers.
- **Delegated start/completion UX behaviors**: unchanged.
- **Local surface-owned behavior that remains**: existing proof/reference display and existing initiation inputs only.
- **Queued DB-notification policy**: unchanged; no new queued DB notifications.
- **Terminal notification path**: unchanged.
- **Exception required?**: none planned.

## Provider Boundary / Platform Core Check

- **Shared provider/platform boundary touched?**: possibly, only where provider freshness affects evidence/currentness claims.
- **Boundary classification**: mixed. Provider freshness/permissions remain provider-owned; evidence, review/report truth, OperationRun proof, workspace/environment scoping, and customer-safe disclosure are platform-core product semantics.
- **Seams affected**: evidence currentness, provider freshness labels that influence evidence claims, report/review output, restore/baseline proof, OperationRun proof links.
- **Neutral platform terms preserved or introduced**: workspace, managed environment, provider, evidence, proof, review, report, operation, current, released, historical, customer-safe.
- **Provider-specific semantics retained and why**: Microsoft/Graph/Entra terms remain only in existing provider-owned diagnostics and are not promoted to platform-core evidence vocabulary.
- **Why this does not deepen provider coupling accidentally**: the spec verifies existing evidence/currentness claims and forbids new provider models or taxonomies.
- **Follow-up path**: provider readiness/onboarding productization remains a separate manual candidate if runtime evidence shows operator friction.

## UI / Surface Guardrail Impact

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Evidence overview/detail | yes, if labels or links change | Native Filament + existing evidence helpers | evidence/status/link | page, table, detail route | none planned | Existing-surface evidence truth only |
| Customer review workspace | yes | Existing Filament page | customer-safe evidence/report output | page, table, report/action link | none planned | No raw proof by default |
| Review pack/environment review/stored report | yes | Native Filament resources/pages | released/current proof and report output | detail, actions, report links | none planned | Existing output semantics only |
| OperationRun proof links | possibly | Existing link helpers/policies | technical proof links | link/action/detail route | none planned | Link visibility/scoping only |
| Baseline/restore/finding references | possibly | Existing resources/pages/views | evidence/readiness/proof | page, detail, wizard, table | none planned | Correct labels only |

## Decision-First Surface Role

| Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction |
|---|---|---|---|---|---|---|---|
| Evidence Overview | Dashboard Page | Decide whether environment evidence can support review/report work | environment, evidence state, generated time, next step | internal evidence detail and technical proof links | Dashboard because it summarizes workspace evidence readiness; proof inspection stays secondary through demoted links | evidence readiness and review preparation | reduces search for stale/missing proof |
| Customer Review Workspace | Primary Decision Surface for customer-safe consumption | Decide whether released review/output can be consumed or downloaded | released review state, customer-safe evidence summary, package/download availability | internal evidence hidden; detail only through authorized operator paths | Primary for customer-safe consumption | customer review/report consumption | prevents customer-facing overclaim |
| Review Pack / Report Receipt | Receipt Page | Decide whether an output happened and can be trusted | generated/released state, evidence basis, customer-safe availability | technical proof and operation detail secondary | Receipt because it proves what happened | output verification | separates current runtime from released evidence |
| OperationRun detail/link | Technical Annex Page | Diagnose proof or execution outcome | run status and authorized link only when relevant | full operation detail in Monitoring | Not primary for customer/customer default views | troubleshooting/audit | keeps technical proof demoted |
| Restore/Baseline/Finding evidence references | Decision or Wizard context depending on existing surface | Decide whether readiness/result/governance claim is trustworthy | currentness/readiness/evidence availability | raw proof secondary | Existing primary context remains unchanged | restore/baseline/finding workflow | prevents false readiness |

## Audience-Aware Disclosure

| Surface | Audience Modes In Scope | Decision-First Default-Visible Content | Operator Diagnostics | Support / Raw Evidence | One Dominant Next Action | Hidden / Gated By Default | Duplicate-Truth Prevention |
|---|---|---|---|---|---|---|---|
| Customer Review Workspace | customer/read-only, operator-MSP | released review status, customer-safe evidence summary, package/download state | operator-only review/report detail via existing authorized paths | raw evidence, OperationRun, fingerprints, source keys hidden | open/download customer-safe output when ready | raw evidence and technical proof | customer summary states evidence basis once |
| Evidence Overview / Evidence Detail | operator-MSP, support-platform | evidence state, currentness, next step | technical detail and source summary | raw payload/source keys only where existing authorized detail allows | inspect current evidence or refresh/generate evidence | cross-environment records, raw payloads | anchor result owns link meaning |
| Review Pack / Stored Report | operator-MSP, customer-safe output | released/generated evidence basis and customer-safe output state | report/review internals where authorized | raw payloads and renderer internals hidden | open/download output or inspect review | OperationRun/raw artifact links in default customer view | released versus current labels do not repeat conflicting truth |
| Restore/Baseline/Finding references | operator-MSP | readiness/result/evidence availability | existing proof/diagnostic sections | raw restore/baseline/evidence payloads hidden | continue existing workflow action | technical proof details secondary | one readiness/currentness source per concept |

## UI/UX Surface Classification

| Surface | Action Surface Class | Surface Type | Likely Next Operator Action | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type / Justification |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Evidence Overview | List / Table / Read-only | Monitoring registry | Inspect current evidence or see missing/stale proof | existing row navigation/filter | existing | existing secondary/internal links | none | `/admin/evidence` route name in repo | evidence snapshot detail when linkable | workspace and explicit environment filter | Evidence | evidence state and next step | none |
| Customer Review Workspace | Workbench / Report | Customer-safe review hub | Open or download customer-safe output | existing row/action | existing | existing secondary actions | none | existing customer review workspace route | review/report/pack detail by existing routes | workspace and environment filter | Customer review | released/customer-safe proof basis | none |
| Review Pack / Stored Report | Receipt / Detail | Output receipt | Open/download/inspect output | existing detail pages | existing | internal proof secondary | existing actions unchanged | existing resources | existing resource view pages | workspace/environment | Review pack / Stored report | generated/released evidence basis | none |
| Restore/Baseline/Finding references | Existing Decision/Wizard/List | Existing domain surfaces | Continue safe workflow or inspect proof | existing | existing | existing proof/detail secondary | existing destructive actions unchanged | existing resources/pages | existing resources/pages | workspace/environment | Existing domain nouns | readiness/currentness truth | none |

## Operator Surface Contract

| Surface | Primary Persona | Decision / Operator Action Supported | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|---|
| Evidence Overview | Workspace operator | Decide whether evidence can support review/report work | Secondary context list | Is the evidence basis current and usable? | state, generated time, next step, scoped link if authorized | raw items, source keys, technical detail | evidence currentness, completeness, lifecycle | read-only | inspect evidence / clear filter | none |
| Customer Review Workspace | Customer reviewer / MSP operator | Decide whether released output is safe to consume | Customer-safe report hub | Can this released review/output be trusted? | released review/output state, customer-safe summary, download state | raw evidence, operations, fingerprints | released/current distinction, customer-safe availability | read-only/customer output | open/download customer-safe output | none |
| OperationRun proof links | Operator/support | Diagnose proof/execution | Technical annex link | Can I inspect the operation proof? | scoped authorized link only when allowed | full run context | execution outcome | read-only detail | view run | none |
| Restore/Baseline/Finding references | Tenant operator | Decide whether readiness/result/governance claim is safe | Existing domain surface | Does this claim have current proof? | readiness/evidence state and next safe action | raw payloads/proof internals | readiness, evidence, execution result | existing behavior | existing primary action | existing dangerous actions unchanged |

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Evidence Overview | `EvidenceOverview` page | existing clear filters only | existing row/detail link only when authorized/current enough | none planned | none | existing | N/A | N/A | no mutation | Correct labels/links only |
| EvidenceSnapshotResource | resource pages | existing actions only | existing record URL | existing | existing | existing | existing | existing | existing for mutations | No new actions |
| CustomerReviewWorkspace | page | existing customer-safe actions | existing row/action links | existing | none | existing | N/A | N/A | existing acknowledgements only | No raw proof links by default |
| EnvironmentReview/ReviewPack/StoredReport resources | resource pages | existing actions only | existing | existing | existing | existing | existing | existing | existing | Released/current labels and proof links only |
| Restore/Baseline/Finding resources/pages | existing pages | existing actions only | existing | existing | existing | existing | existing | existing | existing | No new dangerous/high-impact actions |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: no.
- **New persisted entity/table/artifact?**: no.
- **New abstraction?**: no by default. Extending existing helpers may be allowed only if a matrix finding proves direct local correction is insufficient.
- **New enum/state/reason family?**: no new family. Existing statuses and canonical product vocabulary must be reused or mapped.
- **New cross-domain UI framework/taxonomy?**: no.
- **Current operator problem**: existing surfaces may overstate evidence proof or currentness, especially customer-safe/released/current distinctions.
- **Existing structure is insufficient because**: unknown until matrix/test inventory. If existing structures can represent the correct truth, use them. If not, update spec/plan before adding structure.
- **Narrowest correct implementation**: matrix-first proof, targeted tests, local/shared-path corrections, no broad abstraction.
- **Ownership cost**: focused tests, implementation report, and any small helper extension. No new runtime ownership surface by default.
- **Alternative intentionally rejected**: broad proof-currentness framework, new evidence taxonomy, new UI status model, new report runtime, and full browser audit.
- **Release truth**: current-release trust closure.

### Compatibility posture

Pre-production canonical correction. No compatibility aliases or legacy fallback behavior are approved when they preserve false evidence/currentness claims.

## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*

- **Test purpose / classification**: Unit for existing resolver/helper semantics; Feature/Filament for rendered resource/page state and RBAC; Browser for focused evidence/currentness/customer-safe flows; Heavy-Governance only if an explicit matrix guard is added.
- **Validation lane(s)**: confidence, browser, optional heavy-governance.
- **Why this classification and these lanes are sufficient**: evidence/currentness closure requires both business truth tests and representative rendered proof. Full browser audit is out of scope.
- **New or expanded test families**: focused Spec 403 tests only; reuse existing Spec 388/393/Evidence/Review/Report/Restore/Baseline tests where possible.
- **Fixture / helper cost impact**: workspace, managed-environment, user, evidence snapshot, review, report, review pack, OperationRun, restore, baseline fixtures. Keep new fixture breadth explicit and opt-in.
- **Heavy-family visibility / justification**: none planned.
- **Special surface test profile**: shared-detail-family, customer-safe report surface, monitoring-state-page, restore wizard/detail, baseline decision surface.
- **Standard-native relief or required special coverage**: standard-native Filament relief for unchanged CRUD/resource mechanics; special browser proof for customer-safe and evidence/currentness paths.
- **Reviewer handoff**: verify lane fit, no hidden broad browser/full-suite claim, no new helper default breadth, no raw evidence leakage.
- **Budget / baseline / trend impact**: none expected; document if focused browser/fixture setup materially increases runtime.
- **Escalation needed**: document-in-feature for bounded implementation decisions; follow-up-spec for structural product decisions or recurring proof gaps.
- **Active feature PR close-out entry**: `Guardrail / Exception / Smoke Coverage`.
- **Planned validation commands**:
  - `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 browser smoke for Spec 403
  - `git diff --check`
  - project formatter for changed PHP files

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Current Evidence Claims Are Honest (Priority: P1)

As a workspace operator, I need current evidence links and labels to use only scoped, complete, non-expired evidence so I do not rely on stale, partial, failed, missing, or wrong-environment proof.

**Why this priority**: Current evidence is the basis for review, report, baseline, and restore decisions.

**Independent Test**: Seed current, stale, partial, failed, missing, superseded, wrong-workspace, and wrong-environment evidence and verify only valid scoped current evidence can support a current evidence claim or link.

**Acceptance Scenarios**:

1. **Given** an environment has complete active non-expired evidence with no missing or stale dimensions, **When** the current evidence surface renders, **Then** the claim may be shown as current and linkable only for an authorized actor.
2. **Given** only stale, expired, partial, failed, queued, generating, superseded, or wrong-scope evidence exists, **When** the current evidence surface renders, **Then** it shows `Needs attention`, `Running`, `Failed`, `Blocked`, `Expired`, or `Not configured` language and does not expose a current proof link.
3. **Given** a user is not entitled to a workspace or environment, **When** they access an evidence anchor URL or proof link, **Then** access is denied as not found where membership/scope is missing.

### User Story 2 - Released And Customer-Safe Proof Is Distinct (Priority: P1)

As a customer reviewer or MSP operator, I need released review/report evidence to be distinguished from current runtime evidence and stripped of internal proof so customer output does not overclaim live/current state or leak internal detail.

**Why this priority**: Customer-facing proof must be trustworthy before management-report PDF staging validation or broader output claims.

**Independent Test**: Publish/release a review/report with bound evidence, create newer runtime evidence, and verify customer-safe output remains release-bound and customer-safe while operator surfaces can still compare to current runtime evidence where authorized.

**Acceptance Scenarios**:

1. **Given** a released review or report was generated from evidence A and newer runtime evidence B exists, **When** the customer-safe output renders, **Then** it identifies the released/generated evidence basis and does not claim live current runtime state.
2. **Given** released evidence is missing, failed, partial, stale, or not customer-safe, **When** customer-safe output renders, **Then** it states the limitation or unavailability and does not expose internal proof as a substitute.
3. **Given** an internal proof link exists, **When** a customer-safe context renders, **Then** raw evidence routes, OperationRun links, source keys, fingerprints, provider payloads, and internal reason families are hidden.

### User Story 3 - Operation, Restore, Baseline, Finding, And Report Proof Links Are Scoped (Priority: P2)

As an operator, I need secondary proof links to be authorized, scoped, and labelled with the right proof meaning so I do not mistake execution proof, restore readiness, baseline comparison, finding evidence, or report receipt proof for stronger current evidence than it is.

**Why this priority**: These surfaces are not all customer-default surfaces, but they can still drive unsafe decisions if proof labels are wrong.

**Independent Test**: Use existing OperationRun, restore, baseline, finding, and report fixtures to verify proof links and labels are scoped, authorized, and do not overstate currentness or success.

**Acceptance Scenarios**:

1. **Given** an OperationRun failed, was cancelled, is running, or belongs to another workspace/environment, **When** a proof surface renders, **Then** it is not shown as successful current evidence and links are hidden or denied as appropriate.
2. **Given** restore readiness or baseline compare proof is stale, missing, failed, partial, or expired, **When** the surface renders, **Then** readiness/result language does not imply current executable proof.
3. **Given** a finding or governance reference cites evidence, **When** the reference renders, **Then** the surface distinguishes current, released/historical, missing, blocked, or needs-attention proof where applicable.

### Edge Cases

- Workspace-wide evidence overview must not choose one arbitrary managed-environment snapshot as current evidence.
- Evidence generated for one managed environment must not support another managed environment's claim even inside the same workspace.
- A released review/report remains release-bound when current runtime evidence changes.
- Successful OperationRun execution is not evidence of artifact/currentness unless the artifact proof exists and is current for the claim.
- Failed, cancelled, blocked, running, or stale OperationRuns do not create success proof.
- Missing product decisions must be reported as blockers or deferrals, not silently invented.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-403-001**: The implementation MUST create an Evidence/Currentness Coverage Matrix in `implementation-report.md` before runtime fixes are classified as complete.
- **FR-403-002**: Current evidence claims MUST be backed only by evidence that is scoped to the active workspace and managed environment, complete, active/current according to existing repo contracts, non-expired, and authorized for the actor.
- **FR-403-003**: As an umbrella prohibition, stale, expired, superseded, failed, queued, generating, partial, missing, wrong-workspace, wrong-environment, or unauthorized evidence MUST NOT be shown as current proof.
- **FR-403-004**: Customer-safe surfaces MUST show customer-safe summaries only and MUST NOT expose raw provider payloads, raw evidence source keys, fingerprints, raw evidence IDs, OperationRun URLs, stack traces, raw exception messages, internal reason ownership, or internal-only audit metadata by default.
- **FR-403-005**: Released review/report evidence MUST be distinguished from current runtime evidence and MUST remain tied to the evidence/report/review state used at release or generation time.
- **FR-403-006**: Missing evidence MUST be represented as `Not configured` or `Needs attention` and MUST NOT be shown as verified, ready, current, or complete.
- **FR-403-007**: Failed evidence collection or failed proof generation MUST be represented as `Failed`, `Blocked`, or `Needs attention` and MUST NOT be shown as successful proof.
- **FR-403-008**: Partial evidence MUST be represented as partial/needs attention/incomplete according to existing vocabulary and MUST NOT be shown as complete.
- **FR-403-009**: OperationRun proof links MUST be authorized, workspace-scoped, managed-environment-scoped where applicable, and hidden or denied when the actor lacks entitlement.
- **FR-403-010**: OperationRun proof MUST NOT be exposed in customer-safe context unless an existing contract explicitly allows the customer-safe form; technical OperationRun links remain secondary/internal.
- **FR-403-011**: Provider freshness or permission-limited provider state MUST affect evidence/currentness claims where existing repo contracts already connect provider freshness to evidence quality.
- **FR-403-012**: Baseline compare and restore readiness/proof surfaces MUST not treat stale, expired, failed, partial, or missing proof as current readiness.
- **FR-403-013**: Finding/governance references that cite evidence MUST not imply currentness when only released/historical/old proof exists.
- **FR-403-014**: Runtime fixes MUST reuse or minimally extend existing evidence/currentness helpers and shared patterns; adding a new persisted source of truth, enum/status family, product taxonomy, route, or broad resolver framework requires spec/plan update before coding.
- **FR-403-015**: Remaining P0/P1 findings MUST be fixed if safe and bounded, or reported with exact reason and blocking/defer classification if unresolved product decisions prevent a fix.
- **FR-403-016**: The final implementation report MUST include the Evidence/Currentness Coverage Matrix, runtime changes, tests, browser proof, customer-safe proof, current-versus-released proof, remaining findings, deferred items, validation commands, and recommended next action.
- **FR-403-017**: If implementation changes runtime UI files or reachable evidence/status semantics, it MUST review and update applicable `docs/ui-ux-enterprise-audit/route-inventory.md` and `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` entries for touched existing surfaces, or record that existing registry entries were reviewed and remain current.

### Non-Functional Requirements

- **NFR-403-001**: Evidence/currentness evaluation for rendered pages MUST remain DB-only and MUST NOT make Graph/provider calls during UI render.
- **NFR-403-002**: Any new or changed tests MUST use the narrowest honest lane and keep expensive fixtures explicit.
- **NFR-403-003**: No secrets, tokens, raw provider payloads, raw credential payloads, or sensitive raw evidence dumps may appear in logs, tests, reports, screenshots, or implementation notes.
- **NFR-403-004**: Implementation MUST preserve Filament v5 and Livewire v4 compliance and avoid Filament v3/v4 or Livewire v3 APIs.
- **NFR-403-005**: Implementation MUST not add migrations, env vars, queues, scheduler changes, storage topology changes, panel provider changes, or asset registration unless spec/plan are updated first.

## Key Existing Truth Sources

- **Evidence truth**: `EvidenceSnapshot`, `EvidenceSnapshotItem`, `EvidenceSnapshotStatus`, `EvidenceCompletenessState`, `EvidenceAnchorResolver`, `EvidenceAnchorResult`.
- **Released review/report truth**: `EnvironmentReview`, `ReviewPack`, `StoredReport`, review pack service/builders, report output/receipt builders.
- **Execution proof truth**: `OperationRun`, `OperationRunService`, `OperationRunLinks`, `OperationRunPolicy`, Spec 388 proof-currentness support for review publication.
- **Readiness/proof domain truth**: restore safety/readiness support, baseline compare/evidence providers, finding/evidence references.
- **Authorization truth**: policies, capability resolvers, workspace/environment scoping, Spec 402 resource authorization proof.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-403-001**: The final Evidence/Currentness Coverage Matrix covers all required surface groups from this spec or records why a group is not repo-real/applicable.
- **SC-403-002**: Targeted tests prove stale, missing, failed, partial, released/current, customer-safe, unauthorized, cross-workspace/cross-environment, and OperationRun proof behavior for the critical paths touched or confirmed.
- **SC-403-003**: Focused browser proof covers at least one admin evidence/currentness path, one customer-safe review/report path, one released evidence path, one stale/missing/failed path, one unauthorized/cross-scope path, and one OperationRun proof link visibility or blocked-access path, unless the implementation report records an exact no-browser blocker.
- **SC-403-004**: No P0 findings remain. If any P1 remains, each is explicitly classified with safe deferral or product-decision blocker language.
- **SC-403-005**: No customer-facing claim exceeds the underlying evidence, and no new product/currentness vocabulary is introduced.
- **SC-403-006**: The implementation report can recommend Spec 404 only when Spec 403 returns `PASS`, or can recommend bounded remediation when it returns `PASS WITH CONDITIONS` or `FAIL`.

## Required Evidence/Currentness Matrix

The implementation report MUST include this matrix shape:

| Surface | Evidence Source | Currentness Source | Released Snapshot Source | Customer-safe Boundary | Internal-only Risk | Workspace/Environment Scope | Authorization Mechanism | Test Proof | Browser Proof | Status | Risk | Follow-up |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| TBD during implementation | TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD | PASS / PASS WITH EXCEPTION / MISSING PROOF / DEFECT FOUND / PRODUCT DECISION REQUIRED / DEFERRED | P0/P1/P2/P3/None | TBD |

## Finding Severity

- **P0**: Customer-safe output exposes internal-only evidence; stale/failed/missing proof is shown as current/verified; released output falsely claims live current state; unauthorized evidence/OperationRun proof is accessible.
- **P1**: Critical behavior appears safe but lacks proof for current vs released, customer-safe boundary, OperationRun authorization, stale/failed/partial display, or evidence anchor scoping.
- **P2**: Non-critical productization debt where copy or lower-risk proof could be clearer without materially false claims.
- **P3**: Cleanup only, such as duplicate helper logic or minor non-customer-facing label polish.

## Candidate Gate Rules For Final Implementation Report

- **PASS**: no P0/P1 evidence/currentness proof gaps remain for high-risk customer/admin surfaces; customer-safe boundaries are proven; current vs released semantics are proven; targeted tests and browser proof pass; no new vocabulary was introduced.
- **PASS WITH CONDITIONS**: no P0 remains; remaining P1 items are explicitly deferred with safe justification; customer-facing claims are not overstated; critical current/released/customer-safe paths are proven.
- **FAIL**: any P0 remains; customer-safe output leaks internals; stale/failed/missing evidence is shown as current/verified; released output falsely claims live current state; unauthorized proof is accessible; browser proof cannot run for critical paths; fixes require unresolved product decisions beyond this spec.

## Follow-up Spec Candidates

- Spec 404 - Management Report PDF Staging Validation, only after Spec 403 passes or conditions are resolved.
- Governance artifact lifecycle/retention runtime.
- JSONB payload conversion and indexing for queryable evidence/report/audit payloads.
- Full browser/UX/runtime audit if later productization requires broad coverage.
- Provider readiness/onboarding productization if currentness closure exposes a provider setup friction gap.

## Assumptions

- The product remains pre-production, so false labels or fallback selectors can be cleanly corrected.
- Spec 402's `PASS` implementation report is accepted as clearing the authorization prerequisite for Spec 403.
- Existing evidence/currentness helpers from Specs 388 and 393 are repo truth until implementation inventory proves a gap.
- Browser support is available through the existing Pest browser setup; if not, the implementation report must record the exact blocker.

## Open Questions

- None block implementation preparation.
- If implementation finds that an existing surface lacks a product decision for customer-safe proof or stale-provider evidence handling, classify it in the report rather than inventing behavior.