@opengsd/gsd-core 1.10.0 → 1.12.0

package/scripts/base64-scan.sh

@@ -9,12 +9,29 @@
 #   scripts/base64-scan.sh --file path/to/file   # Scan a single file
 #   scripts/base64-scan.sh --dir agents/          # Scan all files in a directory
 #
-# Exit codes:
-#   0 = clean
-#   1 = findings detected
-#   2 = usage error
+# Exit codes (ADR-3889, #3908 — registered in gsd-core/bin/shared/exit-codes.json):
+#   0                = clean
+#   1                = findings detected
+#   $EXIT_USAGE       (64) = usage error (bad argv, missing --file/--dir target)
+#   $EXIT_NO_INPUT    (66) = ran; scope established; zero files in scope (genuinely empty)
+#   $EXIT_UNAVAILABLE (69) = could not establish scope (bad ref, not a repo, unreadable dir)
 set -euo pipefail
 
+# ─── Exit-code registry (ADR-3889, #3908) ────────────────────────────────────
+# Resolved relative to THIS script's location, not the caller's cwd. Loud,
+# non-zero failure if the fragment is missing — never fall back to a guessed
+# literal integer, and never let a missing registry silently degrade to
+# exit 0.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXIT_CODES_SH="$SCRIPT_DIR/../gsd-core/bin/shared/exit-codes.sh"
+if [[ ! -f "$EXIT_CODES_SH" ]]; then
+  echo "base64-scan: FATAL: exit-code registry not found at $EXIT_CODES_SH" >&2
+  echo "  Regenerate with: node scripts/gen-exit-code-registry.cjs --write" >&2
+  exit 1
+fi
+# shellcheck disable=SC1090
+. "$EXIT_CODES_SH"
+
 # ── Locale hardening (#116) ───────────────────────────────────────────────────
 # BSD tr (macOS) treats input bytes as multi-byte characters under any UTF-8
 # locale.  When the input to `tr -cd '[:print:]'` contains bytes that are not
@@ -180,7 +197,31 @@ collect_files() {
   case "$mode" in
     --diff)
       local base="${1:-origin/main}"
-      git diff --name-only --diff-filter=ACMR "$base"...HEAD 2>/dev/null \
+      # Run git separately from the filter pipe so its OWN exit status (not
+      # grep's) decides whether the diff could be established. stdout and
+      # stderr are captured SEPARATELY (never merged with `2>&1`) so that a
+      # warning git writes to stderr on an otherwise successful diff can
+      # never be mistaken for a filename in the file list. On failure the
+      # captured stderr is emitted as the diagnostic; on success it is
+      # forwarded as a warning, never folded into the file list.
+      # `|| true` on the filter below is CORRECT (not gratuitous): `grep -v`
+      # exits 1 when every line is filtered out (e.g. an all-images diff),
+      # which is a legitimate empty result, not a failure to run.
+      local raw status err_file
+      err_file=$(mktemp)
+      raw=$(git diff --name-only --diff-filter=ACMR "$base"...HEAD 2>"$err_file")
+      status=$?
+      if (( status != 0 )); then
+        cat "$err_file" >&2
+        rm -f "$err_file"
+        exit "$EXIT_UNAVAILABLE"
+      fi
+      if [[ -s "$err_file" ]]; then
+        echo "Warning: git diff emitted stderr output:" >&2
+        cat "$err_file" >&2
+      fi
+      rm -f "$err_file"
+      printf '%s\n' "$raw" \
         | grep -vE '\.(png|jpg|jpeg|gif|ico|woff|woff2|ttf|eot|otf|zip|tar|gz|pdf)$' || true
       ;;
     --file)
@@ -188,24 +229,41 @@ collect_files() {
         echo "$1"
       else
         echo "Error: file not found: $1" >&2
-        exit 2
+        exit "$EXIT_USAGE"
       fi
       ;;
     --dir)
       local dir="$1"
       if [[ ! -d "$dir" ]]; then
         echo "Error: directory not found: $dir" >&2
