# Feature Specification: Compliance Evidence Mapping v1

**Feature Branch**: `259-compliance-evidence-mapping`  
**Created**: 2026-04-30  
**Status**: Draft  
**Input**: User description: "Compliance Evidence Mapping v1 as the smallest versioned overlay that maps existing technical governance truth into one customer-safe control/readiness view and one reuse path in the released review or export flow, without certification claims, new control foundations, or a parallel reporting engine."

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

- **Problem**: TenantPilot already has repo-real canonical controls, evidence snapshots, findings, accepted-risk governance, and customer-review surfaces, but the product still lacks one explicit customer-safe layer that turns existing technical governance truth into a control/readiness story a customer can understand without operator translation.
- **Today's failure**: Operators and customer-facing reviewers still have to translate raw findings, evidence, and accepted-risk details into control meaning by hand. That makes the product harder to sell, easier to overstate, and less trustworthy than the existing repo truth.
- **User-visible improvement**: An authorized reviewer can open the existing customer review flow and understand which controls need attention, what evidence supports that view, what risk is accepted, and what next action is recommended without seeing raw diagnostics or certification-style claims.
- **Smallest enterprise-capable version**: Add one versioned interpretation overlay over existing canonical control references and render it in the current customer review workspace plus released review detail flow so the same customer-safe control/readiness meaning appears in both surfaces.
- **Explicit non-goals**: No certification claims, no legal/compliance guarantees, no BSI/NIS2/CIS/ISO-specific framework engine, no new provider-specific control model, no new portal or panel, no new persistence table, no new report engine, no review authoring or mutation flow, no destructive actions, and no broad export-suite redesign.
- **Permanent complexity imported**: One bounded versioned control-interpretation overlay, one shared customer-safe control/readiness vocabulary, one shared summary contract reused across current review surfaces, and focused review/evidence test expansion. No new persisted entity, no new panel, and no multi-framework taxonomy are introduced in v1.
- **Why now**: The roadmap and implementation ledger both keep compliance evidence mapping as the next open moat-building follow-up after customer review productization, and `specs/258-customer-review-productization/spec.md` explicitly defers this slice.
- **Why not local**: A page-local copy rewrite would not keep workspace and detail flows consistent, would not make interpretation version explicit, and would not provide a reusable customer-safe meaning layer over canonical control references.
- **Approval class**: Core Enterprise
- **Red flags triggered**: New semantic layer, new versioned interpretation vocabulary, and review-surface reuse concerns. Defense: the slice is bounded to one overlay family and one current review path, derives from existing truth, and explicitly defers framework-specific and packaging follow-ups.
- **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 evidence summary/proof routes reached from released review context when the actor is entitled
- **Data Ownership**: All control/readiness truth remains derived from existing tenant-owned review, finding, accepted-risk, and evidence records plus the existing canonical control catalog. Existing review payloads may carry derived interpretation version and control summary data, but no new workspace-owned or tenant-owned table, projection store, or standalone artifact family is introduced.
- **RBAC**:
  - this remains an admin-plane follow-up, not a new panel or identity surface
  - workspace membership remains the first isolation boundary
  - page entry requires an established workspace scope plus at least one entitled tenant the actor may read through the existing capability registry
  - evidence pointers and deeper proof paths remain capability-gated through current review and evidence authorization paths
  - non-members or out-of-scope tenant requests resolve as deny-as-not-found
  - no new customer-only role family or raw capability strings are introduced

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: When launched from tenant-scoped review 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 lists, control summaries, review detail entry, and evidence pointers only resolve for tenants the actor is entitled to in the current workspace. Inaccessible tenant 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, review summaries, detail disclosure, evidence/report viewers, recommendation phrasing, and safe evidence-link affordances
- **Systems touched**: existing `CanonicalControlCatalog`, existing `CanonicalControlResolver`, existing tenant review composition, existing `CustomerReviewWorkspace`, existing released review detail surfaces, and existing evidence-summary/proof presentation
- **Existing pattern(s) to extend**: current canonical control references already exposed through tenant review composition and the customer review productization flow from Spec 258
- **Shared contract / presenter / builder / renderer to reuse**: `CanonicalControlCatalog`, `CanonicalControlResolver`, `TenantReviewSectionFactory`, `TenantReviewComposer`, and the existing customer review workspace/detail surfaces
- **Why the existing shared path is sufficient or insufficient**: The repo already has canonical control references flowing into review composition, but it does not yet have one explicit customer-safe interpretation layer over those references. The missing piece is shared interpretation, not new data foundations.
- **Allowed deviation and why**: none. The feature must add one shared interpretation path rather than a second page-local control vocabulary.
- **Consistency impact**: Control labels, readiness wording, evidence-basis language, recommended action phrasing, accepted-risk influence, and interpretation-version disclosure must stay aligned between workspace summary and released review detail.
- **Review focus**: Reviewers must block any page-local control taxonomy, direct framework naming, or raw technical status mapping that bypasses the shared interpretation layer.

