@ecoma-io/archkeep 0.16.0 → 0.17.0

package/src/report/adr-text.mjs

@@ -15,10 +15,90 @@ import { ADR_DIR, ADR_STATUSES } from "../governance/adr-registry.mjs";
 /** A status label for a record, in the text a human reads. */
 function statusLabel(status) {
   if (status === "accepted") return "accepted";
+  if (status === "active") return "active";
   if (status === "superseded") return "superseded";
+  if (status === "retired") return "retired";
   return "proposed";
 }
 
+/**
+ * The `fitness:` line for one record — the per-decision verification level
+ * the command derives (`../governance/decision-fitness.mjs` owns the
+ * vocabulary). The line is always printed with its reason when the level has
+ * one; an `enforced` level carries none and says so. This command alone can
+ * never verify anything (its header's "What it cannot assert" owns why), so
+ * the level comes in precomputed from the caller — absent it, the line is an
+ * explicit "(not measured)" that cannot be mistaken for a verdict.
+ *
+ * @param {{level: string, verified: boolean, reason?: string}|undefined} fitness
+ * @returns {string}
+ */
+function fitnessLine(fitness) {
+  if (fitness === undefined) return `fitness:      ${"(not measured)"}`;
+  if (fitness.verified)
+    return `fitness:      ${fitness.level} — verified true: bound constraints resolve and pass`;
+  if (typeof fitness.reason === "string") {
+    return `fitness:      ${fitness.level} — ${fitness.reason}`;
+  }
+  return `fitness:      ${fitness.level}`;
+}
+
+/**
+ * The `created:` / `updated:` metadata lines for one record, when the record
+ * carries them. Absent frontmatter stays absent — these are the decision's
+ * own committed timeline, never a wall-clock guess.
+ *
+ * @param {object} record
+ * @returns {string[]}
+ */
+function timelineLines(record) {
+  const lines = [];
+  if (typeof record.created === "string") lines.push(`created:   ${record.created}`);
+  if (typeof record.updated === "string") lines.push(`updated:   ${record.updated}`);
+  return lines;
+}
+
+/**
+ * The reverse lineage line — the records whose `supersedes` names this one,
+ * derived at load by the registry and therefore always consistent with the
+ * forward `supersedes:` line on the other record.
+ *
+ * @param {object} record
+ * @returns {string[]}
+ */
+function supersededByLines(record) {
+  if (!Array.isArray(record.supersededBy) || record.supersededBy.length === 0) return [];
+  return [`supersededBy: ${record.supersededBy.join(", ")}`];
+}
+
+/**
+ * One prose field rendered for the single-record view: the label on the
+ * first line, continued lines aligned under the prose. A field that is
+ * absent or blank renders nothing — the record's own body decides.
+ *
+ * @param {string} label The 12-wide `label:` prefix.
+ * @param {string} text The field's markdown prose.
+ * @returns {string[]}
+ */
+function proseLines(label, text) {
+  const content = text.split("\n").map((line) => line.trimEnd());
+  const out = [`${label}${content[0]}`];
+  for (const line of content.slice(1)) {
+    out.push(`${" ".repeat(label.length)}${line}`);
+  }
+  return out;
+}
+
+/** The prose fields of one record, in the order §3.2 of the wave 2 contract names them. */
+const PROSE_FIELDS = [
+  ["context:     ", "context"],
+  ["decision:    ", "decision"],
+  ["rationale:   ", "rationale"],
+  ["alternatives:", "alternatives"],
+  ["consequences:", "consequences"],
+  ["assumptions: ", "assumptions"],
+];
+
 /**
  * The `bindings:` line for one record — the ONE place either face decides how
  * a binding is rendered.
@@ -54,21 +134,26 @@ function bindingsLine(record, known) {
  * Renders the whole registry: one block per record, each naming its status,
  * its supersession chain, and the rules/fitnesses it binds.
  *
- * @param {{records: object[], knownFitness?: Set<string>}} result
+ * @param {{records: object[], knownFitness?: Set<string>, fitnessById?:
+ *   Map<string, {level: string, verified: boolean, reason?: string}>}} result
  * @returns {string}
  */