-        exit 2
+        exit "$EXIT_USAGE"
+      fi
+      # Same treatment as --diff: a `find` that fails (e.g. permission
+      # denied) must not be reported as an empty directory, and stdout/stderr
+      # are captured separately so a stderr warning never enters the file list.
+      local raw status err_file
+      err_file=$(mktemp)
+      raw=$(find "$dir" -type f ! -path '*/node_modules/*' ! -path '*/.git/*' ! -path '*/dist/*' \
+        ! -name '*.png' ! -name '*.jpg' ! -name '*.gif' ! -name '*.woff*' 2>"$err_file")
+      status=$?
+      if (( status != 0 )); then
+        cat "$err_file" >&2
+        rm -f "$err_file"
+        exit "$EXIT_UNAVAILABLE"
+      fi
+      if [[ -s "$err_file" ]]; then
+        echo "Warning: find emitted stderr output:" >&2
+        cat "$err_file" >&2
       fi
-      find "$dir" -type f ! -path '*/node_modules/*' ! -path '*/.git/*' ! -path '*/dist/*' \
-        ! -name '*.png' ! -name '*.jpg' ! -name '*.gif' ! -name '*.woff*' 2>/dev/null || true
+      rm -f "$err_file"
+      printf '%s\n' "$raw"
       ;;
     --stdin)
       cat
       ;;
     *)
       echo "Usage: $0 --diff [base] | --file <path> | --dir <path> | --stdin" >&2
-      exit 2
+      exit "$EXIT_USAGE"
       ;;
   esac
 }
