TenantAtlas/specs/236-canonical-control-catalog-foundation/spec.md

Feature Specification: Canonical Control Catalog Foundation

Feature Branch: 236-canonical-control-catalog-foundation
Created: 2026-04-24
Status: Approved
Input: User description: "Canonical Control Catalog Foundation"

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

• Problem: TenantPilot already has real governance workflows across baselines, drift, findings, evidence, exceptions, and review packs, but it still lacks one shared canonical control object that those workflows can point at.
• Today's failure: The same technical control objective can be expressed differently in baseline logic, finding summaries, evidence interpretation, and later framework discussions, which blurs what the control actually is versus which Microsoft subject, workload, or evidence item currently supports it.
• User-visible improvement: Governance artifacts can converge on one stable control identity and one honest detectability story instead of each surface inventing local control meaning.
• Smallest enterprise-capable version: Introduce a product-seeded canonical control catalog with stable control keys, control metadata, detectability and evaluation semantics, evidence archetypes, Microsoft subject bindings, and one shared resolution contract consumed by existing governance builders.
• Explicit non-goals: No certification engine, no framework-first catalog, no full NIS2/BSI/ISO/COBIT library, no operator-managed CRUD UI for controls, no posture scoring, no second artifact store, and no broad Microsoft-domain expansion.
• Permanent complexity imported: One canonical control registry, one subject-binding model, one shared control-resolution contract, a small metadata family for detectability and evaluation semantics, and focused regression coverage for consumers.
• Why now: The roadmap and spec candidates place this as the next strategic bridge between the shipped governance engine and later readiness or customer-review work.
• Why not local: A local label or mapping inside one feature would keep control meaning fragmented and force every downstream surface to keep duplicating the same semantics.
• Approval class: Core Enterprise
• Red flags triggered: New source-of-truth risk and taxonomy risk. Defense: the first slice stays product-seeded, narrow, framework-neutral, and avoids authoring UI or speculative multi-provider machinery.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes:
  • No new standalone route is required in the foundation slice.
  • First-slice consumers remain on their current surfaces, specifically evidence snapshots and tenant review composition paths. Findings continue to feed the existing evidence pipeline on their current path, and any tenant review inspection remains downstream of already composed review data rather than a separate adoption target in this slice.
• Data Ownership:
  • Canonical control definitions are product-seeded platform truth consumed safely within workspace-scoped governance workflows.
  • Derived control references in the first slice remain owned by existing evidence snapshot and tenant review records that consume them. Findings remain feeder inputs rather than a direct canonical-control consumer surface in this slice.
  • No new operator-managed tenant-owned entity is introduced in the first slice.
• RBAC:
  • No new top-level capability is introduced for the first slice.
  • Existing authorization on evidence and tenant review surfaces continues to gate any downstream control metadata shown through those surfaces in the first slice.
  • The catalog foundation must not relax tenant or workspace isolation.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes
• Interaction class(es): evidence viewers, tenant review composition, governance summaries, read-model composition
• Systems touched: findings-derived evidence composition, evidence snapshot composition, tenant review composition, and downstream inspection of already composed review data
• Existing pattern(s) to extend: existing governance summary builders and existing evidence or review composition paths
• Shared contract / presenter / builder / renderer to reuse: existing domain builders stay in place; they consume one new shared control-resolution contract rather than inventing local control labels
• Why the existing shared path is sufficient or insufficient: existing builders are sufficient for surface-specific formatting, but they are insufficient for cross-domain control identity because each builder currently has only local subject or evidence context
• Allowed deviation and why: none
• Consistency impact: control key, control label, detectability language, and evidence suitability semantics must remain identical wherever the shared control contract is consumed
• Review focus: reviewers should block any new consumer that bypasses the shared control catalog by inventing local control-family wording or workload-first labels

Provider Boundary / Platform Core Check (mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write N/A - no shared provider/platform boundary touched)

• Shared provider/platform boundary touched?: yes
• Boundary classification: mixed
• Seams affected: control taxonomy, governed-subject binding, control-resolution semantics, downstream operator vocabulary derived from canonical controls
• Neutral platform terms preserved or introduced: canonical control, control domain, control subdomain, control class, detectability class, evaluation strategy, evidence archetype, governed subject, provider binding
• Provider-specific semantics retained and why: Microsoft workload, subject-family, and signal bindings remain provider-owned metadata because the current product truth is Microsoft-first
• Why this does not deepen provider coupling accidentally: canonical control keys and primary control definitions remain framework-neutral and provider-neutral; Microsoft-specific bindings are attached as secondary metadata, not used as the primary control identity
• Follow-up path: none

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

