@ecoma-io/archkeep 0.13.0 → 0.15.0

package/cli.mjs

@@ -51,15 +51,19 @@
  * tree is dirty" from "you typed it wrong" from "the checker itself broke":
  *   0  no violations, and every selected file was analyzed
  *   1  findings — boundary violations, go.work drift, dead tsconfig path
- *      aliases, or architecture-intent findings. `check` is the only command
- *      that can produce this exit code — every other verb this table might grow
+ *      aliases, architecture-intent findings, a non-waived violation `delta`
+ *      classifies as introduced, or a change-intent reconciliation that found
+ *      undeclared material changes, unfulfilled declarations, or a failed
+ *      declared constraint. `check`, `fitness`, `delta` and `change` are the
+ *      verbs whose verdicts carry this code — every other verb in this table
  *      only ever reads.
  *   2  usage error — unknown command, unknown flag, missing argument, path
  *      outside the tree
  *   3  no verdict — no workspace, malformed config, the graph provider or git
  *      failed, a selected file could not be analyzed, an architecture-intent
- *      boundary matched no observed project, or a `boundarySuppressions` row
- *      accepts nothing this run judged. Distinct from
+ *      boundary matched no observed project, a `boundarySuppressions` row
+ *      accepts nothing this run judged, or a change intent could not be
+ *      verified against its declared base. Distinct from
  *      1 on purpose: a checker that could not look must never be mistaken for
  *      one that looked and found nothing.
  *
@@ -93,7 +97,7 @@ import { dirname, isAbsolute, join, resolve } from "node:path";
 import { containmentViolation } from "./src/containment.mjs";
 import { UsageError } from "./src/errors.mjs";
 import { check, sortViolations } from "./src/commands/check.mjs";
