TenantAtlas/specs/204-platform-core-vocabulary-hardening/spec.md
2026-04-14 08:07:40 +02:00

62 KiB

Feature Specification: Platform Core Vocabulary Hardening

Feature Branch: 204-platform-core-vocabulary-hardening
Created: 2026-04-13
Status: Draft
Input: User description: "Spec 204 - Platform Core Vocabulary Hardening"

  • Type: Core vocabulary hardening / platform-boundary clarification
  • Priority: High
  • Depends on: Spec 202 - Governance Subject Taxonomy and Baseline Scope V2
  • Recommended after / alongside: Spec 203 - Baseline Compare Engine Strategy Extraction
  • Blocks: Clean multi-domain expansion without semantic drift in platform-core surfaces
  • Does not block: Continued Intune-first operation during the transition period

Spec Candidate Check (mandatory - SPEC-GATE-001)

  • Problem: Platform-core contracts, operation typing, reason-code layers, and some registries still speak in Intune-shaped vocabulary as though every governed subject were an Intune policy, even after the platform started defining broader governance concepts.
  • Today's failure: The codebase can become structurally more extensible through Specs 202 and 203 while still teaching contributors the wrong architecture. That creates semantic lock-in, ambiguous platform boundaries, and avoidable friction for future governance domains.
  • User-visible improvement: Operators keep current Intune-first behavior, but platform-facing labels, run types, summaries, and reason semantics become clearer, more future-safe, and less misleading. Contributors can tell what is platform-core and what is intentionally Intune-specific without guessing.
  • Smallest enterprise-capable version: Define one maintained platform vocabulary source of truth, harden only the platform-near discriminators and catalogs that currently leak false-universal Intune terminology, adopt canonical domain-aware operation types, separate platform and domain reason-code ownership, and preserve Intune-native naming where it is actually correct.
  • Explicit non-goals: No new governance domain, no broad repo-wide rename sweep, no fake generic rewrite of Intune adapters, no new plugin system, no redesign of baseline scope beyond Spec 202, no replacement of compare strategy extraction from Spec 203, and no generic backup or restore engine.
  • Permanent complexity imported: One canonical glossary or boundary note, one canonical operation-type naming model, one explicit platform-vs-domain reason-code boundary, targeted migration or mapping rules where needed, and focused regression coverage.
  • Why now: Spec 202 establishes governed-subject vocabulary and Spec 203 extracts compare strategy boundaries. If platform-core vocabulary stays Intune-shaped now, future domains will inherit the wrong mental model and force more expensive cleanup later.
  • Why not local: A few local renames would not solve the platform-wide ambiguity. The problem is not one page or one class; it is the product's implied architecture at platform-core boundaries.
  • Approval class: Core Enterprise
  • Red flags triggered: Rename-sweep risk, future-domain preparation risk, and cross-domain taxonomy risk. Defense: this spec is intentionally narrow, preserves domain-native Intune terms, limits persistence churn to platform-near boundaries, and exists to correct current-release platform meaning rather than to build speculative infrastructure.
  • Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 1 | Wiederverwendung: 2 | Gesamt: 10/12
  • Decision: approve

Spec Scope Fields (mandatory)

  • Scope: workspace, tenant, platform, canonical-view
  • Primary Routes (summary anchors only; the four surface-governance tables below are the authoritative route inventory for touched operator-facing surfaces):
    • /admin/operations
    • /admin/operations/{run}
    • /admin/t/{tenant}
    • /system
    • /admin/t/{tenant}/baseline-compare
    • /admin/t/{tenant}/evidence
    • /admin/t/{tenant}/reviews
    • /admin/t/{tenant}/review-packs
    • /admin/provider-connections
    • /admin/t/{tenant}/inventory/inventory-items
    • /admin/t/{tenant}/backup-schedules
    • /admin/onboarding
  • Data Ownership:
    • Workspace-owned platform registries, glossaries, and boundary notes define canonical platform vocabulary and ownership rules.
    • Tenant-owned operation runs, findings, evidence, and review summaries may receive vocabulary hardening where they expose platform-core semantics.
    • Pure Intune-owned entities, metadata, and adapter persistence remain Intune-owned unless a platform-near discriminator or label boundary explicitly requires hardening.
    • This feature may require targeted persisted discriminator renames or mapping only where a platform-near surface currently encodes false-universal Intune meaning.
  • RBAC:
    • Existing platform, workspace, and tenant authorization boundaries remain authoritative.
    • /system surfaces continue to use the platform guard and existing system-panel capability checks; vocabulary hardening must not widen platform-plane visibility or cross-plane leakage.
    • Non-members remain 404, entitled members without capability remain 403, and vocabulary hardening must not change access boundaries.
    • No new destructive operator action is introduced by this spec.

For canonical-view specs, the spec MUST define:

  • Default filter behavior when tenant-context is active: Canonical monitoring and review surfaces touched by this spec continue to respect active workspace context and should prefilter tenant-owned results to the current tenant when entered from tenant context, while tenant-neutral platform records remain clearly labeled as platform-scoped.
  • Explicit entitlement checks preventing cross-tenant leakage: Canonical operation and review surfaces must continue to enforce workspace entitlement first and tenant entitlement for tenant-owned records second. Vocabulary hardening must not reveal hidden tenants, hidden runs, or inaccessible review context through labels, filters, or reason text.

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

