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

Quickstart — Compliance Evidence Mapping v1

Preconditions

• Docker is running and the Sail stack for apps/platform is available.
• The feature stays inside the existing Laravel monolith and existing admin plane.
• Filament remains v5 on Livewire v4.
• Panel providers remain registered through ../../apps/platform/bootstrap/providers.php; no provider or panel change is part of this work.
• No new persistence table, no new OperationRun flow, no new portal shell, no new report engine, no global-search expansion, and no asset strategy change are in scope.
• Governance-as-a-Service Packaging and framework-specific overlays remain deferred.

Intended Implementation Order

1. Review the current canonical-control, findings-summary, tenant-review composition, workspace, detail, evidence, and feature-test seams so the change stays on one shared path.
2. Add one fixed v1 interpretation helper near the canonical control or tenant-review composition seams. Keep it single-purpose and versioned instead of building a generic overlay registry.
3. Extend ../../apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php and ../../apps/platform/app/Services/TenantReviews/TenantReviewComposer.php to embed interpretation_version, compact customer control summaries, and one detailed control-explanation section into the existing review payloads.
4. Add narrow access helpers on ../../apps/platform/app/Models/TenantReview.php if needed so both surfaces can read the same embedded contract without re-deriving it.
5. Update ../../apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php and its Blade intro to render interpretation-version disclosure, customer-safe control summaries, explicit limitation states, and one dominant Open released review action.
6. Update ../../apps/platform/app/Filament/Resources/TenantReviewResource.php and ../../apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php so the released-review detail explains the same mapped control meaning, stays read-only in customer-workspace mode, and keeps supporting evidence as capability-gated in-body drilldown.
7. Reuse existing evidence routes and shared audit events, enriching metadata with interpretation-version context where needed instead of inventing a new audit concept.
8. Update existing DE/EN localization keys for customer-safe wording and explicit non-certification disclosure.
9. Expand only the existing review, workspace, detail, evidence, and smoke tests.
10. Run the targeted tests and Pint after implementation.

Targeted Validation Commands (after implementation)

• 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
• export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Planned Smoke Checklist (after implementation)

1. Sign in to /admin as a readonly-capable actor with workspace scope and open /admin/reviews/workspace.
2. Confirm only entitled tenants appear and that the default-visible path uses released reviews only.
3. Confirm the workspace shows the interpretation version, non-certification disclosure, control summaries, limitation states, and one dominant Open released review path.
4. Open a released review and confirm the same interpretation version and mapped control meaning appear on the detail surface.
5. Confirm raw payloads, provider IDs, fingerprints, and support-only diagnostics remain hidden by default in customer-workspace mode.
6. Drill into supporting evidence and confirm the route is capability-gated, tenant-safe, and still tied back to the customer-review flow.
7. Attempt an explicit out-of-scope tenant target and confirm the response remains not found without leaking tenant or review presence.

Notes

• Implementation close-out on 2026-04-30: the package is implemented in the existing review, evidence, audit, localization, and test seams without adding new persistence, assets, providers, panels, OperationRun behavior, or destructive actions.
• Filament remains v5 on Livewire v4.
• Provider registration remains in ../../apps/platform/bootstrap/providers.php with no change expected.
• ../../apps/platform/app/Filament/Resources/TenantReviewResource.php, ../../apps/platform/app/Filament/Resources/ReviewPackResource.php, and ../../apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php remain globally disabled; this slice does not change their search posture.
• No destructive, authoring, publishing, generation, or remediation action belongs on the customer-safe mapped-control path.
• No new Filament assets are expected. If future implementation unexpectedly registers assets, deployment still requires cd apps/platform && php artisan filament:assets, but this package does not plan such a change.
• Governance-as-a-Service Packaging and framework-specific overlays stay outside this spec and should not be folded into implementation tasks for v1.

Implementation Validation Results

• Focused review/evidence/browser regression: ./vendor/bin/sail artisan test --compact tests/Unit/TenantReview/TenantReviewComposerTest.php tests/Feature/TenantReview/TenantReviewCanonicalControlReferenceTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/Reviews/CustomerReviewWorkspaceLaunchLinksTest.php tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php tests/Feature/TenantReview/TenantReviewAuditLogTest.php tests/Feature/Evidence/EvidenceSnapshotResourceTest.php tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php passed with 51 tests and 323 assertions.
• Adjacent contract regression: ./vendor/bin/sail artisan test --compact tests/Feature/Reviews/CustomerReviewWorkspaceAuthorizationTest.php tests/Feature/Reviews/CustomerReviewWorkspaceNavigationContextTest.php tests/Feature/TenantReview/TenantReviewUiContractTest.php tests/Feature/Evidence/EvidenceSnapshotCanonicalControlReferenceTest.php tests/Feature/ReviewPack/ReviewPackResourceTest.php tests/Feature/ReviewPack/ReviewPackWidgetTest.php passed with 43 tests and 225 assertions.
• Formatting: ./vendor/bin/sail bin pint --dirty --format agent passed.
• Browser smoke path: tenant review detail → Open customer workspace → released-review workspace row → Open latest review → customer-workspace review detail, with no browser console or JavaScript errors.