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](../../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](../../apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php) and [../../apps/platform/app/Services/TenantReviews/TenantReviewComposer.php](../../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](../../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](../../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](../../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) 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](../../apps/platform/bootstrap/providers.php) with no change expected.
- [../../apps/platform/app/Filament/Resources/TenantReviewResource.php](../../apps/platform/app/Filament/Resources/TenantReviewResource.php), [../../apps/platform/app/Filament/Resources/ReviewPackResource.php](../../apps/platform/app/Filament/Resources/ReviewPackResource.php), and [../../apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php](../../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.