TenantAtlas/specs/260-governance-service-packaging/spec.md

# Feature Specification: Governance-as-a-Service Packaging v1

**Feature Branch**: `260-governance-service-packaging`  
**Created**: 2026-05-01  
**Status**: Draft  
**Input**: User description: "Prepare Governance-as-a-Service Packaging v1 as the smallest viable on-demand management-ready governance package for one released review context, built from existing review packs, evidence snapshots, stored reports, findings, accepted-risk truth, and the shared compliance interpretation layer, without adding a new panel, report engine, scheduling system, or parallel package domain."

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

- **Problem**: TenantPilot already has repo-real tenant reviews, review packs, evidence snapshots, stored reports, accepted-risk governance, and customer-safe review surfaces, but operators still lack one repeatable management-ready deliverable that packages that truth for MSP and customer stakeholders.
- **Today's failure**: Operators still rely on manual screenshot decks, spreadsheet extracts, or ad-hoc summaries to explain released review truth. That manual packaging can bypass the customer-safe interpretation layer, weaken auditability, and drift away from the underlying review and artifact truth.
- **User-visible improvement**: An entitled actor can open one released review context and access one repeatable management-ready governance package that is customer-safe and management-readable by default.
- **Smallest enterprise-capable version**: One on-demand governance package for one released review context inside the current admin-plane review flow, derived from existing released review, review-pack, evidence, stored-report, finding, and exception or risk-acceptance truth plus the shared customer-safe interpretation layer from Spec 259. No new portal, no scheduling, no multi-pack automation, and no second source of truth ship in v1.
- **Explicit non-goals**: No new panel, no customer portal, no separate identity plane, no new report engine, no scheduling or batching system, no campaign workflow, no CRM or PSA handoff, no AI-generated summaries, no raw operator-data dump as the default deliverable, no broad multi-pack automation, and no standalone `GovernancePackage` domain.
- **Permanent complexity imported**: One bounded management-ready packaging contract over existing review and export surfaces, one bounded package-availability state on current review surfaces, focused feature plus bounded browser coverage, and explicit audit expectations for package access. No new table, no new panel, no new identity plane, and no campaign framework are introduced.
- **Why now**: `docs/product/spec-candidates.md`, `docs/product/roadmap.md`, and `docs/product/implementation-ledger.md` all keep this as an active open commercial follow-up, and Specs 258 and 259 explicitly defer it as the next bounded step after customer-safe review productization and shared interpretation are prepared.
- **Why not local**: A one-off PDF or export tweak or a single-page summary would either bypass the shared interpretation and artifact truth or remain too inconsistent across review, evidence, and review-pack surfaces to become a repeatable MSP deliverable.
- **Approval class**: Core Enterprise
- **Red flags triggered**: New packaging vocabulary and multi-surface reuse. Defense: the slice remains fully derived from existing review, export, evidence, and interpretation truth; it introduces no new persistence or automation framework; it explicitly narrows the roadmap phrase `open decisions` to repo-real exception and risk-acceptance decision truth; and it defers branding or profile variants rather than inventing a new presentation-truth source.
- **Score**: Nutzen: 2 | Dringlichkeit: 1 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 10/12**
- **Decision**: approve

## Spec Scope Fields *(mandatory)*

- **Scope**: canonical-view
- **Primary Routes**:
  - existing admin-plane customer review workspace at `/admin/reviews/workspace`
  - existing tenant-scoped released review detail route for the selected review
  - existing review-pack access or download surface reached from released review context
  - existing evidence summary and proof routes reached from released review context when the actor is entitled
- **Data Ownership**: All visible truth remains derived from existing tenant-owned `TenantReview`, `ReviewPack`, `EvidenceSnapshot`, `StoredReport`, `Finding`, `FindingException`, `FindingExceptionDecision`, and `AuditLog` records plus the shared customer-safe interpretation layer prepared by Spec 259. No new `GovernancePackage` table, no mirrored package artifact family, no campaign record, and no parallel report-store namespace are introduced. In v1, the downloadable artifact behind `Download governance package` is the current export review pack for the released review; the governance package summary is derived presentation over that existing artifact and related evidence truth, not a second export family. If an existing review or export artifact carries package output, it remains subordinate to the released review context and does not become independent source truth.
- **RBAC**:
  - this remains an admin-plane follow-up, not a new panel or authorization plane
  - workspace membership remains the first isolation boundary
  - page entry requires an established workspace scope plus at least one entitled tenant and released review the actor may read through the current capability registry
  - package access reuses existing review visibility, review-pack access, evidence or proof access, workspace entitlements, and current audit boundaries
  - non-members and out-of-scope tenant or review targets resolve as deny-as-not-found
  - actors inside an established scope may receive capability denial on the reused released-review detail route if they lack inherited review-view capability, and on gated secondary artifact or proof paths they are not entitled to use
  - the package remains read-only and introduces no operator mutation or provider-changing action

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: When launched from tenant-scoped review, evidence, or review-pack context, the workspace prefilters to that tenant and foregrounds the latest released review for that tenant. Without incoming tenant context, the page shows only entitled tenants in the current workspace.
- **Explicit entitlement checks preventing cross-tenant leakage**: Aggregated package availability, released-review entry, review-pack access, evidence links, and any already-existing secondary proof drilldowns only resolve for tenants and released reviews the actor is already entitled to read in the current workspace. Inaccessible targets are omitted from aggregated lists and resolve as not found when directly targeted.

