Merge pull request #2 from Coding-Autopilot-System/gsd/phase-2-compatibility-distribution

feat: automate compatibility and schema distribution

Author: OgeonX-Ai

.github/workflows/compatibility.yml

@@ -0,0 +1,64 @@
+name: Compatibility
+
+on:
+  pull_request:
+    paths:
+      - "schemas/**"
+      - "scripts/compatibility.mjs"
+      - "scripts/lib.mjs"
+      - "tests/compatibility.test.mjs"
+      - ".github/workflows/compatibility.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  classify:
+    name: Classify schema compatibility
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out proposed contracts
+        uses: actions/checkout@v4
+        with:
+          path: candidate
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: candidate/package-lock.json
+      - run: npm ci
+        working-directory: candidate
+      - name: Extract latest released contracts
+        shell: bash
+        working-directory: candidate
+        run: |
+          set -euo pipefail
+          latest="$(git tag --list "v[0-9]*.[0-9]*.[0-9]*" --sort=-version:refname | head -n 1)"
+          test -n "$latest"
+          mkdir -p ../baseline
+          git archive "$latest" schemas | tar -x -C ../baseline
+      - name: Classify changes
+        id: classify
+        shell: bash
+        run: |
+          set +e
+          node candidate/scripts/compatibility.mjs \
+            --base baseline/schemas \
+            --head candidate/schemas \
+            --output candidate/compatibility-report.json
+          code=$?
+          {
+            echo "## Compatibility against latest release"
+            echo '```json'
+            cat candidate/compatibility-report.json
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+          exit "$code"
+      - name: Upload compatibility report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: compatibility-report
+          path: candidate/compatibility-report.json

.github/workflows/publish-registry.yml

@@ -0,0 +1,66 @@
+name: Publish schema registry
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build registry
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm test
+      - name: Build every released schema version
+        shell: bash
+        run: |
+          set -euo pipefail
+          rm -rf registry release-source
+          while IFS= read -r tag; do
+            version="${tag#v}"
+            line="v${version%.*}"
+            mkdir -p "release-source/$version"
+            git archive "$tag" "schemas/$line" | tar -x -C "release-source/$version"
+            node scripts/build-registry.mjs \
+              --version "$version" \
+              --source "release-source/$version/schemas/$line" \
+              --output registry \
+              --append
+          done < <(git tag --list "v[0-9]*.[0-9]*.[0-9]*" --sort=version:refname)
+      - run: npm run validate:registry -- --registry registry
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: registry
+
+  deploy:
+    name: Deploy registry
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,4 +1,7 @@
 node_modules/
 coverage/
+registry/
+release-source/
+.tmp/
 *.log
 .DS_Store

.planning/PROJECT.md

@@ -13,6 +13,7 @@ Every CAS component can exchange trustworthy lifecycle data without guessing str
 ### Validated
 
 - v0.1 lifecycle schemas, examples, tests, CI, and governance - Phase 1
+- Automated compatibility classification and stable versioned schema distribution - Phase 2
 
 ### Active
 
@@ -48,6 +49,8 @@ CAS currently has multiple repositories that need a shared language for prompts,
 | Use one common lifecycle metadata definition | Prevent traceability drift across contracts | Pending |
 | Keep contracts implementation-neutral | Allow all CAS runtimes to adopt them | Pending |
 | Publish examples as executable fixtures | Documentation and validation stay synchronized | Pending |
+| Fail unknown schema semantics as review-required | Prevent false compatibility claims | Implemented in Phase 2 |
+| Rebuild all release tags for registry publication | Preserve immutable release URLs while stable lines advance | Implemented in Phase 2 |
 
 ## Evolution
 
@@ -58,4 +61,4 @@ This document evolves at phase transitions and milestone boundaries.
 3. Reconfirm that contract interoperability remains the core value.
 
 ---
-*Last updated: 2026-06-11 after Phase 1 verification*
+*Last updated: 2026-06-11 after Phase 2 verification*

.planning/REQUIREMENTS.md

@@ -26,8 +26,8 @@
 ## vNext Requirements
 
 - **SDK-01**: Consumers can install generated typed SDKs for supported languages.
-- **REG-01**: Consumers can resolve published schemas from a stable registry endpoint.
-- **COMP-01**: CI automatically compares proposed schemas against the latest release for compatibility.
+- [x] **REG-01**: Consumers can resolve published schemas from a stable registry endpoint.
+- [x] **COMP-01**: CI automatically compares proposed schemas against the latest release for compatibility.
 
 ## Out of Scope
 
@@ -50,8 +50,10 @@
 | GOV-01 | Phase 1 | Complete |
 | GOV-02 | Phase 1 | Complete |
 | GOV-03 | Phase 1 | Complete |
+| COMP-01 | Phase 2 | Complete |
+| REG-01 | Phase 2 | Complete |
 
-**Coverage:** 9 v0.1 requirements, 9 mapped, 0 unmapped.
+**Coverage:** 12 requirements, 12 mapped, 0 unmapped.
 
 ---
-*Last updated: 2026-06-11 after Phase 1 verification*
+*Last updated: 2026-06-11 after Phase 2 verification*

.planning/ROADMAP.md

@@ -18,6 +18,16 @@
 
 **Requirements:** COMP-01, REG-01
 
+**Status:** Complete (2026-06-11)
+
+**Plans:** 2/2 plans complete
+
+**Wave 1**
+- [x] 02-01: Automated compatibility classification and PR enforcement
+
+**Wave 2** *(blocked on Wave 1 completion)*
+- [x] 02-02: Deterministic versioned registry and release distribution
+
 **Success criteria:**
 1. Pull requests receive automated breaking-change classification.
 2. Released schemas are resolvable from stable versioned URLs.

.planning/STATE.md

@@ -1,21 +1,38 @@
+---
+gsd_state_version: 1.0
+milestone: v0.1
+milestone_name: Foundation
+status: ready_to_plan
+last_updated: 2026-06-11T11:07:16.086Z
+progress:
+  total_phases: 3
+  completed_phases: 2
+  total_plans: 2
+  completed_plans: 2
+  percent: 67
+stopped_at: Phase 2 complete (2/2) - ready to discuss Phase 3
+---
+
 # Project State
 
 ## Project Reference
 
 See: `.planning/PROJECT.md` (updated 2026-06-11)
 
-**Core value:** Every CAS component can exchange trustworthy lifecycle data without guessing structure, identity, traceability, or compatibility.  
-**Current focus:** Phase 2 - Compatibility Automation and Distribution
+**Core value:** Every CAS component can exchange trustworthy lifecycle data without guessing structure, identity, traceability, or compatibility.
+**Current focus:** Phase 3 - Typed SDKs and Adoption
 
 ## Status
 
-- Phase: 1 of 3 complete; Phase 2 pending
+- Phase: 2 of 3 complete; Phase 3 pending
 - Milestone: v0.1
 - Mode: YOLO, quality, parallel
-- Next action: Integrate v0.1 contracts into CAS producers and consumers, then automate compatibility checks.
+- Next action: Plan Phase 3 typed SDKs and adoption.
 
 ## Decisions
 
 - JSON Schema Draft 2020-12 is authoritative.
 - Shared lifecycle metadata is mandatory.
 - Examples are executable fixtures.
+- Unknown schema semantic changes require review rather than a compatibility claim.
+- Registry publication preserves immutable releases and advances stable version lines.

.planning/config.json

@@ -10,6 +10,6 @@
     "verifier": true,
     "nyquist_validation": true,
     "auto_advance": true,
-    "_auto_chain_active": true
+    "_auto_chain_active": false
   }
 }

