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