@ecoma-io/archkeep 0.16.1 → 0.18.0

package/src/report/evolution-text.mjs

@@ -22,8 +22,10 @@ import { formatChanges, sanitize, transitionKind } from "./snapshot-text.mjs";
  * @param {{result: {base: string, head: string,
  *   revisions: {commit: string, id: string}[],
  *   transitions: {from: string, to: string, architectureChanged: boolean,
- *     changes: object|null, policyChanged: boolean|null, providerChanged: boolean,
- *     codeDrift: boolean, notes: string[]}[]}, coverage: object}} input
+ *     changes: object|null, policyChanged: boolean|null, policyOneSided: boolean,
+ *     provenanceChanged: boolean|null, providerChanged: boolean,
+ *     codeDrift: boolean, notes: string[], comparison?: object}[],
+ *   summary?: object}, coverage: object}} input
  * @returns {string}
  */
 export function formatEvolutionReport({ result, coverage }) {
@@ -62,6 +64,17 @@ export function formatEvolutionReport({ result, coverage }) {
     for (const note of transition.notes) {
       sections.push(`  ${note}`);
     }
+    // The per-transition comparison report — the eight questions answered on
+    // this one revision pair (design §6), from the envelope fields the command
+    // already computed. An incomparable axis is printed with its reason, never
+    // folded into silence.
+    if (transition.comparison) {
+      sections.push(``);
+      sections.push(
+        `  comparison for ${sanitize(transition.from.slice(0, 12))} → ${sanitize(transition.to.slice(0, 12))}`,
+      );
+      sections.push(...formatComparisonSection(transition.comparison));
+    }
   }
 
   if (changed === 0) {
@@ -79,5 +92,221 @@ export function formatEvolutionReport({ result, coverage }) {
     );
   }
 
+  // The range-wide summary — the same eight questions answered over the whole
+  // record, so a reader sees both the per-pair detail and the verdict carried
+  // by all of them together (design §8). An axis that any pair could not
+  // compare is reported as n/a with the reason, never as a fabricated clean
+  // aggregate.
+  if (result.summary) {
+    sections.push(``);
+    sections.push(`summary`);
+    sections.push(...formatSummarySection(result.summary));
+  }
+
   return sections.join("\n");
 }
