create-agent-rig 0.5.0 → 0.6.1

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

@@ -0,0 +1,306 @@
+/**
+ * Gate coverage — did every reviewer this round asked for actually answer, and
+ * for the commit being merged?
+ *
+ * Three writers already record the three halves of a gate round, and until this
+ * module existed nothing compared them:
+ *
+ *   - `decision-router.mjs` journals the set the route ASKED FOR, on the lane it
+ *     actually took (`gate: "review-routing:<lane>"`, with `reviewers`);
+ *   - `pr-ship` journals the set it actually LAUNCHED, with the head it launched
+ *     against (`gate: "reviewer-fan-out"`);
+ *   - each verdict that PARSED is journalled under the reviewer's own name.
+ *
+ * The two failures that hide in the gap between them both end in a merge that
+ * reads as fully gated: a reviewer the router named and nobody started, and a
+ * reviewer that answered — about a commit two pushes ago.
+ *
+ * 🔴 **A verdict that names no commit is not coverage of this one.** `headSha` is
+ * optional in the schema — every report written before it existed omits one — and
+ * reading absence as "it must have meant the head I am holding" is the inference
+ * the schema's own limit 6 forbids. It gets its own list rather than a pass.
+ *
+ * 🔴 **No fan-out record is not a clean round.** A run whose journal records no
+ * fan-out has not been shown to be covered, it has been shown to be unreadable —
+ * and four empty lists are exactly what a clean round looks like. That case
+ * answers `ok: false` and says why in `reason`. A missing fan-out, a missing route,
+ * an unconsumed route, a fan-out missing its head commit, and a fan-out for a different head
+ * commit are the unreadable-round answers; each reason names the evidence boundary the journal
+ * could not establish.
+ *
+ * 🔴 **A round is judged against its OWN route, not the run's last one.** The
+ * answers are scoped to the records after the last fan-out; the route needs the
+ * mirror of that, and not having it made the refusal above vacuous in the case it
+ * was written for. A run directory spans several rounds and several PRs, so an
+ * earlier round's route would otherwise satisfy a later round that journalled
+ * none — and its *set* would be inherited too, which after a `deterministic` lane
+ * means `neverLaunched` is empty for the rest of the run whatever the route asked
+ * for. So the route that counts is the last one carrying `reviewers` **between the
+ * previous fan-out and the last one**: the route that produced the fan-out being
+ * judged.
+ *
+ * 🔴 **An unconsumed route after the last fan-out is an unreadable boundary.**
+ * The journal cannot say whether this round's fan-out record is missing or the
+ * router was re-run after a completed fan-out. Both readings refuse coverage;
+ * re-running the fan-out for this head records the boundary either one needs.
+ */
+
+/** The gate name `pr-ship` writes its fan-out under. */
+const FAN_OUT = 'reviewer-fan-out';
+
+/** Every lane the router reports on shares this prefix; only the taken one carries a set. */
+const ROUTING = 'review-routing:';
+
+const gateOf = (record) => (typeof record?.gate === 'string' ? record.gate : '');
+
+/**
+ * The reviewer names in a journalled set.
+ *
+ * `recordDecision` checks for a list of strings and nothing about what a name
+ * is, so a blank one is dropped here rather than reported as a reviewer nobody
+ * can launch.
+ */
+const namesOf = (value) =>
+  Array.isArray(value) ? value.filter((name) => typeof name === 'string' && name.trim() !== '') : [];
+
+/** Order-preserving, because the output is read by a human looking for a name. */
+const uniq = (names) => [...new Set(names)];
+
+/**
+ * The shortest commit id the verdict schema accepts, and the floor a prefix
+ * match needs to be worth anything (`lib/verdict.mjs`, `isCommitId`).
+ */
+const SHORTEST_COMMIT = 7;
+
+/**
+ * The lengths a COMPLETE commit id has: sha-1 and sha-256.
+ *
+ * An abbreviation resolves against a complete id and nothing else. Without this,
+ * any strict extension of a full id prefix-matched it — a 50-character value
+ * built by appending to a 40-character commit was counted as coverage of that
+ * commit, and it passes the schema (7–64 hex), so it arrives through the fully
+ * validated path rather than as obvious junk.
+ */
+const COMPLETE_COMMIT_LENGTHS = new Set([40, 64]);
+
+/**
+ * Are these two ids the same commit?
+ *
+ * 🔴 **Not string equality, and the difference is a false HOLD.** The schema
+ * accepts an abbreviated id, so a reviewer may answer `b4e3ef0` about the commit
+ * `git rev-parse HEAD` prints in full — the same commit, written shorter. Exact
+ * comparison reports that as answered-for-another-commit and holds the merge on
+ * honest work, which is the way a guard loses the room.
+ *
+ * So: equal ids match, and otherwise the shorter must be a prefix of a
+ * **complete** one, case-insensitively — the way git resolves an abbreviation.
+ * Two bounds, each closing one direction:
+ *
+ * - **the floor.** Both must reach `SHORTEST_COMMIT`. A shorter value is one the
+ *   verdict schema refuses, and stretching it into a match would let a value
+ *   nothing accepted decide that a gate was covered. ⚠ The journal is the other
+ *   way in and it does not apply that schema (`run-journal.mjs` takes `headSha`
+ *   as any non-blank string), so this floor is enforced here on its own account,
+ *   not on the strength of an upstream check.
+ * - **the ceiling.** The longer must be a complete id. An abbreviation resolves
+ *   against a whole commit; a value that merely *extends* one is not that commit
+ *   written shorter, and counting it as coverage fails in the unsafe direction.
+ *
+ * One case is decided rather than left ambiguous: a 40-character value that
+ * prefixes a 64-character one matches, because the longer is complete. It could
+ * be a sha-256 abbreviated to 40 or a sha-1 with characters appended, and nothing
+ * here can resolve which — a pure function has no repository to ask. The first
+ * reading is the one an honest run produces.
+ */
+const sameCommit = (one, other) => {
+  if (one.length < SHORTEST_COMMIT || other.length < SHORTEST_COMMIT) return false;
+  const first = one.toLowerCase();
+  const second = other.toLowerCase();
+  if (first === second) return true;
+  const [shorter, longer] = first.length <= second.length ? [first, second] : [second, first];
+  if (!COMPLETE_COMMIT_LENGTHS.has(longer.length)) return false;
+  return longer.startsWith(shorter);
+};
+
+/**
+ * Which reviewers are outstanding for `headSha`, and in which of the four ways.
+ *
+ * @param {{ records?: unknown, headSha?: unknown }} input
+ *   `records` is `readRun(...).decisions` — the run's decision journal, in
+ *   journal order. `headSha` is the commit the round is about.
+ * @returns {{
+ *   ok: boolean, routed: string[], launched: string[],
+ *   neverLaunched: string[], unanswered: string[],
+ *   unattributed: string[], stale: string[], reason?: string,
+ * }}
+ */
+export const coverageOf = ({ records, headSha } = {}) => {
+  const journal = Array.isArray(records) ? records : [];
+  const target = typeof headSha === 'string' ? headSha : '';
+
+  // One forward pass, keeping the LAST of each: a branch gets a second gate
+  // round after fixes, and the round's whole question is whether THIS round's
+  // reviewers answered. An earlier fan-out answers about a round already over.
+  //
+  // `pendingRoute` is what makes the route round-scoped: a routing record is held
+  // until a fan-out consumes it, and each fan-out takes only what was journalled
+  // since the previous one. Nothing survives a fan-out, so no round can inherit
+  // the round before it.
+  let pendingRoute = null;
+  let routeOfRound = null;
+  let fanOutAt = -1;
+  let launchedNames = [];
+  let fanOutHead = null;
+
+  for (let index = 0; index < journal.length; index += 1) {
+    const record = journal[index];
+    const gate = gateOf(record);
+    // Only the taken lane carries a set; a declined lane's line has no
+    // `reviewers` key at all, and reading one off it would compare the answers
+    // against a lane nobody took.
+    if (gate.startsWith(ROUTING) && Array.isArray(record?.reviewers)) {
+      // A set was RECORDED, which is a different fact from the set being empty.
+      // The `deterministic` lane legitimately routes nobody; a round that never
+      // journalled a route knows nothing about who should have been launched.
+      pendingRoute = namesOf(record.reviewers);
+    }
+    if (gate === FAN_OUT) {
+      fanOutAt = index;
+      launchedNames = namesOf(record?.reviewers);
+      fanOutHead = typeof record?.headSha === 'string' ? record.headSha : null;
+      routeOfRound = pendingRoute;
+      pendingRoute = null;
+    }
+  }
+
+  if (pendingRoute !== null) {
+    return {
+      ok: false,
+      routed: uniq(pendingRoute),
+      launched: [],
+      neverLaunched: [],
+      unanswered: [],
+      unattributed: [],
+      stale: [],
+      reason:
+        'a routed reviewer set was journalled after the last fan-out, so the round ' +
+        'boundary is unreadable: either this round\'s fan-out record is missing, or the ' +
+        'router ran again after the fan-out. Rerun the fan-out step for this head so ' +
+        'the round it belongs to has a record.',
+    };
+  }
+
+  const routeRecorded = routeOfRound !== null;
+  const routedNames = routeOfRound ?? [];
+
+  const routed = uniq(routedNames);
+
+  if (fanOutAt === -1) {
+    return {
+      ok: false,
+      routed,
+      launched: [],
+      neverLaunched: [],
+      unanswered: [],
+      unattributed: [],
+      stale: [],
+      reason:
+        'this run journalled no reviewer fan-out, so there is no set to check the verdicts ' +
+        'against. That is not a round with nothing outstanding — it is a round nothing can ' +
+        'read, and the two look identical from the lists alone.',
+    };
+  }
+
+  if (fanOutHead === null) {
+    return {
+      ok: false,
+      routed: [],
+      launched: [],
+      neverLaunched: [],
+      unanswered: [],
+      unattributed: [],
+      stale: [],
+      reason:
+        'the last reviewer fan-out names no head commit, so it cannot be coverage of ' +
+        'this one. Rerun the fan-out step for this head and record the commit it launched.',
+    };
+  }
+
+  if (!sameCommit(fanOutHead, target)) {
+    return {
+      ok: false,
+      routed: [],
+      launched: [],
+      neverLaunched: [],
+      unanswered: [],
+      unattributed: [],
+      stale: [],
+      reason:
+        'the last reviewer fan-out names a different head commit, so its launched set ' +
+        'does not cover this one. Rerun the fan-out step for this head before reading verdicts.',
+    };
+  }
+
+  const launched = uniq(launchedNames);
+  // Answers are the records that come AFTER the fan-out. A verdict from the
+  // previous round is still in the journal, and a reader that scanned the whole
+  // file would find an answer and report the current round covered.
+  const after = journal.slice(fanOutAt + 1);
+
+  // The lane is a floor and never a ceiling — the triggers may only ADD
+  // reviewers — so a launched set larger than the routed one is the ordinary
+  // case and is not a finding. Only the other direction is.
+  const neverLaunched = routed.filter((name) => !launched.includes(name));
+
+  const unanswered = [];
+  const unattributed = [];
+  const stale = [];
+
+  for (const name of launched) {
+    // Matched by gate name, which is what keeps another writer's record — the
+    // router's own line, `pr-ship`'s, a deploy verdict — from being read as a
+    // reviewer's answer.
+    const commits = after
+      .filter((record) => gateOf(record) === name)
+      .map((record) => record?.headSha)
+      .filter((commit) => typeof commit === 'string' && commit !== '');
+
+    const answered = after.some((record) => gateOf(record) === name);
+    if (!answered) {
+      unanswered.push(name);
+    } else if (commits.some((commit) => sameCommit(commit, target))) {
+      // Covered. A HOLD counts here exactly as a SHIP does: coverage is about
+      // who spoke for which commit, never about what they said.
+    } else if (commits.length === 0) {
+      unattributed.push(name);
+    } else {
+      stale.push(name);
+    }
+  }
+
+  const outstanding =
+    neverLaunched.length + unanswered.length + unattributed.length + stale.length;
+
+  return {
+    ok: routeRecorded && outstanding === 0,
+    routed,
+    launched,
+    neverLaunched,
+    unanswered,
+    unattributed,
+    stale,
+    // Unlike the missing fan-out, this one still has a launched set and answers
+    // to compare, so the four lists are computed and returned — the reason says
+    // which half of the check could not run, rather than replacing the half that
+    // could.
+    ...(routeRecorded
+      ? {}
+      : {
+          reason:
+            'this round journalled no routed reviewer set, so `neverLaunched` was compared ' +
+            'against nothing: a reviewer the route asked for and nobody launched would not ' +
+            'appear. An empty route that WAS recorded is a different answer, and so is a ' +
+            'route belonging to an earlier round — neither is this one.',
+        }),
+  };
+};

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