Surface Decision Role Human-in-the-loop Moment Immediately Visible for First Decision On-Demand Detail / Evidence Why This Is Primary or Why Not Workflow Alignment Attention-load Reduction
Monitoring operations list Primary Decision Surface Decide which run needs inspection or can be safely ignored Canonical operation label, domain grouping, scope context, and high-level outcome Legacy type mapping detail, raw provider wording, and deep diagnostics Primary because monitoring attention and follow-up start here Follows monitoring and troubleshooting workflow Removes guesswork caused by ambiguous or Intune-shaped run labels
Operation run detail Tertiary Evidence / Diagnostics Surface Understand why a run had a given type, outcome, or explanation Canonical operation type, platform reason family, and clear top-level meaning Domain-specific cause detail, transition mapping context, and low-level diagnostics Not primary because it explains evidence after the operator chooses to inspect a run Follows diagnostics workflow after monitoring or review Keeps platform meaning visible without forcing operators to decode domain-local internals
Tenant dashboard recent operations widget Secondary Context Surface Notice whether a recent tenant-scoped run deserves deeper inspection Canonical operation label, tenant context, and high-level outcome Raw alias mapping and deeper diagnostics on linked monitoring surfaces Not primary because it summarizes current tenant activity inside the dashboard rather than replacing the monitoring register Follows tenant triage workflow Reduces the need to leave the dashboard for routine orientation
System dashboard Control Tower widgets Secondary Context Surface Notice whether failure clusters or repeat offenders require monitoring follow-up Failure pressure, time-window context, and canonical operation labels Per-run diagnostics and raw alias history Not primary because the widgets summarize console pressure before the operator enters detailed monitoring views Follows ops-console workflow Keeps the system dashboard scannable and calm
Evidence snapshot resource and snapshot presentation Tertiary Evidence / Diagnostics Surface Inspect the evidence that backs a governed-subject or comparison outcome Snapshot label, governed-subject descriptor, and evidence state Raw payload structure and compatibility alias detail Not primary because it explains evidence after a review or compare decision already exists Follows evidence inspection workflow Keeps evidence readable without defaulting to Intune-only nouns
Tenant baseline compare surfaces Primary Decision Surface Decide whether tenant follow-up is needed based on compare and review truth Platform-correct governed-subject wording, canonical operation naming where shown, and clear platform-versus-domain explanation semantics Domain-specific Intune detail, raw identifiers, and deep evidence Primary because this is where the operator decides what to do next Follows compare, review, and follow-up workflow Prevents operators from mistaking Intune-local causes for universal platform concepts
Tenant review resource Primary Decision Surface Decide which review record or export context needs action Review status, canonical reason ownership, and review summary language Raw export details and deeper historical reasoning Primary because review follow-up decisions happen here Follows tenant review workflow Keeps review meaning obvious before the operator opens exports or linked evidence
Tenant review pack widget Secondary Context Surface Notice whether the latest review pack warrants deeper inspection Pack freshness, canonical review wording, and tenant scope Export internals and derived detail on linked reporting surfaces Not primary because it summarizes review state inside a broader tenant context Follows tenant reporting workflow Reduces clicks to current pack status
Provider connection resource launch surface Secondary Context Surface Decide whether to inspect or launch a provider workflow from the existing connection surface Connection identity, status, and canonical launch labels Provider diagnostics and audit history Not primary because provider workflows remain subordinate to the connection record Follows integration maintenance workflow Keeps launch wording consistent without turning the record into a workflow hub
Inventory item list launch surface Secondary Context Surface Decide whether to inspect the item or launch inventory follow-up Inventory state, scope context, and canonical launch wording Deep dependency detail and raw provider wording Not primary because inventory inspection stays primary Follows inventory review workflow Keeps follow-up wording clear without cluttering the list
Backup schedule resource launch surface Secondary Context Surface Decide whether to inspect or run schedule-related work Schedule cadence, scope, and canonical run labels Historical operation detail and raw audit wording Not primary because schedule management remains the owning workflow Follows backup management workflow Keeps operational wording consistent
Managed tenant onboarding wizard Primary Decision Surface Decide the next onboarding step and launch verification at the right time Current step, verification progress, and platform-safe action wording Deeper provider diagnostics and legacy alias detail Primary because onboarding progression decisions happen directly here Follows staged onboarding workflow Keeps the next step obvious

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

List Surface Review Checklist: Because this feature modifies the Monitoring operations list and may affect list-style review or reporting surfaces that render hardened vocabulary, sign-off MUST include review against docs/product/standards/list-surface-review-checklist.md for each touched list surface.

