@intentius/chant 0.45.0 → 0.49.0

package/src/cli/mcp/tools/explain.ts

@@ -1,6 +1,19 @@
-import { resolve } from "path";
+import { resolve, dirname } from "path";
 import { discover } from "../../../discovery/index";
 import { buildOkfBundle, OKF_VERSION } from "../../../okf";
+import { loadOkfBundle, bindConcepts, type OkfConcept } from "../../../okf-read";
+import { loadChantConfigUpward, resolveKnowledgeDir } from "../../../config";
+
+/** One bound concept as surfaced in an explain knowledge section — the trio the #1867 design calls for, not the full {@link OkfConcept}. */
+export interface ExplainKnowledgeEntry {
+  type: string;
+  title?: string;
+  path: string;
+}
+
+function toKnowledgeEntry(concept: OkfConcept): ExplainKnowledgeEntry {
+  return { type: concept.type, title: concept.title, path: concept.path };
+}
 
 /**
  * Explain tool definition for MCP
@@ -46,6 +59,25 @@ export async function handleExplain(params: Record<string, unknown>): Promise<un
     };
   }
 
+  // Authored knowledge (#1867, design #1059): bind the project's OKF bundle
+  // (if any) to the discovered entities and carry each bound concept's
+  // type/title/path into the summary. A project with no `knowledge/` yet
+  // binds nothing — `bound` is empty — so the section is omitted below
+  // rather than rendered empty; this is the CLI and MCP tool's one shared
+  // code path, so both surfaces match by construction.
+  // `loadChantConfigUpward` walks up from `infraPath` (chant #1117) — a
+  // `chant explain src/<stack>` two levels below `chant.config.ts` must find
+  // the same `knowledge/` a `chant explain .` at the root would, matching
+  // `build.ts`'s `configDir` derivation for the same reason.
+  const loaded = await loadChantConfigUpward(infraPath);
+  const projectRoot = loaded.configPath ? dirname(loaded.configPath) : infraPath;
+  const knowledgeDir = resolveKnowledgeDir(loaded.config, projectRoot);
+  const bundle = await loadOkfBundle(knowledgeDir);
+  const { bound } = bindConcepts(bundle, result.entities);
+  const knowledge = new Map<string, ExplainKnowledgeEntry[]>(
+    Array.from(bound.entries()).map(([name, concepts]) => [name, concepts.map(toKnowledgeEntry)]),
+  );
+
   // Group entities by lexicon and kind
   const byLexicon = new Map<string, { resources: string[]; properties: string[] }>();
 
@@ -89,7 +121,11 @@ export async function handleExplain(params: Record<string, unknown>): Promise<un
   };
 
   if (format === "json") {
-    return summary;
+    // Omitted entirely when no entity bound a concept — "cleanly absent" per
+    // #1867's AC, not an empty `{}`.
+    return knowledge.size > 0
+      ? { ...summary, knowledge: Object.fromEntries(knowledge) }
+      : summary;
   }
 
   // Markdown format
@@ -133,6 +169,19 @@ export async function handleExplain(params: Record<string, unknown>): Promise<un
     lines.push("");
   }
 
+  if (knowledge.size > 0) {
+    lines.push("## Knowledge");
+    lines.push("");
+    for (const [name, entries] of knowledge) {
+      lines.push(`### \`${name}\``);
+      for (const entry of entries) {
+        const title = entry.title ? `${entry.title} ` : "";
+        lines.push(`- ${entry.type || "concept"}: ${title}(\`${entry.path}\`)`);
+      }
+      lines.push("");
+    }
+  }
+
   if (result.errors.length > 0) {
     lines.push("## Errors");
     lines.push("");

package/src/cli/plugins.ts

@@ -106,10 +106,12 @@ export function collectBuildRootContributors(
   plugins: readonly LexiconPlugin[] | undefined,
   config: Record<string, unknown>,
   projectRoot: string,
-): Array<() => Promise<import("../lexicon").BuildRootContribution>> {
+): Array<import("../lexicon").BuildRootContributor> {
   return (plugins ?? [])
     .filter((plugin) => typeof plugin.buildRoots === "function")
-    .map((plugin) => () => plugin.buildRoots!({ projectRoot, config }));
+    // `entities` is not bindable here — discovery has not run — so the merge
+    // hands it in when it calls the closure (#1828 / SOPS provenance).
+    .map((plugin) => (ctx) => plugin.buildRoots!({ projectRoot, config, entities: ctx?.entities }));
 }
 
 /**

package/src/cli/registry.ts

@@ -85,6 +85,13 @@ export interface ParsedArgs {
   namespace?: string;
   /** `chant lifecycle rollback --dry-run` — compute the rollback delta and print it; open no PR, push nothing, leave no branch. */
   dryRun?: boolean;
