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

Feature Specification: Spec 393 - Evidence Anchor Reconciliation v1

Feature Branch: feat/393-evidence-anchor-reconciliation-v1 Created: 2026-06-20 Status: Draft Type: Bugfix / correctness / trust boundary / productization Priority: P1 Runtime posture: Clean canonical replacement over existing evidence-link and evidence-selection behavior. No legacy compatibility, no fallback-to-latest behavior, no new proof surfaces, and no UI expansion. Input: User-provided Spec 393 draft plus repo truth from evidence/review/report/customer-output code and related completed specs.

Dependencies And Historical Context

Spec 393 is a clean-cut follow-up over existing evidence, review, and output productization work:

• Spec 361 - Report evidence reconciliation, completed artifact/reconciliation context.
• Spec 372 - Customer/auditor surface safety pass, completed customer-safe disclosure context.
• Spec 385 - Evidence and review readiness integration, completed readiness/evidence context.
• Spec 386 - Review publication resolution workflow, runtime context for review-publication blockers.
• Spec 387 - Review publication resolution decision UX, runtime context for review-publication decisions.
• Spec 388 - Resolution proof currentness contract, completed proof-currentness context.
• Spec 392 - Customer output gating and review pack navigation, completed customer-output gate and label context.

Repo-truth observations that shape this spec:

• EvidenceSnapshot already has workspace_id, managed_environment_id, status, completeness_state, summary, generated_at, expires_at, fingerprint, and an active-snapshot unique index.
• EnvironmentReview already stores evidence_snapshot_id, current_export_review_pack_id, status, published_at, and superseded_by_review_id.
• ReviewPack already stores evidence_snapshot_id, environment_review_id, file metadata, status, expiration, and summary payloads.
• StoredReport already has source review/review-pack fields for management-report PDF provenance.
• Current code contains multiple local evidence selectors and link builders, including EvidenceSnapshotResolver, EnvironmentReviewService::resolveLatestSnapshot(), EvidenceOverview, CustomerReviewWorkspace, EnvironmentReviewResource, ReviewPackResource, ReviewPublicationProofResolver, ArtifactTruthPresenter, OperationRunLinks, RelatedNavigationResolver, GovernanceDecisionRegisterBuilder, and management-report payload generation.
• Current EvidenceSnapshot::scopeCurrent() includes queued/generating/active snapshots. Spec 393 distinguishes that technical/current-process concept from product-facing CURRENT_SCOPE_EVIDENCE.

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

• Problem: Evidence links can look trustworthy while pointing to the wrong snapshot for the user's product context.
• Today's failure: Dashboard, review, customer workspace, report, or evidence overview code can select evidence through local relation traversal, latest-created/latest-generated heuristics, review-pack relations, or report metadata. That can expose partial, stale, superseded, wrong-scope, draft, or old review evidence as if it were current proof.
• User-visible improvement: A product-facing evidence label answers the correct question: current-state surfaces link to current valid evidence, released review surfaces reference release-bound evidence, and customer-safe surfaces avoid raw technical evidence links by default.
• Smallest enterprise-capable version: One canonical evidence anchor resolver/result contract, replacement of local selectors in the affected product surfaces, focused route/action label cleanup, and regression tests proving no partial/superseded/wrong-scope fallback.
• Explicit non-goals: No Evidence Snapshot page redesign, no Technical Annex buildout, no new evidence generation pipeline, no provider integration, no new report profile, no new review publication state, no new customer portal, no new dashboard/card/table, no baseline-readiness rebuild, and no compatibility shims.
• Permanent complexity imported: One derived resolver/result contract plus one non-persisted value object/constant vocabulary for anchor type and allowed UI state; focused Unit/Feature/Filament/Browser tests. No default new table, migration, persisted state, broad UI framework, persisted enum/status family, or new route family.
• Why now: Current customer-output/review/evidence flows are productized enough that wrong evidence anchors are a direct trust failure, not cosmetic drift.
• Why not local: The defect exists across dashboards, reviews, customer workspace, report provenance, and evidence overview. Page-local patches would keep parallel semantics and allow future wrong-anchor regressions.
• Approval class: Core Enterprise.
• Red flags triggered: New resolver abstraction, canonical anchor types, multiple surfaces, and trust-boundary semantics. Defense: this protects workspace/tenant isolation, auditability, customer-safe disclosure, and evidence truth across existing real consumers; it replaces duplicated selectors instead of adding another parallel layer.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve.

Candidate Source And Completed-Spec Guardrail

