37 KiB
Implementation Plan: Compliance Evidence Mapping v1
Branch: 259-compliance-evidence-mapping | Date: 2026-04-30 | Spec: spec.md
Input: Feature specification from 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 page and the existing released-review detail flow anchored by ../../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 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 and ../../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 and ../../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 to derive one customer-safe control interpretation section inside the existing review section family.
- ../../apps/platform/app/Services/TenantReviews/TenantReviewComposer.php to carry
interpretation_versionplus compact mapped-control summaries into the existingTenantReview.summarypayload so workspace and detail surfaces stay aligned. - ../../apps/platform/app/Models/TenantReview.php and ../../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 to keep workspace access on the current latest-published and tenant-entitlement seams.
- ../../apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php and ../../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 reviewpath. - ../../apps/platform/app/Filament/Resources/TenantReviewResource.php and ../../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 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 and ../../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 and ../../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/Reviews/CustomerReviewWorkspacePageTest.php, ../../apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php, ../../apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceNavigationContextTest.php, ../../apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php, ../../apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php, ../../apps/platform/tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php, ../../apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php, ../../apps/platform/tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php, and ../../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 and ../../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.summaryfor workspace consumption and one detailed control-explanation section inTenantReviewSectionfor 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 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 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 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, andEvidenceSnapshotResourceare 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 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 and ../../apps/platform/app/Services/Audit/WorkspaceAuditLogger.php as the only audit path.
- Existing
customer_review_workspace.opened,tenant_review.opened, andevidence_snapshot.openedaction 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_summaryevidence entries and ../../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 detailedTenantReviewSectionentry 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, andaccepted-risk-influencedshould remain overlay-local derived semantics, not a new platform-wide lifecycle/state framework. - Keep supporting proof anchored to existing
EvidenceSnapshottruth 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 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 reviewpath, 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 and ../../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, andinterpretation 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-featurefor the bounded v1 overlay;follow-up-specfor 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
404boundaries. - RBAC-UX plane separation: PASS. All changes remain in the existing
/adminplane 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, andEvidenceSnapshotResourceare 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
TenantReviewandTenantReviewSectionpayloads 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, 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, data-model.md, quickstart.md, and 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.phpexport 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.phpexport 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
404isolation 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-featurefor contained metadata or helper-shape notes;reject-or-splitfor 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)
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)
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
TenantReviewsummary 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
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
TenantReviewandTenantReviewSectionpayloads 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 copilotmust run after the design artifacts are generated, even if it results in no technology changes
Artifacts:
- data-model.md
- contracts/compliance-evidence-mapping.openapi.yaml
- 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.mdas the repo workflow expects.
Phase 2 — Planning (for tasks.md)
Dependency-ordered outline for the later tasks.md step:
- 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.
- Extend
TenantReviewSectionFactoryandTenantReviewComposerto persistinterpretation_version, compact control summaries, and detailed per-control explanations into existing review payloads and sections. - Update
CustomerReviewWorkspaceand its Blade intro to read the shared overlay contract, show interpretation-version and non-certification disclosure, preserve tenant-safe prefilter behavior, and keepOpen released reviewas the one dominant action. - 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.
- Reuse existing evidence routes and audit events, enriching shared metadata with interpretation-version context where needed.
- 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, 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.
ComplianceEvidenceMappingV1derives one storedcontrol_interpretationcontract 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 carrysource_surface,review_idwhere applicable,tenant_filter_id, andinterpretation_version; no new audit event family was required. - Global-search safety outcome: PASS.
TenantReviewResource,ReviewPackResource, andEvidenceSnapshotResourceremain 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 reviewas the only row action. - Document-in-feature decision: T023 closed as metadata reuse at existing call sites.
WorkspaceAuditLoggerandAuditActionIddid 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.