paperlint 2.0.0

package/hooks/paper-status-gates.hook.mjs

@@ -0,0 +1,156 @@
+/**
+ * paper-status-gates — a PostToolUse react: editing a paper's source surfaces that paper's
+ * readiness verdict and its UNRUN GATES, unprompted.
+ *
+ * A ☐ against study-accepted / pc-panel / harden / verify-citations is a HOLE, not an
+ * "anti-churn" skip: a session that skipped three of them had the panel come back with real
+ * must-fixes. Advisory, never blocks, always exits 0 — a `react`'s type has no `deny`.
+ *
+ * ── WHY IT WAS WORTH SURFACING AT ALL ───────────────────────────────────────
+ * The checker PARSED the verdict line (to test it was not a bare percentage) and never PRINTED
+ * it, so the one fact its author kept asking for by hand was the one thing the tooling reliably
+ * withheld. A status file nobody is shown is a status file nobody reads.
+ *
+ * ── THE PURE / IMPURE LINE, AND WHERE IT REALLY FALLS ───────────────────────
+ * An earlier header claimed this half "READS A FILE and interpolates its contents, and a vigiles
+ * `react` is a pure function — it cannot", and called that the honest boundary of the closed
+ * vocabulary. That reading was one step too pessimistic. The boundary is real, but it falls
+ * between DECIDING and DOING, not between "hook" and "shell": deciding whether this edit
+ * concerns a paper, and WHICH one, is pure and belongs here; reading that paper's status file
+ * and running the checker is a tool, and `run()` is how a react invokes one.
+ *
+ * ── WHY THE DIRECTORY NAME IS VALIDATED BEFORE IT REACHES A COMMAND ─────────
+ * `run()` takes a string AND IT GOES THROUGH A SHELL — measured 2026-09-12: a `$(…)` inside a
+ * `run()` command substitutes. This one embeds a path taken from the event, so the name is
+ * extracted by an anchored pattern and accepted only if it is `[A-Za-z0-9._-]+` — no slash, no
+ * space, no shell metacharacter can survive. The shell predecessor got this incidentally, via a
+ * `grep -oE`; here it is explicit, because "incidentally safe" is how it stops being safe.
+ *
+ * 🔴 THE `(?:^|\/)` IS NOT DECORATION, AND LEAVING IT OUT KILLED THIS HOOK ONCE. The first
+ * version anchored the papers root at `^`, which passed every test in the harness — because the
+ * harness's own edit helper builds a RELATIVE path. The live harness sends an ABSOLUTE one.
+ * Measured against the real runtime:
+ *
+ *   file_path "<root>/<paper>/paper.md"                → fires
+ *   file_path "/abs/path/to/repo/<root>/<paper>/…"      → SILENT
+ *
+ * So the hook would have been dead in production and green in the tests: precisely the
+ * false-confidence class this whole exercise is about, reintroduced while converting a hook away
+ * from it. The shell version was accidentally immune — it grepped the raw payload with no anchor
+ * at all. The harness now sends BOTH spellings for every case.
+ *
+ * The boundary is still required (`^` or `/`), so a directory merely ENDING in the root's last
+ * segment cannot smuggle a match.
+ *
+ * ── WHAT THIS HOOK'S OUTPUT DOES *NOT* DO, measured and named ───────────────
+ * ⚠️ A `run()` reaction's output is passed through RAW — 0 bytes of `hookSpecificOutput` on
+ * stdout, the tool's own text on stderr (measured 2026-09-12: 1 184 bytes of stderr, 0 of
+ * stdout). Only a `notice` on an injectable event becomes `additionalContext`. So this hook's
+ * findings reach a HUMAN reading the transcript's debug output, not the model's context. That is
+ * a property of the reaction KIND, not a bug here, and it is the reason the static half lives in
+ * `paper-skills-nudge` as a `notice` instead: that one does land.
+ *
+ * ── WHY `.mjs` AND NOT A `.hook.ts` SPEC ────────────────────────────────────
+ * See `paper-edit-guard.hook.mjs`: a `.ts` hook reached through `node_modules` does not load,
+ * and a consumer-side thin spec importing this logic is refused by `vigiles compile` and can
+ * never be re-stamped. Both halves measured there.
+ */
+import {
+  experimental_defineReact,
+  tools,
+  provide,
+  run,
+  nothing,
+} from "vigiles/hook";
+
+/** The key every carrier of this package reads its consumer-specific settings from. */
+export const CONFIG_KEY = "paperlint";
+/** The key's name before 2.0.0 — still read, a copy of `lib/paper-config.mjs`. */
+export const LEGACY_CONFIG_KEY = "research-paper-pipeline";
+/** The default. A consumer that declares nothing is assumed to keep papers in `papers/`. */
+export const DEFAULT_PAPERS_ROOT = "papers";
+/**
+ * The field under CONFIG_KEY that names the papers directory, and its old name. A copy of the
+ * constants in `lib/paper-config.mjs` (a hook may import nothing but `vigiles/hook`);
+ * `lib/paper-config.harness.mjs` checks that the copies match.
+ */
+export const PAPERS_DIR_FIELD = "papersDir";
+export const OLD_PAPERS_DIR_FIELD = "papers";
+
+/**
+ * The declared papers root, or `null` when it is unusable.
+ *
+ * ⚠️ `null` means SILENCE, not refusal — same asymmetry as `paper-skills-nudge` and for the same
+ * reason: this is advisory, and a `react` cannot deny anyway. The gate (`paper-edit-guard`) is
+ * the one that must refuse on an unreadable declaration, because there a silent default would
+ * pass the very writes it exists to stop.
+ *
+ * 🔴 `declared === undefined`, NOT `declared ?? DEFAULT` — `"papersDir": null` is a keystroke, not
+ * an absence.
+ */
+const papersRoot = (rawPkg) => {
+  let declared;
+  try {
+    const pkg = JSON.parse(rawPkg);
+    const settings = pkg?.[CONFIG_KEY] ?? pkg?.[LEGACY_CONFIG_KEY];
+    // Old field name: stay silent rather than fall back to the default directory.
+    if (settings && Object.hasOwn(settings, OLD_PAPERS_DIR_FIELD)) return null;
+    declared = settings?.[PAPERS_DIR_FIELD];
+  } catch {
+    return null;
+  }
+  const root = declared === undefined ? DEFAULT_PAPERS_ROOT : declared;
+  if (typeof root !== "string" || root.length === 0) return null;
+  return root.replace(/\/+$/, "");
+};
+
+/**
+ * A paper SOURCE under `<root>/<dir>/`, with `<dir>` captured.
+ *
+ * 🔴 THE ROOT IS REGEX-ESCAPED. It is a path from a config file, and `.` is both a legal
+ * directory character and a regex wildcard: an unescaped root like `docs.v2/papers` would match
+ * `docsXv2/papers` too. Cheap to get right, and the failure it prevents is a hook firing about
+ * the wrong tree.
+ */
+const paperSourceRe = (root) =>
+  new RegExp(
+    `(?:^|/)${root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/([A-Za-z0-9._-]+)/(?:[^/]*\\.tex|(?:.*/)?(?:paper|draft)\\.md)$`,
+  );
+
+/**
+ * The tool invocation, with the script located rather than assumed.
+ *
+ * 🔴 `require.resolve` INSTEAD OF A HARD-CODED `node_modules/<pkg>/…` PATH. This package must
+ * not spell its own install location: a consumer may install it under an alias, and a
+ * pnpm/yarn-berry layout is not `node_modules/<name>` at all. `require.resolve` asks the
+ * resolver the same question Node itself answers, and it works for a non-JS extension —
+ * measured 2026-09-12 against a `.md` and a `.sh` in an installed copy. It runs in a `$(…)`
+ * because `run()` goes through a shell (also measured).
+ */
+const surface = (dir) =>
+  `bash "$(node -p "require.resolve('${CONFIG_KEY}/hooks/paper-status-gates.sh')")" --surface ${dir}`;
+
+export default experimental_defineReact({
+  on: "PostToolUse",
+  match: tools("Edit", "Write", "MultiEdit"),
+  // 🔴 THE PATH IS ANCHORED TO THE PROJECT ROOT, and that is not decoration. vigiles runs the
+  // provider "via execSync in the hook's cwd", and the hook process's cwd is the consumer's
+  // own wiring — a string this hook cannot see. A bare `cat package.json` therefore reads from
+  // whatever directory the Bash tool last moved to, and a `cd` into a subdirectory with no
+  // manifest breaks the read.
+  //
+  // ⚠️ THE FAILURE HERE IS SILENT, which makes it more dangerous than its neighbor's.
+  // `paper-edit-guard` on PreToolUse DENIES loudly and visibly when the declaration is
+  // unreadable. This hook on PostToolUse just returns `nothing()`, i.e. simply stops firing:
+  // the `cat` chain fails → empty string → `JSON.parse("")` throws → `papersRoot` returns null
+  // → silence. And silence is exactly what a nudge's success state looks like, so a dead hook
+  // is indistinguishable from a working one.
+  needs: [provide("pkg", 'cat "${CLAUDE_PROJECT_DIR:-.}/package.json"')],
+  react: (e) => {
+    const root = papersRoot(e.ctx.pkg);
+    if (root === null) return nothing();
+    const m = paperSourceRe(root).exec(e.path.raw.replace(/^\.\//, ""));
+    if (m === null) return nothing();
+    return run(surface(m[1]));
+  },
+});

package/hooks/paper-status-gates.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# paper-status-gates.sh — NOT A HOOK. This is a TOOL invoked by `paper-status-gates.hook.mjs`,
+# which owns the event routing and decides WHICH paper (if any) an edit concerned.
+#
+#   --surface <paper-dir>   print the readiness verdict + run the pipeline checker
+#
+# 🔴 WHAT LEFT THIS FILE AND WHY IT MATTERS. It used to read its payload with
+# `INPUT="${CLAUDE_TOOL_INPUT:-}"` plus a `timeout 1 cat` fallback and then grep that blob for a
+# paper path. `$CLAUDE_TOOL_INPUT` is NOT set by the harness — the payload arrives on stdin — and
+# that single idiom left THREE hooks silently dead for twelve days. None of it survives here:
+# this file receives an already-validated directory NAME as an argument, and it is registered as
+# a hook nowhere, so it cannot contract that disease again.
+#
+# Advisory (stderr), never blocks, always exits 0.
+set -euo pipefail
+
+[ "${1:-}" = "--surface" ] || {
+  echo "paper-status-gates.sh: a tool, not a hook. Use --surface <paper-dir>." >&2
+  exit 0
+}
+
+pdir_name="${2:-}"
+[ -n "$pdir_name" ] || exit 0
+# Defence in depth: the hook already anchored this to [A-Za-z0-9._-]+, and it is re-checked here
+# so the file is safe to call directly too.
+case "$pdir_name" in
+  *[!A-Za-z0-9._-]* | "" | . | ..) exit 0 ;;
+esac
+
+# ── WHERE THE CONSUMER'S THINGS ARE — TWO CARRIERS, READ, NOT ASSUMED ────────
+# This file used to hard-code both of these paths, which made it a tool with exactly one possible
+# user. Both now come from the one declaration every other carrier of this package reads:
+#
+#   "paperlint": { "papersDir": "docs/papers", "scripts": "tools/pipeline" }
+#
+# (The key's name before 2.0.0, "research-paper-pipeline", is still read.)
+#
+# ⚠️ `node -p` RATHER THAN grep/sed ON package.json. A JSON value is not a line of text: it can
+# be quoted, escaped, or spread across lines, and a pattern that gets it right today gets it
+# wrong on the first reformat — silently, by producing a root that matches nothing. Node is
+# already a hard dependency of the checker this script runs, so there is no new requirement.
+ROOT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+read_key() { # $1 = key, $2 = default
+  node -p "((p) => p['paperlint'] ?? p['research-paper-pipeline'] ?? {})(require('$ROOT_DIR/package.json'))['$1'] ?? '$2'" \
+    2>/dev/null || echo "$2"
+}
+# The field used to be called "papers". Every other reader refuses the old name; this script only
+# gives advice, so it stays silent instead of falling back to the default directory.
+[ -z "$(read_key papers '')" ] || exit 0
+papers_root="$(read_key papersDir papers)"
+scripts_root="$(read_key scripts .claude/skills/paper-pipeline/scripts)"
+
+# 🔴 AN UNUSABLE ROOT EXITS, IT DOES NOT BUILD A PATH FROM IT. `node -p` prints `undefined` for a
+# key whose value is literally `null` (`?? ` only catches null/undefined AFTER the object lookup,
+# and a `null` value reaches the default — but a malformed package.json makes the whole command
+# fail and the `|| echo` hands back the default). Either way, an empty or nonsense value would
+# produce `/<paper>/PIPELINE-STATUS.md` rooted at the filesystem, which does not exist, and this
+# script would exit 0 looking like a paper with nothing to report. Named rather than risked.
+case "$papers_root" in
+  "" | undefined | null) exit 0 ;;
+esac
+
+pdir="$papers_root/$pdir_name"
+STATUS="$ROOT_DIR/$pdir/PIPELINE-STATUS.md"
+[ -f "$STATUS" ] || exit 0
+
+# 🔴 SURFACE THE VERDICT, UNPROMPTED — see the header: the checker parsed this line and never
+# printed it, so the single fact anyone actually wanted was the one the tooling withheld.
+VERDICT=$(grep -m1 -E '^\*\*Readiness verdict:\*\*' "$STATUS" 2>/dev/null || true)
+if [ -n "$VERDICT" ]; then
+  echo "📊 $(echo "$VERDICT" | sed -E 's/\*\*//g' | cut -c1-200)" >&2
+else
+  echo "📊 PIPELINE-STATUS.md has NO '**Readiness verdict:**' line — the scorecard cannot say" >&2
+  echo "   whether this paper is submittable, which is the one question it exists to answer." >&2
+fi
+
+CHECK="$ROOT_DIR/$scripts_root/pipeline-check.mjs"
+if [ -f "$CHECK" ]; then
+  # The real checker: stale continuous passes, gates missing their declared inputs, a study that
+  # ran before the claim was stated, submit-access inside the moderation window, a verdict that is
+  # only a percentage, unrun gates. Advisory, always exit 0.
+  node "$CHECK" "$ROOT_DIR/$pdir" >&2 || true
+else
+  # Fallback for a checkout without the skill tree — the old crude surface.
+  gates=$(grep -E '☐' "$STATUS" 2>/dev/null | grep -iE 'study-accepted|pc-panel|harden|verify.?citations' || true)
+  if [ -n "$gates" ]; then
+    echo "⚠️ UNRUN GATES in $pdir/PIPELINE-STATUS.md (☐ — run them, don't 'anti-churn'-skip):" >&2
+    echo "$gates" | sed -E 's/\|.*//; s/^\| */   /' >&2
+  fi
+fi
+exit 0

