@ecoma-io/archkeep 0.24.1 → 0.26.0

package/src/commands/evolution.mjs

@@ -82,6 +82,7 @@ import {
   classifyEvolution,
   edgeEvolutionIdentity,
   eventDedupeKey,
+  EVENT_DISPOSITIONS,
   eventId,
   EVOLUTION_EVENT_SCHEMA_VERSION,
 } from "../governance/evolution-event.mjs";
@@ -838,14 +839,33 @@ function buildTransitionEvent(from, to, transition, comparison) {
  * axis at any transition is surfaced as `{available: false, reason}` naming
  * the transition index, never folded into a fabricated clean aggregate.
  *
+ * The disposition loop latches the event vocabulary: a comparison whose
+ * disposition is unknown or absent THROWS naming it — the `?? 1` it replaced
+ * defaulted a stranger to rank 1, accepted's own rank, so a garbled
+ * disposition could never be the summary's worst. Production dispositions
+ * arrive validated (`classifyEvolution`, `readEvents`), so the throw fires
+ * only where archkeep itself is buggy — the same latch `deltaDisposition`
+ * holds.
+ *
  * @param {object[]} comparisons The per-transition comparison objects.
  * @returns {object} The summary.
+ * @throws {Error} On a comparison whose `disposition` is outside
+ *   `EVENT_DISPOSITIONS`, naming the value.
  */
-function buildEvolutionSummary(comparisons) {
+export function buildEvolutionSummary(comparisons) {
   const dispositionRank = { accepted: 1, rejected: 2, "no-verdict": 3 };
   let disposition = "accepted";
   for (const comparison of comparisons) {
-    if ((dispositionRank[comparison.disposition] ?? 1) > dispositionRank[disposition]) {
+    if (!EVENT_DISPOSITIONS.includes(comparison.disposition)) {
+      throw new Error(
+        `the evolution summary folds dispositions by rank, and ${JSON.stringify(
+          comparison.disposition,
+        )} is not one of [${EVENT_DISPOSITIONS.join(", ")}] — an unknown disposition would ` +
+          `default to rank 1, accepted's own rank, and could never be the summary's worst. ` +
+          `This is a bug in archkeep, not a fact about the workspace.`,
+      );
+    }
+    if (dispositionRank[comparison.disposition] > dispositionRank[disposition]) {
       disposition = comparison.disposition;
     }
   }

package/src/commands/explain-capability.mjs

@@ -0,0 +1,11 @@
+/**
+ * `explain` capability facade — the word's verb roster as explicit named
+ * re-exports: `explain`.
+ *
+ * Pure surface module: no judgment, no defaults, no logic — every export is
+ * a re-export of a command module. `cli.mjs` routes its verb imports through
+ * the facade so the vocabulary's code referent is visible to the import
+ * graph, not just to a comment (PD-18,
+ * ../../../../docs/architecture/refactor/DECISIONS.md).
+ */
+export { explain } from "./explain.mjs";

package/src/commands/explain.mjs

@@ -86,8 +86,10 @@ import { findConstraintsFor } from "../rules/tags.mjs";
 import { findProjectForPath, createProjectRootMappings } from "../rules/specifiers.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { coverageVerdict } from "./coverage-verdict.mjs";
+import { resolveCommandContext } from "./context.mjs";
 import { formatExplainReport } from "../report/explain-text.mjs";
 import { resolveProvenance } from "./provenance.mjs";
+import { resolvePolicy } from "./policy.mjs";
 import { readAdrContext } from "./adr.mjs";
 import { lineage } from "../governance/decision-graph.mjs";
 import { unresolvedDecisionRefNote } from "./provenance-command.mjs";
@@ -613,3 +615,25 @@ export function explainCommand(site, commandContext, config, options = {}) {
     },
   };
 }
+
+/**
+ * `explain` as the CLI drives it: the shared preamble — command context,
+ * then the boundary law — resolved here so `../../cli.mjs`'s driver only
+ * wires options, IO seams, and where output lands (`./README.md`). The
+ * engine this returns from is `explainCommand` above, unchanged.
+ *
+ * @param {{config: string|null, paths: string[]}} options This run's parsed
+ *   flags; `paths[0]` is the site, a `file:line:column` string.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `explainCommand`'s result, unmodified.
+ */
+export async function explain(options, { cwd, readGraph, listFiles }) {
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, 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);
+  return explainCommand(options.paths[0], commandContext, config);
+}

package/src/commands/fitness.mjs

@@ -49,13 +49,18 @@ import { blindSpotRows } from "../analysis/source-util.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatFitnessSection } from "../report/text.mjs";
 import { resolveProvenance } from "./provenance.mjs";
+import { resolveCommandContext } from "./context.mjs";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { driftForCheck } from "./drift.mjs";
+import { resolvePolicy } from "./policy.mjs";
 import {
   evaluateFitness,
   fitnessSnapshot,
   fitnessVerdictFor,
 } from "../governance/fitness-registry.mjs";
+import { VERDICTS, isVerdict } from "../governance/verdict.mjs";
+import { buildDecision } from "../report/evidence.mjs";
+import { describe } from "../values.mjs";
 
 /**
  * The `fitness` command's own text report: the same verdict table `check`'s
@@ -104,6 +109,55 @@ export function declaresFitness(config) {
   return config !== null && config !== undefined && config.fitness !== undefined;
 }
 
+/**
+ * The `fitness` exit fold, lifted out of `fitnessCommand` as a pure function
+ * so the mapping from the overall verdict to the status is a fact a test can
+ * pin (`./change.mjs`'s `reconcileDisposition` is the arrangement's
+ * precedent). D-09, as below: `fail` → `findings`/1, `unknown` →
+ * `no-verdict`/3, `pass` and an all-`not_applicable` run alike → `ok`/0.
+ *
+ * The input latch runs first: `overall.verdict` is the handshake with
+ * `fitnessVerdictFor`, and a value the fold does not recognize matches
+ * neither the `fail` nor the `unknown` arm — it would fall to `ok`, a clean
+ * exit over a run the fold could not read. A verdict outside the four states
+ * is refused as a no-verdict whose single reason names it (`refused`), never
+ * folded past. The literals stay hand-rolled per site by decision — the
+ * carrier folds are the pinned baseline INV-2 names, not a table to be
+ * converged (`docs/architecture/refactor/AUTHORITY-MAP.md`).
+ *
+ * `overall.decisions` is validated for the same reason the delta fold
+ * validates buckets the fold itself does not count first: `result.functions`
+ * and the text table render them downstream of this fold, so a malformed one
+ * is refused while there is still a verdict to withhold.
+ *
+ * @param {{verdict: string, decisions: object[]}} overall From
+ *   `fitnessVerdictFor`.
+ * @returns {{status: "ok"|"findings"|"no-verdict", exitCode: 0|1|3,
+ *   refused?: undefined}|
+ *   {status: "no-verdict", exitCode: 3, refused: string}}
+ */
+export function fitnessFold(overall) {
+  if (!isVerdict(overall?.verdict)) {
+    return {
+      status: "no-verdict",
+      exitCode: 3,
+      refused: `the fitness fold maps "overall.verdict", which is ${describe(overall?.verdict)} — a verdict outside ${VERDICTS.join(", ")} matches neither the fail nor the unknown lane, and reads "ok". This is a bug in archkeep, not a fact about the workspace.`,
+    };
+  }
+  if (!Array.isArray(overall?.decisions)) {
+    return {
+      status: "no-verdict",
+      exitCode: 3,
+      refused: `the fitness fold reads "overall.decisions", which is ${describe(overall?.decisions)} — the verdict table the run reports is built from it below, and a list that is not an array renders as an empty table. This is a bug in archkeep, not a fact about the workspace.`,
+    };
+  }
+  return overall.verdict === "fail"
+    ? { status: "findings", exitCode: 1 }
+    : overall.verdict === "unknown"
+      ? { status: "no-verdict", exitCode: 3 }
+      : { status: "ok", exitCode: 0 };
+}
+
 /**
  * Runs the `fitness` command: loads the boundary policy, evaluates every
  * declared function against the workspace's facts, and renders the verdict
@@ -115,8 +169,8 @@ export function declaresFitness(config) {
  *
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {{config?: object|null}} [io] The loaded policy, injectable for tests.
- * @returns {Promise<{status: "ok"|"findings"|"no-verdict", fitness?: object,
- *   coverage: object, report: {text: string, json: string}}>}
+ * @returns {Promise<{status: "ok"|"findings"|"no-verdict", exitCode: 0|1|3,
+ *   fitness?: object, coverage: object, report: {text: string, json: string}}>}
  *   `status: "no-verdict"` from the coverage refusal carries no `fitness`
  *   payload — the verdict was withheld, and the envelope's `coverage` block is
  *   the whole answer (#608).
@@ -207,13 +261,40 @@ export async function fitnessCommand(commandContext, io = {}) {
   // every function is `not_applicable` are both `ok`: nothing failed and
   // nothing stayed undetermined. The status↔exitCode pair is asserted by
   // `jsonEnvelope` (3-on-no-verdict), so a wrong mapping here cannot ship.
-  /** @type {{status: "ok"|"findings"|"no-verdict", exitCode: 0|1|3}} */
-  const { status, exitCode } =
-    overall.verdict === "fail"
-      ? { status: "findings", exitCode: 1 }
-      : overall.verdict === "unknown"
-        ? { status: "no-verdict", exitCode: 3 }
-        : { status: "ok", exitCode: 0 };
+  // `fitnessFold` above owns the mapping and its input latch; a refusal
+  // withholds the verdict table exactly the coverage refusal does, and the
+  // decision it carries names the input the fold could not read.
+  const fold = fitnessFold(overall);
+  if (fold.refused !== undefined) {
+    return {
+      status: fold.status,
+      exitCode: fold.exitCode,
+      coverage: { ...coverage, notes: [...coverage.notes, fold.refused] },
+      report: {
+        text: `fitness: no verdict — ${fold.refused}\n`,
+        json: renderJson(
+          jsonEnvelope({
+            command: "fitness",
+            context,
+            status: fold.status,
+            exitCode: fold.exitCode,
+            coverage: { ...coverage, notes: [...coverage.notes, fold.refused] },
+            // The refusal-withheld payload, stated the way `coverageRefusal`
+            // states it: `jsonEnvelope` requires the key, the refusal has no
+            // result to report.
+            result: undefined,
+            decision: buildDecision({
+              status: fold.status,
+              coverageComplete: true,
+              findings: 0,
+              reason: fold.refused,
+            }),
+          }),
+        ),
+      },
+    };
+  }
+  const { status, exitCode } = fold;
   const result = { verdict: overall.verdict, functions: decisions };
 
   const report = {
@@ -223,5 +304,33 @@ export async function fitnessCommand(commandContext, io = {}) {
     ),
   };
 
-  return { status, fitness: result, coverage, report };
+  return { status, exitCode, fitness: result, coverage, report };
+}
+
+/**
+ * `fitness` as the CLI drives it: the shared preamble — command context,
+ * then the boundary law — resolved here so `../../cli.mjs`'s driver only
+ * wires options, IO seams, and where output lands (`./README.md`). The
+ * engine this returns from is `fitnessCommand` above, unchanged.
+ *
+ * @param {{config: string|null, paths: string[]}} options This run's parsed
+ *   flags.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `fitnessCommand`'s result, unmodified.
+ */
+export async function fitness(options, { cwd, readGraph, listFiles }) {
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, 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` 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 rather than a config-loading failure.
+  const { config } = await resolvePolicy(options, commandContext, cwd);
+  return fitnessCommand(commandContext, { config });
 }

package/src/commands/govern-capability.mjs

@@ -0,0 +1,16 @@
+/**
+ * `govern` capability facade — the word's verb roster as explicit named
+ * re-exports: `waivers`, `report`, `debt`, `provenance`, `decisions`, `adr`.
+ *
+ * Pure surface module: no judgment, no defaults, no logic — every export is
+ * a re-export of a command module. `cli.mjs` routes its verb imports through
+ * the facade so the vocabulary's code referent is visible to the import
+ * graph, not just to a comment (PD-18,
+ * ../../../../docs/architecture/refactor/DECISIONS.md).
+ */
+export { waivers } from "./waivers.mjs";
+export { report } from "./report.mjs";
+export { debt } from "./debt.mjs";
+export { provenanceCommand } from "./provenance-command.mjs";
+export { decisions } from "./decisions.mjs";
+export { adrCommand } from "./adr.mjs";

package/src/commands/graph.mjs

@@ -41,7 +41,9 @@ import { DEFAULT_WORKSPACE_LAYOUT } from "../rules/specifiers.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatGraphReport } from "../report/graph-text.mjs";
 import { coverageIncompleteReasons } from "../verdict.mjs";
+import { resolveCommandContext } from "./context.mjs";
 import { coverageVerdict } from "./coverage-verdict.mjs";
+import { resolveDescribedPolicy } from "./policy.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 
 /**
@@ -342,3 +344,40 @@ export function graphCommand(commandContext, { config = null } = {}) {
     },
   };
 }
+
+/**
+ * `graph` as the CLI drives it: the shared preamble — command context, then
+ * the workspace's described policy — resolved here, so `../../cli.mjs`'s
+ * driver only wires options, IO seams, and where output lands
+ * (`./README.md`). The engine this returns from is `graphCommand` above,
+ * unchanged.
+ *
+ * The policy is DESCRIBED, not judged: `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`
+ * (`./policy.mjs`) rather than here, so the descriptive commands and the
+ * MCP face that serves them cannot disagree about what "no law declared"
+ * means.
+ *
+ * @param {{config: string|null, paths: string[]}} options This run's parsed
+ *   flags — `graph` has no `--config` flag, so `config` is always `null`
+ *   and the workspace's own default is what resolves.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `graphCommand`'s result, unmodified.
+ */
+export async function graph(options, { cwd, readGraph, listFiles }) {
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, listFiles });
+  // The fingerprint is why the config loads even though `graph` judges
+  // nothing: `diff` warns when the policy changed between runs, and a
+  // profile-selected workspace's `boundaryConfig` names a profile rather
+  // than a file, resolved the same way `check` resolves it
+  // (`resolveDescribedPolicy`), so the fingerprint moves with a profile edit
+  // the same way it already does with a file or inline-object edit.
+  const { config } = await resolveDescribedPolicy(options, commandContext, cwd);
+  return graphCommand(commandContext, { config });
+}

package/src/commands/health.mjs

@@ -49,10 +49,12 @@ import {
   unresolvableLiteralCount,
 } from "../analysis/source-util.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
+import { isAbsolute, resolve } from "node:path";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatHealthReport } from "../report/health-text.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { readSnapshots } from "./history.mjs";
+import { resolveCommandContext } from "./context.mjs";
 import {
   boundaryMetrics,
   couplingMetrics,
@@ -61,6 +63,8 @@ import {
   structuralMetrics,
 } from "../governance/metrics.mjs";
 import { judgeIntent } from "../architecture-intent/judge.mjs";
+import { loadIntentIfTracked } from "../architecture-intent/model.mjs";
+import { resolvePolicy } from "./policy.mjs";
 
 /**
  * Computes the intent verdict the fitness metric reads — the same `judgeIntent`
@@ -222,3 +226,33 @@ export function healthCommand(commandContext, io = {}) {
     },
   };
 }
+
+/**
+ * `health` as the CLI drives it: the shared preamble — command context, the
+ * boundary law, the tracked intent — resolved here, so `../../cli.mjs`'s
+ * driver only wires options, IO seams, and where output lands
+ * (`./README.md`). The engine this returns from is `healthCommand` above,
+ * unchanged.
+ *
+ * @param {{config: string|null, paths: string[]}} options This run's parsed
+ *   flags; at most one positional, the snapshot directory for trends.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `healthCommand`'s result, unmodified.
+ */
+export async function health(options, { cwd, readGraph, listFiles }) {
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, 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 = await loadIntentIfTracked(commandContext.root, commandContext.tracked);
+  const trendDir =
+    options.paths.length === 1
+      ? isAbsolute(options.paths[0])
+        ? options.paths[0]
+        : resolve(cwd, options.paths[0])
+      : null;
+  return healthCommand(commandContext, { config, intent, trendDir });
+}

package/src/commands/history.mjs

@@ -72,7 +72,7 @@
  */
 import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 
 import {
   blindSpotRows,
@@ -85,9 +85,11 @@ import { classifyEvolution } from "../governance/evolution-event.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatHistoryReport } from "../report/history-text.mjs";
 import { computeDiff, parseBaseline } from "./diff.mjs";
-import { buildDependencies, buildProjects } from "./graph.mjs";
+import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
+import { resolveCommandContext } from "./context.mjs";
+import { resolvePolicy } from "./policy.mjs";
 
 /**
  * A graph envelope's architecture identity: the part that determines whether
@@ -112,6 +114,12 @@ import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
  * Provider and provenance changes surface through the transition
  * classification instead.
  *
+ * This function is the graph-snapshot family's ONE identity — evolution event
+ * sides consume its output through `eventSnapshotSide` below, never a second
+ * derivation (`../../../../docs/adr/0008-snapshot-identity-per-family.md`
+ * records the one-identity-per-family decision, including why the evidence
+ * snapshot family deliberately carries no id at all).
+ *
  * @param {{projects: object[], dependencies: object[], policy?: {fingerprint: string}|null}} snapshot
  * @returns {string} A hex-encoded SHA-256.
  */
@@ -136,6 +144,34 @@ export function snapshotIdentity({ projects, dependencies, policy }) {
   return createHash("sha256").update(canonical).digest("hex");
 }
 
+/**
+ * An evolution event's identity side: the reference to ONE state — a revision
+ * when one is known, plus the snapshot identity of the graph that side was
+ * judged over. `delta` and `change` build every side through this one
+ * function so the identity spelling cannot drift between them, and a storage
+ * path can never re-enter the tuple a committed event store dedupes on
+ * (`docs/concepts/evolution.md`'s "Nor does a storage path"). `history` and
+ * `evolution` spell the same `{revision, snapshot}` shape directly, from a
+ * snapshot whose identity is already computed.
+ *
+ * @param {{revision?: string|null, projects: object[], dependencies: object[],
+ *   policyFingerprint?: string|null}} side
+ * @returns {{revision?: string, snapshot: string}} The identity side.
+ */
+export function eventSnapshotSide({ revision, projects, dependencies, policyFingerprint }) {
+  return {
+    ...(typeof revision === "string" ? { revision } : {}),
+    snapshot: snapshotIdentity({
+      projects,
+      dependencies,
+      policy:
+        policyFingerprint === undefined || policyFingerprint === null
+          ? null
+          : { fingerprint: policyFingerprint },
+    }),
+  };
+}
+
 /**
  * Reads and validates every snapshot in the history directory.
  *
@@ -732,3 +768,84 @@ function envelopeToSnapshot(envelope, path, id) {
     id,
   };
 }
+
+/**
+ * The history directory, resolved once from the single positional argument —
+ * shared by the CLI entry and the output guard below.
+ *
+ * @param {{paths: string[]}} options This run's parsed flags.
+ * @param {string} cwd The run's working directory.
+ * @returns {string}
+ */
+function historyDirFrom(options, cwd) {
+  return isAbsolute(options.paths[0]) ? resolve(options.paths[0]) : resolve(cwd, options.paths[0]);
+}
+
+/**
+ * `history`'s 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). Declared by the command that owns the law and
+ * enforced by the driver's write door; `null` means no refusal.
+ *
+ * @param {{output: string|null, paths: string[]}} options This run's parsed
+ *   flags.
+ * @param {string} cwd The run's working directory, for relative flag
+ *   resolution.
+ * @returns {string|null} The refusal message, or `null` when the output is
+ *   safe.
+ */
+export function historyOutputRefusal(options, cwd) {
+  if (!options.output) return null;
+  // `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);
+  const dir = historyDirFrom(options, cwd);
+  if (dirname(outputAbs) === dir) {
+    return (
+      `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 null;
+}
+
+/**
+ * `history` as the CLI drives it: the history directory resolved from the
+ * single positional argument, then the shared preamble — command context,
+ * and under `--capture` the boundary law whose fingerprint the snapshot
+ * records — so `../../cli.mjs`'s driver only wires options, IO seams, and
+ * where output lands (`./README.md`). The engine this returns from is
+ * `historyCommand` above, unchanged.
+ *
+ * @param {{capture: boolean, config: string|null, paths: string[]}} options
+ *   This run's parsed flags.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `historyCommand`'s result, unmodified.
+ */
+export async function history(options, { cwd, readGraph, listFiles }) {
+  const dir = historyDirFrom(options, cwd);
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, 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);
+    }
+  }
+  return historyCommand(dir, commandContext, {
+    capture: options.capture,
+    policyFingerprint: fingerprint,
+  });
+}

package/src/commands/impact.mjs

@@ -40,8 +40,10 @@ import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatImpactReport } from "../report/impact-text.mjs";
 import { resolveProvenance } from "./provenance.mjs";
+import { resolveCommandContext } from "./context.mjs";
 import { composeImpactStatement } from "./impact-statement.mjs";
 import { computeImpact } from "./impact-reachability.mjs";
+import { resolvePolicy } from "./policy.mjs";
 
 /**
  * The reachability walk this command reports, shared with the canonical
@@ -171,3 +173,24 @@ export function impactCommand(projectName, commandContext, config = null) {
     },
   };
 }
+
+/**
+ * `impact` as the CLI drives it: the shared preamble — command context, then
+ * the boundary law — resolved here so `../../cli.mjs`'s driver only wires
+ * options, IO seams, and where output lands (`./README.md`). The engine this
+ * returns from is `impactCommand` above, unchanged.
+ *
+ * @param {string} projectName The project whose dependents are walked.
+ * @param {{config: string|null}} options This run's parsed flags.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `impactCommand`'s result, unmodified.
+ */
+export async function impact(projectName, options, { cwd, readGraph, listFiles }) {
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, 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);
+  return impactCommand(projectName, commandContext, config);
+}

package/src/commands/inspect-capability.mjs

@@ -0,0 +1,16 @@
+/**
+ * `inspect` capability facade — the word's verb roster as explicit named
+ * re-exports: `graph`, `impact`, `context` (the non-plan read; `--plan`
+ * dispatches to `planContext`), `health`.
+ *
+ * Pure surface module: no judgment, no defaults, no logic — every export is
+ * a re-export of a command module. `cli.mjs` routes its verb imports through
+ * the facade so the vocabulary's code referent is visible to the import
+ * graph, not just to a comment (PD-18,
+ * ../../../../docs/architecture/refactor/DECISIONS.md).
+ */
+export { graph } from "./graph.mjs";
+export { impact } from "./impact.mjs";
+export { context } from "./context-command.mjs";
+export { planContext } from "./plan-context-command.mjs";
+export { health } from "./health.mjs";

package/src/commands/plan-context-command.mjs

@@ -61,6 +61,7 @@
  * reporting set. This makes the plan's verdict correct on every provider.
  */
 import { statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
 import { join } from "node:path";
 
 import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
@@ -82,6 +83,8 @@ import { buildDependencies, buildProjects, computePolicyFingerprint } from "./gr
 import { resolveProvenance } from "./provenance.mjs";
 import { readAdrContext } from "./adr.mjs";
 import { declaresFitness, fitnessForCheck } from "./fitness.mjs";
+import { resolveCommandContext } from "./context.mjs";
+import { resolvePolicy } from "./policy.mjs";
 import { computeWaivers } from "./waivers.mjs";
 import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/adr-registry.mjs";
 import { formatPlanContextReport } from "../report/plan-context-text.mjs";
@@ -667,3 +670,35 @@ function goWorkResult(goWork) {
 function tsconfigPathsResult(tsconfigPaths) {
   return tsconfigPaths === null ? null : { checked: true, findings: tsconfigPaths.findings };
 }
+
+/**
+ * `context --plan` as the CLI drives it: the shared preamble — command
+ * context, then the boundary law — resolved here, plus the plan's own
+ * arguments (the project, the change's scope paths, the optional history
+ * directory), so `../../cli.mjs`'s driver only wires options, IO seams, and
+ * where output lands (`./README.md`). The engine this returns from is
+ * `planContextCommand` above, unchanged.
+ *
+ * @param {{config: string|null, historyDir: string|null, paths: string[]}} options
+ *   This run's parsed flags; `paths[0]` is the project name, the rest are
+ *   the change's scope.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `planContextCommand`'s result, unmodified.
+ */
+export async function planContext(options, { cwd, readGraph, listFiles }) {
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, listFiles });
+  const { config } = await resolvePolicy(options, commandContext, cwd);
+  const historyDir = options.historyDir
+    ? isAbsolute(options.historyDir)
+      ? options.historyDir
+      : resolve(cwd, options.historyDir)
+    : null;
+  return planContextCommand(
+    options.paths[0],
+    options.paths.slice(1),
+    commandContext,
+    config,
+    historyDir,
+  );
+}