ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
0c81051426
TenantAtlas/specs/232-operation-run-link-contract/tasks.md
Ahmed Darrazi 0c81051426
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 54s
Details
Enforce operation run link contract
2026-04-23 15:08:43 +02:00

20 KiB
Raw Blame History

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

  • Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
  • New or changed tests stay in the smallest honest family, and any heavy-governance or browser addition is explicit.
  • Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
  • Planned validation commands cover the change without pulling in unrelated lane cost.
  • The declared surface test profile or standard-native-filament relief is explicit.
  • 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.

  • T001 [P] Extend baseline helper contract coverage for canonical admin and system collection/detail URLs in apps/platform/tests/Feature/OpsUx/CanonicalViewRunLinksTest.php
  • 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
  • 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
  • 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.

  • 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
  • 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

  • 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
  • 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
  • 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

  • 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
  • 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(...)
  • 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
  • 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

  • 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

  • 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
  • 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
  • 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

  • T018 [P] [US3] Add bounded app-side scan coverage, exception handling, and actionable failure assertions in apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php
  • 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

  • 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
  • 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
  • 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.

  • 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
  • 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
  • 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
  • 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

# 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

# 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

# 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.