+  /** `chant lifecycle teardown <env> --yes` — execute the planned deletion
+   * (#1222). Without it the command plans and stops. */
+  yes?: boolean;
+  /** `chant lifecycle teardown <env> --yes --confirm-prod` — the non-interactive
+   * form of the extra confirmation a production-like environment name demands
+   * (#1222). Meaningless without `--yes`. */
+  confirmProd?: boolean;
   /** `chant import --verbatim` — keep server-defaulted fields in live import */
   verbatim?: boolean;
   /** `chant lifecycle … --src <dir>` — build root override for lifecycle commands */

package/src/cli/reporters/stylish.test.ts

@@ -1,6 +1,17 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { formatStylish, formatSummary, formatJson, formatSarif } from "./stylish";
 import type { LintDiagnostic, LintRule } from "../../lint/rule";
+import type { OkfBundle, OkfConcept } from "../../okf-read";
+
+function concept(overrides: Partial<OkfConcept> & { path: string }): OkfConcept {
+  return {
+    type: "decision",
+    binds: [],
+    frontmatter: {},
+    body: "",
+    ...overrides,
+  };
+}
 
 describe("formatStylish", () => {
   const originalNoColor = process.env.NO_COLOR;
@@ -123,6 +134,149 @@ describe("formatStylish", () => {
   });
 });
 
