@ersbeth/codelife 0.0.0-bootstrap.0 → 0.11.1

package/scripts/release/entry.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// `codelife release entry` (K-16, R-247): once the tag is on origin, the forge's release entry for
+// it, its notes the version's changelog section — an entry the forge already has, or refuses, is a
+// line, never a failure —, then the hand-off: the pipeline's URL, the registry page of a package
+// that is not private, and the failure modes a person watching recognises. Publishes nothing and
+// watches nothing. Exit 1 when the tag is missing, here or on origin.
+import '../node-floor.mjs';
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { tagFor } from '../tags.mjs';
+import { cli as forgeCli, env, parseOrigin } from '../tracker/lib.mjs';
+import { hasOrigin, manifest, said, say, trackerKind, versionFile } from './lib.mjs';
+import { git, sh } from '../verify/lib.mjs';
+
+if (process.argv.length > 2) { console.error('usage: codelife release entry'); process.exit(2); }
+console.log('### release entry');
+const stop = (why) => { say('stop', why); process.exit(1); };
+const pkg = manifest(versionFile()) ?? {};
+const v = pkg.version, tag = v && tagFor(v);
+if (!tag || !git('tag', '-l', tag).out) stop(`no tag ${tag ?? 'for the version file'} — \`codelife release cut\` first`);
+if (!hasOrigin()) { say('entry', 'none — no origin: the changelog section is the entry'); process.exit(0); }
+const ls = git('ls-remote', '--exit-code', '--tags', 'origin', `refs/tags/${tag}`);
+if (ls.status === 2) stop(`origin has no ${tag} — \`git push origin refs/tags/${tag}\` first`);
+if (ls.status) stop(`origin could not tell — ${said(ls)}`);
+
+const kind = trackerKind();
+let notes = '';
+try {
+  const lines = readFileSync('CHANGELOG.md', 'utf8').split('\n');
+  const at = lines.findIndex((l) => l.startsWith(`## [${v}]`));
+  if (at >= 0) { const end = lines.findIndex((l, i) => i > at && (l.startsWith('## ') || l.startsWith('<!--'))); notes = lines.slice(at + 1, end < 0 ? undefined : end).join('\n').trim(); }
+} catch { /* no changelog: an entry with no notes */ }
+if (kind === 'glab' || kind === 'gh') {
+  const file = join(mkdtempSync(join(tmpdir(), 'codelife-release-')), 'notes.md');
+  writeFileSync(file, `${notes}\n`);
+  const cli = (...a) => sh(forgeCli(), a, { env: env() });
+  if (cli('release', 'view', tag).status === 0) say('entry', `exists already on ${tag} — left as it is`);
+  else {
+    const r = kind === 'glab' ? cli('release', 'create', tag, '--name', v, '--notes-file', file) : cli('release', 'create', tag, '--title', v, '--notes-file', file, '--verify-tag');
+    say('entry', r.status ? `degraded — ${said(r)}` : `created on ${tag}${r.out ? ` — ${r.out.split('\n').at(-1)}` : ''}`);
+  }
+} else say('entry', `none — tracker.kind ${kind}: the changelog section is the entry`);
+
+const url = git('remote', 'get-url', 'origin').out, forge = parseOrigin(url);
+if (!forge) say('pipeline', `none — origin ${url} is no forge`);
+else if (kind === 'gh' || forge.host === 'github.com') say('pipeline', `https://${forge.host}/${forge.project}/actions`);
+else say('pipeline', `https://${forge.host}/${forge.project}/-/pipelines?ref=${tag}`);
+say('registry', pkg.private || !pkg.name ? 'none — the package is private or unnamed' : `https://www.npmjs.com/package/${pkg.name}`);
+say('watch for', 'no pipeline at all — the tag matches nothing the pipeline\'s rules watch for');
+say('watch for', 'an authentication error at publish time (EOTP and its kin) — an account authenticated where a trusted publisher was expected');
+say('watch for', 'a green pipeline that published nothing — the job\'s condition did not match the tag');

