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 Input: Feature specification from specs/095-graph-contracts-registry-completeness/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)

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

Source Code (repository root)

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 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 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 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.