+describe("formatStylish suppressed section (#1866, design #1059)", () => {
+  beforeEach(() => {
+    process.env.NO_COLOR = "1";
+  });
+  afterEach(() => {
+    delete process.env.NO_COLOR;
+  });
+
+  const suppressedDiag: LintDiagnostic & { reason?: string } = {
+    file: "src/storage.ts",
+    line: 12,
+    column: 1,
+    ruleId: "AWS021",
+    severity: "warning",
+    message: "Bucket ACL is public-read",
+  };
+
+  test("no section when there are no suppressed diagnostics", () => {
+    const result = formatStylish([], []);
+    expect(result).not.toContain("Suppressed");
+  });
+
+  test("renders a Suppressed section when suppressed diagnostics exist", () => {
+    const result = formatStylish([], [{ ...suppressedDiag, reason: "backwards compat" }]);
+
+    expect(result).toContain("Suppressed");
+    expect(result).toContain("src/storage.ts");
+    expect(result).toContain("AWS021");
+    expect(result).toContain("backwards compat");
+  });
+
+  test("renders the section even when there are no active diagnostics", () => {
+    const result = formatStylish([], [suppressedDiag]);
+    expect(result).toContain("Suppressed");
+    // No active errors/warnings were counted from a suppressed diagnostic
+    expect(result).toContain("No problems found");
+  });
+
+  test("an okf: citation resolves to the concept's title and bundle-relative path", () => {
+    const bundle: OkfBundle = {
+      concepts: [
+        concept({
+          path: "decisions/public-assets.md",
+          title: "Public asset bucket stays world-readable",
+        }),
+      ],
+    };
+
+    const result = formatStylish(
+      [],
+      [{ ...suppressedDiag, reason: "okf:/decisions/public-assets.md" }],
+      bundle,
+    );
+
+    expect(result).toContain("Public asset bucket stays world-readable");
+    expect(result).toContain("decisions/public-assets.md");
+    expect(result).not.toContain("okf:/decisions/public-assets.md");
+  });
+
+  test("also resolves a citation without a leading slash", () => {
+    const bundle: OkfBundle = {
+      concepts: [concept({ path: "decisions/public-assets.md", title: "Public assets" })],
+    };
+
+    const result = formatStylish(
+      [],
+      [{ ...suppressedDiag, reason: "okf:decisions/public-assets.md" }],
+      bundle,
+    );
+
+    expect(result).toContain("Public assets");
+  });
+
+  test("an unresolvable citation prints the raw reason with a warning", () => {
+    const bundle: OkfBundle = { concepts: [] };
+
+    const result = formatStylish(
+      [],
+      [{ ...suppressedDiag, reason: "okf:/decisions/does-not-exist.md" }],
+      bundle,
+    );
+
+    expect(result).toContain("okf:/decisions/does-not-exist.md");
+    expect(result).toContain("unresolved okf citation");
+  });
+
+  test("an okf: citation with no bundle loaded prints the raw reason with a warning", () => {
+    const result = formatStylish([], [{ ...suppressedDiag, reason: "okf:/decisions/public-assets.md" }]);
+
+    expect(result).toContain("okf:/decisions/public-assets.md");
+    expect(result).toContain("unresolved okf citation");
+  });
+
+  test("a plain (non-okf) reason renders as-is, unaffected by a loaded bundle", () => {
+    const bundle: OkfBundle = {
+      concepts: [concept({ path: "decisions/public-assets.md", title: "Public assets" })],
+    };
+
+    const result = formatStylish([], [{ ...suppressedDiag, reason: "grandfathered, see #412" }], bundle);
+
+    expect(result).toContain("grandfathered, see #412");
+    expect(result).not.toContain("Public assets");
+  });
+
+  test("a suppressed diagnostic with no reason still renders", () => {
+    const result = formatStylish([], [suppressedDiag]);
+    expect(result).toContain("AWS021");
+    expect(result).toContain("suppressed");
+  });
+
+  test("active diagnostics and the suppressed section coexist", () => {
+    const active: LintDiagnostic = {
+      file: "src/other.ts",
+      line: 1,
+      column: 1,
+      ruleId: "COR001",
+      severity: "error",
+      message: "Active problem",
+    };
+
+    const result = formatStylish([active], [{ ...suppressedDiag, reason: "okf:/decisions/public-assets.md" }], {
+      concepts: [concept({ path: "decisions/public-assets.md", title: "Public assets" })],
+    });
+
+    expect(result).toContain("src/other.ts");
+    expect(result).toContain("Active problem");
+    expect(result).toContain("1 error");
+    expect(result).toContain("Suppressed");
+    expect(result).toContain("Public assets");
+  });
+
+  test("a title-less resolved concept falls back to its path as the label", () => {
+    const bundle: OkfBundle = {
+      concepts: [concept({ path: "decisions/public-assets.md" })],
+    };
+
+    const result = formatStylish([], [{ ...suppressedDiag, reason: "okf:/decisions/public-assets.md" }], bundle);
+
+    expect(result).toContain("decisions/public-assets.md");
+    expect(result).not.toContain("unresolved");
+  });
+});
+
 describe("formatSummary", () => {
   beforeEach(() => {
     process.env.NO_COLOR = "1";

package/src/cli/reporters/stylish.ts

@@ -1,4 +1,5 @@
 import type { LintDiagnostic, LintRule, Severity } from "../../lint/rule";
+import type { OkfBundle } from "../../okf-read";
 import { pathToFileURL } from "node:url";
 
 /**
@@ -33,64 +34,184 @@ function color(text: string, colorCode: string): string {
 /**
  * Format diagnostics in stylish format (similar to ESLint)
  * Groups by file, shows severity, message, and rule ID
+ *
+ * @param diagnostics - Active (non-suppressed) diagnostics
+ * @param suppressed - Suppressed diagnostics with optional reason (optional). When
+ *   present and non-empty, a "Suppressed" section is appended (#1866, design #1059)
+ *   below the active diagnostics, mirroring SARIF's `suppressed` param on
+ *   {@link formatSarif} rather than changing what "diagnostics" means here.
+ * @param bundle - The project's loaded OKF knowledge bundle (`../../okf-read`'s
+ *   `loadOkfBundle`), used to resolve `okf:` citations in suppression reasons.
+ *   Omitted (or a bundle with no matching concept) falls back to printing the
+ *   raw reason with a warning — this never affects suppression itself, only
+ *   how a cited reason renders.
  */
-export function formatStylish(diagnostics: LintDiagnostic[]): string {
-  if (diagnostics.length === 0) {
+export function formatStylish(
+  diagnostics: LintDiagnostic[],
+  suppressed?: Array<LintDiagnostic & { reason?: string }>,
+  bundle?: OkfBundle,
+): string {
+  const hasSuppressed = suppressed !== undefined && suppressed.length > 0;
+
+  if (diagnostics.length === 0 && !hasSuppressed) {
     return formatSummary(0, 0);
   }
 
-  // Group by file
-  const byFile = new Map<string, LintDiagnostic[]>();
-  for (const diag of diagnostics) {
+  const lines: string[] = [];
+  let errorCount = 0;
+  let warningCount = 0;
+
+  if (diagnostics.length > 0) {
+    // Group by file
+    const byFile = new Map<string, LintDiagnostic[]>();
+    for (const diag of diagnostics) {
+      const existing = byFile.get(diag.file) ?? [];
+      existing.push(diag);
+      byFile.set(diag.file, existing);
+    }
+
+    for (const [file, fileDiags] of byFile) {
+      // File header with underline
+      lines.push("");
+      lines.push(color(file, colors.underline));
+
+      // Sort by line, then column
+      fileDiags.sort((a, b) => {
+        if (a.line !== b.line) return a.line - b.line;
+        return a.column - b.column;
+      });
+
+      for (const diag of fileDiags) {
+        // Count errors and warnings
+        if (diag.severity === "error") {
+          errorCount++;
+        } else if (diag.severity === "warning") {
+          warningCount++;
+        }
+
+        // Format: "  line:col  severity  message  ruleId"
+        const location = color(
+          `${String(diag.line).padStart(4)}:${String(diag.column).padEnd(3)}`,
+          colors.gray
+        );
+
+        const severityColor = diag.severity === "error" ? colors.red : colors.yellow;
+        const severity = color(diag.severity.padEnd(7), severityColor);
+
+        const ruleId = color(diag.ruleId, colors.gray);
+
+        lines.push(`  ${location}  ${severity}  ${diag.message}  ${ruleId}`);
+      }
+    }
+  }
+
+  if (hasSuppressed) {
+    lines.push(...formatSuppressedSection(suppressed!, bundle));
+  }
+
+  // Summary line
+  lines.push("");
+  const summary = formatSummary(errorCount, warningCount);
+  lines.push(summary);
+
+  return lines.join("\n");
+}
+
+/**
+ * A suppression reason's `okf:` citation, resolved against a loaded bundle.
+ */
+interface ResolvedCitation {
+  /** What to print beside the rule id: the concept title when resolved, the raw reason otherwise. */
+  label: string;
+  /** The concept's bundle-relative path, printed on the line below — only set when resolved. */
+  path?: string;
+  /** True when the reason carried an `okf:` token that named no concept in `bundle`. */
+  unresolved: boolean;
+}
+
+/**
+ * Resolve a suppression reason's `okf:<path>` citation (#1866, design #1059)
+ * against a loaded bundle's concepts, matched on `OkfConcept.path`. Not an
+ * `okf:` citation at all: returns `null`, and the reason renders as plain
+ * text, same as before this section existed. A leading `/` on the cited path
+ * is accepted and stripped — `okf-read.ts`'s bundle-relative paths never
+ * carry one, but the design doc's worked example writes citations with one
+ * (mirroring an absolute-from-bundle-root reading), so both forms resolve.
+ */
+function resolveOkfCitation(reason: string, bundle: OkfBundle | undefined): ResolvedCitation | null {
+  const prefix = "okf:";
+  if (!reason.startsWith(prefix)) return null;
+
+  const token = reason.slice(prefix.length).trim().replace(/^\/+/, "");
+  const concept = bundle?.concepts.find((c) => c.path === token);
+
+  if (concept) {
+    return { label: concept.title ?? concept.path, path: concept.path, unresolved: false };
+  }
+
+  return { label: reason, unresolved: true };
+}
+
+/**
+ * Render the "Suppressed" section: every suppressed diagnostic, grouped by
+ * file like the active section above, with an `okf:` reason resolved to its
+ * concept's title (and bundle-relative path on the line below) when
+ * `bundle` has a match. A citation naming no concept — including when no
+ * `bundle` was loaded at all — prints the raw reason plus a warning; a
+ * plain (non-`okf:`) reason prints as-is. Never affects which diagnostics
+ * are suppressed, only how the reason renders (design #1059: "a cited
+ * suppression suppresses exactly as an uncited one does").
+ */
+function formatSuppressedSection(
+  suppressed: Array<LintDiagnostic & { reason?: string }>,
+  bundle: OkfBundle | undefined,
+): string[] {
+  const lines: string[] = [];
+
+  const byFile = new Map<string, Array<LintDiagnostic & { reason?: string }>>();
+  for (const diag of suppressed) {
     const existing = byFile.get(diag.file) ?? [];
     existing.push(diag);
     byFile.set(diag.file, existing);
   }
 
-  const lines: string[] = [];
-  let errorCount = 0;
-  let warningCount = 0;
+  lines.push("");
+  lines.push(color("Suppressed", colors.underline));
 
   for (const [file, fileDiags] of byFile) {
-    // File header with underline
     lines.push("");
     lines.push(color(file, colors.underline));
 
-    // Sort by line, then column
     fileDiags.sort((a, b) => {
       if (a.line !== b.line) return a.line - b.line;
       return a.column - b.column;
     });
 
     for (const diag of fileDiags) {
-      // Count errors and warnings
-      if (diag.severity === "error") {
-        errorCount++;
-      } else if (diag.severity === "warning") {
-        warningCount++;
-      }
-
-      // Format: "  line:col  severity  message  ruleId"
-      const location = color(
-        `${String(diag.line).padStart(4)}:${String(diag.column).padEnd(3)}`,
-        colors.gray
-      );
-
-      const severityColor = diag.severity === "error" ? colors.red : colors.yellow;
-      const severity = color(diag.severity.padEnd(7), severityColor);
-
+      const locationPlain = `${String(diag.line).padStart(4)}:${String(diag.column).padEnd(3)}`;
+      const location = color(locationPlain, colors.gray);
+      const severity = color("suppressed", colors.cyan);
       const ruleId = color(diag.ruleId, colors.gray);
 
-      lines.push(`  ${location}  ${severity}  ${diag.message}  ${ruleId}`);
+      const citation = diag.reason ? resolveOkfCitation(diag.reason, bundle) : null;
+      const indent = " ".repeat(2 + locationPlain.length + 2 + "suppressed".length + 2 + diag.ruleId.length + 2);
+
+      if (citation) {
+        lines.push(`  ${location}  ${severity}  ${ruleId}  ${citation.label}`);
+        if (!citation.unresolved) {
+          lines.push(`${indent}${color(citation.path!, colors.gray)}`);
+        } else {
+          lines.push(`${indent}${color("⚠ unresolved okf citation", colors.yellow)}`);
+        }
+      } else if (diag.reason) {
+        lines.push(`  ${location}  ${severity}  ${ruleId}  ${diag.reason}`);
+      } else {
+        lines.push(`  ${location}  ${severity}  ${ruleId}`);
+      }
     }
   }
 
-  // Summary line
-  lines.push("");
-  const summary = formatSummary(errorCount, warningCount);
-  lines.push(summary);
-
-  return lines.join("\n");
+  return lines;
 }
 
 /**

package/src/codegen/lexicon-regen.ts

@@ -25,6 +25,7 @@
 import { existsSync, readFileSync, writeFileSync, readdirSync, type Dirent } from "fs";
 import { join } from "path";
 import { execSync } from "child_process";
+import { SNAPSHOT_UPDATE_ENV } from "./validate";
 import {
   extractSurface,
   diffSurface,
@@ -114,6 +115,17 @@ export interface RegenOptions {
    *   sha256:<64-hex-chars>  <relative-path-to-spec-file>
    */
   pinnedDigestPath?: string;
+  /**
+   * This run is about to rewrite the baseline snapshot (#1825).
+   *
+   * The `validate` step runs with {@link SNAPSHOT_UPDATE_ENV} set so its
+   * `surface-matches-snapshot` check is skipped. A lexicon whose snapshot gate
+   * runs in `"always"` mode (#1475) fails validate on a stale baseline, and a
+   * stale baseline is exactly what a re-baseline starts from — without this
+   * exemption the documented update flow deadlocks. Every other validate check
+   * still gates the run, so a broken generate cannot be baselined.
+   */
+  updatingSnapshot?: boolean;
 }
 
 // ── Pipeline ──────────────────────────────────────────────────────────
@@ -132,6 +144,7 @@ export async function regenLexicon(opts: RegenOptions): Promise<RegenResult> {
     skipBuild = false,
     skipLint = false,
     skipExamples = true,
+    updatingSnapshot = false,
   } = opts;
 
   const failures: RegenFailure[] = [];
@@ -177,7 +190,12 @@ export async function regenLexicon(opts: RegenOptions): Promise<RegenResult> {
   }
 
   // Step 4: validate
-  const validateFail = runScript(lexiconDir, "validate", process.env, verbose);
+  // A re-baseline run is exempt from the surface-matches-snapshot check only
+  // (#1825) — see RegenOptions.updatingSnapshot.
+  const validateEnv: NodeJS.ProcessEnv = updatingSnapshot
+    ? { ...process.env, [SNAPSHOT_UPDATE_ENV]: "1" }
+    : process.env;
+  const validateFail = runScript(lexiconDir, "validate", validateEnv, verbose);
   if (validateFail) {
     failures.push(validateFail);
   }

package/src/codegen/validate.test.ts

@@ -182,4 +182,37 @@ describe("surface snapshot gate (#1473)", () => {
     const check = result.checks.find((c) => c.name === "surface-matches-snapshot");
     expect(check?.ok).toBe(false);
   });
+
+  test("an update run skips the staleness check it is about to fix (#1825)", async () => {
+    // `--update-snapshot` sets CHANT_SNAPSHOT_UPDATE for its validate run.
+    // Without this, an "always" gate deadlocks the documented re-baseline flow:
+    // validate fails on the stale snapshot, and the update writes only after a
+    // green validate.
+    const stale = JSON.stringify({ schemaVersion: 1, generatedAt: "2026-01-01T00:00:00.000Z", entries: {} });
+    const result = await validateLexiconArtifacts({
+      lexiconJsonFilename: "lexicon-test.json",
+      requiredNames: [],
+      basePath: fixture({ snapshot: stale }),
+      checkSurfaceSnapshot: "always",
+      env: { CHANT_SNAPSHOT_UPDATE: "1" },
+    });
+    expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
+    expect(result.success).toBe(true);
+  });
+
+  test("an update run is exempt from the staleness check and nothing else", async () => {
+    // A failing check other than surface-matches-snapshot must still refuse
+    // the run, so a broken generate cannot be baselined.
+    const stale = JSON.stringify({ schemaVersion: 1, generatedAt: "2026-01-01T00:00:00.000Z", entries: {} });
+    const result = await validateLexiconArtifacts({
+      lexiconJsonFilename: "lexicon-test.json",
+      requiredNames: ["NotThere"],
+      basePath: fixture({ snapshot: stale }),
+      checkSurfaceSnapshot: "always",
+      env: { CHANT_SNAPSHOT_UPDATE: "1" },
+    });
+    expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
+    expect(result.checks.find((c) => c.name === "required-names")?.ok).toBe(false);
+    expect(result.success).toBe(false);
+  });
 });

package/src/codegen/validate.ts

@@ -27,6 +27,17 @@ export interface ValidateResult {
  */
 export const RELEASE_GATE_ENV = "CHANT_RELEASE_GATE";
 
+/**
+ * Set by `chant dev surface-diff --update-snapshot` for the validate run it
+ * performs before rewriting the baseline (chant #1825). When set to "1", the
+ * `surface-matches-snapshot` check is skipped. That check fails on exactly the
+ * staleness the update run exists to fix, and with an `"always"` gate (#1475)
+ * the two would deadlock: validate cannot pass until the snapshot is updated,
+ * and the snapshot cannot be updated until validate passes. Every other check
+ * still runs, so a broken generate cannot be baselined.
+ */
+export const SNAPSHOT_UPDATE_ENV = "CHANT_SNAPSHOT_UPDATE";
+
 export interface LexiconValidationConfig {
   /** Filename of the lexicon JSON (e.g. "lexicon-mydom.json") */
   lexiconJsonFilename: string;
@@ -201,10 +212,18 @@ export async function validateLexiconArtifacts(config: LexiconValidationConfig):
   // Runs on the artifacts already on disk — no second generation — and is
   // skipped for a lexicon with no committed snapshot, which is the case for a
   // new lexicon before its first baseline.
+  //
+  // A re-baseline run (`chant dev surface-diff --update-snapshot`) sets
+  // {@link SNAPSHOT_UPDATE_ENV} and is exempt: the check would fail on the
+  // stale snapshot that run is about to rewrite, deadlocking the documented
+  // update flow against an `"always"` gate (#1825). Only this check is exempt —
+  // every other check above still gates the run.
   const snapshotPath = join(config.basePath, "surface.snapshot.json");
+  const env = config.env ?? process.env;
   const surfaceGate =
-    config.checkSurfaceSnapshot === "always" ||
-    (config.checkSurfaceSnapshot === true && (config.env ?? process.env)[RELEASE_GATE_ENV] === "1");
+    (config.checkSurfaceSnapshot === "always" ||
+      (config.checkSurfaceSnapshot === true && env[RELEASE_GATE_ENV] === "1")) &&
+    env[SNAPSHOT_UPDATE_ENV] !== "1";
   if (surfaceGate && lexiconData && existsSync(snapshotPath) && existsSync(dtsPath)) {
     try {
       const fresh = extractSurface(readFileSync(lexiconPath, "utf-8"), readFileSync(dtsPath, "utf-8"));

package/src/components/auto-release.ts

@@ -117,6 +117,10 @@ export interface AutoReleaseRunInfo {
   digest?: string;
   /** Orchestrator run identifier — a Temporal `runId`, or a locally generated id for the local executor (mirrors `runComponentsReleaseRecord`'s `--run-id` default). */
   runId: string;
+  /** The bypassed capability-profile divergences, when the caller deliberately overrode a deploy-time profile assertion (chant #1244) — recorded verbatim as the release record's `profileOverride`. */
+  profileOverride?: string;
+  /** The deploy's input-side digest, when `digest` is a rendered-content identity (a pinned helm deploy, chant #1242) — recorded as the release record's `inputDigest` so ledger queries can still join on inputs across clusters whose bytes legitimately differ. */
+  inputDigest?: string;
 }
 
 /** Opt-out + field-override knobs for auto-release recording, threaded from CLI flags/config (#597: "opt-out-able (flag/config), documented default"). */
@@ -202,6 +206,8 @@ export async function maybeRecordAutoRelease(
         runId: run.runId,
         timestamp,
         actor,
+        ...(run.profileOverride ? { profileOverride: run.profileOverride } : {}),
+        ...(run.inputDigest ? { inputDigest: run.inputDigest } : {}),
       },
       { cwd: options.cwd },
     );

package/src/components/registry.test.ts

@@ -92,9 +92,14 @@ describe("createCapabilityRegistry", () => {
     }
   });
 
-  test("family table lists exactly the agnostic starter families (cloud leaves moved to lexicons)", () => {
+  // Every AWS/k8s cloud leaf moved out to its lexicon — but the three
+  // Cloudflare Workers apply verbs (#1293, epic #1296) stay in core by
+  // deliberate decision (see ./verbs/wrangler.ts's module doc): the epic
+  // cedes the Workers plane to `wrangler` and there is no cloudflare lexicon
+  // for them to live in instead.
+  test("family table lists exactly the agnostic starter families plus the Cloudflare apply leaves (#1293)", () => {
     expect(Object.keys(STARTER_VERB_FAMILIES).sort()).toEqual(
-      ["build", "escapeHatch", "sbom", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
+      ["build", "cloudflare", "escapeHatch", "sbom", "secrets", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
     );
   });