• Selected candidate: Evidence Anchor Reconciliation v1.
• Source location: User-provided Spec 393 draft in this conversation. Roadmap relationship is the R2 evidence/review/report trust lane in docs/product/roadmap.md; docs/product/spec-candidates.md has no auto-prep queue but allows explicit manual promotion.
• Completed-spec check:
  • No specs/393-* package existed before this preparation.
  • Specs 361, 372, 385, 388, and 392 contain completed-task, validation, smoke, or implementation-history signals and are read-only historical context.
  • Specs 386 and 387 provide runtime/review-publication context and must not be rewritten by this preparation.
• Close alternatives deferred:
  • Technical Annex pattern: deferred because Spec 393 only labels and gates existing technical evidence access.
  • Product Surface Contract Enforcement pass: deferred because this spec is evidence-anchor-specific.
  • Governance artifact lifecycle/retention runtime: separate lifecycle/retention gap.
  • Management Report PDF staging runtime validation: separate Spec 379 follow-through.
  • Customer portal/external workspace expansion: separate product decision.
• Smallest viable implementation slice: Existing product-facing evidence links/selectors only: dashboard/workspace/environment current evidence, Evidence Overview current anchor, Customer Review Workspace customer-safe evidence summary, Review Pack/Environment Review/Stored Report/released output evidence provenance, and internal technical evidence detail links.

Spec Scope Fields (mandatory)

• Scope: workspace canonical view plus environment-owned evidence/review/report artifact surfaces.
• Primary Routes / Surfaces:
  • /admin/reviews/workspace via App\Filament\Pages\Reviews\CustomerReviewWorkspace
  • Evidence overview via App\Filament\Pages\Monitoring\EvidenceOverview
  • App\Filament\Resources\EvidenceSnapshotResource
  • App\Filament\Resources\EnvironmentReviewResource
  • App\Filament\Resources\ReviewPackResource
  • App\Filament\Resources\StoredReportResource
  • Review Pack download/rendered report controllers where evidence provenance appears
  • Management Report PDF payload/provenance where evidence is included
  • Environment dashboard/workspace overview evidence CTAs where repo-real
• Data Ownership:
  • EvidenceSnapshot remains tenant-owned evidence artifact truth.
  • EnvironmentReview.evidence_snapshot_id remains review-bound/released evidence truth for that review.
  • ReviewPack.evidence_snapshot_id and ReviewPack.environment_review_id remain review-pack artifact provenance.
  • StoredReport.source_environment_review_id and source_review_pack_id remain report artifact provenance where present.
  • OperationRun remains execution/proof diagnostics, not evidence-anchor truth.
  • No new persisted truth is expected.
• RBAC:
  • Workspace membership and managed-environment entitlement are mandatory before any target route is returned.
  • Raw technical evidence links require existing evidence/detail permissions and internal/operator context.
  • Customer-safe viewers receive customer-safe summary state, not raw snapshot routes.
  • Non-member or wrong workspace/environment remains deny-as-not-found.
  • Member without capability receives no technical route and direct route access remains denied by policies/controllers.

For canonical-view specs:

• Default filter behavior when tenant-context is active: Workspace-wide surfaces remain workspace-owned with explicit environment_id filtering. This spec must not reintroduce hidden tenant context, /admin/t, remembered-environment authority, or legacy query aliases.
• Explicit entitlement checks preventing cross-tenant leakage: The resolver must scope by workspace and managed environment before choosing evidence, review, review-pack, or report targets. Wrong-scope records must not be returned as anchors.
• Workspace-wide/no-environment current anchor behavior: If no managed environment is supplied, the resolver must either return a non-link workspace summary state or select only from actor-authorized managed environments. It must never choose a tenant-owned target outside the actor's entitlement. Product-facing single-target current evidence links should prefer an explicit environment filter; workspace-wide summaries may expose per-environment anchors only after entitlement filtering.

Canonical Evidence Anchor Contract

The implementation must create or consolidate one canonical resolver with behavior equivalent to:

EvidenceAnchorResolver::currentForScope($workspace, ?$environment, ?User $actor)
EvidenceAnchorResolver::forReviewPackDraft($reviewPack, ?User $actor)
EvidenceAnchorResolver::forReviewPackRelease($reviewPack, ?User $actor)
EvidenceAnchorResolver::forCustomerWorkspace($reviewPackOrReview, ?User $actor)
EvidenceAnchorResolver::technicalDetail($evidenceSnapshot, ?User $actor)

Exact class/method names may differ if existing repo ownership points to a better domain namespace. The final product-facing decision must still be one canonical contract consumed by affected surfaces. currentForScope($workspace, null, $actor) must follow the workspace-wide/no-environment behavior above.

Each resolver result must expose structured, testable fields:

anchor_type
state
evidence_snapshot_id nullable
target_route nullable
is_current
is_release_bound
is_customer_safe
is_technical_only
is_partial
is_superseded
is_expired
can_link
can_view_technical_detail
primary_reason
blocking_reasons[]
display_label

Allowed product-facing states:

Ready
Needs attention
Blocked
Expired
Not configured
Unknown

