@ecoma-io/archkeep 0.25.0 → 0.26.0

package/src/commands/context-command.mjs

@@ -37,10 +37,12 @@ import { judgeEdge } from "../rules/edge-constraints.mjs";
 import { findConstraintsFor } from "../rules/tags.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatContextReport } from "../report/context-text.mjs";
+import { resolveCommandContext } from "./context.mjs";
 import { coverageVerdict } from "./coverage-verdict.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { readAdrContext } from "./adr.mjs";
 import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/adr-registry.mjs";
+import { resolvePolicy } from "./policy.mjs";
 
 /**
  * Collects the architecture context for a project: its tags, which constraint
@@ -210,3 +212,32 @@ export function contextCommand(projectName, commandContext, config) {
     },
   };
 }
+
+/**
+ * `context` as the CLI drives it (the non-plan read): 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 `contextCommand`
+ * above, unchanged.
+ *
+ * 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
+ * keeps the non-plan `context` path byte-for-byte identical.
+ *
+ * @param {{config: string|null, paths: string[]}} options This run's parsed
+ *   flags; `paths[0]` is the project name.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `contextCommand`'s result, unmodified.
+ */
+export async function context(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` 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);
+  return contextCommand(options.paths[0], commandContext, config);
+}

package/src/commands/coverage-verdict.mjs

@@ -135,7 +135,7 @@ export function coverageVerdict(commandContext, { acceptedFiles } = {}) {
  *   command was asking (the text face's one free clause), `acceptedFiles`
  *   forwards to `coverageVerdict` (see above), and `decision: true` attaches
  *   the canonical `unknown` decision.
- * @returns {{status: "no-verdict", coverage: object,
+ * @returns {{status: "no-verdict", exitCode: 3, coverage: object,
  *   report: {text: string, json: string}}}
  */
 export function coverageRefusal({ command, commandContext, what, acceptedFiles, decision }) {
@@ -151,6 +151,18 @@ export function coverageRefusal({ command, commandContext, what, acceptedFiles,
   }
   /** @type {"no-verdict"} The completeness is false, so this is the status. */
   const status = "no-verdict";
+  // The `complete` throw above pins the STATUS; this guard pins the EXIT the
+  // same way, so the `{3}` annotation below is a checked fact rather than an
+  // unchecked assertion — a future `coverageVerdict` that let an incomplete
+  // run claim a clean exit dies here, loudly, instead of typing the lie.
+  if (verdict.exitCode !== EXIT.error) {
+    throw new Error(
+      `coverageRefusal: ${command}'s incomplete verdict carries exit ${verdict.exitCode} — ` +
+        `a refusal never exits clean`,
+    );
+  }
+  /** @type {3} The value flows from the one verdict table; the type is proven above. */
+  const refusalExitCode = verdict.exitCode;
   const reasons = coverageIncompleteReasons({
     unchecked: verdict.notAnalyzed.length,
     blindSpots: verdict.blindSpotCount,
@@ -174,7 +186,7 @@ export function coverageRefusal({ command, commandContext, what, acceptedFiles,
       provenance: resolveProvenance(commandContext.root),
     },
     status,
-    exitCode: verdict.exitCode,
+    exitCode: refusalExitCode,
     coverage,
     result: undefined,
     ...(decision === true
@@ -190,6 +202,7 @@ export function coverageRefusal({ command, commandContext, what, acceptedFiles,
   });
   return {
     status,
+    exitCode: refusalExitCode,
     coverage,
     report: {
       text:

package/src/commands/debt.mjs

@@ -51,11 +51,14 @@ import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
 import { computeDebtLedger } from "../governance/debt-ledger.mjs";
 import { readEvents } from "../governance/evolution-store.mjs";
 import { formatDebtReport } from "../report/debt-text.mjs";
+import { isAbsolute, resolve } from "node:path";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { buildObserved, refuseIncompleteGraph } from "./drift.mjs";
 import { readSnapshots } from "./history.mjs";
+import { resolveCommandContext } from "./context.mjs";
+import { resolvePolicy } from "./policy.mjs";
 
 /**
  * Runs the `debt` command: computes the current candid facts, ages them across
@@ -240,3 +243,30 @@ export async function debtCommand(dir, commandContext, options = {}) {
     },
   };
 }
+
+/**
+ * `debt` as the CLI drives it: the history directory resolved from the
+ * single positional argument, then the shared preamble — command context,
+ * then the boundary law — so `../../cli.mjs`'s driver only wires options,
+ * IO seams, and where output lands (`./README.md`). The engine this returns
+ * from is `debtCommand` above, unchanged.
+ *
+ * @param {{config: string|null, events: string|null, paths: string[]}} options
+ *   This run's parsed flags; `paths[0]` is the history directory.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `debtCommand`'s result, unmodified.
+ */
+export async function debt(options, { cwd, readGraph, listFiles }) {
+  const dir = isAbsolute(options.paths[0]) ? options.paths[0] : resolve(cwd, options.paths[0]);
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, 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);
+  return debtCommand(dir, commandContext, {
+    config,
+    events: options.events,
+  });
+}

package/src/commands/decisions.mjs

@@ -46,9 +46,13 @@ import { computeDecisionFitness } from "../governance/decision-fitness.mjs";
 import { stripAdrPrefix, stripRuleFitnessPrefix } from "../governance/adr-registry.mjs";
 import { intentRows, configRows, rowLabel } from "./provenance-command.mjs";
 import { evaluateFitness, fitnessSnapshot } from "../governance/fitness-registry.mjs";
+import { resolveCommandContext } from "./context.mjs";
+import { driftForCheck } from "./drift.mjs";
 import { hasTag, isComboDepConstraint } from "../rules/tags.mjs";
 import { resolveMembers } from "../architecture-intent/selectors.mjs";
+import { loadIntentIfTracked } from "../architecture-intent/model.mjs";
 import { evaluate } from "../rules/index.mjs";
+import { resolvePolicy } from "./policy.mjs";
 
 /**
  * The projects whose tags satisfy a constraint row's source selector — the
@@ -119,12 +123,33 @@ function intentRowGoverns(intent, graph, row) {
  *
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {object} config The resolved boundary law.
- * @param {object|null} intent The normalized intent model, or null when the
- *   workspace declares none.
- * @returns {object[]} `[{name, verdict}, ...]`.
+ * @returns {Promise<object[]>} `[{name, verdict}, ...]`.
  */
-function fitnessVerdictsFor(commandContext, config, intent) {
+async function fitnessVerdictsFor(commandContext, config) {
   if (!Array.isArray(config?.fitness) || config.fitness.length === 0) return [];
+  // A `drift-free` gate judges the SAME verdict-shaped intent the `fitness`
+  // command feeds its registry — `driftForCheck`'s, not the raw normalized
+  // model the walk's intent rows are built from: that model carries no
+  // `.verdict`, and a gate dispatched on it read as a fail over a clean tree
+  // (#737). The construction mirrors `./fitness.mjs`'s `fitnessCommand` —
+  // the same `drift.intent === undefined` → `null` resolution — so the two
+  // faces derive identical rows from identical facts.
+  const drift = await driftForCheck(commandContext);
+  const intent =
+    drift.intent === undefined
+      ? null
+      : {
+          verdict:
+            drift.findings.length > 0
+              ? "findings"
+              : drift.unresolved.length > 0
+                ? "no-verdict"
+                : "ok",
+          boundaries: drift.boundaries,
+          findings: drift.findings,
+          unresolved: drift.unresolved,
+          notes: drift.notes,
+        };
   const snapshot = fitnessSnapshot(commandContext, {
     intent,
     suppressions: config.suppressions ?? [],
@@ -145,12 +170,14 @@ function fitnessVerdictsFor(commandContext, config, intent) {
  * @param {{intent?: object|null, fitnessVerdicts?: object[]}} [io]
  *   `intent` is the normalized intent model (or null); `fitnessVerdicts`
  *   overrides the run's own evaluation — a test supplies a fixed list.
- * @returns {{status: "ok"|"no-verdict", result: object, coverage: object,
- *   report: {text: string, json: string}}}
- * @throws {Error} on an unreadable registry, a malformed law, or a config
- *   declaring fitness that fails to evaluate — exit-3 class.
+ * @returns {Promise<{status: "ok"|"no-verdict", result: object, coverage: object,
+ *   report: {text: string, json: string}}>}
+ * @throws {Error} on an unreadable registry, a malformed law, a
+ *   `driftForCheck` refusal on the fitness leg's intent (an unreadable or
+ *   invalid `architecture-intent.json`, an unregistered-plugin graph), or a
+ *   config declaring fitness that fails to evaluate — exit-3 class.
  */
-export function decisionsCommand(decisionId, commandContext, config, io = {}) {
+export async function decisionsCommand(decisionId, commandContext, config, io = {}) {
   const intent = io.intent ?? null;
 
   // The registry read — throws on an unreadable `docs/adr/`, which the caller
@@ -225,7 +252,7 @@ export function decisionsCommand(decisionId, commandContext, config, io = {}) {
   // the `{name, verdict}` list from the declared fitness gates above (or the
   // caller's override). `computeDecisionFitness`'s second argument carries
   // verdicts but is unused; the lookup is the single door, so it is null.
-  const verdicts = io.fitnessVerdicts ?? fitnessVerdictsFor(commandContext, config, intent);
+  const verdicts = io.fitnessVerdicts ?? (await fitnessVerdictsFor(commandContext, config));
   const verdictByName = new Map(verdicts.map((v) => [v.name, v]));
   const fitnessLookup = (bindingId) => verdictByName.get(stripRuleFitnessPrefix(bindingId));
   const fitnessById = new Map(
@@ -289,3 +316,25 @@ export function decisionsCommand(decisionId, commandContext, config, io = {}) {
     },
   };
 }
+
+/**
+ * `decisions` 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 `decisionsCommand`
+ * above, unchanged.
+ *
+ * @param {{config: string|null, paths: string[]}} options This run's parsed
+ *   flags; `paths[0]` is the ADR id.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `decisionsCommand`'s result, unmodified.
+ */
+export async function decisions(options, { cwd, readGraph, listFiles }) {
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, 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 = await loadIntentIfTracked(commandContext.root, commandContext.tracked);
+  return decisionsCommand(options.paths[0], commandContext, config, { intent });
+}

package/src/commands/delta.mjs

@@ -105,11 +105,15 @@ import {
   serializeEvidenceSnapshot,
 } from "./delta-snapshot.mjs";
 import { computeDiff } from "./diff.mjs";
+import { isAbsolute, resolve } from "node:path";
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
 import { eventSnapshotSide } from "./history.mjs";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { resolveProvenance } from "./provenance.mjs";
+import { resolveCommandContext } from "./context.mjs";
 import { compareSnapshotMetadata, dirtyBaselineNote, dirtyHeadNote } from "./snapshot-meta.mjs";
+import { describe } from "../values.mjs";
+import { resolvePolicy } from "./policy.mjs";
 
 const require = createRequire(import.meta.url);
 /** @type {{name: string, version: string}} */
@@ -382,11 +386,15 @@ export function sourceProjectAttributor(headGraph, baselineProjects) {
  *   a custom-rule-only introduced finding never reaches the VIOLATION
  *   predicate, so a classifications scan would read "accepted" on an exit-1
  *   run — the silent direction;
- * - everything else — a clean comparable capture (`ok`, `[]` classifications),
- *   an `ok` capture with a fact class (REPAIR, CHANGE, DRIFT,
- *   DECISION_CHANGE — each accepted by the vocabulary `classification` earns),
- *   or an `ok` capture holding a WAIVED violation (a waiver is a tracked
- *   acceptance — which is exactly what kept the gate `ok`) ⇒ `accepted`.
+ * - `ok` status — a clean comparable capture (`[]` classifications), an `ok`
+ *   capture with a fact class (REPAIR, CHANGE, DRIFT, DECISION_CHANGE — each
+ *   accepted by the vocabulary `classification` earns), or an `ok` capture
+ *   holding a WAIVED violation (a waiver is a tracked acceptance — which is
+ *   exactly what kept the gate `ok`) ⇒ `accepted`;
+ * - any OTHER status — a typo, a case- or whitespace-mangled spelling, an
+ *   absent field — THROWS naming the input, the input latch `verdictFor`
+ *   holds. There is no fourth status to fold, and folding a stranger to a
+ *   verdict would be the silent direction.
  *
  * The two refusals that can never reach this mapping — an unjudgeable head
  * and a provider mismatch — THROW before any event exists, so a delta that
@@ -395,12 +403,162 @@ export function sourceProjectAttributor(headGraph, baselineProjects) {
  *
  * @param {{status: "ok"|"findings"|"no-verdict"}} input
  * @returns {"accepted"|"rejected"|"no-verdict"}
+ * @throws {Error} On any `status` outside the three-verb contract, naming the
+ *   input.
  */
 export function deltaDisposition({ status }) {
   // used by its own test
   if (status === "no-verdict") return "no-verdict";
   if (status === "findings") return "rejected";
-  return "accepted";
+  if (status === "ok") return "accepted";
+  throw new Error(
+    `deltaDisposition: unknown delta status ${describe(status)} — expected "ok", "findings", ` +
+      `or "no-verdict". A status outside the delta verb's own contract has no disposition; ` +
+      `guessing one would be the silent direction. This is a bug in archkeep, not a fact about ` +
+      `the workspace.`,
+  );
+}
+
+/**
+ * The input latch for `deltaFold`: names the first counted bucket that is not
+ * an array, or `null` when every one is. A returned problem becomes the
+ * fold's refusal — never a throw, because the refusal is a fact about the run
+ * the command reports in-band, the same lane an `unknown` classification
+ * takes.
+ *
+ * Every bucket the COMMAND counts is validated, not only the ones the fold
+ * reads first: the custom-rule notes loop, the §1 mapping, `result.summary`
+ * and both report faces count the same buckets downstream of the fold, so a
+ * bucket that would crash or silently empty one of them is refused while
+ * there is still a verdict to withhold.
+ *
+ * @param {object} classification From `classifyDelta`.
+ * @param {{judged: object[], skipped: object[], removed: string[],
+ *   findings: {introduced: object[], resolved: object[], unchanged: object[],
+ *   unknown: object[]}}|null} custom
+ * @returns {string|null}
+ */
+function deltaFoldInputProblem(classification, custom) {
+  const counted = [
+    ["classification.violations.introduced", classification?.violations?.introduced],
+    ["classification.violations.resolved", classification?.violations?.resolved],
+    ["classification.violations.unchanged", classification?.violations?.unchanged],
+    ["classification.violations.unknown", classification?.violations?.unknown],
+    ["classification.unresolvable.introduced", classification?.unresolvable?.introduced],
+    ["classification.unresolvable.resolved", classification?.unresolvable?.resolved],
+    ["classification.unresolvable.unchanged", classification?.unresolvable?.unchanged],
+    ["classification.unresolvable.unknown", classification?.unresolvable?.unknown],
+    ...(custom === null
+      ? []
+      : [
+          ["custom.judged", custom?.judged],
+          ["custom.skipped", custom?.skipped],
+          ["custom.removed", custom?.removed],
+          ["custom.findings.introduced", custom?.findings?.introduced],
+          ["custom.findings.resolved", custom?.findings?.resolved],
+          ["custom.findings.unchanged", custom?.findings?.unchanged],
+          ["custom.findings.unknown", custom?.findings?.unknown],
+        ]),
+  ];
+  for (const [name, value] of counted) {
+    if (!Array.isArray(value)) {
+      return `the delta fold counts "${name}", which is ${describe(value)} — a bucket that is not an array counts as empty in every lane, and an empty delta reads "no change". This is a bug in archkeep, not a fact about the workspace.`;
+    }
+  }
+  return null;
+}
+
+/**
+ * The `delta` exit fold, lifted out of `deltaCommand` as a pure function so
+ * the mapping from classification buckets to the verdict is a fact a test can
+ * pin (`./change.mjs`'s `reconcileDisposition` is the arrangement's
+ * precedent). The lane order is the one `deltaCommand`'s header states:
+ * introduced-and-not-waived (violations and custom findings alike) →
+ * `findings`/1; else any unknown item → `no-verdict`/3; else `ok`/0.
+ *
+ * The input latch runs first: a bucket the fold cannot read is refused as a
+ * no-verdict whose single reason names it (`refused`), never folded past as a
+ * silently-empty count. 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`).
+ *
+ * Pure and exported for the fold's own tests; `deltaCommand` is its only
+ * production caller.
+ *
+ * @param {object} classification From `classifyDelta`.
+ * @param {{judged: object[], skipped: object[], removed: string[],
+ *   findings: {introduced: object[], resolved: object[], unchanged: object[],
+ *   unknown: object[]}}|null} custom
+ * @returns {{status: "ok"|"findings"|"no-verdict", exitCode: 0|1|3,
+ *   decision: object, introducedWaived: number, refused?: undefined}|
+ *   {status: "no-verdict", exitCode: 3, decision: object, introducedWaived?: undefined,
+ *   refused: string}}
+ *   `introducedWaived` rides every judged lane because `result.summary`
+ *   reports it whichever lane fired; a refusal carries `refused` and no
+ *   counts, and is the one return whose `decision.reason` names a malformed
+ *   input rather than a fact about the trees.
+ */
+export function deltaFold(classification, custom) {
+  const problem = deltaFoldInputProblem(classification, custom);
+  if (problem !== null) {
+    return {
+      status: "no-verdict",
+      exitCode: 3,
+      decision: buildDecision({
+        status: "no-verdict",
+        coverageComplete: true,
+        findings: 0,
+        reason: problem,
+      }),
+      refused: problem,
+    };
+  }
+  const { violations, unresolvable } = classification;
+  const introducedWaived = violations.introduced.filter((entry) => entry.waived === true).length;
+  const introducedNotWaived = violations.introduced.length - introducedWaived;
+  // Custom findings have no waiver lane (`./delta-classify.mjs`'s
+  // `classifyCustomFindings` argues the by-construction absence), so every
+  // introduced one gates.
+  const customIntroduced = custom === null ? 0 : custom.findings.introduced.length;
+  const customUnknown = custom === null ? 0 : custom.findings.unknown.length;
+  const unknownCount = violations.unknown.length + unresolvable.unknown.length + customUnknown;
+
+  if (introducedNotWaived + customIntroduced > 0) {
+    return {
+      status: "findings",
+      exitCode: 1,
+      decision: buildDecision({
+        status: "findings",
+        coverageComplete: true,
+        findings: introducedNotWaived + customIntroduced,
+      }),
+      introducedWaived,
+    };
+  }
+  if (unknownCount > 0) {
+    return {
+      status: "no-verdict",
+      exitCode: 3,
+      decision: buildDecision({
+        status: "no-verdict",
+        coverageComplete: true,
+        findings: 0,
+        reason:
+          `${unknownCount} delta item${unknownCount === 1 ? "" : "s"} could not be classified — ` +
+          (customUnknown > 0
+            ? `${customUnknown} of them custom-rule item${customUnknown === 1 ? "" : "s"} — `
+            : "") +
+          `an item whose identity cannot be stated is never guessed into a bucket`,
+      }),
+      introducedWaived,
+    };
+  }
+  return {
+    status: "ok",
+    exitCode: 0,
+    decision: buildDecision({ status: "ok", coverageComplete: true, findings: 0 }),
+    introducedWaived,
+  };
 }
 
 /** First eight hex characters of a fingerprint, for prose that names one. */
@@ -449,8 +607,8 @@ const short = (fingerprint) =>
  *   `loadIntent`; absent intent ⇒ no ids, an in-band note says so), and the
  *   custom-rule host's two injectable seams, passed through to
  *   `customRulesForDelta`.
- * @returns {Promise<{status: "ok"|"findings"|"no-verdict", delta?: object,
- *   coverage: object,
+ * @returns {Promise<{status: "ok"|"findings"|"no-verdict",
+ *   exitCode: 0|1|3, delta?: object, coverage: object,
  *   eventWrite?: {id: string, duplicate: boolean}|null,
  *   report: {text: string, json: string, sarif?: string}}>} `delta` carries
  *   the additive `classifications`/`affected` fields (design §1); `eventWrite`
@@ -691,6 +849,48 @@ export async function deltaCommand(
       findings: { introduced: [], resolved: [], unchanged: [], unknown: [] },
     };
   }
+  // The exit fold, taken the moment both of its inputs are final: everything
+  // below — the custom-rule notes loop, the §1 mapping, `result.summary`, both
+  // report faces — counts the same buckets, and a malformed one must be
+  // refused HERE, in-band (no-verdict, exit 3, the bucket named), never
+  // counted past as a silently-empty bucket. The refusal withholds `delta`
+  // and the event exactly the coverage refusal does (#608): a comparison
+  // whose counts could not be read has no result to report.
+  const fold = deltaFold(classification, custom);
+  if (fold.refused !== undefined) {
+    const refusalCoverage = {
+      complete: true,
+      projects: Object.keys(graph.nodes).length,
+      analyzedFiles: analysis.analyzed,
+      imports: analysis.imports.length,
+      notAnalyzed: [],
+      blindSpots: blindSpotRows(analysis.failures),
+      notes: [fold.refused],
+    };
+    return {
+      status: fold.status,
+      exitCode: fold.exitCode,
+      coverage: refusalCoverage,
+      report: {
+        text: `delta: no verdict — ${fold.refused}\n`,
+        json: renderJson(
+          jsonEnvelope({
+            command: "delta",
+            context: { root, provider, marker, provenance: headProvenance },
+            status: fold.status,
+            exitCode: fold.exitCode,
+            coverage: refusalCoverage,
+            // The refusal-withheld payload, stated the way `coverageRefusal`
+            // states it: `jsonEnvelope` requires the key, the refusal has no
+            // result to report.
+            result: undefined,
+            decision: fold.decision,
+          }),
+        ),
+      },
+    };
+  }
+
   if (custom !== null) {
     for (const skipped of custom.skipped) {
       notes.push(`custom rule "${skipped.name}" was not classified — ${skipped.reason}`);
@@ -737,48 +937,10 @@ export async function deltaCommand(
     codeDrift,
   });
 
+  // The verdict, from the one fold — `deltaFold` above owns the lane order
+  // and the input latch; this destructure is the command's only hand in it.
   const { violations, unresolvable } = classification;
-  const introducedWaived = violations.introduced.filter((entry) => entry.waived === true).length;
-  const introducedNotWaived = violations.introduced.length - introducedWaived;
-  // Custom findings have no waiver lane (`./delta-classify.mjs`'s
-  // `classifyCustomFindings` argues the by-construction absence), so every
-  // introduced one gates.
-  const customIntroduced = custom === null ? 0 : custom.findings.introduced.length;
-  const customUnknown = custom === null ? 0 : custom.findings.unknown.length;
-  const unknownCount = violations.unknown.length + unresolvable.unknown.length + customUnknown;
-
-  /** @type {"ok"|"findings"|"no-verdict"} */
-  let status;
-  /** @type {0|1|3} */
-  let exitCode;
-  let decision;
-  if (introducedNotWaived + customIntroduced > 0) {
-    status = "findings";
-    exitCode = 1;
-    decision = buildDecision({
-      status,
-      coverageComplete: true,
-      findings: introducedNotWaived + customIntroduced,
-    });
-  } else if (unknownCount > 0) {
-    status = "no-verdict";
-    exitCode = 3;
-    decision = buildDecision({
-      status,
-      coverageComplete: true,
-      findings: 0,
-      reason:
-        `${unknownCount} delta item${unknownCount === 1 ? "" : "s"} could not be classified — ` +
-        (customUnknown > 0
-          ? `${customUnknown} of them custom-rule item${customUnknown === 1 ? "" : "s"} — `
-          : "") +
-        `an item whose identity cannot be stated is never guessed into a bucket`,
-    });
-  } else {
-    status = "ok";
-    exitCode = 0;
-    decision = buildDecision({ status, coverageComplete: true, findings: 0 });
-  }
+  const { status, exitCode, decision, introducedWaived } = fold;
 
   const coverage = {
     complete: true,
@@ -948,6 +1110,7 @@ export async function deltaCommand(
 
   return {
     status,
+    exitCode,
     eventWrite,
     delta: result,
     coverage,
@@ -961,3 +1124,54 @@ export async function deltaCommand(
     },
   };
 }
+
+/**
+ * `delta --capture` as the CLI drives it: the shared preamble — command
+ * context, then the boundary law — resolved here, so `../../cli.mjs`'s
+ * driver only wires where the evidence text lands. The engine this returns
+ * from is `captureDelta` above, unchanged; the driver owns the write door.
+ *
+ * @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>} `captureDelta`'s result (`snapshot`, `text`),
+ *   unmodified.
+ */
+export async function captureBaseline(options, { cwd, readGraph, listFiles }) {
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, listFiles });
+  // The snapshot's policy fingerprint needs the boundary config — the
+  // workspace's own `boundaryConfig` (profile-aware the same way `check` is,
+  // `resolvePolicy`), so the stored fingerprint agrees with a standalone
+  // `graph` fingerprint over the same workspace, kept in one place so a
+  // capture and a `graph` never disagree about the current policy.
+  const { config } = await resolvePolicy(options, commandContext, cwd);
+  return captureDelta(commandContext, { config });
+}
+
+/**
+ * `delta` (compare) 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. The engine this returns from is
+ * `deltaCommand` above, unchanged.
+ *
+ * @param {{config: string|null, eventOut: 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>} `deltaCommand`'s result, unmodified.
+ */
+export async function delta(options, { cwd, readGraph, listFiles }) {
+  const baselinePath = isAbsolute(options.paths[0])
+    ? resolve(options.paths[0])
+    : resolve(cwd, options.paths[0]);
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, listFiles });
+  // 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 deltaCommand(baselinePath, commandContext, {
+    config,
+    eventOut: options.eventOut,
+  });
+}