TenantAtlas/specs/001-governance-subject-taxonomy/plan.md

Implementation Plan: Governance Subject Taxonomy and Baseline Scope V2

Branch: 001-governance-subject-taxonomy | Date: 2026-04-13 | Spec: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/001-governance-subject-taxonomy/spec.md Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/001-governance-subject-taxonomy/spec.md

Note: This plan upgrades baseline scope semantics from legacy Intune-shaped lists to a versioned governance-subject contract while preserving current Intune baseline behavior and keeping rollout risk low.

Summary

Introduce a platform-safe governance subject taxonomy registry and a canonical Baseline Scope V2 document for existing baseline profiles. Reuse current config catalogs and support metadata as registry contributors, evolve the existing BaselineScope integration point into a V2-aware normalizer, persist canonical V2 on save, keep the current Intune-first baseline UI understandable, and route baseline capture and compare through normalized effective scope with explicit eligibility validation and auditable operation context. No new table, no new OperationRun type, and no broad policy_type rename are required.

Technical Context

Language/Version: PHP 8.4.15
Primary Dependencies: Laravel 12, Filament v5, Livewire v4, Pest v4, Tailwind CSS v4, Laravel Sail, existing BaselineScope, InventoryPolicyTypeMeta, BaselineSupportCapabilityGuard, BaselineCaptureService, and BaselineCompareService
Storage: PostgreSQL via existing baseline_profiles.scope_jsonb, baseline_tenant_assignments.override_scope_jsonb, and operation_runs.context; no new tables planned
Testing: Pest unit, feature, and focused Filament Livewire tests run through Laravel Sail
Target Platform: Laravel monolith web application under apps/platform
Project Type: web application
Performance Goals: Keep taxonomy lookup and scope normalization fully in-process, avoid new remote calls or query fan-out on baseline surfaces, and keep capture or compare start overhead effectively unchanged aside from deterministic validation
Constraints: No eager migration, no new OperationRun type, no broad repo-wide policy_type rename, no generic plugin system, no UI overclaim of inactive domains, and no new panel/provider or asset work
Scale/Scope: One workspace-owned baseline resource, one model-cast integration point, two baseline start services, one config-backed taxonomy contributor set, one optional maintenance command, and focused unit/feature/Filament regression coverage

Constitution Check

GATE: Passed before Phase 0 research. Re-checked after Phase 1 design and still passing.

Principle	Pre-Research	Post-Design	Notes
Inventory-first / snapshots-second	PASS	PASS	The feature changes baseline definition semantics only; inventory and snapshot truth sources remain unchanged.
Read/write separation	PASS	PASS	Save-forward writes stay on existing baseline profile save flows and retain current audit behavior; capture and compare still run through existing operation starts.
Graph contract path	N/A	N/A	No new Microsoft Graph path or contract-registry change is introduced.
Deterministic capabilities	PASS	PASS	The new taxonomy registry reuses existing config plus InventoryPolicyTypeMeta::baselineSupportContract() and remains snapshot-testable.
Workspace + tenant isolation	PASS	PASS	Baseline profiles remain workspace-owned; tenant compare and capture operations remain tenant-scoped and unchanged in authorization boundaries.
RBAC-UX authorization semantics	PASS	PASS	No new authorization plane or capability path is introduced; non-members remain 404 and in-scope capability failures remain 403.
Run observability / Ops-UX	PASS	PASS	Existing baseline_capture and baseline_compare runs are reused; only the effective scope payload becomes canonical and more explicit.
Data minimization	PASS	PASS	No new persistence or secret-bearing payloads are introduced; scope remains derived from existing config and baseline data.
Proportionality / anti-bloat	PASS	PASS	The registry and V2 scope are justified by a current contract problem and two existing concrete catalogs; no universal plugin framework is added.
No premature abstraction	PASS	PASS	The registry consolidates existing supported policy types and foundation types into one authoritative contract instead of adding a speculative extension system.
Persisted truth / behavioral state	PASS	PASS	V2 stays inside existing scope_jsonb; no new table or independent lifecycle is added.
UI semantics / few layers	PASS	PASS	Operator summaries derive directly from canonical scope; no presenter or explanation framework is introduced.
Filament v5 / Livewire v4 compliance	PASS	PASS	The plan stays inside existing Filament resources and Livewire-backed pages.
Provider registration location	PASS	PASS	No panel or provider change is required; Laravel 11+ provider registration remains in bootstrap/providers.php.
Global search hard rule	PASS	PASS	BaselineProfileResource already disables global search and this plan does not change that.
Destructive action safety	PASS	PASS	No new destructive action is introduced. Existing destructive actions on baseline surfaces must keep confirmation and authorization unchanged.
Asset strategy	PASS	PASS	No new assets are required. Existing deployment handling of cd apps/platform && php artisan filament:assets remains unchanged.

Filament-Specific Compliance Notes

