TenantAtlas/specs/385-evidence-review-readiness/spec.md

Feature Specification: Spec 385 - Evidence and Review Readiness Integration v1

Feature Branch: 385-evidence-review-readiness Created: 2026-06-17 Status: Implemented / Manual review close-out recorded Input: User-provided draft candidate "Spec 385 - Evidence & Review Readiness Integration v1" from /Users/ahmeddarrazi/.codex/attachments/ebb66191-6453-4e97-b245-eb040b3857d1/pasted-text.txt.

Repo-Truth Adjustment

The user supplied a complete numbered draft for Spec 385. Repo truth confirms the intended predecessor chain exists and is implemented or closed out:

• specs/381-provider-resource-identity-binding/
• specs/382-baseline-matching-canonicalization/
• specs/383-baseline-result-semantics/
• specs/384-baseline-subject-resolution-ui/

Those completed specs are dependency context only. This Spec 385 package does not modify their historical close-out notes, validation records, completed tasks, or smoke evidence.

Spec 385 narrows the draft to one implementation-ready runtime and presentation slice:

• consume Spec 383 structured baseline compare semantics and Spec 384 operator decisions in Evidence Snapshot completeness;
• make BaselineDriftPostureSource distinguish trusted no drift, trusted drift, unresolved identity, missing local evidence, missing provider resource, unsupported coverage, accepted limitations, exclusions, stale, and failed states;
• carry that baseline readiness into Environment Review readiness, publication blockers, and guidance;
• carry that baseline readiness into Review Pack output readiness, disclosure policy, customer-safe limitation summaries, and internal technical detail;
• keep customer-facing output safe and avoid false green or false red claims;
• avoid new matching, new compare semantics, new resolution UI, new report/PDF runtime work, new workflow engine, and legacy compatibility mappers.

Candidate Selection Gate

• Selected candidate: Spec 385 - Evidence and Review Readiness Integration v1.
• Source: Direct user-provided candidate attachment. It is the fifth item in the 381-385 baseline identity/readiness sequence.
• Why selected: Specs 381-384 are present and completed, so the next bounded value is to make Evidence, Environment Review, and Review Pack readiness consume the new compare and operator-decision truth instead of old incomplete heuristics.
• Roadmap relationship: Supports R2 Evidence & Exception Workflows, customer-safe review consumption, provider-neutral baseline drift trust, and governance output correctness. It does not reopen the active candidate queue, which currently has no automatic next-best-prep target.
• Close alternatives deferred:
  • Management Report PDF runtime validation remains tied to Specs 378-379 and is out of scope.
  • Governance artifact lifecycle retention runtime remains manual-promotion backlog, not an automatic prep target.
  • Provider readiness onboarding productization remains optional manual-promotion backlog.
  • Cross-domain indicator runtime follow-through remains a broader guardrail lane and must not be hidden inside this spec.
  • New resolution UI, matching, and compare semantics are already covered by Specs 382-384 and must not be reimplemented here.
• Completed-spec guardrail result:
  • Specs 381, 382, 383, and 384 all contain implementation close-out or validation signals and are treated as completed dependency context only.
  • Adjacent review/output specs such as specs/347-review-pack-output-contract-readiness-semantics/, specs/349-review-output-resolution-guidance/, specs/351-review-output-resolve-actions/, specs/357-report-profile-disclosure-policy/, and specs/379-management-report-pdf-runtime/ are context only and must not be rewritten by this prep.
  • No existing specs/385-* package or 385-* local/remote branch was found before the Spec Kit create script ran.
• Smallest viable implementation slice: Derive baseline evidence readiness from existing compare semantics and binding decisions, then feed the derived blocker/limitation/detail payload into existing Evidence Snapshot, Environment Review, and Review Pack readiness paths.
• Gate result: PASS. The candidate is directly provided by the user, is not already specced or completed, follows completed dependencies, aligns with roadmap trust/customer-readiness priorities, and is bounded enough for a later implementation loop.

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

