@codedology/code-forge 0.1.0

package/src/gates/run.mjs

@@ -0,0 +1,72 @@
+/**
+ * The gate runner (plan §4.6 row 3: "all gates green in one run — each exit status read"). Runs
+ * every configured gate command (`test`, `lint`, `types`, `format`) INDEPENDENTLY — never chained
+ * with `&&`, so a red gate never hides the ones after it: "a red gate in the middle of 3 is
+ * reported red" means each of the three still gets its own read exit status, not that the run
+ * stops early.
+ */
+
+import { exec } from '../util/exec.mjs';
+
+/** @typedef {import('./detect.mjs').Gate} Gate */
+/** @typedef {import('./detect.mjs').GateCommand} GateCommand */
+/** @typedef {import('./detect.mjs').DetectedGates} DetectedGates */
+
+/**
+ * @typedef {object} GateResult
+ * @property {'test'|'lint'|'types'|'format'} gate
+ * @property {string[] | null} argv
+ * @property {boolean} skipped - true when the gate has no configured command (argv was null).
+ * @property {boolean} ok - true when skipped, or when the command exited with code 0 (and, for a
+ *   `failOnStdout` gate, its stdout was empty).
+ * @property {number | null} code
+ * @property {string} stdout
+ * @property {string} stderr
+ */
+
+/** Fixed run order — always all four, regardless of an earlier one's result. */
+const GATE_ORDER = /** @type {const} */ (['test', 'lint', 'types', 'format']);
+
+/**
+ * A gate command is either a plain argv array or `{argv, failOnStdout: true}` (detect.mjs's
+ * `GateCommand`, e.g. `gofmt -l` which always exits 0). Normalized here so the run loop below has
+ * one shape to deal with.
+ * @param {GateCommand} command
+ * @returns {{argv: string[], failOnStdout: boolean}}
+ */
+function normalizeCommand(command) {
+  if (Array.isArray(command)) return { argv: command, failOnStdout: false };
+  return { argv: command.argv, failOnStdout: command.failOnStdout === true };
+}
+
+/**
+ * @param {{test?: Gate, lint?: Gate, types?: Gate, format?: Gate}} gates
+ * @param {{cwd: string, timeoutMs?: number}} opts
+ * @returns {Promise<{results: GateResult[], allOk: boolean}>}
+ */
+export async function runGates(gates, opts) {
+  if (!gates || typeof gates !== 'object') {
+    throw new TypeError('runGates: gates must be an object with test/lint/types/format');
+  }
+  const { cwd, timeoutMs = 300000 } = opts ?? {};
+  if (typeof cwd !== 'string' || cwd.length === 0) {
+    throw new TypeError('runGates: opts.cwd must be a non-empty string');
+  }
+
+  /** @type {GateResult[]} */
+  const results = [];
+  for (const gate of GATE_ORDER) {
+    const command = gates[gate] ?? null;
+    if (command === null) {
+      results.push({ gate, argv: null, skipped: true, ok: true, code: null, stdout: '', stderr: '' });
+      continue;
+    }
+    const { argv, failOnStdout } = normalizeCommand(command);
+    // Each command is run and its exit status read on its own — never `&&`-chained with the
+    // next, so a red gate is reported red without swallowing the gates that follow it.
+    const res = await exec(argv, { cwd, timeoutMs });
+    const ok = res.result === 'ok' && (!failOnStdout || res.stdout.trim().length === 0);
+    results.push({ gate, argv, skipped: false, ok, code: res.code, stdout: res.stdout, stderr: res.stderr });
+  }
+  return { results, allOk: results.every((r) => r.ok) };
+}

package/src/gates/safe-edit.mjs

