From bd2d99adc95dcfaf22e032be39fbf5b3bb759a9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kim=20Harjam=C3=A4ki?= Date: Wed, 8 Jul 2026 15:13:38 +0300 Subject: [PATCH 1/2] docs(36-02): fix registry $id framing and append freshness footer - Clarify Pages registry is authoritative now; schemas.coding-autopilot.dev migration is in progress (PR #18), not settled fact - Append docs-verified freshness footer --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 49acead..b910756 100644 --- a/README.md +++ b/README.md @@ -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 + + From 3ae0a88d490ba3e4665eeaf0638d5cd153b12ff5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kim=20Harjam=C3=A4ki?= Date: Wed, 8 Jul 2026 15:22:27 +0300 Subject: [PATCH 2/2] docs(36-03): add docs/wiki tree (Home, Architecture, Operations, Decisions) - Architecture.md documents the schema-versioning + Pages registry publishing pipeline, and the in-progress $id migration (PR #18) - Operations.md verified test/validate/build-registry/CI commands - Decisions.md indexes phase history and open PRs --- docs/wiki/Architecture.md | 53 +++++++++++++++++++++++++++++++++++++++ docs/wiki/Decisions.md | 29 +++++++++++++++++++++ docs/wiki/Home.md | 33 ++++++++++++++++++++++++ docs/wiki/Operations.md | 39 ++++++++++++++++++++++++++++ 4 files changed, 154 insertions(+) create mode 100644 docs/wiki/Architecture.md create mode 100644 docs/wiki/Decisions.md create mode 100644 docs/wiki/Home.md create mode 100644 docs/wiki/Operations.md diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md new file mode 100644 index 0000000..ea95877 --- /dev/null +++ b/docs/wiki/Architecture.md @@ -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/*"] +``` + + + +## 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`. + + diff --git a/docs/wiki/Decisions.md b/docs/wiki/Decisions.md new file mode 100644 index 0000000..7ab5ea8 --- /dev/null +++ b/docs/wiki/Decisions.md @@ -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. + + diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..7ffab88 --- /dev/null +++ b/docs/wiki/Home.md @@ -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) + + diff --git a/docs/wiki/Operations.md b/docs/wiki/Operations.md new file mode 100644 index 0000000..cc1d1c1 --- /dev/null +++ b/docs/wiki/Operations.md @@ -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). + +