• Problem: Evidence and review output can still imply a stronger or weaker baseline posture than the new compare and subject-resolution truth supports.
• Today's failure: A review or customer package can treat zero findings as verified no drift even when compare identity is unresolved, treat accepted limitations as success, treat exclusions as compliant, confuse missing local evidence with provider drift, or keep resolved provider defaults as false blockers.
• User-visible improvement: Operators and customer-facing reviewers see honest readiness: trusted findings can be published, accepted limitations are disclosed, unresolved governed blockers stop customer-safe claims, and specific guidance points to subject resolution, evidence refresh, or review limitation handling.
• Smallest enterprise-capable version: Add or extend a bounded baseline evidence readiness mapper, update baseline evidence collection, update existing review readiness/publication blocker logic, update existing Review Pack readiness/guidance/disclosure mapping, and add focused tests and smoke coverage for affected customer/operator surfaces.
• Explicit non-goals: No new provider identity foundation, no matching pipeline changes, no compare result taxonomy rebuild, no Baseline Subject Resolution UI changes beyond linking to the existing page, no generic workflow engine, no approval workflow, no broad Governance Inbox, no customer portal redesign, no Management Report/PDF runtime validation, no old payload compatibility readers, and no new durable decision table.
• Permanent complexity imported: A bounded mapper or extension to existing readiness helpers, derived readiness/detail payloads, possible derived readiness constants if existing ones are insufficient, tests across evidence/review/review-pack surfaces, and UI copy/guidance updates. No new primary table, route family, panel provider, provider client, or queue family is approved.
• Why now: Specs 381-384 made identity, matching, compare semantics, and operator decisions repo-real. Leaving Evidence and Review readiness on older heuristics preserves the false-green/false-red gap at the customer output boundary.
• Why not local: Patching only one output label would leave BaselineDriftPostureSource, Evidence Snapshot completeness, Environment Review blockers, Review Pack output readiness, disclosure policy, and customer-safe guidance able to disagree.
• Approval class: Core Enterprise.
• Red flags triggered: Derived readiness semantics, cross-surface output mapping, customer-safe presentation, and possible helper layer. Defense: this spec consumes existing truth, avoids new persistence, avoids new UI/workflow engines, reuses existing review-pack readiness/disclosure paths, and tests concrete false-green/false-red cases.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve as a narrowed Core Enterprise readiness-integration slice.

Problem Statement

TenantPilot can now produce structured baseline compare outcomes and operator decisions through Specs 383 and 384, but downstream Evidence and Review surfaces can still infer readiness from older, incomplete signals such as operation success, drift finding count, or generic evidence completeness.

That creates two customer-safety risks:

1. False green: output appears customer-ready or verified when identity, coverage, evidence, or compare trust is unresolved.
2. False red: output stays blocked when provider defaults, accepted limitations, exclusions, or trusted drift findings are validly classified and safe to disclose.

Spec 385 makes baseline evidence readiness the bridge between technical compare truth and customer/operator output truth.

Business / Product Value

• Prevents customer-facing no-drift claims unless identity, comparison, coverage, and required evidence are trusted.
• Lets operators publish with explicit limitations when a limitation is accepted or allowed by the report profile.
• Preserves trusted drift as a valid customer-visible finding rather than a publication failure by default.
• Makes publication blockers specific enough to act on: resolve subject identity, refresh evidence, run compare, accept/disclose limitation, or review unsupported scope.
• Keeps internal proof available without leaking raw provider internals into customer-safe output.

Primary Users / Operators

• MSP or tenant operator preparing an Environment Review or Review Pack for customer consumption.
• Workspace manager responsible for baseline governance output quality.
• Support/platform operator diagnosing why Evidence or Review output is blocked, limited, stale, internal-only, or ready.
• Customer/auditor consuming customer-safe review output where limitation wording must be clear and non-technical.

Spec Scope Fields (mandatory)

• Scope: tenant-owned evidence/review/output readiness inside established workspace and managed-environment boundaries.
• Primary Routes:
  • existing Evidence Snapshot resource/detail and Evidence Overview surfaces;
  • existing Environment Review resource/detail/register and Customer Review Workspace surfaces;
  • existing Review Pack resource/detail/download/rendered output readiness surfaces;
  • existing Baseline Subject Resolution page only as a linked next action, not as a changed decision UI.
• Data Ownership:
  • OperationRun baseline compare context/result remains execution/proof truth.
  • provider_resource_bindings remains durable operator decision truth.
  • EvidenceSnapshot and EvidenceSnapshotItem remain evidence artifact truth.
  • EnvironmentReview and EnvironmentReviewSection remain review composition truth.
  • ReviewPack and StoredReport remain output artifact truth.
  • Spec 385 readiness details are derived unless implementation proves a current-release source-of-truth need and updates this spec before adding persistence.
• RBAC: Existing workspace and managed-environment entitlement rules remain mandatory. Non-members receive deny-as-not-found. Entitled members missing view/export/publish capabilities receive the existing forbidden behavior. Customer-safe output must not reveal tenant/provider internals across workspace or environment boundaries.

For canonical-view specs:

• Default filter behavior when tenant-context is active: existing page-level environment_id filter behavior remains; no hidden /admin/t or retired tenant-panel context is revived.
• Explicit entitlement checks preventing cross-tenant leakage: all evidence, review, pack, stored report, operation, and subject-resolution links must resolve through existing scoped routes/policies before data is rendered.

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: no new table, form, route, modal, wizard, panel provider, or action is planned. Derived readiness reason/state values may be narrowly extended only if existing helpers cannot preserve the required stale/failed/blocker/limitation behavior; any public state-family expansion must update this spec/plan/tasks before implementation.

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