Surface Action Surface Class Surface Type Decision-role Prominence Likely Next Operator Action Primary Inspect/Open Model Row Click Secondary Actions Placement Destructive Actions Placement Canonical Collection Route Canonical Detail Route Scope Signals Canonical Noun Critical Truth Visible by Default Exception Type / Justification
Monitoring operations list List / Table / Bulk Read-only Registry / Report Surface Primary Decision Surface Filter to a domain or open one run Full-row open to operation detail required Filter and grouping controls stay in list chrome none /admin/operations /admin/operations/{run} Workspace context, tenant context when filtered, canonical domain-aware operation type Operations / operation runs What ran, in which domain, and whether the top-level outcome needs inspection none
Operation run detail Record / Detail / Edit Detail-first Operational Surface Tertiary Evidence / Diagnostics Surface Inspect run meaning and next step Explicit run detail page n/a Navigation and related links remain secondary to the summary body none /admin/operations /admin/operations/{run} Workspace context, tenant scope when applicable, platform reason family, domain detail when present Operation run Why the run means what it means without conflating platform and domain causes canonical evidence detail
Tenant dashboard recent operations widget Monitoring / Queue / Workbench Read-only Registry / Report Surface Secondary Context Surface Jump to the tenant-scoped monitoring slice or open the highlighted run Existing widget links open the tenant dashboard summary or run detail n/a Widget links remain limited to monitoring context none /admin/t/{tenant} /admin/operations/{run} Tenant context, canonical operation labels, high-level outcome Recent operations Which recent tenant-scoped runs deserve deeper inspection none
System dashboard Control Tower widgets Monitoring / Queue / Workbench Read-only Registry / Report Surface Secondary Context Surface Jump to failing-run monitoring or open the highlighted run Existing widget links open system monitoring or run detail n/a Widget links remain limited to system-console context none /system /system/ops/runs/{run} System time-window context, failure pressure, canonical operation labels Control Tower summaries Which failing or repeat-offender runs deserve follow-up none
Evidence snapshot resource and snapshot presentation List / Table / Bulk Read-only Registry / Report Surface Tertiary Evidence / Diagnostics Surface Open the evidence snapshot that explains a governed subject or comparison result Existing row or identifier open to snapshot detail required Filter and export controls remain secondary none /admin/t/{tenant}/evidence /admin/t/{tenant}/evidence/{snapshot} Tenant or workspace context, governed-subject descriptor, evidence state Evidence snapshot Snapshot meaning stays operator-safe without relying on false-universal policy_type none
Tenant baseline compare surfaces Monitoring / Queue / Workbench Queue / Review Surface Primary Decision Surface Decide whether to follow up, inspect evidence, or defer Explicit page and linked review context forbidden Secondary links to evidence, findings, and diagnostics remain contextual none /admin/t/{tenant}/baseline-compare /admin/t/{tenant}/baseline-compare Workspace context, tenant context, governed-subject wording, review meaning Baseline compare / review Platform-correct governed-subject and explanation language, with domain-specific detail only when needed none
Tenant review resource List / Table / Bulk Read-only Registry / Report Surface Primary Decision Surface Open a review record or export context with canonical terminology intact Existing row or identifier open to review detail required Existing safe review actions remain contextual none /admin/t/{tenant}/reviews /admin/t/{tenant}/reviews/{review} Tenant scope, review status, canonical reason ownership Tenant review Review status and meaning stay canonical without hiding domain detail none
Tenant review pack widget Monitoring / Queue / Workbench Read-only Registry / Report Surface Secondary Context Surface Open the latest review pack or linked tenant review context Existing widget CTA opens pack or review detail n/a Widget CTA remains scoped to the current tenant review context none /admin/t/{tenant}/review-packs /admin/t/{tenant}/review-packs/{reviewPack} Tenant scope, pack freshness, canonical review wording Review pack The latest pack state is visible with canonical vocabulary before opening export or detail none
Provider connection resource launch surface List / Table / Bulk CRUD / List-first Resource Secondary Context Surface Launch provider-related flows without reintroducing legacy operation labels Existing row or identifier open remains the inspect path allowed when the owning resource already uses it Launch actions stay in existing header or overflow locations none /admin/provider-connections /admin/provider-connections/{connection} Workspace scope, provider identity, canonical operation labels for launched flows Provider connection The connection record remains primary while launch labels stay canonical none
Inventory item list launch surface List / Table / Bulk Read-only Registry / Report Surface Secondary Context Surface Launch inventory-related follow-up from the existing list without losing canonical operation wording Existing row or identifier open remains the inspect path allowed when the owning resource already uses it Launch actions remain contextual to the list or record none /admin/t/{tenant}/inventory/inventory-items /admin/t/{tenant}/inventory/inventory-items/{item} Workspace and tenant scope, inventory state, canonical operation wording Inventory item Inventory meaning stays primary while launch wording stays canonical none
Backup schedule resource launch surface List / Table / Bulk CRUD / List-first Resource Secondary Context Surface Launch or inspect backup schedule work with canonical operation wording Existing row or identifier open remains the inspect path allowed when the owning resource already uses it Launch actions stay in existing header or overflow locations none /admin/t/{tenant}/backup-schedules /admin/t/{tenant}/backup-schedules/{schedule}/edit Tenant or workspace scope, schedule status, canonical backup-run wording Backup schedule The schedule stays primary while run labels remain canonical none
Managed tenant onboarding wizard Wizard / Flow Detail-first Operational Surface Primary Decision Surface Continue onboarding and launch verification steps with canonical platform wording Existing staged wizard progression n/a Secondary actions remain limited to back, resume, or contextual help none /admin/onboarding /admin/onboarding/{onboardingDraft} Workspace scope, tenant identification, verification progress, canonical operation wording Managed tenant onboarding The next onboarding step remains obvious while workflow labels stay platform-safe Wizard

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

Surface Primary Persona Decision-role Prominence Decision / Operator Action Supported Surface Type Primary Operator Question Default-visible Information Diagnostics-only Information Status Dimensions Used Mutation Scope Primary Actions Dangerous Actions
Monitoring operations list Workspace operator Primary Decision Surface Decide which run needs inspection or filtering Read-only Registry / Report Surface What ran, and is the operation meaning clear enough to inspect or ignore? Canonical operation label, domain grouping, scope context, and outcome Legacy mapping detail and raw provider wording execution outcome, domain, scope read-only Filter, open run none
Operation run detail Workspace operator or entitled tenant operator Tertiary Evidence / Diagnostics Surface Diagnose why the run means what it means Detail-first Operational Surface Is this a platform-level issue, a domain-specific issue, or both? Canonical operation type, platform reason family, and top-level explanation Domain-specific cause detail, transition mapping, raw diagnostics execution outcome, platform reason, domain cause read-only Open related evidence or review surfaces none
Tenant dashboard recent operations widget Tenant operator Secondary Context Surface Spot the recent tenant-scoped run cohort that deserves deeper inspection Read-only Registry / Report Surface Which recent operations on this tenant should I inspect next? Canonical operation labels, summarized outcome, and tenant context Raw alias mapping or deeper diagnostics remain in linked detail surfaces execution outcome, tenant scope read-only Open linked monitoring slices or run detail none
System dashboard Control Tower widgets Platform operator Secondary Context Surface Spot failing or repeat-offender run cohorts that deserve deeper inspection Read-only Registry / Report Surface Which failures or offenders need console follow-up now? Failure pressure, time-window context, and canonical operation labels Per-run diagnostics and raw alias history remain in linked console views failure pressure, execution outcome, time window read-only Open linked monitoring slices or run detail none
Evidence snapshot resource and snapshot presentation Workspace operator or entitled tenant operator Tertiary Evidence / Diagnostics Surface Cross-check the evidence that explains a governed subject or comparison result Read-only Registry / Report Surface Which evidence snapshot explains this state, and is the governed-subject wording still canonical? Snapshot label, governed-subject descriptor, and evidence state Raw payload structure and compatibility alias detail evidence freshness, subject scope, evidence status read-only Open snapshot detail or export existing evidence views none
Tenant baseline compare surfaces Tenant operator Primary Decision Surface Decide whether tenant state needs follow-up Queue / Review Surface What needs action, and is the explanation platform-wide or Intune-specific? Governed-subject wording, review meaning, and platform reason semantics Raw evidence, domain-specific detail, historical transition detail governance result, evidence completeness, explanation ownership simulation only or existing mutation scope for linked actions Existing compare or review actions none
Tenant review resource Tenant operator Primary Decision Surface Open a review record or export context with canonical terminology intact Read-only Registry / Report Surface Which tenant review needs inspection, and is its explanation still aligned with platform vocabulary? Review status, canonical reason ownership, and review summary language Raw export details and deeper historical reasoning review lifecycle, explanation ownership, export readiness existing read-only or linked mutation scope Open review detail or linked exports none
Tenant review pack widget Tenant operator Secondary Context Surface Open the latest review pack or linked tenant review context Read-only Registry / Report Surface Do I need to inspect the newest review pack or linked review state now? Pack freshness, tenant scope, and canonical review wording Export internals and derived detail remain on linked surfaces pack freshness, tenant scope read-only Open pack or linked tenant review detail none
Provider connection resource launch surface Workspace operator Secondary Context Surface Launch provider-related flows without losing canonical operation wording CRUD / List-first Resource Can I inspect this connection and launch the next provider workflow with clear wording? Connection identity, status, and canonical launch labels Audit history and deeper provider diagnostics connection state, provider type existing resource mutation scope Existing inspect, edit, and launch actions none
Inventory item list launch surface Workspace operator Secondary Context Surface Launch inventory-related follow-up from the existing list Read-only Registry / Report Surface Which inventory record needs follow-up, and is the action wording still canonical? Inventory state, scope context, and canonical launch wording Deep dependency detail and raw provider wording inventory status, tenant scope read-only Existing inspect and launch actions none
Backup schedule resource launch surface Workspace operator Secondary Context Surface Launch or inspect backup schedule work with canonical run wording CRUD / List-first Resource Which schedule am I managing, and do its run actions still read clearly? Schedule cadence, scope, and canonical run labels Historical operation detail and raw audit wording schedule state, tenant scope existing resource mutation scope Existing inspect, edit, and launch actions none
Managed tenant onboarding wizard Workspace operator Primary Decision Surface Continue onboarding and launch verification steps with canonical wording Detail-first Operational Surface What is the next onboarding step, and does the launch wording match platform semantics? Current step, verification progress, and platform-safe action wording Deeper provider diagnostics and legacy alias detail onboarding stage, tenant identification, verification progress staged workflow only Continue, resume, verify none

