yadflow 3.18.1 → 4.0.0-next.1

package/cli/codeowners.mjs

@@ -0,0 +1,397 @@
+// CODEOWNERS as a HINT (E68). Part 3: "CODEOWNERS is a hint, never an authority — in practice these files
+// rot." So nothing here decides anything: it never holds a gate, never counts toward an approval, never
+// requests a reviewer. `yad open-pr` prints what the file on the BASE branch lists for the files a change
+// touches, on its own line, beside (never merged with) the people git history names.
+//
+// THE RULES ARE THE PLATFORMS' OWN, taken from their docs (checked 2026-09-22), never from memory:
+//
+//   GitHub (docs.github.com, "About code owners"):
+//     - the first of `.github/CODEOWNERS`, `CODEOWNERS`, `docs/CODEOWNERS`; a file of 3 MB or more is not loaded;
+//     - gitignore patterns, EXCEPT that `\` escaping, `!` negation and `[ ]` ranges do not work;
+//     - the LAST matching line decides, and a line with no owners leaves the path with none;
+//     - owners are `@user`, `@org/team` or an e-mail address; `#` starts a comment, also after a pattern;
+//     - "If any line … contains invalid syntax, that line will be skipped."
+//   GitLab (docs.gitlab.com, "Code Owners" and "Syntax of CODEOWNERS file"):
+//     - the first of `CODEOWNERS`, `docs/CODEOWNERS`, `.gitlab/CODEOWNERS`;
+//     - a path WITHOUT a leading `/` matches at any depth, even with a `/` inside (`internal/README.md`
+//       matches `/docs/internal/README.md`) — unlike gitignore, which anchors such a path at the root;
+//     - `[Section]`, `^[Optional]`, `[Section][2]`, and default owners after the heading; names are
+//       case-insensitive and duplicates combine (required if any copy is); a heading it cannot parse is
+//       read as an entry; the unnamed section holds everything before the first heading;
+//     - within a section the last matching entry decides; every section answers for itself;
+//     - `!path` excludes within its section, and a later entry cannot include it again;
+//     - owners are `@user`, `@group`, `@group/subgroup`, `@@role` or an e-mail address; a malformed owner
+//       is ignored; "Inline comments are unsupported. Any Code Owners listed in a comment are parsed";
+//     - a space in a path is written `\ `.
+//
+// WHAT IS NOT GUESSED. A pattern that uses a form its platform's docs do not describe (`?` or `**` on
+// GitLab outside `/**/`, any `\` on GitHub, `[`) is not matched, and the line is reported as not read — a
+// wrong match would print the wrong person, which is the whole class of bug E67 paid for eight times.
+// One reading is ours, from both platforms' examples: a pattern whose LAST segment holds no wildcard also
+// covers everything under a directory of that name (`apps/`, `**/logs`, GitLab's `docs`), while one whose
+// last segment has a wildcard matches files only (`docs/*` never reaches `docs/build-app/x.md`).
+//
+// NO E-MAIL ADDRESS IS EVER PRINTED (E67's rule): an address owner is kept as "an e-mail address".
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { gitEnv } from './riskmap-command.mjs';
+
+export const CODEOWNERS_PATHS = {
+  github: ['.github/CODEOWNERS', 'CODEOWNERS', 'docs/CODEOWNERS'],
+  gitlab: ['CODEOWNERS', 'docs/CODEOWNERS', '.gitlab/CODEOWNERS'],
+};
+// GitHub: "CODEOWNERS files must be under 3 MB in size." Read as 3 000 000 bytes: the smaller reading, so
+// a file GitHub may not load is never quietly used here.
+export const GITHUB_MAX_BYTES = 3_000_000;
+
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// One owner word → { kind, text }, or null when it is not an owner on this platform.
+export function ownerOf(word, platform) {
+  // `key` tells two addresses apart for counting; it stays inside this module and is never printed.
+  if (EMAIL.test(word)) return { kind: 'email', text: 'an e-mail address', key: word.toLowerCase() };
+  if (platform === 'gitlab') {
+    if (/^@@[A-Za-z]+$/.test(word)) return { kind: 'role', text: word };
+    if (/^@[^\s@/]+(\/[^\s@/]+)+$/.test(word)) return { kind: 'group', text: word };
+    if (/^@[^\s@/]+$/.test(word)) return { kind: 'name', text: word };
+    return null;
+  }
+  if (/^@[^\s@/]+\/[^\s@/]+$/.test(word)) return { kind: 'team', text: word };
+  if (/^@[^\s@/]+$/.test(word)) return { kind: 'user', text: word };
+  return null;
+}
+
+// Split a GitLab line on spaces and tabs, where `\ ` is a space inside a word. Any other `\` is a form the
+// docs do not describe: { bad } says so.
+function gitlabWords(line) {
+  const words = [];
+  let cur = '';
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === '\\') {
+      if (line[i + 1] === ' ') { cur += ' '; i++; continue; }
+      return { bad: 'a `\\` that is not `\\ ` (GitLab\'s docs describe only an escaped space)' };
+    }
+    if (ch === ' ' || ch === '\t') { if (cur) words.push(cur); cur = ''; continue; }
+    cur += ch;
+  }
+  if (cur) words.push(cur);
+  return { words };
+}
+
+// A word from the file, quoted for a `not read` reason — unless it holds an `@` after its first character:
+// a pattern can be a mistyped address (`alice@corp.com docs/`), and no address is ever printed.
+const quoted = (w) => (w.indexOf('@', 1) >= 0 ? 'an address-like word' : `\`${w}\``);
+
+const escRe = (s) => s.replace(/[.+^${}()|[\]\\*?]/g, '\\$&');
+
+// A pattern → { re, dirs } or { bad: why }. `re` is tested against a file path and, when `dirs`, against
+// each directory above it (see WHAT IS NOT GUESSED).
+export function patternOf(raw, platform) {
+  if (raw.includes('[')) return { bad: `${quoted(raw)} uses \`[\`, which ${platform === 'gitlab' ? 'GitLab\'s docs do not describe' : 'GitHub does not support'}` };
+  if (platform !== 'gitlab' && raw.includes('\\')) return { bad: `${quoted(raw)} uses \`\\\`, which GitHub does not support in CODEOWNERS` };
+  if (platform === 'gitlab' && raw.includes('?')) return { bad: `${quoted(raw)} uses \`?\`, which GitLab's docs do not describe` };
+  let p = raw;
+  const dirOnly = p.endsWith('/');
+  if (dirOnly) p = p.replace(/\/+$/, '');
+  const rooted = p.startsWith('/');
+  if (rooted) p = p.replace(/^\/+/, '');
+  if (!p) return { re: /^/, dirs: true, all: true };
+  const segs = p.split('/');
+  // GitHub follows gitignore: a `/` at the start or in the middle anchors the pattern at the root.
+  // GitLab anchors only on a leading `/`.
+  const anchored = rooted || (platform !== 'gitlab' && segs.length > 1);
+  let body = '';
+  for (let i = 0; i < segs.length; i++) {
+    const seg = segs[i];
+    const last = i === segs.length - 1;
+    if (seg === '**') {
+      if (!last) { body += '(?:.*/)?'; continue; }
+      if (platform === 'gitlab') return { bad: `${quoted(raw)} ends in \`/**\`, which GitLab's docs do not describe (they say to end a directory with \`/\`)` };
+      if (i === 0) { body += '.*'; continue; }
+      body = body.replace(/\/$/, '') + '/.+';
+      continue;
+    }
+    if (seg.includes('**') && platform === 'gitlab') return { bad: `${quoted(raw)} uses \`**\` inside a name, which GitLab's docs do not describe` };
+    body += seg.split('').map((ch) => (ch === '*' ? '[^/]*' : ch === '?' ? '[^/]' : escRe(ch))).join('').replace(/(\[\^\/\]\*)+/g, '[^/]*');
+    if (!last) body += '/';
+  }
+  const lastSeg = segs[segs.length - 1];
+  // `s`: a folder name can hold a line break (git lists it), and `.` must cross it like any character.
+  return { re: new RegExp(`^${anchored ? '' : '(?:.*/)?'}${body}$`, 's'), dirs: dirOnly || !/[*?]/.test(lastSeg), fileToo: !dirOnly };
+}
+
+export function matches(pat, file) {
+  if (pat.all) return true;
+  if (pat.fileToo && pat.re.test(file)) return true;
+  if (!pat.dirs) return false;
+  const segs = file.split('/');
+  for (let i = 1; i < segs.length; i++) if (pat.re.test(segs.slice(0, i).join('/'))) return true;
+  return false;
+}
+
+// The file's text → { rules, skipped }. A rule is { line, section, negate, pattern, pat, owners }; `pattern`
+// is the path as written (without a GitLab `!`), `section` the lower-cased name ('' for the unnamed one)
+// and `optional` a per-section fact kept in `sections`. `skipped` is every line this reader did not use,
+// with why — printed, never dropped quietly.
+export function parseCodeowners(text, platform) {
+  const rules = [];
+  const skipped = [];
+  const sections = new Map([['', { optional: false }]]);
+  let section = '';
+  let defaults = [];
+  const lines = String(text).replace(/^\uFEFF/, '').split('\n');
+  lines.forEach((rawLine, i) => {
+    const line = rawLine.replace(/\r$/, '');
+    const n = i + 1;
+    if (!line.trim() || /^[ \t]*#/.test(line)) return;
+    if (platform === 'gitlab') {
+      const h = line.match(/^(\^)?\[([^\]]+)\](?:\[(\d+)\])?(?:[ \t]+(.*))?$/);
+      if (h && h[2].trim()) {
+        section = h[2].trim().toLowerCase();
+        const prev = sections.get(section);
+        // "If a section is duplicated … and one of them is marked as optional and the other isn't, the
+        // section is required."
+        sections.set(section, { optional: prev ? prev.optional && !!h[1] : !!h[1] });
+        const w = gitlabWords(h[4] || '');
+        // Default owners this reader cannot split are reported, never read as "no defaults".
+        if (w.bad) skipped.push({ line: n, why: w.bad });
+        defaults = (w.words || []).map((x) => ownerOf(x, platform)).filter(Boolean);
+        return;
+      }
+      const w = gitlabWords(line.replace(/^[ \t]+/, ''));
+      if (w.bad) { skipped.push({ line: n, why: w.bad }); return; }
+      let [pattern, ...rest] = w.words;
+      const negate = pattern.startsWith('!');
+      if (negate) pattern = pattern.slice(1);
+      const pat = patternOf(pattern, platform);
+      if (pat.bad) { skipped.push({ line: n, why: pat.bad }); return; }
+      // GitLab ignores a malformed owner and keeps the rest. The section's defaults apply only to an entry
+      // that WRITES no owner at all: one whose words are all unreadable (`docs/ bob`, `docs/ # note`) has
+      // no owner, never the defaults — printing a default owner there would name the wrong person. It is
+      // also reported, so the answer is hedged.
+      const own = rest.map((x) => ownerOf(x, platform)).filter(Boolean);
+      // An exclusion takes no owners, so words after it are nothing to report.
+      if (!negate && rest.length && !own.length) {
+        skipped.push({ line: n, why: `${quoted(pattern)} is read as having no owner: none of its owner words is one this reader can read${defaults.length ? ', and the section\'s default owners do not apply to it' : ''}` });
+      }
+      rules.push({ line: n, section, negate, pattern, pat, owners: rest.length ? own : defaults });
+      return;
+    }
+    const words = line.trim().split(/[ \t]+/);
+    const cut = words.findIndex((x, j) => j > 0 && x.startsWith('#'));
+    const [pattern, ...rest] = cut < 0 ? words : words.slice(0, cut);
+    if (pattern.startsWith('!')) { skipped.push({ line: n, why: `${quoted(pattern)} is a \`!\` pattern, which GitHub does not support` }); return; }
+    const pat = patternOf(pattern, platform);
+    if (pat.bad) { skipped.push({ line: n, why: pat.bad }); return; }
+    const owners = rest.map((x) => ownerOf(x, platform));
+    const badAt = owners.indexOf(null);
+    if (badAt >= 0) {
+      // A word with an `@` anywhere after its first character may be a mistyped address (`bob@corp`,
+      // `@alice@corp.com`), so it is never printed as written (`quoted`).
+      skipped.push({ line: n, why: `${quoted(rest[badAt])} is not an owner (@user, @org/team or an e-mail address)` });
+      return;
+    }
+    rules.push({ line: n, section: '', negate: false, pattern, pat, owners });
+  });
+  return { rules, skipped, sections };
+}
+
+// The owners of the files a change touches. Per file: GitHub takes the last matching line; GitLab takes,
+// in every section, the last matching entry unless an exclusion in that section matches. Returns
+// { owners: [{ kind, text, files, optional }], matched, unmatched } — `files` is how many touched files
+// list that owner, `optional` true when every such listing is in a GitLab `^[optional]` section, and
+// `unmatched` how many touched files no line gives an owner.
+export function ownersFor(parsed, files) {
+  const by = new Map();
+  let matched = 0;
+  for (const f of files) {
+    const got = [];
+    for (const [name, meta] of parsed.sections) {
+      const inSec = parsed.rules.filter((r) => r.section === name);
+      if (inSec.some((r) => r.negate && matches(r.pat, f))) continue;
+      let last = null;
+      for (const r of inSec) if (!r.negate && matches(r.pat, f)) last = r;
+      if (last) for (const o of last.owners) got.push({ ...o, optional: meta.optional });
+    }
+    if (got.length) matched++;
+    const seen = new Set();
+    for (const o of got) {
+      const k = `${o.kind}\0${o.key || o.text}`;
+      const row = by.get(k) || { kind: o.kind, text: o.text, files: 0, optional: true };
+      if (!seen.has(k)) row.files++;
+      seen.add(k);
+      row.optional = row.optional && o.optional;
+      by.set(k, row);
+    }
+  }
+  // Every e-mail address prints the same words, so they are one row.
+  const rows = [...by.values()];
+  const mails = rows.filter((o) => o.kind === 'email');
+  const out = rows.filter((o) => o.kind !== 'email');
+  if (mails.length) out.push({ kind: 'email', text: mails.length > 1 ? `${mails.length} e-mail addresses` : 'an e-mail address', files: Math.max(...mails.map((m) => m.files)), optional: mails.every((m) => m.optional) });
+  return { owners: out.sort((a, b) => b.files - a.files), matched, unmatched: files.length - matched };
+}
+
+// The CODEOWNERS file on `baseRef` — the base, like the risk map, so a change cannot rewrite the hint it
+// is shown. { path, text } for the first location the platform reads, { none } when there is none, or
+// { unknown: why } — git failing is never "none". Only a regular file is read (a symlink's `git show` is
+// its target's name).
+export function baseCodeowners(repoRoot, baseRef, platform) {
+  // gitEnv: a pathspec variable in the caller's environment makes `ls-tree -- <path>` fail outright.
+  const git = (args) => spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8', maxBuffer: 1 << 30, env: gitEnv() });
+  const paths = CODEOWNERS_PATHS[platform];
+  if (!paths) return { unknown: `no CODEOWNERS locations are known for platform '${platform}'` };
+  for (const p of paths) {
+    const ls = git(['ls-tree', '--full-tree', baseRef, '--', p]);
+    if (ls.status !== 0) return { unknown: `git could not read '${baseRef}'` };
+    if (!ls.stdout) continue;
+    if (!/^100(644|755) blob /.test(ls.stdout)) return { unknown: `${p} on ${baseRef} is not a regular file` };
+    const show = spawnSync('git', ['show', `${baseRef}:${p}`], { cwd: repoRoot, maxBuffer: 1 << 30 });
+    if (show.status !== 0) return { unknown: `git could not read ${p} on ${baseRef}` };
+    if (platform === 'github' && show.stdout.length >= GITHUB_MAX_BYTES) {
+      return { unknown: `${p} on ${baseRef} is 3 MB or more, and GitHub does not load a file that large` };
+    }
+    return { path: p, text: show.stdout.toString('utf8') };
+  }
+  return { none: `no CODEOWNERS on ${baseRef} (${paths.join(', ')})` };
+}
+
+// E69 — the lines that match no file: a fact about the file list, never a guess about a person. A GitLab
+// `!` line that excludes nothing is one too. `files` is every file the repo holds; `submodules` the paths
+// of its submodules, whose contents are not in that list — so a line that could reach into one is never
+// called dead (the probe name is a NUL, which no pattern this reader accepts can spell but `*` matches).
+// Returns [{ line, pattern, negate }] in file order.
+export function deadLines(parsed, files, { submodules = [] } = {}) {
+  const names = [...files, ...submodules.map((g) => `${g}/\u0000`)];
+  // `matches` asks about a file and every folder above it, and a dead line is asked about every name — the
+  // E69 reviews measured 300 000 files × 1 000 dead lines at minutes. So each folder is asked about ONCE,
+  // and each rule takes the fastest road that gives exactly `matches`' answer (tests hold them equal): a
+  // plain part no name has settles it at once; plain text is a set lookup; an "at any depth" pattern that
+  // cannot match a `/` tests the distinct last k parts; a pattern anchored at the top tests only the names
+  // that start with its plain head. Anything else scans every name.
+  const dirs = new Set();
+  for (const f of names) for (let i = f.indexOf('/'); i >= 0; i = f.indexOf('/', i + 1)) dirs.add(f.slice(0, i));
+  const dirList = [...dirs];
+  const nameSet = new Set(names);
+  const partSet = new Set(names.flatMap((f) => f.split('/')));
+  const sortedNames = [...names].sort();
+  const sortedDirs = [...dirList].sort();
+  // The distinct last `k` parts of every name, built once per `k`.
+  const tails = new Map();
+  const tailsOf = (k) => {
+    if (!tails.has(k)) {
+      // A name with fewer than k parts gives itself, which holds fewer than k-1 slashes and so never matches.
+      const cut = (list) => new Set(list.map((x) => x.split('/').slice(-k).join('/')));
+      const files = cut(names);
+      const folders = cut(dirList);
+      tails.set(k, { files, dirs: folders, fileList: [...files], dirList: [...folders] });
+    }
+    return tails.get(k);
+  };
+  // The names in a sorted list that start with `prefix`.
+  const under = (sorted, prefix) => {
+    let lo = 0;
+    let hi = sorted.length;
+    while (lo < hi) { const mid = (lo + hi) >> 1; if (sorted[mid] < prefix) lo = mid + 1; else hi = mid; }
+    const out = [];
+    for (let i = lo; i < sorted.length && sorted[i].startsWith(prefix); i++) out.push(sorted[i]);
+    return out;
+  };
+  const test = (pat, fileList, folderList) => (pat.fileToo && fileList.some((f) => pat.re.test(f))) || (pat.dirs && folderList.some((d) => pat.re.test(d)));
+
+  const live = (pat) => {
+    if (pat.all) return names.length > 0;
+    // `patternOf` writes `^`, then `(?:.*\/)?` for "at any depth" (once per leading `**/`), then the rest,
+    // then `$`. The rest is read piece by piece: a character, `\` + a character that is not a letter or a
+    // digit (V8 writes a carriage return in `source` as `\r`, which is NOT the letter `r`), `[^/]` with or
+    // without `*`, or anything else, which is not read here. Reading a piece as "anything else" is always
+    // safe: it only sends the rule down a slower road to the same answer.
+    const m = pat.re.source.match(/^\^((?:\(\?:\.\*\\\/\)\?)*)(.*)\$$/);
+    if (!m) return test(pat, names, dirList);
+    const [, anyDepth, rest] = m;
+    const parts = [];
+    for (let i = 0; i < rest.length;) {
+      if (rest.startsWith('[^/]', i)) { parts.push({ cls: true }); i += rest[i + 4] === '*' ? 5 : 4; continue; }
+      const ch = rest[i];
+      if (ch === '\\' && i + 1 < rest.length && !/[A-Za-z0-9]/.test(rest[i + 1])) { parts.push({ text: rest[i + 1] }); i += 2; continue; }
+      if (/[\\.*+?()[\]{}|^$]/.test(ch)) { parts.push({ other: true }); i++; continue; }
+      parts.push({ text: ch });
+      i++;
+    }
+    // Every part of the pattern that is plain text between two real slashes (or an end) must be some
+    // name's part, or nothing can match — true for every shape, and it settles most dead lines at once.
+    // (A slash inside `(?:.*\/)?` sits next to `(` or `)`, so the parts beside it are never plain.)
+    let seg = [];
+    for (const p of [...parts, { text: '/' }]) {
+      if (p.text !== '/') { seg.push(p); continue; }
+      if (seg.length && seg.every((q) => 'text' in q) && !partSet.has(seg.map((q) => q.text).join(''))) return false;
+      seg = [];
+    }
+    const plain = parts.every((p) => 'text' in p);
+    const text = plain ? parts.map((p) => p.text).join('') : '';
+    if (plain && !anyDepth) return (pat.fileToo && nameSet.has(text)) || (pat.dirs && dirs.has(text));
+    if (anyDepth && !parts.some((p) => p.other)) {
+      // "At any depth", and the rest holds exactly k-1 slashes and nothing that can match one: only a
+      // name's last k parts can match it, so the distinct last k parts are tested instead of every path.
+      const t = tailsOf(parts.filter((p) => p.text === '/').length + 1);
+      if (plain) return (pat.fileToo && t.files.has(text)) || (pat.dirs && t.dirs.has(text));
+      const last = new RegExp(`^${rest}$`, 's');
+      return (pat.fileToo && t.fileList.some((x) => last.test(x))) || (pat.dirs && t.dirList.some((x) => last.test(x)));
+    }
+    if (!anyDepth) {
+      // Anchored at the top: every match starts with the plain text before the first wildcard, so only
+      // the names that start with it can match.
+      let head = '';
+      for (const p of parts) { if (!('text' in p)) break; head += p.text; }
+      if (head) return test(pat, under(sortedNames, head), under(sortedDirs, head));
+    }
+    return test(pat, names, dirList);
+  };
+  return parsed.rules.filter((r) => !live(r.pat)).map((r) => ({ line: r.line, pattern: r.pattern, negate: r.negate }));
+}
+
+// Does `rel` exist under `root` with exactly this spelling? A macOS or Windows disk ignores case, so a
+// plain stat finds `.github/codeowners` for `.github/CODEOWNERS` — but git, and so the platform, stores the
+// name as written (E69 review, round 1). Each part is looked for in its folder's listing. Throws what
+// reading a folder throws.
+function exactName(root, rel) {
+  let dir = root;
+  for (const part of rel.split('/')) {
+    if (!fs.readdirSync(dir).includes(part)) return false;
+    dir = path.join(dir, part);
+  }
+  return true;
+}
+
+// E69 — the CODEOWNERS file on DISK (the working tree, like `yad risk-map check`), as its platform would
+// pick it: the first of its locations that exists. Returns { path, text, ignored } — `ignored` the other
+// locations that hold a file the platform never reads — or { path, tooBig, ignored } for a GitHub file of
+// 3 MB or more, { none } when there is none, or { unknown: why }. A first location that is not a regular
+// file is `unknown`: the platform reads the blob git stores, and a symlink's blob is its target's name.
+export function diskCodeowners(repoRoot, platform) {
+  const paths = CODEOWNERS_PATHS[platform];
+  if (!paths) return { unknown: `no CODEOWNERS locations are known for platform '${platform}'` };
+  const found = [];
+  for (const p of paths) {
+    try {
+      if (!exactName(repoRoot, p)) continue;
+      found.push({ p, st: fs.lstatSync(path.join(repoRoot, p)) });
+    } catch (e) {
+      if (e.code === 'ENOENT' || e.code === 'ENOTDIR') continue;
+      return { unknown: `${p} could not be read (${e.code})` };
+    }
+  }
+  if (!found.length) return { none: `no CODEOWNERS (${paths.join(', ')})` };
+  const [first, ...rest] = found;
+  if (!first.st.isFile()) return { unknown: `${first.p} is not a regular file` };
+  const ignored = rest.filter((x) => !x.st.isDirectory()).map((x) => x.p);
+  if (platform === 'github' && first.st.size >= GITHUB_MAX_BYTES) return { path: first.p, tooBig: true, ignored };
+  try {
+    return { path: first.p, text: fs.readFileSync(path.join(repoRoot, first.p), 'utf8'), ignored };
+  } catch (e) {
+    return { unknown: `${first.p} could not be read (${e.code})` };
+  }
+}

