--- description: "Task list for Canonical Operation Type Source of Truth" --- # Tasks: Canonical Operation Type Source of Truth **Input**: Design documents from `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/239-canonical-operation-type-source-of-truth/` **Prerequisites**: `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/239-canonical-operation-type-source-of-truth/plan.md` (required), `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/239-canonical-operation-type-source-of-truth/spec.md` (required), `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/239-canonical-operation-type-source-of-truth/research.md`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/239-canonical-operation-type-source-of-truth/data-model.md`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/239-canonical-operation-type-source-of-truth/contracts/`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/239-canonical-operation-type-source-of-truth/quickstart.md` **Tests**: REQUIRED (Pest) for runtime behavior changes; keep proof in the narrow `Unit`, `Feature`, and existing `Heavy-Governance` lanes named in the plan **Operations**: No new `OperationRun` family, panel, or Monitoring IA is introduced; preserve the shared OperationRun Start UX contract while canonicalizing `operation_type` across touched write and read surfaces **RBAC**: Preserve existing workspace, tenant, and platform authorization semantics on operations and onboarding surfaces, including unchanged `404` versus `403` behavior **Provider Boundary**: `operation_type` remains platform-core; provider operation bindings stay provider-owned and may not reintroduce raw aliases as shared truth **Organization**: Tasks are grouped by user story so canonical contract owners, monitoring parity, onboarding bootstrap state, provider-start writers, audit-adjacent summaries, and anti-drift guardrails can be implemented and validated incrementally without widening into broader naming cleanup or a generic compatibility framework. ## Test Governance Checklist - [X] Lane assignment stays `Unit` plus `Feature` plus existing `Heavy-Governance` and remains the narrowest sufficient proof for the changed behavior. - [X] New or changed tests stay in existing support, provider, onboarding, monitoring, and guard families; existing `tests/Architecture` and `tests/Feature/OpsUx` heavy-governance families may be reused, but no new heavy-governance family or browser lane is added. - [X] Shared helpers, factories, seeds, onboarding draft defaults, and operation fixtures stay cheap by default; no new alias-preserving helper layer is introduced. - [X] Planned validation commands cover canonical resolution, operations filter parity, tenant-safe operations visibility, DB-only monitoring rendering, onboarding bootstrap lifecycle, provider-start truth, and guardrails without widening scope. - [X] The declared surface test profile remains `monitoring-state-page` plus `standard-native-filament`; no exception-coded surface or browser proof is required. - [X] Any remaining compatibility seam resolves as `document-in-feature` or `follow-up-spec`, not as a silent generic compatibility framework. ## Phase 1: Setup (Shared Context) **Purpose**: Confirm the exact contract hotspots, owning files, and existing proof lanes before code changes begin. - [X] T001 Review the current canonical contract owners in `apps/platform/app/Support/OperationRunType.php`, `apps/platform/app/Support/OperationCatalog.php`, and `apps/platform/config/tenantpilot.php` - [X] T002 [P] Review representative write owners and onboarding bootstrap state in `apps/platform/app/Services/Providers/ProviderOperationRegistry.php`, `apps/platform/app/Services/Providers/ProviderOperationStartGate.php`, `apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`, and `apps/platform/app/Services/Onboarding/OnboardingLifecycleService.php` - [X] T003 [P] Review monitoring, filter, reference, audit, tenant-scope, and DB-only proof hotspots in `apps/platform/app/Filament/Resources/OperationRunResource.php`, `apps/platform/app/Support/Filament/FilterOptionCatalog.php`, `apps/platform/app/Support/OpsUx/OperationUxPresenter.php`, `apps/platform/app/Support/References/Resolvers/OperationRunReferenceResolver.php`, `apps/platform/app/Services/Audit/AuditEventBuilder.php`, `apps/platform/tests/Feature/Filament/OperationRunListFiltersTest.php`, `apps/platform/tests/Feature/Monitoring/OperationsTenantScopeTest.php`, `apps/platform/tests/Feature/Monitoring/OperationsDbOnlyRenderTest.php`, `apps/platform/tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php`, and `apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php` --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Collapse the shared canonical contract onto one platform-owned truth before any user story work begins. **⚠️ CRITICAL**: No user story work should begin until this phase is complete. - [X] T004 [P] Add or extend canonical resolution and unknown-label coverage in `apps/platform/tests/Unit/Support/OperationTypeResolutionTest.php` and `apps/platform/tests/Feature/OpsUx/UnknownOperationTypeLabelTest.php` - [X] T005 [P] Add enum and vocabulary anti-drift coverage in `apps/platform/tests/Unit/Support/OperationRunTypeCanonicalContractTest.php` and `apps/platform/tests/Architecture/PlatformVocabularyBoundaryGuardTest.php` - [X] T006 Update `apps/platform/app/Support/OperationRunType.php` and `apps/platform/app/Support/OperationCatalog.php` so canonical dotted `operation_type` values are the only normative write-time contract and aliases remain read-side only - [X] T007 Update `apps/platform/config/tenantpilot.php` and `apps/platform/app/Support/Operations/OperationLifecyclePolicy.php` so covered lifecycle keys and policy lookups use canonical dotted `operation_type` values directly **Checkpoint**: Shared canonical contract owners and guard foundations are ready; user story work can now proceed. --- ## Phase 3: User Story 1 - See One Operation Identity Everywhere (Priority: P1) 🎯 MVP **Goal**: Make operations lists, filters, references, and audit-adjacent monitoring summaries resolve one canonical operation identity instead of teaching alias variants as peer truths. **Independent Test**: Load covered operations surfaces with historical and current rows and verify one canonical filter choice, one operator label source, and one canonical summary identity for the same operation family. ### Tests for User Story 1 - [X] T008 [P] [US1] Extend canonical filter convergence coverage in `apps/platform/tests/Feature/Filament/OperationRunListFiltersTest.php` - [X] T009 [P] [US1] Extend monitoring, widget-summary, related-link, unknown-label, tenant-scope, tenantless-viewer, DB-only, and audit-adjacent canonicalization coverage in `apps/platform/tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, `apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php`, `apps/platform/tests/Feature/Monitoring/AuditCoverageOperationsTest.php`, `apps/platform/tests/Feature/Monitoring/OperationsTenantScopeTest.php`, `apps/platform/tests/Feature/Monitoring/OperationsDbOnlyRenderTest.php`, `apps/platform/tests/Feature/OpsUx/UnknownOperationTypeLabelTest.php`, `apps/platform/tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php`, and `apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php` ### Implementation for User Story 1 - [X] T010 [US1] Replace raw type comparisons and duplicate option logic in `apps/platform/app/Filament/Resources/OperationRunResource.php` and `apps/platform/app/Support/Filament/FilterOptionCatalog.php` - [X] T011 [P] [US1] Align shared labels and related-run links with canonical resolution in `apps/platform/app/Support/OpsUx/OperationUxPresenter.php`, `apps/platform/app/Support/References/Resolvers/OperationRunReferenceResolver.php`, and `apps/platform/app/Support/OperationRunLinks.php` - [X] T012 [P] [US1] Canonicalize audit-adjacent operation metadata in `apps/platform/app/Services/Audit/AuditEventBuilder.php` and `apps/platform/app/Services/OperationRunService.php` - [X] T013 [P] [US1] Canonicalize monitoring and summary payloads in `apps/platform/app/Services/SystemConsole/OperationRunTriageService.php`, `apps/platform/app/Services/Evidence/Sources/OperationsSummarySource.php`, and `apps/platform/app/Services/Runbooks/FindingsLifecycleBackfillRunbookService.php` - [X] T014 [US1] Run the relevant quickstart verification blocks for US1 from `specs/239-canonical-operation-type-source-of-truth/quickstart.md` (expanded narrow proving lane, representative operator-surface proof, and guardrail proof) against `apps/platform/tests/Feature/Filament/OperationRunListFiltersTest.php`, `apps/platform/tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, `apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php`, `apps/platform/tests/Feature/Monitoring/AuditCoverageOperationsTest.php`, `apps/platform/tests/Feature/Monitoring/OperationsTenantScopeTest.php`, `apps/platform/tests/Feature/Monitoring/OperationsDbOnlyRenderTest.php`, `apps/platform/tests/Feature/OpsUx/UnknownOperationTypeLabelTest.php`, `apps/platform/tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php`, `apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php`, and `apps/platform/tests/Unit/Support/OperationTypeResolutionTest.php` **Checkpoint**: User Story 1 is independently deliverable as the core monitoring and read-model parity slice. --- ## Phase 4: User Story 2 - Resume Onboarding Without Rewriting Legacy Drift (Priority: P1) **Goal**: Make onboarding bootstrap resume, save, and start flows normalize legacy selections to canonical dotted operation codes without rewriting the platform back to raw aliases. **Independent Test**: Resume an onboarding draft with legacy bootstrap selections, save it again, and start bootstrap actions to verify canonical operation codes are persisted and handed to the shared start UX path. ### Tests for User Story 2 - [X] T015 [P] [US2] Extend onboarding draft canonicalization coverage in `apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php` and `apps/platform/tests/Unit/Onboarding/OnboardingDraftResolverTest.php` - [X] T016 [P] [US2] Extend onboarding provider-start and authorization-safe bootstrap coverage in `apps/platform/tests/Feature/Workspaces/ManagedTenantOnboardingProviderStartTest.php` and `apps/platform/tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php` ### Implementation for User Story 2 - [X] T017 [US2] Normalize `bootstrap_operation_types` and `started_operation_type` on load, save, resume, and start in `apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `apps/platform/app/Services/Onboarding/OnboardingLifecycleService.php` - [X] T018 [US2] Keep resumed consent and callback flows writing canonical bootstrap state in `apps/platform/app/Http/Controllers/AdminConsentCallbackController.php` and `apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` - [X] T019 [US2] Align onboarding audit metadata and shared start handoff with canonical operation codes in `apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `apps/platform/app/Services/Audit/AuditEventBuilder.php` - [X] T020 [US2] Run the relevant quickstart verification blocks for US2 from `specs/239-canonical-operation-type-source-of-truth/quickstart.md` (expanded narrow proving lane plus representative operator-surface proof) against `apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php`, `apps/platform/tests/Unit/Onboarding/OnboardingDraftResolverTest.php`, `apps/platform/tests/Feature/Workspaces/ManagedTenantOnboardingProviderStartTest.php`, and `apps/platform/tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php` **Checkpoint**: User Stories 1 and 2 now expose the same canonical operation identity across monitoring and onboarding bootstrap state. --- ## Phase 5: User Story 3 - Extend Operation Families Without Creating Peer Truths (Priority: P2) **Goal**: Harden provider-start and representative write paths so future work cannot silently reintroduce raw alias writers or alternate registry truth. **Independent Test**: Run focused registry, start-gate, and architecture guard coverage and verify raw alias write-time values fail while historical read-side compatibility remains explicitly bounded. ### Tests for User Story 3 - [X] T021 [P] [US3] Add provider registry and start-gate canonical contract coverage in `apps/platform/tests/Unit/Providers/ProviderOperationRegistryCanonicalTypeTest.php` and `apps/platform/tests/Unit/Providers/ProviderOperationStartGateTest.php` - [X] T022 [P] [US3] Extend raw-alias reintroduction guard coverage in `apps/platform/tests/Architecture/PlatformVocabularyBoundaryGuardTest.php` and `apps/platform/tests/Unit/Support/OperationRunTypeCanonicalContractTest.php` ### Implementation for User Story 3 - [X] T023 [US3] Replace legacy registry `operation_type` values with canonical dotted codes and bounded read-side-only semantics in `apps/platform/app/Services/Providers/ProviderOperationRegistry.php` and `apps/platform/app/Services/Providers/ProviderOperationStartGate.php` - [X] T024 [US3] Converge representative `OperationRun` writers on canonical dotted types in `apps/platform/app/Services/Inventory/InventorySyncService.php`, `apps/platform/app/Services/BackupScheduling/BackupScheduleDispatcher.php`, `apps/platform/app/Services/ReviewPackService.php`, `apps/platform/app/Services/Evidence/EvidenceSnapshotService.php`, and `apps/platform/app/Services/TenantReviews/TenantReviewService.php` - [X] T025 [US3] Document and enforce the remaining read-side compatibility boundary in `apps/platform/app/Support/OperationCatalog.php` and `specs/239-canonical-operation-type-source-of-truth/contracts/canonical-operation-type-source-of-truth.logical.openapi.yaml` - [X] T026 [US3] Run the relevant quickstart verification blocks for US3 from `specs/239-canonical-operation-type-source-of-truth/quickstart.md` (expanded narrow proving lane plus guardrail proof) against `apps/platform/tests/Unit/Providers/ProviderOperationRegistryCanonicalTypeTest.php`, `apps/platform/tests/Unit/Providers/ProviderOperationStartGateTest.php`, `apps/platform/tests/Unit/Support/OperationRunTypeCanonicalContractTest.php`, and `apps/platform/tests/Architecture/PlatformVocabularyBoundaryGuardTest.php` **Checkpoint**: All user stories are independently functional, and representative write paths are locked behind focused canonical-operation guardrails. --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Refresh implementation notes, run final narrow validation, and close out the bounded compatibility seam explicitly. - [X] T027 [P] Refresh implementation notes, logical contract wording, and validation commands in `specs/239-canonical-operation-type-source-of-truth/spec.md`, `specs/239-canonical-operation-type-source-of-truth/plan.md`, `specs/239-canonical-operation-type-source-of-truth/quickstart.md`, and `specs/239-canonical-operation-type-source-of-truth/contracts/canonical-operation-type-source-of-truth.logical.openapi.yaml` - [X] T028 [P] Run formatting for touched files in `apps/platform/app/Support/`, `apps/platform/app/Services/`, `apps/platform/app/Filament/Pages/Workspaces/`, `apps/platform/app/Filament/Resources/`, `apps/platform/app/Http/Controllers/`, and `apps/platform/tests/` - [X] T029 Run the full quickstart verification sequence from `specs/239-canonical-operation-type-source-of-truth/quickstart.md` against `apps/platform/tests/Unit/Support/OperationTypeResolutionTest.php`, `apps/platform/tests/Unit/Support/OperationRunTypeCanonicalContractTest.php`, `apps/platform/tests/Unit/Providers/ProviderOperationRegistryCanonicalTypeTest.php`, `apps/platform/tests/Unit/Providers/ProviderOperationStartGateTest.php`, `apps/platform/tests/Unit/Onboarding/OnboardingDraftResolverTest.php`, `apps/platform/tests/Feature/Filament/OperationRunListFiltersTest.php`, `apps/platform/tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, `apps/platform/tests/Feature/Guards/OperationRunLinkContractGuardTest.php`, `apps/platform/tests/Feature/Monitoring/AuditCoverageOperationsTest.php`, `apps/platform/tests/Feature/Monitoring/OperationsTenantScopeTest.php`, `apps/platform/tests/Feature/Monitoring/OperationsDbOnlyRenderTest.php`, `apps/platform/tests/Feature/OpsUx/UnknownOperationTypeLabelTest.php`, `apps/platform/tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php`, `apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php`, `apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php`, `apps/platform/tests/Feature/Workspaces/ManagedTenantOnboardingProviderStartTest.php`, `apps/platform/tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php`, and `apps/platform/tests/Architecture/PlatformVocabularyBoundaryGuardTest.php` - [X] T030 Record the guardrail close-out, `document-in-feature` disposition for the bounded read-side seam, and any deferred `follow-up-spec` boundary in `specs/239-canonical-operation-type-source-of-truth/plan.md` and `specs/239-canonical-operation-type-source-of-truth/quickstart.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 stories. - **User Story 1 (Phase 3)**: Depends on Foundational completion. - **User Story 2 (Phase 4)**: Depends on Foundational completion and should coordinate with User Story 1 where `apps/platform/app/Services/Audit/AuditEventBuilder.php` is shared. - **User Story 3 (Phase 5)**: Depends on Foundational completion and should follow User Story 2 because provider-start hardening is the narrowest proof once onboarding handoff already emits canonical codes. - **Polish (Phase 6)**: Depends on all desired user stories being complete. ### User Story Dependencies - **User Story 1 (P1)**: This is the demonstration MVP for operator-visible monitoring parity. - **User Story 2 (P1)**: Conceptually independent after Phase 2, but it shares `apps/platform/app/Services/Audit/AuditEventBuilder.php` with User Story 1 and should reuse the same canonical metadata truth. - **User Story 3 (P2)**: Depends on the foundational contract and should harden provider-start and representative writers only after User Story 2 proves onboarding now hands off canonical codes. ### Within Each User Story - Tests should be written and fail before the corresponding implementation tasks. - Phase 2 must settle the canonical dotted contract before any read-model, onboarding, or provider-start adoption task lands. - Serialize edits in `apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` across T017, T018, and T019. - Serialize edits in `apps/platform/app/Services/Audit/AuditEventBuilder.php` across T012 and T019. - Finish each story’s validation task before moving to the next priority when working sequentially. ### Parallel Opportunities - **Setup**: T002 and T003 can run in parallel. - **Foundational**: T004 and T005 can run in parallel before T006; T007 follows T006. - **US1 tests**: T008 and T009 can run in parallel. - **US1 implementation**: T011, T012, and T013 can run in parallel after T010 settles the primary filter/read-model behavior. - **US2 tests**: T015 and T016 can run in parallel. - **US3 tests**: T021 and T022 can run in parallel. - **Polish**: T027 and T028 can run in parallel before T029 and T030. --- ## Parallel Example: User Story 1 ```bash # Run US1 proof tasks in parallel: T008 apps/platform/tests/Feature/Filament/OperationRunListFiltersTest.php T009 apps/platform/tests/Feature/Monitoring/AuditCoverageOperationsTest.php and apps/platform/tests/Feature/OpsUx/UnknownOperationTypeLabelTest.php # Then split non-overlapping implementation follow-up: T011 apps/platform/app/Support/OpsUx/OperationUxPresenter.php, apps/platform/app/Support/References/Resolvers/OperationRunReferenceResolver.php, and apps/platform/app/Support/OperationRunLinks.php T013 apps/platform/app/Services/SystemConsole/OperationRunTriageService.php, apps/platform/app/Services/Evidence/Sources/OperationsSummarySource.php, and apps/platform/app/Services/Runbooks/FindingsLifecycleBackfillRunbookService.php ``` --- ## Parallel Example: User Story 2 ```bash # Run US2 proof tasks in parallel: T015 apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php and apps/platform/tests/Unit/Onboarding/OnboardingDraftResolverTest.php T016 apps/platform/tests/Feature/Workspaces/ManagedTenantOnboardingProviderStartTest.php and apps/platform/tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php ``` --- ## Parallel Example: User Story 3 ```bash # Run US3 guard tasks in parallel: T021 apps/platform/tests/Unit/Providers/ProviderOperationRegistryCanonicalTypeTest.php and apps/platform/tests/Unit/Providers/ProviderOperationStartGateTest.php T022 apps/platform/tests/Architecture/PlatformVocabularyBoundaryGuardTest.php and apps/platform/tests/Unit/Support/OperationRunTypeCanonicalContractTest.php ``` --- ## Implementation Strategy ### MVP First (User Story 1 Demonstration) 1. Complete Phase 1: Setup. 2. Complete Phase 2: Foundational. 3. Complete Phase 3: User Story 1. 4. Stop and validate with T014. 5. Review whether operations filters, labels, references, and audit-adjacent summaries now teach one canonical `operation_type` truth. Even if User Story 1 is demoable on its own, User Stories 2 and 3 should land before merge because the active write surfaces and anti-drift guardrails are part of the accepted scope. ### Incremental Delivery 1. Setup and Foundational establish one canonical dotted contract and bounded read-side seam. 2. Add User Story 1 and validate monitoring/filter/read-model parity. 3. Add User Story 2 and validate onboarding bootstrap lifecycle and canonical start handoff. 4. Add User Story 3 and validate provider-start truth plus representative writer guardrails. 5. Finish with formatting, final validation, and explicit close-out of the remaining compatibility seam. ### Parallel Team Strategy With multiple developers: 1. Complete Setup and Foundational together. 2. After Phase 2: - Developer A: User Story 1 read-model parity in `apps/platform/app/Filament/Resources/OperationRunResource.php`, `apps/platform/app/Support/Filament/FilterOptionCatalog.php`, and the shared presenter/reference files. - Developer B: User Story 2 onboarding bootstrap normalization in `apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `apps/platform/app/Services/Onboarding/OnboardingLifecycleService.php`. - Developer C: User Story 3 provider-start and representative write-path hardening in `apps/platform/app/Services/Providers/ProviderOperationRegistry.php`, `apps/platform/app/Services/Providers/ProviderOperationStartGate.php`, and the representative writer services. 3. Serialize edits in `apps/platform/app/Services/Audit/AuditEventBuilder.php` and `apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` because multiple story tasks touch those files. ### Suggested MVP Scope The narrowest demonstration slice is Phase 1 through Phase 3. The narrowest merge-ready slice is Phase 1 through Phase 5, with Phase 6 reserved for close-out and final proof. --- ## Notes - `[P]` marks tasks that can run in parallel once prerequisites are satisfied and files do not overlap. - `[US1]`, `[US2]`, and `[US3]` map directly to the user stories in `spec.md`. - Keep this feature strictly scoped to canonical `operation_type` truth. Do not widen into broader naming cleanup, governed-subject taxonomy work, monitoring IA redesign, or a generic compatibility framework. - The only allowed compatibility seam is read-side resolution for historical `operation_runs.type` rows and persisted onboarding draft state already covered in the plan and logical contract.