@ersbeth/codelife 0.0.0-stage → 0.11.1

package/scripts/audit/prepare.mjs

@@ -0,0 +1,180 @@
+// `codelife audit prep [full | targeted <LENS>…] [--red]` (C-869): everything a campaign does
+// before any agent, from the repository's root. The tree clean but for a campaign under way and a
+// domain lens the close commit carries; the
+// campaign — the one under way, resumed at the commit its index records, or the next number the
+// campaign table gives; the lenses — every applicable one for `full`, the named ones for
+// `targeted`, a retired id or one with no reference refused; the known list — the open issues and
+// what docs/spec/ decided; the fingerprint, before anything runs; then verify's report at HEAD — the
+// push tier, the hygiene scripts, the history, PERF's timings, the cut —, a red tier stopping
+// unless `--red` audits it; then the campaign folder and its index, and outside the tree a folder
+// for the judge of every part whose `NN/` holds no `part.md`, each with a folder per lens holding
+// only what that lens reads. Prints one `### audit prep` summary; a `- stop:` line exits 1.
+import '../node-floor.mjs';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { decided } from '../brainstorm/lib.mjs';
+import { tier as tierOf } from '../verify/lib.mjs';
+import { field } from '../contract.mjs';
+import { cadence } from './cadence.mjs';
+import { env } from '../tracker/lib.mjs';
+import { shown, state } from '../port/lib.mjs';
+import { HYGIENE, KIND, RETIRED, domainIds, fingerprint, idOf, inProgress, lensIds, lines, parts, pkg, read, reference, row, sh } from './lib.mjs';
+
+const summary = ['### audit prep'];
+const say = (line) => summary.push(`- ${line}`);
+const done = (code) => { console.log(summary.join('\n')); process.exit(code); };
+const stop = (why) => { say(`stop: ${why}`); done(1); };
+const argv = process.argv.slice(2);
+const red = argv.includes('--red');
+const [mode = 'full', ...named] = argv.filter((a) => a !== '--red');
+if (!['full', 'targeted'].includes(mode) || (mode === 'full') !== !named.length) {
+  console.error('usage: codelife audit prep [full | targeted <LENS>…] [--red]');
+  process.exit(2);
+}
+
+// The tree: an audit measures a commit, and its scripts write into this tree.
+const dirty = lines(sh('git', ['status', '--porcelain', '--untracked-files=all']).stdout).map((l) => l.slice(3))
+  .filter((p) => !/^"?docs\/audit\/(A\d+-|lenses\/)/.test(p));
+if (dirty.length) stop(`the tree is not clean — ${dirty.slice(0, 10).join(', ')}${dirty.length > 10 ? ', …' : ''}: commit or restore it first`);
+const head = sh('git', ['rev-parse', 'HEAD']).stdout.trim();
+const branch = sh('git', ['branch', '--show-current']).stdout.trim() || 'detached HEAD';
+const kind = field('kind') ?? 'none';
+const tracker = field('tracker.kind') ?? 'none';
+
+// The campaign: the one under way, or the next number. Resumed, it keeps its lenses and its commit.
+let folder = inProgress(), lenses;
+const date = new Date().toISOString().slice(0, 10);
+if (folder) {
+  const index = read(join(folder, '00-index.md'));
+  const at = /`([0-9a-f]{7,40})`/.exec(row(index, 'Commit') ?? '')?.[1];
+  if (at && !head.startsWith(at)) stop(`the campaign in ${folder} is at ${at}, HEAD is ${head}: check ${at} out to resume it, or delete the folder to abandon it`);
+  lenses = (row(index, 'Lenses run') ?? '').split(/, */).filter(Boolean);
+  const judged = parts(folder).filter((nn) => existsSync(join(folder, nn, 'part.md'))).length;
+  say(`campaign: ${folder}/ — resumed, ${judged} parts judged${named.length ? `; its own lenses kept, not ${named.join(' ')}` : ''}`);
+} else {
+  const all = lensIds(), domain = domainIds();
+  if (mode === 'full') lenses = [...all.filter((l) => !Object.values(KIND).flat().includes(l)), ...KIND[kind] ?? [], ...domain];
+  else {
+    for (const id of named) {
+      if (RETIRED[id]) stop(`${id} is retired: its question is ${RETIRED[id]}'s now`);
+      if (!reference(id)) stop(`${id} has no reference: write docs/audit/lenses/${id}.md from the plugin's skills/audit/templates/lens.md, then run again`);
+    }
+    lenses = named;
+  }
+  const n = Math.max(0, ...cadence().rows.map((r) => Number(r[0].match(/^A(\d+)/)[1]))) + 1;
+  folder = `docs/audit/A${n}-${date}-${mode === 'full' ? 'full' : `targeted-${named.join('-')}`}`;
+  say(`campaign: ${folder}/ — new`);
+}
+lenses = [...new Set(lenses)];
+const hygiene = lenses.filter((l) => HYGIENE.includes(l)), hunting = lenses.filter((l) => !HYGIENE.includes(l));
+say(`lenses: ${hunting.join(', ') || 'none'}${hygiene.length ? ` · hygiene, one agent: ${hygiene.join(', ')}` : ''}`);
+say(`commit: ${head} on ${branch}`);
+
+// The known list: the open issues, one line each, and every rule and refusal of docs/spec/.
+const run = mkdtempSync(join(tmpdir(), 'codelife-audit-'));
+let open = [], listed = tracker === 'none';
+if (listed) open = existsSync('issues') ? (await import('../tracker/none.mjs')).lines() : [];
+else {
+  const r = sh(process.execPath, [join(pkg, 'scripts/tracker/list.mjs')]);
+  listed = r.status === 0;
+  if (listed) open = lines(r.stdout); else say(`tracker: not connected — no open issue swept, nothing can be filed (${(r.stderr || r.stdout).trim().split('\n')[0]})`);
+}
+const decisions = existsSync('docs/spec') ? decided(['docs/spec']) : [];
+const known = join(run, 'known.txt');
+writeFileSync(known, `## Open issues\n${open.join('\n')}\n\n## Decisions\n${decisions.join('\n')}\n`);
+say(`sweep: ${open.length} open issues, ${decisions.length} decisions — ${known}`);
+// CONF's measure, the port's own (K-20 — The target, R-19): CONF files only an item it reads to do.
+const measure = join(run, 'measure.txt');
+if (lenses.includes('CONF')) writeFileSync(measure, shown(state({ forge: tracker, connected: listed })).map(([k, v]) => `- ${k}: ${v}\n`).join(''));
+let visibility = 'unknown';
+if (tracker === 'glab' || tracker === 'gh') {
+  const v = sh(tracker, tracker === 'glab' ? ['repo', 'view', '-F', 'json'] : ['repo', 'view', '--json', 'visibility'], { env: env() });
+  visibility = /"visibility":\s*"(\w+)"/i.exec(v.stdout)?.[1]?.toLowerCase() ?? 'unknown';
+}
+say(`visibility: ${visibility}${visibility === 'private' ? '' : ' — an exploitable reproduction is withheld'}`);
+
+// The fingerprint, before anything runs: the push tier is where a script once wrote into the tree.
+const print = existsSync(join(folder, 'fingerprint.tsv')) ? null : fingerprint();
+
+// verify's report at HEAD: the push tier, the hygiene scripts, the history, the timings, the cut.
+const push = tierOf('push');
+if (push.missing) stop(`${push.missing}: /setup ports the tiers`);
+const tier = [push.file, ...push.args].join(' ');
+const scripts = hygiene.filter((l) => existsSync(join(pkg, 'scripts/verify', `${l}.mjs`)));
+const r = sh(process.execPath, [join(pkg, 'scripts/verify/report.mjs'), ...(scripts.length ? ['--lenses', scripts.join(',')] : []), '--tree',
+  ...(lenses.includes('PERF') ? ['--timings'] : []), '--', tier]);
+const block = r.stdout;
+const tierLine = block.split('\n').find((l) => l.startsWith(`- ${tier} — `)) ?? '';
+const suite = /output in (\S+)/.exec(tierLine)?.[1] ?? null;
+if (r.status !== 0) { console.log(block || r.stderr); stop('the cut failed: its block is above'); }
+if (!/ — passed/.test(tierLine) && !red) stop(`the push tier is red, ${tierLine.replace(/^- /, '')} — fix it first, or run again with --red to audit the failure`);
+say(`baseline: ${tierLine.replace(/^- /, '')}`);
+const report = join(run, 'report.md');
+writeFileSync(report, block);
+const cut = block.split('\n').slice(block.split('\n').findIndex((l) => l.startsWith('- parts · ')) + 1).map((l) => l.slice(4));
+const dir = /^parts in (.+), at most \d+ bytes each$/m.exec(cut.join('\n'))[1];
+const count = readdirSync(dir).filter((f) => /^part-\d+\.txt$/.test(f)).length;
+const binary = /^binary files in no part: (\d+)/m.exec(cut.join('\n'))?.[1] ?? '0';
+say(`facts: verify's block in ${report}`);
+say(`parts: ${count}, ${binary} binary files in no part — ${dir}`);
+
+// The campaign folder and its index, once: a resumed campaign keeps both.
+if (print) {
+  mkdirSync(folder, { recursive: true });
+  writeFileSync(join(folder, 'fingerprint.tsv'), print.map((l) => `${l}\n`).join(''));
+  const sha = sh('git', ['-C', pkg, 'rev-parse', '--short', 'HEAD']);
+  let version = '';
+  try { version = JSON.parse(readFileSync(join(pkg, 'package.json'), 'utf8')).version; } catch { /* none */ }
+  const last = cadence().last;
+  const fill = { id: idOf(`/${folder}`), type: mode === 'full' ? 'full' : `targeted (${named.join(', ')})`, date, commit: head.slice(0, 7), branch,
+    lenses: lenses.join(', '), baseline: `\`${tier}\` — ${/ — passed/.test(tierLine) ? 'green' : 'red, audited as a finding'} on ${date}`,
+    instrument: `codelife ${version}${sha.status === 0 ? ` at \`${sha.stdout.trim()}\`` : ''}, loaded from \`${pkg.replace(/\/$/, '')}\``,
+    previous: last ? last[0] : 'none — this is the first', open: open.length, decisions: decisions.length,
+    measure: `${count} parts × ${lenses.length} lenses, ${binary} binary files in no part; never read: {{unread}}` };
+  const template = readFileSync(join(pkg, 'skills/audit/templates/index.md'), 'utf8');
+  writeFileSync(join(folder, '00-index.md'), template.replace(/\{\{(\w+)\}\}/g, (m, k) => (k in fill ? String(fill[k]) : m)));
+}
+
+// A folder per judge, outside the tree: every part whose NN/ holds no part.md, emptied for it.
+const root = `root: ${process.cwd()}`;
+const id = idOf(`/${folder}`);
+const text = (l) => l.map((x) => `${x}\n`).join('');
+const judges = [];
+let places = 0;
+for (let p = 1; p <= count; p++) {
+  const nn = String(p).padStart(2, '0'), out = resolve(folder, nn);
+  if (existsSync(join(out, 'part.md'))) continue;
+  rmSync(out, { recursive: true, force: true });
+  mkdirSync(out, { recursive: true });
+  const j = mkdtempSync(join(run, `judge-${nn}.`));
+  for (const [f, to] of [[known, 'known.txt'], [report, 'report.md']]) copyFileSync(f, join(j, to));
+  writeFileSync(join(j, 'arguments.txt'), text([root, `campaign: ${id}`, `sha: ${head}`, `part: ${nn}`, `visibility: ${visibility}`, `write: ${out}`]));
+  const lens = (ids) => {
+    const d = mkdtempSync(join(j, `${ids.join('-')}.`));
+    const files = [[join(dir, `part-${p}.txt`), 'part.txt'], [join(dir, 'tracked.txt'), 'tracked.txt'], [known, 'known.txt'], [report, 'report.md'],
+      ...ids.map((l) => [reference(l), `lens-${l}.md`]),
+      ...(ids.includes('VERIF') && suite ? [[suite, 'suite.txt']] : []),
+      ...(ids.includes('CONF') ? [[join(pkg, 'scripts/target/target-base.md'), 'target-base.md'],
+        [join(pkg, `scripts/target/target-${kind}.md`), `target-${kind}.md`], [measure, 'measure.txt']] : [])].filter(([f]) => f && existsSync(f));
+    for (const [f, to] of files) copyFileSync(f, join(d, to));
+    writeFileSync(join(d, 'arguments.txt'), text([root, `sha: ${head}`, `lenses: ${ids.join(', ')}`, `files: ${files.map(([, to]) => to).join(', ')}`]));
+    return [ids.join(','), d];
+  };
+  const rows = [...(p === 1 && hygiene.length ? [lens(hygiene)] : []), ...hunting.map((l) => lens([l]))];
+  writeFileSync(join(j, 'lenses.tsv'), text(rows.map((x) => x.join('\t'))));
+  places = Math.max(places, 1 + rows.length);
+  judges.push([nn, j]);
+}
+writeFileSync(join(run, 'judges.tsv'), text(judges.map((x) => x.join('\t'))));
+say(`judges: ${judges.length} of ${count} parts to judge${judges.length ? ` — ${judges.map(([nn]) => nn).join(', ')} · ${places} places a judge` : ''} — ${join(run, 'judges.tsv')}`);
+
+// Claude Code's cap on concurrent subagents: a judge holds itself and each lens it dispatches.
+if (judges.length) {
+  const setting = 'CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS', raw = process.env[setting];
+  const cap = /^[1-9]\d*$/.test(raw ?? '') ? Number(raw) : 20;
+  const atOnce = Math.floor(cap / places);
+  if (!atOnce) stop(`a judge holds ${places} places, more than the cap ${cap} — raise ${setting}`);
+  say(`cap: ${cap} (${raw ? `${setting}=${raw}` : `${setting} unset`}) · ${atOnce} judges at once · ${Math.ceil(judges.length / atOnce)} round${Math.ceil(judges.length / atOnce) > 1 ? 's' : ''} · raised by ${setting}`);
+}
+done(0);