Internal diagnostic states may exist in code, but default product UI must map them to the allowed vocabulary.

Canonical anchor types:

• CURRENT_SCOPE_EVIDENCE
• REVIEW_DRAFT_EVIDENCE
• REVIEW_RELEASED_EVIDENCE
• CUSTOMER_SAFE_EVIDENCE_SUMMARY
• TECHNICAL_EVIDENCE_DETAIL
• NO_VALID_EVIDENCE

Anchor Semantics

CURRENT_SCOPE_EVIDENCE

Used by dashboard, workspace, environment, evidence overview, current readiness, and operator current-state triage surfaces.

Must resolve only to evidence that is:

• correct workspace
• correct managed environment when an environment is in scope
• status = active
• completeness_state = complete
• not expired
• not superseded
• not archived/revoked if such state exists in repo truth
• not known partial, failed, missing, stale, queued, or generating
• deterministic newest valid current anchor for the exact scope

Current selection order must be explicit and tested:

1. Correct workspace and environment.
2. Active status.
3. Complete/current-state eligible evidence.
4. Not expired.
5. Not superseded/archived/revoked.
6. Most recent generated_at, falling back only to an explicitly documented timestamp if needed.
7. Deterministic tie-breaker by descending id.

Do not rely on implicit database ordering.

REVIEW_DRAFT_EVIDENCE

Used only in internal/operator draft review workflows. It may be incomplete or internal, but must be labelled as draft/internal and must not be exposed as customer-safe.

REVIEW_RELEASED_EVIDENCE

Used by published/released review output, review pack details, rendered reports, stored reports, management-report PDF provenance, and customer-safe released output.

Must resolve to the evidence bound to the released review or released review pack, not whatever current evidence is latest. New current evidence must not silently change a released review's evidence provenance.

CUSTOMER_SAFE_EVIDENCE_SUMMARY

Used by Customer Review Workspace and customer-safe outputs. It may show a compact evidence summary such as Evidence captured for this review or Evidence current at publication, but must not expose raw evidence snapshot links by default.

TECHNICAL_EVIDENCE_DETAIL

Used only behind internal/operator details, audit trail, technical annex, or system/admin surfaces. May link to raw evidence snapshots only when authorized and clearly labelled as internal/technical.

NO_VALID_EVIDENCE

Used when no valid evidence exists for the product context. The UI must show a non-link state and must not fall back to partial, superseded, expired, stale, wrong-scope, or arbitrary latest evidence.

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

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

• No UI surface impact
• 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
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

Navigation destination targets may change for existing actions/rows, but no new navigation entry, route family, or Filament panel path is expected. "New table/form/state" means derived result state vocabulary only; no new table or form is expected.

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

Route/page/surface	Archetype	Design depth	Repo-truth level	Existing pattern reused	Screenshot / audit need	Customer-safe review	Dangerous-action review
Workspace / Environment dashboard evidence CTA	Existing dashboard signal	Domain Pattern Surface	repo-verified by current app surfaces	existing dashboard/action payload patterns	Browser smoke if visible link changes	yes	no new dangerous action
Evidence Overview	Existing evidence monitoring context	Secondary Context / Evidence	repo-verified	current Filament page, EvidenceSnapshotResource links	Browser/Feature proof for current anchor	yes for default labels	no
Customer Review Workspace	Existing strategic customer review surface	Strategic Surface	repo-verified + historical browser-tested	Specs 342/372/392 hierarchy	Browser smoke required for no raw evidence link	yes	no new dangerous action
Environment Review detail	Existing review detail	Domain Pattern Surface	repo-verified	EnvironmentReviewResource evidence basis	Feature/Livewire proof; screenshot if material	yes	preserve existing actions
Review Pack detail/rendered report	Existing artifact detail/report	Domain Pattern Surface	repo-verified	ReviewPackResource, output gate, disclosure policy	Feature/HTTP proof; browser if customer path changes	yes	preserve existing actions
Stored Report / Management Report PDF provenance	Existing report artifact detail/output	Domain Pattern Surface	repo-verified	StoredReportResource, Spec 379 provenance	Feature proof if touched	yes for customer output	no
Evidence Snapshot detail	Technical/evidence detail	Tertiary Evidence / Diagnostics	repo-verified	EvidenceSnapshotResource	Browser/Feature only if labels/actions change	internal-only default	preserve existing actions

• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md (not expected: no new route/navigation entry; update only if implementation changes route reachability)
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md (not expected: no new archetype/count; document no-count-change if unchanged)
  • docs/ui-ux-enterprise-audit/page-reports/... when implementation materially changes reachable page behavior
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md (not expected: no new strategic surface category)
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md (not expected)
  • docs/ui-ux-enterprise-audit/unresolved-pages.md (not expected)
  • N/A - no reachable UI surface impact