## 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 stays on read-only review and evidence interpretation surfaces and does not add a new run start, queue, resume, or completion path.
- **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**: canonical control interpretation, review-summary payloads, customer-safe labels, readiness wording, and evidence-link semantics
- **Neutral platform terms preserved or introduced**: canonical control, control readiness, evidence basis, recommendation, interpretation version
- **Provider-specific semantics retained and why**: Existing Microsoft subject bindings remain internal resolution inputs only because the current canonical control catalog already depends on them. They must not become customer-visible control language.
- **Why this does not deepen provider coupling accidentally**: Customer-facing summaries stay keyed to canonical control keys and released review truth, not provider object IDs, Graph-specific nouns, or framework-specific policy names.
- **Follow-up path**: framework-specific overlays and management/export packaging remain follow-up specs after this shared customer-safe layer is stable

## 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/evidence primitives | status messaging, review summaries, evidence-link affordances | page, table/filter, disclosure state | no | Existing page gains one control/readiness view rather than a new navigation surface |
| Released Customer Review detail | yes | Native Filament resource/detail surface plus shared review/evidence primitives | detail disclosure, evidence summaries, recommendation framing | detail sections, disclosure state | no | Existing detail flow becomes the explanation surface for the mapped control/readiness view |

## 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 | Customer reviewer, customer admin, or auditor decides which controls need follow-up and whether the released review is sufficient for the current conversation | control/readiness summary, top evidence basis, accepted-risk influence, and recommended next action | released review detail and entitled evidence pointers after explicit open | Primary because it is the first calm customer-safe review route and should answer the top-level control question without forcing raw technical reconstruction | Follows review-consumption workflow, not storage-object navigation | Replaces manual translation of findings into control meaning across multiple pages |
| Released Customer Review detail | Secondary Context Surface | Reader validates why a control is in its current state and what evidence or accepted-risk context supports that interpretation | per-control explanation, evidence basis, accepted-risk context, and next recommendation | deeper proof context only after explicit drilldown and capability checks | Not primary because it deepens the summary chosen in the workspace rather than replacing it | Keeps the workflow centered on one released review after the overview step | Prevents the first page from carrying both high-level decision support and full technical explanation |