• Livewire v4.0+ compliance: The affected baseline surfaces remain on Filament v5 + Livewire v4 and no legacy API is introduced.
• Provider registration location: No new panel or provider is needed; Laravel 11+ provider registration remains in bootstrap/providers.php.
• Global search: BaselineProfileResource is already not globally searchable, so the hard rule about view or edit pages is unaffected.
• Destructive actions: This feature adds no new destructive action. Existing destructive actions on baseline surfaces must retain ->requiresConfirmation() and server-side authorization.
• Asset strategy: No global or on-demand asset registration is planned. Deployment handling of cd apps/platform && php artisan filament:assets remains unchanged.
• Testing plan: Extend unit coverage for scope normalization and taxonomy lookups, extend baseline capture and compare feature coverage for normalized effective scope and support gating, extend Filament baseline profile tests for save-forward behavior and UI honesty, and add focused coverage for the optional backfill command.

Phase 0 Research

Research outcomes are captured in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/001-governance-subject-taxonomy/research.md.

Key decisions:

• Evolve the existing BaselineScope integration point into the V2-aware orchestration layer instead of adding a parallel top-level scope class.
• Build the governance taxonomy registry by composing current tenantpilot.supported_policy_types, tenantpilot.foundation_types, and existing baseline support metadata rather than introducing a second config truth source.
• Introduce platform-facing governance domain and subject-class vocabulary separate from the existing baseline support SubjectClass and ResolutionPath enums.
• Map current Intune policy types to domain_key = intune and subject_class = policy, and map current baseline foundations to domain_key = platform_foundation and subject_class = configuration_resource.
• Use tolerant read plus save-forward for rollout and keep backfill as an optional maintenance command, not a migration.
• Keep operator selection Intune-first for now and derive canonical V2 internally rather than expanding the UI into a fake multi-domain selector.
• Record canonical effective scope in operation context while keeping temporary compatibility projections only where existing consumers still require them.
• Merge duplicate entries deterministically when domain, subject class, and filters match, and reject ambiguous overlaps when they do not.

Phase 1 Design

Design artifacts are created under /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/001-governance-subject-taxonomy/:

• research.md: decisions and rejected alternatives for taxonomy, scope, and rollout
• data-model.md: canonical V2 scope document, taxonomy entry model, legacy-ingestion contract, and effective-scope projection
• contracts/governance-subject-taxonomy.logical.openapi.yaml: internal logical contract for registry listing, scope normalization, save-forward writes, and normalized operation starts
• quickstart.md: implementation and verification sequence for the feature

Design decisions:

• Keep the canonical persisted shape explicit: version = 2 plus entries[].
• Make legacy policy_types and foundation_types ingestion-only and normalize them immediately.
• Keep current Filament baseline profile forms Intune-first while rendering normalized scope summaries from canonical V2.
• Reuse existing baseline support capability checks by attaching them to registry entries instead of duplicating support logic in the scope model.
• Store canonical effective scope in operation context for capture and compare so audit and debugging no longer depend on reconstructing legacy lists.
• Keep the optional cleanup path outside normal request flows and implement it as a one-time maintenance command.

Project Structure

Documentation (this feature)

specs/001-governance-subject-taxonomy/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── spec.md
├── contracts/
│   └── governance-subject-taxonomy.logical.openapi.yaml
└── checklists/
    └── requirements.md

Source Code (repository root)

apps/platform/
├── app/
│   ├── Console/Commands/
│   │   └── [optional legacy-scope backfill command]
│   ├── Filament/
│   │   └── Resources/
│   │       ├── BaselineProfileResource.php
│   │       └── BaselineProfileResource/
│   │           └── Pages/
│   │               ├── CreateBaselineProfile.php
│   │               ├── EditBaselineProfile.php
│   │               └── ViewBaselineProfile.php
│   ├── Models/
│   │   └── BaselineProfile.php
│   ├── Services/
│   │   └── Baselines/
│   │       ├── BaselineCaptureService.php
│   │       └── BaselineCompareService.php
│   └── Support/
│       ├── Baselines/
│       │   ├── BaselineScope.php
│       │   ├── BaselineSupportCapabilityGuard.php
│       │   ├── ResolutionPath.php
│       │   └── SubjectClass.php
│       ├── Governance/
│       │   └── [new taxonomy records and registry]
│       └── Inventory/
│           └── InventoryPolicyTypeMeta.php
├── config/
│   └── tenantpilot.php
└── tests/
    ├── Feature/
    │   ├── Baselines/
    │   │   ├── BaselineCaptureTest.php
    │   │   ├── BaselineComparePreconditionsTest.php
    │   │   ├── BaselineSupportCapabilityGuardTest.php
    │   │   └── [new scope-v2 and backfill coverage]
    │   └── Filament/
    │       ├── BaselineProfileFoundationScopeTest.php
    │       ├── BaselineProfileCaptureStartSurfaceTest.php
    │       └── BaselineProfileCompareStartSurfaceTest.php
    └── Unit/
        └── Baselines/
            ├── BaselineScopeTest.php
            └── [new taxonomy registry coverage]