• No-impact rationale when applicable: N/A.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes.
• Interaction class(es): evidence links, status messaging, dashboard CTAs, report/review evidence viewers, customer-safe disclosure, technical/audit detail links.
• Systems touched:
  • App\Services\Evidence\EvidenceSnapshotResolver
  • new or consolidated Evidence Anchor Resolver contract
  • App\Services\EnvironmentReviews\EnvironmentReviewService
  • App\Filament\Pages\Monitoring\EvidenceOverview
  • App\Filament\Pages\Reviews\CustomerReviewWorkspace
  • App\Filament\Resources\EnvironmentReviewResource
  • App\Filament\Resources\ReviewPackResource
  • App\Filament\Resources\StoredReportResource
  • App\Filament\Resources\EvidenceSnapshotResource
  • App\Support\ReviewPacks\ManagementReportPdfPayloadBuilder
  • App\Support\ReviewPublicationResolution\ReviewPublicationProofResolver
  • App\Support\Ui\GovernanceArtifactTruth\ArtifactTruthPresenter
  • App\Support\OperationRunLinks
  • App\Support\Navigation\RelatedNavigationResolver
  • App\Support\GovernanceDecisions\GovernanceDecisionRegisterBuilder
  • route/controller paths that output evidence provenance
• Existing pattern(s) to extend: existing evidence resolver, review/review-pack relations, Spec 392 customer output gate, existing policies/capabilities, existing BadgeRenderer/BadgeCatalog patterns, existing ArtifactTruthPresenter/GovernanceArtifactTruth paths, existing Filament resources/pages.
• Shared contract / presenter / builder / renderer to reuse: The final resolver should reuse current model relationships and existing authorization helpers. It should replace local selectors rather than coexisting with them. ArtifactTruthPresenter/GovernanceArtifactTruth may remain artifact-state presentation only, and any product-facing EvidenceSnapshot links they emit must consume resolver output or be classified technical/internal-only by the implementation inventory. OperationRunLinks, RelatedNavigationResolver, and GovernanceDecisionRegisterBuilder remain technical/related-navigation helpers unless a product-facing path consumes them, in which case they must not bypass the resolver.
• Why the existing shared path is sufficient or insufficient: EvidenceSnapshotResolver currently resolves review-pack required dimensions but does not express product anchor type, released-review stability, customer-safe summary, or technical-only link flags. Local UI selectors still choose evidence independently.
• Allowed deviation and why: One narrow Evidence Anchor Resolver/result contract is allowed because evidence anchors are security/audit/customer trust boundaries with multiple real consumers. It must not become a generic proof framework or report-readiness engine.
• Consistency impact: A label saying Current evidence must resolve current evidence; Review evidence must resolve review-bound/released evidence; View internal evidence details must be technical/internal and permission-protected.
• Review focus: Block local fallback queries, arbitrary latest ordering, customer raw evidence links, wrong-scope anchors, and compatibility shims.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: no new operation start/completion. Existing OperationRun proof links may remain only as technical/internal diagnostics.
• Shared OperationRun UX contract/layer reused: existing OperationRun link helpers where technical detail remains.
• Delegated start/completion UX behaviors: N/A.
• Local surface-owned behavior that remains: evidence-anchor labels and summary states only.
• Queued DB-notification policy: N/A.
• Terminal notification path: unchanged.
• Exception required?: none.

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: no new provider seam.
• Boundary classification: platform-core evidence/review/report trust boundary over provider-collected artifacts.
• Seams affected: evidence anchor selection, route labels, customer-safe evidence summaries, technical detail links.
• Neutral platform terms preserved or introduced: workspace, managed environment, evidence, review evidence, current evidence, customer-safe summary, technical detail, audit trail.
• Provider-specific semantics retained and why: Provider facts may remain inside existing evidence payloads and technical detail pages. Default product anchor labels must not use provider-specific source keys, detector names, or raw Graph terminology.
• Why this does not deepen provider coupling accidentally: No Graph contracts, provider credentials, provider connections, provider identifiers, or Microsoft-specific scopes are introduced.
• Follow-up path: none unless implementation finds provider-specific evidence leakage requiring a separate follow-up.

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
Dashboard/workspace/environment evidence CTA	yes	existing dashboard payload	dashboard signals, evidence links	page payload, route	no	replace or remove wrong link
Customer Review Workspace evidence summary	yes	existing Filament page plus Blade composition	customer-safe disclosure	page payload, route	no	no raw link by default
Review Pack / Environment Review evidence basis	yes	native Filament resources	artifact/report/evidence viewers	detail, route	no	released evidence only
Evidence Overview primary row/action targets	yes	existing Filament page	evidence monitoring and drill-down	row URL, page payload	no	current anchor only
Technical Evidence Detail link	yes when surfaced	EvidenceSnapshotResource	technical/audit detail	route, action label	no	internal/audit 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
Dashboard evidence CTA	Secondary Context Surface	Operator verifies whether current evidence supports current-state decisions	current evidence state and one truthful action or non-link	technical evidence detail only if internal	Not primary; it supports current-state triage	dashboard-to-evidence verification	removes stale-proof guessing
Customer Review Workspace	Primary Decision Surface	Customer/auditor/operator consumes released review context	customer-safe evidence summary, not raw link	internal audit/evidence only behind secondary action	Primary for customer-safe consumption	released-review handoff	removes internal proof leakage
Review Pack / Environment Review detail	Secondary Context / Artifact Surface	Operator/auditor verifies released review evidence provenance	review evidence state bound to release	raw evidence and operation proof secondary/internal	Secondary because it verifies one output/review	review-output verification	prevents current/released mixups
Evidence Snapshot detail	Tertiary Evidence / Diagnostics Surface	Internal user inspects raw evidence detail	technical evidence context	raw payloads and source dimensions	Tertiary by design	audit/support diagnostics	preserves depth without making it customer proof

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
Dashboard/current-state surfaces	operator-MSP	current evidence state, reason, one action	audit trail link if allowed	raw snapshot/source internals	view current evidence or resolve evidence issue	technical evidence detail	resolver state owns label
Customer Review Workspace	customer-read-only, operator-MSP, support where authorized	evidence captured/current at publication summary	secondary internal evidence detail for operators	raw evidence IDs, source keys, detector output, operation proof	review/download customer output or view audit trail	raw evidence snapshot link	summary only, no duplicate raw proof
Review Pack / report output	customer/auditor/operator	released review evidence summary/provenance	technical evidence detail secondary	renderer/storage/source internals	download/open output or review evidence state	raw payload/technical proof	release-bound anchor owns provenance

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
Dashboard evidence action	Dashboard Signal	Navigation/status action	inspect current evidence or resolve issue	explicit action	N/A	internal audit action secondary	none	existing dashboard	current evidence detail or no-link state	workspace/environment	Current evidence	validity and currentness	none
Customer Review Workspace evidence block	Utility / Review Workspace	Customer-safe summary	consume released review safely	no raw evidence route by default	N/A	audit/evidence detail secondary	existing actions unchanged	/admin/reviews/workspace	review/pack/report routes	workspace + environment filter	Review evidence	released/customer-safe summary	none
Review Pack evidence basis	Utility / Artifact Detail	Artifact proof/detail	verify release-bound evidence	detail field/action	current repo behavior	technical detail secondary	existing actions unchanged	review-pack index	review-pack detail	workspace/environment	Review evidence	release-bound evidence state	none
Evidence Overview row	List / Monitoring	Evidence overview	open current valid evidence or see no valid state	row URL only when resolver can link	existing row URL	technical detail label when applicable	none	evidence overview	evidence snapshot detail	workspace/environment	Evidence	current state validity	none