@@ -0,0 +1,29 @@
+/**
+ * The revalidation points — ONE spelling of the fact (AR-137).
+ * All upstream test pointers in this script name the generator suite, absent in a generated rig.
+ *
+ * `queue/index.mjs next` writes the SELECT record; `revalidate.mjs` writes the
+ * other two and answers outcomes at all three; `revalidation-report.mjs`
+ * counts all three. Before this module each carried its own list, and one
+ * computed a fourth (`['SELECT', ...POINTS]`). Four spellings of one fact is
+ * how a point gets added to the report and not to the script, silently.
+ *
+ * `REVALIDATES` is DERIVED, not restated: the asymmetry that SELECT is written
+ * elsewhere is encoded here once, where a reader looks for it.
+ *
+ * The prose that names these points is kept in step by a two-direction check —
+ * the generator's test/template/correspondence.test.ts › "every point the
+ * module knows is named by the loop or pr-ship skill, and vice versa".
+ *
+ * Maintenance and noise cost, recorded (AR-137): adding a point touches this
+ * list and the prose that names it as `--point X` or `point: X`, and the check
+ * says which side was forgotten. The check reads only the `loop` and `pr-ship`
+ * skills — a point named anywhere else is invisible to it — and it parses
+ * those two by that exact spelling, so a rewording breaks it loudly, as a named
+ * failure, never silently.
+ */
+
+export const POINTS = Object.freeze(['SELECT', 'BEFORE_PR', 'BEFORE_CLOSE']);
+
+/** What `revalidate.mjs` can revalidate itself: every point but SELECT. */
+export const REVALIDATES = Object.freeze(POINTS.filter((point) => point !== 'SELECT'));

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