Proportionality Review (mandatory when structural complexity is introduced)

  • New source of truth?: yes
  • New persisted entity/table/artifact?: no
  • New abstraction?: yes
  • New enum/state/reason family?: yes
  • New cross-domain UI framework/taxonomy?: yes, but only as a narrow platform vocabulary hardening layer that builds directly on Spec 202
  • Current operator problem: Platform surfaces and platform-near contracts still imply that the universal governed object is an Intune policy. That ambiguity makes monitoring, compare, review, and future domain work harder to understand and maintain.
  • Existing structure is insufficient because: Structural progress alone does not fix the architecture the product communicates through names. Without explicit hardening, future contributors will keep placing platform concepts into Intune-shaped terms.
  • Narrowest correct implementation: Define a canonical glossary, harden only platform-core and platform-near vocabulary that is currently misleading, adopt canonical operation types, separate platform and domain reason-code ownership, and preserve Intune-native naming where the object is truly Intune-owned.
  • Ownership cost: Ongoing glossary maintenance, transition mapping discipline, targeted migration review where persisted fields are hardened, and regression coverage for operation labels, reason semantics, and no-regression Intune behavior.
  • Alternative intentionally rejected: A local rename sweep, or a broad generic platform rewrite. The rename sweep would leave semantic ambiguity in place, and the rewrite would over-abstract current product reality.
  • Release truth: current-release platform-boundary clarification with near-term value for Specs 202 and 203, not a speculative multi-domain framework build

User Scenarios & Testing (mandatory)

User Story 1 - Remove false-universal Intune language from platform surfaces (Priority: P1)

As a platform contributor, I want platform-core and platform-near contracts to use canonical platform vocabulary so that I do not assume every governed subject is an Intune policy.

Why this priority: This is the core reason for the feature. If the platform continues to speak in universal policy_type semantics, future structural improvements still land into the wrong mental model.

Independent Test: Review the hardened platform contracts, summaries, and registries touched by this spec and confirm they use canonical platform terms while leaving explicitly Intune-owned contracts unchanged.

Acceptance Scenarios:

  1. Given a platform-core contract that currently uses policy_type as a universal discriminator, When the hardening is applied, Then the contract uses canonical platform vocabulary instead of implying every governed subject is an Intune policy.
  2. Given an explicitly Intune-owned contract such as policy metadata or adapter-specific catalog data, When the hardening is applied, Then Intune-native terms remain in place and are not replaced with vague generic wording.

User Story 2 - Keep monitoring and review semantics clear during transition (Priority: P1)

As an operator, I want operation labels, reason semantics, and grouped summaries to remain understandable during the transition so that vocabulary hardening does not break monitoring or review workflows.

Why this priority: This feature cannot improve architecture at the cost of confusing current operators or breaking run and review interpretation.

Independent Test: Exercise historical and canonical operation types across monitoring, run detail, and compare or review surfaces and confirm labels, groupings, and explanation semantics remain correct.

Acceptance Scenarios:

  1. Given a historical run or summary that still carries a legacy operation type, When an operator views it after this feature lands, Then the surface resolves it to the canonical operator-facing label and correct domain grouping without breaking the run history.
  2. Given a surface that shows a platform reason and a domain-specific cause, When the operator inspects the explanation, Then the platform reason remains distinct from the domain-owned detail instead of collapsing into one ambiguous code family.

User Story 3 - Make platform and domain ownership obvious to future contributors (Priority: P2)

As a contributor onboarding to the codebase, I want one maintained boundary reference for canonical platform terms so that I can tell whether a registry, discriminator, or reason belongs to the platform core or to the Intune adapter.

Why this priority: Clear ownership is what keeps future work from reintroducing semantic drift after the first hardening pass.

Independent Test: Use the glossary and boundary guidance alone to classify touched terms, registries, and reason families as platform_core, cross_domain_governance, or intune_specific, without relying on historical Intune knowledge.

Acceptance Scenarios:

  1. Given a contributor reads the maintained glossary or boundary note, When they inspect a touched registry or reason family, Then they can determine whether it is platform_core, cross_domain_governance, or intune_specific from the documented vocabulary alone.
  2. Given a contributor adds new platform-core work within the scope of this feature, When they choose labels or contract terms, Then the canonical glossary directs them away from false-universal Intune wording.

