Add the v1 portable core contract validator (inactive)

.github/workflows/ci.yml

@@ -163,6 +163,32 @@ jobs:
           git config --global user.name "ci"
           bash scripts/test/v2-check-rename.test.sh
 
+      - name: Portable core contract tests
+        env:
+          # jq 1.6 exactly — core/v1/contracts.jq's canonical-JSON rules depend on this
+          # exact release's formatting. The ubuntu-latest preinstalled jq is newer, so a
+          # coder testing locally with a different jq version could pass locally and fail
+          # here (or vice versa); this pin plus AGENTS.md's local setup keep them in sync.
+          # SHA-256 is the official jq-1.6 release asset's digest for jq-linux64.
+          JQ16_SHA256: "af986793a515d500ab2d35f8d2aecd656e764504b789b66d7e1a0b727a124c44"
+        run: |
+          set -euo pipefail
+          mkdir -p /tmp/ystack-jq-1.6
+          curl --proto '=https' --tlsv1.2 -fsSL \
+            https://github.com/jqlang/jq/releases/download/jq-1.6/jq-linux64 \
+            -o /tmp/ystack-jq-1.6/jq
+          printf '%s  %s\n' "$JQ16_SHA256" /tmp/ystack-jq-1.6/jq | sha256sum -c -
+          chmod 0555 /tmp/ystack-jq-1.6/jq
+          export PATH="/tmp/ystack-jq-1.6:$PATH"
+          got="$(jq --version)"
+          if [ "$got" != "jq-1.6" ]; then
+            echo "jq version mismatch: expected jq-1.6, got $got"; exit 1
+          fi
+          echo "jq pinned to $got — ok"
+          # This PATH prepend is scoped to this one step; every other step (including
+          # Shellcheck's own script sweep above) keeps using the runner's system jq.
+          bash scripts/test/core-contract.test.sh
+
       - name: Rename gate
         run: |
           # Patrols tracked files for old names left over from the rename.

AGENTS.md

@@ -30,9 +30,24 @@ Two goals drive the backlog:
   (runs the Codex reviewer against a PR).
 
 ## Stack & commands