## 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 | customer-read-only, customer-admin, auditor-read-only, operator-MSP | which controls need attention, what evidence basis exists, what risk is accepted, and what next step is recommended | release timing and secondary freshness/context only after opening the review | raw payloads, provider IDs, and unrestricted diagnostics stay out of the default path | `Open released review` | raw/support detail and deeper proof context remain hidden or capability-gated | Workspace summary states the mapped control meaning once; the detail surface explains it rather than restating the same summary blocks |
| Released Customer Review detail | customer-read-only, customer-admin, auditor-read-only, operator-MSP | per-control readiness meaning, linked findings/evidence basis, accepted-risk influence, interpretation version, and next recommendation | secondary lineage and deeper evidence detail only in follow-on sections | raw payloads, provider-debug data, and unrestricted evidence internals remain hidden or gated | `Review supporting evidence` | support-only detail and deep diagnostics remain outside the default customer-safe view | Detail expands the chosen control state and version; it does not recreate the workspace overview as a separate source of 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 the selected tenant | full-row open to released review detail | required | evidence and proof links stay inside the detail flow, not peer row actions | none | /admin/reviews/workspace | /admin/t/{tenant}/reviews/{record} | workspace context, tenant prefilter, interpretation version, control readiness | Customer review | which controls need attention, why, and what next action is recommended | none |
| Released Customer Review detail | Detail / Report / Evidence | Read-only detail report | Review supporting evidence for a surfaced control | sectioned detail page with in-body drilldown | forbidden | in-body evidence pointers only after the mapped control explanation | none | /admin/reviews/workspace | /admin/t/{tenant}/reviews/{record} | workspace, tenant, released review, interpretation version, evidence basis | Customer review | why this control is in its current state and what evidence 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 | Customer reviewer, customer admin, or auditor with read access | Decide which control areas need follow-up conversation and which are sufficiently evidenced for the current review cycle | Read-only workspace review overview | Which control areas matter now, what evidence supports them, and what should happen next? | mapped control states, evidence basis summary, accepted-risk influence, and next recommendation | release lineage, deeper evidence detail, and secondary diagnostics only after drilldown | control readiness, evidence completeness/freshness, accepted-risk influence, release state | none | Open released review | none |
| Released Customer Review detail | Customer reviewer, customer admin, or auditor with read access | Understand why a mapped control has its current state and what evidence or accepted-risk context supports that view | Read-only detail report | Why does this control read this way, and what supports or limits that interpretation? | per-control explanation, linked findings, evidence basis, accepted-risk context, interpretation version, and next recommendation | deeper proof metadata and support-only diagnostics | control readiness, evidence sufficiency, accepted-risk timing, interpretation version | none | Review supporting evidence | none |

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

- **New source of truth?**: yes
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: yes
- **New enum/state/reason family?**: yes
- **New cross-domain UI framework/taxonomy?**: yes
- **Current operator problem**: Existing customer review truth already references canonical controls, but customers still consume technical findings and evidence fragments without one bounded customer-safe control/readiness meaning layer.
- **Existing structure is insufficient because**: Raw canonical control references alone do not explain customer-safe readiness meaning, evidence sufficiency, accepted-risk influence, or next action, and page-local copy would drift across workspace and detail surfaces.
- **Narrowest correct implementation**: Introduce exactly one versioned interpretation overlay and use it in one current review path so the same mapped control meaning appears in the workspace summary and released review detail without adding a framework engine or new persistence.
- **Ownership cost**: Maintain one interpretation catalog/version, one customer-safe readiness vocabulary, one shared summary contract, and focused review/evidence tests that prove consistency and non-overstatement.
- **Alternative intentionally rejected**: A copy-only local rewrite was rejected because it would not make the interpretation version explicit or reusable. A multi-framework compliance engine was rejected because it would import broad permanent complexity before a single customer-safe overlay is proven.
- **Release truth**: current-release moat and sellability blocker, not future-release 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.

Canonical replacement is preferred over preservation.

