@ersbeth/codelife 0.0.0-stage → 0.11.1

package/scripts/port/prep.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// `codelife port prep` (K-2 — port-toolchain, R-158, R-166): everything /port-toolchain states before
+// it proposes — the kind and the ported package, each toolchain item's state with its reasons and its
+// `port:` issue, the toolchain's summary line, and the first item to propose. Reads only; one
+// `### port prep` block; a `- stop:` line per thing that stops the run, and exit 1.
+import '../node-floor.mjs'
+import { check, contract } from '../contract.mjs'
+import { auth, git, items as base, origin, say } from '../setup/lib.mjs'
+import { dir, shown, state } from './lib.mjs'
+
+if (process.argv.length > 2) { console.error('usage: codelife port prep'); process.exit(2) }
+console.log('### port prep')
+const stop = (why) => { say('stop', why); process.exit(1) }
+if (git('rev-parse', '--show-toplevel').status !== 0) stop('not a git repository')
+const c = contract()
+if (!c) stop('no contract — run /setup first')
+const { invalid } = check(c)
+if (invalid.length) stop(`the contract is invalid — ${invalid.join('; ')}: /setup`)
+const kind = c.data.kind
+if (kind === 'none') stop('kind: none — there is no toolchain to port')
+const forge = c.data.tracker?.kind ?? 'none'
+const o = origin()
+const connected = forge === 'none' || Boolean(o && auth(forge, o.host).connected)
+if (!connected) stop(`this machine is not connected to ${o?.host ?? 'its host'} — /setup connects it`)
+const missing = base({ forge, connected }).filter((i) => ['scripts', 'hooks'].includes(i.item) && i.state === 'to do')
+if (missing.length) stop(`the base is not in place — ${missing.map((i) => `${i.item}: ${i.why.join('; ')}`).join(' · ')}: /setup`)
+const dirty = git('status', '--porcelain').stdout.trim()
+if (dirty) stop(`the tree is not clean — an item's commit holds that item's changes alone: commit or stash yours first\n${dirty}`)
+
+say('kind', `${kind} — the package ${dir() === '.' ? 'at the root' : dir()}`)
+const s = state({ forge, connected })
+for (const [k, v] of shown(s)) say(k, v)
+say('next', s.next ?? 'none — no item to do has its precondition done')

package/scripts/port/version.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// `codelife port version <tool>` (K-2 — port-toolchain, R-162): the version a tool moves to. Past the
+// repository's minimumReleaseAge always; vite-plus itself, its newest release past it; a tool
+// vite-plus carries, the exact version that release pins; any other, the newest release past it that
+// every peerDependencies range of pnpm-lock.yaml admits. A move across a major is a `- ask:` line,
+// with the newest release inside the current major; a newer release the window still holds is a
+// `- held:` line. Reads only, from the registry and the lockfile; exit 1 when the registry cannot answer.
+import '../node-floor.mjs'
+import { say } from '../setup/lib.mjs'
+import { admitted, at, carried, deps, installed, peers, releases, vitePlus, window } from './lib.mjs'
+import { readFileSync } from 'node:fs'
+
+const [tool] = process.argv.slice(2)
+if (!tool || process.argv.length > 3) { console.error('usage: codelife port version <tool>'); process.exit(2) }
+console.log('### port version')
+const fail = (why) => { say('stop', `the registry did not answer — ${why}`); process.exit(1) }
+const date = (v, list) => list.find((r) => r.v === v)?.date ?? 'date unknown'
+const major = (v) => v?.split('.')[0]
+let pj = null
+try { pj = JSON.parse(readFileSync(at('package.json'), 'utf8')) } catch { /* none */ }
+const current = installed(tool) ?? deps(pj)[tool]?.replace(/^[\^~=v]+/, '') ?? null
+say('current', current ? `${tool} ${current}` : `${tool} is not a dependency yet`)
+say('window', `${window()} minutes — minimumReleaseAge`)
+
+const r = releases(tool)
+if (r.error) fail(r.error)
+let chosen, why
+if (tool === 'vite-plus' || carried(tool)) {
+  const vp = vitePlus()
+  if (vp.error) fail(vp.error)
+  chosen = tool === 'vite-plus' ? vp.v : vp.pins[tool]
+  if (!chosen) { say('stop', `vite-plus ${vp.v} pins no ${tool} — it is not a tool the toolchain carries`); process.exit(1) }
+  why = tool === 'vite-plus' ? 'the newest past the window' : `pinned exactly by vite-plus ${vp.v} (${vp.date}), the newest past the window — not the registry's newest`
+} else {
+  const ranges = peers(tool)
+  for (const [p, range] of ranges) say('range', `${p} ${range}`)
+  const a = admitted(tool, ranges)
+  if (a.error) fail(a.error)
+  chosen = r.past.find((x) => !a.set || a.set.has(x.v))?.v
+  if (!chosen) { say('stop', `no release past the window is admitted by every range above`); process.exit(1) }
+  why = ranges.length ? 'the newest past the window that every peer range admits' : 'the newest past the window — no peer range in the lockfile'
+}
+say('version', `${tool} ${chosen} (${date(chosen, r.all)}) — ${why}`)
+if (current === chosen) say('move', 'none — already on it')
+if (current && major(chosen) !== major(current)) {
+  const inside = r.past.find((x) => major(x.v) === major(current))
+  say('ask', `${chosen} crosses a major from ${current} — put it to the user; the newest inside ${major(current)}.x past the window is ${inside ? `${inside.v} (${inside.date})` : 'none'}`)
+}
+const young = r.all.find((x) => !r.past.includes(x))
+if (young && r.all.indexOf(young) < r.all.findIndex((x) => x.v === chosen)) say('held', `${young.v} (${young.date}) is inside the window — only if the work needs it, put to the user beside ${chosen}`)