• Route/page/surface: Evidence Snapshot detail/Evidence Overview, Environment Review detail/register, Customer Review Workspace, Review Pack detail/download/rendered output, and baseline readiness/guidance sections within those existing surfaces.
• Current or new page archetype: existing evidence/review/output strategic and domain pattern surfaces; no new route archetype.
• Design depth: Strategic Surface for customer review/output readiness; Domain Pattern Surface for evidence and review detail readiness.
• Repo-truth level: repo-verified existing runtime surfaces.
• Existing pattern reused: existing ReviewPackOutputReadiness, ReviewPackOutputResolutionGuidance, ReportDisclosurePolicy, Environment Review readiness, Evidence Snapshot completeness, BadgeCatalog/badge domains, and existing customer-safe disclosure patterns.
• New pattern required: no new broad pattern. A bounded baseline readiness mapper or extension is allowed only to align existing surfaces.
• Screenshot required: yes. This spec changes customer/operator-visible readiness presentation, so implementation must include focused browser-smoke/screenshot evidence for the affected customer-safe review/output readiness unless the implementation updates this spec/plan first to prove no rendered presentation changed.
• Page audit required: implementation must update relevant existing page reports or record a checked no-new-route/no-archetype note, especially ui-006-customer-review-workspace.md, ui-011-reviews.md, ui-042-review-pack-detail.md, and ui-046-evidence-snapshot-detail.md where affected.
• Customer-safe review required: yes. This spec directly changes customer-ready, published-with-limitations, internal-only, and publication-blocked semantics.
• Dangerous-action review required: no new destructive/high-impact action is expected. Existing publish/export/download actions keep existing authorization and confirmation rules.
• 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.
• Interaction class(es): status messaging, readiness labels, publication blockers, action links, evidence/report viewers, customer-safe disclosure, internal technical detail, and badge/status presentation.
• Systems touched:
  • BaselineDriftPostureSource
  • EvidenceCompletenessEvaluator
  • Evidence Snapshot creation/detail rendering
  • EnvironmentReviewReadinessGate
  • EnvironmentReviewComposer
  • ReviewPackOutputReadiness
  • ReviewPackOutputResolutionGuidance
  • ReportDisclosurePolicy
  • Customer Review Workspace
  • Review Pack render/export/download support where readiness is displayed
  • existing Baseline Subject Resolution links only as next-action targets
• Existing pattern(s) to extend: existing evidence completeness states, existing review readiness blockers, existing review-pack readiness/guidance/disclosure helpers, existing badge catalog/renderers, existing OperationRun/source-proof link helpers.
• Shared contract / presenter / builder / renderer to reuse: prefer extending ReviewPackOutputReadiness, ReviewPackOutputResolutionGuidance, ReportDisclosurePolicy, EnvironmentReviewReadinessGate, EvidenceCompletenessEvaluator, and badge helpers before adding local mappings.
• Why the existing shared path is sufficient or insufficient: Existing paths already own review/output readiness and disclosure. They are insufficient today because baseline compare semantics and subject-resolution decisions are not yet first-class inputs to their readiness calculations.
• Allowed deviation and why: one bounded baseline readiness mapper or support helper is allowed if it prevents duplicate interpretation across Evidence, Review, and Review Pack. It must remain baseline-readiness-owned and must not become a generic workflow/report engine.
• Consistency impact: Evidence completeness, review blockers, review-pack state, limitation summaries, customer-safe disclosure, and internal diagnostics must describe the same baseline truth.
• Review focus: no parallel readiness dialect, no customer leakage of raw provider IDs/canonical keys/OperationRun JSON, no false no-drift, no generic task/workflow layer.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: yes for source-proof and next-action links only; no new operation start/completion semantics.
• Shared OperationRun UX contract/layer reused: existing OperationRun proof/link helpers and existing baseline compare start UX for any "run compare again" or "open operation" action.
• Delegated start/completion UX behaviors: queued toast, run link, browser event, dedupe messaging, and terminal notifications remain delegated to existing compare/evidence/review operation paths.
• Local surface-owned behavior that remains: readiness explanation, limitation summary, blocker guidance, and link selection.
• Queued DB-notification policy: no new queued DB notifications.
• Terminal notification path: unchanged.
• Exception required?: none.