UI Action Matrix

Action label	Surface(s)	Destination / effect	Primary or secondary	Visible / enabled rule	Server-side enforcement	Destructive?
Current evidence	dashboard, workspace, evidence overview	current valid evidence for exact scope	primary when valid	only when CURRENT_SCOPE_EVIDENCE is Ready and can_link is true	resolver scope + EvidenceSnapshot policy	no
Evidence not ready / Evidence unavailable / Evidence needs attention	current-state surfaces	non-link state	primary state, no navigation	when resolver returns no valid current evidence	resolver only, no target route	no
Review evidence / Evidence captured for this review	review pack, released review, report provenance	released review evidence summary or release-bound evidence detail when internal	primary summary, link only in non-customer contexts	release-bound resolver result	resolver + review/report policies	no
View audit trail	customer workspace and review/report details where applicable	internal audit/review/evidence context	secondary	internal/operator actor with permission	existing policies and route checks	no
View internal evidence details	technical/internal action areas	raw EvidenceSnapshot detail	secondary/technical	TECHNICAL_EVIDENCE_DETAIL with permission	EvidenceSnapshot policy and workspace/environment scope	no

Forbidden default product labels:

• Evidence #<id>
• Open artifact
• Open evidence artifact
• Technical dimensions
• Detector output
• Source keys
• Operation proof

