@ecoma-io/archkeep 0.25.0 → 0.27.0

package/cli.mjs

@@ -55,8 +55,10 @@
  *      classifies as introduced, or a change-intent reconciliation that found
  *      undeclared material changes, unfulfilled declarations, or a failed
  *      declared constraint. `check`, `fitness`, `delta` and `change` are the
- *      verbs whose verdicts carry this code — every other verb in this table
- *      only ever reads.
+ *      verbs whose verdicts carry this code, plus `rules verify` — the
+ *      artifact-integrity fold, a bounded verification surface, not a fifth
+ *      architecture carrier (`docs/reference/exit-codes.md` owns the
+ *      roster). Every other verb only ever reads.
  *   2  usage error — unknown command, unknown flag, missing argument, path
  *      outside the tree
  *   3  no verdict — no workspace, malformed config, the graph provider or git
@@ -92,7 +94,7 @@
  * only once a later command needs something this table cannot express.
  */
 import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { createRequire } from "node:module";
 
 const require = createRequire(import.meta.url);
@@ -101,59 +103,70 @@ const { name: TOOL_NAME, version: TOOL_VERSION } = require("./package.json");
 
 import { containmentViolation } from "./src/containment.mjs";
 import { UsageError } from "./src/errors.mjs";
-import { check, sortViolations } from "./src/commands/check.mjs";
-import { resolveDescribedPolicy, resolvePolicy } from "./src/commands/policy.mjs";
+// Verb imports route through the capability facades: each
+// `<word>-capability.mjs` module is its word's explicit verb roster — pure
+// re-exports, zero judgment. The vocabulary's roster lives in
+// docs/concepts/architecture.md's "The 24 commands".
+// Non-verb helper modules keep their direct imports.
 import {
-  DEFAULT_OPTIONS,
-  WORKSPACE_MARKERS,
-  markersAt,
-  resolveCommandContext,
-} from "./src/commands/context.mjs";
-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, proposalToIntent } from "./src/commands/discover.mjs";
-import { driftCommand } from "./src/commands/drift.mjs";
-import { fitnessCommand } from "./src/commands/fitness.mjs";
-import { reconcileCommand } from "./src/commands/reconcile.mjs";
-import { changeCommand } from "./src/commands/change.mjs";
-import { computePolicyFingerprint, graphCommand } from "./src/commands/graph.mjs";
-import { historyCommand } from "./src/commands/history.mjs";
-import { trajectoryCommand } from "./src/commands/trajectory.mjs";
-import { evolutionCommand } from "./src/commands/evolution.mjs";
-import { healthCommand } from "./src/commands/health.mjs";
-import { reportCommand } from "./src/commands/report.mjs";
-import { debtCommand } from "./src/commands/debt.mjs";
-import { explainCommand } from "./src/commands/explain.mjs";
-import { impactCommand } from "./src/commands/impact.mjs";
-import { scenarioCommand } from "./src/commands/scenario.mjs";
-import { provenanceCommand } from "./src/commands/provenance-command.mjs";
+  discoverCommand,
+  intentJsonFromProposal,
+  intentWriteRefusal,
+} from "./src/commands/analyze-capability.mjs";
+import { check, fitness, scenario, sortViolations } from "./src/commands/check-capability.mjs";
+import {
+  captureBaseline,
+  change,
+  changeOutputRefusal,
+  delta,
+  diff,
+  drift,
+  evolutionCommand,
+  history,
+  historyOutputRefusal,
+  reconcileCommand,
+  trajectoryCommand,
+  trajectoryOutputRefusal,
+} from "./src/commands/compare-capability.mjs";
+import { explain } from "./src/commands/explain-capability.mjs";
+import { context, graph, health, impact, planContext } from "./src/commands/inspect-capability.mjs";
+import {
+  debt,
+  decisions,
+  provenanceCommand,
+  report,
+  waivers,
+} from "./src/commands/govern-capability.mjs";
 import {
   rulesAddCommand,
   rulesInfoCommand,
   rulesListCommand,
   rulesVerifyCommand,
-} from "./src/commands/rules.mjs";
-import { waiversCommand } from "./src/commands/waivers.mjs";
-import { INTENT_FILE, loadIntent } from "./src/architecture-intent/model.mjs";
+} from "./src/commands/rules-capability.mjs";
+import { nativePolicyOptions } from "./src/commands/policy.mjs";
+import {
+  DEFAULT_OPTIONS,
+  WORKSPACE_MARKERS,
+  markersAt,
+  resolveCommandContext,
+} from "./src/commands/context.mjs";
+import { adrForWorkspace } from "./src/commands/adr-for-workspace.mjs";
+import { INTENT_FILE } from "./src/architecture-intent/model.mjs";
 import { isProgramEntry } from "./src/entry-point.mjs";