Spec 385 may add source operation IDs and counts to derived evidence/readiness payloads, but it must not transition OperationRun.status or OperationRun.outcome outside existing services.

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: yes.
• Boundary classification: platform-core for readiness, blockers, limitation, evidence completeness, publication state, and customer-safe wording; provider-owned for raw provider identifiers and resource descriptors that remain proof/diagnostics only.
• Seams affected: baseline compare semantic payloads, provider resource binding decisions, evidence readiness details, review blockers, review-pack disclosure, guidance links, and operator/customer vocabulary.
• Neutral platform terms preserved or introduced: baseline subject, provider resource, governed subject, trusted compare, accepted limitation, excluded subject, missing evidence, missing provider resource, unsupported coverage, publication blocker, internal-only, customer-ready, published with limitations.
• Provider-specific semantics retained and why: provider key/type/id and canonical subject key may remain in internal technical details because they prove source identity. They must not appear in customer-safe output or primary operator summary unless already redacted/truncated and explicitly internal.
• Why this does not deepen provider coupling accidentally: readiness maps Spec 383 provider-neutral reasons and Spec 384 provider-resource decisions; it does not branch on Microsoft/Intune display labels, Graph endpoints, or raw provider payload shapes.
• Follow-up path: document-in-feature for contained profile/copy decisions; follow-up-spec for limitation expiry, approval workflow, external portal, or broader lifecycle retention.

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 Snapshot baseline completeness/readiness	yes	existing Filament resource/detail and badge patterns	evidence completeness, source proof, status messaging	detail, payload	no	Existing routes only
Environment Review readiness/publication blockers	yes	existing Filament resource/detail and review services	review readiness, blocker guidance, action links	detail, summary payload	no	Existing routes only
Customer Review Workspace readiness/guidance	yes	existing customer-safe review surface	customer-safe disclosure, next action, evidence basis	page, environment filter payload	no	Existing route only
Review Pack output readiness/disclosure	yes	existing resource/detail/rendered output helpers	output readiness, limitation summaries, report profile	detail, artifact payload	no	Existing routes/output artifacts only
Baseline Subject Resolution link target	no material surface change	existing Filament page	next-action link only	URL/query	no	Link target only; do not change Spec 384 UI unless implementation finds a broken link contract

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
Customer Review Workspace baseline readiness	Primary Decision Surface	Operator decides whether customer output is ready, limited, internal-only, or blocked	readiness state, top blocker/limitation, customer-safe summary, one next action	evidence snapshot, review sections, source compare run, subject resolution link	Primary because customer handoff happens here	follows review publication/handoff workflow	avoids reading raw compare run payloads before deciding
Environment Review readiness	Secondary Context	Operator decides whether a review can be published/exported	blockers, required section/evidence state, baseline readiness impact	evidence snapshot detail, operation proof, section details	Secondary because it governs review lifecycle	supports publish/export decision	turns vague blockers into specific actions
Evidence Snapshot detail	Tertiary Evidence / Diagnostics	Operator verifies the evidence basis behind readiness	baseline completeness state, counts, source run ID, measured/freshness timestamps	structured reason counts and source proof	Not primary because it proves the output decision	supports evidence investigation	keeps proof out of customer default output
Review Pack detail/rendered output	Secondary Context	Operator/customer verifies package state and limitations	customer-safe state, limitation summary, download qualification	internal technical appendix where profile allows	Secondary because the workspace/review owns the decision	supports artifact handoff	makes limitations explicit without duplicate status blocks

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-safe review consumer, operator-MSP, support-platform	state, reason, impact, limitation summary, qualified download/review action	counts by blocker/limitation/finding, source evidence, source compare run	raw provider IDs, canonical keys, raw OperationRun JSON	resolve blocker, review limitations, or download qualified pack	raw/provider/support detail collapsed or capability-gated	top state appears once; lower sections add proof only
Environment Review detail	operator-MSP, support-platform	publish/export readiness, specific blockers, refresh/resolve guidance	section details, evidence details, source operation links	raw section payloads/support diagnostics	resolve review blocker	raw details secondary	blockers share the same derived baseline readiness source
Review Pack output	customer-safe or internal profile reader	package readiness, allowed limitations, non-certification/evidence disclosure	internal appendix where allowed	provider IDs/canonical keys/raw JSON omitted from customer profile	review limitations or download package	internal technical details hidden from customer output	limitation wording aligns with readiness state

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
Customer Review Workspace	Utility / Workspace Decision	Read-only strategic review hub	resolve blocker, review limitations, or download qualified pack	explicit primary action in readiness block	N/A	secondary proof/action links in detail panels	none in scope	/admin/reviews/workspace	existing review/pack/evidence routes	workspace shell and environment filter	Customer review output	readiness, blocker/limitation, evidence basis	none
Environment Review detail	Utility / Review Detail	Lifecycle/detail surface	resolve publication blocker or export	existing detail page	current behavior only	proof/action links in sections	existing dangerous actions unchanged	existing Environment Review collection	existing Environment Review detail	workspace/environment context	Environment review	readiness/blockers	none
Evidence Snapshot detail	Utility / Evidence Detail	Evidence/proof surface	inspect evidence basis	existing detail page	current behavior only	source operation and diagnostics links	none in scope	existing Evidence Snapshot collection	existing Evidence Snapshot detail	workspace/environment context	Evidence snapshot	completeness and source proof	none
Review Pack detail/output	Utility / Artifact Detail	Output artifact proof	review limitations or download	existing detail/download/rendered output	current behavior only	secondary proof/download links	existing regenerate/expire actions out of scope	existing Review Pack collection	existing Review Pack detail	workspace/environment/artifact status	Review pack	output readiness and limitation summary	none

UI Action Matrix (mandatory when Filament is changed)