Those may appear only in technical annex/system/admin diagnostic contexts.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no.
• New persisted entity/table/artifact?: no by default.
• New abstraction?: yes, one derived Evidence Anchor Resolver/result contract.
• New enum/state/reason family?: yes, one derived non-persisted anchor type/state vocabulary; no persisted enum/status family.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: Operators and customer-facing surfaces can land on plausible but wrong evidence, undermining evidence as a trust object.
• Existing structure is insufficient because: Existing selectors answer local data questions, not product intent questions. They do not consistently distinguish current evidence, draft review evidence, released review evidence, customer-safe summaries, and technical evidence detail.
• Narrowest correct implementation: A derived resolver/result contract over existing records, consumed by existing product surfaces, with local fallback selectors removed.
• Ownership cost: Resolver/result code, focused tests, and a small set of UI label/action updates. No default database/schema ownership.
• Alternative intentionally rejected: Page-local query fixes, compatibility redirects, latest-by-generated-at fallback, raw evidence links hidden only by copy, or a broad technical annex/proof framework.
• Release truth: current-release trust/correctness.

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, old query ordering, route aliases, old translation keys, fixture expectations, and compatibility redirects are out of scope. When current behavior conflicts with Spec 393, Spec 393 wins.

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

• Test purpose / classification: Unit for resolver decisions; Feature/HTTP for routes/scope and report/review provenance; Filament/Livewire for action visibility/labels; Browser for customer workspace/dashboard/review/evidence smoke.
• Validation lane(s): fast-feedback, confidence, browser.
• Why this classification and these lanes are sufficient: Resolver correctness is pure/domain behavior; product surfaces and routes need Feature/Livewire proof; customer-safe leakage and CTA destination truth need browser smoke.
• New or expanded test families: Spec393EvidenceAnchorResolverTest, focused Feature/Filament tests, and one bounded Browser smoke.
• Fixture / helper cost impact: reuse existing review-output/evidence factories and browser fixture helpers. Build only minimal explicit fixtures for current/partial/superseded/released/wrong-scope evidence.
• Heavy-family visibility / justification: one bounded Browser smoke is explicit because this is a customer-facing trust boundary and includes UI leakage checks.
• Special surface test profile: customer-safe strategic review surface + evidence/artifact detail + dashboard signal.
• Standard-native relief or required special coverage: ordinary Feature/Filament coverage plus focused Browser smoke for key trust paths.
• Reviewer handoff: reviewers must verify no local fallback evidence selectors remain in affected product surfaces and no customer-safe page exposes raw evidence links by default.
• Budget / baseline / trend impact: no material expected beyond focused tests.
• Escalation needed: none unless implementation requires schema change or broad technical annex behavior.
• Active feature PR close-out entry: Guardrail / Smoke Coverage.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec393
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec393EvidenceAnchorReconciliationSmokeTest.php
  • targeted existing review/customer/evidence browser tests if still applicable
  • cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
  • git diff --check

User Scenarios & Testing (mandatory)

User Story 1 - Current Evidence Anchors Are Correct (Priority: P1)

As an operator using dashboard, workspace, environment, or evidence overview surfaces, I need evidence actions to point only to the current valid evidence for that exact workspace/environment, or show that no valid current evidence exists.

Why this priority: This blocks the most direct false-proof risk on current-state surfaces.

Independent Test: Create older partial/superseded evidence and newer valid current evidence for the same environment. The resolver and dashboard/evidence overview choose only the valid current evidence. With only partial/superseded evidence, no product-facing link appears.

Acceptance Scenarios:

1. Given a workspace/environment has superseded evidence and newer valid complete active evidence, When the current evidence anchor is resolved, Then the valid complete active evidence is selected.
2. Given a workspace/environment has only partial, expired, failed, stale, queued, generating, or superseded evidence, When the current evidence anchor is resolved, Then the result is not linkable and uses a needs-attention or no-valid-evidence state.
3. Given evidence exists in another workspace or environment, When the current evidence anchor is resolved, Then wrong-scope evidence is never returned.

User Story 2 - Released Review Evidence Remains Stable (Priority: P1)

As an operator or auditor viewing a released review, review pack, stored report, rendered report, or management report, I need evidence provenance to remain bound to the released review output and not silently follow newer current evidence.

Why this priority: Released customer output must be reproducible and auditable.

Independent Test: Release a review with evidence snapshot A, create newer current evidence B, then verify released review/report/pack provenance still references A while dashboard current evidence may reference B.

Acceptance Scenarios:

1. Given a review is released with evidence snapshot A, When newer current evidence B exists, Then released review output still resolves released review evidence A.
2. Given a review pack is bound to a released review, When its evidence anchor is resolved, Then it uses the review/pack-bound evidence and does not query arbitrary latest evidence.
3. Given released evidence cannot be resolved, When the product renders review output, Then it shows Evidence not configured, Evidence unavailable, or Review evidence needs attention instead of borrowing current evidence.

User Story 3 - Customer Workspace Is Customer-Safe By Default (Priority: P1)

As a customer reviewer or customer-facing operator, I need the Customer Review Workspace to show customer-safe evidence summary text without raw evidence snapshot links, internal IDs, operation proof, source keys, detector output, or technical dimensions by default.