-export function formatAdrDump({ records, knownFitness }) {
+export function formatAdrDump({ records, knownFitness, fitnessById }) {
   if (records.length === 0) {
     return `no ADRs in ${ADR_DIR}/ — nothing is recorded, and nothing is enforceable through it`;
   }
   const known = knownFitness ?? new Set();
+  const fitnessMap = fitnessById ?? new Map();
   const blocks = records.map((record) => {
     const header = `${record.id}  (${statusLabel(record.status)})`;
     const lines = [header, "-".repeat(header.length)];
     if (record.supersedes.length > 0) {
       lines.push(`supersedes: ${record.supersedes.join(", ")}`);
     }
+    lines.push(...supersededByLines(record));
+    lines.push(...timelineLines(record));
     lines.push(bindingsLine(record, known));
+    lines.push(fitnessLine(fitnessMap.get(record.id)));
     lines.push(`status set: ${ADR_STATUSES.join(", ")}`);
     return lines.join("\n");
   });
@@ -110,20 +195,40 @@ export function formatAdrMissing({ adrId }) {
  * a reader who asked about one record sees strictly less than one who dumped
  * the registry otherwise, and what they stop seeing is the marker.
  *
- * @param {{id: string, status: string, supersedes: string[], bindings: string[]}} record
+ * Beyond the dump's lines it also renders the record's own prose (context,
+ * decision, rationale, alternatives, consequences, assumptions) when the body
+ * records them — this is the view a reader asking "why was this decided" gets.
+ *
+ * @param {{id: string, status: string, supersedes: string[], supersededBy?:
+ *   string[], bindings: string[], created?: string, updated?: string, context?:
+ *   string, decision?: string, rationale?: string, alternatives?: string,
+ *   consequences?: string, assumptions?: string}} record
  * @param {Set<string>} [knownFitness] The ids the registry's records mention.
  *   Optional only so the parameter can be omitted where there is nothing to
  *   compare against; an absent set marks every binding rather than none,
  *   because "nothing corroborates this" is the honest answer when no set was
  *   supplied — never the quiet one.
+ * @param {Map<string, {level: string, verified: boolean, reason?: string}>}
+ *   [fitnessById] The fitness level per record id, computed by the caller
+ *   (`../commands/adr.mjs`). Absent, a record's fitness line reads as the
+ *   explicit "(not measured)" — never as a verdict this renderer invented.
  * @returns {string}
  */
-export function formatAdrRecord(record, knownFitness) {
+export function formatAdrRecord(record, knownFitness, fitnessById) {
   const header = `${record.id}  (${statusLabel(record.status)})`;
   const lines = [header, "-".repeat(header.length)];
   if (record.supersedes.length > 0) {
     lines.push(`supersedes: ${record.supersedes.join(", ")}`);
   }
+  lines.push(...supersededByLines(record));
+  lines.push(...timelineLines(record));
   lines.push(bindingsLine(record, knownFitness ?? new Set()));
+  lines.push(fitnessLine(fitnessById?.get(record.id)));
+  for (const [label, key] of PROSE_FIELDS) {
+    const text = record[key];
+    if (typeof text === "string" && text.trim() !== "") {
+      lines.push(...proseLines(label, text));
+    }
+  }
   return lines.join("\n");
 }

package/src/report/decisions-text.mjs

@@ -0,0 +1,164 @@
+/**
+ * The `decisions` command's text renderer — the deterministic chain
+ * decision → governed rows → projects → findings → fitness, one function a
+ * test drives for both the resolved and the unresolved walk.
+ *
+ * The renderer owns the invariant: a chain that could not walk every hop
+ * (`walk.ok === false`) renders a loud unresolved block, never a clean-looking
+ * chain. The walk (`../governance/decision-graph.mjs`) reports each
+ * unresolved reference with a reason; this face prints them all, so a reader
+ * sees which hop broke and why — the same refrain as every other surface in
+ * this wave ("an empty result is a claim, not a shrug").
+ *
+ * It is a pure function of the walk result + the record + the fitness level;
+ * it reads no files. The fitness line reuses the `fitness:` byte convention
+ * `./adr-text.mjs` establishes, so the two decision surfaces cannot disagree
+ * about what a level means.
+ */
+
+/** A status label for a record, in the same terms `./adr-text.mjs` uses. */
+function statusLabel(status) {
+  if (status === "accepted") return "accepted";
+  if (status === "active") return "active";
+  if (status === "superseded") return "superseded";
+  if (status === "retired") return "retired";
+  return "proposed";
+}
+
+/**
+ * The `fitness:` line — byte-identical to `./adr-text.mjs`'s own, so a fitness
+ * level means the same thing on the `adr` face and here.
+ *
+ * @param {{level: string, verified: boolean, reason?: string}|undefined} fitness
+ * @returns {string}
+ */
+function fitnessLine(fitness) {
+  if (fitness === undefined) return `fitness:      ${"(not measured)"}`;
+  if (fitness.verified)
+    return `fitness:      ${fitness.level} — verified true: bound constraints resolve and pass`;
+  if (typeof fitness.reason === "string") {
+    return `fitness:      ${fitness.level} — ${fitness.reason}`;
+  }
+  return `fitness:      ${fitness.level}`;
+}
+
+/** One prose field rendered for a record, first line carrying the label. */
+function proseLines(label, text) {
+  const first = text.split("\n")[0];
+  const rest = text.split("\n").slice(1);
+  const out = [`${label}${first}`];
+  for (const line of rest) out.push(`${" ".repeat(label.length)}${line}`);
+  return out;
+}
+
+/** The prose fields of one record, in the order the wave-2 contract names them. */
+const PROSE_FIELDS = [
+  ["context:     ", "context"],
+  ["decision:    ", "decision"],
+  ["rationale:   ", "rationale"],
+  ["alternatives:", "alternatives"],
+  ["consequences:", "consequences"],
+  ["assumptions: ", "assumptions"],
+];
+
+/** The kind label a governed row node renders as. */
+const ROW_KIND_LABEL = {
+  intent: "intent row",
+  constraint: "constraint",
+  fitness: "fitness rule",
+};
+
+/**
+ * Renders the deterministic decision chain for one record.
+ *
+ * @param {object} args
+ * @param {string} args.decisionId The id the caller asked about.
+ * @param {object} args.record The ADR record the chain is about.
+ * @param {object} args.walk The `forwardDecision` walk
+ *   (`../governance/decision-graph.mjs`): `{ok, nodes, edges, unresolved}`.
+ * @param {{level: string, verified: boolean, reason?: string}|undefined}
+ *   args.fitness The per-decision fitness level, computed by the caller.
+ * @returns {string}
+ */
+export function formatDecisionChain({ decisionId, record, walk, fitness }) {
+  const lines = [];
+
+  // An id the registry does not know is a named unknown, never a clean chain:
+  // the record is null, so there is no header to derive — the walk's
+  // unresolved block below is the whole answer. The renderer must not throw
+  // over a null record; that is precisely the case it exists to report.
+  const header =
+    record === null || record === undefined
+      ? `${decisionId}  (unknown)`
+      : `${record.id}  (${statusLabel(record.status)})`;
+  lines.push(header, "-".repeat(header.length));
+
+  if (record !== null && record !== undefined) {
+    for (const [label, key] of PROSE_FIELDS) {
+      const text = record[key];
+      if (typeof text === "string" && text.trim() !== "") {
+        lines.push(...proseLines(label, text));
+      }
+    }
+
+    if ((record.supersedes ?? []).length > 0) {
+      lines.push(`supersedes: ${record.supersedes.join(", ")}`);
+    }
+
+    lines.push(fitnessLine(fitness));
+  }
+
+  // The governed rows the decision attaches (decisionRef citations and
+  // bindings): the "who stands on this decision" half of the chain.
+  const rowNodes = walk.nodes.filter(
+    (node) => node.kind === "constraint" || node.kind === "intent" || node.kind === "fitness",
+  );
+  if (rowNodes.length > 0) {
+    lines.push("governs:");
+    for (const node of rowNodes) {
+      const governed = walk.edges
+        .filter((edge) => edge.kind === "governs" && edge.from === node.id)
+        .map((edge) => edge.to);
+      const kind = ROW_KIND_LABEL[node.kind] ?? node.kind;
+      const target = governed.length > 0 ? ` → ${governed.join(", ")}` : "";
+      lines.push(`  ${node.id}  (${kind})${target}`);
+    }
+  } else {
+    lines.push("governs: (none — recorded but not enforceable)");
+  }
+
+  // The evidence leg: every project the rows govern, and each project's
+  // current findings. A project with no findings is a fact, stated as such.
+  const projectNodes = walk.nodes.filter((node) => node.kind === "project");
+  if (projectNodes.length > 0) {
+    lines.push("evidence:");
+    for (const project of projectNodes) {
+      const findings = walk.nodes
+        .filter((node) => node.kind === "finding")
+        .filter((finding) =>
+          walk.edges.some(
+            (edge) => edge.kind === "finding" && edge.from === project.id && edge.to === finding.id,
+          ),
+        );
+      if (findings.length === 0) {
+        lines.push(`  ${project.id}: no current findings`);
+      } else {
+        for (const finding of findings) {
+          const ruleId = finding.data?.ruleId ?? "";
+          lines.push(`  ${project.id}: ${finding.label}${ruleId ? ` (${ruleId})` : ""}`);
+        }
+      }
+    }
+  }
+
+  // The loud unresolved block — a walk that could not resolve every hop never
+  // reads as a clean chain.
+  if (!walk.ok) {
+    lines.push("unresolved:");
+    for (const entry of walk.unresolved) {
+      lines.push(`  ${entry.ref}: ${entry.reason}`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/report/explain-text.mjs

@@ -7,7 +7,7 @@
  * shape `./text.mjs` uses for violations. Everything after it is indented,
  * so the position line stands alone.
  *
- * Seven things are printed, each with a reader in mind:
+ * Eight things are printed, each with a reader in mind:
  *
  * - the import specifier and its kind (what was written)
  * - the source project and its tags (who wrote it)
@@ -19,6 +19,11 @@
  *   and a remediation line that is the author's declared guidance verbatim —
  *   or, when none is declared, an explicit pointer at the constraint row and
  *   its `decisionRef`, never a fix this renderer composed
+ * - for a matched row carrying a `decisionRef`: the governing decision's
+ *   status and authority, its context/rationale prose, and its supersession
+ *   lineage — or, when the ref or the registry cannot be resolved, a loud
+ *   UNRESOLVED line naming the reason (an empty result here would read as
+ *   "no decision behind this row", which is a different claim)
  * - coverage information (whether this explanation is complete)
  *
  * This module decides nothing. A formatter that filtered would be a rule
@@ -84,6 +89,69 @@ function formatMatchedConstraint(constraint) {
   return formatConstraint(constraint);
 }
 
+/**
+ * The status line for one governing decision: `id  (status — authority)`.
+ *
+ * @param {object} entry A resolved `"adr"` chain entry.
+ * @returns {string}
+ */
+function decisionStatusLine(entry) {
+  const authority = entry.authority ? " — has authority" : " — no authority";
+  return `${DETAIL}decision     ${entry.record.id}  (${entry.record.status}${authority})`;
+}
+
+/**
+ * The first non-empty line of a prose field, trimmed to a display width.
+ * The excerpt is a pointer, never a paraphrase — a reader who needs the whole
+ * context opens the ADR.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function proseExcerpt(text) {
+  const first = text.split("\n").find((line) => line.trim() !== "") ?? "";
+  const trimmed = first.trim();
+  return trimmed.length > 120 ? `${trimmed.slice(0, 117)}…` : trimmed;
+}
+
+/**
+ * One decision-chain entry as report lines. The chain never renders blank:
+ * a ref the registry cannot resolve, and a ref that cannot be read at all,
+ * both render as UNRESOLVED naming the reason (AGENTS.md: "an empty result
+ * is a claim, not a shrug").
+ *
+ * @param {object} entry One `explanation.decisions` entry.
+ * @returns {string[]}
+ */
+function formatDecisionEntry(entry) {
+  if (entry.resolution === "unknown") {
+    return [`${DETAIL}decisionRef  ${entry.ref} (UNRESOLVED — ${entry.reason})`];
+  }
+  if (entry.resolution === "fitness") {
+    return [`${DETAIL}decisionRef  ${entry.ref} — a fitness rule this law declares`];
+  }
+  const lines = [decisionStatusLine(entry)];
+  if (typeof entry.record.context === "string") {
+    lines.push(`${DETAIL}context      ${proseExcerpt(entry.record.context)}`);
+  }
+  if (typeof entry.record.rationale === "string") {
+    lines.push(`${DETAIL}rationale    ${proseExcerpt(entry.record.rationale)}`);
+  }
+  const supersedes = Array.isArray(entry.record.supersedes) ? entry.record.supersedes : [];
+  const supersededBy = Array.isArray(entry.record.supersededBy) ? entry.record.supersededBy : [];
+  if (supersedes.length > 0 || supersededBy.length > 0) {
+    const parts = [];
+    if (supersedes.length > 0) parts.push(`supersedes: ${supersedes.join(", ")}`);
+    if (supersededBy.length > 0) parts.push(`superseded by: ${supersededBy.join(", ")}`);
+    lines.push(`${DETAIL}lineage      ${parts.join(" · ")}`);
+  } else {
+    lines.push(`${DETAIL}lineage      none — no supersession chain is recorded for this decision`);
+  }
+  for (const gap of entry.lineage?.unresolved ?? []) {
+    lines.push(`${DETAIL}lineage      UNRESOLVED — ${gap.reason}`);
+  }
+  return lines;
+}
 /**
  * The whole explain report.
  *
@@ -165,6 +233,14 @@ export function formatExplainReport({ explanation, coverage }) {
     } else {
       sections.push(`${DETAIL}verdict      allowed — no constraint was violated`);
     }
+
+    // The "why does this constraint exist" chain — one block per governing
+    // decision the matched rows name. Additive: an explanation whose rows
+    // carry no `decisionRef` has no `decisions` list, and renders exactly as
+    // it did before this section existed.
+    for (const entry of explanation.decisions ?? []) {
+      sections.push(...formatDecisionEntry(entry));
+    }
   }
 
   // Coverage — same shape as every other command's footer.

package/src/report/provenance-text.mjs

@@ -9,6 +9,13 @@
  * `../commands/provenance-command.mjs` already resolved — no wall-clock time
  * and no `localeCompare` enter here, matching every other report renderer.
  *
+ * A fourth section carries the decision lifecycle: every recorded decision's
+ * status, authority, committed timeline, lineage, and bindings, attributed
+ * with WHO recorded it (the record file's own git history). A decision with
+ * no attributable history is named `no origin recorded — cannot attest`,
+ * never silently passed; the section renders only when at least one decision
+ * exists, the same "no fact, no claim" bargain the row arms state.
+ *
  * This module decides nothing. A formatter that filtered would be a rule
  * wearing a formatter's name (`./README.md`).
  */
@@ -19,10 +26,17 @@
  *   rowsTotal: number,
  *   unattested: {kind: string, label: string, note: string}[],
  *   decisionRefTotal: number,
- *   unresolvedDecisionRefs: {kind: string, label: string, decisionRef: string, note: string}[]}} input
+ *   unresolvedDecisionRefs: {kind: string, label: string, decisionRef: string, note: string}[],
+ *   decisionLifecycle?: {id: string, status: string, authority: boolean,
+ *     created: string|null, updated: string|null, supersedes: string[],
+ *     supersededBy: string[], bindings: string[],
+ *     attribution: {createdBy: object|null, lastChangedBy: object|null}|null,
+ *     attested: boolean, note: string|null}[]}} input
  *   `decisionRefTotal` is how many governance rows cite a `decisionRef` at
  *   all — the resolution section renders only when it is non-zero, the same
  *   "no fact, no claim" bargain every optional axis in this tool states.
+ *   `decisionLifecycle` (optional, default `[]`) is the decision-lifecycle
+ *   section — it renders only when non-empty.
  * @returns {string}
  */
 export function formatProvenanceReport({
@@ -32,6 +46,7 @@ export function formatProvenanceReport({
   unattested,
   decisionRefTotal,
   unresolvedDecisionRefs,
+  decisionLifecycle = [],
 }) {
   const attestedCount = rowsTotal - unattested.length;
   const text = [];
@@ -74,5 +89,56 @@ export function formatProvenanceReport({
       );
     }
   }
+  // PR E — the decision lifecycle. "No fact, no claim", like the resolution
+  // arm: the section renders only when the registry holds at least one
+  // decision, and a decision with no attributable history is listed under a
+  // cannot-attest heading, never silently passed.
+  const decidedCount = decisionLifecycle.length;
+  if (decidedCount > 0) {
+    const attributedCount = decisionLifecycle.filter((d) => d.attested).length;
+    const unattributedCount = decidedCount - attributedCount;
+    text.push(
+      `decisions  ${decidedCount} recorded — ${attributedCount} attributed, ` +
+        `${unattributedCount} without attribution`,
+    );
+    for (const decision of decisionLifecycle) {
+      if (!decision.attested) continue;
+      const createdBy = decision.attribution?.createdBy ?? null;
+      const lastChangedBy = decision.attribution?.lastChangedBy ?? null;
+      const facts = [
+        createdBy === null
+          ? "created — no origin recorded — cannot attest"
+          : `created by ${createdBy.by} on ${createdBy.on}`,
+        lastChangedBy === null
+          ? "changed — no origin recorded — cannot attest"
+          : `changed by ${lastChangedBy.by} on ${lastChangedBy.on}`,
+      ];
+      if (decision.supersedes.length > 0) {
+        facts.push(`supersedes ${decision.supersedes.join(", ")}`);
+      }
+      if (decision.supersededBy.length > 0) {
+        facts.push(`superseded by ${decision.supersededBy.join(", ")}`);
+      }
+      if (decision.bindings.length > 0) {
+        facts.push(`binds ${decision.bindings.join(", ")}`);
+      }
+      if (decision.created !== null || decision.updated !== null) {
+        facts.push(`timeline ${decision.created ?? "?"} → ${decision.updated ?? "?"}`);
+      }
+      text.push(`  ${decision.status.padEnd(11)} ${decision.id}  ${facts.join("; ")}`);
+    }
+    if (unattributedCount > 0) {
+      text.push("unattributed lifecycle (no origin recorded — cannot attest):");
+      for (const decision of decisionLifecycle) {
+        if (!decision.attested) text.push(`  ${decision.id}`);
+      }
+      text.push(`${unattributedCount} of them carry no recorded origin behind their lifecycle`);
+    } else {
+      text.push(
+        `✔ every decision's lifecycle is attributed — each change names who ` +
+          `recorded it and with what tool`,
+      );
+    }
+  }
   return text.join("\n");
 }

package/src/report/report-text.mjs

@@ -155,7 +155,13 @@ function fitnessLines(fitness) {
  */
 function decisionLines(decisions) {
   const lines = [surfaceLine("decisions", decisions)];
-  if (decisions.registry.count !== null) {
+  // "does not resolve" is a claim about the REF — that nothing in the
+  // workspace answers to it. When the registry itself could not be read, that
+  // claim is not one this run established: it could not look. The two get
+  // different sentences, for the same reason `unknown` and `not_applicable`
+  // do (`count: null` is how the command says the registry was unreadable).
+  const registryUnread = decisions.registry.count === null;
+  if (!registryUnread) {
     lines.push(
       `    ${decisions.registry.count} record${decisions.registry.count === 1 ? "" : "s"} in ` +
         `${decisions.registry.dir}/`,
@@ -165,29 +171,58 @@ function decisionLines(decisions) {
         record.bindings.length > 0
           ? `binds ${record.bindings.join(", ")}`
           : "binds nothing — not yet enforceable";
+      // The record row is byte-identical to the pre-wave-2 line; the fitness
+      // and "stands on" lines below it are additive surface (contract items
+      // 3 + F/B), never a rewrite of what a longer-maintained reader expects.
       lines.push(`      ${record.id}  (${record.status})  ${binds}`);
+      if (record.fitness !== undefined) {
+        const fit = record.fitness;
+        const reasonString =
+          typeof fit.reason === "string"
+            ? ` — ${fit.reason}`
+            : fit.verified
+              ? " — verified true: bound constraints resolve and pass"
+              : "";
+        lines.push(`          fitness: ${fit.level}${reasonString}`);
+      }
+      if (record.authority) {
+        if (record.constraints.length > 0) {
+          const refs = record.constraints.map((c) => `${c.kind} ${c.label}`).join(", ");
+          lines.push(`          stands on: ${refs}`);
+        } else {
+          lines.push("          stands on: no governed row cites this decision");
+        }
+      }
     }
   }
+  // The citations render even when the registry could not be read: that is
+  // exactly the case where "does not resolve" must NOT be claimed and the
+  // registry-unreadable sentence must. Skipping them here would print the
+  // "unknown" verdict with no citation lines to back it — the silent direction.
   if (decisions.citations.length === 0) {
     lines.push("    no governed row cites a decisionRef");
-    return lines;
+  } else {
+    for (const citation of decisions.citations) {
+      const target =
+        citation.resolution === "adr" && citation.adr !== null
+          ? `${citation.adr.id} (${citation.adr.status})`
+          : citation.resolution === "fitness"
+            ? `${citation.decisionRef} — a fitness rule this law declares`
+            : registryUnread
+              ? `${citation.decisionRef} — unresolved: the decision registry could not be read`
+              : `${citation.decisionRef} — does not resolve`;
+      lines.push(`    ${citation.resolution.padEnd(10)}${citation.label} → ${target}`);
+    }
   }
-  // "does not resolve" is a claim about the REF — that nothing in the
-  // workspace answers to it. When the registry itself could not be read, that
-  // claim is not one this run established: it could not look. The two get
-  // different sentences, for the same reason `unknown` and `not_applicable`
-  // do (`count: null` is how the command says the registry was unreadable).
-  const registryUnread = decisions.registry.count === null;
-  for (const citation of decisions.citations) {
-    const target =
-      citation.resolution === "adr" && citation.adr !== null
-        ? `${citation.adr.id} (${citation.adr.status})`
-        : citation.resolution === "fitness"
-          ? `${citation.decisionRef} — a fitness rule this law declares`
-          : registryUnread
-            ? `${citation.decisionRef} — unresolved: the decision registry could not be read`
-            : `${citation.decisionRef} — does not resolve`;
-    lines.push(`    ${citation.resolution.padEnd(10)}${citation.label} → ${target}`);
+  if (
+    !registryUnread &&
+    Array.isArray(decisions.unresolvedDecisionRefs) &&
+    decisions.unresolvedDecisionRefs.length > 0
+  ) {
+    lines.push("    unresolved decisionRefs:");
+    for (const ref of decisions.unresolvedDecisionRefs) {
+      lines.push(`      ${ref.kind} ${ref.label} → ${ref.reason}`);
+    }
   }
   return lines;
 }