@assuredloop/cli 0.0.0-stage → 0.1.0

package/src/conclude.js

@@ -0,0 +1,293 @@
+// al conclude <name> [--dropped Dn] [--yes] ([STA-7], [STA-6], [REC-9]): it
+// refuses unless the sign-off is current and every held section is
+// consolidated, carried, dropped while retaining nothing ([STA-3]), or kept;
+// then it writes the Outcome, sets the Status and moves the folder to
+// requests/archive/. It prints three lines or fewer, plus the frame.
+import { existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Fail, HISTORY, cutOff, gapFail, git, historyGap, mainCommit, mainName, ownCommits } from './git.js';
+import { openTree, findRequest, noSymlinkOn } from './tree.js';
+import { rootOf, rootLine, baseline } from './spec.js';
+import { CONSOLIDATED, allBlocks, blockFault, stateText, statesOf } from './states.js';
+import { organized, parts, signoffState, signoffStep, statusAt, statusField, tierIs } from './signoff.js';
+import { requestToWrite, decisionList, childrenOf } from './commands.js';
+import { decisions } from './record-section.js';
+import { liveCode } from './views.js';
+import { filesOf, idsOn, mayTouch, ownFiles, paths, requestOf, requestsIn, sectionsChanged } from './links.js';
+import { TITLES, headingAt, prose, sameSection, sectionsById } from './sections.js';
+import { adrsOf } from './adrs.js';
+
+const NOT_KNOWN = ['whether the code does what the spec says, and whether review agreed (conclude reads only the records)'];
+
+// Each block's fate: held, kept or dropped, or why conclude refuses it.
+function fateOf(e, b, { name, dropped, blocks, signedR, ownerDecisions }) {
+  if (b.kept) {
+    if (!CONSOLIDATED.includes(e.state)) return { bad: `${e.block} is Kept but reads ${e.state}; align it before it is kept` };
+    // Its own signed R, or, when successors carry it, any one of theirs (design §5.4).
+    const traced = signedR(b) || (e.state === 'carried' && e.carriers.some((k) => signedR(blocks.get(k)))) || ownerDecisions.has(b.kept[1]);
+    return traced ? { fate: 'kept' } : { bad: `${e.block} is Kept, but traces to no signed requirement and no owner decision ([STA-6])` };
+  }
+  if (dropped || b.dropped) {
+    return e.retainsNothing ? { fate: 'dropped' }
+      : { bad: `${e.block} is dropped but possibly retained (${e.state}): al consolidate ${name} --revert ${e.id}, or keep it` };
+  }
+  return CONSOLIDATED.includes(e.state) ? { fate: 'held' }
+    : { bad: `${e.block} ${stateText(e)}` };
+}
+
+// Each section's kind in the Outcome (by its blocks' net op, or Kept or
+// Dropped), and each R's sections ([REC-9]).
+export function outcomeFacts(org, fates) {
+  const ids = new Map();
+  for (const f of fates) ids.set(f.b.id, [...(ids.get(f.b.id) ?? []), f]);
+  const kind = (fs) => {
+    const byN = [...fs].sort((x, y) => x.b.n - y.b.n);
+    if (fs.some((f) => f.fate === 'kept')) return 'Kept';
+    if (fs.some((f) => f.fate === 'dropped')) return 'Dropped';
+    return byN[0].b.op === 'add' ? 'Added' : byN.at(-1).b.op === 'remove' ? 'Removed' : 'Modified';
+  };
+  const kinds = new Map([...ids].map(([id, fs]) => [id, kind(fs)]));
+  // A tier-1 record names the sections it amends with `Amends: [ID]`: under
+  // R<n>, for R<n>; anywhere else in the organized section, for every R-line.
+  const all = org ? parts(org.text, org.oneLine) : [];
+  const isR = (x) => /^R\d+$/.test(x.key);
+  const level = (x) => x.text.match(/^\s*(#+)\s/)?.[1].length ?? 0;
+  // A part under a deeper heading inside R<n> stays in R<n>'s scope.
+  let r = null;
+  const scope = all.map((x) => (r = isR(x) ? x : r && level(x) > level(r) ? r : null)?.key ?? null);
+  const under = (key) => all.filter((x, i) => scope[i] === key).flatMap((x) => amends(x.text));
+  const everyR = under(null);
+  const rs = all.filter(isR).map((p) => ({
+    key: p.key,
+    title: p.text.split('\n')[0].replace(/^\s*#+\s+R\d+\s*/, '').replace(/^R\d+:\s*/, '').replace(/\s*\bAmends:.*$/, '').trim(),
+    ids: [...new Set([...[...ids].filter(([id, fs]) => kinds.get(id) !== 'Dropped' && fs.some((f) => f.b.forR.includes(p.key))).map(([id]) => `[${id}]`),
+      ...under(p.key), ...everyR])],
+  }));
+  return { kinds, rs };
+}
+
+// The IDs an `Amends:` names: the bracketed ones after it, on its line, out
+// of fenced code.
+export const amends = (text) => [...prose(text).matchAll(/\bAmends:([^\n]*)/g)]
+  .flatMap((m) => idsOn(m[1]).map((id) => `[${id}]`));
+
+// A tier-1 record: request folder `dir` in `tree` has no change.md, so its
+// sections come from the baseline itself ([REC-9]).
+export const noChangeMd = (tree, dir) => tree.read(`${dir}/change.md`) === null;
+
+// A request with no change.md ([REC-9]): the sections its branch added,
+// modified and removed, from `was` (the baseline at its fork) to `now`, both
+// maps of ID to text; and, against the IDs its Amends: names, the changed ones
+// it doesn't name and the named ones that didn't change.
+export function baselineLists(was, now, org, own) {
+  const named = org ? amends(org.text).map((x) => x.slice(1, -1)) : [];
+  const changed = [...new Set([...was.keys(), ...now.keys()])].filter((id) => !(was.has(id) && now.has(id) && sameSection(was.get(id), now.get(id))));
+  const ids = changed.filter((id) => own.has(id));
+  return {
+    Added: ids.filter((id) => !was.has(id)), Modified: ids.filter((id) => was.has(id) && now.has(id)), Removed: ids.filter((id) => !now.has(id)),
+    unnamed: ids.filter((id) => !named.includes(id)),
+    // "Did not change" is said of the section itself, whoever changed it.
+    unchanged: [...new Set(named)].filter((id) => !changed.includes(id)),
+  };
+}
+
+// A spike ([REC-10]) has findings.md, starting with its Answer, and changes no
+// spec: what request `name` at `dir` in `tree` misses of that, as note texts,
+// given `edited()`, the baseline IDs its own work changed. Notes only:
+// conclude still concludes.
+export function spikeNotes(tree, name, dir, md, edited) {
+  if (!tierIs(statusField(md, 'Tier'), 'S')) return [];
+  const findings = tree.read(`${dir}/findings.md`)?.toString('utf8');
+  const first = findings?.split('\n').find((l) => l.trim()) ?? '';
+  const out = [];
+  if (findings === undefined) out.push(`${name} is a spike with no findings.md ([REC-10])`);
+  else if (!/^\s*(#+\s*)?Answer\b/.test(first)) out.push(`${name}'s findings.md does not start with its Answer ([REC-10])`);
+  const ids = edited();
+  if (ids.length) out.push(`${name} is a spike, but it edits the baseline: ${ids.map((id) => `[${id}]`).join(', ')}; a spike changes no spec ([REC-10])`);
+  return out;
+}
+
+// The baseline IDs request `name`'s own work changed ([LNK-2]): in the commits
+// fork..tip that map to it, merges left out, and, when `working`, in the
+// working tree's changes not yet committed.
+export function ownIds(top, name, fork, root, requests, working, tip = 'HEAD') {
+  const ids = new Set();
+  const seen = new Map();
+  for (const sha of fork ? ownCommits(top, fork, tip) : []) {
+    if (!requestOf(top, sha, requests, seen, ownFiles).names.includes(name)) continue;
+    // A merge's own: the sections that differ from every parent. Past the
+    // shallow boundary, the fork stands in for the parent it lacks ([VW-9]).
+    const parents = ownFiles(top, sha) ? git(top, ['rev-list', '--parents', '-n', '1', sha]).split(' ').slice(1) : [fork];
+    const each = (parents.length ? parents : [`${sha}^`]).map((p) => new Set(sectionsChanged(top, p, sha, root, mayTouch(top, sha, fork))));
+    each[0].forEach((id) => each.every((s) => s.has(id)) && ids.add(id));
+  }
+  if (working) {
+    const files = [...paths(git(top, ['diff', '--name-only', '-z', 'HEAD'], { allowFail: true, worktree: true }) ?? ''), ...paths(git(top, ['ls-files', '--others', '--exclude-standard', '-z'], { worktree: true }))];
+    sectionsChanged(top, 'HEAD', null, root, files, openTree(top)).forEach((id) => ids.add(id));
+  }
+  return ids;
+}
+
+// The baseline's sections by ID in `tree`, under `root`.
+const sectionsOf = (tree, root) => sectionsById(baseline(tree, root));
+
+// baselineLists for request `name`'s own work in `tree` (at commit `at`, or the
+// working tree, its uncommitted changes included), from `fork`.
+// The fork's tree is a past tree: its root: line alone, or today's root ([VW-8]).
+const ownLists = (top, tree, at, fork, name, org) => {
+  const root = rootOf(top, tree, at);
+  const was = fork ? sectionsOf(openTree(top, fork), rootLine(top, openTree(top, fork), fork) ?? root) : sectionsOf(tree, root);
+  return baselineLists(was, sectionsOf(tree, root), org, ownIds(top, name, fork, root, requestsIn(tree), !at, at ?? 'HEAD'));
+};
+
+// The generated block of the Outcome ([REC-9]): content facts only.
+function outcome(md, org, fates, droppedBy, live, adrs, lists) {
+  const { kinds, rs } = outcomeFacts(org, fates);
+  // With no change.md, the added, modified and removed come from the baseline itself.
+  const list = (ks) => (lists && ks[0] in lists ? lists[ks[0]] : [...kinds].filter(([, k]) => ks.includes(k)).map(([id]) => id))
+    .map((id) => `[${id}]`).join(', ') || 'none';
+  const lines = droppedBy ? [`- Dropped as a whole by ${droppedBy}`] : [];
+  for (const r of rs) lines.push(`- ${r.key}${r.title ? ` ${r.title}` : ''}: ${r.ids.length ? `in ${r.ids.join(', ')}` : 'in no section'}`);
+  for (const k of ['Added', 'Modified', 'Removed', 'Dropped', 'Kept']) lines.push(`- ${k}: ${list([k])}`);
+  const all = decisionList(md);
+  lines.push(`- Decisions: ${all.filter((d) => !d.agent).map((d) => d.id).join(', ') || 'none'}`);
+  lines.push(`- Agent rulings: ${all.filter((d) => d.agent).map((d) => d.id).join(', ') || 'none'}`);
+  lines.push(`- ADRs added: ${adrs.added.map((a) => `${a.n}${a.status === 'proposed' ? ' (proposed)' : ''}`).join(', ') || 'none'}`);
+  lines.push(`- ADRs superseded: ${adrs.superseded.map((a) => a.n).join(', ') || 'none'}`);
+  // Any code still live for dropped work: all the request's for a dropped
+  // request, else only under the markers of its Dropped sections.
+  const droppedIds = [...kinds].filter(([, k]) => k === 'Dropped').map(([id]) => id);
+  const code = droppedBy || droppedIds.length ? live(droppedBy ? null : droppedIds) : [];
+  if (code === null) lines.push(`- Code still live for dropped work: ${HISTORY}`);
+  else if (code.length) lines.push(`- Code still live for dropped work: ${code.join(', ')}`);
+  return lines;
+}
+
+// request.md with the Outcome (re)generated at its place, or appended; the
+// text from its `Notes:` line on is kept.
+function withOutcome(md, generated) {
+  const block = `## ${TITLES.outcome}\n\n${generated.join('\n')}\n\n`;
+  const lines = md.split('\n');
+  const at = headingAt(lines, TITLES.outcome);
+  if (at < 0) return `${md.replace(/\s+$/, '')}\n\n${block}Notes:\n`;
+  const start = lines.slice(0, at).reduce((n, l) => n + l.length + 1, 0);
+  const after = start + lines[at].length;
+  const next = md.slice(after).search(/^#{1,2}\s/m);
+  const end = next < 0 ? md.length : after + next;
+  const notes = md.slice(start, end).search(/^Notes:/m);
+  return md.slice(0, start) + block + (notes < 0 ? 'Notes:\n' : md.slice(start + notes, end)) + md.slice(end);
+}
+
+// The value of `Status:` on the request's status line set to `status`.
+function withStatus(md, status) {
+  const lines = md.split('\n');
+  const i = statusAt(lines);
+  if (i >= 0) lines[i] = lines[i].replace(/(\bStatus:\s*)[^·]*?(\s*(?:·|$))/, `$1${status}$2`);
+  else lines.splice(lines.findIndex((l) => l.startsWith('# ')) + 1, 0, `Status: ${status}`);
+  return lines.join('\n');
+}
+
+export function conclude({ top, args, opts }) {
+  const [name] = args;
+  const tree = openTree(top);
+  const dir = requestToWrite(top, tree, name);
+  const target = `requests/archive/${name}`;
+  const moving = dir !== target;
+  const md = tree.read(`${dir}/request.md`).toString('utf8');
+  const dropped = opts.dropped !== undefined;
+  if (dropped && !decisions(md).names.includes(opts.dropped)) {
+    throw new Fail(`--dropped ${opts.dropped}: name an entry of ## ${TITLES.decisions} in ${dir}/request.md (the decision to drop it, with its source)`,
+      `write the decision, then al conclude ${name} --dropped Dn`);
+  }
+  if (!noSymlinkOn(top, `${dir}/request.md`) || !noSymlinkOn(top, target)) {
+    throw new Fail(`${dir} or ${target} is reached through a symlink; records are written only through real folders, and nothing was written`, 'make requests/ a real folder in this repo');
+  }
+  if (moving && existsSync(join(top, target))) throw new Fail(`${target} already exists; a request name is never reused`, `al context ${name}`);
+
+  const main = mainCommit(top);
+  const fork = main && git(top, ['merge-base', main, 'HEAD'], { allowFail: true });
+  // The Outcome is written as fact: a fork not in the clone, or a commit past
+  // the shallow boundary, hides what the branch changed ([VW-9]).
+  const gap = main && !fork && historyGap(top);
+  if (gap) throw gapFail(gap, `, and the merge-base of ${mainName(top)} and HEAD is not in it; nothing was written`);
+  const cut = fork ? ownCommits(top, fork, 'HEAD').filter((c) => cutOff(top, c)).map((c) => c.slice(0, 7)) : [];
+  if (cut.length) throw gapFail(historyGap(top), `, and ${cut.join(', ')} ${cut.length === 1 ? 'has its parent' : 'have their parents'} past its boundary; nothing was written`);
+  const { sign, org, fates, refusals } = judge(top, tree, name, dir, dropped, undefined, fork);
+  // [STA-7]: three lines or fewer, so reasons beyond the second share the third.
+  const body = [...refusals.slice(0, 2), ...(refusals.length > 2 ? [refusals.slice(2).join(' · ')] : [])].map((r) => `refused: ${r}`);
+  if (body.length) {
+    return {
+      refused: true, body,
+      next: sign.blocked && !dropped ? signoffStep(name, dir, sign)
+        : `al context ${name}; then consolidate, revert or keep what is named`,
+      notKnown: NOT_KNOWN,
+    };
+  }
+
+  const status = dropped ? 'dropped' : 'concluded';
+  const root = rootOf(top, tree);
+  const live = (ids) => liveCode(top, name, root, ids);
+  const adrs = adrsOf(top, tree, undefined, name, requestsIn(tree));
+  const own = () => ownLists(top, tree, undefined, fork, name, org);
+  const lists = noChangeMd(tree, dir) ? own() : null;
+  const generated = outcome(md, org, fates, opts.dropped, live, adrs, lists);
+  const text = withOutcome(withStatus(md, status), generated);
+  const children = childrenOf(md).filter((c) => c !== name && tree.read(`requests/${c}/request.md`) !== null);
+  // [STA-7]: three lines or fewer, so every note shares one line.
+  const notes = [...spikeNotes(tree, name, dir, md, () => { const l = lists ?? own(); return [...l.Added, ...l.Modified, ...l.Removed]; }),
+    ...(children.length ? [`child request ${children.join(', ')} is still open`] : []),
+    ...adrs.added.filter((a) => a.status === 'proposed').map((a) => `${a.path}, added by ${name}, is still proposed`)];
+  const note = notes.length ? [`note: ${notes.join('; ')}`] : [];
+  // [TL-1]: the text it writes, on one line ([STA-7]).
+  const what = `Status: ${status}${moving ? `, and ${dir}/ moved to ${target}/` : ''}; Outcome: ${generated.map((l) => l.replace(/^- /, '')).join(' · ')}`;
+  if (!opts.yes) return { body: [`Would conclude ${name}: ${what}`, ...note], next: 'run the same command with --yes to do it', notKnown: NOT_KNOWN };
+
+  writeFileSync(join(top, dir, 'request.md'), text);
+  if (moving) {
+    mkdirSync(join(top, 'requests/archive'), { recursive: true });
+    renameSync(join(top, dir), join(top, target));
+  }
+  return { body: [`Concluded ${name}: ${what}`, ...note], next: `review ${target}/request.md, then commit it`, notKnown: NOT_KNOWN };
+}
+
+// conclude's rules on request `name` in `tree` (at commit `at`, or the working
+// tree), its branch forked from main at `fork`: the refusals, none when it may
+// conclude, and the facts they rest on.
+export function judge(top, tree, name, dir, dropped, at, fork) {
+  const md = tree.read(`${dir}/request.md`).toString('utf8');
+  const sign = signoffState(tree, dir, name);
+  const org = organized(md);
+  const blocks = allBlocks(tree);
+  const signed = new Map();
+  const signedRs = (request) => {
+    if (!signed.has(request)) {
+      const d = findRequest(tree, request);
+      const o = d && organized(tree.read(`${d}/request.md`).toString('utf8'));
+      signed.set(request, o && !signoffState(tree, d, request).blocked ? parts(o.text, o.oneLine).map((p) => p.key) : []);
+    }
+    return signed.get(request);
+  };
+  const facts = {
+    name, dropped,
+    blocks,
+    // Whether a block's `for R<n>` names an R its request signed off, the sign-off current ([REC-5]).
+    signedR: (x) => x.forR.some((r) => signedRs(x.request).includes(r)),
+    ownerDecisions: new Set(decisionList(md).filter((d) => /\bowner\b/.test(d.source) && !d.agent).map((d) => d.id)),
+  };
+  const fates = statesOf(baseline(tree, rootOf(top, tree, at)), blocks, (b) => b.request === name)
+    .map((e) => ({ e, b: blocks.get(e.block), ...fateOf(e, blocks.get(e.block), facts) }));
+  // [STA-3]: with no change.md, a dropped request retains its own baseline
+  // changes; it has no block to revert or keep them by.
+  const lists = dropped && noChangeMd(tree, dir) && ownLists(top, tree, at, fork, name, org);
+  const retained = lists ? [...lists.Added, ...lists.Modified, ...lists.Removed] : [];
+  // [REC-6]: blocked, only a drop where every section retains nothing goes ahead.
+  const refusals = [];
+  if (sign.blocked && !(dropped && !retained.length && fates.every((f) => f.fate === 'dropped'))) refusals.push(`${name} is blocked: ${sign.reason} ([REC-6])`);
+  if (retained.length) refusals.push(`${name} is dropped but its baseline changes are retained: ${retained.map((id) => `[${id}]`).join(', ')}; revert them by hand ([STA-7])`);
+  // [SPC-5]: a block that can't be read as written is fixed before anything is judged.
+  const unreadable = [...blocks.values()].filter((b) => b.request === name).map(blockFault).filter(Boolean);
+  if (unreadable.length) refusals.push(unreadable.join(' · '));
+  const bad = fates.filter((f) => f.bad).map((f) => f.bad);
+  if (bad.length) refusals.push(bad.join(' · '));
+  return { md, sign, org, fates, refusals };
+}

package/src/consolidate.js

@@ -0,0 +1,279 @@
+// al consolidate <name> [--section <ID>] [--yes], and --revert <ID> ([STA-4]):
+// everything is validated on a copy of the baseline in memory, shown, and with
+// --yes every changed file is written at once. Only a pending block not marked
+// Dropped is written ([STA-6]); a blocked request ([REC-6]) and a duplicate ID
+// in the root ([SPC-3]) refuse.
+import { lstatSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { Fail } from './git.js';
+import { openTree, noSymlinkOn } from './tree.js';
+import { parseSections, sameSection } from './sections.js';
+import { rootOf, baseline, duplicateIds, inBaseline } from './spec.js';
+import { CONSOLIDATED, allBlocks, anchorFault, blockFault, stateText, statesOf } from './states.js';
+import { signoffState, signoffStep } from './signoff.js';
+import { requestToWrite } from './commands.js';
+
+const NOT_KNOWN = ['whether the code does what the consolidated text says (tests and review judge that)'];
+
+// `text` without its trailing blank lines (the last line keeps its newline).
+function trimEnd(text) {
+  const lines = text.split(/(?<=\n)/);
+  while (lines.length && !lines.at(-1).trim()) lines.pop();
+  return lines.join('');
+}
+const tidy = (text) => `${trimEnd(text).replace(/\n$/, '')}\n`;
+
+// The sections of `text` with offsets: `start`, `stop` (after its last
+// non-blank line) and `end` (after its trailing blank lines).
+function spans(text) {
+  let at = text.length;
+  const sections = parseSections(text);
+  at -= sections.reduce((n, s) => n + s.text.length, 0);
+  return sections.map((s) => {
+    const start = at;
+    at += s.text.length;
+    return { ...s, start, stop: start + trimEnd(s.text).length, end: at };
+  });
+}
+
+// `section` placed at `pos` in `text`: one blank line before it, and the gap
+// that stood at `pos` (at least one blank line) before what follows.
+function insertAt(text, pos, section) {
+  const before = text.slice(0, pos);
+  const rest = text.slice(pos);
+  const gap = rest.match(/^(?:[ \t]*\r?\n)*/)[0];
+  const after = rest.slice(gap.length);
+  const head = before.trim() ? `${before.replace(/\n?$/, '\n')}\n` : '';
+  return head + section + (after ? (gap || '\n') + after : '');
+}
+
+// After section `i` and the deeper headings under it.
+function afterSubtree(list, i) {
+  let j = i;
+  while (j + 1 < list.length && list[j + 1].level > list[i].level) j++;
+  return list[j].stop;
+}
+
+// A modify keeps the baseline heading's `#` count ([SPC-4] leaves it out of the comparison).
+const withLevelOf = (old, section) => section.replace(/^ {0,3}#+/, old.text.match(/^ {0,3}#+/)[0]);
+
+function removeSection(text, s) {
+  const out = text.slice(0, s.start) + text.slice(s.end);
+  return s.end === text.length ? trimEnd(out) : out;
+}
+
+// The file and section holding `id` in the in-memory baseline, if any.
+function find(texts, id) {
+  for (const [path, text] of texts) {
+    const list = spans(text);
+    const i = list.findIndex((s) => s.id === id);
+    if (i >= 0) return { path, text, list, i, section: list[i] };
+  }
+  return null;
+}
+
+// [SPC-5]: a block holds exactly one heading, and it carries the block's own ID.
+export function headingFault(b, text, side) {
+  const headings = parseSections(text);
+  if (headings.length !== 1) return `${b.key} holds ${headings.length} headings in its ${side}; a block holds exactly one ([SPC-5])`;
+  if (headings[0].id !== b.id) return `${b.key}'s heading carries ${headings[0].id ? `[${headings[0].id}]` : 'no ID'}, not [${b.id}] ([SPC-5])`;
+  return null;
+}
+
+const filesOf = (texts) => [...texts].sort(([a], [b]) => (a < b ? -1 : 1)).map(([path, text]) => ({ path, sections: parseSections(text) }));
+
+// Apply one pending block to `texts`: what it did, or why it cannot.
+function apply(texts, b, blocks) {
+  const now = b.now === null ? null : tidy(b.now);
+  if (b.op === 'add' && b.path) {
+    const text = texts.get(b.path) ?? '';
+    texts.set(b.path, insertAt(text, trimEnd(text).length, now));
+    return { did: `[${b.id}] at the end of ${b.path}`, text: now };
+  }
+  if (b.op === 'add') {
+    const at = find(texts, b.anchor);
+    if (!at) {
+      const holder = [...blocks.values()].find((x) => x.open && x.op === 'add' && x.id === b.anchor && !x.dropped);
+      return { cannot: `anchor [${b.anchor}] is not in the baseline${holder ? `: ${holder.key} holds it pending; consolidate them together, or that one first` : ''}` };
+    }
+    texts.set(at.path, insertAt(at.text, afterSubtree(at.list, at.i), now));
+    return { did: `[${b.id}] after [${b.anchor}] in ${at.path}`, text: now };
+  }
+  const at = find(texts, b.id);
+  if (b.op === 'remove') {
+    // [SPC-5]: "was first in <path>" holds only for that file's first section.
+    if (b.firstIn && (at.path !== b.firstIn || at.i !== 0)) return { cannot: `[${b.id}] is not the first section of ${b.firstIn}, as its remove says` };
+    texts.set(at.path, removeSection(at.text, at.section));
+    return { did: `the removal of [${b.id}] from ${at.path}` };
+  }
+  texts.set(at.path, at.text.slice(0, at.section.start) + withLevelOf(at.section, now) + at.text.slice(at.section.stop));
+  return { did: `[${b.id}] in place in ${at.path}`, text: withLevelOf(at.section, now) };
+}
+
+export function consolidate({ top, args, opts }) {
+  const [name] = args;
+  if (opts.revert !== undefined && opts.section !== undefined) {
+    throw new Fail('give --section or --revert, not both', `al consolidate ${name} --revert <ID>`);
+  }
+  const tree = openTree(top);
+  const dir = requestToWrite(top, tree, name);
+  const root = rootOf(top, tree);
+  const original = new Map(baseline(tree, root).map((f) => [f.path, f.text]));
+  const texts = new Map(original);
+  const blocks = allBlocks(tree);
+  const id = opts.revert ?? opts.section;
+  const mine = [...blocks.values()].filter((b) => b.request === name && (id === undefined || b.id === id));
+  if (id !== undefined && !mine.length) throw new Fail(`${name} holds no block for [${id}]`, `al context ${name}`);
+  const refuse = (reasons, next = `al context ${name}`) => ({ refused: true, body: reasons.map((r) => `refused: ${r}`), next, notKnown: NOT_KNOWN });
+
+  const dups = duplicateIds(filesOf(texts));
+  if (dups.length) {
+    return refuse(dups.map(([d, at]) => `duplicate ID [${d}] in ${at.join(' and ')}; no consolidate writes until it is fixed ([SPC-3])`),
+      'rename one copy of each duplicate ID by hand, to a new ID; an ID is never reused');
+  }
+  // [SPC-5]: a block that can't be read as written is fixed before any write, a revert included.
+  const unreadable = mine.map(blockFault).filter(Boolean);
+  if (unreadable.length) return refuse(unreadable, `fix the blocks named in ${dir}/change.md`);
+  if (opts.revert !== undefined) return revert({ top, root, name, id, mine, blocks, texts, original, opts, refuse });
+
+  const state = signoffState(tree, dir, name);
+  if (state.blocked) {
+    return refuse([`${name} is blocked: ${state.reason}; it is consolidated only once the sign-off is current ([REC-6])`],
+      signoffStep(name, dir, state));
+  }
+  const todo = mine.filter((b) => !b.dropped);
+  if (id !== undefined && !todo.length) return refuse([`every block of [${id}] in ${name} is marked Dropped, and a dropped section is not written`]);
+  const faults = todo.filter((b) => b.now !== null).map((b) => headingFault(b, b.now, 'Now')).filter(Boolean);
+  // [STA-4]: a remove's anchor is checked against the baseline as it stands before any write.
+  for (const b of todo.filter((x) => x.op === 'remove' && x.anchor)) {
+    const at = find(original, b.id);
+    const wrong = at && anchorFault(b, { path: at.path, sections: at.list });
+    if (wrong) faults.push(`${b.key} ${wrong}`);
+  }
+  if (faults.length) return refuse(faults, `fix the blocks named in ${dir}/change.md`);
+
+  // Write one pending block at a time, re-reading the states after each, so a
+  // request's own chain and an add with its anchor go together.
+  const read = () => new Map(statesOf(filesOf(texts), blocks, (b) => b.request === name).map((e) => [e.block, e]));
+  const done = [];
+  const cannot = new Map();
+  for (let progress = true; progress;) {
+    progress = false;
+    const states = read();
+    for (const b of todo) {
+      if (done.some((d) => d.key === b.key) || states.get(b.key).state !== 'pending') continue;
+      const r = apply(texts, b, blocks);
+      if (r.cannot) { cannot.set(b.key, r.cannot); continue; }
+      cannot.delete(b.key);
+      done.push({ key: b.key, did: r.did, text: r.text });
+      progress = true;
+      break;
+    }
+  }
+  const final = read();
+  const reasons = todo.filter((b) => !CONSOLIDATED.includes(final.get(b.key).state)).map((b) => {
+    const e = final.get(b.key);
+    return `${b.key} ${cannot.get(b.key) ?? stateText(e)}`;
+  });
+  if (reasons.length) return refuse(reasons);
+  if (!done.length) return { body: [`nothing to write: ${name}'s ${id === undefined ? 'sections are' : `[${id}] is`} consolidated or carried`], next: `al context ${name}`, notKnown: NOT_KNOWN };
+  return write(top, root, original, texts, done.map((d) => ({ did: `${d.did}, from ${d.key}`, text: d.text })), opts.yes, name);
+}
+
+// --revert <ID>: the "was" of the request's first block for the ID goes back.
+function revert({ top, root, name, id, mine, blocks, texts, original, opts, refuse }) {
+  const first = mine.reduce((m, b) => (b.n < m.n ? b : m));
+  // A Dropped marker never lifts the guard: carried is read as if no block were dropped ([STA-6]).
+  const undropped = new Map([...blocks].map(([k, b]) => [k, { ...b, dropped: null, requestDropped: false }]));
+  const carried = statesOf(filesOf(texts), undropped, (b) => mine.some((m) => m.key === b.key))
+    .find((e) => e.state === 'carried' && !e.by.startsWith(`${name}/`));
+  if (carried) return refuse([`[${id}] is carried by ${carried.by}; a section carried by a successor is not reverted, only kept ([STA-6])`]);
+  const fault = first.was !== null && headingFault(first, first.was, 'Was');
+  if (fault) return refuse([fault], `fix the block named in its change.md`);
+  const at = find(texts, id);
+  let did = null;
+  let text = null;
+  if (first.op === 'add') {
+    if (at) {
+      texts.set(at.path, removeSection(at.text, at.section));
+      did = `the removal of [${id}] from ${at.path}`;
+    }
+  } else if (at) {
+    if (!sameSection(at.section.text, first.was)) {
+      text = withLevelOf(at.section, tidy(first.was));
+      texts.set(at.path, at.text.slice(0, at.section.start) + text + at.text.slice(at.section.stop));
+      did = `the "was" of [${id}] in place in ${at.path}`;
+    }
+  } else if (mine.find((b) => b.op === 'remove')?.firstIn) {
+    // [STA-4]: a removed first section goes back first in its file, after any text before it.
+    const path = mine.find((b) => b.op === 'remove').firstIn;
+    const file = texts.get(path) ?? '';
+    text = tidy(first.was);
+    texts.set(path, insertAt(file, spans(file)[0]?.start ?? file.length, text));
+    did = `[${id}] back first in ${path}`;
+  } else {
+    const removal = mine.find((b) => b.op === 'remove' && b.anchor);
+    const anchor = removal?.anchor;
+    const where = anchor ? find(texts, anchor) : null;
+    if (!where) {
+      return refuse([`[${id}] cannot be put back: ${anchor ? `its anchor [${anchor}] is not in the baseline` : 'it is not in the baseline, and no remove records where it stood'}`]);
+    }
+    // A shallower anchor is the parent: the section goes back first under it.
+    // The removal's Was, which the check held against the anchor, says which.
+    const unread = headingFault(removal, removal.was, 'Was');
+    if (unread) return refuse([unread], `fix the block named in its change.md`);
+    const under = where.section.level < parseSections(removal.was)[0].level;
+    text = tidy(first.was);
+    texts.set(where.path, insertAt(where.text, under ? where.section.stop : afterSubtree(where.list, where.i), text));
+    did = `[${id}] back ${under ? 'first under' : 'after'} [${anchor}] in ${where.path}`;
+  }
+  if (!did) return { body: [`nothing to write: [${id}] already reads the "was" of ${first.key}`], next: `al context ${name}`, notKnown: NOT_KNOWN };
+  return write(top, root, original, texts, [{ did: `${did}, from ${first.key}`, text }], opts.yes, name);
+}
+
+// Show the writes, each with the section text it writes ([TL-1]), or with
+// --yes write every changed file at once: each to a new temporary file
+// beside it, then all renamed into place. Every file written
+// is a .md file under the root, reached through real folders inside the repo,
+// and is a regular file or not there yet. If any step fails, the files already
+// renamed are put back and the temporary files removed, so nothing is written.
+function write(top, root, original, texts, what, yes, name) {
+  const changed = [...texts].filter(([path, text]) => original.get(path) !== text);
+  for (const [path] of changed) {
+    let kind = null;
+    try { kind = lstatSync(join(top, path)); } catch { /* not there yet */ }
+    if (!inBaseline(path, root) || !noSymlinkOn(top, path) || (kind && !kind.isFile())) {
+      throw new Fail(`${path}: consolidate writes only .md files under the baseline root ${root}/, named in plain form, inside this repo, not through a symlink and not over a folder; nothing was written`,
+        `fix the path in the block's heading in change.md, e.g. add in ${root}/<area>.md`);
+    }
+  }
+  const shown = (verb) => what.flatMap((w) => [`${verb} ${w.did}`, ...(w.text ? w.text.replace(/\n$/, '').split('\n') : [])]);
+  if (!yes) return { body: shown('Would write'), next: 'run the same command with --yes to write it', notKnown: NOT_KNOWN };
+  const temps = [];
+  const renamed = [];
+  try {
+    for (const [path, text] of changed) {
+      mkdirSync(dirname(join(top, path)), { recursive: true });
+      const tmp = join(top, dirname(path), `.${basename(path)}.al-${process.pid}`);
+      writeFileSync(tmp, text, { flag: 'wx' }); // a new file: never through or over what is there
+      temps.push([tmp, path]);
+    }
+    for (const [tmp, path] of temps) {
+      renameSync(tmp, join(top, path));
+      renamed.push(path);
+    }
+  } catch (e) {
+    for (const path of renamed) {
+      if (original.has(path)) writeFileSync(join(top, path), original.get(path));
+      else rmSync(join(top, path), { force: true });
+    }
+    for (const [tmp] of temps) rmSync(tmp, { force: true });
+    throw new Fail(`could not write the baseline (${e.code ?? e.message}${e.path ? ` at ${e.path}` : ''}); every file was put back as it was, and nothing was written`,
+      'remove what is in the way, then run the same command again');
+  }
+  return {
+    body: shown('Wrote'),
+    next: `review the diff of ${changed.map(([p]) => p).join(', ')} and commit it; then al context ${name}`,
+    notKnown: NOT_KNOWN,
+  };
+}