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

# Implementation Plan: Graph Contracts Registry Completeness

**Branch**: `095-graph-contracts-registry-completeness` | **Date**: 2026-02-15 | **Spec**: [specs/095-graph-contracts-registry-completeness/spec.md](spec.md)
**Input**: Feature specification from [specs/095-graph-contracts-registry-completeness/spec.md](spec.md)

## Summary

This change closes governance gaps in the Microsoft Graph contract registry by explicitly registering four Graph resources already used by the product (templates, settings catalog definitions, categories, role assignments), refactoring a small set of known call sites to use registry-backed paths, and adding regression tests to prevent future “untracked” Graph usage.

Clarified constraints:
- Enforce registry-backed paths only for these four resources and the five known call sites.
- Acceptance evidence is automated Pest tests only (no live tenant required).
- Do not expand scope if additional missing resources are discovered.

## Technical Context

**Language/Version**: PHP 8.4.x  
**Primary Dependencies**: Laravel 12, Filament v5, Livewire v4, Microsoft Graph integration via `GraphClientInterface`  
**Storage**: PostgreSQL (via Laravel Sail)  
**Testing**: Pest v4 (Laravel test runner via Sail)  
**Target Platform**: Docker (Laravel Sail) for local dev; container-based deploy (Dokploy)  
**Project Type**: Web application (Laravel)  
**Performance Goals**: N/A (no runtime hot path changes intended)  
**Constraints**:
- No new dependencies.
- No new UI/routes.
- Do not require a live tenant for acceptance.
- Keep change bounded to the four resources + five known call sites.
**Scale/Scope**: Small refactor + config change + targeted regression tests.

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Inventory-first: PASS (no inventory/snapshot changes).
- Read/write separation: PASS (no new write workflows).
- Single contract path to Graph: PASS (this feature strengthens the contract registry and prevents ad-hoc endpoints).
- Deterministic capabilities: N/A (no capability derivation changes).
- RBAC-UX: PASS (no authorization model or UI surfaces changed).
- Workspace/tenant isolation: PASS (no new cross-tenant reads/writes; registry changes do not imply access).
- Run observability: PASS (no new long-running operations; tests-only acceptance).
- Data minimization & safe logging: PASS (no new payload logging).
- Badge semantics (BADGE-001): N/A (no badges).
- Filament UI Action Surface Contract: N/A (no Filament resources/pages modified).

## Project Structure

### Documentation (this feature)

```text
specs/095-graph-contracts-registry-completeness/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
└── checklists/
```

### Source Code (repository root)

```text
app/
├── Services/
│   ├── Graph/
│   └── Intune/
config/
├── graph_contracts.php
tests/
└── Feature/
```

**Structure Decision**: Laravel monolith. Changes are limited to `config/graph_contracts.php`, small helpers under `app/Services/Graph`, a handful of service call sites under `app/Services/Intune`, and a new targeted Pest test.

## Phase 0 — Outline & Research

### Unknowns / Items to Validate

None required to proceed; the spec is bounded and based on known call sites.

### Research Outputs

- Create [specs/095-graph-contracts-registry-completeness/research.md](research.md) documenting:
  - Contract registry patterns used in this repo.
  - Drift-check enumeration behavior (top-level resources).
  - Test strategy for preventing endpoint string regressions.

## Phase 1 — Design & Contracts

### Data Model

- No new database entities.
- Create [specs/095-graph-contracts-registry-completeness/data-model.md](data-model.md) documenting “no new entities” explicitly.

### Contracts

- Create minimal external API contract documentation under `contracts/` describing the four affected Microsoft Graph endpoints.
- Output: `contracts/graph-deviceManagement-contracts.yaml`.

### Quickstart

- Create [specs/095-graph-contracts-registry-completeness/quickstart.md](quickstart.md) showing how to run the focused tests via Sail.

### Agent Context Update

- Run `.specify/scripts/bash/update-agent-context.sh copilot`.

### Constitution Re-check (post design)

- Expected: still PASS (no UI, no RBAC, no long-running ops).

## Phase 2 — Implementation Plan (no code yet)

1. Add/verify contract registry entries for the four resources in `config/graph_contracts.php`.
2. Ensure contract registry supports a subresource template for “Configuration Policy Template → setting templates”.
3. Refactor the five in-scope call sites to resolve Graph paths via the registry (no hardcoded endpoint substrings for these resources).
4. Add regression tests:
   - Registry completeness for the four resources + required subresource template.
   - String-guard checks for the five in-scope files to prevent reintroducing hardcoded endpoints.
5. Run formatting: `vendor/bin/sail bin pint --dirty`.
6. Run focused tests via Sail (acceptance evidence): `vendor/bin/sail artisan test --compact` with the new/updated test file(s).

## Complexity Tracking

No constitution violations expected; no complexity exemptions required.