@assuredloop/cli 0.1.0 → 0.2.1

package/src/v4/repos.js

@@ -0,0 +1,329 @@
+// One central spec repo, and output repos (design.md 12; T12, decision D13).
+// The central repo's config lists its output repos; an output repo's config
+// names the central repo. Another repo is read only through git, at its
+// selected commit: its tree, its blobs and its commit messages, never its
+// working tree, and nothing is fetched. A repo that cannot be read so is
+// unknown, with its reason, and nothing is inferred from it.
+import { existsSync, realpathSync } from 'node:fs';
+import { isAbsolute, posix, resolve } from 'node:path';
+import { parse } from 'yaml';
+import { read, sha256 } from './base.js';
+import { loadConfig } from './config.js';
+import { commitOf, commitsOf, fileAt, filesAt, git, mergeBase, mergesOf } from './git.js';
+import { loadState, qualify, requestNames } from './indexer.js';
+import { latest } from './records.js';
+import { parseResult } from './results.js';
+
+const OUTPUT_LINKS = ['implements', 'verifies', 'documents'];
+// A qualified central ID in text: `central:` and an optional `<request>/`,
+// then a spec ID (EXP-4, ADR-3-2) or a request's R, Q, D, S or T number.
+const QID = /(?<![A-Za-z0-9_-])central:((?:[a-z0-9][a-z0-9-]*\/)?(?:[A-Z][A-Z0-9]*-\d+(?:-\d+)?|[RQDST]\d+))(?![A-Za-z0-9_])/g;
+const TASK = /^[a-z0-9][a-z0-9-]*\/T\d+$/;
+const PR = /^([A-Za-z0-9][A-Za-z0-9._-]*)#(\d+)$/;
+const PROVES = {
+  cites: 'the file names the ID',
+  'named-by': 'the commit message names the task',
+  declared: 'a claim, not proven',
+  pr: 'a reference; the merge is found in git',
+};
+
+const short = (sha) => sha.slice(0, 7);
+const ids = (text) => [...text.matchAll(QID)].map((m) => m[1]);
+
+// An ID in text, qualified (`central:EXP-4`) or bare (`EXP-4`, `invoice-exports/R3`).
+const ANY_ID = /(?<![A-Za-z0-9_\/-])(central:)?((?:[a-z0-9][a-z0-9-]*\/)?(?:[A-Z][A-Z0-9]*-\d+(?:-\d+)?|[RQDST]\d+))(?![A-Za-z0-9_])/g;
+
+// The IDs that a line names, as written: with `qualified`, only `central:<ID>`;
+// else also a bare ID, and only those whose ID is in `known`.
+export function namedIds(text, { qualified = true, known = null } = {}) {
+  const out = [];
+  for (const m of text.matchAll(ANY_ID)) {
+    if (qualified ? !m[1] : known && !known.has(m[2])) continue;
+    if (!out.includes(m[0])) out.push(m[0]);
+  }
+  return out;
+}
+
+// The one cite finder (design.md 3, 12; D17): each line of the repo at `dir`
+// that names an ID, at commit `rev`, or in the working tree (tracked, and
+// untracked not ignored) when `rev` is null. Text files only; nothing under
+// the `exclude` paths. Options as namedIds. Returns [{ file, line, text, ids }].
+export function findCites(dir, rev, { qualified = true, known = null, exclude = [] } = {}) {
+  const pattern = qualified ? 'central:' : '[A-Z][A-Z0-9]*-?[0-9]';
+  const args = ['grep', '-I', '-n', '-z', ...(rev ? [] : ['--untracked']), '-E', '-e', pattern, ...(rev ? [rev] : []),
+    '--', '.', ...exclude.map((p) => `:(exclude)${p}`)];
+  const out = git(dir, args, { allowFail: true }) ?? '';
+  const found = [];
+  for (const l of out.split('\n')) {
+    if (!l) continue;
+    const [where, n, ...rest] = l.split('\0');
+    const text = rest.join('\0');
+    const named = namedIds(text, { qualified, known });
+    if (named.length) found.push({ file: rev ? where.slice(rev.length + 1) : where, line: Number(n), text, ids: named });
+  }
+  return found;
+}
+
+// A repo named in config, made readable: { dir, sha } or { unknown }.
+function open(top, { name, path, url, commit }) {
+  if (typeof path !== 'string' || !path) return { unknown: url ? `no path in config; al does not fetch ${url}` : 'no path in config' };
+  const dir = isAbsolute(path) ? path : resolve(top, path);
+  if (!existsSync(dir)) return { unknown: `no clone at ${path}` };
+  const toplevel = git(dir, ['rev-parse', '--show-toplevel'], { allowFail: true });
+  if (!toplevel || realpathSync(toplevel) !== realpathSync(dir)) return { unknown: `${path} is not a git repository` };
+  const sha = commitOf(dir, commit);
+  if (!sha) return { unknown: `commit ${commit} is not in the ${name} clone` };
+  return { dir, sha };
+}
+
+// The output repos of the central repo's config, in config order.
+export function outputRepos(top, config = loadConfig(top)) {
+  const seen = new Set();
+  return (Array.isArray(config.outputs) ? config.outputs : []).map((o) => {
+    const e = o && typeof o === 'object' && !Array.isArray(o) ? o : {};
+    const name = typeof e.name === 'string' ? e.name : null;
+    const entry = { name, path: e.path ?? null, url: e.url ?? null, commit: e.commit == null ? 'HEAD' : String(e.commit) };
+    let r;
+    if (!name || !/^[a-z0-9][a-z0-9._-]*$/.test(name)) r = { unknown: 'no valid name in config' };
+    else if (seen.has(name)) r = { unknown: `a second outputs entry named ${name}` };
+    else r = open(top, entry);
+    if (name) seen.add(name);
+    return { ...entry, sha: r.sha ?? null, unknown: r.unknown ?? null, dir: r.dir ?? null };
+  });
+}
+
+// A central ID (with no `central:`), found in a state: { display, kind } or null.
+export function findCentral(state, ref) {
+  const t = qualify(ref, null);
+  if (t.cross) return null;
+  if (!t.req) {
+    const p = state.spec.get(t.id);
+    return p ? { display: p.displayNumber, kind: p.kind ?? null } : null;
+  }
+  const r = state.requests.get(t.req);
+  if (!r) return null;
+  const data = r.data ?? {};
+  const listed = (key) => (Array.isArray(data[key]) ? data[key] : []).some((e) => e?.id === t.id);
+  let found;
+  if (/^[RQ]\d+$/.test(t.id)) found = r.reqs.some((q) => q.id === t.id) || latest(data, t.id) !== null;
+  else if (/^D\d+$/.test(t.id)) found = listed('decisions');
+  else if (/^S\d+$/.test(t.id)) found = listed('signoff');
+  else if (/^T\d+$/.test(t.id)) found = listed('tasks');
+  else {
+    const p = r.paras.get(t.id);
+    return p ? { display: `${t.req}/${p.displayNumber}`, kind: p.kind ?? null } : null;
+  }
+  return found ? { display: `${t.req}/${t.id}`, kind: null } : null;
+}
+
+// The config a state is loaded with: the spec root as a repo path.
+const stateConfig = (c) => ({ ...c, root: posix.normalize(String(c.root ?? 'specs')).replace(/\/+$/, ''), docs: Array.isArray(c.docs) ? c.docs : [] });
+
+// The repo's own config at `sha`, or {} when it has none or it does not parse.
+export function repoConfigAt(dir, sha) {
+  try {
+    const c = parse(fileAt(dir, sha, '.assuredloop/config.yaml') ?? '') ?? {};
+    return typeof c === 'object' && !Array.isArray(c) ? c : {};
+  } catch {
+    return {};
+  }
+}
+
+// Each line of `dir`'s tree at `sha` that names a central ID: [{ file, line, ids }].
+const citingLines = (dir, sha) => findCites(dir, sha, { exclude: ['.assuredloop'] })
+  .map(({ file, line, ids: named }) => ({ file, line, ids: named.map((x) => x.slice('central:'.length)) }));
+
+// The first line of each (file, ID) in `lines`, in file and line order.
+function firsts(lines) {
+  const seen = new Map();
+  for (const { file, line, ids: found } of lines) {
+    for (const id of found) if (!seen.has(`${file}\t${id}`)) seen.set(`${file}\t${id}`, { file, line, id });
+  }
+  return [...seen.values()];
+}
+
+// Whether a declared target resolves in the central state: `central:X` and an
+// unqualified X are the central repo's; another qualifier is not (null).
+function resolves(state, target, request) {
+  const ref = target.startsWith('central:') ? target.slice('central:'.length) : target;
+  if (ref.includes(':')) return null;
+  const own = new Set(state.requests.get(request)?.paras.keys() ?? []);
+  const t = qualify(ref, request, own);
+  return findCentral(state, t.req ? `${t.req}/${t.id}` : t.id) !== null;
+}
+
+// Whether a result applies to the repo's tree at `sha` (design.md 9);
+// `bytes` holds the declared inputs there, by path.
+function applies(repo, res, bytes) {
+  if (!res.inputs.length) return 'applicability unknown: no declared inputs';
+  if (res.commit === 'unknown') return 'applicability unknown: the commit is unknown';
+  if (!res.resolved) return `applicability unknown: commit ${res.commit} is not in the ${repo.name} clone`;
+  for (const x of res.inputs) {
+    if (bytes.get(String(x.file)) === null) return `applicability unknown: the declared input ${x.file} is not there`;
+  }
+  for (const x of res.inputs) {
+    if (sha256(bytes.get(String(x.file))) !== x.sha256) return `does not apply to the current text: ${x.file} changed`;
+  }
+  return `declared inputs unchanged since ${repo.name}@${short(res.resolved)}`;
+}
+
+// The result files of an output repo at its commit, in its own results folder.
+function resultsOf(repo) {
+  // As a repo path, the form git gives back: `./ci/results/` is `ci/results`;
+  // `.` and `./` are the repo's top, whose files git gives with no prefix.
+  const dir = posix.normalize(String(repoConfigAt(repo.dir, repo.sha).results ?? '.assuredloop/results')).replace(/\/+$/, '');
+  const prefix = dir === '.' ? '' : `${dir}/`;
+  const files = (git(repo.dir, ['ls-tree', '-z', '--name-only', repo.sha, ...(prefix ? ['--', prefix] : [])], { allowFail: true }) ?? '')
+    .split('\0').filter((f) => f.startsWith(prefix) && !f.slice(prefix.length).includes('/') && f.endsWith('.yaml')).sort();
+  // The result files, then all their declared inputs, each in one batch.
+  const texts = filesAt(repo.dir, repo.sha, files);
+  const parsed = files.map((file) => [file, parseResult(file, texts.get(file) ?? '')]);
+  const bytes = filesAt(repo.dir, repo.sha, [...new Set(parsed.flatMap(([, r]) => (r.inputs ?? []).map((x) => String(x.file))))], null);
+  // The commits the results ran at, in one batch.
+  const commits = commitsOf(repo.dir, parsed.map(([, r]) => r.commit).filter((c) => typeof c === 'string' && c !== 'unknown'));
+  return parsed.map(([file, r]) => {
+    const inputs = r.inputs ?? [];
+    const resolved = typeof r.commit === 'string' && r.commit !== 'unknown' ? commits.get(r.commit) : null;
+    const res = { repo: repo.name, file, check: r.check ?? null, outcome: r.outcome ?? null, commit: r.commit ?? null, resolved, inputs, by: r.by ?? null, source: r.source ?? null, note: r.note ?? null, problems: r.problems };
+    return { ...res, applies: applies(repo, res, bytes) };
+  });
+}
+
+// The commits reachable from `sha` whose message names a central task: [{ sha, task }].
+function taskCommits(dir, sha) {
+  const out = git(dir, ['log', '--format=%H%x00%B%x01', sha], { allowFail: true }) ?? '';
+  const found = [];
+  for (const entry of out.split('\x01')) {
+    const [h, message = ''] = entry.replace(/^\s+/, '').split('\0');
+    if (!h) continue;
+    for (const id of new Set(ids(message))) if (TASK.test(id)) found.push({ sha: h, task: id });
+  }
+  return found;
+}
+
+// The output repos of the central repo at `top` and their results, and
+// nothing else of crossRepo: what al check reads (design.md 9, 12).
+export function crossResults(top) {
+  const repos = outputRepos(top, loadConfig(top));
+  return { repos: repos.map(({ dir, ...r }) => r), results: repos.filter((r) => r.sha).flatMap((r) => resultsOf(r)) };
+}
+
+const link = (fields) => ({ repo: null, holder: null, link: null, target: null, how: null, proves: null, commit: null, unknown: null, resolves: null, file: null, line: null, request: null, ...fields });
+
+// The cross-repo links of the central repo at `top` (design.md 12): its output
+// repos, each link from them or to them, and their results.
+export function crossRepo(top) {
+  const config = loadConfig(top);
+  const repos = outputRepos(top, config);
+  if (!repos.length) return { repos: [], links: [], results: [] };
+  const byName = new Map(repos.filter((r) => r.name).map((r) => [r.name, r]));
+  const self = new Set(['central', ...(typeof config.repo === 'string' ? [config.repo] : [])]);
+  const state = loadState(top, null, stateConfig(config), requestNames(top));
+  const links = [];
+  const results = [];
+
+  for (const repo of repos) {
+    if (!repo.sha) continue;
+    for (const { file, line, id } of firsts(citingLines(repo.dir, repo.sha))) {
+      links.push(link({ repo: repo.name, holder: `${repo.name}/${file}`, link: 'cites', target: `central:${id}`, how: 'exact', proves: PROVES.cites, commit: repo.sha, resolves: findCentral(state, id) !== null, file, line }));
+    }
+    for (const { sha, task } of taskCommits(repo.dir, repo.sha)) {
+      links.push(link({ repo: repo.name, holder: `${repo.name}@${sha}`, link: 'named-by', target: `central:${task}`, how: 'exact', proves: PROVES['named-by'], commit: sha, resolves: findCentral(state, task) !== null }));
+    }
+    results.push(...resultsOf(repo));
+  }
+
+  // What the central records declare: outputs in other repos, and the PRs of tasks.
+  // The merges of each repo are read once (mergesOf).
+  const mergesByRepo = new Map();
+  const unknownOf = (name) => (byName.has(name) ? byName.get(name).unknown : 'not an output repo in config');
+  // The declared output files of each readable repo, read in one batch per repo.
+  const declared = new Map();
+  for (const r of state.requests.values()) {
+    for (const o of Array.isArray(r.data?.outputs) ? r.data.outputs : []) {
+      if (!o?.file || !o.repo || self.has(o.repo) || !byName.get(o.repo)?.sha) continue;
+      if (!declared.has(o.repo)) declared.set(o.repo, new Set());
+      declared.get(o.repo).add(String(o.file));
+    }
+  }
+  const present = new Map([...declared].map(([name, files]) => [name, filesAt(byName.get(name).dir, byName.get(name).sha, [...files], null)]));
+  for (const r of state.requests.values()) {
+    const data = r.data ?? {};
+    for (const o of Array.isArray(data.outputs) ? data.outputs : []) {
+      if (!o?.file || !o.repo || self.has(o.repo)) continue;
+      const repo = byName.get(o.repo);
+      const known = repo?.sha ? repo : null;
+      for (const kind of OUTPUT_LINKS) {
+        for (const ref of [].concat(o[kind] ?? [])) {
+          links.push({
+            ...link({ repo: String(o.repo), holder: `${o.repo}/${o.file}`, link: kind, target: String(ref), how: 'declared', proves: PROVES.declared, commit: known?.sha ?? null, unknown: unknownOf(o.repo), resolves: resolves(state, String(ref), r.name), file: String(o.file), request: r.name }),
+            present: known ? present.get(o.repo).get(String(o.file)) !== null : null,
+          });
+        }
+      }
+    }
+    for (const task of Array.isArray(data.tasks) ? data.tasks : []) {
+      for (const ref of [].concat(task?.prs ?? [])) {
+        const m = PR.exec(String(ref));
+        if (!m || self.has(m[1])) continue;
+        const repo = byName.get(m[1]);
+        let merge = null;
+        let unknown = unknownOf(m[1]);
+        if (!unknown) {
+          if (!mergesByRepo.has(repo.name)) mergesByRepo.set(repo.name, mergesOf(repo.dir, repo.sha));
+          merge = mergesByRepo.get(repo.name)(m[2]);
+          if (!merge) unknown = `no merge found at ${repo.name}@${short(repo.sha)}`;
+        }
+        links.push({
+          ...link({ repo: m[1], holder: `${r.name}/${task.id}`, link: 'pr', target: String(ref), how: 'declared', proves: PROVES.pr, commit: merge, unknown, request: r.name }),
+          merged: merge ? `merged at ${m[1]}@${short(merge)}` : null,
+        });
+      }
+    }
+  }
+
+  const order = new Map(repos.map((r, i) => [r.name, i]));
+  const rank = (name) => order.get(name) ?? repos.length;
+  links.sort((a, b) => rank(a.repo) - rank(b.repo) || a.link.localeCompare(b.link) || a.holder.localeCompare(b.holder)
+    || a.target.localeCompare(b.target) || (a.line ?? 0) - (b.line ?? 0));
+  return { repos: repos.map(({ dir, ...r }) => r), links, results };
+}
+
+// In an output repo: the files that the branch changed (merge-base with main
+// to the working tree, and untracked files not ignored), or with no base every
+// file; never under .assuredloop/.
+function changedFiles(top, base) {
+  const list = (args) => (git(top, args, { allowFail: true }) ?? '').split('\0').filter(Boolean);
+  const files = base
+    ? [...list(['diff', '--name-only', '-z', base, '--']), ...list(['ls-files', '-z', '--others', '--exclude-standard'])]
+    : list(['ls-files', '-z', '--cached', '--others', '--exclude-standard']);
+  return [...new Set(files)].filter((f) => !f.startsWith('.assuredloop/')).sort();
+}
+
+// al check in an output repo (design.md 12): each central ID that the branch's
+// changed files cite, looked up in the central repo at its selected commit.
+// Returns { body, notKnown }; both empty when config names no central repo.
+export function centralLookup(top) {
+  const config = loadConfig(top);
+  const c = config.central;
+  if (!c || typeof c !== 'object' || Array.isArray(c)) return { body: [], notKnown: [] };
+  const central = { name: 'central', path: c.path ?? null, url: c.url ?? null, commit: c.commit == null ? 'HEAD' : String(c.commit) };
+  const r = open(top, central);
+  if (r.unknown) return { body: [`unknown: the central repo: ${r.unknown}`], notKnown: [`the central repo (${r.unknown}): no central ID was looked up`] };
+  const base = mergeBase(top);
+  const lines = [];
+  for (const file of changedFiles(top, base)) {
+    let text;
+    try { text = read(top, file); } catch { continue; }
+    if (text === null || text.includes('\0')) continue;
+    text.split('\n').forEach((l, i) => { const found = ids(l); if (found.length) lines.push({ file, line: i + 1, ids: found }); });
+  }
+  const state = loadState(r.dir, r.sha, stateConfig(repoConfigAt(r.dir, r.sha)), requestNames(r.dir, r.sha));
+  const body = [`central repo ${c.path} at ${r.sha}`];
+  for (const { file, line, id } of firsts(lines)) {
+    const found = findCentral(state, id);
+    body.push(found ? `info cites ${file}:${line} central:${id} ${found.display} ${found.kind ?? '-'}`
+      : `hint unresolved-central ${file}:${line} central:${id} not in the central repo at ${short(r.sha)}`);
+  }
+  return { body, notKnown: base ? [] : ['no base (no main branch, or no commit): every file was looked at for central IDs'] };
+}