.planning/phases/02-compatibility-automation-and-distribution/02-01-PLAN.md

@@ -0,0 +1,54 @@
+---
+phase: 02-compatibility-automation-and-distribution
+plan: "01"
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - package.json
+  - scripts/compatibility.mjs
+  - scripts/lib.mjs
+  - tests/compatibility.test.mjs
+  - tests/fixtures/compatibility/
+  - .github/workflows/compatibility.yml
+  - docs/VERSIONING.md
+  - CONTRIBUTING.md
+autonomous: true
+requirements: [COMP-01]
+must_haves:
+  truths:
+    - Pull requests automatically classify schema changes against their merge base.
+    - Breaking and review-required changes cannot be silently reported as compatible.
+    - Compatibility results are available as machine-readable JSON and a CI summary.
+---
+
+<objective>
+Implement conservative automated JSON Schema breaking-change classification and enforce it in pull-request CI.
+</objective>
+
+<tasks>
+<task type="auto">
+  <name>Implement classifier and CLI</name>
+  <read_first>scripts/lib.mjs, docs/VERSIONING.md, schemas/v0.1/common.schema.json</read_first>
+  <action>Add a dependency-free directional schema-tree comparator. Report unchanged, compatible, breaking, and review_required outcomes with JSON details. Exit nonzero for breaking changes and support explicit base/head directories.</action>
+  <acceptance_criteria>`node scripts/compatibility.mjs --help` exits successfully and documents CLI inputs and exit behavior.</acceptance_criteria>
+</task>
+<task type="auto">
+  <name>Add compatibility fixtures and tests</name>
+  <read_first>tests/contracts.test.mjs, scripts/compatibility.mjs</read_first>
+  <action>Add tests for additions, removals, required properties, type and enum narrowing, extensibility tightening, constraints, schema removal, and unknown changed keywords.</action>
+  <acceptance_criteria>`npm.cmd test` passes and exercises all four classifications.</acceptance_criteria>
+</task>
+<task type="auto">
+  <name>Integrate PR compatibility CI and governance docs</name>
+  <read_first>.github/workflows/ci.yml, CONTRIBUTING.md, docs/VERSIONING.md</read_first>
+  <action>Add a least-privilege pull-request workflow that compares against the merge base, writes a job summary, uploads the JSON report, and fails on breaking changes. Document local classification and review-required semantics.</action>
+  <acceptance_criteria>Workflow uses full-history checkout, runs the classifier, uploads its report, and has read-only contents permission.</acceptance_criteria>
+</task>
+</tasks>
+
+<verification>
+- `npm.cmd test`
+- `npm.cmd run validate`
+- Run the CLI against identical schema trees and a known breaking fixture.
+</verification>