Spec 385 does not add a new Filament Resource, RelationManager, Page, route, navigation entry, modal, wizard, destructive action, or bulk action. It may modify readiness labels, badges, summaries, and guidance on existing Filament/Blade surfaces. The Action Surface Contract is satisfied when implementation preserves the existing inspect/open model, action placement, RBAC enforcement, confirmation behavior, and audit behavior for each affected surface.

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 Snapshot detail/readiness	apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php and pages	Existing actions only; no new Spec 385 header action planned	Existing resource inspect model unchanged	Existing row actions unchanged	Existing bulk behavior unchanged	Existing empty states unchanged	Existing detail actions unchanged	N/A	Existing audit behavior unchanged	Readiness presentation only; no action-surface exemption planned; no raw provider IDs, DB IDs, internal enum names, binding internals, or raw OperationRun JSON in customer-safe output
Environment Review detail/readiness	apps/platform/app/Filament/Resources/EnvironmentReviewResource.php and pages	Existing publish/export/review actions only	Existing resource inspect model unchanged	Existing row actions unchanged	Existing bulk behavior unchanged	Existing empty states unchanged	Existing detail actions unchanged	Existing create/edit behavior unchanged if untouched	Existing audit behavior unchanged	Spec 385 may change blocker/guidance text only; one dominant next action should remain resolve subjects, refresh evidence, rerun compare, or review limitations
Customer Review Workspace readiness	apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php and Blade view	Existing page actions only	N/A	N/A	N/A	Existing empty states unchanged unless readiness wording changes	Existing links/download affordances only	N/A	Existing audit/download behavior unchanged	One dominant next action must remain; no new mutation; customer-facing stale/failed/blocker/limitation explanations must remain safe and non-technical
Review Pack detail/output readiness	apps/platform/app/Filament/Resources/ReviewPackResource.php, ReviewPackService, and rendered output helpers	Existing generate/download/render actions only	Existing resource inspect model unchanged	Existing row actions unchanged	Existing bulk behavior unchanged	Existing empty states unchanged	Existing detail actions unchanged	N/A	Existing generate/download audit behavior unchanged	Existing dangerous/high-impact actions stay in their current guarded paths; stale/failed may map to existing output states with explicit reason/limitation codes unless a narrow helper extension is recorded before implementation

UI-FIL-001 remains satisfied by using existing Filament resources/pages and shared badge/disclosure helpers. Any implementation that adds a new visible action, changes action placement, adds bulk actions, or changes dangerous-action behavior must update this matrix, tasks, and the implementation close-out before merge.

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
Customer Review Workspace	MSP/workspace operator	decide whether customer output can be shared, shared with limitations, kept internal, or blocked	workspace review hub	Can I safely share this review output, and what blocks it?	readiness state, reason, limitation summary, evidence basis, one next action	source compare run, subject resolution counts, raw proof links	evidence completeness, baseline readiness, review publication, output readiness	none by default	resolve blocker, review limitations, download qualified pack	none in scope
Environment Review detail	MSP/workspace operator	decide whether review can publish/export	review detail	What must be fixed before this review is ready?	blockers, required dimensions, section/evidence state	source proof and section diagnostics	review lifecycle, evidence completeness, baseline readiness	existing review lifecycle actions only	resolve blocker/open evidence/export if allowed	existing actions unchanged
Review Pack output	MSP/customer-safe reader	consume package with correct limitation boundary	output artifact	What does this package prove, and what does it not prove?	customer-safe readiness, disclosure, limitation text	internal appendix where profile allows	artifact state, disclosure, evidence basis, baseline readiness	none	download/review package	none in scope

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no. Readiness is derived from existing compare, binding, evidence, review, and pack truth.
• New persisted entity/table/artifact?: no new primary table or artifact is approved. Existing evidence/review/pack payloads may carry derived detail if needed.
• New abstraction?: maybe one bounded baseline evidence readiness mapper or extension to existing helpers.
• New enum/state/reason family?: no new persisted family by default. Derived readiness constants may be added only if existing values cannot represent blocker/limitation/internal/customer-ready behavior without ambiguity.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: customer and operator readiness can misstate baseline posture even though upstream compare/decision truth is now structured.
• Existing structure is insufficient because: each downstream path can infer readiness differently from operation success, finding counts, section completeness, export availability, or old evidence state.
• Narrowest correct implementation: one shared baseline readiness derivation consumed by existing Evidence, Review, and Review Pack helpers, with presentation using existing UI/disclosure patterns.
• Ownership cost: mapper/helper ownership, cross-surface tests, customer-safe copy review, and additional regression coverage for false-green/false-red cases.
• Alternative intentionally rejected: page-local label patches. They would leave Evidence, Review, Review Pack, and customer output semantics able to disagree.
• Release truth: current-release truth after completed Specs 381-384.

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility readers for old baseline compare payloads, old OperationRun context shapes, old reason codes, old display-name readiness interpretation, or old local/dev evidence/review/pack data are out of scope.

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

