TenantAtlas/specs/202-governance-subject-taxonomy/tasks.md

Tasks: Governance Subject Taxonomy and Baseline Scope V2

Input: Design documents from /specs/202-governance-subject-taxonomy/
Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/governance-subject-taxonomy.logical.openapi.yaml, quickstart.md

Tests: Required. This feature changes runtime baseline scope persistence, Filament baseline surfaces, and capture or compare start behavior, so Pest unit, feature, and Filament coverage must be added or extended.

Organization: Tasks are grouped by user story so each slice stays independently testable. Recommended delivery order is US1 -> US2 -> US3 -> US4, with US1 as the MVP cut after the shared taxonomy, transition, and normalization foundation is in place.

Phase 1: Setup (Shared Infrastructure)

Purpose: Prepare focused test entry points for taxonomy, canonical scope persistence, and rollout maintenance.

• T001 Create the governance taxonomy registry test scaffold in apps/platform/tests/Unit/Baselines/GovernanceSubjectTaxonomyRegistryTest.php
• T002 [P] Create the canonical scope persistence test scaffold in apps/platform/tests/Feature/Filament/BaselineProfileScopeV2PersistenceTest.php
• T003 [P] Create the rollout backfill command test scaffold in apps/platform/tests/Feature/Baselines/BaselineScopeBackfillCommandTest.php

Checkpoint: Dedicated Spec 202 test entry points exist and implementation can proceed without mixing this slice into unrelated suites.

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Codify the shared governance taxonomy, canonical scope, and transition infrastructure that every user story depends on.

⚠️ CRITICAL: No user story work should start before this phase is complete.

• T004 [P] Add taxonomy composition, Intune and foundation mapping, and future-domain plausibility expectations in apps/platform/tests/Unit/Baselines/GovernanceSubjectTaxonomyRegistryTest.php and apps/platform/tests/Unit/Baselines/InventoryMetaContractTest.php
• T005 [P] Add canonical V2 normalization, duplicate merge, mixed-payload rejection, default-empty filters coverage, and legacy empty-list plus missing-key defaults coverage in apps/platform/tests/Unit/Baselines/BaselineScopeTest.php
• T006 [P] Add transition-safe effective-scope compatibility projection coverage in apps/platform/tests/Feature/Baselines/BaselineCaptureTest.php, apps/platform/tests/Feature/Baselines/BaselineComparePreconditionsTest.php, and apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
• T007 Implement platform-facing governance domain and subject-class value objects in apps/platform/app/Support/Governance/GovernanceDomainKey.php and apps/platform/app/Support/Governance/GovernanceSubjectClass.php
• T008 Implement the governance subject type record and composed taxonomy registry in apps/platform/app/Support/Governance/GovernanceSubjectType.php and apps/platform/app/Support/Governance/GovernanceSubjectTaxonomyRegistry.php
• T009 Implement registry composition against existing metadata in apps/platform/config/tenantpilot.php, apps/platform/app/Support/Inventory/InventoryPolicyTypeMeta.php, and apps/platform/app/Support/Governance/GovernanceSubjectTaxonomyRegistry.php
• T010 Wire canonical scope normalization and save-forward persistence into apps/platform/app/Support/Baselines/BaselineScope.php and apps/platform/app/Models/BaselineProfile.php
• T011 Inventory effective-scope consumers and implement transition-safe compatibility projection plus canonical operation context in apps/platform/app/Services/Baselines/BaselineCaptureService.php and apps/platform/app/Services/Baselines/BaselineCompareService.php

Checkpoint: The repo can compose active governance subject metadata, prove future-safe contract shape, normalize legacy and V2 scope deterministically, persist canonical scope, and retain only the transition compatibility projection still required by current consumers.

---

Phase 3: User Story 1 - Keep Existing Intune Baselines Usable (Priority: P1) 🎯 MVP

Goal: Preserve the current Intune baseline workflow while the underlying scope contract moves to canonical V2.

Independent Test: Open a legacy baseline profile, verify its normalized scope renders understandably, save it, then launch baseline capture and compare and confirm behavior remains unchanged.

Tests for User Story 1

Note

: Write these tests first and confirm they fail before implementation.