User Story 4 - Preserve Intune-first behavior while hardening boundaries (Priority: P2)

As a product maintainer, I want vocabulary hardening to leave current Intune-first operation, compare, evidence, and review behavior intact so that the transition stays safe while the platform boundary becomes clearer.

Why this priority: The feature is about correctness of platform meaning, not about changing what the current Intune product does.

Independent Test: Run focused regression coverage for current Intune-first flows that use the touched operation types, reason semantics, registries, and platform-near discriminators and confirm behavior stays the same except for the intended vocabulary hardening.

Acceptance Scenarios:

  1. Given an existing Intune-first compare, evidence, review, or monitoring flow, When the feature ships, Then the flow still works and the only intended difference is clearer platform-vs-domain vocabulary where the old wording was misleading.
  2. Given a platform-near persisted discriminator or summary is hardened, When existing Intune data is read or rendered, Then compatibility mapping preserves current behavior during the documented transition period.

Edge Cases

  • A historical operation run still stores a legacy type value that no longer matches the canonical operation name one-to-one.
  • A platform summary consumes data from an untouched Intune adapter contract that still uses policy_type, and the boundary must prevent that term from leaking back into platform-core language.
  • A reason explanation includes both a platform-wide failure category and an Intune-specific root cause, and the surface must keep ownership explicit.
  • A contributor encounters a registry whose name was historically broad but whose contents are still domain-owned, and the hardening must avoid leaving it ambiguously universal.
  • A platform-near persisted discriminator needs a rename in one surface but remains Intune-owned in a neighboring table, and the transition must not imply a fake generic rewrite.
  • Legacy and canonical operation type names coexist temporarily in reporting filters, exports, or saved views, and the system must not make both names appear permanently canonical.

Requirements (mandatory)

Constitution alignment (required): This feature does not introduce a new Microsoft Graph path or a new long-running workflow. It hardens the vocabulary used by existing platform surfaces, operation types, summaries, registries, and reason semantics so that platform-core meaning stays accurate as the product expands.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): The glossary, operation-type model, and reason-code ownership rules are justified by current-release platform ambiguity. The spec must stay narrow: no new persisted entity, no generic plugin framework, no fake platform rewrite of Intune adapters, and no new state family without operator or contributor consequence.

Constitution alignment (OPS-UX): Existing OperationRun lifecycles, status ownership, summary-count rules, and three-surface feedback remain unchanged. If operation types or run titles are hardened, the change must preserve current observability and keep transition support compatible with existing monitoring surfaces.

Constitution alignment (RBAC-UX): The feature spans platform /system console surfaces, workspace monitoring surfaces, and tenant review surfaces but does not change guard, membership, or capability boundaries. Non-members remain 404, capable members remain governed by current plane-specific capability checks, and vocabulary hardening must not leak hidden records through labels or explanations.

Constitution alignment (OPS-EX-AUTH-001): Not applicable beyond reaffirming that this feature does not create an authentication-handshake exception.

Constitution alignment (BADGE-001): If any status-like or outcome-adjacent labels are touched, their semantics must remain centralized and derived from canonical platform or domain truth rather than page-local wording.

Constitution alignment (UI-FIL-001): Touched monitoring and review surfaces continue to use existing Filament pages, summaries, tables, and shared UI primitives. Vocabulary hardening must not introduce a page-local semantic framework or custom status language.

Constitution alignment (UI-NAMING-001): Operation labels, run titles, summary headings, notifications, and audit prose touched by this spec must use one canonical term per platform concept. Domain disambiguation must appear only where it clarifies ownership rather than adding noise.

Constitution alignment (DECIDE-001): The feature does not create a new primary decision surface. It improves existing decision and diagnostics surfaces by making platform-core meaning explicit and keeping domain-local detail secondary.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001): Existing navigation, inspect models, and action placement remain unchanged. The material change is vocabulary and grouping clarity, not a new surface hierarchy.

Constitution alignment (ACTSURF-001 - action hierarchy): No new header, row, or bulk action structure is introduced. Any touched labels or helper copy must preserve the current separation between navigation, mutation, context, and dangerous actions.

Constitution alignment (OPSURF-001): Default-visible content on touched monitoring and review surfaces must stay operator-first. Canonical operation meaning and platform reason semantics belong in the default view; raw provider terms, migration detail, and deep diagnostics remain secondary.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): The feature must not add a second semantic interpretation layer. It should replace misleading names with canonical names and keep tests focused on operator meaning, boundary ownership, and compatibility behavior.

Constitution alignment (Filament Action Surfaces): The Action Surface Contract remains satisfied. Each touched surface keeps one primary inspect or open model, no redundant View action is introduced, no empty action groups are added, and no destructive action changes are required. The UI Action Matrix below records the touched surfaces.

Constitution alignment (UX-001 - Layout & Information Architecture): Existing monitoring and review layouts remain in place. Vocabulary hardening must not introduce new layout patterns, duplicate summaries, or parallel explanation panes.