## 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 control-reference reuse, customer-safe disclosure, interpretation-version visibility, no-certification wording, tenant isolation, and evidence-link gating. One bounded browser smoke remains justified because the slice materially changes default-visible decision content on an existing review surface.
- **New or expanded test families**: expand the existing `Reviews/CustomerReviewWorkspace` and `TenantReview` feature families; keep exactly one bounded browser smoke around the customer review workspace flow
- **Fixture / helper cost impact**: low to moderate. Reuse existing tenant review evidence builders, canonical control references, released review fixtures, findings, accepted-risk truth, and evidence snapshot helpers rather than introducing new provider or queue-heavy defaults.
- **Heavy-family visibility / justification**: exactly one browser smoke stays explicit because this slice is about customer-safe wording and disclosure on a real rendered page. No broader 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, interpretation consistency, and partial/unmapped states; the existing bounded smoke remains the only required browser proof.
- **Reviewer handoff**: Reviewers must confirm that the same control/readiness meaning appears in workspace and detail views, that interpretation version is explicit, that no surface implies certification or legal attestation, that unauthorized tenant targets leak nothing, and that deeper proof remains capability-gated.
- **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/TenantReview/TenantReviewCanonicalControlReferenceTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.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`
  - `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 versioned interpretation overlay over existing canonical control references already present in review composition
- customer-safe control/readiness summaries in the existing customer review workspace and released review detail flow
- per-control linkage to existing findings, evidence basis, accepted-risk context, and recommended next action
- explicit interpretation-version disclosure wherever the mapped control/readiness view appears
- explicit separation between technical findings and customer-safe interpretation so the product does not overstate compliance claims
- explicit partial, unmapped, stale, unavailable, or accepted-risk-influenced states when the evidence basis does not support a stronger claim
- reuse of existing entitlement, redaction, localization, review, evidence, and audit foundations
- one shared interpretation contract reused across the current review surfaces so future review/export work can build on the same meaning rather than retranslate it

### Non-Goals

- certification claims or legal/regulatory guarantees
- hard-coded BSI, NIS2, CIS, ISO, or similar framework semantics in platform core
- multiple overlay families, customer profiles, or framework-specific scorecards in v1
- a parallel reporting engine, new review-pack format, or recurring governance-package system
- new persistence tables, new review publication lifecycle, or a separate compliance artifact family
- new panel, portal, customer shell, or identity plane
- raw evidence payload viewers, provider-debug views, or support-only diagnostics in the customer-safe default path
- remediation, authoring, publication, generation, or other write paths
- a new global-searchable resource or widened cross-tenant discovery behavior

## Dependencies

- existing `CanonicalControlCatalog` and `CanonicalControlResolver`
- existing canonical control references already surfaced through tenant review composition
- existing `TenantReviewSectionFactory` and `TenantReviewComposer`
- existing evidence snapshot, finding, and accepted-risk workflow truth
- existing `CustomerReviewWorkspace` and released review detail surfaces
- customer review productization foundations defined in `specs/258-customer-review-productization/spec.md`
- existing workspace and tenant RBAC plus evidence-link capability enforcement

## Assumptions

- Canonical control references already flowing through tenant review composition remain authoritative starting points for the first overlay.
- The current Filament v5 and Livewire v4 admin-plane customer review workspace remains the canonical entry surface for v1; no new provider registration or panel path is needed.
- One interpretation version identifier can be carried through existing review payloads and surfaces without inventing a new persistence family.
- Existing evidence snapshots already contain enough finding and accepted-risk truth to support one customer-safe control/readiness view.
- Existing panel assets are sufficient; this slice does not justify new global or on-demand asset registration.
- Review-pack packaging and framework-specific overlays can remain follow-up work once one customer-safe interpretation path is proven.

## Risks

- If the mapped control/readiness wording sounds too definitive, customers could misread the feature as legal attestation rather than product interpretation.
- Some released reviews may contain sparse canonical control coverage, forcing partial or unmapped states until more evidence references are present.
- If workspace and detail surfaces compute the interpretation separately, the same control could drift between surfaces; the implementation must preserve one shared meaning path.
- Over-eager implementation could smuggle in framework naming or export packaging changes because those follow-ups are adjacent; this spec must keep them deferred.
- If interpretation version is not visible and traceable, later review history could become harder to defend or compare safely.

## Candidate Selection Rationale

