@ecoma-io/archkeep 0.16.1 → 0.18.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/change-text.mjs

@@ -13,6 +13,11 @@
  * outcome, so an empty reconciliation is a verifiable claim rather than
  * silence (`../../../../AGENTS.md`).
  *
+ * With `--event-out`, the report's first section names the reconcile event
+ * that was recorded (id, directory, duplicate-or-written) — the one section
+ * that renders only when the flag was passed, so the default report is
+ * byte-identical to a pre-wave-3 run.
+ *
  * This module decides nothing. A formatter that filtered would be a rule
  * wearing a formatter's name (`./README.md`).
  */
@@ -62,14 +67,27 @@ function describeOrigin(provenance) {
 /**
  * The whole change report.
  *
- * @param {{change: object, coverage: object}} input `change` is
- *   `../commands/change.mjs`'s result payload; `coverage` its coverage block.
+ * @param {{change: object, coverage: object, eventWritten?: object}} input
+ *   `change` is `../commands/change.mjs`'s result payload; `coverage` its
+ *   coverage block; `eventWritten` the reconcile event write result (`{dir,
+ *   id, duplicate}`) — present ONLY when `--event-out` was passed, so the
+ *   default report is byte-identical to a pre-wave-3 run.
  * @returns {string}
  */
-export function formatChangeReport({ change, coverage }) {
+export function formatChangeReport({ change, coverage, eventWritten }) {
   const { intent, baseline, head, reconciliation, constraints, policy } = change;
   const sections = [];
 
+  // The reconcile event line renders ONLY when `--event-out` was passed and
+  // the run wrote one (`../commands/change.mjs`): the write is opt-in output
+  // the report makes observable rather than a file appearing silently.
+  if (eventWritten !== undefined) {
+    sections.push(
+      `event      reconcile/change ${eventWritten.id.slice(0, 8)} → ${eventWritten.dir}` +
+        (eventWritten.duplicate ? " (duplicate — nothing written)" : ""),
+    );
+  }
+
   sections.push(
     `intent     ${intent.file} — base ${intent.base.commit.slice(0, 8)}` +
       (intent.summary === undefined ? "" : `\n             "${intent.summary}"`),

package/src/report/debt-text.mjs

@@ -41,8 +41,11 @@ function sanitize(text) {
  *
  * @param {{ledger: {dir: string, snapshots: number, agings: boolean,
  *   sampleTime: string, entries: {source: string, kind: string,
- *   severity: string, age: number, count: number, remediationHint: string}[],
- *   total: number, byKind: object, bySeverity: object},
+ *   severity: string, age: number, count: number, remediationHint: string,
+ *   id: string, status: string, introducedBy?: string}[],
+ *   resolved?: {id: string, status: string, resolvedBy: string}[],
+ *   total: number, byKind: object, bySeverity: object,
+ *   lifecycle?: {linked: boolean, note: string|null}},
  *   coverage: object}} input
  * @returns {string}
  */
@@ -60,15 +63,14 @@ export function formatDebtReport({ ledger, coverage }) {
 
   const orderedKinds = [
     ["waiver", "waivers (accepted boundary violations)"],
+    ["expired-waiver", "expired waivers (accepted violations that lapsed back into force)"],
     ["aspirational-gap", "aspirational gaps (optional allowed rows not built)"],
     ["drift", "drift findings"],
     ["unresolved", "unresolved intent"],
   ];
-  let sawAny = false;
   for (const [kind, label] of orderedKinds) {
     const items = ledger.entries.filter((e) => e.kind === kind);
     if (items.length === 0) continue;
-    sawAny = true;
     sections.push(`${items.length} ${label}:`);
     for (const entry of items) {
       const age = ledger.agings ? `age ${entry.age}` : "age not yet established";
@@ -76,17 +78,51 @@ export function formatDebtReport({ ledger, coverage }) {
         `  [${entry.kind}] ${entry.severity}  ${sanitize(entry.source)}  (${age}, count ${entry.count})`,
       );
       sections.push(`    ${sanitize(entry.remediationHint)}`);
+      // The lifecycle fields (design §6) ride the entry as appended lines only;
+      // every existing line above keeps its exact bytes. When no event store is
+      // linked, the id/status are still printed (they are facts about the entry,
+      // always determinable); refs are printed only when actually present.
+      sections.push(`    id ${entry.id} · status ${entry.status}`);
+      if (entry.introducedBy) sections.push(`    introducedBy ${entry.introducedBy}`);
     }
   }
-
-  if (!sawAny) {
+  // The positive claim must be byte-truthful: no CURRENT findings AND no
+  // retained resolution history. A ledger with an empty entry list but a
+  // non-empty resolved list is not "no architecture debt" — it has history
+  // that was resolved and is retained below (F-DEB-4).
+  const resolved = ledger.resolved ?? [];
+  if (ledger.entries.length === 0 && resolved.length === 0) {
     sections.push(
       "✔ no architecture debt — no waivers, aspirational gaps, drift or unresolved intent",
     );
+  } else if (ledger.entries.length === 0 && resolved.length > 0) {
+    sections.push(
+      `no current architecture debt; ${resolved.length} resolved entry${resolved.length === 1 ? "" : "s"} retained below`,
+    );
+  }
+
+  // The resolved surface (design §6): debt whose candidate fact is gone at
+  // head AND closed by evidence (a REPAIR event). Entries are retained — the
+  // history is never deleted — but they are no longer current findings. This
+  // list is empty (and no line is printed) when no event store is linked or
+  // nothing has been resolved.
+  if (resolved.length > 0) {
+    sections.push(`${resolved.length} resolved (no longer current findings):`);
+    for (const entry of resolved) {
+      // The resolved surface is evidence-backed only — id/status/resolvedBy
+      // (F-DEB-2). The kind/severity/hint of the original entry live in the
+      // history snapshots the ledger read, never in this row.
+      sections.push(`  id ${entry.id} · status ${entry.status}`);
+      if (entry.resolvedBy) sections.push(`    resolvedBy ${entry.resolvedBy}`);
+    }
+  }
+  if (ledger.lifecycle?.note) {
+    sections.push(ledger.lifecycle.note);
   }
 
   sections.push(
     `total ${ledger.total} ${word} · byKind: waiver ${ledger.byKind.waiver}, ` +
+      `expired-waiver ${ledger.byKind["expired-waiver"]}, ` +
       `aspirational-gap ${ledger.byKind["aspirational-gap"]}, drift ${ledger.byKind.drift}, ` +
       `unresolved ${ledger.byKind.unresolved} · bySeverity: high ${ledger.bySeverity.high}, ` +
       `medium ${ledger.bySeverity.medium}, low ${ledger.bySeverity.low}`,

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/delta-text.mjs

@@ -18,7 +18,10 @@
  * `../commands/delta.mjs` pushes there — fold into the report as their own
  * lines, so a note that rides the JSON envelope also reaches the terminal.
  *
- * This module decides nothing. A formatter that filtered would be a rule
+ * The wave-3 additive block — `classifications` and `affected` — is appended
+ * after every existing line (and only when the payload carries the fields), so
+ * a payload that predates them renders exactly what it always did. This module
+ * decides nothing. A formatter that filtered would be a rule
  * wearing a formatter's name (`./README.md`).
  */
 
@@ -259,6 +262,38 @@ export function formatDeltaReport({ delta, coverage }) {
         `no waiver lane, every one gates`,
     );
   }
+  // The wave-3 additive block: the evolution classification and its affected
+  // identities, appended after every existing line so an older report's lines
+  // stay byte-identical. Rendered only when the payload carries the fields —
+  // a payload that predates them renders exactly what it always did. An empty
+  // classification list is not silence here: the closing claims above already
+  // state what was compared, and `classifications  none` says plainly that no
+  // class applies.
+  if (delta.classifications !== undefined) {
+    sections.push(
+      `classifications  ${
+        delta.classifications.length === 0 ? "none" : delta.classifications.join(", ")
+      }`,
+    );
+  }
+  if (delta.affected !== undefined) {
+    const affectedParts = [];
+    if (delta.affected.projects.length > 0) {
+      affectedParts.push(`projects: ${delta.affected.projects.join(", ")}`);
+    }
+    if (delta.affected.boundaries.length > 0) {
+      affectedParts.push(`boundaries: ${delta.affected.boundaries.join(", ")}`);
+    }
+    if (delta.affected.constraints.length > 0) {
+      affectedParts.push(`constraints: ${delta.affected.constraints.join(", ")}`);
+    }
+    if (delta.affected.decisions.length > 0) {
+      affectedParts.push(`decisions: ${delta.affected.decisions.join(", ")}`);
+    }
+    sections.push(
+      `affected         ${affectedParts.length === 0 ? "none" : affectedParts.join(" · ")}`,
+    );
+  }
 
   return sections.join("\n");
 }