@codedology/code-forge 0.1.0

package/src/engines/render-rules.mjs

@@ -0,0 +1,41 @@
+/**
+ * Small shared helpers over a forbidden-list RENDER — the shape `renderForClaude`/`renderForGrok`
+ * (`{id, rules: string[], enforced}[]`) or `renderForCodex` (`{id, patterns: string[][],
+ * enforced}[]`) from `src/util/forbidden.mjs` (B0/B8) return. Used by `builders/claude.mjs` and
+ * `builders/grok.mjs` so the "flatten every entry's rules into one argv run" logic exists once,
+ * not twice, and by all three coder builders to refuse an empty render (fix round 1, MAJOR: a
+ * coder role must always carry a non-empty forbidden list — a renderer regression that returns
+ * nothing must be a thrown error, not a silently-empty `--disallowedTools`/rules file).
+ *
+ * `idsMissingFromArgv` moved OUT of this file in fix round 1 (MINOR, dead-code finding): nothing
+ * under `src/` ever called it — only tests did — so it now lives in
+ * `test/engines/builders/argv-check.mjs`, alongside the `.every`-not-`.some` fix and two new
+ * position-aware helpers the review asked for.
+ */
+
+/**
+ * @typedef {{id: string, rules?: ReadonlyArray<string>, patterns?: ReadonlyArray<ReadonlyArray<string>>, enforced: boolean}} RenderedEntry
+ */
+
+/**
+ * @param {ReadonlyArray<{id: string, rules: ReadonlyArray<string>, enforced: boolean}>} rendered
+ * @returns {string[]} every rule string of every entry, in entry order, entry-internal order
+ *   preserved (an `enforced: false` entry contributes an empty `rules` array, so it drops out
+ *   naturally rather than needing a separate filter).
+ */
+export function flattenRuleStrings(rendered) {
+  return rendered.flatMap((entry) => [...entry.rules]);
+}
+
+/**
+ * Whether a render has AT LEAST ONE usable rule/pattern anywhere across its entries — the guard a
+ * coder-role builder throws on when this is false (a coder must always carry a real forbidden
+ * list; an empty one is a renderer regression, never a legitimate state). Works for both the
+ * Claude/Grok shape (`rules`) and the Codex shape (`patterns`) without the caller needing to know
+ * which.
+ * @param {ReadonlyArray<RenderedEntry>} rendered
+ * @returns {boolean}
+ */
+export function hasAnyRenderedRule(rendered) {
+  return rendered.some((entry) => (entry.rules?.length ?? 0) > 0 || (entry.patterns?.length ?? 0) > 0);
+}

package/src/engines/sentinel.mjs