## Cross-Cutting / Shared Pattern Reuse *(mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write `N/A - no shared interaction family touched`)*

- **Cross-cutting feature?**: yes
- **Interaction class(es)**: status messaging, management summary sections, action links, evidence viewers, review-pack access, package-availability states, and stored-report-backed evidence disclosure
- **Systems touched**: existing `CustomerReviewWorkspace`, existing released review detail surfaces, `TenantReviewSectionFactory`, `TenantReviewComposer`, the shared `control_interpretation` contract prepared by Spec 259, `ArtifactTruthPresenter`, `ArtifactTruthEnvelope`, existing review-pack access or download surfaces, existing evidence summary and proof viewers, stored-report-backed evidence inputs, localization, and audit infrastructure
- **Existing pattern(s) to extend**: the current customer review productization contract from Spec 258, the shared customer-safe control or readiness interpretation path from Spec 259, and the existing review-pack, evidence, and artifact-truth disclosure surfaces
- **Shared contract / presenter / builder / renderer to reuse**: `TenantReviewSectionFactory`, `TenantReviewComposer`, the shared `control_interpretation` contract from Spec 259, `ArtifactTruthPresenter`, `ArtifactTruthEnvelope`, `SurfaceCompressionContext`, and the current review, evidence, stored-report-backed evidence, and review-pack disclosure surfaces
- **Why the existing shared path is sufficient or insufficient**: Existing review, interpretation, review-pack, evidence, stored-report, and audit truth already cover what the package should say. The missing piece is one repeatable management-ready packaging pass that keeps those truths aligned instead of forcing manual translation or page-local exports.
- **Allowed deviation and why**: none. This slice must tighten the current review and export path rather than introduce a parallel package domain, package-specific vocabulary layer, or direct raw-report export.
- **Consistency impact**: Executive summary wording, top findings, accepted-risk governance wording, governance-decision follow-up phrasing, evidence-link language, package-availability states, current review-pack framing, and audit labels must stay aligned between workspace summary, released review detail, and package access.
- **Review focus**: Reviewers must block any new standalone package domain, any page-local interpretation path, any raw data-dump default, or any management export that bypasses released review and shared interpretation truth.

## OperationRun UX Impact *(mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an `OperationRun`; otherwise write `N/A - no OperationRun start or link semantics touched`)*

- **Touches OperationRun start/completion/link UX?**: no
- **Shared OperationRun UX contract/layer reused**: `N/A`
- **Delegated start/completion UX behaviors**: `N/A`
- **Local surface-owned behavior that remains**: This slice packages only already released review truth and already available evidence, report, and review-pack inputs. It must not start new review-pack, stored-report, evidence, or package runs in v1.
- **Queued DB-notification policy**: `N/A`
- **Terminal notification path**: `N/A`
- **Exception required?**: none

## Provider Boundary / Platform Core Check *(mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write `N/A - no shared provider/platform boundary touched`)*

- **Shared provider/platform boundary touched?**: yes
- **Boundary classification**: platform-core
- **Seams affected**: customer-safe interpretation reuse, management package wording, evidence-link semantics, package labels, and summary language
- **Neutral platform terms preserved or introduced**: governance package, released review, control or readiness summary, evidence basis, accepted-risk governance decision, and review context
- **Provider-specific semantics retained and why**: Provider-specific report types or evidence labels may remain reachable only through entitled secondary drilldown because some existing stored reports are provider-owned artifacts. They are not part of the default management-ready package language.
- **Why this does not deepen provider coupling accidentally**: Package summary and availability are derived from released review truth plus the shared customer-safe interpretation layer, not from raw Microsoft report types, provider identifiers, or provider payload language.
- **Follow-up path**: future framework-specific package profiles or broader portfolio packaging remain follow-up specs after this bounded v1 proves itself

## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)*

