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

Feature Specification: Spec 388 - Resolution Proof & Currentness Contract v1

Feature Branch: 388-resolution-proof-currentness-contract-v1 Created: 2026-06-19 Status: Draft / Ready for implementation planning Input: User-provided draft candidate "Spec 388 - Resolution Proof & Currentness Contract v1" from /Users/ahmeddarrazi/.codex/attachments/cc062aad-6a0b-4321-9b06-b7886c0c6e2a/pasted-text.txt.

Repo-Truth Adjustment

The user supplied a complete numbered draft for Spec 388 after Specs 386 and 387. Repo truth confirms:

• docs/product/spec-candidates.md still states that no safe automatic next-best-prep target remains in the active queue.
• This candidate is therefore treated as a direct manual promotion, not as an auto-selected backlog item.
• specs/386-review-publication-resolution-workflow-v1/ already introduced the review-publication resolution case, steps, readiness fingerprint, proof references, OperationRun links, audit, route, and workflow page.
• specs/387-review-publication-resolution-decision-ux-v1/ already hardened the existing workflow UI and contains completed task markers and screenshot/browser evidence.
• Current code already has App\Support\ReviewPublicationResolution\ReviewPublicationProofResolver, ReviewPublicationReadinessEvaluator, ReviewPublicationStepPlanner, ReviewPublicationResolutionService, ReviewPublicationResolutionStepAuthorizer, and the ReviewPublicationResolutionCase / ReviewPublicationResolutionStep models.

The supplied draft proposed a possibly reusable apps/platform/app/Support/ResolutionProof/ package and generic proof contract. This preparation narrows the approved V1:

• V1 MUST wire proof/currentness semantics into the existing Review Publication Resolution path first.
• V1 SHOULD extend or replace the existing primitive array-based review-publication proof resolver with typed, bounded proof evaluation objects only where this directly prevents stale, superseded, inaccessible, or misleading proof from driving the current workflow.
• V1 MUST NOT introduce a global proof adapter registry, workflow engine, generic resolver framework, or broad cross-domain proof package unless the spec/plan/tasks are updated first with a new proportionality defense and concrete repo evidence that a narrower review-publication implementation is insufficient.
• Restore, Provider Onboarding, Evidence/Baseline Readiness outside the current review path, Report Delivery, Governance Inbox, Cross-Tenant Promotion, and AI governance proof are follow-up candidates only.

Candidate Selection Gate

• Selected candidate: Spec 388 - Resolution Proof & Currentness Contract v1.
• Source: Direct user-provided candidate attachment with target path specs/388-resolution-proof-currentness-contract-v1/.
• Why selected: The active automatic queue is empty, but the user provided an explicit next numbered candidate. The candidate addresses a real trust gap left after Specs 386 and 387: old failed or stale proof can still influence readiness/resolution decisions unless proof currentness is normalized.
• Roadmap relationship: Supports R2 Evidence & Exception Workflows, customer-safe review consumption, Governance-of-Record auditability, OperationRun-backed proof, operator workflow compression, and the roadmap principle that current proof must not overstate readiness.
• Close alternatives deferred:
  • Management Report PDF runtime validation remains tied to Specs 378-380 and staging/Dokploy renderer validation.
  • Governance artifact lifecycle retention runtime remains manual promotion only.
  • Provider readiness onboarding productization remains optional manual promotion only.
  • Cross-domain indicator runtime follow-through remains a broader guardrail lane.
  • Restore proof hardening, Provider onboarding proof, Governance Inbox intake, and cross-tenant promotion proof are follow-up specs only.
• Completed-spec guardrail result:
  • specs/385-evidence-review-readiness/ has implementation close-out and is completed dependency context only.
  • specs/386-review-publication-resolution-workflow-v1/ contains completed task markers, validation/smoke signals, and existing runtime implementation; it is context only and is not rewritten by this preparation.
  • specs/387-review-publication-resolution-decision-ux-v1/ contains completed task markers and screenshot/browser evidence; it is context only and is not rewritten by this preparation.
  • Specs 350, 351, 367, and 381-384 are related guidance, OperationRun, and baseline context only.
