TenantAtlas/specs/260-governance-service-packaging/quickstart.md

Quickstart — Governance-as-a-Service Packaging v1

Preconditions

• Docker is running and the Sail stack for apps/platform is available.
• The feature stays inside the existing Laravel monolith and current 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 GovernancePackage persistence family, no new report engine, no new schedule or batch path, no new OperationRun, no new stored-report viewer shell, no global-search expansion, and no asset strategy change are in scope.
• The management-ready path must reuse released-review truth plus existing review-pack, evidence, stored-report-backed evidence, and governance-decision truth.

Intended Implementation Order

1. Review the current workspace, released-review detail, tenant-review composition, review-pack download, artifact-truth, evidence-source, capability, audit, and localization seams so the implementation stays on one shared path.
2. Confirm that package readiness on the workspace can be expressed from current review summary and artifact-truth semantics without introducing a competing package row action.
3. Confirm that the released-review detail surface in customer-workspace mode remains read-only and continues to expose only the current signed package-download seam instead of starting export generation.
4. Tighten ../../apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php and its Blade intro so package readiness, management value, evidence basis, and calm unavailable states are visible at the right disclosure level.
5. Tighten ../../apps/platform/app/Filament/Resources/TenantReviewResource.php and ../../apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php so the released-review detail owns the management-ready summary and keeps one dominant package action.
6. Reuse existing TenantReview.summary, section payloads, and ../../apps/platform/app/Support/Governance/Controls/ComplianceEvidenceMappingV1.php for package wording instead of adding a package-local mapper.
7. Reuse ../../apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php plus current review-pack truth for available, partial, unavailable, expired, and blocked states rather than a new package state family. Use the canonical mapping publishable -> available, internal_only or stale -> partial, blocked or missing_input -> unavailable, historical_only -> expired, and package-level entitlement restrictions -> blocked. If only supporting proof is restricted, keep the package summary readable and mark the affected secondary link unavailable or forbidden. Stale or entitlement-restricted conditions must map to reason codes inside those states, not to a second availability taxonomy.
8. Keep stored reports subordinate to evidence basis; only link to secondary detail when an existing entitled viewer seam already exists.
9. Reuse current audit events and current capability checks for package access, package download, and proof access.
10. Expand only the existing unit, feature, and smoke suites listed below, then run the targeted tests and Pint.

Targeted Validation Commands (after implementation)

• export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/TenantReview/TenantReviewComposerTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.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/Reviews/CustomerReviewWorkspaceAuthorizationTest.php tests/Feature/Reviews/CustomerReviewWorkspaceNavigationContextTest.php tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php tests/Feature/TenantReview/TenantReviewUiContractTest.php tests/Feature/TenantReview/TenantReviewAuditLogTest.php tests/Feature/TenantReview/TenantReviewExecutivePackTest.php tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php tests/Feature/ReviewPack/ReviewPackEntitlementEnforcementTest.php tests/Feature/ReviewPack/ReviewPackValidRiskAcceptanceTest.php tests/Feature/Evidence/ExceptionValidityEvidenceIntegrationTest.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 an actor with workspace scope and open /admin/reviews/workspace.
2. Confirm only entitled tenants appear and that package readiness is shown as information, not as a second competing row action.
3. Confirm the workspace exposes calm management-ready cues built from current review truth, including current evidence basis and current recommended next action.
4. Open a released review and confirm the detail surface owns the package summary and exposes the current package action without showing operator-only export actions.
5. Confirm the package path reuses current review-pack truth and does not trigger generation or a new OperationRun when supporting artifacts are missing.
6. Confirm accepted-risk entries stay distinct from governance-decision follow-up entries, remain bounded to current governance truth, and do not read like a broader decision inbox.
7. Drill into supporting proof where entitled and confirm raw payloads and support-only diagnostics remain secondary.
8. Attempt an out-of-scope tenant or review target and confirm the response remains not found without leaking package, review, or artifact presence.

Notes

• This is a preparation-only package. No application implementation or validation results belong in this planning artifact yet.
• 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, remediation, publication, generation, or provider-changing action belongs on the management-ready package path.
• No branding, profile-variant, or client-specific layout system belongs in v1; Download governance package remains neutral framing over the current export review pack only.
• No new Filament assets are expected. If later implementation unexpectedly registers assets, deployment still requires cd apps/platform && php artisan filament:assets, but this package does not plan such a change.
• The plan assumes current review-pack reuse is the default delivery seam. If implementation proves that no current pack exists for an otherwise eligible released review, the correct v1 behavior is an explicit unavailable or partial state, not a new generation workflow.
• Stored reports stay subordinate source truth. If no current entitled viewer seam exists, the package should stop at truthful evidence-basis disclosure rather than inventing a new route.