Functional Requirements

  • FR-204-001 Canonical glossary source of truth: The product MUST maintain one internal source of truth for canonical platform vocabulary defining at least domain_key, subject_class, subject_type_key, resource_type if used, operation_type, platform_reason_family, reason_owner.owner_namespace, reason_code, registry_key, and boundary_classification for registry ownership.
  • FR-204-002 Boundary rule in glossary: The maintained vocabulary source MUST explicitly state that platform-core and cross-domain contracts use platform vocabulary, while Intune-owned contracts may retain correct Intune-native terminology.
  • FR-204-003 Platform-core discriminator hardening: Platform-core and cross-domain contracts touched by this spec MUST stop using policy_type or equivalent Intune-only wording as a universal governed-subject discriminator.
  • FR-204-004 Intune-owned vocabulary preservation: Intune-owned entities, metadata, and adapter contracts touched by this spec MUST remain free to use policy_type, Policy, PolicyVersion, assignment, scope tags, Graph resource terms, and other Intune-native language where the object is explicitly Intune-owned.
  • FR-204-005 Canonical governed-subject vocabulary: Platform-near discriminators hardened by this spec MUST use the governed-subject vocabulary established by Spec 202, including domain_key, subject_class, and subject_type_key or an equivalent plural form when the contract carries multiple subject types.
  • FR-204-006 Platform-near persistence hardening: If a platform-near persisted discriminator still communicates false-universal Intune meaning, the surface MUST be renamed or wrapped by a platform-correct contract; purely Intune-owned persistence MAY remain unchanged.
  • FR-204-007 Canonical operation type model: The canonical platform operation-type model MUST be domain-aware and MUST use the exact <domain>.<capability>.<action> format for canonical operation codes.
  • FR-204-008 One canonical operation type per action: Each operation surfaced after this hardening MUST have exactly one canonical operation type, and new or updated platform flows touched by this spec MUST emit only canonical names.
  • FR-204-009 Legacy operation-type mapping: Where historical operation types already exist, the system MAY support a temporary mapping layer, but the mapping MUST point toward one canonical future-safe operation type and MUST be documented as transitional.
  • FR-204-010 Operation catalog continuity: Operation catalogs, labels, groupings, filters, and monitoring summaries touched by this spec MUST resolve both canonical and supported legacy operation-type values without breaking operator comprehension during the transition period.
  • FR-204-011 Platform reason-family boundary: Platform reason families touched by this spec MUST contain only domain-neutral causes that can apply across governance domains.
  • FR-204-012 Domain reason-code ownership: Domain-specific reason codes touched by this spec MUST be namespaced or otherwise clearly segregated so they are recognizable as domain-owned rather than platform-core concepts.
  • FR-204-013 Explanation layering: Operator-facing explanation surfaces touched by this spec MUST show platform reason meaning separately from domain-specific cause detail when both are present.
  • FR-204-014 Registry ownership naming: Registries and catalogs touched by this spec MUST explicitly signal whether they are platform_core, cross_domain_governance, or intune_specific.
  • FR-204-015 No implicit universal Intune registry: No contributor-facing registry, catalog, or API touched by this spec may imply that the current Intune policy catalog or supported Intune type list is the universal governed-subject registry of the platform.
  • FR-204-016 Platform-summary vocabulary hardening: Compare, evidence, review, reporting, and monitoring summaries touched by this spec MUST use canonical platform vocabulary for governed subjects, operation types, and explanation ownership.
  • FR-204-017 One concept, one canonical name: For each hardened platform concept, the spec MUST identify one canonical name and MUST document any temporary legacy alias that remains supported during rollout.
  • FR-204-018 Transition retirement rule: Any dual vocabulary introduced for compatibility MUST include a documented retirement path so old and new names do not remain equally canonical after rollout stabilizes.
  • FR-204-019 Targeted migration rule: Any persisted rename introduced by this spec MUST be narrowly targeted, backward-compatible during rollout, and limited to surfaces where the old name causes cross-domain confusion.
  • FR-204-020 No-regression guarantee: The hardening MUST preserve current Intune-first operation, compare, evidence, review, and reporting behavior unless a separate spec explicitly changes that behavior.
  • FR-204-021 Contributor boundary guidance: The resulting glossary or boundary note MUST let a new contributor answer whether a touched concept is platform_core, cross_domain_governance, or intune_specific without guessing from naming alone.
  • FR-204-022 Anti-churn guardrail: The implementation MUST avoid broad repository-wide renaming and limit hardening to surfaces where vocabulary materially affects platform semantics, expansion safety, or contributor mental model.
  • FR-204-023 No reintroduction through copy: New or changed platform-core labels, run titles, notifications, audit prose, and helper copy included in this spec MUST not reintroduce false-universal Intune wording.
  • FR-204-024 Regression coverage: Automated coverage MUST protect operation-type mapping, reason-code layering, registry ownership boundaries, platform-near discriminator behavior, and no-regression Intune semantics for the flows touched by this spec.

Non-Functional Requirements

  • NFR-204-001 DB-only render invariant: Touched monitoring and review surfaces MUST remain DB-only at render time and MUST NOT initiate provider, Graph, or other external calls as a side effect of rendering, filtering, summarizing, or opening detail pages.
  • NFR-204-002 In-process resolution invariant: Canonical operation resolution, reason ownership and family translation, registry ownership lookup, and platform subject normalization MUST execute in-process against application code, configuration, and persisted state already available to the request.
  • NFR-204-003 Query-shape guardrail: Vocabulary hardening MUST NOT introduce request-path schema rewrites or query fan-out on touched monitoring and review surfaces relative to the current read-path architecture.

Canonical Vocabulary Appendix

Hardened Concept Canonical Name / Code Supported Legacy Alias Retirement Path / Status
Governance domain field domain_key none Permanent canonical field for the governance domain on touched cross-domain and platform-near contracts
Governance subject class field subject_class none Permanent canonical field for subject-class semantics on touched cross-domain and platform-near contracts
Platform governed-subject discriminator subject_type_key plus subject_type_label, with domain_key and subject_class policy_type on platform-core or platform-near surfaces Retire from touched platform-owned summaries, filters, and context payloads in Spec 204; keep only where the object remains explicitly Intune-specific
Platform governed-subject discriminator (plural) subject_type_keys with per-item subject_type_label or display_label policy_types on platform-core or platform-near surfaces Retire from touched platform-owned collection payloads in Spec 204; adapter-owned lists may remain Intune-specific
Optional platform resource field resource_type mixed resource-like nouns on touched platform-owned summaries when a separate resource noun is required Use only where a touched platform-facing contract needs a resource-shaped noun distinct from subject_type_key; otherwise omit
Platform operation-type field operation_type raw type on platform-facing summaries or filters Use canonical operation_type on touched read models, summaries, filters, and exports even when persisted storage continues to use operation_runs.type
Platform reason-family field platform_reason_family none Permanent canonical field for platform-neutral cause grouping
Domain reason ownership signal reason_owner.owner_namespace plus original reason_code unlabeled or mixed domain reason groupings Use explicit owner namespace and original domain code on touched explanation contracts; do not keep unlabeled domain families as if they were platform-wide
Registry key registry_key none Permanent internal identifier for touched registries and catalogs
Registry boundary classification boundary_classification with platform_core, cross_domain_governance, intune_specific unlabeled broad registry ownership Retire unlabeled ownership on touched registries during Spec 204 review and implementation
Baseline compare operation type baseline.compare.execute baseline_compare New or updated touched producers emit the canonical code in Spec 204; legacy alias remains read-only compatibility for historical runs until no supported producer writes it
Baseline capture operation type baseline.capture.execute baseline_capture New or updated touched producers emit the canonical code in Spec 204; legacy alias remains read-only compatibility for historical runs until no supported producer writes it
Inventory sync operation type inventory.sync.execute inventory_sync New or updated touched producers emit the canonical code in Spec 204; legacy alias remains read-only compatibility for historical runs until no supported producer writes it
Directory groups sync operation type directory.groups.sync entra_group_sync New or updated touched producers emit the canonical code in Spec 204; legacy alias remains read-only compatibility for historical runs until no supported producer writes it
Backup schedule execution operation type backup.schedule.execute backup_schedule_run New or updated touched producers emit the canonical code in Spec 204; legacy alias remains read-only compatibility for historical runs until no supported producer writes it
Tenant review composition operation type tenant.review.compose none Already canonical; no alias retirement required
Review pack generation operation type tenant.review_pack.generate none Already canonical for current scope; no alias retirement required
Evidence snapshot generation operation type tenant.evidence.snapshot.generate none Already canonical for current scope; no alias retirement required

