@ecoma-io/archkeep 0.25.0 → 0.26.0

package/src/commands/diff.mjs

@@ -42,12 +42,15 @@ import { readFileSync } from "node:fs";
 
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
 import { computeRuleImpact } from "../rules/edge-constraints.mjs";
+import { isAbsolute, resolve } from "node:path";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { SCHEMA_VERSION } from "../report/json.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatDiffReport } from "../report/diff-text.mjs";
 import { compareSnapshotMetadata, dirtyBaselineNote, dirtyHeadNote } from "./snapshot-meta.mjs";
 import { resolveProvenance } from "./provenance.mjs";
+import { resolveCommandContext } from "./context.mjs";
+import { resolvePolicy } from "./policy.mjs";
 
 /**
  * Reads and validates a baseline snapshot from `path`.
@@ -236,6 +239,20 @@ function buildHeadSnapshot(commandContext) {
  * consumer wants to see: it is a real architectural event, not an
  * implementation detail.
  *
+ * This key is in-memory arithmetic and nothing else: `Map`/`Set` keys inside
+ * one run, never persisted and never emitted — only counts derived from
+ * those sets reach an envelope. The STORED spelling of edge identity is
+ * `edgeEvolutionIdentity` (`../governance/evolution-event.mjs`), the escaped
+ * `source>target:type` string evolution events carry, and the two spellings
+ * are deliberately not unified — each medium keeps exactly one identity
+ * constructor (`../../../../docs/adr/0008-snapshot-identity-per-family.md`;
+ * INV-6 in `../../../../docs/architecture/refactor/INVARIANTS.md`). An edge
+ * crosses from a structural diff into an event as its raw
+ * `{source, target, type}` triple, mapped through that function at the
+ * command boundary; a `\0`-joined key written into an event record would
+ * give one edge two spellings inside the store, and anything comparing
+ * identity strings across events would read them as different boundaries.
+ *
  * @param {{source: string, target: string, type: string}} edge
  * @returns {string}
  */
@@ -558,3 +575,31 @@ export function diffCommand(
     },
   };
 }
+
+/**
+ * `diff` as the CLI drives it: the baseline path resolved from the single
+ * positional argument, then the shared preamble — command context, boundary
+ * law — so `../../cli.mjs`'s driver only wires options, IO seams, and where
+ * output lands (`./README.md`). The engine this returns from is
+ * `diffCommand` above, unchanged.
+ *
+ * @param {{format: string, output: string|null, config: string|null, paths: string[]}} options
+ *   This run's parsed flags; `paths[0]` is the baseline file.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `diffCommand`'s result, unmodified.
+ */
+export async function diff(options, { cwd, readGraph, listFiles }) {
+  const baselinePath = isAbsolute(options.paths[0])
+    ? options.paths[0]
+    : resolve(cwd, options.paths[0]);
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, 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);
+  return diffCommand(baselinePath, commandContext, { config });
+}

package/src/commands/discover.mjs

@@ -122,6 +122,43 @@ export function proposalToIntent(proposal) {
   };
 }
 
+/**
+ * Serialize a proposal into the exact bytes `--write-intent` plants at the
+ * target path — `proposalToIntent` rendered as stable, two-space JSON with a
+ * trailing newline, so the file a human reviews as a diff is the file
+ * `check` would read. Owned here, beside the conversion it renders, so the
+ * CLI's write door can never re-derive a second spelling of it.
+ *
+ * @param {object} proposal The proposal from `discoverCommand`'s result.
+ * @returns {string} The serialized intent document.
+ */
+export function intentJsonFromProposal(proposal) {
+  return JSON.stringify(proposalToIntent(proposal), null, 2) + "\n";
+}
+
+/**
+ * The `--write-intent` self-footgun refusal, decided beside the proposal it
+ * protects. A proposal is a suggestion; 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 — the same
+ * posture `--output`'s fixed-name table holds at the write door, specialized
+ * to the one target `discover` itself names. The CLI keeps the mechanics
+ * (the `wx` write, the stderr wording around it); the DECISION to refuse
+ * travels with the verb, the way `historyOutputRefusal` does for history.
+ *
+ * @param {string} target The `--write-intent` path as the user wrote it.
+ * @param {{exists: (path: string) => boolean}} io Injectable existence read —
+ *   the same seam style `loadNativeModel`'s `{readFile}` keeps.
+ * @returns {string|null} The refusal message, or `null` when the write may
+ *   proceed.
+ */
+export function intentWriteRefusal(target, { exists }) {
+  return exists(target)
+    ? `archkeep: ${target} already exists, and a proposal must never ` +
+        `silently replace what is there. Move or delete the file first, then run this again.`
+    : null;
+}
+
 /**
  * Runs the `discover` command: observes the workspace, optionally proposes the
  * candidate architecture over it, and returns the report.

package/src/commands/drift.mjs

@@ -77,6 +77,8 @@
  * intent produce byte-identical text and JSON.
  */
 import { blindSpotRows } from "../analysis/source-util.mjs";
+import { resolveCommandContext } from "./context.mjs";
+import { resolvePolicy } from "./policy.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
@@ -471,3 +473,46 @@ export async function driftCommand(commandContext, io = {}) {
     },
   };
 }
+
+/**
+ * `drift` 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 `driftCommand` above, unchanged.
+ *
+ * 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.
+ *
+ * @param {{format: string, output: 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>} `driftCommand`'s result, unmodified.
+ */
+export async function drift(options, { cwd, readGraph, listFiles }) {
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, listFiles });
+  let config = null;
+  let configError = null;
+  try {
+    ({ config } = await resolvePolicy({ ...options, config: null }, commandContext, cwd));
+  } catch (error) {
+    configError = /** @type {Error} */ (error);
+  }
+  return driftCommand(commandContext, { config, configError });
+}

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
@@ -766,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,
+  });
+}