- **Selected candidate**: Compliance Evidence Mapping v1
- **Source locations**:
  - `docs/product/spec-candidates.md` active P2 candidate
  - `docs/product/roadmap.md` compliance moat / executive review follow-through ordering
  - `docs/product/implementation-ledger.md` open gap `Compliance-oriented control mapping is not productized`
  - `specs/258-customer-review-productization/spec.md` explicit deferral of this follow-up
  - existing repo seams around canonical controls, tenant reviews, evidence snapshots, and the customer review workspace
- **Why selected**: This is the next unspecced candidate that both roadmap docs and repo truth support after the completed customer-review productization prep. It unlocks a reusable customer-safe interpretation layer that governance packaging depends on.
- **Why this is the smallest viable implementation slice**: The repo already has canonical control references, review composition, evidence truth, and the customer review workspace. The missing piece is one bounded customer-safe interpretation overlay over that truth, not a new control foundation or reporting engine.
- **Intentional narrowing from source candidate**: This slice deliberately limits itself to one overlay family and the current review surfaces. Multi-framework overlays, management packaging, and broader export presentation remain follow-up work.
- **Why close alternatives are deferred**:
  - Governance-as-a-Service Packaging v1 remains deferred because it depends on this shared interpretation layer before it can package the meaning safely.
  - External Support Desk / PSA Handoff is a separate commercialization lane and does not unblock the compliance-readiness story.
  - Private AI Execution Governance Foundation is a later architecture lane and does not address the current customer-safe control/readiness gap.

## Follow-up Candidates

- Governance-as-a-Service Packaging v1 once this customer-safe interpretation layer can be reused in one management-ready package
- framework-specific overlays only after one shared canonical interpretation path is proven and bounded
- review-pack or export reuse of the same interpretation contract once the current review-surface meaning is stable

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Understand control readiness at a glance (Priority: P1)

An authorized customer reviewer wants the customer review workspace to explain which control areas currently need follow-up, what evidence basis exists, and what next action is recommended without manually translating raw findings.

**Why this priority**: This is the core moat and sellability gap. If the workspace still reads like raw technical findings, the feature fails.

**Independent Test**: Sign in as an entitled read-only actor, open the customer review workspace, and confirm that the latest released review for each visible tenant shows a customer-safe control/readiness summary with evidence basis and next recommendation.

**Acceptance Scenarios**:

1. **Given** an entitled actor has access to a tenant with a released review and canonical control references, **When** they open the customer review workspace, **Then** they see only entitled tenants and a customer-safe control/readiness summary for the current released review.
2. **Given** a surfaced control has linked findings, evidence, or accepted-risk context, **When** the actor scans the workspace summary, **Then** they can understand the control state, supporting evidence basis, and recommended next action without opening raw diagnostics.
3. **Given** a released review has no mapped canonical control references for the first overlay, **When** the actor opens the workspace, **Then** the surface shows an explicit partial or unmapped state rather than fabricating control coverage.

---

### User Story 2 - Understand why a control reads this way (Priority: P1)

An authorized customer reviewer wants the released review detail to explain why a mapped control has its current state so they can trust the interpretation and review the supporting evidence without seeing operator-only residue.

**Why this priority**: Productization is incomplete if the workspace summary is calm but the first drilldown still forces technical translation.

**Independent Test**: Open a released review from the workspace and verify that each surfaced control explains linked findings, evidence basis, accepted-risk influence, interpretation version, and next recommendation while keeping raw provider detail hidden by default.

**Acceptance Scenarios**:

1. **Given** a released review contains mapped control data, **When** the actor opens the released review detail, **Then** they see why each surfaced control has its current state through linked findings, evidence basis, accepted-risk context, and recommendation.
2. **Given** deeper proof context exists, **When** the actor stays on the default detail view, **Then** raw payloads, provider IDs, and support-only diagnostics remain hidden until explicit drilldown and capability checks.
3. **Given** the evidence basis is incomplete, stale, or partially mapped, **When** the actor reviews the control explanation, **Then** the state is clearly partial or limited rather than overstated as satisfied or compliant.

---

### User Story 3 - Trust the interpretation basis and its limits (Priority: P2)