• Smallest viable implementation slice: Normalize currentness/status/usability/visibility evaluation for Review Publication Resolution proof candidates already used by Spec 386: StoredReport-backed required reports, EvidenceSnapshot, EnvironmentReview/review composition, ReviewPack/current export, and relevant OperationRun references.
• Gate result: PASS. The candidate is directly supplied, unprepared, not completed, roadmap-aligned, bounded to one active workflow, and explicitly defers broader adapters.

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

• Problem: Review Publication Resolution has persistent steps and proof references, but the current resolver is too shallow to decide whether proof is still current, stale, superseded, accessible, or usable for the current readiness fingerprint.
• Today's failure: An old failed OperationRun can keep a step looking failed after newer artifact proof exists; an old successful run can look sufficient when the expected artifact is stale or missing; an EvidenceSnapshot, StoredReport, or ReviewPack can be shown as useful proof even when inputs have changed.
• User-visible improvement: Operators see an honest "current proof", "outdated proof", "superseded by newer result", "operation running", "action failed", "proof missing", or "not available with your permissions" state, and stale proof no longer blocks or completes a step incorrectly.
• Smallest enterprise-capable version: Add a bounded proof evaluation contract inside the existing Review Publication Resolution flow, update step planning and proof display to consume it, and add focused tests for current, stale, superseded, missing, running, failed, inaccessible, and safe-summary cases.
• Explicit non-goals: No generic workflow engine, no global proof adapter registry, no broad cross-domain proof service, no full Restore adapter, no full Provider onboarding adapter, no Governance Inbox intake, no customer-facing proof explorer, no raw OperationRun log viewer, no raw evidence/report payload viewer, no automatic backfill of old proof records, and no auto-publish.
• Permanent complexity imported: A small DTO/value-object family, proof status/currentness/usability/visibility enums or equivalent constants, fingerprint comparison helpers, updated review-publication proof resolver behavior, mapping tests, and selected UI/proof disclosure tests. No new source-of-truth table is approved by default.
• Why now: Specs 386 and 387 made the resolution workflow product-real. The next risk is trust: the workflow must not let old runs or stale artifacts create false confidence or false blockers as operators repeat the workflow.
• Why not local: A local label change cannot safely answer whether a proof reference is current for the present review, action, readiness fingerprint, actor, workspace, and environment. The decision affects step completion, blocked/running/failed display, audit metadata, and customer non-leakage.
• Approval class: Core Enterprise.
• Red flags triggered: New status axes, new DTOs, possible resolver layer, and future-facing wording. Defense: the scope is narrowed to one existing workflow; each state changes operator action or step completion; no registry/framework/persistence is approved; future adapters are explicitly deferred.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 1 | Gesamt: 10/12
• Decision: approve as a bounded Core Enterprise trust-hardening slice over existing Review Publication Resolution proof.

Problem Statement

TenantPilot increasingly uses readiness-driven review surfaces. A blocked Environment Review can now open a guided Review Publication Resolution case, but the workflow must decide whether proof objects are still valid for the current subject and action.

The workflow must answer:

• Is this proof for the same workspace and managed environment?
• Is it for the same Environment Review and resolution step action?
• Does it match the current readiness fingerprint or has the input state changed?
• Is a newer successful artifact available that supersedes an older failed run?
• Is a running OperationRun still relevant, or has current artifact proof replaced it?
• Is a successful OperationRun enough, or is the expected StoredReport, EvidenceSnapshot, EnvironmentReview output, or ReviewPack still missing?
• Can the current actor see the proof, or should the page show a safe limited state?
• Can this proof complete the step, or is it diagnostics only?

Without an explicit contract, each service or UI surface can drift. The result is false confidence, false blockers, and inconsistent customer/operator disclosure.

Business / Product Value

• Prevents stale proof from completing or blocking review-publication steps incorrectly.
• Makes the resolution workflow more trustworthy during repeated report/evidence/review/export cycles.
• Keeps OperationRun as execution truth while preserving artifact truth in StoredReports, EvidenceSnapshots, EnvironmentReviews, and ReviewPacks.
• Improves supportability by exposing safe normalized proof reasons without raw payloads or exception messages.
• Creates a narrow contract future proof-related specs can study without committing this V1 to a broad platform framework.

Primary Users / Operators

• MSP or workspace operator preparing an Environment Review for publication.
• Workspace manager verifying that blocked review publication is now ready or still needs action.
• Support/platform operator diagnosing why a resolution step remains blocked, failed, or waiting.
• Read-only users who may inspect safe state but must not execute steps or see unauthorized technical proof.
• Customer-facing review consumers who must not see internal proof mechanics.