package/cli/commit.mjs

@@ -9,7 +9,8 @@ import fs from 'node:fs';
 import { c, log, ok, info, warn, fail, run, exists } from './lib.mjs';
 import {
   COMMIT_TYPES, AI_COAUTHORS, ATOMIC_FILE_LIMIT,
-  TASK_TRAILER, CONTRACT_CHANGE_TRAILER, COAUTHOR_TRAILER, PROJECT_FILES, TASK_ID_RE,
+  TASK_TRAILER, CONTRACT_CHANGE_TRAILER, COAUTHOR_TRAILER, TASK_ID_RE,
+  productConfigPath,
 } from './manifest.mjs';
 
 // PURE — unit tested directly. Build the full commit message text.
@@ -52,7 +53,7 @@ export async function runCommit(root, opts = {}) {
   if (!staged.length) { fail('nothing staged — `git add` your atomic change first'); process.exitCode = 1; return; }
 
   if (staged.length > ATOMIC_FILE_LIMIT && !opts.force) {
-    warn(`${staged.length} files staged (atomic guard: ≤${ATOMIC_FILE_LIMIT}). Split the change, or pass --force.`);
+    fail(`${staged.length} files staged (atomic guard: ≤${ATOMIC_FILE_LIMIT}). Split the change, or pass --force.`);
     for (const f of staged) info(f);
     process.exitCode = 1;
     return;
@@ -61,11 +62,11 @@ export async function runCommit(root, opts = {}) {
   const branch = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: root }).stdout;
   const task = opts.task || taskFromBranch(branch);
   if (!task) {
-    // spec-link is a code-repo gate (REPO_WIRING.common), not a hub gate — so a missing Task trailer
-    // is expected on a hub PR (front-half artifact review or hub tooling) and only matters on a repo.
-    const onHub = exists(path.join(root, PROJECT_FILES.hubConfig));
+    // spec-link is a code-repo gate (REPO_WIRING.common), not a Product gate — so a missing Task trailer
+    // is expected on a Product PR (Shape artifact review or Product tooling) and only matters on a repo.
+    const onHub = exists(productConfigPath(root));
     warn(onHub
-      ? 'no Task trailer (none given and branch has no -S0N-T0N) — fine for a hub PR; required on code-repo tasks (spec-link gate)'
+      ? 'no Task trailer (none given and branch has no -S0N-T0N) — fine for a Product PR; required on code-repo tasks (spec-link gate)'
       : 'no Task trailer (none given and branch has no -S0N-T0N) — spec-link gate will fail on a code repo');
   }
 
@@ -77,13 +78,16 @@ export async function runCommit(root, opts = {}) {
     });
   } catch (e) { fail(e.message); process.exitCode = 1; return; }
 