package/scripts/pre-commit.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// Holds what is fast and what the push tier does not, run by the pre-commit hook from the
+// repository's root: the specification's form for every kind, and for a library the outputs its
+// contract declares. It runs no verification tier — `codelife verify commit` is the commit tier's one
+// run, and a hand commit is held by pre-push, whose tier contains the commit tier, before it reaches
+// the remote.
+import './node-floor.mjs'
+import { execFileSync, spawnSync } from 'node:child_process'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { entries, field } from './contract.mjs'
+import { fileURLToPath } from 'node:url'
+
+const run = (cmd, opts = {}) => {
+  const r = spawnSync(cmd[0], cmd.slice(1), { stdio: 'inherit', shell: process.platform === 'win32', ...opts })
+  if (r.status !== 0) return r.status ?? 1
+}
+
+// An edit to docs/spec/ is held here, read from the index — what this commit carries, not what the
+// working tree holds beside it (#1085): docs/spec/ exported to a folder of its own, the form script
+// run there. Once the seven entries exist, what breaks the form is refused; before that the script
+// says the specification is not in the form. The script is the package's own, run by `node` alone.
+const index = mkdtempSync(join(tmpdir(), 'codelife-index-'))
+const staged = execFileSync('git', ['ls-files', '-z', '--', 'docs/spec'], { encoding: 'utf8' })
+if (staged) execFileSync('git', ['checkout-index', '-z', '--stdin', `--prefix=${index}/`], { input: staged })
+const form = run(['node', fileURLToPath(new URL('./spec-form.mjs', import.meta.url)), 'spec'], { cwd: index })
+rmSync(index, { recursive: true, force: true })
+if (form) process.exit(form)
+
+if (field('kind') === 'lib') {
+  // A library versions its build, and the commit tier does not build it — pack is a push-tier cost —
+  // so this runs each generated[] entry the contract declares with a `when` and stages its path with
+  // the commit: the former bundler's command until item d of the port names vp pack, nothing where
+  // nothing is declared. Unconditionally, not behind a "did src/ change" test: the build is the
+  // authority on whether its output moved. `-A` so that a file the build stopped producing is staged
+  // as the deletion it is. Built from the WORKING TREE, so when the index and the tree differ the
+  // commit can carry output its own source does not.
+  for (const g of entries('generated').filter((e) => e.when.length)) {
+    for (const c of g.command) { const s = run([c], { shell: true }); if (s) process.exit(s) }
+    if (g.path.length) execFileSync('git', ['add', '-A', '--', ...g.path], { stdio: 'inherit' })
+  }
+}