.planning/phases/02-compatibility-automation-and-distribution/02-01-SUMMARY.md

@@ -0,0 +1,49 @@
+---
+phase: 02-compatibility-automation-and-distribution
+plan: "01"
+subsystem: compatibility
+tags: [json-schema, ci, semver]
+requires: [01-useful-v0.1-foundation]
+provides: [compatibility-classifier, compatibility-pr-check]
+affects: [distribution, governance]
+tech-stack:
+  added: []
+  patterns: [conservative-directional-classification, machine-readable-ci-report]
+key-files:
+  created:
+    - scripts/compatibility.mjs
+    - tests/compatibility.test.mjs
+    - .github/workflows/compatibility.yml
+  modified:
+    - scripts/lib.mjs
+    - docs/VERSIONING.md
+    - CONTRIBUTING.md
+key-decisions:
+  - Unknown semantic keyword changes are review_required and fail CI rather than being falsely classified compatible.
+requirements-completed: [COMP-01]
+completed: 2026-06-11
+---
+
+# Phase 2 Plan 1: Compatibility Automation Summary
+
+Implemented a dependency-free directional JSON Schema classifier with pull-request enforcement and machine-readable reports.
+
+## Results
+
+- Classifies unchanged, compatible, breaking, and review-required schema tree changes.
+- Detects property, required-field, type, enum, constraint, extensibility, definition, and schema-file compatibility changes.
+- Compares pull requests with the latest semantic release and fails CI for breaking and review-required changes.
+- Documents local use and governance semantics.
+
+## Verification
+
+- `npm.cmd test`: 8/8 passed
+- `npm.cmd run validate`: 7 lifecycle examples validated
+- Identical live schema tree classified as `unchanged`
+- CLI help and exit behavior verified
+
+## Deviations from Plan
+
+Compatibility tests generate isolated fixtures at runtime instead of storing static fixture directories. This keeps each case explicit and avoids fixture drift.
+
+## Self-Check: PASSED