UI Action Matrix (mandatory when Filament is changed)

Surface Location Header Actions Inspect Affordance (List/Table) Row Actions (max 2 visible) Bulk Actions (grouped) Empty-State CTA(s) View Header Actions Create/Edit Save+Cancel Audit log? Notes / Exemptions
Monitoring operations list Existing Monitoring operations list surface at /admin/operations No new header actions; existing monitoring actions remain Existing full-row or explicit run open remains the inspect path Existing safe list actions only Existing grouped bulk actions only Existing monitoring empty-state CTA remains n/a n/a Existing run and audit semantics remain Action hierarchy does not change; vocabulary, labels, and filters are the only material changes
Operation run detail Existing canonical operation detail surface at /admin/operations/{run} No new header actions; existing navigation actions remain Explicit run detail page none added none Existing no-data or no-run states remain Existing detail-page actions remain n/a Existing run-backed audit semantics remain Platform and domain explanation layers become clearer, but no new action plane is introduced
Tenant dashboard recent operations widget Existing tenant dashboard widget at /admin/t/{tenant} No new dashboard header actions are introduced by this spec Linked widget summary opens the existing run or monitoring context none added none Existing dashboard empty-state behavior remains n/a n/a Existing run and tenant audit semantics remain Widget copy changes only; it must remain a calm secondary context surface
System dashboard Control Tower widgets Existing system dashboard widgets at /system Existing system dashboard header actions remain unchanged Linked widget summary opens the existing console monitoring context or run detail none added none Existing dashboard empty-state behavior remains n/a n/a Existing system-console audit semantics remain Widget copy changes only; no new system-console action plane is introduced
Evidence snapshot resource and snapshot presentation Existing evidence surfaces at /admin/t/{tenant}/evidence and /admin/t/{tenant}/evidence/{snapshot} Existing list-header create-snapshot action remains Existing clickable-row snapshot open remains the inspect path Existing safe row actions remain grouped under More Existing grouped bulk actions remain unchanged Existing evidence empty-state CTA remains Existing snapshot detail actions remain Existing create flow remains unchanged Existing evidence audit semantics remain Governed-subject wording changes, not action hierarchy
Tenant baseline compare surfaces Existing tenant review surfaces including /admin/t/{tenant}/baseline-compare Existing compare or review actions remain unchanged Existing page and linked review context remain the inspect path none added none Existing compare or review empty-state CTA remains Existing page actions remain n/a Existing review and compare audit semantics remain No destructive-action change and no Action Surface Contract exemption needed
Tenant review resource Existing tenant review resource at /admin/t/{tenant}/reviews and /admin/t/{tenant}/reviews/{review} Existing create or export header actions remain Existing clickable-row review open remains the inspect path Existing safe review actions remain contextual Existing grouped bulk actions remain unchanged Existing review empty-state CTA remains Existing review detail actions remain Existing create flow remains unchanged Existing review audit semantics remain Vocabulary hardening must not alter review action hierarchy
Tenant review pack widget Existing tenant reporting widget opening /admin/t/{tenant}/review-packs/{reviewPack} No new widget header actions are introduced Existing widget CTA remains the inspect path none added none Existing widget empty-state behavior remains n/a n/a Existing review-pack audit semantics remain Widget copy and labels change only
Provider connection resource launch surface Existing provider connection resource at /admin/provider-connections and /admin/provider-connections/{connection} Existing create and provider-operation header actions remain Existing clickable-row or detail inspect path remains primary Existing provider-operation actions remain grouped under More or detail headers Existing bulk-action omission remains Existing empty-state CTA remains Existing provider-connection detail actions remain Existing create and edit flows remain unchanged Existing provider audit semantics remain Launch labels change only; no new workflow hub is introduced
Inventory item list launch surface Existing inventory register at /admin/t/{tenant}/inventory/inventory-items and /admin/t/{tenant}/inventory/inventory-items/{item} Existing list-header sync action remains Existing clickable-row item open remains the inspect path Existing safe launch actions remain contextual Existing bulk-action omission remains Existing inventory empty-state behavior remains Existing item detail actions remain n/a Existing inventory and run audit semantics remain Vocabulary hardening must not turn the list into a control center
Backup schedule resource launch surface Existing backup schedule resource at /admin/t/{tenant}/backup-schedules and /admin/t/{tenant}/backup-schedules/{schedule}/edit Existing create and schedule-run header actions remain Existing clickable-row or edit inspect path remains primary Existing schedule actions remain grouped under More or detail headers Existing grouped bulk actions remain Existing backup empty-state CTA remains Existing schedule detail actions remain Existing create and edit flows remain unchanged Existing backup audit semantics remain Canonical run wording changes only
Managed tenant onboarding wizard Existing onboarding routes at /admin/onboarding and /admin/onboarding/{onboardingDraft} Existing staged wizard header actions remain Existing staged wizard progression remains the inspect path Existing inline stage actions remain limited to the current step none Existing onboarding empty-state and resume affordances remain Existing stage actions remain Existing staged save and resume flow remains unchanged Existing onboarding audit semantics remain Wizard exception remains explicit; the next step must stay obvious