• T012 [P] [US1] Add legacy profile load, on-demand normalization-lineage, and save-forward coverage in apps/platform/tests/Feature/Filament/BaselineProfileScopeV2PersistenceTest.php and apps/platform/tests/Feature/Filament/BaselineProfileFoundationScopeTest.php
• T013 [P] [US1] Extend legacy capture and compare no-regression coverage in apps/platform/tests/Feature/Baselines/BaselineCaptureTest.php, apps/platform/tests/Feature/Baselines/BaselineComparePreconditionsTest.php, and apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
• T014 [P] [US1] Extend baseline authorization continuity coverage for legacy-scope save and start actions in apps/platform/tests/Feature/Baselines/BaselineProfileAuthorizationTest.php and apps/platform/tests/Feature/Filament/BaselineActionAuthorizationTest.php

Implementation for User Story 1

• T015 [US1] Keep legacy baseline detail and start-surface flows stable while reading normalized scope in apps/platform/app/Filament/Resources/BaselineProfileResource.php and apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php
• T016 [US1] Preserve capture and compare readiness semantics on the baseline view surface while canonical scope rolls out in apps/platform/app/Filament/Resources/BaselineProfileResource.php and apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php

Checkpoint: Legacy Intune baseline profiles remain independently usable for load, save, capture, and compare after canonical scope normalization lands.

---

Phase 4: User Story 2 - Define a Baseline with Explicit Governed-Subject Semantics (Priority: P1)

Goal: Keep the current Intune-first workflow while making the saved baseline contract explicit about domain, subject class, and subject families.

Independent Test: Create a new baseline profile through the existing baseline form and confirm the stored scope is canonical V2 with explicit domain and subject-class semantics and an operator-safe summary.

Tests for User Story 2

Note

: Write these tests first and confirm they fail before implementation.

• T017 [P] [US2] Add canonical V2 create and update persistence coverage in apps/platform/tests/Feature/Filament/BaselineProfileScopeV2PersistenceTest.php
• T018 [P] [US2] Add create and edit form summary, active subject-group, support-readiness, and invalid-selection feedback coverage in apps/platform/tests/Feature/Filament/BaselineProfileScopeV2PersistenceTest.php and apps/platform/tests/Feature/Filament/BaselineProfileFoundationScopeTest.php
• T019 [P] [US2] Add hidden-raw-json and readiness copy coverage in apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php and apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php

Implementation for User Story 2

• T020 [US2] Update create and edit form state handling to translate Intune-first selectors into canonical V2 entries with empty-by-default filters in apps/platform/app/Filament/Resources/BaselineProfileResource.php, apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/CreateBaselineProfile.php, and apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/EditBaselineProfile.php
• T021 [US2] Render normalized scope summaries, active subject groups, support readiness, and invalid-selection feedback on create and edit surfaces in apps/platform/app/Filament/Resources/BaselineProfileResource.php, apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/CreateBaselineProfile.php, and apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/EditBaselineProfile.php
• T022 [US2] Add normalized governed-subject summaries with operator-safe selected labels and on-demand normalization lineage to the baseline detail surface in apps/platform/app/Filament/Resources/BaselineProfileResource.php and apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php
• T023 [US2] Keep operator-facing scope vocabulary platform-safe while remaining Intune-first in apps/platform/app/Support/Governance/GovernanceSubjectTaxonomyRegistry.php and apps/platform/app/Filament/Resources/BaselineProfileResource.php

Checkpoint: New and updated baseline profiles are independently functional with canonical V2 persistence, explicit form feedback, and clear governed-subject summaries.

---

Phase 5: User Story 3 - Reject Unsupported Combinations Before Work Starts (Priority: P2)

Goal: Fail invalid or unsupported scope selections before any capture or compare run is created.

Independent Test: Attempt to save or execute scope selections with an unknown domain, invalid class, inactive subject type, unsupported filter payload, or unsupported capture or compare combination and verify the action is blocked clearly before any run starts.

Tests for User Story 3

Note

: Write these tests first and confirm they fail before implementation.

• T024 [P] [US3] Add invalid domain, invalid class, inactive-type, mixed-payload, and future-domain selection rejection coverage in apps/platform/tests/Unit/Baselines/BaselineScopeTest.php and apps/platform/tests/Unit/Baselines/GovernanceSubjectTaxonomyRegistryTest.php
• T025 [P] [US3] Extend create and edit save validation coverage for inactive subject types and unsupported filters in apps/platform/tests/Feature/Filament/BaselineProfileScopeV2PersistenceTest.php and apps/platform/tests/Feature/Filament/BaselineProfileFoundationScopeTest.php
• T026 [P] [US3] Extend capture and compare pre-run gating coverage in apps/platform/tests/Feature/Baselines/BaselineCaptureTest.php, apps/platform/tests/Feature/Baselines/BaselineComparePreconditionsTest.php, apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php, and apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php