package/src/v4/request-md.js

@@ -0,0 +1,108 @@
+// The parts of request.md that v4 reads and writes: the organized
+// requirement (or question), its requirements with their `from` markers, the
+// Signed off line and the decisions.
+import { sha256 } from './base.js';
+
+const ORGANIZED = /^##\s+Organized (requirement|question)\s*$/;
+const MARKER = /^\s*<!--.*-->\s*$/;
+const SIGNED_OFF = /^Signed off:/;
+const lf = (md) => md.replace(/\r\n?/g, '\n');
+
+// The organized section: its line range in `md`, from its `##` heading to the
+// next `#` or `##` heading. Null when there is none.
+export function organized(md) {
+  const lines = lf(md).split('\n');
+  const start = lines.findIndex((l) => ORGANIZED.test(l));
+  if (start < 0) return null;
+  let end = lines.findIndex((l, i) => i > start && /^#{1,2}\s/.test(l));
+  if (end < 0) end = lines.length;
+  return { lines, start, end };
+}
+
+// What a sign-off binds: the organized section with no Signed off line and no
+// marker framing, the marker line and the blank line after it (D22, as the
+// paragraph hash drops it), so adding markers changes no signed byte.
+export function signedText(md) {
+  const o = organized(md);
+  if (!o) return null;
+  const lines = o.lines.slice(o.start, o.end);
+  const kept = lines.filter((l, i) => !SIGNED_OFF.test(l) && !MARKER.test(l)
+    && !(l === '' && i > 0 && MARKER.test(lines[i - 1])));
+  while (kept.length && !kept.at(-1).trim()) kept.pop();
+  return `${kept.join('\n')}\n`;
+}
+
+// Each `### R<n> <title>` (or `### Q<n>`): { id, title, text, sha256, from }.
+// Its text runs from the heading to the next heading, or an Out:, Assumed:
+// or Signed off: line, with no marker line and no blank line at either end.
+// `from` lists the snapshot files of the `<!-- R<n> from:... -->` markers.
+export function requirements(md) {
+  const o = organized(md);
+  if (!o) return [];
+  const from = new Map();
+  const out = [];
+  let cur = null;
+  const close = () => {
+    if (!cur) return;
+    const body = cur.lines.filter((l) => !MARKER.test(l));
+    while (body.length && !body.at(-1).trim()) body.pop();
+    const text = `${body.join('\n')}\n`;
+    out.push({ id: cur.id, title: cur.title, text, sha256: sha256(text) });
+    cur = null;
+  };
+  for (const l of o.lines.slice(o.start + 1, o.end)) {
+    const m = l.match(/^\s*<!--\s*([RQ]\d+)\b(.*?)-->\s*$/);
+    if (m) {
+      const files = [...m[2].matchAll(/(?:^|\s)from:(\S+)/g)].flatMap((x) => x[1].split(',').filter(Boolean));
+      from.set(m[1], [...(from.get(m[1]) ?? []), ...files]);
+    }
+    const h = l.match(/^###\s+([RQ]\d+)\b\s*(.*)$/);
+    if (h) { close(); cur = { id: h[1], title: h[2].trim(), lines: [l] }; continue; }
+    if (/^#{1,6}\s/.test(l) || /^(Out|Assumed|Signed off):/.test(l)) { close(); continue; }
+    if (cur) cur.lines.push(l);
+  }
+  close();
+  return out.map((r) => ({ ...r, from: from.get(r.id) ?? [] }));
+}
+
+// Sets `Signed off: …` as the last line of the organized section, in place of
+// any earlier one there.
+export function setSignedOff(md, line) {
+  const o = organized(md);
+  const lines = o.lines.filter((l, i) => !(i > o.start && i < o.end && SIGNED_OFF.test(l)));
+  const end = o.end - (o.lines.length - lines.length);
+  let last = end - 1;
+  while (last > o.start && !lines[last].trim()) last--;
+  lines.splice(last + 1, 0, line);
+  return lines.join('\n');
+}
+
+// The D numbers in `## Decisions`.
+export function decisionNumbers(md) {
+  const lines = lf(md).split('\n');
+  const at = lines.findIndex((l) => /^##\s+Decisions\s*$/.test(l));
+  if (at < 0) return [];
+  const out = [];
+  for (const l of lines.slice(at + 1)) {
+    if (/^#{1,2}\s/.test(l)) break;
+    const m = l.match(/^- D(\d+)\b/);
+    if (m) out.push(Number(m[1]));
+  }
+  return out;
+}
+
+// `entry` as the last entry of `## Decisions`, the section added at the end
+// when missing.
+export function addDecision(md, entry) {
+  const lines = lf(md).split('\n');
+  const at = lines.findIndex((l) => /^##\s+Decisions\s*$/.test(l));
+  if (at < 0) return `${lf(md).replace(/\n*$/, '\n')}\n## Decisions\n\n${entry}\n`;
+  let end = lines.findIndex((l, i) => i > at && /^#{1,2}\s/.test(l));
+  if (end < 0) end = lines.length;
+  let last = end;
+  while (last > at + 1 && !lines[last - 1].trim()) last--;
+  // A heading right after the entry gets a blank line before it.
+  const after = last === end && end < lines.length ? [entry, ''] : [entry];
+  if (last === at + 1) after.unshift('');
+  return [...lines.slice(0, last), ...after, ...lines.slice(last)].join('\n');
+}

package/src/v4/results.js

@@ -0,0 +1,42 @@
+// Result files (design.md 9; the T6 decision): what ran, its outcome, the
+// commit it ran at (or "unknown") and its declared inputs, with optional
+// by, source and note. This reads and checks the format only; whether a
+// result applies to the current text is judged by the checks (T10).
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { Fail, read } from './base.js';
+import { loadConfig } from './config.js';
+
+const OUTCOMES = ['pass', 'fail', 'not run'];
+
+export function loadResults(top) {
+  const dir = String(loadConfig(top).results ?? '.assuredloop/results').replace(/\/+$/, '');
+  let files = [];
+  try { files = readdirSync(join(top, dir)).filter((f) => f.endsWith('.yaml')).sort(); } catch { return []; }
+  return files.map((f) => {
+    const file = `${dir}/${f}`;
+    let text;
+    try { text = read(top, file); } catch (e) { return { file, problems: [e instanceof Fail ? e.message : 'not YAML'] }; }
+    return parseResult(file, text);
+  });
+}
+
+// One result file's text, read and checked: its fields and its problems.
+export function parseResult(file, text) {
+  let r;
+  // The failsafe schema keeps each value as written: a commit such as 0123456 stays text.
+  try { r = parse(text, { schema: 'failsafe' }); } catch { return { file, problems: ['not YAML'] }; }
+  if (!r || typeof r !== 'object' || Array.isArray(r)) return { file, problems: ['not a YAML map'] };
+  const problems = [];
+  for (const k of ['check', 'outcome', 'commit']) if (r[k] === undefined || r[k] === null || r[k] === '') problems.push(`no ${k}`);
+  if (r.outcome != null && !OUTCOMES.includes(r.outcome)) problems.push(`outcome ${r.outcome}: one of ${OUTCOMES.join(', ')}`);
+  if (r.commit != null && r.commit !== 'unknown' && !/^[0-9a-f]{7,40}$/.test(r.commit)) problems.push(`commit ${r.commit}: a 7-40 hex commit, or unknown`);
+  const inputs = r.inputs ?? [];
+  if (!Array.isArray(inputs)) problems.push('inputs: a list of {file, sha256}');
+  else inputs.forEach((x, i) => {
+    if (!x?.file) problems.push(`input ${i + 1}: no file`);
+    if (!/^[0-9a-f]{64}$/.test(String(x?.sha256 ?? ''))) problems.push(`input ${i + 1}: sha256 is not 64 hex`);
+  });
+  return { file, check: r.check, outcome: r.outcome, commit: r.commit, inputs: Array.isArray(inputs) ? inputs : [], by: r.by, source: r.source, note: r.note, problems };
+}

package/src/v4/scope.js

@@ -0,0 +1,167 @@
+// The docs whose paragraphs carry markers, in two kinds of scope (architect,
+// 2026-10-10): the spec scope, every *.md under the spec root except its adr/
+// folder plus the files config's docs list names; and one scope per request,
+// its requests/<name>/spec.md (or the archived one), with prefix SP and IDs of
+// its own. Two scopes never share IDs.
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { join, posix, relative } from 'node:path';
+import { git, filesAt, readObjects } from './git.js';
+import { parseMarkdown } from './markers.js';
+
+export const SPEC = 'spec';
+const REQUEST = /^requests\/(?:archive\/)?([^/]+)\/spec\.md$/;
+
+const clean = (p) => posix.normalize(String(p)).replace(/^\.\//, '').replace(/\/+$/, '');
+const outside = (p) => posix.isAbsolute(String(p)) || /^\.\.(\/|$)/.test(clean(p));
+
+// The root and the docs entries of config that are outside the repository,
+// as written (the root with a trailing slash): never walked or read.
+const outsideDocs = (config) => [
+  ...(outside(config.root) ? [`${String(config.root).replace(/\/+$/, '')}/`] : []),
+  ...config.docs.map((d) => String(d.file)).filter(outside),
+];
+
+// The first part of `path` (from the repo top) that is a symlink, or null.
+export function symlinkOn(top, path) {
+  let at = top;
+  for (const part of path.split('/')) {
+    at = join(at, part);
+    let stat;
+    try {
+      stat = lstatSync(at);
+    } catch {
+      return null;
+    }
+    if (stat.isSymbolicLink()) return relative(top, at);
+  }
+  return null;
+}
+
+// The root and the docs entries that are inside the repository but reached
+// through a symlink: never walked or read either.
+const linked = (top, config) => [
+  ...(!outside(config.root) && symlinkOn(top, clean(config.root)) ? [`${String(config.root).replace(/\/+$/, '')}/`] : []),
+  ...insideDocs(config).map((d) => String(d.file)).filter((f) => symlinkOn(top, clean(f))),
+];
+
+// Why config's root cannot be used, or null: the repository top is no spec root.
+export const rootProblem = (config) => (!outside(config.root) && ['.', ''].includes(clean(config.root))
+  ? `.assuredloop/config.yaml: root: ${JSON.stringify(String(config.root))} is the repository top; give the spec folder, for example specs`
+  : null);
+
+// One line for each root or docs entry that is not read, and why.
+export const notRead = (top, config) => [
+  ...outsideDocs(config).map((f) => `not read: ${f}: outside the repository`),
+  ...linked(top, config).map((f) => `not read: ${f}: through a symlink`),
+];
+
+const insideDocs = (config) => config.docs.filter((d) => !outside(d.file));
+
+// The scope of a repo path, or null when it holds no markers.
+export function scopeOf(path, config) {
+  const root = clean(config.root);
+  const r = REQUEST.exec(path);
+  if (r) return `request:${r[1]}`;
+  if (path.startsWith(`${root}/adr/`)) return null;
+  if (insideDocs(config).some((d) => clean(d.file) === path)) return SPEC;
+  if (path.startsWith(`${root}/`) && path.endsWith('.md')) return SPEC;
+  return null;
+}
+
+// The prefix of a doc: SP in a request spec, else the one config lists, or null.
+export function prefixOf(path, config) {
+  if (REQUEST.test(path)) return 'SP';
+  return insideDocs(config).find((d) => clean(d.file) === path)?.prefix ?? null;
+}
+
+// Every file of the working tree under `dir`, symlinks not followed.
+function walk(top, dir, out = []) {
+  if (!existsSync(join(top, dir)) || !lstatSync(join(top, dir)).isDirectory()) return out;
+  for (const e of readdirSync(join(top, dir), { withFileTypes: true })) {
+    if (e.name === '.git' || e.name === 'node_modules') continue;
+    const p = dir ? `${dir}/${e.name}` : e.name;
+    if (e.isDirectory()) walk(top, p, out);
+    else if (e.isFile()) out.push(p);
+  }
+  return out;
+}
+
+// The docs in scope: [{ path, scope, text }], from the working tree when
+// `rev` is null, else from that commit.
+export function docsInScope(top, config, rev = null) {
+  const root = clean(config.root);
+  let paths;
+  if (rev === null) {
+    const read = (p) => !symlinkOn(top, p);
+    paths = [...(outside(config.root) || !read(root) ? [] : walk(top, root)), ...walk(top, 'requests'), ...insideDocs(config).map((d) => clean(d.file)).filter(read)];
+  } else {
+    paths = (git(top, ['ls-tree', '-r', '-z', '--name-only', rev], { allowFail: true }) ?? '').split('\0').filter(Boolean);
+  }
+  const inScope = [...new Set(paths)].sort().filter((path) => scopeOf(path, config));
+  const atRev = rev === null ? null : filesAt(top, rev, inScope);
+  const docs = [];
+  for (const path of inScope) {
+    const scope = scopeOf(path, config);
+    let text;
+    if (rev !== null) text = atRev.get(path);
+    else if (existsSync(join(top, path)) && lstatSync(join(top, path)).isFile()) text = readFileSync(join(top, path), 'utf8');
+    if (text == null) continue;
+    docs.push({ path, scope, text });
+  }
+  return docs;
+}
+
+// Parses each doc; returns Map scope → paragraphs, and every lint.
+export function parseScopes(docs, kinds) {
+  const scopes = new Map();
+  const lints = [];
+  for (const d of docs) {
+    const r = parseMarkdown(d.text, d.path, { kinds });
+    if (!scopes.has(d.scope)) scopes.set(d.scope, []);
+    scopes.get(d.scope).push(...r.paragraphs);
+    lints.push(...r.lints);
+  }
+  return { scopes, lints };
+}
+
+// Every ID that a marker held in any commit up to `rev` (a commit, or --all
+// for every ref), by scope: each version of each doc in history, from
+// `git log --raw -z` (exact paths), read with `git cat-file --batch` and
+// parsed, so a marker inside fenced code is no ID. Null when `rev` is null.
+export function idsEverUsed(top, config, rev) {
+  if (!rev) return null;
+  const used = new Map();
+  const specs = ['*.md', ...insideDocs(config).map((d) => clean(d.file))];
+  const out = git(top, ['log', '--raw', '-z', '--no-abbrev', '--no-renames', '--format=', rev, '--', ...specs], { allowFail: true });
+  if (!out) return used;
+  // Each changed file is ":<mode> <mode> <old blob> <new blob> <status>" NUL "<path>" NUL.
+  const scopes = new Map();
+  const fields = out.split('\0');
+  for (let i = 0; i < fields.length - 1; i++) {
+    const meta = fields[i].replace(/^\n+/, '');
+    if (!meta.startsWith(':')) continue;
+    const scope = scopeOf(fields[++i], config);
+    if (!scope) continue;
+    for (const blob of meta.split(' ').slice(2, 4)) {
+      if (/^0+$/.test(blob)) continue;
+      if (!scopes.has(blob)) scopes.set(blob, new Set());
+      scopes.get(blob).add(scope);
+    }
+  }
+  for (const [blob, text] of readBlobs(top, [...scopes.keys()])) {
+    for (const p of parseMarkdown(text, '').paragraphs) {
+      for (const scope of scopes.get(blob)) {
+        if (!used.has(scope)) used.set(scope, new Set());
+        used.get(scope).add(p.id);
+      }
+    }
+  }
+  return used;
+}
+
+// The text of each blob that is there.
+function readBlobs(top, blobs) {
+  return new Map([...readObjects(top, blobs)].map(([b, bytes]) => [b, bytes.toString('utf8')]));
+}
+
+export const isShallow = (top) => git(top, ['rev-parse', '--is-shallow-repository'], { allowFail: true }) === 'true';