@@ -0,0 +1,133 @@
+/**
+ * The subprocess-mode coder sentinel contract (plan §5.2, §5.3, C11) and the `ACK <sha8>
+ * lines=<n>` wire receipt.
+ *
+ * **Sentinel.** A coder prints `===BLOCK <id> COMPLETE===` on success or `===BLOCK <id> FAILED:
+ * <reason>===` on failure (§10.7's forecast-exceeded stop line — `===BLOCK <id> FAILED: forecast
+ * exceeded, split plan <id>a/<id>b===` — is one concrete instance of the FAILED shape). A coder can
+ * print MORE than one of these across a long-running transcript (a retry after a local fix, a
+ * revised final report); `parseSentinel` always takes the LAST occurrence, never the first (plan
+ * §5.2: "`sentinel.mjs` takes the **last** occurrence"). Both patterns are anchored to the WHOLE
+ * trimmed line (`^...$`), so a coder quoting the sentinel text inside ordinary prose ("I will not
+ * print ===BLOCK B4 COMPLETE=== yet") never matches — only a line that IS exactly the sentinel does.
+ *
+ * **ACK.** Before any tool call, a coder replies `ACK <sha8> lines=<n>` to the wire receipt it was
+ * sent — the sha of the brief file, truncated to 8 hex characters (matched case-insensitively;
+ * compared lowercased), and the brief's line count. `parseAck` returns the LAST matching line (fix
+ * round 1, MAJOR): the protocol is "no/wrong ACK within the launch window ⇒ resend once" (§5.2),
+ * so when a caller passes the transcript up through a resend, the LAST ACK is the one that reflects
+ * whether the resend succeeded — a first-match reading would report the pre-resend failure even
+ * after a successful resend. An optional `after` marker lets a caller scope the search to
+ * everything strictly after the last occurrence of that marker (e.g. the literal wire-receipt text
+ * that was just (re)sent), which also defends against an unrelated earlier line that happens to
+ * look like an ACK (an echoed instruction, a quoted example) being mistaken for the real one.
+ */
+
+/** @typedef {{status: "complete", blockId: string} | {status: "failed", blockId: string, reason: string}} SentinelResult */
+
+const COMPLETE_RE = /^===BLOCK\s+(\S+)\s+COMPLETE===$/;
+const FAILED_RE = /^===BLOCK\s+(\S+)\s+FAILED:\s*(.*?)\s*===$/;
+
+/**
+ * @param {string} output - the full captured transcript (subprocess stdout, or a Solo
+ *   `get_process_output` join).
+ * @param {string} [blockId] - when given, only sentinel lines for THIS block id count — a shared
+ *   pane/log can interleave another block's lines.
+ * @returns {SentinelResult | null} the LAST matching sentinel line, or `null` if none is present.
+ */
+export function parseSentinel(output, blockId) {
+  if (typeof output !== 'string') {
+    throw new TypeError('parseSentinel: output must be a string');
+  }
+  /** @type {SentinelResult | null} */
+  let last = null;
+  for (const rawLine of output.split('\n')) {
+    const line = rawLine.trim();
+    const complete = COMPLETE_RE.exec(line);
+    if (complete && (!blockId || complete[1] === blockId)) {
+      last = { status: 'complete', blockId: complete[1] };
+      continue;
+    }
+    const failed = FAILED_RE.exec(line);
+    if (failed && (!blockId || failed[1] === blockId)) {
+      last = { status: 'failed', blockId: failed[1], reason: failed[2] };
+    }
+  }
+  return last;
+}
+
+/** @typedef {{sha8: string, lines: number}} ParsedAck */
+
+/** Case-insensitive: normalized to lowercase before comparison in {@link verifyAck}. */
+const ACK_RE = /^ACK\s+([0-9a-fA-F]{8})\s+lines=(\d+)\s*$/;
+
+/**
+ * @param {string} output
+ * @param {{after?: string} | null} [opts] - `after`: only text strictly after the LAST occurrence
+ *   of this marker is searched (the whole `output` is searched when omitted or not found). `opts`
+ *   may be `null`; `after` must be a non-empty string when given (TypeError otherwise).
+ * @returns {ParsedAck | null} the LAST `ACK <sha8> lines=<n>` line in the searched window (fix
+ *   round 1, MAJOR — was the first).
+ */
+export function parseAck(output, opts = {}) {
+  if (typeof output !== 'string') {
+    throw new TypeError('parseAck: output must be a string');
+  }
+  const after = opts?.after;
+  if (after !== undefined && (typeof after !== 'string' || after.length === 0)) {
+    // An empty marker would make `lastIndexOf` return output.length and empty the window.
+    throw new TypeError('parseAck: opts.after must be a non-empty string when given');
+  }
+  let window = output;
+  if (after !== undefined) {
+    const idx = output.lastIndexOf(after);
+    if (idx !== -1) window = output.slice(idx + after.length);
+  }
+  /** @type {ParsedAck | null} */
+  let last = null;
+  for (const rawLine of window.split('\n')) {
+    const match = ACK_RE.exec(rawLine.trim());
+    if (match) {
+      last = { sha8: match[1].toLowerCase(), lines: Number(match[2]) };
+    }
+  }
+  return last;
+}
+
+/** @typedef {{status: "ok", ack: ParsedAck} | {status: "parked", reason: string}} AckVerification */
+
+const SHA8_RE = /^[0-9a-fA-F]{8}$/;
+
+/**
+ * @param {string} output
+ * @param {string} expectedSha8 - exactly 8 hex characters (case-insensitive).
+ * @param {number} [expectedLines] - when given, a line-count mismatch also parks (the brief was
+ *   truncated in flight).
+ * @param {{after?: string} | null} [opts] - forwarded to {@link parseAck}.
+ * @returns {AckVerification}
+ * @throws {TypeError} if `expectedSha8` is not exactly 8 hex characters — a caller passing a full
+ *   40-character sha (or any other malformed value) gets a clear refusal here instead of a
+ *   confusing "no ACK" / "sha mismatch" `parked` result. Also if `expectedLines` is given but is
+ *   not a non-negative integer (null, NaN, a numeric string), instead of a misleading
+ *   "ACK lines mismatch" park.
+ */
+export function verifyAck(output, expectedSha8, expectedLines, opts = {}) {
+  if (typeof expectedSha8 !== 'string' || !SHA8_RE.test(expectedSha8)) {
+    throw new TypeError(`verifyAck: expectedSha8 must be exactly 8 hex characters, got ${JSON.stringify(expectedSha8)}`);
+  }
+  if (expectedLines !== undefined && !(Number.isInteger(expectedLines) && expectedLines >= 0)) {
+    throw new TypeError(`verifyAck: expectedLines must be a non-negative integer when given, got ${JSON.stringify(expectedLines)}`);
+  }
+  const normalizedExpected = expectedSha8.toLowerCase();
+  const ack = parseAck(output, opts);
+  if (!ack) {
+    return { status: 'parked', reason: 'no ACK line found in the searched window' };
+  }
+  if (ack.sha8 !== normalizedExpected) {
+    return { status: 'parked', reason: `ACK sha mismatch: expected ${normalizedExpected}, got ${ack.sha8}` };
+  }
+  if (expectedLines !== undefined && ack.lines !== expectedLines) {
+    return { status: 'parked', reason: `ACK lines mismatch: expected ${expectedLines}, got ${ack.lines}` };
+  }
+  return { status: 'ok', ack };
+}