-- Markdown + shell. The setup/reviewer tooling lives in `scripts/*.sh`; validators are
-  still to come.
-- CI: `.github/workflows/ci.yml` (structure check + shellcheck). **CI must stay green —
+- Markdown + shell. The setup/reviewer tooling lives in `scripts/*.sh`. The first real
+  validator has landed: `core/v1/contracts.jq` (the portable core contract, a pure jq
+  schema/relation checker) plus its front door `scripts/core-contract.sh` and its test
+  suite `scripts/test/core-contract.test.sh` / `scripts/test/core-contract-fixtures.jq`.
+  It is manual and inactive — nothing in the live profile calls it yet. Run its tests
+  locally with:
+
+  ```sh
+  bash scripts/test/core-contract.test.sh
+  ```
+
+  This needs **jq 1.6 exactly** on `PATH` first (a newer jq formats JSON differently,
+  which breaks the canonical-byte checks). Grab the pinned release for your platform
+  from the jq GitHub releases (e.g. `jq-osx-amd64` on Apple Silicon, run through
+  Rosetta) and verify its SHA-256 before use; see the header of
+  `scripts/test/core-contract.test.sh` for the exact download/verify steps.
+- CI: `.github/workflows/ci.yml` (structure check + shellcheck + the test suites above,
+  including the portable core contract's own jq-1.6-pinned step). **CI must stay green —
   it is the hard merge gate.** Add real tests as code lands.
   - **Shellcheck is pinned to `0.11.0`** (the `SHELLCHECK_VERSION` constant in
     `ci.yml` is the single source of truth). CI downloads that exact static release and

README.md

@@ -241,6 +241,35 @@ so yshifu's decisions rest on evidence. This is a **prompt-level** wiring: it ta
 effect once `scripts/install.sh` regenerates the live `/yshifu` command, not merely by
 merging the doc change — `doctor.sh`'s static validation is unaffected.
 
+## Portable core contract
+
+`core/v1/contracts.jq` defines the smallest vendor-neutral record family later
+adapters can share: five documents (`adapter_manifest`, `profile`, `resolved_profile`,
+`stage_request`, `stage_result`), three capabilities, and five permissions — see
+[`work/portable-core-contracts/spec.md`](work/portable-core-contracts/spec.md). It is a
+**pure, offline validator**: it checks shapes, references, and relations between
+caller-supplied documents. It never reads Git, launches a process, calls a model, or
+proves that a claim is true — a passing check is not trust or authority.
+
+Run it through the one public front door, `scripts/core-contract.sh`:
+
+```sh
+scripts/core-contract.sh validate-document DOCUMENT
+scripts/core-contract.sh validate-profile-set PROFILE RESOLVED_PROFILE MANIFEST...
+scripts/core-contract.sh validate-stage-run REQUEST RESOLVED_PROFILE RESULT
+```
+
+Every argument is a path to one canonical-JSON document. Success is exit 0 with empty
+output; failure is a nonzero exit with one `E_*` token on stderr (see the header comment
+in `core/v1/contracts.jq` for the full list). The wrapper requires **jq 1.6 exactly** —
+see `scripts/test/core-contract.test.sh` for the pinned-binary setup on Apple Silicon.
+Local test command: `bash scripts/test/core-contract.test.sh`.
+
+This is a **manual, inactive validator** today: nothing in the live profile, `/yshifu`,
+or any target template calls it. It does not select, activate, or change any current
+behavior — it exists so later profile-resolution and adapter-contract-test work has a
+stable, tested vocabulary to build on.
+
 ## Layout
 
 ```
@@ -260,6 +289,8 @@ scripts/merge-pr.sh        Safe merge harness for the OPERATOR's own use (yshifu
 scripts/setup-target-repo.sh  Bootstrap a target repo's loop labels (idempotent)
 scripts/lib/north-star.sh  Resolver: returns the active target repo's committed .ystack/north-star.md (or root NORTH_STAR.md when ystack itself is the target)
 scripts/doctor.sh          Read-only restore + readiness self-check (install, auth, restore-critical files, north star, model config, ...)
+core/v1/contracts.jq       Portable core contract v1 (pure jq validator; manual, inactive — see "Portable core contract" above)
+scripts/core-contract.sh   Shell front door to core/v1/contracts.jq: validate-document / validate-profile-set / validate-stage-run
 config/models.conf         Shipped model-tiering defaults (coder/hands ceilings, gate models/effort) — see "Model policy" below
 templates/yshifu-command.md Template for the /yshifu command (path placeholder)
 templates/target-CLAUDE.md Drop into each target repo (conventions + PR-size rule)

RESTORE.md

@@ -29,7 +29,10 @@ Accounts and access you need before starting:
 - **GitHub access** to each target repo, plus the **`gh` CLI authenticated** locally
   (`gh auth status` should show you logged in) for labels and the loop's `gh` calls.
 - **`jq` on `PATH`** — the review/debate gates validate Codex's `--json` event stream with it,
-  and the merge helper parses GitHub check JSON with it.
+  and the merge helper parses GitHub check JSON with it. The portable core contract
+  validator (`scripts/core-contract.sh`, section 7 below) additionally requires **jq 1.6
+  exactly** — a different version is refused (`E_RUNTIME`), since a newer jq can format or
+  canonicalize JSON differently. This does not change the `jq` version used elsewhere.
 - **The personal config you must supply** (keep it parameterized — see the note above):
   - the **target repo name(s)**, e.g. `<owner>/<repo>` — the repo(s) the team works in.
     (ystack is its own target repo; add others as you adopt the team elsewhere.)
@@ -324,6 +327,27 @@ These are load-bearing — per the self-modification safety section of
 
 ---
 
+## 7. Optional: verify the portable core contract validator
+
+`core/v1/contracts.jq` + `scripts/core-contract.sh` are a **manual, inactive**
+validator — nothing in the restored `/yshifu` command or any target profile calls
+them, so this step is optional and does not affect the restore path above.
+
+To confirm the restored copy still works:
+
+1. Install **jq 1.6 exactly** (not whatever version your OS ships — see
+   `scripts/test/core-contract.test.sh` for the pinned `jq-osx-amd64` asset and its
+   SHA-256, or use the matching official release for your platform). Put it first on
+   `PATH` for this check.
+2. Run `bash scripts/test/core-contract.test.sh`. It builds one small valid
+   document graph, runs it through `scripts/core-contract.sh`, and asserts at least
+   60 positive and mutation cases with zero failures — no Git, network, or `gh`
+   needed.
+3. If it fails, the validator itself is broken; nothing else in the restored team
+   depends on it, so this does not block the rest of the rebuild.
+
+---
+
 ## Troubleshooting / gotchas
 
 Real lessons from setting this up:

ci/required-files.txt

@@ -47,6 +47,7 @@ scripts/manager-review.sh
 scripts/merge-pr.sh
 scripts/setup-target-repo.sh
 scripts/doctor.sh
+scripts/core-contract.sh
 
 # Sourced libraries (not executed directly; sourced by the scripts above)
 scripts/lib/north-star.sh
@@ -85,3 +86,9 @@ scripts/test/north-star-resolver.test.sh
 scripts/test/north-star-gate.test.sh
 scripts/test/models-conf-parser.test.sh
 scripts/test/codex-degraded-gate.test.sh
+scripts/test/core-contract.test.sh
+
+# Portable core contract v1 (manual validator; not part of any live profile —
+# see work/portable-core-contracts/plan.md)
+core/v1/contracts.jq
+scripts/test/core-contract-fixtures.jq