ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
acc8947384
TenantAtlas/specs/194-governance-friction-hardening/quickstart.md
ahmido acc8947384 feat: harden governance action semantics (#229) 
## Summary
- add the Spec 194 governance action catalog, friction classes, reason policies, and regression guards
- align exception, review, evidence, finding, tenant, provider connection, and system run actions to the shared semantics model
- add focused feature, RBAC, audit, unit, and browser coverage, including the tenant detail triage header consistency update

## Verification
- ran the focused Spec 194 verification pack from the quickstart and task plan
- ran targeted tenant triage coverage after the detail-header update
- ran `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`

## Filament Notes
- Filament v5 / Livewire v4 compliance preserved
- provider registration remains in `apps/platform/bootstrap/providers.php`
- globally searchable resources were not changed
- destructive actions remain confirmation-gated and server-authorized
- no new Filament assets were introduced; the existing `cd apps/platform && php artisan filament:assets` deploy step stays unchanged

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #229
2026-04-12 21:21:44 +00:00

7.0 KiB
Raw Blame History

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.

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.