@codedology/code-forge 0.7.7 → 0.8.0

package/src/context/pack.mjs

@@ -0,0 +1,319 @@
+/**
+ * The coder context pack (block B63a; issue #13 item 5, issue #10 item 2).
+ *
+ * The top-level `context` key of `.code-forge.yml` names what every coder task should carry:
+ *
+ *   context:
+ *     rules: [CLAUDE.md, docs/conventions.md]   repository-relative files, in order
+ *     lessons: docs/lessons.md                  one repository-relative file
+ *     commands: {build: [...], test: [...], lint: [...], format: [...]}   argv arrays, each optional
+ *     max_lines: 300                            the pack's line cap (integer >= 20)
+ *     require_coder_tests: false                B63b: close needs the coder's `TESTS … exit=0` line
+ *
+ * `assemblePack` turns it into ONE pack for a block, in this order: the header (run, block, level,
+ * owned files, test files when the block has them, worktree path and branch when it has one), the
+ * commands (never run; each argv shown POSIX shell-quoted, so a pasted line expands nothing), each
+ * rules file, then the lessons file — every file section headed by its source path (an empty
+ * file: the heading alone). Over `max_lines` the lessons are cut first, then the
+ * rules from the last file backwards, each cut section ending in `[cut: N lines dropped]`; the
+ * header and the commands are never cut.
+ *
+ * `reviewDigest` is the ONE builder of the review packets' rules digest (`## project rules`, ≤ 60
+ * lines, `packet.mjs`): the rules files' text, then a `### lessons` subheading and the lessons.
+ * With no `context` key it is '' — the packet is then byte-identical to before (`(none)`). A file
+ * it cannot read throws: the worker answers that ticket `review.unavailable`, `context-unreadable`.
+ *
+ * Files are always read from the MAIN tree's root (`repoRoot`), never from a block worktree a coder
+ * can write to. A path that is absolute, has a `..` segment, or leads out of the repository through
+ * a symlink (a broken one too: its target is checked) is refused, and so is a missing file
+ * (`ContextError`). A control character (a newline included) in a command token, a rules or
+ * lessons path, or a header value (owned or test file, worktree path or branch) is refused, so
+ * nothing can forge a line of the pack. Command lines go through `redact`, as the rules and
+ * lessons do. The `context` key is not
+ * authority: it is not fixed for the run, and `run reload` takes a change to it — except B63b's
+ * `context.require_coder_tests`, which tightens `block close`: it is read from the run-start
+ * snapshot only (`requireCoderTests`, `src/state/config-snapshot.mjs`) and `run reload` refuses a
+ * change to it. It plays no part in the pack.
+ */
+
+import { lstatSync, readFileSync, readlinkSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { estimateTokens } from '../review/packet.mjs';
+import { splitLines } from '../review/context.mjs';
+import { redact } from '../util/redact.mjs';
+
+/** The pack's line cap when `context.max_lines` is not set. */
+export const DEFAULT_MAX_LINES = 300;
+
+/** The smallest `context.max_lines` accepted. */
+export const MIN_MAX_LINES = 20;
+
+/** The `context.commands` keys, in the order the pack lists them. */
+export const COMMAND_KEYS = Object.freeze(['build', 'test', 'lint', 'format']);
+
+/** The subheading the lessons get in the review digest. */
+export const DIGEST_LESSONS_HEADING = '### lessons';
+
+/**
+ * A refusal with a stable `code`. Thrown here: `bad-context` (a bad `context` value),
+ * `control-character` (in a path or a header value), `outside`, `missing` (ENOENT), `unreadable`
+ * (any other lstat or read error, with its code), `not-file`. Thrown by `src/cli/context.mjs`:
+ * `no-block`, `bad-config`, `no-context`, `no-run-root`, `write-failed`.
+ */
+export class ContextError extends Error {
+  /** @param {string} code @param {string} message */
+  constructor(code, message) {
+    super(message);
+    this.name = 'ContextError';
+    this.code = code;
+  }
+}
+
+/** C0 and C1 control characters and DEL: a newline among them. */
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+
+/** @param {unknown} v @returns {v is Record<string, unknown>} */
+const isMapping = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * @typedef {object} ContextSettings
+ * @property {string[]} rules
+ * @property {string | null} lessons
+ * @property {Record<string, string[]>} commands - only the keys that are set.
+ * @property {number} maxLines
+ */
+
+/**
+ * The `context` key of a config, checked; null when the key is absent.
+ * @param {Record<string, any> | null | undefined} cfg
+ * @returns {ContextSettings | null}
+ * @throws {ContextError} `bad-context`, naming the key.
+ */
+export function contextSettings(cfg) {
+  const raw = cfg?.context;
+  if (raw === undefined || raw === null) return null;
+  if (!isMapping(raw)) throw new ContextError('bad-context', 'context must be a mapping');
+  const rules = raw.rules ?? [];
+  if (!Array.isArray(rules) || !rules.every((r) => typeof r === 'string' && r.length > 0)) throw new ContextError('bad-context', 'context.rules must be a list of file paths');
+  // `CLAUDE.md` and `./CLAUDE.md` are the same file
+  if (new Set(rules.map((r) => path.posix.normalize(r))).size !== rules.length) throw new ContextError('bad-context', 'context.rules names a file twice');
+  const lessons = raw.lessons ?? null;
+  if (lessons !== null && (typeof lessons !== 'string' || lessons.length === 0)) throw new ContextError('bad-context', 'context.lessons must be one file path');
+  const commandsRaw = raw.commands ?? {};
+  if (!isMapping(commandsRaw)) throw new ContextError('bad-context', 'context.commands must be a mapping');
+  /** @type {Record<string, string[]>} */
+  const commands = {};
+  for (const key of Object.keys(commandsRaw)) {
+    if (!COMMAND_KEYS.includes(key)) throw new ContextError('bad-context', `context.commands.${key} is not one of ${COMMAND_KEYS.join(', ')}`);
+  }
+  for (const key of COMMAND_KEYS) {
+    const argv = commandsRaw[key];
+    if (argv === undefined || argv === null) continue;
+    if (!Array.isArray(argv) || argv.length === 0 || !argv.every((a) => typeof a === 'string' && a.length > 0)) throw new ContextError('bad-context', `context.commands.${key} must be an argv list of non-empty strings`);
+    if (argv.some((a) => CONTROL.test(a))) throw new ContextError('bad-context', `context.commands.${key} contains a control character`);
+    commands[key] = [...argv];
+  }
+  // B63b: authority, read by `block close` from the run-start snapshot only; checked here so a
+  // pack is never built from a config that carries a malformed value
+  const requireTests = raw.require_coder_tests ?? false;
+  if (typeof requireTests !== 'boolean') throw new ContextError('bad-context', 'context.require_coder_tests must be true or false');
+  const maxLines = raw.max_lines ?? DEFAULT_MAX_LINES;
+  if (!Number.isInteger(maxLines) || /** @type {number} */ (maxLines) < MIN_MAX_LINES) throw new ContextError('bad-context', `context.max_lines must be an integer >= ${MIN_MAX_LINES}`);
+  return { rules: [...rules], lessons: /** @type {string | null} */ (lessons), commands, maxLines: /** @type {number} */ (maxLines) };
+}
+
+/** How many symlinks one path may pass through before it counts as a loop (as the kernel's ELOOP). */
+const MAX_LINK_HOPS = 40;
+
+/**
+ * `abs` with every symlink on it resolved, as far as its components exist — a symlink whose target
+ * is missing (a broken link) is still followed through its `readlink` text, so where it POINTS is
+ * what is checked. A component that does not exist ends the walk (the rest is joined as given); a
+ * link loop ends it at the link.
+ * @param {string} abs - absolute, without `..` segments. @returns {string}
+ */
+function walkLinks(abs) {
+  const parts = abs.split(path.sep).filter(Boolean);
+  let cur = path.parse(abs).root;
+  let hops = 0;
+  while (parts.length > 0) {
+    const next = path.join(cur, /** @type {string} */ (parts.shift()));
+    let st;
+    try {
+      st = lstatSync(next);
+    } catch {
+      return path.join(next, ...parts);
+    }
+    if (!st.isSymbolicLink()) {
+      cur = next;
+      continue;
+    }
+    hops += 1;
+    if (hops > MAX_LINK_HOPS) return path.join(next, ...parts);
+    // `cur` holds no symlink, so resolving the target's `..` against it is exact
+    const target = path.resolve(cur, readlinkSync(next));
+    parts.unshift(...target.split(path.sep).filter(Boolean));
+    cur = path.parse(target).root;
+  }
+  return cur;
+}
+
+/** @param {string} root @param {string} p @returns {boolean} `p` is `root` or under it. */
+const inside = (root, p) => {
+  const rel = path.relative(root, p);
+  // only a real `..` segment leaves the root: a file named `..notes.md` is inside
+  return !(rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel));
+};
+
+/**
+ * The real path of the context file `rel` (named by `key`) under `repoRoot`.
+ * @param {string} repoRoot - the main tree's root. @param {string} rel @param {string} key
+ * @returns {string}
+ * @throws {ContextError} `control-character`, `outside`, `missing`, `unreadable`, `not-file`
+ */
+export function resolveContextFile(repoRoot, rel, key) {
+  const shown = JSON.stringify(rel);
+  if (CONTROL.test(rel)) throw new ContextError('control-character', `${key}: ${shown} contains a control character`);
+  if (path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) {
+    throw new ContextError('outside', `${key}: ${shown} is outside the repository (give a path relative to the repository root)`);
+  }
+  const root = realpathSync(repoRoot);
+  // every symlink on the way is followed — a broken one too, by its target — and the end checked
+  const real = walkLinks(path.resolve(root, rel));
+  if (!inside(root, real)) throw new ContextError('outside', `${key}: ${shown} leads outside the repository`);
+  let st;
+  try {
+    st = lstatSync(real);
+  } catch (err) {
+    const code = /** @type {NodeJS.ErrnoException} */ (err).code ?? 'error';
+    if (code === 'ENOENT') throw new ContextError('missing', `${key}: ${shown} does not exist`);
+    throw new ContextError('unreadable', `${key}: ${shown} cannot be read (${code})`);
+  }
+  // still a link here: a loop (or more than MAX_LINK_HOPS links) — nothing to read
+  if (st.isSymbolicLink()) throw new ContextError('missing', `${key}: ${shown} does not exist`);
+  if (!st.isFile()) throw new ContextError('not-file', `${key}: ${shown} is not a file`);
+  return real;
+}
+
+/**
+ * @param {string} repoRoot @param {string} rel @param {string} key
+ * @returns {string[]} the file's lines (redacted, trailing whitespace of the file dropped); none
+ *   for an empty or whitespace-only file.
+ * @throws {ContextError} as {@link resolveContextFile}, or `unreadable` when the read fails.
+ */
+function readLines(repoRoot, rel, key) {
+  const file = resolveContextFile(repoRoot, rel, key);
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch (err) {
+    throw new ContextError('unreadable', `${key}: ${JSON.stringify(rel)} cannot be read (${/** @type {NodeJS.ErrnoException} */ (err).code ?? 'error'})`);
+  }
+  const text = /** @type {string} */ (redact(raw)).trimEnd();
+  return text === '' ? [] : splitLines(text);
+}
+
+/**
+ * Every rules file and the lessons file, read. A missing or outside file is a refusal.
+ * @param {string} repoRoot @param {ContextSettings} settings
+ * @returns {{rules: Array<{path: string, lines: string[]}>, lessons: {path: string, lines: string[]} | null}}
+ * @throws {ContextError}
+ */
+export function readSources(repoRoot, settings) {
+  const rules = settings.rules.map((rel) => ({ path: rel, lines: readLines(repoRoot, rel, 'context.rules') }));
+  const lessons = settings.lessons === null ? null : { path: settings.lessons, lines: readLines(repoRoot, settings.lessons, 'context.lessons') };
+  return { rules, lessons };
+}
+
+/**
+ * The token as a POSIX shell would take it back: bare when it holds only characters no shell
+ * expands, else in single quotes (an embedded `'` as `'\\''`), so a pasted line never expands
+ * `$x`, a backtick, a glob or a brace.
+ * @param {string} token @returns {string}
+ */
+const argvToken = (token) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(token) ? token : `'${token.replaceAll("'", "'\\''")}'`);
+
+/** @param {string[]} argv @returns {string} */
+export const argvText = (argv) => argv.map(argvToken).join(' ');
+
+/**
+ * @typedef {object} PackBlock
+ * @property {string} run
+ * @property {string} block
+ * @property {string | null} [level]
+ * @property {string[]} [owned]
+ * @property {string[] | null} [tests]
+ * @property {{path: string, branch: string} | null} [worktree]
+ */
+
+/**
+ * Build the pack text for a block (pure over what it is given).
+ * @param {{settings: ContextSettings, sources: ReturnType<typeof readSources>, block: PackBlock}} opts
+ * @returns {{text: string, lines: number, cut: number}} `cut`: the lines dropped.
+ * @throws {ContextError} `control-character` when a header value holds one.
+ */
+export function assemblePack({ settings, sources, block }) {
+  /** @type {Array<[string, unknown]>} */
+  const values = [['level', block.level], ...(block.owned ?? []).map((f) => /** @type {[string, unknown]} */ (['owned file', f])), ...(block.tests ?? []).map((f) => /** @type {[string, unknown]} */ (['test file', f]))];
+  if (block.worktree) values.push(['worktree path', block.worktree.path], ['worktree branch', block.worktree.branch]);
+  for (const [label, v] of values) {
+    if (typeof v === 'string' && CONTROL.test(v)) throw new ContextError('control-character', `block ${block.block}: ${label} ${JSON.stringify(v)} contains a control character`);
+  }
+  const header = ['# code-forge context pack', '## block', `run: ${block.run}`, `block: ${block.block}`, `level: ${block.level ?? '(unknown)'}`, 'owned files:'];
+  for (const f of block.owned ?? []) header.push(`- ${f}`);
+  if (Array.isArray(block.tests) && block.tests.length > 0) {
+    header.push('test files:');
+    for (const f of block.tests) header.push(`- ${f}`);
+  }
+  if (block.worktree) header.push(`worktree: ${block.worktree.path}`, `branch: ${block.worktree.branch}`);
+  header.push('## commands (never run by code-forge)');
+  const keys = COMMAND_KEYS.filter((k) => Object.hasOwn(settings.commands, k));
+  if (keys.length === 0) header.push('(none)');
+  // a command line can name a secret (a token in an argv): it is redacted as rules and lessons are
+  for (const k of keys) header.push(`${k}: ${redact(argvText(settings.commands[k]))}`);
+
+  /** @type {Array<{heading: string, body: string[], dropped: number}>} */
+  const sections = sources.rules.map((r) => ({ heading: `## rules: ${r.path}`, body: [...r.lines], dropped: 0 }));
+  if (sources.lessons) sections.push({ heading: `## lessons: ${sources.lessons.path}`, body: [...sources.lessons.lines], dropped: 0 });
+
+  const total = () => header.length + sections.reduce((n, s) => n + 1 + s.body.length + (s.dropped > 0 ? 1 : 0), 0);
+  // cut order: the lessons first, then the rules from the last file backwards
+  for (const s of [...sections].reverse()) {
+    let excess = total() - settings.maxLines;
+    if (excess <= 0) break;
+    // the marker takes one line: a section is only cut when that leaves it shorter
+    if (s.body.length < 2) continue;
+    const drop = Math.min(s.body.length, excess + 1);
+    s.body = s.body.slice(0, s.body.length - drop);
+    s.dropped = drop;
+  }
+  const out = [...header];
+  for (const s of sections) {
+    out.push(s.heading, ...s.body);
+    if (s.dropped > 0) out.push(`[cut: ${s.dropped} lines dropped]`);
+  }
+  return { text: `${out.join('\n')}\n`, lines: out.length, cut: sections.reduce((n, s) => n + s.dropped, 0) };
+}
+
+/**
+ * The review packets' rules digest (`## project rules`), built from the MAIN tree each time a
+ * packet is built: the rules files' lines in order, then `### lessons` and the lessons' lines.
+ * '' when the config has no `context` key (the packet stays as it was), or names no rules and no
+ * lessons. `packet.mjs` keeps the first 60 lines and trims from the end over budget, rules and
+ * lessons together.
+ * @param {{repoRoot: string, cfg: Record<string, any> | null | undefined}} opts
+ * @returns {string}
+ * @throws {ContextError} a bad `context` value, or a rules or lessons file that is missing,
+ *   outside the repository or unreadable — the worker makes that ticket `review.unavailable`
+ *   with `reason: context-unreadable` (no review runs without the rules it was promised).
+ */
+export function reviewDigest({ repoRoot, cfg }) {
+  const settings = contextSettings(cfg);
+  if (settings === null) return '';
+  const out = settings.rules.flatMap((rel) => readLines(repoRoot, rel, 'context.rules'));
+  if (settings.lessons !== null) out.push(DIGEST_LESSONS_HEADING, ...readLines(repoRoot, settings.lessons, 'context.lessons'));
+  return out.join('\n');
+}
+
+/** @param {string} text @returns {number} the pack's estimated tokens (the review packets' bytes / 4). */
+export const packTokens = (text) => estimateTokens(text);