Spec Scope Fields (mandatory)

• Scope: managed-environment-scoped Review Publication Resolution proof inside established workspace boundaries.
• Primary Routes:
  • existing Environment Review detail route(s);
  • existing Review Publication Resolution page from Spec 386;
  • existing Evidence Snapshot, Stored Report, Review Pack, OperationRun, and Environment Review destinations as proof or diagnostics links only;
  • Customer Review Workspace only for negative leakage regression.
• Data Ownership:
  • OperationRun remains execution truth.
  • StoredReport remains report truth.
  • EvidenceSnapshot remains evidence truth.
  • EnvironmentReview remains review-output truth.
  • ReviewPack remains export/package truth.
  • ReviewPublicationResolutionCase and ReviewPublicationResolutionStep remain workflow state and proof-reference holders.
  • New proof evaluation objects are derived contract output, not independent persisted truth.
• RBAC:
  • Workspace membership and managed-environment entitlement are required before proof is resolved or displayed.
  • Viewing a resolution page does not grant permission to view all proof detail or execute step actions.
  • Proof details must be hidden or summarized when the actor lacks operation/evidence/report/review-pack capability.
  • Non-member or non-entitled access remains deny-as-not-found; entitled users missing a capability receive safe limited/forbidden states according to existing policies.

For canonical-view specs:

• Default filter behavior when tenant-context is active: N/A. This spec does not add canonical collection filtering or revive retired /admin/t routes.
• Explicit entitlement checks preventing cross-tenant leakage: proof candidates must be resolved through workspace and managed-environment scoped queries/policies before they can become usable, linked, or visible.

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

Clarification: this spec changes state presentation and proof disclosure on an existing operator workflow page. Customer-facing scope is negative leakage regression only unless implementation discovers an existing overclaim and updates the spec before changing customer copy.

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

• Route/page/surface:
  • Review Publication Resolution page (ResolveReviewPublication);
  • technical proof and operation history disclosure inside that page;
  • Environment Review blocked/readiness state only where it consumes proof summary;
  • Customer Review Workspace leakage boundary checks only.
• Current or new page archetype: existing UI-101 Review Publication Resolution strategic workflow surface; existing UI-040 Environment Review detail; existing UI-006 Customer Review Workspace for negative no-leakage checks.
• Design depth: Strategic Surface for UI-101; Domain Pattern Surface for proof disclosure states; customer-safe regression only for UI-006.
• Repo-truth level: repo-verified through Specs 386 and 387.
• Existing pattern reused: existing Spec 386 page, native Filament actions/sections/badges, existing collapsed technical proof disclosure, existing OperationRun links/helpers, existing policy/UiEnforcement paths.
• New pattern required: no new route/archetype. A local or bounded proof-state presenter is allowed only if it maps normalized proof states to existing UI affordances and does not become a generic UI framework.
• Screenshot required: yes for proof states that materially change rendering, under specs/388-resolution-proof-currentness-contract-v1/artifacts/screenshots/; screenshot substitutions may be documented for states that are fully covered by Feature/Livewire tests but hard to produce in browser fixtures.
• Page audit required: update UI-101 only if visible structure/copy materially changes; otherwise record a no-new-route/no-new-archetype implementation note.
• Customer-safe review required: yes, negative leakage checks only.
• Dangerous-action review required: no new dangerous action is approved. Existing step actions remain governed by Spec 386/387 confirmation, authorization, audit, and tests.
• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md
  • 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 reachable UI surface impact
• No-impact rationale when applicable: N/A.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes, but V1 scope is one existing workflow.
• Interaction class(es): status messaging, proof disclosure, OperationRun links, artifact links, readiness labels, customer-safe disclosure, audit metadata.
• Systems touched:
  • App\Support\ReviewPublicationResolution\ReviewPublicationProofResolver
  • ReviewPublicationReadinessEvaluator
  • ReviewPublicationStepPlanner
  • ReviewPublicationResolutionService
  • ResolveReviewPublication
  • existing OperationRun reconciliation/actionability helpers as read-only context
  • existing EvidenceSnapshot, StoredReport, ReviewPack, and EnvironmentReview services as artifact truth providers
