Coding-Autopilot-System · OgeonX-Ai · Jul 8, 2026 · Jul 8, 2026 · Jul 8, 2026 · chatgpt-codex-connector
@@ -60,7 +60,7 @@ Producers should emit records that validate against the declared version. Consum
 The schemas are public APIs. Review [versioning and compatibility](docs/VERSIONING.md), [contributing](CONTRIBUTING.md), and [security](SECURITY.md) before proposing changes.
 
 Released schemas are discoverable from `https://coding-autopilot-system.github.io/cas-contracts/registry/index.json`. Use stable `registry/vMAJOR.MINOR` URLs for compatible updates or immutable `registry/releases/vMAJOR.MINOR.PATCH` URLs for reproducible builds. See [schema distribution](docs/DISTRIBUTION.md).
-Authoritative schema identity remains under `https://schemas.coding-autopilot.dev/`; the GitHub Pages registry is the current live distribution endpoint.
+The GitHub Pages registry above is the authoritative, resolvable distribution endpoint today. The 22 schema `$id` values currently in `schemas/` still point at `https://schemas.coding-autopilot.dev/`, a domain that is not presently resolvable; migrating those `$id` values to the resolvable Pages registry URL is in progress (PR #18, `fix(registry): rewrite schema $id to the resolvable Pages registry URL`). Until that PR merges, treat the Pages registry index — not the `schemas.coding-autopilot.dev` `$id` values — as the source of truth for schema identity.
 
 The v1 `WorkRequest` rejects dispatch unless objective, repositories,
 measurable criteria, constraints, risk, approval and verification policies,
@@ -75,3 +75,5 @@ seconds, model calls 20, and no-progress limit 2.
 ## License
 
 MIT
+
+<!-- docs-verified: 991c3606b148ab42134e505f4cf110afb8cb8e6b 2026-07-08 -->
@@ -0,0 +1,53 @@
+# Architecture
+
+## Schema versioning + Pages registry publishing pipeline
+
+```mermaid
+flowchart TD
+    Dev["Schema author\n(schemas/vMAJOR.MINOR/*.schema.json)"] -->|"npm test"| Validate["Draft 2020-12 compile\n+ example validation\n+ lifecycle correlation"]
+    Validate --> Tag["git tag vMAJOR.MINOR.PATCH"]
+    Tag --> Push["push to main / tag push"]
+    Push --> Pages["pages.yml (sole Pages owner)"]
+    subgraph Pages["Deploy Pages workflow"]
+        Docs["mkdocs build\n(documentation site)"]
+        Registry["build-registry.mjs per tag\n-> registry/vMAJOR.MINOR\n-> registry/releases/vMAJOR.MINOR.PATCH"]
+        ValidateReg["validate:registry"]
+        Merge["cp registry/ into site/registry/\n(single artifact, no CNAME clash)"]
+    end
+    Docs --> Merge
+    Registry --> ValidateReg --> Merge
+    Merge --> Deploy["actions/deploy-pages\ncoding-autopilot-system.github.io/cas-contracts/registry/"]
+    Deploy --> Consumers["Consumers (gsd-orchestrator, autogen, cas-evals)\nfetch registry/index.json, vMAJOR.MINOR/*, releases/*"]
+```
+
+<!-- codex:generate-image prompt="A printing-press pipeline: a schema document enters a validation gate, gets stamped with a version tag, then travels down a single conveyor belt that merges with a documentation-site stream before both are printed onto one large publication board reading REGISTRY; several small robot consumers below reach up and pull dated copies off the board; isometric, enterprise blue/graphite palette" style="isometric, enterprise, clean" replaces="mermaid-above" -->
+
+## Publishing pipeline detail
+
+`.github/workflows/pages.yml` is the **sole owner** of the GitHub Pages deployment — it builds
+the mkdocs documentation site and the schema registry into one artifact so a docs push and a
+schema release tag can never clobber each other on the single Pages origin. It runs on pushes
+to `main`/`master` and on `v[0-9]+.[0-9]+.[0-9]+` tags. For each existing release tag it
+archives `schemas/vMAJOR.MINOR/` at that tag, runs `scripts/build-registry.mjs` to produce
+`registry/vMAJOR.MINOR` (stable, receives compatible patches) and
+`registry/releases/vMAJOR.MINOR.PATCH` (immutable) trees, validates the assembled registry,
+strips any `CNAME` (the registry is a Pages sub-path, not its own origin), and deploys via
+`actions/deploy-pages`.
+
+## Schema identity vs. distribution — currently in transition
+
+`docs/DISTRIBUTION.md` already states the accurate contract: schema `$id` values reserve the
+canonical namespace `https://schemas.coding-autopilot.dev/`, but that domain is not currently
+resolvable, so **the GitHub Pages registry is the authoritative, resolvable distribution
+endpoint today**. PR #18 (`fix(registry): rewrite schema $id to the resolvable Pages registry
+URL`) is rewriting all 22 schemas' `$id` values to match this reality directly; it is open and
+not yet merged — see [Decisions](./Decisions.md).
+
+## Lifecycle contract
+
+Every record carries `correlationId`, `promptId`, `runId`, structured `actor`, RFC 3339
+`timestamp`, explicit `schemaVersion`, and W3C `traceparent`/`tracestate`, so an
+`EvaluationResult` can be traced back through `VerificationResult`, `ArtifactManifest`, and
+`RunEvent[]` to the originating `PromptEnvelope`.
+
+<!-- docs-verified: 991c3606b148ab42134e505f4cf110afb8cb8e6b 2026-07-08 -->
@@ -0,0 +1,29 @@
+# Decisions
+
+## ADR convention
+
+`docs/adr/README.md` establishes the convention (sequential numbering, Context/Decision/
+Consequences) but **no numbered ADR files exist in the repo yet**. Decisions to date live in
+`.planning/phases/` plan/summary pairs and `docs/VERSIONING.md` / `docs/DISTRIBUTION.md`
+instead.
+
+## Phase history (`.planning/phases/`, this repo's own GSD project)
+
+| Phase | Topic |
+|---|---|
+| 02 | Compatibility automation and distribution |
+
+See `.planning/phases/02-compatibility-automation-and-distribution/02-01-SUMMARY.md` and
+`02-02-SUMMARY.md` for the detailed record, and `.planning/research/SUMMARY.md` for the
+research that preceded it.
+
+## Open decisions tracked in this Phase 36 refresh
+
+- **PR #18** (`fix/registry-resolvable-id`) — rewrites all 22 schema `$id` values from the
+  unresolvable `schemas.coding-autopilot.dev` domain to the resolvable Pages registry URL;
+  open, not yet merged. This is the highest-risk documentation item in this refresh — see
+  [Architecture](./Architecture.md#schema-identity-vs-distribution--currently-in-transition).
+- **PR #19** (`ci/sha-pin-and-least-privilege`) — pins third-party GitHub Actions to commit
+  SHAs and adds least-privilege permissions; open, not yet merged.
+
+<!-- docs-verified: 991c3606b148ab42134e505f4cf110afb8cb8e6b 2026-07-08 -->
@@ -0,0 +1,33 @@
+# CAS Contracts Wiki
+
+## Role in the CAS portfolio
+
+`cas-contracts` is part of the **Governance plane** of the Coding-Autopilot-System
+three-plane model (Control / Execution / Governance). It publishes the public, versioned,
+implementation-neutral JSON schemas (`PromptEnvelope` → `PolicyDecision` → `WorkRequest` →
+`RunEvent[]` → `ArtifactManifest` → `VerificationResult` → `EvaluationResult`) that every
+other CAS component validates against at its trust boundaries.
+
+| Plane | This repo's responsibility |
+|---|---|
+| Control | *(consumed by)* `gsd-orchestrator` |
+| Execution | *(consumed by)* `autogen` |
+| Governance | Schema authority, versioning policy, registry publishing |
+
+## Quickstart
+
+- [README.md](../../README.md) — Quickstart, repository layout, adoption
+- [Architecture](./Architecture.md) — schema versioning + Pages registry publishing pipeline
+- [Operations](./Operations.md) — verified test/validate/build-registry commands
+- [Decisions](./Decisions.md) — phase history, ADR convention, and open PRs (including the
+  registry `$id` migration, PR #18)
+
+## Ecosystem links
+
+Part of the [Coding-Autopilot-System](https://github.com/Coding-Autopilot-System) org:
+[gsd-orchestrator](https://github.com/Coding-Autopilot-System/gsd-orchestrator) (control plane) ·
+[autogen](https://github.com/Coding-Autopilot-System/autogen) (execution plane) ·
+[Promptimprover](https://github.com/Coding-Autopilot-System/Promptimprover) (prompt governance) ·
+[cas-evals](https://github.com/Coding-Autopilot-System/cas-evals) (evidence gate)
+
+<!-- docs-verified: 991c3606b148ab42134e505f4cf110afb8cb8e6b 2026-07-08 -->
@@ -0,0 +1,39 @@
+# Operations
+
+## Setup and test
+
+```powershell
+npm ci
+npm test
+npm run validate
+```
+
+`npm test` compiles every Draft 2020-12 schema, validates all examples, verifies lifecycle
+correlation, and proves malformed metadata is rejected.
+
+## Local registry build
+
+```powershell
+npm run build:registry -- --version 0.1.0
+npm run validate:registry -- --registry registry
+```
+
+Writes `registry/`, validates the version, preserves relative schema references, and produces
+deterministic manifests.
+
+## CI (`.github/workflows/ci.yml`, `.github/workflows/compatibility.yml`, `.github/workflows/codeql.yml`)
+
+- `ci.yml` — install, `npm test`, `npm run validate` on pushes and PRs.
+- `compatibility.yml` — cross-version compatibility checks for released schema lines.
+- `codeql.yml` — CodeQL analysis (badge in the root `README.md`).
+
+## Publishing (`.github/workflows/pages.yml`)
+
+Runs automatically on push to `main`/`master` and on `v[0-9]+.[0-9]+.[0-9]+` tags. Builds the
+mkdocs documentation site and rebuilds every tagged schema release into `site/registry/` in
+one artifact, then deploys via `actions/deploy-pages` using GitHub's OIDC token (no stored
+deployment credentials). See [Architecture](./Architecture.md) for the full pipeline and
+`docs/DISTRIBUTION.md` for the release-ordering caveat (create a post-release metadata commit
+so the Pages deployment runs from a fresh SHA that picks up the new tag).
+
+<!-- docs-verified: 991c3606b148ab42134e505f4cf110afb8cb8e6b 2026-07-08 -->