@assuredloop/cli 0.2.3 → 1.0.0

package/src/v4/blocks.js

@@ -0,0 +1,321 @@
+// The rules that block (#238, design.md 3, 6 and 10, schema.md 5): the few
+// findings that are `not ok` because an exact check of the records, hashes
+// and links decides them, and breaking them lets an unapproved or wrong
+// decision be built. Every other finding of al check is a hint.
+// - unsigned-requirement: the latest version of each requirement has a valid
+//   sign-off (R3);
+// - record-evidence: each file that a record lists with a hash still has it (R4);
+// - superseded-cited and superseded-status: a current place that names a
+//   superseded ADR names its successor, and the status line names it (R5);
+// - record-unreadable: a request record that cannot be read or is not a YAML
+//   mapping, or whose request has no request.md.
+// Each finding is { severity, code, where, id, message }, as in checks.js.
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { read, recordPath, sha256 } from './base.js';
+import { SIGNED } from './snapshot.js';
+import { SPEC, linkedDocs, rootNotOk } from './scope.js';
+
+const isMap = (x) => !!x && typeof x === 'object' && !Array.isArray(x);
+const text = (x) => typeof x === 'string' && x.length > 0;
+const whole = (x) => Number.isInteger(x) && x > 0;
+const REQ = /^[RQ]\d+$/;
+const SYMLINK = 'it is a symlink, and al does not read through a symlink';
+// A symlink that stands for a current place: to a Markdown file, or to a
+// folder (its type is read from the link, nothing through it).
+const placeLink = (top, path) => {
+  if (path.endsWith('.md')) return true;
+  try {
+    return statSync(join(top, path)).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+// The bytes of a snapshot after its separator line, as al new and al record
+// hashed them: the first line that is `---` (or `--- signed text ---`), or
+// only `--- signed text ---` for a sign-off. Null when there is none.
+function snapshotText(bytes, signedOnly) {
+  const seps = signedOnly ? [`\n${SIGNED}\n`] : ['\n---\n', `\n${SIGNED}\n`];
+  const at = seps.map((s) => [bytes.indexOf(s), s]).filter(([i]) => i >= 0).sort((a, b) => a[0] - b[0])[0];
+  return at ? bytes.subarray(at[0] + at[1].length) : null;
+}
+
+// What a record's file name in origin/ gives: { hash } of its snapshot text,
+// or { problem } that says why it has none.
+function evidence(top, r, file, signedOnly) {
+  const name = String(file).replace(/^origin\//, '');
+  if (!/^[^/\\]+$/.test(name) || name === '.' || name === '..') return { problem: `${file} is not a file in ${r.dir}/origin/` };
+  let bytes;
+  try {
+    bytes = read(top, `${r.dir}/origin/${name}`, null);
+  } catch (e) {
+    return { problem: `${r.dir}/origin/${name} cannot be read: ${e.message}` };
+  }
+  if (bytes === null) return { problem: `${r.dir}/origin/${name} is missing` };
+  const t = snapshotText(bytes, signedOnly);
+  if (t === null) return { problem: `${r.dir}/origin/${name} has no ${signedOnly ? `"${SIGNED}"` : '"---"'} line, so its text cannot be read` };
+  return { hash: sha256(t) };
+}
+
+// R3, R4 and the unreadable record, for each request with a record, open or archived.
+export function recordBlocks(top, state, add) {
+  // A record whose request has no request.md: nothing in it can be checked.
+  const folder = '.assuredloop/records/requests';
+  let records = [];
+  try {
+    records = readdirSync(join(top, folder), { withFileTypes: true }).filter((e) => e.name.endsWith('.yaml')).map((e) => e.name.slice(0, -5)).sort();
+  } catch (e) {
+    records = [];
+    if (e.code !== 'ENOENT') add('not ok', 'record-unreadable', folder, '-', `${folder} cannot be read (${e.code ?? e.message}), so no record in it is checked`);
+  }
+  for (const name of records.filter((n) => !state.requests.has(n))) {
+    const at = recordPath(name);
+    add('not ok', 'record-unreadable', at, name, `${at} has no request.md in requests/${name}/ or requests/archive/${name}/, so its requirements, sign-offs and evidence are not checked`);
+  }
+  for (const r of state.requests.values()) {
+    const at = recordPath(r.name);
+    const data = r.data;
+    if (r.recordError) {
+      add('not ok', 'record-unreadable', at, r.name, `${at} cannot be read (${r.recordError}), so its requirements, sign-offs and evidence are not checked; fix it by hand`);
+      continue;
+    }
+    if (!data) continue;
+    const bad = (code, where, id, message) => add('not ok', code, where, `${r.name}/${id}`, message);
+
+    // R4: each origin file under sources:, and each sign-off file.
+    const sources = data.sources ?? [];
+    if (!Array.isArray(sources)) bad('record-evidence', at, 'sources', 'sources: is not a list, so its files cannot be checked');
+    for (const s of Array.isArray(sources) ? sources : []) {
+      if (!isMap(s) || !text(s.file) || !text(s.sha256)) {
+        bad('record-evidence', at, isMap(s) && text(s.file) ? s.file : '-', 'a sources entry with no file or no sha256');
+        continue;
+      }
+      const e = evidence(top, r, s.file, false);
+      if (e.problem) bad('record-evidence', at, s.file, e.problem);
+      else if (e.hash !== s.sha256) bad('record-evidence', at, s.file, `${r.dir}/origin/${s.file.replace(/^origin\//, '')} changed: its text no longer has the sha256 that the record lists`);
+    }
+    const signoffs = data.signoff ?? [];
+    if (!Array.isArray(signoffs)) bad('unsigned-requirement', at, 'signoff', 'signoff: is not a list, so no sign-off can be read');
+    // Each sign-off: why it is not valid (R3), or null.
+    const why = new Map();
+    for (const s of Array.isArray(signoffs) ? signoffs : []) {
+      const id = isMap(s) && text(s.id) ? s.id : '-';
+      if (!isMap(s) || !text(s.id) || !text(s.file) || !text(s.sha256) || !Array.isArray(s.covers)) {
+        if (isMap(s) && !(text(s.file) && text(s.sha256))) bad('record-evidence', at, id, 'a sign-off with no file or no sha256');
+        bad('unsigned-requirement', at, id, 'a sign-off entry that cannot be read: it needs id, file, sha256 and a covers list');
+        continue;
+      }
+      const e = evidence(top, r, s.file, true);
+      if (e.problem) bad('record-evidence', at, s.file, e.problem);
+      else if (e.hash !== s.sha256) bad('record-evidence', at, s.file, `${r.dir}/origin/${s.file.replace(/^origin\//, '')} changed: its signed text no longer has the sha256 of ${s.id}`);
+      const covers = s.covers.filter((c) => isMap(c) && text(c.id) && whole(c.version) && text(c.sha256));
+      if (covers.length < s.covers.length) {
+        bad('unsigned-requirement', at, s.id, `${s.id} has a covers entry that cannot be read: it needs id, a whole version above 0 and sha256`);
+        continue;
+      }
+      const problem = e.problem ? `its file: ${e.problem}`
+        : e.hash !== s.sha256 ? 'its file\'s signed text does not have its sha256'
+          : !(text(s.signed) && !Number.isNaN(Date.parse(s.signed))) ? 'it does not record when it was signed'
+            : !text(s.words) ? 'it does not record the signer\'s words' : null;
+      why.set(s, problem);
+    }
+
+    // R3: only a request whose record has requirements:.
+    if (!Object.hasOwn(data, 'requirements')) continue;
+    if (!Array.isArray(data.requirements)) {
+      bad('unsigned-requirement', at, 'requirements', 'requirements: is not a list, so no requirement can be read');
+      continue;
+    }
+    const latest = new Map();
+    for (const v of data.requirements) {
+      if (!isMap(v) || !(typeof v.id === 'string' && REQ.test(v.id)) || !whole(v.version) || !text(v.sha256)) {
+        bad('unsigned-requirement', at, isMap(v) && text(v.id) ? v.id : '-', 'a requirement entry that cannot be read: it needs an id R<n> or Q<n>, a whole version above 0 and sha256');
+        continue;
+      }
+      if (!latest.has(v.id) || v.version > latest.get(v.id).version) latest.set(v.id, v);
+    }
+    const md = `${r.dir}/request.md`;
+    const next = `run al index, then show it to the owner: al record ${r.name} signoff`;
+    const shown = new Set();
+    for (const q of r.reqs) {
+      const v = latest.get(q.id);
+      if (!v) bad('unsigned-requirement', md, q.id, `${q.id} is in request.md, but the record has no version of it, so no sign-off covers it; ${next}`);
+      else if (v.sha256 !== q.sha256) bad('unsigned-requirement', md, q.id, `${q.id} in request.md is not its latest recorded version ${v.version}: it is a new version that no sign-off covers; ${next}`);
+      else continue;
+      shown.add(q.id);
+    }
+    for (const v of latest.values()) {
+      if (shown.has(v.id)) continue;
+      const covering = [...why.keys()].filter((s) => s.covers.some((c) => c.id === v.id && c.version === v.version && c.sha256 === v.sha256));
+      if (covering.some((s) => why.get(s) === null)) continue;
+      const reason = covering.length
+        ? covering.map((s) => `${s.id} covers it, but is not valid: ${why.get(s)}`).join('; ')
+        : `no sign-off covers version ${v.version} with its sha256`;
+      bad('unsigned-requirement', md, v.id, `${v.id} version ${v.version} is not signed: ${reason}; ${next}`);
+    }
+  }
+}
+
+// The ADRs that each ADR supersedes, directly: those its marker names in
+// supersedes:, and those whose status line names it.
+function supersedes(state) {
+  const out = new Map([...state.adrs.keys()].map((id) => [id, new Set()]));
+  for (const a of state.adrs.values()) {
+    for (const x of (a.head?.links.supersedes ?? []).map(adrOf).filter(Boolean)) out.get(a.id).add(x);
+    if (a.by && out.has(a.by)) out.get(a.by).add(a.id);
+  }
+  return out;
+}
+
+// What a superseded-ADR finding says (supersededIn).
+export const citedMessage = (c) => (c.next.length
+  ? `names ${c.adr}, which is superseded, but not ${c.next.join(' or ')}, which supersedes it, ${c.link ? 'in the same marker' : 'in the same paragraph'}`
+  : `names ${c.adr}, which is superseded, and no ADR supersedes it (see superseded-status)`);
+
+// The ADR that a link value or word names: `ADR-n` and `ADR-n-k` name ADR-n.
+const ADR_REF = /^ADR-(\d+)(?:-\d+)?$/;
+const adrOf = (ref) => (ADR_REF.test(ref) ? `ADR-${Number(ADR_REF.exec(ref)[1])}` : null);
+const MARKER = /^\s*<!--(.*)-->\s*$/;
+
+// The places of a Markdown text: each marker line and each run of text lines,
+// with the ADRs it names and the ID of the marker it falls under. A heading
+// that `skip` matches starts a section that is not read, up to the next
+// heading of level 1 or 2.
+function places(textOf, skip) {
+  const lines = textOf.replace(/\r\n?/g, '\n').split('\n');
+  const out = [];
+  let id = null;
+  let skipping = false;
+  let run = null;
+  const close = () => {
+    if (run && run.names.size) out.push(run);
+    run = null;
+  };
+  lines.forEach((l, i) => {
+    if (/^#{1,2}\s/.test(l)) skipping = Boolean(skip && skip.test(l));
+    if (skipping || !l.trim()) { close(); return; }
+    const m = MARKER.exec(l);
+    if (m) {
+      close();
+      const tokens = m[1].trim().split(/\s+/).filter(Boolean);
+      if (tokens[0] && !tokens[0].includes(':')) id = tokens[0];
+      const names = new Set(tokens.filter((t) => t.indexOf(':') > 0).flatMap((t) => t.slice(t.indexOf(':') + 1).split(',')).map(adrOf).filter(Boolean));
+      if (names.size) out.push({ line: i + 1, id, link: true, names });
+      return;
+    }
+    if (!run) run = { line: i + 1, id, link: false, names: new Set() };
+    for (const w of l.matchAll(/\bADR-(\d+)(?:-\d+)?\b/g)) run.names.add(`ADR-${Number(w[1])}`);
+  });
+  close();
+  return out;
+}
+
+// R5's rule on one text: each place that names a superseded ADR, but no ADR
+// that supersedes it, in the same marker or the same paragraph. Gives
+// (text, { skip, exempt }) => [{ line, id, link, adr, next }]. al check
+// --issues reads the issues with the same rule (issue-hints D7).
+export function supersededIn(state) {
+  const down = supersedes(state);
+  const up = (id) => [...down].filter(([, xs]) => xs.has(id)).map(([y]) => y);
+  const superseded = (id) => state.adrs.get(id)?.status === 'superseded';
+  return (textOf, { skip = null, exempt = new Set() } = {}) => places(textOf, skip).flatMap((p) => [...p.names]
+    .filter((x) => superseded(x) && !exempt.has(x) && !up(x).some((y) => p.names.has(y)))
+    .map((x) => ({ line: p.line, id: p.id, link: p.link, adr: x, next: up(x) })));
+}
+
+// The Markdown files of an open request's folder, in its subfolders too, but
+// origin/; a symlink to a Markdown file or a folder, or a subfolder that
+// cannot be read, is given as { unreadable, why }.
+export function requestMarkdown(top, dir, sub = '') {
+  let entries = [];
+  try {
+    entries = readdirSync(join(top, dir, sub), { withFileTypes: true });
+  } catch (e) {
+    return sub && e.code !== 'ENOENT' ? [{ unreadable: sub, why: e.code ?? e.message }] : [];
+  }
+  return entries.sort((a, b) => (a.name < b.name ? -1 : 1)).flatMap((e) => {
+    const f = sub ? `${sub}/${e.name}` : e.name;
+    if (e.isSymbolicLink()) return f !== 'origin' && placeLink(top, `${dir}/${f}`) ? [{ unreadable: f, why: SYMLINK }] : [];
+    if (e.isDirectory()) return f === 'origin' ? [] : requestMarkdown(top, dir, f);
+    return e.isFile() && e.name.endsWith('.md') ? [f] : [];
+  });
+}
+
+// R5: a current place that names a superseded ADR names an ADR that
+// supersedes it, in the same marker or the same paragraph; and each
+// superseded ADR's status line names an ADR whose marker supersedes it.
+export function supersededBlocks(top, state, add) {
+  const down = supersedes(state);
+  const cited = supersededIn(state);
+  // The ADRs that `id` supersedes, directly or through a chain.
+  const chain = (id) => {
+    const seen = new Set();
+    const walk = (x) => { for (const y of down.get(x) ?? []) if (!seen.has(y)) { seen.add(y); walk(y); } };
+    walk(id);
+    return seen;
+  };
+
+  for (const a of state.adrs.values()) {
+    if (a.status !== 'superseded') continue;
+    const where = `${a.file}:1`;
+    if (!a.by) add('not ok', 'superseded-status', where, a.id, `${a.id} is superseded, but its status line does not say by which ADR: write "Status: superseded by ADR-<n>"`);
+    else if (!state.adrs.has(a.by)) add('not ok', 'superseded-status', where, a.id, `${a.id} says it is superseded by ${a.by}, which does not exist`);
+    else if (!(state.adrs.get(a.by).head?.links.supersedes ?? []).some((x) => adrOf(x) === a.id)) {
+      add('not ok', 'superseded-status', where, a.id, `${a.id} says it is superseded by ${a.by}, but the marker of ${a.by} has no supersedes:${a.id}`);
+    }
+  }
+
+  const check = (file, textOf, { skip = null, exempt = new Set(), name = null } = {}) => {
+    for (const c of cited(textOf, { skip, exempt })) {
+      const id = c.id ? (name ? `${name}/${c.id}` : c.id) : '-';
+      add('not ok', 'superseded-cited', `${file}:${c.line}`, id, citedMessage(c));
+    }
+  };
+  // A current place that cannot be read: its citations are not checked, and
+  // a read failure never hides a block (SCH-37).
+  const unreadable = (path, why) => add('not ok', 'superseded-cited', path, '-', `${path} cannot be read (${why}), so its citations of superseded ADRs are not checked`);
+  // A symlinked Markdown file or folder under the spec root (the ADRs too) is not read.
+  const linked = (dir) => {
+    let entries = [];
+    try {
+      entries = readdirSync(join(top, dir), { withFileTypes: true });
+    } catch {
+      entries = [];
+    }
+    return entries.flatMap((e) => (e.isSymbolicLink() ? (placeLink(top, `${dir}/${e.name}`) ? [`${dir}/${e.name}`] : []) : e.isDirectory() ? linked(`${dir}/${e.name}`) : []));
+  };
+  // Only a root that is in the repo and not through a symlink is walked
+  // (scope.js); the docs that config lists are spec docs too.
+  const links = new Set([...(rootNotOk(top, state.config) ? [] : linked(state.root)), ...linkedDocs(top, state.config)]);
+  for (const f of [...links].sort()) unreadable(f, SYMLINK);
+  // The spec docs, each paragraph with its marker.
+  for (const d of state.docs ?? []) if (d.scope === SPEC && typeof d.text === 'string') check(d.path, d.text);
+  // The Markdown files of each open request, but origin/ and the recorded decisions.
+  for (const r of state.requests.values()) {
+    if (!r.open) continue;
+    for (const f of requestMarkdown(top, r.dir)) {
+      if (f.unreadable) {
+        unreadable(`${r.dir}/${f.unreadable}`, f.why);
+        continue;
+      }
+      let t;
+      let why = 'it is there, but it cannot be read as a file';
+      try {
+        t = read(top, `${r.dir}/${f}`);
+      } catch (e) {
+        t = null;
+        why = e.message.split('\n')[0];
+      }
+      if (t === null) unreadable(`${r.dir}/${f}`, why);
+      else check(`${r.dir}/${f}`, t, { name: r.name, skip: f === 'request.md' ? /^#{1,2}\s+Decisions\s*$/ : null });
+    }
+  }
+  // An ADR file that cannot be read: neither its status nor its citations are known.
+  for (const file of state.unreadableAdrs ?? []) unreadable(file, 'it is there, but it cannot be read as a file');
+  // Each proposed or accepted ADR, but its History section and the ADRs it supersedes.
+  for (const a of state.adrs.values()) {
+    if (!['proposed', 'accepted'].includes(a.status)) continue;
+    check(a.file, a.text, { skip: /^#{1,2}\s+History\s*$/, exempt: chain(a.id) });
+  }
+}

package/src/v4/check.js

@@ -3,9 +3,11 @@
 // again, one ID in two files), then each paragraph's change (T8); then the
 // checks that read records (T10, checks.js). The base is the merge-base of
 // HEAD with main; the head is the working tree. It exits 0; with --strict, 1
-// when it prints a `not ok`. --strict raises every marker lint and an invalid
-// disposition to `not ok`; the hints that need judgment stay hints. A lost ID
-// of an open request's change spec is a hint, also under --strict (#230).
+// when it prints a `not ok`. A finding has the same severity in both modes:
+// the marker and ID lints are hints for the review, and only the exact rules
+// of checks.js are `not ok` (#238). With --issues <folder> it also checks the
+// work items that the caller saved there (issue-hints R1).
+import { relative } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { read, recordPath } from './base.js';
 import { loadConfig, loadSchema } from './config.js';
@@ -15,12 +17,30 @@ import { docsInScope, idsEverUsed, isShallow, notRead, parseScopes, rootNotOk, r
 import { Fail } from './spec.js';
 import { centralLookup } from './repos.js';
 import { checks } from './checks.js';
+import { loadPhrases } from './phrases.js';
+import { loadItems } from './issues.js';
 
-export function check({ top, opts }) {
+// A file or folder that al check cannot read, and that no check reports as
+// not ok, stops it with a refusal: never an internal error, never a pass (#238).
+const UNREADABLE = new Set(['EACCES', 'EPERM', 'EISDIR', 'ENOTDIR', 'ELOOP']);
+export function check(args) {
+  try {
+    return checkAll(args);
+  } catch (e) {
+    if (e instanceof Fail || !UNREADABLE.has(e.code) || !e.path) throw e;
+    throw new Fail(`${relative(args.top, e.path)} cannot be read`, 'make it readable, then run al check again');
+  }
+}
+
+function checkAll({ top, cwd, opts }) {
   const config = loadConfig(top);
   const root = rootProblem(config);
   if (root) throw new Fail(root, 'fix root: in .assuredloop/config.yaml');
   const { kinds } = loadSchema(top);
+  // A bad phrases: list is a refusal before anything is read (issue-hints D6).
+  const phrases = loadPhrases(config);
+  // The work items that the caller saved; a folder that is not there is a refusal.
+  const issues = opts.issues === undefined ? null : loadItems(cwd ?? top, opts.issues);
   const base = mergeBase(top);
   const now = parseScopes(docsInScope(top, config), kinds);
   const was = base ? parseScopes(docsInScope(top, config, base), kinds) : null;
@@ -28,6 +48,7 @@ export function check({ top, opts }) {
   // A change spec's removes: names spec paragraphs.
   const removes = [...now.scopes].filter(([s]) => s !== SPEC).flatMap(([, ps]) => ps.flatMap((p) => p.links.removes));
 
+  // Each marker and ID lint is a hint for the review, in every mode (#238).
   const lints = [...now.lints];
   const changes = [];
   for (const scope of new Set([...now.scopes.keys(), ...(was?.scopes.keys() ?? [])])) {
@@ -41,22 +62,20 @@ export function check({ top, opts }) {
     changes.push(...diffParagraphs(before, head).filter((c) => c.changes.length));
   }
 
-  const t10 = checks(top, { base, strict: opts.strict });
+  const t10 = checks(top, { base, phrases, issues });
   // An adopted paragraph needs no link while its text is the captured text (D16).
-  const shown = lints.filter((l) => !(l.code === 'no-link' && t10.adopted.has(l.id) && !l.file.startsWith('requests/')));
+  const shown = lints.filter((l) => !(l.code === 'no-link' && t10.adopted.has(l.id) && !l.file.startsWith('requests/'))).map((l) => ({ ...l, severity: 'hint' }));
   lints.length = 0;
   lints.push(...shown);
-  const severity = (l) => (opts.strict && !l.staysHint ? 'not ok' : l.severity);
   const body = notRead(top, config);
   // A root that config sets but that is not read is a not ok, as in al index (#218).
   const rootLine = rootNotOk(top, config);
   if (rootLine) body.push(rootLine);
-  body.push(...lints.map((l) => `${severity(l)} ${l.code} ${l.file}:${l.line} ${l.id ?? '-'} ${l.message}`));
+  body.push(...lints.map((l) => `${l.severity} ${l.code} ${l.file}:${l.line} ${l.id ?? '-'} ${l.message}`));
   if (base) body.push(...changes.map((c) => `${c.file} ${c.id} ${c.changes.join('+')}`));
   if (!lints.length) body.push('ok: no marker lint');
   body.push(...t10.findings.map((f) => `${f.severity} ${f.code} ${f.where} ${f.id} ${f.message}`));
-  // Under --strict every marker lint is a not ok.
-  const notOk = Boolean(rootLine) || lints.some((l) => severity(l) === 'not ok') || t10.findings.some((f) => f.severity === 'not ok');
+  const notOk = Boolean(rootLine) || lints.some((l) => l.severity === 'not ok') || t10.findings.some((f) => f.severity === 'not ok');
   // In an output repo: the central IDs that the branch's changed files cite (T12).
   const central = centralLookup(top);
   body.push(...central.body);
@@ -67,8 +86,9 @@ export function check({ top, opts }) {
   return {
     body,
     read: base ? `working tree · base ${base.slice(0, 7)} (merge-base with main)` : 'working tree · no base',
-    next: nextStep([...(rootLine ? ['not ok'] : []), ...lints.map(severity), ...t10.findings.map((f) => f.severity),
-      ...central.body.map((l) => (/^not ok /.test(l) ? 'not ok' : /^hint /.test(l) ? 'hint' : 'info'))], lints.some((l) => l.code === 'no-id')),
+    next: nextStep([...(rootLine ? ['not ok'] : []), ...lints.map((l) => l.severity), ...t10.findings.map((f) => f.severity),
+      ...central.body.map((l) => (/^not ok /.test(l) ? 'not ok' : /^hint /.test(l) ? 'hint' : 'info'))], lints.some((l) => l.code === 'no-id'),
+      t10.findings.some((f) => f.code === 'unsigned-requirement')),
     notKnown,
     exit: opts.strict && notOk ? 1 : 0,
   };
@@ -96,15 +116,16 @@ function deleted(top, l) {
     ...list(rec?.decisions).filter((d) => d?.wording?.source === source).map((d) => `decision ${d.id} names its wording`),
   ];
   const message = `${source} is deleted${facts.map((f) => `; ${f}`).join('')}. If that is on purpose, nothing more is needed: the ID is retired and never used again.`;
-  return { ...l, severity: 'hint', staysHint: true, message };
+  return { ...l, message };
 }
 
 // The Next line names what to do for what printed: a not ok, a hint, both, or
-// neither (#198).
-function nextStep(severities, noId) {
+// neither (#198); and for an unsigned requirement, how to get it signed (#238).
+function nextStep(severities, noId, unsigned) {
   const notOk = severities.includes('not ok');
   const hint = severities.includes('hint');
-  const addIds = noId ? '; al spec --add-ids <file> marks the paragraphs with no ID' : '';
+  const addIds = (noId ? '; al spec --add-ids <file> marks the paragraphs with no ID' : '')
+    + (unsigned ? '; for an unsigned requirement, run al index, then ask the owner to sign it (al record <name> signoff)' : '');
   if (notOk && hint) return `fix each not ok, and deal with each hint or say in the PR why it stays${addIds}`;
   if (notOk) return `fix each not ok${addIds}`;
   if (hint) return 'deal with each hint, or say in the PR why it stays';

package/src/v4/checks.js

@@ -17,6 +17,9 @@ import {
 import { NEAR, closeness, diffWords, marks, requirementWords, sentencesOf, showHunk } from './words.js';
 import { groupOf, sameBlocks } from './markers.js';
 import { isCentral } from './indexer.js';
+import { recordBlocks, supersededBlocks } from './blocks.js';
+import { phraseFindings } from './phrases.js';
+import { issueHints } from './issues.js';
 
 const DESIGN = ['component', 'interface', 'data', 'flow', 'choice'];
 const TIER = /^[ \t]*Tier:[ \t]*(0|1d|1|2|3|S)\b[ \t]*(?:—|–|--?)?[ \t]*(.*)$/m;
@@ -122,7 +125,7 @@ export function branchOf(top, now, was, base) {
   return { changes, captured, notAdopted, claim, commits, typo, isPromiseChange, uncovered };
 }
 
-export function checks(top, { base, strict = false }) {
+export function checks(top, { base, phrases = [], issues = null }) {
   const now = loadState(top);
   const was = base ? loadState(top, base) : null;
   const findings = [];
@@ -144,7 +147,7 @@ export function checks(top, { base, strict = false }) {
   } else if (claim.tier === '0') {
     for (const c of changes) {
       if (typo.has(c.name)) continue;
-      if (isPromiseChange(c)) add('not ok', 'path-claim', c.head ?? c.base, c.name, `path 0, but a ${(c.head ?? c.base).kind} paragraph is ${changeWord(c)} with no typo claim`);
+      if (isPromiseChange(c)) add('hint', 'path-claim', c.head ?? c.base, c.name, `path 0, but a ${(c.head ?? c.base).kind} paragraph is ${changeWord(c)} with no typo claim`);
       else if (!c.request && ['design', 'informative'].includes(groupOf((c.head ?? c.base).kind, now.kinds))) {
         add('hint', 'path-claim', c.head ?? c.base, c.name, `path 0, but a ${(c.head ?? c.base).kind} paragraph is ${changeWord(c)}: path 1d or 2?`);
       }
@@ -152,8 +155,8 @@ export function checks(top, { base, strict = false }) {
   } else if (claim.tier === '1d') {
     for (const c of changes) {
       const p = c.head ?? c.base;
-      if (isPromiseChange(c)) add('not ok', 'path-claim', p, c.name, `path 1d, but a ${p.kind} paragraph is ${changeWord(c)}; 1d is for names and wording of design paragraphs`);
-      else if (DESIGN.includes(p.kind) && (!c.head || !c.base)) add('not ok', 'path-claim', p, c.name, `path 1d, but a ${p.kind} paragraph is ${changeWord(c)}; 1d adds or removes no design paragraph`);
+      if (isPromiseChange(c)) add('hint', 'path-claim', p, c.name, `path 1d, but a ${p.kind} paragraph is ${changeWord(c)}; 1d is for names and wording of design paragraphs`);
+      else if (DESIGN.includes(p.kind) && (!c.head || !c.base)) add('hint', 'path-claim', p, c.name, `path 1d, but a ${p.kind} paragraph is ${changeWord(c)}; 1d adds or removes no design paragraph`);
     }
   }
   const byName = new Map(changes.map((c) => [c.name, c]));
@@ -252,7 +255,7 @@ export function checks(top, { base, strict = false }) {
         const who = named(r?.name ?? null, p.id);
         if (word === 'removes' && !t.req && !now.spec.has(t.id) && r) continue; // its own removal, done
         if (!t.req && removerOf(t.id)) add('hint', 'target-removed', p, who, `${ref}: target removed by ${removerOf(t.id)}; align this link`);
-        else add('not ok', 'unresolved-link', p, who, `${ref}: no such ID${adr ? ` (in ${adr.id})` : ''}`);
+        else add('hint', 'unresolved-link', p, who, `${ref}: no such ID${adr ? ` (in ${adr.id})` : ''}`);
       }
     }
   }
@@ -346,19 +349,29 @@ export function checks(top, { base, strict = false }) {
     const judged = judgeRequest(now, r, { typo, baseSpec });
     for (const j of judged) {
       if (j.status === 'pending') continue;
-      if (!j.valid) add(strict ? 'not ok' : 'hint', 'disposition', j.p, j.id, `${j.status} is not valid: ${j.reason}`);
+      if (!j.valid) add('hint', 'disposition', j.p, j.id, `${j.status} is not valid: ${j.reason}`);
       for (const n of j.notes) add(n.startsWith('near-match') ? 'hint' : 'info', n.startsWith('near-match') ? 'near-match' : 'disposition', j.p, j.id, n.replace(/^near-match /, ''));
     }
     const pending = judged.filter((j) => j.status === 'pending').map((j) => j.p.id);
     if (pending.length) add('info', 'disposition-pending', r.specFile, r.name, `${pending.length} of ${judged.length} paragraphs with a baseline effect have no disposition for their current version: ${pending.join(', ')}`);
   }
 
-  // ADRs (schema.md 5).
+  // ADRs (schema.md 5). An ADR's text may be rewritten when its decision
+  // stays, so a change is a hint for the review (#238). Links may be added to
+  // the heading marker of an accepted ADR: the same kind, each old link kept,
+  // the rest unchanged; that gives no finding.
+  const linksAdded = (a, h) => a.status === 'accepted' && a.head && h.head && a.rest === h.rest && a.head.kind === h.head.kind
+    && Object.entries(a.head.links).every(([k, refs]) => refs.every((x) => h.head.links[k].includes(x)));
   for (const [id, a] of was?.adrs ?? []) {
     if (!['accepted', 'superseded'].includes(a.status)) continue;
     const h = now.adrs.get(id);
-    if (!h) add('not ok', 'adr-changed', a.file, id, `${id} was ${a.status} and its file is gone; an ADR is superseded, never edited or deleted`);
-    else if (h.body !== a.body) add('not ok', 'adr-changed', h.head ?? h.file, id, `the text of ${id} changed after it was accepted; write a new ADR that supersedes it`);
+    if (!h) add('hint', 'adr-changed', a.file, id, `${id} was ${a.status} and its file is gone: check that its decision is not lost; an ADR that no longer holds is superseded by a new ADR, not deleted`);
+    else if (h.body !== a.body && !linksAdded(a, h)) add('hint', 'adr-changed', h.head ?? h.file, id, `${id}'s text changed: check that its decision is unchanged; if the decision changed, write a new ADR that supersedes it`);
+  }
+  for (const a of now.adrs.values()) {
+    if (!['proposed', 'accepted'].includes(a.status)) continue;
+    const missing = ['source', 'decides'].filter((w) => !a.head?.links[w].length);
+    if (missing.length) add('hint', 'adr-links', a.head ?? a.file, a.id, `${a.id} has ${missing.map((w) => `no ${w}:`).join(' and ')}; add the links to its marker`);
   }
   for (const a of now.adrs.values()) {
     for (const old of a.head?.links.supersedes ?? []) {
@@ -373,6 +386,17 @@ export function checks(top, { base, strict = false }) {
     for (const a of govern) add('hint', 'adr-governs', p, c.id, `check that ${a.id} still holds`);
   }
 
+  // The rules that block (#238): unsigned requirements, record evidence,
+  // unreadable records and citations of superseded ADRs.
+  recordBlocks(top, now, add);
+  supersededBlocks(top, now, add);
+
+  // Phrases for the review (issue-hints R2), and with --issues <folder> the
+  // hints from the work items that the caller saved (issue-hints R1); without
+  // it, no item is read and nothing is added.
+  phraseFindings(top, now, phrases, add);
+  if (issues) notKnown.push(...issueHints(top, now, phrases, add, issues));
+
   // Results (design.md 9): whether each one applies to the current text. The
   // commits they ran at are looked up in one batch.
   const results = loadResults(top);

package/src/v4/commands.js

@@ -107,11 +107,13 @@ function recordOrigin({ top, cwd, args, opts }) {
   return { body: [`Wrote ${dir}/origin/${file} and source ${file} in ${rec.path}`], next: `name it in a requirement's marker: <!-- R<n> from:${file} -->` };
 }
 
-// al record <name> signoff --source <where> [--words <quote>] [--presented <x>] [--transcribed-by <who>] [--yes]
+// al record <name> signoff --source <where> --words <quote> [--presented <x>] [--transcribed-by <who>] [--yes]
 function recordSignoff({ top, args, opts }) {
   const [name] = args;
   oneLine(opts, ['source', 'words', 'presented', 'transcribed-by']);
   if (!opts.source) throw new Fail('--source <where the owner signed> is missing', `al record ${name} signoff --source <where> --words <quote>`);
+  // A sign-off with no words is not valid in al check (DES-89, D10).
+  if (typeof opts.words !== 'string' || !opts.words) throw new Fail('--words <the owner\'s words> is missing', `pass the owner's words: al record ${name} signoff --source <where> --words <quote>`);
   const { dir, rec } = openRequest(top, name);
   const md = read(top, `${dir}/request.md`);
   const text = signedText(md);

package/src/v4/conclude.js

@@ -6,7 +6,7 @@
 // change of the branch, against the merge-base with main, counts as al check
 // counts it (branchOf, #217). With
 // --yes it writes the Outcome, sets the status and archives the request.
-import { mkdirSync, renameSync } from 'node:fs';
+import { mkdirSync, renameSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { Fail, day, exists, guard, isName, now, write } from './base.js';
 import { branchOf } from './checks.js';
@@ -112,13 +112,17 @@ export function conclude({ top, args, opts }) {
   const block = outcome(state, r, judged, top);
   const target = `requests/archive/${name}`;
   if (exists(top, target)) throw new Fail(`${target} already exists; a request name is never reused`, `al context ${name}`);
+  // The preview refuses for each reason that --yes refuses (#241).
+  const rec = openRecord(top, name);
+  if (!rec) throw new Fail(`${name} has no record .assuredloop/records/requests/${name}.yaml`, 'a v4 request is made with al new');
+  guard(top, [`${r.dir}/request.md`, `${target}/request.md`, rec.path]);
+  if (statSync(join(top, dirname(target)), { throwIfNoEntry: false })?.isDirectory() === false) {
+    throw new Fail(`${dirname(target)} is not a folder; nothing was written`, `make ${dirname(target)} a folder, then al conclude ${name} again`);
+  }
   const what = `Status: concluded, the Outcome in ${target}/request.md, status: concluded in the record, and ${r.dir}/ moved to ${target}/`;
   if (!opts.yes) {
     return { body: [`Would conclude ${name}: ${what}`, ...block.slice(2).map((l) => `  ${l}`)], read, next: 'run the same command with --yes to do it', notKnown };
   }
-  const rec = openRecord(top, name);
-  if (!rec) throw new Fail(`${name} has no record .assuredloop/records/requests/${name}.yaml`, 'a v4 request is made with al new');
-  guard(top, [`${r.dir}/request.md`, `${target}/request.md`, rec.path]);
   const md = withOutcome(withStatus(r.md), block);
   rec.doc.set('status', 'concluded');
   mkdirSync(dirname(join(top, target)), { recursive: true });

package/src/v4/indexer.js

@@ -6,7 +6,6 @@ import { readdirSync } from 'node:fs';
 import { join, posix } from 'node:path';
 import { isMap, parse, stringify } from 'yaml';
 import { parseMarkdown } from './markers.js';
-import { diffParagraphs } from './ids.js';
 import { git, mergeBase, fileAt, filesAt } from './git.js';
 import { loadConfig } from './config.js';
 import { SPEC, docsInScope, symlinkOn } from './scope.js';
@@ -310,11 +309,8 @@ export function index({ top, opts }) {
   }
 
   // The per-doc records: regenerable fields, written fresh; hints kept by ID.
-  // A change spec's IDs are its request's own, so they are compared as <request>/<ID>.
-  const qualified = (docs) => docs.flatMap((d) => d.paragraphs.map((p) => (d.request ? { ...p, id: `${d.request}/${p.id}` } : p)));
-  const diffs = main ? diffParagraphs(qualified(loadState(top, main, config, names).docs), qualified(now.docs)) : null;
-  const own = (d, id) => (d.request ? `${d.request}/${id}` : id);
-  const changeOf = new Map((diffs ?? []).filter((x) => x.sha256 !== null).map((x) => [`${x.file}\t${x.id}`, x.changes]));
+  // Nothing in them depends on the branch or its base, so main's index
+  // rebuilds a merged record as it is (#245).
   const outputs = [];
   for (const d of now.docs) {
     const path = docRecordPath(d.file);
@@ -328,13 +324,11 @@ export function index({ top, opts }) {
     }
     const status = d.adr ? d.text.split('\n').find((l) => l.trim())?.match(/^Status:\s*([a-z]+)/i)?.[1].toLowerCase() : undefined;
     const paragraphs = d.paragraphs.map((p) => {
-      const change = changeOf.get(`${d.file}\t${own(d, p.id)}`) ?? [];
       const hint = hints.get(p.id);
       if (hint && stale(hint, p)) body.push(`refresh hint: ${d.file} ${p.id}`);
-      return { id: p.id, ...(p.kind ? { kind: p.kind } : {}), text_sha256: p.sha256, display: p.displayNumber, ...(change.length ? { change } : {}), ...(hint ? { hint } : {}) };
+      return { id: p.id, ...(p.kind ? { kind: p.kind } : {}), text_sha256: p.sha256, display: p.displayNumber, ...(hint ? { hint } : {}) };
     });
-    const removed = (diffs ?? []).filter((x) => x.sha256 === null && x.file === d.file).map((x) => (d.request ? x.id.slice(d.request.length + 1) : x.id));
-    const rec = { schema: SCHEMA, file: d.file, ...(status ? { status } : {}), paragraphs, ...(removed.length ? { removed } : {}) };
+    const rec = { schema: SCHEMA, file: d.file, ...(status ? { status } : {}), paragraphs };
     outputs.push([path, stringify(rec, YAML_OPTIONS)]);
   }
   for (const [, rec] of recs) if (rec.changed) outputs.push([rec.path, recordText(rec)]);