package/scripts/release/lib.mjs

@@ -0,0 +1,136 @@
+// What `codelife release prep`, `cut` and `entry` share (K-16), from the repository's root: where a
+// release may run, the line's last tag and the commits since it, the bump the scheme gives, and a
+// version already prepared. The rules are release.md's; each function says which.
+import '../node-floor.mjs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PATTERNS, spellings, versionOf } from '../tags.mjs';
+import { git, guards, sh } from '../verify/lib.mjs';
+import { field } from '../contract.mjs';
+
+export const said = (r) => (r.err || r.out).split('\n').at(-1);
+export const say = (key, value) => console.log(`- ${key}: ${value}`);
+
+export const versionFile = () => field('release.version_file') ?? '';
+export const trackerKind = () => field('tracker.kind') ?? 'none';
+export const manifest = (path, ref) => {
+  const text = ref ? git('show', `${ref}:${path}`) : { status: existsSync(path) ? 0 : 1, out: existsSync(path) ? readFileSync(path, 'utf8') : '' };
+  try { return text.status ? null : JSON.parse(text.out); } catch { return null; }
+};
+export const isTagged = (version, name) => !!git('tag', '-l', ...spellings(version, name)).out;
+// The paths the tree changed, staged or not, untracked included; read untrimmed, NUL-separated.
+// A rename's or a copy's entry is followed by its origin's, skipped. A git status that fails is
+// `fail`'s, a `- stop:` and exit 1 unless the caller gives its own: never a clean tree.
+export const dirtyPaths = (fail = (why) => { say('stop', why); process.exit(1); }) => {
+  const r = sh('git', ['status', '--porcelain', '-z', '-uall'], { trim: false });
+  if (r.status) return fail(`git status could not tell what the tree changed — ${r.err}`);
+  const entries = r.out.split('\0');
+  const paths = [];
+  for (let i = 0; i < entries.length; i++) if (entries[i]) { paths.push(entries[i].slice(3)); if (/^[RC]/.test(entries[i])) i++; }
+  return paths;
+};
+export const hasOrigin = () => git('remote', 'get-url', 'origin').status === 0;
+
+// R-241: `develop` cuts a release, `main` a hotfix's patch, `support/` a patch on an older line;
+// `--prepare` runs on any branch, the merge and the tag left to a later run on one of those three.
+export function where(prepare) {
+  const branch = git('branch', '--show-current').out;
+  const kind = { develop: 'release', main: 'hotfix' }[branch] ?? (branch.startsWith('support/') ? 'support' : null);
+  const stops = [];
+  if (!branch) stops.push('HEAD is detached — check out develop, main or a support/ branch');
+  else if (!kind && !prepare) stops.push(`${branch} is a work branch — merge it, then run /release on develop (C-355), or prepare it with --prepare`);
+  const dirty = dirtyPaths((why) => { stops.push(why); return []; });
+  if (dirty.length) stops.push(`the tree is not clean — a release commits what it writes and nothing else: ${dirty.slice(0, 5).join(', ')}${dirty.length > 5 ? ', …' : ''}`);
+  return { branch, kind, stops };
+}
+
+// R-241: level with origin as the forge has it, not as the last fetch left it. Behind or diverged
+// stops; ahead is what the pushes carry; no origin keeps the release local.
+export function level(branch) {
+  if (!hasOrigin()) return { line: 'none — the release stays local: nothing compared, pushed or handed off' };
+  const ls = git('ls-remote', '--exit-code', '--heads', 'origin', branch);
+  if (ls.status === 2) return { line: `has no ${branch} yet — ahead, the push carries it` };
+  const f = ls.status ? ls : git('fetch', 'origin', `+refs/heads/${branch}:refs/remotes/origin/${branch}`);
+  if (f.status) return { stop: `origin could not tell — ${said(f)}` };
+  const [behind, ahead] = git('rev-list', '--left-right', '--count', `origin/${branch}...HEAD`).out.split(/\s+/).map(Number);
+  if (behind && ahead) return { stop: `${branch} diverged from origin/${branch}, ${ahead} ahead and ${behind} behind — reconcile first` };
+  if (behind) return { stop: `${branch} is ${behind} behind origin/${branch} — \`git pull --ff-only\`, then /release again` };
+  return { line: ahead ? `${ahead} ahead of origin/${branch} — the push carries it` : `level with origin/${branch}` };
+}
+
+// R-242: the line's last tag, whichever spelling it has, and the commits since it as Conventional
+// Commits; with no tag, the whole history.
+export const lastTag = () => {
+  const r = git('describe', '--tags', '--abbrev=0', ...PATTERNS.flatMap((p) => ['--match', p]), 'HEAD');
+  return r.status ? null : r.out;
+};
+export const commits = (from) => git('log', '--no-merges', '--format=%H%x1f%s%x1f%b%x1e', ...(from ? [`${from}..HEAD`] : ['HEAD'])).out
+  .split('\x1e').map((x) => x.replace(/^\n/, '')).filter(Boolean).map((record) => {
+    const [sha, subject, body = ''] = record.split('\x1f');
+    const m = subject.match(/^(\w+)(?:\([^)]*\))?(!)?: \S/);
+    return { sha, subject, type: m?.[1] ?? null, breaking: !!m?.[2] || /^BREAKING[ -]CHANGE: /m.test(body) };
+  });
+
+// R-242: the scheme, derived from the manifest at the last tag — `major.peer.patch` when its version
+// reads `<n>.<peer>.<p>` and a peerDependencies entry has minor `<peer>` —, then the bump.
+const numbers = (v) => v.split('-')[0].split('.').map(Number);
+const peerMinor = (range) => { const m = String(range ?? '').match(/(\d+)\.(\d+)/); return m ? Number(m[2]) : null; };
+export function bump(from, list, before, now) {
+  const [M, m, p] = numbers(from);
+  const peer = Object.entries(before?.peerDependencies ?? {}).find(([, r]) => peerMinor(r) === m)?.[0];
+  const breaking = list.some((c) => c.breaking), feat = list.some((c) => c.type === 'feat');
+  const scheme = peer ? `major.peer.patch — peer ${peer}` : 'semver';
+  if (from.includes('-')) return { scheme, version: `${M}.${m}.${p}`, why: `the final release of the pre-release ${from}` };
+  if (peer) {
+    const moved = peerMinor(now?.peerDependencies?.[peer]);
+    if (moved !== null && moved !== m) return { scheme, version: `${M + 1}.${moved}.0`, why: `the peer ${peer} moved from minor ${m} to ${moved}: a new line`, support: `support/${M}.${m}` };
+    return breaking ? { scheme, version: `${M + 1}.${m}.0`, why: 'a breaking change bumps the own major, at the same peer' }
+      : { scheme, version: `${M}.${m}.${p + 1}`, why: 'anything else bumps the patch under major.peer.patch' };
+  }
+  if (M === 0) return breaking || feat ? { scheme, version: `0.${m + 1}.0`, why: `${breaking ? 'a breaking change' : 'a feat'} bumps the middle number on a 0.x line` }
+    : { scheme, version: `0.${m}.${p + 1}`, why: 'no feat and no breaking change' };
+  if (breaking) return { scheme, version: `${M + 1}.0.0`, why: 'a breaking change' };
+  return feat ? { scheme, version: `${M}.${m + 1}.0`, why: 'a feat, no breaking change' } : { scheme, version: `${M}.${m}.${p + 1}`, why: 'no feat and no breaking change' };
+}
+
+// R-241: a version file ahead of every tag is a release prepared — by `--prepare`, or by a run
+// interrupted after its commit — and is resumed at the merge only when nothing landed after its
+// release commit; otherwise the bump is redone from the last tag.
+export function prepared(version, name, from) {
+  if (!version || version === '0.0.0' || isTagged(version, name)) return null;
+  const commit = git('log', '-1', '--format=%H', '-F', `--grep=chore(release): ${version}`, ...(from ? [`${from}..HEAD`] : ['HEAD'])).out;
+  if (!commit) return { version, commit: null, after: [] };
+  return { version, commit, after: git('rev-list', '--no-merges', `${commit}..HEAD`).out.split('\n').filter(Boolean) };
+}
+
+// R-244: the version file, and every published package.json the workspace declares.
+export function packages(vf) {
+  const root = manifest('package.json') ?? {};
+  let globs = Array.isArray(root.workspaces) ? root.workspaces : root.workspaces?.packages ?? [];
+  if (existsSync('pnpm-workspace.yaml')) {
+    const block = readFileSync('pnpm-workspace.yaml', 'utf8').split(/^packages:\s*$/m)[1]?.split(/^\S/m)[0] ?? '';
+    globs = [...block.matchAll(/^\s+-\s*['"]?([^'"\s#]+)/gm)].map((m) => m[1]);
+  }
+  const dirs = globs.filter((g) => !g.startsWith('!')).flatMap((g) => g.endsWith('/*')
+    ? (existsSync(g.slice(0, -2)) ? readdirSync(g.slice(0, -2), { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => join(g.slice(0, -2), d.name)) : [])
+    : [g.replace(/\/$/, '')]);
+  const files = dirs.map((d) => join(d, 'package.json')).filter((f) => { const j = manifest(f); return j && !j.private && j.version; });
+  return [...new Set([vf, ...files])];
+}
+
+// R-243: the generated[] entry that writes CHANGELOG.md, its command one line of shell.
+export const changelog = () => guards('generated').find((g) => (g.path ?? []).includes('CHANGELOG.md'))?.command?.join(' && ') ?? null;
+
+// The facts prep prints and cut acts on, read once.
+export function read(prepare = false) {
+  const w = where(prepare);
+  const vf = versionFile();
+  const now = vf ? manifest(vf) : null;
+  const tag = lastTag();
+  const list = commits(tag);
+  const from = tag ? versionOf(tag) : null;
+  const p = now ? prepared(now.version, now.name, tag) : null;
+  const resume = p?.commit && !p.after.length ? p : null;
+  const proposed = from && list.length ? bump(from, list, manifest(vf, tag), now) : null;
+  return { ...w, vf, now, tag, from, list, prepared: p, resume, proposed };
+}

package/scripts/release/prep.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// `codelife release prep [--prepare]` (K-16): everything /release states before it asks for the
+// version — the branch, origin, the last tag, the commits since it, the bump, a release already
+// prepared, the audit the cadence proposes, the changelog generator. Reads only; one `### release
+// prep` block; a `- stop:` line per thing that stops the run, and exit 1.
+import '../node-floor.mjs';
+import { cadence } from '../audit/cadence.mjs';
+import { changelog, level, read, say, trackerKind } from './lib.mjs';
+import { git, sh } from '../verify/lib.mjs';
+
+const args = process.argv.slice(2);
+if (args.some((a) => a !== '--prepare')) { console.error('usage: codelife release prep [--prepare]'); process.exit(2); }
+const prepare = args.includes('--prepare');
+const f = read(prepare);
+const stops = [...f.stops];
+
+console.log('### release prep');
+say('branch', `${f.branch || 'detached'} — ${{ release: 'a release, merged into main and tagged there', hotfix: 'a patch after a hotfix, tagged on main and merged back into develop', support: 'a patch on an older line, tagged here, merged nowhere' }[f.kind] ?? 'a work branch'}${prepare ? ' — --prepare: up to the release commit' : ''}`);
+if (f.branch) {
+  const l = level(f.branch);
+  if (l.stop) stops.push(l.stop); else say('origin', l.line);
+}
+if (!f.vf || !f.now?.version) stops.push(`no version read from release.version_file ('${f.vf}') — /setup`);
+else say('version file', `${f.vf} reads ${f.now.version}`);
+say('last tag', f.tag ? `${f.tag} (${f.from})` : 'none — the whole history is read, and the first version is yours to give');
+
+const types = Object.entries(f.list.reduce((n, c) => ({ ...n, [c.type ?? 'unparsed']: (n[c.type ?? 'unparsed'] ?? 0) + 1 }), {})).sort((a, b) => b[1] - a[1]);
+say('commits', f.list.length ? `${f.list.length} since ${f.tag ?? 'the first'} — ${types.map(([t, n]) => `${t} ${n}`).join(', ')}` : 'none');
+for (const c of f.list.filter((x) => x.breaking)) say('breaking', `${c.sha.slice(0, 8)} ${c.subject}`);
+
+if (f.resume) say('resume', `${f.resume.version} is prepared by ${f.resume.commit.slice(0, 8)} chore(release): ${f.resume.version} and carries no tag — \`codelife release cut\` goes straight to the merge and the tag`);
+else {
+  if (f.prepared?.commit) say('prepared', `${f.prepared.version} by ${f.prepared.commit.slice(0, 8)}, but ${f.prepared.after.length} commit${f.prepared.after.length === 1 ? '' : 's'} landed after it — the bump is redone from ${f.tag ?? 'the first commit'}`);
+  else if (f.prepared) say('prepared', `${f.prepared.version} carries no tag and no release commit — the bump is redone from ${f.tag ?? 'the first commit'}`);
+  if (f.tag && !f.list.length) stops.push(`nothing since ${f.tag} — no release to cut`);
+  if (f.proposed) {
+    say('scheme', f.proposed.scheme);
+    say('bump', `${f.proposed.version} — ${f.proposed.why}`);
+    if (f.proposed.support) say('support', `${f.proposed.support} at ${f.tag}, opened with the bump so the old line stays patchable`);
+    const [M, m] = f.from.split('.').map(Number), [nM, nm] = f.proposed.version.split('.').map(Number);
+    // A campaign since the last tag already answers the bump's proposal (R-248, C-368); both days in UTC (#1137).
+    const c = cadence(), since = new Date(git('log', '-1', '--format=%ct', f.tag).out * 1000).toISOString().slice(0, 10);
+    const after = (row) => row && row[1] >= since;
+    const audit = c.due ? `full — ${c.due}` : nM > M && !after(c.full) ? 'full — before a major' : nm > m && !after(c.last) ? 'targeted — before a minor' : null;
+    say('audit', audit ? `${audit}: /audit proposed first` : 'none due');
+  } else if (!f.tag) say('bump', 'none — no tag: give the first version');
+}
+
+const cl = changelog();
+if (!cl) stops.push('no generated[] entry writes CHANGELOG.md — /setup');
+else {
+  const r = sh(`${cl} --check`, [], { shell: true });
+  if (r.status) stops.push(`the changelog generator refuses — ${r.err.split('\n')[0] || `exit ${r.status}`}`);
+  else say('changelog', `\`${cl}\` renders`);
+}
+say('tracker', trackerKind());
+for (const s of stops) say('stop', s);
+process.exit(stops.length ? 1 : 0);

package/scripts/review-mr/prepare.mjs

@@ -0,0 +1,163 @@
+// /review-mr's preparation, `codelife review prep [<n>]` (C-762): the merge request — the argument,
+// or the one open for the current branch —, the account, the forge CLI against its floor, the head
+// asserted and the tree clean, the diff with each file's changed lines, *How to test* split by
+// shape, the known list, the reader's case and the earlier pass — every file in a run folder
+// outside the tree, and a summary printed, which the brief is made from. Its forge and git reads run
+// scripts/tracker/ and scripts/git/, each named after its operation. A precondition that fails, or
+// a read that does, prints `- stop:` and exits 1, before any agent. From the repository's root.
+//
+// The run folder: mr.json, comments.md, diff.diff, lines.tsv (`<path>\t<new|old>\t<a>\t<b>`),
+// commands.txt and manual.md (*How to test*'s commands, one a line, and its manual steps), known.txt,
+// case.md — what the reader is handed: the range, the issues the commits close with their umbrella
+// and what each cites, or the description when none is closed.
+import '../node-floor.mjs';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { field } from '../contract.mjs';
+
+const pkg = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+let n = process.argv[2];
+if (n !== undefined && !/^\d+$/.test(n)) {
+  console.error('usage: codelife review prep [<mr-number>]');
+  process.exit(2);
+}
+const summary = ['### prepare'];
+const say = (line) => summary.push(`- ${line}`);
+const stop = (why) => {
+  say(`stop: ${why}`);
+  console.log(summary.join('\n'));
+  process.exit(1);
+};
+const spawn = (file, args, input) => spawnSync(file, args, { encoding: 'utf8', input, maxBuffer: 256 * 1024 * 1024 });
+// op <skill> <operation> <args> [stdin] — that skill's script for the operation: { status, stdout, stderr }.
+const op = (skill, operation, args = [], input) => spawn(process.execPath, [join(pkg, 'scripts', skill, `${operation}.mjs`), ...args], input);
+// must — the same, its stdout, or the stop naming the operation and its error.
+const must = (skill, operation, args, input) => {
+  const r = op(skill, operation, args, input);
+  if (r.status !== 0) stop(`scripts/${skill}/${operation}.mjs failed — ${(r.stderr || r.stdout).trim()}`);
+  return r.stdout;
+};
+const nul = (...paths) => paths.filter(Boolean).join('\0');
+const lines = (text) => text.split('\n').filter(Boolean);
+const section = (text, heading) => text.split(new RegExp(`^## ${heading}.*$`, 'm'))[1]?.split(/^## |^<!-- codelife:end/m)[0] ?? '';
+
+// Where you are: the CLI and its floor, the account, the merge request, the head and the tree.
+const [cli, version] = must('tracker', 'cli.version').trim().split(' ');
+const row = lines(readFileSync(join(pkg, 'scripts/target/target-base.md'), 'utf8'))
+  .find((l) => l.startsWith('| ') && l.split('|')[1].includes(`\`${cli}\``))?.split('|')[3] || '';
+const floor = row.match(new RegExp(`\`${cli}\` (\\S+)`))?.[1] || row.trim().split(' ')[0];
+const below = (have, want) => {
+  const [a, b] = [have, want].map((v) => v.split('.').map(Number));
+  for (let i = 0; i < 3; i++) if ((a[i] || 0) !== (b[i] || 0)) return (a[i] || 0) < (b[i] || 0);
+  return false;
+};
+const account = must('tracker', 'account').trim();
+if (n === undefined) {
+  const branch = spawn('git', ['branch', '--show-current']).stdout.trim();
+  const open = branch ? lines(must('tracker', 'mr.find_for_branch', [branch])).filter((l) => l.endsWith(' open')) : [];
+  if (open.length !== 1) stop(`no number given, and ${branch ? `${branch} has ${open.length} open merge requests` : 'HEAD is on no branch'} — \`/review-mr <n>\``);
+  n = open[0].split(' ')[0];
+  say(`number: !${n}, the open merge request of ${branch}`);
+}
+must('tracker', 'mr.fetch_head', [n]);
+const mr = JSON.parse(must('tracker', 'mr.view', [n]));
+say(`merge request: !${n} — head ${mr.sha}, target ${mr.target}, merge base ${mr.base}, author ${mr.author}, draft ${mr.draft ? 'yes' : 'no'}, state ${mr.state}`);
+if (mr.author === account) stop(`!${n} is ${account}'s own merge request — reviewed inside its unit, before it opened (work C-861); /review-mr reviews another person's`);
+say(`account: ${account} — a reviewer`);
+say(`forge CLI: ${cli} ${version}, floor ${floor || 'unread'}`);
+if (floor && floor !== 'none' && below(version, floor)) stop(`${cli} ${version} is below the floor ${floor} the review's posting needs`);
+const tree = JSON.parse(must('git', 'status'));
+if (tree.oid !== mr.sha) stop(`HEAD is ${tree.oid}, not the head ${mr.sha} — \`${must('tracker', 'mr.checkout_command', [n]).trim()}\` reaches it`);
+const dirty = [...tree.staged, ...tree.modified, ...tree.untracked];
+if (dirty.length) stop(`the tree is not clean: ${dirty.join(', ')}`);
+say('tree: at the head, clean');
+const run = mkdtempSync(join(tmpdir(), 'codelife-review-'));
+say(`run: ${run}`);
+writeFileSync(join(run, 'mr.json'), JSON.stringify(mr, null, 2));
+
+// The earlier pass, whoever ran it: its number and the sha it read, and the comments people wrote
+// after it, which this pass carries (C-865).
+const comments = must('tracker', 'mr.comments', [n]);
+writeFileSync(join(run, 'comments.md'), comments);
+const [, k, reviewed] = comments.match(/^- latest pass: (\d+) — (\S+) — /m) || [];
+say(k ? `review: pass ${+k + 1}, later, since pass ${k} at ${reviewed} — comments.md carries it and what people wrote since` : 'review: pass 1, first');
+
+// The diff, file by file in git's order, and the lines each changes: a finding outside them is not
+// the merge request's.
+const files = JSON.parse(must('git', 'diff', [mr.base, mr.sha]));
+let diff = '';
+const tsv = [];
+for (const f of files) {
+  const text = must('git', 'diff_lines', [mr.base, mr.sha], nul(f.old, f.path));
+  diff += text;
+  for (const [, a, b = '1', c, d = '1'] of text.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)) {
+    if (+d) tsv.push(`${f.path}\tnew\t${c}\t${+c + +d - 1}`);
+    if (+b) tsv.push(`${f.path}\told\t${a}\t${+a + +b - 1}`);
+  }
+}
+writeFileSync(join(run, 'diff.diff'), diff);
+writeFileSync(join(run, 'lines.tsv'), tsv.map((l) => `${l}\n`).join(''));
+say(`diff: ${files.length} files in diff.diff, their changed lines in lines.tsv`);
+// The submodules at the head: a file under one is another repository's, where no skill files (C-919).
+const subs = JSON.parse(must('git', 'submodules', [mr.sha]));
+if (subs.length) say(`submodules: ${subs.join(', ')} — a debt in a file under one is named, not filed (C-919)`);
+
+// *How to test*, from the description's tagged region, by shape: a bullet opening on a backticked
+// command is a command; a *manual* bullet with its indented lines is one step, a command inside it
+// one of its actions; any other bullet is not runnable as written.
+const region = mr.description.split('<!-- codelife:begin -->')[1]?.split('<!-- codelife:end -->')[0] ?? '';
+const how = /^## How to test/m.test(region) ? section(region, 'How to test') : null;
+const bullets = (how ?? '').split(/^(?=- )/m).filter((b) => b.startsWith('- '));
+const commands = bullets.map((b) => b.match(/^- `([^`]+)`/)?.[1]).filter(Boolean);
+const manual = bullets.filter((b) => /^- \*manual\*/.test(b));
+const prose = bullets.filter((b) => !/^- (`|\*manual\*)/.test(b)).map((b) => b.split('\n')[0].slice(2).trim());
+writeFileSync(join(run, 'commands.txt'), commands.map((c) => `${c}\n`).join(''));
+writeFileSync(join(run, 'manual.md'), manual.map((b) => b.trimEnd()).join('\n\n') + (manual.length ? '\n' : ''));
+say(how === null ? 'how to test: none in the description — `/mr` writes one'
+  : `how to test: ${commands.length} commands in commands.txt, ${manual.length} manual steps in manual.md${prose.length ? `; not runnable as written: ${prose.join(' | ')}` : ''}`);
+// The running application a manual step's browser reaches — the contract's `app` block, which the
+// session hands each reproduce agent with its step (reproduce.md R-143).
+if (manual.length && field('kind') === 'app') say(field('app.url') ? `app: ${field('app.url')}, started by \`${field('app.start') || 'no command in the contract'}\` — never started by the review` : 'app: no `app` block in the contract — a browser step cannot reach the application');
+
+// The known list: the open issues and the debt the description names — a defect one of them
+// already carries is not filed again.
+const open = lines(must('tracker', 'list'));
+const debt = lines(section(mr.description, 'Debt noticed')).filter((l) => /^- #\d+/.test(l));
+writeFileSync(join(run, 'known.txt'), [['## Open issues', open], ['## Debt noticed', debt.map((l) => l.slice(2))]]
+  .map(([h, l]) => [h, ...l].join('\n')).join('\n\n') + '\n');
+say(`known list: known.txt — ${open.length} open issues, debt noticed ${debt.map((l) => l.match(/#\d+/)[0]).join(', ') || 'none'}`);
+
+// The reader's case: the range, and what the merge request was meant to do — the issues its commits
+// close, their umbrella and the identifiers each cites, each checked to resolve; the description,
+// outside *How to test*, when it closes none (C-499).
+const words = JSON.parse(must('git', 'log_since', [mr.base])).flatMap((c) => c.closes), number = /^#?\d+$/;
+const closes = [...new Set(words.filter((w) => number.test(w)).map((w) => w.replace('#', '')))];
+const said = [], unresolved = [...new Set(words.filter((w) => !number.test(w)))].map((w) => `Closes: ${w}`);
+const umbrellas = new Set();
+// known <id> — where it is defined under docs/spec/, empty when nowhere; a scan that fails stops.
+const known = (id) => {
+  const r = spawn(process.execPath, [join(pkg, 'scripts/brainstorm/named.mjs'), id]);
+  if (r.status !== 0) stop(`scripts/brainstorm/named.mjs failed — ${(r.stderr || r.error?.message || '').trim()}`);
+  return r.stdout.trim();
+};
+for (const k of closes) {
+  const issue = JSON.parse(must('tracker', 'view', [k]));
+  const lot = issue.title.match(/\blot #(\d+)/)?.[1];
+  if (lot) umbrellas.add(lot);
+  const ids = [...new Set([...(issue.title.match(/\bspec:([A-Z]-\d+)/)?.slice(1) || []),
+    ...[...section(issue.body, 'Where it comes from').matchAll(/^(?:- )?([RC]-\d+) — /gm)].map((m) => m[1])])];
+  for (const id of ids) if (!known(id)) unresolved.push(`#${k} ${id}`);
+  said.push(`- #${k} — ${issue.title}${ids.length ? ` — cites ${ids.join(', ')}` : ' — cites nothing: its text is what was asked'}`);
+}
+const kase = [`Range: ${mr.base}...${mr.sha} — \`git diff ${mr.base}...${mr.sha}\` shows the change.`,
+  'Command line: codelife — on your PATH: run each `codelife <verb>` as written.', ''];
+if (closes.length) kase.push('The issues it closes — read each by section, its plan among them:', '', ...said,
+  ...(umbrellas.size ? ['', `The lot: ${[...umbrellas].map((u) => `#${u}`).join(', ')} — read its \`## Done when\`.`] : []));
+else kase.push(`!${n} closes no issue: its description, outside *How to test*, is what was asked.`, '',
+  (region || mr.description).replace(/^## How to test[\s\S]*?(?=^## |(?![\s\S]))/m, '').trim());
+writeFileSync(join(run, 'case.md'), `${kase.join('\n')}\n`);
+say(`case: case.md — ${closes.length ? closes.map((k) => `#${k}`).join(', ') : 'no issue closed — the description is what was asked'}${unresolved.length ? `; resolves to nothing: ${unresolved.join(', ')}` : ''}`);
+console.log(summary.join('\n'));