@opengsd/gsd-core 1.8.0 → 1.9.1

package/scripts/gen-emitted-baseline.cjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * gen-emitted-baseline.cjs — publishes the emitted-baseline artifact the
+ * differential attribution check reads via `resolveBaseline()` (#2724, ADR-2719 §5).
+ *
+ * ## Why this exists
+ *
+ * Phase 3 (#2723) built `resolveBaseline()` (tests/helpers/emitted-baseline.cjs) and its
+ * cache-key staleness discipline, but nothing produced the artifact it reads — the
+ * dual-run window instead read the baseline straight off the committed golden fixtures
+ * at the base ref (`baselineManifestsAtRef`). Phase 4 deletes those fixtures, so
+ * something has to build and publish `{version, sha, manifests, sizes}` for real.
+ *
+ * ## What it does
+ *
+ * Builds the emitted manifest set (19 real installer spawns) and the workflow/agent size
+ * maps for the tree at `--dir <path>` (default: THIS script's own checkout — i.e.
+ * whatever commit is currently checked out where `gen-emitted-baseline.cjs` itself
+ * lives). Writes the result to `--out <path>` (default `.gsd-cache/emitted-baseline.json`).
+ *
+ * `--dir` decouples "which copy of this script runs" from "which tree gets measured"
+ * (#2767). The MEASUREMENT SCHEMA — this script, and the `currentManifests`/
+ * `currentSizes`/`buildParityManifest` functions it calls — always comes from wherever
+ * `gen-emitted-baseline.cjs` itself is being run from (relative `require`s resolve
+ * there); only the tree being measured (which `bin/install.js` gets spawned, which
+ * `hooks/`/`gsd-core/workflows/`/`agents/` get read) moves to `--dir`. That is what lets
+ * a differential apply ONE definition of "the emitted manifest" to two different
+ * commits and stay comparable even as that definition evolves — see
+ * `tests/helpers/emitted-runtime.cjs`'s `buildBaselineAtRef` for the caller that
+ * exercises this for real, and why it must NOT run the `--dir` tree's own copy of this
+ * script (which may be an older version, or — for any base ref that predates the PR
+ * that added this script at all — may not exist there yet).
+ *
+ * ## Callers
+ *
+ *   1. CI's push-to-`next` job runs this straight after `next` advances (no `--dir`,
+ *      measuring its own checkout), then uploads `.gsd-cache/emitted-baseline.json` as a
+ *      cache entry keyed on the merge sha (.github/workflows/test.yml,
+ *      `publish-emitted-baseline` job).
+ *   2. `tests/emitted-attribution.test.cjs`'s real-tree test passes
+ *      `buildBaselineAtRef` (tests/helpers/emitted-runtime.cjs) to `resolveBaseline()`
+ *      as the `buildFallback` for a cache miss: it checks out `base` into a throwaway
+ *      `git worktree`, symlinks in `node_modules` and runs `npm run build:lib` there
+ *      (this script and the test helpers are Node-builtins-only per CONTRIBUTING.md's
+ *      "No external dependencies in core", but `tests/helpers/install-shared.cjs`
+ *      requires the TSC-compiled, gitignored `gsd-core/bin/lib/*.cjs`, so that one build
+ *      step is unavoidable), then spawns THIS repo's OWN `gen-emitted-baseline.cjs`
+ *      with `--dir <worktree> --out <tmp>` and reads the artifact back.
+ *
+ * Every git subprocess is bounded (CLAUDE.md → KNOWN DEFECTS: unbounded subprocesses
+ * hang CI silently).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { runMain, ExitError } = require('./lib/cli-exit.cjs');
+const { BUILD_SCRIPT } = require('../tests/helpers/install-shared.cjs');
+const { currentManifests, currentSizes, git } = require('../tests/helpers/emitted-runtime.cjs');
+const { BASELINE_VERSION } = require('../tests/helpers/emitted-baseline.cjs');
+
+const REPO_ROOT = path.join(__dirname, '..');
+const DEFAULT_OUT = path.join(REPO_ROOT, '.gsd-cache', 'emitted-baseline.json');
+
+// Reuses emitted-runtime.cjs's `git()` (not a local execFileSync) so the
+// `-c safe.directory=<dir>` fix for the remote runner's dubious-ownership
+// mount (#2767) has exactly one source of truth — see that module's
+// `safeDirArgs` doc comment.
+function resolveHeadSha(cwd) {
+  return git(['rev-parse', 'HEAD'], { cwd }).trim();
+}
+
+function parseArgs(argv) {
+  let out = DEFAULT_OUT;
+  let dir = REPO_ROOT;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--out') {
+      out = argv[i + 1];
+      i++;
+    } else if (argv[i] === '--dir') {
+      dir = argv[i + 1];
+      i++;
+    } else {
+      throw new ExitError(2, `gen-emitted-baseline: unknown argument "${argv[i]}"`);
+    }
+  }
+  if (!out || typeof out !== 'string') {
+    throw new ExitError(2, 'gen-emitted-baseline: --out requires a path');
+  }
+  if (!dir || typeof dir !== 'string') {
+    throw new ExitError(2, 'gen-emitted-baseline: --dir requires a path');
+  }
+  return {
+    out: path.isAbsolute(out) ? out : path.join(process.cwd(), out),
+    dir: path.isAbsolute(dir) ? dir : path.join(process.cwd(), dir),
+  };
+}
+
+async function main() {
+  const { out, dir } = parseArgs(process.argv.slice(2));
+
+  if (!fs.existsSync(dir)) {
+    throw new ExitError(1, `gen-emitted-baseline: --dir "${dir}" does not exist`);
+  }
+
+  const sha = resolveHeadSha(dir);
+  if (!/^[0-9a-f]{40}$/.test(sha)) {
+    throw new ExitError(1, `gen-emitted-baseline: HEAD of "${dir}" did not resolve to a 40-hex sha: ${sha}`);
+  }
+
+  // hooks/dist is gitignored and built; a scoped CI checkout may not have run
+  // build:hooks yet. Idempotent, mirrors the real-tree test. Built INSIDE `dir` — the
+  // MEASURED tree's own hooks/ source, not this script's — so a `--dir` pointed at a
+  // different checkout (e.g. a base-ref worktree) reflects that checkout's hooks, not
+  // the caller's. `dir === REPO_ROOT` (the default, no `--dir`) collapses to the
+  // pre-#2767 behavior of building this own repo's hooks/dist.
+  const buildScript = dir === REPO_ROOT ? BUILD_SCRIPT : path.join(dir, 'scripts', 'build-hooks.js');
+  execFileSync(process.execPath, [buildScript], { cwd: dir, encoding: 'utf-8', stdio: 'pipe', timeout: 120_000 });
+
+  // The measurement SCHEMA (currentManifests/currentSizes/buildParityManifest) is
+  // always THIS script's own — only the tree being measured moves with `repoRoot`.
+  const manifests = currentManifests({ repoRoot: dir });
+  const sizes = currentSizes({ repoRoot: dir });
+
+  const artifact = { version: BASELINE_VERSION, sha, manifests, sizes };
+
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+
+  const familyCount = Object.keys(manifests).length;
+  const sizeCount = Object.keys(sizes).length;
+  process.stdout.write(
+    `gen-emitted-baseline: wrote ${out} (dir=${dir}, sha=${sha.slice(0, 12)}, ${familyCount} families, ${sizeCount} sized files)\n`,
+  );
+  return 0;
+}
+
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = { parseArgs, resolveHeadSha, DEFAULT_OUT, REPO_ROOT };