@@ -309,7 +367,7 @@ extract_and_check_blobs() {
 main() {
   if [[ $# -eq 0 ]]; then
     echo "Usage: $0 --diff [base] | --file <path> | --dir <path>" >&2
-    exit 2
+    exit "$EXIT_USAGE"
   fi
 
   load_ignorelist
@@ -321,8 +379,12 @@ main() {
   files=$(collect_files "$mode" "$@")
 
   if [[ -z "$files" ]]; then
+    # collect_files already exited (UNAVAILABLE/USAGE) for anything that
+    # could not establish scope. Reaching here with an empty result means
+    # scope WAS established and is genuinely empty (e.g. an all-images
+    # diff) — that is NO_INPUT, not a silent clean pass.
     echo "base64-scan: no files to scan"
-    exit 0
+    exit "$EXIT_NO_INPUT"
   fi
 
   local total=0

package/scripts/baselines/planning-prompt-drift-baseline.json

@@ -0,0 +1,4 @@
+{
+  "$comment": "ADR-3180 Decision 4(e) ratchet, owned by Phase 8 (#3218). See scripts/lint-planning-prompt-drift.cjs. SHRINK-ONLY: entries are removed as sites migrate to the gsd-core CLI; new or changed entries fail lint:ci. `count` is the number of byte-identical (file, text) occurrences acknowledged at this site — a run producing fewer fails as a partial migration, more fails as an unacknowledged new copy. Emptied by #3218: all 6 recorded sites (7 occurrences) migrated to `gsd_run query find-phase` — see gsd-core/workflows/{execute-plan,plan-phase,plan-review-convergence,progress}.md.",
+  "entries": []
+}

package/scripts/baselines/planning-snapshot-bypass-baseline.json

@@ -0,0 +1,12 @@
+{
+  "$comment": "ADR-3180 §8.1 rule 2 ratchet, owned by Phase 11 (#3309). See scripts/lint-planning-snapshot-bypass-drift.cjs. SHRINK-ONLY: entries are removed as cmdValidateHealth migrates onto src/planning-snapshot.cts; new or changed entries fail lint:ci. `count` is the number of byte-identical (file, text) occurrences acknowledged at this site — a run producing fewer fails as a partial migration, more fails as an unacknowledged new copy.",
+  "entries": [
+    {
+      "file": "src/verify.cts",
+      "text": "const stateContent = fs.readFileSync(statePath, 'utf-8');",
+      "derivation": "planning-snapshot-bypass",
+      "owner_issue": "#3309",
+      "count": 1
+    }
+  ]
+}

package/scripts/baselines/unreachable-guard-drift-baseline.json

@@ -0,0 +1,4 @@
+{
+  "$comment": "#3409 unreachable-shell-guard ratchet. See scripts/lint-unreachable-guard-drift.cjs. SHRINK-ONLY: entries are removed as sites migrate off the unreachable-arm shape; new or changed entries fail lint:ci. `count` is the number of byte-identical (file, text) occurrences acknowledged at this site — a run producing fewer fails as a partial migration, more fails as an unacknowledged new copy.",
+  "entries": []
+}

package/scripts/build-hooks.js

@@ -71,6 +71,11 @@ const HOOKS_TO_COPY = [
   'gsd-session-state.sh',
   'gsd-validate-commit.sh',
   'gsd-phase-boundary.sh',
+  // Portable node resolver (#3662). Not a registered hook itself: managed JS
+  // hook commands under --portable-hooks route through it (bash <resolver>
+  // <baked-node> <script>) so node resolves at hook-fire time in every
+  // environment sharing the config root. Staged verbatim — no templating.
+  'gsd-node-runner.sh',
   // Graphify auto-update hook (#3347 / PR #3557 / #3579). Opt-in via
   // .planning/config.json graphify.auto_update; off by default.
   'gsd-graphify-update.sh'

package/scripts/changeset/lint.cjs

@@ -22,6 +22,7 @@ const LINT_REASON = Object.freeze({
   OK_NO_USER_FACING_CHANGES: 'ok_no_user_facing_changes',
   FAIL_MISSING_FRAGMENT: 'fail_missing_fragment',
   FAIL_INVALID_FRAGMENT: 'fail_invalid_fragment',
+  FAIL_PR_FIELD_DRIFT: 'fail_pr_field_drift',
 });
 
 const OPT_OUT_LABEL = 'no-changelog';
@@ -35,8 +36,6 @@ const USER_FACING_PREFIXES = [
   'agents/',
   'commands/',
   'hooks/',
-  'sdk/src/',
-  'sdk/prompts/',
 ];
 
 // Exact-match user-facing files. Any direct edit to one of these without a
@@ -53,10 +52,47 @@ function isFragment(file) {
   return /^\.changeset\/[^/]+\.md$/.test(file) && !file.endsWith('/README.md');
 }
 
-function evaluateLint({ changedFiles, labels, fragmentFailures = [] }) {
+/**
+ * DEFECT.CHANGESET-PR-FIELD-DRIFT (#3316, #3325): a fragment's `pr:` field is
+ * a guess (issue number, stacked-PR leftover) that never got backfilled to
+ * the real PR number after `gh api POST /pulls` returned it.
+ *
+ * Pure: given `prEntries` (`[{ file, pr }]`, one entry per successfully
+ * parsed changed fragment — `pr` is always a positive integer, since
+ * `parseFragment` already rejects `pr: 0` / non-numeric values as
+ * `invalid_pr` before a fragment ever reaches this function) and
+ * `realPrNumber` (the PR this run belongs to, or `null` when unknown —
+ * push/non-PR runs), returns every fragment whose `pr` disagrees with
+ * `realPrNumber`. `realPrNumber == null` always yields `[]`: with no PR
+ * event payload to compare against, there is nothing to drift-check.
+ *
+ * `pr === 0` is always silent regardless of `realPrNumber` — CONTRIBUTING.md
+ * documents `pr: 0` as the deliberate placeholder used "during initial
+ * commit" before `gh api POST /pulls` returns the real number, so it is not
+ * yet a drifted value, just an unbackfilled one. (In practice `parseFragment`
+ * already rejects `pr: 0` as `invalid_pr` before a fragment reaches this
+ * function via `main()`'s wiring — this guard documents and locks in the
+ * pure function's own contract independent of that upstream check.)
+ */
+function findPrFieldDrift(prEntries, realPrNumber) {
+  if (realPrNumber == null) return [];
+  const drift = [];
+  for (const { file, pr } of prEntries) {
+    if (pr === 0) continue;
+    if (pr !== realPrNumber) {
+      drift.push({ file, found: pr, expected: realPrNumber });
+    }
+  }
+  return drift;
+}
+
+function evaluateLint({ changedFiles, labels, fragmentFailures = [], prFieldDrift = [] }) {
   if (fragmentFailures.length > 0) {
     return { ok: false, reason: LINT_REASON.FAIL_INVALID_FRAGMENT, failures: fragmentFailures };
   }
+  if (prFieldDrift.length > 0) {
+    return { ok: false, reason: LINT_REASON.FAIL_PR_FIELD_DRIFT, drift: prFieldDrift };
+  }
   if (changedFiles.some(isFragment)) {
     return { ok: true, reason: LINT_REASON.OK_FRAGMENT_PRESENT };
   }
@@ -78,10 +114,18 @@ function main() {
   // GitHub Actions event payload path
   const eventPath = process.env.GITHUB_EVENT_PATH;
   let labels = [];
+  // DEFECT.CHANGESET-PR-FIELD-DRIFT: the real PR number this run belongs to,
+  // read from the same event payload. `null` on a push / non-PR run (no
+  // `pull_request` in the payload, or no payload at all) — the drift check
+  // below is a no-op in that case, it never fails a push run.
+  let realPrNumber = null;
   if (eventPath && fs.existsSync(eventPath)) {
     try {
       const event = JSON.parse(fs.readFileSync(eventPath, 'utf8'));
       labels = (event.pull_request?.labels || []).map((l) => l.name);
+      if (event.pull_request && Number.isInteger(event.pull_request.number)) {
+        realPrNumber = event.pull_request.number;
+      }
     } catch { /* fall through */ }
   }
   // #2988: local fallback must match the repo's integration branch (`next`),
@@ -107,6 +151,7 @@ function main() {
 
   // Validate the content of every changed fragment file.
   const fragmentFailures = [];
+  const prEntries = [];
   for (const file of changedFiles) {
     if (!isFragment(file)) continue;
     // A fragment path in the diff that no longer exists on disk was deleted in
@@ -125,10 +170,13 @@ function main() {
     const result = parseFragment(src);
     if (!result.ok) {
       fragmentFailures.push({ file, reason: result.reason, detail: result.detail });
+      continue;
     }
+    prEntries.push({ file, pr: result.fragment.pr });
   }
 
-  const verdict = evaluateLint({ changedFiles, labels, fragmentFailures });
+  const prFieldDrift = findPrFieldDrift(prEntries, realPrNumber);
+  const verdict = evaluateLint({ changedFiles, labels, fragmentFailures, prFieldDrift });
   if (process.argv.includes('--json')) {
     process.stdout.write(JSON.stringify({ ...verdict, changedFiles, labels }, null, 2) + '\n');
   } else if (verdict.ok) {
@@ -141,6 +189,13 @@ function main() {
       process.stderr.write(`  ${f.file}: ${f.reason}${detail}\n`);
     }
     process.stderr.write(`Fix the fragment(s) above before merging.\n`);
+  } else if (verdict.reason === LINT_REASON.FAIL_PR_FIELD_DRIFT) {
+    process.stderr.write(`\nERROR changeset-lint: ${verdict.reason}\n`);
+    process.stderr.write(`The following .changeset fragment(s) have a stale \`pr:\` field (DEFECT.CHANGESET-PR-FIELD-DRIFT):\n`);
+    for (const d of verdict.drift) {
+      process.stderr.write(`  ${d.file}: pr: ${d.found}, expected pr: ${d.expected}\n`);
+    }
+    process.stderr.write(`Backfill \`pr:\` with this PR's real number (see .changeset/README.md), then push again.\n`);
   } else {
     process.stderr.write(`\nERROR changeset-lint: ${verdict.reason}\n`);
     process.stderr.write(`PR touches user-facing files but does not include a .changeset/*.md fragment.\n`);
@@ -152,4 +207,4 @@ function main() {
 
 if (require.main === module) runMain(main);
 
-module.exports = { evaluateLint, LINT_REASON, OPT_OUT_LABEL, isUserFacing, isFragment, DEFAULT_BASE };
+module.exports = { evaluateLint, LINT_REASON, OPT_OUT_LABEL, isUserFacing, isFragment, DEFAULT_BASE, findPrFieldDrift };

package/scripts/check-alias-drift.cjs

@@ -4,9 +4,10 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const { FAMILIES, ALIAS_TABLE } = require('./lib/alias-drift-families.cjs');
 
 const ROOT = path.resolve(__dirname, '..');
-const aliasesPath = path.join(ROOT, 'gsd-core', 'bin', 'lib', 'command-aliases.cjs');
+const aliasesPath = path.join(ROOT, 'gsd-core', 'bin', 'lib', `${ALIAS_TABLE}.cjs`);
 
 function fail(message) {
   process.stderr.write(`${message}\n`);
@@ -36,48 +37,11 @@ function main() {
 
   const aliases = require(aliasesPath);
 
-  const families = [
-    {
-      commandAliases: 'STATE_COMMAND_ALIASES',
-      subcommands: 'STATE_SUBCOMMANDS',
-      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'state-command-router.cjs'),
-    },
-    {
-      commandAliases: 'VERIFY_COMMAND_ALIASES',
-      subcommands: 'VERIFY_SUBCOMMANDS',
-      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'verify-command-router.cjs'),
-    },
-    {
-      commandAliases: 'INIT_COMMAND_ALIASES',
-      subcommands: 'INIT_SUBCOMMANDS',
-      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'init-command-router.cjs'),
-    },
-    {
-      commandAliases: 'PHASE_COMMAND_ALIASES',
-      subcommands: 'PHASE_SUBCOMMANDS',
-      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'phase-command-router.cjs'),
-    },
-    {
-      commandAliases: 'PHASES_COMMAND_ALIASES',
-      subcommands: 'PHASES_SUBCOMMANDS',
-      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'phases-command-router.cjs'),
-    },
-    {
-      commandAliases: 'VALIDATE_COMMAND_ALIASES',
-      subcommands: 'VALIDATE_SUBCOMMANDS',
-      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'validate-command-router.cjs'),
-    },
-    {
-      commandAliases: 'ROADMAP_COMMAND_ALIASES',
-      subcommands: 'ROADMAP_SUBCOMMANDS',
-      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'roadmap-command-router.cjs'),
-    },
-    {
-      commandAliases: 'EVAL_COMMAND_ALIASES',
-      subcommands: 'EVAL_SUBCOMMANDS',
-      routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', 'eval-command-router.cjs'),
-    },
-  ];
+  const families = FAMILIES.map((family) => ({
+    commandAliases: family.commandAliases,
+    subcommands: family.subcommands,
+    routerPath: path.join(ROOT, 'gsd-core', 'bin', 'lib', `${family.router}.cjs`),
+  }));
 
   for (const family of families) {
     const commandAliases = aliases[family.commandAliases];

package/scripts/check-contract-drift.cjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+/**
+ * check-contract-drift.cjs
+ *
+ * Enforces that gsd-core/references/agent-contracts.md's `## Agent Registry`
+ * table stays in sync with reality:
+ *
+ *   1. The table itself must parse cleanly (no malformed rows).
+ *   2. Every agents/*.md file must have its fenced code blocks properly
+ *      closed (an unclosed fence makes in-fence marker detection unreliable).
+ *   3. Every marker an agent actually emits in-fence, and every marker the
+ *      registry declares for it, must agree (contractViolations' declared/
+ *      emitted checks) -- unless the row opts out via `kind:
+ *      artifact+query`/`structured-return`, in which case any emitted
+ *      marker is itself a violation (vestigial_marker).
+ *   4. Every `sentinel-match` row's declared markers must have at least one
+ *      exact-case consumer somewhere under gsd-core/workflows/, commands/,
+ *      or agents/ (excluding the producing agent's own file).
+ *   5. Registry roster coverage: every agents/*.md file has exactly one
+ *      row, every row names an agent file that exists
+ *      (agent_without_contract / duplicate_registry_row / unknown_producer),
+ *      and every file-shaped `Consumed by` entry resolves (unknown_consumer).
+ *   6. Read-tag arm: no `<files_to_read>` survives anywhere in the consumer
+ *      corpus (legacy_read_tag), and whenever a declared consumer emits
+ *      `<required_reading>` the producing agent's file must reference the
+ *      gate (read_tag_gate_missing).
+ *   7. Reverse direction: a workflow/command matching a quoted `## TOKEN`
+ *      no agent declares or emits is dispatch-on-phantom
+ *      (unmatched_consumer_token) — F9's shape from the consumer side.
+ *
+ * Exit 0 = clean. Exit 1 = violations (with diagnostics on stderr).
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+function resolveRoot(argv) {
+  const idx = argv.indexOf('--root');
+  if (idx === -1) return path.join(__dirname, '..');
+  const value = argv[idx + 1];
+  if (!value) {
+    throw new Error('check-contract-drift: --root requires a directory argument');
+  }
+  return path.resolve(value);
+}
+
+const ROOT           = resolveRoot(process.argv.slice(2));
+const CONTRACTS_FILE = path.join(ROOT, 'gsd-core', 'references', 'agent-contracts.md');
+const AGENTS_DIR      = path.join(ROOT, 'agents');
+const WORKFLOWS_DIR    = path.join(ROOT, 'gsd-core', 'workflows');
+const COMMANDS_DIR     = path.join(ROOT, 'commands');
+
+const {
+  extractMarkers,
+  parseAgentContracts,
+  contractViolations,
+  readTagViolations,
+  parseConsumedByCell,
+  unmatchedConsumerTokens,
+  sanitizeEcho,
+  REMEDIES,
+} = require('./command-contract-helpers.cjs');
+
+const { runMain } = require('./lib/cli-exit.cjs');
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function walkMarkdownFiles(dir, acc) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkMarkdownFiles(full, acc);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+function toRepoRelative(absPath) {
+  return path.relative(ROOT, absPath).split(path.sep).join('/');
+}
+
+/**
+ * referenceIncludes(content)
+ *
+ * Plain scan for `@~/.claude/gsd-core/references/*.md` tokens anywhere in an
+ * agent file's content -- inside an `<execution_context>` block (already
+ * covered structurally by `executionContextRefs` in command-contract-helpers,
+ * but a raw regex over the whole string picks those up too) and, just as
+ * importantly, OUTSIDE one: agents frequently point at a reference doc from
+ * plain prose (e.g. "See @~/.claude/gsd-core/references/planner-guidance.md
+ * for ...") rather than from the eager `<execution_context>` include list.
+ * An agent's completion-marker contract can be authored in such a reference
+ * file rather than the agent file itself -- gsd-planner declares
+ * `PLANNING COMPLETE` in its registry row, but the example heading itself
+ * lives in `gsd-core/references/planner-guidance.md`, which the agent only
+ * `@`-includes -- so the producer scan below must follow these includes to
+ * see markers an agent's contract legitimately delegates to a reference doc.
+ * Returns ROOT-relative paths (`gsd-core/references/foo.md`), de-duplicated.
+ */
+function referenceIncludes(content) {
+  const seen = new Set();
+  const re = /@~\/\.claude\/gsd-core\/references\/[A-Za-z0-9._-]+\.md/g;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    const relPath = 'gsd-core/references/' + m[0].slice('@~/.claude/gsd-core/references/'.length);
+    seen.add(relPath);
+  }
+  return [...seen];
+}
+
+function remedyFor(kind) {
+  return REMEDIES[kind] || 'review the registry row and agent file for drift';
+}
+
+// ─── run ─────────────────────────────────────────────────────────────────────
+
+function main() {
+  if (!fs.existsSync(CONTRACTS_FILE)) {
+    process.stderr.write(`\nERROR check-contract-drift: contracts file not found at ${toRepoRelative(CONTRACTS_FILE)}\n\n`);
+    return 1;
+  }
+
+  const contractsMd = fs.readFileSync(CONTRACTS_FILE, 'utf-8');
+  const { rows: registry, errors: parseErrors } = parseAgentContracts(contractsMd);
+
+  // knownMarkers: every marker string declared anywhere in the registry --
+  // extractMarkers only ever resolves a heading against this vocabulary, it
+  // never falls back to guessing a shape. Includes `(unconsumed: …)` entries
+  // so their declared↔emitted agreement is checked too.
+  const knownMarkers = new Set();
+  for (const row of registry) {
+    for (const m of row.completion_markers || []) knownMarkers.add(m);
+    for (const m of row.unconsumed_markers || []) knownMarkers.add(m);
+  }
+
+  // producerMarkers: agent -> [in-fence marker strings that matched knownMarkers]
+  // candidateMarkers: agent -> [in-fence marker-shaped headings NOT in knownMarkers,
+  //   deduped per marker — "emitted but undeclared" is a fact about the
+  //   marker, not about each line or file it appears in]
+  // agentTexts: agent -> file content CONCATENATED with every
+  // references/*.md file the agent @-includes, for the read-tag arm's gate
+  // check. The fold is load-bearing: planner/executor/phase-researcher
+  // deliver the MUST-Read gate via the shared mandatory-initial-read.md
+  // include, so the agent file alone would report a gate that actually
+  // arrives (the same producer-scope gap referenceIncludes() fixes for
+  // markers, one layer up).
+  const producerMarkers = new Map();
+  const candidateMarkers = new Map();
+  const agentTexts = new Map();
+  const unclosedFenceViolations = [];
+
+  const agentFiles = fs.existsSync(AGENTS_DIR)
+    ? fs.readdirSync(AGENTS_DIR).filter(f => f.endsWith('.md'))
+    : [];
+
+  for (const file of agentFiles) {
+    const agent = file.replace(/\.md$/, '');
+    const abs = path.join(AGENTS_DIR, file);
+    const content = fs.readFileSync(abs, 'utf-8');
+    // Single pass over the agent's @-included references: each file is read
+    // once and feeds BOTH the read-tag fold (agentTexts) and marker
+    // extraction (producer/candidate attribution).
+    const includeTexts = [];
+    for (const refRelPath of referenceIncludes(content)) {
+      try {
+        includeTexts.push(fs.readFileSync(path.join(ROOT, refRelPath), 'utf-8'));
+      } catch {
+        // include miss — lint-command-contract rule 4 owns @-ref existence
+      }
+    }
+    agentTexts.set(agent, [content, ...includeTexts].join('\n'));
+    const { markers, candidates, unclosedFence } = extractMarkers(agentTexts.get(agent), knownMarkers);
+    const inFenceMarkers = markers.filter(m => m.inFence).map(m => m.marker);
+    const inFenceCandidates = candidates.filter(m => m.inFence).map(m => m.marker);
+
+    producerMarkers.set(agent, inFenceMarkers);
+    candidateMarkers.set(agent, [...new Set(inFenceCandidates)]);
+
+    if (unclosedFence) {
+      unclosedFenceViolations.push({
+        kind: 'unclosed_fence',
+        agent,
+        marker: null,
+        detail: `${toRepoRelative(abs)} has an unterminated code fence`,
+      });
+    }
+  }
+
+  // consumerTexts: every *.md under gsd-core/workflows/, commands/, agents/
+  // — plus every file-shaped `Consumed by` entry that resolves on disk, so
+  // a row citing a reference doc or an ADR (e.g. intel-updater's
+  // docs/adr/22-plan-drift-guard.md) is validated against the real file and
+  // its text participates in consumer matching, not just workflows.
+  const consumerTexts = new Map();
+  const consumerDirs = [WORKFLOWS_DIR, COMMANDS_DIR, AGENTS_DIR];
+  for (const dir of consumerDirs) {
+    for (const abs of walkMarkdownFiles(dir, [])) {
+      consumerTexts.set(toRepoRelative(abs), fs.readFileSync(abs, 'utf-8'));
+    }
+  }
+  for (const row of registry) {
+    for (const rel of parseConsumedByCell(row.consumed_by)) {
+      if (consumerTexts.has(rel)) continue;
+      const abs = path.join(ROOT, rel);
+      try {
+        consumerTexts.set(rel, fs.readFileSync(abs, 'utf-8'));
+      } catch {
+        // absent — contractViolations reports it as unknown_consumer
+      }
+    }
+  }
+
+  const contractViolationsList = contractViolations({ registry, producerMarkers, candidateMarkers, consumerTexts });
+  const readTagViolationsList = readTagViolations({ registry, agentTexts, consumerTexts });
+  const reverseViolationsList = unmatchedConsumerTokens({ consumerTexts, vocabulary: knownMarkers });
+
+  const parseViolations = parseErrors.map(e => ({
+    kind: 'parse_error',
+    agent: null,
+    marker: null,
+    detail: `agent-contracts.md:${e.line} — ${e.reason}`,
+  }));
+
+  const allViolations = [
+    ...parseViolations,
+    ...unclosedFenceViolations,
+    ...contractViolationsList,
+    ...readTagViolationsList,
+    ...reverseViolationsList,
+  ];
+
+  const agentCount = registry.length;
+  const markerCount = registry.reduce((n, r) => n + (r.completion_markers || []).length, 0);
+
+  // --json: the typed surface tests consume (CONTRIBUTING "Raw Text
+  // Matching" rule — the human formatter below is for operators only).
+  if (process.argv.includes('--json')) {
+    console.log(
+      JSON.stringify({
+        check: 'check-contract-drift',
+        status: allViolations.length === 0 ? 'ok' : 'violations',
+        agents: agentCount,
+        markers: markerCount,
+        violations: allViolations.map((v) => ({
+          kind: v.kind,
+          agent: v.agent ?? null,
+          marker: v.marker ?? null,
+          detail: sanitizeEcho(v.detail),
+        })),
+      }),
+    );
+    return allViolations.length === 0 ? 0 : 1;
+  }
+
+  if (allViolations.length === 0) {
+    console.log(`ok check-contract-drift: ${agentCount} agents, ${markerCount} markers, 0 violations`);
+    return 0;
+  }
+
+  // group by violation kind
+  const byKind = new Map();
+  for (const v of allViolations) {
+    if (!byKind.has(v.kind)) byKind.set(v.kind, []);
+    byKind.get(v.kind).push(v);
+  }
+
+  process.stderr.write(
+    `\nERROR check-contract-drift: ${allViolations.length} violation(s) across ${byKind.size} kind(s)\n\n`,
+  );
+
+  for (const [kind, violations] of byKind) {
+    process.stderr.write(`  ${kind} (${violations.length}):\n`);
+    for (const v of violations) {
+      const agentLabel = v.agent ? sanitizeEcho(v.agent) : '(registry)';
+      const markerLabel = v.marker ? ` marker "${sanitizeEcho(v.marker)}"` : '';
+      process.stderr.write(`    - ${agentLabel}${markerLabel}: ${sanitizeEcho(v.detail)}\n`);
+      process.stderr.write(`      remedy: ${remedyFor(kind)}\n`);
+    }
+    process.stderr.write('\n');
+  }
+
+  process.stderr.write('See gsd-core/references/agent-contracts.md for the registry contract spec.\n\n');
+
+  return 1;
+}
+
+runMain(main);