@@ -1,5 +1,6 @@
 // The credential vocabulary, decided once, so that everything which refuses a
 // credential refuses the same set.
+// All upstream test pointers in this script name the generator suite, absent in a generated rig.
 //
 // Every layer that refuses one reads THIS module — which layers exist is a
 // question about the project, not about this file. A freshly generated rig has
@@ -18,7 +19,9 @@
 // GENERATOR this rig came from, not in this repository — the same arrangement
 // `.claude/rules/invariants.md` describes for the hooks themselves under "About
 // the hooks you were given". They are where a claim is proven, not cover you
-// have here. The moment you edit this module, its tests are yours.
+// have here. A manifest-backed generator upgrade remains inherited while
+// `.claude/.rig-manifest.json` matches; once the hash differs, the local test is
+// yours.
 //
 // It answers two different questions, and keeping them apart matters:
 //

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

@@ -70,7 +70,9 @@
  *    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.
+ *    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. */
@@ -166,11 +168,14 @@ const DIAGNOSIS_LIMIT = 120;
  * 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.
  *
- * ⚠ **The CLI's own argv is not passed through it.** 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.
+ * ⚠ **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
@@ -210,6 +215,29 @@ const isPlainObject = (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
@@ -398,10 +426,11 @@ export function parseVerdict(text) {
   }
 
   const headSha = parsed.headSha;
-  if (headSha !== undefined && !isText(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 a line of text when present.',
+        '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.',
     );
   }
 

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
@@ -95,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 {
@@ -172,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;

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

@@ -14,7 +14,7 @@
  */
 
 import { execFileSync } from 'node:child_process';
-import { dirname } from 'node:path';
+import { dirname, resolve } from 'node:path';
 
 // The sanitiser is IMPORTED, never re-derived. This repo had already ruled on
 // which git variables to strip, exported the answer with its stated limit, and
@@ -76,7 +76,9 @@ export const mainCheckoutRoot = (startDir) => {
         env: { ...withoutGitLocation(), LC_ALL: 'C', LANGUAGE: '' },
       },
     ).trim();
-    return gitDir ? dirname(gitDir) : startDir;
+    // `resolve`, because git answers with forward slashes on Windows
+    // (`C:/Users/...`) and every caller compares against a native path.
+    return gitDir ? resolve(dirname(gitDir)) : startDir;
   } catch (error) {
     if (error?.code === 'ENOENT') return startDir; // git is not installed
     const stderr = String(error?.stderr ?? '');
@@ -87,3 +89,61 @@ export const mainCheckoutRoot = (startDir) => {
     );
   }
 };
