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

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

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:

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:

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:

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.