ahmido
7541b1eb41
## Summary - introduce the governance subject taxonomy registry and canonical Baseline Scope V2 normalization and persistence - update baseline profile Filament surfaces, validation, capture/compare gating, and add the optional scope backfill command with audit logging - add focused unit, feature, Filament, and browser smoke coverage for save-forward behavior, operation truth, authorization continuity, and invalid-scope rendering - remove the duplicate legacy spec plan under `specs/001-governance-subject-taxonomy/plan.md` ## Verification - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec202GovernanceSubjectTaxonomySmokeTest.php` - focused Spec 202 regression pack: `56 passed (300 assertions)` - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` ## Notes - no schema migration required - no new Filament asset registration required - branch includes the final browser smoke test coverage for the current feature Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #232
246 lines
21 KiB
Markdown
246 lines
21 KiB
Markdown
# 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.
|
||
|
||
- [X] T001 Create the governance taxonomy registry test scaffold in `apps/platform/tests/Unit/Baselines/GovernanceSubjectTaxonomyRegistryTest.php`
|
||
- [X] T002 [P] Create the canonical scope persistence test scaffold in `apps/platform/tests/Feature/Filament/BaselineProfileScopeV2PersistenceTest.php`
|
||
- [X] 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.
|
||
|
||
- [X] 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`
|
||
- [X] 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`
|
||
- [X] 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`
|
||
- [X] 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`
|
||
- [X] 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`
|
||
- [X] 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`
|
||
- [X] T010 Wire canonical scope normalization and save-forward persistence into `apps/platform/app/Support/Baselines/BaselineScope.php` and `apps/platform/app/Models/BaselineProfile.php`
|
||
- [X] 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.
|
||
|
||
- [X] 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`
|
||
- [X] 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`
|
||
- [X] 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
|
||
|
||
- [X] 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`
|
||
- [X] 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.
|
||
|
||
- [X] T017 [P] [US2] Add canonical V2 create and update persistence coverage in `apps/platform/tests/Feature/Filament/BaselineProfileScopeV2PersistenceTest.php`
|
||
- [X] 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`
|
||
- [X] 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
|
||
|
||
- [X] 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`
|
||
- [X] 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`
|
||
- [X] 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`
|
||
- [X] 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.
|
||
|
||
- [X] 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`
|
||
- [X] 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`
|
||
- [X] 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
|
||
|
||
- [X] 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`
|
||
- [X] 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`
|
||
- [X] 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.
|
||
|
||
- [X] 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`
|
||
- [X] 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
|
||
|
||
- [X] 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`
|
||
- [X] 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`
|
||
- [X] 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.
|
||
|
||
- [X] T035 [P] Add cross-cutting operation-truth assertions for canonical effective scope and compatibility projection in `apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`
|
||
- [X] 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`
|
||
- [X] 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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. |