TenantAtlas/specs/204-platform-core-vocabulary-hardening/plan.md

Implementation Plan: Platform Core Vocabulary Hardening

Branch: 204-platform-core-vocabulary-hardening | Date: 2026-04-13 | Spec: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/204-platform-core-vocabulary-hardening/spec.md Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/204-platform-core-vocabulary-hardening/spec.md

Note: This plan hardens platform-core and platform-near vocabulary by extending the existing governance, operation, and reason-translation layers already in the codebase, rather than introducing a parallel framework or broad rename sweep.

Summary

Reuse the existing App\Support\Governance, App\Support\OperationCatalog, App\Support\OperationRunType, and App\Support\ReasonTranslation seams to define one maintained code-side platform vocabulary glossary, resolve mixed stored operation type codes through one canonical domain-aware operation vocabulary, classify platform reason families separately from domain-owned reason codes, and harden platform-near compare, snapshot, monitoring, review, and reporting contracts to prefer governed-subject descriptors over false-universal policy_type wording. Keep Intune-owned tables, Graph contracts, and adapter-local metadata intentionally Intune-specific, preserve historical run and filter compatibility through alias resolution instead of a mass rewrite, and add regression guards so touched platform surfaces cannot drift back into implicit Intune-as-universal semantics.

Technical Context

Language/Version: PHP 8.4.15
Primary Dependencies: Laravel 12, Filament v5, Livewire v4, Pest v4, Laravel Sail, existing GovernanceSubjectTaxonomyRegistry, BaselineScope, CompareStrategyRegistry, OperationCatalog, OperationRunType, ReasonTranslator, ReasonResolutionEnvelope, ProviderReasonTranslator, and current Filament monitoring or review surfaces
Storage: PostgreSQL via existing operation_runs.type, operation_runs.context, baseline_profiles.scope_jsonb, baseline_snapshot_items, findings, evidence payloads, and current config-backed registries; no new top-level tables planned
Testing: Pest unit, feature, architecture, and focused Filament Livewire tests run through Laravel Sail
Target Platform: Laravel monolith web application under apps/platform with queue-backed operations and Filament admin or operator surfaces
Project Type: web application in a monorepo (apps/platform plus apps/website)
Performance Goals: Keep operation label and reason translation resolution fully in-process, avoid new remote calls on monitoring or review pages, preserve current operation list and filter responsiveness, and avoid request-path schema rewrites or query fan-out caused by vocabulary hardening
Constraints: No repo-wide rename sweep, no fake generic rewrite of Intune adapters, no new panel or provider, no new assets, no break in historical run filtering or labeling, no change to current 404 or 403 semantics, keep compatibility explicitly transitional, and prefer wrapper or alias hardening over broad schema churn
Scale/Scope: One existing governance namespace, one existing operation vocabulary seam, one existing reason-translation seam, several monitoring or review surfaces, a small set of platform-near compare and snapshot contracts, optional targeted platform-owned persistence wrappers, and focused regression coverage across monitoring, reason translation, and baseline compare or snapshot surfaces

Constitution Check

GATE: Passed before Phase 0 research. Re-checked after Phase 1 design and still passing with narrow proportionality exceptions documented below.