+
+/**
+ * Is this checkout in a state a gate round may be counted against (AR-141)?
+ *
+ * A round is counted per branch and the fan-out's verdicts name a head. On one
+ * branch two rounds were counted before a commit that pre-commit then refused,
+ * so the counter and the records named a head that never shipped. The three
+ * states that make a head unshippable are decidable from git alone: a dirty
+ * working tree (tracked or untracked), a branch with no upstream, and commits
+ * the upstream has not seen. `{ ok: true }` otherwise; a git that cannot answer
+ * is reported as such, never as clean.
+ *
+ * Bounded: two git calls, each with a timeout, and the porcelain output is
+ * read only for emptiness. The upstream question has one catch for three
+ * states — a detached HEAD, a branch with no upstream, an upstream that is
+ * gone — and names none of them apart; the refusal is right for all three.
+ */
+export const checkoutIsShippable = (root) => {
+  const git = (args) =>
+    execFileSync('git', args, {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env: withoutGitLocation(),
+      timeout: 30_000,
+    }).trim();
+  let status;
+  try {
+    status = git(['status', '--porcelain']);
+  } catch (error) {
+    return { ok: false, why: `git could not read the working tree at ${root}: ${error.message}` };
+  }
+  if (status !== '') {
+    return {
+      ok: false,
+      why: 'the working tree is dirty — a round counted now would name a head that has not ' +
+        'been committed; commit (and push) first',
+    };
+  }
+  let ahead;
+  try {
+    ahead = git(['rev-list', '--count', '@{upstream}..HEAD']);
+  } catch {
+    return {
+      ok: false,
+      why: 'HEAD has no upstream — push the branch first, so the round names a head the ' +
+        'reviewers and CI can see',
+    };
+  }
+  if (ahead !== '0') {
+    return {
+      ok: false,
+      why: `HEAD is ${ahead} commit(s) ahead of its upstream — push first, so the round names ` +
+        'the head that ships',
+    };
+  }
+  return { ok: true };
+};