• Test purpose / classification: Unit for readiness mapping; Feature for evidence/review/review-pack integration; Filament/Livewire Feature for changed surfaces; Browser for customer/output smoke because this spec changes customer-facing readiness presentation.
• Validation lane(s): fast-feedback, confidence, browser; PostgreSQL only if migrations/indexes/constraints are introduced after spec update.
• Why this classification and these lanes are sufficient: The main risk is deterministic mapping and existing DB-backed presentation, with limited browser smoke for customer-safe output/readiness rendering.
• New or expanded test families: focused baseline readiness tests under existing evidence/review/review-pack families; no new heavy-governance family by default.
• Fixture / helper cost impact: reuse existing baseline compare, subject resolution, evidence snapshot, environment review, and review pack fixtures. Keep any new fixture local and explicit.
• Heavy-family visibility / justification: none expected.
• Special surface test profile: shared-detail-family for readiness/detail output; standard-native-filament relief for existing Filament resources unless layout/action hierarchy changes.
• Standard-native relief or required special coverage: use ordinary feature coverage for existing native surfaces; browser smoke is required for changed customer-facing readiness presentation.
• Reviewer handoff: verify lane fit, no hidden browser/heavy-governance expansion, no raw provider leakage, no old payload compatibility, and no false-green/false-red regressions.
• Budget / baseline / trend impact: none expected; document-in-feature if browser fixture setup becomes materially heavier.
• Escalation needed: document-in-feature for contained disclosure/profile decisions; follow-up-spec for limitation expiry, approval workflow, external portal, or lifecycle retention.
• Active feature PR close-out entry: Evidence and Review Readiness Integration.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Baselines tests/Unit/Evidence tests/Unit/Support/ReviewPacks
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Evidence/BaselineDriftPostureSourceTest.php tests/Feature/EnvironmentReview tests/Feature/ReviewPack
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/Spec347CustomerReviewWorkspaceOutputReadinessTest.php tests/Feature/Filament/Spec349CustomerReviewWorkspaceOutputGuidanceTest.php
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec347ReviewPackOutputReadinessSmokeTest.php or a new focused Spec 385 browser smoke covering changed customer-facing readiness rendering.
  • cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
  • git diff --check

User Scenarios & Testing (mandatory)

User Story 1 - Evidence reflects trusted baseline posture (Priority: P1)

As an MSP operator, I need Evidence Snapshot baseline completeness to distinguish trusted no drift, trusted drift, blockers, limitations, missing evidence, stale data, and failed compare, so review output does not rely on raw finding count alone.

Why this priority: Evidence is the source basis for downstream review and pack readiness. If it is wrong, every customer-facing output can be wrong.

Independent Test: Generate or evaluate baseline evidence from structured compare semantics and active subject-resolution decisions, then assert the evidence item state, summary payload, and fingerprint payload classify blockers and limitations correctly.

Acceptance Scenarios:

1. Given a completed trusted baseline compare with resolved identity and no drift, When baseline evidence is collected, Then the evidence dimension is complete and records verified no-drift counts.
2. Given a completed trusted baseline compare with drift findings, When baseline evidence is collected, Then the evidence dimension is complete with findings and does not become missing or publication-blocked solely because drift exists.
3. Given unresolved identity in required governed scope, When baseline evidence is collected, Then the evidence dimension is partial/action-required or blocked according to existing state shape and records a subject-resolution next action.
4. Given missing local evidence, When baseline evidence is collected, Then the evidence dimension records missing evidence and does not describe it as provider drift.
5. Given accepted limitations or excluded non-governed subjects, When baseline evidence is collected, Then they are not counted as verified no drift or compliant pass.

---

User Story 2 - Review readiness blocks and limitations are precise (Priority: P1)

As an operator preparing a review, I need Environment Review readiness to turn baseline evidence blockers into actionable publication guidance, so I know whether to resolve identity, refresh evidence, accept/disclose a limitation, or proceed with findings.

Why this priority: Review publish/export decisions are where false-ready claims become customer risk.

Independent Test: Compose or evaluate an Environment Review with baseline evidence detail payloads for blocker, limitation, trusted finding, and clean cases, then assert review status, blockers, section completeness, and guidance.

Acceptance Scenarios:

1. Given unresolved required baseline identity remains, When review readiness is evaluated, Then publication is blocked with guidance to open Baseline Subject Resolution.
2. Given accepted limitations are allowed by profile/disclosure policy, When review readiness is evaluated, Then the review can be published with limitations instead of falsely reporting verified no drift.
3. Given trusted drift findings exist with complete evidence, When review readiness is evaluated, Then drift is reported as a finding and does not block publication by itself.
4. Given required evidence is missing or compare failed, When review readiness is evaluated, Then the review is blocked or internal-only with a specific refresh/rerun action.

---

User Story 3 - Review Pack output is customer-safe and limitation-aware (Priority: P1)

As an operator or customer-safe reviewer, I need Review Pack readiness and rendered output to explain what is customer-ready, limited, internal-only, or blocked without exposing raw provider internals, so the package can be shared safely.

Why this priority: Review Pack output is the customer handoff boundary and must not overstate assurance or leak internal proof.

Independent Test: Build Review Pack readiness from reviews containing baseline blockers/limitations and assert readiness state, limitation summaries, disclosure policy output, and hidden raw technical detail.

Acceptance Scenarios:

1. Given no blockers and complete required evidence, When Review Pack readiness is derived, Then it is customer-safe ready.
2. Given accepted/customer-disclosable limitations exist and no required blocker remains, When Review Pack readiness is derived, Then it is published with limitations and includes customer-safe limitation wording.
3. Given unresolved required identity or missing required evidence remains, When Review Pack readiness is derived, Then publication is blocked or export not ready with one dominant next action.
4. Given internal-only technical details exist, When customer-safe output is rendered, Then raw provider IDs, canonical subject keys, binding internals, internal enum names, and OperationRun JSON are absent.