package/lib/agent-cli-version.harness.mjs

@@ -0,0 +1,165 @@
+/**
+ * `observeAgentCli` — both halves, every case staged through an INJECTED spawner.
+ *
+ * The case that matters most is 4: a probe that discards its output. It cannot be staged at
+ * all against a real `spawnSync`, because there is no way to ask the installed binary to print
+ * nothing — which is precisely why the observation had to leave the harness that spawns it
+ * before it could be tested (issue #7).
+ */
+import assert from "node:assert/strict";
+import { recordCheck } from "vigiles";
+import { observeAgentCli, CHARACTERIZED_CLI } from "./agent-cli-version.mjs";
+
+/** A spawner that records how it was called, so the CALL SHAPE is assertable, not just the result. */
+const spawner = (result) => {
+  const seen = [];
+  const fn = (program, args, options) => {
+    seen.push({ program, args, options });
+    return result;
+  };
+  fn.seen = seen;
+  return fn;
+};
+
+const cases = [];
+
+// ── 1. BINARY ABSENT: no throw, and `present` says so — the skip path of the caller.
+{
+  const spawnSync = spawner({ status: 127, stdout: "", stderr: "not found" });
+  const o = observeAgentCli({ spawnSync });
+  assert.equal(
+    o.present,
+    false,
+    "a non-zero probe means the binary is not usable",
+  );
+  assert.equal(o.version, "", "and there is no version to report");
+  assert.match(
+    o.note,
+    /not installed/,
+    "the note must say WHY there is nothing to observe",
+  );
+  cases.push("CLI absent → present:false, no throw, note explains");
+}
+
+// ── 2. 🔴 DRIFT IS NAMED, NOT INFERRED. The measured case from issue #7: the machine carries
+//      2.1.273 while the assertions were written against 2.1.227.
+{
+  const spawnSync = spawner({
+    status: 0,
+    stdout: "2.1.273 (Claude Code)\n",
+    stderr: "",
+  });
+  const o = observeAgentCli({ spawnSync });
+  assert.equal(o.present, true);
+  assert.equal(
+    o.version,
+    "2.1.273",
+    "the version must be PARSED out of the line, not left raw",
+  );
+  assert.equal(
+    o.raw,
+    "2.1.273 (Claude Code)",
+    "and the full line kept for the report",
+  );
+  assert.equal(
+    o.characterized,
+    CHARACTERIZED_CLI,
+    "the characterized number rides along as a value",
+  );
+  assert.equal(
+    o.drifted,
+    true,
+    "2.1.273 ≠ 2.1.227 is drift and must be computed, not eyeballed",
+  );
+  assert.ok(
+    o.note.includes("2.1.273") && o.note.includes(CHARACTERIZED_CLI),
+    `the note must name BOTH numbers so a reader sees them diverge; got: ${o.note}`,
+  );
+  cases.push(
+    "drifted CLI → version parsed, drifted:true, note names BOTH numbers",
+  );
+}
+
+// ── 3. NO DRIFT: the same machinery must stay quiet when the numbers agree, or `drifted`
+//      would be a constant rather than a comparison.
+{
+  const spawnSync = spawner({
+    status: 0,
+    stdout: `${CHARACTERIZED_CLI} (Claude Code)\n`,
+    stderr: "",
+  });
+  const o = observeAgentCli({ spawnSync });
+  assert.equal(o.drifted, false, "matching versions are not drift");
+  assert.equal(o.version, CHARACTERIZED_CLI);
+  cases.push("CLI at the characterized version → drifted:false");
+}
+
+// ── 4. 🔴 THE DEFECT ITSELF: exit 0, nothing on stdout — what `stdio: "ignore"` produced.
+//      Reporting `characterized against ""` would be issue #7 wearing new clothes, so this
+//      must THROW rather than return an empty observation.
+{
+  const spawnSync = spawner({ status: 0, stdout: null, stderr: "" });
+  assert.throws(
+    () => observeAgentCli({ spawnSync }),
+    /is not an observation/,
+    "exit 0 with no version on stdout must fail loudly, not be reported as a version",
+  );
+  cases.push(
+    'exit 0 + empty stdout (the `stdio: "ignore"` shape) → throws, does not report a blank',
+  );
+}
+
+// ── 5. THE CALL SHAPE, asserted directly. Case 4 catches a discarding probe only because the
+//      double returns nothing; a real `stdio: "ignore"` would ALSO have to be caught if some
+//      other path happened to fill stdout. So the options handed to the spawner are checked.
+{
+  const spawnSync = spawner({
+    status: 0,
+    stdout: "2.1.273 (Claude Code)\n",
+    stderr: "",
+  });
+  observeAgentCli({ spawnSync });
+  const { args, options } = spawnSync.seen[0];
+  assert.deepEqual(
+    args,
+    ["--version"],
+    "the observation must ask for the version",
+  );
+  assert.equal(
+    options.encoding,
+    "utf8",
+    "without an encoding the output is a Buffer nobody reads",
+  );
+  assert.notEqual(
+    options.stdio,
+    "ignore",
+    '`stdio: "ignore"` is the discarded-output defect itself',
+  );
+  cases.push("the probe is spawned with encoding:utf8 and never stdio:ignore");
+}
+
+// ── 6. AND THE REAL BINARY, when this machine has one. Cases 1-5 are about the module; this
+//      one is about reality — an observer that only ever meets a double proves nothing about
+//      the output format of the tool it exists to read.
+{
+  const { spawnSync } = await import("node:child_process");
+  const o = observeAgentCli({ spawnSync });
+  if (o.present) {
+    assert.match(
+      o.version,
+      /^\d+\.\d+\.\d+$/,
+      `the real CLI's version must parse; raw was ${JSON.stringify(o.raw)}`,
+    );
+    cases.push(
+      `real \`claude\` binary present → observed ${o.version} (characterized ${o.characterized}${o.drifted ? ", DRIFTED" : ""})`,
+    );
+  } else {
+    cases.push(
+      "real `claude` binary absent on this machine → absent path exercised for real",
+    );
+  }
+}
+
+recordCheck(cases.length);
+console.log(`observeAgentCli: ${cases.length} cases:`);
+for (const c of cases) console.log(`  ok  ${c}`);

