@ecoma-io/archkeep 0.16.1 → 0.18.0

package/README.md

@@ -225,7 +225,7 @@ Ten minutes end to end, most of it spent deciding what your tags mean:
 Ten minutes end to end, most of it spent deciding what your tags mean:
 [**Getting started →**](https://github.com/ecoma-io/archkeep/blob/main/docs/getting-started/installation.md). `graph`, `diff`,
 `history`, `trajectory`, `evolution`, `drift`, `impact`, `explain`,
-`context` and the rest of the 22-command surface are in the
+`context` and the rest of the 23-command surface are in the
 [CLI reference](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/cli.md).
 
 ## Documentation map

package/cli.mjs

@@ -107,6 +107,7 @@ import {
 import { contextCommand } from "./src/commands/context-command.mjs";
 import { planContextCommand } from "./src/commands/plan-context-command.mjs";
 import { adrCommand } from "./src/commands/adr.mjs";
+import { decisionsCommand } from "./src/commands/decisions.mjs";
 import { diffCommand } from "./src/commands/diff.mjs";
 import { captureDelta, deltaCommand } from "./src/commands/delta.mjs";
 import { discoverCommand } from "./src/commands/discover.mjs";
@@ -930,12 +931,8 @@ async function runDiff(options, { cwd, env }) {
  *
  * `--capture` writes the evidence snapshot a later run compares against;
  * `delta <baseline>` loads one, re-judges both sides under the current law,
- * and folds the classification into the exit code — the one descriptive-family
- * verb beside `check` and `fitness` whose verdict carries exit 1
- * (`./src/commands/delta.mjs` owns the fold).
- *
  * @param {{format: string, output: string|null, config: string|null, capture: boolean,
- *   paths: string[]}} options
+ *   eventOut: string|null, paths: string[]}} options
  * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
  * @returns {Promise<number>}
  */
@@ -947,6 +944,13 @@ async function runDelta(options, { cwd, env }) {
       );
       return EXIT.usage;
     }