Structure Decision: Keep the work inside the existing baseline model, baseline services, and Filament resource surfaces. Add one narrow Support/Governance namespace for platform-facing taxonomy records and registry logic, but do not introduce a wider plugin or extension framework.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
Governance taxonomy registry	The product already has two concrete baseline subject catalogs and one support-metadata contract that need a single authoritative selection view now	Leaving config arrays and support logic separate would preserve the hidden semantic split that this spec is explicitly fixing
Baseline Scope V2 document and entry model	Legacy dual-list scope cannot express domain, subject class, or future-safe filters and cannot support a stable compare-input contract	Extending policy_types and foundation_types with ad-hoc flags would keep the model Intune-shaped and ambiguous

Proportionality Review

• Current operator problem: Baseline scope still hides governed-subject meaning behind Intune policy lists and an unnamed foundation list, which makes validation, auditability, and compare-input semantics harder than they should be.
• Existing structure is insufficient because: Legacy scope cannot express domain ownership or platform-level subject shape, and the current support metadata lives separately from the selection contract.
• Narrowest correct implementation: Reuse existing config and support contributors, introduce a small taxonomy registry plus V2 scope document, normalize legacy payloads deterministically, and keep UI and run semantics otherwise unchanged.
• Ownership cost created: One new support namespace, explicit mapping maintenance for taxonomy entries, additional normalization and no-regression tests, and one optional backfill command to maintain.
• Alternative intentionally rejected: A local wrapper around legacy arrays or a broad rename/plugin system were rejected because the former keeps the semantic leak and the latter imports unnecessary churn and abstraction.
• Release truth: current-release contract correction that deliberately prepares the input boundary needed for Spec 203

Implementation Strategy

Phase A — Taxonomy Registry and Platform Vocabulary

• Add platform-facing governance domain and subject-class enums or records.
• Implement a taxonomy registry that composes current supported policy types, foundation types, labels, descriptions, and support flags.
• Keep existing support-resolution enums (SubjectClass, ResolutionPath) as internal capability metadata rather than reusing them as the operator-facing taxonomy.

Phase B — Canonical Scope V2 and Legacy Normalization

• Upgrade the current BaselineScope entrypoint to accept legacy and V2 payloads.
• Add canonical V2 entries, deterministic duplicate handling, and strict mixed-payload rejection.
• Preserve derived compatibility helpers only where current UI or tests still require them during rollout.

Phase C — Save-Forward Persistence and UI Integration

• Update baseline profile persistence so new and saved profiles write canonical V2 into scope_jsonb.
• Keep current Intune-first selectors for now, but derive canonical entries from them on save.
• Add normalized scope summaries to touched baseline surfaces without exposing raw V2 JSON.

Phase D — Capture/Compare Integration and Auditable Scope Context

• Route baseline capture and compare through normalized effective scope.
• Apply eligibility gating before enqueue when selected subject types are unsupported for the requested operation.
• Write canonical effective scope into OperationRun.context and retain transitional projections only where existing consumers still need them.

Phase E — Optional Cleanup and Verification

• Add an optional Artisan maintenance command to backfill remaining legacy scope rows to canonical V2.
• Extend unit, feature, and Filament test suites for normalization, save-forward behavior, operation gating, UI honesty, and no-regression baseline flows.
• Keep current audit, authorization, and run-observability behavior green throughout the rollout.

Risk Assessment

Risk	Impact	Likelihood	Mitigation
The registry becomes a second or speculative truth source	High	Medium	Build it from existing config and support metadata contributors rather than from new hand-maintained arrays.
Foundation mapping chooses the wrong domain or subject-class shape	Medium	Medium	Keep the mapping explicit, minimal, and covered by registry tests so it can evolve intentionally in later specs rather than implicitly.
Legacy and V2 payloads silently diverge during transition	High	Medium	Reject mixed payloads, normalize deterministically, and add save-forward plus backfill coverage.
Capture or compare still bypasses canonical scope in one code path	High	Medium	Centralize effective-scope derivation through the upgraded scope contract and add feature tests on both start services.
UI starts implying future domain readiness too early	Medium	Low	Only expose active and supported subject types and keep the current selector intentionally Intune-first.

Test Strategy

• Extend BaselineScopeTest to cover legacy normalization into V2, duplicate merge or rejection rules, mixed-payload rejection, and explicit V2 serialization.
• Add focused registry coverage for domain, subject-class, subject-type, and support-flag mapping from the current config contributors.
• Extend BaselineCaptureTest and BaselineComparePreconditionsTest to assert canonical effective scope and operation-support gating before run creation.
• Add focused feature coverage for the optional backfill command and for legacy rows becoming canonical V2 on save.
• Extend Filament baseline profile tests to verify Intune-first form behavior still works, canonical V2 is persisted, and normalized scope summaries remain operator-safe.
• Keep existing baseline authorization and start-surface tests green so save-forward semantics do not weaken access control or operator-flow clarity.