• Existing pattern(s) to extend: existing review-publication proof resolver and readiness fingerprint; existing OperationRun link/actionability behavior; existing collapsed technical proof/history UI.
• Shared contract / presenter / builder / renderer to reuse: existing ReviewPublicationProofResolver, ReviewPublicationReadinessEvaluator, OperationRunLinks/operation UX helpers where applicable, existing Filament badge/status rendering.
• Why the existing shared path is sufficient or insufficient: existing paths are sufficient for workflow ownership and UI placement, but insufficient because proof is currently only a shallow reference/status array rather than a normalized currentness/usability/visibility result.
• Allowed deviation and why: a bounded typed proof evaluation result is allowed because it prevents false step completion/blocking. A global registry, generic adapter system, or cross-domain proof framework is not allowed in V1.
• Consistency impact: step completion, current-step state, technical proof display, audit metadata, and customer-safe non-leakage must agree about the same proof evaluation.
• Review focus: stale/superseded proof must not dominate current proof; successful runs must not replace artifact proof; missing/inaccessible proof must not leak existence across workspace/environment boundaries.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: yes for proof classification and display; no new start/completion UX is approved.
• Shared OperationRun UX contract/layer reused: existing Spec 386/387 OperationRun links, start behavior, terminal notification path, and operation lifecycle service remain authoritative.
• Delegated start/completion UX behaviors: queued toast, run link, artifact link, browser event, dedupe messaging, terminal notification, and safe URL resolution stay delegated to existing OperationRun UX/lifecycle paths.
• Local surface-owned behavior that remains: classification of whether a run is current proof, superseded diagnostics, running inspection-only state, failed/not-usable state, and safe proof summary display.
• Queued DB-notification policy: unchanged.
• Terminal notification path: unchanged.
• Exception required?: none.

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: yes, platform-core proof vocabulary touches provider-backed report/evidence artifacts but does not change provider contracts.
• Boundary classification: platform-core for proof status/currentness/usability/visibility vocabulary; provider-owned for raw Microsoft/Graph/provider identifiers and payload details.
• Seams affected: readiness fingerprint inputs, report/evidence/review-pack artifact proof, OperationRun proof, safe summary metadata, proof labels.
• Neutral platform terms preserved or introduced: proof, currentness, usability, visibility, artifact, operation, readiness fingerprint, safe summary, subject, action.
• Provider-specific semantics retained and why: required report keys such as permission posture or Entra admin roles remain domain-specific report requirements where existing review readiness already uses them. They must not become raw provider payload or customer-facing debug language.
• Why this does not deepen provider coupling accidentally: proof evaluation consumes existing artifact records and safe identifiers; it does not add Graph calls, provider-specific payload readers, or provider-specific shared platform truth.
• Follow-up path: follow-up spec only for provider onboarding proof if current provider readiness surfaces show a concrete gap.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Review Publication Resolution proof disclosure	yes	Existing Filament page + existing Blade disclosure	status messaging, proof links, OperationRun links	page, proof detail, step state	no	no new route or navigation
Environment Review blocked/readiness state	yes, only if proof summary changes visible state	Existing Filament detail	review readiness status	detail	no	update only where current proof affects display
Customer Review Workspace leakage boundary	no positive UI feature	Existing customer-safe surface	customer disclosure	negative regression only	no	no internal proof mechanics may appear

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

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
Review Publication Resolution page	Primary Decision Surface	Operator decides whether to take the current preparation action, wait, inspect failure, or return to review	current proof state, next action, blocked/running/failed/outdated state	proof type/id, operation link, evaluated at, safe reason code	Primary because it owns blocked publication resolution	existing Spec 386 workflow	avoids cross-page interpretation of stale runs and artifacts
Environment Review detail	Secondary Context	Operator decides whether to start or resume resolution	publication blocked/ready state and one CTA	proof detail remains in resolution page	Secondary because it starts the flow but should not become proof explorer	review publication handoff	keeps proof detail out of review summary
Customer Review Workspace	Customer-safe consumption	Customer/auditor sees review availability only	safe availability state only	no internal proof detail	Not primary for resolution	customer-safe review consumption	prevents internal mechanics from creating confusion or leakage

