create-agent-rig 0.4.0 → 0.6.0

package/templates/agent-os/universal/.claude/scripts/lib/verdict.mjs

@@ -0,0 +1,462 @@
+/**
+ * The verdict schema — one shape every gate in this rulebook answers in.
+ *
+ * Before this module, a gate's verdict was a sentence the calling session
+ * pattern-matched by eye: `VERDICT: HOLD`, `PREMISE FALSE`, "not
+ * security-relevant". A reviewer that rambled a paragraph and never wrote the
+ * line was read as whatever the caller expected.
+ *
+ * Two of the properties the rulebook states are decided here: a blocker names
+ * what it violates, and a verdict that stops the change lists at least one. The
+ * third — one verdict per report — is asked for by each gate's spec and is not
+ * decided here: this reads the LAST block and ignores every earlier one
+ * (limit 3), which is what lets a reviewer quote the shape and then answer.
+ *
+ * So a gate now ends its report with exactly one fenced ```json block, and
+ * `parseVerdict` is the single place that decides whether such a block says
+ * anything. `verdict.mjs` (the CLI beside this file) is how `pr-ship` calls it;
+ * `run-journal.mjs` records the parsed value rather than the prose.
+ *
+ * 🔴 **Both directions of "the blocker list disagrees with the word" are
+ * refused, and the second is the dangerous one.** A `HOLD` naming no blocker
+ * gives the author nothing to act on, so the guess is usually "nothing". A
+ * `SHIP` that carries blockers reads as a pass while listing the reasons it
+ * should not have been one — same defect, wearing the answer everyone wanted.
+ *
+ * ⚠ **What this module is not.** It decides whether a verdict is WELL-FORMED,
+ * never whether it is right: a reviewer that saw nothing and answers `SHIP`
+ * passes here exactly like one that read the whole diff. It also does not run,
+ * launch or count gates — `pr-ship` runs the fan-out, `queue/index.mjs
+ * gate-round` counts the rounds.
+ *
+ * ⚠ **The limits, stated rather than implied.**
+ *
+ * 1. **An unknown gate name is accepted, with any word from `VERDICT_WORDS`.**
+ *    A project adds reviewers of its own, and a schema that refused every name
+ *    it had not been told about would be deleted by the first project that
+ *    extended it. Such a gate is checked against the shared list and not against
+ *    a per-gate one; a gate name with a typo in it is not caught either, and
+ *    that is the price of the limit.
+ *
+ *    **One shipped gate is in that position on purpose**, and it is a reviewer
+ *    a stack layer adds. This file travels to every target, and the shared layer
+ *    may not print a provider's name anywhere — so a gate whose own name carries
+ *    one cannot be listed here, whatever else is true of it, and reaches the
+ *    schema as an unknown gate. `GATE_VOCABULARY` therefore names the gates
+ *    whose NAMES this layer may carry, which is not the same set as the gates a
+ *    given target runs: a stack gate whose name is neutral is listed.
+ * 2. **A blocker may name no file.** A failing required check and a
+ *    Definition-of-Done line have no `file:line`, and demanding one would make
+ *    every run invent a location to satisfy the schema — worse than the prose
+ *    this replaces. What every blocker does name is the `rule` it violates.
+ * 3. **It reads the LAST block in the report.** A spec shows the shape it wants
+ *    and the reviewer then answers, so the first block in a report is usually
+ *    the example — somebody else's gate, and usually the opposite word.
+ * 4. **Nothing launches it.** Like every gate in this layer it holds because a
+ *    skill says to call it, not because a hook fires it.
+ * 5. **A second ``` after the opening fence makes the block's end a guess, and
+ *    the guess is refused.** Markdown has no escape for a fence, so a reviewer
+ *    quoting a fenced snippet in a `note` writes a block whose end is
+ *    ambiguous — and reading it to the first closing fence would silently keep
+ *    the front half, which on a measured case was a `SHIP` standing in front of
+ *    the `HOLD` behind it. The test is deliberately coarser than that one case:
+ *    **any** further fence is refused, including a well-formed block followed by
+ *    a fenced snippet in trailing prose, because from here the two are the same
+ *    text. Every spec says the block is the last thing in the report, so the
+ *    remedy is the same either way — move the fenced snippet above the block,
+ *    or name it in `evidence`, and answer again.
+ * 6. **`headSha` is optional, and an absent one means the gate did not say
+ *    which commit it answered for — never that it answered for the current
+ *    one.** A caller that read absence as "the head I am holding" would take a
+ *    verdict about a diff nobody named as a verdict about the diff it is about
+ *    to merge, so a caller that needs the answer keyed to a commit handles
+ *    absence itself — `lib/gate-coverage.mjs` is the one that does, and it puts
+ *    such a verdict in its own list rather than counting it either way. When
+ *    present the value is a commit SHAPE, not free text: see `isCommitId`.
+ */
+
+/** Every word any gate in this rulebook may return. */
+export const VERDICT_WORDS = Object.freeze([
+  'SHIP',
+  'HOLD',
+  'HEALTHY',
+  'REGRESSION',
+  'PREMISES_HOLD',
+  'PREMISE_FALSE',
+  'UNVERIFIABLE',
+  'UNMEASURED',
+  'NOT_APPLICABLE',
+]);
+
+/**
+ * The part of that vocabulary each gate can actually mean.
+ *
+ * A shared list alone would let `code-reviewer` answer `HEALTHY` and
+ * `post-deploy-verify` answer `SHIP` — words whose meaning belongs to another
+ * gate, and which a caller reading only the word would act on.
+ *
+ * 🔴 `check-premises` writes its verdicts with spaces in prose (`PREMISES
+ * HOLD`) and as one token inside the block. Both forms are the contract; this
+ * is the machine one.
+ */
+export const GATE_VOCABULARY = Object.freeze({
+  'pr-ship': Object.freeze(['SHIP', 'HOLD']),
+  'code-reviewer': Object.freeze(['SHIP', 'HOLD', 'NOT_APPLICABLE']),
+  'prose-reviewer': Object.freeze(['SHIP', 'HOLD', 'NOT_APPLICABLE']),
+  'security-scanner': Object.freeze(['SHIP', 'HOLD', 'NOT_APPLICABLE']),
+  'check-premises': Object.freeze([
+    'PREMISES_HOLD',
+    'PREMISE_FALSE',
+    'UNVERIFIABLE',
+    'UNMEASURED',
+  ]),
+  'post-deploy-verify': Object.freeze(['HEALTHY', 'REGRESSION']),
+});
+
+/**
+ * The words that mean stop — each one has to name what stopped it.
+ *
+ * `UNVERIFIABLE` and `UNMEASURED` are here for the same reason `HOLD` is: each
+ * is about a specific claim or sentence, and a verdict that will not say which
+ * one leaves the caller exactly where the free prose did.
+ */
+export const BLOCKING_VERDICTS = Object.freeze([
+  'HOLD',
+  'REGRESSION',
+  'PREMISE_FALSE',
+  'UNVERIFIABLE',
+  'UNMEASURED',
+]);
+
+/** The only keys a block may carry. */
+const SHAPE_KEYS = Object.freeze([
+  'gate',
+  'verdict',
+  'blockers',
+  'advisories',
+  'evidence',
+  'headSha',
+]);
+
+const FENCE = '```json';
+
+/** How much of one reviewer-written value a diagnosis will carry. */
+const DIAGNOSIS_LIMIT = 120;
+
+/**
+ * One reviewer-written value, made safe to print in a diagnosis.
+ *
+ * 🔴 **Every message below that quotes the report interpolates through this** — the
+ * key, the verdict word, the gate, and the parse error, whose message carries a
+ * snippet of the block the reviewer wrote — and there is exactly one of it.
+ *
+ * The values are written by a subagent and read by a
+ * human in a terminal: a `gate` carrying `ESC[2K ESC[1A … ESC[0m` erases the line
+ * above and repaints a refusal as a pass for whoever is watching the scrollback. The
+ * exit code and the empty stdout are unaffected — the target is the person, not the
+ * caller — which is exactly why it is the person's copy that has to be cleaned.
+ *
+ * It strips what a terminal *acts on* (C0, DEL, C1) rather than what it shows, so
+ * the text the operator has to read survives: a repainting payload arrives as its
+ * own visible words. Long values are cut to `DIAGNOSIS_LIMIT` with a `…`, so one
+ * field cannot push the rest of the diagnosis off the screen.
+ *
+ * ⚠ **What it does not remove, and why that is the line.** Bidirectional overrides
+ * (`U+202E` and family), zero-width characters, the soft hyphen and combining marks
+ * survive. None of them can address the cursor, so none can reach outside the value
+ * — every site prints it inside backticks with a constant sentence after it, and the
+ * worst they buy is a misread within those backticks. Escape sequences are the ones
+ * that rewrite the operator's screen, and those are what this removes.
+ *
+ * ⚠ **Two of the CLI's own arguments are passed through it, and two are not.**
+ * The report's path and the subcommand are printed exactly as the caller wrote
+ * them, because their whole job is to be pasted back into a command. The
+ * expected-gate argument IS sanitised, because it is printed beside a
+ * reviewer-written gate as one of two names the operator compares, and a value
+ * that can repaint that comparison defeats it. So is `coverage`'s commit
+ * argument, which is printed beside journal-written reviewer names for the same
+ * reason.
+ *
+ * It never throws — it is called only where something has already gone wrong, and a
+ * sanitiser that throws there turns a diagnosis into a crash the caller reads as
+ * "the gate did not answer".
+ */
+export const safeForDiagnosis = (value) => {
+  let text;
+  try {
+    text = typeof value === 'string' ? value : String(value);
+  } catch {
+    return '<unprintable>';
+  }
+
+  // One forward pass over CODE POINTS, and the cap counts the units a terminal
+  // and a JSON writer count. Slicing the accumulated string instead would cut an
+  // astral character in half and hand the next consumer a lone surrogate.
+  const kept = [];
+  let units = 0;
+  for (const character of text) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code < 0x20 || (code >= 0x7f && code <= 0x9f)) continue;
+
+    if (units + character.length > DIAGNOSIS_LIMIT) {
+      // Something is left over, so the value is cut and says so. Drop whole
+      // characters until the ellipsis fits inside the cap.
+      while (units > DIAGNOSIS_LIMIT - 1) units -= kept.pop().length;
+      return `${kept.join('')}…`;
+    }
+    kept.push(character);
+    units += character.length;
+  }
+  return kept.join('');
+};
+
+const isPlainObject = (value) =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isText = (value) => typeof value === 'string' && value.trim() !== '';
+
+/**
+ * A commit id, checked as a SHAPE rather than as text (AR-79).
+ *
+ * `headSha` arrived as "any non-blank text". **No consumer interpolates it
+ * today** — the only reader compares it as a string (`lib/gate-coverage.mjs`),
+ * and the merge criterion takes its SHA from `gh pr view --json headRefOid`, not
+ * from a verdict. The shape is fixed here so that the first consumer that does
+ * put it in an argument position inherits the check instead of having to
+ * remember it; `--upload-pack=…`, a leading `-` and `../…` are not commits, and
+ * a field that only ever holds commits is the cheap way to keep them out.
+ *
+ * ⚠ **This covers the value inside a verdict block, and nothing else.**
+ * `run-journal.mjs` takes `headSha` on a decision record as any non-blank
+ * string, and `pr-ship`'s fan-out record reaches it without passing through
+ * `parseVerdict` at all — so a commit id that never came from a reviewer's block
+ * is not shaped by this.
+ *
+ * **Checked on the raw value — never trimmed, never lowercased.** A value that
+ * needs rewriting to pass is a value the reviewer did not write, and rewriting it
+ * silently is how a near-miss becomes a match.
+ */
+export const isCommitId = (value) => typeof value === 'string' && /^[0-9a-f]{7,64}$/i.test(value);
+
+/**
+ * The last fenced ```json block, as one of three answers: `{ raw }` for a block
+ * whose extent is unambiguous, `{ ambiguous: true }` for one carrying a fence of
+ * its own (limit 5), and `null` when the report has no such block at all.
+ *
+ * One backward scan for the opening fence and one forward pass counting the
+ * closing ones — no regular expression over model-written text, which is
+ * unbounded and arrives from a subagent.
+ */
+const lastJsonBlock = (text) => {
+  const opening = text.lastIndexOf(FENCE);
+  if (opening === -1) return null;
+
+  let start = opening + FENCE.length;
+  while (start < text.length && (text[start] === ' ' || text[start] === '\t')) start += 1;
+  if (text[start] === '\r') start += 1;
+  if (text[start] === '\n') start += 1;
+
+  const closing = text.indexOf('```', start);
+  // No closing fence at all: the rest of the report is the body, and JSON tells
+  // the reader what is wrong with it. One closing fence is the ordinary block.
+  if (closing === -1) return { raw: text.slice(start) };
+  if (text.indexOf('```', closing + 3) === -1) return { raw: text.slice(start, closing) };
+
+  // 🔴 More than one: the block's end is a guess, and the two guesses disagree
+  // about the verdict rather than about whitespace. Refuse instead.
+  return { ambiguous: true };
+};
+
+const checkBlocker = (blocker, index, problems) => {
+  const where = `blocker #${index + 1}`;
+  if (!isPlainObject(blocker)) {
+    problems.push(`${where} is not an object — a blocker names a rule and a note.`);
+    return;
+  }
+
+  if (!isText(blocker.rule)) {
+    problems.push(
+      `${where} names no \`rule\`: every blocker says what it violates — a checklist ` +
+        'item, a required check by name, or the Definition-of-Done line that does not hold.',
+    );
+  }
+  if (!isText(blocker.note)) {
+    problems.push(`${where} names no \`note\`: what is wrong, in the author's terms.`);
+  }
+
+  const hasFile = blocker.file !== undefined && blocker.file !== null;
+  const hasLine = blocker.line !== undefined && blocker.line !== null;
+
+  if (hasFile && !isText(blocker.file)) {
+    problems.push(`${where} has a \`file\` that is not a path.`);
+  } else if (hasFile && !(Number.isInteger(blocker.line) && blocker.line >= 1)) {
+    problems.push(
+      `${where} names a \`file\` but no usable \`line\`: a location is a file AND the ` +
+        'line inside it, so a reader lands where the finding is.',
+    );
+  } else if (hasLine && !hasFile) {
+    problems.push(`${where} names a \`line\` but no \`file\`, so the line points nowhere.`);
+  }
+};
+
+/**
+ * Read a gate's report and decide whether it ended in a verdict.
+ *
+ * Returns `{ ok: true, verdict }` or `{ ok: false, problems }` — never both, and
+ * never a throw: the input is a subagent's report, so malformed IS the expected
+ * case and it has to arrive as an answer rather than as a crash.
+ *
+ * Every problem in the block is reported together. One per round would cost the
+ * gate a round per problem, and `pr-ship` has a counted, finite number of them.
+ */
+export function parseVerdict(text) {
+  const problems = [];
+  if (typeof text !== 'string') {
+    return { ok: false, problems: ['no report was supplied to read a verdict from.'] };
+  }
+
+  const block = lastJsonBlock(text);
+  if (block === null) {
+    return {
+      ok: false,
+      problems: [
+        'the report carries no fenced ```json block, so it states no verdict this gate ' +
+          'can act on. Every gate ends with exactly one.',
+      ],
+    };
+  }
+  if (block.ambiguous) {
+    return {
+      ok: false,
+      problems: [
+        'a second ``` follows the opening fence of the final json block, so where that ' +
+          'block ends is a guess — either backticks inside it, or a fenced snippet after ' +
+          'it, and from here the two are the same text. The block is the last thing in ' +
+          'the report: move the snippet above it, or name it in `evidence`, and answer ' +
+          'again.',
+      ],
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(block.raw);
+  } catch (error) {
+    return {
+      ok: false,
+      // 🔴 Through the sanitiser like every other quoted value, and this one is
+      // the least obvious of them: V8 puts a ~20-character snippet of the input
+      // INTO the SyntaxError's message, so the reviewer chooses what a failed
+      // parse prints just as directly as it chooses a gate name.
+      problems: [
+        `the final fenced json block is not JSON ` +
+          `(${safeForDiagnosis(error?.message ?? 'parse failed')}).`,
+      ],
+    };
+  }
+
+  if (!isPlainObject(parsed)) {
+    return {
+      ok: false,
+      problems: ['the final fenced json block is not an object naming a gate and a verdict.'],
+    };
+  }
+
+  for (const key of Object.keys(parsed)) {
+    if (!SHAPE_KEYS.includes(key)) {
+      problems.push(
+        `the block carries \`${safeForDiagnosis(key)}\`, which this shape does not define. ` +
+          'Refused rather ' +
+          'than dropped: a silently ignored field is one the reviewer believes it reported.',
+      );
+    }
+  }
+
+  const gate = parsed.gate;
+  if (!isText(gate)) {
+    problems.push('the block names no `gate`, so nothing says which gate this verdict is from.');
+  }
+
+  const verdict = parsed.verdict;
+  const known = typeof verdict === 'string' && VERDICT_WORDS.includes(verdict);
+  if (!known) {
+    problems.push(
+      `\`${safeForDiagnosis(verdict)}\` is not a verdict any gate in this rulebook returns ` +
+        `(${VERDICT_WORDS.join(', ')}).`,
+    );
+  } else if (isText(gate) && Object.hasOwn(GATE_VOCABULARY, gate)) {
+    const allowed = GATE_VOCABULARY[gate];
+    if (!allowed.includes(verdict)) {
+      problems.push(
+        `${safeForDiagnosis(gate)} cannot return ${verdict} — that word belongs to another ` +
+          'gate. It returns ' +
+          `one of: ${allowed.join(', ')}.`,
+      );
+    }
+  }
+
+  const blockers = parsed.blockers;
+  if (!Array.isArray(blockers)) {
+    problems.push(
+      'the block names no `blockers` list. It is required and may be empty; absent, a ' +
+        'reader cannot tell "this gate found nothing" from "this gate did not say".',
+    );
+  } else {
+    blockers.forEach((blocker, index) => checkBlocker(blocker, index, problems));
+
+    if (known && BLOCKING_VERDICTS.includes(verdict) && blockers.length === 0) {
+      problems.push(
+        `${verdict} is a verdict that stops the change, and this one names no blocker. A ` +
+          'stop nobody can act on is worse than no stop: the author has to guess what to ' +
+          'fix, and the guess is usually "nothing".',
+      );
+    }
+    if (known && !BLOCKING_VERDICTS.includes(verdict) && blockers.length > 0) {
+      problems.push(
+        `${verdict} means proceed, and this one lists ${blockers.length} blocker(s). Either ` +
+          'the word or the list is wrong, and a pass carrying the reasons it should not ' +
+          'have been one is the more expensive of the two to discover later.',
+      );
+    }
+  }
+
+  const advisories = parsed.advisories;
+  if (advisories !== undefined && !Array.isArray(advisories)) {
+    problems.push('`advisories` is not a list — it is optional, and a list when present.');
+  }
+
+  const headSha = parsed.headSha;
+  if (headSha !== undefined && !isCommitId(headSha)) {
+    problems.push(
+      `\`headSha\` is \`${safeForDiagnosis(headSha)}\`, which is not a commit this verdict ` +
+        'could have answered for. It is optional, and 7 to 64 hex characters (0-9a-f) when ' +
+        'present — nothing else, and with no surrounding space.',
+    );
+  }
+
+  const evidence = parsed.evidence;
+  if (evidence !== undefined) {
+    if (!Array.isArray(evidence)) {
+      problems.push('`evidence` is not a list of lines — it is optional, and a list when present.');
+    } else if (!evidence.every((line) => typeof line === 'string')) {
+      problems.push('`evidence` carries an entry that is not a line of text.');
+    }
+  }
+
+  if (problems.length > 0) return { ok: false, problems };
+
+  return {
+    ok: true,
+    verdict: {
+      gate,
+      verdict,
+      blockers,
+      advisories: advisories ?? [],
+      evidence: evidence ?? [],
+      // Spread, never a hardcoded key: a verdict that named no commit must come
+      // back without the key at all, so a caller can tell "answered for this
+      // commit" from "said nothing about which commit".
+      ...(headSha === undefined ? {} : { headSha }),
+    },
+  };
+}

package/templates/agent-os/universal/.claude/scripts/preflight.mjs

@@ -11,7 +11,7 @@
 // reason it is safe to script half a checklist. The honest objection to a partial
 // script — "a script that half-checks is worse than a list the run actually
 // reads" — is true exactly while the boundary is invisible. A silent script would
-// let a GO on three items read as a pass on six.
+// let a GO on four items read as a pass on seven.
 //
 // 🔴 **`unknown` never becomes `pass`.** A probe that could not run tells you
 // nothing, and "I could not look" recorded as "it is fine" is the failure this
@@ -43,23 +43,13 @@ export const UNCHECKED = [
  *
  * 🔴 Limit: only repository *location* is stripped. `gh` inherits the rest of
  * the environment on purpose — its credentials live there.
+ *
+ * It lives in `git-env.mjs` and is re-exported here, so callers that already
+ * import it from this file keep working while the queue seam — which must not
+ * pull a CLI script into its read path — imports the small module directly.
  */
-export const withoutGitLocation = (env = process.env) => {
-  const sanitised = { ...env };
-  for (const key of [
-    'GIT_DIR',
-    'GIT_WORK_TREE',
-    'GIT_INDEX_FILE',
-    'GIT_COMMON_DIR',
-    'GIT_OBJECT_DIRECTORY',
-    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
-    'GIT_NAMESPACE',
-    'GIT_PREFIX',
-  ]) {
-    delete sanitised[key];
-  }
-  return sanitised;
-};
+export { withoutGitLocation } from './git-env.mjs';
+import { withoutGitLocation } from './git-env.mjs';
 
 const run = (command, args) =>
   execFileSync(command, args, {
@@ -105,6 +95,31 @@ export const checkDefaultBranchFresh = () => {
   }
 };
 
+/**
+ * `RIG_RUN_DIR` must not already be exported when preflight runs (AR-139).
+ *
+ * Preflight walks BEFORE this run declares its directory (`loop` §1), so a
+ * value already in the environment is a leak — an `export` that outlived an
+ * earlier run, or a shell that inherited one. Everything the run then spawns
+ * inherits it too: the queue CLI under test, the gate scripts, and the real
+ * run's append-only trace receives their fixture records. Measured at 38
+ * fixture selections and 22 fixture revalidation events, plus two tests
+ * exiting 1 and blamed on load. A hard failure, because starting on it puts
+ * this run's stops in somebody else's file.
+ */
+export const checkRunDirNotExported = (env = process.env) => {
+  const value = env.RIG_RUN_DIR;
+  return value
+    ? {
+        ok: false,
+        detail:
+          `RIG_RUN_DIR is already exported (${value}) — a leak from an earlier run. ` +
+          '`unset RIG_RUN_DIR`, then declare this run\'s own directory; an inherited ' +
+          "one lands this run's trace and stop conditions in somebody else's file",
+      }
+    : { ok: true, detail: 'not exported' };
+};
+
 /** The last deploy must have concluded successfully — never start on a broken runtime. */
 export const checkLastDeploy = ({ workflow = 'deploy' } = {}) => {
   try {
@@ -182,6 +197,7 @@ const invokedDirectly = () => {
 if (invokedDirectly()) {
   const checks = {
     killSwitch: checkKillSwitch(),
+    runDirNotExported: checkRunDirNotExported(),
     defaultBranchFresh: checkDefaultBranchFresh(),
     lastDeploy: checkLastDeploy(),
   };

package/templates/agent-os/universal/.claude/scripts/queue/as-of.mjs

@@ -0,0 +1,51 @@
+// The two git questions a proposal's `asOf` needs answered (AR-116):
+// which commit is HEAD, and what changed between a commit and HEAD.
+//
+// Kept out of `core.mjs`, which is pure, and out of the adapters, which would
+// otherwise each spawn git their own way. Both answers are `null` when git
+// cannot answer — no checkout, an unknown commit, a shallow clone — and
+// `overtakenOf` in core.mjs turns that `null` into an "unanswerable" finding
+// rather than a clean one.
+
+import { execFileSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { withoutGitLocation } from '../git-env.mjs';
+
+const git = (args, cwd) =>
+  execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    env: withoutGitLocation(),
+  }).trim();
+
+/** HEAD of the checkout at `cwd`, or null where there is none. */
+export const headShaOf = ({ cwd = process.cwd() } = {}) => {
+  try {
+    const sha = git(['rev-parse', 'HEAD'], cwd);
+    return /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+};
+
+/** Paths changed between `asOf` and `head`, or null when git cannot say. */
+export const changedSinceOf = ({ cwd = process.cwd(), asOf, head = 'HEAD' } = {}) => {
+  if (typeof asOf !== 'string' || !/^[0-9a-f]{7,40}$/.test(asOf)) return null;
+  try {
+    return git(['diff', '--name-only', '-z', asOf, head], cwd).split('\0').filter(Boolean);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The commit a proposal is measured against: what the caller says, or HEAD of
+ * the project this script belongs to. `null` files without one — and hygiene
+ * then reports the proposal as unanswerable rather than current. One
+ * implementation for all three adapters, so they cannot answer differently.
+ */
+const PROJECT_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+export const withAsOf = (proposal) =>
+  proposal.asOf === undefined ? { ...proposal, asOf: headShaOf({ cwd: PROJECT_ROOT }) } : proposal;