# Implementation Plan: Compliance Evidence Mapping v1 **Branch**: `259-compliance-evidence-mapping` | **Date**: 2026-04-30 | **Spec**: [spec.md](spec.md) **Input**: Feature specification from [spec.md](spec.md) ## Summary Add one bounded, versioned interpretation overlay over the canonical control references already flowing through tenant review composition, then reuse that same overlay in the existing [../../apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php](../../apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php) page and the existing released-review detail flow anchored by [../../apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php](../../apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php). The narrow implementation path is to derive the customer-safe control meaning once from existing review, finding, accepted-risk, and evidence truth, carry the versioned result inside the existing `TenantReview` summary and section payloads, and render those same payloads on both surfaces. This remains an admin-plane Filament v5 surface running on Livewire v4. Provider registration remains in [../../apps/platform/bootstrap/providers.php](../../apps/platform/bootstrap/providers.php) with no change expected. No new panel, provider, OperationRun flow, destructive action, persistence table, report engine, portal, global-search scope, or asset strategy change is planned. Governance-as-a-Service Packaging and framework-specific overlays remain explicitly deferred. ## Technical Context **Language/Version**: PHP 8.4, Laravel 12 **Primary Dependencies**: Filament v5, Livewire v4, Pest v4, existing canonical-control, evidence, tenant-review, RBAC, localization, and audit seams **Storage**: PostgreSQL via existing `tenant_reviews`, `tenant_review_sections`, `evidence_snapshots`, `evidence_snapshot_items`, `findings`, `finding_exceptions`, memberships, and `audit_logs`; no new persistence table planned **Testing**: Pest v4 feature coverage plus one bounded browser smoke on the existing customer review workspace flow **Validation Lanes**: confidence, browser **Target Platform**: Laravel monolith in `apps/platform`, existing `/admin` workspace surface plus existing tenant-scoped `/admin/t/{tenant}` detail and proof reuse **Project Type**: Web application (Laravel monolith with Filament pages and resources) **Performance Goals**: derive the overlay from already-composed review/evidence truth, keep render-time queries tenant-safe and eager-loaded, avoid new Graph calls, and avoid new queue starts during page render **Constraints**: one bounded versioned overlay only; no new table; no parallel report engine; no panel/provider change; no OperationRun UX; no destructive or authoring actions; no global-search expansion; no asset strategy change; no Governance-as-a-Service packaging or framework-specific overlay work **Scale/Scope**: one shared overlay version, one existing workspace page, one existing released-review detail flow, existing evidence proof routes, existing DE/EN localization files, existing audit metadata, and focused expansion of the current review/evidence/browser tests ## Likely Affected Repo Surfaces - [../../apps/platform/app/Support/Governance/Controls/CanonicalControlCatalog.php](../../apps/platform/app/Support/Governance/Controls/CanonicalControlCatalog.php) and [../../apps/platform/app/Support/Governance/Controls/CanonicalControlDefinition.php](../../apps/platform/app/Support/Governance/Controls/CanonicalControlDefinition.php) as the existing provider-neutral control identity, name, summary, and evidence metadata reused by the overlay. - [../../apps/platform/app/Support/Governance/Controls/CanonicalControlResolver.php](../../apps/platform/app/Support/Governance/Controls/CanonicalControlResolver.php) and [../../apps/platform/app/Services/Evidence/Sources/FindingsSummarySource.php](../../apps/platform/app/Services/Evidence/Sources/FindingsSummarySource.php) as the only current control-resolution path feeding review evidence; this feature should not create a second resolver. - [../../apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php](../../apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php) to derive one customer-safe control interpretation section inside the existing review section family. - [../../apps/platform/app/Services/TenantReviews/TenantReviewComposer.php](../../apps/platform/app/Services/TenantReviews/TenantReviewComposer.php) to carry `interpretation_version` plus compact mapped-control summaries into the existing `TenantReview.summary` payload so workspace and detail surfaces stay aligned. - [../../apps/platform/app/Models/TenantReview.php](../../apps/platform/app/Models/TenantReview.php) and [../../apps/platform/app/Models/TenantReviewSection.php](../../apps/platform/app/Models/TenantReviewSection.php) for narrow helper access to the stored overlay contract without adding a new persisted entity family. - [../../apps/platform/app/Services/TenantReviews/TenantReviewRegisterService.php](../../apps/platform/app/Services/TenantReviews/TenantReviewRegisterService.php) to keep workspace access on the current latest-published and tenant-entitlement seams. - [../../apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php](../../apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php) and [../../apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php](../../apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php) for mapped-control summary rows, interpretation-version disclosure, safe tenant-prefilter reuse, and one dominant `Open released review` path. - [../../apps/platform/app/Filament/Resources/TenantReviewResource.php](../../apps/platform/app/Filament/Resources/TenantReviewResource.php) and [../../apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php](../../apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php) for the detailed per-control explanation path, customer-workspace read-only mode, and in-body supporting-evidence placement. - [../../apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php](../../apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php) and existing evidence detail pages only as reused supporting-proof routes when the actor explicitly drills deeper and has the current capability. - [../../apps/platform/app/Services/Audit/WorkspaceAuditLogger.php](../../apps/platform/app/Services/Audit/WorkspaceAuditLogger.php) and [../../apps/platform/app/Support/Audit/AuditActionId.php](../../apps/platform/app/Support/Audit/AuditActionId.php) for shared audit metadata tying workspace entry, review open, and evidence open events back to the interpretation version. - [../../apps/platform/lang/en/localization.php](../../apps/platform/lang/en/localization.php) and [../../apps/platform/lang/de/localization.php](../../apps/platform/lang/de/localization.php) for localization-ready customer-safe wording and non-certification disclosure. - [../../apps/platform/tests/Feature/TenantReview/TenantReviewCanonicalControlReferenceTest.php](../../apps/platform/tests/Feature/TenantReview/TenantReviewCanonicalControlReferenceTest.php), [../../apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php](../../apps/platform/tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php), [../../apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php](../../apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php), [../../apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceNavigationContextTest.php](../../apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceNavigationContextTest.php), [../../apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php](../../apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php), [../../apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php](../../apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php), [../../apps/platform/tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php](../../apps/platform/tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php), [../../apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php](../../apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php), [../../apps/platform/tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php](../../apps/platform/tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php), and [../../apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php](../../apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php) for the bounded proof surface already in the repo. ## Shared Interpretation Path - Keep canonical control resolution exactly where it already happens today: upstream in evidence collection via [../../apps/platform/app/Services/Evidence/Sources/FindingsSummarySource.php](../../apps/platform/app/Services/Evidence/Sources/FindingsSummarySource.php) and [../../apps/platform/app/Support/Governance/Controls/CanonicalControlResolver.php](../../apps/platform/app/Support/Governance/Controls/CanonicalControlResolver.php). The UI must not grow a second control-resolution path. - Introduce one fixed v1 interpretation helper adjacent to the governance controls or tenant-review composition seams, not a generic registry or framework engine. Its only job is to turn existing canonical control references plus review, finding, accepted-risk, and evidence truth into one customer-safe control summary contract with a version label. - Persist the shared result inside existing review truth so both surfaces read the same meaning: a compact control-summary block in `TenantReview.summary` for workspace consumption and one detailed control-explanation section in `TenantReviewSection` for released-review detail. - Keep the overlay version explicit inside that shared payload and reuse it in audit metadata when the actor opens the workspace, opens a released review from that workspace, or drills into supporting evidence. - Preserve one dominant inspect path. The workspace remains scan-first and opens the released review. Supporting evidence or export affordances must not compete with that path and should stay secondary, preferably inside the detail surface rather than as a second peer action on the list. ## UI / Filament & Livewire Fit - Keep [../../apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php](../../apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php) as the primary decision surface. No new page, Resource, cluster, panel, portal, or provider is introduced. - Keep the existing customer-workspace query-flag path on [../../apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php](../../apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php) as the secondary context surface. It should deepen the mapped control meaning without reopening operator lifecycle controls. - Preserve Filament v5 plus Livewire v4 admin-plane patterns. Provider registration remains in [../../apps/platform/bootstrap/providers.php](../../apps/platform/bootstrap/providers.php) with no change expected. - Preserve one dominant next action. On the workspace that remains `Open released review`. On the released-review detail surface, the mapped-control explanation is primary and supporting evidence stays in-body and capability-gated rather than becoming a new competing header action. - Keep all touched resources non-search-expanding. `TenantReviewResource`, `ReviewPackResource`, and `EvidenceSnapshotResource` are already globally disabled, and this feature does not change that posture. - No destructive actions are introduced. If existing non-customer detail actions are touched to preserve the customer-workspace mode, they remain outside this slice and continue to rely on `->action(...)`, `->requiresConfirmation()`, and existing authorization when used in their normal operator context. ## RBAC / Policy Fit - Workspace membership remains the first isolation boundary through [../../apps/platform/app/Services/TenantReviews/TenantReviewRegisterService.php](../../apps/platform/app/Services/TenantReviews/TenantReviewRegisterService.php) and current workspace context. - Tenant entitlement remains capability-first and reuse-only. This slice does not add a new role family, raw capability strings, or customer-only policy branch. - Non-members and out-of-scope tenant targets remain `404`. Inside an established scope, optional secondary evidence routes may still return explicit capability denial when the actor lacks the supporting evidence capability. - The workspace continues to show only the latest published review per entitled tenant. Internal-only, draft, or ready-but-unreleased reviews remain outside the default customer-safe path. - Supporting evidence drilldown stays on existing tenant-scoped evidence routes and current policy enforcement. The mapped control overlay does not widen discovery or expose new artifact classes. ## Audit / Logging Fit - Reuse [../../apps/platform/app/Support/Audit/AuditActionId.php](../../apps/platform/app/Support/Audit/AuditActionId.php) and [../../apps/platform/app/Services/Audit/WorkspaceAuditLogger.php](../../apps/platform/app/Services/Audit/WorkspaceAuditLogger.php) as the only audit path. - Existing `customer_review_workspace.opened`, `tenant_review.opened`, and `evidence_snapshot.opened` action IDs are sufficient for the current slice. The narrow follow-up, if needed, is metadata enrichment rather than a new event family. - Planned shared audit metadata should include the source surface, active tenant prefilter when present, review identifier when relevant, and the interpretation version shown to the actor so FR-014 remains traceable without a new audit store. - Passive render should stay quiet. Audit boundaries remain explicit workspace entry, explicit released-review open, and explicit evidence open. ## Data & Query Fit - Keep canonical control references anchored to existing `findings_summary` evidence entries and [../../apps/platform/app/Models/TenantReview.php](../../apps/platform/app/Models/TenantReview.php)`::canonicalControlReferences()` rather than recomputing control identity in page code. - Add the customer-safe interpretation as one bounded embedded contract inside existing review payloads. The likely shape is a compact `summary['control_interpretation']` block for workspace use plus one detailed `TenantReviewSection` entry for released-review detail. - Carry the version identifier with the shared payload at compose time so older published reviews preserve the interpretation version that produced them. Avoid render-time reinterpretation drift between workspace and detail surfaces. - Keep limitation states explicit but bounded. `unmapped`, `partial`, `stale`, `unavailable`, and `accepted-risk-influenced` should remain overlay-local derived semantics, not a new platform-wide lifecycle/state framework. - Keep supporting proof anchored to existing `EvidenceSnapshot` truth and current evidence routes. The overlay should summarize the evidence basis, not create a second proof model. - Avoid touching [../../apps/platform/app/Services/Evidence/Sources/FindingsSummarySource.php](../../apps/platform/app/Services/Evidence/Sources/FindingsSummarySource.php) unless implementation proves a missing normalized field blocks a single shared interpretation pass. The default plan is to consume its current canonical-control and governance-state output as-is. ## UI / Surface Guardrail Plan - **Guardrail scope**: changed surfaces - **Native vs custom classification summary**: native Filament - **Shared-family relevance**: status messaging, review summaries, detail disclosure, evidence viewers, recommendation phrasing, and navigation entry points - **State layers in scope**: page, detail, URL-query, table/session restore - **Audience modes in scope**: customer/read-only, customer-admin, auditor-read-only, operator-MSP - **Decision/diagnostic/raw hierarchy plan**: decision-first, diagnostics-second, support-raw-third - **Raw/support gating plan**: collapsed by default and capability-gated on reused evidence/detail routes only - **One-primary-action / duplicate-truth control**: the workspace keeps one dominant `Open released review` path, the detail page stays explanation-first, and the mapped control meaning is authored once in the shared overlay contract rather than duplicated in page-local mappers - **Handling modes by drift class or surface**: review-mandatory - **Repository-signal treatment**: review-mandatory - **Special surface test profiles**: standard-native-filament, shared-detail-family - **Required tests or manual smoke**: functional-core, state-contract, bounded-browser-smoke - **Exception path and spread control**: none planned; any proposal for a page-local mapper, new portal surface, or framework-specific overlay becomes exception-required drift - **Active feature PR close-out entry**: Guardrail / Smoke Coverage ## Shared Pattern & System Fit - **Cross-cutting feature marker**: yes - **Systems touched**: `CanonicalControlCatalog`, `CanonicalControlResolver`, `FindingsSummarySource`, `TenantReviewSectionFactory`, `TenantReviewComposer`, `CustomerReviewWorkspace`, `TenantReviewResource`, `ViewTenantReview`, `EvidenceSnapshotResource`, `WorkspaceAuditLogger`, `AuditActionId`, and review localization copy - **Shared abstractions reused**: canonical control definitions and resolver output, existing review summary and section payloads, existing workspace and tenant-scoped routes, current capability checks, and the shared audit logger - **New abstraction introduced? why?**: one bounded v1 interpretation helper is expected because current repo seams identify canonical controls but do not yet produce a customer-safe, versioned control/readiness contract reusable across surfaces - **Why the existing abstraction was sufficient or insufficient**: existing seams already provide the released review truth, control references, accepted-risk signals, evidence basis, and UI surfaces; what is missing is one shared interpretation contract, not a new persistence or routing foundation - **Bounded deviation / spread control**: keep the interpretation helper fixed to one overlay version and current review surfaces; packaging and framework-specific overlays are explicitly deferred to later specs ## OperationRun UX Impact - **Touches OperationRun start/completion/link UX?**: no - **Central contract reused**: `N/A` - **Delegated UX behaviors**: `N/A` - **Surface-owned behavior kept local**: read-only workspace, detail, and evidence rendering only - **Queued DB-notification policy**: `N/A` - **Terminal notification path**: `N/A` - **Exception path**: none ## Provider Boundary & Portability Fit - **Shared provider/platform boundary touched?**: yes - **Provider-owned seams**: Microsoft-specific subject binding and signal resolution inside [../../apps/platform/app/Support/Governance/Controls/CanonicalControlResolver.php](../../apps/platform/app/Support/Governance/Controls/CanonicalControlResolver.php) and [../../apps/platform/app/Services/Evidence/Sources/FindingsSummarySource.php](../../apps/platform/app/Services/Evidence/Sources/FindingsSummarySource.php) - **Platform-core seams**: interpretation version, customer-safe control readiness wording, evidence-basis phrasing, accepted-risk influence wording, recommendation phrasing, and audit metadata tying the shown interpretation back to the released review - **Neutral platform terms / contracts preserved**: `canonical control`, `control readiness`, `evidence basis`, `accepted risk`, `recommendation`, and `interpretation version` - **Retained provider-specific semantics and why**: provider-specific Microsoft bindings remain internal input truth only because they already exist upstream in canonical control resolution; they do not become customer-facing labels - **Bounded extraction or follow-up path**: `document-in-feature` for the bounded v1 overlay; `follow-up-spec` for Governance-as-a-Service packaging or framework-specific overlays if later required ## Constitution Check *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* - Inventory-first / snapshot truth: PASS. The slice derives from existing evidence snapshots and released review truth only. - Read/write separation: PASS. No new mutation, publication, regeneration, remediation, or destructive action is introduced. - Graph contract path: PASS. No new Graph work, provider calls, or contract registry changes are part of this preparation slice. - Deterministic capabilities: PASS. Existing capability registries and role maps remain authoritative. - Workspace and tenant isolation: PASS. Workspace membership and tenant entitlement remain `404` boundaries. - RBAC-UX plane separation: PASS. All changes remain in the existing `/admin` plane and current tenant-scoped detail/proof routes. - Destructive confirmation standard: PASS by non-use. No destructive action is planned for the customer-safe path. - Global search safety: PASS. `TenantReviewResource`, `ReviewPackResource`, and `EvidenceSnapshotResource` are already globally disabled, and no new searchable surface is introduced. - OperationRun / Ops-UX: PASS by non-use. The feature starts no runs and changes no run lifecycle UX. - Data minimization: PASS. Raw payloads, provider IDs, and support-only diagnostics remain hidden by default and only appear through existing gated drilldown. - Test governance (TEST-GOV-001): PASS. Planned proof stays inside focused feature files plus one bounded browser smoke. - Proportionality / no premature abstraction: PASS with constraint. One bounded v1 interpretation helper is justified because the spec requires a shared versioned meaning layer; a generic registry or multi-framework engine is explicitly out of bounds. - Persisted truth (PERSIST-001): PASS. No new table or artifact family is planned; the versioned overlay is carried inside existing `TenantReview` and `TenantReviewSection` payloads only. - Behavioral state (STATE-001): PASS. Readiness buckets and limitation markers stay overlay-local and serve customer-safe decision support; they are not elevated into a cross-domain lifecycle framework. - UI semantics / shared pattern first / Filament-native UI: PASS. Existing Filament pages and review/evidence seams remain the default path, and the shared interpretation contract prevents page-local drift. - Provider boundary (PROV-001): PASS. Provider-specific semantics stay inside existing resolution inputs and do not leak into customer-facing platform-core vocabulary. - Filament / Laravel planning contract: PASS. Filament v5 stays on Livewire v4, provider registration remains in [../../apps/platform/bootstrap/providers.php](../../apps/platform/bootstrap/providers.php), no new panel/provider work is planned, no global-search expansion is planned, and asset handling remains unchanged. - Explicit deferrals: PASS. Governance-as-a-Service Packaging and framework-specific overlays remain out of scope for this version. **Gate evaluation**: PASS. - The narrow path is defensible if the implementation derives the interpretation once during review composition and keeps both UI surfaces on that shared payload. - The plan fails the gate if it drifts into page-local mappers, a new packaging/reporting engine, or a multi-framework taxonomy. **Post-design re-check**: PASS once [research.md](research.md), [data-model.md](data-model.md), [quickstart.md](quickstart.md), and [contracts/compliance-evidence-mapping.openapi.yaml](contracts/compliance-evidence-mapping.openapi.yaml) are present and the agent-context update step is executed. ## Test Governance Check - **Test purpose / classification by changed surface**: Feature for review composition, workspace summary, detail explanation, authorization, navigation context, and evidence drilldown; Browser for one bounded workspace-to-detail smoke - **Affected validation lanes**: confidence, browser - **Why this lane mix is the narrowest sufficient proof**: the existing feature families already cover review composition, customer review workspace behavior, and detail-surface contracts; one existing browser smoke is enough to catch rendered disclosure regressions without creating a new browser family - **Narrowest proving command(s)**: - `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 tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php tests/Feature/Reviews/CustomerReviewWorkspaceNavigationContextTest.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/Evidence/EvidenceSnapshotResourceTest.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` - **Fixture / helper / factory / seed / context cost risks**: moderate but contained; reuse existing tenant review, evidence snapshot, finding, finding-exception, workspace membership, and readonly-actor fixtures - **Expensive defaults or shared helper growth introduced?**: no; new helper use should stay explicit and local to the tenant-review and review-workspace family - **Heavy-family additions, promotions, or visibility changes**: none beyond the already-existing single browser smoke - **Surface-class relief / special coverage rule**: standard-native-filament relief on the workspace page, shared-detail-family coverage on released-review explanation and evidence drilldown - **Closing validation and reviewer handoff**: rerun the focused commands above, verify the same interpretation version and control meaning appear on both surfaces, verify `404` isolation for out-of-scope tenant targets, verify capability-gated evidence drilldown, and verify non-certification wording stays visible - **Budget / baseline / trend follow-up**: none expected beyond small feature-local additions in existing suites - **Review-stop questions**: lane fit, hidden fixture growth, browser sprawl, page-local mapper drift, and framework-scope creep - **Escalation path**: `document-in-feature` for contained metadata or helper-shape notes; `reject-or-split` for any drift into packaging, framework-specific overlays, or a second interpretation path - **Active feature PR close-out entry**: Guardrail / Smoke Coverage - **Why no dedicated follow-up spec is needed**: this package is already the bounded follow-up spec for the customer review productization lane; broader packaging and framework overlay work are explicitly deferred ## Project Structure ### Documentation (this feature) ```text specs/259-compliance-evidence-mapping/ ├── spec.md ├── plan.md ├── research.md ├── data-model.md ├── quickstart.md ├── contracts/ │ └── compliance-evidence-mapping.openapi.yaml └── tasks.md # Created later by /speckit.tasks, not by this plan step ``` ### Source Code (repository root) ```text apps/platform/ ├── app/ │ ├── Filament/ │ │ ├── Pages/Reviews/ │ │ │ └── CustomerReviewWorkspace.php │ │ └── Resources/ │ │ ├── TenantReviewResource.php │ │ ├── TenantReviewResource/Pages/ViewTenantReview.php │ │ └── EvidenceSnapshotResource.php │ ├── Models/ │ │ ├── TenantReview.php │ │ ├── TenantReviewSection.php │ │ ├── EvidenceSnapshot.php │ │ ├── EvidenceSnapshotItem.php │ │ └── FindingException.php │ ├── Services/ │ │ ├── Audit/WorkspaceAuditLogger.php │ │ ├── Evidence/Sources/FindingsSummarySource.php │ │ └── TenantReviews/ │ │ ├── TenantReviewComposer.php │ │ ├── TenantReviewRegisterService.php │ │ └── TenantReviewSectionFactory.php │ ├── Support/ │ │ ├── Audit/AuditActionId.php │ │ └── Governance/Controls/ │ │ ├── CanonicalControlCatalog.php │ │ ├── CanonicalControlDefinition.php │ │ └── CanonicalControlResolver.php ├── config/canonical_controls.php ├── lang/ │ ├── de/localization.php │ └── en/localization.php ├── bootstrap/providers.php └── tests/ ├── Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php ├── Feature/Reviews/ └── Feature/TenantReview/ ``` **Structure Decision**: Laravel monolith. The implementation stays inside the existing `apps/platform` governance, review, evidence, localization, and audit seams, with no new panel/provider location and no new persistence layer. ## Complexity Tracking | Violation | Why Needed | Simpler Alternative Rejected Because | |-----------|------------|-------------------------------------| | One bounded v1 interpretation helper and embedded payload shape | The spec requires one shared, versioned control/readiness meaning reused across workspace and detail surfaces | Page-local copy or two separate mappers would drift across surfaces and would not keep older released reviews traceable to one interpretation version | ## Proportionality Review - **Current operator problem**: customer reviewers still have to translate canonical control references, findings, accepted-risk details, and evidence snapshots into a control/readiness story by hand. - **Existing structure is insufficient because**: current catalog and resolver identify controls, but they do not yet produce one customer-safe, versioned interpretation contract reusable across workspace and detail surfaces. - **Narrowest correct implementation**: introduce one fixed v1 interpretation helper, persist the derived result inside existing `TenantReview` summary and section payloads, and render that same payload on the existing workspace and released-review detail surfaces. - **Ownership cost created**: maintain one overlay version label, one bounded readiness vocabulary, one detailed control explanation section, localized customer-safe copy, and focused review/evidence tests. - **Alternative intentionally rejected**: page-local mappers, a multi-framework overlay engine, Governance-as-a-Service packaging, and a new reporting or portal surface were rejected because they import broad permanent complexity before one shared interpretation path is proven. - **Release truth**: current-release truth. This is the next bounded follow-up after customer review productization, not speculative future infrastructure. ## Phase 0 — Research (output: research.md) Research resolves the remaining implementation-shaping decisions: - keep the existing customer review workspace and released-review detail routes as the only primary and secondary surfaces - derive the interpretation once during tenant review composition and reuse it through existing review payloads instead of page-local mappers - reuse canonical control catalog metadata and current findings-summary resolution rather than adding a second control taxonomy - carry the version label through existing review and audit truth so older released reviews remain traceable - keep supporting evidence on existing evidence routes and current capability checks - keep Governance-as-a-Service packaging and framework-specific overlays explicitly deferred - keep validation inside the current review/evidence feature families plus the single existing browser smoke **Output**: [research.md](research.md) ## Phase 1 — Design (outputs: data-model.md, contracts/, quickstart.md) Design artifacts capture the narrow interpretation shape: - no new table, cache, or report artifact family; the overlay lives inside existing `TenantReview` and `TenantReviewSection` payloads only - one compact workspace contract plus one detailed released-review explanation contract document how the same mapped control meaning is reused across surfaces - one conceptual OpenAPI file documents the existing workspace, released-review detail, and supporting evidence routes that consume the shared overlay - quickstart records the intended implementation order, validation commands, Filament v5 plus Livewire v4 posture, unchanged provider-registration location, and explicit deferrals - `.specify/scripts/bash/update-agent-context.sh copilot` must run after the design artifacts are generated, even if it results in no technology changes **Artifacts**: - [data-model.md](data-model.md) - [contracts/compliance-evidence-mapping.openapi.yaml](contracts/compliance-evidence-mapping.openapi.yaml) - [quickstart.md](quickstart.md) - Required agent-context update executed during planning on 2026-04-30 via `.specify/scripts/bash/update-agent-context.sh copilot`, refreshing `.github/agents/copilot-instructions.md` as the repo workflow expects. ## Phase 2 — Planning (for tasks.md) Dependency-ordered outline for the later `tasks.md` step: 1. Define one fixed v1 interpretation helper near the canonical control or tenant-review composition seams, using existing control references, finding outcomes, accepted-risk truth, and evidence basis only. 2. Extend `TenantReviewSectionFactory` and `TenantReviewComposer` to persist `interpretation_version`, compact control summaries, and detailed per-control explanations into existing review payloads and sections. 3. Update `CustomerReviewWorkspace` and its Blade intro to read the shared overlay contract, show interpretation-version and non-certification disclosure, preserve tenant-safe prefilter behavior, and keep `Open released review` as the one dominant action. 4. Update the released-review detail surface to explain the same mapped control meaning, keep customer-workspace mode read-only, and move supporting evidence access into explicit in-body drilldown rather than competing primary actions. 5. Reuse existing evidence routes and audit events, enriching shared metadata with interpretation-version context where needed. 6. Expand the focused review, workspace, detail, evidence, and smoke tests without introducing a new browser family or a second interpretation path. ## Planning Guardrail Notes - Planning guardrail result: PASS. Filament remains v5 on Livewire v4, provider registration remains in [../../apps/platform/bootstrap/providers.php](../../apps/platform/bootstrap/providers.php), no new panel/provider is expected, no global-search expansion is planned, no destructive action is introduced, and no new asset bundle is planned. - Shared-path result: the plan keeps one interpretation contract reused across composition, workspace, and detail surfaces rather than duplicating logic in local mappers. - Explicit deferral result: Governance-as-a-Service Packaging and framework-specific overlays remain follow-up specs and are not folded into this package. - Preparation workflow result: the required agent-context refresh step has already been completed for this package and does not need a follow-on prep task. ## Implementation Close-Out - Guardrail / Smoke Coverage result: PASS on 2026-04-30. The implementation stayed on Filament v5 plus Livewire v4, did not add a panel/provider/path, did not add assets, did not add persistence, did not add OperationRun behavior, and did not add destructive actions. - Shared-interpretation-path outcome: PASS. `ComplianceEvidenceMappingV1` derives one stored `control_interpretation` contract during review composition; the workspace, released-review detail, and supporting evidence links read that stored payload instead of remapping controls locally. - Audit-metadata reuse outcome: PASS. Existing `customer_review_workspace.opened`, `tenant_review.opened`, `evidence_snapshot.opened`, and review-pack download audit paths carry `source_surface`, `review_id` where applicable, `tenant_filter_id`, and `interpretation_version`; no new audit event family was required. - Global-search safety outcome: PASS. `TenantReviewResource`, `ReviewPackResource`, and `EvidenceSnapshotResource` remain globally disabled; no searchable resource was added. - List-surface review outcome: PASS. The customer review workspace shows entitled tenants with released reviews only, keeps no-released-review as a page-level empty state, shows visible version and non-certification disclosure, and keeps `Open released review` as the only row action. - Document-in-feature decision: T023 closed as metadata reuse at existing call sites. `WorkspaceAuditLogger` and `AuditActionId` did not need code changes because the existing actions already cover the required audit moments. - Follow-up-spec decisions: none required for this v1 implementation. Governance-as-a-Service packaging and framework-specific overlays remain explicitly deferred from this spec.