@ecoma-io/archkeep 0.24.1 → 0.26.0

package/commands.mjs

@@ -25,7 +25,12 @@
  * one. What is deliberately absent: the `run*` drivers and argv parsing
  * (`cli.mjs` alone owns what a process's stdout and exit code mean), and the
  * renderers (`src/report/` shapes bytes for humans; an importer reads the
- * envelopes the commands already return).
+ * envelopes the commands already return). `adrForWorkspace`
+ * (`./src/commands/adr-for-workspace.mjs`) is on the roster without bending
+ * that: it composes the workspace preamble two faces (`cli.mjs`'s `runAdr`
+ * and the MCP history adapter) used to duplicate — one of them past this
+ * subpath — and returns exactly what `adrCommand` returns, printing no byte
+ * and deciding no exit code of its own.
  *
  * The seams the CLI threads are threaded the same way here: `readGraph` and
  * `listFiles` are injectable on every entry point that reaches outside the
@@ -45,6 +50,7 @@ export { driftCommand } from "./src/commands/drift.mjs";
 export { planContextCommand } from "./src/commands/plan-context-command.mjs";
 export { historyCommand } from "./src/commands/history.mjs";
 export { adrCommand } from "./src/commands/adr.mjs";
+export { adrForWorkspace } from "./src/commands/adr-for-workspace.mjs";
 export { discoverCommand } from "./src/commands/discover.mjs";
 export { reconcileCommand } from "./src/commands/reconcile.mjs";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.24.1",