N/A - no new operator-facing surface is required in the foundation slice. Existing surfaces may consume canonical control references through later adoption or small follow-through changes, but this spec does not add a new page, queue, or custom UI framework.

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
• Current operator problem: Operators, reviewers, and future customer-facing outputs do not yet have one stable answer to which control an artifact is about; the same objective can still be rephrased differently per workflow.
• Existing structure is insufficient because: governed-subject taxonomy explains what Microsoft object or subject family is in scope, but it does not define the higher-order control objective, its detectability class, or how evidence should be interpreted across domains.
• Narrowest correct implementation: use a product-seeded canonical control registry plus one shared resolution contract and keep the first adoption derived rather than introducing CRUD management or broad new persistence.
• Ownership cost: the seed catalog must be curated, binding rules must stay deterministic, and downstream consumer tests must prevent drift in control identity or detectability semantics.
• Alternative intentionally rejected: feature-local control labels and an immediate DB-backed authoring system were rejected because the former preserves fragmentation and the latter imports unnecessary lifecycle and UI complexity before the catalog proves itself.
• Release truth: current-release truth with deliberate preparation for later readiness and reporting overlays

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Unit, Feature
• Validation lane(s): fast-feedback, confidence
• Why this classification and these lanes are sufficient: the first slice is primarily a deterministic catalog and resolution contract with a few bounded integration points; unit tests prove metadata and resolution rules, and focused feature tests prove downstream consumers do not fork control meaning locally
• New or expanded test families: targeted governance foundation tests only
• Fixture / helper cost impact: minimal; use seeded config or registry fixtures and existing baseline, finding, evidence, and review factories where integration coverage is needed
• Heavy-family visibility / justification: none; no browser or heavy-governance family is required for the first slice
• Special surface test profile: N/A
• Standard-native relief or required special coverage: ordinary feature coverage only
• Reviewer handoff: reviewers should confirm that lane choice stays narrow, no expensive shared helper defaults are introduced, and all downstream references come from the shared contract rather than local labels
• Budget / baseline / trend impact: none expected
• Escalation needed: none
• Active feature PR close-out entry: Guardrail
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Governance/CanonicalControlCatalogTest.php tests/Unit/Governance/CanonicalControlResolverTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Governance/CanonicalControlResolutionIntegrationTest.php tests/Feature/Evidence/EvidenceSnapshotCanonicalControlReferenceTest.php tests/Feature/TenantReview/TenantReviewCanonicalControlReferenceTest.php

User Scenarios & Testing (mandatory)

User Story 1 - Resolve One Stable Control Identity (Priority: P1)

As an operator or reviewer, I want governance artifacts that describe the same control objective to resolve to one stable canonical control so the product stops explaining the same issue differently per feature.

Why this priority: This is the primary value of the foundation. Without stable control identity, later readiness, reporting, and customer review work will keep duplicating local semantics.

Independent Test: Resolve the same governance objective through at least two existing consumer contexts and confirm the shared contract returns the same canonical control key and metadata.

Acceptance Scenarios:

1. Given two Microsoft subject families that represent the same governance objective, When the system resolves their canonical control references, Then both resolve to the same canonical control key and label.
2. Given a findings-derived evidence composition path and a tenant review consumer that point at the same governance objective, When both request canonical control metadata, Then both receive the same control identity and detectability semantics.

---

User Story 2 - Preserve Honest Detectability and Evidence Meaning (Priority: P1)

As an operator preparing a governance review, I want the platform to distinguish direct-technical controls from indirect, attested, or external-evidence-only controls so later outputs do not over-claim what TenantPilot can prove automatically.

Why this priority: Honest detectability is part of the product's trust contract. A canonical control layer that collapses all controls into one false verified or not-verified path would harm operator trust.

Independent Test: Inspect seed controls with different detectability classes and verify each one carries explicit evaluation and evidence semantics.

Acceptance Scenarios:

1. Given a seed control that is only workflow-attested or external-evidence-only, When the control is resolved, Then the metadata explicitly marks that detectability class instead of implying direct technical verification.
2. Given a seed control with multiple allowed evidence archetypes, When a downstream consumer requests suitability metadata, Then the response identifies which evidence forms are valid for that control.

---

User Story 3 - Add Microsoft Bindings Without Making Microsoft the Control Model (Priority: P2)

As a maintainer extending governance coverage, I want Microsoft workload and signal bindings to attach to canonical controls without turning service-specific labels into the platform's primary control vocabulary.

