TenantAtlas/specs/308-decision-register-summary-review-pack/spec.md

Feature Specification: Decision Register Customer-Safe Summary & Review-Pack Inclusion

Feature Branch: 308-decision-register-summary-review-pack Created: 2026-05-15 Status: Ready for implementation Input: User description: "308 - Decision Register Customer-Safe Summary & Review-Pack Inclusion"

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

• Problem: The operator Decision Register is now repo-real through Specs 265, 306, and 307, and Review Pack / Customer Review Workspace delivery is repo-real through Specs 109, 258, 260, and 263. The remaining gap is that customer-safe review consumption does not yet clearly carry the Decision Register accountability story into released-review summaries and review-derived Review Packs.
• Today's failure: Operators can inspect decisions and proof internally, and review packs can include accepted-risk and governance-package content, but stakeholder-facing summaries can still miss the current decision-register framing: which governance decisions need customer awareness, why they matter, what evidence basis supports them, and what next action is expected without exposing raw operator diagnostics.
• User-visible improvement: A released customer review and its review-derived Review Pack include a calm customer-safe decision summary that explains accepted-risk / exception decision follow-through, uses existing governance-package truth, preserves redaction, and avoids raw OperationRun, payload, fingerprint, or internal reason-family detail.
• Smallest enterprise-capable version: Extend the existing Environment Review governance-package summary and review-derived Review Pack export path with one derived customer-safe decision-summary projection. Reuse existing EnvironmentReview.summary, existing Review Pack summary.json, existing executive-summary.md, existing customer workspace/review detail surfaces, and existing Decision Register truth. No new table, no new approval workflow, no new customer portal, no new operation lifecycle, and no new export subsystem.
• Explicit non-goals: No new governance_decisions table; no new ReviewPack status; no generic decision framework; no inline customer approval; no Decision Register redesign; no new Review Pack storage family; no raw evidence payload export; no OperationRun URLs in customer-safe exported content; no PSA/ticket handoff; no AI summary generation; no broad localization pass.
• Permanent complexity imported: One bounded customer-safe summary shape inside existing review/governance-package payloads, focused feature tests, and one bounded browser smoke update if UI copy changes. No new persisted entity, enum family, public service framework, route family, queue family, or asset bundle.
• Why now: docs/product/roadmap.md ranks "Decision Register customer-safe summary / review-pack inclusion" as the first current manual-promotion item. docs/product/implementation-ledger.md says Decision Register proof/run links are now repo-backed while customer-safe summary and review-pack inclusion remain separate follow-ups.
• Why not local: A one-off label on the Decision Register would not reach customer-facing review consumption or exported Review Packs. A broad review-pack rewrite would be too large. The narrow correct point is the existing review/governance-package composition and review-derived pack export path.
• Approval class: Workflow Compression
• Red flags triggered: Cross-surface review/export productization and customer-safe disclosure. Defense: the slice derives from existing truth, extends existing artifacts only, and explicitly forbids new persistence, new lifecycle states, and raw diagnostic leakage.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 12/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: canonical-view
• Primary Routes:
  • existing /admin/governance/decisions Decision Register page as operator context only
  • existing EnvironmentReviewResource view route for released-review detail
  • existing CustomerReviewWorkspace route for customer-safe review consumption
  • existing ReviewPackResource view and signed download route for review-derived pack delivery
• Data Ownership:
  • FindingException and FindingExceptionDecision remain the decision source of truth.
  • FindingExceptionEvidenceReference, EvidenceSnapshot, and StoredReport remain evidence/report truth.
  • EnvironmentReview.summary remains released-review summary truth.
  • ReviewPack.summary and the generated ZIP files remain review-pack artifact truth.
  • OperationRun remains execution truth and is not copied into customer-safe decision content beyond safe count/source statements already present in review summaries.