-  if (opts.dryRun) { log('\n' + c.dim(message) + '\n'); info('dry run — not committed'); return { message }; }
+  // The --json answer (E1): what was (or would be) committed.
+  const answer = { message, task: task || null, files: staged, contractChange: !!opts.contractChange };
+  if (opts.dryRun) { log('\n' + c.dim(message) + '\n'); info('dry run — not committed'); return { ...answer, committed: false, dryRun: true }; }
 
   const r = run('git', ['commit', '-m', message], { cwd: root });
-  if (!r.ok) { fail(`git commit failed — ${r.stderr.split('\n')[0] || r.code}`); process.exitCode = 1; return { message }; }
+  if (!r.ok) { fail(`git commit failed — ${r.stderr.split('\n')[0] || r.code}`); process.exitCode = 1; return { ...answer, committed: false, dryRun: false }; }
   ok(`committed ${staged.length} file(s)${task ? ` for ${task}` : ''}`);
   if (opts.contractChange) warn('Contract-Change: yes — this routes back to the architecture gate');
-  return { message };
+  const sha = run('git', ['rev-parse', 'HEAD'], { cwd: root });
+  return { ...answer, committed: true, dryRun: false, commit: sha.ok ? sha.stdout : null };
 }
 
 // installed by yad-implement, but offer it here too for convenience.