Principle	Pre-Research	Post-Design	Notes
Inventory-first / snapshots-second	PASS	PASS	The feature hardens vocabulary only; inventory, snapshots, and external Microsoft truth sources remain unchanged.
Read/write separation	PASS	PASS	Most work is read-path and presentation-path hardening. Any touched persisted write path stays on existing model or service flows and keeps existing audit and authorization behavior.
Graph contract path	PASS	PASS	No new Microsoft Graph path or graph_contracts.php entry is introduced. Intune-owned Graph terminology remains in the adapter layer.
Deterministic capabilities	PASS	PASS	Existing taxonomy, compare strategy, and operation catalog seams remain deterministic and testable. Any new vocabulary mapping is code-side and snapshot-testable.
Workspace + tenant isolation	PASS	PASS	Monitoring, compare, and review surfaces keep current workspace and tenant scope enforcement. Vocabulary hardening must not expose hidden records through labels or explanations.
RBAC-UX authorization semantics	PASS	PASS	No new authorization plane or capability family is added. Non-members remain 404, in-scope capability denials remain 403, and no new raw capability strings are introduced.
Run observability / Ops-UX	PASS	PASS	Existing OperationRun lifecycle, summary counts, notifications, and DB-only monitoring rules remain unchanged. Operation type hardening is alias and presentation aware, not a run-lifecycle redesign.
Data minimization	PASS	PASS	No new persisted entity or external payload is introduced. Existing JSON context and derived presentation payloads are hardened in place.
Proportionality / anti-bloat	PASS	PASS	The plan extends existing governance, operation, and reason translation seams instead of introducing a second registry framework or presentation pipeline.
No premature abstraction	PASS	PASS	The glossary, alias map, and reason-family classification are narrow extensions to already-existing abstractions rather than brand-new plugin points.
Persisted truth / behavioral state	PASS	PASS	No new top-level persisted truth is added. Any touched reason-family or operation-type classification remains derived unless a platform-owned field cannot be safely wrapped.
UI semantics / few layers	PASS	PASS	Reason ownership and canonical labels are derived through the existing translation and catalog layers. The plan does not add a second operator-semantics framework.
Filament v5 / Livewire v4 compliance	PASS	PASS	All touched UI surfaces remain on existing Filament v5 + Livewire v4 resources, pages, widgets, and detail views.
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	No new globally searchable resource is introduced. Touched resources continue their current search behavior and existing view-detail capability.
Destructive action safety	PASS	PASS	No new destructive action is introduced. Existing destructive actions remain unchanged and must keep confirmation plus authorization.
Asset strategy	PASS	PASS	No new global or on-demand assets are planned. Existing deployment handling of cd apps/platform && php artisan filament:assets remains unchanged.

Filament-Specific Compliance Notes

• Livewire v4.0+ compliance: The touched monitoring and review surfaces stay on Filament v5 + Livewire v4 and the plan introduces no legacy API usage.
• Provider registration location: No new panel or provider is required; bootstrap/providers.php remains the only relevant provider registration location.
• Global search: No new globally searchable resource is added. OperationRunResource already has a detail surface, and touched baseline surfaces keep their existing view or search posture.
• Destructive actions: This feature adds no new destructive action. Existing destructive actions must retain ->requiresConfirmation() and server-side authorization.
• Asset strategy: No asset registration changes are planned. Deployment handling of cd apps/platform && php artisan filament:assets remains unchanged.
• Testing plan: Extend unit coverage for glossary and alias resolution, extend reason-translation and architecture guard coverage for ownership boundaries, extend monitoring and Filament operation-run coverage for canonical labels and filter continuity, and extend baseline snapshot or compare coverage for platform-near subject vocabulary hardening.

Phase 0 Research

Research outcomes are captured in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/204-platform-core-vocabulary-hardening/research.md.

Key decisions:

• Keep the maintained glossary inside the existing App\Support\Governance namespace rather than creating a second documentation-only or config-only source of truth.
• Treat existing stored operation type codes as compatibility aliases and resolve them through one canonical domain-aware operation vocabulary contract.
• Evolve OperationCatalog into the central canonical operation registry rather than introducing a parallel catalog.
• Keep ProviderReasonCodes, RbacReason, and BaselineCompareReasonCode domain-owned and derive platform reason families at the existing ReasonTranslation boundary.
• Prefer governed-subject descriptors built from subject_type_key and subject_type_label on platform-owned or platform-near payloads while preserving Intune-owned policy_type where the object is truly adapter-owned.
• Use wrapper-first and alias-first hardening for platform-owned JSON and presentation contracts before considering any schema change.
• Limit registry hardening to explicit ownership descriptors around current registries instead of building a universal plugin system.
• Add regression guards that prevent false-universal Intune vocabulary from reappearing on touched platform surfaces.

