ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
fc794b67e1
TenantAtlas/specs/204-platform-core-vocabulary-hardening/quickstart.md
Ahmed Darrazi fc794b67e1 Spec 204: harden platform core vocabulary
2026-04-14 08:07:40 +02:00

12 KiB
Raw Blame History

Quickstart: Platform Core Vocabulary Hardening

Goal

Harden platform-core and platform-near vocabulary so monitoring, compare, snapshot, evidence, review, and reporting surfaces resolve canonical platform meaning through the existing governance, operation, and reason-translation seams while preserving legitimate Intune-owned terminology where ownership is explicit.

Prerequisites

  1. Work on branch 204-platform-core-vocabulary-hardening.
  2. Ensure the platform containers are available:
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail up -d
  1. Keep Spec 202 governance taxonomy and Spec 203 compare strategy assumptions available because this feature extends those seams rather than replacing them.

Recommended Implementation Order

1. Lock the current behavior with focused regression coverage

Run the current reason-translation, operation-run, and baseline presentation tests before changing vocabulary resolution:

cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/ReasonTranslation/ProviderReasonTranslationTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/ReasonTranslation/RbacReasonTranslationTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/OperationRunListFiltersTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Baselines/SnapshotRendering/BaselineSnapshotPresenterTest.php

Add any missing targeted tests for canonical operation aliasing, registry ownership lookup, and platform subject descriptor normalization before moving core resolution logic.

2. Introduce the maintained platform glossary and registry ownership descriptors

Add the narrow glossary and ownership descriptors under app/Support/Governance.

Cover:

  • canonical platform nouns
  • explicit three-way boundary classification for platform-core, cross-domain governance, and Intune-specific concepts
  • explicit owner layers
  • forbidden false-universal aliases
  • registry ownership classification for governance taxonomy, operation catalog, provider reason registries, and domain-owned policy catalogs

Do not create a new table or a new top-level framework.

3. Canonicalize operation type resolution through the existing operation catalog

Extend OperationCatalog and the current operation helpers so touched surfaces resolve one canonical operation code from historical raw values.

Update touched run-creating services and launch surfaces to emit canonical operation codes on new writes wherever this feature changes the flow.

Focus on:

  • OperationRunType
  • OperationCatalog
  • touched run producers such as compare, capture, evidence, review, inventory, schedule, and directory sync services
  • OperationRunResource
  • monitoring pages and widgets
  • audit prose and any run reference presentation helpers

Preserve existing filters and historical run readability during the alias transition.

4. Enrich reason translation with explicit ownership and platform reason families

Extend ReasonResolutionEnvelope and ReasonTranslator so translated operator explanations carry:

  • explicit owner layer
  • stable owner namespace
  • one platform reason family
  • the existing explanation, actionability, next steps, and diagnostics fields

Do not rename current domain reason codes.

5. Harden platform-near subject descriptors and remove false-universal policy_type usage from touched surfaces

Update platform-near compare, snapshot, evidence, and run-context projections so they prefer:

  • domain_key
  • subject_class
  • subject_type_key
  • subject_type_label
  • operator-safe subject labels

Keep policy_type only where the owning object is explicitly Intune-native or where a compatibility fallback is still required.

Audit platform-owned persisted payloads touched by this feature, especially operation_runs.context, compare subcontext payloads, and evidence payloads, and normalize them through wrappers or presenters before considering any rename.

6. Add guardrails for regression-prone surfaces

Extend architecture and feature coverage so touched surfaces cannot bypass canonical resolution or reintroduce false-universal Intune vocabulary.

Priority guard surfaces:

  • reason translation primary surfaces
  • operation run list and detail surfaces
  • monitoring widgets or recent-run summaries
  • evidence snapshot resource and snapshot presentation surfaces
  • baseline compare explanation and evidence surfaces
  • snapshot presentation and filter-option catalogs
  • tenant review resource and review-pack widget surfaces
  • provider connection, inventory item, backup schedule, and onboarding launch surfaces

Focused Verification

Run the full spec-specific suites after each phase and before final sign-off:

cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Governance/PlatformVocabularyGlossaryTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/Governance/RegistryOwnershipDescriptorTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Baselines/GovernanceSubjectTaxonomyRegistryTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Architecture/ReasonTranslationPrimarySurfaceGuardTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Architecture/PlatformVocabularyBoundaryGuardTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Authorization/ReasonTranslationScopeSafetyTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/ReasonTranslation/ReasonResolutionEnvelopeTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/ReasonTranslation/ProviderReasonTranslationTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/ReasonTranslation/RbacReasonTranslationTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/ReasonTranslation/TenantOperabilityReasonTranslationTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/ReasonTranslation/ExecutionDenialReasonTranslationTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReasonTranslation/GovernanceReasonPresentationTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReasonTranslation/ReasonTranslationExplanationTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/OperationRunListFiltersTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/ControlTowerDashboardTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Baselines/SnapshotRendering/BaselineSnapshotPresenterTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineSnapshotStructuredRenderingTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineSnapshotResolvedReferencePresentationTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Evidence/EvidenceSnapshotResourceTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareDriftEvidenceContractTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareExplanationSurfaceTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareWhyNoFindingsReasonCodeTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineSnapshotFallbackRenderingTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareDriftEvidenceContractRbacTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantReview/TenantReviewExecutivePackTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantReview/TenantReviewUiContractTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/ReviewPackGenerationTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/ReviewPackWidgetTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/InventoryItemResourceTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/BackupScheduling/BackupScheduleCrudTest.php
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingEntryPointTest.php

If any touched Filament explanation or run-detail surface changes materially, keep the existing UI-facing smoke coverage green before expanding scope.

Final Validation

  1. Run formatting:
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
  1. Re-run the focused verification pack.
  2. Confirm historical operation types still render current operator meaning while new or touched flows resolve canonical operation codes.
  3. Confirm touched platform surfaces prefer governed-subject descriptors and no longer rely on false-universal policy_type labels.
  4. Confirm domain-owned Intune models and Graph-facing adapters retain their intentional terminology.
  5. Review touched list surfaces against docs/product/standards/list-surface-review-checklist.md before sign-off.