package/scripts/audit/table.mjs

@@ -0,0 +1,65 @@
+// `codelife audit table <LENS>[,<LENS>…]` (K-33, R-110): the table one lens's findings are confirmed
+// on — or the hygiene lenses' together —, from the campaign under way, from the repository's root.
+// First every part must be judged and accounted for: a part without its part.md, or whose judge
+// received a candidate id no line of the part names again (#825), stops it. Then one row per
+// finding across the parts — its id, title, severity, effort and state: its disposition when one is
+// written, `filed #n` when an issue already carries its id, `known #n`, or `new`, and a title two
+// rows share flagged —, then below the rows each point the table would hide: what its judges watched,
+// read as a deliberate choice or refuted, and the decisions they found contested. Writes nothing.
+import '../node-floor.mjs';
+import { existsSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { findings, inProgress, partFile, parts, pkg, sh, unaccounted } from './lib.mjs';
+
+const [arg] = process.argv.slice(2);
+if (!arg || !/^[A-Z][A-Z0-9]+(,[A-Z][A-Z0-9]+)*$/.test(arg)) {
+  console.error('usage: codelife audit table <LENS>[,<LENS>…]');
+  process.exit(2);
+}
+const lenses = arg.split(',');
+const out = [`### audit table — ${lenses.join(', ')}`];
+const stop = (why) => { out.push(`- stop: ${why}`); console.log(out.join('\n')); process.exit(1); };
+const folder = inProgress() ?? stop('no campaign in progress: `codelife audit prep` opens one');
+
+const waiting = parts(folder).filter((nn) => !existsSync(join(folder, nn, 'part.md')));
+if (waiting.length) stop(`parts not judged: ${waiting.join(', ')} — run \`codelife audit prep\` again, which dispatches them alone`);
+for (const nn of parts(folder)) {
+  const lost = unaccounted(folder, nn);
+  if (lost.length) stop(`part ${nn}'s judge left ${lost.join(', ')} unaccounted — delete ${join(folder, nn, 'part.md')} and run \`codelife audit prep\` again`);
+}
+
+// Already filed: an issue whose title's tag holds the finding's id, open or closed.
+const tmp = mkdtempSync(join(tmpdir(), 'codelife-table-'));
+let connected = true;
+const filed = (id) => {
+  if (!connected) return null;
+  writeFileSync(join(tmp, 'key'), `audit:${id}`);
+  const r = sh(process.execPath, [join(pkg, 'scripts/tracker/search_id.mjs'), join(tmp, 'key'), '--all']);
+  if (r.status !== 0) { connected = false; return null; }
+  return /^#(\d+)/.exec(r.stdout)?.[1] ?? null;
+};
+const rows = findings(folder, lenses);
+const titles = new Map();
+out.push('| Id | Title | Severity | Effort | State |', '|---|---|---|---|---|');
+for (const f of rows) {
+  const n = f.disposition ? null : filed(f.id);
+  const twin = titles.get(f.title.toLowerCase());
+  titles.set(f.title.toLowerCase(), titles.get(f.title.toLowerCase()) ?? f.id);
+  const state = f.disposition ?? (n ? `filed #${n}` : f.known ? `known #${f.known}` : 'new');
+  out.push(`| ${f.id} | ${f.title}${twin ? ` — same title as ${twin}` : ''} | ${f.severity}${f.unverified ? ' UNVERIFIED' : ''} | ${f.effort} | ${state} |`);
+}
+if (!rows.length) out.push('| none | | | | |');
+if (!connected) out.push('- tracker: not reached — no row looked up');
+
+// Below the rows: one line per point a judge kept out of the table, by part.
+const below = [], contested = [];
+for (const nn of parts(folder)) {
+  const { sections } = partFile(folder, nn);
+  for (const l of [...new Set(lenses.flatMap((x) => sections[x] ?? []))]) {
+    if (/^\*Contested\b/.test(l)) contested.push(`- part ${nn}: ${l}`);
+    else if (/^\*(To watch|Deliberate choice|False)\b/.test(l)) below.push(`- part ${nn}: ${l}`);
+  }
+}
+out.push('Below the rows:', ...(below.length ? below : ['- none']), 'Contested:', ...(contested.length ? contested : ['- none']));
+console.log(out.join('\n'));

package/scripts/brainstorm/decided.mjs

@@ -0,0 +1,6 @@
+// What is decided: one `file:line: text` per rule in force (`### R-<n> — …`) and per refusal (a line
+// of a `## Rejected`) under the directories given: `node decided.mjs docs/spec`.
+import { decided } from './lib.mjs';
+
+const out = decided(process.argv.slice(2));
+if (out.length) console.log(out.join('\n'));

package/scripts/brainstorm/lib.mjs

@@ -0,0 +1,33 @@
+// What the readers of what is decided share — each reads Markdown and prints `file:line: text`
+// lines. From the repository's root.
+import '../node-floor.mjs';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+
+// The `.md` files under each path, sorted, spelled as `find` spells them: the path given, then the entry.
+const files = (path) => (statSync(path).isDirectory()
+  ? readdirSync(path).flatMap((e) => files(`${path.replace(/\/+$/, '')}/${e}`))
+  : path.endsWith('.md') ? [path] : []);
+export const markdown = (paths) => paths.flatMap(files).sort();
+
+// Every line of every file for which keep(line, section) holds, as `file:line: text`; the section is
+// the last `## ` heading read in that file.
+export const scan = (paths, keep) => {
+  const out = [];
+  for (const file of markdown(paths)) {
+    let section = '';
+    readFileSync(file, 'utf8').split('\n').forEach((line, i) => {
+      if (line.startsWith('## ')) section = line;
+      if (keep(line, section)) out.push(`${file}:${i + 1}: ${line}`);
+    });
+  }
+  return out;
+};
+
+// decided <paths> — what is decided: one `file:line: text` per rule in force (`### R-<n> — …`) and per
+// refusal (a line of a `## Rejected`).
+export const decided = (paths) => scan(paths, (line, section) =>
+  /^### R-[0-9]+ — /.test(line) || (section === '## Rejected' && line.startsWith('- ')));
+
+// unfinished <paths> — what the notes still pending say they are about: one `file:line: text` per
+// note's title and per **Open** item.
+export const unfinished = (paths) => scan(paths, (line) => /^# /.test(line) || line.includes('**Open —**'));

package/scripts/brainstorm/named.mjs

@@ -0,0 +1,9 @@
+// The heading each identifier opens, anywhere under docs/spec/: `node named.mjs <id>…`, one
+// `file:line: text` per identifier; nothing for one that resolves to nothing, which the caller names.
+import { scan } from './lib.mjs';
+
+const out = process.argv.slice(2).flatMap((id) => scan(['docs/spec'], (line) => {
+  const [hashes, name, dash] = line.split(/[ \t]+/);
+  return /^#+$/.test(hashes) && name === id && dash === '—';
+}));
+if (out.length) console.log(out.join('\n'));

package/scripts/changelog.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Writes CHANGELOG.md: the released part rendered by git-cliff above the marker, everything already
+// below it kept untouched: `node scripts/changelog.mjs [--check] [root]`. The contract names this
+// script as the generated[] command for that file, so it is the single authority: /release runs
+// it, and the guard that compares the tracked file to its generator runs it with `--check`.
+//
+// git-cliff alone does NOT produce this file: it renders an `## [Unreleased]` section for every
+// commit past the newest tag, which the tracked file never carries and which is stale at the very
+// next commit. Dropping that section is what `kept` below does. `--latest` is not the same thing
+// and must not be substituted: with two tags it renders only the newest section, so a comparison
+// against it passes on a file that lost every older release.
+//
+// With `--check` it writes the rebuilt file to stdout and leaves CHANGELOG.md alone, so a guard can
+// compare without mutating a tracked file — an audit campaign runs in place and may not.
+import './node-floor.mjs'
+import { execFileSync, spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { compare, spellings, tagFor } from './tags.mjs'
+import { field } from './contract.mjs'
+import { lf } from './text.mjs'
+
+const args = process.argv.slice(2)
+const check = args[0] === '--check'
+if (check) args.shift()
+const root = args[0] ?? '.'
+const f = `${root}/CHANGELOG.md`
+const marker = '<!-- codelife: generated above, history below -->'
+
+const stop = (...lines) => { console.error(lines.join('\n')); process.exit(1) }
+const fail = (what, ...more) => stop(`changelog.mjs: ${what}`, ...more.map((l) => `              ${l}`))
+const read = (p) => { try { return lf(readFileSync(p, 'utf8')) } catch { return null } }
+
+// The marker line, found once for this refusal and the cut below, says where the generated part
+// stops. Without it there is no safe splice, so this refuses rather than guess and truncate the file.
+const all = read(f)?.split('\n') ?? []
+const at = all.findIndex((l) => l.trimEnd() === marker)
+if (at < 0) fail(`no marker in ${f} — refusing to guess where the generated part ends`, `add this line above the hand-written part: ${marker}`)
+
+// git-cliff does NOT fail when its configuration is missing: it prints a warning, exits 0, and
+// renders its own generic template — including the `## [Unreleased]` heading this file forbids.
+// So the configuration is never looked up in the repository: it is the one this package ships,
+// passed with `--config`, and a package without it refuses rather than render with the defaults.
+const pkg = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const config = join(pkg, 'scripts/target/templates/cliff.toml')
+if (!existsSync(config)) fail(`no ${config} — refusing to render with git-cliff's defaults`, 'the package is incomplete; reinstall it')
+
+// The version the contract's release.version_file names, when no tag names it yet, is the release
+// being cut: /release bumps the file, then writes the section with this script, so the section and
+// the guard comparing the file against it come out of one command. git-cliff takes it as `--tag`,
+// in the spelling the release will give it, scripts/tags.mjs's. `0.0.0` is nothing released,
+// as the GOV lens reads it, not a pending 0.0.0; no version read at all is a refusal, never nothing
+// pending, which would drop the release's section with the comparison agreeing.
+const vf = field('release.version_file', root) ?? ''
+// A key of the version file, read at its top level: the first match at any depth can be a nested one.
+const json = (key) => { try { return String(JSON.parse(readFileSync(`${root}/${vf}`, 'utf8'))[key] ?? '') } catch { return '' } }
+const version = vf ? json('version') : ''
+if (!version) fail(`no version read from release.version_file ('${vf}') in ${root}/.claude/codelife.md`)
+let pending = []
+if (version !== '0.0.0') {
+  // Released already when a tag of scripts/tags.mjs's spellings names it.
+  let tagged = ''
+  try { tagged = execFileSync('git', ['-C', root, 'tag', '-l', ...spellings(version, json('name'))], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }) } catch { /* not a repository: nothing is tagged */ }
+  if (!tagged.trim()) pending = ['--tag', tagFor(version)]
+}
+
+// git-cliff is the package's pinned dependency, never whatever is on PATH: the version the config
+// was measured on is the one in this package's manifest. Resolved from this script, so it is found
+// where the package manager put it beside the package, and run by node: no `.bin` link is assumed.
+let cliff
+try { cliff = fileURLToPath(import.meta.resolve('git-cliff/cli')) } catch { fail('git-cliff is not resolvable from the package — it is a pinned dependency; install the dependencies') }
+
+const r = spawnSync(process.execPath, [cliff, '--config', config, ...pending], { cwd: root, encoding: 'utf8', maxBuffer: 1 << 28 })
+if (r.status !== 0) fail(`git-cliff exited ${r.status ?? r.error?.message}; ${f} was not touched`, ...r.stderr.split('\n').filter(Boolean))
+const out = r.stdout.replace(/\n+$/, '')
+
+// Only the versions newer than the newest one the history below the marker carries are rendered.
+// git-cliff renders every tag, and a converted changelog keeps its hand-written releases as
+// history: without this, each of them appeared twice, and an old tag the history never had came
+// out above newer releases. The generated part starts where the history ends.
+const history = all.slice(at).join('\n').replace(/\n+$/, '')
+const seen = history.split('\n').filter((l) => l.startsWith('## ')).map((l) => /[0-9]+\.[0-9]+\.[0-9]+[0-9A-Za-z.+-]*/.exec(l)?.[0]).filter(Boolean)
+const newest = seen.sort(compare).pop()
+const heading = (l) => l.startsWith('## [') ? l.split(/\s+/)[1].replace(/[[\]]/g, '') : undefined
+let skip = false
+const kept = out.split('\n').filter((l) => {
+  const v = heading(l)
+  if (v !== undefined) skip = v === 'Unreleased' || (newest !== undefined && /^\d/.test(v) && compare(v, newest) <= 0)
+  return !skip
+})
+const text = kept.map((l) => `${l}\n`).join('') + `${history}\n`
+
+if (check) process.stdout.write(text)
+else {
+  // Written beside the file and renamed over it, never written in place: a failure there would
+  // leave the tracked file truncated, and a failed write must leave it as it was.
+  const tmp = `${f}.${process.pid}.tmp`
+  try { writeFileSync(tmp, text); renameSync(tmp, f) } catch { rmSync(tmp, { force: true }); fail(`could not write the rebuilt file; ${f} was not touched`) }
+}

package/scripts/check-tag.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// The publication job's one check: `node scripts/check-tag.mjs <tag> [<npm version>]`. The tag is
+// `v` and the package's version, read from the package.json beside `scripts/`, and the npm that
+// publishes is 11.5.1 or later, the first to publish with a trusted publisher. A refusal prints
+// why and exits 1, so the job goes red before anything is published. Built-in modules only.
+import './node-floor.mjs'
+import { readFileSync } from 'node:fs'
+
+const [tag = '', npm] = process.argv.slice(2)
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+const refuse = (why) => { console.error(`check-tag: ${why}`); process.exit(1) }
+
+if (!/^v\d+\.\d+\.\d+$/.test(tag)) refuse(`tag '${tag}' is not of the form vX.Y.Z`)
+if (tag !== `v${version}`) refuse(`tag '${tag}' does not name package.json's version ${version}`)
+if (npm !== undefined) {
+  const [a, b, c] = npm.split('.').map(Number)
+  if (!(a > 11 || (a === 11 && (b > 5 || (b === 5 && c >= 1))))) refuse(`npm ${npm} is older than 11.5.1`)
+}
+console.log(`check-tag: ${tag} names package.json's version${npm ? `, npm ${npm}` : ''}`)

package/scripts/checks.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// `codelife checks <base> [<commands file>]` (review-mr R-291, C-853): the deterministic checks a
+// review runs before any agent starts — the push tier, then each `guards[]` entry of the contract
+// whose `when` matches a path the diff from <base> to `HEAD` touches, then the hygiene scripts that
+// only read, then each `generated[]` output whose `when` the diff matches, failed when the diff
+// leaves it untouched, then each line of the commands file once, the push tier's own command
+// skipped — one after the other, from the repository's root. Prints one line per check, `passed`, `failed` or,
+// for a hygiene script whose subject is absent, `could not tell`, anything but a pass followed by
+// the last lines of its output and a guard's `note`, and nothing else. Exit 0 when no check failed, 1 when one failed or
+// could not run,
+// 2 on a base git cannot resolve or diff against `HEAD` — no merge base, a shallow clone — since an
+// empty diff would skip every guard and pass.
+import './node-floor.mjs'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { fired, git, guards, runChecks, tier } from './verify/lib.mjs'
+import { field } from './contract.mjs'
+
+const [base = '', file] = process.argv.slice(2)
+if (!base || git('rev-parse', '--verify', '--quiet', `${base}^{commit}`).status !== 0) {
+  console.error(`usage: codelife checks <base> — '${base}' is no commit git can resolve`)
+  process.exit(2)
+}
+
+const diff = git('diff', '--name-only', '-z', `${base}...HEAD`)
+if (diff.status !== 0) {
+  console.error(`codelife checks: no diff from ${base} to HEAD — ${diff.err}`)
+  process.exit(2)
+}
+const touched = diff.out.split('\0').filter(Boolean)
+
+const checks = [tier('push')]
+for (const g of fired(guards(), touched)) for (const c of g.run) checks.push({ name: c, file: c, shell: true, note: g.note })
+// The hygiene scripts that only read, of the lenses the contract's `kind` applies — DEPS and GUARD
+// for every kind, TYPE for a library (scripts/audit/lib.mjs); BUILD rebuilds and PKG
+// packs, the audit's, and GOV and LINES read no diff. One fails by printing its facts, exit 0; any
+// other exit is `could not tell` — its subject absent, exit 3 — never a pass and never red.
+const kind = field('kind')
+for (const lens of ['DEPS', 'GUARD', ...(kind === 'lib' ? ['TYPE'] : [])])
+  checks.push({ name: lens, file: process.execPath, args: [fileURLToPath(new URL(`./verify/${lens}.mjs`, import.meta.url))], hygiene: true })
+
+// An output is stale when the diff touches its sources and not it: read, never regenerated.
+for (const g of fired(guards('generated'), touched)) {
+  const path = (g.path?.[0] ?? '').replace(/\/$/, '')
+  const hit = touched.some((t) => t === path || t.startsWith(`${path}/`))
+  checks.push(hit ? { name: `generated ${path}`, pass: true } : { name: `generated ${path}`, missing: 'the diff changes its sources and leaves it untouched' })
+}
+// *How to test*'s commands, as the preparation wrote them: the push tier ran above.
+const push = /^\S+( run)? verify:push$/
+for (const c of new Set(file ? readFileSync(file, 'utf8').split('\n').map((l) => l.trim()).filter((l) => l && !push.test(l)) : []))
+  checks.push({ name: c, file: c, shell: true })
+
+process.exit(runChecks(checks) ? 1 : 0)

package/scripts/codelife.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// The `codelife` command line (K-43): `codelife <verb> [arguments]` runs the verb's script with the
+// arguments that follow its name, where it is called, and exits with that script's status;
+// `codelife help` lists the verbs and `codelife help <verb>` prints one's manual; `codelife help
+// method|template [<name>]` lists the shared methods or the templates, or prints one. The verbs
+// are scripts/verbs.mjs's. An unknown verb, method or template exits 2, naming it.
+import './node-floor.mjs'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { method, methods, template, templates, verb, VERBS } from './verbs.mjs'
+
+const args = process.argv.slice(2)
+const SHELVES = { method: [methods, method], template: [templates, template] }
+const unknown = (words, what = 'verb', lister = 'help') => {
+  console.error(`codelife: no ${what} '${words.join(' ')}' — \`codelife ${lister}\` lists them`)
+  process.exit(2)
+}
+
+if (!args.length || args[0] === 'help') {
+  const asked = args.slice(1)
+  if (!asked.length) {
+    const width = Math.max(...Object.keys(VERBS).map((n) => n.length))
+    for (const [n, v] of Object.entries(VERBS)) console.log(`${n.padEnd(width)}  ${v.summary}`)
+  } else if (asked[0] in SHELVES) {
+    const [names, one] = SHELVES[asked[0]]
+    if (asked.length === 1) console.log(names().join('\n'))
+    else if (asked.length > 2 || !one(asked[1])) unknown(asked.slice(1), asked[0], `help ${asked[0]}`)
+    else process.stdout.write(one(asked[1]))
+  } else {
+    const found = verb(asked)
+    if (!found || found[1].length) unknown(asked)
+    console.log(VERBS[found[0]].manual)
+  }
+  process.exit(0)
+}
+
+const found = verb(args)
+if (!found) unknown(args)
+const [name, rest] = found
+const { script, lead = [] } = VERBS[name]
+const r = spawnSync(process.execPath, [fileURLToPath(new URL(`../${script}`, import.meta.url)), ...lead, ...rest], { stdio: 'inherit' })
+process.exit(r.status ?? 1)

package/scripts/commit-msg.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// Refuses a commit message that is not a Conventional Commit, because CHANGELOG.md is generated
+// from these messages and a message that does not parse is a change that never reaches the
+// changelog. Run by the commit-msg hook: `node scripts/commit-msg.mjs <message file>`.
+import './node-floor.mjs'
+import { readFileSync } from 'node:fs'
+
+let text
+try { text = readFileSync(process.argv[2], 'utf8') } catch { process.exit(0) }
+
+// The subject is the first line that is neither blank nor a comment.
+const subject = text.split('\n').find((l) => !l.startsWith('#') && l.trim() !== '')
+
+// Nothing to check: git will refuse an empty message on its own. Git's own machinery goes through.
+if (subject === undefined || /^(Merge |Revert |fixup! |squash! |amend! )/.test(subject)) process.exit(0)
+
+const types = ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert']
+
+// The subject line is read in a list of commits, in a changelog and in a blame: 72 characters is
+// what a terminal and a forge show without truncating. Counted as code points, whatever the shell
+// and the locale — the shell version counted bytes under dash and passed on a Mac what Linux
+// refused (#53).
+const n = [...subject].length
+if (n > 72) {
+  console.error(`\n  The subject line is ${n} characters; 72 is the limit:\n\n    ${subject}\n\n  Move what does not fit into the body, which is where the why belongs.\n`)
+  process.exit(1)
+}
+
+// type(optional scope)optional !: space, then a subject opening on a character that is not a space (#1060).
+if (new RegExp(`^(${types.join('|')})(\\([a-z0-9._/-]+\\))?!?: \\S`).test(subject)) process.exit(0)
+
+console.error(`
+  This commit message is not a Conventional Commit:
+
+    ${subject}
+
+  Expected  <type>(<optional scope>): <subject>
+  Types     ${types.join(' ')}
+  Breaking  put a ! before the colon — feat(api)!: drop the legacy entry point
+
+  The body says why. Cite the issue in the footer: Refs: #123
+`)
+process.exit(1)