Phase 1 Design

Design artifacts are created under /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/204-platform-core-vocabulary-hardening/:

• research.md: architecture decisions and rejected alternatives for vocabulary ownership, operation types, reason families, and platform-near discriminator hardening
• data-model.md: glossary, operation alias resolution, platform reason family, registry ownership, and platform subject descriptor contracts
• contracts/platform-core-vocabulary-hardening.logical.openapi.yaml: logical internal contract for glossary lookup, operation type resolution, reason translation, registry ownership lookup, and platform subject descriptor normalization
• quickstart.md: implementation and verification sequence for the feature

Design decisions:

• Reuse the current governance namespace for canonical term definitions and ownership descriptors instead of creating a second top-level framework.
• Keep OperationRunType and OperationCatalog as the existing operation vocabulary seam, but add canonical operation codes, domain grouping, and explicit legacy alias resolution.
• Extend ReasonResolutionEnvelope and ReasonTranslator so operator-facing explanations carry explicit ownership and platform reason-family metadata without renaming domain reason codes.
• Harden platform-near compare, snapshot, monitoring, and review payloads to prefer domain_key, subject_class, subject_type_key, and subject_type_label semantics rather than using policy_type as a universal noun.
• Preserve Intune-owned tables, config registries, Graph contracts, and adapter metadata as intentionally Intune-specific.
• Keep compatibility explicitly temporary and visible in code so old names are readable but not treated as equally canonical.

Project Structure

Documentation (this feature)

specs/204-platform-core-vocabulary-hardening/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── spec.md
├── contracts/
│   └── platform-core-vocabulary-hardening.logical.openapi.yaml
└── checklists/
    └── requirements.md

Source Code (repository root)

apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Pages/
│   │   │   ├── BaselineCompareLanding.php
│   │   │   └── BaselineCompareMatrix.php
│   │   ├── Resources/
│   │   │   ├── OperationRunResource.php
│   │   │   └── EvidenceSnapshotResource.php
│   │   ├── System/
│   │   │   └── Pages/
│   │   │       ├── Ops/
│   │   │       │   ├── Runs.php
│   │   │       │   ├── Failures.php
│   │   │       │   └── Stuck.php
│   │   │       └── Directory/
│   │   │           ├── ViewTenant.php
│   │   │           └── ViewWorkspace.php
│   │   │   └── Widgets/
│   │   │       ├── ControlTowerRecentFailures.php
│   │   │       └── ControlTowerTopOffenders.php
│   │   └── Widgets/
│   │       └── Dashboard/RecentOperations.php
│   ├── Jobs/
│   │   └── CompareBaselineToTenantJob.php
│   ├── Models/
│   │   └── OperationRun.php
│   ├── Services/
│   │   ├── Audit/
│   │   │   └── AuditEventBuilder.php
│   │   └── Baselines/
│   │       └── SnapshotRendering/
│   │           └── BaselineSnapshotPresenter.php
│   └── Support/
│       ├── Governance/
│       │   ├── GovernanceDomainKey.php
│       │   ├── GovernanceSubjectClass.php
│       │   ├── GovernanceSubjectTaxonomyRegistry.php
│       │   ├── GovernanceSubjectType.php
│       │   ├── PlatformVocabularyGlossary.php
│       │   ├── PlatformVocabularyTerm.php
│       │   ├── RegistryOwnershipDescriptor.php
│       │   ├── PlatformSubjectDescriptor.php
│       │   └── PlatformSubjectDescriptorNormalizer.php
│       ├── Providers/
│       │   ├── ProviderReasonCodes.php
│       │   └── ProviderReasonTranslator.php
│       ├── ReasonTranslation/
│       │   ├── Contracts/
│       │   ├── ReasonResolutionEnvelope.php
│       │   ├── ReasonTranslator.php
│       │   └── ReasonPresenter.php
│       ├── Baselines/
│       │   ├── BaselineCompareReasonCode.php
│       │   ├── BaselineScope.php
│       │   └── Compare/
│       │       ├── CompareSubjectProjection.php
│       │       └── CompareSubjectResult.php
│       ├── Filament/
│       │   └── FilterOptionCatalog.php
│       ├── OperationCatalog.php
│       └── OperationRunType.php
├── config/
│   └── tenantpilot.php
└── tests/
    ├── Architecture/
    │   └── ReasonTranslationPrimarySurfaceGuardTest.php
    ├── Feature/
    │   ├── Authorization/
    │   │   └── ReasonTranslationScopeSafetyTest.php
    │   ├── Baselines/
    │   │   ├── BaselineCompareExecutionGuardTest.php
    │   │   ├── BaselineCompareDriftEvidenceContractTest.php
    │   │   └── BaselineCompareWhyNoFindingsReasonCodeTest.php
    │   ├── Filament/
    │   │   ├── OperationRunListFiltersTest.php
    │   │   ├── OperationRunEnterpriseDetailPageTest.php
    │   │   ├── OperationRunBaselineTruthSurfaceTest.php
    │   │   ├── BaselineCompareLandingWhyNoFindingsTest.php
    │   │   └── BaselineCompareSummaryConsistencyTest.php
    │   ├── Monitoring/
    │   │   └── OperationRunResolvedReferencePresentationTest.php
    │   └── ReasonTranslation/
    │       ├── GovernanceReasonPresentationTest.php
    │       └── ReasonTranslationExplanationTest.php
    └── Unit/
        ├── Baselines/
        │   └── SnapshotRendering/BaselineSnapshotPresenterTest.php
        └── Support/
            ├── Governance/
            │   ├── PlatformVocabularyGlossaryTest.php
            │   ├── RegistryOwnershipDescriptorTest.php
            │   └── PlatformSubjectDescriptorNormalizerTest.php
            ├── OperationTypeResolutionTest.php
            ├── ReasonTranslation/
            │   ├── ExecutionDenialReasonTranslationTest.php
            │   ├── ProviderReasonTranslationTest.php
            │   ├── RbacReasonTranslationTest.php
            │   ├── ReasonResolutionEnvelopeTest.php
            │   └── TenantOperabilityReasonTranslationTest.php

Structure Decision: Keep the work inside the existing governance, operation, baseline compare, and reason-translation seams. Add one narrow glossary and ownership layer under app/Support/Governance and small extensions to current catalogs or envelopes rather than introducing a second cross-cutting framework. The intended implementation surface is one glossary, one operation-resolution seam, one reason-owner extension, and one subject normalizer; any additional named contracts from the data model should be realized only as small value objects under those seams when keeping them inline would duplicate meaning across multiple touched surfaces.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
Code-side platform vocabulary glossary and ownership descriptors	The codebase already has governance and compare vocabulary primitives, but it lacks one maintained source that explains canonical platform terms, registry ownership, and where Intune-native terms remain valid	A spec-only note or scattered inline comments would not keep code, tests, and review surfaces aligned once changes start landing
Canonical operation type alias resolution	Historical stored operation codes are mixed between canonical domain-aware names and older underscore names; the platform needs one future-safe vocabulary model without breaking current run history or filters	An immediate rewrite of all persisted operation types is too risky, while leaving the mixed names equally canonical defeats the purpose of the hardening
Platform reason-family classification at the translation boundary	Platform surfaces need to distinguish domain-neutral cause families from domain-owned causes without flattening Provider, RBAC, and baseline compare reasons into one misleading universal enum	Renaming every existing domain reason code into a platform-wide code family would add churn, blur ownership, and break current translation paths unnecessarily

Proportionality Review