-import { readPluginOptions } from "./src/options.mjs";
-import { EXIT, verdictFor } from "./src/verdict.mjs";
+import { ARCHKEEP_MODEL_FILE, readPluginOptions } from "./src/options.mjs";
+import { EXIT } from "./src/verdict.mjs";
 
-import { ARCHKEEP_MODEL_FILE, loadNativeModel } from "./src/providers/native/model.mjs";
-import { findWorkspaceRoot, listTrackedFiles } from "./src/workspace.mjs";
+import { findWorkspaceRoot } from "./src/workspace.mjs";
 
 /**
  * Workspace-relative read from `root`, the same default `createWorkspace`
  * builds when no reader is injected (`./src/workspace.mjs`) — duplicated
  * rather than imported for the reason `./src/commands/context.mjs` carries its
  * own copy of the same helper: `optionsForUsage` below needs one BEFORE any
- * `Workspace` exists, to hand `loadNativeModel` a reader for `archkeep.json`
- * itself. `check` no longer needs a copy of its own — `resolveCommandContext`
- * owns that read now — which is why this is the only one left in this file.
+ * `Workspace` exists, to hand `nativePolicyOptions` a reader for
+ * `archkeep.json` itself. `check` no longer needs a copy of its own —
+ * `resolveCommandContext` owns that read now — which is why this is the only
+ * one left in this file.
  *
  * @param {string} root
  * @returns {(path: string) => string|null}
@@ -338,20 +351,7 @@ function optionsForUsage(cwd) {
     if (root === null) return DEFAULT_OPTIONS;
     const { hasNx, hasNative } = markersAt(root);
     if (hasNative && !hasNx) {
-      const model = loadNativeModel(root, { readFile: readWorkspaceRoot(root) });
-      // An inline policy object has no filename to print — `${boundaryConfig}`
-      // below would otherwise coerce it to the literal text "[object Object]",
-      // which reads as a real (and wrong) filename rather than as the "there
-      // is no file" it actually means. `inline: true` is what tells `usage()`
-      // to print the paragraph that says so, instead of the one describing a
-      // named file.
-      return typeof model.boundaryConfig === "string"
-        ? { boundaryConfig: model.boundaryConfig, tsConfig: model.tsConfig }
-        : {
-            boundaryConfig: "an inline policy in archkeep.json",
-            tsConfig: model.tsConfig,
-            inline: true,
-          };
+      return nativePolicyOptions(root, { readFile: readWorkspaceRoot(root) });
     }
     return readPluginOptions(root);
   } catch {
@@ -771,9 +771,9 @@ async function runCheck(options, { cwd, env }) {
         (result.intentFindings > 0
           ? `, ${result.intentFindings} architecture-intent finding${result.intentFindings === 1 ? "" : "s"}`
           : "") +
-        // Fitness drives the exit code exactly like every count above it
-        // (`verdictFor`) — omitting it here is what let a fitness-only
-        // failure log "0 violations …" beside a non-zero exit.
+        // Fitness drives the exit code exactly like every count above it —
+        // omitting it here is what let a fitness-only failure log "0
+        // violations …" beside a non-zero exit.
         (result.fitnessFail > 0
           ? `, ${result.fitnessFail} fitness function${result.fitnessFail === 1 ? "" : "s"} failed`
           : "") +
@@ -781,9 +781,9 @@ async function runCheck(options, { cwd, env }) {
           ? `, ${result.fitnessUnknown} fitness function${result.fitnessUnknown === 1 ? "" : "s"} undetermined`
           : "") +
         // Custom rules drive the exit code exactly like every count above
-        // them (`verdictFor`), so they are named here for the same reason
-        // fitness is: a custom-rule-only failure would otherwise log
-        // "0 violations …" beside a non-zero exit.
+        // them, so they are named here for the same reason fitness is: a
+        // custom-rule-only failure would otherwise log "0 violations …"
+        // beside a non-zero exit.
         (result.customRuleFail > 0
           ? `, ${result.customRuleFail} custom rule${result.customRuleFail === 1 ? "" : "s"} failed`
           : "") +
@@ -799,7 +799,11 @@ async function runCheck(options, { cwd, env }) {
     env.out(result.report);
   }
 
-  return verdictFor(result).exitCode;
+  // `check`'s own verdict rides its return (`./src/commands/check.mjs`): the
+  // command computes the one exit authority, and the process returns it
+  // unmodified — a second fold here would be a second chance for the printed
+  // verdict and the process exit to disagree.
+  return result.exitCode;
 }
 
 /**
@@ -818,32 +822,7 @@ async function runGraph(options, { cwd, env }) {
 
   let result;
   try {
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-
-    // Load the boundary config so the snapshot carries a policy fingerprint
-    // that `diff` can use to warn when the policy changed between runs. Without
-    // a config, the snapshot carries no policy identity — the consumer did not
-    // provide one (`./src/commands/graph.mjs` makes that field conditional). A
-    // profile-selected workspace's `boundaryConfig` names a profile rather than
-    // a file, resolved the same way `check` resolves it (`resolvePolicy`), so
-    // the fingerprint moves with a profile edit the same way it already does
-    // with a file or inline-object edit.
-    //
-    // `graph` describes the project graph, not the boundary law — it reads no
-    // constraint row and judges nothing against one — so a workspace that has
-    // not written a law yet must not be refused here. Every arm of that
-    // decision — what is skipped is the load of a file that is NOT THERE, the
-    // `boundaryConfigDeclared` bit that keeps the guard to the un-overridden
-    // default, and why a law someone named and then deleted stays loud — lives
-    // in `resolveDescribedPolicy` (`./src/commands/policy.mjs`) rather than
-    // here, so the descriptive commands and the MCP face that serves them
-    // cannot disagree about what "no law declared" means.
-    const { config } = await resolveDescribedPolicy(options, commandContext, cwd);
-
-    result = graphCommand(commandContext, { config });
+    result = await graph(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -890,26 +869,9 @@ async function runDiff(options, { cwd, env }) {
     return EXIT.usage;
   }
 
-  const baselinePath = isAbsolute(options.paths[0])
-    ? options.paths[0]
-    : resolve(cwd, options.paths[0]);
-
   let result;
   try {
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-
-    // Load the boundary config when --config is given or when the workspace
-    // declares one, so rule-impact analysis is computed. Without a config,
-    // the diff reports only structural changes — same as before. A
-    // profile-selected workspace resolves the same way `check` does
-    // (`resolvePolicy`), so a policy edit under an unchanged profile NAME is
-    // still visible as a fingerprint change here.
-    const { config } = await resolvePolicy(options, commandContext, cwd);
-
-    result = diffCommand(baselinePath, commandContext, { config });
+    result = await diff(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -974,18 +936,12 @@ async function runDelta(options, { cwd, env }) {
 
   let result;
   try {
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-
-    // Both modes need the boundary law: capture fingerprints it, compare
-    // re-judges both sides under it — the same ladder every judging command
-    // resolves through (`resolvePolicy`).
-    const { config } = await resolvePolicy(options, commandContext, cwd);
-
     if (options.capture) {
-      const { text } = captureDelta(commandContext, { config });
+      const { text } = await captureBaseline(options, {
+        cwd,
+        readGraph: env.readGraph,
+        listFiles: env.listFiles,
+      });
       if (options.output) {
         // Atomic, symlink-safe write — `writeOutputReport`'s own docstring
         if (!writeOutputReport(options.output, text, env, cwd, options.config)) return EXIT.error;
@@ -997,13 +953,7 @@ async function runDelta(options, { cwd, env }) {
       return EXIT.ok;
     }
 
-    const baselinePath = isAbsolute(options.paths[0])
-      ? resolve(options.paths[0])
-      : resolve(cwd, options.paths[0]);
-    result = await deltaCommand(baselinePath, commandContext, {
-      config,
-      eventOut: options.eventOut,
-    });
+    result = await delta(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -1053,13 +1003,10 @@ async function runDelta(options, { cwd, env }) {
     );
   }
 
-  // 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.
-  return (
-    { ok: EXIT.ok, findings: EXIT.violations, "no-verdict": EXIT.error }[result.status] ??
-    EXIT.error
-  );
+  // The exit `deltaCommand` computed: a non-waived introduced violation is a
+  // finding, an unclassifiable item is a no-verdict, anything else is clean —
+  // the command's return carries the pair, the process returns it as is.
+  return result.exitCode;
 }
 
 /**
@@ -1081,36 +1028,7 @@ async function runDrift(options, { cwd, env }) {
 
   let result;
   try {
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-    // The loaded policy — profile-aware the same way `check` is
-    // (`resolvePolicy`), `null` when the workspace declares none. Drift reads
-    // the intent's rows, and the fitness half of a row's `decisionRef`
-    // resolves against the ids THIS policy declares (F04), so the same policy
-    // that made the boundary law answerable to the model must answer here.
-    // `drift` has no `--config` (`DRIFT_FLAG_HELP`), so `config` is always the
-    // workspace's own default — resolvePolicy reads `options.config` as the
-    // override, hence `null` here, which selects the workspace's configured
-    // boundary law (or a profile, when one is registered).
-    //
-    // The failure is DEFERRED rather than thrown here. `drift`'s only reader of
-    // this policy is the non-verdict decisionRef axis, and only for rows that
-    // carry one, so a workspace with an intent and no boundary config was
-    // exiting 3 over a law drift would never have opened — a fifth refusal
-    // neither `docs/usage/drift.md` nor `reconcile`, which makes the same four,
-    // ever had. `driftCommand` rethrows it, unchanged, at the one site that
-    // reads the policy, so every workspace whose intent cites anything keeps the
-    // exact exit-3 it had.
-    let config = null;
-    let configError = null;
-    try {
-      ({ config } = await resolvePolicy({ ...options, config: null }, commandContext, cwd));
-    } catch (error) {
-      configError = /** @type {Error} */ (error);
-    }
-    result = await driftCommand(commandContext, { config, configError });
+    result = await drift(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -1154,7 +1072,9 @@ async function runDrift(options, { cwd, env }) {
  * Provenance reads no graph and judges nothing — it describes where the run's
  * facts came from and which governance rows carry an origin. It is
  * fail-closed the way every descriptive command is: a malformed intent or
- * boundary config throws out of `provenanceCommand` → exit 3, so "rows
+ * boundary config throws out of `provenanceCommand` → exit 3, and so does
+ * a law the shared ladder refuses (`./src/commands/policy.mjs` — e.g. a
+ * `coverage` key in a native workspace's `boundaryConfig` file), so "rows
  * unlisted" never reads as "rows attested".
  *
  * @param {{format: string, output: string|null, paths: string[]}} options
@@ -1293,55 +1213,15 @@ async function runChange(options, { cwd, env }) {
     return EXIT.usage;
   }
 
-  const baselinePath = isAbsolute(options.paths[0])
-    ? options.paths[0]
-    : resolve(cwd, options.paths[0]);
-  const intentPath = isAbsolute(options.intent) ? options.intent : resolve(cwd, options.intent);
-
-  // A self-footgun guard, the same shape `history`'s holds: writing the
-  // reconciliation report over the very manifest this run just read would
-  // destroy the declaration it verified, with the loss surfacing only later —
-  // the first time someone tries to re-run the verification.
-  if (options.output) {
-    const outputAbs = isAbsolute(options.output)
-      ? resolve(options.output)
-      : resolve(cwd, options.output);
-    if (outputAbs === intentPath) {
-      env.err(
-        `archkeep: --output '${options.output}' resolves to the change-intent manifest itself — ` +
-          `overwriting the declaration with its own reconciliation report would destroy it. ` +
-          `Write the report somewhere else.`,
-      );
-      return EXIT.usage;
-    }
+  const refusal = changeOutputRefusal(options, cwd);
+  if (refusal) {
+    env.err(refusal);
+    return EXIT.usage;
   }
 
   let result;
   try {
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-
-    // Declared constraints are judged under whichever law THIS run resolves,
-    // and the envelope records that law's fingerprint beside the baseline's —
-    // the same loading every judging command does (`resolvePolicy`),
-    // profile-aware the same way `check` is.
-    const { config } = await resolvePolicy(options, commandContext, cwd);
-
-    // `--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 }),
-    });
+    result = await change(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -1371,12 +1251,9 @@ async function runChange(options, { cwd, env }) {
     env.out(report);
   }
 
-  // The verdict fold `changeCommand` computed, mapped here the way `delta`'s
-  // and `fitness`' are.
-  return (
-    { ok: EXIT.ok, findings: EXIT.violations, "no-verdict": EXIT.error }[result.status] ??
-    EXIT.error
-  );
+  // The verdict fold `changeCommand` computed, returned as the command
+  // carries it.
+  return result.exitCode;
 }
 
 /**
@@ -1400,25 +1277,7 @@ async function runWaivers(options, { cwd, env }) {
 
   let result;
   try {
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-
-    // The waivers surface is part of the run's boundary law, so the law is
-    // loaded the same way `check` loads it (`resolvePolicy`) and `--config`
-    // wins the same way — resolved against the working directory, never
-    // against this tool's own location, and a `profiles` registry resolves
-    // `--config`/`boundaryConfig` as a profile NAME the same way `check`
-    // does. A malformed law throws here, exit 3, exactly as in `check`.
-    const { config, source } = await resolvePolicy(options, commandContext, cwd);
-
-    // `source` rides along for one job: `waiversCommand` subtracts the law's
-    // own file from the unowned-file set the `coverage.unowned` acceptances
-    // are matched against, exactly as `check` does — the law is not source
-    // judged by the law (`../src/commands/context.mjs`'s
-    // `unownedGapWithoutRunConfiguration`).
-    result = await waiversCommand(commandContext, config, { policySource: source });
+    result = await waivers(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -1471,8 +1330,9 @@ async function runWaivers(options, { cwd, env }) {
  * sits at the tail of this function, and `../src/commands/fitness.mjs` states
  * the posture — a failing fitness function is a finding, not a print job
  * (D-09). `check` folds the same `fail` into its own exit 1 by presence, so the
- * two faces agree; `check` and `fitness` are the only verbs whose verdict
- * carries that code.
+ * two faces agree; the verbs whose verdict carries that code are `check`,
+ * `fitness`, `delta` and `change`, plus the `rules verify` artifact-integrity
+ * fold (`docs/reference/exit-codes.md` owns the roster).
  *
  * @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
@@ -1486,24 +1346,7 @@ async function runFitness(options, { cwd, env }) {
 
   let result;
   try {
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-
-    // Fitness is part of the run's boundary law, so the law is loaded the same
-    // way `check` loads it (`resolvePolicy`) and `--config` wins the same
-    // way — resolved against the working directory, never against this
-    // tool's own location, profile-aware the same way `check` is. A malformed
-    // law throws here, exit 3, exactly as in `check`. A profile's `block` may
-    // carry a `fitness` key (`docs/concepts/profiles.md` now names four
-    // block keys, fitness among them), so a profile-selected workspace folds
-    // the declared functions the same way a file-selected one does — a
-    // profile that declares none reaches `fitnessCommand`'s own "declares no
-    // fitness functions" refusal below rather than a config-loading failure.
-    const { config } = await resolvePolicy(options, commandContext, cwd);
-
-    result = await fitnessCommand(commandContext, { config });
+    result = await fitness(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -1532,13 +1375,10 @@ async function runFitness(options, { cwd, env }) {
   }
 
   // `fitness` is a verdict, not a print job (D-09): `fail` exits 1, `unknown`
-  // exits 3, and a run that completed with everything `pass` (or not
-  // applicable) exits 0. The command's own status carries the pair, and the
-  // JSON envelope asserts it; this mapping is the one process-level exit.
-  return (
-    { ok: EXIT.ok, findings: EXIT.violations, "no-verdict": EXIT.error }[result.status] ??
-    EXIT.error
-  );
+  // exits 3, a run whose every function is `pass` (or not applicable) exits 0.
+  // The command's return carries the pair the envelope asserts; this return
+  // is that verdict, unmodified.
+  return result.exitCode;
 }
 
 /**
@@ -1564,17 +1404,11 @@ async function runImpact(options, { cwd, env }) {
 
   let result;
   try {
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-
-    // Load the boundary config when --config is given or when the workspace
-    // declares one, so constraint-impact analysis is computed — profile-aware
-    // the same way `check` is (`resolvePolicy`).
-    const { config } = await resolvePolicy(options, commandContext, cwd);
-
-    result = impactCommand(projectName, commandContext, config);
+    result = await impact(projectName, options, {
+      cwd,
+      readGraph: env.readGraph,
+      listFiles: env.listFiles,
+    });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -1647,14 +1481,11 @@ async function runScenario(options, { cwd, env }) {
 
   let result;
   try {
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-
-    const { config } = await resolvePolicy(options, commandContext, cwd);
-
-    result = scenarioCommand(projectName, scenarioJson, commandContext, config);
+    result = await scenario(projectName, scenarioJson, options, {
+      cwd,
+      readGraph: env.readGraph,
+      listFiles: env.listFiles,
+    });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -1702,22 +1533,9 @@ async function runExplain(options, { cwd, env }) {
     return EXIT.usage;
   }
 
-  const site = options.paths[0];
-
   let result;
   try {
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-
-    // The config's location is a separate fact from the workspace root.
-    // Same loading logic as `check` (`resolvePolicy`) — a `--config`
-    // overrides the workspace's own `boundaryConfig`, profile-aware the same
-    // way `check` is.
-    const { config } = await resolvePolicy(options, commandContext, cwd);
-
-    result = explainCommand(site, commandContext, config);
+    result = await explain(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -1768,36 +1586,11 @@ async function runContextCommand(options, { cwd, env }) {
     return EXIT.usage;
   }
 
-  const projectName = options.paths[0];
-  const scopePaths = options.plan ? options.paths.slice(1) : [];
-
   let result;
   try {
-    // The command context is resolved over the WHOLE workspace. Scoping by
-    // path is the plan command's decision (which projects the change touches),
-    // not the preamble's: the rule verdict and the architecture snapshot must
-    // be over the whole tree, and only reporting is narrowed. Passing no paths
-    // here keeps the non-plan `context` path byte-for-byte identical to before.
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-
-    // The config's location is a separate fact from the workspace root.
-    // Same loading logic as `check` and `explain` (`resolvePolicy`) — a
-    // `--config` overrides the workspace's own `boundaryConfig`,
-    // 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, historyDir)
-      : contextCommand(projectName, commandContext, config);
+      ? await planContext(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles })
+      : await context(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -1824,22 +1617,26 @@ async function runContextCommand(options, { cwd, env }) {
  * `adr`'s `run`: reads the ADR registry at the workspace root and renders it.
  *
  * The registry lives in `docs/adr/` in the tree being described, not in this
- * package's own tree, so the root comes from the current working directory —
- * the same walking `resolveCommandContext` does, but without the whole
- * project-graph preamble. `adr` never exits 1: a description of what is
- * recorded is never a finding. An unreadable registry (a malformed record, an
- * unreadable file, a bad filename) throws → exit 3; an id the user asked
- * about that the registry does not know → exit 3, the invariant.
- *
- * The tracked-file list is read the same way every other command reads it —
- * `env.listFiles ?? listTrackedFiles`, so a test can inject a fake the same
- * way `runCheck` and its siblings do — and handed to `adrCommand` so the
- * registry resolves only git-tracked records (`src/governance/adr-registry.mjs`'s
+ * package's own tree, and the preamble it needs — the root walked up from
+ * `cwd`, the tracked file list — is the one `adrForWorkspace`
+ * (`./src/commands/adr-for-workspace.mjs`) composes, the same composition
+ * the MCP history adapter runs. This driver decides none of it: it words the
+ * no-workspace refusal (`adrForWorkspace` returns the `null` and holds no
+ * message of its own) and maps the command's throws. `adr` never exits 1: a
+ * description of what is recorded is never a finding. An unreadable registry
+ * (a malformed record, an unreadable file, a bad filename) throws → exit 3;
+ * an id the user asked about that the registry does not know → exit 3, the
+ * invariant.
+ *
+ * The tracked-file list is injected the way every other command's is —
+ * `env.listFiles`, so a test can drive the read over a fixture tree with no
+ * git — and reaches `adrCommand` through the driver, so the registry
+ * resolves only git-tracked records (`src/governance/adr-registry.mjs`'s
  * header). A `git ls-files` failure here throws the same as any other
  * unreadable registry, mapped to exit 3 below.
  *
  * @param {{format: string, output: string|null, paths: string[]}} options
- * @param {{cwd: string, env: {out: Function, err: Function, listFiles?: typeof listTrackedFiles}}} runContext
+ * @param {{cwd: string, env: {out: Function, err: Function, listFiles?: Function}}} runContext
  * @returns {Promise<number>}
  */
 async function runAdr(options, { cwd, env }) {
@@ -1851,23 +1648,20 @@ async function runAdr(options, { cwd, env }) {
     return EXIT.usage;
   }
 
-  const root = resolveWorkspaceRootForUsage(cwd);
-  if (root === null) {
-    env.err(
-      `archkeep: adr needs a workspace root — no nx.json, archkeep.json, or ` +
-        `.moon/workspace.yml marker found walking up from ${cwd}`,
-    );
-    return EXIT.error;
-  }
-
   let result;
   try {
-    const tracked = (env.listFiles ?? listTrackedFiles)(root);
-    result = adrCommand(root, { id: options.paths[0] }, { tracked });
+    result = adrForWorkspace({ cwd }, { id: options.paths[0] }, { listFiles: env.listFiles });
   } catch (error) {
     env.err(String(error?.message ?? error));
     return EXIT.error;
   }
+  if (result === null) {
+    env.err(
+      `archkeep: adr needs a workspace root — no nx.json, archkeep.json, or ` +
+        `.moon/workspace.yml marker found walking up from ${cwd}`,
+    );
+    return EXIT.error;
+  }
 
   const report = options.format === "json" ? result.report.json : result.report.text;
 
@@ -1913,20 +1707,7 @@ async function runDecisions(options, { cwd, env }) {
 
   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 });
+    result = await decisions(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -2014,7 +1795,12 @@ async function runRules(options, { cwd, env }) {
     env.out(report);
   }
 
-  // Exit codes: 0 for ok, 1 for findings (verify only), 3 for no-verdict
+  // Exit codes: `verify`'s return carries the pair its status asserts (0 ok,
+  // 1 findings, 3 could-not-look). The descriptive subcommands (`list`,
+  // `info`, `add`) expose no exit field — their statuses are `ok` or a
+  // no-verdict class only, never findings — so this ladder keeps their exits
+  // exactly as they were.
+  if (subcommand === "verify") return result.exitCode;
   if (result.status === "ok") return EXIT.ok;
   if (result.status === "findings") return EXIT.violations;
   return EXIT.error;
@@ -2040,56 +1826,15 @@ async function runHistory(options, { cwd, env }) {
     return EXIT.usage;
   }
 
-  const dir = isAbsolute(options.paths[0])
-    ? resolve(options.paths[0])
-    : resolve(cwd, options.paths[0]);
-
-  // A self-footgun guard: writing the history report back into the very
-  // directory `history` reads would poison every later run (the report envelope
-  // is a `history` envelope, which `parseBaseline` refuses as a non-`graph`
-  // snapshot). Refuse loudly instead of eventually failing on a poisoned dir.
-  if (options.output) {
-    // `resolve()` on the absolute branch too — not just the raw path — the
-    // same normalization `writeOutputReport` applies, so an absolute
-    // `--output` carrying a `..` segment that resolves INTO the history
-    // directory cannot slip past this guard unnormalized.
-    const outputAbs = isAbsolute(options.output)
-      ? resolve(options.output)
-      : resolve(cwd, options.output);
-    if (dirname(outputAbs) === dir) {
-      env.err(
-        `archkeep: --output '${options.output}' is inside the history directory '${dir}' — ` +
-          `writing the report there would be read back as a snapshot on the next run. ` +
-          `Write it somewhere else.`,
-      );
-      return EXIT.usage;
-    }
+  const refusal = historyOutputRefusal(options, cwd);
+  if (refusal) {
+    env.err(refusal);
+    return EXIT.usage;
   }
 
   let result;
   try {
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-
-    // The boundary law's fingerprint when the workspace declares one, so a
-    // captured snapshot records the policy it was taken under — the same
-    // config loading `graph` uses (`resolvePolicy`, profile-aware the same
-    // way `check` is), kept in one place so a capture and a standalone
-    // `graph` never disagree about the current policy.
-    let fingerprint = null;
-    if (options.capture) {
-      const { config } = await resolvePolicy(options, commandContext, cwd);
-      if (config) {
-        fingerprint = computePolicyFingerprint(config);
-      }
-    }
-
-    result = historyCommand(dir, commandContext, {
-      capture: options.capture,
-      policyFingerprint: fingerprint,
-    });
+    result = await history(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -2139,22 +1884,10 @@ async function runTrajectory(options, { cwd, env }) {
     ? resolve(options.paths[0])
     : resolve(cwd, options.paths[0]);
 
-  // The same self-footgun guard `runHistory` applies: a report written into
-  // the directory being read would be read back as a snapshot on the next run
-  // (the envelope is not a `graph` snapshot, which `parseBaseline` refuses) —
-  // poison the record loudly refused rather than quietly planted.
-  if (options.output) {
-    const outputAbs = isAbsolute(options.output)
-      ? resolve(options.output)
-      : resolve(cwd, options.output);
-    if (dirname(outputAbs) === dir) {
-      env.err(
-        `archkeep: --output '${options.output}' is inside the history directory '${dir}' — ` +
-          `writing the report there would be read back as a snapshot on the next run. ` +
-          `Write it somewhere else.`,
-      );
-      return EXIT.usage;
-    }
+  const refusal = trajectoryOutputRefusal(options, cwd);
+  if (refusal) {
+    env.err(refusal);
+    return EXIT.usage;
   }
 
   let result;
@@ -2293,25 +2026,9 @@ async function runDebt(options, { cwd, env }) {
     return EXIT.usage;
   }
 
-  const dir = isAbsolute(options.paths[0]) ? options.paths[0] : resolve(cwd, options.paths[0]);
-
   let result;
   try {
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-
-    // The boundary law the ledger ages waivers against — resolved the same way
-    // `graph` and `diff` resolve it (`resolvePolicy`), so a `debt` run and a
-    // `check` run never disagree about the current suppressions, and a
-    // profile-selected workspace resolves the same way `check` does.
-    const { config } = await resolvePolicy(options, commandContext, cwd);
-
-    result = await debtCommand(dir, commandContext, {
-      config,
-      events: options.events,
-    });
+    result = await debt(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -2402,22 +2119,17 @@ async function runDiscover(options, { cwd, env }) {
   }
 
   if (options.writeIntent) {
-    // The one write that can turn a proposal into the law `check` gates on,
-    // so it refuses to replace: a file already at the target is a law (or a
-    // candidate someone holds), and silently overwriting it with a proposal
-    // is the adoption this command must never perform by itself. Move or
-    // delete the file first — a step a human reviews.
-    if (existsSync(options.writeIntent)) {
-      env.err(
-        `archkeep: ${options.writeIntent} already exists, and a proposal must never ` +
-          `silently replace what is there. Move or delete the file first, then run this again.`,
-      );
+    // The one write that can turn a proposal into the law `check` gates on —
+    // the refusal DECISION is discover's own (`intentWriteRefusal`, beside the
+    // proposal it protects, the way `historyOutputRefusal` sits with history);
+    // this driver keeps the mechanics only.
+    const intentRefusal = intentWriteRefusal(options.writeIntent, { exists: existsSync });
+    if (intentRefusal) {
+      env.err(intentRefusal);
       return EXIT.error;
     }
     try {
-      const intentJson = JSON.stringify(proposalToIntent(result.proposal), null, 2) + "\n";
-      // `wx` refuses the file materializing between the check above and this
-      // write, so the refusal above cannot be raced past.
+      const intentJson = intentJsonFromProposal(result.proposal);
       writeFileSync(options.writeIntent, intentJson, { encoding: "utf-8", flag: "wx" });
       env.err(`archkeep: proposed architecture written to ${options.writeIntent}`);
       env.err(
@@ -2434,8 +2146,6 @@ async function runDiscover(options, { cwd, env }) {
 }
 
 /**
- * `health`'s `run`: resolves the command context, drives `healthCommand`,
- * writes the report where it belongs, and returns the process's exit code.
  * `health`'s `run`: resolves the command context, drives `healthCommand`,
  * writes the report where it belongs, and returns the process's exit code.
  *
@@ -2456,31 +2166,9 @@ async function runHealth(options, { cwd, env }) {
     return EXIT.usage;
   }
 
-  const trendDir =
-    options.paths.length === 1
-      ? isAbsolute(options.paths[0])
-        ? options.paths[0]
-        : resolve(cwd, options.paths[0])
-      : null;
-
   let result;
   try {
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-
-    // The boundary law and the intent, the same loading every command does
-    // (`resolvePolicy`) — a `--config` overrides the workspace's own
-    // `boundaryConfig`, profile-aware the same way `check` is, and the
-    // intent is the tracked root `architecture-intent.json` (or absent).
-    const { config } = await resolvePolicy(options, commandContext, cwd);
-
-    const intent = commandContext.tracked.includes(INTENT_FILE)
-      ? await loadIntent(commandContext.root, { tracked: commandContext.tracked })
-      : null;
-
-    result = healthCommand(commandContext, { config, intent, trendDir });
+    result = await health(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -2528,47 +2216,20 @@ async function runReport(options, { cwd, env }) {
     return EXIT.usage;
   }
 
-  const trendDir =
-    options.paths.length === 1
-      ? isAbsolute(options.paths[0])
-        ? options.paths[0]
-        : resolve(cwd, options.paths[0])
-      : null;
-
   let result;
   try {
-    const commandContext = resolveCommandContext(
-      { cwd },
-      { readGraph: env.readGraph, listFiles: env.listFiles },
-    );
-
-    // ONE law for the whole document — resolved exactly the way `check` and
-    // `health` resolve theirs, and handed to every surface the report
-    // composes, so no two sections can cite different laws.
-    const { config, source } = await resolvePolicy(options, commandContext, cwd);
-
-    const intent = commandContext.tracked.includes(INTENT_FILE)
-      ? await loadIntent(commandContext.root, { tracked: commandContext.tracked })
-      : null;
-
-    result = await reportCommand(commandContext, {
-      config,
-      intent,
-      trendDir,
-      policySource: source,
-    });
+    result = await report(options, { cwd, readGraph: env.readGraph, listFiles: env.listFiles });
   } 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;
+  const rendered = 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`;
+    const reportText = rendered.endsWith("\n") ? rendered : `${rendered}\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 document for an established
@@ -2581,7 +2242,7 @@ async function runReport(options, { cwd, env }) {
         : `NO VERDICT — ${gaps} surface${gaps === 1 ? "" : "s"} could not be inspected`;
     env.err(`archkeep: report complete (${verdict}) → ${options.output}`);
   } else {
-    env.out(report);
+    env.out(rendered);
   }
 
   // Descriptive: 0 when every surface reached a verdict, 3 when any evidence