Audience-Aware Disclosure (mandatory when operator-facing surfaces are changed)

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
Review Publication Resolution page	operator-MSP, manager, readonly inspector, support-platform	proof label, currentness/usability, next action or wait/fix message	operation/artifact references, safe reason code, evaluated at	raw provider payloads and raw report/evidence contents remain absent	execute current step, wait, inspect failure, or return to review	raw payloads, raw exception messages, unauthorized proof links	proof status is stated once; technical details explain but do not restate
Customer Review Workspace	customer-read-only, operator-MSP	preparing/available/unavailable style state only	none for customer mode	none	review/download only where already allowed	OperationRun, proof fingerprint, reason code, case/step details	no internal proof terms in customer output

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

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
Review Publication Resolution page	Workflow / Detail	Primary Decision workflow detail	resolve current blocker, wait, inspect failed proof, or return to review	existing page route	N/A	technical proof disclosure	existing cancel behavior only	existing Environment Review collection	existing resolution page	workspace and managed environment	Review publication resolution	current proof state and one next action	none
Environment Review detail	Detail / Handoff	Secondary context detail	resume resolution	existing detail route	N/A	proof detail on resolution page	existing review actions unchanged	existing Environment Review collection	existing detail route	workspace and managed environment	Environment review	publication readiness and CTA	none

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

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
Review Publication Resolution page	MSP/workspace operator	Decide whether current proof supports the step or another action is needed	workflow detail	Is this blocker resolved with current proof, or what must I do now?	proof label, currentness/usability, next action, no-auto-publish assurance	proof ID/type, operation link, safe reason, evaluated timestamp	execution outcome, artifact availability, currentness, usability, visibility	TenantPilot workflow plus source-owned step operations	current step action, wait/inspect, return to review	existing cancel and existing step actions only

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no. Proof evaluation is derived from existing domain truth and resolution step references.
• New persisted entity/table/artifact?: no by default. Existing review_publication_resolution_* records may store proof references/metadata already introduced by Spec 386. Any migration requires updating this spec/plan/tasks before implementation.
• New abstraction?: yes, a bounded proof evaluation DTO/value-object and resolver behavior are expected.
• New enum/state/reason family?: yes, proof status/currentness/usability/visibility states or equivalent enum families are expected.
• New cross-domain UI framework/taxonomy?: no. UI mapping remains local to Review Publication Resolution and existing surfaces.
• Current operator problem: operators can be misled by stale failed runs, stale artifacts, inaccessible proof, or successful runs without required artifacts.
• Existing structure is insufficient because: the current resolver returns only proof_type, proof_id, proof_status, and operation_run_id, which cannot distinguish current/stale/superseded/not accessible/inspection-only/usable proof.
• Narrowest correct implementation: evaluate only proof needed by the existing review-publication steps and reuse current readiness fingerprint/artifact records. Defer all non-review adapters.
• Ownership cost: maintain enum/DTO mappings, resolver tests, step-planner behavior, and UI label mapping for proof states.
• Alternative intentionally rejected: local string labels on existing proof arrays. This was rejected because it cannot safely govern step completion, actor visibility, and stale/superseded behavior.
• Release truth: current-release trust hardening for an already implemented workflow, not speculative future-release platform preparation.

Compatibility posture

This feature assumes the current pre-production posture. Backward compatibility shims, dual readers, historical proof backfill, and legacy aliases are out of scope unless the spec is updated with a concrete current-release need.

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

• Test purpose / classification: Unit for proof evaluation and fingerprint comparison; Feature for step planner/service integration, RBAC/scope, audit metadata, and customer leakage; Filament/Livewire for proof display/action states; Browser for representative proof-state rendering where useful.
• Validation lane(s): fast-feedback and confidence; browser for focused visual smoke; PostgreSQL only if implementation updates schema/constraints.
• Why this classification and these lanes are sufficient: the risk is deterministic proof classification and safe display over existing DB-backed workflow state, not new provider execution.
• New or expanded test families: new focused Spec 388 proof/currentness unit and feature families; optional focused browser file or extension of Spec 387 browser smoke.
• Fixture / helper cost impact: reuse Spec 386/387 helpers and existing apps/platform/tests/Pest.php review/evidence/report fixtures; do not add broad default workspace/provider setup.
• Heavy-family visibility / justification: none planned.
• Special surface test profile: workflow-detail surface with proof-state smoke; customer-safe negative leakage path.
• Standard-native relief or required special coverage: ordinary Feature/Filament coverage for most states; screenshot/browser smoke for representative current/stale/superseded/failed states only where fixtures make it safe.
• Reviewer handoff: verify no global registry/framework, no new persistence by default, no raw payload leakage, no Step completion from stale proof, no customer internal proof exposure, and no local OperationRun lifecycle rewrites.
• Budget / baseline / trend impact: no material trend impact expected; document-in-feature if browser fixture scope grows.
• Escalation needed: document-in-feature for contained proof-state exceptions; follow-up-spec for recurring cross-domain proof needs outside review publication.
• Active feature PR close-out entry: Proof Currentness / No Generic Registry / Smoke Coverage.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/ReviewPublicationResolution tests/Feature/EnvironmentReview/Spec388ReviewPublicationProofCurrentnessTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EnvironmentReview/Spec386ReviewPublicationResolutionWorkflowTest.php tests/Feature/EnvironmentReview/Spec387ReviewPublicationResolutionDecisionUxTest.php
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec388ReviewPublicationProofCurrentnessSmokeTest.php if browser coverage is implemented as a separate file
  • cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
  • git diff --check