+  "version": "0.26.0",
   "description": "Architecture authority for human and agentic software development — deterministic, evidence-backed enforcement of declared architecture.",
   "keywords": [
     "architecture",

package/src/architecture-intent/judge.mjs

@@ -34,7 +34,7 @@ import { buildReachability, getPath, pathExists } from "../../src/rules/reachabi
 /**
  * What a finding means — one entry per `messageId`, the arrangement
  * `../../src/report/sarif.mjs` derives its rule descriptors from, the same as
- * `../../src/go-work.mjs` and `../../src/tsconfig-paths.mjs`.
+ * the per-domain tables in `../rules/messages.mjs`.
  */
 export const INTENT_MESSAGES = Object.freeze({
   intentForbiddenEdge:

package/src/architecture-intent/model.mjs

@@ -11,6 +11,17 @@
  * observed architecture stays the graph Archkeep derives from source; governance
  * is a deterministic comparison (`./judge.mjs`). NO LLM/AI anywhere in the core.
  *
+ * Which "intent" this is: one of four unrelated surfaces sharing the word —
+ * PD-13 outcome (c), four surfaces, never one type
+ * (`../../../../docs/architecture/refactor/DECISIONS.md`). This module is
+ * the workspace-declared law: the grammar, validation, and loading of
+ * `architecture-intent.json`, judged against the observed graph by `check`
+ * and `drift`. The other three: the v1.0 evidence-manifest registry
+ * (`../intent/` — `intent-manifest.json` and its executable gate), the
+ * declared-change grammar (`../commands/change-intent.mjs`, one change's
+ * expected consequences, verified by the `change` command), and the fileless
+ * run-envelope intent shape (`result.intent` in a `--format json` envelope).
+ *
  * This module mirrors `../../config.mjs`'s and
  * `../../providers/native/model.mjs`'s split: a pure `(raw) -> string[]`
  * validator and a thin loader that reads, parses, validates and throws — one
@@ -696,3 +707,26 @@ export async function loadIntent(root, { read = readFileFromDisk, tracked } = {}
   }
   return normalizeIntent(raw);
 }
+
+/**
+ * The driver gate over `loadIntent`: load the workspace's declared law only
+ * when the tracked-file list names it, `null` otherwise.
+ *
+ * Three `cli.mjs` drivers (decisions, health, report) need the same answer:
+ * an intent file `git ls-files` does not list is absence — the callers render
+ * their no-intent face — while a tracked-but-unreadable file is a no-verdict
+ * throw that the shared catch folds to exit 3. The membership pre-test is a
+ * pure equivalence, not a containment guard: `loadIntent` early-returns for
+ * untracked input before any containment check, so this helper changes no
+ * verdict on any input.
+ *
+ * @param {string} root Absolute workspace root.
+ * @param {string[]} tracked The `git ls-files` list.
+ * @returns {Promise<object|null>} The normalized, validated model, or `null`
+ *   when the file is not tracked.
+ * @throws {Error} exactly what `loadIntent` throws — tracked-but-unreadable
+ *   stays a no-verdict, never absence.
+ */
+export async function loadIntentIfTracked(root, tracked) {
+  return tracked.includes(INTENT_FILE) ? loadIntent(root, { tracked }) : null;
+}

package/src/canonical.mjs

@@ -11,7 +11,8 @@
  * correct.
  *
  * Used by `computePolicyFingerprint` (`../commands/graph.mjs`), the intent
- * fingerprint (`./intent-fingerprint.mjs`), the evidence-snapshot serializer
+ * fingerprint (`./architecture-intent/intent-fingerprint.mjs`), the
+ * evidence-snapshot serializer
  * (`./commands/delta-snapshot.mjs`, through the exported replacer below), and
  * anything else a fingerprint or a byte-deterministic file is produced from —
  * one canonicalizer, in one place, so two serializations cannot drift.

package/src/commands/adr-for-workspace.mjs

@@ -0,0 +1,63 @@
+/**
+ * The `adr` preamble, composed once: the workspace root walked up from a
+ * working directory, the tracked file list, then `./adr.mjs`'s `adrCommand`.
+ * `../../cli.mjs`'s `runAdr` and the MCP history adapter
+ * (`../../../archkeep-mcp/src/engine.mjs`) each inlined these three steps,
+ * and the adapter's copy reached past the `./commands` subpath into the
+ * engine's root entry for `findWorkspaceRoot` and `listTrackedFiles` — the
+ * one import in that package that made it something other than a client of
+ * the command layer. The composition lives here, beside the command it
+ * feeds, so both faces run one path and neither needs the root entry for it.
+ *
+ * It holds no policy of its own. The two preamble decisions move verbatim,
+ * because inventing either here would be a second opinion about what a
+ * workspace is:
+ *
+ * - the root is `findWorkspaceRoot(cwd, WORKSPACE_MARKERS)` — the same
+ *   marker list `./context.mjs`'s `resolveCommandContext` walks, whose own
+ *   header owns why callers of a workspace root may not differ in what a
+ *   workspace root IS;
+ * - the files are `(io.listFiles ?? listTrackedFiles)(root)` — the injectable
+ *   default every command reads through, so a test drives the read over a
+ *   fixture tree with no git.
+ *
+ * Everything a caller might decide stays with the caller. The `null` — no
+ * ancestor of `cwd` is a workspace root — is the caller's refusal to render,
+ * never an answer: the CLI words its own refusal and picks its own exit
+ * code, the adapter throws its own, and a caller that ignored the null
+ * crashes one line later instead of reading a clean result. The throws
+ * (`adrCommand`'s unreadable registry, `listTrackedFiles`' failed
+ * `git ls-files`) propagate unchanged for the same reason. And it prints no
+ * byte and decides no exit code, so it is not one of the `run*` drivers
+ * `../../commands.mjs` leaves to `../../cli.mjs` — it returns exactly what
+ * the command returns.
+ */
+import { findWorkspaceRoot, listTrackedFiles } from "../workspace.mjs";
+
+import { adrCommand } from "./adr.mjs";
+import { WORKSPACE_MARKERS } from "./context.mjs";
+
+/**
+ * Runs the `adr` command for the workspace `cwd` falls in.
+ *
+ * @param {{cwd: string}} request The working directory the root is walked up
+ *   from — the same walk `resolveCommandContext` makes, without the project
+ *   graph it builds.
+ * @param {{id?: string}} [options] Forwarded to `adrCommand` unchanged.
+ * @param {{listFiles?: Function}} [io] The tracked-file seam, typed like
+ *   every command's (`Function`, the shape `./check.mjs` and
+ *   `./context.mjs` declare), defaulted to `git ls-files`
+ *   (`../workspace.mjs`) — injected where a test answers for git.
+ * @returns {object|null} What `adrCommand` returns, verbatim; `null` when no
+ *   ancestor of `cwd` is a workspace root — the caller's refusal to render,
+ *   never a clean answer (the module header owns why the message is not
+ *   worded here).
+ * @throws {Error} on an unreadable registry or a failed `git ls-files`,
+ *   exactly as `adrCommand` and `listTrackedFiles` throw — each caller maps
+ *   that the way it already did.
+ */
+export function adrForWorkspace({ cwd }, options = {}, io = {}) {
+  const root = findWorkspaceRoot(cwd, WORKSPACE_MARKERS);
+  if (root === null) return null;
+  return adrCommand(root, options, { tracked: (io.listFiles ?? listTrackedFiles)(root) });
+}

package/src/commands/analyze-capability.mjs

@@ -0,0 +1,13 @@
+/**
+ * `analyze` capability facade — the word's verb roster as explicit named
+ * re-exports: `discover`, with the two proposal→intent steps the
+ * `--write-intent` lane drives — the serialized bytes and the target
+ * refusal.
+ *
+ * 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 { discoverCommand, intentJsonFromProposal, intentWriteRefusal } from "./discover.mjs";

package/src/commands/change-intent.mjs

@@ -9,6 +9,17 @@
  * architectural delta (`./change.mjs`), and then belongs to the pull request
  * as the reviewable answer to "what did this change do to the architecture?".
  *
+ * Which "intent" this is: one of four unrelated surfaces sharing the word —
+ * PD-13 outcome (c), four surfaces, never one type
+ * (`../../../../docs/architecture/refactor/DECISIONS.md`). This module is
+ * the declared-change grammar: one change's expected architectural
+ * consequences, verified by the `change` command against the actual delta.
+ * The other three: the workspace-declared law (`../architecture-intent/` —
+ * the `architecture-intent.json` file this module deliberately does not
+ * extend, per the paragraph below), the v1.0 evidence-manifest registry
+ * (`../intent/`), and the fileless run-envelope intent shape
+ * (`result.intent` in a `--format json` envelope).
+ *
  * This file mirrors `../architecture-intent/model.mjs`'s split — a pure
  * `(raw) -> string[]` validator, a thin loader that reads, parses, validates
  * and throws one Error naming every violation at once — and deliberately does

package/src/commands/change.mjs

@@ -101,14 +101,17 @@ import {
 } from "./delta.mjs";
 import { providerMismatch, readEvidenceSnapshot } from "./delta-snapshot.mjs";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
+import { isAbsolute, resolve } from "node:path";
 import { blindSpotRows } from "../analysis/source-util.mjs";
 import { cyclicProjects } from "../governance/fitness-rules.mjs";
-import { fitnessVerdict } from "../governance/verdict.mjs";
+import { eventSnapshotSide } from "./history.mjs";
+import { VERDICTS, fitnessVerdict, isVerdict } from "../governance/verdict.mjs";
+import { describe, isStringArray } from "../values.mjs";
 import { buildDecision } from "../report/evidence.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatChangeReport } from "../report/change-text.mjs";
 import { evaluateRun } from "../rules/index.mjs";
-import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
+import { compareSnapshotMetadata, dirtyBaselineNote, dirtyHeadNote } from "./snapshot-meta.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import {
@@ -124,6 +127,8 @@ import { writeEvent } from "../governance/evolution-store.mjs";
 import { judgeIntent } from "../architecture-intent/judge.mjs";
 import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
 import { debtChangeDiff } from "../governance/debt-ledger.mjs";
+import { resolveCommandContext } from "./context.mjs";
+import { resolvePolicy } from "./policy.mjs";
 
 /**
  * One expected-fact row as the report and JSON carry it. Kept in one builder
@@ -368,6 +373,9 @@ function reconciliationVerdict(lists, unprovenReasons) {
   return "matched";
 }
 
+/** The verdict axis `reconcileDisposition` maps — the four `reconciliationVerdict` answers. */
+const RECONCILE_VERDICTS = Object.freeze(["matched", "undeclared", "unfulfilled", "unproven"]);
+
 /**
  * The reconcile DISPOSITION mapping (wave 3, design §5) — the verdict axis
  * first, then the declared constraints' verdicts. Pure and exported so the
@@ -390,8 +398,33 @@ function reconciliationVerdict(lists, unprovenReasons) {
  *   this run — empty when none were declared or when the base identity was
  *   unproven (constraints are left unevaluated then).
  * @returns {"accepted"|"rejected"|"no-verdict"}
+ * @throws {Error} on an axis value outside the four, or a constraint row
+ *   whose verdict is outside the canonical vocabulary — a stranger would fold
+ *   to `accepted`, and a fabricated acceptance is the one answer this mapping
+ *   never hands out.
  */
 export function reconcileDisposition(verdict, constraints = []) {
+  // The mapping owns its input latch — it is exported and pure, the one place
+  // the precedence is stated, and a stranger axis value would match no named
+  // arm and land on `accepted`: a fabricated acceptance, the one answer this
+  // function must never hand out over input it did not understand.
+  if (!RECONCILE_VERDICTS.includes(verdict)) {
+    throw new Error(
+      `archkeep: refusing to map a reconcile verdict ${describe(verdict)} — ` +
+        `expected one of ${RECONCILE_VERDICTS.join(", ")}. This is a bug in the ` +
+        `reconciliation that produced it.`,
+    );
+  }
+  // Same latch one axis down: a constraint row verdict outside the four states
+  // matches neither `unknown` nor `fail`, and the mapping reads it as consent.
+  for (const row of constraints) {
+    if (!isVerdict(row.verdict)) {
+      throw new Error(
+        `archkeep: refusing to map a constraint row whose verdict is ${describe(row.verdict)} — ` +
+          `expected one of ${VERDICTS.join(", ")}. This is a bug in the judge that built the row.`,
+      );
+    }
+  }
   // used by its own test
   if (verdict === "unproven") return "no-verdict";
   if (verdict === "undeclared" || verdict === "unfulfilled") return "rejected";
@@ -400,6 +433,124 @@ export function reconcileDisposition(verdict, constraints = []) {
   return "accepted";
 }
 
+/**
+ * The input latch for `changeFold`: names the first way its inputs are not a
+ * shape the fold can count, or `null` when they are. A returned problem
+ * becomes the fold's refusal — never a throw, the same in-band lane
+ * `deltaFold`'s latch takes one module over.
+ *
+ * @param {object} reconciliation From `reconcileMaterialDelta`.
+ * @param {object[]} constraints Judged `fitnessVerdict` rows.
+ * @param {string[]} unprovenReasons Why the base identity could not be proven.
+ * @returns {string|null}
+ */
+function changeFoldInputProblem(reconciliation, constraints, unprovenReasons) {
+  for (const key of ["matched", "unexpected", "missingExpected"]) {
+    if (!Array.isArray(reconciliation?.[key])) {
+      return `the change fold counts "reconciliation.${key}", which is ${describe(reconciliation?.[key])} — a list that is not an array counts as empty in every lane, and an empty reconciliation reads "matched". This is a bug in archkeep, not a fact about the workspace.`;
+    }
+  }
+  if (!Array.isArray(constraints)) {
+    return `the change fold counts "constraints", which is ${describe(constraints)} — a list that is not an array counts as empty in every lane, and an empty constraint list reads "every declared constraint passing". This is a bug in archkeep, not a fact about the workspace.`;
+  }
+  for (const [index, row] of constraints.entries()) {
+    if (!isVerdict(row?.verdict)) {
+      return `the change fold counts the verdict of constraint row ${index}, which is ${describe(row?.verdict)} — a verdict outside ${VERDICTS.join(", ")} matches neither the fail nor the unknown lane, and reads as consent. This is a bug in archkeep, not a fact about the workspace.`;
+    }
+  }
+  if (!isStringArray(unprovenReasons)) {
+    return `the change fold reads "unprovenReasons", which is ${describe(unprovenReasons)} — reasons that are not a string array read as "no reasons" below, and an unproven base then reads "matched". This is a bug in archkeep, not a fact about the workspace.`;
+  }
+  return null;
+}
+
+/**
+ * The `change` exit fold, lifted out of `changeCommand` as a pure function so
+ * the mapping from the reconciliation lists and the judged constraints to the
+ * verdict is a fact a test can pin (`reconcileDisposition` directly above is
+ * the arrangement's precedent — it latches the EVENT disposition; this is the
+ * STATUS fold the envelope and the exit code read). Lane order: an unproven
+ * base identity or any undetermined constraint → `no-verdict`/3; else any
+ * unexpected fact, missing expected fact, or failed constraint →
+ * `findings`/1; else `ok`/0.
+ *
+ * The input latch runs first: input the fold cannot read is refused as a
+ * no-verdict whose single reason names it (`refused`), never folded past as a
+ * silently-empty count — `reconciliationVerdict` reads `unprovenReasons`
+ * before any list, so a malformed one reaching it unguarded can name the
+ * whole run unproven or matched for reasons the counts never supported. 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`).
+ *
+ * @param {{matched: object[], unexpected: object[], missingExpected: object[]}} reconciliation
+ * @param {{verdict: string}[]} constraints Judged `fitnessVerdict` rows —
+ *   empty when none were declared or the base identity was unproven.
+ * @param {string[]} unprovenReasons Why the base identity could not be proven.
+ * @returns {{status: "ok"|"findings"|"no-verdict", exitCode: 0|1|3,
+ *   decision: object, verdict: "matched"|"undeclared"|"unfulfilled"|"unproven",
+ *   refused?: undefined}|
+ *   {status: "no-verdict", exitCode: 3, decision: object, verdict?: undefined,
+ *   refused: string}}
+ *   `verdict` rides every judged lane because the event's `declaredIntentRows`
+ *   and `result.reconciliation` report it whichever lane fired; a refusal
+ *   carries `refused` and no verdict, and is the one return whose
+ *   `decision.reason` names a malformed input rather than a fact about the
+ *   trees.
+ */
+export function changeFold(reconciliation, constraints, unprovenReasons) {
+  const problem = changeFoldInputProblem(reconciliation, constraints, unprovenReasons);
+  if (problem !== null) {
+    return {
+      status: "no-verdict",
+      exitCode: 3,
+      decision: buildDecision({
+        status: "no-verdict",
+        coverageComplete: true,
+        findings: 0,
+        reason: problem,
+      }),
+      refused: problem,
+    };
+  }
+  const verdict = reconciliationVerdict(reconciliation, unprovenReasons);
+  const failedConstraints = constraints.filter((row) => row.verdict === "fail").length;
+  const unknownConstraints = constraints.filter((row) => row.verdict === "unknown").length;
+  const findings =
+    reconciliation.unexpected.length + reconciliation.missingExpected.length + failedConstraints;
+
+  if (verdict === "unproven" || unknownConstraints > 0) {
+    return {
+      status: "no-verdict",
+      exitCode: 3,
+      decision: buildDecision({
+        status: "no-verdict",
+        coverageComplete: true,
+        findings: 0,
+        reason:
+          verdict === "unproven"
+            ? `the change intent could not be verified against the declared base: ${unprovenReasons[0]}`
+            : `${unknownConstraints} declared constraint${unknownConstraints === 1 ? "" : "s"} could not be determined`,
+      }),
+      verdict,
+    };
+  }
+  if (findings > 0) {
+    return {
+      status: "findings",
+      exitCode: 1,
+      decision: buildDecision({ status: "findings", coverageComplete: true, findings }),
+      verdict,
+    };
+  }
+  return {
+    status: "ok",
+    exitCode: 0,
+    decision: buildDecision({ status: "ok", coverageComplete: true, findings: 0 }),
+    verdict,
+  };
+}
+
 /**
  * Judges the constraints the contract declares, through the shared engine —
  * both sides re-judged under the CURRENT law and one shared instant, exactly
@@ -509,7 +660,7 @@ function judgeDeclaredConstraints(intent, io) {
  *   architecture-intent seam `drift` uses (defaults to `loadIntent`); the
  *   change event's `debt` diff judges the intent over this run's base and
  *   head graphs and would be untestable without it.
- * @returns {Promise<{status: "ok"|"findings"|"no-verdict",
+ * @returns {Promise<{status: "ok"|"findings"|"no-verdict", exitCode: 0|1|3,
  *   changeIntent?: object, coverage: object, report: {text: string, json: string}}>}
  *   `status: "no-verdict"` from the coverage refusal (#608) carries no
  *   `changeIntent` payload — the reconciliation was withheld, and the
@@ -648,6 +799,28 @@ export async function changeCommand(
     dependencies: buildDependencies(graph.dependencies),
   };
   const structural = computeDiff(baseGraphForDiff, headGraphForDiff);
+  // The event's identity sides are frozen HERE — at the same instant the diff
+  // above was computed from these same graph objects — so the identity always
+  // describes the graph the diff actually compared. Everything between this
+  // line and the event assembly (constraint re-judgement, custom rules,
+  // classification, debt) reads the graphs too; the engine's purity is what
+  // keeps them honest today, but the WS-I adversarial audit named the seam:
+  // identity and diff agreeing must not rest on purity conventions alone when
+  // one structural line closes it.
+  const baseCommit = baseline.provenance?.commit;
+  const headCommit = headProvenance?.commit;
+  const eventBase = eventSnapshotSide({
+    revision: baseCommit,
+    projects: baseGraphForDiff.projects,
+    dependencies: baseGraphForDiff.dependencies,
+    policyFingerprint: baseline.policyFingerprint,
+  });
+  const eventHead = eventSnapshotSide({
+    revision: headCommit,
+    projects: headGraphForDiff.projects,
+    dependencies: headGraphForDiff.dependencies,
+    policyFingerprint: headFingerprint,
+  });
   const reconciliation = reconcileMaterialDelta(intent, structural);
 
   // Constraints and the law axis are computed over both sides re-judged under
@@ -694,38 +867,13 @@ export async function changeCommand(
     liveViolations = headEval.violations.length;
   }
 
-  const verdict = reconciliationVerdict(reconciliation, unprovenReasons);
-  const failedConstraints = constraints.filter((row) => row.verdict === "fail").length;
-  const unknownConstraints = constraints.filter((row) => row.verdict === "unknown").length;
-  const findings =
-    reconciliation.unexpected.length + reconciliation.missingExpected.length + failedConstraints;
-
-  /** @type {"ok"|"findings"|"no-verdict"} */
-  let status;
-  /** @type {0|1|3} */
-  let exitCode;
-  let decision;
-  if (verdict === "unproven" || unknownConstraints > 0) {
-    status = "no-verdict";
-    exitCode = 3;
-    decision = buildDecision({
-      status,
-      coverageComplete: true,
-      findings: 0,
-      reason:
-        verdict === "unproven"
-          ? `the change intent could not be verified against the declared base: ${unprovenReasons[0]}`
-          : `${unknownConstraints} declared constraint${unknownConstraints === 1 ? "" : "s"} could not be determined`,
-    });
-  } else if (findings > 0) {
-    status = "findings";
-    exitCode = 1;
-    decision = buildDecision({ status, coverageComplete: true, findings });
-  } else {
-    status = "ok";
-    exitCode = 0;
-    decision = buildDecision({ status, coverageComplete: true, findings: 0 });
-  }
+  // The verdict comes from the one fold — `changeFold` above owns the lane
+  // order and the input latch — but it is TAKEN after the notes and coverage
+  // blocks below, so a refusal can carry the disclosures (policy-changed,
+  // dirty sides) the run already computed: a withheld verdict that dropped
+  // them would hide a weaker-evidence fact from the only envelope the run
+  // emits. Nothing between this comment and the fold call reads the fold's
+  // inputs or outputs.
 
   /** @type {string[]} */
   const notes = [];
@@ -736,16 +884,10 @@ export async function changeCommand(
     );
   }
   if (meta.dirtyBaseline) {
-    notes.push(
-      "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
-        "claim about the commit the contract pins",
-    );
+    notes.push(dirtyBaselineNote(true));
   }
   if (meta.dirtyHead) {
-    notes.push(
-      "this run's working tree is dirty — the head side describes uncommitted state, not the " +
-        "commit HEAD names",
-    );
+    notes.push(dirtyHeadNote());
   }
   if (meta.provenanceOneSided) {
     notes.push(
@@ -769,6 +911,40 @@ export async function changeCommand(
     notes,
   };
 
+  // The exit fold, at the input boundary: input the fold cannot read is
+  // refused in-band (no-verdict, exit 3, the field named), never counted past
+  // as a silently-empty list. The refusal withholds `result` and the event
+  // exactly the coverage refusal does: a comparison whose counts could not be
+  // read has no verdict to report, and the refusal rides the envelope beside
+  // the coverage notes the run already earned.
+  const fold = changeFold(reconciliation, constraints, unprovenReasons);
+  if (fold.refused !== undefined) {
+    const refusalCoverage = { ...coverage, notes: [...notes, fold.refused] };
+    return {
+      status: fold.status,
+      exitCode: fold.exitCode,
+      coverage: refusalCoverage,
+      report: {
+        text: `change: no verdict — ${fold.refused}\n`,
+        json: renderJson(
+          jsonEnvelope({
+            command: "change",
+            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,
+          }),
+        ),
+      },
+    };
+  }
+  const { status, exitCode, decision, verdict } = fold;
+
   // Wave 3 (design §1, §2, §5): the evolution classification and the reconcile
   // event. The classification is ALWAYS computed — it rides the envelope
   // result in memory even when no event is written (design §4) — and the
@@ -855,23 +1031,24 @@ export async function changeCommand(
     }
   }
 
-  const baseCommit = baseline.provenance?.commit;
-  const headCommit = headProvenance?.commit;
   /** @type {object} */
   const event = {
     schemaVersion: EVOLUTION_EVENT_SCHEMA_VERSION,
     kind: "reconcile",
     source: "change",
-    base: {
-      ...(typeof baseCommit === "string" ? { revision: baseCommit } : {}),
-      // The caller's own evidence ref — the baseline file this run consumed,
-      // spelled as the run received it (the same convention `declaration.file`
-      // uses for the intent path).
-      evidence: baselinePath,
-    },
-    head: {
-      ...(typeof headCommit === "string" ? { revision: headCommit } : {}),
-    },
+    // Both sides were frozen through the ONE identity spelling
+    // (`eventSnapshotSide`, ./history.mjs) at the diff site above: a revision
+    // when one is known, plus the snapshot identity of the graph the diff
+    // compared — never the baseline's storage path, which is machine-local
+    // and must not make the identity a per-machine property.
+    base: eventBase,
+    head: eventHead,
+    // The caller's own evidence ref — the baseline file this run consumed,
+    // spelled as the run received it (the same convention `declaration.file`
+    // uses for the intent path). Disclosed OUTSIDE the identity: the tuple
+    // above names the state itself, so a relocated baseline is still the
+    // same event.
+    evidence: baselinePath,
     declaration: { file: intentPath, digest: declarationDigest(intent) },
     observed,
     affected: evolution.affected,
@@ -983,6 +1160,7 @@ export async function changeCommand(
 
   return {
     status,
+    exitCode,
     changeIntent: result,
     coverage,
     report: {
@@ -997,3 +1175,85 @@ export async function changeCommand(
     },
   };
 }
+
+/**
+ * The paths `change` runs over, resolved once and shared by the CLI entry
+ * and the output guard below — one spelling of "where does this flag point",
+ * the same relative-to-cwd resolution every path flag uses.
+ *
+ * @param {{intent: string, paths: string[]}} options This run's parsed flags.
+ * @param {string} cwd The run's working directory.
+ * @returns {{baselinePath: string, intentPath: string}}
+ */
+function changePaths(options, cwd) {
+  return {
+    baselinePath: isAbsolute(options.paths[0]) ? options.paths[0] : resolve(cwd, options.paths[0]),
+    intentPath: isAbsolute(options.intent) ? options.intent : resolve(cwd, options.intent),
+  };
+}
+
+/**
+ * `change`'s self-footgun guard, the same shape `history`'s holds: writing
+ * the reconciliation report over the very manifest this run just read would
+ * destroy the declaration it verified, with the loss surfacing only later —
+ * the first time someone tries to re-run the verification. Declared by the
+ * command that owns the law and enforced by the driver's write door; `null`
+ * means no refusal.
+ *
+ * @param {{output: string|null, intent: string, 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 changeOutputRefusal(options, cwd) {
+  if (!options.output) return null;
+  const outputAbs = isAbsolute(options.output)
+    ? resolve(options.output)
+    : resolve(cwd, options.output);
+  if (outputAbs === changePaths(options, cwd).intentPath) {
+    return (
+      `archkeep: --output '${options.output}' resolves to the change-intent manifest itself — ` +
+      `overwriting the declaration with its own reconciliation report would destroy it. ` +
+      `Write the report somewhere else.`
+    );
+  }
+  return null;
+}
+
+/**
+ * `change` as the CLI drives it: the baseline and manifest paths resolved,
+ * then the shared preamble — command context, boundary law, the optional
+ * `--event-out` directory — so `../../cli.mjs`'s driver only wires options,
+ * IO seams, and where output lands (`./README.md`). The engine this returns
+ * from is `changeCommand` above, unchanged.
+ *
+ * @param {{config: string|null, eventOut?: string|null, intent: string, paths: string[]}} options
+ *   This run's parsed flags; `paths[0]` is the baseline evidence snapshot.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `changeCommand`'s result, unmodified.
+ */
+export async function change(options, { cwd, readGraph, listFiles }) {
+  const { baselinePath, intentPath } = changePaths(options, cwd);
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, listFiles });
+  // Declared constraints are judged under whichever law THIS run resolves,
+  // and the envelope records that law's fingerprint beside the baseline's —
+  // the same loading every judging command does (`resolvePolicy`),
+  // profile-aware the same way `check` is.
+  const { config } = await resolvePolicy(options, commandContext, cwd);
+  // `--event-out` names the reconcile event store directory, resolved from
+  // cwd like the other path flags; `undefined` when absent, so a run
+  // without the flag writes no event and stays byte-identical.
+  const eventOut =
+    typeof options.eventOut === "string" && options.eventOut !== ""
+      ? isAbsolute(options.eventOut)
+        ? options.eventOut
+        : resolve(cwd, options.eventOut)
+      : undefined;
+  return changeCommand(baselinePath, intentPath, commandContext, {
+    config,
+    ...(eventOut === undefined ? {} : { eventOut }),
+  });
+}