• Current operator problem: Monitoring, compare, evidence, and review surfaces still expose platform meaning through a mix of Intune-shaped operation names, reason codes, and subject terms, which makes the product's architecture harder to understand and more error-prone for future work.
• Existing structure is insufficient because: Current governance taxonomy, compare strategy, operation catalog, and reason translation seams exist, but they do not yet define one canonical boundary for platform vocabulary ownership, alias handling, or subject descriptor hardening across touched platform surfaces.
• Narrowest correct implementation: Extend the existing governance namespace, operation catalog, and reason translation envelope with glossary, ownership, alias, and descriptor metadata; harden only the touched platform-near payloads and surfaces; preserve Intune-owned persistence and catalogs where they are legitimately domain-specific.
• Implementation preference: Extend existing seams first and add standalone support types only where they replace repeated array-shape ambiguity across multiple touched surfaces.
• Ownership cost created: Ongoing glossary maintenance, explicit alias retirement review, additional architecture and regression tests, and careful review of touched platform-near payloads to keep compatibility temporary.
• Alternative intentionally rejected: A broad repo-wide rename or a brand-new platform vocabulary framework. The rename sweep creates churn without enough boundary discipline, and the new framework would over-abstract a problem that current seams can solve more narrowly.
• Release truth: current-release platform-boundary clarification with compatibility support, not speculative multi-domain infrastructure

Implementation Strategy

Phase A - Canonical Glossary and Ownership Boundaries

• Add a narrow code-side glossary under app/Support/Governance that defines canonical platform terms and ownership layers.
• Make the contributor boundary explicit so touched concepts can be classified as platform_core, cross_domain_governance, or intune_specific without relying on historical naming.
• Classify current registries and catalogs as platform_core, cross_domain_governance, or intune_specific, starting with governance taxonomy, operation catalog, provider reason registries, and Intune policy type config.
• Document forbidden false-universal aliases for platform contexts, especially policy_type where the surface is not explicitly Intune-owned.

Phase B - Operation Vocabulary Canonicalization

• Extend OperationCatalog and related helpers to resolve one canonical domain-aware operation code from stored or legacy operation type values.
• Update touched run-creating services, jobs, and launch surfaces to emit canonical operation codes on new writes wherever this spec changes the flow.
• Expose canonical operation_type on touched read models, summaries, filters, and exports even where persisted storage continues to use operation_runs.type.
• Keep OperationRunType readable for current services and jobs, but add alias and grouping metadata so monitoring, filters, audit prose, and run detail surfaces render canonical meaning consistently.
• Update touched monitoring and review surfaces to rely on canonical in-process resolution rather than raw stored strings, without introducing render-time external calls or query fan-out.

Phase C - Reason Ownership and Platform Reason Families

• Extend ReasonResolutionEnvelope and ReasonTranslator so translated explanations carry explicit ownership and platform reason-family metadata.
• Keep ProviderReasonCodes, RbacReason, and BaselineCompareReasonCode domain-owned and namespaced.
• Ensure operator-facing surfaces show platform reason meaning first and domain-specific cause detail second when both are present.

Phase D - Platform-Neutral Subject and Contract Hardening

• Harden platform-near compare, snapshot, monitoring, and review payloads to prefer domain_key, subject_class, subject_type_key, and subject_type_label descriptors where available.
• Audit platform-owned persisted payloads, especially operation_runs.context, compare subcontext payloads, and evidence payloads touched by this spec, and normalize them through wrapper or presenter contracts before any rename is considered.
• Reduce or remove false-universal policy_type usage from touched run context, compare payloads, snapshot rendering, and reporting summaries while keeping Intune-owned persistence untouched.
• Prefer wrapper or projection hardening for platform-owned JSON and presenter contracts before any schema change is considered.

Phase E - Transition, Guardrails, and Verification