| 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 page | yes | Native Filament page plus shared review and evidence primitives | status messaging, package availability, navigation entry points | page, table or filter state, disclosure state | no | Existing page stays the selection surface and does not become a separate package registry |
| Released Customer Review detail | yes | Native Filament resource or detail surface plus shared review, evidence, and export primitives | management summary sections, package access, evidence and report viewers | detail sections, disclosure state, access states | no | Existing detail becomes the package-owning context and avoids a new page shell |

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

| Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction |
|---|---|---|---|---|---|---|---|
| Customer Review Workspace page | Primary Decision Surface | Operator decides which released review context is ready for stakeholder packaging | released review state, package availability, top-line governance signal, and evidence-basis presence | released review detail, package summary, and supporting proof after explicit open | Primary because it is the calm review-selection surface and should answer where packaging can begin before deeper inspection | Aligns packaging with the existing review-consumption workflow instead of with storage-object navigation | Removes hunting across review pack, stored report, and evidence screens before the first decision |
| Released Customer Review detail | Secondary Context Surface | Operator confirms what the package will say and accesses the package for one released review | executive summary, top findings, accepted risks, governance-decision follow-up, evidence links, and package state | deeper proof, stored-report context, and raw or support detail only after explicit drilldown | Secondary because it is entered after the workspace has already selected one review context | Keeps packaging centered on one released review instead of inventing a second package dashboard | Removes manual summary assembly by making the released review the single packaging anchor |

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

| Surface | Audience Modes In Scope | Decision-First Default-Visible Content | Operator Diagnostics | Support / Raw Evidence | One Dominant Next Action | Hidden / Gated By Default | Duplicate-Truth Prevention |
|---|---|---|---|---|---|---|---|
| Customer Review Workspace page | operator-MSP, customer-admin, auditor-read-only, customer-read-only | released review state, package availability, calm executive-summary teaser, top findings and accepted-risk signal, and evidence-basis presence | review freshness, lineage, and source completeness only after opening the review | raw reports, provider IDs, fingerprints, and raw evidence remain hidden or gated | `Open released review` | raw or support detail and secondary artifact links stay off the list surface by default | Workspace states package readiness once; detail owns the actual package summary |
| Released Customer Review detail | operator-MSP, customer-admin, auditor-read-only, customer-read-only | management-ready executive summary, top findings, accepted risks, current governance decisions needing awareness, evidence links, package scope, current review-pack delivery framing, and package-access state | review lineage, freshness, section completeness, and source artifact detail in secondary sections only | raw evidence payloads, stored-report payloads, provider-debug context, and unrestricted support detail remain hidden or gated | `Download governance package` | raw source payloads, unrestricted stored-report detail, and operator-only diagnostics remain secondary and explicit | Detail owns the management package summary; deeper proof links add source context without restating the same summary cards as peer truth |

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

| Surface | Action Surface Class | Surface Type | Likely Next Operator Action | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type / Justification |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Customer Review Workspace page | List / Table / Read-only workspace report | Read-only registry report | Open the released review for packaging context | full-row open to released review detail | required | no peer package row action; package availability stays informational on the list surface | none | `/admin/reviews/workspace` | `/admin/t/{tenant}/reviews/{record}` | workspace context, tenant prefilter, release state, package availability | Customer review | whether the current released review is eligible for management-ready delivery | none |
| Released Customer Review detail | Detail / Report / Management export | Read-only detail report | Download the governance package for the current released review | sectioned detail page with one dominant safe header action | forbidden | existing proof links and review-pack access remain secondary in-body or lower-priority actions | none | `/admin/reviews/workspace` | `/admin/t/{tenant}/reviews/{record}` | workspace, tenant, release state, interpretation version, package availability | Governance package | what this package covers, what matters now, and which evidence basis supports it | none |

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

| Surface | Primary Persona | Decision / Operator Action Supported | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|---|
| Customer Review Workspace page | MSP operator or entitled customer-safe reviewer | Decide whether the current released review is ready to package and which review to open | Read-only workspace review overview | Which released review should I package for stakeholder delivery? | released review state, package availability, top-line findings or accepted-risk signal, and evidence-basis presence | review lineage, freshness, and source completeness in secondary context only | release state, package readiness, evidence completeness, accepted-risk governance signal | none | Open released review | none |
| Released Customer Review detail | MSP operator or entitled customer-safe reviewer | Inspect the management-ready summary and access the package for one released review | Read-only detail report | What will this stakeholder package say, and is the supporting basis ready and safe to deliver? | executive summary, top findings, accepted risks, governance-decision follow-up, evidence links, package state, and explicit current review-pack delivery framing | deeper stored-report and evidence provenance plus raw or support details only after explicit drilldown and entitlement | interpretation version, evidence sufficiency, accepted-risk governance validity, package availability | none | Download governance package | none |

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

