# Quickstart: Governance Friction Hardening and Operator Vocabulary ## Goal Bring in-scope governance actions under one bounded semantics contract so that similar operator decisions use the same friction class, reason burden, danger semantics, and vocabulary across tenant, workspace, and system surfaces. ## Implementation Sequence 1. Introduce the shared semantics catalog. - Add the Spec 194 governance catalog and its enums. - Define the canonical families, friction classes, reason rules, and approved deviations. - Add the spec guard so new governance actions cannot appear without a declared family rule. 2. Align the highest-risk families first. - Refactor `FindingExceptionsQueue` and `ViewFindingException` around one exception-decision family. - Refactor `ViewTenantReview` so publish and archive semantics are clearly distinct from export. - Refactor evidence snapshot actions so refresh and expiry no longer behave like equivalent mutations. - Refactor `System ViewRun` so retry, cancel, and mark investigated clearly communicate different severity. 3. Extend service-level reason and audit propagation where the new family rules require it. - Keep existing services as mutation owners. - Add or standardize reason inputs and audit metadata only where F2 or F3 requires it. - Preserve existing `OperationRun` and notification behavior. 4. Align supporting lifecycle families. - Harmonize finding close and reopen semantics. - Harmonize tenant archive and restore semantics across view and edit pages. - Verify `TenantlessOperationRunViewer` remains context-first and does not invent local triage semantics. 5. Add regression protection and browser verification. - Add the spec guard and unit coverage for the catalog. - Extend focused feature and RBAC tests on the affected surfaces. - Add one browser smoke suite that exercises the highest-risk family flows. ## Suggested Source Files - `apps/platform/app/Support/Ui/GovernanceActions/Enums/GovernanceFrictionClass.php` - `apps/platform/app/Support/Ui/GovernanceActions/Enums/GovernanceReasonPolicy.php` - `apps/platform/app/Support/Ui/GovernanceActions/GovernanceActionRule.php` - `apps/platform/app/Support/Ui/GovernanceActions/GovernanceActionCatalog.php` - `apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php` - `apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php` - `apps/platform/app/Filament/Resources/FindingResource.php` - `apps/platform/app/Filament/Resources/FindingResource/Pages/ViewFinding.php` - `apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php` - `apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php` - `apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php` - `apps/platform/app/Filament/System/Pages/Ops/ViewRun.php` - `apps/platform/app/Filament/Resources/TenantResource.php` - `apps/platform/app/Filament/Resources/TenantResource/Pages/ViewTenant.php` - `apps/platform/app/Filament/Resources/TenantResource/Pages/EditTenant.php` - `apps/platform/app/Services/Findings/FindingExceptionService.php` - `apps/platform/app/Services/Findings/FindingWorkflowService.php` - `apps/platform/app/Services/Evidence/EvidenceSnapshotService.php` - `apps/platform/app/Services/TenantReviews/TenantReviewLifecycleService.php` - `apps/platform/app/Services/SystemConsole/OperationRunTriageService.php` ## Suggested Test Files - `apps/platform/tests/Feature/Guards/Spec194GovernanceActionSemanticsGuardTest.php` - `apps/platform/tests/Unit/Ui/GovernanceActions/GovernanceActionCatalogTest.php` - `apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php` - `apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueTest.php` - `apps/platform/tests/Feature/Findings/FindingExceptionWorkflowTest.php` - `apps/platform/tests/Feature/Findings/FindingExceptionRenewalTest.php` - `apps/platform/tests/Feature/Findings/FindingExceptionRevocationTest.php` - `apps/platform/tests/Feature/Findings/FindingWorkflowViewActionsTest.php` - `apps/platform/tests/Feature/Findings/FindingAuditLogTest.php` - `apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php` - `apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php` - `apps/platform/tests/Feature/TenantReview/TenantReviewLifecycleTest.php` - `apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php` - `apps/platform/tests/Feature/Operations/SystemRunBlockedExecutionNotificationTest.php` - `apps/platform/tests/Feature/Rbac/TenantLifecycleActionVisibilityTest.php` - `apps/platform/tests/Feature/Rbac/EditTenantArchiveUiEnforcementTest.php` - `apps/platform/tests/Feature/Rbac/TenantResourceAuthorizationTest.php` - `apps/platform/tests/Feature/Audit/TenantLifecycleAuditLogTest.php` - `apps/platform/tests/Browser/Spec194GovernanceFrictionSmokeTest.php` ## Minimum Verification Commands Run all commands through Sail from `apps/platform`. ```bash cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Ui/GovernanceActions/GovernanceActionCatalogTest.php cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/Spec194GovernanceActionSemanticsGuardTest.php cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingExceptionWorkflowTest.php cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Evidence/EvidenceSnapshotResourceTest.php cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantReview/TenantReviewLifecycleTest.php cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/TenantLifecycleActionVisibilityTest.php cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec194GovernanceFrictionSmokeTest.php cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent ``` ## Manual Acceptance Checklist 1. Open `FindingExceptionsQueue` and verify that approve and reject use the expected friction and reason semantics. 2. Open `ViewFindingException` and verify that renew and revoke are clearly differentiated in severity and rationale burden. 3. Open `ViewTenantReview` and verify that publish, export, and archive no longer read like equivalent lifecycle peers. 4. Open an evidence snapshot detail page and verify that refresh remains lighter than expire. 5. Open `System ViewRun` and verify that retry, cancel, and mark investigated communicate different seriousness. 6. Open `ViewTenant` and `EditTenant` and verify that archive and restore remain semantically aligned across both surfaces. 7. Confirm browser smoke checks show no JavaScript errors on the remediated governance surfaces. ## Deployment Notes - No migration is expected. - No provider registration change is expected; Laravel 11+ provider registration remains in `bootstrap/providers.php`. - No new asset registration is expected. Existing deploy handling of `cd apps/platform && php artisan filament:assets` remains sufficient.