+
+/**
+ * Renders an incomparable axis marker as `n/a — <reason>` (design §6). An
+ * axis that could not be answered is never folded into a clean "none".
+ *
+ * @param {{available: false, reason?: string}|undefined} axis
+ * @returns {string}
+ */
+function naWithReason(axis) {
+  return `n/a — ${axis?.reason ?? "not comparable"}`;
+}
+
+/**
+ * Renders one verdict value: a verdict string as-is, an incomparable marker
+ * as `n/a — <reason>`, and an absent value as `n/a` with a fallback reason.
+ *
+ * @param {string|{available: false, reason?: string}|undefined} value
+ * @param {string} [fallbackReason]
+ * @returns {string}
+ */
+function renderVerdict(value, fallbackReason) {
+  if (value === undefined || value === null) return `n/a — ${fallbackReason ?? "unknown"}`;
+  if (typeof value === "object" && value.available === false) {
+    return `n/a — ${value.reason ?? "not comparable"}`;
+  }
+  return String(value);
+}
+
+/**
+ * Names an edge for the report: `source→target:type` for the object shape the
+ * diff produces, plain text otherwise.
+ *
+ * @param {object|string} edge
+ * @returns {string}
+ */
+function edgeName(edge) {
+  return edge && typeof edge === "object"
+    ? `${edge.source}→${edge.target}${edge.type ? `:${edge.type}` : ""}`
+    : String(edge);
+}
+
+/**
+ * The report section for one transition's comparison (design §6) — the eight
+ * questions answered for that single revision pair. Reads the envelope fields
+ * the command computed; incomparable axes print `n/a — <reason>`, never a
+ * fabricated clean answer.
+ *
+ * @param {object} comparison One `result.transitions[i].comparison`.
+ * @returns {string[]} Report lines.
+ */
+function formatComparisonSection(comparison) {
+  const out = [];
+  const observed = comparison.observed ?? {};
+  const projects = observed.projects ?? {};
+  const edges = observed.edges ?? {};
+  const projectName = (p) => (typeof p === "string" ? p : (p?.name ?? JSON.stringify(p)));
+  const listLine = (label, items) =>
+    items.length === 0 ? [] : [`  ${label}: ${items.join(", ")}`];
+
+  out.push(`  disposition: ${comparison.disposition ?? "unknown"}`);
+  const cls = comparison.classifications ?? [];
+  out.push(`  classifications: ${cls.length === 0 ? "none" : cls.join(", ")}`);
+  out.push(`  architecture changed: ${observed.architectureChanged ? "yes" : "no"}`);
+  out.push(...listLine("projects added", (projects.added ?? []).map(projectName)));
+  out.push(...listLine("projects removed", (projects.removed ?? []).map(projectName)));
+  out.push(...listLine("projects changed", (projects.changed ?? []).map(projectName)));
+  out.push(...listLine("edges added", (edges.added ?? []).map(edgeName)));
+  out.push(...listLine("edges removed", (edges.removed ?? []).map(edgeName)));
+  if (observed.policyChanged === true || observed.policyChanged === false) {
+    out.push(`  policy changed: ${observed.policyChanged ? "yes" : "no"}`);
+  }
+  if (observed.policyOneSided === true) out.push(`  policy changed: one-sided`);
+  if (observed.providerChanged === true || observed.providerChanged === false) {
+    out.push(`  provider changed: ${observed.providerChanged ? "yes" : "no"}`);
+  }
+  if (observed.provenanceChanged === true) out.push(`  provenance changed: yes`);
+
+  const findings = comparison.findings;
+  if (findings?.available === false) out.push(`  drift findings: ${naWithReason(findings)}`);
+  else if (findings) {
+    out.push(
+      `  drift findings: introduced ${findings.introduced.length}, resolved ${findings.resolved.length}` +
+        (findings.unknown?.length ? `, unknown ${findings.unknown.length}` : ""),
+    );
+  }
+
+  const debt = comparison.debt;
+  if (debt?.available === false) out.push(`  debt: ${naWithReason(debt)}`);
+  else if (debt)
+    out.push(`  debt: introduced ${debt.introduced.length}, resolved ${debt.resolved.length}`);
+
+  const fitness = comparison.fitness;
+  if (fitness?.available === false) out.push(`  fitness: ${naWithReason(fitness)}`);
+  else if (fitness?.verdictDeltas) {
+    out.push(`  fitness:`);
+    for (const delta of fitness.verdictDeltas) {
+      out.push(`    ${delta.id}: ${renderVerdict(delta.base)} → ${renderVerdict(delta.head)}`);
+    }
+  }
+
+  const cov = comparison.coverage;
+  if (cov) {
+    out.push(
+      `  coverage: base ${cov.base?.projects ?? 0} project${cov.base?.projects === 1 ? "" : "s"} / ` +
+        `${cov.base?.analyzedFiles ?? 0} files / ${cov.base?.imports ?? 0} imports; ` +
+        `head ${cov.head?.projects ?? 0} / ${cov.head?.analyzedFiles ?? 0} / ${cov.head?.imports ?? 0}`,
+    );
+  }
+
+  const affected = comparison.affected;
+  if (affected) {
+    if (affected.projects?.length) out.push(`  affected projects: ${affected.projects.join(", ")}`);
+    if (affected.boundaries?.length)
+      out.push(`  affected boundaries: ${affected.boundaries.join(", ")}`);
+    if (affected.constraints?.length)
+      out.push(`  affected constraints: ${affected.constraints.join(", ")}`);
+    if (affected.decisions?.length)
+      out.push(`  affected decisions: ${affected.decisions.join(", ")}`);
+    if (
+      !["projects", "boundaries", "constraints", "decisions", "lineage"].some(
+        (key) => affected[key]?.length,
+      )
+    ) {
+      out.push(`  affected: none`);
+    }
+  }
+
+  for (const note of comparison.notes ?? []) out.push(`  note: ${note}`);
+  return out;
+}
+
+/**
+ * The report section for the whole-range summary (design §8) — the same eight
+ * questions answered over every transition together. Any axis with an
+ * incomparable transition prints `n/a — <reason>` naming that transition.
+ *
+ * @param {object} summary `result.summary`.
+ * @returns {string[]} Report lines.
+ */
+function formatSummarySection(summary) {
+  const out = [];
+  out.push(`  transitions: ${summary.transitions}`);
+  out.push(`  disposition: ${summary.disposition ?? "unknown"}`);
+  const cls = summary.classifications ?? [];
+  out.push(`  classifications: ${cls.length === 0 ? "none" : cls.join(", ")}`);
+
+  const observed = summary.observed ?? {};
+  const projects = observed.projects ?? {};
+  const edges = observed.edges ?? {};
+  const listLine = (label, items) =>
+    items.length === 0 ? [] : [`  ${label}: ${items.join(", ")}`];
+  out.push(
+    `  architecture changed in ${observed.architectureChanged ?? 0} transition${
+      observed.architectureChanged === 1 ? "" : "s"
+    }`,
+  );
+  out.push(...listLine("projects added", projects.added ?? []));
+  out.push(...listLine("projects removed", projects.removed ?? []));
+  out.push(...listLine("projects changed", projects.changed ?? []));
+  out.push(...listLine("edges added", (edges.added ?? []).map(edgeName)));
+  out.push(...listLine("edges removed", (edges.removed ?? []).map(edgeName)));
+  const policyChanged = observed.policyChanged;
+  if (policyChanged !== undefined && policyChanged !== null) {
+    out.push(
+      typeof policyChanged === "object" && policyChanged.available === false
+        ? `  policy: ${naWithReason(policyChanged)}`
+        : `  policy changed: ${policyChanged}`,
+    );
+  }
+  const findings = summary.findings;
+  if (findings?.available === false) out.push(`  drift findings: ${naWithReason(findings)}`);
+  else if (findings) {
+    out.push(
+      `  drift findings: introduced ${findings.introduced.length}, resolved ${findings.resolved.length}`,
+    );
+  }
+
+  const debt = summary.debt;
+  if (debt?.available === false) out.push(`  debt: ${naWithReason(debt)}`);
+  else if (debt)
+    out.push(`  debt: introduced ${debt.introduced.length}, resolved ${debt.resolved.length}`);
+
+  const fitness = summary.fitness;
+  if (fitness?.available === false) out.push(`  fitness: ${naWithReason(fitness)}`);
+  else if (fitness?.verdictDeltas) {
+    out.push(`  fitness:`);
+    for (const delta of fitness.verdictDeltas) {
+      out.push(`    ${delta.id}: ${renderVerdict(delta.base)} → ${renderVerdict(delta.head)}`);
+    }
+  }
+
+  const affected = summary.affected;
+  if (affected) {
+    if (affected.projects?.length) out.push(`  affected projects: ${affected.projects.join(", ")}`);
+    if (affected.boundaries?.length)
+      out.push(`  affected boundaries: ${affected.boundaries.join(", ")}`);
+    if (affected.constraints?.length)
+      out.push(`  affected constraints: ${affected.constraints.join(", ")}`);
+    if (affected.decisions?.length)
+      out.push(`  affected decisions: ${affected.decisions.join(", ")}`);
+  }
+
+  for (const note of summary.notes ?? []) out.push(`  note: ${note}`);
+  return out;
+}

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,108 @@ 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 lineage-comparison disclosure — `explain`'s optional base-registry
+ * seam, rendered only when the caller supplied a base registry and the
+ * resolved-site explanation carries a `decisionChange` field. The fact is
+ * stated either way — superseded or not — because "the lineage was compared
+ * and did not move" must read differently from "no comparison happened"
+ * (`../../../../AGENTS.md`: an empty result is a claim, never a shrug);
+ * every disclosure note rides appended lines. Appended only: an explanation
+ * that has no `decisionChange` field renders exactly as it did before.
+ *
+ * @param {{superseded: boolean, comparable: boolean, notes: string[]}} change
+ *   A `detectDecisionChange` result. `superseded` is meaningful only when
+ *   `comparable` is `true`; a non-comparable comparison (one-sided or
+ *   unreadable) renders "could not compare", never "did not move", because
+ *   the latter would assert a fact the comparison could not hold.
+ * @returns {string[]}
+ */
+function formatDecisionChange(change) {
+  const lines = [];
+  if (change.comparable === false) {
+    lines.push(
+      `${DETAIL}decisionChange  could not compare — the decision lineage was not established between the compared registry states`,
+    );
+  } else if (change.superseded) {
+    lines.push(
+      `${DETAIL}decisionChange  superseded — the decision lineage moved between the compared registry states`,
+    );
+  } else {
+    lines.push(
+      `${DETAIL}decisionChange  none — the decision lineage did not move between the compared registry states`,
+    );
+  }
+  for (const note of change.notes) {
+    lines.push(`${DETAIL}decisionChange  ${note}`);
+  }
+  return lines;
+}
+
 /**
  * The whole explain report.
  *
@@ -165,6 +272,20 @@ export function formatExplainReport({ explanation, coverage }) {
     } else {
       sections.push(`${DETAIL}verdict      allowed — no constraint was violated`);
     }
+    // The lineage-comparison disclosure — present only when the explanation
+    // carries it (the caller supplied a base registry); otherwise nothing
+    // here renders, and the report is byte-for-byte what it was.
+    if (explanation.decisionChange !== undefined) {
+      sections.push(...formatDecisionChange(explanation.decisionChange));
+    }
+
+    // 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/history-text.mjs

@@ -12,7 +12,7 @@
  * becomes prose, so the two commands cannot disagree about it.
  */
 