package/lib/agent-cli-version.mjs

@@ -0,0 +1,106 @@
+/**
+ * OBSERVE the `claude` CLI version instead of merely probing for the binary.
+ *
+ * ── THE DEFECT THIS EXISTS FOR (issue #7, measured) ─────────────────────────────
+ * `plan-paper-timeline.effects.harness.mjs` is a CHARACTERIZATION test: its job is to go red
+ * when the upstream CLI changes under it. It named the version it characterized — 2.1.227 —
+ * in prose, and then threw away the version it actually saw:
+ *
+ *     spawnSync("claude", ["--version"], { stdio: "ignore" })   // ← only `status` was read
+ *
+ * `stdio: "ignore"` discards the output, so `claude --version` ran as a PRESENCE probe. The
+ * string it printed was never read, never reported and never compared with the prose. Measured
+ * on this machine: the binary is **2.1.273**, the docblock says **2.1.227** — forty-six patch
+ * releases of drift, invisible to a reader of a green log.
+ *
+ * 🔴 WHY NOT PIN THE VERSION. A pin defeats the test: it is SUPPOSED to see upstream move. The
+ * repair is not to stop the drift but to stop the SILENCE about it — observe what is already
+ * spawned, carry the characterized number as a VALUE beside it, and let a reader see the two
+ * diverge instead of inferring it. CI installs `@anthropic-ai/claude-code` unpinned on purpose.
+ *
+ * ── WHY A MODULE AND NOT THREE LINES IN THE HARNESS ─────────────────────────────
+ * The three lines the issue suggests are correct and untestable where they were proposed. The
+ * harness that would exercise them spawns the real CLI, so its assertions about the observation
+ * depend on which version the machine happens to carry — and the one case that matters most,
+ * "the probe discards its output", cannot be staged at all when the spawn is hard-wired. With
+ * the spawner INJECTED, every case becomes deterministic: absent binary, drifted version,
+ * matching version, and the discarding probe itself.
+ */
+
+/**
+ * The version the effects harness's characterization was written against.
+ *
+ * 🔴 A VALUE, NOT A SENTENCE, and that is the whole point of this constant. The number lived in
+ * a docblock, where nothing could compare it with anything. Here it is compared on every run.
+ * Moving it means deliberately re-characterizing — which is the edit that should be conscious.
+ */
+export const CHARACTERIZED_CLI = "2.1.227";
+
+/** What `claude --version` prints: `2.1.273 (Claude Code)`. */
+const VERSION_IN = /\b(\d+\.\d+\.\d+)\b/;
+
+/**
+ * @typedef {object} CliObservation
+ * @property {boolean} present  the binary answered `--version` with status 0
+ * @property {string}  raw      the full line it printed, trimmed
+ * @property {string}  version  the dotted version parsed out of it
+ * @property {string}  characterized  the version the assertions were written against
+ * @property {boolean} drifted  observed and characterized differ
+ * @property {string}  note     one line naming BOTH numbers, for the report and for failures
+ */
+
+/**
+ * @param {object} deps
+ * @param {Function} deps.spawnSync  injected, so every case below is stageable
+ * @param {string}  [deps.program]
+ * @param {string}  [deps.characterized]
+ * @returns {CliObservation}
+ */
+export function observeAgentCli({
+  spawnSync,
+  program = "claude",
+  characterized = CHARACTERIZED_CLI,
+}) {
+  // 🔴 `encoding: "utf8"` IS THE FIX. With `stdio: "ignore"` — the shape this replaces — the
+  // child's output goes nowhere and `probe.stdout` comes back null, so everything downstream
+  // would be describing a string that was never read.
+  const probe = spawnSync(program, ["--version"], { encoding: "utf8" });
+
+  if (probe.status !== 0)
+    return {
+      present: false,
+      raw: "",
+      version: "",
+      characterized,
+      drifted: false,
+      note: `the \`${program}\` CLI is not installed, so no run can be observed`,
+    };
+
+  const raw = (probe.stdout ?? "").trim();
+  const version = VERSION_IN.exec(raw)?.[1] ?? "";
+
+  // ⚠️ EXIT 0 AND NOTHING ON STDOUT IS NOT A CLEAN OBSERVATION — it is exactly what the discarded
+  // probe looked like, and reporting `characterized against ""` would be the same lie in a new
+  // place. This is rule 4 of CLAUDE.md applied to the check that enforces it.
+  if (version === "")
+    throw new Error(
+      `\`${program} --version\` exited 0 but printed no version on stdout (got ${JSON.stringify(raw)}` +
+        `${probe.stderr ? `, stderr ${JSON.stringify(String(probe.stderr).trim().slice(0, 200))}` : ""}). ` +
+        `A presence probe is not an observation: this is the \`stdio: "ignore"\` shape that issue #7 ` +
+        `is about, and a version nobody read must not be reported as one.`,
+    );
+
+  const drifted = version !== characterized;
+  return {
+    present: true,
+    raw,
+    version,
+    characterized,
+    drifted,
+    note: drifted
+      ? `observed \`${program}\` ${version} — the assertions here were characterized against ` +
+        `${characterized}. They still hold, which is itself the result: a characterization test that ` +
+        `silently still holds is indistinguishable from one nobody re-checked.`
+      : `observed \`${program}\` ${version} — the version these assertions were characterized against.`,
+  };
+}