package/scripts/pre-push.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// Runs the complete verification tier before a push, so that a red tip never reaches the remote:
+// the repository's `verify:push`, run through the package manager it names. When what is pushed is
+// a version tag it runs `verify:release` instead, which contains it, so a tag pushed by hand,
+// outside `/release`, is held by the same proof of the package as one `/release` cuts;
+// `--no-verify` passes over it, the limit every hook already accepts.
+// This is the tier /audit uses as its baseline, so what passes here is what the audit assumes
+// about the commit it reads.
+//
+// This hook runs INSIDE a connection git has already opened: the refs on stdin exist only because
+// git contacted the remote and read them first, and that socket is then held idle for as long as
+// the tier takes. A remote that drops idle connections fails the push of a tip this tier just
+// passed. There is no hook before the connection, so the answer is not here but in the clone's
+// `core.sshCommand` keepalive, which the port imposes beside `core.hooksPath` — without it, a long
+// tier and a proxied remote break a green push.
+//
+// In the WORKING TREE, where the dependencies are installed. A tier run anywhere else meets a pnpm
+// workspace without its per-package node_modules, which are gitignored, and pnpm's pre-run check
+// installs them there — through any link back into the clone, rewriting the clone's own
+// node_modules, or refusing the push when it cannot. What that costs: the tree is measured instead
+// of the tip the remote will hold, so uncommitted work can turn the tier green on a red tip, or
+// refuse a push whose commits are all fine.
+import './node-floor.mjs'
+import { execFileSync, spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { packageManager, script } from './package-manager.mjs'
+
+// One line per ref git is about to send: <local ref> <local sha> <remote ref> <remote sha>. A
+// deletion carries the null sha as its local one: nothing arrives at the remote, so a push of
+// deletions alone has nothing to verify. A hand run has no stdin and verifies nothing.
+let refs = ''
+try { refs = readFileSync(0, 'utf8') } catch { /* no stdin */ }
+if (!refs.split('\n').some((l) => /[^0]/.test(l.split(/\s+/)[1] ?? ''))) process.exit(0)
+
+const git = (...a) => execFileSync('git', a, { encoding: 'utf8' }).trim()
+const top = git('rev-parse', '--show-toplevel')
+// Git hands a hook its repository-local variables — the git directory of a linked worktree. Left
+// set, every `git` the tier runs in a repository of its own reads and writes this one. Cleared
+// after the lookup above, which still needs them.
+const env = { ...process.env }
+for (const k of git('rev-parse', '--local-env-vars').split('\n')) delete env[k]
+
+const pm = packageManager(top)
+if (!pm) {
+  console.error('\n  Neither packageManager nor a lockfile names the package manager, so the push tier cannot run and the push is refused.\n')
+  process.exit(1)
+}
+// A version tag: the remote ref, what will exist there — `HEAD:refs/tags/v1.0.0` too (#1058) — under
+// refs/tags/ with a name of `v` and a digit, pushed rather than deleted.
+const versionTag = refs.split('\n').some((l) => { const [, sha, remote] = l.split(/\s+/); return /^refs\/tags\/v\d/.test(remote ?? '') && /[^0]/.test(sha ?? '') })
+const [cmd, ...args] = script(pm, versionTag ? 'verify:release' : 'verify:push')
+const r = spawnSync(cmd, args, { cwd: top, env, stdio: 'inherit', shell: process.platform === 'win32' })
+process.exit(r.status ?? 1)

package/scripts/prepare-lib.mjs

@@ -0,0 +1,81 @@
+// What the preparations share (R-288) — /work's preparation and the branch script it
+// both run: the summary a run is made from, the stop that ends it before any table, and the reads of the
+// scripts under scripts/tracker/, scripts/git/ and scripts/read-roadmap/ — and the one umbrella close the `issue close`
+// and `lot leave` verbs share. Nothing here reads stdin.
+import './node-floor.mjs';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { valid } from './contract.mjs';
+
+const scripts = dirname(fileURLToPath(import.meta.url));
+const spawn = (file, args, input = '') => spawnSync(file, args, { encoding: 'utf8', input, maxBuffer: 256 * 1024 * 1024 });
+
+export const said = (r) => (r.stdout + r.stderr).trim() || r.error?.message || '';
+export const first = (body) => body.split('\n')[0];
+// The first line a comment says below its heading: a STATUS's reason, a closing's verdict.
+export const gist = (body) => body.split('\n').slice(1).find((l) => l.trim())?.trim();
+
+// prep(heading) — { say, stop, done, include, op, must, title, kind }: the summary under `### <heading>`.
+export const prep = (heading) => {
+  const summary = [`### ${heading}`];
+  const say = (line) => summary.push(`- ${line}`);
+  const stop = (why) => {
+    say(`stop: ${why}`);
+    console.log(summary.join('\n'));
+    process.exit(1);
+  };
+  const done = () => {
+    console.log(summary.join('\n'));
+    process.exit(0);
+  };
+  // op <domain> <operation> <args> [stdin] — scripts/<domain>/<operation>.mjs: { status, stdout, stderr }.
+  const op = (skill, operation, args = [], input) => spawn(process.execPath, [join(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 — ${said(r)}`);
+    return r.stdout;
+  };
+  // include — another script's summary lines, kept; its stop is this run's.
+  const include = (r) => {
+    for (const l of r.stdout.split('\n').filter((l) => l.startsWith('- '))) summary.push(l);
+    if (r.status !== 0) {
+      if (!r.stdout.includes('- stop: ')) say(`stop: ${said(r)}`);
+      console.log(summary.join('\n'));
+      process.exit(1);
+    }
+  };
+  // title <script> <text> [args…] — a title script of scripts/tracker/, the text on its stdin.
+  const title = (script, text, ...args) => spawn(process.execPath, [join(scripts, 'tracker', script), ...args], text).stdout.trim();
+  // kind — the contract's `tracker.kind`, `none` when it names no forge.
+  const kind = () => { const v = valid(); return v.stop ? stop(v.stop) : v.contract.data.tracker?.kind || 'none'; };
+  // slug — a title's sentence as a branch name's words, cut at a word within 40 characters.
+  const slug = (text) => {
+    const s = title('title.sentence_of.mjs', text).toLowerCase().replace(/['’]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+    return s.length > 40 ? s.slice(0, s.lastIndexOf('-', 40)) : s;
+  };
+  return { summary, say, stop, done, include, op, must, title, kind, slug };
+};
+
+// tasks — an umbrella's task list in order: { n, effort }.
+export const tasks = (body) => [...body.matchAll(/^- \[[ xX]\] #(\d+)(?: \(([A-Za-z]+)\))?/gm)].map((m) => ({ n: m[1], effort: m[2] ?? '' }));
+
+// currentBranch — the branch checked out, '' on none.
+export const currentBranch = () => spawn('git', ['branch', '--show-current']).stdout.trim();
+
+// closeLot(must, lot, state, rows, by, branch) — the umbrella closed on its `lot-closing` comment
+// (R-193, R-70), the tracker's close line: the rows as the members closed, and — only when a branch is
+// given and a row is left — the branch and the merge request to come; `wontfix` when no row is left. A
+// leave runs on whatever branch, so it gives none and the comment says neither. An umbrella already
+// closed — the merge closed its members first, or an earlier caller did — gets nothing (#1042).
+export const closeLot = (must, lot, state, rows, by, branch) => {
+  if (/^closed$/i.test(state)) return `#${lot} already closed, no lot-closing comment`;
+  const file = join(mkdtempSync(join(tmpdir(), 'lot-closing-')), 'lot-closing.md');
+  writeFileSync(file, [`codelife: lot-closing — ${by} — ${new Date().toISOString().slice(0, 10)}`, '',
+    ...(branch ? [`Branch: \`${branch}\`.`] : []), `Members closed: ${rows.map((n) => `#${n}`).join(', ') || 'none'}.`,
+    ...(rows.length && branch ? [`Merge request: not yet opened — \`/work ${lot}\` opens it from the branch once every member's commit is there.`] : []), ''].join('\n'));
+  return must('tracker', 'close', [lot, file, ...(rows.length ? [] : ['wontfix'])]).trim();
+};

package/scripts/read-roadmap/lib.mjs

@@ -0,0 +1,116 @@
+// The one reading of the roadmap (K-41's R-277), which `codelife roadmap prep|write`, `codelife
+// work prep` and `codelife overview` import: a line of its `## The order`, the lots that can start,
+// an umbrella's count, the roadmap and its mark, and what a range of the specification changed.
+import '../node-floor.mjs';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// `3. #412 Undo of a stroke — after #405, #408` → { lot: '412', after: ['405', '408'] }; null for a
+// line out of shape, an `after` in another form included — never read as waiting for nothing.
+export const orderLine = (line) => {
+  if (!/^[0-9]+\. #[0-9]+ [^ ]/.test(line)) return null;
+  const lot = line.split(/[ \t]+/)[1].slice(1);
+  const i = line.indexOf(' — after ');
+  if (i < 0) return /after #/i.test(line) ? null : { lot, after: [] };
+  const after = line.slice(i + ' — after '.length);
+  if (!/^#[0-9]+(, #[0-9]+)*$/.test(after)) return null;
+  return { lot, after: after.replaceAll('#', '').split(', ') };
+};
+
+// canStart(order, open) — the open lots that can start, in the order's order: every lot each waits
+// for is closed. `order` is orderLine's objects, `open` the open umbrellas' numbers as strings.
+export const canStart = (order, open) =>
+  order.filter((o) => open.includes(o.lot) && !o.after.some((l) => open.includes(l))).map((o) => o.lot);
+
+// lotCount(body) — an umbrella's rows: { open, total, effort }, the effort of its open rows as
+// `2S 1M`, or `effort none` when no open row carries one.
+export const lotCount = (body) => {
+  const rows = [...body.matchAll(/^- \[([ xX])\] #(\d+)(?: \(([SML])\))?/gm)];
+  const open = rows.filter((m) => m[1] === ' ');
+  const effort = ['S', 'M', 'L'].map((e) => `${open.filter((m) => m[3] === e).length}${e}`).filter((x) => !x.startsWith('0')).join(' ');
+  return { open: open.length, total: rows.length, effort: effort || 'effort none' };
+};
+
+// What moved and what a range changed, from the scripts under scripts/tracker/ and scripts/git/. `op` runs one of
+// them, `must` the same but throws its error, which a script prints as the operation's answer.
+const pkg = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const op = (skill, operation, args = [], input = '') =>
+  spawnSync(process.execPath, [join(pkg, 'scripts', skill, `${operation}.mjs`), ...args], { encoding: 'utf8', input, maxBuffer: 256 * 1024 * 1024 });
+const said = (r) => (r.stdout + r.stderr).trim() || r.error?.message || '';
+const must = (skill, operation, args, input) => {
+  const r = op(skill, operation, args, input);
+  if (r.status !== 0) throw new Error(`scripts/${skill}/${operation}.mjs failed — ${said(r)}`);
+  return r.stdout;
+};
+const lines = (text) => text.split('\n').filter(Boolean);
+const section = (text, heading) => text.split(new RegExp(`^## ${heading}[ \\t]*$`, 'm'))[1]?.split(/^## /m)[0] ?? '';
+
+// roadmap() — { roadmap, mark }: `#<n>`, `none`, `two: #a, #b` or `could not tell: <why>`, and the
+// mark `<sha>, contained|not contained`, `out of shape: <text>`, `unresolved: <git>` or `none`, with
+// `sha` when git resolves it. A lookup that fails could not tell, and is never `none` (R-279).
+export const roadmap = () => {
+  const dir = mkdtempSync(join(tmpdir(), 'read-roadmap-')), key = join(dir, 'key');
+  writeFileSync(key, 'roadmap');
+  const r = op('tracker', 'search_id', [key]);
+  rmSync(dir, { recursive: true, force: true });
+  if (r.status !== 0) return { roadmap: `could not tell: ${said(r)}`, mark: 'none' };
+  const found = lines(r.stdout).map((l) => l.match(/^#?(\d+)/)?.[1]).filter(Boolean);
+  if (!found.length) return { roadmap: 'none', mark: 'none' };
+  if (found.length > 1) return { roadmap: `two: ${found.map((n) => `#${n}`).join(', ')}`, mark: 'none' };
+  const body = JSON.parse(must('tracker', 'view', [found[0]])).body;
+  const text = lines(section(body, 'Mark'))[0] ?? '';
+  const sha = text.match(/^`([0-9a-f]{7,64})`/)?.[1];
+  if (!sha) return { roadmap: `#${found[0]}`, mark: `out of shape: ${text}` };
+  const at = op('git', 'is_ancestor', [sha, 'HEAD']);
+  if (at.status !== 0) return { roadmap: `#${found[0]}`, mark: `unresolved: ${said(at)}` };
+  return { roadmap: `#${found[0]}`, mark: `${sha}, ${at.stdout.trim()}`, sha };
+};
+
+// range(mark, head) — what the specification changed between two commits, read as one change, final
+// state only: { changed, created, retired, other } — each `{ id, file, section }`, `other` without
+// an id — or { unresolved } when either commit does not resolve, since a diff from a commit git
+// cannot read comes back empty, and empty is not *nothing changed*. A line added belongs to the rule
+// or the case whose heading stands above it at `head`, a line removed to the one it stood under at
+// `mark`; a heading reworded is the same rule, changed, and one no heading at `head` carries any
+// more is retired.
+export const range = (mark, head) => {
+  const anc = op('git', 'is_ancestor', [mark, head]);
+  if (anc.status !== 0) return { unresolved: said(anc) };
+  const touched = new Map(), other = new Map(), atMark = new Set(), atHead = new Set(), added = new Set();
+  const id = (l) => l.match(/^#+ ([A-Z]+-\d+) — /)?.[1];
+  // where — for each line of a file, the identifier whose heading stands above it and the `##` section.
+  const where = (text) => {
+    let cur = null, sec = '';
+    return text.split('\n').map((l) => {
+      if (/^#+ /.test(l)) cur = id(l) ?? null;
+      if (/^## /.test(l)) sec = l.slice(3);
+      return { id: cur, section: sec };
+    });
+  };
+  const files = JSON.parse(must('git', 'diff', [mark, head])).filter((f) => `${f.old ?? ''} ${f.path}`.includes('docs/spec/'));
+  for (const f of files) {
+    const old = f.old ?? f.path;
+    const before = f.status === 'A' ? [] : must('git', 'show', [mark], old);
+    const after = f.status === 'D' ? [] : must('git', 'show', [head], f.path);
+    for (const [text, set] of [[before, atMark], [after, atHead]]) for (const l of String(text).split('\n')) if (id(l)) set.add(id(l));
+    const [was, now] = [String(before), String(after)].map(where);
+    const hit = (file, at) => at && (at.id ? touched.set(at.id, { id: at.id, file, section: at.section })
+      : other.set(`${file}\0${at.section}`, { file, section: at.section }));
+    for (const hunk of must('git', 'diff_lines', [mark, head], [f.old, f.path].filter(Boolean).join('\0')).split(/^@@ /m).slice(1)) {
+      const [, a, b = '1', c, d = '1'] = hunk.match(/^-(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
+      for (let i = 0; i < +b; i++) hit(old, was[+a - 1 + i]);
+      for (let i = 0; i < +d; i++) hit(f.path, now[+c - 1 + i]);
+      for (const l of hunk.split('\n')) if (l.startsWith('+') && id(l.slice(1))) added.add(id(l.slice(1)));
+    }
+  }
+  const all = [...touched.values()];
+  return {
+    changed: all.filter((t) => atHead.has(t.id) && !(added.has(t.id) && !atMark.has(t.id))),
+    created: all.filter((t) => added.has(t.id) && !atMark.has(t.id)),
+    retired: all.filter((t) => !atHead.has(t.id)),
+    other: [...other.values()],
+  };
+};

package/scripts/read-roadmap/moved.mjs

@@ -0,0 +1,70 @@
+// read-roadmap.moved(n…): whether a rule each issue cites moved since the roadmap's mark. An issue
+// filed from the specification describes a rule as it stood; when a brainstorm rewrites that rule and
+// `/roadmap` has not run since, working the issue builds the former rule. One line per issue,
+// `- moved #<n>: passes | stops: <why>`, after the result's `roadmap:` and `mark:` lines; exit 1 when
+// any stops. `node moved.mjs <n>…`, from the repository's root.
+//
+// No roadmap passes, there being no mark to compare; any other mark that is no commit stops. What an
+// issue cites is the `R-<n>` and `C-<n>` lines of its *Where it comes from* — none passes. What
+// moved is `range(<mark>, HEAD)`, then the same up to the local `develop`: a rule rewritten there
+// after this branch was cut moved all the same, and the local branch, not `origin/develop`, holds a
+// specification commit not yet pushed — `origin/develop` in a clone that has none, so holds none.
+// A change elsewhere in the specification blocks nothing.
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { range, roadmap } from './lib.mjs';
+
+const issues = process.argv.slice(2);
+if (!issues.length || !issues.every((n) => /^\d+$/.test(n))) {
+  console.error('usage: node moved.mjs <n>…');
+  process.exit(2);
+}
+const pkg = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const op = (skill, operation, args = []) =>
+  spawnSync(process.execPath, [join(pkg, 'scripts', skill, `${operation}.mjs`), ...args], { encoding: 'utf8', input: '', maxBuffer: 256 * 1024 * 1024 });
+const out = [];
+const say = (line) => out.push(`- ${line}`);
+let stopped = false;
+const answer = (n, why) => {
+  if (why) stopped = true;
+  say(`moved #${n}: ${why ? `stops: ${why}` : 'passes'}`);
+};
+
+const dev = spawnSync('git', ['rev-parse', '--verify', '--quiet', 'refs/heads/develop']).status === 0 ? 'develop' : 'origin/develop';
+const r = roadmap();
+say(`roadmap: ${r.roadmap}`);
+say(`mark: ${r.mark}`);
+// moving — the identifiers a range touched, or the stop its unresolved range is.
+const ranges = {};
+const moving = (head) => {
+  if (!ranges[head]) {
+    const g = range(r.sha, head);
+    ranges[head] = g.unresolved ? g : { ids: new Set([...g.changed, ...g.created, ...g.retired].map((t) => t.id)) };
+  }
+  return ranges[head];
+};
+// since — the `docs(spec)` commits since the mark, on HEAD or on develop.
+const since = (develop) => {
+  const s = op('git', 'log_since', develop ? [r.sha, dev] : [r.sha]);
+  if (s.status !== 0) return `(the docs(spec) commits could not be read: ${(s.stderr || s.stdout).trim()})`;
+  return JSON.parse(s.stdout).filter((c) => c.type === 'docs' && c.scope === 'spec').map((c) => `${c.sha.slice(0, 8)} ${c.subject}`).join('; ');
+};
+for (const n of issues) {
+  if (r.roadmap === 'none') { answer(n); continue; }
+  if (!r.sha) { answer(n, `the roadmap gives no mark to compare — roadmap ${r.roadmap}, mark ${r.mark}`); continue; }
+  const v = op('tracker', 'view', [n]);
+  if (v.status !== 0) { answer(n, `#${n} could not be read — ${(v.stderr || v.stdout).trim()}`); continue; }
+  const where = JSON.parse(v.stdout).body.split(/^## Where it comes from[ \t]*$/m)[1]?.split(/^## /m)[0] ?? '';
+  const cited = [...where.matchAll(/^(?:- )?([RC]-\d+) — /gm)].map((m) => m[1]);
+  if (!cited.length) { answer(n); continue; }
+  const head = moving('HEAD'), develop = moving(dev);
+  const bad = head.unresolved ?? develop.unresolved;
+  if (bad) { answer(n, `the range from the mark is unresolved — ${bad}`); continue; }
+  const here = cited.filter((i) => head.ids.has(i)), there = cited.filter((i) => develop.ids.has(i) && !head.ids.has(i));
+  if (here.length) answer(n, `${here.join(', ')} moved since the mark — ${since(false)} — \`/roadmap\` rewrites or closes the issue`);
+  else if (there.length) answer(n, `${there.join(', ')} moved on develop only — ${since(true)} — \`/roadmap\` run on develop, or develop brought into this branch`);
+  else answer(n);
+}
+console.log(out.join('\n'));
+process.exit(stopped ? 1 : 0);

package/scripts/read-roadmap/range.mjs

@@ -0,0 +1,15 @@
+// read-roadmap.range(mark, head): lib.mjs's `range`, as JSON, the result's `range:` field; exit 1 on
+// `unresolved: <git's answer>`. `node range.mjs <mark> <head>`, from the repository's root.
+import { range } from './lib.mjs';
+
+const [mark, head] = process.argv.slice(2);
+if (!mark || !head) {
+  console.error('usage: node range.mjs <mark> <head>');
+  process.exit(2);
+}
+const r = range(mark, head);
+if (r.unresolved) {
+  console.log(`unresolved: ${r.unresolved}`);
+  process.exit(1);
+}
+console.log(JSON.stringify(r));

package/scripts/release/cut.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// `codelife release cut [<version>] [--prepare]` (K-16): the release you confirmed, made locally.
+// The version written into the version file and every published package.json (R-244), the
+// changelog section, the generated outputs the range since the last tag makes stale, the release
+// tier and the guards that range fires (R-245) — a red restores what it wrote and stops —, then
+// `chore(release): <version>`. Without --prepare, the merge and the annotated tag (R-246): develop
+// merged into main, tagged there, develop fast-forwarded; on main, tagged then merged back into
+// develop; on a support/ branch, tagged in place. A version already prepared, with nothing landed
+// after its commit, goes straight to the merge. Pushes nothing: prints one `push:` line per thing to
+// push, each yours to run. Exit 1 on a stop, 2 on a usage error.
+import '../node-floor.mjs';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { compare, tagFor } from '../tags.mjs';
+import { fired, git, guards, paths, runChecks, tier } from '../verify/lib.mjs';
+import { changelog, dirtyPaths, hasOrigin, level, packages, read, said, say } from './lib.mjs';
+
+const args = process.argv.slice(2);
+const prepare = args.includes('--prepare');
+const [version, ...extra] = args.filter((a) => a !== '--prepare');
+if (extra.length || (version && !/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(version))) { console.error('usage: codelife release cut [<version>] [--prepare]'); process.exit(2); }
+
+console.log('### release cut');
+const stop = (why) => { say('stop', why); process.exit(1); };
+const run = (...a) => { const r = git(...a); if (r.status) stop(`git ${a.join(' ')} — ${said(r)}`); return r.out; };
+const f = read(prepare);
+if (f.stops.length) stop(f.stops[0]);
+const l = level(f.branch);
+if (l.stop) stop(l.stop);
+const name = f.now?.name ?? '';
+
+if (!changelog()) stop('no generated[] entry writes CHANGELOG.md — /setup');
+let v = version;
+if (f.resume && (!v || v === f.resume.version)) {
+  v = f.resume.version;
+  say('resumed', `${v}, prepared by ${f.resume.commit.slice(0, 8)}`);
+  if (prepare) { say('prepared', 'already — nothing to do'); process.exit(0); }
+} else {
+  if (!v) stop(f.proposed ? `give the version you confirmed — prep proposed ${f.proposed.version}` : 'give the first version');
+  if (f.from && compare(v, f.from) <= 0) stop(`${v} is not after the last tag's ${f.from}`);
+
+  // The version, then the section — the generator reads the bumped file as the release being cut.
+  const range = f.tag ? paths('diff', '--name-only', `${f.tag}...HEAD`) : null;
+  const files = packages(f.vf);
+  for (const p of files) writeFileSync(p, readFileSync(p, 'utf8').replace(/("version"\s*:\s*")[^"]*(")/, `$1${v}$2`));
+  say('version', `${v} in ${files.join(', ')}`);
+  const restore = (why) => {
+    git('restore', '--source=HEAD', '--staged', '--worktree', '--', ':/');
+    const left = dirtyPaths();
+    stop(`${why} — every tracked file restored${left.length ? `; left untracked: ${left.join(', ')}` : ''}`);
+  };
+  const generated = guards('generated');
+  const outputs = generated.filter((g) => !(g.path ?? []).includes('CHANGELOG.md') && (!range || fired([g], range).length));
+  const shell = (cs) => (cs ?? []).map((c) => ({ name: c, file: c, shell: true }));
+  if (runChecks(shell([changelog(), ...outputs.flatMap((g) => g.command ?? [])]), '- ')) restore('a generator failed');
+  const declared = [...files, 'CHANGELOG.md', ...outputs.flatMap((g) => g.path ?? []).map((p) => p.replace(/\/$/, ''))];
+  const outside = dirtyPaths(restore).filter((p) => !declared.some((d) => p === d || p.startsWith(`${d}/`)));
+  if (outside.length) restore(`changed outside the declared paths: ${outside.join(', ')}`);
+  if (runChecks([tier('release'), ...shell(guards().filter((g) => !range || fired([g], range).length).flatMap((g) => g.run))], '- ')) restore('a check is red');
+  run('--literal-pathspecs', 'add', '-A', '--', ...dirtyPaths(restore));
+  const c = git('commit', '-m', `chore(release): ${v}`);
+  if (c.status) restore(`the commit was refused — ${said(c)}`);
+  say('commit', `${run('rev-parse', '--short=8', 'HEAD')} chore(release): ${v}`);
+  if (f.proposed?.support && v === f.proposed.version && f.kind === 'release') {
+    if (!git('rev-parse', '--verify', '--quiet', f.proposed.support).out) run('branch', f.proposed.support, f.tag);
+    say('support', `${f.proposed.support} at ${f.tag}`);
+  }
+}
+
+// The section's size, counted here so that nobody counts it by hand: the brief shows it whole when it
+// is short, and this line, its breaking entries and the file when it is not.
+{
+  const lines = readFileSync('CHANGELOG.md', 'utf8').split('\n');
+  const at = lines.findIndex((x) => x.startsWith(`## [${v}]`));
+  const end = lines.findIndex((x, i) => i > at && (x.startsWith('## ') || x.startsWith('<!--')));
+  const body = at < 0 ? [] : lines.slice(at, end < 0 ? undefined : end).filter((x) => x.trim());
+  const groups = []; for (const x of body) if (x.startsWith('### ')) groups.push([x.slice(4), 0]); else if (x.startsWith('- ') && groups.length) groups.at(-1)[1]++;
+  const breaking = body.filter((x) => x.startsWith('- ') && x.endsWith('— **breaking**')).length;
+  say('section', at < 0 ? `CHANGELOG.md has no [${v}] section` : `CHANGELOG.md [${v}], ${body.length} lines — ${[...groups.map(([g, n]) => `${g} ${n}`), `breaking ${breaking}`].join(', ')}`);
+}
+if (prepare) { say('prepared', `stopped at the release commit — merge this branch, then /release on develop`); process.exit(0); }
+
+// The merge and the tag, locally; origin's copy of a branch about to move is brought forward first.
+const tag = tagFor(v);
+if (git('tag', '-l', tag).out) stop(`${tag} exists already — a tag consumers have fetched is never moved`);
+const origin = hasOrigin();
+const has = (ref) => !!git('rev-parse', '--verify', '--quiet', ref).out;
+const contains = (a, b) => git('merge-base', '--is-ancestor', a, b).status === 0;
+const forward = (b) => {
+  if (origin && git('ls-remote', '--exit-code', '--heads', 'origin', b).status === 0) {
+    run('fetch', 'origin', `+refs/heads/${b}:refs/remotes/origin/${b}`);
+    if (!has(`refs/heads/${b}`) || contains(b, `origin/${b}`)) run('fetch', '.', `refs/remotes/origin/${b}:refs/heads/${b}`);
+    else if (!contains(`origin/${b}`, b)) stop(`${b} diverged from origin/${b} — reconcile first`);
+  }
+  if (!has(`refs/heads/${b}`)) stop(`no ${b} branch — /setup creates it`);
+};
+const merge = (from, into) => {
+  forward(into);
+  run('switch', into);
+  const r = git('merge', '--no-ff', '-m', `Merge branch '${from}' into ${into} for ${v}`, from);
+  if (r.status) stop(`merging ${from} into ${into} conflicts — the merge is left in place for you: ${git('diff', '--name-only', '--diff-filter=U').out.split('\n').join(', ')}`);
+  say('merge', `${from} into ${into}: ${run('rev-parse', '--short=8', 'HEAD')}`);
+};
+const annotate = () => { run('tag', '-a', tag, '-m', tag); say('tag', `${tag} on ${git('branch', '--show-current').out}`); };
+const pushes = [];
+if (f.kind === 'release') {
+  merge('develop', 'main'); annotate();
+  run('switch', 'develop'); run('merge', '--ff-only', 'main');
+  say('develop', 'fast-forwarded to the merge');
+  pushes.push('main', 'develop');
+} else if (f.kind === 'hotfix') {
+  annotate(); merge('main', 'develop'); run('switch', 'main');
+  pushes.push('main', 'develop');
+} else {
+  annotate();
+  pushes.push(f.branch);
+}
+if (f.proposed?.support && git('rev-parse', '--verify', '--quiet', f.proposed.support).out) pushes.push(f.proposed.support);
+if (!origin) say('push', 'nothing — no origin: the release stays in this clone');
+else for (const p of [...pushes.map((b) => `git push origin ${b}`), `git push origin refs/tags/${tag}`]) say('push', p);
+say('then', origin ? '`codelife release entry` once the tag is on origin' : 'nothing — no origin, no entry');