243 lines
18 KiB
Markdown
243 lines
18 KiB
Markdown
# Tasks: Governance Friction Hardening and Operator Vocabulary
|
|
|
|
**Input**: Design documents from `/specs/194-governance-friction-hardening/`
|
|
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `contracts/governance-action-semantics.logical.openapi.yaml`, `quickstart.md`
|
|
|
|
**Tests**: Required. This feature changes runtime behavior on existing Filament v5 / Livewire v4 operator surfaces, so Pest unit, feature, RBAC, audit, and browser smoke coverage must be added or extended.
|
|
|
|
**Organization**: Tasks are grouped by user story so each slice stays independently testable. Recommended delivery order is `US1 -> US2 -> US3 -> US4`, with `US1` as the MVP cut after the shared catalog and guard foundation is in place.
|
|
|
|
## Phase 1: Setup (Shared Infrastructure)
|
|
|
|
**Purpose**: Create the dedicated support and test entry points for Spec 194 without changing runtime behavior yet.
|
|
|
|
- [X] T001 Create the governance action support scaffolds in `apps/platform/app/Support/Ui/GovernanceActions/GovernanceActionCatalog.php`, `apps/platform/app/Support/Ui/GovernanceActions/GovernanceActionRule.php`, `apps/platform/app/Support/Ui/GovernanceActions/Enums/GovernanceFrictionClass.php`, and `apps/platform/app/Support/Ui/GovernanceActions/Enums/GovernanceReasonPolicy.php`
|
|
- [X] T002 [P] Create the Spec 194 unit and guard test scaffolds in `apps/platform/tests/Unit/Ui/GovernanceActions/GovernanceActionCatalogTest.php` and `apps/platform/tests/Feature/Guards/Spec194GovernanceActionSemanticsGuardTest.php`
|
|
- [X] T003 [P] Create the browser smoke scaffold in `apps/platform/tests/Browser/Spec194GovernanceFrictionSmokeTest.php`
|
|
|
|
**Checkpoint**: The new support namespace and dedicated Spec 194 test entry points exist, so shared rule work can begin without mixing this slice into unrelated suites.
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Codify the shared governance semantics inventory and regression gate that every story depends on.
|
|
|
|
**⚠️ CRITICAL**: No user story work should start before this phase is complete.
|
|
|
|
- [X] T004 [P] Add catalog invariant, deterministic F1 reason-policy, and documented-deviation coverage in `apps/platform/tests/Unit/Ui/GovernanceActions/GovernanceActionCatalogTest.php`
|
|
- [X] T005 [P] Add family, surface, vocabulary, indirect risk-acceptance continuity, and exception regression coverage in `apps/platform/tests/Feature/Guards/Spec194GovernanceActionSemanticsGuardTest.php`
|
|
- [X] T006 [P] Implement the friction and reason enums in `apps/platform/app/Support/Ui/GovernanceActions/Enums/GovernanceFrictionClass.php` and `apps/platform/app/Support/Ui/GovernanceActions/Enums/GovernanceReasonPolicy.php`
|
|
- [X] T007 [P] Implement the shared rule value object in `apps/platform/app/Support/Ui/GovernanceActions/GovernanceActionRule.php`
|
|
- [X] T008 Implement the canonical family inventory, surface bindings, deterministic F1 reason defaults, indirect risk-acceptance continuity, and documented deviations in `apps/platform/app/Support/Ui/GovernanceActions/GovernanceActionCatalog.php`
|
|
|
|
**Checkpoint**: The repo can enumerate in-scope governance actions, classify them, and fail CI on undocumented semantic drift before any page-level refactor starts.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Make a Formal Exception Decision Safely (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Make queue and detail exception decisions use one predictable friction, reason, and vocabulary contract.
|
|
|
|
**Independent Test**: Open the finding exceptions queue and one finding exception detail page, then confirm approve, reject, renew, and revoke follow the shared exception-family semantics without changing any review, evidence, run, or tenant lifecycle pages.
|
|
|
|
### Tests for User Story 1
|
|
|
|
> **NOTE**: Write these tests first and confirm they fail before implementation.
|
|
|
|
- [X] T009 [P] [US1] Extend queue selection-state, modal friction, and reason-prompt coverage in `apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php` and `apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueTest.php`
|
|
- [X] T010 [P] [US1] Extend exception lifecycle, authorization, header-discipline, audit, and indirect risk-acceptance vocabulary continuity coverage in `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/FindingExceptionAuthorizationTest.php`, `apps/platform/tests/Feature/Findings/FindingExceptionPolicyTest.php`, and `apps/platform/tests/Feature/Filament/FindingExceptionHeaderDisciplineTest.php`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T011 [US1] Align exception-family reason propagation, canonical audit verbs, and success copy in `apps/platform/app/Services/Findings/FindingExceptionService.php`
|
|
- [X] T012 [US1] Refactor queue decision actions to consume catalog rules in `apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php`
|
|
- [X] T013 [US1] Refactor exception detail lifecycle actions to consume catalog rules and keep revoke as the separated F3 action in `apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php`
|
|
|
|
**Checkpoint**: Exception governance is independently functional and consistent across queue and detail surfaces.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Distinguish Governance Lifecycle from Technical Refresh (Priority: P1)
|
|
|
|
**Goal**: Make review publication or archival and evidence refresh or expiry read as clearly different action families instead of peer mutations.
|
|
|
|
**Independent Test**: Open a tenant review detail page and an evidence snapshot detail page, then confirm publish and archive are distinct from export, while refresh remains lighter than expire, without changing run or tenant lifecycle surfaces.
|
|
|
|
### Tests for User Story 2
|
|
|
|
> **NOTE**: Write these tests first and confirm they fail before implementation.
|
|
|
|
- [X] T014 [P] [US2] Extend review lifecycle, export separation, authorization, and audit coverage in `apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php`, `apps/platform/tests/Feature/TenantReview/TenantReviewLifecycleTest.php`, `apps/platform/tests/Feature/TenantReview/TenantReviewRbacTest.php`, `apps/platform/tests/Feature/TenantReview/TenantReviewAuditLogTest.php`, `apps/platform/tests/Feature/TenantReview/TenantReviewExecutivePackTest.php`, and `apps/platform/tests/Feature/Filament/TenantReviewHeaderDisciplineTest.php`
|
|
- [X] T015 [P] [US2] Extend evidence refresh-versus-expire, authorization, and audit coverage in `apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php` and `apps/platform/tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T016 [P] [US2] Align review lifecycle reason propagation, audit prose, and notification wording in `apps/platform/app/Services/TenantReviews/TenantReviewLifecycleService.php`
|
|
- [X] T017 [US2] Refactor review detail actions so publish and archive follow the catalog while export and create-next stay outside governance friction in `apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php`
|
|
- [X] T018 [P] [US2] Align evidence lifecycle reason propagation, audit prose, and notification wording in `apps/platform/app/Services/Evidence/EvidenceSnapshotService.php`
|
|
- [X] T019 [US2] Refactor evidence list and detail actions so refresh remains F1 and expire follows governed lifecycle rules in `apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php` and `apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php`
|
|
|
|
**Checkpoint**: Review and evidence lifecycle actions are independently functional and semantically distinct from technical refresh or export actions.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Intervene on Runs with Calibrated Severity (Priority: P2)
|
|
|
|
**Goal**: Make retry, mark investigated, and cancel communicate different seriousness on triage-owned run surfaces while preserving calm monitoring context elsewhere.
|
|
|
|
**Independent Test**: Open the system run detail page and the tenantless run viewer, then confirm retry stays lighter than mark investigated and cancel, while the tenantless viewer does not promote undocumented triage actions.
|
|
|
|
### Tests for User Story 3
|
|
|
|
> **NOTE**: Write these tests first and confirm they fail before implementation.
|
|
|
|
- [X] T020 [P] [US3] Extend system run triage severity, reason, and authorization coverage in `apps/platform/tests/Feature/Operations/SystemRunBlockedExecutionNotificationTest.php` and `apps/platform/tests/Feature/RunAuthorizationTenantIsolationTest.php`
|
|
- [X] T021 [P] [US3] Extend calm-surface and no-triage-regression coverage in `apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T022 [US3] Align run-triage reason propagation, audit verbs, and operator copy in `apps/platform/app/Services/SystemConsole/OperationRunTriageService.php`
|
|
- [X] T023 [US3] Refactor the system run header actions so retry, mark investigated, and cancel use calibrated friction, danger, and placement from the catalog in `apps/platform/app/Filament/System/Pages/Ops/ViewRun.php`
|
|
- [X] T024 [US3] Review the tenantless viewer and keep it context-first unless a documented governance binding is required in `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
|
|
|
|
**Checkpoint**: Run triage is independently functional on the system surface without leaking high-friction semantics onto the calm tenantless viewer.
|
|
|
|
---
|
|
|
|
## Phase 6: User Story 4 - Keep Tenant Lifecycle Clear Without Inflating All Actions (Priority: P3)
|
|
|
|
**Goal**: Keep archive and restore consistent across tenant view and edit surfaces without over-hardening lower-risk lifecycle moves.
|
|
|
|
**Independent Test**: Open the tenant view and edit surfaces for active and archived tenants, then confirm archive and restore use the same vocabulary, confirm depth, and danger rules on both pages.
|
|
|
|
### Tests for User Story 4
|
|
|
|
> **NOTE**: Write these tests first and confirm they fail before implementation.
|
|
|
|
- [X] T025 [P] [US4] Extend tenant lifecycle visibility, naming, and authorization coverage in `apps/platform/tests/Feature/Rbac/TenantLifecycleActionVisibilityTest.php`, `apps/platform/tests/Feature/Rbac/TenantLifecycleActionNamingTest.php`, `apps/platform/tests/Feature/Rbac/TenantResourceAuthorizationTest.php`, and `apps/platform/tests/Feature/Rbac/EditTenantArchiveUiEnforcementTest.php`
|
|
- [X] T026 [P] [US4] Extend tenant lifecycle audit and cross-surface presentation coverage in `apps/platform/tests/Feature/Audit/TenantLifecycleAuditLogTest.php` and `apps/platform/tests/Feature/Filament/TenantLifecyclePresentationAcrossTenantSurfacesTest.php`
|
|
|
|
### Implementation for User Story 4
|
|
|
|
- [X] T027 [US4] Refactor tenant lifecycle action definitions to bind archive and restore to the shared catalog in `apps/platform/app/Filament/Resources/TenantResource.php`
|
|
- [X] T028 [US4] Refactor tenant view and edit page lifecycle actions so archive and restore stay aligned across both surfaces in `apps/platform/app/Filament/Resources/TenantResource/Pages/ViewTenant.php` and `apps/platform/app/Filament/Resources/TenantResource/Pages/EditTenant.php`
|
|
|
|
**Checkpoint**: Tenant lifecycle actions are independently functional and consistent across both workspace tenant surfaces.
|
|
|
|
---
|
|
|
|
## Phase 7: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Finish the remaining finding-lifecycle alignment, lock in browser proof, and run focused verification.
|
|
|
|
- [X] T029 [P] Add finding lifecycle header-, row-, and bulk-action, navigation-separation, destructive-confirmation, authorization, and audit coverage in `apps/platform/tests/Feature/Findings/FindingWorkflowViewActionsTest.php`, `apps/platform/tests/Feature/Findings/FindingWorkflowRowActionsTest.php`, `apps/platform/tests/Feature/Findings/FindingBulkActionsTest.php`, `apps/platform/tests/Feature/Findings/FindingWorkflowUiEnforcementTest.php`, `apps/platform/tests/Feature/Findings/FindingRbacTest.php`, and `apps/platform/tests/Feature/Findings/FindingAuditLogTest.php`
|
|
- [X] T030 [P] Add cross-surface browser smoke coverage for exception, review, evidence, run, and tenant lifecycle semantics in `apps/platform/tests/Browser/Spec194GovernanceFrictionSmokeTest.php`
|
|
- [X] T031 Refactor finding lifecycle header, row, and bulk actions so close and reopen follow the catalog while request-exception stays navigation into governance in `apps/platform/app/Filament/Resources/FindingResource.php`, `apps/platform/app/Filament/Resources/FindingResource/Pages/ViewFinding.php`, and `apps/platform/app/Services/Findings/FindingWorkflowService.php`
|
|
- [X] T032 Review mutation-scope wording, explicit confirmation copy for destructive families, canonical labels, notifications, indirect risk-acceptance continuity, and documented deviations in `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/TenantReviewResource/Pages/ViewTenantReview.php`, `apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php`, `apps/platform/app/Filament/System/Pages/Ops/ViewRun.php`, and `apps/platform/app/Filament/Resources/TenantResource.php`
|
|
- [X] T033 Run the focused Sail verification workflow from `specs/194-governance-friction-hardening/quickstart.md` against the changed unit, feature, RBAC, audit, and browser tests in `apps/platform/tests/`
|
|
- [X] T034 Run formatting with `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` for the changed files in `apps/platform/app/` and `apps/platform/tests/`
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: No dependencies; can start immediately.
|
|
- **Foundational (Phase 2)**: Depends on Setup completion; blocks all user stories.
|
|
- **User Story 1 (Phase 3)**: Depends on Foundational completion; recommended MVP cut.
|
|
- **User Story 2 (Phase 4)**: Depends on Foundational completion; can run in parallel with US1 after the shared catalog is stable.
|
|
- **User Story 3 (Phase 5)**: Depends on Foundational completion; can run in parallel with US1 or US2 once the run family keys exist in the catalog.
|
|
- **User Story 4 (Phase 6)**: Depends on Foundational completion; can run in parallel with US2 or US3 because it touches separate tenant lifecycle files.
|
|
- **Polish (Phase 7)**: Depends on the desired user stories being complete; it closes the remaining finding lifecycle requirement and final regression proof.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **US1**: No dependencies beyond Foundational.
|
|
- **US2**: No dependencies beyond Foundational, but it reuses the catalog and guard patterns established for US1.
|
|
- **US3**: No dependencies beyond Foundational, but it reuses the same reason and danger semantics contract.
|
|
- **US4**: No dependencies beyond Foundational; it consumes the shared lifecycle rules after the catalog exists.
|
|
|
|
### Within Each User Story
|
|
|
|
- Write the story tests first and confirm they fail before implementation.
|
|
- Update the owning service before finalizing the matching page actions when reason propagation or audit wording changes.
|
|
- Keep each story independently shippable before widening the slice.
|
|
|
|
### Parallel Opportunities
|
|
|
|
- `T002` and `T003` can run in parallel after `T001`.
|
|
- `T004`, `T005`, `T006`, and `T007` can run in parallel before `T008`.
|
|
- Within US1, `T009` and `T010` can run in parallel.
|
|
- Within US2, `T014` and `T015` can run in parallel, and `T016` and `T018` can run in parallel.
|
|
- Within US3, `T020` and `T021` can run in parallel.
|
|
- Within US4, `T025` and `T026` can run in parallel.
|
|
- Within Phase 7, `T029` and `T030` can run in parallel once all page-level story work is complete.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Parallel test pass for US1
|
|
T009 Extend queue selection-state, modal friction, and reason-prompt coverage
|
|
T010 Extend exception lifecycle, authorization, header-discipline, and audit coverage
|
|
```
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Parallel story work for US2
|
|
T014 Extend tenant review lifecycle, export separation, authorization, and audit coverage
|
|
T015 Extend evidence refresh-versus-expire, authorization, and audit coverage
|
|
T016 Align review lifecycle reason propagation, audit prose, and notification wording
|
|
T018 Align evidence lifecycle reason propagation, audit prose, and notification wording
|
|
```
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# Parallel test pass for US3
|
|
T020 Extend system run triage severity, reason, and authorization coverage
|
|
T021 Extend calm-surface and no-triage-regression coverage
|
|
```
|
|
|
|
## Parallel Example: User Story 4
|
|
|
|
```bash
|
|
# Parallel test pass for US4
|
|
T025 Extend tenant lifecycle visibility, naming, and authorization coverage
|
|
T026 Extend tenant lifecycle audit and cross-surface presentation coverage
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First (User Story 1 Only)
|
|
|
|
1. Complete Phase 1: Setup.
|
|
2. Complete Phase 2: Foundational catalog and guard work.
|
|
3. Complete Phase 3: User Story 1.
|
|
4. Validate the exception-family behavior through the focused US1 tests.
|
|
5. Stop and review the shared catalog shape before widening the slice.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Ship US1 to establish the first remediated governance family.
|
|
2. Add US2 to normalize review and evidence lifecycle semantics.
|
|
3. Add US3 to calibrate run triage without destabilizing calm monitoring surfaces.
|
|
4. Add US4 to finish tenant lifecycle alignment.
|
|
5. Finish with Phase 7 to align finding lifecycle, add browser proof, and run focused verification.
|
|
|
|
### Parallel Team Strategy
|
|
|
|
1. One contributor completes Setup and Foundational tasks.
|
|
2. After Foundation is green:
|
|
- Contributor A takes US1.
|
|
- Contributor B takes US2.
|
|
- Contributor C takes US3.
|
|
- Contributor D takes US4.
|
|
3. Merge back for Phase 7 finding-lifecycle alignment, browser smoke, and verification.
|