- **New source of truth?**: no
- **New persisted entity/table/artifact?**: no new artifact family
- **New abstraction?**: no
- **New enum/state/reason family?**: no
- **New cross-domain UI framework/taxonomy?**: no
- **Current operator problem**: Existing review truth can explain one released review, but it still does not provide one repeatable management-ready package that stays aligned with shared interpretation and artifact truth.
- **Existing structure is insufficient because**: Review workspace and detail flows answer review questions, but they do not yet provide a bounded deliverable contract for stakeholder packaging. Manual packaging currently re-translates the same truth outside the product.
- **Narrowest correct implementation**: One derived management-ready package bound to one released review context and current review, evidence, report, and export surfaces, with explicit unavailable states instead of generating missing source truth.
- **Ownership cost**: A bounded disclosure and wording pass plus focused package-access, authorization, and audit tests, and one bounded browser smoke.
- **Alternative intentionally rejected**: A standalone `GovernancePackage` model and campaign engine were rejected as structurally too heavy. A page-local export template that reads raw findings or reports directly was rejected because it would drift from shared interpretation and artifact truth.
- **Release truth**: current-release commercial follow-through, not future-release platform buildout

### 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.

Canonical reuse of existing review and export truth is preferred over introducing a new package domain.

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

- **Test purpose / classification**: Feature, Browser
- **Validation lane(s)**: confidence, browser
- **Why this classification and these lanes are sufficient**: Focused feature tests are the narrowest sufficient proof for package availability logic, interpretation dependency, auditability, `404` or `403` boundaries, explicit unavailable or partial states, and truth separation across the existing review surfaces. One bounded browser smoke remains justified because this slice materially changes default-visible management-ready content and action hierarchy on rendered review surfaces.
- **New or expanded test families**: expand the existing `Reviews/CustomerReviewWorkspace`, `TenantReview`, `ReviewPack`, and adjacent audit or package-access families; keep exactly one bounded browser smoke around the current review workspace and detail flow
- **Fixture / helper cost impact**: low to moderate. Reuse existing workspace membership, released review, review pack, evidence snapshot, stored report, finding, exception decision, interpretation summary, and audit fixtures. Avoid provider sync or queue-heavy defaults.
- **Heavy-family visibility / justification**: exactly one browser smoke stays explicit because the slice is primarily about packaging disclosure and action placement on existing rendered surfaces. No broader browser or heavy-governance family is introduced.
- **Special surface test profile**: shared-detail-family
- **Standard-native relief or required special coverage**: ordinary Filament feature coverage is sufficient for routing, authorization, availability, localization-ready wording, and package-truth separation. The bounded browser smoke is the only required rendered proof.
- **Reviewer handoff**: Reviewers must confirm that package access never bypasses the shared interpretation layer, no new package domain or search surface appears, out-of-scope tenants leak nothing, management summary stays customer-safe, `Download governance package` resolves to the current export review pack rather than a second artifact family, and no branding or profile system is smuggled into v1.
- **Budget / baseline / trend impact**: low feature-local increase only
- **Escalation needed**: none
- **Active feature PR close-out entry**: Smoke Coverage
- **Planned validation commands**:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantReview/TenantReviewUiContractTest.php tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php`

## Scope Boundaries

### In Scope
- one on-demand management-ready governance package for one released review context
- executive summary in customer-safe language grounded in released review truth
- top findings, accepted risks, current governance decisions requiring awareness, and evidence links
- reuse of the shared customer-safe interpretation layer from Spec 259, which the package must not bypass
- package availability plus explicit `available`, `partial`, `unavailable`, `expired`, and `blocked` states, with stale or entitlement-restricted conditions expressed through those state reasons
- explicit current review-pack framing that does not introduce a second downloadable artifact family
- explicit auditability for package access or download and secondary evidence or proof opens
- localization-ready customer-safe and management-ready wording
- reuse of current review-pack, stored-report, evidence-snapshot, and review surfaces rather than a parallel package domain

### Non-Goals

- a new panel, portal, customer shell, or separate identity plane
- a new report engine, campaign system, schedule, batch flow, newsletter flow, or communications automation
- PSA or CRM workflow, service-desk handoff, or broader customer-ops orchestration
- review authoring, publishing, regeneration, or evidence or report refresh generation
- raw operator-data dumps as the default deliverable
- AI-generated summaries or packaging
- branding or profile variants beyond neutral v1 governance-package framing over the current export review pack
- multi-review or multi-tenant package automation
- a new governance-decision workflow state or broader decision board beyond repo-real exception and risk-acceptance truth
- a new standalone governance-package persistence family

## Dependencies

- current customer review productization contract from `specs/258-customer-review-productization/spec.md`
- shared customer-safe interpretation layer from `specs/259-compliance-evidence-mapping/spec.md`
- existing `TenantReview`, `ReviewPack`, `EvidenceSnapshot`, `StoredReport`, `Finding`, `FindingException`, and `FindingExceptionDecision` truth
- existing review-pack access or download surfaces and evidence or report drilldown surfaces
- existing localization, entitlements, capability-first RBAC, and audit foundations

## Assumptions

- released review truth remains the authoritative context for stakeholder delivery
- the shared customer-safe interpretation layer from Spec 259 exists and is reused; packaging does not compute management meaning separately
- an eligible existing review, evidence, and report basis is available for at least one released review context; when it is not, v1 can show explicit unavailable or partial state instead of generating missing sources
- current Filament v5 plus Livewire v4 admin-plane surfaces remain the canonical entry points; no panel or provider registration change is required
- existing asset strategy is sufficient; this slice does not justify heavy new asset registration
- existing review-pack or download entitlement rules remain the governing commercial gate for artifact access
- branding or profile variants stay deferred until the repo has a clear existing source of presentation truth that does not add new persistence or configuration scope

## Risks

- packaging copy could drift from the shared interpretation layer if implementation reads raw findings or stored reports directly
- scope pressure could try to add client-specific branding, profile variants, or bespoke layouts even though v1 intentionally keeps neutral governance-package framing over the current export review pack only
- some released reviews may have incomplete evidence or report basis, forcing explicit partial package states
- the roadmap phrase `open decisions` could be over-read as a broader queue or approval engine unless the slice stays narrowed to repo-real exception or risk-acceptance decision truth
- if package access attempts to trigger missing review-pack or report generation, scope could spill into report-engine or `OperationRun` work

## Candidate Selection Rationale

- **Selected candidate**: Governance-as-a-Service Packaging v1
- **Source locations**:
  - `docs/product/spec-candidates.md` active P2 candidate
  - `docs/product/roadmap.md` priority order item 5 plus the dedicated packaging section
  - `docs/product/implementation-ledger.md` open gap `Review truth is not yet packaged as a repeatable MSP deliverable`
  - `specs/258-customer-review-productization/spec.md`
  - `specs/259-compliance-evidence-mapping/spec.md`
- **Why selected**: This is the active unspecced P2 candidate with no direct existing spec. Specs 258 and 259 explicitly defer it as the next bounded follow-up, and the roadmap order plus implementation ledger both place it in the current sellability lane.
- **Why this is the smallest viable implementation slice**: It keeps the work on one on-demand management-ready package for one already released review context, using current review, evidence, report, and export artifacts plus shared customer-safe interpretation, with no new package domain, campaign engine, or scheduling system.
- **Intentional narrowing from source candidate**: The roadmap and candidate phrase `open decisions` is narrowed here to repo-real governance decision truth from exceptions and risk acceptance, especially current accepted-risk governance decisions and exception decisions that still need follow-up or contextual explanation. V1 does not invent a broader decision queue, approval workflow, or new operator inbox semantics, and it defers bounded MSP branding until the repo has a clear existing source of presentation truth to reuse.
- **Why close alternatives are deferred**:
  - Cross-Tenant Compare and Promotion v1 already has refreshed Spec 043 and remains a separate portfolio-action track.
  - Workspace, Tenant & Managed Object Lifecycle Governance v1 is explicitly strategic and not ready in the active candidate queue.
  - External Support Desk / PSA Handoff already has Spec 256 and is a separate commercialization lane.
  - Customer Review Productization and Compliance Evidence Mapping already have Specs 258 and 259; this package depends on them instead of reopening them.

## Follow-up Candidates

- recurring schedule, batch, or campaign packaging only after one on-demand package proves product fit and stays audit-safe
- broader branding or profile variants only after the default package remains truthful across customers and the repo has a clear existing presentation-truth source to reuse
- portfolio or multi-tenant package automation after compare or promotion and governance decision convergence are materially closed
- external delivery workflows such as PSA, service-desk, or communications automation as separate follow-ups

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Produce one repeatable stakeholder package from a released review (Priority: P1)

An MSP operator wants one package from a released review so they can deliver a recurring governance update without manual slide decks, spreadsheet extracts, or ad-hoc screenshots.

**Why this priority**: This is the core sellability gap. If the operator still has to assemble the management story outside the product, the feature fails.

**Independent Test**: Open an eligible released review and access the package that is built from existing review, evidence, report, and review-pack basis without triggering a new reporting or generation workflow.

**Acceptance Scenarios**:

1. **Given** an entitled actor has a released review with an eligible existing evidence and report basis, **When** they open the released review detail, **Then** they can access one management-ready governance package without starting new review, evidence, or report generation.
2. **Given** no eligible released review basis exists, **When** the actor requests the package, **Then** the surface shows an explicit unavailable or partial state instead of a hidden admin path or a new generation workflow.
3. **Given** the actor opens the workspace with multiple entitled tenants, **When** they scan the review list, **Then** they can identify which released review context is package-ready before opening detail.

---

### User Story 2 - Read management-ready governance meaning without raw operator translation (Priority: P1)

A customer admin or auditor wants the package to explain what matters now in calm management-ready terms so they can understand the governance position without reading raw operator detail.

**Why this priority**: Packaging is not useful if it still requires manual translation of technical findings and evidence into stakeholder language.

**Independent Test**: Open the package or its access context for one released review and confirm that the output summarizes executive position, top findings, accepted risks, governance decisions, and evidence links using shared customer-safe interpretation.

**Acceptance Scenarios**:

1. **Given** the package is available, **When** the actor opens it or its access context, **Then** the output summarizes executive position, top findings, accepted risks, current governance decisions requiring awareness, and evidence links in customer-safe language.
2. **Given** the shared interpretation layer marks a control, readiness summary, or package section as partial, **When** the package is shown, **Then** the package keeps that limitation visible and does not infer stronger management claims from raw evidence.
3. **Given** the actor stays in the default package view, **When** deeper stored reports or raw evidence exist, **Then** raw payloads and operator or support diagnostics remain hidden until explicit entitled drilldown.

---

### User Story 3 - Trust packaging boundaries, auditability, and scope isolation (Priority: P2)

An MSP operator wants the package to stay auditable and safe even when secondary access paths are restricted, so stakeholder delivery does not weaken trust or isolation.

**Why this priority**: A management package only helps if it remains attributable, bounded, and safe to expose across tenant and workspace boundaries.

**Independent Test**: Access or download the package for an entitled review, then verify auditability, explicit secondary-access unavailability, current review-pack delivery framing, and deny-as-not-found behavior for out-of-scope targets.

**Acceptance Scenarios**:

1. **Given** the package is accessed or downloaded, **When** the action completes, **Then** the audit trail records that access using the current audit infrastructure.
2. **Given** the actor lacks a secondary review-pack or proof-access entitlement inside an otherwise visible review context, **When** the package renders, **Then** the management summary remains readable while secondary artifact access is explicitly unavailable.
3. **Given** the actor targets a tenant or review outside their scope, **When** the package or supporting link is opened, **Then** the system resolves as not found and reveals no package, review, or evidence presence.

### Edge Cases

- a released review exists but the shared interpretation layer or version is unavailable for one section, so the package must show explicit partial or unavailable content and no raw-report fallback
- accepted risk exists but current governance is expired, revoked, or rejected, so the package must show governance follow-up needed rather than treat the issue as safely accepted
- a review pack exists but a supporting stored report or evidence link has expired or been redacted, so the package must keep the summary truthful and mark the supporting link unavailable
- a workspace filter or direct link targets an inaccessible tenant or unreleased review, so the request must resolve safely without leakage

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces no new Microsoft Graph calls, no tenant-changing write path, no new scheduled work, and no new `OperationRun`. It packages already released review truth and already available evidence or report inputs for stakeholder delivery.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** This follow-up must stay derived. It must not introduce a standalone package source of truth, a new report engine, a campaign system, or a new package-specific taxonomy.

**Constitution alignment (XCUT-001):** The feature must extend existing review, interpretation, review-pack, evidence, report, localization, and audit paths rather than invent a package-local semantic layer.

**Constitution alignment (DECIDE-AUD-001 / OPSURF-001):** Default-visible content must remain customer-safe and management-ready, with raw or support detail hidden by default and one dominant next action preserved per surface.

**Constitution alignment (TEST-GOV-001):** The implementation must stay with focused feature coverage plus one bounded browser smoke and avoid creating a broader heavy family.

**Constitution alignment (RBAC-UX):** Workspace and tenant membership remain deny-as-not-found boundaries. Optional secondary artifact access remains capability-gated inside an established scope. No new role strings or raw capability strings are introduced by this spec.

**Constitution alignment (UI-FIL-001 / UI-NAMING-001 / DECIDE-001 / ACTSURF-001):** The slice must remain a native Filament read-only review and export flow with one dominant inspect action on the workspace and one dominant package action on released review detail. No destructive actions are introduced.

### Functional Requirements

- **FR-001**: The system MUST keep this slice inside the existing admin-plane customer review workspace and released-review detail flow rather than creating a new panel, portal, or customer shell.
- **FR-002**: The system MUST derive every management-ready package summary from existing released review, review-pack, evidence-snapshot, stored-report, finding, accepted-risk, and exception-decision truth rather than from a new standalone package record.
- **FR-003**: The package MUST depend on the shared customer-safe interpretation layer prepared by Spec 259 and MUST NOT render management meaning directly from raw findings, stored reports, or evidence payloads when that layer is absent.
- **FR-004**: V1 MUST support exactly one package per released review context at a time and MUST keep packaging anchored to that released review rather than to a broader workspace campaign or portfolio bundle.
- **FR-005**: The default-visible package summary MUST answer what review context is covered, what matters now, which findings and accepted risks are most material, which governance decisions require awareness, what evidence basis exists, and what the next stakeholder-facing action is.
- **FR-006**: The roadmap and candidate phrase `open decisions` MUST be narrowed in this slice to repo-real governance decision truth rooted in exceptions and risk acceptance. V1 MUST NOT imply a broader approval queue, decision inbox, or new workflow engine.
- **FR-007**: Accepted-risk and governance-decision content shown through this slice MUST summarize decision reason, accountable role or person when product truth exists, timing, and expiry, re-review, or follow-up state without exposing internal workflow residue. `accepted_risks` MUST contain currently valid tolerated-risk positions that explain why risk is presently accepted, while `governance_decisions` MUST contain only accepted-risk or exception entries that still require stakeholder awareness or follow-up. The same source decision MUST NOT appear in both lists for the same released review.
- **FR-008**: Evidence links in the package MUST point to existing entitled evidence or review-pack surfaces and MUST NOT duplicate raw payloads or provider-debug data as default package content. Existing report detail may only appear when an already-existing entitled viewer seam is available through the current evidence path.
- **FR-009**: The package MUST preserve artifact and result truth separation: findings, evidence snapshots, stored reports, review packs, and package summary remain distinct, and the package MUST NOT overwrite or redefine those source records as canonical truth.
- **FR-010**: The package MUST remain on-demand and bounded to existing released-review truth. V1 MUST NOT schedule, batch, queue campaigns, or automate multi-pack delivery.
- **FR-011**: When required source basis is unavailable, stale, expired, redacted, or incomplete, the surface MUST show explicit `partial`, `unavailable`, `expired`, or `blocked` states with truthful reason messaging rather than generating missing truth or implying false calmness.
- **FR-012**: Package availability MUST only be shown for entitled tenants and eligible released reviews in the current workspace.
- **FR-013**: Non-members and out-of-scope workspace, tenant, or review requests MUST resolve as deny-as-not-found, while actors inside an established scope MAY receive capability denial on the reused released-review detail route or on gated secondary artifact or proof paths when inherited capability checks deny access.
- **FR-014**: Every explicit package access or download and every secondary proof or review-pack action exposed through this slice MUST remain auditable through the current audit infrastructure.
- **FR-015**: V1 MUST NOT introduce custom branding, profile variants, or client-specific layout logic. `Download governance package` remains governance-package framing over the current export review pack for the released review and MUST NOT become a second downloadable artifact family.
- **FR-016**: Customer-facing and stakeholder-facing labels introduced by this slice MUST remain localization-ready for the existing DE and EN language posture.
- **FR-017**: The slice MUST expose no destructive, remediation, publication, regeneration, provider-changing, or admin-only actions in the management-ready package path.
- **FR-018**: The slice MUST NOT introduce a new global-searchable resource or widen existing cross-tenant discovery for package, review, report, or evidence artifacts.
- **FR-019**: Package summary and package-availability meaning for the same released review MUST stay consistent between workspace summary, released-review detail, and any package-access path.
- **FR-020**: The slice MUST reuse current review-pack, evidence, and stored-report artifacts instead of introducing a standalone governance-package report engine or package persistence family.

### Non-Functional Requirements

- **NFR-001**: V1 MUST introduce no new Graph calls, no new queue or `OperationRun`, and no scheduled or batched runtime path.
- **NFR-002**: Asset strategy remains unchanged. If later implementation unexpectedly registers assets, deployment still uses the existing `cd apps/platform && php artisan filament:assets` step.
- **NFR-003**: The package MUST remain understandable from the current review surfaces without requiring a second navigation shell or parallel package registry.

### UX Requirements

- **UXR-001**: The workspace list keeps one dominant `Open released review` action, and released review detail keeps one dominant package action.
- **UXR-002**: Raw or support detail remains secondary and explicit; the workspace list does not gain a peer package row action that competes with review inspection.
- **UXR-003**: Package `partial`, `unavailable`, `expired`, and `blocked` states, including stale or entitlement-restricted reasons, are calm, explicit, and management-readable.

### RBAC / Security Requirements

- **RBR-001**: The slice MUST reuse the canonical capability registry and MUST NOT introduce raw capability strings or role-name checks in feature code.
- **RBR-002**: Package availability, evidence links, report links, and review-pack access MUST NOT leak inaccessible tenant or review hints through counts, labels, empty states, or direct-link responses.

### Auditability / Observability Requirements

- **AOR-001**: Package access, package download, and secondary artifact access exposed by this slice MUST be auditable through the current audit infrastructure, with no new parallel audit store.
- **AOR-002**: Package output remains attributable to one released review context and one interpretation version so later operators can understand what meaning layer produced the package.

### Data / Truth-Source Requirements

- **DTR-001**: `TenantReview`, `ReviewPack`, `EvidenceSnapshot`, `StoredReport`, `Finding`, `FindingException`, `FindingExceptionDecision`, and `AuditLog` remain the authoritative persisted inputs for this slice.
- **DTR-002**: Governance package output is a derived packaging layer only and MUST NOT become independent product truth about review state, evidence state, or governance state.

## Out of Scope

- new package persistence or campaign state
- scheduled or batched governance delivery
- PSA, CRM, or customer-communications automation
- AI-generated package content
- review or report generation, publication, or regeneration flows

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

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Customer Review Workspace | existing `App\Filament\Pages\Reviews\CustomerReviewWorkspace` | `Clear filters` only | `recordUrl()` or full-row open to the released review | `Open released review` only | none | `Clear filters` only when filters are active; otherwise explanatory no-data text with no package-generation CTA | `N/A` | `N/A` | yes | Package readiness remains informational on the list surface so the dominant action stays choosing the released review context |
| Released Customer Review detail | existing tenant-scoped released review detail surface | `Download governance package` only when the released review and source basis are eligible | `N/A` | `N/A` | none | `N/A` | no additional peer header action beyond the dominant package action; evidence and existing review-pack links stay secondary | `N/A` | yes | Package access stays bound to the current released review and reuses the current export review pack, existing proof, entitlements, and audit gates |

Action Surface Contract is satisfied for this slice. Each affected surface keeps one dominant inspect or action model, no empty `ActionGroup` or `BulkActionGroup` placeholder, and no destructive-action placement rules are needed because destructive actions are out of scope. `UI-FIL-001` and `UX-001` are satisfied by staying inside native Filament read-only review surfaces, using explicit empty states, and keeping management-ready emphasis aligned to shared review and interpretation semantics rather than page-local visual language.

### Key Entities *(include if feature involves data)*

- **Released Review Context**: The existing tenant review chosen for stakeholder delivery and used to anchor all package content.
- **Governance Package Output**: The derived management-ready package rendered from existing review, evidence, report, and export truth for one released review. It is not a standalone persisted domain.
- **Customer-safe Interpretation Summary**: The shared interpretation output from Spec 259 that converts technical governance truth into management-ready meaning.
- **ReviewPack**: The existing packaged export artifact reused as a supporting source or linked artifact for stakeholder delivery.
- **EvidenceSnapshot**: The existing proof artifact referenced by package evidence basis and deeper drilldown.
- **StoredReport**: The existing report artifact family that may provide supporting source detail but is not the customer-safe package itself.
- **Governance Decision Record**: The existing exception or risk-acceptance decision truth, including `FindingExceptionDecision` and current governance validity.
- **AuditLog**: The existing audit trail that keeps package and supporting artifact access attributable without introducing a new audit store.

## Acceptance Criteria

- an authorized actor can access one repeatable on-demand governance package for an eligible released review from the current review surfaces
- the package is management-readable and customer-safe by default and clearly represents top findings, accepted risks, current governance decisions, and evidence links
- the package depends on the shared customer-safe interpretation layer and never bypasses it with raw provider or report language
- the `Download governance package` path remains governance-package framing over the current export review pack and does not introduce a second artifact family
- no new package domain, report engine, schedule, or cross-tenant discovery surface is introduced

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: An entitled actor can reach the governance package for an eligible released review in three interactions or fewer from the current customer review workspace.
- **SC-002**: In 100% of validated scenarios, the same released review shows consistent executive summary meaning, top findings, accepted-risk governance decisions, and interpretation-dependent messaging across workspace summary, released-review detail, and package access.
- **SC-003**: In 100% of validated unauthorized or out-of-scope scenarios, the feature reveals no cross-tenant package, review, report, or evidence presence.
- **SC-004**: In 100% of validated incomplete-source scenarios, the package shows an explicit partial or unavailable state instead of implying a complete management package.
- **SC-005**: In 100% of validated package-download scenarios, `Download governance package` resolves to the current export review pack for the released review and preserves the ordering and wording of core governance truth and evidence links.

## Open Questions

- none