-import { formatChanges, transitionKind } from "./snapshot-text.mjs";
+import { formatChanges, formatClassifications, transitionKind } from "./snapshot-text.mjs";
 
 /**
  * The whole history report.
@@ -20,8 +20,9 @@ import { formatChanges, transitionKind } from "./snapshot-text.mjs";
  * @param {{evolution: {dir: string, captured: object|null,
  *   snapshots: {name: string, id: string}[],
  *   transitions: {from: string, to: string, architectureChanged: boolean,
- *     changes: object|null, policyChanged: boolean|null, providerChanged: boolean,
- *     codeDrift: boolean, notes: string[]}[]}, coverage: object}} input
+ *     changes: object|null, policyChanged: boolean|null, policyOneSided: boolean,
+ *     provenanceChanged: boolean|null, providerChanged: boolean,
+ *     codeDrift: boolean, notes: string[], classifications?: string[]}[]}, coverage: object}} input
  * @returns {string}
  */
 export function formatHistoryReport({ evolution, coverage }) {
@@ -61,6 +62,11 @@ export function formatHistoryReport({ evolution, coverage }) {
     if (transition.architectureChanged) changed += 1;
     const kind = transitionKind(transition);
     sections.push(`~ ${transition.from} → ${transition.to}  (${kind})`);
+    // The canonical classes, appended as their own line so the kind label
+    // (a display shorthand) and the classification (a fact) both print.
+    for (const line of formatClassifications(transition.classifications)) {
+      sections.push(`  ${line}`);
+    }
     if (transition.changes) {
       for (const line of formatChanges(transition.changes)) sections.push(`  ${line}`);
     }

package/src/report/plan-context-text.mjs

@@ -76,6 +76,68 @@ export function formatPlanContextReport({ project, coverage, unresolvedDecisionR
     );
   }
 
+  // Decisions / ADRs in scope (resolved decision lineage).
+  if (plan.decisions && plan.decisions.length > 0) {
+    sections.push(
+      `Decisions (${plan.decisions.length} resolved reference${plan.decisions.length === 1 ? "" : "s"})`,
+    );
+    for (const d of plan.decisions) {
+      const title = d.record ? `${d.record.id}: ${d.record.title}` : d.decisionRef;
+      const status = d.record ? d.record.status : "unresolved";
+      sections.push(`${DETAIL}${title}  (${status})`);
+      if (d.record?.context) {
+        sections.push(`${DETAIL}  context: ${d.record.context}`);
+      }
+    }
+  }
+
+  // Fitness.
+  if (plan.fitness) {
+    sections.push("Fitness");
+    if (!plan.fitness.verified) {
+      sections.push(`${DETAIL}no-verdict — ${plan.fitness.error ?? "could not be evaluated"}`);
+    } else {
+      sections.push(`${DETAIL}overall verdict: ${plan.fitness.overall.verdict}`);
+      if (plan.fitness.decisions.length > 0) {
+        for (const d of plan.fitness.decisions) {
+          sections.push(
+            `${DETAIL}${d.name ?? d.id}: ${d.verdict}${d.reason ? ` — ${d.reason}` : ""}`,
+          );
+        }
+      }
+    }
+  } else {
+    sections.push("Fitness  (no fitness functions declared in the boundary policy)");
+  }
+
+  // Waivers.
+  sections.push("Waivers");
+  if (!plan.waivers.declared) {
+    sections.push(`${DETAIL}no suppressions declared — every boundary is enforced`);
+  } else {
+    const waiverCount = plan.waivers.waivers.length;
+    const permCount = plan.waivers.permanentSuppressions.length;
+    sections.push(
+      `${DETAIL}${waiverCount} waiver${waiverCount === 1 ? "" : "s"}, ` +
+        `${permCount} permanent suppression${permCount === 1 ? "" : "s"}, ` +
+        `${plan.waivers.covered} covering violations, ` +
+        `${plan.waivers.expired} expired, ` +
+        `${plan.waivers.stale} stale`,
+    );
+    if (waiverCount > 0) {
+      for (const w of plan.waivers.waivers) {
+        const term = w.expiresAt
+          ? `expires ${w.expiresAt} (${w.status}, ${w.remainingMs}ms remaining)`
+          : "permanent";
+        sections.push(
+          `${DETAIL}${w.path}  ${term}  covers ${w.covered} violation${w.covered === 1 ? "" : "s"}`,
+        );
+        if (w.reason) sections.push(`${DETAIL}  reason: ${w.reason}`);
+        if (w.origin) sections.push(`${DETAIL}  origin: ${w.origin}`);
+      }
+    }
+  }
+
   // Affected projects.
   sections.push("Architecture");
   sections.push(
@@ -135,6 +197,38 @@ export function formatPlanContextReport({ project, coverage, unresolvedDecisionR
     sections.push(`${DETAIL}${plan.intent.verdict}: ${verdict} (${plan.intent.rows} rows)`);
   }
 
+  // Architecture debt.
+  if (plan.debt) {
+    sections.push("Architecture debt");
+    if (!plan.debt.available) {
+      sections.push(
+        `${DETAIL}not available — ${plan.debt.reason ?? "history directory unavailable"}`,
+      );
+    } else {
+      const entries = plan.debt.entries;
+      const open = plan.debt.total.open;
+      const resolved = plan.debt.total.resolved;
+      sections.push(
+        `${DETAIL}${entries.length} entry${entries.length === 1 ? "" : "s"} ` +
+          `(${open} open, ${resolved} resolved, ${plan.debt.total.total} total) ` +
+          `across ${plan.debt.snapshots} snapshot` +
+          `${plan.debt.snapshots === 1 ? "" : "s"}`,
+      );
+      if (plan.debt.byKind && Object.keys(plan.debt.byKind).length > 0) {
+        const kinds = Object.entries(plan.debt.byKind)
+          .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+          .map(([kind, count]) => `${kind}: ${count}`);
+        sections.push(`${DETAIL}by kind: ${kinds.join(", ")}`);
+      }
+      if (plan.debt.agings && plan.debt.agings.meanDays !== null) {
+        sections.push(
+          `${DETAIL}mean age: ${plan.debt.agings.meanDays.toFixed(1)} days` +
+            `${plan.debt.agings.maxDays !== null ? `, max ${plan.debt.agings.maxDays.toFixed(1)} days` : ""}`,
+        );
+      }
+    }
+  }
+
   // Verification commands.
   sections.push("Verify after the change");
   for (const command of plan.verify) {

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");
 }