ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
fb32e9bfa5
TenantAtlas/specs/239-canonical-operation-type-source-of-truth/tasks.md
ahmido fb32e9bfa5
Some checks failed
Main Confidence / confidence (push) Failing after 49s
Details
feat: canonical operation type source of truth (#276) 
## Summary
- implement the canonical operation type source-of-truth slice across operation writers, monitoring surfaces, onboarding flows, and supporting services
- add focused contract and regression coverage for canonical operation type handling
- include the generated spec 239 artifacts for the feature slice

## Validation
- browser smoke PASS for `/admin` -> workspace overview -> operations -> operation detail -> tenant-scoped operations drilldown
- spec/plan/tasks/quickstart artifact analysis cleaned up to a no-findings state
- automated test suite not run in this session

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #276
2026-04-25 18:11:23 +00:00

24 KiB
Raw Blame History

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

  • Lane assignment stays Unit plus Feature plus existing Heavy-Governance and remains the narrowest sufficient proof for the changed behavior.
  • 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.
  • Shared helpers, factories, seeds, onboarding draft defaults, and operation fixtures stay cheap by default; no new alias-preserving helper layer is introduced.
  • 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.
  • The declared surface test profile remains monitoring-state-page plus standard-native-filament; no exception-coded surface or browser proof is required.
  • 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.

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

  • 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
  • T005 [P] Add enum and vocabulary anti-drift coverage in apps/platform/tests/Unit/Support/OperationRunTypeCanonicalContractTest.php and apps/platform/tests/Architecture/PlatformVocabularyBoundaryGuardTest.php
  • 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
  • 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

  • T008 [P] [US1] Extend canonical filter convergence coverage in apps/platform/tests/Feature/Filament/OperationRunListFiltersTest.php
  • 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

  • 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
  • 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
  • T012 [P] [US1] Canonicalize audit-adjacent operation metadata in apps/platform/app/Services/Audit/AuditEventBuilder.php and apps/platform/app/Services/OperationRunService.php
  • 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
  • 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

  • T015 [P] [US2] Extend onboarding draft canonicalization coverage in apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php and apps/platform/tests/Unit/Onboarding/OnboardingDraftResolverTest.php
  • 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

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

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

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

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

# 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

# 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

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