User Scenarios & Testing (mandatory)

User Story 1 - Current Artifact Proof Supersedes Old Failed Runs (Priority: P1)

As an operator resolving blocked review publication, I need a newer successful artifact to supersede an older failed OperationRun so I am not blocked by obsolete failure state.

Why this priority: This is the highest false-blocker risk in the existing workflow.

Independent Test: Create or simulate an old failed report/evidence/export run, then create newer current artifact proof for the same step and verify the step is completed or actionable based on the artifact, not failed because of the old run.

Acceptance Scenarios:

1. Given a failed report-generation OperationRun and a newer current StoredReport required by the step, When the resolution case is refreshed, Then the failed run is marked/displayed as superseded or diagnostics-only and the StoredReport becomes current usable proof.
2. Given a failed review-pack OperationRun and a newer ready ReviewPack generated from the current review output, When the step planner evaluates export readiness, Then the old run does not keep the step failed.

---

User Story 2 - Stale or Missing Artifacts Cannot Complete Steps (Priority: P1)

As an operator, I need the workflow to reject stale or missing artifacts so a step does not look complete when the review input state changed.

Why this priority: This prevents false confidence and unsafe publication readiness.

Independent Test: Create stale StoredReport/EvidenceSnapshot/ReviewPack conditions by changing relevant input timestamps or fingerprints, then verify proof currentness is stale and usability is not usable.

Acceptance Scenarios:

1. Given an EvidenceSnapshot exists but required reports changed after it was collected, When proof is evaluated for evidence, Then currentness is stale and the collect-evidence step remains actionable.
2. Given a ReviewPack exists but the EnvironmentReview changed after pack generation, When export proof is evaluated, Then currentness is stale and the prepare-export step remains actionable.
3. Given a successful OperationRun exists but the expected artifact is missing, When the step is evaluated, Then the run is diagnostics-only or not usable and the step is not completed.

---

User Story 3 - Proof Visibility Respects RBAC and Customer Boundaries (Priority: P1)

As a readonly or customer-safe user, I need internal proof details hidden or summarized so TenantPilot does not leak operation, evidence, report, or fingerprint internals.

Why this priority: Proof trust cannot compromise workspace/tenant isolation or customer-safe disclosure.

Independent Test: Evaluate the same proof as an authorized operator, readonly actor, unauthorized workspace actor, and customer-safe viewer; verify visibility and links differ appropriately.

Acceptance Scenarios:

1. Given proof belongs to another workspace or managed environment, When it is evaluated for the current actor, Then it is not usable and not visible, preferably deny-as-not-found according to existing patterns.
2. Given a readonly actor can inspect the resolution page but lacks operation/evidence/report detail capability, When proof is displayed, Then the page shows safe limited proof state and no executable step action.
3. Given a customer-facing review surface is rendered, When internal proof exists, Then no OperationRun IDs, proof fingerprints, resolution step keys, raw reason codes, raw provider payloads, or report/evidence internals appear.

---

User Story 4 - Operators Can Inspect Safe Proof Reasons (Priority: P2)

As a support or operator user with permission, I need a safe proof summary that explains why proof is current, stale, superseded, running, failed, missing, inaccessible, or unknown without exposing raw payloads.

Why this priority: Safe reason codes reduce support effort and make the workflow reviewable.