• RBAC:
  • Workspace membership remains the first boundary for customer review and review-pack surfaces.
  • Environment/managed-environment entitlement remains required before any released review or Review Pack is visible.
  • Existing review and review-pack capabilities remain authoritative: no new capability is introduced.
  • Non-members or out-of-scope workspace/environment actors get deny-as-not-found (404).
  • Members missing review or review-pack capability get existing 403 capability denial where policies already define it.

For canonical-view specs:

• Default filter behavior when tenant-context is active: Customer Review Workspace and released-review detail preserve existing managed-environment prefilter behavior. This feature does not change Decision Register default filters.
• Explicit entitlement checks preventing cross-tenant leakage: Decision summary entries are derived only from the same workspace and managed environment as the released review / review pack. Cross-workspace and cross-environment decision, proof, and operation records must not affect counts, summaries, links, or unavailable-state copy.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes.
• Interaction class(es): customer-safe review summaries, governance package summaries, review-pack export content, evidence/report disclosure, action links, and status messaging.
• Systems touched: EnvironmentReviewComposer, EnvironmentReviewSectionFactory, CustomerReviewWorkspace, EnvironmentReviewResource, ReviewPackService, GenerateReviewPackJob, ReviewPackResource, existing Review Pack download route, existing Decision Register builder/page as source context only, and focused review/review-pack tests.
• Existing pattern(s) to extend: existing governance_package payload in EnvironmentReview.summary, existing review-derived Review Pack contract auditor_ready_executive_export.v1, existing executive-summary.md, existing customer workspace package availability states, existing BADGE-001-backed status display.
• Shared contract / presenter / builder / renderer to reuse: Reuse existing review composition and review-pack export paths. Reuse BadgeRenderer / BadgeCatalog for status-like UI if UI display changes. Reuse existing resource URL helpers for review/pack navigation. Do not create a new decision-summary presenter framework unless implementation proves the current composer cannot safely host the projection.
• Why the existing shared path is sufficient or insufficient: Existing review/package paths already carry executive summary, accepted risks, governance decisions, evidence basis, and package metadata. They are sufficient for v1 if they get an explicit customer-safe Decision Register summary shape and tests. The operator Decision Register builder is not sufficient by itself because it intentionally exposes operator-only proof and OperationRun affordances.
• Allowed deviation and why: A small private helper inside the existing review composer or review-pack generation job is allowed to keep customer-safe copy bounded. A public reusable framework is not allowed in v1.
• Consistency impact: Decision register, Governance decisions requiring awareness, Accepted risks, Evidence basis, Next action, and Review pack wording must stay aligned across review detail, customer workspace, and review-pack export.
• Review focus: Block raw payload/fingerprint/internal reason export, fake customer links, duplicate lifecycle truth, second approval surfaces, and any new persistence or workflow engine.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: yes, indirectly and read-only. Existing review-derived Review Pack generation already creates an OperationRun; this feature must not create a new run type or local start UX. Customer-safe summaries must not expose OperationRun URLs or raw run diagnostics by default.
• Shared OperationRun UX contract/layer reused: Existing ReviewPackService, GenerateReviewPackJob, OperationRunService, and existing OperationRunLinks usage remain the only run paths.
• Delegated start/completion UX behaviors: Existing review-pack generation queue/toast/run behavior remains delegated to current Review Pack and OperationRun infrastructure. No new queued toast, browser event, DB notification, dedupe messaging, or terminal notification is introduced.
• Local surface-owned behavior that remains: Customer-safe summary may state that evidence was generated or that a review pack is available, but must not render raw run status, run identifiers, or operation links in customer/read-only default paths.
• Queued DB-notification policy: N/A - no new notification policy.
• Terminal notification path: Existing review-pack terminal notification behavior remains unchanged.
• Exception required?: none.

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: no new provider seam.
• Boundary classification: platform-core review/export summary over existing governance truth.
• Seams affected: Existing review and review-pack summary payloads; no Graph contract, provider connection, or provider dispatch seam changes.
• Neutral platform terms preserved or introduced: decision, governance decision, accepted risk, evidence basis, review, review pack, managed environment, workspace.
• Provider-specific semantics retained and why: Existing evidence and finding content may originate from Microsoft/Intune data because those records already own that truth. The customer-safe summary must not add Microsoft-specific platform-core language unless existing evidence titles already contain it.
• Why this does not deepen provider coupling accidentally: The feature derives from TenantPilot governance decision and review artifacts rather than Graph payloads or provider contracts.
• Follow-up path: none.