---

User Story 4 - Internal proof remains useful without customer leakage (Priority: P2)

As a support/platform operator, I need internal technical detail to retain source run, evidence, compare, and decision counts, so I can diagnose readiness without exposing those details to customer-safe output.

Why this priority: Support diagnosis remains necessary, but it must not pollute customer-ready surfaces.

Independent Test: Evaluate internal profile/readiness output and customer-safe profile output from the same evidence state, then assert internal profile includes safe technical counts while customer-safe profile omits raw identifiers.

Acceptance Scenarios:

1. Given the internal profile is selected, When readiness details are rendered, Then source operation IDs, snapshot IDs, reason counts, and diagnostics are available according to existing profile rules.
2. Given the customer-safe profile is selected, When readiness details are rendered, Then only customer-safe limitation summaries and required next actions are visible.

Functional Requirements (mandatory)

• FR-385-001: Baseline evidence readiness MUST consume Spec 383 structured compare semantics instead of relying only on drift finding count or OperationRun success.
• FR-385-002: Baseline evidence readiness MUST honor active operator decisions from provider_resource_bindings, including bindings, accepted limitations, exclusions, unsupported coverage, and revocations.
• FR-385-003: Unresolved identity in required governed scope MUST block customer-ready claims.
• FR-385-004: Missing local evidence MUST be classified separately from missing provider resource and drift.
• FR-385-005: Accepted limitations MUST remain limitations and MUST NOT be treated as verified no drift.
• FR-385-006: Excluded non-governed subjects MUST be excluded from governed claims and MUST NOT be counted as compliant/no-drift.
• FR-385-007: Unsupported or inventory-only coverage MUST be represented as limitation or blocker according to report profile/disclosure policy and required-scope rules.
• FR-385-008: Zero drift findings MUST NOT be considered complete unless compare completed with trusted identity and required comparable subjects or accepted/excluded outcomes.
• FR-385-009: Trusted drift findings MUST be allowed in customer-ready output with findings when evidence and identity are trusted and profile rules allow disclosure.
• FR-385-010: Review readiness MUST include precise blocker and limitation guidance derived from baseline evidence details.
• FR-385-011: Review Pack readiness MUST distinguish customer-ready, published-with-limitations, internal-only, publication-blocked/export-not-ready, stale, and failed output behavior using existing readiness states plus explicit primary reason/limitation codes by default; narrowly extended readiness helpers/constants are allowed only if the existing output contract cannot preserve distinct operator/customer consequences and this spec/plan/tasks are updated first.
• FR-385-012: Customer-safe output MUST use safe limitation wording and MUST NOT expose raw provider IDs, canonical subject keys, binding internals, internal enum names, database IDs, or raw OperationRun JSON.
• FR-385-013: Internal technical output MAY include source operation/snapshot IDs, reason counts, and technical diagnostics where existing profile/disclosure policy allows.
• FR-385-014: The implementation MUST NOT add legacy compare/evidence/review compatibility mappers or old OperationRun context readers.
• FR-385-015: The implementation MUST NOT introduce a generic workflow engine, approval engine, broad dashboard, or new resolution UI.
• FR-385-016: Any new readiness constants or helper abstractions MUST be justified in this spec/plan before implementation and must replace ambiguity rather than create duplicate truth.

Non-Functional Requirements

• NFR-385-001 - Customer Safety: Customer output must never imply verified posture where identity, trust, coverage, evidence, or compare result is unresolved.
• NFR-385-002 - Determinism: The same compare, binding, evidence, review, and profile inputs must produce the same readiness state and guidance.
• NFR-385-003 - Provider Agnosticism: Readiness language and primary output must remain provider-neutral.
• NFR-385-004 - Auditability: Readiness details must be traceable to source compare run, evidence snapshot, and operator decision where available.
• NFR-385-005 - No False Green: Accepted limitation, exclusion, unsupported coverage, inventory-only coverage, or missing evidence must not become verified no drift.
• NFR-385-006 - No False Red: Resolved provider built-ins/defaults/virtual resources and allowed limitations must not create false publication blockers.
• NFR-385-007 - Minimal UI Change: UI changes should be limited to existing readiness labels, badges, summaries, guidance, and proof disclosure needed to reflect new semantics.
• NFR-385-008 - No Legacy Compatibility: Historical/local/dev payload compatibility is not a product requirement.

Key Entities / Truth Sources

• Baseline compare semantic payload: Existing OperationRun/compare proof from Spec 383.
• Provider resource binding decision: Existing provider_resource_bindings durable decision truth from Specs 381/384.
• Baseline readiness detail: Derived payload that summarizes verified, drift, blocker, limitation, missing, stale, failed, excluded, and source proof counts.
• Evidence Snapshot item: Existing evidence artifact item that carries baseline completeness and summary/fingerprint payloads.
• Environment Review readiness: Existing review readiness and blocker calculation over composed sections and evidence.
• Review Pack output readiness: Existing derived output readiness/guidance/disclosure state over review, evidence, and pack truth.

Assumptions