Independent Test: Produce each proof state and verify the normalized reason code, evaluated timestamp, proof/artifact type, and safe summary appear only in authorized technical disclosure.

Acceptance Scenarios:

1. Given proof currentness cannot be determined safely, When proof is evaluated, Then usability is not usable and the operator sees "Proof cannot be verified" or equivalent safe copy.
2. Given proof is running, When the page renders, Then the current action is not duplicated and running proof is inspection-only.
3. Given proof is failed, When the page renders, Then raw exception messages are not shown and the normalized reason code is safe.

Functional Requirements

• FR-388-001: The system MUST produce a normalized proof evaluation for each Review Publication Resolution step that includes proof type, proof id, subject type/id, action key, status, currentness, usability, visibility, optional operation run id, normalized reason code, evaluated timestamp, proof timestamps, and safe summary.
• FR-388-002: The proof evaluation MUST distinguish these V1 status outcomes: missing, available, running, succeeded, failed, cancelled, unavailable, not accessible, and unknown. Renaming, narrowing, or merging these outcomes requires updating this spec, plan, and tasks before implementation continues.
• FR-388-003: The proof evaluation MUST distinguish at least these currentness outcomes: current, stale, superseded, not applicable, and unknown.
• FR-388-004: The proof evaluation MUST distinguish at least these usability outcomes: usable, usable with warning, not usable, and inspection only.
• FR-388-005: The proof evaluation MUST distinguish at least these visibility outcomes: operator visible, operator limited, customer safe summary only, and hidden.
• FR-388-006: Proof from another workspace MUST never be usable or visible for the current subject.
• FR-388-007: Proof from another managed environment MUST never be usable for environment-scoped resolution steps.
• FR-388-008: A successful OperationRun MUST NOT complete an artifact-backed step unless the expected artifact exists and is current.
• FR-388-009: A failed OperationRun MUST become superseded or inspection-only when newer successful current artifact proof exists for the same step requirement.
• FR-388-010: A running OperationRun MUST be current only when it belongs to the same scope, subject, action, and readiness fingerprint or source-owned operation context, and no newer completed proof supersedes it.
• FR-388-011: StoredReport proof for required reports MUST be usable only when it matches the required report key/dimension, workspace, managed environment, successful/evaluated state, and current readiness inputs.
• FR-388-012: Zero-result StoredReports MUST be usable proof when the report was successfully evaluated and matches the current requirement.
• FR-388-013: EvidenceSnapshot proof MUST be usable only when required dimensions are complete or explicitly accepted by product rules and the snapshot is current relative to required report changes.
• FR-388-014: EnvironmentReview/review-output proof MUST be usable only when review composition is current relative to evidence/report inputs and publication blockers are resolved.
• FR-388-015: ReviewPack proof MUST be usable only when generated from the current EnvironmentReview output and matching the intended disclosure/export profile.
• FR-388-016: Safe summaries MUST NOT contain raw provider payloads, Graph responses, tokens, secrets, full report content, full evidence content, raw exception messages, or customer-unsafe internal reason families.
• FR-388-017: Step planning MUST consume proof currentness/usability so stale, superseded, inaccessible, unknown, or diagnostics-only proof cannot complete a step.
• FR-388-018: Technical proof disclosure MUST show authorized operators safe currentness/usability/reason information without making technical proof more prominent than the next operator decision.
• FR-388-019: Customer-facing surfaces MUST use only customer-safe availability/preparing/unavailable style summary and MUST NOT display internal proof mechanics.
• FR-388-020: Audit metadata for proof-driven step transitions MUST include safe proof fields when existing audit patterns support it without noisy per-render audit events.
• FR-388-021: The implementation MUST keep proof evaluation derived from existing domain objects and MUST NOT create an independent proof source of truth by default.
• FR-388-022: Any schema migration, new persisted proof fields, or generic proof namespace requires updating this spec, plan, and tasks before implementation continues.

Non-Functional Requirements