@@ -0,0 +1,266 @@
+/**
+ * The safe-edit gate (plan `gates.extra.safe_edit`, default true): abort a block whose diff
+ * deletes a test file, or whose test-declaration count shrinks by more than 20 % against the
+ * block's base — the two ways a coder can make a red suite look green by removing the evidence
+ * instead of fixing the code, per the project's own "verification remains mandatory" rule.
+ *
+ * The decision (`safeEdit`) is a PURE function over two `{file: count}` maps so it is trivial to
+ * test and cannot itself run a process; `checkSafeEdit` is the thin git-backed orchestration that
+ * builds those maps for a real base/working-tree pair. Every git call strips inherited `GIT_*` env
+ * (a hook's `GIT_DIR` would silently redirect the read) and disables system/global config.
+ */
+
+import os from 'node:os';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { exec } from '../util/exec.mjs';
+import { showArgv } from '../util/git.mjs';
+
+/** Fraction of the base test count below which the shrink aborts the gate (a >20% shrink). */
+export const SHRINK_THRESHOLD = 0.8;
+
+/**
+ * File-name → stack, by basename pattern. A LIST (not a map keyed by stack) checked in order,
+ * because file-classification and declaration-counting must agree on exactly one stack per file —
+ * summing every stack's declaration pattern over one file double-counts wherever two stacks'
+ * patterns overlap (PHP's `\btest\(`/`\bit\(` also match plain JS `test('x', ...)`/`it('x', ...)`
+ * calls character-for-character), which is exactly the bug this per-file classification avoids.
+ * @type {ReadonlyArray<{stack: string, pattern: RegExp}>}
+ */
+const TEST_FILE_KINDS = Object.freeze([
+  { stack: 'node', pattern: /\.test\.[cm]?[jt]sx?$/ }, // foo.test.mjs, foo.test.ts
+  { stack: 'node', pattern: /\.spec\.[cm]?[jt]sx?$/ },
+  { stack: 'php', pattern: /Test\.php$/ }, // PHPUnit/Pest class-style
+  { stack: 'python', pattern: /^test_.*\.py$/ }, // pytest
+  { stack: 'go', pattern: /_test\.go$/ },
+  // Rust has no test-FILE naming convention (a #[test] can live in any .rs file) — safe-edit's
+  // file-level "deleted test file" check does not apply to it; `countTestDeclarations(x, 'rust')`
+  // is still directly usable by a caller that already knows a given file is a rust test module.
+]);
+
+/** Per-stack test-declaration regexes (global, so `matchAll` can count every occurrence). */
+const TEST_DECL_PATTERNS = Object.freeze({
+  node: /\b(?:test|it)\s*\(/g,
+  php: /(?:public\s+function\s+test[A-Z_]\w*\s*\(|\bit\s*\(|\btest\s*\()/g,
+  python: /^\s*def test_\w+/gm,
+  rust: /#\[test\]/g,
+  go: /^func Test[A-Z]\w*/gm,
+});
+
+/**
+ * @param {string} filePath
+ * @returns {string | null} the stack `filePath`'s basename matches, by naming convention, or
+ *   `null` when none does — the file is not treated as a test file at all.
+ */
+function classifyTestFile(filePath) {
+  const base = path.basename(filePath);
+  const kind = TEST_FILE_KINDS.find(({ pattern }) => pattern.test(base));
+  return kind ? kind.stack : null;
+}
+
+/**
+ * @param {string} filePath
+ * @returns {boolean} whether `filePath`'s basename matches a known test-file naming convention.
+ */
+export function isTestFile(filePath) {
+  return classifyTestFile(filePath) !== null;
+}
+
+/**
+ * Count test declarations in `content`, using ONLY the given stack's pattern — never every
+ * pattern summed, which would double-count where two stacks' patterns overlap (see
+ * `TEST_FILE_KINDS`'s doc). A caller that does not already know the file's stack should classify
+ * it first (`isTestFile` alone only says yes/no; this module classifies internally via
+ * `classifyTestFile` for its own git-backed orchestration below).
+ * @param {string} content @param {string} stack - one of `TEST_DECL_PATTERNS`'s keys.
+ * @returns {number}
+ * @throws {TypeError} on an unknown stack.
+ */
+export function countTestDeclarations(content, stack) {
+  const pattern = /** @type {Record<string, RegExp>} */ (TEST_DECL_PATTERNS)[stack];
+  if (!pattern) {
+    throw new TypeError(`countTestDeclarations: unknown stack ${JSON.stringify(stack)} (known: ${Object.keys(TEST_DECL_PATTERNS).join(', ')})`);
+  }
+  // The pattern object carries the `g` flag's own `lastIndex`; matchAll on a fresh copy avoids
+  // any stateful reuse across calls.
+  return [...content.matchAll(new RegExp(pattern.source, pattern.flags))].length;
+}
+
+/**
+ * @typedef {Record<string, number>} CountsByFile - test-declaration count per test-file path.
+ * @typedef {{ok: true} | {ok: false, reason: string}} SafeEditResult
+ */
+
+/**
+ * The pure decision (plan acceptance: "aborts on a >20% test-count shrink and on a deleted test
+ * file"). Deleted-file check runs first: a deleted file makes the shrink check redundant but a
+ * caller should see the more specific reason.
+ * @param {{base: CountsByFile, current: CountsByFile}} counts
+ * @returns {SafeEditResult}
+ */
+export function safeEdit({ base, current }) {
+  const deleted = Object.keys(base).filter((file) => !(file in current));
+  if (deleted.length > 0) {
+    return { ok: false, reason: `deleted test file(s): ${deleted.sort().join(', ')}` };
+  }
+  const totalBase = Object.values(base).reduce((a, b) => a + b, 0);
+  const totalCurrent = Object.values(current).reduce((a, b) => a + b, 0);
+  if (totalBase > 0 && totalCurrent < totalBase * SHRINK_THRESHOLD) {
+    return { ok: false, reason: `test count shrank from ${totalBase} to ${totalCurrent} (more than 20%)` };
+  }
+  return { ok: true };
+}
+
+/** `process.env` minus every inherited `GIT_*`, with no system/global config. */
+function gitEnv() {
+  /** @type {NodeJS.ProcessEnv} */
+  const env = { GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: os.devNull };
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!key.startsWith('GIT_')) env[key] = value;
+  }
+  return env;
+}
+
+const GIT_TIMEOUT_MS = 30000;
+
+/**
+ * `git ls-tree -r -z --name-only <base>` — NUL-terminated, unquoted paths, the same `-z`
+ * convention `gates/scope.mjs` uses and this file's own `currentTestFiles` already uses for the
+ * CURRENT side. Without `-z`, git C-quotes a path containing non-ASCII bytes, `"`, `\` or control
+ * characters (e.g. `café.test.mjs` → `"caf\303\251.test.mjs"`); a newline-split reader then gets
+ * that quoted literal, whose basename ends in `.mjs"` — `classifyTestFile` no longer recognizes
+ * it as a test file at all, so a deleted quoted-name test file is silently dropped from the base
+ * count instead of tripping the deleted-file check. Not one of `util/git.mjs`'s read-only
+ * builders (its `lsFilesArgv` deliberately refuses any `-`-leading element, so this couldn't be
+ * built through it either way); `base` is guarded the same way those builders guard their own ref
+ * arguments.
+ * @param {string} base @returns {string[]}
+ */
+function lsTreeArgv(base) {
+  if (typeof base !== 'string' || base.length === 0 || base.startsWith('-')) {
+    throw new TypeError(`safe-edit: base must be a non-empty string not starting with "-" (got ${JSON.stringify(base)})`);
+  }
+  return ['git', 'ls-tree', '-r', '-z', '--name-only', base];
+}
+
+/**
+ * @param {string} base @param {string} cwd
+ * @returns {Promise<{file: string, stack: string}[]>} every test file tracked at `base`, with the
+ *   stack its name classified to.
+ */
+async function testFilesAtBase(base, cwd) {
+  const res = await exec(lsTreeArgv(base), { cwd, env: gitEnv(), timeoutMs: GIT_TIMEOUT_MS });
+  if (res.result !== 'ok') {
+    throw new Error(`safe-edit: git ls-tree -r -z --name-only ${base} failed (exit ${res.code}): ${res.stderr}`);
+  }
+  /** @type {{file: string, stack: string}[]} */
+  const testFiles = [];
+  for (const file of splitNul(res.stdout)) {
+    const stack = classifyTestFile(file);
+    if (stack !== null) testFiles.push({ file, stack });
+  }
+  return testFiles;
+}
+
+/**
+ * @param {string} base @param {string} filePath @param {string} stack @param {string} cwd
+ * @returns {Promise<number>} test-declaration count of `filePath` AT `base`.
+ */
+async function countAtBase(base, filePath, stack, cwd) {
+  const res = await exec(showArgv(base, filePath), { cwd, env: gitEnv(), timeoutMs: GIT_TIMEOUT_MS });
+  if (res.result !== 'ok') {
+    throw new Error(`safe-edit: git show ${base}:${filePath} failed (exit ${res.code}): ${res.stderr}`);
+  }
+  return countTestDeclarations(res.stdout, stack);
+}
+
+/**
+ * `git ls-files -z` (tracked, incl. staged) — NUL-terminated so a path with whitespace/quotes is
+ * read exactly, matching `gates/scope.mjs`'s `-z` convention.
+ * @returns {string[]}
+ */
+function lsFilesZArgv() {
+  return ['git', 'ls-files', '-z'];
+}
+
+/** `git ls-files -z --others --exclude-standard` — untracked, not gitignored. @returns {string[]} */
+function lsFilesOthersZArgv() {
+  return ['git', 'ls-files', '-z', '--others', '--exclude-standard'];
+}
+
+/** @param {string} text @returns {string[]} NUL-split entries, empty ones dropped, never trimmed. */
+function splitNul(text) {
+  return text.split('\0').filter((entry) => entry.length > 0);
+}
+
+/**
+ * Every CURRENT test file in the working tree — tracked union untracked-but-not-ignored — each
+ * classified to its stack. This is deliberately NOT limited to base's file list: a test moved
+ * from one file to a NEW one (a coder splitting `a.test.mjs`'s 10 tests into `a.test.mjs` (2) +
+ * `b.test.mjs` (8), still 10 total) must still be counted, or the shrink check would misread a
+ * pure reorganization as a real loss of coverage.
+ * @param {string} cwd
+ * @returns {Promise<{file: string, stack: string}[]>}
+ */
+async function currentTestFiles(cwd) {
+  const [tracked, untracked] = await Promise.all([
+    exec(lsFilesZArgv(), { cwd, env: gitEnv(), timeoutMs: GIT_TIMEOUT_MS }),
+    exec(lsFilesOthersZArgv(), { cwd, env: gitEnv(), timeoutMs: GIT_TIMEOUT_MS }),
+  ]);
+  if (tracked.result !== 'ok') {
+    throw new Error(`safe-edit: git ls-files -z failed (exit ${tracked.code}): ${tracked.stderr}`);
+  }
+  if (untracked.result !== 'ok') {
+    throw new Error(`safe-edit: git ls-files -z --others --exclude-standard failed (exit ${untracked.code}): ${untracked.stderr}`);
+  }
+  const files = new Set([...splitNul(tracked.stdout), ...splitNul(untracked.stdout)]);
+  /** @type {{file: string, stack: string}[]} */
+  const testFiles = [];
+  for (const file of files) {
+    const stack = classifyTestFile(file);
+    if (stack !== null) testFiles.push({ file, stack });
+  }
+  return testFiles;
+}
+
+/**
+ * @param {string} filePath @param {string} stack @param {string} cwd
+ * @returns {Promise<number | null>} test-declaration count of `filePath` on DISK, or `null` when
+ *   it no longer exists there (a race between listing it and reading it — not the normal "was it
+ *   deleted" question, which `safeEdit` answers from the base/current file-name sets themselves).
+ */
+async function countOnDisk(filePath, stack, cwd) {
+  try {
+    const content = await readFile(path.join(cwd, filePath), 'utf8');
+    return countTestDeclarations(content, stack);
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/**
+ * The git-backed orchestration: lists test files tracked at `base`, and SEPARATELY every test file
+ * present in the CURRENT working tree (tracked + untracked, not just base's own file list — see
+ * `currentTestFiles`'s doc), counts each with its own stack's pattern, then applies `safeEdit`.
+ * @param {{cwd: string, base: string}} opts
+ * @returns {Promise<SafeEditResult>}
+ */
+export async function checkSafeEdit({ cwd, base }) {
+  const [baseFiles, currentFiles] = await Promise.all([testFilesAtBase(base, cwd), currentTestFiles(cwd)]);
+
+  /** @type {CountsByFile} */
+  const baseCounts = {};
+  for (const { file, stack } of baseFiles) {
+    baseCounts[file] = await countAtBase(base, file, stack, cwd);
+  }
+
+  /** @type {CountsByFile} */
+  const currentCounts = {};
+  for (const { file, stack } of currentFiles) {
+    const count = await countOnDisk(file, stack, cwd);
+    if (count !== null) currentCounts[file] = count;
+  }
+
+  return safeEdit({ base: baseCounts, current: currentCounts });
+}

package/src/gates/scope.mjs

@@ -0,0 +1,154 @@
+/**
+ * The block gate's file set (plan §4.1, O1) and the shared-tree scope check (§4.7, O2).
+ *
+ * File set = `git diff --name-only -z <base>` (tracked changes) ∪ untracked files from
+ * `git status --porcelain -z --untracked-files=all`. **`-z` is load-bearing, not cosmetic:**
+ * without it, git wraps any path containing whitespace, quotes, control characters or (under the
+ * default `core.quotePath`) non-ASCII bytes in C-style quotes (`"a b.txt"`, `"caf\303\251.md"`),
+ * so a newline-split reader gets the quoted literal instead of the real path and every later
+ * `ownsFile`/`scopeGate` lookup silently fails to match it — a real file becomes a phantom orphan
+ * (or a wrongly-missed out-of-scope file). `-z` disables quoting entirely and NUL-terminates each
+ * entry instead, so paths are read as their exact raw bytes; `splitNul` below never `.trim()`s an
+ * entry, because a real leading/trailing space in a filename is data, not padding.
+ *
+ * The scope MATHS itself (which block owns which file, which files are orphans) already lives in
+ * B8's `state/registry.mjs` — this module only supplies the file set that maths runs on (the
+ * registry's own doc: "the caller supplies the file set … B5 computes it"), and re-exports the
+ * registry functions so a consumer needs one import.
+ *
+ * Every `git` call here strips inherited `GIT_*` env vars (a hook can export `GIT_DIR`/
+ * `GIT_WORK_TREE`, silently redirecting the read to an unrelated repo) and disables system/global
+ * git config, the same guard every other git-calling module in this package uses. `base` is
+ * rejected outright when it starts with `-` (`assertRefNoLeadingDash`) — the SAME argv-injection
+ * guard `util/git.mjs`'s builders apply to their own ref arguments (`--output=/some/path` would
+ * otherwise be read by git as an OPTION, not a revision) — reimplemented locally here because the
+ * `-z` forms below are not among `util/git.mjs`'s existing read-only builders.
+ */
+
+import os from 'node:os';
+import { exec } from '../util/exec.mjs';
+import { diffNoIndexArgv } from '../util/git.mjs';
+
+export { computeScopes, ownsFile, scopeGate } from '../state/registry.mjs';
+
+/** `process.env` minus every inherited `GIT_*`, with no system/global config. */
+function gitEnv() {
+  /** @type {NodeJS.ProcessEnv} */
+  const env = { GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: os.devNull };
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!key.startsWith('GIT_')) env[key] = value;
+  }
+  return env;
+}
+
+const GIT_TIMEOUT_MS = 30000;
+
+/**
+ * Reject a git ref argument that starts with `-` before it ever reaches argv — the same guard
+ * `util/git.mjs`'s `assertNoLeadingDash` applies, reimplemented here because the `-z` builders
+ * below are local (not one of `util/git.mjs`'s existing read-only builders).
+ * @param {unknown} value @param {string} name @returns {string}
+ * @throws {TypeError}
+ */
+function assertRefNoLeadingDash(value, name) {
+  if (typeof value !== 'string' || value.length === 0 || value.startsWith('-')) {
+    throw new TypeError(`${name} must be a non-empty string not starting with "-" (got ${JSON.stringify(value)}) — option injection`);
+  }
+  return value;
+}
+
+/**
+ * `git diff --name-only -z <base>` — NUL-terminated, unquoted paths (see the module doc).
+ * @param {string} base @returns {string[]}
+ */
+function diffNameOnlyZArgv(base) {
+  return ['git', 'diff', '--name-only', '-z', assertRefNoLeadingDash(base, 'base')];
+}
+
+/** `git status --porcelain -z --untracked-files=all` — NUL-terminated, unquoted entries. */
+function statusZArgv() {
+  return ['git', 'status', '--porcelain', '-z', '--untracked-files=all'];
+}
+
+/**
+ * Split a NUL-terminated `-z` git output into its entries, dropping the trailing empty entry the
+ * final terminator produces. Never trims — a real leading/trailing space in a path is data.
+ * @param {string} text @returns {string[]}
+ */
+function splitNul(text) {
+  return text.split('\0').filter((entry) => entry.length > 0);
+}
+
+/**
+ * @typedef {object} FileSet
+ * @property {string[]} tracked - changed tracked files (`git diff --name-only -z <base>`).
+ * @property {string[]} untracked - untracked files (`git status -z`, `??` entries).
+ * @property {string[]} all - the sorted, de-duplicated union — the file set of §4.1.
+ */
+
+/**
+ * @param {string} base @param {string} cwd
+ * @returns {Promise<string[]>}
+ * @throws {TypeError} when `base` starts with `-` (argv-injection guard) or isn't a non-empty string.
+ */
+export async function trackedChangedFiles(base, cwd) {
+  const res = await exec(diffNameOnlyZArgv(base), { cwd, env: gitEnv(), timeoutMs: GIT_TIMEOUT_MS });
+  if (res.result !== 'ok') {
+    throw new Error(`trackedChangedFiles: git diff --name-only -z ${base} failed (exit ${res.code}): ${res.stderr}`);
+  }
+  return splitNul(res.stdout);
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<string[]>} untracked paths only (git status `??` entries, exact bytes) —
+ *   renames, modifications and deletions of tracked files are NOT included; those come from
+ *   `trackedChangedFiles`.
+ */
+export async function untrackedFiles(cwd) {
+  const res = await exec(statusZArgv(), { cwd, env: gitEnv(), timeoutMs: GIT_TIMEOUT_MS });
+  if (res.result !== 'ok') {
+    throw new Error(`untrackedFiles: git status failed (exit ${res.code}): ${res.stderr}`);
+  }
+  // A rename/copy entry's `-z` record is TWO NUL-terminated fields (new path, then the ORIGINAL
+  // path with no status prefix at all) — splitNul yields that orig-path as its own bare entry,
+  // which the `?? ` prefix filter below naturally excludes since it never starts with `?? `.
+  return splitNul(res.stdout)
+    .filter((entry) => entry.startsWith('?? '))
+    .map((entry) => entry.slice(3));
+}
+
+/**
+ * The complete, UNFILTERED file set of §4.1: tracked changes since `base` union untracked files.
+ * A caller that needs it filtered to one block's `owned_files` does so with `ownsFile` (re-exported
+ * above) — the scope check specifically needs the unfiltered set (§4.1: "unfiltered for the scope
+ * check").
+ * @param {{cwd: string, base: string}} opts
+ * @returns {Promise<FileSet>}
+ */
+export async function computeFileSet({ cwd, base }) {
+  const [tracked, untracked] = await Promise.all([trackedChangedFiles(base, cwd), untrackedFiles(cwd)]);
+  return { tracked, untracked, all: [...new Set([...tracked, ...untracked])].sort() };
+}
+
+/**
+ * `git diff --no-index /dev/null <path>` for one NEW/untracked file, plus its `+` line count.
+ * The header (`--- a/…`, `+++ b/<path>`) is skipped by POSITION — everything up to and including
+ * the first `@@ …@@` hunk marker — not by matching a `+++` PREFIX: a real content line that itself
+ * starts with `++` (`++i;`, a markdown/diff fixture) renders as `+++i;` in the diff body and would
+ * otherwise be misread as a second header line and dropped, undercounting. Exit code 1
+ * (differences found) is the expected, non-error outcome.
+ * @param {string} cwd @param {string} relPath
+ * @returns {Promise<{diff: string, plusCount: number}>}
+ */
+export async function diffNoIndexWithCount(cwd, relPath) {
+  const res = await exec(diffNoIndexArgv(relPath), { cwd, env: gitEnv(), okExitCodes: [0, 1], timeoutMs: GIT_TIMEOUT_MS });
+  if (res.result !== 'ok') {
+    throw new Error(`diffNoIndexWithCount: git diff --no-index failed for ${relPath} (exit ${res.code}): ${res.stderr}`);
+  }
+  const lines = res.stdout.split('\n');
+  const hunkStart = lines.findIndex((line) => line.startsWith('@@'));
+  const body = hunkStart < 0 ? [] : lines.slice(hunkStart + 1);
+  const plusCount = body.filter((line) => line.startsWith('+')).length;
+  return { diff: res.stdout, plusCount };
+}

package/src/gates/secret-scan.mjs

@@ -0,0 +1,79 @@
+/**
+ * Secret scanning gate (plan §8, `gates.extra.secret_scan`). Reuses B1's shape-based token
+ * detector (`config/secret-patterns.mjs`) rather than duplicating a pattern list — this module's
+ * only job is turning "these files' text" into "hits", with the one FAKE-marker allowance the
+ * package's own test fixtures rely on (coder rule: every fake key in this repo's tests contains
+ * `FAKE`/`fake`, e.g. `sk-ant-FAKE0123456789`).
+ *
+ * Hits never carry the token text itself — only `{path, line}` — so a caller can log or print a
+ * scan result without ever risking a real secret reaching output (plan §8.2).
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { secretTokensIn } from '../config/secret-patterns.mjs';
+
+/** A token containing this (case-insensitive) is a fixture/test key, never a real one. */
+const FAKE_MARKER = /fake/i;
+
+/**
+ * @typedef {object} SecretHit
+ * @property {string} path
+ * @property {number} line - 1-based.
+ * @property {number} count - secret-shaped tokens found on that line (fake-marked ones excluded).
+ */
+
+/**
+ * @param {string} text
+ * @param {string} [filePath] - included on each hit; defaults to `''`.
+ * @returns {SecretHit[]}
+ */
+export function scanText(text, filePath = '') {
+  /** @type {SecretHit[]} */
+  const hits = [];
+  const lines = String(text).split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const tokens = secretTokensIn(lines[i]).filter((token) => !FAKE_MARKER.test(token));
+    if (tokens.length > 0) hits.push({ path: filePath, line: i + 1, count: tokens.length });
+  }
+  return hits;
+}
+
+/**
+ * @param {ReadonlyArray<{path: string, content: string}>} files
+ * @returns {SecretHit[]}
+ */
+export function scanFileContents(files) {
+  if (!Array.isArray(files)) {
+    throw new TypeError('scanFileContents: files must be an array of {path, content}');
+  }
+  return files.flatMap(({ path: filePath, content }) => scanText(content, filePath));
+}
+
+/**
+ * Reads and scans each file under `cwd`. Only a MISSING file (deleted between the scope check and
+ * the scan — `ENOENT`, or a dangling symlink target — `ENOTDIR` on a bogus intermediate segment)
+ * is skipped rather than failing the whole scan, since it genuinely has no content to scan. Any
+ * OTHER read error (`EACCES`, `EISDIR`, `EIO`, …) is a file this scan could NOT actually read —
+ * silently treating that the same as "nothing to see" would report the gate green on a file it
+ * never scanned, so it is re-thrown and turns the gate red via the caller's catch.
+ * @param {string} cwd
+ * @param {ReadonlyArray<string>} relPaths
+ * @returns {Promise<SecretHit[]>}
+ */
+export async function scanFiles(cwd, relPaths) {
+  /** @type {SecretHit[]} */
+  const hits = [];
+  for (const rel of relPaths) {
+    let content;
+    try {
+      content = await readFile(path.join(cwd, rel), 'utf8');
+    } catch (err) {
+      const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+      if (code === 'ENOENT' || code === 'ENOTDIR') continue;
+      throw err;
+    }
+    hits.push(...scanText(content, rel));
+  }
+  return hits;
+}

package/src/gates/transcript-grep.mjs

@@ -0,0 +1,27 @@
+/**
+ * The block gate's transcript grep (plan §8.6/C4, row 9 of §4.6: "no `rule_break` row —
+ * including the transcript grep"). The actual scanner (`scanTranscript`) already lives in B0's
+ * `util/forbidden.mjs` (extended by B8 in Wave 1 with the signer-protection ★ entries) — this
+ * module is the gate-facing wrapper: it decides pass/fail and shapes a `rule_break`-ready reason,
+ * it does not re-implement the scan.
+ */
+
+import { FORBIDDEN, mergeForbidden, scanTranscript } from '../util/forbidden.mjs';
+
+/**
+ * @typedef {{id: string, line: number}} TranscriptHit
+ * @typedef {{ok: boolean, hits: TranscriptHit[]}} TranscriptCheck
+ */
+
+/**
+ * @param {string} text - captured coder output (subprocess stdout, Solo `search_output`, a
+ *   harness log).
+ * @param {{extraTokens?: string[]}} [opts] - `extraTokens` merges in `production.markers`/
+ *   `production.names` (B1 config), the same way `mergeForbidden` does everywhere else.
+ * @returns {TranscriptCheck}
+ */
+export function checkTranscript(text, opts = {}) {
+  const list = opts.extraTokens && opts.extraTokens.length > 0 ? mergeForbidden(opts.extraTokens) : FORBIDDEN;
+  const hits = scanTranscript(text, list);
+  return { ok: hits.length === 0, hits };
+}

package/src/install/agent-env.mjs

@@ -0,0 +1,76 @@
+/**
+ * Agent-environment detection and the single-JSON-line output convention (Laravel installer
+ * pattern, research/installer-patterns.md; coder-rules.md: "Agent detection env vars ...
+ * CLAUDECODE/CLAUDE_CODE, CURSOR_AGENT, AI_AGENT — when set, output exactly one JSON line").
+ *
+ * This module owns the MECHANISM only: detecting the env vars, and writing exactly one JSON line
+ * to a stream. It does not build the `init` wizard's own payload shape (`{ok, wrote, harnesses,
+ * doctor, log, log_tail}`, plan §2) — that composition belongs to `init`, a later block (B13).
+ * Any verb can call {@link maybeEmitAgentJson} with whatever plain-JSON-serializable payload it
+ * has, and the "exactly one line" guarantee holds regardless of the payload's shape.
+ */
+
+/**
+ * Env var names checked, in this fixed order — first one present (as an own, non-empty string
+ * property) wins and is reported as `source`. Order does not change the detection RESULT (any
+ * one being present is enough), only which name is reported when more than one is set.
+ */
+export const AGENT_ENV_VARS = Object.freeze(['CLAUDECODE', 'CLAUDE_CODE', 'CURSOR_AGENT', 'AI_AGENT']);
+
+/**
+ * @typedef {object} AgentDetection
+ * @property {boolean} isAgent
+ * @property {string|null} source - the env var name that triggered detection, or `null`.
+ */
+
+/**
+ * @param {NodeJS.ProcessEnv} [env] - defaults to `process.env`.
+ * @returns {AgentDetection}
+ */
+export function detectAgentEnv(env = process.env) {
+  for (const name of AGENT_ENV_VARS) {
+    if (Object.hasOwn(env, name) && typeof env[name] === 'string' && env[name].length > 0) {
+      return { isAgent: true, source: name };
+    }
+  }
+  return { isAgent: false, source: null };
+}
+
+/**
+ * Serializes `payload` as ONE line of compact JSON (no pretty-printing — a pretty-printed object
+ * spans multiple lines, which breaks "exactly one JSON line on stdout" for any caller parsing
+ * line-by-line) and writes it in a SINGLE `stream.write()` call, so nothing else can interleave a
+ * partial write between two calls.
+ * @param {unknown} payload - must be JSON-serializable; `undefined` is refused (it would silently
+ *   produce no output at all, which is not "one JSON line").
+ * @param {object} [opts]
+ * @param {{write: (s: string) => unknown}} [opts.stdout] - defaults to `process.stdout`.
+ * @returns {void}
+ */
+export function writeAgentJson(payload, opts = {}) {
+  const stdout = opts.stdout ?? process.stdout;
+  const serialized = JSON.stringify(payload);
+  if (typeof serialized !== 'string') {
+    throw new TypeError('writeAgentJson: payload must be JSON-serializable (JSON.stringify returned undefined)');
+  }
+  stdout.write(`${serialized}\n`);
+}
+
+/**
+ * Writes `payload` as one JSON line IF the environment looks like an agent harness, otherwise
+ * writes nothing at all. Returns whether it wrote, so a caller (e.g. `init`) can skip its normal
+ * interactive/human-readable output in the same branch.
+ * @param {unknown} payload
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {{write: (s: string) => unknown}} [opts.stdout]
+ * @returns {boolean}
+ */
+export function maybeEmitAgentJson(payload, opts = {}) {
+  const { isAgent } = detectAgentEnv(opts.env ?? process.env);
+  if (!isAgent) {
+    return false;
+  }
+  writeAgentJson(payload, opts);
+  return true;
+}