@assuredloop/cli 0.0.0-stage → 0.1.0

package/src/links.js

@@ -0,0 +1,181 @@
+// Rough links, derived when read and never kept ([LNK-1]): a bracketed ID,
+// blame, files changed together, and shared words; and a commit's request
+// ([LNK-2]): a Request: line, else the request folder it touched, else an
+// issue number in a request's owner's words.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { HISTORY, cutOff, day, git } from './git.js';
+import { folderOf, requestDirs } from './tree.js';
+import { ID_TEXT, TITLES, parseSections, sameSection, sectionsById } from './sections.js';
+import { entriesOf } from './commands.js';
+
+export const WIDE = 30;
+const REQUEST_LINE = /^[ \t]*(?:[-*][ \t]+)?Request:[ \t]*([a-z0-9][a-z0-9-]*)[ \t]*$/gm;
+const ID_MARK = new RegExp(`\\[(${ID_TEXT})\\]`, 'g');
+const STOP = new Set(['must', 'with', 'from', 'that', 'this', 'each', 'when', 'have', 'into', 'than', 'then', 'only', 'also', 'more', 'none', 'what', 'which', 'their', 'there', 'they', 'will', 'shall', 'should']);
+
+export const paths = (out) => (out ?? '').split('\0').filter(Boolean);
+export const idsOn = (line) => [...line.matchAll(ID_MARK)].map((m) => m[1]);
+export const cites = (text, id) => text.includes(`[${id}]`);
+
+// The words of a heading or a path, for link 4: split on non-letters and at
+// camelCase, lowercased, four letters or more, without a few common words.
+export const wordsOf = (text) => new Set(text.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z]+/)
+  .filter((w) => w.length >= 4 && !STOP.has(w)));
+
+// Every request in `tree`, open or archived, with its records.
+export function requestsIn(tree) {
+  return requestDirs(tree).map((r) => ({ ...r, md: tree.read(`${r.dir}/request.md`)?.toString('utf8') ?? '', change: tree.read(`${r.dir}/change.md`)?.toString('utf8') ?? '' }))
+    .filter((r) => r.md);
+}
+
+// The files a commit changed, against its first parent (all of them for a root
+// commit); null, unknown, for one whose parent is past the shallow boundary ([VW-9]).
+export function filesOf(top, sha) {
+  const parent = git(top, ['rev-parse', '--verify', '--quiet', `${sha}^1`], { allowFail: true });
+  if (!parent && cutOff(top, sha)) return null;
+  return paths(parent ? git(top, ['diff', '--name-only', '-z', '--no-renames', parent, sha])
+    : git(top, ['diff-tree', '-r', '-z', '--no-commit-id', '--name-only', '--root', sha]));
+}
+
+// The files a commit changed on its own: for a merge, those that differ from
+// every parent (an edit made while merging), never what it brought from
+// either side; for any other commit, filesOf (null when unknown).
+export function ownFiles(top, sha) {
+  if (!git(top, ['rev-parse', '--verify', '--quiet', `${sha}^2`], { allowFail: true })) return filesOf(top, sha);
+  return paths(git(top, ['diff-tree', '-r', '-z', '--no-commit-id', '--name-only', '-c', sha]));
+}
+
+// For a read bounded by the branch's final state: a commit's own files, or,
+// when they are unknown, those that differ from the fork `base` (every file of
+// its tree with no fork); never to say what it changed ([VW-9]).
+export const mayTouch = (top, sha, base, files = ownFiles) => files(top, sha)
+  ?? paths(git(top, base ? ['diff', '--name-only', '-z', '--no-renames', base, sha] : ['ls-tree', '-r', '-z', '--name-only', sha]));
+
+// The commits up to `rev` that map to request `name`, by every route [LNK-2]
+// maps by: a Request: line, its folder, an issue number in its owner's words
+// (`issues`, such as ['#123']). Each as requestOf gives it.
+export function requestCommits(top, name, issues, rev, requests, seen = new Map()) {
+  const shas = [...new Set([
+    ...git(top, ['log', '-E', `--grep=^[[:space:]]*([-*][[:space:]]+)?Request:[[:space:]]*${name}[[:space:]]*$`, '--format=%H', rev]).split('\n'),
+    ...git(top, ['log', '--format=%H', rev, '--', `requests/${name}/`, `requests/archive/${name}/`]).split('\n'),
+    ...issues.flatMap((n) => git(top, ['log', '-E', `--grep=${n}([^0-9]|$)`, '--format=%H', rev]).split('\n')),
+  ].filter(Boolean))];
+  return shas.map((sha) => requestOf(top, sha, requests, seen)).filter((c) => c.names.includes(name));
+}
+
+// The request a commit maps to ([LNK-2]): { names, how, when }, cached in `seen`.
+// `files` gives a commit's files for the folder route (ownFiles for a branch's commits).
+export function requestOf(top, sha, requests, seen = new Map(), files = filesOf) {
+  if (seen.has(sha)) return seen.get(sha);
+  const [when, ...body] = git(top, ['show', '-s', '--format=%ct%n%B', sha]).split('\n');
+  const message = body.join('\n');
+  let names = [...new Set([...message.matchAll(REQUEST_LINE)].map((m) => m[1]))];
+  let how = 'Request: line';
+  let fs;
+  if (!names.length) {
+    fs = files(top, sha);
+    names = [...new Set((fs ?? []).map(folderOf).filter(Boolean))];
+    how = names.length > 1 ? 'folder, ambiguous' : 'folder';
+  }
+  for (const [, n] of names.length ? [] : message.matchAll(/#(\d+)(?!\d)/g)) {
+    names = requests.filter((r) => new RegExp(`#${n}(?!\\d)`).test(entriesOf(r.md, TITLES.words).join('\n'))).map((r) => r.name);
+    how = `issue #${n}`;
+    if (names.length) break;
+  }
+  // Its files unknown, the folder route is too: not "no request" ([VW-9]).
+  const found = { sha, names, how: names.length ? how : fs === null ? HISTORY : 'no request', when: new Date(Number(when) * 1000) };
+  seen.set(sha, found);
+  return found;
+}
+
+// `a, b by <how>`, or `no request (<sha> <date>)`.
+export const describe = (c) => (c.names.length ? `${c.names.join(', ')} by ${c.how}` : `no request (${c.sha.slice(0, 7)} ${day(c.when)})`);
+
+// The commits .git-blame-ignore-revs lists, as it is at `at` (the working
+// tree when null), each one that git knows as `--ignore-rev <sha>`.
+function ignored(top, at) {
+  const file = join(top, '.git-blame-ignore-revs');
+  const text = at ? git(top, ['show', `${at}:.git-blame-ignore-revs`], { allowFail: true }) : existsSync(file) ? readFileSync(file, 'utf8') : null;
+  return (text ?? '').split('\n').map((l) => l.replace(/#.*/, '').trim()).filter(Boolean)
+    .filter((r) => git(top, ['rev-parse', '--verify', '--quiet', `${r}^{commit}`], { allowFail: true }))
+    .flatMap((r) => ['--ignore-rev', r]);
+}
+
+// Blame of `ranges` ([from, to] pairs) of `path` at `rev` (the working tree when
+// null): each line's commit and time. -w -M always, -C for code, and the
+// project's .git-blame-ignore-revs as it is at `ignoreAt` (by default `rev`,
+// so a view of commits reads only committed records) ([LNK-1] #2).
+export function blame(top, rev, path, ranges, { code, ignoreAt = rev }) {
+  if (!ranges.length) return [];
+  // --ignore-revs-file '' first clears any file git's own config names (blame.ignoreRevsFile).
+  const out = git(top, ['blame', '--porcelain', '-w', '-M', ...(code ? ['-C'] : []), '--ignore-revs-file', '', ...ignored(top, ignoreAt),
+    ...ranges.flatMap(([a, b]) => ['-L', `${a},${b}`]), ...(rev ? [rev] : []), '--', path], { allowFail: true, worktree: !rev }) ?? '';
+  const result = [];
+  const times = new Map();
+  for (const l of out.split('\n')) {
+    const h = l.match(/^([0-9a-f]{40}) \d+ (\d+)/);
+    if (h) result.push({ sha: h[1], line: Number(h[2]) });
+    const t = l.match(/^committer-time (\d+)/);
+    if (t) times.set(result.at(-1).sha, Number(t[1]));
+  }
+  return result.map((r) => ({ ...r, when: new Date((times.get(r.sha) ?? 0) * 1000) }));
+}
+
+// The sections by ID in a Markdown text.
+export const byId = (text) => sectionsById([{ sections: parseSections(text) }]);
+
+// The IDs of the baseline sections that differ between two revs (or that one
+// of them lacks), over the root's Markdown files among `files`.
+export function sectionsChanged(top, from, to, root, files, tree) {
+  const ids = [];
+  for (const f of files.filter((p) => p.startsWith(`${root}/`) && p.endsWith('.md'))) {
+    // `to` null with a `tree`: the working tree's text.
+    const show = (rev) => byId(rev ? git(top, ['show', `${rev}:${f}`], { allowFail: true }) ?? '' : tree?.read(f)?.toString('utf8') ?? '');
+    const [a, b] = [show(from), show(to)];
+    for (const id of new Set([...a.keys(), ...b.keys()])) if (!(a.has(id) && b.has(id) && sameSection(a.get(id), b.get(id)))) ids.push(id);
+  }
+  return ids;
+}
+
+// The sections found in another file of `after` than in `before` (baseline
+// files, each with its sections), their text unchanged ([SPC-4]): { id, from, to }.
+export function movesOf(before, after) {
+  const where = (files) => new Map(files.flatMap((f) => f.sections.filter((s) => s.id).map((s) => [s.id, { path: f.path, text: s.text }])));
+  const [was, now] = [where(before), where(after)];
+  return [...now].filter(([id, n]) => was.has(id) && was.get(id).path !== n.path && sameSection(was.get(id).text, n.text))
+    .map(([id, n]) => ({ id, from: was.get(id).path, to: n.path }));
+}
+
+// Link 3: the commits (up to `rev`) that changed `path`, with their files;
+// commits over 30 files are skipped and counted.
+export function changedWith(top, rev, path) {
+  const commits = [];
+  let skipped = 0;
+  for (const sha of git(top, ['log', '--format=%H', rev, '--', path]).split('\n').filter(Boolean)) {
+    const files = filesOf(top, sha);
+    if (!files) continue;
+    if (files.length > WIDE) skipped++;
+    else commits.push({ sha, files });
+  }
+  return { commits, skipped };
+}
+
+// Link 1 for a change at new-side line `at` (the first changed line) of a file:
+// the IDs on the changed lines, each at the first line naming it, else the
+// nearest [ID] line above, at `at` with its distance.
+export function idNear(fileLines, at, changed) {
+  const on = new Map();
+  for (const n of changed) for (const id of idsOn(fileLines[n - 1] ?? '')) if (!on.has(id)) on.set(id, n);
+  if (on.size) return [...on].map(([id, line]) => ({ id, line, reason: `names [${id}] on the changed line` }));
+  for (let n = at - 1; n >= 1; n--) {
+    const ids = idsOn(fileLines[n - 1] ?? '');
+    if (ids.length) return ids.map((id) => ({ id, line: at, reason: `names [${id}], ${at - n} line${at - n === 1 ? '' : 's'} above` }));
+  }
+  return [];
+}
+
+// Ranges of line numbers, as `a-b` or `a`.
+export const ranges = (numbers) => [...numbers].sort((x, y) => x - y)
+  .reduce((out, n) => (out.length && out.at(-1)[1] === n - 1 ? (out.at(-1)[1] = n, out) : [...out, [n, n]]), [])
+  .map(([a, b]) => (a === b ? `${a}` : `${a}-${b}`));

package/src/record-section.js

@@ -0,0 +1,126 @@
+// al record <name> section <ID> [--builds-on <request>] [--accept] [--decision Dn] [--yes]
+// ([STA-5], [TL-1]): hold a baseline section, build on another request's
+// block, revise one's own block under an existing decision, or accept the
+// text underneath. Shows what it would write, and writes on --yes.
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Fail, day, historyGap, now } from './git.js';
+import { openTree, noSymlinkOn, findRequest, isName } from './tree.js';
+import { rootOf, baseline, idsUsed, nextId } from './spec.js';
+import { blockFault, parseChange, takeText, withRepeats } from './states.js';
+import { BAD_NAME, decisionList, requestToWrite } from './commands.js';
+import { headingFault } from './consolidate.js';
+import { TITLES, headingAt } from './sections.js';
+
+const indent = (text) => text.replace(/\n+$/, '').split('\n').map((l) => (l ? `    ${l}` : '')).join('\n') + '\n';
+const render = (head, was, now) => `### ${head}\n` + (was != null ? `Was:\n\n${indent(was)}\n` : '') + (now != null ? `Now:\n\n${indent(now)}\n` : '');
+
+// The line range of block `<ID>@<n>` in change.md: from its heading to the next `### ` heading.
+function range(lines, id, n) {
+  const start = lines.findIndex((l) => l.startsWith(`### [${id}]@${n} `) || l === `### [${id}]@${n}`);
+  let end = start + 1;
+  while (end < lines.length && !/^#{2,3}\s/.test(lines[end])) {
+    if (/^(Was|Now):\s*$/.test(lines[end].trim())) end = takeText(lines, end + 1).next;
+    else end++;
+  }
+  return { start, end };
+}
+
+// The D-numbers of the entries in request.md's `## Decisions` (to the next
+// level-1/2 heading), and where the next entry goes.
+export function decisions(md) {
+  const lines = md.split('\n');
+  const at = headingAt(lines, TITLES.decisions);
+  let end = lines.length;
+  if (at >= 0) for (let i = at + 1; i < lines.length; i++) if (/^#{1,2}\s/.test(lines[i])) { end = i; break; }
+  const names = decisionList(md).map((d) => d.id);
+  const ids = names.map((n) => Number(n.slice(1)));
+  let last = end;
+  while (last > at + 1 && !lines[last - 1].trim()) last--;
+  return { at, ids, names, insertAt: last, lines };
+}
+
+export function recordSection({ top, args, opts }) {
+  const [name, , id] = args;
+  const tree = openTree(top);
+  const dir = requestToWrite(top, tree, name);
+  if (!id) throw new Fail('which section? al record <name> section <ID>', `al record ${name} section <ID>`);
+  const changePath = `${dir}/change.md`;
+  const reqPath = `${dir}/request.md`;
+  if (!noSymlinkOn(top, changePath) || !noSymlinkOn(top, reqPath)) {
+    throw new Fail(`${dir} is reached through a symlink; records are written only through real folders, and nothing was written`, `make ${dir} a real folder in this repo`);
+  }
+  const change = tree.read(changePath)?.toString('utf8') ?? null;
+  const md = tree.read(reqPath).toString('utf8');
+  const mine = change ? parseChange(change, name).filter((b) => b.id === id) : [];
+  const latest = mine.reduce((m, b) => (!m || b.n > m.n ? b : m), null);
+  const section = baseline(tree, rootOf(top, tree)).flatMap((f) => f.sections).find((s) => s.id === id);
+  const underneath = section ? section.text.replace(/\n+$/, '\n') : null;
+  const date = day(now());
+  const notKnown = ['whether the new text is right (review judges that)'];
+  let newChange;
+  let newRequest = md;
+  let shown;
+
+  if (opts.accept) {
+    if (!latest || !underneath) throw new Fail(`--accept needs a block of ${name} holding [${id}] and [${id}] in the baseline`, `al context ${name}`);
+    const lines = change.split('\n');
+    const { start, end } = range(lines, id, latest.n);
+    const head = lines[start].slice(4);
+    newChange = [...lines.slice(0, start), render(head, latest.was, underneath).replace(/\n$/, ''), ...lines.slice(end)].join('\n');
+    const { at, ids, insertAt, lines: mdLines } = decisions(md);
+    const d = `- D${Math.max(0, ...ids) + 1}, ${date}. Source: the agent. Accepted the text underneath [${id}] as the new "now" for ${latest.key}.`;
+    newRequest = at < 0 ? `${md.replace(/\n*$/, '\n')}\n## ${TITLES.decisions}\n\n${d}\n`
+      : [...mdLines.slice(0, insertAt), d, ...mdLines.slice(insertAt)].join('\n');
+    shown = [`${latest.key}: Now becomes the text underneath:`, ...underneath.replace(/\n$/, '').split('\n'), `and request.md gets: ${d}`];
+  } else if (latest) {
+    if (opts['builds-on']) throw new Fail(`${name} already holds [${id}] (${latest.key}); a new version builds on it`, `al record ${name} section ${id} --decision Dn`);
+    const d = opts.decision;
+    if (!decisions(md).names.includes(d)) {
+      throw new Fail(`a revision of ${latest.key} needs --decision Dn naming an entry in ## ${TITLES.decisions}: write the decision first (why, and its source), then pass --decision Dn`,
+        `write the decision in ${reqPath}, then al record ${name} section ${id} --decision Dn`);
+    }
+    const lines = change.split('\n');
+    const { start, end } = range(lines, id, latest.n);
+    const marked = `${lines[start]}   Revised ${date} (${d})`;
+    const next = render(`[${id}]@${latest.n + 1} modify`, latest.now, latest.now);
+    newChange = [...lines.slice(0, start), marked, ...lines.slice(start + 1, end), next, ...lines.slice(end)].join('\n');
+    shown = [`${latest.key} is marked Revised ${date} (${d}), and after it:`, ...next.replace(/\n$/, '').split('\n')];
+  } else {
+    let head = `[${id}]@1 modify`;
+    let text = underneath;
+    if (opts['builds-on']) {
+      const other = opts['builds-on'];
+      if (!isName(other)) throw new Fail(BAD_NAME(other), `al record ${name} section ${id} --builds-on <request>`);
+      const dir = findRequest(tree, other);
+      if (!dir) throw new Fail(`no request named ${other} in the ${tree.label}`, 'al context for the requests there are');
+      const theirs = parseChange(tree.read(`${dir}/change.md`)?.toString('utf8') ?? '', other).filter((b) => b.id === id);
+      const top1 = theirs.reduce((m, b) => (!m || b.n > m.n ? b : m), null);
+      if (!top1) throw new Fail(`${other} holds no block for [${id}]`, `al context ${other}`);
+      head += `   builds on ${top1.key}`;
+      text = top1.now;
+    } else if (!underneath) {
+      // [SPC-3]: a new section takes the next ID ever free for its prefix.
+      const prefix = id.split('-')[0];
+      const root = rootOf(top, tree);
+      const gap = historyGap(top);
+      if (gap) throw new Fail(`[${id}] is in neither the baseline nor ${name}, and the next free ${prefix} ID is not known: this clone is ${gap.kind}, without the full history`, gap.next);
+      const free = nextId(idsUsed(top, tree, root), prefix);
+      throw new Fail(`[${id}] is in neither the baseline nor ${name}. A new section takes the next free ${prefix} ID, [${free}]: write its block by hand in ${changePath}, headed ### [${free}]@1 add in ${root}/<file>.md (or add after [ID]), then Now: and the section, indented`,
+        `edit ${changePath}, then al context ${name}`);
+    }
+    const block = render(head, text, text);
+    const base = change ?? `## ${TITLES.specChanges}\n`;
+    const withSpec = headingAt(base.split('\n'), TITLES.specChanges) >= 0 ? base : `${base.replace(/\n*$/, '\n')}\n## ${TITLES.specChanges}\n`;
+    newChange = `${withSpec.replace(/\n*$/, '\n')}\n${block}`;
+    shown = block.replace(/\n$/, '').split('\n');
+  }
+
+  // [SPC-5]: the request's blocks that break the one-heading rule, said; drafting is never refused.
+  const faults = withRepeats(change ? parseChange(change, name) : []).flatMap((b) => [blockFault(b), ...[[b.now, 'Now'], [b.was, 'Was']].map(([t, side]) => t !== null && headingFault(b, t, side))])
+    .filter(Boolean).map((f) => `not ok: ${f}; fix it in ${changePath}, then al context ${name}`);
+  if (!opts.yes) return { body: ['Would write:', ...shown, ...faults], next: 'run the same command with --yes to write it', notKnown };
+  writeFileSync(join(top, changePath), newChange);
+  if (newRequest !== md) writeFileSync(join(top, reqPath), newRequest);
+  return { body: ['Wrote:', ...shown, ...faults], next: `al context ${name}`, notKnown };
+}

package/src/sections.js

@@ -0,0 +1,125 @@
+// Sections and their IDs ([SPC-2]), and when two sections are the same ([SPC-4]).
+
+// An ATX heading as in CommonMark: 0-3 spaces, 1-6 `#`, then a space, a tab or
+// the end of the line. Groups: the marks, the gap after them, the heading text.
+const HEADING = /^( {0,3}#{1,6})([ \t]+|$)(.*)$/;
+// The ID grammar ([SPC-2]): a prefix of capitals and digits, starting with a
+// capital, a hyphen, then numbers joined by dots. Every pattern for an ID is
+// built from these.
+export const PREFIX_TEXT = '[A-Z][A-Z0-9]*';
+export const ID_TEXT = `${PREFIX_TEXT}-\\d+(?:\\.\\d+)*`;
+const ID = new RegExp(`^\\[(${ID_TEXT})\\][ \\t]*`);
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+
+// The titles of the record sections the tool reads and writes: request.md's
+// ([REC-2], [REC-7], [REC-8], [REC-9]) and change.md's ([SPC-5]).
+export const TITLES = { words: "Owner's words and dialog", decisions: 'Decisions', parts: 'Parts', outcome: 'Outcome', specChanges: 'Spec changes' };
+
+// The index among `lines` of the line that heads a record's `## <title>`
+// section, or -1: one form for every reader and writer.
+export const headingAt = (lines, title) => lines.findIndex((l) => new RegExp(`^##\\s+${title}\\s*$`).test(l));
+
+// Whether `line` closes the fence `fence` opened: 0-3 spaces, then the same
+// mark, at least as long, and nothing else.
+export function closes(line, fence) {
+  const f = line.match(FENCE);
+  return Boolean(f && f[1][0] === fence[0] && f[1].length >= fence.length && line.trim() === f[1]);
+}
+
+// Each line of `text` with its ending, whether it is a heading, and whether it
+// is fenced code (a fence line included): lines in fenced code are not
+// headings, and indented code never matches HEADING.
+function scan(text) {
+  const lines = text.split(/(?<=\n)/);
+  let fence = null;
+  return lines.map((raw) => {
+    const line = raw.replace(/\r?\n$/, '');
+    const f = line.match(FENCE);
+    if (fence) {
+      if (closes(line, fence)) fence = null;
+      return { raw, heading: null, code: true };
+    }
+    if (f) {
+      fence = f[1];
+      return { raw, heading: null, code: true };
+    }
+    return { raw, heading: line.match(HEADING), code: false };
+  });
+}
+
+// For each line of `text` (split after each newline), whether it is fenced code.
+export const codeLines = (text) => scan(text).map((l) => l.code);
+
+// `text` without its fenced code.
+export const prose = (text) => scan(text).filter((l) => !l.code).map((l) => l.raw).join('');
+
+// A section is one heading and the text up to the next heading of any level.
+export function parseSections(text) {
+  const sections = [];
+  scan(text).forEach(({ raw, heading }, i) => {
+    if (heading) {
+      const content = heading[3].trim();
+      const id = content.match(ID);
+      sections.push({
+        id: id ? id[1] : null,
+        level: heading[1].trim().length,
+        title: id ? content.slice(id[0].length) : content,
+        text: raw,
+        line: i + 1,
+      });
+    } else if (sections.length) {
+      sections.at(-1).text += raw;
+    }
+  });
+  return sections;
+}
+
+// The sections of `files` (each with its `sections`) by ID, each as `pick` gives it (its text
+// by default); of a duplicate ID the first copy counts, as in statesOf and
+// consolidate ([SPC-3]).
+export function sectionsById(files, pick = (s) => s.text) {
+  const byId = new Map();
+  for (const f of files) for (const s of f.sections) if (s.id && !byId.has(s.id)) byId.set(s.id, pick(s, f));
+  return byId;
+}
+
+// The text outside every section with an ID, one piece each: before the
+// first heading, then each section whose heading has none.
+export function unheld(text) {
+  const sections = parseSections(text);
+  return [text.slice(0, text.length - sections.reduce((n, s) => n + s.text.length, 0)), ...sections.filter((s) => !s.id).map((s) => s.text)];
+}
+
+// `text` with every heading that has no ID given `[<prefix>-n] `, n counting
+// up from `first`; everything else byte for byte. Returns the new text and the
+// headings it numbered.
+export function numberHeadings(text, prefix, first) {
+  let n = first;
+  const numbered = [];
+  const out = scan(text).map(({ raw, heading }) => {
+    if (!heading || heading[3].trim().match(ID)) return raw;
+    const id = `[${prefix}-${n++}]`;
+    const line = heading[3] === '' ? `${heading[1]} ${id}` : `${heading[1]}${heading[2]}${id} ${heading[3]}`;
+    numbered.push(line);
+    return line + raw.slice(raw.replace(/\r?\n$/, '').length);
+  });
+  return { text: out.join(''), numbered };
+}
+
+// Normalized only as [SPC-4] allows: line endings, trailing spaces and tabs,
+// blank lines at the edges and after the heading, and the heading's `#` count.
+function normalize(text) {
+  const lines = text.replace(/\r\n/g, '\n').split('\n').map((l) => l.replace(/[ \t]+$/, ''));
+  while (lines.length && lines[0] === '') lines.shift();
+  while (lines.length && lines.at(-1) === '') lines.pop();
+  const heading = lines.length ? lines[0].match(HEADING) : null;
+  if (heading) {
+    lines[0] = lines[0].replace(/#+/, '#');
+    while (lines.length > 1 && lines[1] === '') lines.splice(1, 1);
+  }
+  return lines.join('\n');
+}
+
+export function sameSection(a, b) {
+  return normalize(a) === normalize(b);
+}

package/src/signoff.js

@@ -0,0 +1,166 @@
+// The organized section ([REC-4]), its sign-offs ([REC-5]) and the blocked
+// state ([REC-6]). Everything is judged from the text in the files, never from
+// commits, so a squash changes nothing.
+import { codeLines, parseSections, prose, sameSection } from './sections.js';
+import { isSignoff, snapshots } from './snapshot.js';
+import { childrenOf } from './commands.js';
+import { requestDirs } from './tree.js';
+
+const ORGANIZED = /^Organized (requirement|question)$/;
+export const SIGNED_OFF = /^Signed off:/;
+
+// [REC-4]: only a tier-1 request (`Tier: 1` on its status line) MAY write a
+// requirement as one line, `R1: …`.
+// Whether a tier claim, such as `0 — a fix`, is tier `t`.
+export const tierIs = (claim, t) => new RegExp(`^${t}\\b`).test(claim ?? '');
+
+export const tierOne = (md) => tierIs(statusField(md, 'Tier'), '1');
+
+// The index of request.md's status line among its `lines`: the first with `Status:`.
+export const statusAt = (lines) => lines.findIndex((l) => /\bStatus:/.test(l));
+
+// The value of `key` (Status, Tier, Follows…) on request.md's status line, up
+// to the next `·`, trimmed; undefined when the line has none.
+export const statusField = (md, key) => {
+  const lines = md.split('\n');
+  return (lines[statusAt(lines)] ?? '').match(new RegExp(`\\b${key}:\\s*([^·]+)`))?.[1].trim();
+};
+export const isDropped = (md) => /^dropped\b/.test(statusField(md, 'Status') ?? '');
+// The request names after `Follows:`.
+export const follows = (md) => statusField(md, 'Follows')?.split(/[\s,]+/).filter(Boolean) ?? [];
+
+// The organized section of request.md: from its heading to the next heading of
+// level 1 or 2, without any `Signed off:` line. `start` and `end` are offsets
+// in `md`; `text` is what a sign-off binds; `oneLine`, whether `R1: …` lines
+// are requirements.
+export function organized(md) {
+  const sections = parseSections(md);
+  let offset = md.length - sections.reduce((n, s) => n + s.text.length, 0);
+  let found = null;
+  for (const s of sections) {
+    if (found && s.level <= 2) break;
+    if (!found && s.level <= 2 && ORGANIZED.test(s.title)) found = { start: offset, raw: '' };
+    if (found) found.raw += s.text;
+    offset += s.text.length;
+  }
+  if (!found) return null;
+  const text = found.raw.split(/(?<=\n)/).filter((l) => !SIGNED_OFF.test(l)).join('');
+  return { start: found.start, end: found.start + found.raw.length, raw: found.raw, text, oneLine: tierOne(md) };
+}
+
+// The parts of an organized section: the intro, each `### R<n>` sub-section,
+// and the `Out:` and `Assumed:` paragraphs, and, when `oneLine`, each `R<n>:`
+// line. Parts with no text are left out. A line in fenced code is text of the
+// part it sits in.
+export function parts(text, oneLine = false) {
+  const out = [];
+  let current = { key: 'intro', text: '' };
+  const lines = text.split(/(?<=\n)/).slice(1);
+  const code = codeLines(text).slice(1);
+  const subheads = new Set(parseSections(text).filter((s) => s.level >= 3).map((s) => s.line - 2));
+  lines.forEach((line, i) => {
+    let key = null;
+    if (subheads.has(i)) key = line.match(/^\s*#+\s+(R\d+)\b/)?.[1] ?? line.replace(/^\s*#+\s+/, '').trim();
+    else if (code[i]) key = null;
+    else if (/^(Out|Assumed):/.test(line)) key = line.match(/^(Out|Assumed)/)[1];
+    // [REC-4]: a tier-1 requirement MAY be one line, `R1: …`, read as an `### R1` sub-section.
+    else if (oneLine && /^R\d+:\s/.test(line)) key = line.match(/^(R\d+)/)[1];
+    if (key) {
+      out.push(current);
+      current = { key, text: '' };
+    }
+    current.text += line;
+  });
+  out.push(current);
+  return out.filter((p) => p.text.trim());
+}
+
+// [REC-4]: the lines of an organized requirement `org` that say MUST, SHOULD
+// or MAY before its first requirement (in the intro, out of fenced code), so
+// are not read as one.
+export function unlabelled(org) {
+  if (!/requirement/.test(org.text.split('\n')[0])) return [];
+  const intro = parts(org.text, org.oneLine).find((p) => p.key === 'intro')?.text ?? '';
+  return prose(intro).split('\n').filter((l) => /\b(MUST|SHOULD|MAY)\b/.test(l)).map((l) => l.trim());
+}
+
+// The same part, ignoring the number in `### R<n>` (a child renumbers what it copies).
+const unnumbered = (text) => text.replace(/^(\s*#+\s+)R\d+\b/, '$1R').replace(/^R\d+:/, 'R:');
+export const samePart = (a, b) => sameSection(unnumbered(a.text), unnumbered(b.text));
+
+// The sign-off that counts: the one with the latest Fetched among those whose
+// signed text still matches its SHA-256. On a tie, the one the `Signed off:`
+// line names; if it names none of them, `tie` gives the time.
+export function latestSignoff(tree, dir, md) {
+  const signoffs = [];
+  for (const { file, s } of snapshots(tree, dir)) {
+    if (isSignoff(s) && s.intact) signoffs.push({ file, fetched: s.fields.Fetched, text: s.text.toString('utf8'), oneLine: tierOne(md) });
+  }
+  if (!signoffs.length) return { signoff: null };
+  // Fetched is a stamp (STAMP in git.js), so the latest is the greatest string.
+  const last = signoffs.reduce((m, s) => (s.fetched > m ? s.fetched : m), '');
+  const latest = signoffs.filter((s) => s.fetched === last);
+  if (latest.length === 1) return { signoff: latest[0] };
+  const line = md.split('\n').find((l) => SIGNED_OFF.test(l)) ?? '';
+  // Only the line's first pointer counts; later ones cite earlier sign-offs.
+  const named = line.match(/origin\/([^\s,;()]+)/)?.[1];
+  const chosen = latest.find((s) => s.file === named);
+  return chosen ? { signoff: chosen } : { signoff: null, tie: last };
+}
+
+// The request whose `## Parts` section names `name` as its child ([REC-8]):
+// an open one first, else an archived one, since [REC-5] sets no condition
+// that the parent stays open.
+export function parentOf(tree, name) {
+  for (const { name: other, dir } of requestDirs(tree)) {
+    if (other === name) continue;
+    const md = tree.read(`${dir}/request.md`)?.toString('utf8');
+    if (md && childrenOf(md).includes(name)) return { name: other, dir, md };
+  }
+  return null;
+}
+
+// Whether a request is blocked, and why ([REC-6]). One function for every
+// command that must know.
+export function signoffState(tree, dir, name) {
+  const md = tree.read(`${dir}/request.md`).toString('utf8');
+  const org = organized(md);
+  if (!org) return { blocked: true, unwritten: true, reason: 'no organized requirement in request.md' };
+  const { signoff: own, tie } = latestSignoff(tree, dir, md);
+  const parent = parentOf(tree, name);
+  const parentSignoff = parent ? latestSignoff(tree, parent.dir, parent.md).signoff : null;
+
+  if (!parentSignoff) {
+    if (!own) {
+      const why = tie ? `: two sign-offs at ${tie}; which counts is not known` : '';
+      return { blocked: true, reason: `awaiting owner sign-off${why}` };
+    }
+    if (sameSection(org.text, own.text)) return { blocked: false, signoff: own };
+    return { blocked: true, reason: `changed since ${own.file}`, signoff: own, changed: changedParts(org.text, own.text, org.oneLine) };
+  }
+
+  // A child: every part is in the parent's or its own signed text, and every
+  // part it signed itself is still there.
+  const now = parts(org.text, org.oneLine);
+  const covers = [...parts(parentSignoff.text, parentSignoff.oneLine), ...(own ? parts(own.text, own.oneLine) : [])];
+  const uncovered = now.filter((p) => !covers.some((c) => samePart(p, c))).map((p) => p.key);
+  const dropped = own ? parts(own.text, own.oneLine).filter((p) => !now.some((c) => samePart(p, c))).map((p) => p.key) : [];
+  if (!uncovered.length && !dropped.length) return { blocked: false, signoff: own, parent: parent.name, parentSignoff };
+  const changed = [...uncovered, ...dropped];
+  if (own) return { blocked: true, reason: `changed since ${own.file}`, signoff: own, parent: parent.name, parentSignoff, changed };
+  return { blocked: true, reason: `awaiting owner sign-off (not in ${parent.name}'s signed text)`, parent: parent.name, parentSignoff, changed };
+}
+
+// The step that unblocks request `name` at `dir`, given its signoffState:
+// write the organized section, or, on the owner's OK only, record the sign-off.
+export const signoffStep = (name, dir, state) => (state.unwritten ? `write the organized requirement in ${dir}/request.md, then al context ${name}`
+  : `show the owner the organized requirement; on their OK: al record ${name} signoff --source <where> --words <quote> --yes`);
+
+// The parts added, changed or removed between the signed text and now.
+export function changedParts(now, signed, oneLine) {
+  const a = parts(now, oneLine);
+  const b = parts(signed, oneLine);
+  const changed = a.filter((p) => !b.some((q) => q.key === p.key && sameSection(q.text, p.text))).map((p) => p.key);
+  const removed = b.filter((q) => !a.some((p) => p.key === q.key)).map((q) => q.key);
+  return [...changed, ...removed];
+}