package/scripts/gen-registry.cjs

@@ -2,10 +2,14 @@
 'use strict';
 
 /**
- * scripts/gen-registry.cjs — generates docs/registries/capability-registry.md
- * (and, once PR2 ships docs/registries/eos.json, docs/registries/eos-registry.md)
- * from the corresponding source JSON, via registry-schema.cjs#renderMarkdown.
- * Issue #2182.
+ * scripts/gen-registry.cjs — generates docs/registries/capability-registry.md,
+ * docs/registries/eos-registry.md, and docs/registries/reviewer-registry.md
+ * from their corresponding source JSON, via registry-schema.cjs#renderMarkdown.
+ * Issue #2182 (capability/eos); issue #2904 (reviewer).
+ *
+ * eos.json and reviewers.json are both OPTIONAL sources (`SOURCES[].optional`)
+ * — an absent one is skipped silently. capabilities.json is the primary
+ * source and is never optional.
  *
  * NOT to be confused with `scripts/gen-capability-registry.cjs`: that script
  * generates the RUNTIME capability manifest consumed by the host at runtime
@@ -34,7 +38,8 @@ const { renderMarkdown } = require('./registry-schema.cjs');
 
 const SOURCES = [
   { type: 'capability', jsonFile: 'capabilities.json', mdFile: 'capability-registry.md' },
-  { type: 'eos', jsonFile: 'eos.json', mdFile: 'eos-registry.md' },
+  { type: 'eos', jsonFile: 'eos.json', mdFile: 'eos-registry.md', optional: true },
+  { type: 'reviewer', jsonFile: 'reviewers.json', mdFile: 'reviewer-registry.md', optional: true },
 ];
 
 /**
@@ -57,14 +62,16 @@ function getRegistriesDir() {
  * Render the markdown for a single registry type from its committed source
  * JSON.
  *
- * Only `eos.json` is optional (pre-PR2, before that source JSON ships) —
- * an absent `eos.json` returns null and callers treat that as "nothing to
- * do". `capabilities.json` is the primary registry source: a missing
- * `capabilities.json` is ALWAYS an error (never a silent "up to date"
- * pass), mirroring the type distinction in `scripts/validate-registry.cjs`
- * (`type === 'eos' && !exists → continue`).
+ * Optionality is a per-source data flag (`SOURCES[].optional`), not a
+ * hardcoded type literal: `eos.json` (pre-PR2) and `reviewers.json` (issue
+ * #2904) are both optional — an absent source JSON returns null and callers
+ * treat that as "nothing to do". `capabilities.json` is still the primary
+ * registry source and is never optional: a missing `capabilities.json` is
+ * ALWAYS an error (never a silent "up to date" pass), mirroring the same
+ * `optional` flag in `scripts/validate-registry.cjs`
+ * (`optional && !exists → continue`).
  *
- * @param {'capability'|'eos'} type
+ * @param {'capability'|'eos'|'reviewer'} type
  * @returns {string|null}
  */
 function renderFor(type) {
@@ -73,14 +80,31 @@ function renderFor(type) {
 
   const jsonPath = path.join(getRegistriesDir(), source.jsonFile);
   if (!fs.existsSync(jsonPath)) {
-    if (type === 'eos') return null;
+    if (source.optional) return null;
     throw new ExitError(
       1,
       `${source.jsonFile} does not exist at ${jsonPath}. Run:\n  node scripts/gen-registry.cjs --write\n(after adding docs/registries/${source.jsonFile})`,
     );
   }
 
-  const entries = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+  // A malformed source JSON must surface as an actionable CLI error, not an
+  // unhandled SyntaxError with a raw Node stack trace — mirrors
+  // scripts/validate-registry.cjs#validateFile's try/catch around JSON.parse.
+  let entries;
+  try {
+    entries = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+  } catch (err) {
+    throw new ExitError(1, `${source.jsonFile} is not valid JSON at ${jsonPath}: ${err.message}`);
+  }
+
+  // Mirrors validate-registry.cjs's explicit non-array rejection: a source
+  // JSON that parses to a non-array (object, string, etc.) would otherwise
+  // throw an opaque TypeError from `[...entries].sort()` in renderMarkdown,
+  // or silently mis-render for an iterable-but-wrong-shape value like a string.
+  if (!Array.isArray(entries)) {
+    throw new ExitError(1, `${source.jsonFile} must be a JSON array of entries`);
+  }
+
   return renderMarkdown(entries, { type, sourceFile: source.jsonFile });
 }
 
@@ -91,7 +115,7 @@ function main() {
 
   for (const { type, mdFile } of SOURCES) {
     const rendered = renderFor(type);
-    if (rendered === null) continue; // source JSON absent (eos.json before PR2)
+    if (rendered === null) continue; // source JSON absent and optional (eos.json before PR2 / reviewers.json)
 
     const mdPath = path.join(registriesDir, mdFile);
 

package/scripts/lint-compiled-artifact-sync.cjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * lint-compiled-artifact-sync — fail when a *tracked* compiled artifact under
+ * gsd-core/bin/lib/ has drifted from its src/*.cts source.
+ *
+ * ADR-457 compiles src/*.cts to gsd-core/bin/lib/*.cjs at build time and expects
+ * those artifacts to be gitignored. Most are (see .gitignore). A handful are
+ * still tracked because the migration that moved the module into src/ did not
+ * also add the emitted .cjs to .gitignore. While a compiled artifact remains
+ * tracked, the committed bytes are what ships to anyone who reads the repo
+ * without building — so they must match the source.
+ *
+ * #2653: gsd-core/bin/lib/api-coverage.cjs sat four days behind its .cts after
+ * PR #2551 changed the source without regenerating the artifact, shipping a
+ * module that silently lacked the entire #2366 fix while CI stayed green.
+ *
+ * This check is deliberately regime-agnostic: it asserts a property of whatever
+ * is tracked right now. If the remaining artifacts are later untracked and
+ * gitignored (the ADR-457 end state), the tracked set becomes empty and this
+ * script passes trivially — no edit required.
+ *
+ * Usage: node scripts/lint-compiled-artifact-sync.cjs [--check]
+ * Exit 0 when every tracked artifact matches a fresh compile; 1 otherwise.
+ */
+
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const LIB_DIR = path.join('gsd-core', 'bin', 'lib');
+const SRC_DIR = 'src';
+
+/** Frozen reason codes so tests assert on structure, not prose. */
+const REASON = Object.freeze({
+  OK: 'ok_artifacts_in_sync',
+  DRIFTED: 'fail_artifact_drifted',
+  BUILD_FAILED: 'fail_build_failed',
+  MISSING_EMIT: 'fail_missing_emit',
+});
+
+function git(args) {
+  return execFileSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8' });
+}
+
+/**
+ * Tracked .cjs files under gsd-core/bin/lib/ that have a matching src/*.cts.
+ * Uses `git ls-files` so the set is derived from what git actually tracks
+ * rather than a hand-maintained list that could itself drift.
+ */
+function trackedCompiledArtifacts() {
+  const tracked = git(['ls-files', LIB_DIR]).split('\n').filter((l) => l.endsWith('.cjs'));
+  const out = [];
+  for (const rel of tracked) {
+    const stem = path.basename(rel, '.cjs');
+    const subdir = path.dirname(path.relative(LIB_DIR, rel));
+    const srcRel = path.join(SRC_DIR, subdir === '.' ? '' : subdir, `${stem}.cts`);
+    if (fs.existsSync(path.join(REPO_ROOT, srcRel))) out.push({ artifact: rel, source: srcRel });
+  }
+  return out.sort((a, b) => (a.artifact < b.artifact ? -1 : a.artifact > b.artifact ? 1 : 0));
+}
+
+/** Compile the whole project to a throwaway outDir so the work tree is untouched. */
+function compileToTemp() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-artifact-sync-'));
+  try {
+    execFileSync(
+      process.execPath,
+      [
+        path.join(REPO_ROOT, 'node_modules', 'typescript', 'bin', 'tsc'),
+        '-p', path.join(REPO_ROOT, 'tsconfig.build.json'),
+        '--outDir', tmp,
+        // A throwaway outDir must not reuse the in-tree incremental state, or
+        // tsc skips emit for files it believes are already current.
+        '--incremental', 'false',
+        '--tsBuildInfoFile', 'null',
+      ],
+      { cwd: REPO_ROOT, encoding: 'utf8', stdio: 'pipe' },
+    );
+    return { ok: true, dir: tmp };
+  } catch (err) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    const detail = [err.stdout, err.stderr].filter(Boolean).join('\n').trim();
+    return { ok: false, detail };
+  }
+}
+
+function main() {
+  const pairs = trackedCompiledArtifacts();
+  if (pairs.length === 0) {
+    console.log('ok compiled-artifact-sync: no tracked compiled artifacts (ADR-457 end state)');
+    return 0;
+  }
+
+  const build = compileToTemp();
+  if (!build.ok) {
+    console.error(`FAIL compiled-artifact-sync: ${REASON.BUILD_FAILED}`);
+    console.error(build.detail);
+    return 1;
+  }
+
+  const drifted = [];
+  const missing = [];
+  try {
+    for (const { artifact, source } of pairs) {
+      const fresh = path.join(build.dir, path.relative(LIB_DIR, artifact));
+      if (!fs.existsSync(fresh)) { missing.push({ artifact, source }); continue; }
+      const a = fs.readFileSync(path.join(REPO_ROOT, artifact));
+      const b = fs.readFileSync(fresh);
+      if (!a.equals(b)) drifted.push({ artifact, source, committed: a.length, expected: b.length });
+    }
+  } finally {
+    fs.rmSync(build.dir, { recursive: true, force: true });
+  }
+
+  if (missing.length > 0) {
+    console.error(`FAIL compiled-artifact-sync: ${REASON.MISSING_EMIT}`);
+    for (const m of missing) console.error(`  ${m.artifact} — no emit produced from ${m.source}`);
+    return 1;
+  }
+
+  if (drifted.length > 0) {
+    console.error(`FAIL compiled-artifact-sync: ${REASON.DRIFTED}`);
+    for (const d of drifted) {
+      console.error(`  ${d.artifact} (${d.committed} bytes) != compile of ${d.source} (${d.expected} bytes)`);
+    }
+    console.error('');
+    console.error('The committed artifact is what ships to anyone reading the repo without');
+    console.error('building, so it must match its source. Fix with:');
+    console.error('  npm run build:lib && git add ' + drifted.map((d) => d.artifact).join(' '));
+    console.error('');
+    console.error('Alternatively, per ADR-457 these artifacts are meant to be gitignored —');
+    console.error('untracking them (git rm --cached + .gitignore) also resolves this.');
+    return 1;
+  }
+
+  console.log(`ok compiled-artifact-sync: ${pairs.length} tracked artifact(s) match their source`);
+  return 0;
+}
+
+if (require.main === module) process.exitCode = main();
+
+module.exports = { REASON, trackedCompiledArtifacts };

package/scripts/lint-emitted-drift-ack.cjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-emitted-drift-ack — refuse to merge a broken emitted-drift acknowledgment (#2789).
+ *
+ * The ack document is read from TWO sides: the working tree (`readAckFile`) and the BASE
+ * REF (`readAckFileAtRef`), because an entry already present at the base is spent and may
+ * no longer clear a delta. The base-side read fails LOUDLY on a document it cannot parse
+ * — it has to, since silently inheriting nothing would leave every entry able to consume
+ * a delta, which is the pre-#2789 gate.
+ *
+ * That makes a corrupt document ON THE BASE BRANCH unusually expensive: it reds every PR
+ * that carries an ack until someone repairs it. The real-tree test avoids an outright
+ * deadlock (a tree with no ack never consults the base, so the repair PR still lands),
+ * but the cheaper answer is to never let a broken document reach the base at all. This
+ * runs in `lint:ci`, so a PR carrying one cannot go green and cannot merge.
+ *
+ * This validator is DELIBERATELY STANDALONE. `scripts/` ships in the npm package and
+ * `tests/` does not (package.json `files`), so requiring the gate's own `parseAck` from
+ * here would be a MODULE_NOT_FOUND in the published package. The duplication is bounded
+ * by a parity test — `tests/emitted-attribution.test.cjs` runs both surfaces over one
+ * corpus and fails if they ever disagree about what is schema-valid.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ACK_VERSION = 1;
+const ACK_REPO_PATH = 'tests/emitted-drift-ack.json';
+const REPO_ROOT = path.join(__dirname, '..');
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * Validate an ack document's raw text.
+ *
+ * `schemaErrors` are the ones that must agree with the gate's `parseAck` — the shape
+ * contract. `policyErrors` are lint-only rules that `parseAck` deliberately does NOT
+ * enforce, because they are about what may be COMMITTED rather than what may be parsed:
+ * a present-but-entryless document parses fine and signals nothing, so it must be deleted
+ * rather than left behind.
+ *
+ * @param {string|null} raw  file contents, or null when the file is absent
+ * @returns {{ schemaErrors: string[], policyErrors: string[], ok: boolean }}
+ */
+function validateAckText(raw) {
+  const schemaErrors = [];
+  const policyErrors = [];
+  const done = () => ({ schemaErrors, policyErrors, ok: schemaErrors.length === 0 && policyErrors.length === 0 });
+
+  if (raw === null) return done(); // absent is the healthy steady state
+
+  if (raw.trim() === '') {
+    schemaErrors.push(`${ACK_REPO_PATH} is present but empty`);
+    return done();
+  }
+
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (err) {
+    schemaErrors.push(`${ACK_REPO_PATH} is not valid JSON: ${err.message}`);
+    return done();
+  }
+
+  // A document that is literally `null` is POLICY, not schema. The gate's `parseAck` uses
+  // `null` as its "absent == no acks" sentinel, so it reads such a file as legal and
+  // harmless — and the parity test holds us to that. It is still not something to commit:
+  // it declares nothing, so the remedy is the same as an entryless document.
+  if (doc === null) {
+    policyErrors.push(
+      `${ACK_REPO_PATH} contains "null" and declares no acknowledgments. Delete the file — `
+      + 'the healthy steady state is no file at all.',
+    );
+    return done();
+  }
+
+  if (!isPlainObject(doc)) {
+    schemaErrors.push(
+      `${ACK_REPO_PATH}: must be a JSON object, got ${Array.isArray(doc) ? 'array' : typeof doc}`,
+    );
+    return done();
+  }
+
+  if (doc.version !== undefined && doc.version !== ACK_VERSION) {
+    schemaErrors.push(
+      `${ACK_REPO_PATH}: unsupported version ${JSON.stringify(doc.version)} (expected ${ACK_VERSION})`,
+    );
+  }
+
+  const paths = doc.paths;
+  if (paths !== undefined && !isPlainObject(paths)) {
+    schemaErrors.push(`${ACK_REPO_PATH}: "paths" must be an object of <emitted path> -> { reason }`);
+    return done();
+  }
+
+  const entries = paths === undefined ? [] : Object.entries(paths);
+  for (const [rel, value] of entries) {
+    const reason = isPlainObject(value) ? value.reason : value;
+    if (typeof reason !== 'string' || reason.trim() === '') {
+      schemaErrors.push(`${ACK_REPO_PATH}: ack for "${rel}" has no non-empty "reason"`);
+    }
+  }
+
+  // Lint-only. An entryless document parses cleanly and acknowledges nothing, so it is
+  // pure confusion on the base branch — and it is exactly what a contributor leaves
+  // behind after removing the last entry by hand.
+  if (entries.length === 0) {
+    policyErrors.push(
+      `${ACK_REPO_PATH} is present but declares no acknowledgments. Delete the file — an `
+      + 'empty one signals nothing, and the healthy steady state is no file at all.',
+    );
+  }
+
+  return done();
+}
+
+function readIfPresent(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+}
+
+function main() {
+  const file = path.join(REPO_ROOT, ...ACK_REPO_PATH.split('/'));
+  const result = validateAckText(readIfPresent(file));
+  const all = [...result.schemaErrors, ...result.policyErrors];
+
+  if (all.length) {
+    console.error(`lint-emitted-drift-ack: ${all.length} problem(s) in ${ACK_REPO_PATH}\n`);
+    for (const e of all) console.error(`  - ${e}`);
+    console.error(
+      '\nThis blocks the merge on purpose. The base-side reader fails loudly on a document '
+      + 'it cannot parse, so a broken one on the base branch reds every PR that carries an '
+      + 'acknowledgment. Fix or delete the file here, where it is cheap.',
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(
+    fs.existsSync(file)
+      ? `ok lint-emitted-drift-ack: ${ACK_REPO_PATH} is well-formed`
+      : `ok lint-emitted-drift-ack: ${ACK_REPO_PATH} absent (the healthy steady state)`,
+  );
+}
+
+if (require.main === module) main();
+
+module.exports = { validateAckText, ACK_VERSION, ACK_REPO_PATH };

package/scripts/lint-fix-has-regression-test.cjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-fix-has-regression-test.cjs — gate: every fix(#NNNN) commit must
+ * include at least one behavioral test file (tests/*.test.cjs) that is NOT
+ * an auto-generated fixture/baseline.
+ *
+ * ## Why
+ *
+ * CONTRIBUTING.md:47: "Fix it. Write a test that would have caught the bug."
+ * CLAUDE.md: "Regression Protocol: Write the regression test first."
+ *
+ * Three merged PRs shipped without regression tests because the golden-fixture
+ * regeneration (20+ files under tests/) camouflaged the absence of real
+ * *.test.cjs changes. This gate makes the rule machine-enforced.
+ *
+ * ## What this enforces
+ *
+ * For every commit in `git log origin/next..HEAD` whose subject matches
+ * /^fix\(#\d+\)/ or /^feat\(#\d+\)/, the cumulative diff must include at
+ * least one file under tests/ matching /\.test\.cjs$/ that is NOT:
+ *   - under tests/fixtures/
+ *   - under tests/install-tree/
+ *   - a *-baseline.json file
+ *
+ * If the filtered list is empty, the gate fails with a message naming the
+ * fix commits and directing the author to add a regression test.
+ *
+ * ## Overrides
+ *
+ * Set GSD_SKIP_REGRESSION_TEST_GATE=1 for legitimate exceptions (e.g. a
+ * pure-config or pure-refactor PR where no behavioral test is possible).
+ * This env var is auditable in CI logs.
+ */
+
+const { execSync } = require('child_process');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const FIX_OR_FEAT_RE = /^(?:fix|feat)\(#(\d+)\)/;
+
+const EXCLUDE_PATTERNS = [
+  /tests[\\/]fixtures[\\/]/,
+  /tests[\\/]install-tree[\\/]/,
+  /-baseline\.json$/,
+];
+
+function isRealTestFile(filePath) {
+  if (!filePath.includes('tests/')) return false;
+  if (!/\.test\.cjs$/.test(filePath)) return false;
+  return !EXCLUDE_PATTERNS.some((re) => re.test(filePath));
+}
+
+function getFixCommits(baseRef) {
+  const log = execSync(
+    `git log ${baseRef}..HEAD --format='%H%x09%s' --no-merges`,
+    { encoding: 'utf8', timeout: 10000 },
+  );
+  return log
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const [sha, subject] = line.split('\t');
+      const match = subject.match(FIX_OR_FEAT_RE);
+      return match ? { sha: sha.slice(0, 12), subject, issue: match[1] } : null;
+    })
+    .filter(Boolean);
+}
+
+function getChangedTestFiles(baseRef) {
+  const diff = execSync(
+    `git diff ${baseRef}...HEAD --name-only --no-merges`,
+    { encoding: 'utf8', timeout: 10000 },
+  );
+  return diff
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .filter(isRealTestFile);
+}
+
+function main() {
+  if (process.env.GSD_SKIP_REGRESSION_TEST_GATE === '1') {
+    console.log('lint-fix-has-regression-test: SKIPPED (GSD_SKIP_REGRESSION_TEST_GATE=1)');
+    return;
+  }
+
+  const baseRef = process.env.GSD_REGRESSION_GATE_BASE || 'origin/next';
+
+  let fixCommits;
+  try {
+    fixCommits = getFixCommits(baseRef);
+  } catch {
+    console.log(`lint-fix-has-regression-test: no fix/feat commits found vs ${baseRef}, skipping`);
+    return;
+  }
+
+  if (fixCommits.length === 0) {
+    console.log('lint-fix-has-regression-test: no fix/feat commits, passing');
+    return;
+  }
+
+  let testFiles;
+  try {
+    testFiles = getChangedTestFiles(baseRef);
+  } catch {
+    testFiles = [];
+  }
+
+  if (testFiles.length === 0) {
+    const commitList = fixCommits
+      .map((c) => `  ${c.sha} ${c.subject}`)
+      .join('\n');
+    throw new ExitError(1,
+      `lint-fix-has-regression-test: ${fixCommits.length} fix/feat commit(s) but ZERO behavioral test files (*.test.cjs) in the diff.\n` +
+      `Auto-generated fixtures (tests/fixtures/, *-baseline.json) do NOT count.\n\n` +
+      `Fix commits:\n${commitList}\n\n` +
+      `CONTRIBUTING.md:47: "Write a test that would have caught the bug."\n` +
+      `Add a regression test to an existing tests/*.test.cjs file, or set ` +
+      `GSD_SKIP_REGRESSION_TEST_GATE=1 if no behavioral test is possible (auditable in CI).`
+    );
+  }
+
+  console.log(
+    `lint-fix-has-regression-test: PASS — ${fixCommits.length} fix/feat commit(s), ` +
+    `${testFiles.length} behavioral test file(s): ${testFiles.join(', ')}`
+  );
+}
+
+runMain(main);

package/scripts/lint-resolution-provenance.cjs

@@ -56,6 +56,15 @@ const REGISTRY = [
     sourceFile: 'src/init.cts',
     testFile: 'tests/agent-skills.test.cjs',
   },
+  {
+    // Registered by #1880 (ADR-1411 amendment "corrupt is not absent"). Until
+    // this entry existed the config-loader seam carried the provenance contract
+    // with nothing guarding it, so a regression that collapsed configured_empty
+    // back into not_configured would have shipped silently.
+    verb: 'config-loader',
+    sourceFile: 'src/config-loader.cts',
+    testFile: 'tests/config-loader.test.cjs',
+  },
 ];
 
 // Markers that MUST appear in every registered verb's test file.