UI / Surface Guardrail Impact (mandatory)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Customer Review Workspace governance-package summary	yes	Existing Filament page / shared view primitives	customer-safe review consumption, package availability	page, table/detail context	no	Add bounded customer-safe decision summary only if current surface has a package summary location
Environment Review detail governance-package disclosure	yes	Native Filament resource/infolist	released-review detail, package export action	detail	no	Existing view remains the action owner; no new mutation action
Review Pack detail/export	yes	Native Filament resource plus existing ZIP export	review-pack artifact truth and signed download	detail, artifact content	no	Export content changes; no new asset or route
Decision Register page	no direct UI change expected	Existing native Filament page	operator-only context	none	no	Source context only; do not redesign register

Implementation intent: use existing Filament-native sections/infolists/table display and existing export files. Do not add local CSS, ad-hoc cards, custom badges, hover affordances, or new assets. Filament remains v5 with Livewire v4.1.4+.

Decision-First Surface Role (mandatory)

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	Primary customer-safe consumption surface	Customer/stakeholder understands which governance decisions require awareness	customer-safe decision count, short summary, evidence basis, next action wording	released-review detail and downloadable review pack	Primary for customer consumption because it avoids sending stakeholders to operator register pages	Follows released-review delivery, not internal queue work	Reduces operator translation before sharing review status
Environment Review detail	Secondary context	Operator/customer-safe reviewer inspects one released review before export	decision-summary section, package availability, export action	sections, evidence basis, audit context where allowed	Secondary because it deepens the chosen review and starts export	Keeps review lifecycle ownership on existing detail page	Prevents rebuilding summary from Decision Register rows
Review Pack export	Tertiary evidence / delivery artifact	Stakeholder consumes the exported summary offline	executive decision-awareness section and structured summary JSON	appendix files in ZIP	Delivery artifact, not an interactive decision surface	Carries the released-review truth into the customer artifact	Avoids separate manual deck or email summary
Decision Register page	Operator primary decision surface, unchanged	Operator decides internal follow-up	existing register row proof/link state	existing detail/proof/operation links	Not customer-facing in this slice	Remains internal action and proof surface	Avoids duplicating operator workflow in customer surfaces

Audience-Aware Disclosure (mandatory)

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Customer Review Workspace	customer-read-only, operator-MSP	decision summary, evidence-basis wording, readiness/follow-up state	review detail and existing diagnostics remain secondary	raw payloads, fingerprints, platform reason families, run identifiers hidden	Open review or Download review pack depending current context	raw evidence and operation details	Summary states customer impact once; detail/export add evidence rather than restating internal state
Environment Review detail	customer-read-only, operator-MSP	released-review decision summary and package availability	review sections, evidence/source context	low-level evidence and run detail stays secondary/capability-gated	Download governance package when ready	raw JSON/fingerprints/internal reason ownership	Review summary remains the source for exported pack
Review Pack export	customer-read-only	executive story, accepted risks, governance decisions requiring awareness, next actions, non-certification disclosure	structured appendix only	raw payloads, fingerprints, internal reason families, OperationRun URLs absent	read executive entrypoint first	raw/support diagnostics absent from default entrypoint	summary.json carries structured truth; executive-summary.md carries readable summary