package/lib/agent-cli-version.mutations.mjs

@@ -0,0 +1,109 @@
+/**
+ * Battery for `observeAgentCli`. Five mutations, five different assertions.
+ *
+ * 🔴 The first one is the issue #7 defect itself, restored verbatim: bring back
+ * `stdio: "ignore"`. It is the whole point of this battery. Before the observation was pulled
+ * out into its own module, there was NOWHERE to place this mutation: the spawn was baked into
+ * the harness, which brings up the real CLI, and "ask the binary to print nothing" is not
+ * something you can do. A green battery against a baked-in spawn would have been a finding
+ * about the test, not about the defense.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { runMutations } from "./mutation-driver.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, "..");
+const MOD = join(HERE, "agent-cli-version.mjs");
+const HARNESS = join(HERE, "agent-cli-version.harness.mjs");
+
+process.exit(
+  runMutations({
+    root: ROOT,
+    runner: "node",
+    cases: [
+      {
+        name: '🔴 revert to `stdio: "ignore"` — the issue #7 defect verbatim',
+        harness: HARNESS,
+        // ⚠️ The assertion this trips is NOT the one I was aiming for, and this was corrected
+        // BY RUNNING IT, not from memory. The double hands back stdout regardless of the
+        // options, so the observation succeeds, and the first thing to go red is the
+        // `encoding` assertion. The `stdio` assertion itself is hit by the next case.
+        expect: "without an encoding the output is a Buffer nobody reads",
+        disables:
+          "the observation itself — the version is printed into the void again, and the tier characterizes nothing",
+        edits: [
+          [
+            MOD,
+            'spawnSync(program, ["--version"], { encoding: "utf8" })',
+            'spawnSync(program, ["--version"], { stdio: "ignore" })',
+          ],
+        ],
+      },
+      {
+        name: '`stdio: "ignore"` added ALONGSIDE encoding — output still goes nowhere',
+        harness: HARNESS,
+        expect: "is the discarded-output defect itself",
+        disables:
+          "the second call-shape assertion: `encoding` is present, but the stream is still killed",
+        edits: [
+          [
+            MOD,
+            'spawnSync(program, ["--version"], { encoding: "utf8" })',
+            'spawnSync(program, ["--version"], { encoding: "utf8", stdio: "ignore" })',
+          ],
+        ],
+      },
+      {
+        name: "empty stdout at exit code 0 stops being a failure",
+        harness: HARNESS,
+        expect: "must fail loudly, not be reported as a version",
+        disables:
+          "rule 4 — `exit 0` with empty output reads as a clean measurement again",
+        edits: [[MOD, 'if (version === "")', "if (false)"]],
+      },
+      {
+        name: "drift is computed as a constant, not a comparison",
+        harness: HARNESS,
+        expect: "must be computed, not eyeballed",
+        disables:
+          "the comparison of observed against characterized — the divergence becomes invisible again",
+        edits: [
+          [
+            MOD,
+            "const drifted = version !== characterized;",
+            "const drifted = false;",
+          ],
+        ],
+      },
+      {
+        name: "only one of the two numbers survives into the message",
+        harness: HARNESS,
+        expect: "must name BOTH numbers",
+        disables:
+          "showing the divergence — the reader is back to having to remember the second number",
+        edits: [
+          [
+            MOD,
+            "`observed \\`${program}\\` ${version} — the assertions here were characterized against ` +\n        `${characterized}.",
+            "`observed \\`${program}\\` ${version} — characterized elsewhere.",
+          ],
+        ],
+      },
+      {
+        name: "the version is not parsed out of the string, taken whole instead",
+        harness: HARNESS,
+        expect: "must be PARSED out of the line, not left raw",
+        disables:
+          "parsing the version string — `2.1.273 (Claude Code)` stops being comparable to `2.1.227`",
+        edits: [
+          [
+            MOD,
+            'const version = VERSION_IN.exec(raw)?.[1] ?? "";',
+            "const version = raw;",
+          ],
+        ],
+      },
+    ],
+  }),
+);