package/cli/companion.mjs

@@ -1,5 +1,5 @@
-// cli/companion.mjs — pure, perspective-neutral helpers for the Review Companion, shared by the front
-// half (yad gate …) and the back half (yad review …). The CLI never calls an LLM — generation happens
+// cli/companion.mjs — pure, perspective-neutral helpers for the Review Companion, shared by Shape
+// (yad gate …) and Build (yad review …). The CLI never calls an LLM — generation happens
 // in the skill/harness layer (like yad-learn/yad-docs). This module owns the platform MARKERS, the
 // engagement parsing, the trailer-block upsert, and the message text the skill and the gate share.
 //

package/cli/dial.mjs

@@ -0,0 +1,183 @@
+// `yad dial` / `yad kill` / `yad unkill` — the advance dial, set freely, and the kill switch (E34).
+//
+// Automation used to be earned: the `yad-run` skill refused `advance: auto` until a step's trust log
+// cleared a threshold, and `yad-status` nudged about steps that had cleared it and stayed manual. E34
+// deletes both. The team sets the dial; this command shows the run record beside it as ADVICE and never
+// refuses on it. The rules live in epic-state.mjs (`planShapeDial`, `planLaneDial`, `planKill`,
+// `effectiveAdvance`); this reads the files, prints the advice and writes the result.
+//
+// What it never does: set a gate to `auto` (rule 1), write over an `automation.json` it cannot read, or
+// write a lane step that `yad-run` has not put on the lane yet.
+//
+// READING IS A CONTRACT. The `yad-run` skill asks `yad dial … --json` for the dial of every step it walks,
+// the merge gate included, and uses `advance`. So a read never refuses a gate — it answers `human`, `why:
+// gate` — and never fails because the run record beside the dial cannot be read.
+import path from 'node:path';
+
+import { c, fail, hand, info, ok, readJSONStrict, warn, writeJSON, emitJSON } from './lib.mjs';
+import {
+  effectiveAdvance, epicRel, epicRoot, epicStories, isGateStep, killSwitchOn, loadAutomation, loadLedger, planKill,
+  planLaneDial, planShapeDial, serializeAutomation, stepDef,
+} from './epic-state.mjs';
+import { epicFiles, PROJECT_FILES } from './manifest.mjs';
+import { readTrustRuns } from './ledger.mjs';
+import { recordActor } from './skip.mjs';
+
+const makeBail = (json) => (message, hint) => {
+  if (json) emitJSON({ ok: false, error: message, hint: hint || null });
+  else { fail(message); if (hint) hand(hint); }
+  process.exitCode = 1;
+};
+
+const killLine = (kill) => {
+  const who = [kill?.by ? `by ${kill.by}` : '', kill?.date ? `on ${kill.date}` : ''].filter(Boolean).join(' ');
+  return `the kill switch is ON${who ? ` (${who})` : ''}${kill?.reason ? `: ${kill.reason}` : ''}`;
+};
+
+// A broken `automation.json` holds every step at human; say that it is the FILE, not somebody's switch.
+const heldLine = (automation) => (automation.error
+  ? `${PROJECT_FILES.automationConfig} ${automation.error} — every step is held at advance: human until it is fixed (yad doctor)`
+  : killLine(automation.kill));
+// Only when there is one, so a healthy project's JSON keeps exactly the keys it had.
+const errorKey = (automation) => (automation.error ? { automationError: automation.error } : {});
+
+// `yad dial <step> [--to auto|human]` for a Shape author step, or
+// `yad dial <epic> <story> --repo <name> <step> [--to auto|human]` for a Build lane step. No `--to` reads.
+export async function runDial(root, { epic = null, story = null, repo = null, step, to = null, json = false } = {}) {
+  const bail = makeBail(json);
+  if (!step) return bail('usage: yad dial <step> [--to auto|human]   |   yad dial <epic> <story> --repo <name> <step> [--to auto|human]');
+  const automation = loadAutomation(root);
+  return epic
+    ? dialLane(root, { epic, story, repo, step, to, json, bail, automation })
+    : dialShape(root, { step, to, json, bail, automation });
+}
+
+// The answer for a gate asked with no `--to`: always a person. Not a refusal (see the header).
+function gateAnswer({ json, automation, scope, fields, label }) {
+  if (json) {
+    return emitJSON({
+      ok: true, scope, ...fields, set: 'human', advance: 'human', why: 'gate', changed: false,
+      kill: automation.kill, trust: null, ...errorKey(automation),
+    });
+  }
+  ok(`${label} — advance: human (a review gate: always a person)`);
+}
+
+function dialShape(root, { step, to, json, bail, automation }) {
+  if (!to && stepDef(step)?.kind === 'review' && stepDef(step)?.phase !== 'build') {
+    return gateAnswer({ json, automation, scope: 'shape', fields: { step }, label: c.bold(step) });
+  }
+  // Nothing is written over a file that cannot be read — it may hold a kill switch somebody set. This is
+  // the only path that writes `automation.json`, so it is the only one that refuses on it.
+  if (to && automation.error) {
+    return bail(`${PROJECT_FILES.automationConfig} ${automation.error} — nothing is written over it, and every step is held at advance: human until it is fixed`,
+      'fix the JSON, or delete the file to go back to the defaults (kill switch off, every Shape step human)');
+  }
+  const plan = planShapeDial(automation, { step, to: to || 'human' });
+  if (!plan.ok) return bail(plan.message, plan.hint);
+  const after = to ? plan.automation : automation;
+  if (to && plan.changed) writeJSON(path.join(root, PROJECT_FILES.automationConfig), serializeAutomation(plan.automation));
+  const eff = effectiveAdvance({ id: step }, { ...after, error: automation.error });
+  if (json) {
+    return emitJSON({
+      ok: true, scope: 'shape', step, set: eff.set, advance: eff.advance, why: eff.why,
+      changed: !!to && plan.changed, kill: automation.kill, trust: null, ...errorKey(automation),
+    });
+  }
+  const label = c.bold(step);
+  if (!to) ok(`${label} — advance: ${eff.set}${eff.why === 'kill' ? ' (held at human)' : ''}`);
+  else if (plan.changed) ok(`${label} set to advance: ${to} for this project`);
+  else ok(`${label} was already advance: ${to} — nothing changed`);
+  if (eff.set === 'auto') {
+    info('no run record exists for a Shape step — the yad-run skill records Build steps only');
+    info(`recorded, not acted on yet: nothing drives a Shape step on its own until the engine runs agents (E26), so ${step} still waits for its author. Its review gate is always a person`);
+  }
+  if (killSwitchOn(automation)) warn(heldLine(automation));
+  if (to && plan.changed) hand(`commit ${PROJECT_FILES.automationConfig}  (reverse with \`yad dial ${step} --to ${to === 'auto' ? 'human' : 'auto'}\`)`);
+}
+
+function dialLane(root, { epic, story, repo, step, to, json, bail, automation }) {
+  if (!story || !repo) return bail(`usage: yad dial ${epic} <story> --repo <name> ${step} [--to auto|human]`);
+  const epicDir = epicRoot(root, epic);
+  const ledger = loadLedger(epicDir);
+  if (!ledger.state) return bail(`no epic state at ${epicRel(epic)} — seed the epic first`);
+  const entry = epicStories(epicDir).find((st) => st.id === story);
+  if (!entry) return bail(`no story ${story} under ${epicRel(epic)}/stories/`);
+  const label = `${c.cyan(story)} / ${c.bold(repo)} ${c.bold(step)}`;
+  if (!to && stepDef(step)?.phase === 'build' && isGateStep({ id: step })) {
+    return gateAnswer({ json, automation, scope: 'lane', fields: { epic, story, repo, step }, label });
+  }
+  const file = path.join(epicFiles(epicDir).buildStateDir, `${story}.json`);
+  // Strict: a read-modify-write against a file that will not parse would delete what is in it.
+  const current = readJSONStrict(file, null);
+  const plan = planLaneDial(current, { story, repo, step, to: to || 'human', declared: entry.repos });
+  if (!plan.ok) return bail(plan.message, plan.hint);
+
+  // The advice, read BEFORE anything is written: every recorded run of this step in this repo. A record
+  // that cannot be read is reported and set aside — advice never blocks the dial it sits beside.
+  let trust = null;
+  let trustError = null;
+  try {
+    const runs = readTrustRuns(epicDir).filter((e) => e && e.step === step && e.repo === repo);
+    trust = { runs: runs.length, approvedUnchanged: runs.filter((e) => e.verdict === 'approved-unchanged').length };
+  } catch (e) {
+    trustError = e.message;
+  }
+
+  const state = to ? plan.buildState : current;
+  if (to && plan.changed) writeJSON(file, plan.buildState);
+  const row = state.repos[repo].steps.find((x) => x && x.id === step);
+  const eff = effectiveAdvance(row, automation);
+
+  if (json) {
+    return emitJSON({
+      ok: true, scope: 'lane', epic, story, repo, step, set: eff.set, advance: eff.advance, why: eff.why,
+      changed: !!to && plan.changed, kill: automation.kill, trust, ...errorKey(automation),
+      ...(trustError ? { trustError } : {}),
+    });
+  }
+  if (!to) ok(`${label} — advance: ${eff.set}${eff.why === 'kill' ? ' (held at human)' : ''}`);
+  else if (plan.changed && plan.before === to) ok(`${label} was already advance: ${to} — the new dial name was added beside the old one`);
+  else if (plan.changed) ok(`${label} set to advance: ${to}`);
+  else ok(`${label} was already advance: ${to} — nothing changed`);
+  if (trustError) warn(`the run record cannot be read (${trustError}) — the dial is not affected; run \`yad doctor\``);
+  else {
+    info(trust.runs
+      ? `run record for ${step} in ${repo}: ${trust.runs} run(s), ${Math.round((trust.approvedUnchanged / trust.runs) * 100)}% approved unchanged`
+      : `nothing has run ${step} in ${repo} yet — no evidence either way`);
+    info(c.dim('advice, not a rule: the team decides (E34)'));
+  }
+  if (eff.set === 'auto') {
+    info(`the yad-run skill moves past ${step} on its own after a clean run. A failed check, a scope overrun or a contract touch still stops it, and the merge is always a person`);
+  }
+  if (killSwitchOn(automation)) warn(heldLine(automation));
+  if (to && plan.changed) hand(`commit it with \`yad checkpoint --push\`  (reverse with \`yad dial ${epic} ${story} --repo ${repo} ${step} --to ${to === 'auto' ? 'human' : 'auto'}\`)`);
+}
+
+// `yad kill --reason "<why>"` / `yad unkill [--reason "<why>"]`.
+export async function runKill(root, { on, reason = null, json = false, today = null } = {}) {
+  const bail = makeBail(json);
+  const automation = loadAutomation(root);
+  if (automation.error) {
+    return bail(`${PROJECT_FILES.automationConfig} ${automation.error} — nothing is written over it`,
+      'fix the JSON, or delete the file (kill switch off, every Shape step human), then run this again');
+  }
+  const plan = planKill(automation, { on, reason, by: recordActor(root), date: today });
+  if (!plan.ok) return bail(plan.message, plan.hint);
+  if (!plan.already) writeJSON(path.join(root, PROJECT_FILES.automationConfig), serializeAutomation(plan.automation));
+  const kill = plan.automation.kill;
+  if (json) return emitJSON({ ok: true, kill, changed: !plan.already });
+  if (plan.already) {
+    ok(`the kill switch was already ${on ? 'on' : 'off'} — nothing changed`);
+    if (on) info(killLine(kill));
+    return;
+  }
+  if (on) {
+    ok('kill switch ON — every step is held at advance: human');
+    info(`reason: ${kill.reason}`);
+  } else {
+    ok('kill switch off — each step follows its own dial again');
+    if (kill.reason) info(`reason: ${kill.reason}`);
+  }
+  hand(`commit ${PROJECT_FILES.automationConfig} so every machine and CI run sees it  (reverse with \`yad ${on ? 'unkill' : 'kill --reason "<why>"'}\`)`);
+}