UI/UX Surface Classification (mandatory)

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	List / Review Workspace	Customer-safe released-review list/detail handoff	Open review or download current pack	Existing row/detail handoff	current behavior preserved	package download remains contextual	none	existing customer workspace route	existing EnvironmentReview view route	workspace and managed-environment scope	Customer reviews	whether governance package and decision summary are available	none
Environment Review detail	Detail / Reviewable governance artifact	Released-review detail	Download governance package	Existing detail page	N/A	export action remains detail-owned	none	existing EnvironmentReview list/register	existing EnvironmentReview view	managed environment and review status	Environment review	decision summary, evidence basis, export readiness	none
Review Pack detail/export	Detail / Artifact delivery	Review-pack artifact	Download pack	Existing ReviewPack view/download	N/A	regenerate remains operator-only outside customer flow	existing expire/regenerate confirmation unchanged	existing ReviewPack list	existing ReviewPack view	managed environment, review link, status	Review pack	generated artifact truth and summary	none

Operator Surface Contract (mandatory)

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	Customer-safe reader / MSP operator	Understand released review and choose whether to open or download	Customer-safe review workspace	What does the latest released review mean for governance follow-up?	executive summary, decision-awareness count/summary, evidence-basis copy, package availability	raw evidence and run detail remain elsewhere	review status, completeness, package availability, decision-awareness state	none	Open review / Download review pack	none
Environment Review detail	MSP operator / customer-safe reviewer	Validate released-review summary and export package	Detail page	Is this review ready to share and what decisions require awareness?	decision summary, package availability, evidence basis, next action	sections, evidence source detail, audit context	review status, completeness, governance-package availability	TenantPilot artifact export only	Download governance package	none in this slice
Review Pack detail/export	MSP operator / customer-safe reader	Consume or deliver review-pack artifact	Artifact detail/export	What is included in this package and is it safe to share?	status, customer-safe summary, review link, evidence snapshot completeness	fingerprints and operation links hidden in customer flow	pack status, evidence completeness, review status	existing review-pack generation only	Download	existing regenerate/expire only, unchanged

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no. Decision truth remains FindingException / FindingExceptionDecision; review truth remains EnvironmentReview.summary; pack truth remains ReviewPack.summary and generated files.
• New persisted entity/table/artifact?: no new entity/table/artifact family. Existing review and review-pack artifacts receive derived customer-safe summary content.
• New abstraction?: no public framework. A private helper in the existing composer/job is allowed only if it keeps the derived summary readable and bounded.
• New enum/state/reason family?: no. Any customer-safe state labels are derived presentation strings from existing governance states.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: Operators need customer-ready decision accountability to travel with released reviews and review packs without manual translation.
• Existing structure is insufficient because: Current operator Decision Register and proof links are internal; current review-pack content has governance-package concepts but does not yet explicitly prove the customer-safe Decision Register follow-through requirement.
• Narrowest correct implementation: Extend existing governance-package summary and review-derived export content; add focused tests that prove safe inclusion and no raw diagnostic leakage.
• Ownership cost: A small payload contract inside existing review summary, focused review/review-pack tests, and one bounded smoke if rendered customer-safe UI changes.
• Alternative intentionally rejected: New customer decision portal, new decision persistence, new export file family, and generic decision-summary service were rejected as broader than current-release truth.
• Release truth: Current-release productization over existing governance-of-record truth, not future workflow-platform preparation.

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec. Existing review-pack ZIP consumers are internal/pre-production; additive structured summary keys are allowed, but the implementation should avoid breaking existing file names unless a test proves the changed contract.

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