Implementation for User Story 3

• T027 [US3] Implement unknown-domain, invalid-class, inactive-type, future-domain, and filter guardrails in apps/platform/app/Support/Baselines/BaselineScope.php and apps/platform/app/Support/Governance/GovernanceSubjectTaxonomyRegistry.php
• T028 [US3] Enforce capture and compare eligibility gating before run creation in apps/platform/app/Services/Baselines/BaselineCaptureService.php and apps/platform/app/Services/Baselines/BaselineCompareService.php
• T029 [US3] Surface deterministic validation and readiness feedback without exposing inactive future domains in apps/platform/app/Filament/Resources/BaselineProfileResource.php, apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/CreateBaselineProfile.php, apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/EditBaselineProfile.php, and apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php

Checkpoint: Invalid or unsupported scope combinations are independently blocked before save, capture, or compare work begins.

---

Phase 6: User Story 4 - Roll Out Progressively Without Forced Migration Churn (Priority: P3)

Goal: Keep legacy rows readable during rollout and provide an optional cleanup path once canonical V2 behavior is trusted.

Independent Test: Keep a mixed dataset of legacy and V2 baseline profiles, verify both remain usable, then run the optional cleanup path and confirm legacy rows are rewritten without changing their governed-subject meaning.

Tests for User Story 4

Note

: Write these tests first and confirm they fail before implementation.

• T030 [P] [US4] Add mixed legacy profile-scope dataset coverage plus dry-run preview, explicit write confirmation, audit logging, and idempotent backfill assertions in apps/platform/tests/Feature/Baselines/BaselineScopeBackfillCommandTest.php
• T031 [P] [US4] Extend tolerant-read, compatibility-projection, save-forward rollout coverage for untouched and rewritten profile rows, and compare assignment-override normalization coverage in apps/platform/tests/Feature/Filament/BaselineProfileScopeV2PersistenceTest.php and apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php

Implementation for User Story 4

• T032 [US4] Create the optional baseline scope backfill command with preview-by-default and explicit write confirmation in apps/platform/app/Console/Commands/BackfillBaselineScopeV2.php
• T033 [US4] Implement legacy baseline-profile row selection, canonical rewrite, idempotent reporting, and audit logging in apps/platform/app/Console/Commands/BackfillBaselineScopeV2.php and apps/platform/app/Models/BaselineProfile.php
• T034 [US4] Keep assignment-override reads and mixed-dataset compare behavior tolerant in apps/platform/app/Support/Baselines/BaselineScope.php and apps/platform/app/Services/Baselines/BaselineCompareService.php

Checkpoint: Mixed legacy and V2 datasets remain independently usable, and optional cleanup can be run later without semantic drift.

---

Phase 7: Polish & Cross-Cutting Concerns

Purpose: Lock the slice down with operation-truth, authorization, and focused verification coverage.

• T035 [P] Add cross-cutting operation-truth assertions for canonical effective scope and compatibility projection in apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
• T036 [P] Recheck baseline authorization and operator-copy regressions in apps/platform/tests/Feature/Baselines/BaselineProfileAuthorizationTest.php, apps/platform/tests/Feature/Filament/BaselineActionAuthorizationTest.php, and apps/platform/tests/Feature/Filament/BaselineProfileFoundationScopeTest.php
• T037 [P] Run the full required Sail verification and formatting workflow from specs/202-governance-subject-taxonomy/quickstart.md

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies; can start immediately.
• Foundational (Phase 2): Depends on Setup completion; blocks all user stories.
• User Story 1 (Phase 3): Depends on Foundational completion; this is the recommended MVP cut.
• User Story 2 (Phase 4): Depends on Foundational completion and is easiest to review after US1 proves no-regression behavior.
• User Story 3 (Phase 5): Depends on Foundational completion and should land after the P1 persistence and summary work stabilizes.
• User Story 4 (Phase 6): Depends on Foundational completion and should land after the P1 and P2 rollout behavior is trusted.
• Polish (Phase 7): Depends on all desired user stories being complete.

User Story Dependencies

• US1: No dependencies beyond Foundational.
• US2: No hard dependency beyond Foundational, but it builds most cleanly after US1 proves the no-regression save-forward path.
• US3: Depends on the shared taxonomy, default filter semantics, and transition infrastructure from Foundational and should be verified against the P1 surfaces.
• US4: Depends on the shared infrastructure and should follow the rollout behavior established by US1 through US3.

Within Each User Story