Key Entities (include if feature involves data)

  • Canonical Platform Vocabulary Glossary: The maintained source of truth that defines platform-core terms, ownership boundaries, and the canonical names contributors must use.
  • Platform-near Governed Subject Discriminator: Any persisted or contract-level discriminator on a platform-facing surface that identifies what kind of governed subject a record refers to.
  • Canonical Operation Type: The domain-aware identifier used by platform operation catalogs, monitoring surfaces, and run semantics.
  • Platform Reason Family: The reusable platform-wide explanation category set used to describe cross-domain causes such as unsupported scope or provider unavailability.
  • Domain Reason Ownership Signal: The explicit owner namespace and original domain code that identify a cause as Intune-owned or otherwise domain-owned rather than platform-core.
  • Registry Ownership Boundary: The documented distinction between platform-wide registries and domain-owned registries or catalogs.

Verification Scope Inventory

For FR-204-024 and SC-001 through SC-005, "touched", "reviewed", and "focused regression coverage" refer only to:

  • the operator-facing surfaces enumerated in the Decision-First Surface Role, UI/UX Surface Classification, Operator Surface Contract, and UI Action Matrix tables
  • the platform-near contract families enumerated in the Canonical Vocabulary Appendix
  • the platform-owned or platform-near payloads, filters, summaries, and translation envelopes that directly serve those surfaces

No other repository surface, contract, or adapter is implicitly included in those measurements.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: In the reviewed platform-core and platform-near contracts touched by this feature, 100% of universal governed-subject discriminators no longer rely on Intune-only policy_type wording.
  • SC-002: In regression coverage for touched monitoring and review flows, 100% of supported historical and canonical operation-type values resolve to the correct operator label and domain grouping during transition.
  • SC-003: In regression coverage for touched explanation surfaces, 100% of platform reason families remain domain-neutral and 100% of domain-local causes appear only as namespaced or domain-owned detail.
  • SC-004: Architecture review can classify every touched registry, catalog, and reason family as platform_core, cross_domain_governance, or intune_specific using the maintained glossary or boundary note alone.
  • SC-005: Current Intune-first operation, compare, evidence, review, and reporting behavior remains unchanged in focused regression coverage except for the intended vocabulary hardening on platform-core surfaces.

Rollout Strategy

Phase 1 - Introduce canonical vocabulary

  • Publish the maintained glossary or boundary note.
  • Define the canonical operation-type model.
  • Define platform-vs-domain reason-code ownership and registry ownership rules.

Phase 2 - Harden platform-core surfaces

  • Update platform-near discriminators and platform summaries where the old wording is misleading.
  • Update operation catalogs, labels, and grouping semantics.
  • Harden touched compare, evidence, review, and reporting contracts to use canonical platform vocabulary.

Phase 3 - Transitional compatibility

  • Support limited mapping from legacy operation-type names or discriminator aliases where historical values already exist.
  • Keep compatibility explicitly temporary and documented.
  • Prevent new code added within scope from reintroducing legacy platform-core vocabulary.

Phase 4 - Remove ambiguity

  • Remove unnecessary dual names once rollout is stable.
  • Retire temporary aliases and mapping where feasible.
  • Keep only the canonical platform names documented as current truth.

Non-Goals

  • Implementing a new governance domain
  • Redesigning baseline scope after Spec 202
  • Replacing compare strategy extraction from Spec 203
  • Generalizing Intune-owned adapter models into vague platform abstractions
  • Renaming every historical Intune table, field, or model in the repository
  • Reworking backup and restore into a generic cross-domain engine
  • Redesigning user-facing copy across every page unless needed to stop platform-core leakage
  • Building a universal plugin framework for every registry or catalog

Assumptions

  • Spec 202 provides the canonical governed-subject vocabulary the platform should prefer for cross-domain semantics.
  • Spec 203 provides the compare boundary that this vocabulary hardening can align with rather than replace.
  • Intune remains the first real governance domain during this rollout, so preserving correct Intune-native terminology is part of the success condition.
  • Historical operation-type values and some platform-near discriminators may already exist and may require temporary mapping rather than immediate destructive rewrite.
  • Current monitoring, compare, evidence, review, and reporting surfaces are the operator truth surfaces that most need stable platform vocabulary.

Dependencies

  • Spec 202 - Governance Subject Taxonomy and Baseline Scope V2
  • Spec 203 - Baseline Compare Engine Strategy Extraction
  • Existing Monitoring operations list and operation detail surfaces
  • Existing compare, evidence, review, and reporting summaries touched by platform-core labels or explanation semantics
  • Existing Intune adapters, catalogs, and metadata as the baseline behavior and vocabulary that must remain intact where domain-owned

Risks

  • The work could drift into a broad rename sweep instead of targeted platform hardening.
  • Intune-specific objects could be renamed into vague generic language, reducing clarity instead of improving it.
  • Compatibility support could become permanent and leave dual vocabulary in place.
  • Targeted persisted renames could create unnecessary migration churn if the platform-near boundary is not explicit enough.
  • Operation-type changes could break monitoring, filtering, or reporting if mapping and regression coverage are incomplete.

Definition of Done

  • The codebase has one maintained canonical platform vocabulary for governed subjects, operation types, reason ownership, and registry ownership.
  • Platform-core and platform-near surfaces touched by this spec no longer communicate that everything is an Intune policy.
  • Intune-owned adapter surfaces remain clearly and intentionally Intune-specific.
  • Operation typing is domain-aware, future-safe, and backward-compatible during the documented transition.
  • Platform reason semantics are cleanly separated from domain-specific cause vocabularies.
  • Registry and catalog ownership is obvious to contributors.
  • Focused regression coverage proves no current Intune-first behavior regressed because of the hardening.
  • Documentation makes platform-core versus domain-owned boundaries obvious for future contributors.