-import { hasProfiles, resolvePolicy } from "./src/commands/policy.mjs";
+import { resolveDescribedPolicy, resolvePolicy } from "./src/commands/policy.mjs";
 import {
   DEFAULT_OPTIONS,
   WORKSPACE_MARKERS,
@@ -104,12 +108,16 @@ import { contextCommand } from "./src/commands/context-command.mjs";
 import { planContextCommand } from "./src/commands/plan-context-command.mjs";
 import { adrCommand } from "./src/commands/adr.mjs";
 import { diffCommand } from "./src/commands/diff.mjs";
+import { captureDelta, deltaCommand } from "./src/commands/delta.mjs";
 import { discoverCommand } from "./src/commands/discover.mjs";
 import { driftCommand } from "./src/commands/drift.mjs";
 import { fitnessCommand } from "./src/commands/fitness.mjs";
 import { reconcileCommand } from "./src/commands/reconcile.mjs";
+import { changeCommand } from "./src/commands/change.mjs";
 import { computePolicyFingerprint, graphCommand } from "./src/commands/graph.mjs";
 import { historyCommand } from "./src/commands/history.mjs";
+import { trajectoryCommand } from "./src/commands/trajectory.mjs";
+import { evolutionCommand } from "./src/commands/evolution.mjs";
 import { healthCommand } from "./src/commands/health.mjs";
 import { reportCommand } from "./src/commands/report.mjs";
 import { debtCommand } from "./src/commands/debt.mjs";
@@ -169,6 +177,16 @@ const CHECK_FORMATS = Object.freeze(["text", "sarif", "json"]);
  */
 const DESCRIBABLE_FORMATS = Object.freeze(["text", "json"]);
 
+/**
+ * Every format `delta --format` accepts. SARIF joins the two descriptive
+ * formats because `delta`'s compare mode is a gate that produces findings —
+ * the introduced bucket is exactly what a code-scanning upload annotates at
+ * head sites — while every other descriptive-family verb stays on
+ * `DESCRIBABLE_FORMATS`: none of them produces findings, and SARIF's
+ * `results[]` is a findings container.
+ */
+const DELTA_FORMATS = Object.freeze(["text", "sarif", "json"]);
+
 /**
  * Column `usage()`'s Options block aligns flag descriptions to. Matches the
  * hand-written text this table-driven rendering replaced, so deriving the
@@ -803,54 +821,14 @@ async function runGraph(options, { cwd, env }) {
     //
     // `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. It was, with exit 3: the
-    // workspace-default `boundaryConfig` is never absent on the Nx and Moon
-    // paths (`readPluginOptions` falls back to `DEFAULT_OPTIONS`, and Moon
-    // takes the same default by convention), so that arm of `resolvePolicy`
-    // fired unconditionally and a missing file became the command's exit code.
-    // `discover`, the other descriptive verb over the same graph, answered
-    // fine on the identical tree — and `graph` is what a workspace runs to see
-    // what Archkeep found, which is what it needs in order to WRITE a first
-    // policy.
-    //
-    // What is skipped is the load of a file that is NOT THERE. A boundary
-    // config that exists and will not load still fails the run, because an
-    // absent law and a broken one must not report alike; a `--config`, a
-    // profile, and an inline `archkeep.json` policy are explicit declarations
-    // and stay loud. Every command that JUDGES against the law keeps loading
-    // it unconditionally — making it optional for those would turn a missing
-    // file into a silent no-law run.
-    //
-    // `boundaryConfigDeclared` is what keeps this guard to the un-overridden
-    // default, and it is load-bearing rather than belt-and-braces. The name
-    // alone cannot answer it: `commandContext.options.boundaryConfig` is a
-    // string BOTH when it came from `./src/options.mjs`'s `DEFAULT_OPTIONS`
-    // and when the consumer WROTE it into `nx.json`'s plugin options or
-    // `archkeep.json`, and a workspace is free to declare the convention
-    // filename itself, so comparing against the default would still read a
-    // deliberate declaration as an assumption. Without the bit, measured on a
-    // committed native tree whose `archkeep.json` declares `boundaryConfig:
-    // "policy-we-declared.mjs"` and does not contain that file: `graph` exited
-    // 0 with a snapshot carrying no `policy` field — byte-identical to a
-    // workspace that never had a law — where the same tree with that file
-    // present but unparseable exited 3. A law someone named and then renamed
-    // or deleted is exactly the case that must stay loud, so the provenance
-    // survives the options layer instead (`./src/options.mjs`'s
-    // `resolveOptions`, `./src/providers/native/model.mjs`'s
-    // `normalizeNativeModel`, and `./src/commands/context.mjs`'s three
-    // branches carry it; Moon answers `false` because it has no table to
-    // declare one in).
-    const workspaceDefault =
-      !options.config &&
-      !hasProfiles(commandContext.options) &&
-      commandContext.options.boundaryConfigDeclared === false &&
-      typeof commandContext.options.boundaryConfig === "string"
-        ? resolve(commandContext.root, commandContext.options.boundaryConfig)
-        : null;
-    const { config } =
-      workspaceDefault !== null && !existsSync(workspaceDefault)
-        ? { config: null }
-        : await resolvePolicy(options, commandContext, cwd);
+    // 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` (`./src/commands/policy.mjs`) rather than
+    // here, so the descriptive commands and the MCP face that serves them
+    // cannot disagree about what "no law declared" means.
+    const { config } = await resolveDescribedPolicy(options, commandContext, cwd);
 
     result = graphCommand(commandContext, { config });
   } catch (error) {
@@ -941,6 +919,98 @@ async function runDiff(options, { cwd, env }) {
   return EXIT.ok;
 }
 
+/**
+ * `delta`'s `run`: two modes behind one verb.
+ *
+ * `--capture` writes the evidence snapshot a later run compares against;
+ * `delta <baseline>` loads one, re-judges both sides under the current law,
+ * and folds the classification into the exit code — the one descriptive-family
+ * verb beside `check` and `fitness` whose verdict carries exit 1
+ * (`./src/commands/delta.mjs` owns the fold).
+ *
+ * @param {{format: string, output: string|null, config: string|null, capture: boolean,
+ *   paths: string[]}} options
+ * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
+ * @returns {Promise<number>}
+ */
+async function runDelta(options, { cwd, env }) {
+  if (options.capture) {
+    if (options.paths.length !== 0) {
+      env.err(
+        `archkeep: delta --capture takes no positional arguments; got ${options.paths.join(", ")}`,
+      );
+      return EXIT.usage;
+    }
+  } else if (options.paths.length !== 1) {
+    env.err(
+      `archkeep: delta takes exactly one positional argument (the baseline evidence snapshot), ` +
+        `or --capture to write one; got ${options.paths.length}`,
+    );
+    return EXIT.usage;
+  }
+
+  let result;
+  try {
+    const commandContext = resolveCommandContext(
+      { cwd },
+      { readGraph: env.readGraph, listFiles: env.listFiles },
+    );
+
+    // Both modes need the boundary law: capture fingerprints it, compare
+    // re-judges both sides under it — the same ladder every judging command
+    // resolves through (`resolvePolicy`).
+    const { config } = await resolvePolicy(options, commandContext, cwd);
+
+    if (options.capture) {
+      const { text } = captureDelta(commandContext, { config });
+      if (options.output) {
+        // Atomic, symlink-safe write — `writeOutputReport`'s own docstring
+        // owns the mechanism and the threat it closes.
+        if (!writeOutputReport(options.output, text, env, cwd, options.config)) return EXIT.error;
+        env.err(`archkeep: delta baseline captured → ${options.output}`);
+      } else {
+        env.out(text);
+      }
+      // Capture is descriptive: 0 on success, 3 on any failure, never 1.
+      return EXIT.ok;
+    }
+
+    const baselinePath = isAbsolute(options.paths[0])
+      ? resolve(options.paths[0])
+      : resolve(cwd, options.paths[0]);
+    result = await deltaCommand(baselinePath, commandContext, { config });
+  } catch (error) {
+    const usageError = error instanceof UsageError;
+    env.err(String(error?.message ?? error));
+    return usageError ? EXIT.usage : EXIT.error;
+  }
+
+  const report =
+    options.format === "json"
+      ? result.report.json
+      : options.format === "sarif"
+        ? result.report.sarif
+        : result.report.text;
+
+  if (options.output) {
+    // Atomic, symlink-safe write — `writeOutputReport`'s own docstring owns
+    // the mechanism and the threat it closes.
+    const reportText = report.endsWith("\n") ? report : `${report}\n`;
+    if (!writeOutputReport(options.output, reportText, env, cwd, options.config)) return EXIT.error;
+    env.err(`archkeep: delta complete → ${options.output}`);
+  } else {
+    env.out(report);
+  }
+
+  // The exit fold `deltaCommand` computed: a non-waived introduced violation
+  // is a finding, an unclassifiable item is a no-verdict, anything else is
+  // clean — mapped here the same way `fitness`'s status is.
+  return (
+    { ok: EXIT.ok, findings: EXIT.violations, "no-verdict": EXIT.error }[result.status] ??
+    EXIT.error
+  );
+}
+
 /**
  * `drift`'s `run`: resolves the command context, drives `driftCommand`, writes
  * the report where it belongs, and returns the process's exit code.
@@ -1124,6 +1194,108 @@ async function runReconcile(options, { cwd, env }) {
   return EXIT.ok;
 }
 
+/**
+ * `change`'s `run`: resolves the command context and the boundary law, drives
+ * `changeCommand` over the baseline evidence snapshot and the intent manifest,
+ * writes the report where it belongs, and returns the process's exit code.
+ *
+ * The fourth verb whose verdict carries exit 1, beside `check`, `fitness` and
+ * `delta`: an undeclared material change, an unfulfilled declaration, or a
+ * failed declared constraint is a finding; an unproven base identity or an
+ * undeterminable constraint is a no-verdict. The workspace-law axis the
+ * envelope reports is informational — it never moves this exit code, because
+ * `check` remains the authority on the law.
+ *
+ * @param {{format: string, output: string|null, config: string|null,
+ *   intent: string|null, paths: string[]}} options
+ * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function,
+ *   listFiles?: Function}}} runContext
+ * @returns {Promise<number>}
+ */
+async function runChange(options, { cwd, env }) {
+  if (options.paths.length !== 1) {
+    env.err(
+      `archkeep: change takes exactly one positional argument (the baseline evidence snapshot ` +
+        `from 'delta --capture'); got ${options.paths.length}`,
+    );
+    return EXIT.usage;
+  }
+  if (!options.intent) {
+    env.err(
+      "archkeep: change needs '--intent <file>' naming the change-intent manifest — without a " +
+        "declaration there is nothing to reconcile against",
+    );
+    return EXIT.usage;
+  }
+
+  const baselinePath = isAbsolute(options.paths[0])
+    ? options.paths[0]
+    : resolve(cwd, options.paths[0]);
+  const intentPath = isAbsolute(options.intent) ? options.intent : resolve(cwd, options.intent);
+
+  // A 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.
+  if (options.output) {
+    const outputAbs = isAbsolute(options.output)
+      ? resolve(options.output)
+      : resolve(cwd, options.output);
+    if (outputAbs === intentPath) {
+      env.err(
+        `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 EXIT.usage;
+    }
+  }
+
+  let result;
+  try {
+    const commandContext = resolveCommandContext(
+      { cwd },
+      { readGraph: env.readGraph, listFiles: env.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);
+
+    result = await changeCommand(baselinePath, intentPath, commandContext, { config });
+  } catch (error) {
+    const usageError = error instanceof UsageError;
+    env.err(String(error?.message ?? error));
+    return usageError ? EXIT.usage : EXIT.error;
+  }
+
+  const report = options.format === "json" ? result.report.json : result.report.text;
+
+  if (options.output) {
+    // Atomic, symlink-safe write — `writeOutputReport`'s own docstring owns
+    // the mechanism and the threat it closes.
+    const reportText = report.endsWith("\n") ? report : `${report}\n`;
+    if (!writeOutputReport(options.output, reportText, env, cwd, options.config)) return EXIT.error;
+    env.err(
+      `archkeep: change ${result.changeIntent.reconciliation.verdict} ` +
+        `(+${result.changeIntent.reconciliation.matched.length} matched, ` +
+        `!${result.changeIntent.reconciliation.unexpected.length} undeclared, ` +
+        `?${result.changeIntent.reconciliation.missingExpected.length} unfulfilled) → ${options.output}`,
+    );
+  } else {
+    env.out(report);
+  }
+
+  // The verdict fold `changeCommand` computed, mapped here the way `delta`'s
+  // and `fitness`' are.
+  return (
+    { ok: EXIT.ok, findings: EXIT.violations, "no-verdict": EXIT.error }[result.status] ??
+    EXIT.error
+  );
+}
+
 /**
  * `waivers`' `run`: resolves the command context, drives `waiversCommand`,
  * writes the report where it belongs, and returns the process's exit code.
@@ -1156,9 +1328,14 @@ async function runWaivers(options, { cwd, env }) {
     // against this tool's own location, and a `profiles` registry resolves
     // `--config`/`boundaryConfig` as a profile NAME the same way `check`
     // does. A malformed law throws here, exit 3, exactly as in `check`.
-    const { config } = await resolvePolicy(options, commandContext, cwd);
+    const { config, source } = await resolvePolicy(options, commandContext, cwd);
 
-    result = await waiversCommand(commandContext, config);
+    // `source` rides along for one job: `waiversCommand` subtracts the law's
+    // own file from the unowned-file set the `coverage.unowned` acceptances
+    // are matched against, exactly as `check` does — the law is not source
+    // judged by the law (`../src/commands/context.mjs`'s
+    // `unownedGapWithoutRunConfiguration`).
+    result = await waiversCommand(commandContext, config, { policySource: source });
   } catch (error) {
     const usageError = error instanceof UsageError;
     env.err(String(error?.message ?? error));
@@ -1622,6 +1799,157 @@ async function runHistory(options, { cwd, env }) {
   return EXIT.ok;
 }
 
+/**
+ * `trajectory`'s run: resolves the command context, drives
+ * `trajectoryCommand`, writes the report, and returns the exit code.
+ *
+ * The history directory is the single positional argument — the same
+ * consumer-managed directory `history` and `debt` read. No boundary law is
+ * loaded and no snapshot is captured: the fingerprints compared travel inside
+ * the stored snapshots (`src/commands/trajectory.mjs`'s header owns both
+ * halves of that posture).
+ *
+ * @param {{format: string, output: string|null, paths: string[]}} options
+ * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
+ * @returns {Promise<number>}
+ */
+async function runTrajectory(options, { cwd, env }) {
+  if (options.paths.length !== 1) {
+    env.err(
+      `archkeep: trajectory takes exactly one positional argument (the history directory); ` +
+        `got ${options.paths.length}`,
+    );
+    return EXIT.usage;
+  }
+
+  const dir = isAbsolute(options.paths[0])
+    ? resolve(options.paths[0])
+    : resolve(cwd, options.paths[0]);
+
+  // The same self-footgun guard `runHistory` applies: a report written into
+  // the directory being read would be read back as a snapshot on the next run
+  // (the envelope is not a `graph` snapshot, which `parseBaseline` refuses) —
+  // poison the record loudly refused rather than quietly planted.
+  if (options.output) {
+    const outputAbs = isAbsolute(options.output)
+      ? resolve(options.output)
+      : resolve(cwd, options.output);
+    if (dirname(outputAbs) === dir) {
+      env.err(
+        `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 EXIT.usage;
+    }
+  }
+
+  let result;
+  try {
+    const commandContext = resolveCommandContext(
+      { cwd },
+      { readGraph: env.readGraph, listFiles: env.listFiles },
+    );
+    result = trajectoryCommand(dir, commandContext);
+  } catch (error) {
+    const usageError = error instanceof UsageError;
+    env.err(String(error?.message ?? error));
+    return usageError ? EXIT.usage : EXIT.error;
+  }
+
+  const report = options.format === "json" ? result.report.json : result.report.text;
+
+  if (options.output) {
+    // Atomic, symlink-safe write — `writeOutputReport`'s own docstring owns
+    // the mechanism and the threat it closes.
+    const reportText = report.endsWith("\n") ? report : `${report}\n`;
+    // No `--config` flag (`TRAJECTORY_FLAG_HELP`) — there is no override to pass.
+    if (!writeOutputReport(options.output, reportText, env, cwd, null)) return EXIT.error;
+    env.err(`archkeep: trajectory complete → ${options.output}`);
+  } else {
+    env.out(report);
+  }
+
+  // Trajectory is descriptive: 0 when the aggregation completes, never 1.
+  return EXIT.ok;
+}
+
+/**
+ * `evolution`'s `run`: resolves the workspace root the way `adr` does (a light
+ * marker walk — this command describes OTHER trees, so it must not fail
+ * because the caller's own working tree does not fully analyze right now),
+ * drives `evolutionCommand`, writes the report, and returns the exit code.
+ *
+ * The range is `--base` plus optional `--head`; there are no positional
+ * arguments. The Nx and git seams in `env` thread into EVERY analyzed
+ * revision's context, the same way they thread into one tree elsewhere — in
+ * production both are undefined and every revision is read for real.
+ *
+ * @param {{format: string, output: string|null, base: string|null, head: string|null,
+ *   paths: string[]}} options
+ * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
+ * @returns {Promise<number>}
+ */
+async function runEvolution(options, { cwd, env }) {
+  if (!options.base) {
+    env.err(
+      `archkeep: evolution needs --base <rev> — a commit, branch, or tag the range starts at ` +
+        `(--head defaults to HEAD).`,
+    );
+    return EXIT.usage;
+  }
+  if (options.paths.length > 0) {
+    env.err(
+      `archkeep: evolution takes no positional arguments; the range is --base plus --head. ` +
+        `Got '${options.paths.join("', '")}'`,
+    );
+    return EXIT.usage;
+  }
+
+  const root = findWorkspaceRoot(cwd, WORKSPACE_MARKERS);
+  if (root === null) {
+    env.err(
+      `archkeep: evolution needs a workspace root — no nx.json, archkeep.json, or .moon marker found ` +
+        `walking up from ${cwd}`,
+    );
+    return EXIT.error;
+  }
+
+  let result;
+  try {
+    result = await evolutionCommand(
+      root,
+      { base: options.base, head: options.head },
+      {
+        readGraph: env.readGraph,
+        listFiles: env.listFiles,
+      },
+    );
+  } catch (error) {
+    const usageError = error instanceof UsageError;
+    env.err(String(error?.message ?? error));
+    return usageError ? EXIT.usage : EXIT.error;
+  }
+
+  const report = options.format === "json" ? result.report.json : result.report.text;
+
+  if (options.output) {
+    // Atomic, symlink-safe write — `writeOutputReport`'s own docstring owns
+    // the mechanism and the threat it closes.
+    const reportText = report.endsWith("\n") ? report : `${report}\n`;
+    // No `--config` flag exists here (`EVOLUTION_FLAG_HELP`) — there is no
+    // override to pass, only the workspace's un-overridden default to guard.
+    if (!writeOutputReport(options.output, reportText, env, cwd, null)) return EXIT.error;
+    env.err(`archkeep: evolution complete → ${options.output}`);
+  } else {
+    env.out(report);
+  }
+
+  // Descriptive: where the architecture changed is a fact about history,
+  // never a finding.
+  return EXIT.ok;
+}
+
 /**
  * `debt`'s `run`: resolves the command context, drives `debtCommand`, writes
  * the ledger report, and returns the exit code.
@@ -2011,6 +2339,107 @@ const DIFF_FLAG_HELP = Object.freeze([
   }),
 ]);
 
+/**
+ * `delta`'s flags: `--capture` writes the evidence snapshot a later run
+ * compares against; without it the baseline file is the single positional
+ * argument. `--config` overrides the boundary law the same way `check`'s
+ * does, because both sides are re-judged under whichever law this run
+ * resolves.
+ *
+ * @type {readonly FlagHelp[]}
+ */
+const DELTA_FLAG_HELP = Object.freeze([
+  Object.freeze({
+    flag: "--capture",
+    key: "capture",
+    arg: "",
+    describe: Object.freeze([
+      "Write an evidence snapshot of the current tree",
+      "(raw import records, graph, coverage, policy",
+      "fingerprint) for a later delta run to compare against",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--format",
+    key: "format",
+    arg: "text|sarif|json",
+    describe: Object.freeze([
+      "Terminal report (default), SARIF 2.1.0 of the introduced",
+      "findings for GitHub code scanning, or the versioned JSON",
+      "envelope docs/reference/json-output.md documents",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--output",
+    key: "output",
+    arg: "<file>",
+    describe: Object.freeze([
+      "Write the report — or, with --capture, the snapshot —",
+      "to a file instead of stdout",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--config",
+    key: "config",
+    arg: "<file>",
+    describe: ({ boundaryConfig, inline }) =>
+      Object.freeze([
+        "Read the boundary law from here instead of",
+        inline
+          ? "the inline boundaryConfig in archkeep.json"
+          : `<workspace root>/${boundaryConfig}`,
+      ]),
+  }),
+]);
+
+/**
+ * `change`'s flags: text or JSON envelope, optional file output, and the
+ * required `--intent` naming the change-intent manifest. `--config` joins for
+ * the same reason `delta`'s does: declared constraints are re-judged under
+ * whichever law this run resolves.
+ *
+ * @type {readonly FlagHelp[]}
+ */
+const CHANGE_FLAG_HELP = Object.freeze([
+  Object.freeze({
+    flag: "--intent",
+    key: "intent",
+    arg: "<file>",
+    describe: Object.freeze([
+      "The change-intent manifest declaring the material",
+      "architectural consequences this change expects",
+      "(required; see docs/usage/change.md)",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--format",
+    key: "format",
+    arg: "text|json",
+    describe: Object.freeze([
+      "Terminal report (default) or the versioned JSON envelope",
+      "docs/reference/json-output.md documents",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--output",
+    key: "output",
+    arg: "<file>",
+    describe: Object.freeze(["Write the report to a file instead of stdout"]),
+  }),
+  Object.freeze({
+    flag: "--config",
+    key: "config",
+    arg: "<file>",
+    describe: ({ boundaryConfig, inline }) =>
+      Object.freeze([
+        "Read the boundary law from here instead of",
+        inline
+          ? "the inline boundaryConfig in archkeep.json"
+          : `<workspace root>/${boundaryConfig}`,
+      ]),
+  }),
+]);
+
 /**
  * `drift`'s flags: text or JSON envelope, optional file output. The intent is
  * always read from the tracked root `architecture-intent.json` — the same one
@@ -2227,6 +2656,51 @@ const HISTORY_FLAG_HELP = Object.freeze([
   }),
 ]);
 
+/**
+ * `evolution`'s flags: text or JSON envelope, optional file output, and the
+ * two revisions that bound the range. There is no `--config` — each analyzed
+ * revision is judged under the law its own tree declares (`src/commands/evolution.mjs`),
+ * and a law carried from outside would misattribute policy changes to
+ * revisions that never made them.
+ *
+ * @type {readonly FlagHelp[]}
+ */
+const EVOLUTION_FLAG_HELP = Object.freeze([
+  Object.freeze({
+    flag: "--format",
+    key: "format",
+    arg: "text|json",
+    describe: Object.freeze([
+      "Terminal report (default) or the versioned JSON envelope",
+      "docs/reference/json-output.md documents",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--output",
+    key: "output",
+    arg: "<file>",
+    describe: Object.freeze(["Write the report to a file instead of stdout"]),
+  }),
+  Object.freeze({
+    flag: "--base",
+    key: "base",
+    arg: "<rev>",
+    describe: Object.freeze([
+      "The baseline revision — a commit, branch, tag,",
+      "or HEAD~n; the first revision analyzed",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--head",
+    key: "head",
+    arg: "<rev>",
+    describe: Object.freeze([
+      "The tip revision (default HEAD); must be a",
+      "linear descendant of --base with no merges between",
+    ]),
+  }),
+]);
+
 /**
  * `health`'s flags: text or JSON envelope, optional file output. The optional
  * positional argument is the snapshot directory for trends, the same directory
@@ -2303,6 +2777,35 @@ const REPORT_FLAG_HELP = Object.freeze([
   }),
 ]);
 
+/**
+ * `trajectory`'s flags: text or JSON envelope and optional file output — and
+ * deliberately no `--config` and no `--capture`. There is no current-law
+ * input to override: the fingerprints being compared travel inside the
+ * snapshots, so the law each observation is judged under is the one it was
+ * captured under. And the command writes nothing into the history directory —
+ * capture stays `history --capture`'s job, so there is exactly one way a
+ * snapshot enters the record.
+ *
+ * @type {readonly FlagHelp[]}
+ */
+const TRAJECTORY_FLAG_HELP = Object.freeze([
+  Object.freeze({
+    flag: "--format",
+    key: "format",
+    arg: "text|json",
+    describe: Object.freeze([
+      "Terminal report (default) or the versioned JSON envelope",
+      "docs/reference/json-output.md documents",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--output",
+    key: "output",
+    arg: "<file>",
+    describe: Object.freeze(["Write the report to a file instead of stdout"]),
+  }),
+]);
+
 /**
  * `debt`'s flags: text or JSON envelope, optional file output, and the same
  * `--config` the other descriptive commands take, so a ledger ages the
@@ -2527,6 +3030,27 @@ const COMMANDS = Object.freeze({
     formats: DESCRIBABLE_FORMATS,
     run: runDiff,
   }),
+  delta: Object.freeze({
+    name: "delta",
+    args: "<baseline> | --capture",
+    summary: "Classify how boundary violations moved between a captured baseline and head",
+    flagHelp: DELTA_FLAG_HELP,
+    flags: Object.freeze(Object.fromEntries(DELTA_FLAG_HELP.map((f) => [f.flag, f.key]))),
+    defaults: Object.freeze({ format: "text", output: null, config: null, capture: false }),
+    formats: DELTA_FORMATS,
+    booleans: Object.freeze(["capture"]),
+    run: runDelta,
+  }),
+  change: Object.freeze({
+    name: "change",
+    args: "<baseline> --intent <file>",
+    summary: "Reconcile a declared change intent against the architectural delta",
+    flagHelp: CHANGE_FLAG_HELP,
+    flags: Object.freeze(Object.fromEntries(CHANGE_FLAG_HELP.map((f) => [f.flag, f.key]))),
+    defaults: Object.freeze({ format: "text", output: null, config: null, intent: null }),
+    formats: DESCRIBABLE_FORMATS,
+    run: runChange,
+  }),
   discover: Object.freeze({
     name: "discover",
     args: "[--propose]",
@@ -2590,6 +3114,26 @@ const COMMANDS = Object.freeze({
     booleans: Object.freeze(["capture"]),
     run: runHistory,
   }),
+  trajectory: Object.freeze({
+    name: "trajectory",
+    args: "<dir>",
+    summary: "Aggregate the deterministic drift trajectory across snapshots",
+    flagHelp: TRAJECTORY_FLAG_HELP,
+    flags: Object.freeze(Object.fromEntries(TRAJECTORY_FLAG_HELP.map((f) => [f.flag, f.key]))),
+    defaults: Object.freeze({ format: "text", output: null }),
+    formats: DESCRIBABLE_FORMATS,
+    run: runTrajectory,
+  }),
+  evolution: Object.freeze({
+    name: "evolution",
+    args: "",
+    summary: "Describe how the architecture evolved across a Git revision range",
+    flagHelp: EVOLUTION_FLAG_HELP,
+    flags: Object.freeze(Object.fromEntries(EVOLUTION_FLAG_HELP.map((f) => [f.flag, f.key]))),
+    defaults: Object.freeze({ format: "text", output: null, base: null, head: null }),
+    formats: DESCRIBABLE_FORMATS,
+    run: runEvolution,
+  }),
   health: Object.freeze({
     name: "health",
     args: "[<snapshot-dir>]",