package/src/engines/usage-parse.mjs

@@ -0,0 +1,149 @@
+/**
+ * Token-usage extraction from a provider CLI's own JSON output (plan §6.1: "Tokens: reported when
+ * the CLI's JSON carries usage (`claude -p --output-format json` does `[A2]`; Codex/Grok
+ * best-effort `[A14]`), else `estimated`. **Tokens are facts, dollars are estimates.**").
+ *
+ * **Not independently verified on this Mac** — the plan's own `[A2]`/`[A14]` tags mean the exact
+ * JSON field names were not read from a real run for this revision (only `--help` text was; §0.6.8
+ * tolerates this for the ledger's `tokens_source` field). This parser is deliberately lenient: it
+ * tries the field names each vendor's own API/CLI documentation uses elsewhere, and falls back to
+ * `tokensSource: "estimated"` rather than throwing when none match — a shape drift here must never
+ * crash a review or a coder run, only degrade the ledger's tokens field, exactly as §6.1 describes.
+ *
+ * **Fix round 1 (isolated per-file review):**
+ *  - **Claude**: `input_tokens` alone undercounts a cached run — Anthropic's Messages API (which
+ *    Claude Code's own JSON result reuses) reports prompt-cache reads/writes as SEPARATE fields
+ *    (`cache_creation_input_tokens`, `cache_read_input_tokens`), NOT folded into `input_tokens`.
+ *    `tokensIn` is now their sum, and the individual cache fields are kept on the returned record
+ *    (`cacheCreationTokens`/`cacheReadTokens`) so a caller doesn't lose the split.
+ *  - `PARSERS[cli]`/`Object.hasOwn`: the cli lookup is now guarded so `parseUsage('constructor',
+ *    …)` (and `'toString'`, `'__proto__'`, …) hits the documented "unknown cli" error instead of a
+ *    prototype-chain member.
+ *  - Codex/Grok no longer mix naming schemes within one payload: `tokensIn` from `input_tokens` and
+ *    `tokensOut` from `completion_tokens` (two different vendors' field names) never happens now —
+ *    one scheme is picked (input_tokens/output_tokens if BOTH present, else prompt_tokens/
+ *    completion_tokens if BOTH present, else `estimated`).
+ *  - JSDoc on `parseCodexUsage` now names exactly which Codex `--json` event a caller must pass.
+ */
+
+/**
+ * @typedef {{tokensIn: number, tokensOut: number, tokensSource: "reported", cacheCreationTokens?: number, cacheReadTokens?: number}
+ *   | {tokensIn: null, tokensOut: null, tokensSource: "estimated"}} UsageResult
+ */
+
+const ESTIMATED = Object.freeze({ tokensIn: null, tokensOut: null, tokensSource: /** @type {"estimated"} */ ('estimated') });
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+function asNonNegativeInt(value) {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+
+/**
+ * Claude Code `-p --output-format json` result shape: a top-level `usage` object with
+ * `input_tokens`/`output_tokens` (Anthropic Messages API field names, which Claude Code's own JSON
+ * result reuses), PLUS `cache_creation_input_tokens`/`cache_read_input_tokens` when prompt caching
+ * was used — both optional, defaulting to 0, folded into `tokensIn` and also kept split.
+ * @param {unknown} parsed
+ * @returns {UsageResult}
+ */
+function parseClaudeUsage(parsed) {
+  if (!isPlainObject(parsed) || !isPlainObject(parsed.usage)) return ESTIMATED;
+  const usage = parsed.usage;
+  const baseIn = asNonNegativeInt(usage.input_tokens);
+  const tokensOut = asNonNegativeInt(usage.output_tokens);
+  if (baseIn === undefined || tokensOut === undefined) return ESTIMATED;
+  // Optional cache fields: absent OR `null` is legitimate (no caching happened; the Messages API
+  // types both as `integer | null`) and treated as 0 without setting the split field. A
+  // present, non-null, malformed value (negative, non-integer) must not be silently ignored — it
+  // falls back to the whole result being `estimated`, same as a malformed base field would.
+  const hasCacheCreation = usage.cache_creation_input_tokens != null;
+  const hasCacheRead = usage.cache_read_input_tokens != null;
+  const cacheCreation = hasCacheCreation ? asNonNegativeInt(usage.cache_creation_input_tokens) : 0;
+  const cacheRead = hasCacheRead ? asNonNegativeInt(usage.cache_read_input_tokens) : 0;
+  if (cacheCreation === undefined || cacheRead === undefined) return ESTIMATED;
+  return {
+    tokensIn: baseIn + cacheCreation + cacheRead,
+    tokensOut,
+    tokensSource: 'reported',
+    ...(hasCacheCreation ? { cacheCreationTokens: cacheCreation } : {}),
+    ...(hasCacheRead ? { cacheReadTokens: cacheRead } : {}),
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} usage
+ * @returns {{tokensIn: number, tokensOut: number} | undefined} both fields from ONE naming scheme
+ *   only — `input_tokens`/`output_tokens` if BOTH are present and valid, else `prompt_tokens`/
+ *   `completion_tokens` if BOTH are, else `undefined`. Never mixes a field from one scheme with a
+ *   field from the other (fix round 1, MINOR).
+ */
+function oneSchemeTokens(usage) {
+  const anthropicIn = asNonNegativeInt(usage.input_tokens);
+  const anthropicOut = asNonNegativeInt(usage.output_tokens);
+  if (anthropicIn !== undefined && anthropicOut !== undefined) {
+    return { tokensIn: anthropicIn, tokensOut: anthropicOut };
+  }
+  const openaiIn = asNonNegativeInt(usage.prompt_tokens);
+  const openaiOut = asNonNegativeInt(usage.completion_tokens);
+  if (openaiIn !== undefined && openaiOut !== undefined) {
+    return { tokensIn: openaiIn, tokensOut: openaiOut };
+  }
+  return undefined;
+}
+
+/**
+ * Codex `--json` prints one JSONL EVENT per line, not a single result object; usage lives on the
+ * turn-completion event (the one carrying a `usage` object — Codex's own docs do not name a fixed
+ * event-type string this build can pin against yet, `[A14]`). **The caller is responsible for
+ * locating and passing that ONE parsed event object** — this function does not scan a list of
+ * events or sum usage across turns; a caller with a multi-turn run must do that summation itself
+ * before calling this, or accept per-turn `estimated`/`reported` rows.
+ * @param {unknown} parsed - one already-located, already-parsed Codex event object.
+ * @returns {UsageResult}
+ */
+function parseCodexUsage(parsed) {
+  if (!isPlainObject(parsed) || !isPlainObject(parsed.usage)) return ESTIMATED;
+  const tokens = oneSchemeTokens(parsed.usage);
+  return tokens ? { ...tokens, tokensSource: 'reported' } : ESTIMATED;
+}
+
+/**
+ * Grok `usage` subcommand / JSON output: best-effort, same single-scheme field acceptance as
+ * Codex — no verified sample exists for either.
+ * @param {unknown} parsed
+ * @returns {UsageResult}
+ */
+function parseGrokUsage(parsed) {
+  return parseCodexUsage(parsed);
+}
+
+/** @type {Readonly<Record<"claude"|"codex"|"grok", (parsed: unknown) => UsageResult>>} */
+const PARSERS = Object.freeze({ claude: parseClaudeUsage, codex: parseCodexUsage, grok: parseGrokUsage });
+
+/**
+ * @param {"claude"|"codex"|"grok"} cli
+ * @param {unknown} parsedJSON - already `JSON.parse`d CLI output (this module never parses raw
+ *   text itself — a malformed JSON string is the caller's problem to report, not silently degrade
+ *   into "estimated" here).
+ * @returns {UsageResult}
+ * @throws {Error} for an unknown `cli` — guarded with `Object.hasOwn` so a prototype-chain name
+ *   (`"constructor"`, `"toString"`, `"__proto__"`, …) hits this same error instead of an unrelated
+ *   crash or a wrong result (fix round 1, MINOR).
+ */
+export function parseUsage(cli, parsedJSON) {
+  if (typeof cli !== 'string' || !Object.hasOwn(PARSERS, cli)) {
+    throw new Error(`parseUsage: unknown cli "${cli}"`);
+  }
+  return PARSERS[/** @type {"claude"|"codex"|"grok"} */ (cli)](parsedJSON);
+}

package/src/gates/acceptance.mjs

@@ -0,0 +1,95 @@
+/**
+ * Acceptance-clause coverage (plan §4.6 row 4, O17): "every clause names ≥ 1 test id; each named
+ * test exists in the tree and passed in this gate run (parsed from the runner output)." This is
+ * DETERMINISTIC — S1's `scope` question (§3.2) judges only whether hunks OUTSIDE the named tests
+ * are unrelated; whether a named test id actually passed is a fact, never a model's opinion.
+ *
+ * `parseTapPassed` reads real TAP (RFC-ish "TAP version 13") output — the default `node --test`
+ * reporter on this Mac (verified: `node --test` with no `--test-reporter` flag prints
+ * `TAP version 13` / `ok N - <name>` / `not ok N - <name>`, 2026-09-24) — into passed/failed name
+ * sets. A project on a different runner supplies its own `passed` set built however fits that
+ * runner's output; `checkAcceptance` itself does not care where the set came from.
+ */
+
+/**
+ * @typedef {{clause: string, tests: string[]}} AcceptanceClause
+ * @typedef {{ok: true} | {ok: false, reason: string, clause: string, test: string}} AcceptanceResult
+ */
+
+/** A TAP directive suffix on a test description (`name # SKIP reason`, `name # TODO reason`). */
+const TAP_DIRECTIVE = /^(.*?)\s*#\s*(SKIP|TODO)\b/i;
+
+/**
+ * @param {string} text - the captured `<name...>` portion of an `ok`/`not ok` TAP line.
+ * @returns {{name: string, directive: 'SKIP' | 'TODO' | null}}
+ */
+function parseNameAndDirective(text) {
+  const m = TAP_DIRECTIVE.exec(text);
+  return m ? { name: m[1].trim(), directive: /** @type {'SKIP'|'TODO'} */ (m[2].toUpperCase()) } : { name: text.trim(), directive: null };
+}
+
+/**
+ * @param {string} output - raw TAP text from a test-runner invocation.
+ * @returns {{passed: Set<string>, failed: Set<string>}}
+ */
+export function parseTapPassed(output) {
+  /** @type {Set<string>} */
+  const passed = new Set();
+  /** @type {Set<string>} */
+  const failed = new Set();
+  for (const rawLine of String(output).split('\n')) {
+    const line = rawLine.trim();
+    const ok = /^ok\s+\d+\s+-\s+(.+)$/.exec(line);
+    if (ok) {
+      const { name, directive } = parseNameAndDirective(ok[1]);
+      // `node --test` reports a skipped or todo test as an "ok" TAP line with a `# SKIP`/`# TODO`
+      // directive — it did not actually run to a real pass, so it must NOT satisfy an acceptance
+      // clause (O17: "passed in this gate run", not merely "not reported as failed").
+      if (directive === null) passed.add(name);
+      continue;
+    }
+    const notOk = /^not ok\s+\d+\s+-\s+(.+)$/.exec(line);
+    if (notOk) {
+      failed.add(parseNameAndDirective(notOk[1]).name);
+    }
+  }
+  return { passed, failed };
+}
+
+/**
+ * @param {ReadonlyArray<AcceptanceClause>} clauses - each must name ≥ 1 test id.
+ * @param {Set<string> | ReadonlyArray<string>} passed - test ids that passed in THIS gate run.
+ * @param {Set<string> | ReadonlyArray<string>} [failed] - test ids that FAILED in this gate run.
+ *   `parseTapPassed` flattens every file's/describe-block's TAP subtests into one global name set,
+ *   so two unrelated tests can share a name; when one passes and the other fails, that name lands
+ *   in BOTH sets. `failed` is checked independently of `passed` so that ambiguity never accepts a
+ *   clause on the strength of some OTHER test with the same name having passed.
+ * @returns {AcceptanceResult} refused (naming the offending clause and test) on the FIRST clause
+ *   whose acceptance is not fully covered; `{ok: true}` only when every clause's every named test
+ *   id is in `passed` and NOT in `failed`.
+ */
+export function checkAcceptance(clauses, passed, failed = new Set()) {
+  if (!Array.isArray(clauses) || clauses.length === 0) {
+    return { ok: false, reason: 'no acceptance clauses given', clause: '', test: '' };
+  }
+  const passedSet = passed instanceof Set ? passed : new Set(passed);
+  const failedSet = failed instanceof Set ? failed : new Set(failed);
+  for (const entry of clauses) {
+    const clause = entry?.clause;
+    const tests = entry?.tests;
+    if (typeof clause !== 'string' || clause.length === 0 || !Array.isArray(tests) || tests.length === 0) {
+      return { ok: false, reason: 'clause names no test id', clause: String(clause ?? ''), test: '' };
+    }
+    for (const test of tests) {
+      if (failedSet.has(test) || !passedSet.has(test)) {
+        return {
+          ok: false,
+          reason: `clause "${clause}" names test "${test}", which did not exist or did not pass in this gate run`,
+          clause,
+          test,
+        };
+      }
+    }
+  }
+  return { ok: true };
+}

package/src/gates/detect.mjs

@@ -0,0 +1,187 @@
+/**
+ * Gate auto-detection (plan §2.2, `src/gates/detect.mjs`): given a project root, decide which
+ * stack it is and produce the four gate commands (`test`, `lint`, `types`, `format`) as argv
+ * arrays, or `null` when the stack has no tool for that gate. Detection is pure filesystem
+ * evidence (`fs.existsSync`/`readFileSync`) — no `git`, no child process, no network.
+ *
+ * Evidence is checked in the table's own order (PHP/Pest, then `package.json` scripts, Cargo,
+ * pyproject, go.mod); the first stack whose marker file exists wins. A project with no marker
+ * file at all is `unknown`: every gate is `null`, and `code` (a later block) refuses to run a
+ * block whose `gates.test` is null — a block without a test gate cannot produce evidence.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * A gate command is normally a plain argv array (its own exit code decides red/green). Some tools
+ * (`gofmt -l`) exit 0 regardless of whether anything is unformatted and instead print the
+ * offending file names to stdout — for those, the descriptor carries `failOnStdout: true` so
+ * `run.mjs` treats non-empty stdout as red too, since a bare exit-code check can never fail.
+ * @typedef {string[] | {argv: string[], failOnStdout: true}} GateCommand
+ * @typedef {GateCommand | null} Gate
+ */
+/** @typedef {{stack: string, test: Gate, lint: Gate, types: Gate, format: Gate}} DetectedGates */
+
+/** @param {string} root @param {string} rel @returns {boolean} */
+function has(root, rel) {
+  return existsSync(path.join(root, rel));
+}
+
+/**
+ * @param {string} root @param {string} rel
+ * @returns {Record<string, any> | null} parsed JSON, or null when the file is absent or invalid.
+ */
+function readJSON(root, rel) {
+  try {
+    return JSON.parse(readFileSync(path.join(root, rel), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** @param {string} root @param {string} rel @returns {string | null} */
+function readText(root, rel) {
+  try {
+    return readFileSync(path.join(root, rel), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// ── PHP / Pest ───────────────────────────────────────────────────────────────
+
+/** @param {string} root @returns {DetectedGates | null} */
+function detectPhp(root) {
+  if (!has(root, 'composer.json') || !has(root, 'vendor/bin/pest')) return null;
+  const test = has(root, 'artisan') ? ['php', 'artisan', 'test', '--compact'] : ['vendor/bin/pest'];
+  const types = has(root, 'phpstan.neon') || has(root, 'phpstan.neon.dist') ? ['vendor/bin/phpstan'] : null;
+  const format = has(root, 'pint.json') || has(root, 'vendor/bin/pint') ? ['vendor/bin/pint', '--test'] : null;
+  return { stack: 'php-pest', test, lint: null, types, format };
+}
+
+// ── Node (package.json scripts) ────────────────────────────────────────────
+
+/**
+ * `pm` resolution order (§2.2): the `packageManager` field, then the lockfile present
+ * (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn), else `npm`.
+ * @param {string} root @param {Record<string, any>} pkg @returns {string}
+ */
+function resolvePackageManager(root, pkg) {
+  if (typeof pkg.packageManager === 'string' && pkg.packageManager.length > 0) {
+    const name = pkg.packageManager.split('@')[0];
+    if (name === 'pnpm' || name === 'yarn' || name === 'npm' || name === 'bun') return name;
+  }
+  if (has(root, 'pnpm-lock.yaml')) return 'pnpm';
+  if (has(root, 'yarn.lock')) return 'yarn';
+  return 'npm';
+}
+
+/**
+ * A `package.json` `devDependencies`/`dependencies` entry named `dep`.
+ * @param {Record<string, any>} pkg @param {string} dep @returns {boolean}
+ */
+function hasDependency(pkg, dep) {
+  return Boolean(pkg.dependencies?.[dep] || pkg.devDependencies?.[dep]);
+}
+
+/** @param {string} root @returns {DetectedGates | null} */
+function detectNode(root) {
+  const pkg = readJSON(root, 'package.json');
+  if (!pkg || typeof pkg !== 'object') return null;
+  const scripts = pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+  if (typeof scripts.test !== 'string') return null;
+
+  const pm = resolvePackageManager(root, pkg);
+  // `bun test` invokes Bun's OWN built-in test runner and ignores the package.json `test` script
+  // entirely — `bun run test` is the form that actually runs the configured script, matching
+  // every other package manager's `[pm, "test"]` shorthand behaviour.
+  const test = pm === 'bun' ? [pm, 'run', 'test'] : [pm, 'test'];
+
+  let lint = null;
+  if (typeof scripts.lint === 'string') lint = [pm, 'run', 'lint'];
+  else if (typeof scripts['lint:check'] === 'string') lint = [pm, 'run', 'lint:check'];
+
+  let types = null;
+  if (typeof scripts.typecheck === 'string') types = [pm, 'run', 'typecheck'];
+  else if (typeof scripts['vue-tsc'] === 'string') types = [pm, 'run', 'vue-tsc'];
+  else if (has(root, 'tsconfig.json')) types = ['npx', 'tsc', '--noEmit'];
+
+  let format = null;
+  if (typeof scripts['format:check'] === 'string') format = [pm, 'run', 'format:check'];
+  else if (has(root, '.prettierrc') || has(root, '.prettierrc.json') || has(root, '.prettierrc.js') || hasDependency(pkg, 'prettier')) {
+    format = ['npx', 'prettier', '--check', '.'];
+  }
+
+  return { stack: 'node', test, lint, types, format };
+}
+
+// ── Cargo ───────────────────────────────────────────────────────────────────
+
+/** @param {string} root @returns {DetectedGates | null} */
+function detectRust(root) {
+  if (!has(root, 'Cargo.toml')) return null;
+  return {
+    stack: 'rust',
+    test: ['cargo', 'test'],
+    lint: ['cargo', 'clippy', '--', '-D', 'warnings'],
+    types: null,
+    format: ['cargo', 'fmt', '--check'],
+  };
+}
+
+// ── Python (pyproject.toml) ─────────────────────────────────────────────────
+
+/** @param {string} text @returns {boolean} a `[tool.mypy]` section is present. */
+function hasMypySection(text) {
+  return /^\[tool\.mypy(\..+)?\]\s*$/m.test(text);
+}
+
+/** @param {string} root @returns {DetectedGates | null} */
+function detectPython(root) {
+  const text = readText(root, 'pyproject.toml');
+  if (text === null) return null;
+  return {
+    stack: 'python',
+    test: ['pytest'],
+    lint: ['ruff', 'check'],
+    types: hasMypySection(text) ? ['mypy'] : null,
+    format: ['ruff', 'format', '--check'],
+  };
+}
+
+// ── Go ───────────────────────────────────────────────────────────────────────
+
+/** @param {string} root @returns {DetectedGates | null} */
+function detectGo(root) {
+  if (!has(root, 'go.mod')) return null;
+  return {
+    stack: 'go',
+    test: ['go', 'test', './...'],
+    lint: ['go', 'vet', './...'],
+    types: null,
+    // `gofmt -l` prints the names of unformatted files to stdout but ALWAYS exits 0 — a bare
+    // exit-code check can never turn this gate red. `failOnStdout` tells run.mjs to also treat
+    // non-empty stdout as a failure.
+    format: { argv: ['gofmt', '-l', '.'], failOnStdout: true },
+  };
+}
+
+/** Detectors in table order — the first stack whose marker evidence exists wins. */
+const DETECTORS = Object.freeze([detectPhp, detectNode, detectRust, detectPython, detectGo]);
+
+/**
+ * @param {string} root - an absolute path to a project root.
+ * @returns {DetectedGates} the detected stack and its four gate commands (argv or null each).
+ *   `stack: 'unknown'` with every gate `null` when no marker evidence matches.
+ */
+export function detectGates(root) {
+  if (typeof root !== 'string' || root.length === 0) {
+    throw new TypeError('detectGates: root must be a non-empty string');
+  }
+  for (const detector of DETECTORS) {
+    const result = detector(root);
+    if (result) return result;
+  }
+  return { stack: 'unknown', test: null, lint: null, types: null, format: null };
+}

package/src/gates/invariants.mjs

@@ -0,0 +1,43 @@
+/**
+ * The invariants gate (plan §1.3 `gates.extra.invariants`: a project-configured PATH, unlike
+ * `secret_scan`/`safe_edit` which are booleans). A project may keep its own structural checks —
+ * comment-only diffs, forbidden patterns, naming conventions — as one executable script; when
+ * `gates.extra.invariants` names it, this gate runs it exactly like `run.mjs` runs `test`/`lint`/
+ * `types`/`format`: one argv, its own exit status read on its own, never chained.
+ *
+ * Unset (`undefined`/empty) is a pass-through, not a failure — a project with no invariants script
+ * simply has nothing extra to check.
+ */
+
+import path from 'node:path';
+import { exec } from '../util/exec.mjs';
+
+/**
+ * @typedef {object} InvariantsResult
+ * @property {boolean} skipped - true when no `invariantsPath` was configured.
+ * @property {boolean} ok
+ * @property {number | null} code
+ * @property {string} stdout
+ * @property {string} stderr
+ */
+
+/**
+ * @param {{cwd: string, invariantsPath?: string | null, timeoutMs?: number}} opts
+ * @returns {Promise<InvariantsResult>}
+ */
+export async function runInvariants(opts) {
+  const { cwd, invariantsPath, timeoutMs = 120000 } = opts ?? {};
+  if (typeof cwd !== 'string' || cwd.length === 0) {
+    throw new TypeError('runInvariants: opts.cwd must be a non-empty string');
+  }
+  if (!invariantsPath) {
+    return { skipped: true, ok: true, code: null, stdout: '', stderr: '' };
+  }
+  // A bare filename (no slash) would otherwise be looked up on PATH instead of the project root,
+  // and a relative path would resolve against the CHILD process's cwd only by accident (it
+  // happens to be the same as `cwd` here, but that's not guaranteed once this call has a caller
+  // with its own cwd) — resolve against the project root explicitly either way.
+  const resolvedPath = path.resolve(cwd, invariantsPath);
+  const res = await exec([resolvedPath], { cwd, timeoutMs });
+  return { skipped: false, ok: res.result === 'ok', code: res.code, stdout: res.stdout, stderr: res.stderr };
+}