TenantAtlas/specs/095-graph-contracts-registry-completeness/spec.md

# Feature Specification: Graph Contracts Registry Completeness

**Feature Branch**: `095-graph-contracts-registry-completeness`  
**Created**: 2026-02-15  
**Status**: Draft  
**Input**: Ensure Microsoft Graph resources already used by the product are explicitly registered in the app’s contract registry, and ensure call sites use the registry rather than ad-hoc paths. Add regression tests so these resources can’t silently become “untracked” again.

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace
- **Primary Routes**: None (no new user-facing pages or routes)
- **Data Ownership**: No new persistent records; registry metadata only
- **RBAC**: No new permissions; behavior must not expand access beyond existing authorization and tenant isolation

## Clarifications

### Session 2026-02-15

- Q: Which enforcement scope do you want for “no freeform Graph paths”? → A: Enforce registry-backed paths only for the 4 specified resources (and the call sites that touch them).
- Q: What evidence should be required for acceptance? → A: Pest regression tests passing is sufficient evidence.
- Q: Which code locations should be considered “in scope” for the regression guard? → A: ConfigurationPolicyTemplateResolver, SettingsCatalogDefinitionResolver, SettingsCatalogCategoryResolver, RbacOnboardingService, and RbacHealthService.
- Q: If we discover additional unregistered Graph resources during implementation, what should we do? → A: Do not expand scope; register only the 4 specified resources (extra findings become a follow-up spec).

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Drift coverage is complete (Priority: P1)

As a maintainer, I need the contract drift check to cover the Graph resources we already depend on, so that operational “drift” detection is trustworthy and doesn’t miss critical resources.

**Why this priority**: Drift-check coverage gaps undermine safety and auditability across multiple other workflows.

**Independent Test**: A test can assert that the registry explicitly includes the required resources (the same registry enumeration the drift check relies on).

**Acceptance Scenarios**:

1. **Given** the contract registry, **When** it is evaluated for registered resources, **Then** it includes:
  - Configuration Policy Templates
  - Configuration Settings (settings catalog definitions)
  - Configuration Categories
  - RBAC Role Assignments
2. **Given** the registry entry for configuration policy templates, **When** nested template setting templates are needed, **Then** the registry can represent that subresource using an approved template (including an item identifier placeholder).

---

### User Story 2 - Graph calls are registry-backed (Priority: P2)

As a maintainer, I need Graph calls for these resources to use the contract registry rather than freeform strings, so that endpoints are governed consistently (naming, review, and drift-check alignment).

**Why this priority**: Prevents silent expansion of Graph surface area and makes review/audit easier.

**Independent Test**: A test can detect reintroduction of hardcoded endpoint substrings in the relevant call sites.

**Acceptance Scenarios**:

1. **Given** code paths that fetch settings catalog definitions or categories, **When** they call Graph, **Then** they source the resource path from the contract registry rather than embedding hardcoded endpoint substrings.
2. **Given** code paths that create/update role assignments, **When** they call Graph, **Then** they source the role-assignments resource path from the contract registry rather than embedding a hardcoded endpoint.

---

### User Story 3 - Regressions are prevented (Priority: P3)

As a maintainer, I need regression tests that fail if these resources become unregistered or if call sites revert to ad-hoc endpoints, so that future refactors cannot silently break governance.

**Why this priority**: The risk is gradual “drift” over time; a regression guard is the lowest-cost long-term control.

**Independent Test**: A test suite can fail on (a) missing registry entries, and (b) hardcoded endpoint usage in targeted files.

**Acceptance Scenarios**:

1. **Given** a future change accidentally removes a required resource from the registry, **When** tests run, **Then** they fail with a clear message identifying which resource is missing.
2. **Given** a future change introduces a hardcoded endpoint string for one of the covered resources, **When** tests run, **Then** they fail and indicate which endpoint substring was reintroduced.

### Edge Cases

- Graph permissions or tenant isolation limitations cause the resource to be inaccessible for a given tenant; contract registration must not imply access.
- The Graph API returns paginated results for list endpoints; registry coverage must not degrade pagination handling.
- The Graph API evolves (resource moved/renamed/deprecated); contract drift check and tests should reveal mismatch quickly.
- A subresource path exists for a registered resource but is not represented in the registry; this must be treated as a governance gap.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature updates the contract registry for Microsoft Graph resources and adds regression tests to ensure completeness and to prevent ad-hoc expansions of Graph calls.

### Functional Requirements

- **FR-001**: The system MUST explicitly register the following Graph resources in the contract registry:
  - Configuration Policy Templates
  - Configuration Settings (settings catalog definitions)
  - Configuration Categories
  - RBAC Role Assignments
- **FR-002**: The system MUST represent the “setting templates” subresource under Configuration Policy Templates as part of the registered contract.
- **FR-003**: The system MUST ensure that Graph calls for the above resources are sourced from the contract registry (not embedded as freeform endpoint strings in call sites).
- **FR-003a**: The “no freeform path” enforcement scope MUST be limited to the four specified resources and the known call sites that access them.
- **FR-004**: The system MUST include regression tests that fail when any of the required resources are not registered.
- **FR-005**: The system MUST include regression tests that detect reintroduction of ad-hoc endpoint strings in the targeted call sites for these resources.
- **FR-005a**: The regression guard “targeted call sites” MUST include: ConfigurationPolicyTemplateResolver, SettingsCatalogDefinitionResolver, SettingsCatalogCategoryResolver, RbacOnboardingService, and RbacHealthService.
- **FR-006**: The implementation scope MUST remain limited to the four specified resources; any additional missing resources discovered during implementation MUST be handled via a follow-up spec.

### Registry Identifiers (internal)

To make the requirements testable and to avoid ambiguity, the contract registry MUST contain stable internal identifiers for these four resources (under the registry’s “types” section):

| Resource | Registry identifier |
|----------|---------------------|
| Configuration Policy Templates | `configurationPolicyTemplate` |
| Configuration Settings (settings catalog definitions) | `settingsCatalogDefinition` |
| Configuration Categories | `settingsCatalogCategory` |
| RBAC Role Assignments | `rbacRoleAssignment` |

Additionally, the Configuration Policy Template contract MUST include a named subresource for “setting templates” that is templated by the parent template identifier (for example: subresource key `settingTemplates`).

### Assumptions

- Existing authorization and tenant isolation rules already constrain whether any given tenant can access these resources; contract registration does not add or expand permissions.
- The contract drift check enumerates registered top-level resources; nested subresources are still registered for governance consistency and reuse.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: 100% of the specified Graph resources are discoverable from the contract registry.
- **SC-002**: Regression tests fail within 1 test run if any specified resource becomes unregistered.
- **SC-003**: Regression tests fail within 1 test run if targeted call sites reintroduce hardcoded endpoint substrings for the specified resources.
- **SC-004**: Maintainers can demonstrate drift-check coverage for these resources without manual inspection (e.g., via automated verification output or test evidence).
- **SC-004a**: Acceptance evidence MUST be satisfied by automated tests (Pest) without requiring a live tenant or manual drift-check output.