Why this priority: The first provider is Microsoft, but the platform core must not become silently Microsoft-shaped. This story protects the boundary while still enabling real current-release bindings.

Independent Test: Add or modify a Microsoft subject binding for a seeded control and confirm the canonical control definition stays unchanged while the binding metadata changes.

Acceptance Scenarios:

1. Given a canonical control already exists for a governance objective, When a new Microsoft subject family is bound to it, Then the system reuses the existing canonical control key instead of creating a duplicate control definition.
2. Given provider-specific subject or signal metadata changes, When the binding is updated, Then the platform-core control definition remains stable and provider-neutral.

---

User Story 4 - Prepare Later Readiness and Review Work Without Local Reinvention (Priority: P3)

As a product maintainer, I want the first-slice evidence and tenant review consumers to have one defined path to canonical control metadata so later work does not invent its own framework or workload-specific control objects.

Why this priority: This is the strategic bridge value of the spec. It keeps later slices smaller and prevents new semantic drift.

Independent Test: Prove that the first-slice evidence and tenant review consumers can request canonical control metadata through one shared contract without adding local control-family registries.

Acceptance Scenarios:

1. Given an evidence or tenant review consumer is in the first adoption slice, When it needs control metadata, Then it uses the shared canonical control contract rather than feature-local labels or registries.
2. Given a framework-specific readiness or reporting slice is planned later, When it references control meaning, Then the canonical catalog remains the primary control layer and any framework mapping remains secondary.

Edge Cases

• One Microsoft subject family can plausibly map to more than one control objective.
• A canonical control is valid for review packs and evidence only, but not for direct baseline or drift evaluation.
• A control is retired for new use, but existing downstream references still point to its stable key.
• A downstream consumer asks for canonical control metadata without a valid subject binding.
• Two provider-owned bindings point to one canonical control while using different signal shapes.
• A future framework mapping attempts to redefine canonical control identity instead of layering on top of it.

Requirements (mandatory)

Constitution alignment (required): This foundation does not add Microsoft Graph calls, destructive actions, or a new operator-facing run flow. The first slice remains read-focused and in-process. If later follow-through work introduces writes, runs, or new surfaces, those slices must define their own safety and observability contract explicitly.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): This feature intentionally introduces one new canonical control taxonomy and one shared resolution contract because governed-subject vocabulary alone cannot safely carry control meaning. The first slice avoids DB-backed control authoring, avoids framework overlays, and keeps consumer adoption derived before persistence.

Constitution alignment (XCUT-001): This feature touches cross-cutting governance summaries plus first-slice evidence and tenant review consumers. Those consumers must continue to use their existing builders and presentation paths, but control identity and detectability semantics must come from the shared canonical control contract.

Constitution alignment (PROV-001): The canonical control catalog is platform-core. Microsoft workload and signal bindings are provider-owned metadata. Provider-specific semantics must remain secondary and must not replace canonical control keys or vocabulary.

Constitution alignment (TEST-GOV-001): Coverage stays in narrow unit and feature lanes. No new heavy browser or broad surface family is justified for the first slice.

Constitution alignment (OPS-UX): Not applicable in the foundation slice because no new OperationRun is required.

Constitution alignment (RBAC-UX): No authorization boundary changes are introduced. Existing capabilities continue to guard any consumer surfaces that later display canonical control metadata.

Constitution alignment (OPS-EX-AUTH-001): Not applicable.

Constitution alignment (BADGE-001): The first slice does not add new badge families. If later consumers render detectability or suitability as badges, they must do so through centralized badge semantics in a follow-through slice.

Constitution alignment (UI-FIL-001): The foundation slice does not require new Filament UI.

Constitution alignment (UI-NAMING-001): Canonical control vocabulary must remain stable across future consumer surfaces. Provider or workload names are secondary descriptors only.

Constitution alignment (DECIDE-001): No new decision surface is added in the foundation slice.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001): Not applicable in the foundation slice because no new operator-facing surface is added.

Constitution alignment (ACTSURF-001 - action hierarchy): Not applicable.

Constitution alignment (OPSURF-001): Not applicable in the foundation slice because there is no new operator-facing page.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): The feature adds one semantic layer because direct domain-to-UI mapping is insufficient across baseline, finding, evidence, and review workflows without a shared control identity. The catalog and resolver must remain the single source for this meaning, and downstream tests must focus on business truth rather than thin wrappers.

Functional Requirements

• FR-236-001 Authoritative canonical control catalog: The system MUST maintain one authoritative canonical control catalog for the first slice with stable canonical control keys that are independent of provider identifiers, framework clause IDs, and individual workload payload shapes, and it MUST support internal listing of seeded control definitions for inspection and validation.
• FR-236-002 Control definition metadata: Each canonical control definition MUST include, at minimum, a stable key, canonical name, control domain, control subdomain, control class, descriptive summary, and operator-safe explanation of what the control is about.
• FR-236-003 Detectability semantics: Each canonical control definition MUST declare a detectability class that distinguishes at least direct-technical, indirect-technical, workflow-attested, and external-evidence-only controls.
• FR-236-004 Evaluation semantics: Each canonical control definition MUST declare an evaluation strategy that explains how the product should reason about the control without collapsing all controls into one universal compliant or non-compliant path.
• FR-236-005 Evidence archetypes: Each canonical control definition MUST declare at least one evidence archetype and MAY declare more than one valid evidence archetype.
• FR-236-006 Artifact suitability: Each canonical control definition MUST declare whether it is baseline-capable, drift-capable, finding-capable, exception-capable, evidence-capable, review-capable, and report-capable.
• FR-236-007 Microsoft subject binding model: The system MUST support provider-owned Microsoft bindings that connect one canonical control to one or more Microsoft subject families, workloads, or signal sources without redefining the control itself.
• FR-236-008 Provider-neutral control identity: Provider-specific subject metadata MUST NOT be the canonical control primary key or replace the provider-neutral control definition.
• FR-236-009 Multi-binding support: One canonical control MUST be able to bind to multiple Microsoft subject families or signals.
• FR-236-010 Ambiguity handling: If a governed subject or signal maps ambiguously to multiple canonical controls without an explicitly declared primary relationship for the current context, the resolver MUST fail deterministically rather than guessing.
• FR-236-011 Shared resolution contract: The platform MUST provide one shared resolution contract that lets downstream governance consumers request canonical control metadata using current governed-subject or signal context.
• FR-236-012 Consumer convergence path: Findings-derived evidence composition and tenant review consumers in scope for first adoption MUST be able to consume canonical control metadata through the shared contract instead of defining local control-family truth.
• FR-236-013 Seed catalog breadth: The first slice MUST ship with a bounded seed catalog covering a small set of high-value control families relevant to the current governance product, including strong authentication, conditional access, privileged access, sharing or boundary controls, endpoint hardening or compliance, audit retention, and delegated admin boundaries.
• FR-236-014 No framework-first primary shape: Framework overlays such as NIS2, BSI, ISO, COBIT, or CIS MUST NOT be the primary shape of the canonical catalog in the first slice.
• FR-236-015 Honest non-direct coverage: The system MUST represent controls that are not directly technically verifiable without implying that they are directly evaluated by the product.
• FR-236-016 Stable historical reference: A canonical control key once shipped MUST remain stable for downstream artifacts to reference it consistently, even if the control later becomes retired for new use.
• FR-236-017 Missing binding failure safety: If a downstream consumer requests canonical control metadata for a subject or signal with no valid binding, the system MUST return an explicit unresolved result rather than inventing a local fallback control label.
• FR-236-018 Narrow rollout model: The first slice MUST stay product-seeded and MUST NOT require operator-managed CRUD authoring for controls.
• FR-236-019 No new Graph path: The first slice MUST NOT introduce Microsoft Graph calls or a provider synchronization job for catalog resolution.
• FR-236-020 Platform vocabulary: Shared platform contracts introduced by this feature MUST use canonical control and governed-subject vocabulary rather than workload-specific or framework-specific names as their primary language.

Key Entities (include if feature involves data)

• Canonical Control Definition: The product-owned description of one stable governance control objective, including its identity, taxonomy placement, detectability semantics, evaluation strategy, evidence archetypes, and suitability metadata.
• Microsoft Subject Binding: Provider-owned metadata that links Microsoft subject families, workloads, or signal sources to one canonical control without changing the control's primary identity.
• Canonical Control Resolution Result: The shared contract outcome that returns either a resolved canonical control reference or an explicit unresolved or ambiguous result for downstream consumers.

Success Criteria (mandatory)

Measurable Outcomes

• SC-236-001: For every seed control in the first slice, 100% of catalog entries include control domain, subdomain, control class, detectability class, evaluation strategy, and at least one evidence archetype.
• SC-236-002: The same governance objective resolved through at least two targeted first-slice consumer contexts returns one identical canonical control key and label.
• SC-236-003: 100% of first-slice evidence and tenant review integrations use the shared canonical control contract and do not introduce feature-local control-family registries or fallback labels.
• SC-236-004: A new Microsoft subject binding for an already-modeled governance objective can be added without creating a duplicate canonical control definition.