Why this priority: Customer-safe output must not leak internal proof detail or invite customers into technical evidence objects.

Independent Test: Render Customer Review Workspace with released review evidence and assert only customer-safe summary text is default-visible; internal technical link is absent or secondary/gated for authorized internal users.

Acceptance Scenarios:

1. Given a released review has evidence, When a customer-safe viewer opens Customer Review Workspace, Then they see evidence summary text and no raw evidence snapshot link.
2. Given an internal operator has permission, When technical detail is available, Then any evidence detail action is secondary and labelled as audit/internal detail.
3. Given a customer/read-only viewer lacks technical permission, When the workspace renders, Then no internal evidence detail route is exposed.

User Story 4 - Technical Evidence Remains Available Only As Internal Detail (Priority: P2)

As an internal operator or support user, I need technical evidence detail to remain reachable for audit and diagnosis, but only through clearly labelled internal/audit paths with authorization.

Why this priority: The platform must preserve audit depth without making raw evidence default product proof.

Independent Test: Resolve a technical detail anchor for an authorized internal actor and an unauthorized actor. The authorized actor gets an internal route; the unauthorized actor gets no target route.

Acceptance Scenarios:

1. Given an authorized internal actor views a product surface, When a technical evidence action is present, Then it is labelled View audit trail or View internal evidence details.
2. Given an unauthorized actor, When a technical detail anchor is resolved, Then can_view_technical_detail is false and no target route is returned.

Functional Requirements

• FR-001: Dashboard, workspace, environment, and evidence overview current-evidence actions MUST use CURRENT_SCOPE_EVIDENCE.
• FR-002: Current-evidence anchors MUST NOT return superseded, partial, stale, failed, queued, generating, expired, wrong-tenant, wrong-workspace, wrong-environment, draft review-bound, or released-review evidence.
• FR-003: If no valid current evidence exists, product surfaces MUST show a non-link state such as Evidence not ready, Evidence unavailable, or Evidence needs attention.
• FR-004: Customer Review Workspace default view MUST NOT expose raw evidence snapshot links, evidence IDs, source keys, detector output, operation-run proof, fingerprints, or technical dimensions.
• FR-005: Customer Review Workspace MAY show only customer-safe evidence summary text by default.
• FR-006: Published/released review output MUST use REVIEW_RELEASED_EVIDENCE and remain stable after newer current evidence is created.
• FR-007: Draft/internal review flows MAY show draft evidence only when labelled as internal/draft and not customer-safe.
• FR-008: Raw Evidence Snapshot detail pages remain technical/internal and may be linked from product surfaces only through secondary internal/audit actions.
• FR-009: The resolver MUST enforce workspace and managed-environment scope before returning any evidence target.
• FR-010: The resolver MUST account for actor permission before returning a target route.
• FR-011: The resolver MUST return structured, inspectable fields sufficient for tests to assert selected snapshot, state, customer-safety, technical-only status, current/release-bound flags, and blocking reasons.
• FR-012: Current evidence selection MUST be deterministic and explicitly ordered.
• FR-013: Product-facing labels MUST be truthful by context and destination.
• FR-014: No local fallback selector that can choose old/latest/partial/superseded/wrong-scope evidence may remain in affected product surfaces.
• FR-015: This spec MUST reduce or preserve visible UI complexity and MUST NOT add new evidence cards, proof sections, readiness badges, operation-run links, or long tables.
• FR-016: Reports and management-report payloads MUST expose correct release-bound evidence provenance internally and only customer-safe provenance in customer-facing output.
• FR-017: Existing direct wrong-scope evidence routes MUST remain protected by authorization/scope checks.
• FR-018: No compatibility shim, legacy redirect, old translation key, old route alias, or old fixture expectation may preserve wrong-anchor behavior.

Non-Functional Requirements

• NFR-001: Resolver evaluation must be DB-only and must not call Graph/provider APIs during render.
• NFR-002: Resolver queries must eager-load or explicitly query relationships needed by affected UI paths to avoid avoidable N+1 behavior.
• NFR-003: Audit logs and UI copy must not include secrets, raw provider payloads, raw Graph errors, source keys, detector internals, or raw evidence payloads on customer-safe paths.
• NFR-004: Implementation must remain compatible with Filament v5 and Livewire v4.0+; no Filament v3/v4 or Livewire v3 APIs.
• NFR-005: No new asset registration is expected; if assets are unexpectedly registered, deployment must include cd apps/platform && php artisan filament:assets.

Edge Cases

