ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
866875559f
TenantAtlas/specs/259-compliance-evidence-mapping/plan.md
ahmido 866875559f
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 1m4s
Details
feat(specs/259): compliance evidence mapping (#312) 
Implements platform feature branch `259-compliance-evidence-mapping`.

Target branch: `platform-dev`.

Follow-up integration path after merge:

`platform-dev` -> `dev`.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #312
2026-04-30 21:27:49 +00:00

309 lines
37 KiB
Markdown
Raw Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink