feat(schemas): v0.1.0 meta-schemas + CI validation (#123, #124)

.agents/context/schema-spec.md

@@ -124,8 +124,8 @@ Meta-schema encodes this via `allOf` with 4 `if/then` branches keyed on `type`.
 - **Per-type constraints:** `allOf` of `if/then` branches (better error messages than `oneOf` in ajv / python-jsonschema)
 - **Unknown keys:** `unevaluatedProperties: false` at every object level (not `additionalProperties: false` — the latter breaks composition with `allOf`)
 - **Extensions:** `patternProperties: { "^x-": {} }` at every object level
-- **Composition:** `$defs` + `$ref` internal; absolute-URL `$ref` across files
-- **Source of truth:** split YAML files in `schemas/v0.1.0/` (OpenAPI-style), bundled to a single JSON artifact on release (AsyncAPI-style). Bundling script in `scripts/`.
+- **Composition:** `$defs` + `$ref` internal; no cross-file `$ref` (revised from the original "split + bundle" plan after the format proved small enough that splitting cost more than it saved).
+- **Source of truth:** two single-file meta-schemas under `schemas/v0.1.0/` — `decree-schema.yaml` (validates `*.decree.schema.yaml`) and `decree-config.yaml` (validates `*.decree.config.yaml`). YAML is the human-edited source; JSON copies are generated by `scripts/yaml-to-json.py` and committed alongside for tooling consumers (schemastore.org, IDE language servers) that prefer JSON.
 
 ### Breaking vs additive (for future minor/patch bumps)
 
@@ -186,8 +186,8 @@ Meta-schema encodes this via `allOf` with 4 `if/then` branches keyed on `type`.
 
 ### Phase B — Meta-schema
 
-- #123 — Author split-file YAML meta-schema under `schemas/v0.1.0/` + bundling script
-- #124 — CI: `check-jsonschema` validates every checked-in schema YAML + known-invalid fixtures
+- #123 — Author meta-schemas under `schemas/v0.1.0/` (`decree-schema.yaml` + `decree-config.yaml`, single-file each, JSON copies generated)
+- #124 — CI: validate every checked-in schema YAML + known-invalid fixtures via `make validate-meta-schemas`
 
 ### Phase C — Publishing
 

.github/workflows/ci.yml

@@ -475,12 +475,42 @@ jobs:
           go-version-file: go.mod
           work-dir: .
 
+  # Validates every checked-in *.decree.schema.yaml and *.decree.config.yaml
+  # against the v0.1.0 meta-schemas, and asserts every fixture under
+  # schemas/v0.1.0/testdata/invalid/ FAILS validation. Closes #124.
+  #
+  # Runs unconditionally — no needs.changes gate — because the script also
+  # cross-checks the meta-schema sources themselves and is fast enough that
+  # path-filtering would add more complexity than it saves.
+  meta-schemas:
+    name: Meta-schemas check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    timeout-minutes: 5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install jsonschema
+        run: pip install --no-cache-dir 'jsonschema>=4.21' 'PyYAML>=6'
+
+      - name: Validate meta-schemas
+        run: make validate-meta-schemas
+
   # Aggregates all job results for branch protection. A single required check
   # that passes iff every listed job passed or was legitimately skipped.
   check:
     name: CI check
     if: always()
-    needs: [lint, test, sdk-compat, docs, e2e, examples, govulncheck, deps-review]
+    needs: [lint, test, sdk-compat, docs, e2e, examples, govulncheck, deps-review, meta-schemas]
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:

CONTRIBUTING.md

@@ -50,6 +50,7 @@ modify specs → generate code → test → lint → build → deploy → e2e te
 | `make docs` | Generate all documentation (API + CLI + man pages) | Mixed |
 | `make image` | Build the Docker image | Docker |
 | `make migrate` | Run database migrations | Docker |
+| `make validate-meta-schemas` | Validate canonical `*.decree.schema.yaml` and `*.decree.config.yaml` files against the v0.1.0 meta-schemas under `schemas/v0.1.0/` (requires `pip install jsonschema PyYAML`) | Local |
 | `make bench` | Run unit benchmarks | Local |
 | `make bench-e2e` | Run e2e benchmarks against docker stack | Docker |
 | `make clean` | Remove build artifacts and generated code | Mixed |

Makefile

@@ -24,7 +24,7 @@ CLI_LDFLAGS := -X main.cliVersion=$(GIT_VERSION) -X main.cliCommit=$(GIT_COMMIT)
 # Module list for multi-module operations.
 SDK_MODULES := sdk/configclient sdk/adminclient sdk/configwatcher sdk/tools
 
-.PHONY: all generate generate-proto generate-sqlc test lint build image migrate e2e examples bench bench-e2e docs docs-api docs-cli docs-man docs-serve docs-deploy pre-commit clean tools help demo-gif
+.PHONY: all generate generate-proto generate-sqlc test lint build image migrate e2e examples bench bench-e2e docs docs-api docs-cli docs-man docs-serve docs-deploy pre-commit clean tools help demo-gif validate-meta-schemas
 
 all: generate lint test build
 
@@ -81,6 +81,10 @@ test:
 	go test ./... -race -count=1
 	@for mod in $(SDK_MODULES) cmd/decree; do (cd $$mod && go test ./... -race -count=1) || exit 1; done
 
+## validate-meta-schemas: Validate canonical schema/config YAMLs against the v0.1.0 meta-schemas
+validate-meta-schemas:
+	python3 scripts/validate-meta-schemas.py
+
 ## pre-commit: Run all before-commit checks (build, vet, format, lint, test, coverage)
 pre-commit:
 	@echo "=== Build ==="

docs/concepts/schemas-and-fields.md

@@ -26,7 +26,7 @@ Published versions are immutable — you cannot change their fields. To evolve a
 Schemas are defined in YAML for import/export. The format uses syntax version `v1`:
 
 ```yaml
-# yaml-language-server: $schema=../../schemas/schema-yaml.json
+# yaml-language-server: $schema=../../schemas/v0.1.0/decree-schema.json
 spec_version: "v1"
 name: payments
 description: Payment processing configuration
@@ -101,7 +101,7 @@ fields:
       url: https://docs.example.com/webhooks
 ```
 
-A [JSON Schema](../../schemas/schema-yaml.json) is available for editor validation and autocomplete.
+JSON Schemas for editor validation and autocomplete are available under [`schemas/v0.1.0/`](../../schemas/v0.1.0/) — `decree-schema.json` validates the schema-definition format documented here, and `decree-config.json` validates the tenant-side config format.
 
 ### Required fields