package/src/doctor/local.mjs

@@ -104,7 +104,8 @@ export async function checkCommands(cfg, pathEnv) {
   rows.push(row('solo', 'INFO', 'solo', 'UNVERIFIED (no Solo probe in this version)'));
   const gates = cfg?.gates && typeof cfg.gates === 'object' ? cfg.gates : {};
   let any = false;
-  for (const [name, argv] of Object.entries(gates)) {
+  for (const [name, command] of Object.entries(gates)) {
+    const argv = command && !Array.isArray(command) && typeof command === 'object' ? command.argv : command; // B60: {argv, env}
     if (!Array.isArray(argv) || argv.length === 0) continue;
     any = true;
     const found = await commandOnPath(String(argv[0]), { pathEnv });

package/src/engines/sentinel.mjs

@@ -11,6 +11,16 @@
  * 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.
  *
+ * **TESTS.** B63b: a coder proves a green test run with a line that IS exactly `TESTS <command>
+ * exit=<n>` (matched after trimming; `<command>` non-empty free text, `<n>` a decimal 0–255 with no
+ * leading zeros — a non-numeric, signed or out-of-range value does not count) printed before its
+ * sentinel. On a returned sentinel, `tests: {command, exit}` is the LAST such line in that
+ * sentinel's own segment: after the previous sentinel line of ANY block (COMPLETE or FAILED) and
+ * before this one. A TESTS line before an earlier attempt's sentinel, or before another block's
+ * sentinel in a shared log, never carries over, and one after the sentinel is ignored; with none
+ * the result has no `tests` key at all. Like the sentinel, the pattern is anchored to the whole
+ * trimmed line, so a TESTS line quoted in prose never matches.
+ *
  * **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
@@ -23,17 +33,21 @@
  * 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 */
+/** @typedef {{command: string, exit: number}} TestsLine */
+/** @typedef {({status: "complete", blockId: string} | {status: "failed", blockId: string, reason: string}) & {tests?: TestsLine}} SentinelResult */
 
 const COMPLETE_RE = /^===BLOCK\s+(\S+)\s+COMPLETE===$/;
 const FAILED_RE = /^===BLOCK\s+(\S+)\s+FAILED:\s*(.*?)\s*===$/;
+/** B63b: `TESTS <command> exit=<n>` as a whole trimmed line (no leading zeros); 0–255 is checked after the match. */
+const TESTS_RE = /^TESTS\s+(\S.*?)\s+exit=(0|[1-9]\d{0,2})$/;
 
 /**
  * @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.
+ * @returns {SentinelResult | null} the LAST matching sentinel line, or `null` if none is present;
+ *   with `tests` when a `TESTS` line comes before it in its segment (B63b).
  */
 export function parseSentinel(output, blockId) {
   if (typeof output !== 'string') {
@@ -41,17 +55,24 @@ export function parseSentinel(output, blockId) {
   }
   /** @type {SentinelResult | null} */
   let last = null;
+  /** @type {TestsLine | null} */
+  let tests = 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] };
+    if (complete) {
+      if (!blockId || complete[1] === blockId) last = { status: 'complete', blockId: complete[1], ...(tests ? { tests } : {}) };
+      tests = null; // B63b: any sentinel line, of any block, ends the segment
       continue;
     }
     const failed = FAILED_RE.exec(line);
-    if (failed && (!blockId || failed[1] === blockId)) {
-      last = { status: 'failed', blockId: failed[1], reason: failed[2] };
+    if (failed) {
+      if (!blockId || failed[1] === blockId) last = { status: 'failed', blockId: failed[1], reason: failed[2], ...(tests ? { tests } : {}) };
+      tests = null;
+      continue;
     }
+    const run = TESTS_RE.exec(line);
+    if (run && Number(run[2]) <= 255) tests = { command: run[1], exit: Number(run[2]) };
   }
   return last;
 }

package/src/gates/detect.mjs

@@ -4,7 +4,7 @@
  * 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,
+ * Evidence is checked in the table's own order (PHP/Pest or PHPUnit, 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.
@@ -18,10 +18,15 @@ import path from 'node:path';
  * (`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
+ * B60: a configured gate may be `{argv, env}` — `env` adds variables to the gate's environment
+ * (the values are never printed, `run.mjs`).
+ * @typedef {string[] | {argv: string[], failOnStdout?: true, env?: Record<string, string>}} GateCommand
  * @typedef {GateCommand | null} Gate
  */
-/** @typedef {{stack: string, test: Gate, lint: Gate, types: Gate, format: Gate}} DetectedGates */
+/**
+ * `stack` is one of `php-pest`, `php-phpunit`, `node`, `rust`, `python`, `go` or `unknown`.
+ * @typedef {{stack: string, test: Gate, lint: Gate, types: Gate, format: Gate}} DetectedGates
+ */
 
 /** @param {string} root @param {string} rel @returns {boolean} */
 function has(root, rel) {
@@ -49,15 +54,23 @@ function readText(root, rel) {
   }
 }
 
-// ── PHP / Pest ───────────────────────────────────────────────────────────────
+// ── PHP (Pest, PHPUnit) ─────────────────────────────────────────────────────
 
-/** @param {string} root @returns {DetectedGates | null} */
+/**
+ * `composer.json` plus an installed runner: `vendor/bin/pest` is `php-pest` (checked first, so a
+ * project with both binaries is Pest), else `vendor/bin/phpunit` is `php-phpunit` (B61). A Laravel
+ * app (`artisan` present) runs either through `php artisan test --compact`; without `artisan` the
+ * runner's own binary runs. `types` and `format` do not depend on the runner.
+ * @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'];
+  if (!has(root, 'composer.json')) return null;
+  const runner = has(root, 'vendor/bin/pest') ? 'pest' : has(root, 'vendor/bin/phpunit') ? 'phpunit' : null;
+  if (runner === null) return null;
+  const test = has(root, 'artisan') ? ['php', 'artisan', 'test', '--compact'] : [`vendor/bin/${runner}`];
   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 };
+  return { stack: `php-${runner}`, test, lint: null, types, format };
 }
 
 // ── Node (package.json scripts) ────────────────────────────────────────────

package/src/gates/expand.mjs

@@ -0,0 +1,202 @@
+/**
+ * B60 (issue #13 item 3): run only the block's related tests, and give a gate its own environment.
+ * Pure — no filesystem, no child process. A gate argv item that is EXACTLY {@link TEST_FILES_TOKEN}
+ * (one whole item, never a substring, never a shell string) stands for the block's test files:
+ *
+ *  - the block's `test_files` (`block open --tests`), else its owned entries that are concrete
+ *    files (no glob, no trailing `/`) and look like tests ({@link isTestPath});
+ *  - when the block owns more FILES than `gates.full_suite_threshold_files` (default 10; globs and
+ *    directories count the tracked and new (not ignored) files they cover — the caller counts them, gates/owned-count.mjs),
+ *    or no test file is known (also: a gate run with no block), the item is DROPPED and the gate
+ *    runs the full suite.
+ *
+ * {@link testScope} decides which, once per gate run; {@link expandArgv} applies it to one argv.
+ * A gate without the token is never touched.
+ *
+ * A gate given as `{argv, env}` runs with `env` added to the inherited environment. Gate env is
+ * NOT a secret store: code-forge prints and records only the variable NAMES ({@link envKeys},
+ * {@link printableGates}), never a value. The child's own output is masked only for values of
+ * {@link MASK_MIN_LENGTH} or more characters ({@link maskableEnvValues}) — a short value such as
+ * `CI=1` or `MODE=test` would otherwise mask unrelated text (`npm test`).
+ */
+
+import { isExactEntry } from '../state/registry.mjs';
+import { TEST_FILES_TOKEN } from '../util/gate-token.mjs';
+
+export { TEST_FILES_TOKEN };
+
+/** `gates.full_suite_threshold_files` when the config leaves it out (the schema default). */
+export const DEFAULT_FULL_SUITE_THRESHOLD = 10;
+
+/** The shortest env value masked in a gate's own output. */
+export const MASK_MIN_LENGTH = 8;
+
+/**
+ * The threshold a configured value gives: the value itself when it is an integer >= 0, else the
+ * default.
+ * @param {unknown} value - `gates.full_suite_threshold_files` as the config holds it.
+ * @returns {number}
+ */
+export function thresholdOf(value) {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : DEFAULT_FULL_SUITE_THRESHOLD;
+}
+
+/** Directory names that hold tests. */
+const TEST_DIRS = new Set(['test', 'tests', '__tests__', 'spec']);
+
+/**
+ * The shared test-path predicate: a directory segment named `test`, `tests`, `__tests__` or
+ * `spec`, or a file name ending `.test.<ext>` / `.spec.<ext>` (`a.test.mjs`, `a.spec.ts`),
+ * `Test.php` (`UserTest.php`), `_test.go`, or a Python `test_*.py`.
+ * @param {string} p - a repo-relative POSIX path (an owned entry; a glob is judged by its text).
+ * @returns {boolean}
+ */
+export function isTestPath(p) {
+  if (typeof p !== 'string' || p.length === 0) return false;
+  const segments = p.split('/');
+  const name = segments[segments.length - 1];
+  if (segments.slice(0, -1).some((s) => TEST_DIRS.has(s))) return true;
+  return /\.(test|spec)\.[^/]+$/.test(name) || name.endsWith('Test.php') || name.endsWith('_test.go') || /^test_.*\.py$/.test(name);
+}
+
+/**
+ * An owned entry that names one file: no glob character (`*`, `?`, `{`) and no trailing `/`.
+ * @param {string} p @returns {boolean}
+ */
+const isConcreteFile = (p) => typeof p === 'string' && p.length > 0 && isExactEntry(p) && !p.endsWith('/');
+
+/**
+ * @typedef {{scope: 'related', files: string[]} | {scope: 'full', reason: 'threshold' | 'no_tests'}} TestScope
+ */
+
+/** A gate run with no block: no test file is known. */
+export const NO_BLOCK_SCOPE = Object.freeze(/** @type {TestScope} */ ({ scope: 'full', reason: 'no_tests' }));
+
+/**
+ * Which tests a `{test_files}` gate runs for one block.
+ * @param {{testFiles?: ReadonlyArray<string> | null, owned: ReadonlyArray<string>, ownedFiles?: number, threshold?: number}} opts
+ *   `testFiles` - the block's `test_files` (`block open --tests`), or none; `owned` - its owned
+ *   entries; `ownedFiles` - how many files those entries cover (`ownedFileCount`,
+ *   gates/owned-count.mjs; when not given, one per entry); `threshold` -
+ *   `gates.full_suite_threshold_files`, compared with `ownedFiles`.
+ * @returns {TestScope}
+ */
+export function testScope({ testFiles, owned, ownedFiles = owned.length, threshold = DEFAULT_FULL_SUITE_THRESHOLD }) {
+  if (ownedFiles > threshold) return { scope: 'full', reason: 'threshold' };
+  const files = testFiles && testFiles.length > 0 ? [...testFiles] : owned.filter((p) => isConcreteFile(p) && isTestPath(p));
+  if (files.length === 0) return { scope: 'full', reason: 'no_tests' };
+  return { scope: 'related', files };
+}
+
+/**
+ * The argv of one gate command (an argv array or `{argv, ...}`), or null.
+ * @param {unknown} command @returns {ReadonlyArray<unknown> | null}
+ */
+function argvOf(command) {
+  if (Array.isArray(command)) return command;
+  if (command && typeof command === 'object' && Array.isArray(/** @type {{argv?: unknown}} */ (command).argv)) return /** @type {{argv: unknown[]}} */ (command).argv;
+  return null;
+}
+
+/**
+ * Does any gate in `gates` have an argv item that is exactly {@link TEST_FILES_TOKEN} (a whole
+ * item — the same test {@link expandArgv} applies)? Only then is a block's test scope worked out;
+ * a run of plain gates never reads it.
+ * @param {Record<string, unknown> | null | undefined} gates @returns {boolean}
+ */
+export function hasTestFilesItem(gates) {
+  return Object.values(gates ?? {}).some((command) => argvOf(command)?.includes(TEST_FILES_TOKEN) === true);
+}
+
+/**
+ * One gate argv with every item that is exactly {@link TEST_FILES_TOKEN} replaced by the related
+ * test files, or dropped for a full run. Always a new array; `scoped` is false (and the items
+ * unchanged) when the gate has no such item.
+ * @param {ReadonlyArray<string>} argv @param {TestScope} scope
+ * @returns {{argv: string[], scoped: boolean}}
+ * @throws {TypeError} a test path that starts with `-` (it would be read as an option; `block
+ *   open --tests` refuses one too).
+ */
+export function expandArgv(argv, scope) {
+  if (!argv.includes(TEST_FILES_TOKEN)) return { argv: [...argv], scoped: false };
+  const files = scope.scope === 'related' ? scope.files : [];
+  const dashed = files.find((f) => f.startsWith('-'));
+  if (dashed !== undefined) throw new TypeError(`expandArgv: test path ${JSON.stringify(dashed)} starts with "-"`);
+  return { argv: argv.flatMap((item) => (item === TEST_FILES_TOKEN ? files : [item])), scoped: true };
+}
+
+/**
+ * The fields a scoped gate's result and ledger row carry: `scope`, plus `test_count` when related
+ * or `reason` when full.
+ * @param {TestScope} scope
+ * @returns {{scope: 'related', test_count: number} | {scope: 'full', reason: 'threshold' | 'no_tests'}}
+ */
+export function scopeFields(scope) {
+  return scope.scope === 'related' ? { scope: 'related', test_count: scope.files.length } : { scope: 'full', reason: scope.reason };
+}
+
+/**
+ * A gate command's env as a plain `NAME: value` map, or null when it has none: an argv array, an
+ * object without `env`, or an empty `env: {}` (treated as no env at all).
+ * @param {unknown} command
+ * @returns {Record<string, string> | null}
+ */
+export function envOf(command) {
+  if (!command || typeof command !== 'object' || Array.isArray(command)) return null;
+  const env = /** @type {{env?: unknown}} */ (command).env;
+  if (!env || typeof env !== 'object' || Array.isArray(env) || Object.keys(env).length === 0) return null;
+  return /** @type {Record<string, string>} */ (env);
+}
+
+/**
+ * The sorted variable NAMES of a gate command's env, or null when it has none.
+ * @param {unknown} command @returns {string[] | null}
+ */
+export function envKeys(command) {
+  const env = envOf(command);
+  return env ? Object.keys(env).sort() : null;
+}
+
+/**
+ * Every non-empty string value of every gate's `env`, across every entry of `gates`.
+ * @param {Record<string, unknown> | null | undefined} gates
+ * @returns {string[]}
+ */
+export function envValues(gates) {
+  /** @type {string[]} */
+  const values = [];
+  for (const command of Object.values(gates ?? {})) {
+    for (const value of Object.values(envOf(command) ?? {})) if (typeof value === 'string' && value.length > 0) values.push(value);
+  }
+  return values;
+}
+
+/**
+ * The env values a gate's own output is masked for: those of {@link MASK_MIN_LENGTH} or more
+ * characters. Shorter ones are not masked (they would hide unrelated text).
+ * @param {Record<string, unknown> | null | undefined} gates @returns {string[]}
+ */
+export function maskableEnvValues(gates) {
+  return envValues(gates).filter((value) => value.length >= MASK_MIN_LENGTH);
+}
+
+/**
+ * A copy of `gates` safe to print: each command given with `env` keeps its other fields and shows
+ * `env_keys` (the names) in place of `env`; an empty env is left out. Nothing else changes.
+ * @template {Record<string, any>} T
+ * @param {T} gates @returns {T}
+ */
+export function printableGates(gates) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const [key, command] of Object.entries(gates ?? {})) {
+    if (!command || typeof command !== 'object' || Array.isArray(command) || !Object.hasOwn(command, 'env')) {
+      out[key] = command;
+      continue;
+    }
+    const { env: _env, ...rest } = /** @type {Record<string, unknown>} */ (command);
+    const keys = envKeys(command);
+    out[key] = keys ? { ...rest, env_keys: keys } : rest;
+  }
+  return /** @type {T} */ (out);
+}