• Write the story tests first and confirm they fail before implementation.
• Keep changes inside the existing baseline model, services, and Filament resource surfaces unless a task explicitly introduces a new governance support file or maintenance command.
• Finish each story’s focused verification before moving to the next priority.

Parallel Opportunities

• T002 and T003 can run in parallel after T001.
• T004, T005, and T006 can run in parallel before T007 through T011.
• Within US1, T012, T013, and T014 can run in parallel.
• Within US2, T017, T018, and T019 can run in parallel.
• Within US3, T024, T025, and T026 can run in parallel.
• Within US4, T030 and T031 can run in parallel.
• T035, T036, and T037 can run in parallel once implementation is complete.

---

Parallel Example: User Story 1

# Parallel test pass for US1
T012 Add legacy profile load, on-demand normalization-lineage, and save-forward coverage in apps/platform/tests/Feature/Filament/BaselineProfileScopeV2PersistenceTest.php and apps/platform/tests/Feature/Filament/BaselineProfileFoundationScopeTest.php
T013 Extend legacy capture and compare no-regression coverage in apps/platform/tests/Feature/Baselines/BaselineCaptureTest.php, apps/platform/tests/Feature/Baselines/BaselineComparePreconditionsTest.php, and apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
T014 Extend baseline authorization continuity coverage in apps/platform/tests/Feature/Baselines/BaselineProfileAuthorizationTest.php and apps/platform/tests/Feature/Filament/BaselineActionAuthorizationTest.php

Parallel Example: User Story 2

# Parallel test pass for US2
T017 Add canonical V2 create and update persistence coverage in apps/platform/tests/Feature/Filament/BaselineProfileScopeV2PersistenceTest.php
T018 Add create and edit form summary, active subject-group, support-readiness, and invalid-selection feedback coverage in apps/platform/tests/Feature/Filament/BaselineProfileScopeV2PersistenceTest.php and apps/platform/tests/Feature/Filament/BaselineProfileFoundationScopeTest.php
T019 Add hidden-raw-json and readiness copy coverage in apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php and apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php

Parallel Example: User Story 3

# Parallel test pass for US3
T024 Add invalid domain, invalid class, inactive-type, mixed-payload, and future-domain selection rejection coverage in apps/platform/tests/Unit/Baselines/BaselineScopeTest.php and apps/platform/tests/Unit/Baselines/GovernanceSubjectTaxonomyRegistryTest.php
T025 Extend create and edit save validation coverage for inactive subject types and unsupported filters in apps/platform/tests/Feature/Filament/BaselineProfileScopeV2PersistenceTest.php and apps/platform/tests/Feature/Filament/BaselineProfileFoundationScopeTest.php
T026 Extend capture and compare pre-run gating coverage in apps/platform/tests/Feature/Baselines/BaselineCaptureTest.php, apps/platform/tests/Feature/Baselines/BaselineComparePreconditionsTest.php, and apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php and apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php

Parallel Example: User Story 4

# Parallel test pass for US4
T030 Add mixed legacy and V2 dataset coverage plus dry-run preview, explicit write confirmation, audit logging, and idempotent backfill assertions in apps/platform/tests/Feature/Baselines/BaselineScopeBackfillCommandTest.php
T031 Extend tolerant-read, compatibility-projection, and save-forward rollout coverage for untouched and rewritten rows in apps/platform/tests/Feature/Filament/BaselineProfileScopeV2PersistenceTest.php and apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php

---

Implementation Strategy

MVP First (User Story 1 Only)

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational taxonomy, transition, and canonical scope work.
3. Complete Phase 3: User Story 1.
4. Validate legacy load, save, capture, and compare behavior with the focused US1 tests.
5. Stop and review the no-regression baseline workflow before widening the slice.

Incremental Delivery

1. Ship US1 to prove canonical scope can land without breaking current Intune baselines.
2. Add US2 to make new and updated baseline profiles explicit about governed-subject semantics and create or edit feedback.
3. Add US3 to block invalid or unsupported scope combinations before work starts.
4. Add US4 to provide an optional cleanup path after rollout confidence exists.
5. Finish with operation-truth, authorization, and focused verification work from Phase 7.

Parallel Team Strategy

1. One contributor completes Setup and Foundational tasks.
2. After Foundation is green:
   • Contributor A takes US1.
   • Contributor B prepares the US2 test pass and follows once the no-regression path is stable.
   • Contributor C prepares the US3 validation and gating tests against the canonical scope foundation.
   • Contributor D prepares the US4 cleanup command tests.
3. Merge back for Phase 7 verification and formatting.