An authorized customer reviewer wants to see which interpretation version they are reading and to understand that the product is surfacing technical governance truth rather than claiming formal certification.

**Why this priority**: Versioned interpretation and bounded claims are what make this layer auditable and safe to reuse later.

**Independent Test**: Open the workspace and released review detail, verify interpretation-version visibility and bounded claim language, and confirm that out-of-scope tenant or gated evidence requests do not leak additional truth.

**Acceptance Scenarios**:

1. **Given** a mapped control/readiness view is shown, **When** the actor views the workspace or released review detail, **Then** the interpretation version and a bounded non-certification disclosure are visible.
2. **Given** the actor targets a tenant outside their scope or a gated evidence link they cannot use, **When** they open that route, **Then** the system reveals no cross-tenant presence and only shows explicit denial or unavailability for in-scope secondary paths.
3. **Given** interpretation rules change in a later release, **When** an older released review is inspected, **Then** its surfaced control/readiness view still identifies the interpretation version that produced it.

### Edge Cases

- What happens when the released review has findings but no canonical control references for the first overlay? The customer-safe surface shows an explicit unmapped or partial state rather than inventing control coverage.
- What happens when a control has accepted-risk context that weakens the recommendation? The summary shows the accepted-risk influence and does not present the same state as an unaccepted open issue.
- What happens when evidence exists but is stale or incomplete? The control view remains explicit about the limited basis and does not collapse into a stronger readiness claim.
- What happens when a user enters through a saved filter or tenant-prefilter for an inaccessible tenant? The filter resolves safely without exposing the tenant or its mapped control state.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces no Microsoft Graph calls, no new write path, no new queue or scheduled work, and no new persistence table. It changes review-surface disclosure, shared interpretation semantics, and existing review payload content.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** This follow-up must justify the new interpretation layer as the minimum shared semantic addition needed now, keep it versioned and bounded, and avoid speculative multi-framework modeling or new persistence.

**Constitution alignment (XCUT-001):** The feature must extend existing canonical control, review, evidence, accepted-risk, localization, and audit paths rather than invent a page-local compliance vocabulary.

**Constitution alignment (DECIDE-AUD-001 / OPSURF-001):** Default-visible content must remain decision-first and customer-safe, with deeper evidence detail revealed only after explicit user intent.

**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 evidence access remains capability-gated inside an established scope. No new role 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 reporting flow with one dominant inspect action and no destructive or mutation actions.