• Multiple complete active snapshots share the same generated_at in a workspace-wide authorized selection set, or another repo-possible multi-record current selection set: choose deterministically by descending id. Same workspace/environment duplicate active snapshots are prevented by the existing active unique index.
• Complete active evidence exists for the workspace but not the selected environment: return no valid environment evidence.
• A released review points to evidence that later becomes superseded for current-state purposes: released review output still resolves the release-bound evidence and labels it as review evidence, not current evidence.
• A review pack exists without an environment review relation: do not infer released review evidence from latest current evidence.
• Evidence is active but expired: current resolver returns expired/non-link state.
• Evidence is active and complete but actor lacks technical permission: summary may be returned, target route must be null.
• Existing Evidence Snapshot detail remains accessible by direct authorized route but must not become a default customer proof path.

Out Of Scope

• Evidence Snapshot page redesign.
• Full Technical Annex.
• Product Surface Contract Enforcement pass.
• Evidence generation pipelines.
• Provider integrations or Graph contract changes.
• New report profiles.
• New review publication states.
• New customer portal functionality.
• New dashboard sections/cards.
• New readiness models or baseline readiness reconciliation.
• Schema changes unless implementation proves existing fields cannot represent the canonical anchor.
• Legacy compatibility behavior.

Acceptance Criteria

• AC-001: Dashboard/workspace/environment evidence actions resolve to current valid evidence and never partial/superseded evidence.
• AC-002: With no valid current evidence, no current-evidence link is shown.
• AC-003: Customer Review Workspace default view has no raw evidence snapshot link, evidence ID, source key, detector output, operation-run proof, or technical dimension.
• AC-004: Released review output references the evidence bound to the released review even after newer current evidence exists.
• AC-005: Draft/internal review-bound evidence is labelled internal/draft and is not customer-safe by default.
• AC-006: Partial evidence is not treated as current proof.
• AC-007: Superseded evidence is not selected as current evidence.
• AC-008: Wrong-scope evidence is never selected by the resolver.
• AC-009: Labels are truthful: current evidence opens current evidence, review evidence references review-bound/released evidence, and internal evidence detail requires permission.
• AC-010: Affected pages do not gain new evidence cards, proof sections, readiness badges, operation-run links, or long tables.
• AC-011: Deprecated wrong-anchor behavior is removed from code and tests.

Success Criteria

• 100% of affected product-facing evidence links use the canonical resolver/result contract.
• Focused Spec 393 resolver tests cover current, released, customer-safe, technical, no-valid, partial, superseded, expired, and wrong-scope scenarios.
• Customer Review Workspace browser/feature assertions show no raw evidence link by default.
• Released review evidence remains stable in tests after newer current evidence is created.
• git diff --check and Pint pass after implementation.
• Human product sanity check confirms labels are truthful and UI complexity is not increased.

Regression Risks

• Risk 1 - Existing tests encode wrong-anchor behavior: Update or remove tests that expect partial, superseded, stale, or arbitrary latest evidence as product proof. Do not weaken the resolver to keep those tests green.
• Risk 2 - Released review output follows current evidence: Add released-review regression coverage proving evidence snapshot A remains the review evidence after newer current evidence B exists.
• Risk 3 - Dashboard loses a familiar link when evidence is invalid: Treat this as correct behavior; show a concise non-link state instead of falling back to stale or partial evidence.
• Risk 4 - Customer workspace loses operator debug convenience: Preserve internal detail only through secondary internal/audit actions with permission, not default customer-safe UI.
• Risk 5 - Technical evidence is hidden too aggressively: Keep authorized Evidence Snapshot technical/detail paths available while preventing those paths from becoming default product proof.
• Risk 6 - Scope checks drift between surfaces: Centralize selection in the resolver and add wrong-workspace/environment tests so page-local shortcuts cannot reintroduce leakage.

Assumptions

• Existing environment_reviews.evidence_snapshot_id, review_packs.evidence_snapshot_id, environment_reviews.current_export_review_pack_id, and stored-report source fields are sufficient to model released-review evidence provenance.
• EvidenceSnapshotStatus::Active plus EvidenceCompletenessState::Complete and non-expired timestamps are sufficient for current product evidence unless implementation finds additional existing readiness truth that must be included.
• Customer-facing users are represented by existing auth/capability boundaries; no new customer portal role model is introduced by this spec.
• Existing EvidenceSnapshot direct routes and policies remain the technical detail access path.

Open Questions

No open question blocks preparation. If implementation proves that existing persisted fields cannot distinguish released review evidence from current evidence in a real affected path, stop and update spec.md and plan.md before adding schema.

Required Implementation Report

The later implementation report must include:

1. Files changed.
2. Resolver/API created or consolidated.
3. Old local evidence-selection paths removed or replaced.
4. Tests added/updated.
5. Browser flows run.
6. Evidence that current evidence and released review evidence are separated.
7. Evidence that Customer Review Workspace no longer exposes raw evidence by default.
8. Confirmation that no legacy fallback/compatibility shim was added.
9. Confirmation that visible UI complexity did not increase.
10. Remaining known unrelated failures, if any.