@ersbeth/codelife 0.0.0-bootstrap.0 → 0.11.1

package/scripts/verify/GOV.mjs

@@ -0,0 +1,34 @@
+// GOV's facts, read from origin: no merged branch left, every name in the model, the shipped
+// version tagged, a licence declared — and this clone's refs pruned. Whether the licence is a
+// decision is the hygiene subagent's.
+import { existsSync, readFileSync } from 'node:fs';
+import { fail, git, lines, remoteHeads } from './lib.mjs';
+import { field } from '../contract.mjs';
+
+const heads = remoteHeads();
+const model = /^(main|develop|(feature|fix|hotfix|lot|support)\/.+)$/;
+const develop = heads.get('develop');
+if (!develop) fail('origin has no develop branch');
+
+for (const [b, sha] of heads) {
+  if (!model.test(b)) fail(`${b}: a branch name outside the model`);
+  if (!develop || b === 'main' || b === 'develop') continue;
+  if (git('cat-file', '-e', `${sha}^{commit}`).status !== 0) fail(`${b}: not in this clone, ancestry unjudged`);
+  else if (git('merge-base', '--is-ancestor', sha, develop).status === 0)
+    fail(`${b} is merged into develop and still a head on origin`);
+}
+
+const file = field('release.version_file');
+if (file && file.endsWith('.json') && existsSync(file)) {
+  const m = JSON.parse(readFileSync(file, 'utf8'));
+  const tags = new Set(lines(git('ls-remote', '--tags', 'origin').out).map((l) => l.split('\t')[1].replace(/^refs\/tags\/|\^\{\}$/g, '')));
+  const v = m.version;
+  if (v && v !== '0.0.0' && ![`v${v}`, v, `${String(m.name).replace(/^@[^/]+\//, '')}--v${v}`].some((t) => tags.has(t)))
+    fail(`version ${v} of ${file} has no tag`);
+  if (!m.license) fail(`${file} declares no license`);
+}
+if (!['LICENSE', 'LICENSE.md', 'LICENSE.txt'].some(existsSync)) fail('no LICENSE file');
+
+for (const ref of lines(git('for-each-ref', '--format=%(refname:lstrip=3)', 'refs/remotes/origin').out))
+  if (ref !== 'HEAD' && !heads.has(ref)) fail(`${ref}: a local ref to a branch origin no longer has`);
+if (git('config', '--get', 'fetch.prune').out !== 'true') fail('fetch.prune is not set to true');

package/scripts/verify/GUARD.mjs

