create-agent-rig 0.2.0 → 0.3.0

package/templates/agent-os/universal/.claude/scripts/detect-missed-gate.mjs

@@ -0,0 +1,489 @@
+#!/usr/bin/env node
+// The one finding a run cannot raise about itself.
+//
+// A change that touches an elevated-tier path must go through a reviewer gate
+// (.claude/rules/autonomy.md, "Tier 2"; .claude/rules/workflow.md, "PR flow").
+// When a run continues past that gate, the miss is invisible by construction:
+// **the run that missed the gate is exactly the run that will not report it.**
+// A run that had known was a run that would have run the gate.
+//
+// So this sweep runs OUTSIDE any run, over merged PRs, reading only merged
+// artifacts. It costs a run nothing and cannot be skipped by one.
+//
+//   node .claude/scripts/detect-missed-gate.mjs                     # last 7 days
+//   node .claude/scripts/detect-missed-gate.mjs --since 2026-07-01 --json
+//   node .claude/scripts/detect-missed-gate.mjs --input prs.json    # offline
+//   node .claude/scripts/detect-missed-gate.mjs --epoch 2026-07-01  # ignore older merges
+//
+// 🔴 **Never invoke it as a step inside a run.** A check the run performs on
+// itself is a check the run in a hurry skips — running it inside would give back
+// exactly the property that makes it worth having. A scheduled job, a weekly
+// habit, or a human is the right caller.
+//
+// It always exits 0 unless it could not run at all: findings are the output, not
+// the status. A non-zero exit would make a sweep that FOUND something look like
+// a sweep that BROKE.
+import { execFileSync } from 'node:child_process';
+import { readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+/**
+ * Read every layer's declaration and union them.
+ *
+ * The set is never duplicated into this file: a list here plus a list in the docs
+ * needs a drift check to stay honest, and a drifted detector quietly stops
+ * detecting. Reading the declaration removes that failure mode instead of
+ * monitoring it.
+ *
+ * `CLAUDE.md` carries the project's own paths; each stack layer's rule file
+ * carries the ones that only exist in that shape (`infra/` comes from the
+ * infrastructure layer, and a project without one must not declare it). Seeding
+ * every path in one place would declare directories that do not exist in half the
+ * targets — and a gate declared over a missing directory reports "clean" while
+ * looking nowhere.
+ */
+export const readDeclaredPaths = (projectRoot, { readFile = readFileSync, listDir = null } = {}) => {
+  const sources = [join(projectRoot, 'CLAUDE.md')];
+  try {
+    const rulesDir = join(projectRoot, '.claude', 'rules');
+    const entries = listDir ? listDir(rulesDir) : readdirSync(rulesDir);
+    for (const entry of entries) {
+      if (entry.endsWith('.md')) sources.push(join(rulesDir, entry));
+    }
+  } catch {
+    // no rules directory — CLAUDE.md alone then
+  }
+
+  const declared = [];
+  let found = false;
+  for (const source of sources) {
+    let parsed;
+    try {
+      parsed = parseElevatedPaths(readFile(source, 'utf8'));
+    } catch {
+      continue; // an unreadable source is not a declaration
+    }
+    if (parsed) {
+      found = true;
+      declared.push(...parsed);
+    }
+  }
+  // null, not [], when nothing declared anything: `sweep` reports that as its own
+  // finding rather than as "no findings".
+  return found ? [...new Set(declared)] : null;
+};
+
+/**
+ * Normalise a path so both sides of the comparison agree.
+ *
+ * `./infra/x.ts`, `/infra/x.ts` and `infra//x.ts` all name the same file as
+ * `infra/x.ts`; comparing raw strings meant each of those slipped the gate
+ * silently. Case is deliberately preserved — paths are case-sensitive on the
+ * systems this runs on, and folding case would create false positives.
+ */
+export const normalizePath = (path) =>
+  String(path ?? '')
+    .replace(/\\/g, '/')
+    .replace(/\/{2,}/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/^\//, '');
+
+export const parseElevatedPaths = (markdown) => {
+  // `\r?` so a file with CRLF line endings is not invisible: the block used to be
+  // undetectable there, and with another source also declaring, the loss was
+  // silent rather than reported as a blind sweep.
+  const blocks = [...String(markdown ?? '').matchAll(/```elevated-paths\r?\n([\s\S]*?)```/g)];
+  if (blocks.length === 0) return null;
+  return blocks.flatMap((block) =>
+    block[1]
+      .split('\n')
+      // an inline comment after the path is a comment, not part of the path
+      .map((line) => normalizePath(line.replace(/\s+#.*$/, '').trim()))
+      .filter((line) => line && !line.startsWith('#')),
+  );
+};
+
+/**
+ * Paths that provision nothing and configure nothing, whatever directory they sit
+ * in — EXCEPT the rulebook itself. Declaring `.claude/` as elevated was a no-op
+ * for every `.md` under it, so a merged PR rewriting the autonomy tiers or the
+ * Never list passed the gate meant to catch exactly that.
+ */
+const isRulebook = (path) => path === 'CLAUDE.md' || path.startsWith('.claude/');
+
+const isInert = (path) =>
+  !isRulebook(path) &&
+  (/\.mdx?$/.test(path) ||
+  /(^|\/)(test|tests|__tests__)\//.test(path) ||
+  /\.(test|spec)\.[cm]?[jt]sx?$/.test(path));
+
+/** Coerce whatever the host returned into a path string, never throwing. */
+const pathOf = (file) => {
+  if (typeof file === 'string') return file;
+  const path = file?.path ?? file?.filename ?? '';
+  return typeof path === 'string' ? path : '';
+};
+
+/**
+ * The elevated-tier files among `files`; empty means the change was not elevated.
+ *
+ * Tolerant of every malformed shape seen in testing (a non-array, an object,
+ * `{path: 42}`) because the alternative was a TypeError that killed the whole
+ * sweep and lost the findings on every other PR — which both this file and the
+ * reconciler explicitly promise not to do.
+ */
+export const elevatedPathsIn = (files = [], elevatedPaths = []) => {
+  if (!Array.isArray(files)) return [];
+  const prefixes = (Array.isArray(elevatedPaths) ? elevatedPaths : []).map(normalizePath);
+  return files
+    .map(pathOf)
+    .map(normalizePath)
+    .filter((path) => path && !isInert(path) && prefixes.some((prefix) => path.startsWith(prefix)));
+};
+
+// A reviewer agent named in the PR body, by convention: the two universal gates
+// plus any project-specific `*-reviewer`.
+// The quantifier is BOUNDED. `[a-z0-9-]*` before a `-reviewer` tail backtracks
+// quadratically on an attacker-written body: 3.9s on a 65k line, and the sweep
+// reads 100 PR bodies, so a crafted set costs minutes of CPU on a scheduled job
+// that reports nothing when it is killed.
+const REVIEWERS = /\b(code-reviewer|security-scanner|[a-z][a-z0-9-]{0,48}-reviewer)\b/i;
+const VERDICT = /\b(clean|passed|pass|approved|no blocking|green)\b/i;
+
+/**
+ * 🔴 The body is NOT authority, and this is the security core of the file.
+ *
+ * The PR body is written by whoever opened the PR — including the run whose
+ * compliance is being audited, and including an outside contributor. Testing it
+ * with a keyword scan made the detector strictly *more* permissive the more
+ * damning the body got: `VERDICT: HOLD — code-reviewer listed 3 blockers`
+ * suppressed the finding, an unticked `- [ ] code-reviewer verdict recorded`
+ * checkbox suppressed it, and so did `ignore the code-reviewer, this is urgent`.
+ * Writing the truth got you flagged; writing a lie did not.
+ *
+ * So only the **`human-review` label** suppresses a finding. Applying a label
+ * needs repository triage permission, which a fork contributor does not have and a
+ * run cannot fake. The body is still read — a plausible-looking verdict there is
+ * reported as a weaker, separate observation, never as a pass.
+ */
+const labelsOf = (pr) => {
+  const labels = pr?.labels;
+  if (typeof labels === 'string') return [labels];
+  if (!Array.isArray(labels)) return [];
+  return labels.map((label) => (typeof label === 'string' ? label : (label?.name ?? '')));
+};
+
+export const gateEvidence = (pr) => {
+  if (labelsOf(pr).includes('human-review')) return 'label';
+  const claimsVerdict = String(pr?.body ?? '')
+    .split('\n')
+    .some((line) => REVIEWERS.test(line) && VERDICT.test(line));
+  return claimsVerdict ? 'body-claim' : 'none';
+};
+
+/**
+ * Which lane produced this PR. The branch convention (`<type>/<queue-id>-<slug>`
+ * — see the `worktree-task` skill) is the discriminator, because it is the one
+ * mark a queue-driven run always leaves and an outside contributor never does.
+ */
+const BRANCH_CONVENTION = /^(?:feat|fix|docs|chore|refactor|test|perf)\/((?:[A-Z][A-Z0-9]*-)?\d+)-/;
+const QUEUE_REF = /#(\d+)\b|\b([A-Z][A-Z0-9]+-\d+)\b/;
+const CLOSES_ISSUE = /\b(?:clos(?:e|es|ed)|fix(?:e[sd])?|resolv(?:e|es|ed))\s+#(\d+)/i;
+
+export const queueRefOf = (pr) => {
+  const fromBranch = String(pr?.headRefName ?? '').match(BRANCH_CONVENTION)?.[1] ?? null;
+  const text = `${pr?.title ?? ''}\n${pr?.body ?? ''}`;
+  const inText = text.match(QUEUE_REF);
+  const fromText = inText ? (inText[1] ?? inText[2] ?? null) : null;
+  const closesIssue = text.match(CLOSES_ISSUE)?.[1] ?? null;
+  return { fromBranch, fromText, closesIssue };
+};
+
+export const laneOf = (pr) => {
+  const { fromBranch, fromText, closesIssue } = queueRefOf(pr);
+  // A queue-driven PR whose description lost the reference is still recognisably
+  // queue-driven. Counting it as external would corrupt the accounting AND hide
+  // the broken convention — so the lane stays `queue` and the gap is a finding.
+  if (fromBranch) {
+    return {
+      lane: 'queue',
+      queueRef: fromBranch,
+      closesIssue,
+      finding: fromText === null ? 'queue-ref-missing-from-description' : null,
+    };
+  }
+  if (closesIssue) return { lane: 'external', queueRef: null, closesIssue, finding: null };
+  // No reference anywhere and nothing closed: owner-directed work outside both
+  // lanes. Recorded, not flagged — it is legitimate.
+  return { lane: 'owner-directed', queueRef: null, closesIssue: null, finding: null };
+};
+
+/**
+ * One merged PR → a `missed-gate` finding, or null. Three tests in order: merged
+ * after the epoch, touched an elevated path, no recorded gate.
+ */
+export const classifyPr = (pr, { elevatedPaths = [], epoch = null } = {}) => {
+  if (!pr || typeof pr !== 'object') return null;
+  if (!pr.mergedAt) return null;
+  if (epoch && new Date(pr.mergedAt) < new Date(epoch)) return null;
+
+  // A file list that is absent is NOT an empty one. `files: null` used to read as
+  // "touched nothing elevated" and pass silently — so a schema change, a truncated
+  // response or a hand-exported fixture turned the sweep into a rubber stamp.
+  // `gh pr list --json files` uses GraphQL `files(first: 100)` and silently
+  // returns only the first 100, with no truncation marker. A PR padded past that
+  // hides its elevated file OUTSIDE the window, and the sweep reads the empty
+  // result as "touched nothing elevated" — the silent variant of the failure this
+  // file exists to prevent. `changedFiles` comes back on the same call and is the
+  // ground truth.
+  const truncated =
+    Array.isArray(pr.files) &&
+    typeof pr.changedFiles === 'number' &&
+    pr.files.length < pr.changedFiles;
+
+  if (pr.files === undefined || pr.files === null || truncated) {
+    return {
+      kind: 'unknown-file-list',
+      pr: pr.number,
+      title: pr.title,
+      url: pr.url,
+      mergedAt: pr.mergedAt,
+      lane: laneOf(pr).lane,
+      elevatedFiles: [],
+      why: truncated
+        ? `the host returned ${pr.files.length} of ${pr.changedFiles} changed files, so ` +
+          'this sweep could not see the whole diff. That is an unknown, not a pass — ' +
+          'check this PR by hand.'
+        : 'the merged PR carries no file list, so this sweep could not tell whether ' +
+          'it crossed an elevated path. That is an unknown, not a pass — re-fetch it ' +
+          'with `--json files` or check the PR by hand.',
+    };
+  }
+
+  const elevatedFiles = elevatedPathsIn(pr.files, elevatedPaths);
+  if (elevatedFiles.length === 0) return null;
+
+  const evidence = gateEvidence(pr);
+  if (evidence === 'label') return null;
+
+  const { lane, queueRef } = laneOf(pr);
+  return {
+    kind: 'missed-gate',
+    pr: pr.number,
+    title: pr.title,
+    url: pr.url,
+    mergedAt: pr.mergedAt,
+    lane,
+    queueRef,
+    evidence,
+    elevatedFiles,
+    why:
+      evidence === 'body-claim'
+        ? `merged touching ${elevatedFiles.length} elevated-tier path(s). The body ` +
+          'claims a reviewer verdict, but the body is written by the author — it is ' +
+          'not verifiable after the fact. Only the human-review label, which needs ' +
+          'repository permission, records the gate. Confirm the gate ran and label it.'
+        : `merged touching ${elevatedFiles.length} elevated-tier path(s) with ` +
+          'no human-review label and no reviewer verdict recorded anywhere',
+  };
+};
+
+/**
+ * A sweep over merged PRs.
+ *
+ * Escalation grows with the second miss: the first is commented and journaled;
+ * a second inside the same window opens an escalation issue, because two misses
+ * is a hole in the gate logic rather than one slip.
+ */
+export const sweep = ({ prs = [], elevatedPaths = [], epoch = null } = {}) => {
+  const findings = [];
+
+  // No declaration is not "nothing to find" — it is a blind sweep, and a blind
+  // sweep reporting "no findings" is the most misleading output this tool has.
+  if (elevatedPaths === null || elevatedPaths.length === 0) {
+    findings.push({
+      kind: 'no-elevated-paths-declared',
+      why:
+        'CLAUDE.md declares no `elevated-paths` block, so this sweep cannot tell ' +
+        'an elevated merge from an ordinary one. Until it does, "no findings" ' +
+        'means "did not look".',
+      actions: ['journal-line', 'escalation-issue'],
+    });
+    return { findings, sweptPrs: prs.length, epoch };
+  }
+
+  // A non-array input is a caller mistake, not forty clean PRs.
+  const rows = Array.isArray(prs) ? prs : [];
+
+  let misses = 0;
+  for (const pr of rows) {
+    let finding;
+    try {
+      finding = classifyPr(pr, { elevatedPaths, epoch });
+    } catch {
+      // One unparseable row must not cost the findings on every other row.
+      findings.push({
+        kind: 'unreadable-record',
+        pr: pr?.number ?? null,
+        why: 'this merged PR could not be read, so it was not checked. That is an unknown, not a pass.',
+        actions: ['journal-line'],
+      });
+      continue;
+    }
+    if (!finding) continue;
+    const actions = [
+      finding.lane === 'queue' ? 'comment-on-queue-item' : 'comment-on-pr',
+      'journal-line',
+    ];
+    if (finding.kind === 'missed-gate') {
+      if (misses >= 1) actions.push('escalation-issue');
+      misses += 1;
+    }
+    findings.push({ ...finding, actions });
+  }
+
+  return { findings, sweptPrs: rows.length, epoch };
+};
+
+// --- CLI -----------------------------------------------------------------------------
+
+/**
+ * Read an offline fixture, or say plainly why it could not be read.
+ *
+ * A raw SyntaxError stack, or a silent fall-through to the live repo when
+ * `--input` was given without a value, are both worse than a one-line diagnosis:
+ * this tool's whole value is that "could not look" never renders as "clean".
+ */
+const readInput = (file, label) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (error) {
+    process.stderr.write(
+      `${label}: could not read ${file} as JSON — nothing was checked. ` +
+        `${String(error?.message ?? error).split('\n')[0]}\n`,
+    );
+    process.exit(1);
+  }
+  if (!Array.isArray(parsed)) {
+    process.stderr.write(
+      `${label}: ${file} does not contain a JSON array of merged PRs, so nothing ` +
+        'was checked. Expected the shape `gh pr list --json …` produces.\n',
+    );
+    process.exit(1);
+  }
+  return parsed;
+};
+
+const parseArgs = (argv) => {
+  const args = { json: false, since: null, epoch: null, input: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i];
+    if (flag === '--json') args.json = true;
+    else if (flag === '--since') args.since = argv[++i];
+    else if (flag === '--epoch') args.epoch = argv[++i];
+    else if (flag === '--input') args.input = argv[++i];
+  }
+  return args;
+};
+
+const daysAgo = (n) => new Date(Date.now() - n * 86_400_000).toISOString().slice(0, 10);
+
+/**
+ * Findings are the output, not the status — but that cuts both ways: a sweep that
+ * could not reach the API must be unmistakably different from a clean sweep. So
+ * this is the one path that exits non-zero, and it says why in one line rather
+ * than dumping a stack.
+ */
+const fetchMergedPrs = (since) => {
+  try {
+    return JSON.parse(
+      execFileSync(
+        'gh',
+        [
+          'pr',
+          'list',
+          '--state',
+          'merged',
+          '--limit',
+          '100',
+          '--search',
+          `merged:>=${since}`,
+          '--json',
+          'number,title,body,headRefName,mergedAt,url,labels,files,changedFiles',
+        ],
+        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+      ),
+    );
+  } catch (error) {
+    process.stderr.write(
+      'missed-gate sweep: could not list merged PRs — the `gh` CLI is missing, ' +
+        'unauthenticated, or the API is unreachable. This is NOT a clean sweep; ' +
+        'nothing was checked. Use --input <file> to sweep an exported list offline.\n' +
+        `  ${String(error?.stderr ?? error?.message ?? error).trim().split('\n')[0]}\n`,
+    );
+    process.exit(1);
+  }
+};
+
+export const render = (result) => {
+  if (result.findings.length === 0) {
+    return (
+      `missed-gate sweep: ${result.sweptPrs} merged PR(s) swept — no findings` +
+      `${result.epoch ? ` (epoch ${result.epoch})` : ''}.\n`
+    );
+  }
+  const lines = [
+    `missed-gate sweep: ${result.findings.length} finding(s) over ${result.sweptPrs} merged PR(s).`,
+    '',
+  ];
+  for (const f of result.findings) {
+    if (f.kind === 'no-elevated-paths-declared') {
+      lines.push(`  [${f.kind}] ${f.why}`);
+    } else {
+      lines.push(
+        `  [missed-gate] #${f.pr} (${f.lane}${f.queueRef ? `, ${f.queueRef}` : ''}) — ${f.title}`,
+      );
+      lines.push(`      elevated files: ${f.elevatedFiles.join(', ')}`);
+      lines.push(`      ${f.why}`);
+    }
+    lines.push(`      actions: ${f.actions.join(' → ')}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+};
+
+/**
+ * Was this file invoked directly?
+ *
+ * Compared by REALPATH on both sides: ESM resolves `import.meta.url` through
+ * symlinks while `process.argv[1]` keeps the path as typed, so a project living
+ * under a symlinked directory (a macOS temp dir, a symlinked home, a checkout
+ * behind a link) would fail a naive equality check — and the script would exit 0
+ * having printed nothing, which reads exactly like "no findings".
+ */
+const invokedDirectly = () => {
+  if (!process.argv[1]) return false;
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  return real(fileURLToPath(import.meta.url)) === real(process.argv[1]);
+};
+
+if (invokedDirectly()) {
+  const args = parseArgs(process.argv.slice(2));
+  const projectRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const prs = args.input
+    ? readInput(args.input, 'missed-gate sweep')
+    : fetchMergedPrs(args.since ?? daysAgo(7));
+  // No declaration anywhere reads as a blind sweep, and `sweep` reports that as
+  // its own finding rather than as "no findings".
+  const elevatedPaths = readDeclaredPaths(projectRoot);
+  const result = sweep({ prs, elevatedPaths, epoch: args.epoch });
+  process.stdout.write(args.json ? `${JSON.stringify(result, null, 2)}\n` : render(result));
+}

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

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// Preflight for an unattended run — walked ONCE, before the first task.
+//
+//   node .claude/scripts/preflight.mjs           # the block, ready to paste
+//   node .claude/scripts/preflight.mjs --json
+//
+// Every scripted item below has already cost a run somewhere: they are cheap
+// before task #1 and expensive at turn 40.
+//
+// 🔴 **It prints the items it did NOT check, every time.** That is the whole
+// 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.
+//
+// 🔴 **`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
+// checklist exists to prevent.
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+// One implementation of the brake, shared with the hook that enforces it. This
+// file used to carry its own `process.env.AGENT_LOOP_STOP || <default>`, which is
+// the replace-not-add bug — fixed in the hook and left open here for a full review
+// cycle, because preflight is the only scripted brake check and had no test.
+import { brakeIsOn } from './stop-flag.mjs';
+
+/** The items this script cannot check: judgement, or a call worth more than it saves. */
+export const UNCHECKED = [
+  'the queue is reachable through its adapter (`node .claude/scripts/queue/index.mjs next`)',
+  'no stray worktree from a dead session that this run might mistake for its own',
+  'a budget is declared for this run, and it is written down somewhere the run can re-read',
+];
+
+const run = (command, args) =>
+  execFileSync(command, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+
+/** The kill switch must be absent before a run starts. */
+export const checkKillSwitch = () => {
+  const armed = brakeIsOn();
+  return armed
+    ? { ok: false, detail: `kill switch is SET (${armed}) — do not start; deal with the cause` }
+    : { ok: true, detail: 'absent' };
+};
+
+/**
+ * The local default branch must match the remote.
+ *
+ * `fetch` is not `pull`, and a stale working tree reads as current — this exact
+ * confusion has produced confidently-wrong runtime diagnoses more than once.
+ */
+export const checkDefaultBranchFresh = () => {
+  try {
+    const branch =
+      run('git', ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'])
+        .split('/')
+        .pop() || 'main';
+    run('git', ['fetch', '--quiet', 'origin', branch]);
+    const local = run('git', ['rev-parse', branch]);
+    const remote = run('git', ['rev-parse', `origin/${branch}`]);
+    return local === remote
+      ? { ok: true, detail: `${branch} == origin/${branch}` }
+      : {
+          // `stale`, not `unknown`: the probe RAN and produced a definite answer.
+          // Reporting a known-stale branch as "could not look" collapsed the two
+          // states this file exists to keep apart.
+          ok: 'stale',
+          detail: `local ${branch} differs from origin/${branch} — pull before starting`,
+        };
+  } catch (error) {
+    return { ok: 'unknown', detail: `could not compare: ${String(error.message ?? error).split('\n')[0]}` };
+  }
+};
+
+/** The last deploy must have concluded successfully — never start on a broken runtime. */
+export const checkLastDeploy = ({ workflow = 'deploy' } = {}) => {
+  try {
+    const runs = JSON.parse(
+      run('gh', ['run', 'list', '--workflow', workflow, '--limit', '1', '--json', 'conclusion,url']),
+    );
+    if (runs.length === 0) return { ok: 'unknown', detail: 'no deploy run found yet' };
+    const [last] = runs;
+    return last.conclusion === 'success'
+      ? { ok: true, detail: `last deploy succeeded (${last.url})` }
+      : { ok: false, detail: `last deploy concluded ${last.conclusion} (${last.url})` };
+  } catch (error) {
+    return {
+      ok: 'unknown',
+      detail: `could not read deploy history: ${String(error.message ?? error).split('\n')[0]}`,
+    };
+  }
+};
+
+/**
+ * STOP on any hard failure; CAUTION on anything that is not a clean pass; GO only
+ * when every scripted item genuinely passed. The three unscripted items are still
+ * the reader's.
+ *
+ * `stale` and `unknown` both give CAUTION but are never merged into one word:
+ * "I looked and it is stale" is actionable, "I could not look" is not, and neither
+ * ever becomes a pass.
+ */
+export const verdictOf = (checks) => {
+  const values = Object.values(checks);
+  if (values.some((check) => check?.ok === false)) return 'STOP';
+  if (values.some((check) => check?.ok !== true)) return 'CAUTION';
+  return 'GO';
+};
+
+export const report = (checks, { unchecked = UNCHECKED } = {}) => {
+  const verdict = verdictOf(checks);
+  const mark = (ok) =>
+    ok === true ? 'pass' : ok === false ? 'FAIL' : ok === 'stale' ? 'stale' : 'unknown';
+  const lines = [
+    `**preflight** — verdict: ${verdict}`,
+    '',
+    ...Object.entries(checks).map(([key, check]) => `- ${mark(check?.ok)} · ${key} — ${check?.detail ?? ''}`),
+    '',
+    `_Not checked by this script — still yours (${unchecked.length}):_`,
+    ...unchecked.map((item) => `- ${item}`),
+    '',
+    '_An item skipped twice is the signal to script it or drop it: a checklist',
+    "nobody completes decays into one nobody reads._",
+  ];
+  return { verdict, checks, unchecked, rendered: lines.join('\n') };
+};
+
+/**
+ * Was this file invoked directly?
+ *
+ * Compared by REALPATH on both sides: ESM resolves `import.meta.url` through
+ * symlinks while `process.argv[1]` keeps the path as typed, so a project living
+ * under a symlinked directory (a macOS temp dir, a symlinked home, a checkout
+ * behind a link) would fail a naive equality check — and the script would exit 0
+ * having printed nothing, which reads exactly like "no findings".
+ */
+const invokedDirectly = () => {
+  if (!process.argv[1]) return false;
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  return real(fileURLToPath(import.meta.url)) === real(process.argv[1]);
+};
+
+if (invokedDirectly()) {
+  const checks = {
+    killSwitch: checkKillSwitch(),
+    defaultBranchFresh: checkDefaultBranchFresh(),
+    lastDeploy: checkLastDeploy(),
+  };
+  const result = report(checks);
+  process.stdout.write(
+    process.argv.includes('--json')
+      ? `${JSON.stringify(result, null, 2)}\n`
+      : `${result.rendered}\n`,
+  );
+}