+    if (options.eventOut !== null) {
+      env.err(
+        `archkeep: delta --capture does not take --event-out — an event records a transition, ` +
+          `and a capture is one side of it`,
+      );
+      return EXIT.usage;
+    }
   } else if (options.paths.length !== 1) {
     env.err(
       `archkeep: delta takes exactly one positional argument (the baseline evidence snapshot), ` +
@@ -971,7 +975,6 @@ async function runDelta(options, { cwd, env }) {
       const { text } = captureDelta(commandContext, { config });
       if (options.output) {
         // Atomic, symlink-safe write — `writeOutputReport`'s own docstring
-        // owns the mechanism and the threat it closes.
         if (!writeOutputReport(options.output, text, env, cwd, options.config)) return EXIT.error;
         env.err(`archkeep: delta baseline captured → ${options.output}`);
       } else {
@@ -984,7 +987,10 @@ async function runDelta(options, { cwd, env }) {
     const baselinePath = isAbsolute(options.paths[0])
       ? resolve(options.paths[0])
       : resolve(cwd, options.paths[0]);
-    result = await deltaCommand(baselinePath, commandContext, { config });
+    result = await deltaCommand(baselinePath, commandContext, {
+      config,
+      eventOut: options.eventOut,
+    });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -1008,6 +1014,18 @@ async function runDelta(options, { cwd, env }) {
     env.out(report);
   }
 
+  // The event the run recorded, when `--event-out` was given — the store's
+  // own `duplicate` answer, so a rerun over the same transition says so
+  // instead of implying a second event was appended. Capture mode refuses the
+  // flag upstream; this line runs only for a compare.
+  if (result.eventWrite !== null) {
+    env.err(
+      `archkeep: evolution event ${
+        result.eventWrite.duplicate ? "duplicate, already recorded" : "recorded"
+      } → ${options.eventOut}`,
+    );
+  }
+
   // The exit fold `deltaCommand` computed: a non-waived introduced violation
   // is a finding, an unclassifiable item is a no-verdict, anything else is
   // clean — mapped here the same way `fitness`'s status is.
@@ -1213,7 +1231,7 @@ async function runReconcile(options, { cwd, env }) {
  * `check` remains the authority on the law.
  *
  * @param {{format: string, output: string|null, config: string|null,
- *   intent: string|null, paths: string[]}} options
+ *   intent: string|null, eventOut?: string|null, paths: string[]}} options
  * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function,
  *   listFiles?: Function}}} runContext
  * @returns {Promise<number>}
@@ -1270,7 +1288,19 @@ async function runChange(options, { cwd, env }) {
     // profile-aware the same way `check` is.
     const { config } = await resolvePolicy(options, commandContext, cwd);
 
-    result = await changeCommand(baselinePath, intentPath, commandContext, { config });
+    // `--event-out` names the reconcile event store directory, resolved from
+    // cwd like the other path flags; `undefined` when absent, so a run
+    // without the flag writes no event and stays byte-identical.
+    const eventOut =
+      typeof options.eventOut === "string" && options.eventOut !== ""
+        ? isAbsolute(options.eventOut)
+          ? options.eventOut
+          : resolve(cwd, options.eventOut)
+        : undefined;
+    result = await changeCommand(baselinePath, intentPath, commandContext, {
+      config,
+      ...(eventOut === undefined ? {} : { eventOut }),
+    });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -1580,7 +1610,7 @@ async function runExplain(options, { cwd, env }) {
  * same as `check` and `explain`, because the answer depends on which boundary
  * law is in effect.
  *
- * @param {{format: string, output: string|null, config: string|null, plan: boolean, paths: string[]}} options
+ * @param {{format: string, output: string|null, config: string|null, plan: boolean, paths: string[], historyDir: string|null}} options
  * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
  * @returns {Promise<number>}
  */
@@ -1621,8 +1651,14 @@ async function runContextCommand(options, { cwd, env }) {
     // profile-aware the same way `check` is.
     const { config } = await resolvePolicy(options, commandContext, cwd);
 
+    const historyDir = options.historyDir
+      ? isAbsolute(options.historyDir)
+        ? options.historyDir
+        : resolve(cwd, options.historyDir)
+      : null;
+
     result = options.plan
-      ? await planContextCommand(projectName, scopePaths, commandContext, config)
+      ? await planContextCommand(projectName, scopePaths, commandContext, config, historyDir)
       : contextCommand(projectName, commandContext, config);
   } catch (error) {
     const usageError = error instanceof UsageError;
@@ -1712,6 +1748,73 @@ async function runAdr(options, { cwd, env }) {
   // Descriptive: 0 for answered, 3 for incomplete coverage.
   return result.status === "ok" ? EXIT.ok : EXIT.error;
 }
+/**
+ * `decisions`'s run: the deterministic chain behind one recorded decision —
+ * decision → governed rows → projects → current findings, with the
+ * per-decision verification level. Exactly one positional: the ADR id.
+ *
+ * The law is resolved the way `report` resolves it (`resolvePolicy`) because
+ * the chain's Fitness leg reads the workspace's declared gates, and `--config`
+ * wins the same way. Fitness verdicts are derived inside the command from the
+ * declared list; a declared gate that fails to evaluate THROWS (exit 3), it
+ * never silently walks clean. `0` when every hop of the chain resolved, `3`
+ * when any did not — never `1`.
+ *
+ * @param {{format: string, output: string|null, config: string|null, paths: string[]}} options
+ * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
+ * @returns {Promise<number>}
+ */
+async function runDecisions(options, { cwd, env }) {
+  if (options.paths.length !== 1) {
+    env.err(
+      `archkeep: decisions takes exactly one positional argument (an ADR id); ` +
+        `got ${options.paths.length}`,
+    );
+    return EXIT.usage;
+  }
+
+  let result;
+  try {
+    const commandContext = resolveCommandContext(
+      { cwd },
+      { readGraph: env.readGraph, listFiles: env.listFiles },
+    );
+
+    // ONE law for the chain, resolved exactly like `report` — the Fitness leg
+    // reads this law's declared gates, so a `--config` override must reach it.
+    const { config } = await resolvePolicy(options, commandContext, cwd);
+
+    const intent = commandContext.tracked.includes(INTENT_FILE)
+      ? await loadIntent(commandContext.root, { tracked: commandContext.tracked })
+      : null;
+
+    result = decisionsCommand(options.paths[0], commandContext, config, { intent });
+  } catch (error) {
+    const usageError = error instanceof UsageError;
+    env.err(String(error?.message ?? error));
+    return usageError ? EXIT.usage : EXIT.error;
+  }
+
+  const report = options.format === "json" ? result.report.json : result.report.text;
+
+  if (options.output) {
+    // Atomic, symlink-safe write — `writeOutputReport`'s own docstring owns
+    // the mechanism and the threat it closes.
+    const reportText = report.endsWith("\n") ? report : `${report}\n`;
+    if (!writeOutputReport(options.output, reportText, env, cwd, options.config)) return EXIT.error;
+    // The confirmation names the no-verdict case, so a reader who only
+    // glances at stderr cannot mistake a written chain for a resolved one.
+    env.err(
+      `archkeep: decision chain for ${options.paths[0]} ` +
+        `${result.status === "ok" ? "resolved" : "did NOT fully resolve"} → ${options.output}`,
+    );
+  } else {
+    env.out(report);
+  }
+
+  // Descriptive: 0 when every hop resolved, 3 when any could not. Never 1.
+  return result.status === "ok" ? EXIT.ok : EXIT.error;
+}
 
 /**
  * `rules`'s `run`: dispatches to the appropriate subcommand (list/info/verify/add),
@@ -1958,7 +2061,7 @@ async function runTrajectory(options, { cwd, env }) {
  * production both are undefined and every revision is read for real.
  *
  * @param {{format: string, output: string|null, base: string|null, head: string|null,
- *   paths: string[]}} options
+ *   eventOut: string|null, paths: string[]}} options
  * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
  * @returns {Promise<number>}
  */
@@ -1989,9 +2092,18 @@ async function runEvolution(options, { cwd, env }) {
 
   let result;
   try {
+    // `--event-out` names the transition event store directory, resolved from
+    // cwd like the other path flags; `null` when absent, so a run without the
+    // flag writes no event and stays byte-identical.
+    const eventOut =
+      typeof options.eventOut === "string" && options.eventOut !== ""
+        ? isAbsolute(options.eventOut)
+          ? options.eventOut
+          : resolve(cwd, options.eventOut)
+        : null;
     result = await evolutionCommand(
       root,
-      { base: options.base, head: options.head },
+      { base: options.base, head: options.head, eventOut },
       {
         readGraph: env.readGraph,
         listFiles: env.listFiles,
@@ -2030,7 +2142,7 @@ async function runEvolution(options, { cwd, env }) {
  * consumer-managed directory `history` reads, so a ledger ages across the
  * same snapshots the evolution record is built from.
  *
- * @param {{format: string, output: string|null, config: string|null, paths: string[]}} options
+ * @param {{format: string, output: string|null, config: string|null, events: string|null, paths: string[]}} options
  * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
  * @returns {Promise<number>}
  */
@@ -2058,7 +2170,10 @@ async function runDebt(options, { cwd, env }) {
     // profile-selected workspace resolves the same way `check` does.
     const { config } = await resolvePolicy(options, commandContext, cwd);
 
-    result = await debtCommand(dir, commandContext, { config });
+    result = await debtCommand(dir, commandContext, {
+      config,
+      events: options.events,
+    });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -2462,6 +2577,17 @@ const DELTA_FLAG_HELP = Object.freeze([
           : `<workspace root>/${boundaryConfig}`,
       ]),
   }),
+  Object.freeze({
+    flag: "--event-out",
+    key: "eventOut",
+    arg: "<dir>",
+    describe: Object.freeze([
+      "Append the delta's evolution event to this directory",
+      "(one canonical record per transition; idempotent — a",
+      "rerun over the same transition writes nothing new).",
+      "Absent: no event file is written",
+    ]),
+  }),
 ]);
 
 /**
@@ -2498,6 +2624,16 @@ const CHANGE_FLAG_HELP = Object.freeze([
     arg: "<file>",
     describe: Object.freeze(["Write the report to a file instead of stdout"]),
   }),
+  Object.freeze({
+    flag: "--event-out",
+    key: "eventOut",
+    arg: "<dir>",
+    describe: Object.freeze([
+      "Also write the reconcile EvolutionEvent to this directory",
+      "(one file per run, idempotent; the classification always",
+      "rides the envelope result — see docs/concepts/evolution.md)",
+    ]),
+  }),
   Object.freeze({
     flag: "--config",
     key: "config",
@@ -2771,6 +2907,16 @@ const EVOLUTION_FLAG_HELP = Object.freeze([
       "linear descendant of --base with no merges between",
     ]),
   }),
+  Object.freeze({
+    flag: "--event-out",
+    key: "eventOut",
+    arg: "<dir>",
+    describe: Object.freeze([
+      "Append one EvolutionEvent per revision pair to this directory",
+      "(idempotent — a re-run over the same pair records a duplicate, never",
+      "a second event). docs/concepts/evolution.md owns the event model.",
+    ]),
+  }),
 ]);
 
 /**
@@ -2913,6 +3059,15 @@ const DEBT_FLAG_HELP = Object.freeze([
           : `<workspace root>/${boundaryConfig}`,
       ]),
   }),
+  Object.freeze({
+    flag: "--events",
+    key: "events",
+    arg: "<dir>",
+    describe: Object.freeze([
+      "Link the evolution event store in <dir> so debt entries carry",
+      "introducedBy/resolvedBy refs and a resolved list",
+    ]),
+  }),
 ]);
 
 /**
@@ -2985,6 +3140,42 @@ const EXPLAIN_FLAG_HELP = Object.freeze([
   }),
 ]);
 
+/**
+ * `decisions`'s flags: text or JSON envelope, optional file output, and the
+ * same `--config` override `report` takes — the chain's Fitness leg reads the
+ * declared gates of one boundary law, and a caller must be able to say which.
+ *
+ * @type {readonly FlagHelp[]}
+ */
+const DECISIONS_FLAG_HELP = Object.freeze([
+  Object.freeze({
+    flag: "--format",
+    key: "format",
+    arg: "text|json",
+    describe: Object.freeze([
+      "Terminal report (default) or the versioned JSON envelope",
+      "docs/reference/json-output.md documents",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--output",
+    key: "output",
+    arg: "<file>",
+    describe: Object.freeze(["Write the report to a file instead of stdout"]),
+  }),
+  Object.freeze({
+    flag: "--config",
+    key: "config",
+    arg: "<file>",
+    describe: ({ boundaryConfig, inline }) =>
+      Object.freeze([
+        "Read the boundary law from here instead of",
+        inline
+          ? "the inline boundaryConfig in archkeep.json"
+          : `<workspace root>/${boundaryConfig}`,
+      ]),
+  }),
+]);
 /**
  * `context`'s flags: text or JSON envelope, optional file output.
  * The project name is a positional argument. `--config` overrides the boundary
@@ -3035,6 +3226,18 @@ const CONTEXT_FLAG_HELP = Object.freeze([
           : `<workspace root>/${boundaryConfig}`,
       ]),
   }),
+  Object.freeze({
+    flag: "--history-dir",
+    key: "historyDir",
+    arg: "<dir>",
+    describe: Object.freeze([
+      "Path to the workspace's history directory. When given and",
+      "the directory holds archived snapshots, the planning context",
+      "includes the architecture-debt snapshot: current violations,",
+      "exemptions, and gaps aged across the history. Used only with",
+      "`--plan`; ignored otherwise.",
+    ]),
+  }),
 ]);
 
 /**
@@ -3148,7 +3351,13 @@ const COMMANDS = Object.freeze({
     summary: "Classify how boundary violations moved between a captured baseline and head",
     flagHelp: DELTA_FLAG_HELP,
     flags: Object.freeze(Object.fromEntries(DELTA_FLAG_HELP.map((f) => [f.flag, f.key]))),
-    defaults: Object.freeze({ format: "text", output: null, config: null, capture: false }),
+    defaults: Object.freeze({
+      format: "text",
+      output: null,
+      config: null,
+      capture: false,
+      eventOut: null,
+    }),
     formats: DELTA_FORMATS,
     booleans: Object.freeze(["capture"]),
     run: runDelta,
@@ -3159,7 +3368,13 @@ const COMMANDS = Object.freeze({
     summary: "Reconcile a declared change intent against the architectural delta",
     flagHelp: CHANGE_FLAG_HELP,
     flags: Object.freeze(Object.fromEntries(CHANGE_FLAG_HELP.map((f) => [f.flag, f.key]))),
-    defaults: Object.freeze({ format: "text", output: null, config: null, intent: null }),
+    defaults: Object.freeze({
+      format: "text",
+      output: null,
+      config: null,
+      intent: null,
+      eventOut: null,
+    }),
     formats: DESCRIBABLE_FORMATS,
     run: runChange,
   }),
@@ -3242,7 +3457,13 @@ const COMMANDS = Object.freeze({
     summary: "Describe how the architecture evolved across a Git revision range",
     flagHelp: EVOLUTION_FLAG_HELP,
     flags: Object.freeze(Object.fromEntries(EVOLUTION_FLAG_HELP.map((f) => [f.flag, f.key]))),
-    defaults: Object.freeze({ format: "text", output: null, base: null, head: null }),
+    defaults: Object.freeze({
+      format: "text",
+      output: null,
+      base: null,
+      head: null,
+      eventOut: null,
+    }),
     formats: DESCRIBABLE_FORMATS,
     run: runEvolution,
   }),
@@ -3272,7 +3493,7 @@ const COMMANDS = Object.freeze({
     summary: "Print the architecture-debt ledger across snapshots",
     flagHelp: DEBT_FLAG_HELP,
     flags: Object.freeze(Object.fromEntries(DEBT_FLAG_HELP.map((f) => [f.flag, f.key]))),
-    defaults: Object.freeze({ format: "text", output: null, config: null }),
+    defaults: Object.freeze({ format: "text", output: null, config: null, events: null }),
     formats: DESCRIBABLE_FORMATS,
     run: runDebt,
   }),
@@ -3302,7 +3523,13 @@ const COMMANDS = Object.freeze({
     summary: "Show the architecture constraints that apply to a project",
     flagHelp: CONTEXT_FLAG_HELP,
     flags: Object.freeze(Object.fromEntries(CONTEXT_FLAG_HELP.map((f) => [f.flag, f.key]))),
-    defaults: Object.freeze({ format: "text", output: null, config: null, plan: false }),
+    defaults: Object.freeze({
+      format: "text",
+      output: null,
+      config: null,
+      plan: false,
+      historyDir: null,
+    }),
     formats: DESCRIBABLE_FORMATS,
     booleans: Object.freeze(["plan"]),
     run: runContextCommand,
@@ -3317,6 +3544,17 @@ const COMMANDS = Object.freeze({
     formats: DESCRIBABLE_FORMATS,
     run: runProvenance,
   }),
+  decisions: Object.freeze({
+    name: "decisions",
+    args: "<id>",
+    summary:
+      "Walk the full chain behind one recorded decision — decision to bound rows, projects, findings, and its verification level",
+    flagHelp: DECISIONS_FLAG_HELP,
+    flags: Object.freeze(Object.fromEntries(DECISIONS_FLAG_HELP.map((f) => [f.flag, f.key]))),
+    defaults: Object.freeze({ format: "text", output: null, config: null }),
+    formats: DESCRIBABLE_FORMATS,
+    run: runDecisions,
+  }),
   adr: Object.freeze({
     name: "adr",
     args: "[<id>]",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "description": "Architecture enforcement for polyglot repositories — dependency graphs and module boundaries for Go, Rust, Python, TypeScript, JavaScript, Vue, Java and Kotlin",
   "keywords": [
     "architecture",
@@ -53,7 +53,7 @@
   },
   "peerDependencies": {
     "@nx/eslint-plugin": ">=21",
-    "fast-xml-parser": "5.11.0",
+    "fast-xml-parser": "5.11.1",
     "nx": ">=21",
     "typescript": ">=5 <7",
     "vue": ">=3"

package/src/architecture-intent/judge.mjs

@@ -168,12 +168,15 @@ function codeDependencies(graph) {
  * @param {object} intent The normalized model from `./model.mjs`.
  * @param {{nodes: object, dependencies?: object}} graph
  * @returns {{verdict: "ok"|"findings"|"no-verdict",
- *   findings: object[], unresolved: object[], boundaries: object[], notes: string[]}}
+ *   findings: object[], unresolved: object[], boundaries: object[], notes: string[],
+ *   gaps: {from: string, to: string, note: string}[]}}
  *   `findings` are `{source, target, rule, boundaryFrom, boundaryTo, message}`;
  *   `unresolved` are `{boundary, issue}` for every empty side or empty
  *   boundary; `boundaries` are `{name, projects[]}` (sorted members); `notes`
  *   are coverage notes that change no verdict — today only an
- *   `"optional": true` `allowed` row whose statement is not yet built.
+ *   `"optional": true` `allowed` row whose statement is not yet built; `gaps`
+ *   carry the same rows' structured `{from, to}` identities (F-DEB-8), the
+ *   stable key the debt ledger hashes an aspirational-gap entry by.
  */
 export function judgeIntent(intent, graph) {
   const nodes = graph.nodes ?? {};
@@ -191,6 +194,7 @@ export function judgeIntent(intent, graph) {
   const findings = [];
   const unresolved = [];
   const notes = [];
+  const gaps = [];
 
   for (const boundary of boundaries) {
     if (boundary.projects.length === 0) {
@@ -291,9 +295,18 @@ export function judgeIntent(intent, graph) {
       // Absence tolerated — aspirational, not drift — but it is still a
       // coverage note and the caller threads it into the report's coverage
       // notes, so a reader can tell "optional and absent" from "never checked".
-      notes.push(
-        `optional allowed intent "${row.from}" → "${row.to}" is not yet observed — aspirational, not drift`,
-      );
+      const note = `optional allowed intent "${row.from}" → "${row.to}" is not yet observed — aspirational, not drift`;
+      notes.push(note);
+      // The structured `{from, to}` is the STABLE identity of the gap — the
+      // debt ledger keys an aspirational-gap entry by it (F-DEB-8), never by
+      // the prose note, so a reworded note does not re-key the fact.
+      gaps.push({
+        from: row.from,
+        to: row.to,
+        note,
+        boundaryFrom: from.boundaryName ?? row.from,
+        boundaryTo: to.boundaryName ?? row.to,
+      });
       return;
     }
     const pairs = [];
@@ -535,5 +548,5 @@ export function judgeIntent(intent, graph) {
 
   const verdict = findings.length > 0 ? "findings" : unresolved.length > 0 ? "no-verdict" : "ok";
 
-  return { verdict, findings, unresolved, boundaries, notes };
+  return { verdict, findings, unresolved, boundaries, notes, gaps };
 }

package/src/commands/adr.mjs

@@ -55,6 +55,20 @@
  * `bindings` beside `knownFitness`, at exit 0. Naming a limit is not a
  * verdict; leaving it unnamed would be the silent direction
  * (`../../../../AGENTS.md`).
+ * ## What it can say about fitness
+ *
+ * Wave 2's fitness derivation (`../governance/decision-fitness.mjs`) folds a
+ * decision's bound constraints and their verdicts into one per-decision
+ * level. It is NOT wired into this command's own read: `adr` stays the
+ * registry-only surface it was. The caller may hand verdicts in through
+ * `io.fitnessVerdicts` (the same `{name, verdict}` shape `fitness` produces)
+ * and every record then renders its level — `verified` only when a bound
+ * constraint passes. Without verdicts the derivation still runs, and its
+ * honest answer is echoed: a decision with authority but nothing verifiable
+ * is `unverifiable` — never healthy — while a status without authority is
+ * `not_applicable`. An empty verdict set is not silence; it is the registry
+ * alone asserting nothing. Levels never change the exit code: `adr` remains
+ * 0/2/3, a description of what is recorded, not a gate.
  */
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import {
@@ -65,6 +79,8 @@ import {
 } from "../report/adr-text.mjs";
 import { ADR_DIR, stripAdrPrefix } from "../governance/adr-registry.mjs";
 import { adrsBinding, boundFitnessIds, loadAdrRegistry } from "../governance/adr-registry.mjs";
+import { computeDecisionFitness } from "../governance/decision-fitness.mjs";
+import { stripRuleFitnessPrefix } from "../governance/adr-registry.mjs";
 
 /**
  * The other half of the id name space the positional argument answers
@@ -124,8 +140,11 @@ export function readAdrContext(root, io = {}) {
  * @param {{id?: string}} options
  * @param {{loadAdrRegistryOverride?: typeof loadAdrRegistry, tracked?: string[],
  *   lstatSync?: (path: string) => {isSymbolicLink: () => boolean},
- *   realpathSync?: (path: string) => string}} [io] Forwarded to
- *   `readAdrContext` unchanged.
+ *   realpathSync?: (path: string) => string, fitnessVerdicts?:
+ *   Array<{name: string, verdict: string}>}} [io] `tracked`, `lstatSync` and
+ *   `realpathSync` are forwarded to `readAdrContext` unchanged; `fitnessVerdicts`
+ *   feeds the per-decision fitness derivation ("What it can say about fitness"
+ *   in the module header owns what an absent array means).
  * @returns {{status: "ok"|"no-verdict", result: object, coverage: object,
  *   report: {text: string, json: string}}}
  * @throws {Error} on an unreadable registry (exit-3 class).
@@ -135,6 +154,21 @@ export function adrCommand(root, options, io = {}) {
 
   const { records, byId, knownFitness } = ctx;
 
+  // Per-decision fitness: the wave-2 derivation, fed a lookup built from
+  // whatever verdicts the caller can supply (`io.fitnessVerdicts`, the same
+  // `{name, verdict}` shape the `fitness` command emits). A binding's prefix
+  // (`rule:`/`fitness:`) is stripped before the lookup — a verdict names a
+  // declared fitness id, and `fitness:hotspot` and `hotspot` are the same id.
+  // An empty verdict set is a legitimate input: every authority decision then
+  // derives `unverifiable`, which is the registry alone asserting nothing —
+  // the module header's "What it can say about fitness" owns the wording.
+  const verdictByName = new Map((io.fitnessVerdicts ?? []).map((v) => [v.name, v]));
+  const fitnessLookup = (bindingId) => verdictByName.get(stripRuleFitnessPrefix(bindingId));
+  const fitnessById = new Map(
+    computeDecisionFitness(records, null, fitnessLookup).map((entry) => [entry.id, entry]),
+  );
+  const fitness = [...fitnessById.values()];
+
   // An id the caller asked about that the registry does not know is a named
   // unknown, not a clean result — the invariant. Two cases, told apart by the
   // id's shape: a `rule:x`/`fitness:x` ref (`FITNESS_REF_PATTERN`, above) is a
@@ -194,15 +228,22 @@ export function adrCommand(root, options, io = {}) {
     supersedes: records.flatMap((record) =>
       record.supersedes.map((ref) => ({ adr: record.id, supersedes: ref })),
     ),
+    // The derived reverse link — the records whose `supersedes` names this
+    // one — so a machine reader of the envelope sees the same lineage the
+    // text face shows.
+    supersededBy: records.flatMap((record) =>
+      record.supersededBy.map((id) => ({ adr: record.id, supersededBy: id })),
+    ),
+    fitness,
     unresolved,
     knownFitness: [...knownFitness].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
   };
 
   const text =
     requestedId === undefined
-      ? formatAdrDump({ records, knownFitness })
+      ? formatAdrDump({ records, knownFitness, fitnessById })
       : byId.has(resolvedAdrId)
-        ? formatAdrRecord(byId.get(resolvedAdrId), knownFitness)
+        ? formatAdrRecord(byId.get(resolvedAdrId), knownFitness, fitnessById)
         : isFitnessRef
           ? formatAdrReverse({ fitnessId: requestedId, adrIds: adrsBinding(records, requestedId) })
           : formatAdrMissing({ adrId: requestedId });