@ecoma-io/archkeep 0.24.1 → 0.26.0

package/src/commands/check-capability.mjs

@@ -0,0 +1,13 @@
+/**
+ * `check` capability facade — the word's verb roster as explicit named
+ * re-exports: `check`, `fitness`, `scenario`.
+ *
+ * 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 { check, sortViolations } from "./check.mjs";
+export { fitness } from "./fitness.mjs";
+export { scenario } from "./scenario.mjs";

package/src/commands/check.mjs

@@ -209,7 +209,7 @@ function declaredEdgeManifest({ provider, graph }, sourceProject) {
  *   evidenceOut?: string|null}} options
  * @param {{cwd: string, readGraph?: Function, listFiles?: Function,
  *   listUntracked?: Function}} context
- * @returns {Promise<{report: string, violations: number, declaredEdgeFindings: number,
+ * @returns {Promise<{exitCode: 0|1|3, report: string, violations: number, declaredEdgeFindings: number,
  *   goWorkDrift: number, tsconfigPathsDead: number, intentFindings: number,
  *   intentUnresolved: number, intentUnresolvedDecisionRefs: number, fitnessFail: number,
  *   fitnessUnknown: number, customRuleFail: number, customRuleUnknown: number,
@@ -521,6 +521,15 @@ export async function check(
   // from the MARKER (the line a reader edits is the document's), project and
   // constraint from the edge — so suppression, waiver annotation, sorting and
   // the SARIF face all treat it as the ordinary violation it is.
+  //
+  // PD-13 (2026-09-06) pins THIS fold as the documented normalization seam
+  // (`../../../../docs/architecture/refactor/DECISIONS.md`): the one place
+  // `judgeEdge`'s markdown-pairing verdicts are reshaped into the exact
+  // `Violation` record `violationOf` (`../rules/index.mjs`) builds — the
+  // families then fold into the one verdict lane as count keys into
+  // `verdictFor` (`../verdict.mjs`). The canonical statement is the
+  // "Finding — the unowned concept" section of
+  // `../../../../docs/architecture/refactor/SEMANTIC-MODEL.md`.
   /** @type {object[]} */
   const markdownRaw = [];
   if (config !== null && markdownTrack !== null && config.depConstraints.length > 0) {
@@ -1289,6 +1298,7 @@ export async function check(
         });
 
   return {
+    exitCode: verdict.exitCode,
     report,
     violations: violations.length,
     waived,
@@ -1311,8 +1321,8 @@ export async function check(
     customRulesDeclared: customRules !== null,
     analyzed,
     unchecked,
-    // The site-level count `verdictFor` needs: `cli.mjs` passes this whole
-    // return through `verdictFor` for the process's exit code, so a count the
+    // The exit authority is `verdict` above, surfaced on this return: the
+    // process exit code comes straight from this field, so a count the
     // envelope saw but the exit code did not would let the two disagree.
     blindSpots: blindSpotCount,
   };

package/src/commands/compare-capability.mjs

@@ -0,0 +1,20 @@
+/**
+ * `compare` capability facade — the word's verb roster as explicit named
+ * re-exports: `diff`, `delta` (both modes), `change`, `drift`, `reconcile`,
+ * `history`, `trajectory`, `evolution`, plus the output guards the two
+ * verbs that write reports declare (`change`, `history`, `trajectory`).
+ *
+ * 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 { diff } from "./diff.mjs";
+export { captureBaseline, delta } from "./delta.mjs";
+export { change, changeOutputRefusal } from "./change.mjs";
+export { drift } from "./drift.mjs";
+export { reconcileCommand } from "./reconcile.mjs";
+export { history, historyOutputRefusal } from "./history.mjs";
+export { trajectoryCommand, trajectoryOutputRefusal } from "./trajectory.mjs";
+export { evolutionCommand } from "./evolution.mjs";

package/src/commands/completeness.mjs

@@ -24,6 +24,18 @@
  * `overallComplete` implies ALL gates pass. Any failed gate MUST prevent
  * `overallComplete = true`.
  *
+ * ## Not the coverage refusal (register R1)
+ *
+ * These statuses grade the composed evaluation — how completely the
+ * Evidence-Complete gates were satisfied for the statement being made. A
+ * different question is whether the run saw enough input to make any claim
+ * at all, and that one is answered only by the graph family's shared
+ * refusal contract (`./coverage-verdict.mjs`): `coverageVerdict` refuses
+ * `no-verdict` (exit 3), and no status here is derived from it or folds
+ * into it. Two models of "did we see everything", owned by different
+ * waves — register R1 in `docs/architecture/refactor/SEMANTIC-MODEL.md`
+ * keeps them separate.
+ *
  * @module
  */
 

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-snapshot.mjs

@@ -274,7 +274,9 @@ export function buildEvidenceSnapshot({
  * order is the only order the format keeps, and `buildEvidenceSnapshot` sorts
  * every array whose source does not guarantee it. Two captures over one
  * unchanged tree produce byte-identical files, which is what makes a plain
- * `diff` of two baselines meaningful.
+ * `diff` of two baselines meaningful. That determinism is also why this
+ * family carries no identity field, by decision: the bytes are the identity
+ * (`../../../../docs/adr/0008-snapshot-identity-per-family.md`).
  *
  * @param {object} snapshot From `buildEvidenceSnapshot`.
  * @returns {string} The JSON text, newline-terminated.
@@ -330,7 +332,11 @@ export function readEvidenceSnapshot(path, io = {}) {
  * What is deliberately NOT a refusal: dirty base provenance. A baseline from
  * an uncommitted tree is weaker evidence, not unreadable evidence — the parsed
  * snapshot exposes `provenance.dirty` so the renderer can say so loudly, and
- * classification itself proceeds.
+ * classification itself proceeds. A dirty BIT that is not a boolean is a
+ * different thing — malformed, not weaker: the gates read `dirty === true`
+ * while the renderers interpolate truthiness, so any other type would read
+ * clean to some consumers and dirty to others. The provenance block below
+ * refuses it by name.
  *
  * @param {string} text The file contents.
  * @param {string} path The path the text came from, for error messages.
@@ -392,8 +398,23 @@ export function parseEvidenceSnapshot(text, path) {
 
   if (parsed.provenance !== null && !isPlainObject(parsed.provenance)) {
     problems.push("provenance: must be an object ({commit, remote, dirty}) or null");
-  } else if (isPlainObject(parsed.provenance) && typeof parsed.provenance.commit !== "string") {
-    problems.push("provenance.commit: must be a string when provenance is present");
+  } else if (isPlainObject(parsed.provenance)) {
+    if (typeof parsed.provenance.commit !== "string") {
+      problems.push("provenance.commit: must be a string when provenance is present");
+    }
+    if (parsed.provenance.remote !== null && typeof parsed.provenance.remote !== "string") {
+      problems.push("provenance.remote: must be a string or null when provenance is present");
+    }
+    if (typeof parsed.provenance.dirty !== "boolean") {
+      // Malformed, not weaker: the gates read `dirty === true` while the
+      // renderers interpolate truthiness, so a value of any other type reads
+      // clean to some consumers and dirty to others — the one disagreement
+      // this record must never carry.
+      problems.push(
+        "provenance.dirty: must be a boolean when provenance is present — the gates decide " +
+          "between committed and uncommitted evidence on this bit",
+      );
+    }
   }
 
   if (typeof parsed.policyFingerprint !== "string" || parsed.policyFingerprint === "") {