@assuredloop/cli 0.2.4 → 2.0.0

package/src/v4/blocks.js

@@ -0,0 +1,333 @@
+// 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);
+    for (const b of a.by) if (out.has(b)) out.get(b).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, directly or through a chain (#1), 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);
+  // The ADRs that supersede `id`, directly or through a chain; never `id`
+  // itself, when the chain is a cycle.
+  const above = (id) => {
+    const seen = new Set([id]);
+    const walk = (x) => { for (const y of up(x)) if (!seen.has(y)) { seen.add(y); walk(y); } };
+    walk(id);
+    seen.delete(id);
+    return seen;
+  };
+  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) && ![...above(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.length) 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>"`);
+    for (const b of a.by) {
+      if (!state.adrs.has(b)) add('not ok', 'superseded-status', where, a.id, `${a.id} says it is superseded by ${b}, which does not exist`);
+      else if (!(state.adrs.get(b).head?.links.supersedes ?? []).some((x) => adrOf(x) === a.id)) {
+        add('not ok', 'superseded-status', where, a.id, `${a.id} says it is superseded by ${b}, but the marker of ${b} 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

@@ -12,11 +12,14 @@ import { diffParagraphs } from './ids.js';
 import { crossResults } from './repos.js';
 import { loadResults } from './results.js';
 import {
-  hasBaselineEffect, isPromise, loadState, named, qualify, requestOf, resolve, servesSigned,
+  adrParagraph, hasBaselineEffect, isPromise, loadState, named, qualify, requestOf, resolve, servesSigned,
 } from './state.js';
 import { NEAR, closeness, diffWords, marks, requirementWords, sentencesOf, showHunk } from './words.js';
-import { groupOf, sameBlocks } from './markers.js';
-import { isCentral } from './indexer.js';
+import { groupOf, markerLines, onlyLinksAdded, sameBlocks } from './markers.js';
+import { canAlignTo, declaredNow, 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]));
@@ -182,10 +185,18 @@ export function checks(top, { base, strict = false }) {
     }
   }
 
-  // Requirement words in a non-promise kind (design.md 3).
+  // In the central repo, `central:X` is its own X (design.md 12).
+  const self = (ref) => (isCentral(now.config) && ref.startsWith('central:') ? ref.slice('central:'.length) : ref);
+
+  // Requirement words in a non-promise kind (design.md 3). A paragraph that
+  // builds on a promise paragraph that exists applies that promise: no hint.
+  const appliesPromise = (p, request) => {
+    const own = new Set(now.requests.get(request)?.paras.keys() ?? []);
+    return p.links.buildsOn.some((ref) => promise(resolve(now, qualify(self(ref), request, own))?.p?.kind));
+  };
   for (const c of changes) {
     const p = c.head;
-    if (!p?.kind || promise(p.kind) || !c.changed) continue;
+    if (!p?.kind || promise(p.kind) || !c.changed || appliesPromise(p, c.request)) continue;
     const w = requirementWords(p.text);
     if (w.length) add('hint', 'promise-kind', p, c.name, `promise kind? a ${p.kind} paragraph holds ${w.join(', ')}`);
   }
@@ -252,7 +263,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})` : ''}`);
       }
     }
   }
@@ -260,8 +271,7 @@ export function checks(top, { base, strict = false }) {
   // Design links (design.md 3): a design or approach paragraph of a change
   // spec that serves a requirement, where promise paragraphs of the same
   // change spec serve it, and that builds on or changes none of them. In the
-  // central repo, `central:X` is its own X (design.md 12).
-  const self = (ref) => (isCentral(now.config) && ref.startsWith('central:') ? ref.slice('central:'.length) : ref);
+  // central repo, `central:X` is its own X (self, above).
   for (const r of open) {
     const own = new Set(r.paras.keys());
     const key = (ref) => qualify(self(ref), r.name, own).key;
@@ -302,9 +312,24 @@ export function checks(top, { base, strict = false }) {
   }
 
   // Bindings whose target changed since they were bound (design.md 4, 6).
+  let declared = null;
+  let alignable = null;
   for (const r of open) {
     for (const b of Array.isArray(r.data?.bindings) ? r.data.bindings : []) {
       if (!b?.target || !b.holder || !b.target_sha256) continue;
+      // A holder paragraph whose text changed since the link was bound
+      // (removed-links/R2, #11). Output files and requirements are not
+      // paragraphs; a link no longer declared is history (#2); the target
+      // must be one that al index --align can move the binding to.
+      if (b.holder_sha256) {
+        const hq = qualify(String(b.holder), null);
+        const hp = hq.req ? now.requests.get(hq.req)?.paras.get(hq.id) : now.spec.get(hq.id) ?? adrParagraph(now, hq.id);
+        declared ??= declaredNow(top, now);
+        alignable ??= canAlignTo(now);
+        if (hp && hp.sha256 !== b.holder_sha256 && declared(b) && alignable(b.target)) {
+          add('hint', 'holder-changed', hp, b.holder, `${b.link} ${b.target}: this paragraph changed after the link was bound. Check that it still ${b.link} ${b.target}, then al index --align ${b.holder}`);
+        }
+      }
       const t = qualify(String(b.target), null);
       if (t.cross) continue;
       const cur = resolve(now, t);
@@ -313,6 +338,9 @@ export function checks(top, { base, strict = false }) {
       if ((Array.isArray(r.data?.dispositions) ? r.data.dispositions : []).some((d) => d?.source === b.holder && d.spec === b.target && d.spec_sha256 === cur.sha)) continue;
       // A superseded ADR's links are history (schema.md 5).
       if (now.adrs.get(String(b.holder))?.status === 'superseded') continue;
+      // A link that its holder no longer declares, or whose holder is gone, is history too (#2).
+      declared ??= declaredNow(top, now);
+      if (!declared(b)) continue;
       const hq = qualify(String(b.holder), null);
       const hp = hq.req ? now.requests.get(hq.req)?.paras.get(hq.id) : now.spec.get(hq.id);
       const msg = /^[RQ]\d+$/.test(t.id ?? '')
@@ -346,27 +374,39 @@ 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). Links may be added to the heading marker of an
-  // accepted ADR: the same kind, each old link kept, the rest unchanged.
-  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)));
+  // 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, with nothing else in that line
+  // changed (#4) and the rest unchanged; that gives no finding.
+  const linksAdded = (a, h) => a.status === 'accepted' && a.head && h.head && a.rest === h.rest
+    && onlyLinksAdded(a.marker, h.marker, now.kinds);
   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 && !linksAdded(a, h)) 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`);
+  }
+  // Every ADR, whatever its status (#4): a first line that is not a known
+  // status, and a marker line that holds more than its ID, a kind and links.
+  for (const a of now.adrs.values()) {
+    if (!a.known) add('hint', 'adr-status', `${a.file}:1`, a.id, `${a.id}'s first line is not a status that al knows: write "Status: proposed", "Status: accepted" or "Status: superseded by ADR-<n>" (or by a list, "ADR-11, ADR-12")`);
+    for (const m of markerLines(a.text, now.kinds)) {
+      const where = `${a.file}:${m.line}`;
+      if (!m.extras) add('hint', 'adr-marker', where, m.id, `the marker line of ${m.id} is not a well-formed marker, so al does not read it: write "<!-- ${m.id} <kind> <links> -->" alone on the line; a page can show text after its -->`);
+      else if (m.extras.length) add('hint', 'adr-marker', where, m.id, `the marker of ${m.id} holds more than its ID, a kind and links: ${m.extras.map((x) => `"${x}"`).join(', ')}; a page can show text that it hides`);
+    }
   }
   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(strict ? 'not ok' : '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`);
+    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 ?? []) {
@@ -381,6 +421,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);