@ersbeth/codelife 0.0.0-stage → 0.11.1

package/scripts/roadmap/assemble.mjs

@@ -0,0 +1,269 @@
+// The cut: the cases a range of the specification covers, assembled into lots from the blocks
+// `prerequisites` returned, one per capability. A case the suite cites — a tracked file outside
+// `docs/` with a quoted string opening on its identifier and a space, a test's title — is built: it
+// leaves the cut, and counts as a prerequisite met. Cases that presume each other are one unit, never
+// split. A unit's stage is the highest of its prerequisites', one more for a prerequisite in another
+// capability, so a case shares a lot with what its own capability built before it and waits for
+// what another builds; a lot is one capability at one stage, and one over the bound is split in
+// consecutive parts, each after the one before. Then the fill: a lot under the bound takes in the
+// next lot of the plan's order its decision last wrote, within the bound, and never one that would
+// make it wait for itself. A prerequisite outside the cut is not this plan's
+// to build: it orders nothing here, and its lot's `outside` line names it for the filing to find
+// the open lot that builds it, if one does. A lot also waits for the lot before it in each of its
+// capabilities, so two lots never change one area of the code at once; and the lots print in the order
+// that brings the journeys to playable as early as possible, the most preferred first.
+// `node assemble.mjs <cases> <cut> <journeys> <block>…`, where <cases> is what the form script's
+// `cases` mode printed, <cut> the case identifiers the range covers, one per line, each followed
+// by a tab and the commit of the range that last wrote it or `none`, and <journeys>
+// the journeys most preferred first, one per line — one it omits comes after, in <cases>' order,
+// and a lot that completes none last. One fact per line,
+// tab-separated, kind first: `refused <block> <case> <identifier>` for each prerequisite that is no
+// case of the specification, `built <case> <files>` for each case of the cut the suite cites, then
+// `lot <first case> <capabilities> <count> <after|none>`, a merged lot's capabilities space-separated, then that lot's
+// `member <lot> <rule> <cases>`, `journey <lot> <J-n>`, `outside <lot> <cases>` and
+// `flag <lot> <cycle|over|members|split|fill|spread> <what>` — every grouping the table must show.
+// What it cannot judge — a cut identifier that is no case or hands no decision, a case no block
+// answers, a block that read nothing, a preferred line that is no journey, a suite it could not
+// read — exits 1, each named, with nothing cut: an unjudged case would look like one that presumes
+// nothing, a lookup not made like a case no commit wrote, an unread preference like none given, an
+// unread suite like one that cites nothing.
+import '../node-floor.mjs';
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+// The bound, here and nowhere else: about ten cases a lot.
+const BOUND = 10;
+
+const [casesFile, cutFile, journeysFile, ...blockFiles] = process.argv.slice(2);
+if (!journeysFile || !blockFiles.length) {
+  console.error('usage: node assemble.mjs <cases> <cut> <journeys> <block>…');
+  process.exit(2);
+}
+const lines = (file) => readFileSync(file, 'utf8').split('\n').filter((l) => l.trim());
+
+const of = new Map(), capabilities = new Map(), journeys = [];
+for (const line of lines(casesFile)) {
+  const [kind, id, a = '', b] = line.split('\t');
+  if (kind === 'case') {
+    if (!capabilities.has(a)) capabilities.set(a, capabilities.size);
+    of.set(id, { capability: a, rule: b, place: of.size });
+  }
+  if (kind === 'journey') journeys.push([id, a.split(' ').filter(Boolean)]);
+}
+
+// An identifier that is no case of the specification — one no heading carries, or a rule's — is
+// refused, named with its block, and builds nothing: a case presumes cases.
+const stops = [], refused = [], presumes = new Map();
+for (const file of blockFiles) {
+  const text = readFileSync(file, 'utf8');
+  if (/^- (capability|index): not passed/m.test(text)) stops.push(`${file}: the block read nothing`);
+  else for (const m of text.matchAll(/^- (C-\d+): (.+)$/gm)) {
+    const cited = m[2].trim() === 'none' ? [] : m[2].trim().split(/\s+/);
+    for (const id of cited.filter((id) => !of.has(id))) refused.push(['refused', file, m[1], id]);
+    presumes.set(m[1], cited.filter((id) => of.has(id)));
+  }
+}
+// The citations, by case: `git grep` reads the tracked files only, and exits 1 when nothing matches;
+// `-z` ends each path on a NUL, so a name git would quote comes back as it is.
+const citing = new Map();
+let grep = '';
+try {
+  grep = execFileSync('git', ['grep', '--full-name', '--no-color', '--no-line-number', '--no-column', '-z', '-I', '-o', '-E', '["\'`]C-[0-9]+', '--', ':/', ':(top,exclude)docs'], { encoding: 'utf8', maxBuffer: 1 << 28 });
+} catch (e) {
+  if (e.status !== 1) stops.push(`the suite's citations: ${String(e.stderr || e.message).trim()}`);
+}
+for (const m of grep.matchAll(/^([^\0\n]*)\0["'`](C-\d+)$/gm)) citing.set(m[2], [...new Set([...(citing.get(m[2]) || []), m[1]])]);
+// A cut line is a case, then the commit of the range that last wrote it — its decision — or `none`,
+// which fills nothing.
+const cut = [], built = [], decisionOf = new Map();
+for (const [c, commit] of lines(cutFile).map((l) => l.trim().split(/\s+/))) {
+  if (cut.includes(c) || built.includes(c)) continue;
+  if (!commit) stops.push(`${c}: no decision handed, nor none`);
+  else if (commit !== 'none') decisionOf.set(c, commit);
+  (of.has(c) && citing.has(c) ? built : cut).push(c);
+}
+for (const c of cut) {
+  if (!of.has(c)) stops.push(`${c}: no case of the specification`);
+  else if (!presumes.has(c)) stops.push(`${c}: no block answers it`);
+}
+const preferred = lines(journeysFile).map((l) => l.trim());
+for (const j of preferred) if (!journeys.some(([id]) => id === j)) stops.push(`${j}: no journey of the specification`);
+if (stops.length) {
+  for (const s of stops) console.log(s);
+  process.exit(1);
+}
+cut.sort((a, b) => of.get(a).place - of.get(b).place);
+const inCut = new Set(cut);
+const deps = (c) => presumes.get(c).filter((p) => inCut.has(p) && p !== c);
+
+// The units, Tarjan's components: each is emitted after every unit it presumes, so the list is in
+// prerequisite order.
+const units = [], unitOf = new Map(), index = new Map(), low = new Map(), stack = [], held = new Set();
+const visit = (c) => {
+  index.set(c, index.size);
+  low.set(c, index.get(c));
+  stack.push(c);
+  held.add(c);
+  for (const p of deps(c)) {
+    if (!index.has(p)) {
+      visit(p);
+      low.set(c, Math.min(low.get(c), low.get(p)));
+    } else if (held.has(p)) low.set(c, Math.min(low.get(c), index.get(p)));
+  }
+  if (low.get(c) !== index.get(c)) return;
+  const unit = { cases: [] };
+  for (let p; p !== c; ) {
+    p = stack.pop();
+    held.delete(p);
+    unit.cases.push(p);
+    unitOf.set(p, unit);
+  }
+  unit.cases.sort((a, b) => of.get(a).place - of.get(b).place);
+  unit.capability = of.get(unit.cases[0]).capability;
+  unit.place = of.get(unit.cases[0]).place;
+  units.push(unit);
+};
+for (const c of cut) if (!index.has(c)) visit(c);
+const unitDeps = (u) => [...new Set(u.cases.flatMap(deps).map((p) => unitOf.get(p)))].filter((d) => d !== u);
+for (const u of units) u.stage = Math.max(0, ...unitDeps(u).map((d) => d.stage + (d.capability === u.capability ? 0 : 1)));
+
+// ordered <items> <before> — items in prerequisite order, the earliest place first among those
+// ready; what a cycle leaves is appended in place order and returned as stuck.
+const ordered = (items, before, place) => {
+  const out = [], left = [...items].sort((a, b) => place(a) - place(b));
+  while (left.length) {
+    const i = left.findIndex((x) => before(x).every((y) => !left.includes(y)));
+    if (i < 0) return { out: out.concat(left), stuck: left };
+    out.push(...left.splice(i, 1));
+  }
+  return { out, stuck: [] };
+};
+
+const groups = new Map();
+for (const u of units) {
+  const key = `${u.stage}\t${u.capability}`;
+  if (!groups.has(key)) groups.set(key, []);
+  groups.get(key).push(u);
+}
+const lots = [], lotOf = new Map();
+for (const group of [...groups.values()].sort((a, b) => a[0].stage - b[0].stage || capabilities.get(a[0].capability) - capabilities.get(b[0].capability))) {
+  const inGroup = ordered(group, (u) => unitDeps(u).filter((d) => group.includes(d)), (u) => u.place).out;
+  const size = inGroup.reduce((n, u) => n + u.cases.length, 0);
+  const target = Math.ceil(size / Math.ceil(size / BOUND));
+  let lot;
+  const parts = [];
+  for (const u of inGroup) {
+    if (!lot || lot.cases.length + u.cases.length > target) {
+      lots.push((lot = { capabilities: [u.capability], cases: [], units: [], split: [], took: [] }));
+      parts.push(lot);
+    }
+    lot.cases.push(...u.cases);
+    lot.units.push(u);
+  }
+  if (parts.length > 1) parts.forEach((p, i) => p.split.push(`part ${i + 1} of ${parts.length}`));
+}
+
+// The lots a lot's cases presume; its members, its cases by rule in their prerequisites' order; and
+// its tag, the first case its first member builds.
+const presumed = (lot) => [...new Set(lot.cases.flatMap(deps).map((p) => lotOf.get(p)))].filter((l) => l !== lot);
+const casesOf = (lot, r) => lot.cases.filter((c) => of.get(c).rule === r);
+const membersOf = (lot) => {
+  const rules = [...new Set(lot.cases.map((c) => of.get(c).rule))];
+  return ordered(rules, (r) => [...new Set(casesOf(lot, r).flatMap(deps).filter((p) => lotOf.get(p) === lot).map((p) => of.get(p).rule))].filter((x) => x !== r), (r) => lot.cases.indexOf(casesOf(lot, r)[0]));
+};
+const tagOf = (lot, members = membersOf(lot)) => casesOf(lot, members.out[0])[0];
+
+// settle — the lots in their prerequisites' order; a journey named on the last lot holding its
+// cases, which waits for the others, its independent test not passing before they close; a lot
+// waiting for its cases' lots and for the lot before it in each of its capabilities, so two lots
+// never change one area of the code at once; then the plan's order, each journey's last lot in
+// preference, everything it waits for placed before it.
+const last = new Map();
+const rank = (j) => (preferred.includes(j) ? preferred.indexOf(j) : preferred.length);
+const settle = () => {
+  lotOf.clear();
+  for (const lot of lots) for (const c of lot.cases) lotOf.set(c, lot);
+  lots.splice(0, lots.length, ...ordered(lots, presumed, (l) => lots.indexOf(l)).out);
+  last.clear();
+  const after = new Map(lots.map((l) => [l, []]));
+  for (const [j, cited] of journeys) {
+    const mine = cited.filter((c) => inCut.has(c)).map((c) => lotOf.get(c));
+    if (!mine.length) continue;
+    const at = lots[Math.max(...mine.map((l) => lots.indexOf(l)))];
+    last.set(j, at);
+    after.get(at).push(...mine.filter((l) => l !== at));
+  }
+  for (const lot of lots) {
+    const earlier = lots.slice(0, lots.indexOf(lot));
+    const before = lot.capabilities.map((k) => earlier.filter((l) => l.capabilities.includes(k)).pop());
+    lot.waits = [...new Set([...after.get(lot), ...presumed(lot), ...before])].filter((l) => l && l !== lot);
+  }
+  const placed = [];
+  const place = (lot) => {
+    if (placed.includes(lot)) return;
+    for (const l of [...lot.waits].sort((a, b) => lots.indexOf(a) - lots.indexOf(b))) place(l);
+    placed.push(lot);
+  };
+  for (const j of [...last.keys()].sort((a, b) => rank(a) - rank(b))) place(last.get(j));
+  for (const lot of lots) place(lot);
+  return placed;
+};
+
+// The fill. A lot's decision is the one commit that last wrote all its cases, none when they name
+// two or none. Walking the plan's order, a lot under the bound takes in the next lot of that order
+// of its decision — a lot of another passed over — while the merged lot stays within the bound and
+// nothing it presumes presumes it in turn; the first that does not fit ends its fill. A merged lot
+// counts as each of its capabilities, and the order is settled again around it.
+const decision = (lot) => {
+  const d = new Set(lot.cases.map((c) => decisionOf.get(c)));
+  return d.size === 1 ? [...d][0] : undefined;
+};
+const cycles = (a, b) => {
+  const seen = new Set(), todo = [...presumed(a), ...presumed(b)].filter((l) => l !== a && l !== b);
+  for (let l; (l = todo.pop()); ) {
+    if (l === a || l === b) return true;
+    if (!seen.has(l)) seen.add(l), todo.push(...presumed(l));
+  }
+  return false;
+};
+const planned = settle();
+for (const lot of planned) {
+  const d = decision(lot);
+  if (lot.into || !d) continue;
+  for (const next of planned.slice(planned.indexOf(lot) + 1)) {
+    if (next.into || decision(next) !== d) continue;
+    if (lot.cases.length + next.cases.length > BOUND || cycles(lot, next)) break;
+    next.into = lot;
+    lot.took.push(tagOf(next));
+    lot.cases.push(...next.cases);
+    lot.units.push(...next.units);
+    lot.split.push(...next.split);
+    lot.capabilities = [...new Set([...lot.capabilities, ...next.capabilities])];
+    for (const c of next.cases) lotOf.set(c, lot);
+  }
+}
+lots.splice(0, lots.length, ...lots.filter((l) => !l.into));
+const placed = settle();
+for (const lot of lots) (lot.members = membersOf(lot)), (lot.tag = tagOf(lot, lot.members));
+
+const print = (...fields) => console.log(fields.join('\t'));
+for (const r of refused) print(...r);
+for (const c of built.sort((a, b) => of.get(a).place - of.get(b).place)) print('built', c, citing.get(c).join(' '));
+for (const lot of placed) {
+  const first = lot.tag, members = lot.members;
+  const after = [...lot.waits].sort((a, b) => placed.indexOf(a) - placed.indexOf(b));
+  print('lot', first, lot.capabilities.join(' '), lot.cases.length, after.map((l) => l.tag).join(' ') || 'none');
+  for (const r of members.out) print('member', first, r, casesOf(lot, r).join(' '));
+  for (const [j, l] of last) if (l === lot) print('journey', first, j);
+  const outside = [...new Set(lot.cases.flatMap((c) => presumes.get(c)).filter((p) => !inCut.has(p) && !citing.has(p)))];
+  if (outside.length) print('outside', first, outside.join(' '));
+  for (const u of lot.units) if (u.cases.length > 1) print('flag', first, 'cycle', u.cases.join(' '));
+  for (const u of lot.units) if (u.cases.length > BOUND) print('flag', first, 'over', `${u.cases.length} cases presume each other, over the bound of ${BOUND}`);
+  if (members.stuck.length) print('flag', first, 'members', `${members.stuck.join(' ')} presume each other's cases`);
+  for (const s of lot.split) print('flag', first, 'split', s);
+  if (lot.took.length) print('flag', first, 'fill', lot.took.join(' '));
+  for (const r of members.out) {
+    const also = lots.filter((l) => l !== lot && l.cases.some((c) => of.get(c).rule === r));
+    if (also.length) print('flag', first, 'spread', `${r} also in ${also.map((l) => l.tag).join(' ')}`);
+  }
+}

package/scripts/roadmap/cut.mjs

@@ -0,0 +1,88 @@
+// /roadmap's cut, one command (K-8): the lots of a run folder `codelife roadmap prep` wrote, from the
+// `prerequisites` blocks saved in its blocks/ — assemble.mjs, then what it cannot see: each lot's
+// place after the confirmed order, the open lot building a case it presumes outside the cut, the
+// open lot of each of its capabilities it waits for (R-264), an orphan citing one of a member's
+// cases proposed as that member, and an effort from the member's count of cases. Writes the whole
+// table to table.md in the folder and prints a `### cut` summary, one line per lot; a `- stop:`
+// line — what assemble could not judge — exits 1. `codelife roadmap cut <run folder>`.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { prep, said } from '../prepare-lib.mjs';
+
+const dir = process.argv[2];
+if (!dir || !existsSync(join(dir, 'cut.tsv'))) {
+  console.error('usage: codelife roadmap cut <the run folder codelife roadmap prep printed>');
+  process.exit(2);
+}
+const { say, stop, done } = prep('cut');
+const read = (f) => readFileSync(join(dir, f), 'utf8');
+const tsv = (f) => read(f).split('\n').filter(Boolean).map((l) => l.split('\t'));
+const cases = tsv('cases.tsv');
+const caseOf = new Map(cases.filter((x) => x[0] === 'case').map(([, id, k, rule]) => [id, { k, rule }]));
+const ruleOf = new Map(cases.filter((x) => x[0] === 'rule').map(([, id, k]) => [id, k]));
+const heading = new Map(cases.filter((x) => x[0] === 'index').map(([, l]) => [l.split(' — ')[0], l]));
+const issues = JSON.parse(read('issues.json')), map = JSON.parse(read('roadmap.json'));
+const section = (text, h) => text.split(new RegExp(`^## ${h}[ \\t]*$`, 'm'))[1]?.split(/^## /m)[0] ?? '';
+const cites = (text, id) => new RegExp(`(^|[^\\w-])${id}(?![\\w-])`).test(section(text, 'Where it comes from'));
+
+const lots = [];
+if (tsv('cut.tsv').length) {
+  const blocks = existsSync(join(dir, 'blocks')) ? readdirSync(join(dir, 'blocks')).map((f) => join(dir, 'blocks', f)) : [];
+  if (!blocks.length) stop(`no block in ${join(dir, 'blocks')} — save each prerequisites agent's block there`);
+  const a = spawnSync(process.execPath, [join(dirname(fileURLToPath(import.meta.url)), 'assemble.mjs'), join(dir, 'cases.tsv'), join(dir, 'cut.tsv'), join(dir, 'journeys.txt'), ...blocks], { encoding: 'utf8' });
+  if (a.status !== 0) stop(`assemble could not judge: ${said(a).split('\n').join('; ')}`);
+  for (const [kind, lot, ...f] of a.stdout.split('\n').filter(Boolean).map((l) => l.split('\t'))) {
+    if (kind === 'refused') say(`refused: ${f[1]}, given for ${f[0]} in ${lot.split('/').pop()}, is no case of the specification`);
+    else if (kind === 'built') say(`built: ${lot} — cited by ${f[0]}`);
+    else if (kind === 'lot') lots.push({ first: lot, caps: f[0].split(' '), after: f[2] === 'none' ? [] : f[2].split(' '), members: [], journeys: [], outside: [], flags: [] });
+    else {
+      const l = lots.find((x) => x.first === lot);
+      if (kind === 'member') l.members.push({ rule: f[0], cases: f[1].split(' ') });
+      else if (kind === 'journey') l.journeys.push(f[0]);
+      else if (kind === 'outside') l.outside.push(...f[0].split(' '));
+      else if (kind === 'flag') l.flags.push(`${f[0]} ${f[1]}`);
+    }
+  }
+}
+
+// What an open umbrella builds: the capabilities its origin and its members' origins name.
+const capsOf = (u) => {
+  const ids = [u.title, ...issues.filter((i) => i.lot === u.n).map((i) => i.title)].map((t) => t.match(/^\[(?:lot · )?spec:([A-Z]-\d+)/)?.[1]).filter(Boolean);
+  return new Set(ids.map((id) => id.startsWith('K-') ? id : caseOf.get(id)?.k ?? ruleOf.get(id)).filter(Boolean));
+};
+const umbrellas = issues.filter((i) => i.labels.includes('lot'));
+const ranked = [...map.order.map((o) => umbrellas.find((u) => u.n === o.lot)).filter(Boolean), ...umbrellas.filter((u) => !map.order.some((o) => o.lot === u.n))];
+const seen = new Set();
+const effort = (n) => (n <= 2 ? 'S' : n <= 5 ? 'M' : 'L');
+const table = [`# The cut`, '', `Run folder: ${dir}. Each lot after the roadmap's ${map.order.length} confirmed lines, in this order.`, ''];
+lots.forEach((l, i) => {
+  // Outside the cut: the open lot whose issue builds the case; none, and the case is built.
+  for (const c of l.outside) {
+    const b = issues.find((x) => x.lot && cites(x.body, c));
+    if (b && !l.after.includes(`#${b.lot}`)) l.after.push(`#${b.lot}`);
+  }
+  // A capability's first lot of this cut waits for the last open lot of that capability.
+  for (const k of l.caps) {
+    if (seen.has(k)) continue;
+    seen.add(k);
+    const u = ranked.filter((x) => capsOf(x).has(k)).at(-1);
+    if (u && !l.after.includes(`#${u.n}`)) l.after.push(`#${u.n}`);
+  }
+  for (const m of l.members) m.existing = issues.find((x) => !x.lot && !x.labels.includes('lot') && m.cases.some((id) => cites(x.body, id)))?.n;
+  const efforts = l.members.map((m) => effort(m.cases.length));
+  const rank = map.order.length + i + 1;
+  say(`lot: ${rank} — spec:${l.first} — ${l.caps.join(' ')} — ${l.members.length} members, ${['S', 'M', 'L'].map((e) => `${efforts.filter((x) => x === e).length}${e}`).filter((x) => !x.startsWith('0')).join(' ')} — after ${l.after.join(', ') || 'none'} — journeys ${l.journeys.join(' ') || 'none'}`);
+  for (const f of l.flags) say(`flag: spec:${l.first} — ${f}`);
+  table.push(`## ${rank}. [lot · spec:${l.first}] — ${l.caps.join(', ')} — after ${l.after.join(', ') || 'none'}`, '',
+    `Journeys it completes: ${l.journeys.join(', ') || 'none'}. Outside the cut: ${l.outside.join(', ') || 'none'}. Flags: ${l.flags.join('; ') || 'none'}.`, '',
+    '| # | Rule | Cases | Effort | Issue |', '|---|---|---|---|---|',
+    ...l.members.map((m, j) => `| ${j + 1} | ${heading.get(m.rule) ?? m.rule} | ${m.cases.map((c) => heading.get(c) ?? c).join('<br>')} | ${effort(m.cases.length)} | ${m.existing ? `#${m.existing} existing` : 'new'} |`), '');
+});
+const built = tsv('built.tsv');
+table.push('## Proposed built', '', ...built.map(([c, m]) => `- ${heading.get(c) ?? c} — merged with its code in ${m}`), ...(built.length ? [] : ['None.']), '');
+writeFileSync(join(dir, 'table.md'), table.join('\n'));
+say(`lots: ${lots.length}${lots.length ? '' : ' — nothing to cut'}`);
+say(`table: ${join(dir, 'table.md')}`);
+done();

package/scripts/roadmap/prepare.mjs

@@ -0,0 +1,249 @@
+// /roadmap's preparation, one command (K-8): everything a plan is made of that no judgement decides.
+// The roadmap, its mark and its order, or a first run's starting point; what docs/spec/ changed from
+// there to HEAD, each case with its decision — the commit of the range that last wrote it — and
+// proposed built when the merge that brought that commit changed code too (R-184); the open
+// issues, each written to a file, sorted into the umbrellas, the members and the orphans; a member
+// whose latest plan waits for a case, and who builds it; the open issues citing what the range
+// changed; one folder per capability to cut. Writes nothing on the forge or in the tree: a run folder
+// outside it, and a `### prepare` summary. A `- stop:` line ends the run before any table, exit 1.
+// `codelife roadmap prep [<label-or-milestone>] [--from <sha>]`, from the repository's root.
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { first, prep, said } from '../prepare-lib.mjs';
+import { lotCount, orderLine, range, roadmap } from '../read-roadmap/lib.mjs';
+
+const usage = () => { console.error('usage: codelife roadmap prep [<label-or-milestone>] [--from <sha>]'); process.exit(2); };
+const argv = process.argv.slice(2);
+let from = null, scope = null;
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === '--from') from = argv[++i] ?? usage();
+  else if (scope === null) scope = argv[i];
+  else usage();
+}
+if (from !== null && !/^[0-9a-f]{7,64}$/.test(from)) usage();
+
+const { say, stop, done, op, must, title, kind } = prep('prepare');
+const git = (...a) => spawnSync('git', a, { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+const out = (...a) => { const r = git(...a); if (r.status !== 0) stop(`git ${a[0]} — ${said(r)}`); return r.stdout.trim(); };
+const section = (text, heading) => text.split(new RegExp(`^## ${heading}[ \\t]*$`, 'm'))[1]?.split(/^## /m)[0] ?? '';
+const cites = (text, id) => new RegExp(`(^|[^\\w-])${id}(?![\\w-])`).test(text);
+
+// The forge, as /work's preparation reads it: one that does not answer is a tracker nobody can plan.
+const forge = kind();
+if (forge !== 'none') {
+  const auth = op('tracker', 'auth');
+  if (auth.status !== 0) stop(`the forge's authentication — ${said(auth)}`);
+}
+const head = out('rev-parse', 'HEAD');
+const dir = mkdtempSync(join(tmpdir(), 'roadmap-'));
+say(`run: ${dir}`);
+say(`forge: ${forge}`);
+say(`head: ${head.slice(0, 8)} — ${out('log', '-1', '--format=%s', 'HEAD')}`);
+
+// The roadmap (R-263): its mark is where the range starts, its order the confirmed one (R-264).
+const r = roadmap();
+if (r.roadmap.startsWith('could not tell')) stop(`the roadmap — ${r.roadmap}`);
+if (r.roadmap.startsWith('two')) stop(`${r.roadmap.replace('two: ', 'two roadmaps: ')} — close the one you do not keep on the forge, then run again`);
+const map = { n: r.roadmap.match(/^#(\d+)$/)?.[1] ?? null, head, order: [], left: [] };
+let start = null, firstRun = false, citation = 'none';
+if (map.n) {
+  say(`roadmap: #${map.n}`);
+  if (/^(out of shape|unresolved)/.test(r.mark)) stop(`the roadmap's mark is ${r.mark} — correct it on the forge`);
+  if (r.mark.endsWith('not contained') && !from) {
+    stop(`the mark ${r.sha} is not an ancestor of HEAD (on ${out('branch', '--show-current') || 'no branch'}) — name the commit to read from: \`codelife roadmap prep --from <sha>\``);
+  }
+  start = from ?? r.sha;
+  say(`mark: ${r.sha}${from ? `, read from ${from} as you named it` : ''}`);
+  const body = JSON.parse(must('tracker', 'view', [map.n])).body;
+  for (const line of section(body, 'The order').split('\n').filter((l) => /^\d+\. /.test(l))) {
+    const o = orderLine(line);
+    if (!o) stop(`a line of the roadmap's order is out of shape: ${line} — correct it on the forge`);
+    map.order.push(o);
+  }
+  map.left = [...section(body, 'Left alone').matchAll(/^- #(\d+)/gm)].map((m) => m[1]);
+  say(`order: ${map.order.map((o) => `#${o.lot}${o.after.length ? ` after ${o.after.map((a) => `#${a}`).join(', ')}` : ''}`).join('; ') || 'none'}`);
+} else {
+  // A first run (R-263): the lots of origin spec: or citation ever filed, closed ones too.
+  firstRun = true;
+  say('roadmap: none — a first run');
+  const lots = must('tracker', 'list', forge === 'gh' ? ['--label', 'lot', '--state', 'all'] : ['-l', 'lot', '-A']).split('\n');
+  const tagged = (tag) => lots.map((l) => l.match(new RegExp(`^#(\\d+)\\t(\\[lot · ${tag}[^\\]]*\\].*)$`))).filter(Boolean);
+  const cited = tagged('citation');
+  if (cited.length) citation = citationLot(cited);
+  if (from) { start = from; say(`start: ${from}, as you named it`); }
+  else if (tagged('spec:').length) {
+    stop(`no roadmap, but lots of origin spec: exist — name the commit to read from, proposed ${out('log', '-1', '--format=%h', '--', 'docs/spec')}, the last that touched docs/spec/: \`codelife roadmap prep --from <sha>\``);
+  } else say('start: the specification from its first commit — no lot was ever filed from it');
+}
+
+// A citation lot already filed decides the pass (R-263): open, or closed before its merge, it stops.
+function citationLot(found) {
+  const [, n] = found[0];
+  const lot = JSON.parse(must('tracker', 'view', [n]));
+  if (!/^closed$/i.test(lot.state)) stop(`the citation lot #${n} is open — the plan is cut once it is merged`);
+  for (const [, m] of lot.body.matchAll(/^- \[[ xX]\] #(\d+)/gm)) {
+    const closing = JSON.parse(must('tracker', 'view', [m])).comments.map((c) => c.body).filter((b) => first(b).startsWith('codelife: closing — ')).at(-1) ?? '';
+    for (const [h] of closing.matchAll(/\b[0-9a-f]{7,40}\b/g)) {
+      if (git('merge-base', '--is-ancestor', h, 'HEAD').status !== 0) stop(`the citation lot #${n} is closed, but HEAD lacks ${h} from #${m} — the plan is cut once its merge request is merged`);
+    }
+  }
+  say(`citation lot: #${n}, merged — no citation pass`);
+  return 'merged';
+}
+
+// What the plan is cut from (K-23's R-271): every rule and case, their capabilities, the journeys.
+const form = spawnSync(process.execPath, [join(dirname(fileURLToPath(import.meta.url)), '..', 'spec-form.mjs'), 'cases'], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+if (form.status !== 0) stop(`codelife form cases — ${said(form)}`);
+writeFileSync(join(dir, 'cases.tsv'), form.stdout);
+const rows = form.stdout.split('\n').map((l) => l.split('\t'));
+const caseOf = new Map(rows.filter((x) => x[0] === 'case').map(([, id, k, rule]) => [id, { k, rule }]));
+const ruleOf = new Map(rows.filter((x) => x[0] === 'rule').map(([, id, k]) => [id, k]));
+const index = rows.filter((x) => x[0] === 'index').map((x) => x.slice(1).join('\t'));
+
+// The range: what changed from the start to HEAD, or everything when the run reads from the start.
+let touched, retired = [];
+if (start) {
+  const g = range(start, head);
+  if (g.unresolved) stop(`the range from ${start} — ${g.unresolved}`);
+  touched = [...g.changed, ...g.created].map((t) => t.id);
+  retired = g.retired.map((t) => t.id);
+} else touched = [...caseOf.keys()];
+const cut = touched.filter((id) => caseOf.has(id));
+const noCase = touched.filter((id) => ruleOf.has(id) && !cut.some((c) => caseOf.get(c).rule === id));
+
+// Each capability's document, by its `# K-<n> — ` heading.
+const docs = new Map();
+const walk = (d) => readdirSync(d, { withFileTypes: true }).forEach((e) => {
+  const p = join(d, e.name);
+  if (e.isDirectory()) walk(p);
+  else if (p.endsWith('.md')) { const k = readFileSync(p, 'utf8').match(/^# (K-\d+) — (.*)$/m); if (k) docs.set(k[1], { path: p, heading: k[2] }); }
+});
+walk('docs/spec');
+
+// Each case's decision — the range's last commit writing its lines at HEAD, its heading to its last
+// line that is not blank — and the first-parent commit of HEAD that brought it: a merge that also
+// changed a file outside docs/ brought the case with its code, and it is proposed built.
+const firstParent = new Set(out('rev-list', '--first-parent', 'HEAD').split('\n'));
+const brought = new Map();
+const broughtBy = (sha) => {
+  if (!brought.has(sha)) {
+    const m = firstParent.has(sha) ? sha : out('rev-list', '--ancestry-path', `${sha}..HEAD`).split('\n').filter((c) => firstParent.has(c)).at(-1);
+    const parent = git('rev-parse', '--verify', '-q', `${m}^1`).stdout.trim();
+    const files = (parent ? out('diff', '--name-only', parent, m) : out('show', '--name-only', '--format=', m)).split('\n').filter(Boolean);
+    brought.set(sha, { merge: m.slice(0, 8), code: files.some((f) => !f.startsWith('docs/')) });
+  }
+  return brought.get(sha);
+};
+// decision <id> <capability> — the range's last commit writing an identifier's lines at HEAD.
+const decision = (id, k) => {
+  const doc = docs.get(k);
+  if (!doc) stop(`${id}: no document carries ${k}`);
+  const lines = readFileSync(doc.path, 'utf8').split('\n');
+  const a = lines.findIndex((l) => new RegExp(`^#+ ${id} — `).test(l));
+  let b = lines.findIndex((l, i) => i > a && /^#/.test(l));
+  if (b < 0) b = lines.length;
+  while (b > a + 1 && !lines[b - 1].trim()) b--;
+  const r = git('log', '-1', '--format=%H', '-s', start ? `${start}..HEAD` : 'HEAD', '-L', `${a + 1},${b}:${doc.path}`);
+  if (r.status !== 0) stop(`${id}: its decision — ${said(r)}`);
+  return r.stdout.trim().split('\n')[0];
+};
+const cutLines = [], builtLines = [];
+for (const c of cut) {
+  const sha = decision(c, caseOf.get(c).k), by = sha && broughtBy(sha);
+  if (by?.code) builtLines.push(`${c}\t${by.merge}`);
+  else cutLines.push(`${c}\t${sha || 'none'}`);
+}
+// A rule whose statement alone changed is a row of no case, unless it came with its code too.
+const unplaced = noCase.filter((id) => { const sha = decision(id, ruleOf.get(id)); return !(sha && broughtBy(sha).code); });
+writeFileSync(join(dir, 'cut.tsv'), cutLines.map((l) => `${l}\n`).join(''));
+writeFileSync(join(dir, 'built.tsv'), builtLines.map((l) => `${l}\n`).join(''));
+const merges = [...new Set(builtLines.map((l) => l.split('\t')[1]))];
+say(`range: ${start ? `${start.slice(0, 8)}..${head.slice(0, 8)}` : 'the whole specification'} — ${cut.length} cases, ${builtLines.length} proposed built, merged with their code${merges.length ? ` in ${merges.join(', ')}` : ''}; ${cutLines.length} to cut`);
+if (unplaced.length) say(`no case: ${unplaced.join(', ')} — a rule's statement alone, for you to place`);
+
+// The journeys, most preferred first: their Priority., ties in the index's order (R-264).
+const rank = { first: 1, second: 2, third: 3, fourth: 4, fifth: 5 };
+const listed = [...readFileSync('docs/spec/README.md', 'utf8').matchAll(/^- \[(J-\d+) — .*\]\((journeys\/[^)]+)\)/gm)];
+const known = new Set(rows.filter((x) => x[0] === 'journey').map((x) => x[1]));
+const journeys = listed.filter(([, j]) => known.has(j)).map(([, j, p], i) => {
+  const word = readFileSync(join('docs/spec', p), 'utf8').match(/^\*\*Priority\.\*\* (\w+)/m)?.[1]?.toLowerCase();
+  return { j, i, p: rank[word] ?? 99 };
+}).sort((x, y) => x.p - y.p || x.i - y.i).map((x) => x.j);
+writeFileSync(join(dir, 'journeys.txt'), journeys.map((j) => `${j}\n`).join(''));
+
+// One folder per capability the cut covers: a copy of its document and the index (K-40).
+const caps = [...new Set(cutLines.map((l) => caseOf.get(l.split('\t')[0]).k))];
+for (const k of caps) {
+  const f = join(dir, k);
+  mkdirSync(f);
+  copyFileSync(docs.get(k).path, join(f, basename(docs.get(k).path)));
+  writeFileSync(join(f, 'index.txt'), index.map((l) => `${l}\n`).join(''));
+  say(`capability: ${k} — ${docs.get(k).heading} — ${cutLines.filter((l) => caseOf.get(l.split('\t')[0]).k === k).length} cases — ${k}/${basename(docs.get(k).path)}, ${k}/index.txt`);
+}
+
+// A first run over a repository with tests, no citation lot filed: the pass (R-263), each
+// capability handed the tracked test files whose path holds a word of its heading.
+if (firstRun && citation === 'none') {
+  const tests = out('ls-files').split('\n').filter((f) => /(^|\/)(tests?|__tests__)\/|\.(test|spec)\.[cm]?[jt]sx?$/.test(f));
+  let handed = 0;
+  for (const k of caps) {
+    const words = docs.get(k).heading.toLowerCase().split(/[^a-z]+/).filter((w) => w.length > 3);
+    const mine = tests.filter((f) => words.some((w) => f.toLowerCase().includes(w)));
+    if (!mine.length) continue;
+    handed++;
+    writeFileSync(join(dir, k, 'tests.txt'), mine.map((f) => `${f}\n`).join(''));
+    say(`citation: ${k} — ${mine.length} test files — ${k}/tests.txt`);
+  }
+  say(`citation pass: ${handed ? `${handed} capabilities handed tests` : tests.length ? 'none — no test file matches a capability' : 'none — no test file'}`);
+}
+
+// The open issues, each written to a file; the roadmap aside, the umbrellas, the members, the orphans.
+const numbers = must('tracker', 'list', []).split('\n').map((l) => l.match(/^#(\d+)\t/)?.[1]).filter(Boolean);
+mkdirSync(join(dir, 'issues'));
+const issues = numbers.filter((n) => n !== map.n).map((n) => {
+  const i = JSON.parse(must('tracker', 'view', [n]));
+  const plan = i.comments.map((c) => c.body).filter((b) => first(b).startsWith('codelife: plan — ')).at(-1) ?? '';
+  writeFileSync(join(dir, 'issues', `${n}.md`), `# ${i.title}\n\nLabels: ${i.labels.join(', ') || 'none'}. Milestone: ${i.milestone || 'none'}.\n\n${i.body}\n${plan ? `\n## Latest plan\n\n${plan}\n` : ''}`);
+  return { n, title: i.title, labels: i.labels, milestone: i.milestone, body: i.body, plan, lot: title('title.lot_of.mjs', i.title) };
+});
+writeFileSync(join(dir, 'issues.json'), JSON.stringify(issues, null, 1));
+writeFileSync(join(dir, 'roadmap.json'), JSON.stringify(map, null, 1));
+say(`issues: ${issues.length} open, each in issues/<n>.md`);
+
+const sentence = (t) => title('title.sentence_of.mjs', t);
+for (const u of issues.filter((i) => i.labels.includes('lot'))) {
+  const { open, total, effort } = lotCount(u.body);
+  const done = section(u.body, 'Done when').split('\n').find((l) => l.trim()) ?? 'none';
+  const place = map.order.findIndex((o) => o.lot === u.n);
+  say(`lot: #${u.n} — ${u.title.match(/^\[lot · ([^\]]+)\]/)?.[1] ?? 'no origin'} — ${sentence(u.title)} — ${open} of ${total} open, ${effort} — ${place < 0 ? 'not on the roadmap' : `rank ${place + 1}`} — done when: ${done.trim()}`);
+}
+
+// A member whose latest plan waits for a case (R-266), and the open issue that builds it.
+for (const m of issues.filter((i) => i.lot && i.plan)) {
+  const w = m.plan.match(/^Waits for: (.*?)\s*$/m)?.[1];
+  if (!w) continue;
+  if (!/^C-\d+$/.test(w)) { say(`waits: #${m.n} (lot #${m.lot}) — unreadable: ${w}`); continue; }
+  const b = issues.find((i) => i.n !== m.n && !i.labels.includes('lot') && cites(section(i.body, 'Where it comes from'), w));
+  say(`waits: #${m.n} (lot #${m.lot}) — ${w} — ${b ? `built by #${b.n}, ${b.lot ? `lot #${b.lot}` : 'in no lot'}` : 'no open issue builds it'}`);
+}
+
+// The open issues citing what the range changed (R-45): a rewrite, a closure, or the member of a row.
+if (start) {
+  // A rule is changed when one of its cases is: an issue citing it is about the rule and its cases.
+  const ids = [...new Set([...touched, ...touched.filter((id) => caseOf.has(id)).map((id) => caseOf.get(id).rule), ...retired])];
+  for (const i of issues) {
+    const hit = ids.filter((id) => cites(section(i.body, 'Where it comes from'), id));
+    if (hit.length) say(`cites: #${i.n} — ${hit.map((id) => `${id} ${retired.includes(id) ? 'retired' : 'changed'}`).join(', ')} — ${i.labels.includes('lot') ? 'umbrella' : i.lot ? `lot #${i.lot}` : 'orphan'} — ${sentence(i.title)}`);
+  }
+}
+
+const orphans = issues.filter((i) => !i.lot && !i.labels.includes('lot'));
+const inScope = orphans.filter((i) => scope === null || i.labels.includes(scope) || i.milestone === scope);
+say(`orphans: ${inScope.length}${scope === null ? '' : ` in ${scope}, of ${orphans.length}`}`);
+for (const o of inScope) say(`orphan: #${o.n} — ${o.labels.join(', ') || 'no label'} — ${o.milestone || 'no milestone'}${map.left.includes(o.n) ? ' — left alone last run' : ''} — ${o.title}`);
+const out_of = orphans.filter((o) => !inScope.includes(o) && map.left.includes(o.n)).map((o) => o.n);
+writeFileSync(join(dir, 'kept.txt'), out_of.map((n) => `${n}\n`).join(''));
+done();

package/scripts/roadmap/roadmap.md

@@ -0,0 +1,30 @@
+<!--
+  The roadmap: the one issue that never closes. Title: [roadmap] <sentence>, filed by
+  `codelife roadmap write` with the origin `roadmap`, and found by that key in a title's tag
+  (scripts/tracker/search_id.mjs). There is one; /roadmap
+  rewrites it last at every run, so an interrupted run reads the same range again.
+  It carries only what exists nowhere else — the mark, the orphans left alone and the order —
+  never a lot's progress, which is read on the lot itself.
+-->
+
+What remains to implement, in order. `/roadmap` rewrites this issue at the end of every run and
+never closes it; reorder the list below here, and the next run keeps your order.
+
+## Mark
+
+`<commit>` — the commit of `docs/spec/` the open issues are aligned with: `/roadmap` reads what
+changed from there to `HEAD`.
+
+## Left alone
+
+The orphans the last run grouped with nothing, each to work on its own — `/overview` offers them to
+`/work` — or *None.*:
+
+- #<n> <the issue's sentence>
+
+## The order
+
+The open lots, the next one first, one umbrella per line, with the lots it waits for:
+
+1. #<n> <the umbrella's sentence>
+2. #<n> <the umbrella's sentence> — after #<a>, #<b>