@ecoma-io/archkeep 0.16.0 → 0.17.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";
@@ -1712,6 +1713,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),
@@ -2985,6 +3053,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
@@ -3317,6 +3421,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.0",
+  "version": "0.17.0",
   "description": "Architecture enforcement for polyglot repositories — dependency graphs and module boundaries for Go, Rust, Python, TypeScript, JavaScript, Vue, Java and Kotlin",
   "keywords": [
     "architecture",

package/src/analysis/csharp.mjs

@@ -70,6 +70,11 @@
  *   same class of limit Kotlin's backtick segments pin.
  * - An **unterminated directive** (no `;` before end of line) is not a
  *   complete directive and is not read.
+ * - A **statement whose initializer opens but never closes** (`using var x =
+ *   new F {`, the `;` never arriving) is neither read nor flagged — the `{`
+ *   behind the resource's `=` is the statement's own (#469), the same
+ *   silence a `using (r) {` block has always held. The malformation scan
+ *   judges directives only.
  */
 import { csharpNamespaceIndex } from "./dotnet/namespaces.mjs";
 import { maskCSharpComments } from "./dotnet/mask.mjs";
@@ -130,6 +135,13 @@ const CS_EXTERN_ALIAS = new RegExp(
 /** Exactly one identifier followed by `=`: the alias form. */
 const ALIAS_FORM = new RegExp(String.raw`^(${SEG})[ \t]*=[ \t]*(.+)$`, "su");
 
+/**
+ * One bare identifier, optionally verbatim (`@class`): an alias's own name.
+ * The malformation scan reads it backwards — the text before an initializer
+ * `=` is an alias's name only when it is NOT this shape.
+ */
+const ALIAS_NAME = new RegExp(String.raw`^@?${SEG}$`, "u");
+
 /** A dotted name, optionally behind the `global::` qualifier: the plain form. */
 const PLAIN_FORM = new RegExp(String.raw`^(?:global::)?(${DOTTED_NAME})$`, "u");
 
@@ -262,10 +274,17 @@ export function parseCSharpDirectiveSites(csharpText) {
  * from one the file truncates — a failed write, a merge marker left
  * mid-directive — which used to parse as zero directive sites with no
  * failure, byte-for-byte identical to a file that imports nothing (#419).
- * A `(` right after the
- * keyword is the using-STATEMENT family — `using (var s = f()) { … }`,
- * `using (x);`, and the `using var x = f();` declaration whose body starts
- * `var` — never a directive; a statement's `;` may arrive inside its own
+ * Statement shapes hold no opinion at all, by two markers the text shows
+ * before any terminator arrives: a `(` right after the keyword is the
+ * parenthesized family — `using (var s = f()) { … }`, `using (x);` — and an
+ * `=` between the keyword and the walk's first `{` is the declaration family
+ * (#469) whenever MORE than one bare identifier precedes it — `var writer`,
+ * `Dictionary<string, int> map`, every declaration spelling — because a
+ * brace behind a resource's own `=` is that statement's initializer, while
+ * the first `{` behind a directive can only be the file's truncation. One
+ * bare identifier before the `=` is an ALIAS's own name (`using Pair = …`),
+ * the brace then belongs to whatever follows, and the truncated alias stays
+ * loud. A statement's `;` may arrive inside its own
  * block, so the scan has no opinion there. One silence the rule keeps: a
  * missing `;` that a LATER declaration supplies its own (`extern alias X`
  * then `namespace Shop.App;`) is not seen — the walk reads the next
@@ -324,11 +343,21 @@ export function csharpDirectiveMalformations(csharpText) {
     if (source[at] === "(") continue;
     const next = usingTerminatorAfter(at);
     if (next === undefined || next[0] === "{") {
-      flag(
-        m.index + m[0].indexOf("using"),
-        "using",
-        "a `using` directive never reaches its `;` — the file is truncated or malformed, so its imports cannot be read",
-      );
+      // The declaration family's initializer `=` (#469) — argued beside the
+      // openers above: an `=` whose prefix is more than one bare identifier
+      // is a resource's own, and the brace with it. One bare identifier is
+      // an alias's own name, the brace belongs to whatever follows, and the
+      // truncated alias stays loud.
+      const eq = next !== undefined ? source.indexOf("=", at) : -1;
+      const initializer =
+        eq !== -1 && eq < next.index && !ALIAS_NAME.test(source.slice(at, eq).trim());
+      if (next === undefined || !initializer) {
+        flag(
+          m.index + m[0].indexOf("using"),
+          "using",
+          "a `using` directive never reaches its `;` — the file is truncated or malformed, so its imports cannot be read",
+        );
+      }
     }
   }
   const externTerminatorAfter = terminatorAfter();

package/src/analysis/go.mjs

@@ -44,6 +44,13 @@
  * quote closed on a later line, a `)` supplied from a function body below —
  * produce a record today and stay the documented parse limits above.
  *
+ * One misread answers neither record nor failure, named as a limit rather
+ * than fixed (#468's neighbourhood): a bare `import` whose line ends with
+ * no path and whose `(` arrives from the statement BELOW it — `import`
+ * alone, then `const (` opening the next — is read as that block, and the
+ * doubly-broken file stays silent. Rejecting it needs a same-line rule
+ * that would flag the legal `import` newline `"path"` continuation.
+ *
  * ## An unreadable go.mod refuses, it does not skip (#405)
  *
  * `parseGoModulePath` parses content; it never sees a failed read. Reading a
@@ -310,7 +317,14 @@ export function goImportMalformations(goText) {
   // close just found rather than rescanning the text before it.
   let lastClose = 0;
   let unclosedSince = -1;
-  for (const m of source.matchAll(/(?:^|;)[ \t]*import/gm)) {
+  // `import` must be the keyword, never a prefix of an identifier (#468): a
+  // const member named `importPath` sits at line head exactly where the
+  // keyword would, and reading it as the keyword flagged a compiling file
+  // "an import states no path". Go lexes by maximal munch — letters, digits,
+  // and `_` continuing the word make it one identifier — so the lookahead
+  // excludes exactly those, and every legal follower (`(`, a quote, an
+  // alias, whitespace) still opens.
+  for (const m of source.matchAll(/(?:^|;)[ \t]*import(?![\p{L}\p{Nd}_])/gmu)) {
     let at = m.index + m[0].length;
     while (at < source.length && /\s/u.test(source[at])) at += 1;
     if (at >= source.length) {

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

package/src/commands/decisions.mjs

@@ -0,0 +1,291 @@
+/**
+ * The `decisions` command: the deterministic chain behind one recorded
+ * architecture decision — decision → the governed rows that stand on it
+ * (intent + constraint + fitness) → the projects they govern → the current
+ * evidence/findings, and the decision's verification level.
+ *
+ * It composes the wave-2 modules without owning any of them:
+ *
+ * - `../governance/adr-registry.mjs` — the read of `docs/adr/` and the
+ *   record index (`readAdrContext` below is this module's thin wrapper);
+ * - `../governance/decision-graph.mjs` — `forwardDecision`, the walk that
+ *   attaches governed rows, projects and evidence, and reports every hop it
+ *   cannot resolve in `walk.unresolved`;
+ * - `../governance/decision-fitness.mjs` — `computeDecisionFitness`, the
+ *   per-decision verification level;
+ * - `./provenance-command.mjs` — `intentRows`/`configRows`, the same row
+ *   walk `provenance` uses, so this command never holds a second copy of
+ *   which rows exist.
+ *
+ * It is descriptive, like `adr`/`report`: it never exits 1. The chain is a
+ * description of what is recorded and whether it is currently satisfied, not
+ * a finding. What it DOES refuse, loudly (exit 3, never clean):
+ *
+ * - an unreadable registry — a read that throws propagates to the caller;
+ * - a reference that does not resolve — either the positional `<id>` naming
+ *   no ADR record, or any hop of the walk (`walk.unresolved`), including a
+ *   binding that names no governed row. A chain that could not walk every hop
+ *   is rendered as an unresolved block, never as a clean chain (the
+ *   invariant, `../../../../AGENTS.md`).
+ *
+ * ## What the chain's Fitness leg verifies
+ *
+ * A decision's `bindings` name rule/fitness ids. This command walks the
+ * workspace's declared `fitness` list (like `report` does) and evaluates
+ * those functions against the same snapshot the `fitness` command builds, so
+ * a binding that names a declared gate derives its real verdict. A binding
+ * naming no declared gate derives `unverifiable` — the registry alone asserts
+ * nothing, never a clean pass. The whole derivation is deterministic: the
+ * same tree, the same law, the same chain.
+ */
+import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { formatDecisionChain } from "../report/decisions-text.mjs";
+import { readAdrContext } from "./adr.mjs";
+import { forwardDecision } from "../governance/decision-graph.mjs";
+import { computeDecisionFitness } from "../governance/decision-fitness.mjs";
+import { stripAdrPrefix, stripRuleFitnessPrefix } from "../governance/adr-registry.mjs";
+import { intentRows, configRows, rowLabel } from "./provenance-command.mjs";
+import { evaluateFitness, fitnessSnapshot } from "../governance/fitness-registry.mjs";
+import { hasTag, isComboDepConstraint } from "../rules/tags.mjs";
+import { resolveMembers } from "../architecture-intent/selectors.mjs";
+import { evaluate } from "../rules/index.mjs";
+
+/**
+ * The projects whose tags satisfy a constraint row's source selector — the
+ * same match `findConstraintsFor` (`../rules/tags.mjs`) makes, so the row's
+ * `governs` never disagrees with the row a rule actually applies to.
+ *
+ * @param {object} row A `depConstraints` row.
+ * @param {object} graph The project graph.
+ * @returns {string[]}
+ */
+function constraintGoverns(row, graph) {
+  return Object.entries(graph.nodes)
+    .filter(([, project]) =>
+      isComboDepConstraint(row)
+        ? row.allSourceTags.every((tag) => hasTag(project, tag))
+        : hasTag(project, row.sourceTag),
+    )
+    .map(([name]) => name)
+    .sort();
+}
+
+/**
+ * Resolves one intent side (`from`/`to`/`name`/`source`/`target`) to the
+ * projects it names: a declared boundary wins, else the side is an inline
+ * selector. Mirrors `sidePatterns` (`../architecture-intent/judge.mjs`).
+ *
+ * @param {object} intent The normalized intent model.
+ * @param {object} graph The project graph.
+ * @param {string} side A boundary name or inline selector.
+ * @returns {string[]}
+ */
+function sideProjects(intent, graph, side) {
+  const declared = (intent.boundaries ?? []).find((b) => b.name === side);
+  const patterns = declared ? declared.match : [side];
+  return resolveMembers(patterns, graph.nodes);
+}
+
+/**
+ * The projects one intent row governs, by row family — the "who does this
+ * row bind" answer. A row with no resolvable side governs nothing, which is
+ * itself a fact the walk reports (a governed project list is never assumed).
+ *
+ * @param {object} intent The normalized intent model.
+ * @param {object} graph The project graph.
+ * @param {object} row An intent row.
+ * @returns {string[]}
+ */
+function intentRowGoverns(intent, graph, row) {
+  if (typeof row.name === "string") return [row.name];
+  if (typeof row.from === "string") {
+    // `forbiddenTags` and the dependency rows claim the FROM side's edges;
+    // `allowed`/`forbidden` claim the boundary between both sides.
+    const from = sideProjects(intent, graph, row.from);
+    if (typeof row.to === "string") {
+      const to = sideProjects(intent, graph, row.to);
+      return Array.from(new Set([...from, ...to])).sort();
+    }
+    return from;
+  }
+  return [];
+}
+
+/**
+ * The verdicts of the workspace's declared fitness functions, folded into a
+ * `{name, verdict}` list — the same `{name, verdict}` shape `fitness` emits,
+ * so `computeDecisionFitness` can verify a decision's bound gates against
+ * this run's real judgements. Deterministic: same tree, same law, same list.
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {object} config The resolved boundary law.
+ * @param {object|null} intent The normalized intent model, or null when the
+ *   workspace declares none.
+ * @returns {object[]} `[{name, verdict}, ...]`.
+ */
+function fitnessVerdictsFor(commandContext, config, intent) {
+  if (!Array.isArray(config?.fitness) || config.fitness.length === 0) return [];
+  const snapshot = fitnessSnapshot(commandContext, {
+    intent,
+    suppressions: config.suppressions ?? [],
+  });
+  return evaluateFitness(config.fitness, snapshot).map((decision) => ({
+    name: decision.name,
+    verdict: decision.verdict,
+  }));
+}
+
+/**
+ * The verdict for one `decisions` run: the payload for both renderers, the
+ * status, and the coverage that decides exit 0 against 3.
+ *
+ * @param {string} decisionId The ADR id to walk (`NNN-slug` or `adr:NNN-slug`).
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {object} config The resolved boundary law.
+ * @param {{intent?: object|null, fitnessVerdicts?: object[]}} [io]
+ *   `intent` is the normalized intent model (or null); `fitnessVerdicts`
+ *   overrides the run's own evaluation — a test supplies a fixed list.
+ * @returns {{status: "ok"|"no-verdict", result: object, coverage: object,
+ *   report: {text: string, json: string}}}
+ * @throws {Error} on an unreadable registry, a malformed law, or a config
+ *   declaring fitness that fails to evaluate — exit-3 class.
+ */
+export function decisionsCommand(decisionId, commandContext, config, io = {}) {
+  const intent = io.intent ?? null;
+
+  // The registry read — throws on an unreadable `docs/adr/`, which the caller
+  // maps to exit 3. Never a clean result.
+  const { records, byId, knownFitness } = readAdrContext(commandContext.root, {
+    tracked: commandContext.tracked,
+  });
+
+  // The governed rows the walk attaches: intent rows and config constraint
+  // rows, each carrying the governance block and the projects it governs.
+  // `governs` is derived deterministically from the graph, so the walk never
+  // has to re-resolve a selector.
+  const rowsFromIntent = intent === null ? [] : intentRows(intent);
+  /** @type {import("../governance/decision-graph.mjs").GovernedRow[]} */
+  const rows = [
+    ...rowsFromIntent.map(
+      ({ kind, row }) =>
+        /** @type {import("../governance/decision-graph.mjs").GovernedRow} */ ({
+          id: rowLabel(kind, row),
+          kind: "intent",
+          decisionRef: row.decisionRef,
+          governs: intentRowGoverns(intent, commandContext.graph, row),
+        }),
+    ),
+    ...configRows(config).map(
+      ({ kind, row }) =>
+        /** @type {import("../governance/decision-graph.mjs").GovernedRow} */ ({
+          id: rowLabel(kind, row),
+          kind: "constraint",
+          decisionRef: row.decisionRef,
+          governs: constraintGoverns(row, commandContext.graph),
+        }),
+    ),
+    // The declared fitness gates themselves, keyed by their name — the same
+    // id space `declaredFitnessNames`/`stripRuleFitnessPrefix` use, so a
+    // decision binding `fitness:cycle-free` resolves to the gate that exists.
+    ...(Array.isArray(config?.fitness) ? config.fitness : []).map(
+      (gate) =>
+        /** @type {import("../governance/decision-graph.mjs").GovernedRow} */ ({
+          id: gate.name,
+          kind: "fitness",
+          governs: resolveMembers(gate.match ?? ["*"], commandContext.graph.nodes),
+        }),
+    ),
+  ];
+
+  // The evidence leg: findings for the projects the rows govern, built from
+  // the same evaluation `check` runs. A path-scoped or graph-less context
+  // would leave this lookup undefined and `attachRowLeg` reports it as an
+  // unresolved walk — never a quiet "no findings" claim.
+  const violations = evaluate(commandContext.analysis.imports, commandContext.graph, config);
+  const findingsByProject = new Map();
+  for (const violation of violations) {
+    const list = findingsByProject.get(violation.sourceProject) ?? [];
+    list.push({
+      id: `${violation.sourceFile}:${violation.line}:${violation.column}`,
+      project: violation.sourceProject,
+      ruleId: violation.messageId,
+    });
+    findingsByProject.set(violation.sourceProject, list);
+  }
+
+  const walk = forwardDecision(decisionId, {
+    records,
+    byId,
+    knownFitness,
+    rows,
+    findingsByProject: (project) => findingsByProject.get(project) ?? [],
+  });
+
+  // The per-decision fitness derivation, folded with THIS run's verdicts —
+  // the `{name, verdict}` list from the declared fitness gates above (or the
+  // caller's override). `computeDecisionFitness`'s second argument carries
+  // verdicts but is unused; the lookup is the single door, so it is null.
+  const verdicts = io.fitnessVerdicts ?? fitnessVerdictsFor(commandContext, config, intent);
+  const verdictByName = new Map(verdicts.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 record = byId.get(stripAdrPrefix(decisionId)) ?? null;
+  const result = {
+    decisionId,
+    record,
+    walk,
+    fitness: record === null ? undefined : fitnessById.get(record.id),
+    knownFitness: [...knownFitness].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
+  };
+
+  const unresolved = walk.unresolved;
+  const status = walk.ok ? "ok" : "no-verdict";
+  const exitCode = status === "ok" ? 0 : 3;
+
+  const coverage = {
+    complete: walk.ok,
+    projects: Object.keys(commandContext.graph?.nodes ?? {}).length,
+    analyzedFiles: commandContext.analysis?.analyzed ?? 0,
+    imports: (commandContext.analysis?.imports ?? []).length,
+    notAnalyzed: unresolved.map(({ ref, kind: ukind, reason }) => ({
+      file: ukind === "decision" ? `${ref}.md` : ref,
+      reason,
+    })),
+    blindSpots: [],
+    notes: [],
+  };
+
+  const envelope = jsonEnvelope({
+    command: "decisions",
+    context: {
+      root: commandContext.root,
+      provider: commandContext.provider ?? "native",
+      marker: "docs/adr",
+      provenance: null,
+    },
+    status,
+    exitCode,
+    coverage,
+    result,
+  });
+
+  const text = formatDecisionChain({
+    decisionId,
+    record,
+    walk,
+    fitness: result.fitness,
+  });
+
+  return {
+    status,
+    result,
+    coverage,
+    report: {
+      text: `${text}\n`,
+      json: renderJson(envelope),
+    },
+  };
+}