# Quickstart: Canonical Control Catalog Foundation

## Goal

Implement the first canonical control core without introducing framework overlays, operator CRUD, or new provider runtime machinery.

## Implementation Sequence

1. Add the product-seeded canonical control registry and the supporting value objects.
2. Add provider-owned Microsoft subject and signal bindings.
3. Implement the shared resolution contract with explicit `resolved`, `unresolved`, and `ambiguous` outcomes.
4. Wire a bounded first-slice set of governance consumers to the shared contract.
5. Add focused unit and feature coverage proving convergence and ambiguity handling.

## Suggested Code Areas

```text
apps/platform/app/Support/Governance/Controls/
apps/platform/config/
apps/platform/app/Services/Evidence/
apps/platform/app/Services/TenantReviews/
apps/platform/tests/Unit/Governance/
apps/platform/tests/Feature/Governance/
apps/platform/tests/Feature/Evidence/
apps/platform/tests/Feature/TenantReview/
```

## Verification Commands

Run the narrowest proving lane first:

```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Governance/CanonicalControlCatalogTest.php tests/Unit/Governance/CanonicalControlResolverTest.php
```

Then run the bounded integration proof:

```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Governance/CanonicalControlResolutionIntegrationTest.php tests/Feature/Evidence/EvidenceSnapshotCanonicalControlReferenceTest.php tests/Feature/TenantReview/TenantReviewCanonicalControlReferenceTest.php
```

If PHP files were added or changed, finish with formatting:

```bash
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
```

## Review Focus

- Confirm the control catalog remains provider-neutral at its core.
- Confirm Microsoft bindings are secondary metadata only.
- Confirm first-slice evidence and tenant review consumers do not invent feature-local control-family wording.
- Confirm ambiguity is explicit and never guessed.
- Confirm no Graph path or provider sync job slipped into the slice.
- Confirm no broad persistence or authoring UI slipped into the first slice.

## Guardrail Close-Out

- Validation completed:
  - `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`
  - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- Guardrails checked:
  - No Graph client change.
  - No `config/graph_contracts.php` change.
  - No provider sync job.
  - No feature-local control-family fallback or workload-first primary control vocabulary in the touched evidence and tenant review adoption paths.
- Bounded follow-up: none for this slice.