@@ -0,0 +1,34 @@
+// GUARD's facts: the hooks are wired and executable, the tiers exist and run something, and every
+// guard of the contract resolves. What a diff should have honoured is the hygiene subagent's.
+import { accessSync, constants, existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fail, git, guards, sh } from './lib.mjs';
+
+const hooks = git('config', '--get', 'core.hooksPath').out;
+if (!hooks) fail('core.hooksPath is not set');
+else if (!existsSync(hooks)) fail(`core.hooksPath names ${hooks}, which does not exist`);
+else
+  for (const h of readdirSync(hooks)) {
+    try {
+      accessSync(join(hooks, h), constants.X_OK);
+    } catch {
+      fail(`hook ${join(hooks, h)} is not executable`);
+    }
+  }
+
+const scripts = existsSync('package.json') ? JSON.parse(readFileSync('package.json', 'utf8')).scripts || {} : {};
+for (const tier of ['verify:commit', 'verify:push']) {
+  const s = scripts[tier];
+  if (!s) fail(`no ${tier} script`);
+  else if (s.split(/&&|;|\|\|/).every((part) => /^\s*echo\b/.test(part))) fail(`${tier} is hollow: ${s}`);
+}
+
+// The guards' `run` commands.
+const runs = guards().flatMap((g) => g.run ?? []);
+const found = (command) => {
+  const [bin, arg] = command.replace(/^['"]|['"]$/g, '').split(/\s+/);
+  if (['node', 'bash', 'sh'].includes(bin) && arg && /\.(m?js|cjs|sh)$/.test(arg)) return existsSync(arg);
+  if (bin.includes('/')) return existsSync(bin);
+  return sh('sh', ['-c', `command -v "$1"`, 'sh', bin], { env: { ...process.env, PATH: `node_modules/.bin:${process.env.PATH}` } }).status === 0;
+};
+for (const r of runs) if (!found(r)) fail(`guard command not found: ${r}`);

package/scripts/verify/LINES.mjs

@@ -0,0 +1,22 @@
+// LINES's facts, read from origin: every older line against main, both directions. A line diverged
+// one way only is abandoned in the other; one diverged neither way can be closed. What ports a fix
+// across is the hygiene subagent's.
+import { absent, fail, git, remoteHeads } from './lib.mjs';
+
+const heads = remoteHeads();
+const older = [...heads.keys()].filter((b) => b.startsWith('support/'));
+if (!older.length) absent('one release line — LINES has no subject');
+const main = heads.get('main');
+if (!main) fail('origin has no main');
+
+for (const b of main ? older : []) {
+  const head = heads.get(b);
+  if ([head, main].some((s) => git('cat-file', '-e', `${s}^{commit}`).status !== 0)) {
+    fail(`${b}: not in this clone, divergence unmeasured`);
+    continue;
+  }
+  const ahead = Number(git('rev-list', '--count', `${main}..${head}`).out);
+  const behind = Number(git('rev-list', '--count', `${head}..${main}`).out);
+  if (!ahead && !behind) fail(`${b} has not diverged from main: it can be closed`);
+  else if (!ahead || !behind) fail(`${b} has diverged in one direction only: ${ahead} ahead, ${behind} behind main`);
+}

package/scripts/verify/PKG.mjs

@@ -0,0 +1,56 @@
+// PKG's facts: every entry point is in the tree and in the tarball, nothing runs at install time,
+// and no tracked file carries a secret, by its name or in its contents.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { fail, manifest, sh, tracked } from './lib.mjs';
+
+const pkg = manifest();
+const clean = (p) => p.replace(/^\.\//, '');
+
+const entries = [];
+for (const k of ['main', 'module', 'types', 'typings', 'browser'])
+  if (typeof pkg[k] === 'string') entries.push([k, pkg[k]]);
+if (typeof pkg.bin === 'string') entries.push(['bin', pkg.bin]);
+else for (const [k, v] of Object.entries(pkg.bin || {})) entries.push([`bin > ${k}`, v]);
+const walk = (e, path) => {
+  if (typeof e === 'string') entries.push([path, e]);
+  else if (e && typeof e === 'object') for (const [k, v] of Object.entries(e)) walk(v, `${path} > ${k}`);
+};
+walk(pkg.exports, 'exports');
+
+const pack = sh('npm', ['pack', '--dry-run', '--json', '--ignore-scripts']);
+let packed = null;
+try {
+  packed = new Set(JSON.parse(pack.out)[0].files.map((f) => f.path));
+} catch {
+  fail(`npm pack --dry-run failed: ${pack.err.split('\n').pop()}`);
+}
+
+for (const [field, target] of entries) {
+  if (target.includes('*')) continue;
+  const p = clean(target);
+  if (!existsSync(p)) fail(`entry ${field} → ${p}: not in the tree`);
+  else if (packed && !packed.has(p)) fail(`entry ${field} → ${p}: not in the tarball`);
+}
+for (const k of ['preinstall', 'install', 'postinstall', 'prepare'])
+  if (pkg.scripts?.[k]) fail(`lifecycle script ${k} runs on the consumer's machine`);
+// A secret, by its name and by its shape in the contents of every tracked file at this commit —
+// never the history. Its value never leaves this script whole: four characters, then masked.
+const shapes = [
+  ['private key', /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----/],
+  ['GitLab token', /\bgl(?:pat|dt|rt|ptt)-[0-9A-Za-z_-]{20,}/],
+  ['GitHub token', /\b(?:gh[pousr]_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{22,})/],
+  ['npm token', /\bnpm_[A-Za-z0-9]{36}/],
+];
+for (const { path: f, kind } of tracked()) {
+  if (/(^|\/)(\.env(\..*)?|[^/]*\.(pem|key|p12)|id_rsa)$/i.test(f)) fail(`a tracked file named like a secret: ${f}`);
+  // A link's target is not the repository's: the cut reads none through a link, nor does this.
+  if (kind === 'link' || !existsSync(f) || !statSync(f).isFile()) continue;
+  const bytes = readFileSync(f);
+  if (bytes.subarray(0, 8000).includes(0)) continue;
+  bytes.toString('utf8').split('\n').forEach((line, i) => {
+    for (const [kind, shape] of shapes) {
+      const m = line.match(shape);
+      if (m) fail(`a credential in ${f}:${i + 1}: ${m[0].slice(0, 4)}… (${kind})`);
+    }
+  });
+}

package/scripts/verify/TYPE.mjs

@@ -0,0 +1,34 @@
+// TYPE's facts: a types entry exists, its condition comes first wherever it is declared, and the
+// declaration entries import nothing a consumer does not receive. Whether the surface matches the
+// documentation is the hygiene subagent's.
+import { builtinModules } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { fail, manifest } from './lib.mjs';
+
+const pkg = manifest();
+const declarations = new Set([pkg.types, pkg.typings].filter((t) => typeof t === 'string'));
+const walk = (e, path) => {
+  if (!e || typeof e !== 'object') return;
+  const keys = Object.keys(e);
+  const conditions = keys.filter((k) => !k.startsWith('.'));
+  if (conditions.includes('types')) {
+    if (conditions[0] !== 'types') fail(`types is not the first condition of ${path}: ${conditions.join(', ')}`);
+    if (typeof e.types === 'string') declarations.add(e.types);
+  }
+  for (const k of keys) walk(e[k], `${path} > ${k}`);
+};
+walk(pkg.exports, 'exports');
+if (!declarations.size) fail('no types entry');
+
+const received = new Set([...Object.keys(pkg.dependencies || {}), ...Object.keys(pkg.peerDependencies || {})]);
+const nameOf = (s) => (s.startsWith('@') ? s.split('/').slice(0, 2).join('/') : s.split('/')[0]);
+for (const d of declarations) {
+  const file = d.replace(/^\.\//, '');
+  if (d.includes('*') || !existsSync(file)) continue;
+  const text = readFileSync(file, 'utf8');
+  const specifiers = [...text.matchAll(/(?:\bfrom|\bimport)\s*\(?\s*['"]([^'"]+)['"]/g)].map((m) => m[1]);
+  for (const s of new Set(specifiers)) {
+    if (s.startsWith('.') || s.startsWith('node:') || builtinModules.includes(s)) continue;
+    if (!received.has(nameOf(s))) fail(`${file} imports ${nameOf(s)}, in neither dependencies nor peerDependencies`);
+  }
+}

package/scripts/verify/cut.mjs

@@ -0,0 +1,73 @@
+// The cut: what the lenses read, into parts one subagent reads whole, each written as a file into a
+// directory this script creates outside the tree. With no argument, the tracked text files in path
+// order — the contract's generated[] paths, the binary files, the submodules and the links in no
+// part — and beside the parts `tracked.txt`, every tracked file with its size, a submodule or a link
+// marked as one, which a lens searches rather than reads. The cut names the tracked links, which
+// no lens opens, each escaped in its note as `named` escapes it. A part closes
+// when the next file would overflow it, and a file larger than a part is a part of its own, so the
+// same tree gives the same parts.
+// `node cut.mjs`, from the repository root. It never exits 0 on a cut it could not
+// make: the parts are the plan the lenses are dispatched on, and report.mjs stops the run on it. A
+// tracked name holding a newline is such a cut: a part is one name per line, and the escaped form
+// names no file, so the tree's cut fails on it, the name escaped in its error to be renamed.
+import { accessSync, constants, lstatSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { generatedPaths, named, tracked } from './lib.mjs';
+
+// The size, here and nowhere else: what a lens subagent was measured to read whole, raised only by
+// a campaign's context peaks and its lenses' *Not reached:* lines.
+const TREE = 200000;
+
+// pack <items> <limit> — consecutive { name, bytes, text } items, a part closing when the next
+// would overflow it.
+const pack = (items, limit) => {
+  const parts = [];
+  let part;
+  for (const item of items) {
+    if (!part || (part.items.length && part.bytes + item.bytes > limit)) parts.push((part = { bytes: 0, items: [] }));
+    part.items.push(item);
+    part.bytes += item.bytes;
+  }
+  return parts;
+};
+
+const files = tracked(), links = files.filter((f) => f.kind === 'link').map((f) => f.path);
+const split = files.filter((f) => f.path.includes('\n')).map((f) => named(f.path));
+if (split.length) throw new Error(`a tracked name holds a newline, which no part can carry: ${split.join(', ')}`);
+const out = mkdtempSync(join(tmpdir(), 'codelife-parts-'));
+const notes = [], items = [];
+{
+  const generated = generatedPaths();
+  let binary = 0;
+  const left = [], submodules = [], sizes = [];
+  for (const { path: name, kind } of files.filter((f) => f.kind !== 'link')) {
+    if (kind !== 'submodule') sizes.push({ name, bytes: lstatSync(name).size });
+    if (kind === 'binary') binary++;
+    else if (kind === 'submodule') submodules.push(name);
+    else if (generated.some((g) => name === g || name.startsWith(`${g}/`))) left.push(name);
+    else {
+      accessSync(name, constants.R_OK);
+      items.push({ ...sizes.at(-1), text: `${name}\n` });
+    }
+  }
+  notes.push(`binary files in no part: ${binary}`, `generated paths in no part: ${left.join(', ') || 'none'}`,
+    `submodules in no part: ${submodules.join(', ') || 'none'}`);
+  writeFileSync(join(out, 'tracked.txt'), [...sizes.map((s) => `${s.bytes} ${s.name}`), ...submodules.map((s) => `submodule ${s}`),
+    ...links.map((l) => `link ${l}`)].map((line) => `${line}\n`).join(''));
+  const total = sizes.reduce((sum, s) => sum + s.bytes, 0);
+  const largest = [...sizes].sort((a, b) => b.bytes - a.bytes).slice(0, 10).map((s) => `${s.bytes} ${s.name}`);
+  notes.push(`tracked files in ${join(out, 'tracked.txt')}: ${sizes.length} files, ${total} bytes; largest: ${largest.join(', ') || 'none'}`);
+}
+notes.push(`links in no part: ${links.map(named).join(', ') || 'none'}`);
+
+const parts = pack(items, TREE);
+console.log(`parts in ${out}, at most ${TREE} bytes each`);
+parts.forEach((part, i) => {
+  const file = `part-${i + 1}.txt`;
+  writeFileSync(join(out, file), part.items.map((item) => item.text).join(''));
+  const n = part.items.length, first = part.items[0].name, last = part.items[n - 1].name;
+  console.log(`  ${file} — ${part.bytes} bytes, ${n} file${n > 1 ? 's' : ''}: ${first}${n > 1 ? ` … ${last}` : ''}`);
+});
+if (!parts.length) console.log('  none');
+for (const note of notes) console.log(note);

package/scripts/verify/history.mjs

@@ -0,0 +1,32 @@
+// The history the lenses read, each answer under the command that produced it: the files changed
+// most in six months, the latest fix commits, and when a document and anything else last changed.
+import { absent, git, lines, named, paths, tracked } from './lib.mjs';
+
+// log <git log's arguments> — its lines, or `absent` when there is no history to read.
+const log = (...args) => {
+  const r = git('log', ...args);
+  if (r.status !== 0) absent(`git log — ${r.err}`);
+  return lines(r.out);
+};
+// section <title> <the command, as a reader would type it> <its answer>
+const section = (title, shown, found) => {
+  console.log(`${title} — ${shown}`);
+  for (const line of found.length ? found : ['none']) console.log(`  ${line}`);
+};
+
+// Each path under its name at HEAD: the log runs newest first, so a rename is read before the
+// commits under its old name, and a path HEAD does not track is left out.
+const counts = new Map(), renamed = new Map(), head = new Set(tracked().map((f) => f.path));
+const changes = paths('log', '--since=6 months ago', '--name-status', '-M', '--format=');
+for (let i = 0; i < changes.length; i++) {
+  const status = changes[i], p = changes[++i], to = /^[RC]/.test(status) ? changes[++i] : p, name = renamed.get(to) ?? to;
+  if (status[0] === 'R') renamed.set(p, name);
+  counts.set(name, (counts.get(name) || 0) + 1);
+}
+section('files changed most in six months', "git log --since='6 months ago' --name-status -M --format=, each path under its name at HEAD",
+  [...counts].filter(([p]) => head.has(p)).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 20).map(([p, n]) => `${n} ${named(p)}`));
+section('fix commits, the 20 latest', "git log --format='%h %s', the subjects opening on fix",
+  log('--format=%h %s').filter((c) => /^\S+ fix/i.test(c)).slice(0, 20));
+section('last change to a document', "git log -1 --format=%ci -- '*.md'", log('-1', '--format=%ci', '--', '*.md'));
+section('last change to anything else', "git log -1 --format=%ci -- . ':(exclude)*.md'",
+  log('-1', '--format=%ci', '--', '.', ':(exclude)*.md'));

package/scripts/verify/lib.mjs

@@ -0,0 +1,129 @@
+// What the hygiene scripts share. Each runs from the repository's root, prints one line per failed
+// fact and exits 0, or calls `absent` and exits 3 — the protocol report.mjs reads.
+import '../node-floor.mjs';
+import { spawnSync } from 'node:child_process';
+import { closeSync, existsSync, mkdtempSync, openSync, readFileSync, rmSync } from 'node:fs';
+import { constants, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { entries } from '../contract.mjs';
+
+// sh <file> [args] [options] — its stdout and stderr trimmed (stdout as is with `trim: false`), and
+// its exit status, stdin closed; never throws.
+// A signal is 128 + its number, as a shell says it, never spawnSync's `null`, which every
+// `if (r.status)` would take for a success.
+export const sh = (file, args = [], { trim = true, ...options } = {}) => {
+  const r = spawnSync(file, args, { encoding: 'utf8', input: '', maxBuffer: 256 * 1024 * 1024, ...options });
+  const status = r.error ? 127 : r.signal ? 128 + (constants.signals[r.signal] ?? 0) : r.status;
+  return { status, out: trim ? (r.stdout || '').trim() : r.stdout || '', err: (r.stderr || r.error?.message || (r.signal ? `killed by ${r.signal}` : '')).trim() };
+};
+export const git = (...args) => sh('git', args);
+export const lines = (text) => text.split('\n').filter(Boolean);
+// paths <git args> — the paths git lists, read NUL-separated, or `absent` when git cannot list them:
+// without -z, git quotes a name holding a byte above 0x7F, a quote, a backslash or a control
+// character, and the quoted form names no file. Read as UTF-8: a name whose bytes are not valid
+// UTF-8 still names none.
+export const paths = (...args) => {
+  const r = git(args[0], '-z', ...args.slice(1));
+  if (r.status !== 0) absent(`git ${args[0]} — ${r.err}`);
+  return r.out.split('\0').filter(Boolean);
+};
+// named <path> — a path as a line of a block: a control character escaped as git escapes it, so a
+// name holding a newline cannot print a line of its own.
+export const named = (p) => p.replace(/[\0-\x1f\x7f]/g, (c) =>
+  ({ '\t': '\\t', '\n': '\\n' })[c] ?? `\\${c.charCodeAt(0).toString(8).padStart(3, '0')}`);
+
+// absent <reason> — the subject is not there: could not tell, never a pass.
+export const absent = (reason) => {
+  console.error(reason);
+  process.exit(3);
+};
+export const fail = (fact) => console.log(fact);
+
+// tracked — every tracked path with its kind, read from the index: `submodule`, `link`, `binary` or
+// `text`; `absent` when git cannot list them.
+export const tracked = () =>
+  paths('ls-files', '--eol', '-s').map((entry) => {
+    const i = entry.indexOf('\t'), j = entry.indexOf('\t', i + 1);
+    const mode = entry.slice(0, entry.indexOf(' ')), eol = entry.slice(i + 1, j);
+    const kind = { 160000: 'submodule', 120000: 'link' }[mode] || (eol.startsWith('i/-text') ? 'binary' : 'text');
+    return { path: entry.slice(j + 1), kind };
+  });
+
+// manifest — package.json parsed, or `absent` when there is none.
+export const manifest = () => {
+  if (!existsSync('package.json')) absent('no package.json — no subject for this lens');
+  return JSON.parse(readFileSync('package.json', 'utf8'));
+};
+
+// runner — the package manager's run prefix, from the lockfile, then from `packageManager`.
+export const runner = (pkg) => {
+  if (existsSync('pnpm-lock.yaml')) return ['pnpm', ['run']];
+  if (existsSync('yarn.lock')) return ['yarn', ['run']];
+  if (existsSync('package-lock.json')) return ['npm', ['run']];
+  const named = (pkg.packageManager || '').split('@')[0];
+  return [named || 'npm', ['run']];
+};
+
+// guards [key] — the contract's guards[] entries, or another list such as generated[], each value a
+// list (scripts/contract.mjs); generatedPaths — generated[]'s paths, a folder's without its slash.
+export const guards = (key = 'guards') => entries(key);
+export const generatedPaths = () => entries('generated').flatMap((g) => g.path).map((p) => p.replace(/\/$/, ''));
+
+// glob <pattern> — the pattern as a regular expression over a whole path: `**/` any number of
+// whole folders, `**` anything, `*` and `?` within one segment, `{a,b}` either.
+export const glob = (p) => new RegExp(`^${p.replace(/[.+^$()|[\]\\]/g, '\\$&').replace(/\{([^}]*)\}/g, (_, a) => `(${a.split(',').join('|')})`)
+  .replace(/\*\*\/?|\*|\?/g, (m) => ({ '**/': '(?:.*/)?', '**': '.*', '*': '[^/]*' })[m] ?? '[^/]')}$`);
+
+// The checks `codelife checks` and `codelife verify` run, one after the other, from the root.
+// tier <name> — the check running the `verify:<name>` script through the package manager, or the
+// one saying it is not ported. On Windows a package manager is a `.cmd`, which only a shell resolves.
+export const tier = (name) => {
+  const pkg = existsSync('package.json') ? JSON.parse(readFileSync('package.json', 'utf8')) : null;
+  if (!pkg?.scripts?.[`verify:${name}`]) return { name: `the ${name} tier`, missing: `no verify:${name} script — not ported` };
+  const [pm, run] = runner(pkg);
+  return { name: `the ${name} tier`, file: pm, args: [...run, `verify:${name}`], shell: process.platform === 'win32' };
+};
+// fired <entries> <paths> — the contract's entries whose `when` matches one of the paths.
+export const fired = (entries, touched) => entries.filter((g) => g.when.some((w) => touched.some((t) => glob(w).test(t))));
+// logged <name> <file> [args] [shell] — runs it with its whole output, stdout and stderr in the
+// order printed, in a file outside the tree named on stderr when it starts, so that a run a timeout
+// cuts leaves it readable: its status (`signal <name>` when killed), its output, and the file — none,
+// and the file removed, when the output is empty. The one runner of the verbs and the audit (R-282).
+let logs, count = 0;
+export const logged = (name, file, args = [], shell = false) => {
+  logs ??= mkdtempSync(join(tmpdir(), 'verify-'));
+  const log = join(logs, `${++count}.log`);
+  console.error(`running ${name}, output in ${log}`);
+  const fd = openSync(log, 'w');
+  const r = spawnSync(file, args, { shell, stdio: ['ignore', fd, fd] });
+  closeSync(fd);
+  const out = readFileSync(log, 'utf8');
+  if (!out.trim()) rmSync(log);
+  return { status: r.error ? r.error.code || r.error.message : r.signal ? `signal ${r.signal}` : r.status, out, file: out.trim() ? log : null };
+};
+// runChecks <checks> [lead] — one line each, `passed`, `failed` or, for a hygiene script whose subject
+// is absent, `could not tell`, anything but a pass followed by its last lines and a guard's `note`;
+// true when one failed.
+// `lead` opens each check's line: `- ` in a verb whose block is a list.
+export const runChecks = (checks, lead = '') => {
+  let red = false;
+  for (const c of checks) {
+    if (c.pass) { console.log(`${lead}passed: ${c.name}`); continue; }
+    const r = c.missing ? null : logged(c.name, c.file, c.args, c.shell);
+    const out = c.missing ?? r.out.trimEnd();
+    const outcome = r?.status !== 0 ? (c.hygiene ? 'could not tell' : 'failed') : c.hygiene && out ? 'failed' : 'passed';
+    if (outcome === 'passed') { console.log(`${lead}passed: ${c.name}`); continue; }
+    red ||= outcome === 'failed';
+    console.log(`${lead}${outcome}: ${c.name}${r && r.status !== 0 ? ` — exit ${r.status}` : ''}${r?.file ? `, output in ${r.file}` : ''}`);
+    for (const l of out.split('\n').slice(-20)) console.log(`  ${l}`);
+    if (c.note?.length) console.log(`  note: ${c.note.join(' ')}`);
+  }
+  return red;
+};
+
+// remoteHeads — origin's branches by name → sha, or `absent` when origin cannot be read.
+export const remoteHeads = () => {
+  const r = git('ls-remote', '--heads', 'origin');
+  if (r.status !== 0) absent(`origin unreachable — ${r.err || 'git ls-remote failed'}`);
+  return new Map(lines(r.out).map((l) => l.split('\t')).map(([sha, ref]) => [ref.replace('refs/heads/', ''), sha]));
+};

package/scripts/verify/report.mjs

@@ -0,0 +1,104 @@
+// verify's reporting operation: runs, one after the other and with no model, the hygiene script of
+// each lens named, with `--tree` the history every lens reads, with
+// `--timings` PERF's timings, each distinct command given after `--` once, and last, with `--tree`, the tree's cut,
+// and prints one `### verify result` block.
+// Nothing stops the run, and it exits 0 whatever it found — a failed fact is a candidate to write,
+// not a gate — but on a cut that failed, the plan the lenses are dispatched on.
+// `node <this directory>/report.mjs [--lenses A,B,…] [--tree] [--timings] [-- '<command>'…]`, from the repository root: one quoted argument per command, each run whole.
+//
+// How each run is read:
+//   hygiene script — exit 0 and silent: passed; exit 0 with lines: failed, one line per fact;
+//                    any other exit, a crash included: could not tell.
+//   tree fact, timing
+//                  — exit 0: passed, its output handed to its lens; otherwise could not tell.
+//   command        — exit 0: passed; otherwise failed. Run through lib.mjs's `logged`, as the verbs'
+//                    checks are; the block names its file, and under a failure carries the output's
+//                    last lines — or says the output is empty.
+//   cut            — exit 0: passed, its parts listed; otherwise failed, and the report exits 1.
+import '../node-floor.mjs';
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { logged } from './lib.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const argv = process.argv.slice(2);
+const cut = argv.indexOf('--');
+const options = cut < 0 ? argv : argv.slice(0, cut);
+const commands = cut < 0 ? [] : argv.slice(cut + 1);
+let lenses = [], tree = false, timings = false;
+for (let i = 0; i < options.length; i++) {
+  if (options[i] === '--lenses' && options[i + 1]) lenses = options[++i].split(',').filter(Boolean);
+  else if (options[i] === '--tree') tree = true;
+  else if (options[i] === '--timings') timings = true;
+  else {
+    console.error('usage: node report.mjs [--lenses A,B,…] [--tree] [--timings] [-- \'<command>\'…]');
+    process.exit(2);
+  }
+}
+// The scripts PERF's timings cover.
+const timed = ['test:all', 'verify:push'];
+
+const lines = ['### verify result'];
+const report = (label, outcome, output = '') => {
+  lines.push(`- ${label} — ${outcome}`);
+  if (output.trim()) lines.push(...output.trimEnd().split('\n').map((l) => `    ${l}`));
+};
+const run = (file, args) => {
+  const r = spawnSync(file, args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  const status = r.error ? r.error.code || r.error.message : r.signal ? `signal ${r.signal}` : r.status;
+  return { status, out: r.stdout || '', err: r.stderr || '' };
+};
+// probe <label> <file> <args> — exit 0: passed, its output handed on; otherwise could not tell.
+const probe = (label, file, args) => {
+  const r = run(file, args);
+  if (r.status === 0) report(label, 'passed', r.out);
+  else report(label, `could not tell: exit ${r.status}`, r.err || r.out);
+};
+
+for (const lens of lenses) {
+  const script = join(here, `${lens}.mjs`);
+  if (!existsSync(script)) {
+    lines.push(`- ${lens} — no script`);
+    continue;
+  }
+  const r = run(process.execPath, [script]);
+  const label = `${lens} · node ${script}`;
+  if (r.status !== 0) report(label, `could not tell: exit ${r.status}`, r.err || r.out);
+  else if (r.out.trim()) report(label, 'failed', r.out);
+  else report(label, 'passed');
+}
+
+for (const name of tree ? ['history'] : []) {
+  const script = join(here, `${name}.mjs`);
+  probe(`tree · node ${script}`, process.execPath, [script]);
+}
+for (const name of timings ? timed : []) {
+  const script = join(here, 'timing.mjs');
+  probe(`PERF · node ${script} ${name}`, process.execPath, [script, name]);
+}
+
+// The lines of a failed command's output the block carries: the end, where a runner prints its
+// summary and its failures' detail.
+const last = 40;
+for (const command of new Set(commands)) {
+  const r = logged(command, command, [], true);
+  const outcome = r.status === 0 ? 'passed' : `failed: exit ${r.status}`;
+  if (!r.file) report(command, `${outcome}, output empty`);
+  else report(command, `${outcome}, output in ${r.file}`, r.status === 0 ? '' : r.out.trimEnd().split('\n').slice(-last).join('\n'));
+}
+let status = 0;
+if (tree) {
+  const args = [join(here, 'cut.mjs')];
+  const r = run(process.execPath, args);
+  const label = `parts · node ${args.join(' ')}`;
+  if (r.status === 0) report(label, 'passed', r.out);
+  else {
+    report(label, `failed: exit ${r.status}`, r.err || r.out);
+    status = 1;
+  }
+}
+
+console.log(lines.join('\n'));
+process.exit(status);

package/scripts/verify/timing.mjs

@@ -0,0 +1,19 @@
+// One script's timing, for PERF: three runs through the repository's run prefix, the median and the
+// runs in seconds. A manifest without the script, or a run that fails, is a timing nobody took.
+// `node timing.mjs <script>`, from the repository root.
+import { absent, manifest, runner, sh } from './lib.mjs';
+
+const name = process.argv[2];
+const pkg = manifest();
+if (!pkg.scripts?.[name]) absent(`no ${name} script in package.json`);
+const [bin, args] = runner(pkg);
+const command = [bin, ...args, name].join(' ');
+const runs = [];
+for (let i = 0; i < 3; i++) {
+  const start = process.hrtime.bigint();
+  const r = sh(bin, [...args, name]);
+  if (r.status !== 0) absent(`${command} exits ${r.status} — ${(r.err || r.out).split('\n').slice(-5).join('\n')}`);
+  runs.push(Number(process.hrtime.bigint() - start) / 1e9);
+}
+const s = (seconds) => `${seconds.toFixed(2)} s`;
+console.log(`${command} — median ${s([...runs].sort((a, b) => a - b)[1])} (${runs.map(s).join(', ')})`);

package/scripts/verify.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// `codelife verify commit|push [<base>]` (R-199, C-857): an implementer's verification before each
+// commit, and the push tier before a lot's merge request — each `generated[]` entry of the contract
+// whose `when` matches a path of the working tree's change (with the diff from <base> to `HEAD` when
+// given), its path staged, then the `verify:<tier>` script and each matching `guards[]` entry. One
+// line per check, as `codelife checks` prints them. Exit 0 when none failed, 1 when one failed or the tier is not ported, 2 on a usage error.
+import './node-floor.mjs'
+import { fired, git, guards, runChecks, tier } from './verify/lib.mjs'
+
+const [name, base] = process.argv.slice(2)
+if (!['commit', 'push'].includes(name) || (base && git('rev-parse', '--verify', '--quiet', `${base}^{commit}`).status !== 0)) {
+  console.error(`usage: codelife verify commit|push [<base>]${base ? ` — '${base}' is no commit git can resolve` : ''}`)
+  process.exit(2)
+}
+
+const names = (...args) => git(...args).out.split('\0').filter(Boolean)
+const touched = () => [...names('diff', '--name-only', '-z', 'HEAD'), ...names('ls-files', '--others', '--exclude-standard', '-z'),
+  ...(base ? names('diff', '--name-only', '-z', `${base}...HEAD`) : [])]
+const shell = (cs, note) => (cs ?? []).map((c) => ({ name: c, file: c, shell: true, note }))
+// The outputs first, each staged before the tier and the guards run (R-125): a check that fails then
+// leaves them staged, and a tier that checks an output is fresh reads it regenerated.
+const outputs = fired(guards('generated'), touched())
+if (runChecks(outputs.flatMap((g) => shell(g.command)))) process.exit(1)
+for (const p of outputs.flatMap((g) => g.path ?? [])) {
+  const r = git('add', '-A', '--', p)
+  console.log(r.status ? `failed: staging ${p} — ${r.err}` : `staged: ${p}`)
+  if (r.status) process.exit(1)
+}
+if (runChecks([tier(name), ...fired(guards(), touched()).flatMap((g) => shell(g.run, g.note))])) process.exit(1)