cool-workflow 0.2.4 → 0.2.6

package/scripts/release-gate.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+"use strict";
+// release-gate.js — deterministic release checks for cool-workflow.
+// Pass = writes .cw-release/gate-<HEAD-sha>.ok
+// This script encodes everything that does NOT need LLM judgment.
+// (Node port of the former release-gate.sh; behavior kept line for line —
+// same six steps, same messages, same exit map: 0 = PASSED, 1 = REJECTED.)
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { resolvePrevReleaseTag } = require("./release-tags.js");
+
+const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" });
+if (top.status !== 0) {
+  process.stderr.write("release-gate: not inside a git work tree\n");
+  process.exit(1);
+}
+const REPO_ROOT = top.stdout.trim();
+
+function gitOut(args) {
+  const r = spawnSync("git", args, { cwd: REPO_ROOT, encoding: "utf8" });
+  return r.status === 0 ? (r.stdout || "").trim() : "";
+}
+
+const SHA = gitOut(["rev-parse", "HEAD"]);
+let FAIL = 0;
+function say(msg) {
+  process.stdout.write(`${msg}\n`);
+}
+function fail(msg) {
+  say(`GATE FAIL: ${msg}`);
+  FAIL = 1;
+}
+
+// Resolve the PREVIOUS release tag by SEMVER ORDER, not ancestry — shared
+// with release-flow.js via release-tags.js (see that file's header for the
+// full story: `git describe --tags` walks ancestry and silently SKIPS the
+// true previous release tag under the tag-only-push design, making the
+// substance/test-evidence/cadence checks below compare against the wrong
+// baseline and pass permanently; ITERATION_LOG cycles 35/36).
+const PREV_TAG = resolvePrevReleaseTag(gitOut);
+
+// An empty PREV_TAG is ambiguous: (a) the genuine first release, so skipping
+// substance/evidence/cadence is right, or (b) tags DO exist but this clone can
+// not see them — a shallow clone hides them in history, and a `git clone
+// --no-tags` / `fetch-tags: false` clone of a long-tagged repo shows 0 local
+// tags too. (a) and (b) look IDENTICAL from local state (both give an empty
+// describe and 0 tags), so we can NOT auto-tell them apart. Fail CLOSED: skip
+// the checks ONLY when the operator positively declares a first release with
+// CW_FIRST_RELEASE=1 (explicit + logged, the same shape the cadence HOTFIX
+// override uses). Otherwise REJECT — a mis-fetched clone must never look like a
+// first release and silently pass. Found by a 2026-07-12 security check; the
+// shallow signal alone closed only half the hole (the `--no-tags` full clone
+// still slipped through).
+if (!PREV_TAG) {
+  const shallow = spawnSync("git", ["rev-parse", "--is-shallow-repository"], { cwd: REPO_ROOT, encoding: "utf8" });
+  const IS_SHALLOW = shallow.status === 0 ? shallow.stdout.trim() : "false";
+  if (IS_SHALLOW === "true") {
+    fail("cannot resolve the previous release tag: this is a shallow git clone (git rev-parse --is-shallow-repository = true), so an older tag may be hidden and substance/test-evidence/cadence cannot be trusted. Fetch full history (actions/checkout with fetch-depth: 0) before running this gate.");
+  } else if (process.env.CW_FIRST_RELEASE === "1") {
+    say("no previous tag; genuine first release declared (CW_FIRST_RELEASE=1) — substance/evidence/cadence will be skipped");
+  } else {
+    fail("cannot resolve the previous release tag on a full (non-shallow) clone. Either tags were not fetched (git clone --no-tags, or actions/checkout fetch-tags: false — fetch tags and re-run), or this is the genuine first release (set CW_FIRST_RELEASE=1 to declare that explicitly). Refusing to silently skip substance/test-evidence/cadence.");
+  }
+}
+const MARKER_DIR = path.join(REPO_ROOT, ".cw-release");
+fs.mkdirSync(MARKER_DIR, { recursive: true });
+
+const MAX_CHILD_DIAGNOSTIC_BYTES = 16 * 1024;
+
+function boundedDiagnostic(text) {
+  const value = String(text || "").trim();
+  if (value.length <= MAX_CHILD_DIAGNOSTIC_BYTES) return value;
+  return `…${value.slice(-MAX_CHILD_DIAGNOSTIC_BYTES)}`;
+}
+
+function reportNpmFailure(label, result) {
+  // Failure facts are local diagnostics, never stdout data and never a saved
+  // release record. Keep the tail so a large smoke run cannot flood a terminal.
+  const out = boundedDiagnostic(result.stdout);
+  const err = boundedDiagnostic(result.stderr);
+  process.stderr.write(`release-gate: ${label} failed (exit ${result.status ?? "unknown"})\n`);
+  if (err) process.stderr.write(`[stderr]\n${err}\n`);
+  if (out) process.stderr.write(`[stdout]\n${out}\n`);
+}
+
+function runNpm(args, extraEnv) {
+  const r = spawnSync("npm", args, {
+    cwd: REPO_ROOT,
+    encoding: "utf8",
+    env: extraEnv ? { ...process.env, ...extraEnv } : process.env,
+  });
+  return r;
+}
+
+// --- 1. Build & tests (run, don't trust pasted output) -----------------
+say("[1/6] build");
+const build = runNpm(["run", "--prefix", "plugins/cool-workflow", "build"]);
+if (build.error || build.status !== 0) {
+  fail("build failed");
+  reportNpmFailure("build", build);
+}
+
+say("[2/6] tests");
+const tests = runNpm(["run", "test:gate", "--prefix", "plugins/cool-workflow"], { CW_TEST_CONCURRENCY: "1" });
+if (tests.error || tests.status !== 0) {
+  fail("tests failed");
+  reportNpmFailure("tests", tests);
+}
+
+if (PREV_TAG) {
+  const RANGE = `${PREV_TAG}..HEAD`;
+  const changedFiles = gitOut(["diff", "--name-only", RANGE]).split("\n").filter(Boolean);
+
+  // --- 2. Substance: changes must exist outside src/types/ and dist/ ---
+  // The spec (AGENTS.md / reviewer-agent.md Gate 1) is "at least one changed
+  // file outside src/types/ and dist/" — ANY such file (src, scripts, docs,
+  // workflows, tests). Count every changed path that is not under those two
+  // generated/declaration-only trees; declared-but-unread spec accretion is the
+  // reviewer agent's deeper judgment call, not this deterministic floor.
+  say("[3/6] substance (diff outside src/types/ and dist/)");
+  const SUBSTANCE = changedFiles.filter((f) => !/^plugins\/cool-workflow\/(src\/types\/|dist\/)/.test(f)).length;
+  if (!(SUBSTANCE > 0)) fail(`only types/dist changed since ${PREV_TAG} (spec accretion)`);
+
+  // --- 3. Test evidence: test files must have changed ------------------
+  say("[4/6] test evidence");
+  const TESTS_CHANGED = changedFiles.filter((f) => /\.(test|spec)\.|\/tests?\//.test(f)).length;
+  if (!(TESTS_CHANGED > 0)) fail(`zero test changes since ${PREV_TAG}`);
+
+  // --- 4. Cadence: >=4 cycles logged OR >=24h since previous tag, or a recorded HOTFIX ---
+  say("[5/6] cadence");
+  let CYCLES = 0;
+  const logDiff = fs.existsSync(path.join(REPO_ROOT, "ITERATION_LOG.md"))
+    ? gitOut(["diff", RANGE, "--", "ITERATION_LOG.md"]).split("\n")
+    : [];
+  CYCLES = logDiff.filter((line) => /^\+.*\|/.test(line)).length;
+  const PREV_TS = Number(gitOut(["log", "-1", "--format=%ct", PREV_TAG]));
+  const NOW_TS = Math.floor(Date.now() / 1000);
+  const HOURS = Math.floor((NOW_TS - PREV_TS) / 3600);
+  // Hotfix path: an urgent fix may ship inside the cadence window, but ONLY via an
+  // EXPLICIT, RECORDED declaration — a "HOTFIX:" line added to ITERATION_LOG.md in this
+  // release range, carrying a reason. It is committed (auditable in the tag's history)
+  // and echoed here, so the bypass is never silent and a reviewer sees the reason.
+  const hotfixLine = logDiff.find((line) => /^\+.*HOTFIX:/.test(line));
+  const HOTFIX = hotfixLine ? hotfixLine.replace(/^\+\s*/, "") : "";
+  if (CYCLES < 4 && HOURS < 24) {
+    if (HOTFIX) {
+      say(`  cadence bypassed by recorded HOTFIX (${HOURS}h, ${CYCLES} cycle-lines): ${HOTFIX}`);
+    } else {
+      fail(`cadence: only ${CYCLES} cycles logged and ${HOURS}h since ${PREV_TAG} (need >=4 cycles, >=24h, or a recorded 'HOTFIX:' line in ITERATION_LOG.md)`);
+    }
+  }
+} else {
+  say("[3-5/6] no previous tag; substance/evidence/cadence checks skipped");
+}
+
+// --- 5. Branch naming: forbid version-number branches -------------------
+say("[6/6] branch naming");
+// On a normal checkout `git rev-parse --abbrev-ref HEAD` is the branch name. On
+// a DETACHED HEAD it prints the literal string "HEAD" — and the tag-push CI
+// (release-gate.yml) ALWAYS checks out the tag, so HEAD is detached there. A
+// literal "HEAD" can never match the version-branch regex below, so this check
+// would silently pass exactly where it is meant to be the backstop. Handle the
+// detached case explicitly: gather the real candidate ref name(s) — the
+// CI-provided source branch (GITHUB_HEAD_REF for a PR, else GITHUB_REF_NAME),
+// plus every local/remote branch whose tip contains this commit — and judge
+// each one. A truly detached checkout with no resolvable branch (a bare
+// `git checkout <sha>`) has no branch to name, so there is nothing to forbid;
+// that is now an explicit, understood pass, not an accidental regex miss.
+const BRANCH = gitOut(["rev-parse", "--abbrev-ref", "HEAD"]) || "HEAD";
+let candidateBranches = [BRANCH];
+if (BRANCH === "HEAD") {
+  candidateBranches = [];
+  // The CI source branch: a PR run exposes it as GITHUB_HEAD_REF; a plain push
+  // exposes the pushed ref as GITHUB_REF_NAME (a tag on a tag push, which simply
+  // will not match the feat/ regex — harmless to include).
+  for (const envRef of [process.env.GITHUB_HEAD_REF || "", process.env.GITHUB_REF_NAME || ""]) {
+    if (envRef) candidateBranches.push(envRef);
+  }
+  // Every local branch whose tip contains this commit, plus every remote-tracking
+  // branch (with its "<remote>/" prefix stripped so the regex still anchors on
+  // "feat/"). --format avoids the "* " current-branch marker git branch prints.
+  const localC = gitOut(["branch", "--contains", "HEAD", "--format=%(refname:short)"]);
+  const remoteC = gitOut(["branch", "-r", "--contains", "HEAD", "--format=%(refname:short)"])
+    .split("\n")
+    .map((b) => b.replace(/^[^/]+\//, ""))
+    .join("\n");
+  for (const chunk of [localC, remoteC]) {
+    if (chunk) candidateBranches.push(...chunk.split("\n"));
+  }
+}
+for (const B of candidateBranches) {
+  if (!B || B === "HEAD") continue;
+  if (/^feat\/(batch-)?v?[0-9]+/.test(B)) {
+    fail(`branch '${B}' is version-number-driven; name the capability instead`);
+  }
+}
+
+// --- Verdict ------------------------------------------------------------
+if (FAIL !== 0) {
+  fs.rmSync(path.join(MARKER_DIR, `gate-${SHA}.ok`), { force: true });
+  say(`RELEASE GATE: REJECTED (${SHA})`);
+  process.exit(1);
+}
+
+fs.writeFileSync(path.join(MARKER_DIR, `gate-${SHA}.ok`), `${new Date().toISOString().replace(/\.\d{3}Z$/, "Z")}\n`);
+say(`RELEASE GATE: PASSED (${SHA}) — next step: release-reviewer agent must record APPROVED`);

package/scripts/release-oneclick.js

@@ -120,6 +120,28 @@ function alreadyCut() {
   return remote.code === 0 && Boolean(remote.out);
 }
 
+// A cut tags the verdict commit LOCALLY and only then pushes the tag. If that
+// push dies (a network drop, an auth expiry) the tag is left local-only:
+// alreadyCut() still sees it and resumes at stage 3, but stage 3 would then
+// wait 45 minutes for a release-gate run CI never started, because the tag
+// never reached origin. So on resume, before the CI wait, make sure the tag is
+// actually on origin — re-push it (the same tag-only refspec cut() uses) when
+// it is only local. This keeps the tag-only-push contract: no branch is pushed,
+// and the tag commit's first parent is untouched (it is exactly what was cut).
+function ensureTagPushedOnResume() {
+  const remote = git(["ls-remote", "origin", `refs/tags/v${version}`]);
+  if (remote.code !== 0) {
+    die("could not reach origin to check the tag — fix network/auth and re-run to resume.", remote.err);
+  }
+  if (remote.out) return; // already on origin — nothing to do
+  say(`tag v${version} is local-only (the cut's tag push must have failed) — re-pushing refs/tags/v${version}.`);
+  const push = git(["push", "origin", `refs/tags/v${version}`]);
+  if (push.code !== 0) {
+    die("re-push of the local-only tag failed (nothing else was done) — fix the issue and re-run to resume.", push.err);
+  }
+  say(`re-pushed refs/tags/v${version} to origin.`);
+}
+
 // ---- stage 0: preflight -----------------------------------------------------
 function runPreflight() {
   stage(0, "preflight");
@@ -318,12 +340,12 @@ function runRecordAndWaitStage() {
   }
 
   say(`waiting for release-gate on tag v${version}...`);
-  const gateRunId = poll({
+  const gate = poll({
     label: "release-gate wait",
     timeoutMs: 45 * 60 * 1000,
     intervalMs: 20000,
     probe: () => {
-      const list = gh(["run", "list", "--workflow", "release-gate", "--limit", "10", "--json", "databaseId,headBranch,status,conclusion"]);
+      const list = gh(["run", "list", "--workflow", "release-gate", "--limit", "10", "--json", "databaseId,headBranch,status,conclusion,updatedAt"]);
       if (list.code !== 0) return { error: true };
       let runs;
       try {
@@ -333,22 +355,29 @@ function runRecordAndWaitStage() {
       }
       const gateRun = runs.find((r) => r.headBranch === `v${version}`);
       if (gateRun && gateRun.status === "completed") {
-        if (gateRun.conclusion === "success") return { done: true, value: gateRun.databaseId };
+        // Carry the gate's OWN completion time out of the poll — the npm-publish
+        // cutoff below must key off when the gate actually finished, not off the
+        // wall clock now (a resume can start long after the gate completed).
+        if (gateRun.conclusion === "success") return { done: true, value: { id: gateRun.databaseId, completedMs: Date.parse(gateRun.updatedAt) } };
         die(`release-gate FAILED — inspect: gh run view ${gateRun.databaseId} --log-failed`);
       }
       return {};
     }
   });
-  say(`release-gate: SUCCESS (run ${gateRunId})`);
+  say(`release-gate: SUCCESS (run ${gate.id})`);
 
   // npm-publish is created only AFTER release-gate completes (workflow_run
   // trigger), so the run to wait for may not exist yet — and the newest
   // completed npm-publish run at this moment is usually the PREVIOUS
   // release's. Only accept a run created at-or-after the moment the gate
-  // finished (small clock-skew allowance), and keep waiting until that run
-  // exists and completes.
+  // FINISHED (small clock-skew allowance), and keep waiting until that run
+  // exists and completes. The cutoff is the gate run's own completion time,
+  // NOT Date.now(): on a resume minutes/days later, a now-based cutoff sits in
+  // the future relative to an already-completed npm-publish run and would drop
+  // it, hanging the wait for a publish that is already done. Fall back to now
+  // only if the gate run reported no parseable completion time.
   say("waiting for npm-publish...");
-  const gateDoneMs = Date.now();
+  const gateDoneMs = Number.isFinite(gate.completedMs) ? gate.completedMs : Date.now();
   poll({
     label: "npm-publish wait",
     timeoutMs: 30 * 60 * 1000,
@@ -396,7 +425,9 @@ if (alreadyCut()) {
   say(`tag v${version} already exists — the cut already happened; resuming at stage 3 (CI wait + record + confirm).`);
   if (DRY_RUN) {
     say("[dry-run] would resume at stage 3: record PR + wait for release-gate/npm-publish + npm view confirmation.");
+    say("[dry-run] would first re-push refs/tags/v" + version + " if it is only local (the cut's tag push had failed).");
   } else {
+    ensureTagPushedOnResume();
     runRecordAndWaitStage();
   }
 } else {

package/scripts/release-tags.js

@@ -0,0 +1,47 @@
+"use strict";
+// release-tags.js — the ONE semver-ordered release-tag lookup, shared by
+// release-flow.js and release-gate.js so the two can never drift (the gate
+// used to carry a bash port of this logic; a mirror copy is exactly the kind
+// of thing that rots).
+//
+// "What was the last release" is a SEMVER question, not an ancestry question:
+// a cut's own tag commit lives on an ephemeral line that is NEVER merged as
+// an ancestor of `main` (cut() tags the verdict-record commit directly), so
+// `git describe --tags --abbrev=0`, which walks ONLY ancestors, always skips
+// the true previous release tag and silently lands one release further back
+// (verified live: `git describe --tags v0.2.4^` -> v0.2.2, skipping v0.2.3).
+// List every vX.Y.Z tag and pick by version order instead.
+
+function parseSemverTag(tag) {
+  const m = /^v(\d+)\.(\d+)\.(\d+)$/.exec(tag);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+function compareSemver(a, b) {
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] - b[i];
+  return 0;
+}
+
+// gitOut: (args: string[]) => string — the caller's own git runner (each
+// caller binds its own repo root), returning trimmed stdout, "" on failure.
+function listReleaseTagsDesc(gitOut) {
+  const out = gitOut(["tag", "-l", "v*"]);
+  if (!out) return [];
+  return out
+    .split("\n")
+    .filter(Boolean)
+    .map((tag) => ({ tag, semver: parseSemverTag(tag) }))
+    .filter((t) => t.semver)
+    .sort((a, b) => compareSemver(b.semver, a.semver));
+}
+
+// The most recent ALREADY-RELEASED tag as of right now: the highest vX.Y.Z
+// tag that does NOT already point at HEAD — so this works whether run before
+// tagging or re-run on a freshly tagged commit.
+function resolvePrevReleaseTag(gitOut) {
+  const headTags = new Set(gitOut(["tag", "--points-at", "HEAD"]).split("\n").filter(Boolean));
+  const found = listReleaseTagsDesc(gitOut).find((t) => !headTags.has(t.tag));
+  return found ? found.tag : "";
+}
+
+module.exports = { parseSemverTag, compareSemver, listReleaseTagsDesc, resolvePrevReleaseTag };

package/scripts/schema-version-inventory.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": 1,
+  "domains": [
+    { "domain": "agent-config", "constant": "AGENT_CONFIG_SCHEMA_VERSION", "source": "shell/agent-config.ts" },
+    { "domain": "blackboard", "constant": "BLACKBOARD_SCHEMA_VERSION", "source": "core/multi-agent/coordinator.ts" },
+    { "domain": "candidate", "constant": "CANDIDATE_SCHEMA_VERSION", "source": "core/multi-agent/candidate-scoring.ts" },
+    { "domain": "collaboration", "constant": "COLLABORATION_SCHEMA_VERSION", "source": "core/multi-agent/collaboration.ts" },
+    { "domain": "contract-migration", "constant": "CONTRACT_MIGRATION_SCHEMA_VERSION", "source": "core/state/contract-migration.ts" },
+    { "domain": "current-run-state", "constant": "CURRENT_RUN_STATE_SCHEMA_VERSION", "source": "core/version.ts" },
+    { "domain": "drive", "constant": "DRIVE_SCHEMA_VERSION", "source": "core/pipeline/drive-decide.ts" },
+    { "domain": "error-feedback", "constant": "ERROR_FEEDBACK_SCHEMA_VERSION", "source": "core/pipeline/error-feedback.ts" },
+    { "domain": "evidence-reasoning", "constant": "EVIDENCE_REASONING_SCHEMA_VERSION", "source": "shell/evidence-reasoning.ts" },
+    { "domain": "execution-backend", "constant": "EXECUTION_BACKEND_SCHEMA_VERSION", "source": "shell/execution-backend/registry.ts" },
+    { "domain": "legacy-run-state", "constant": "LEGACY_RUN_STATE_SCHEMA_VERSION", "source": "core/version.ts" },
+    { "domain": "metrics", "constant": "METRICS_SCHEMA_VERSION", "source": "shell/observability.ts" },
+    { "domain": "minimum-run-state", "constant": "MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION", "source": "core/version.ts" },
+    { "domain": "multi-agent", "constant": "MULTI_AGENT_SCHEMA_VERSION", "source": "core/multi-agent/runtime.ts" },
+    { "domain": "node-snapshot", "constant": "NODE_SNAPSHOT_SCHEMA_VERSION", "source": "core/state/node-snapshot.ts" },
+    { "domain": "pipeline-contract", "constant": "PIPELINE_CONTRACT_SCHEMA_VERSION", "source": "core/state/state-node.ts" },
+    { "domain": "run-registry", "constant": "RUN_REGISTRY_SCHEMA_VERSION", "source": "shell/run-registry-io.ts" },
+    { "domain": "sandbox-profile", "constant": "SANDBOX_PROFILE_SCHEMA_VERSION", "source": "shell/sandbox-profile.ts" },
+    { "domain": "scheduling", "constant": "SCHEDULING_SCHEMA_VERSION", "source": "shell/scheduling-io.ts" },
+    { "domain": "state-explosion", "constant": "STATE_EXPLOSION_SCHEMA_VERSION", "source": "core/state/state-explosion/size.ts" },
+    { "domain": "state-node", "constant": "STATE_NODE_SCHEMA_VERSION", "source": "core/state/state-node.ts" },
+    { "domain": "telemetry-ledger", "constant": "TELEMETRY_LEDGER_SCHEMA_VERSION", "source": "core/trust/telemetry-ledger.ts" },
+    { "domain": "topology", "constant": "TOPOLOGY_SCHEMA_VERSION", "source": "core/multi-agent/topology.ts" },
+    { "domain": "trust-audit", "constant": "TRUST_AUDIT_SCHEMA_VERSION", "source": "shell/trust-audit.ts" },
+    { "domain": "worker-isolation", "constant": "WORKER_ISOLATION_SCHEMA_VERSION", "source": "shell/worker-isolation.ts" },
+    { "domain": "workflow-app", "constant": "WORKFLOW_APP_SCHEMA_VERSION", "source": "core/version.ts" }
+  ]
+}

package/scripts/validate-run-state-schema.js

@@ -19,6 +19,8 @@ const path = require("node:path");
 const PLUGIN_ROOT = path.resolve(__dirname, "..");
 const TYPES_FILE = path.join(PLUGIN_ROOT, "src", "core", "state", "types.ts");
 const SCHEMA_MODULE = path.join(PLUGIN_ROOT, "dist", "core", "state", "schema.js");
+const SOURCE_ROOT = path.join(PLUGIN_ROOT, "src");
+const VERSION_INVENTORY_FILE = path.join(__dirname, "schema-version-inventory.json");
 
 function main() {
   const errors = [];
@@ -43,6 +45,15 @@ function main() {
   const requiredKeys = new Set(schema.REQUIRED_TOP_LEVEL_KEYS || []);
   const optionalKeys = new Set(schema.OPTIONAL_TOP_LEVEL_KEYS || []);
 
+  let versionInventory;
+  try {
+    versionInventory = JSON.parse(fs.readFileSync(VERSION_INVENTORY_FILE, "utf8"));
+  } catch (error) {
+    console.error(`validate-run-state-schema: FATAL — cannot load ${VERSION_INVENTORY_FILE}.`);
+    process.exit(1);
+  }
+  errors.push(...validateSchemaVersionInventory(versionInventory, readTypeScriptSources(SOURCE_ROOT)));
+
   // ---- 3. Cross-check: every type key must be either required or optional ----
   for (const key of runKeys) {
     if (requiredKeys.has(key)) continue;
@@ -70,9 +81,8 @@ function main() {
     console.error("validate-run-state-schema: FAIL CLOSED — schema drift detected.");
     for (const e of errors) console.error(`  ${e}`);
     console.error(
-      `\nFix: update REQUIRED_TOP_LEVEL_KEYS and/or OPTIONAL_TOP_LEVEL_KEYS in ` +
-      `src/run-state-schema.ts, then update normalizeRunState() and validateMigratedRunState() ` +
-      `in src/state-migrations.ts to handle any new required fields.`
+      `\nFix: update the run-state key lists or schema-version-inventory.json and its canonical source. ` +
+      `Keep each schema domain separate.`
     );
     process.exit(1);
   }
@@ -82,6 +92,85 @@ function main() {
     `validate-run-state-schema: ok — ${runKeys.size} WorkflowRun keys accounted for ` +
     `(${requiredKeys.size} required + ${optionalKeys.size} optional = ${total})`
   );
+  console.error(
+    `validate-run-state-schema: ok — ${versionInventory.domains.length} schema version domains have one definition each`
+  );
+}
+
+function readTypeScriptSources(root, base = root) {
+  const files = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const absolute = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...readTypeScriptSources(absolute, base));
+      continue;
+    }
+    if (!entry.isFile() || !entry.name.endsWith(".ts")) continue;
+    files.push({
+      path: path.relative(base, absolute).split(path.sep).join("/"),
+      source: fs.readFileSync(absolute, "utf8"),
+    });
+  }
+  return files;
+}
+
+function validateSchemaVersionInventory(inventory, sourceFiles) {
+  const errors = [];
+  if (!inventory || inventory.schemaVersion !== 1 || !Array.isArray(inventory.domains)) {
+    return ["Schema version inventory must have schemaVersion 1 and a domains array."];
+  }
+
+  const entriesByConstant = new Map();
+  const domains = new Set();
+  for (const entry of inventory.domains) {
+    if (!entry || typeof entry.domain !== "string" || typeof entry.constant !== "string" || typeof entry.source !== "string") {
+      errors.push("Schema version inventory entries need domain, constant, and source strings.");
+      continue;
+    }
+    if (domains.has(entry.domain)) errors.push(`Schema version domain "${entry.domain}" is listed more than once.`);
+    domains.add(entry.domain);
+    if (entriesByConstant.has(entry.constant)) {
+      errors.push(`Schema version constant "${entry.constant}" is listed more than once.`);
+    } else {
+      entriesByConstant.set(entry.constant, entry);
+    }
+  }
+
+  const definitions = new Map();
+  const pattern = /^\s*(?:export\s+)?const\s+([A-Z][A-Z0-9_]*_SCHEMA_VERSION)\s*(?::[^=;]+)?=/gm;
+  for (const file of sourceFiles) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(file.source)) !== null) {
+      const found = definitions.get(match[1]) || [];
+      found.push(file.path);
+      definitions.set(match[1], found);
+    }
+  }
+
+  for (const [constant, sources] of definitions) {
+    const entry = entriesByConstant.get(constant);
+    if (!entry) {
+      errors.push(`Unknown schema version domain: "${constant}" has a definition in ${sources.join(", ")}.`);
+      continue;
+    }
+    if (sources.length > 1) {
+      errors.push(`Schema version constant "${constant}" has more than one definition: ${sources.join(", ")}.`);
+    }
+    for (const source of sources) {
+      if (source !== entry.source) {
+        errors.push(`Schema version constant "${constant}" must be defined in ${entry.source}, not ${source}.`);
+      }
+    }
+  }
+
+  for (const [constant, entry] of entriesByConstant) {
+    if (!definitions.has(constant)) {
+      errors.push(`Schema version inventory entry "${entry.domain}" has no definition for ${constant}.`);
+    }
+  }
+
+  return errors;
 }
 
 /**
@@ -123,4 +212,6 @@ function extractInterfaceKeys(source, interfaceName) {
   return keys;
 }
 
-main();
+if (require.main === module) main();
+
+module.exports = { extractInterfaceKeys, validateSchemaVersionInventory };

package/scripts/verdict-keygen.js

@@ -9,7 +9,7 @@
 // The PRIVATE key stays with whoever runs `release-flow.js --cut`/`--check`
 // (CW_RELEASE_VERDICT_PRIVKEY) and NEVER gets committed. The PUBLIC key is
 // committed to the repo at .cw-release/verdict-signing.pub so CI's
-// release-gate.yml, npm-publish.yml, and the local block-unapproved-tag.sh
+// release-gate.yml, npm-publish.yml, and the local block-unapproved-tag.js
 // hook can all verify a committed verdict without holding any secret.
 //
 // Verification is opt-in and backward compatible: as long as
@@ -76,7 +76,7 @@ process.stdout.write(
     `  git -C "$(git rev-parse --show-toplevel)" commit -m "chore: add release-verdict signing public key"`,
     ``,
     `Once .cw-release/verdict-signing.pub is committed, release-gate.yml, npm-publish.yml,`,
-    `and block-unapproved-tag.sh all start REQUIRING a valid signature on top of the`,
+    `and block-unapproved-tag.js all start REQUIRING a valid signature on top of the`,
     `existing APPROVED text check — an unsigned or hand-written verdict fails closed.`,
     ``
   ].join("\n")