229 lines
20 KiB
Markdown
229 lines
20 KiB
Markdown
# Tasks: Operation Run Link Contract Enforcement
|
||
|
||
**Input**: Design documents from `/specs/232-operation-run-link-contract/`
|
||
**Prerequisites**: `plan.md` (required), `spec.md` (required for user stories), `research.md`, `data-model.md`, `contracts/operation-run-link-contract.logical.openapi.yaml`, `quickstart.md`
|
||
|
||
**Tests**: Required. This feature changes runtime behavior in operator-facing monitoring drill-through and shared link-contract enforcement, so Pest coverage must be added or updated in `apps/platform/tests/Feature/OpsUx/CanonicalViewRunLinksTest.php`, `apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php`, `apps/platform/tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, `apps/platform/tests/Feature/Filament/InventoryCoverageRunContinuityTest.php`, `apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php`, `apps/platform/tests/Feature/144/CanonicalOperationViewerDeepLinkTrustTest.php`, `apps/platform/tests/Feature/078/RelatedLinksOnDetailTest.php`, `apps/platform/tests/Feature/RunAuthorizationTenantIsolationTest.php`, `apps/platform/tests/Feature/System/Spec195/SystemDirectoryResidualSurfaceTest.php`, `apps/platform/tests/Feature/System/Spec113/AuthorizationSemanticsTest.php`, and `apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php`.
|
||
**Operations**: No new `OperationRun` is introduced. Existing admin and system monitoring pages remain the canonical destination surfaces, and this feature must not change run lifecycle, notification, or audit semantics.
|
||
**RBAC**: The feature spans the admin `/admin` plane and the platform `/system` plane. It must preserve non-member or wrong-plane `404`, in-scope missing-capability `403`, tenant-safe canonical admin continuity, and current platform-only system access semantics.
|
||
**UI / Surface Guardrails**: The changed surfaces are native Filament widgets, pages, resources, and shared navigation builders. The admin monitoring entry points keep the `monitoring-state-page` profile, the remaining surfaces take `standard-native-filament` relief, and the repository signal is `review-mandatory` because the feature adds a bounded guard plus explicit exceptions.
|
||
**Filament UI Action Surfaces**: `RecentOperationsSummary`, `InventoryCoverage`, `InventoryItemResource`, `ReviewPackResource`, `TenantlessOperationRunViewer`, and the residual system directory pages keep their existing inspect/open model. No new header, row, bulk, or destructive actions are introduced.
|
||
**Badges**: Existing status and outcome badge semantics remain authoritative. This feature must not add ad-hoc badge mappings or a new status taxonomy.
|
||
|
||
**Organization**: Tasks are grouped by user story so each slice remains independently testable after the shared helper and guard boundary are stabilized. Recommended delivery order is `US1 -> US2 -> US3` because the admin-plane cleanup is the primary migration slice and the guard should close only after the final migrated surface set and exceptions are settled.
|
||
|
||
## Test Governance Checklist
|
||
|
||
- [X] Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
|
||
- [X] New or changed tests stay in the smallest honest family, and any heavy-governance or browser addition is explicit.
|
||
- [X] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
|
||
- [X] Planned validation commands cover the change without pulling in unrelated lane cost.
|
||
- [X] The declared surface test profile or `standard-native-filament` relief is explicit.
|
||
- [X] Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR.
|
||
|
||
## Phase 1: Setup (Shared Link Contract Scaffolding)
|
||
|
||
**Purpose**: Prepare the focused regression surfaces that will prove canonical admin and system link behavior before runtime files are edited.
|
||
|
||
- [X] T001 [P] Extend baseline helper contract coverage for canonical admin and system collection/detail URLs in `apps/platform/tests/Feature/OpsUx/CanonicalViewRunLinksTest.php`
|
||
- [X] T002 [P] Extend tenant-summary and dashboard drill-through coverage for canonical admin collection links in `apps/platform/tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php` and `apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php`
|
||
- [X] T003 [P] Extend resource-level admin detail continuity coverage in `apps/platform/tests/Feature/Filament/InventoryCoverageRunContinuityTest.php` and `apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php`
|
||
- [X] T004 [P] Extend shared resolver, canonical viewer, and system-plane continuity scaffolding in `apps/platform/tests/Feature/144/CanonicalOperationViewerDeepLinkTrustTest.php`, `apps/platform/tests/Feature/078/RelatedLinksOnDetailTest.php`, `apps/platform/tests/Feature/System/Spec195/SystemDirectoryResidualSurfaceTest.php`, and `apps/platform/tests/Feature/System/Spec113/AuthorizationSemanticsTest.php`
|
||
|
||
**Checkpoint**: The focused test surfaces are ready to prove canonical helper adoption, system-plane continuity, and bounded guard behavior.
|
||
|
||
---
|
||
|
||
## Phase 2: Foundational (Blocking Helper And Guard Boundary)
|
||
|
||
**Purpose**: Stabilize the canonical helper contract and the route-bounded guard before any user story migration begins.
|
||
|
||
**Critical**: No user story work should begin until this phase is complete.
|
||
|
||
- [X] T005 Freeze canonical helper inputs, labels, and accepted delegation boundaries in `apps/platform/app/Support/OperationRunLinks.php`, `apps/platform/app/Support/System/SystemOperationRunLinks.php`, and `apps/platform/app/Support/OpsUx/OperationRunUrl.php`
|
||
- [X] T006 [P] Create the bounded raw-bypass guard with scoped include paths, explicit exception candidates, forbidden patterns, and actionable file-plus-snippet output in `apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php`
|
||
|
||
**Checkpoint**: Canonical helper semantics and the initial guard boundary are stable enough for surface-by-surface migration work.
|
||
|
||
---
|
||
|
||
## Phase 3: User Story 1 - Follow Admin Operations Links Consistently (Priority: P1)
|
||
|
||
**Goal**: Platform-owned admin surfaces open canonical operations collection and detail URLs through `OperationRunLinks` with the correct tenant and navigation continuity.
|
||
|
||
**Independent Test**: Open operations links from the tenant summary widget, dashboard drill-throughs, inventory coverage, review packs, and related-link surfaces, then confirm they land on `/admin/operations` or `/admin/operations/{run}` with only helper-supported continuity semantics.
|
||
|
||
### Tests for User Story 1
|
||
|
||
- [X] T007 [P] [US1] Add tenant-aware admin collection link assertions for summary and dashboard sources in `apps/platform/tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php` and `apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php`
|
||
- [X] T008 [P] [US1] Add canonical admin detail link assertions for coverage and review-pack sources in `apps/platform/tests/Feature/Filament/InventoryCoverageRunContinuityTest.php` and `apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php`
|
||
- [X] T009 [P] [US1] Add canonical related-link, viewer fallback, and explicit admin `404`/`403` authorization assertions, including the in-scope capability-denial proof, in `apps/platform/tests/Feature/144/CanonicalOperationViewerDeepLinkTrustTest.php`, `apps/platform/tests/Feature/078/RelatedLinksOnDetailTest.php`, and `apps/platform/tests/Feature/RunAuthorizationTenantIsolationTest.php`
|
||
|
||
### Implementation for User Story 1
|
||
|
||
- [X] T010 [P] [US1] Migrate admin collection links in `apps/platform/app/Filament/Widgets/Tenant/RecentOperationsSummary.php` and the collection/detail continuity paths in `apps/platform/app/Filament/Pages/InventoryCoverage.php` to `OperationRunLinks`
|
||
- [X] T011 [P] [US1] Migrate admin detail links in `apps/platform/app/Filament/Resources/InventoryItemResource.php` and `apps/platform/app/Filament/Resources/ReviewPackResource.php` to `OperationRunLinks::view(...)`
|
||
- [X] T012 [US1] Migrate shared related-navigation and canonical viewer fallback paths in `apps/platform/app/Support/Navigation/RelatedNavigationResolver.php` and `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` to helper-owned admin links
|
||
- [X] T013 [US1] Run the US1 admin continuity verification flow documented in `specs/232-operation-run-link-contract/quickstart.md`
|
||
|
||
**Checkpoint**: User Story 1 is independently functional and platform-owned admin drill-throughs consistently use the canonical admin helper family.
|
||
|
||
---
|
||
|
||
## Phase 4: User Story 2 - Keep System-Plane Run Links In The System Plane (Priority: P1)
|
||
|
||
**Goal**: Platform operators keep landing on canonical `/system/ops/runs` surfaces, and system follow-up links do not regress to admin-plane monitoring.
|
||
|
||
**Independent Test**: Open system directory or operations follow-up links as a platform user and confirm collection/detail URLs remain helper-owned system-plane destinations while wrong-plane access still resolves as deny-as-not-found.
|
||
|
||
### Tests for User Story 2
|
||
|
||
- [X] T014 [P] [US2] Add system-plane continuity and platform-authorization assertions in `apps/platform/tests/Feature/System/Spec195/SystemDirectoryResidualSurfaceTest.php` and `apps/platform/tests/Feature/System/Spec113/AuthorizationSemanticsTest.php`
|
||
|
||
### Implementation for User Story 2
|
||
|
||
- [X] T015 [P] [US2] Audit system directory follow-up links in `apps/platform/app/Filament/System/Pages/Directory/ViewTenant.php` and `apps/platform/app/Filament/System/Pages/Directory/ViewWorkspace.php` and keep collection/detail navigation on `SystemOperationRunLinks` without admin fallbacks
|
||
- [X] T016 [US2] Audit canonical system entry points in `apps/platform/app/Filament/System/Pages/Ops/ViewRun.php`, `apps/platform/app/Filament/System/Pages/Ops/Runs.php`, and `apps/platform/app/Support/System/SystemOperationRunLinks.php` and apply only minimal cleanup needed to keep verified helper-backed system navigation admin-plane free
|
||
- [X] T017 [US2] Run the US2 system-plane verification flow documented in `specs/232-operation-run-link-contract/quickstart.md`
|
||
|
||
**Checkpoint**: User Story 2 is independently functional and system-plane run navigation remains helper-owned and plane-correct.
|
||
|
||
---
|
||
|
||
## Phase 5: User Story 3 - Prevent New Raw Operation-Link Bypasses (Priority: P2)
|
||
|
||
**Goal**: A bounded repository guard blocks new raw operation-route assembly in platform-owned UI and shared navigation code while preserving explicitly justified infrastructure exceptions.
|
||
|
||
**Independent Test**: Introduce a representative raw `route('admin.operations.view', ...)` or direct system operations URL inside the declared app-side boundary, confirm the guard fails with actionable output, then replace it with the canonical helper or an explicitly justified exception and confirm the guard passes.
|
||
|
||
### Tests for User Story 3
|
||
|
||
- [X] T018 [P] [US3] Add bounded app-side scan coverage, exception handling, and actionable failure assertions in `apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php`
|
||
- [X] T019 [P] [US3] Add guard-adjacent regression coverage for accepted delegates and canonical helper outputs in `apps/platform/tests/Feature/OpsUx/CanonicalViewRunLinksTest.php` and `apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php`
|
||
|
||
### Implementation for User Story 3
|
||
|
||
- [X] T020 [US3] Finalize the guard include paths, forbidden patterns, and allowlisted exception entries for `apps/platform/app/Providers/Filament/AdminPanelProvider.php`, `apps/platform/app/Providers/Filament/TenantPanelProvider.php`, `apps/platform/app/Support/Middleware/EnsureFilamentTenantSelected.php`, and `apps/platform/app/Http/Controllers/ClearTenantContextController.php` in `apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php`
|
||
- [X] T021 [US3] Retain the finalized allowlisted exceptions in `apps/platform/app/Providers/Filament/AdminPanelProvider.php`, `apps/platform/app/Providers/Filament/TenantPanelProvider.php`, `apps/platform/app/Support/Middleware/EnsureFilamentTenantSelected.php`, and `apps/platform/app/Http/Controllers/ClearTenantContextController.php`
|
||
- [X] T022 [US3] Run the US3 guardrail verification flow documented in `specs/232-operation-run-link-contract/quickstart.md`
|
||
|
||
**Checkpoint**: User Story 3 is independently functional and future platform-owned raw bypasses are blocked by a bounded, reviewable guard.
|
||
|
||
---
|
||
|
||
## Phase 6: Polish & Cross-Cutting Concerns
|
||
|
||
**Purpose**: Finalize the contract artifacts, formatting, and focused validation workflow for the full feature.
|
||
|
||
- [X] T023 [P] Refresh `specs/232-operation-run-link-contract/contracts/operation-run-link-contract.logical.openapi.yaml` and `specs/232-operation-run-link-contract/quickstart.md` with the final guard boundary, exception inventory, and focused validation steps
|
||
- [X] T024 Run formatting on touched app and test files with `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
|
||
- [X] T025 Run the focused Pest suite from `specs/232-operation-run-link-contract/quickstart.md` against `apps/platform/tests/Feature/OpsUx/CanonicalViewRunLinksTest.php`, `apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php`, `apps/platform/tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, `apps/platform/tests/Feature/Filament/InventoryCoverageRunContinuityTest.php`, `apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php`, `apps/platform/tests/Feature/144/CanonicalOperationViewerDeepLinkTrustTest.php`, `apps/platform/tests/Feature/078/RelatedLinksOnDetailTest.php`, `apps/platform/tests/Feature/RunAuthorizationTenantIsolationTest.php`, `apps/platform/tests/Feature/System/Spec195/SystemDirectoryResidualSurfaceTest.php`, `apps/platform/tests/Feature/System/Spec113/AuthorizationSemanticsTest.php`, and `apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php`
|
||
- [X] T026 Record the finalized producer inventory, allowlisted exception set, guard boundary, and `document-in-feature` test-governance disposition in `specs/232-operation-run-link-contract/plan.md`
|
||
|
||
---
|
||
|
||
## Dependencies & Execution Order
|
||
|
||
### Phase Dependencies
|
||
|
||
- **Setup (Phase 1)**: No dependencies; can start immediately.
|
||
- **Foundational (Phase 2)**: Depends on Setup completion and blocks all user story work.
|
||
- **User Story 1 (Phase 3)**: Depends on Foundational completion and is the recommended first implementation increment.
|
||
- **User Story 2 (Phase 4)**: Depends on Foundational completion and can proceed once helper semantics are stable.
|
||
- **User Story 3 (Phase 5)**: Depends on User Stories 1 and 2 because the final guard boundary must reflect the settled migrated surfaces and explicit exception set.
|
||
- **Polish (Phase 6)**: Depends on all desired user stories being complete.
|
||
|
||
### User Story Dependencies
|
||
|
||
- **US1 (P1)**: Starts immediately after Foundational and delivers the primary admin-plane cleanup.
|
||
- **US2 (P1)**: Can begin after Foundational, but is easiest to validate once US1 has settled the shared helper vocabulary.
|
||
- **US3 (P2)**: Starts after US1 and US2 stabilize because the allowlist and forbidden-pattern boundary should be closed against the final adopted surface set.
|
||
|
||
### Within Each User Story
|
||
|
||
- Story tests should be written and fail before the corresponding implementation tasks are considered complete.
|
||
- Helper-semantics work in Phase 2 should land before any surface migration adopts the final contract.
|
||
- Shared files such as `apps/platform/app/Support/OperationRunLinks.php`, `apps/platform/app/Support/System/SystemOperationRunLinks.php`, and `apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php` should be edited sequentially even when surrounding tasks are otherwise parallelizable.
|
||
- Each story’s verification task should complete before moving to the next priority slice when working sequentially.
|
||
|
||
### Parallel Opportunities
|
||
|
||
- **Setup**: `T001`, `T002`, `T003`, and `T004` can run in parallel.
|
||
- **Foundational**: `T006` can run in parallel with the tail end of `T005` once helper inputs and delegate boundaries are settled.
|
||
- **US1 tests**: `T007`, `T008`, and `T009` can run in parallel.
|
||
- **US1 implementation**: `T010` and `T011` can run in parallel; `T012` should follow once the surrounding helper semantics are stable.
|
||
- **US2**: `T014` can run in parallel with early system normalization in `T015`; `T016` should follow once any needed directory-page normalization is clear.
|
||
- **US3 tests**: `T018` and `T019` can run in parallel.
|
||
- **Polish**: `T023` can run in parallel with `T024` once implementation is stable.
|
||
|
||
---
|
||
|
||
## Parallel Example: User Story 1
|
||
|
||
```bash
|
||
# Run US1 coverage in parallel:
|
||
T007 apps/platform/tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php and apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php
|
||
T008 apps/platform/tests/Feature/Filament/InventoryCoverageRunContinuityTest.php and apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php
|
||
T009 apps/platform/tests/Feature/144/CanonicalOperationViewerDeepLinkTrustTest.php and apps/platform/tests/Feature/078/RelatedLinksOnDetailTest.php
|
||
|
||
# Then split the non-overlapping admin migrations:
|
||
T010 apps/platform/app/Filament/Widgets/Tenant/RecentOperationsSummary.php and apps/platform/app/Filament/Pages/InventoryCoverage.php
|
||
T011 apps/platform/app/Filament/Resources/InventoryItemResource.php and apps/platform/app/Filament/Resources/ReviewPackResource.php
|
||
```
|
||
|
||
---
|
||
|
||
## Parallel Example: User Story 2
|
||
|
||
```bash
|
||
# Run US2 system assertions while normalizing residual system directory links:
|
||
T014 apps/platform/tests/Feature/System/Spec195/SystemDirectoryResidualSurfaceTest.php and apps/platform/tests/Feature/System/Spec113/AuthorizationSemanticsTest.php
|
||
T015 apps/platform/app/Filament/System/Pages/Directory/ViewTenant.php and apps/platform/app/Filament/System/Pages/Directory/ViewWorkspace.php
|
||
```
|
||
|
||
---
|
||
|
||
## Parallel Example: User Story 3
|
||
|
||
```bash
|
||
# Run guard coverage in parallel with adjacent helper-output regressions:
|
||
T018 apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php
|
||
T019 apps/platform/tests/Feature/OpsUx/CanonicalViewRunLinksTest.php and apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php
|
||
```
|
||
|
||
---
|
||
|
||
## Implementation Strategy
|
||
|
||
### First Implementation Increment (User Story 1 Only)
|
||
|
||
1. Complete Phase 1: Setup.
|
||
2. Complete Phase 2: Foundational.
|
||
3. Complete Phase 3: User Story 1.
|
||
4. Validate the feature with `T013` before widening the slice.
|
||
|
||
### Incremental Delivery
|
||
|
||
1. Stabilize the helper contract and guard boundary in Setup and Foundational work.
|
||
2. Ship US1 to migrate the actual admin-plane drift surface set.
|
||
3. Add US2 to lock the system plane and preserve platform-only destination truth.
|
||
4. Add US3 to prevent future raw bypasses and make exceptions explicit.
|
||
5. Finish with contract refresh, formatting, focused tests, and close-out notes.
|
||
|
||
### Parallel Team Strategy
|
||
|
||
With multiple developers:
|
||
|
||
1. One contributor can extend helper and guard tests while another prepares the admin widget/resource drill-through assertions.
|
||
2. After Phase 2, one contributor can migrate admin collection sources, another can migrate admin detail sources, and a third can normalize shared resolver or viewer fallbacks.
|
||
3. Keep `OperationRunLinks.php`, `SystemOperationRunLinks.php`, and `OperationRunLinkContractGuardTest.php` serialized because they define the shared contract boundary.
|
||
|
||
---
|
||
|
||
## Notes
|
||
|
||
- `[P]` marks tasks that can run in parallel once their prerequisites are satisfied and the touched files do not overlap.
|
||
- `[US1]`, `[US2]`, and `[US3]` map directly to the feature specification user stories.
|
||
- The first working increment is Phase 1 through Phase 3, but the approved feature-complete minimum remains Phase 1 through Phase 5 because system-plane continuity and the guardrail are part of the accepted scope.
|
||
- All tasks above follow the required checklist format with task ID, optional parallel marker, story label where applicable, and exact file paths.
|