• Keep compatibility explicitly temporary with one canonical name per platform concept and documented legacy aliases.
• Add regression and architecture guards so touched platform surfaces cannot reintroduce raw mixed operation codes, false-universal Intune vocabulary, non-in-process resolution paths, or request-time query fan-out on monitoring and review reads.
• Validate no-regression Intune-first behavior across monitoring, compare, evidence, review, and snapshot surfaces touched by the hardening.

Risk Assessment

Risk	Impact	Likelihood	Mitigation
Canonical operation aliasing turns into permanent dual vocabulary	High	Medium	Define one canonical operation code per stored alias, make alias status explicit in code, and add tests that new writes on touched flows do not introduce new legacy names.
A platform surface still leaks policy_type after wrapper hardening	High	Medium	Audit touched compare, snapshot, run-context, and presenter contracts; add feature and architecture tests around those surfaces.
Reason-family hardening duplicates or conflicts with existing explanation semantics	Medium	Medium	Extend the current envelope and translator instead of adding a second explanation pipeline, and validate against existing reason-translation and baseline compare explanation tests.
Monitoring filters, labels, or audit prose break when operation types are canonicalized	Medium	Medium	Route filters and labels through canonical resolution and extend OperationRunListFiltersTest, monitoring presentation tests, and audit-event coverage.
The implementation drifts into Intune adapter rewrites or schema churn	Medium	Low	Keep ownership descriptors explicit, prefer wrapper-first hardening, and require a focused proportionality review before any schema change on a platform-owned field.

Test Strategy

• Add focused unit coverage for the platform glossary and operation vocabulary alias resolution.
• Extend tests/Unit/Support/ReasonTranslation/ReasonResolutionEnvelopeTest.php, ProviderReasonTranslationTest.php, and RbacReasonTranslationTest.php for ownership and platform reason-family metadata.
• Extend tests/Architecture/ReasonTranslationPrimarySurfaceGuardTest.php so platform surfaces cannot bypass canonical translation or leak raw domain-owned codes as universal platform reasons.
• Extend tests/Feature/Filament/OperationRunListFiltersTest.php, OperationRunEnterpriseDetailPageTest.php, OperationRunBaselineTruthSurfaceTest.php, RecentOperationsSummaryWidgetTest.php, ProviderConnectionsDbOnlyTest.php, InventoryItemResourceTest.php, BackupScheduleCrudTest.php, and OnboardingEntryPointTest.php for canonical operation labels, grouping, launch-surface wording, and filter continuity.
• Extend tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php and tests/Feature/System/Spec114/ControlTowerDashboardTest.php so historical and canonical operation codes render the same operator meaning during transition across both monitoring pages and monitoring widgets.
• Extend tests/Feature/ReasonTranslation/GovernanceReasonPresentationTest.php and ReasonTranslationExplanationTest.php so platform and domain explanation layering remains explicit.
• Extend tests/Unit/Baselines/SnapshotRendering/BaselineSnapshotPresenterTest.php, tests/Feature/Evidence/EvidenceSnapshotResourceTest.php, tests/Feature/Baselines/BaselineCompareDriftEvidenceContractTest.php, and BaselineCompareWhyNoFindingsReasonCodeTest.php for platform-near subject vocabulary hardening without Intune behavior regression.
• Extend tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php, tests/Feature/TenantReview/TenantReviewExecutivePackTest.php, tests/Feature/TenantReview/TenantReviewUiContractTest.php, tests/Feature/ReviewPack/ReviewPackGenerationTest.php, and tests/Feature/ReviewPack/ReviewPackWidgetTest.php so reporting and executive-pack summaries honor the same canonical vocabulary and explanation ownership rules.
• The focused completion gate for this spec is the full quickstart verification pack, which includes every suite named in the story-level and continuity test tasks plus the final architecture and authorization guard suites.
• Keep existing compare start-surface, baseline summary, and RBAC-related coverage green so vocabulary hardening does not change authorization or workflow semantics.