111 lines
7.0 KiB
Markdown
111 lines
7.0 KiB
Markdown
# 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.
|