• Test purpose / classification: Feature plus one bounded Browser smoke if rendered customer-review UI changes. Unit tests are optional only if implementation extracts non-trivial summary logic.
• Validation lane(s): confidence for focused Pest feature tests; browser only for existing CustomerReviewWorkspaceSmokeTest or equivalent bounded smoke.
• Why this classification and these lanes are sufficient: The behavior is primarily review composition, exported ZIP content, customer-safe rendering, RBAC boundaries, and redaction. Existing feature tests can verify payloads and export files without broad suite cost. One existing browser smoke is enough if UI rendering changes.
• New or expanded test families: expand existing tests/Feature/EnvironmentReview/*, tests/Feature/ReviewPack/*, and tests/Feature/Reviews/* families. Do not create a new heavy-governance family.
• Fixture / helper cost impact: moderate, feature-local. Tests need released reviews, evidence snapshots, risk-accepted findings / finding exceptions, review-derived packs, and customer workspace actors. Helpers must stay opt-in and not make workspace/environment setup heavier by default.
• Heavy-family visibility / justification: none beyond one bounded browser smoke when rendered UI changes.
• Special surface test profile: shared-detail-family plus standard-native-filament.
• Standard-native relief or required special coverage: Existing native Filament resources/pages should need ordinary feature assertions plus one smoke path. Custom export content must be verified by reading generated ZIP entries.
• Reviewer handoff: Reviewers must verify the customer-safe summary excludes raw JSON, fingerprints, internal reason ownership, platform reason families, OperationRun URLs, and cross-scope decision records.
• Budget / baseline / trend impact: low feature-local increase only.
• Escalation needed: none.
• Active feature PR close-out entry: Guardrail / Smoke Coverage.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php tests/Feature/EnvironmentReview/EnvironmentReviewCreationTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php tests/Feature/ReviewPack/ReviewPackResourceTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php if rendered customer workspace or review detail UI changes
  • cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
  • git diff --check

Summary

Prepare a narrow follow-up that carries Decision Register accountability into customer-safe review consumption and review-derived Review Packs.

The feature should make current governance decisions visible to stakeholders as a bounded summary, not as an operator workflow. It should answer:

• Which accepted-risk / exception decisions require customer awareness?
• Why does the decision matter in the released review?
• What evidence basis supports the statement?
• What next action should the customer or MSP understand?

It must not expose raw proof details, operation links, run diagnostics, internal reason families, or cross-tenant state in customer-safe defaults.

Scope Boundaries

In Scope

• customer-safe decision-summary content inside existing released-review governance-package summary
• review-derived Review Pack inclusion through existing summary.json and executive-summary.md
• customer workspace / review detail display only where existing package-summary surfaces already exist
• redaction behavior for include_pii=false
• RBAC and scope isolation for customer review and pack access
• focused tests proving content, omission, redaction, and no raw diagnostic leakage

Non-Goals

• new persisted decision table or projection store
• new customer approval workflow or customer-side mutation
• new Review Pack status, lifecycle, or retention behavior
• new OperationRun type, notification policy, or run-link surface
• broad Decision Register page redesign
• full customer-facing localization adoption
• AI-generated summaries
• generic governance artifact lifecycle runtime

Assumptions

• Existing Environment Review summary composition is the correct source for customer-safe released-review content.
• Existing Review Pack generation from an Environment Review is the correct export path for stakeholder packages.
• Existing governance_package.governance_decisions content is close to the target and should be extended or made explicit rather than replaced.
• Customer-safe summaries may omit proof links where exposing a direct link would leak operator-only context.
• The current product is pre-production, so additive payload-key changes do not require compatibility shims.

Risks

• Reusing operator Decision Register row data directly could leak proof URLs, OperationRun links, or internal state.
• Adding a new public summary service too early could violate proportionality and create another presentation layer.
• Review-pack inclusion could drift into a broad export redesign if it adds new files, statuses, or delivery workflows.
• Customer-safe wording could overstate compliance or certification if non-certification disclosure is not preserved.

Candidate Selection Rationale

• Selected candidate: 308 - Decision Register Customer-Safe Summary & Review-Pack Inclusion.
• Source locations:
  • explicit user request
  • docs/product/roadmap.md priority ranking item 1
  • docs/product/spec-candidates.md manual-promotion backlog for decision-register-review-pack-inclusion / decision-register-customer-safe-summary
  • docs/product/implementation-ledger.md open gap for Decision Register customer-safe/review-pack inclusion
• Why selected: The repo already proves the operator register and proof/run link polish. The highest-priority remaining productization gap is customer-safe consumption and review-pack inclusion, not another operator register pass.
• Why this is the smallest viable implementation slice: It reuses current review/governance-package and review-pack export infrastructure, adds only derived customer-safe content, and leaves all lifecycle actions and proof inspection on existing operator surfaces.
• Intentional narrowing from source candidate: This spec combines customer-safe summary and review-pack inclusion only for existing accepted-risk / exception decision truth. It does not add customer approvals, multi-family decision workflows, broad localization, artifact lifecycle runtime, or new packaging cadence.

Completed-Spec Guardrail Result

Related existing specs are context only and must not be rewritten:

• specs/265-decision-register-approval/ defines the operator register and is not a refresh target.
• specs/306-decision-register-reconciliation/ carries reconciliation evidence and validation summaries.
• specs/307-decision-register-evidence-operationrun-link-polish/ has completed task markers and browser-smoke close-out signals.
• specs/109-review-pack-export/, specs/258-customer-review-productization/, and specs/260-governance-service-packaging/ carry completed or validation/checklist signals and provide only implementation context.

Follow-up Candidates

• Customer-Facing Localization Adoption v1 for translated customer-safe labels and glossary discipline.
• Governance Artifact Lifecycle & Retention v1 for broader artifact hold/export/delete semantics.
• Governance Service Packaging v1 for repeatable MSP package cadence and stakeholder mapping.
• First governed AI runtime consumer for later AI-assisted review drafting only after governed runtime requirements are promoted.

User Scenarios & Testing (mandatory)

User Story 1 - See a customer-safe decision summary in released review consumption (Priority: P1)

As an MSP operator or customer-safe reader, I want the released review to summarize governance decisions requiring awareness so stakeholders understand accepted-risk follow-up without opening the internal Decision Register.

Why this priority: This is the visible productization gap. Without it, operators still manually translate internal decision-register truth into customer language.

Independent Test: Create a released Environment Review with accepted-risk / exception decision data, open customer-safe review surfaces, and verify the decision summary appears with customer-safe wording and no raw diagnostic detail.

Acceptance Scenarios:

1. Given a released review includes accepted-risk entries that require governance follow-up, When the customer-safe review surface renders, Then it shows a concise decision-awareness summary with count, impact, and next-action wording.
2. Given a released review has no governance decisions requiring customer awareness, When the surface renders, Then it shows a calm empty/none state and does not imply hidden risk.
3. Given a decision has proof or operation context internally, When the customer-safe summary renders, Then it does not expose raw proof URLs, OperationRun URLs, fingerprints, internal reason ownership, or platform reason families by default.

User Story 2 - Include the decision summary in review-derived Review Packs (Priority: P1)

As an MSP operator, I want generated review packs to include the customer-safe Decision Register summary so the exported package can be shared without a separate manual explanation.

Why this priority: Review Pack inclusion is the explicit roadmap follow-through and makes the feature useful outside the interactive UI.

Independent Test: Generate a review-derived Review Pack from a released review with governance decisions, inspect summary.json and executive-summary.md, and verify structured and readable decision-summary content is present and redacted correctly.

Acceptance Scenarios:

1. Given a review-derived pack is generated with decisions requiring awareness, When the ZIP is inspected, Then summary.json includes the structured customer-safe decision summary.
2. Given the same pack is inspected, When executive-summary.md is read, Then it includes a readable Governance decisions requiring awareness section that matches the structured summary.
3. Given include_pii=false, When the pack is generated, Then tenant names, actor names, owner labels, and other PII-bearing summary fields are redacted or omitted according to existing redaction behavior.

User Story 3 - Preserve security, scope, and lifecycle boundaries (Priority: P1)

As a platform owner, I need customer-safe decision summaries to preserve workspace/environment isolation, RBAC, auditability, and lifecycle ownership so a trust feature does not become a leak or a second workflow.

Why this priority: Customer-facing governance summaries are high-trust artifacts; leakage or duplicate lifecycle controls would be worse than omission.

Independent Test: Seed same-workspace and cross-workspace/environment decision data, generate reviews and packs, and verify only in-scope decision content appears while lifecycle actions remain on existing operator surfaces.

Acceptance Scenarios:

1. Given hidden environment decisions exist, When a visible environment review or pack is generated, Then hidden decisions do not affect counts, copy, or exported content.
2. Given a user lacks review-pack view capability, When they try to access a pack or download URL, Then existing 404/403 behavior remains unchanged.
3. Given the customer-safe summary renders, When actions are inspected, Then approve, reject, renew, revoke, and closure actions are not introduced on customer-safe surfaces.

Edge Cases

• A review has accepted-risk entries but no current exception decision.
• A decision was revoked or expired after the review evidence snapshot was captured.
• A review pack is generated from a partial or stale evidence basis.
• Multiple decisions reference the same finding or accepted risk.
• Decision proof exists internally but is not customer-safe to link.
• include_pii=false is set and owner labels or tenant names would otherwise appear.
• A review is published but no ready review pack exists yet.
• A generated pack is expired, blocked by entitlement/commercial lifecycle, or unavailable.
• Cross-workspace/environment decisions exist with similar titles or finding IDs.

Requirements (mandatory)

Functional Requirements

• FR-001: Released-review governance-package summaries MUST expose a customer-safe decision summary when in-scope accepted-risk / exception decisions require awareness.
• FR-002: The decision summary MUST include a total count, readable summary text, customer-safe entry titles, governance state or awareness reason, and one next-action statement where current review truth supports it.
• FR-003: Decision summary entries MUST derive from existing review/evidence/decision truth and MUST NOT create or persist a second decision source of truth.
• FR-004: Customer-safe summaries MUST distinguish "no decisions requiring awareness" from "decision data unavailable or incomplete" where current evidence completeness supports that distinction.
• FR-005: Review-derived Review Packs MUST include the decision summary in summary.json.
• FR-006: Review-derived Review Packs MUST include readable decision-awareness content in executive-summary.md.
• FR-007: Review Pack export MUST preserve the existing auditor_ready_executive_export.v1 contract unless the implementation records a bounded additive version note in the existing delivery metadata.
• FR-008: Customer-safe default surfaces and exported executive summaries MUST NOT expose raw JSON, source fingerprints, internal reason ownership, platform reason families, raw OperationRun IDs, OperationRun URLs, debug payloads, or provider payload dumps.
• FR-009: include_pii=false MUST redact or omit PII-bearing decision summary fields using existing Review Pack redaction behavior.
• FR-010: Customer-safe summary generation MUST be scoped to the released review's workspace and managed environment before counts and copy are derived.
• FR-011: The feature MUST NOT introduce customer-facing approval, rejection, renewal, revocation, closure, or escalation actions.
• FR-012: Existing Review Pack generation, download, expire, regenerate, entitlement, and commercial-lifecycle behavior MUST remain unchanged except for included summary content.

Non-Functional Requirements

• NFR-001: The implementation MUST reuse existing review and review-pack composition paths instead of adding a new export subsystem.
• NFR-002: The implementation MUST remain deterministic for the same released review and options.
• NFR-003: Generated summary content MUST be concise enough for first-read review consumption and must not turn exported markdown into a raw appendix.
• NFR-004: No new frontend assets are registered. Deployment filament:assets requirements remain unchanged.
• NFR-005: No database migration is expected. If implementation discovers a migration is necessary, stop and update the spec before continuing.

UX Requirements

• UX-001: Customer-safe decision content MUST be default-visible only at a summary level; diagnostics and raw evidence remain secondary or absent in customer paths.
• UX-002: The customer-safe summary MUST preserve one dominant next action per surface (Open review or Download review pack) and must not make operator-only links visually equal.
• UX-003: Any status-like display MUST use existing BADGE-001 badge rendering or plain supporting text; no ad-hoc color mapping or custom status UI.
• UX-004: Empty states MUST be truthful: no decisions, unavailable evidence, blocked pack, and expired pack are separate meanings.

RBAC / Security Requirements

• SEC-001: Existing workspace membership, managed-environment entitlement, and review/review-pack capabilities remain server-side authorization boundaries.
• SEC-002: Non-member or not-entitled workspace/environment access remains 404.
• SEC-003: Member-but-missing-capability behavior remains existing 403 where current policies define it.
• SEC-004: Customer-safe summaries MUST NOT leak hidden-environment existence through counts, empty-state wording, links, or exported content.

Auditability / Observability Requirements

• AUD-001: Existing review-open, review-pack generation, download, and export audit/telemetry semantics remain unchanged.
• AUD-002: No new audit action ID is required unless implementation introduces a new user-triggered mutation, which is out of scope.
• AUD-003: Review Pack generated artifacts remain traceable through existing ReviewPack, EnvironmentReview, EvidenceSnapshot, and OperationRun links.

Data / Truth-Source Requirements

• DATA-001: Decision truth remains FindingException and FindingExceptionDecision.
• DATA-002: Released-review summary truth remains EnvironmentReview.summary.
• DATA-003: Review-pack artifact truth remains ReviewPack.summary and the generated ZIP file.
• DATA-004: The customer-safe summary is a derived snapshot at review composition / pack generation time, not a live Decision Register view.

Acceptance Criteria

• AC-001: A released review with governance decisions requiring awareness exposes customer-safe summary content on the in-scope review/customer surface.
• AC-002: A released review with no decisions requiring awareness exposes a calm no-decision state.
• AC-003: A review-derived Review Pack ZIP includes matching structured and readable customer-safe decision summary content.
• AC-004: include_pii=false prevents tenant names and actor/owner labels from leaking into exported decision-summary content.
• AC-005: Customer-safe summaries contain no raw JSON, fingerprints, internal reason-family labels, or OperationRun URLs.
• AC-006: Cross-workspace and cross-environment decision records do not influence summary counts or exported content.
• AC-007: Existing review-pack generation/download/regenerate/expire authorization and confirmation behavior is unchanged.
• AC-008: Focused Pest feature tests pass, and browser smoke is completed or explicitly documented if rendered UI changes.

Success Criteria

• SC-001: In focused test scenarios, 100% of generated review-derived packs include decision-summary content when source review truth contains decisions requiring awareness.
• SC-002: In focused negative scenarios, 100% of customer-safe paths omit raw operation/debug/proof internals.
• SC-003: In cross-scope test scenarios, 100% of hidden decisions are excluded from rendered and exported content.
• SC-004: The implementation introduces no new persisted entity, status family, global search resource, asset bundle, or operation type.

Filament v5 Blueprint Contract

• Livewire v4.0+ compliance: Required. Current app uses Livewire 4.1.4.
• Provider registration location: No panel provider changes expected. Laravel 12 panel providers remain in bootstrap/providers.php.
• Global search: No new globally searchable resource is introduced. Existing resources keep their current View/Edit/global-search posture.
• Destructive actions: No new destructive action is introduced. Existing Review Pack Expire / regenerate confirmation behavior remains unchanged and must keep ->requiresConfirmation() and policy/capability enforcement.
• Asset strategy: No new assets. Deployment cd apps/platform && php artisan filament:assets remains the existing deploy step only when registered assets change; this spec expects none.
• Testing plan: Use Pest 4 focused Feature coverage for review, review-pack, and customer workspace paths; use existing bounded Browser smoke only if rendered customer-review UI changes.

Open Questions

None blocking. The implementation may choose whether to extend the existing governance_package.governance_decisions shape directly or add a nested decision_summary key, but it must preserve the requirements above and avoid new persistence or a new framework.