dotmd-cli 0.86.0 → 0.87.0

package/bin/dotmd.mjs

@@ -248,6 +248,7 @@ Analyze:
   diff [file] [--summarize]         Show changes since last updated date
   summary <file> [--json]           AI summary of a document
   glossary <term> [--list] [--json] Look up domain terms + related docs
+  decisions [doc|id] [--all|--check] Open and held decisions, read from the corpus
 
 Validate & Fix:
   doctor [--apply]                  Auto-fix everything: refs, membership, lint, long fields, dates, index (preview by default)
@@ -1329,6 +1330,23 @@ plans, and checklist progress. Plans-only view.
 Options:
   --json                 Output as JSON`,
 
+  decisions: `runlist decisions — the open and held decisions, read from the corpus
+
+  runlist decisions             every open and held decision, one line each
+  runlist decisions <doc>       one document, by path, filename or slug
+  runlist decisions <ID>        one record, whole, as it is written
+  runlist decisions --all       every disposition, not only the pending ones
+  runlist decisions --json      the same rows as data
+  runlist decisions --check     every item it could not read or that is incomplete; exit 1 if any
+
+A decision is an item in a decisions section (a heading naming the section word
+in its first 4 words): a heading, bold lead, bullet or table row whose first
+token is an id. A register is a fenced block whose first line carries
+decisions.register.statusLine; its rows are \`ID  text\`. A disposition is read
+from a \`Disposition:\` line or a row's opening word, then from prose when
+decisions.prose is on, then from the block or bold lead above it. Configure it
+with \`export const decisions = { ... }\` (see src/decisions.mjs).`,
+
   glossary: `runlist glossary <term> — look up domain terms and related docs
 
 Searches the glossary table in your docs for matching terms.
@@ -1898,6 +1916,7 @@ async function main() {
   if (command === 'flags') { const { runFlags } = await import('../src/flags.mjs'); runFlags(restArgs, config); return; }
   if (command === 'flag') { const { runFlag } = await import('../src/flags.mjs'); runFlag(restArgs, config); return; }
   if (command === 'glossary') { const { runGlossary } = await import('../src/glossary.mjs'); runGlossary(restArgs, config); return; }
+  if (command === 'decisions') { const { runDecisions } = await import('../src/decisions.mjs'); runDecisions(restArgs, config); return; }
   if (command === 'export') { const { runExport } = await import('../src/export.mjs'); runExport(restArgs, config, { dryRun, root: rootArg, type: typeArg }); return; }
 
   // Lifecycle commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.86.0",
+  "version": "0.87.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/commands.mjs

@@ -88,6 +88,7 @@ const definitions = [
     form('sync <check-name> [findings]', { subcommands: ['sync'], args: positionals(1, 2), dashPositionalsAfter: 1 }),
   ]),
   command('glossary', none, 'read', [form('[term]', { args: positionals(0, 1), options: [flag('--list'), flag('--json')] })]),
+  command('decisions', none, 'read', [form('[doc-or-id]', { args: positionals(0, 1), options: [flag('--all'), flag('--json'), flag('--check')] })]),
   command('modules', none, 'read', [form('', { options: [value('--sort'), value('--limit'), flag('--all'), flag('--json')] })]),
   command('module', none, 'read', [form('<name>', { args: positionals(1, 1), options: [value('--sort'), flag('--json')] })]),
   command('surfaces', none, 'read', [form('', { options: [flag('--json')] })]),

package/src/decisions.mjs

@@ -0,0 +1,540 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { buildIndex, resolveDocArg } from './index.mjs';
+import { die } from './util.mjs';
+
+// `runlist decisions` — the open decisions, read from the corpus, never typed.
+//
+// A decision is an item inside a decisions section of a document: a heading,
+// a bold lead, a list bullet or a table row whose first token is an id. A
+// register is a fenced block whose first line carries the configured status
+// line; its rows are `ID  text` and index the records the documents hold.
+//
+// Config (`runlist.config.mjs`), every key optional:
+//   export const decisions = {
+//     section: 'Decisions',          // the word a decisions heading names
+//     types: ['plan'],               // which document types carry decisions
+//     paths: ['docs/plans'],         // only documents under these, when set
+//     id: '[A-Z]{1,3}-?\\d{1,3}[a-z]?',
+//     prose: false,                  // also read a disposition out of prose
+//     vocabulary: { open: [...], held: [...], ruled: [...], closed: [...] },
+//     patterns: { ruled: ['regex source', ...] }, // extra prose markers per disposition
+//     requires: { open: ['prose', 'citation', 'answers'] },
+//     answers: ['regex source', ...], // extra phrases the answers detector accepts
+//     register: { file, statusLine },
+//     listHeading: 'Waiting on a decision:',
+//   };
+
+export const DEFAULTS = Object.freeze({
+  section: 'Decisions',
+  types: ['plan'],
+  paths: null,
+  id: '[A-Z]{1,3}-?[A-Z]?\\d{1,3}[a-z]?',
+  prose: false,
+  vocabulary: {
+    ruled: ['ruled', 'ratified', 'resolved', 'approved', 'decided', 'answered', 'settled', 'locked'],
+    closed: ['closed', 'withdrawn', 'superseded', 'overtaken', 'retired', 'cancelled', 'canceled', 'not a decision'],
+    held: ['held', 'on hold', 'deferred', 'paused', 'parked', 'blocked'],
+    open: ['open', 'unruled', 'unratified', 'pending', 'awaiting', 'undecided', 'unanswered', 'tbd'],
+  },
+  patterns: {},
+  requires: {},
+  answers: [],
+  register: null,
+  listHeading: 'Waiting on a decision:',
+});
+
+export const PENDING = new Set(['open', 'held']);
+const KINDS = ['ruled', 'closed', 'held', 'open'];
+const MAX_BODY_LINES = 24;
+
+const escapeRe = s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+export function decisionSettings(raw = {}) {
+  const s = { ...DEFAULTS, ...raw };
+  s.vocabulary = { ...DEFAULTS.vocabulary, ...(raw.vocabulary ?? {}) };
+  s.types = [].concat(s.types ?? DEFAULTS.types);
+  return s;
+}
+
+// ── Grammar ──────────────────────────────────────────────────────────────────
+
+function wordsRe(words) {
+  return words.map(w => escapeRe(w).replace(/\s+/g, '\\s+')).join('|');
+}
+
+// A heading opens a decisions scope when the section word is one of its first
+// 4 words, after any leading enumerator or marker. A heading that only
+// mentions a decision further along is about something else.
+export function isDecisionHeading(text, section = DEFAULTS.section) {
+  const stem = section.toLowerCase().replace(/s$/, '');
+  const stripped = text
+    .replace(/^[^\p{L}\p{N}]+/u, '')
+    .replace(/^(?:[A-Z]|[A-Z]?\d+[A-Za-z]?(?:\.\d+)*)[.)]\s+(?:[—–-]\s+)?/, '')
+    .replace(/^[^\p{L}\p{N}]+/u, '');
+  const words = stripped.split(/\s+/)
+    .filter(w => /[\p{L}\p{N}]/u.test(w))
+    .slice(0, 4)
+    .map(w => w.toLowerCase().replace(/[^\p{L}\p{N}-]+$/u, ''));
+  return words.some(w => w === stem || w === `${stem}s`);
+}
+
+function itemPatterns(id) {
+  return [
+    { kind: 'register', re: new RegExp(`^(${id})\\s{1,3}(\\S.*)$`), registerOnly: true },
+    { kind: 'table', re: new RegExp(`^\\|\\s*\\**(${id})\\**\\s*\\|(.*)$`) },
+    { kind: 'heading', re: new RegExp(`^(#{2,6})\\s+\\**(${id})\\b[\\s,.:—-]*(.*)$`) },
+    { kind: 'record', re: new RegExp(`^\\*\\*(${id})\\b[\\s,.:—-]+(.*)$`) },
+    { kind: 'list', re: new RegExp(`^[-*]\\s+(?:\\[[ xX]\\]\\s+)?\\**(${id})\\b[\\s,.:—-]+(.*)$`) },
+  ];
+}
+
+// An item that presents as a decision and carries no id: a bold `Decision`
+// lead inside a decisions section.
+const UNNAMED = /^(?:[-*]\s+(?:\[[ xX]\]\s+)?)?\*\*Decisions?\b/i;
+
+/**
+ * Every decision item in one document's text, in file order. Pure.
+ * Returns `{id, line, kind, level, context, lines, text}`; `id` is null for an
+ * unnamed item.
+ */
+export function parseDecisionItems(text, settings = DEFAULTS) {
+  const s = decisionSettings(settings);
+  const lines = text.split('\n');
+  // Frontmatter is blanked so line numbers stay file coordinates.
+  if (lines[0] === '---') {
+    const end = lines.indexOf('---', 1);
+    if (end > 0) for (let i = 0; i <= end; i++) lines[i] = '';
+  }
+  const patterns = itemPatterns(s.id);
+  const statusLine = s.register?.statusLine?.trim().toLowerCase() ?? null;
+  const vocab = s.vocabulary;
+  const items = [];
+
+  let fence = null;
+  let inRegister = false;
+  let scope = 0; // the level of the decisions heading in force, 0 for none
+  let context = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trimEnd();
+    const f = line.match(/^\s*(`{3,}|~{3,})/);
+    if (f) {
+      if (fence === null) {
+        fence = f[1][0];
+        const first = (lines[i + 1] ?? '').trim();
+        inRegister = !!statusLine && first.toLowerCase().includes(statusLine);
+        context = inRegister ? leadingDisposition(first, vocab) : null;
+        if (inRegister) i++; // the status line is not a row
+      } else if (f[1][0] === fence) {
+        fence = null;
+        inRegister = false;
+        context = null;
+      }
+      closeOpen(items);
+      continue;
+    }
+    if (fence !== null && !inRegister) continue;
+
+    if (fence === null) {
+      const h = line.match(/^(#{1,6})\s+(.+)$/);
+      if (h) {
+        const level = h[1].length;
+        // A heading that shouts a disposition (`Decisions, both RESOLVED
+        // 2025-01-01`) marks the items under it, as a bold lead does.
+        context = s.prose ? proseDisposition(h[2], vocab, s.patterns, { shoutedOnly: true }) : null;
+        const open = items.at(-1);
+        if (open && !open.closed && open.kind === 'heading' && level > open.level) {
+          // A subheading inside a heading record is part of it.
+        } else {
+          closeOpen(items);
+        }
+        if (isDecisionHeading(h[2], s.section)) scope = level;
+        else if (scope && level <= scope) scope = 0;
+      }
+      const lead = line.match(/^\*\*([^*]{1,120})\*\*/);
+      if (lead && !patterns.some(p => p.re.test(line))) {
+        const kind = leadingDisposition(lead[1], vocab);
+        if (kind) context = kind;
+      }
+    }
+
+    const inScope = inRegister || scope > 0;
+    let matched = false;
+    if (inScope) {
+      for (const p of patterns) {
+        if (Boolean(p.registerOnly) !== inRegister) continue;
+        const m = line.match(p.re);
+        if (!m) continue;
+        closeOpen(items);
+        const heading = p.kind === 'heading';
+        items.push({
+          id: heading ? m[2] : m[1],
+          line: i + 1,
+          kind: p.kind,
+          level: heading ? m[1].length : 0,
+          context,
+          lines: [heading ? m[3] : m[2]],
+        });
+        matched = true;
+        break;
+      }
+      if (!matched && !inRegister && UNNAMED.test(line)) {
+        closeOpen(items);
+        items.push({ id: null, line: i + 1, kind: 'unnamed', level: 0, context, lines: [line] });
+        matched = true;
+      }
+    }
+    if (matched) continue;
+
+    const open = items.at(-1);
+    if (!open || open.closed) continue;
+    if (open.kind === 'register') { open.closed = true; continue; }
+    if (open.kind === 'heading') {
+      if (/^#{1,6}\s/.test(line) && line.match(/^(#{1,6})/)[1].length <= open.level) { open.closed = true; continue; }
+      open.lines.push(line);
+      continue;
+    }
+    if (line.trim() === '' || /^#{1,6}\s/.test(line) || open.lines.length >= MAX_BODY_LINES) {
+      if (line.trim() === '' && open.lines.length < MAX_BODY_LINES && !open.sawBlank) { open.sawBlank = true; continue; }
+      open.closed = true;
+      continue;
+    }
+    open.lines.push(line);
+    open.sawBlank = false;
+  }
+
+  return items.map(({ id, line, kind, level, context: ctx, lines: body }) => ({
+    id, line, kind, level, context: ctx, text: body.join('\n').trim(),
+  }));
+}
+
+function closeOpen(items) {
+  const open = items.at(-1);
+  if (open) open.closed = true;
+}
+
+// ── Disposition ──────────────────────────────────────────────────────────────
+
+/** The disposition a line opens with (`RULED 2026-09-21: …`, `Open, waiting…`). */
+export function leadingDisposition(text, vocab = DEFAULTS.vocabulary) {
+  const t = text.replace(/^[\s*_`]+/, '');
+  for (const kind of KINDS) {
+    if (new RegExp(`^(?:${wordsRe(vocab[kind] ?? [])})\\b`, 'i').test(t)) return kind;
+  }
+  return null;
+}
+
+/** An explicit `Disposition: RULED 2026-09-21` line, or a shouted opening word. */
+export function explicitDisposition(text, vocab = DEFAULTS.vocabulary) {
+  const line = text.match(/\bDisposition\**\s*:\s*\**\s*(\S[^\n]*)$/im);
+  if (line) return leadingDisposition(line[1], vocab);
+  const first = text.trimStart().match(/^[A-Z][A-Z ]*\b/);
+  if (first) {
+    const kind = leadingDisposition(first[0], vocab);
+    if (kind) return kind;
+  }
+  return null;
+}
+
+const DATE = '20\\d{2}-\\d{2}-\\d{2}';
+
+/**
+ * Every disposition word in prose, in order. A ruling word counts only with a
+ * date right against it; a closing word only with a reason after it.
+ */
+export function proseMarkers(text, vocab = DEFAULTS.vocabulary, patterns = {}) {
+  const found = [];
+  const add = (kind, re, test = () => true) => {
+    for (const m of text.matchAll(re)) {
+      if (!test(m)) continue;
+      found.push({ kind, index: m.index, caps: /[A-Z]/.test(m[1]) && m[1] === m[1].toUpperCase() });
+    }
+  };
+  add('ruled', new RegExp(`\\b(${wordsRe(vocab.ruled ?? [])})\\b[,:;—-]?\\s*(?:\\([^)]{0,48}?)?(?:on\\s+|at\\s+|the\\s+)?${DATE}`, 'gi'));
+  add('closed', new RegExp(`\\b(${wordsRe(vocab.closed ?? [])})\\b`, 'gi'),
+    m => text.slice(m.index + m[0].length).replace(/[^a-z]/gi, '').length >= 12);
+  add('held', new RegExp(`\\b(${wordsRe(vocab.held ?? [])})\\b`, 'gi'));
+  add('open', new RegExp(`\\b(${wordsRe(vocab.open ?? [])})\\b`, 'gi'));
+  for (const kind of KINDS) {
+    for (const src of patterns[kind] ?? []) add(kind, new RegExp(`(${src})`, 'gi'));
+  }
+  return found.sort((a, b) => a.index - b.index);
+}
+
+/**
+ * Prose disposition: a shouted word is the row's own line and the last one
+ * wins, because rows are edited in place; with nothing shouted, an answer
+ * outranks a question.
+ */
+export function proseDisposition(text, vocab = DEFAULTS.vocabulary, patterns = {}, { shoutedOnly = false } = {}) {
+  const markers = proseMarkers(text, vocab, patterns);
+  if (!markers.length) return null;
+  const caps = markers.filter(m => m.caps);
+  if (caps.length) return caps.at(-1).kind;
+  if (shoutedOnly) return null;
+  for (const kind of KINDS) if (markers.some(m => m.kind === kind)) return kind;
+  return null;
+}
+
+// Explicit line first, then a shouted word in the item, then the block or bold
+// lead the item sits under, then any word in its prose. A lead such as
+// `**Ruled 2026-07-02:**` is a deliberate mark over the rows below it; a
+// lowercase `open` inside a row is as often about something else.
+export function dispositionOf(item, settings = DEFAULTS) {
+  const s = decisionSettings(settings);
+  const prose = opts => (s.prose ? proseDisposition(item.text, s.vocabulary, s.patterns, opts) : null);
+  return explicitDisposition(item.text, s.vocabulary)
+    ?? prose({ shoutedOnly: true })
+    ?? item.context
+    ?? prose()
+    ?? null;
+}
+
+// ── The record's parts ───────────────────────────────────────────────────────
+
+const CITATION = [
+  /`[^`]*\.(?:ts|tsx|swift|mjs|js|sql|json|sh|py|yaml|yml|kt|java|rs|css|graphql|go|rb)(?::\d+)?[^`]*`/,
+  /\b[\w@./-]+\.(?:ts|tsx|swift|mjs|sql|graphql|go|rb|py)(?::\d+(?:-\d+)?)?\b/,
+  /`[^`]*:\d+(?:-\d+)?`/,
+  /\[[^\]]+\]\([^)]*\.md[^)]*\)/,
+  /\b[\w-]+\.md\b/,
+];
+const ANSWER_PHRASE = /\b(each answer|either answer|both answers|the alternative|what visibly (?:changes|differs))\b/i;
+const OPTION_CLAUSE = /(?:^|[.;!?]\s+|\|\s*|\*\*)([A-Z][^.:;|\n]{1,70}):\s+[a-z"']/g;
+
+export function sentences(text) {
+  return text.replace(/\s+/g, ' ').split(/(?<=[.?!])\s+(?=[A-Z"'`*(])/).map(t => t.trim()).filter(Boolean);
+}
+
+/** Which parts an item's own text carries, from the detectors the tool ships. */
+export function recordParts(text, settings = DEFAULTS) {
+  const s = decisionSettings(settings);
+  const body = text.replace(/\s+/g, ' ').trim();
+  const prose = sentences(text).some(t => !t.endsWith('?') && t.replace(/[^a-z]/gi, '').length >= 40);
+  const citation = CITATION.some(re => re.test(text));
+  const extra = (s.answers ?? []).map(src => new RegExp(src, 'i'));
+  const answers = ANSWER_PHRASE.test(body)
+    || extra.some(re => re.test(body))
+    || [...body.matchAll(OPTION_CLAUSE)].length >= 2
+    || (/\bYes\b\s*[:,]/i.test(body) && /\bNo\b\s*[:,]/i.test(body));
+  return { prose, citation, answers };
+}
+
+/** Documents an item points at, by basename. */
+export function pointedDocs(text) {
+  const out = new Set();
+  for (const m of text.matchAll(/\[[^\]]*\]\(([^)\s]*\.md)(?:#[^)]*)?\)/g)) out.add(m[1].split('/').pop());
+  for (const m of text.matchAll(/\b([\w.-]+\.md)\b/g)) out.add(m[1]);
+  return out;
+}
+
+// ── Assembly ─────────────────────────────────────────────────────────────────
+
+/**
+ * Every item across the given documents with its disposition, its parts (its
+ * own plus a linked record's) and what it is missing. Pure.
+ * @param {{path: string, text: string}[]} docs
+ */
+export function analyzeDecisions(docs, settings = DEFAULTS) {
+  const s = decisionSettings(settings);
+  const items = [];
+  for (const doc of docs) {
+    for (const item of parseDecisionItems(doc.text, s)) {
+      items.push({
+        ...item,
+        doc: doc.path,
+        file: path.basename(doc.path),
+        disposition: dispositionOf(item, s),
+        own: recordParts(item.text, s),
+        points: pointedDocs(item.text),
+      });
+    }
+  }
+
+  const byId = new Map();
+  for (const item of items) {
+    if (!item.id) continue;
+    if (!byId.has(item.id)) byId.set(item.id, []);
+    byId.get(item.id).push(item);
+  }
+  const linked = (a, b) => a !== b && a.file !== b.file && (a.points.has(b.file) || b.points.has(a.file));
+
+  for (const item of items) {
+    item.peers = item.id ? byId.get(item.id).filter(p => linked(item, p)) : [];
+    const parts = { ...item.own };
+    for (const peer of item.peers) for (const k of Object.keys(parts)) if (peer.own[k]) parts[k] = true;
+    item.parts = parts;
+    // A register row that indexes this record governs its disposition.
+    const row = item.kind === 'register' ? null : item.peers.find(p => p.kind === 'register');
+    item.effective = row?.disposition ?? item.disposition;
+    const missing = [];
+    if (!item.id) missing.push('id');
+    if (!item.disposition) missing.push('disposition');
+    for (const part of s.requires[item.disposition] ?? []) if (!parts[part]) missing.push(part);
+    item.missing = missing;
+  }
+  return items;
+}
+
+/** The pending rows, one per decision: linked pairs collapse, a register row preferred. */
+export function pendingRows(items, { doc = null, all = false } = {}) {
+  let rows = items.filter(i => i.id && (all || PENDING.has(i.effective)));
+  if (doc) rows = rows.filter(i => i.doc === doc);
+  const kept = [];
+  const rank = i => (i.kind === 'register' ? 0 : 1);
+  for (const item of [...rows].sort((a, b) => rank(a) - rank(b))) {
+    const dup = kept.find(k => k.id === item.id && (k.doc === item.doc || k.peers.includes(item)));
+    if (!dup) kept.push(item);
+  }
+  const shared = new Map();
+  for (const k of kept) shared.set(k.id, (shared.get(k.id) ?? 0) + 1);
+  return kept
+    .sort((a, b) => a.id.localeCompare(b.id, 'en', { numeric: true }) || a.doc.localeCompare(b.doc))
+    .map(item => ({
+      id: item.id,
+      label: shared.get(item.id) > 1 ? `${item.id} (${item.file})` : item.id,
+      doc: item.doc,
+      line: item.line,
+      kind: item.kind,
+      disposition: item.effective,
+      missing: item.missing,
+      text: renderLine(item),
+    }));
+}
+
+const clean = t => t
+  .replace(/\|/g, ' ')
+  .replace(/\*\*/g, '')
+  .replace(/`/g, '')
+  .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+  .replace(/^\s*(?:[-*]\s+)?Disposition\s*:[^\n]*$/gim, '')
+  .replace(/\s+/g, ' ')
+  .trim();
+
+function renderLine(item) {
+  const partsMissing = item.missing.filter(m => m !== 'id' && m !== 'disposition');
+  if (partsMissing.length) return `(record incomplete: missing ${partsMissing.join(', ')})`;
+  const body = clean(item.text);
+  if (item.kind === 'register') return body;
+  const parts = sentences(body);
+  const at = parts.findIndex(t => t.endsWith('?'));
+  if (at === -1) return body.slice(0, 400);
+  return [parts[at], ...parts.slice(at + 1, at + 4)].join(' ');
+}
+
+/** Defects, one per finding, for `--check`. */
+export function decisionDefects(items) {
+  const out = [];
+  for (const item of items) {
+    if (item.missing.length) {
+      out.push({ doc: item.doc, line: item.line, id: item.id, message: `missing ${item.missing.join(', ')}` });
+    }
+  }
+  const seen = new Map();
+  for (const item of items) {
+    if (!item.id) continue;
+    const key = `${item.doc}#${item.id}#${item.kind === 'register'}`;
+    const prior = seen.get(key);
+    if (prior) out.push({ doc: item.doc, line: item.line, id: item.id, message: `id used again in this document (first at line ${prior.line})` });
+    else seen.set(key, item);
+  }
+  for (const item of items) {
+    if (!PENDING.has(item.disposition)) continue;
+    for (const peer of item.peers) {
+      if (peer.disposition === 'ruled' || peer.disposition === 'closed') {
+        out.push({ doc: item.doc, line: item.line, id: item.id, message: `${item.disposition} here, ${peer.disposition} at ${peer.doc}:${peer.line}` });
+      }
+    }
+  }
+  return out.sort((a, b) => a.doc.localeCompare(b.doc) || a.line - b.line);
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+export function loadDecisionDocs(config, settings) {
+  const s = decisionSettings(settings);
+  const types = new Set(s.types);
+  const archiveDir = config.archiveDir ?? 'archived';
+  const { docs } = buildIndex(config, { fast: true });
+  return docs
+    // A document whose frontmatter did not parse has no type; it is read rather than dropped.
+    .filter(d => (types.has(d.type) || !d.type) && d.status !== 'archived' && !d.path.split('/').includes(archiveDir))
+    .filter(d => !s.paths || [].concat(s.paths).some(p => d.path === p || d.path.startsWith(`${p.replace(/\/$/, '')}/`)))
+    .map(d => ({ path: d.path, text: readFileSync(path.join(config.repoRoot, d.path), 'utf8') }));
+}
+
+export function runDecisions(args, config) {
+  const settings = decisionSettings(config.raw?.decisions ?? {});
+  const json = args.includes('--json');
+  const all = args.includes('--all');
+  const check = args.includes('--check');
+  const target = args.find(a => !a.startsWith('-')) ?? null;
+
+  const docs = loadDecisionDocs(config, settings);
+  const items = analyzeDecisions(docs, settings);
+
+  if (check) {
+    const defects = decisionDefects(items);
+    if (json) process.stdout.write(`${JSON.stringify({ ok: defects.length === 0, items: items.length, defects }, null, 2)}\n`);
+    else {
+      for (const d of defects) process.stdout.write(`${d.doc}:${d.line}  ${d.id ?? '(no id)'}  ${d.message}\n`);
+      process.stdout.write(`${items.length} decision items in ${docs.length} documents; ${defects.length} defects.\n`);
+    }
+    if (defects.length) process.exitCode = 1;
+    return;
+  }
+
+  let docFilter = null;
+  if (target) {
+    const idRe = new RegExp(`^(?:${settings.id})$`);
+    const resolved = idRe.test(target) ? null : resolveDocArg(target, config, { dieOnMiss: false });
+    if (resolved) docFilter = path.relative(config.repoRoot, resolved).split(path.sep).join('/');
+    else if (idRe.test(target)) return showRecord(target, items, docs, json);
+    else die(`No document or decision id matches "${target}".`);
+  }
+
+  const rows = pendingRows(items, { doc: docFilter, all });
+  if (json) {
+    process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
+    return;
+  }
+  if (!rows.length) {
+    process.stdout.write(docFilter ? `No open or held decisions in ${docFilter}.\n` : 'No open or held decisions.\n');
+  } else {
+    process.stdout.write(`${settings.listHeading}\n\n`);
+    for (const row of rows) {
+      const tag = all ? `[${row.disposition ?? 'none'}] ` : '';
+      process.stdout.write(`${row.label}  ${tag}${row.text}\n`);
+    }
+  }
+  const unread = items.filter(i => (!docFilter || i.doc === docFilter) && (!i.id || !i.disposition));
+  if (unread.length) {
+    const noId = unread.filter(i => !i.id).length;
+    process.stderr.write(`${unread.length} decision items could not be read (${noId} with no id, ${unread.length - noId} with no disposition); runlist decisions --check lists them.\n`);
+  }
+}
+
+function showRecord(id, items, docs, json) {
+  const hits = items.filter(i => i.id === id);
+  if (!hits.length) die(`No decision ${id} in any document.`);
+  if (json) {
+    process.stdout.write(`${JSON.stringify(hits.map(h => ({ id, doc: h.doc, line: h.line, kind: h.kind, disposition: h.disposition, missing: h.missing, text: h.text })), null, 2)}\n`);
+    return;
+  }
+  const texts = new Map(docs.map(d => [d.path, d.text.split('\n')]));
+  hits.forEach((h, n) => {
+    const lines = texts.get(h.doc);
+    const bodyLines = h.text.split('\n').filter(l => l.trim() !== '').length;
+    // The record as written: its first line through the last line of its body.
+    let end = h.line - 1;
+    let seen = 0;
+    while (end < lines.length && seen < bodyLines) {
+      if (lines[end].trim() !== '') seen++;
+      end++;
+    }
+    if (n) process.stdout.write('\n');
+    process.stdout.write(`${h.doc}:${h.line}  ${h.disposition ?? 'no disposition'}\n`);
+    process.stdout.write(`${lines.slice(h.line - 1, end).join('\n').trimEnd()}\n`);
+  });
+}

package/src/fix-refs.mjs

@@ -43,9 +43,7 @@ export function fixBrokenRefs(config, opts = {}) {
 
   // ── Fix broken frontmatter references ────────────────────────────────
 
-  const brokenRefErrors = index.errors.filter(e =>
-    e.message.includes('does not resolve to an existing file')
-  );
+  const brokenRefErrors = index.errors.filter(error => error.meta?.kind === 'ref-resolution');
 
   if (brokenRefErrors.length > 0) {
     const fixesByDoc = new Map();
@@ -101,12 +99,12 @@ export function fixBrokenRefs(config, opts = {}) {
   // ── Fix broken body links ────────────────────────────────────────────
 
   for (const doc of index.docs) {
-    const brokenBodyWarnings = doc.warnings.filter(w =>
-      w.meta?.kind === 'body-link-resolution'
-        && w.meta?.targetKind === 'document'
-        && w.meta?.reason === 'missing'
+    const brokenBodyErrors = doc.errors.filter(error =>
+      error.meta?.kind === 'body-link-resolution'
+        && error.meta?.targetKind === 'document'
+        && error.meta?.reason === 'missing'
     );
-    if (!brokenBodyWarnings.length) continue;
+    if (!brokenBodyErrors.length) continue;
 
     const absPath = path.join(config.repoRoot, doc.path);
     let raw = readFileSync(absPath, 'utf8');
@@ -116,10 +114,10 @@ export function fixBrokenRefs(config, opts = {}) {
     const bodyFixes = [];
     const seenBodyTargets = new Set();
 
-    for (const warn of brokenBodyWarnings) {
-      const brokenHref = warn.meta.relPath;
-      const rawHref = warn.meta.rawHref ?? brokenHref;
-      const targetKey = `${warn.meta.angle ? 'angle' : 'plain'}:${rawHref}`;
+    for (const error of brokenBodyErrors) {
+      const brokenHref = error.meta.relPath;
+      const rawHref = error.meta.rawHref ?? brokenHref;
+      const targetKey = `${error.meta.angle ? 'angle' : 'plain'}:${rawHref}`;
       if (seenBodyTargets.has(targetKey)) continue;
       seenBodyTargets.add(targetKey);
       const brokenBasename = path.basename(brokenHref);
@@ -133,11 +131,11 @@ export function fixBrokenRefs(config, opts = {}) {
 
       const suffixAt = rawHref.search(/[?#]/);
       const suffix = suffixAt === -1 ? '' : rawHref.slice(suffixAt);
-      const renderedHref = warn.meta.angle
+      const renderedHref = error.meta.angle
         ? `<${correctHref}${suffix}>`
         : `${correctHref.replace(/([\s()[\]<>])/g, '\\$1')}${suffix}`;
       const linkRegex = new RegExp(
-        '(\\]\\(\\s*)' + (warn.meta.angle ? '<' : '') + escapeRegex(rawHref) + (warn.meta.angle ? '>' : '') + '(?=\\s|\\))',
+        '(\\]\\(\\s*)' + (error.meta.angle ? '<' : '') + escapeRegex(rawHref) + (error.meta.angle ? '>' : '') + '(?=\\s|\\))',
         'g'
       );
       let replacements = 0;

package/src/render.mjs

@@ -516,15 +516,7 @@ export function renderManualFixes(index) {
 }
 
 export function buildReferenceValidationCoverage(index, config) {
-  let checkedDocs = 0;
-  let terminalDocsSkipped = 0;
-  for (const doc of index.docs) {
-    const terminal = config.lifecycle.isTerminal?.(doc.status, doc.type)
-      ?? config.lifecycle.terminalStatuses.has(doc.status);
-    if (terminal) terminalDocsSkipped++;
-    else checkedDocs++;
-  }
-  return { checkedDocs, terminalDocsSkipped };
+  return { checkedDocs: index.docs.length, terminalDocsSkipped: 0 };
 }
 
 function _renderCheck(index, config, opts = {}) {

package/src/validate.mjs

@@ -254,52 +254,45 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     }
   }
 
-  // Validate reference fields resolve to existing files. Terminal statuses
-  // (archived, deprecated, etc.) document historical state — their refs may
-  // legitimately point at moved/deleted targets and shouldn't gate the
-  // exit code with a hard error.
+  // Historical documents still need navigable references. Their prose is a
+  // dated record, but links to moved or deleted files cannot be followed.
   const docDir = path.dirname(path.join(config.repoRoot, doc.path));
   const allRefFields = [...(config.referenceFields.bidirectional || []), ...(config.referenceFields.unidirectional || [])];
-  const skipRefValidation = config.lifecycle.isTerminal?.(doc.status, doc.type)
-    ?? config.lifecycle.terminalStatuses.has(doc.status);
-  if (!skipRefValidation) {
-    for (const field of allRefFields) {
-      for (const relPath of (doc.refFields[field] || [])) {
-        if (!resolveRefPath(relPath, docDir, config.repoRoot)) {
-          doc.errors.push({
-            path: doc.path,
-            level: 'error',
-            message: `${field} entry \`${relPath}\` does not resolve to an existing file.`,
-            meta: { kind: 'ref-resolution', field, relPath },
-          });
-        }
-      }
-    }
-
-    // Validate body links resolve to existing files
-    for (const link of (doc.bodyLinks || [])) {
-      const resolution = resolveBodyLinkTarget(link.href, docDir, config.repoRoot);
-      if (!resolution.ok) {
-        const shownHref = link.rawHref ?? link.href;
-        doc.warnings.push({
+  for (const field of allRefFields) {
+    for (const relPath of (doc.refFields[field] || [])) {
+      if (!resolveRefPath(relPath, docDir, config.repoRoot)) {
+        doc.errors.push({
           path: doc.path,
-          level: 'warning',
-          message: resolution.reason === 'outside-repo'
-            ? `body link \`${shownHref}\` escapes the repository.`
-            : `body link \`${shownHref}\` does not resolve to an existing file or directory.`,
-          meta: {
-            kind: 'body-link-resolution',
-            field: 'body-link',
-            relPath: link.href,
-            rawHref: shownHref,
-            targetKind: link.targetKind ?? 'document',
-            angle: link.angle === true,
-            reason: resolution.reason,
-          },
+          level: 'error',
+          message: `${field} entry \`${relPath}\` does not resolve to an existing file.`,
+          meta: { kind: 'ref-resolution', field, relPath },
         });
       }
     }
   }
+
+  for (const link of (doc.bodyLinks || [])) {
+    const resolution = resolveBodyLinkTarget(link.href, docDir, config.repoRoot);
+    if (!resolution.ok) {
+      const shownHref = link.rawHref ?? link.href;
+      doc.errors.push({
+        path: doc.path,
+        level: 'error',
+        message: resolution.reason === 'outside-repo'
+          ? `body link \`${shownHref}\` escapes the repository.`
+          : `body link \`${shownHref}\` does not resolve to an existing file or directory.`,
+        meta: {
+          kind: 'body-link-resolution',
+          field: 'body-link',
+          relPath: link.href,
+          rawHref: shownHref,
+          targetKind: link.targetKind ?? 'document',
+          angle: link.angle === true,
+          reason: resolution.reason,
+        },
+      });
+    }
+  }
 }
 
 // Guess which doc type a ref field expects so suggestions don't propose