### 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 mapped control/readiness summary from existing canonical control references, findings, accepted-risk truth, evidence snapshots, and released review truth without creating a new persistence table or a parallel reporting engine.
- **FR-003**: The system MUST introduce one explicit versioned interpretation overlay for customer-safe control/readiness meaning and MUST identify that version anywhere the mapped control/readiness view is displayed.
- **FR-004**: The default workspace path MUST show only entitled tenants and only released or otherwise customer-safe reviews as the basis for the control/readiness view.
- **FR-005**: The default-visible workspace summary MUST answer which control areas need follow-up, what evidence basis exists, whether accepted risk changes the interpretation, and what next action is recommended.
- **FR-006**: Mapped control summaries MUST clearly separate technical findings from customer-safe interpretation and MUST NOT claim certification, legal compliance, or framework attestation.
- **FR-007**: The released review detail surface MUST explain why each surfaced control has its current state through linked findings, evidence basis, accepted-risk context, and recommendation.
- **FR-008**: The feature MUST make unmapped, incomplete, stale, unavailable, and accepted-risk-influenced states explicit and MUST NOT silently collapse them into passing or fully ready states.
- **FR-009**: Raw payloads, provider IDs, and support-only diagnostics MUST remain hidden by default and MUST be revealed only through explicit drilldown and existing capability checks.
- **FR-010**: The primary action from the workspace MUST remain opening the released review, and any secondary evidence or proof link MUST NOT compete with operator, mutation, or admin-only actions.
- **FR-011**: Interpretation labels and readiness wording MUST reuse shared canonical control and review semantics rather than page-local mappings.
- **FR-012**: When launched from tenant-scoped context, the workspace MUST preserve a safe tenant prefilter and return path without widening discovery beyond entitled tenants.
- **FR-013**: Non-members or out-of-scope workspace or tenant requests MUST resolve as deny-as-not-found, while actors inside an established scope MAY receive explicit capability denial only for gated secondary evidence paths.
- **FR-014**: The interpretation version and displayed control/readiness summaries MUST remain traceable through existing review and audit truth so later reviewers can identify which mapping produced a surfaced state.
- **FR-015**: The feature MUST NOT introduce a new global-searchable resource or broaden existing search discovery in a way that reveals review, control, or evidence artifacts across tenant boundaries.
- **FR-016**: Customer-facing labels and guidance introduced by this slice MUST remain localization-ready for the existing DE/EN product language posture.
- **FR-017**: The feature MUST expose no destructive, remediation, authoring, publishing, generation, or admin-only actions in the customer-safe mapped control/readiness path.
- **FR-018**: The same mapped control/readiness meaning for a released review MUST remain consistent between workspace summary and released review detail.
- **FR-019**: The feature MUST establish one shared interpretation contract reused across the current review surfaces so later review or export work can consume the same meaning without redefining it.
- **FR-020**: Framework-specific overlays, management packaging, and certification claims MUST remain explicitly out of scope for this version.

## 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 create CTA | `N/A` | `N/A` | yes | One primary inspect path keeps the mapped control summary scan-first and avoids parallel evidence-link clutter on the list surface |
| Released Customer Review detail | existing tenant-scoped released review detail surface | none by default | `N/A` | `N/A` | none | `N/A` | no new dominant header action; supporting evidence stays in-body and capability-gated | `N/A` | yes | The mapped control/readiness view is explanatory, not mutating; no destructive or generation action is introduced |

Action Surface Contract is satisfied for this slice. Each affected surface keeps one primary inspect/open 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 surfaces, using explicit empty states, and keeping the control/readiness emphasis aligned to shared review semantics rather than page-local visual language.

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

- **Control Interpretation Overlay Version**: The bounded version label that states which customer-safe interpretation rules produced the displayed control/readiness summaries.
- **Customer Control Summary**: A derived per-control summary for one released review that combines readiness meaning, evidence basis, accepted-risk influence, and next recommendation without becoming a new persisted entity family.
- **Canonical Control Reference**: The existing shared control reference already flowing through tenant review composition and anchoring which controls may be surfaced in the first overlay.
- **TenantReview**: The existing released review artifact that anchors the customer-safe review flow and detail context.
- **Finding**: The existing issue-level governance truth that feeds the control interpretation and recommendation framing.
- **Accepted Risk Decision**: The existing accepted-risk or exception truth that can change how a control state is presented to the customer.
- **EvidenceSnapshot**: The existing supporting proof artifact that informs evidence basis summaries and deeper proof drilldown.
- **AuditLog**: The existing audit trail used to keep interpretation access and version context traceable without introducing a new audit store.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: An entitled read-only actor can answer which control areas need follow-up, why they read that way, and what next action is recommended from the current customer review flow in two interactions or fewer.
- **SC-002**: In 100% of validated customer-safe scenarios, the workspace and released-review detail surfaces show the same mapped control/readiness meaning and interpretation version for the same released review.
- **SC-003**: In 100% of validated unauthorized workspace, tenant, or gated-evidence scenarios, the feature reveals no cross-tenant control, review, or evidence presence.
- **SC-004**: In 100% of validated mapped-control scenarios, the surface clearly distinguishes technical governance truth from customer-safe interpretation and makes no certification or legal-attestation claim.
- **SC-005**: Reviews lacking sufficient mapped control data show an explicit partial or unmapped state rather than falsely implying complete coverage or readiness.