• Specs 381-384 stay completed and are not modified by this implementation.
• Existing provider_resource_bindings fields and resolution modes are sufficient for V1 readiness decisions.
• Existing Review Pack profile/disclosure helpers are the preferred place to decide customer-safe versus internal-only limitation handling.
• Accepted limitations require profile/disclosure allowance before customer-facing publication.
• Unsupported required scope defaults to a blocker unless the limitation is accepted or the profile explicitly allows disclosure.
• Drift findings do not block publication by themselves when evidence/identity are trusted.
• Missing provider resource can be a trusted governance finding when identity is trusted; missing local evidence is an evidence limitation/blocker.
• Limitation expiry/renewal is out of scope and belongs to a later governance lifecycle spec if needed.

Out of Scope

• New baseline matching logic.
• New compare result semantics model beyond consumption of Spec 383.
• New provider identity foundation.
• New Baseline Subject Resolution UI or new decision actions.
• New generic workflow, task, or approval engine.
• Broad Governance Inbox changes.
• Customer portal redesign.
• Management Report/PDF runtime validation or renderer work.
• Legacy compatibility mapping for old compare/evidence/review payloads.
• Raw provider diagnostics in customer-safe output.
• New persistent readiness table or durable readiness entity.

Risks

• False green: mitigated with mapping tests proving limitations, exclusions, unsupported coverage, and missing evidence do not become verified no drift.
• False red: mitigated with tests proving trusted drift, resolved built-ins/defaults, and allowed limitations do not block publication unnecessarily.
• Customer leakage: mitigated with customer-safe output tests that reject provider IDs, canonical keys, binding internals, internal enum names, and OperationRun JSON.
• Scope creep into report/PDF/runtime: mitigated by keeping Management Report/PDF out of scope and using existing Review Pack readiness/disclosure paths only.
• Semantics duplication: mitigated by reusing or extending existing shared readiness helpers rather than adding page-local mappings.
• Fixture cost growth: mitigated by local explicit fixtures and no heavy-governance family by default.

Success Criteria (mandatory)

• Evidence Snapshot baseline readiness differentiates complete, complete-with-findings, blocked/action-required, limitation-only, missing, stale, and failed cases using existing or narrowly extended state shape.
• Environment Review blockers and guidance are specific and derived from the same baseline readiness detail.
• Review Pack readiness and customer-safe output correctly represent customer-ready, published-with-limitations, internal-only, and blocked/export-not-ready states.
• Customer-safe output contains no raw provider IDs, canonical subject keys, binding internals, internal enum names, database IDs, or raw OperationRun JSON.
• Tests cover false-green and false-red cases across Evidence, Review, and Review Pack surfaces.
• UI/productization coverage updates or no-new-route rationale are recorded for affected existing surfaces.

Implementation Close-Out

• Implementation status: Implemented for the bounded Spec 385 evidence/review/output readiness slice.
• Validation recorded: Focused Spec 385 unit, feature, Filament/Livewire, and browser coverage passed with 36 tests and 160 assertions. php vendor/bin/pint --dirty and git diff --check were also run successfully.
• Baseline readiness review: Manual review confirmed active provider_resource_bindings, accepted limitations, exclusions, unsupported coverage, and revoked decisions after the latest compare are included in derived baseline readiness.
• Customer-safe review: Manual review confirmed customer-safe Review Pack JSON/Markdown and customer-safe UI paths avoid ProviderResourceBinding diagnostics, raw Compare/OperationRun diagnostics, raw baseline state codes, internal database IDs, raw provider IDs, and canonical subject keys.
• Publication semantics: Publish blockers are created only for baseline readiness blockers. Accepted limitations remain visible as published-with-limitations/customer-ready-with-disclosed-limitations instead of becoming verified no-drift or hard blockers.
• Review Pack storage safety: Customer-safe and internal Review Packs for the same review include distinct pack IDs in their ZIP paths, so same-second generation does not overwrite either artifact.
• Filament/Livewire status: Livewire v4.0+ compliance is preserved; the project uses Livewire 4.1.4. No new Filament Resource, global-search surface, panel provider, destructive/high-impact action, modal, route, or asset was added.
• Deployment impact: No new environment variables, migrations, persisted readiness states/entities/enums, provider/Graph calls, scheduler entries, queue names, storage volumes, reverse proxy changes, or asset build steps were introduced. Normal code deploy plus queue worker restart remains sufficient.
• Residual risk: Additional regression coverage would be useful if product semantics later require "latest compare" to mean latest completed compare when a newer in-flight compare exists. Future non-baseline customer-safe payloads that include string-based provider identifiers should receive explicit redaction tests before release.

Open Questions

No open question blocks implementation preparation.

Implementation must verify exact existing profile/disclosure hooks and update this spec/plan before adding a new public state family, persisted readiness entity, new route, or new workflow abstraction.

Follow-Up Spec Candidates

• Limitation expiry/renewal and governance lifecycle handling.
• Customer portal/external consumption boundary, if product direction requires it.
• Broader cross-domain indicator runtime follow-through.
• Governance artifact lifecycle retention runtime.
• Report/PDF staging runtime validation follow-through under Specs 378-379.