TenantAtlas/specs/259-compliance-evidence-mapping/spec.md

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.