ci: require Gemara CUE schema validation for touched catalog YAMLs

[eddie-knight]

Summary

Adds a new CI job — Gemara Schema Check — that compiles and validates every catalog YAML touched in a PR against the Gemara CUE schema (gemaraproj/gemara@v1.2.0). Fails the PR on any compile error or schema violation.

Per-file scope: only the build targets whose YAMLs were touched get re-validated, not the whole repo. Changes to shared/core files (catalogs/categories.yaml, catalogs/core/ccc/**) cascade to every build target because every catalog depends on them.

How it works

1. git diff base...head finds catalog YAMLs touched in the PR.
2. Maps each changed file to its build target (catalogs/<category>/<service>/...).
3. For each affected (target, asset):
   • Runs delivery-toolkit compile to produce a self-describing Gemara artifact.
   • Runs cue vet -d "#<ArtifactType>" gemara-spec <compiled> against the CUE schema.

CUE is the validator because:

• grcli ships from a private repo and can't be used from public CI.
• cuelang.org/go/cmd/cue is the upstream tool the Gemara CUE module was authored for.
• The validation is exactly what grcli validate does internally — cue vet against #<Type>.

Pinned versions:

• Gemara spec: v1.2.0 (matches gemaraSpecVersion in delivery-toolkit/cmd/compile.go:51).
• cue: v0.16.0.

Why per-file, not full-repo

A full-repo run on every PR would be wasteful (~25 targets × 3 assets × seconds each). Per-file scoping makes the check fast and incentivises the team to fix what they touch without forcing a global fix-up to merge unrelated PRs.

Verification

Locally dry-ran the workflow's shell logic against:

• catalogs/storage/object/* — compile + cue vet clean ✅
• catalogs/ai-ml/multi-agent-refarch/* — fails compile (missing metadata.yaml + undefined groups) ❌ (correctly surfaces as a CI failure)
• Heredoc target-loop iteration confirmed processes every line.

Confirmed cue vet catches real schema breaks: wrong metadata.type value, duplicate control ids, missing gemara-version.

Known surfaces this will now block

PRs that touch any of the 13 imports-only or otherwise broken catalog YAMLs will fail this check until the underlying tech debt is addressed:

• 7 existing imports-only sources (e.g. catalogs/compute/virtual-machines/controls.yaml, catalogs/crypto/secrets/threats.yaml)
• catalogs/compute/batchproc/controls.yaml using the wrong imports: key
• catalogs/ai-ml/multi-agent-refarch/ (missing metadata, undefined groups)
• The three targets with missing controls.yaml/threats.yaml (management/tracing, orchestration/etl, orchestration/k8s) — touching their metadata.yaml or capabilities.yaml would now flag any other touched compile failure as well.

That's the intended behaviour: this check is what was missing when those got merged.

Test plan

• PR CI runs and the gemara-schema-checker job appears and passes (this PR touches no catalog YAMLs, so it should no-op).
• A follow-up PR touching catalogs/categories.yaml should trigger the broad-cascade path and validate all 24 catalogs.
• A follow-up PR touching a single catalog YAML should validate only that target.
• Make this check a required status check in branch protection settings (maintainer action — not in this PR).

🤖 Generated with Claude Code

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: eddie-knight / name: Eddie Knight (385c89a)

[netlify]

❌ Deploy Preview for common-cloud-controls failed. Why did it fail? →

Name	Link
🔨 Latest commit	c96b8d3
🔍 Latest deploy log	https://app.netlify.com/projects/common-cloud-controls/deploys/6a2877cfda6f280008d59350

[netlify]

👷 Deploy request for common-cloud-controls pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	1c6b485

[eddie-knight]

CI Checks are failing because every PR currently attempts to build the website, and the site is currently under construction.

[jpower432]

Mostly nits, but requesting changes on the third party actions references.

[jpower432]

CUE has a setup-cue third party action you could use - https://github.com/cue-lang/setup-cue

[jpower432]

Nit: why not just point directly to the module in the CUE registry when running cue vet?

[eddie-knight]

because claude and I didn't know how to do that at the time we were working on this :D