ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity
fdd3a85b64
TenantAtlas/specs/169-action-surface-v11/tasks.md
ahmido 37c6d0622c feat: implement spec 169 action surface contract v1.1 (#200) 
## Summary
- implement the Action Surface Contract v1.1 runtime changes for Spec 169
- add the new explicit ActionSurfaceType contract, validator/discovery updates, and enrolled surface declarations
- update Filament action-surface documentation, focused guard tests, and spec artifacts for the completed feature

## Included
- clickable-row vs explicit-inspect enforcement across monitoring, reporting, CRUD, and system reference surfaces
- helper-first, workflow-next, destructive-last overflow ordering checks
- system panel list discovery in the primary action-surface validator
- Spec 169 artifacts: spec, plan, tasks, research, data model, quickstart, and logical contract

## Verification
- focused Pest verification pack completed for:
  - tests/Feature/Guards/ActionSurfaceValidatorTest.php
  - tests/Feature/Guards/ActionSurfaceContractTest.php
  - tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php
- integrated browser smoke test completed for admin-side reference surfaces:
  - /admin/operations
  - /admin/audit-log
  - /admin/finding-exceptions/queue
  - /admin/reviews
  - /admin/tenants

## Notes
- system panel browser smoke coverage could not be exercised in the same session because /system routes require platform authentication in the integrated browser
- Livewire target remains v4-compliant and no provider registration or asset strategy changes are introduced by this PR

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #200
2026-03-30 09:21:39 +00:00

199 lines
14 KiB
Markdown
Raw Blame History

# Tasks: Action Surface Contract v1.1
**Input**: Design documents from `/specs/169-action-surface-v11/`
**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/action-surface-governance.logical.openapi.yaml, quickstart.md
**Tests**: Required. This feature changes runtime behavior and repository guards, so Pest and Livewire coverage must be added and run.
**Organization**: Tasks are grouped by user story so each story can be implemented and validated independently once the blocking foundation work is complete.
## Phase 1: Setup (Shared Infrastructure)
**Purpose**: Add the minimum shared contract scaffolding that every later story depends on.
- [X] T001 Create the first-class `ActionSurfaceType` enum in `app/Support/Ui/ActionSurface/Enums/ActionSurfaceType.php`
- [X] T002 Extend `app/Support/Ui/ActionSurface/ActionSurfaceDeclaration.php` to require `surfaceType` and store `PrimaryLinkColumn` reason metadata alongside the existing profile, slots, exemptions, and defaults
- [X] T003 [P] Update shared action-surface helper seams in `app/Support/Ui/ActionSurface/Enums/ActionSurfaceInspectAffordance.php` and `app/Support/Ui/ActionSurface/ActionSurfaceProfileDefinition.php` so the new surface-type contract can be referenced consistently
---
## Phase 2: Foundational (Blocking Prerequisites)
**Purpose**: Roll the new declaration field across the enrolled reference surfaces before strict validator enforcement begins.
**⚠️ CRITICAL**: No story-specific enforcement work should begin until every enrolled reference surface can compile with the new `surfaceType` contract.
- [X] T004 [P] Add explicit `surfaceType` declarations to page-backed monitoring and reporting references in `app/Filament/Pages/Monitoring/Operations.php`, `app/Filament/Pages/Monitoring/AuditLog.php`, `app/Filament/Pages/Monitoring/FindingExceptionsQueue.php`, `app/Filament/Pages/Monitoring/EvidenceOverview.php`, and `app/Filament/Pages/Reviews/ReviewRegister.php`
- [X] T005 [P] Add explicit `surfaceType` declarations to representative CRUD resources in `app/Filament/Resources/BackupScheduleResource.php`, `app/Filament/Resources/BaselineProfileResource.php`, `app/Filament/Resources/PolicyResource.php`, `app/Filament/Resources/TenantResource.php`, and `app/Filament/Resources/Workspaces/WorkspaceResource.php`
- [X] T006 [P] Add explicit `surfaceType` declarations to representative read-only registry resources in `app/Filament/Resources/OperationRunResource.php`, `app/Filament/Resources/AlertDeliveryResource.php`, `app/Filament/Resources/BaselineSnapshotResource.php`, `app/Filament/Resources/EvidenceSnapshotResource.php`, `app/Filament/Resources/ReviewPackResource.php`, and `app/Filament/Resources/TenantReviewResource.php`
- [X] T007 [P] Add explicit `surfaceType` declarations to the enrolled system list pages in `app/Filament/System/Pages/Ops/Runs.php`, `app/Filament/System/Pages/Ops/Failures.php`, `app/Filament/System/Pages/Ops/Stuck.php`, `app/Filament/System/Pages/Directory/Tenants.php`, `app/Filament/System/Pages/Directory/Workspaces.php`, and `app/Filament/System/Pages/Security/AccessLogs.php`
**Checkpoint**: The enrolled reference pack is migrated to the v1.1 contract and story-specific guard work can begin.
---
## Phase 3: User Story 1 - Enforce the Correct Inspect Model (Priority: P1) 🎯 MVP
**Goal**: Make the validator and representative guard surfaces fail when clickable-row and explicit-inspect semantics drift from the constitution.
**Independent Test**: Prove one clickable-row reference surface and one explicit-inspect reference surface pass, then prove the guard fails when their inspect models are swapped or duplicated.
### Tests for User Story 1
- [X] T008 [P] [US1] Extend `tests/Feature/Guards/ActionSurfaceValidatorTest.php` with failing cases for missing `surfaceType`, incompatible inspect-affordance pairings, and missing `PrimaryLinkColumn` reason text
- [X] T009 [US1] Extend `tests/Feature/Guards/ActionSurfaceContractTest.php` with failing rendered-behavior checks for clickable-row references and explicit-inspect references using `app/Filament/Pages/Monitoring/Operations.php`, `app/Filament/Resources/OperationRunResource.php`, `app/Filament/Pages/Monitoring/AuditLog.php`, `app/Filament/Pages/Monitoring/FindingExceptionsQueue.php`, `app/Filament/Pages/Reviews/ReviewRegister.php`, and `app/Filament/Pages/Monitoring/EvidenceOverview.php`
### Implementation for User Story 1
- [X] T010 [US1] Implement surface-type inspect compatibility and actionable validation messages in `app/Support/Ui/ActionSurface/ActionSurfaceValidator.php`
- [X] T011 [US1] Align the inspect-model reference declarations in `app/Filament/Pages/Monitoring/Operations.php`, `app/Filament/Resources/OperationRunResource.php`, `app/Filament/Pages/Monitoring/AuditLog.php`, `app/Filament/Pages/Monitoring/FindingExceptionsQueue.php`, `app/Filament/Pages/Reviews/ReviewRegister.php`, and `app/Filament/Pages/Monitoring/EvidenceOverview.php` with the constitution decision tree and explicit exception metadata
- [X] T012 [US1] Update inspect-model guidance in `docs/ui/action-surface-contract.md` and `docs/product/standards/filament-actions-ux.md` to codify clickable-row defaults, explicit-inspect requirements, reporting-registry coverage, and `PrimaryLinkColumn` exception rules
**Checkpoint**: User Story 1 is complete when inspect-model drift fails in both validator stubs and representative rendered guards while the enrolled reference surfaces continue to pass.
---
## Phase 4: User Story 2 - Enforce Stable More-Menu Ordering (Priority: P1)
**Goal**: Make representative governed lists prove helper-first, workflow-next, destructive-last ordering and prevent empty overflow groups from surviving as placeholders.
**Independent Test**: Assert the ordered `More` and `BulkActionGroup` shape on representative CRUD surfaces and fail the guard when helpers do not lead, workflow actions trail destructive ones, or groups become empty placeholders.
### Tests for User Story 2
- [X] T013 [US2] Extend `tests/Feature/Guards/ActionSurfaceContractTest.php` with failing helper-first, workflow-next, destructive-last, and empty-group assertions for representative `More` and `BulkActionGroup` surfaces
- [X] T014 [P] [US2] Extend `tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php` with RBAC-aware overflow ordering assertions for tenant list surfaces
### Implementation for User Story 2
- [X] T015 [P] [US2] Reorder secondary and destructive actions in `app/Filament/Resources/BackupScheduleResource.php` and `app/Filament/Resources/BaselineProfileResource.php` so inspection helpers lead, workflow actions follow, destructive actions stay last, and placeholder groups cannot render
- [X] T016 [P] [US2] Align inline safe shortcut budgets and `More` menu placement in `app/Filament/Resources/TenantResource.php`, `app/Filament/Resources/PolicyResource.php`, and `app/Filament/Resources/Workspaces/WorkspaceResource.php`
- [X] T017 [US2] Update helper-first, workflow-next, destructive-last, and placeholder-group guidance in `docs/product/standards/filament-actions-ux.md` and `docs/ui/action-surface-contract.md`
**Checkpoint**: User Story 2 is complete when representative CRUD and RBAC-aware list surfaces render stable overflow ordering with helpers first, workflow actions next, destructive actions last, and no empty groups.
---
## Phase 5: User Story 3 - Bring System Lists Under Primary Guard Coverage (Priority: P2)
**Goal**: Move the enrolled system-panel list pages from targeted-only assertions into the main repository-wide discovery and validator pass.
**Independent Test**: Prove the primary validator discovers the six enrolled system list pages and still excludes auth, dashboard, widget, chooser, and deferred system tooling surfaces.
### Tests for User Story 3
- [X] T018 [US3] Extend `tests/Feature/Guards/ActionSurfaceContractTest.php` with failing discovery assertions for the six enrolled system list pages and explicit exclusion assertions for `app/Filament/System/Pages/Ops/Runbooks.php` and `app/Filament/System/Pages/RepairWorkspaceOwners.php`
### Implementation for User Story 3
- [X] T019 [US3] Implement narrow system table-page discovery in `app/Support/Ui/ActionSurface/ActionSurfaceDiscovery.php` for declared `app/Filament/System/Pages/**` table pages only
- [X] T020 [US3] Update baseline exemption handling in `app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php` so enrolled system pages are no longer treated like deferred exemptions and deferred families remain explicit
- [X] T021 [P] [US3] Tune the enrolled system reference declarations in `app/Filament/System/Pages/Ops/Runs.php`, `app/Filament/System/Pages/Ops/Failures.php`, `app/Filament/System/Pages/Ops/Stuck.php`, `app/Filament/System/Pages/Directory/Tenants.php`, `app/Filament/System/Pages/Directory/Workspaces.php`, and `app/Filament/System/Pages/Security/AccessLogs.php` for the new discovery path, the repaired `ReadOnlyRegistryReport` classification for system ops lists, and canonical `Operations / Run` naming
**Checkpoint**: User Story 3 is complete when the primary validator discovers the enrolled system list pages without stale baseline exemptions and still excludes deferred system surfaces.
---
## Phase 6: Polish & Cross-Cutting Concerns
**Purpose**: Run the focused verification and formatting steps that close the implementation loop.
- [X] T022 Run `vendor/bin/sail bin pint --dirty --format agent`
- [X] T023 Run the focused verification pack from `specs/169-action-surface-v11/quickstart.md` against `tests/Feature/Guards/ActionSurfaceValidatorTest.php`, `tests/Feature/Guards/ActionSurfaceContractTest.php`, and `tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php`
---
## Dependencies & Execution Order
### Phase Dependencies
- **Setup (Phase 1)**: Starts immediately.
- **Foundational (Phase 2)**: Depends on Setup completion and blocks all user stories.
- **User Story 1 (Phase 3)**: Starts after Phase 2.
- **User Story 2 (Phase 4)**: Starts after Phase 2 and can proceed independently of US1 at the feature level, though both stories touch shared docs and guard files.
- **User Story 3 (Phase 5)**: Starts after Phase 2 and can proceed independently of US1 and US2 at the feature level, though it shares `tests/Feature/Guards/ActionSurfaceContractTest.php`.
- **Polish (Phase 6)**: Starts after all desired user stories are complete.
### User Story Dependencies
- **US1 (P1)**: Depends on Setup and Foundational only.
- **US2 (P1)**: Depends on Setup and Foundational only.
- **US3 (P2)**: Depends on Setup and Foundational only.
### Within Each User Story
- Story tests are written or extended before story implementation tasks.
- Shared validator or discovery code changes come before story-level declaration tuning.
- Reference surfaces are aligned before the focused verification pack runs.
### Parallel Opportunities
- T003 can run in parallel with T001 or T002 once the enum shape is settled.
- T004 through T007 can run in parallel because they touch different declaration families.
- In US1, T008 can run in parallel with declaration tuning preparation because it targets a separate test file.
- In US2, T014, T015, and T016 can run in parallel because they target different files.
- In US3, T021 can run in parallel with T019 or T020 once the discovery rule is agreed.
---
## Parallel Example: User Story 1
```bash
# Launch the validator stub work and rendered guard extension separately:
Task: "Extend tests/Feature/Guards/ActionSurfaceValidatorTest.php with failing cases for missing surfaceType and invalid inspect-affordance pairings"
Task: "Extend tests/Feature/Guards/ActionSurfaceContractTest.php with failing rendered-behavior checks for Monitoring Operations, OperationRunResource, AuditLog, FindingExceptionsQueue, ReviewRegister, and EvidenceOverview"
```
## Parallel Example: User Story 2
```bash
# Split ordering work across resource families:
Task: "Reorder secondary and destructive actions in app/Filament/Resources/BackupScheduleResource.php and app/Filament/Resources/BaselineProfileResource.php so helpers lead, workflow actions follow, and destructive actions stay last"
Task: "Align inline safe shortcut budgets and More menu placement in app/Filament/Resources/TenantResource.php, app/Filament/Resources/PolicyResource.php, and app/Filament/Resources/Workspaces/WorkspaceResource.php"
Task: "Extend tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php with RBAC-aware overflow ordering assertions"
```
## Parallel Example: User Story 3
```bash
# Let discovery and system declaration tuning proceed side by side:
Task: "Implement narrow system table-page discovery in app/Support/Ui/ActionSurface/ActionSurfaceDiscovery.php"
Task: "Tune the enrolled system reference declarations in app/Filament/System/Pages/Ops/Runs.php, app/Filament/System/Pages/Ops/Failures.php, app/Filament/System/Pages/Ops/Stuck.php, app/Filament/System/Pages/Directory/Tenants.php, app/Filament/System/Pages/Directory/Workspaces.php, and app/Filament/System/Pages/Security/AccessLogs.php"
```
---
## Implementation Strategy
### MVP First (User Story 1 Only)
1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Validate the focused inspect-model guard behavior before starting additional stories.
### Incremental Delivery
1. Finish Setup + Foundational to put the enrolled reference pack on the v1.1 declaration contract.
2. Deliver US1 to make inspect-model drift fail decisively.
3. Deliver US2 to stabilize overflow ordering across representative CRUD surfaces.
4. Deliver US3 to bring system lists into the main validator scope.
5. Run the focused quickstart verification and then decide whether to run the full suite.
### Parallel Team Strategy
1. One contributor handles Phase 1 and the shared declaration contract updates.
2. After Phase 2, separate contributors can take:
- US1 validator and monitoring reference surfaces
- US2 CRUD ordering surfaces and RBAC-aware overflow tests
- US3 system discovery and system reference surfaces
3. Rejoin for Phase 6 formatting and focused verification.
---
## Notes
- `[P]` tasks touch separate files and can be executed in parallel after their dependencies are satisfied.
- The main shared hot spots are `tests/Feature/Guards/ActionSurfaceContractTest.php`, `docs/ui/action-surface-contract.md`, and `docs/product/standards/filament-actions-ux.md`; avoid parallel edits there.
- This feature does not add `OperationRun`, assets, routes, persistence, or capability work, so no extra Ops-UX or deployment tasks are required.
Reference in New Issue View Git Blame Copy Permalink