• NFR-388-001 - Data minimization: Proof evaluation and audit metadata must include safe identifiers and normalized reason codes only.
• NFR-388-002 - No render-time provider calls: Proof evaluation must not call Microsoft Graph or any provider during UI render.
• NFR-388-003 - Deterministic evaluation: The same subject, action, actor capability, and readiness fingerprint must produce stable proof currentness outcomes until source domain truth changes.
• NFR-388-004 - Performance: Refreshing a resolution case should not add unbounded queries; relationship-backed proof should be eager-loaded or queried explicitly.
• NFR-388-005 - Pre-production lean posture: Do not add compatibility readers, aliases, historical backfills, or dual semantics for old proof data unless current release truth requires it.
• NFR-388-006 - Filament/Livewire version safety: Any UI work must remain Filament v5 / Livewire v4.0+ compliant and avoid Livewire v3 or Filament v3/v4 APIs.

Key Entities / Concepts

• Proof Evaluation: Derived result that describes whether a proof object can support a specific subject/action/readiness decision.
• Proof Reference: Existing pointer on a resolution step or derived candidate pointer to an artifact/operation.
• Readiness Fingerprint: Existing Spec 386 hash describing meaningful readiness inputs for a review-publication action.
• Proof Status: The proof object's own execution/artifact state.
• Proof Currentness: Whether proof applies to the current subject/action/readiness state.
• Proof Usability: Whether proof can complete or support the step.
• Proof Visibility: Whether the current actor/surface may show the proof or only a safe summary.
• Safe Summary: Sanitized proof explanation with no raw provider/report/evidence/secrets.

Edge Cases

• Newer current artifact proof supersedes an older failed OperationRun.
• Successful OperationRun exists but expected artifact is missing.
• OperationRun is still running but a newer completed artifact exists.
• StoredReport has zero rows but was successfully evaluated.
• EvidenceSnapshot exists but required reports changed after collection.
• ReviewPack exists but EnvironmentReview was refreshed after pack generation.
• Proof belongs to another workspace or managed environment.
• Actor can view resolution summary but lacks operation/evidence/report detail capability.
• Customer-facing surface renders while internal proof exists.
• Currentness cannot be safely determined.

Out of Scope

• Generic workflow engine or generic action-resolution case model.
• Global proof adapter registry.
• Broad Support/ResolutionProof platform package unless spec is updated first.
• Restore proof/currentness adapter.
• Provider onboarding proof/currentness adapter.
• Evidence/Baseline readiness proof outside the current Review Publication Resolution path.
• Report Delivery adapter.
• Governance Inbox proof intake.
• Cross-Tenant Promotion resolution proof.
• AI governance proof contract.
• Customer-facing proof explorer.
• Raw OperationRun log viewer.
• Raw EvidenceSnapshot, StoredReport, ReviewPack, Graph, or provider payload viewer.
• Automatic backfill of old proof records.
• New navigation, Resource, collection route, or global search surface for proof evaluations.

Success Criteria

• SC-388-001: In focused tests, every review-publication step uses normalized proof currentness/usability instead of raw proof status alone.
• SC-388-002: A newer current artifact supersedes an older failed run for at least required reports and review pack proof cases.
• SC-388-003: A successful OperationRun without expected artifact proof cannot complete an artifact-backed step.
• SC-388-004: Stale EvidenceSnapshot and stale ReviewPack proof keep their steps actionable instead of completed.
• SC-388-005: Unauthorized or cross-scope proof is not usable and does not expose proof existence outside existing entitlement rules.
• SC-388-006: Customer-facing output contains no internal proof mechanics or unsafe identifiers.
• SC-388-007: No new Graph/provider calls occur during proof evaluation or UI rendering.
• SC-388-008: The implementation remains bounded to Review Publication Resolution unless this spec is explicitly updated before implementation.

Assumptions

• Specs 386 and 387 are the runtime baseline and should not be rewritten as part of Spec 388.
• Existing review/evidence/report/pack records expose enough timestamps, fingerprints, statuses, and relationships to derive V1 currentness without a migration.
• Existing policies and capability helpers can determine proof visibility; if they cannot, the spec must be updated before adding new capability families.
• Existing audit infrastructure can record safe proof metadata on step transitions without per-render audit noise.

Open Questions

• None blocking implementation planning. If implementation proves current schema cannot store or derive needed currentness, update this spec/plan/tasks before adding migrations or persisted proof state.

Follow-up Spec Candidates

• Restore execution proof/currentness hardening.
• Provider onboarding readiness proof and setup-currentness productization.
• Governance Inbox proof intake and assigned resolution work items.
• Cross-domain proof/currentness contract after at least two additional real consumers prove shared variance.
• Report Delivery proof/currentness for management PDF/export delivery after runtime validation.