@intentius/chant 0.121.1 → 0.123.0

package/src/cli/commands/lint.ts

@@ -1,4 +1,4 @@
-import { resolve, join, relative } from "path";
+import { resolve, join, relative, dirname } from "path";
 import type { BuildParamProvenance } from "../../provenance";
 import { readFileSync, writeFileSync, readdirSync } from "fs";
 import { runLint, parseDisableComments } from "../../lint/engine";
@@ -24,6 +24,14 @@ import { walkDiscovery, workspaceMemberDirs } from "../../discovery/walk";
 import { buildParamValues, resolveBuildParams } from "../../build-params";
 import { setBuildParams } from "../../params";
 import { isNoLexiconDetected } from "../../detectLexicon";
+import { build } from "../../build";
+import { loadChantConfigUpward, resolveOwnershipEnv, resolveOwnershipMarker } from "../../config";
+import { resolveBuildModes, resolveProjectBuildOptions } from "../build-options";
+import { resolveTelemetryAttribution } from "../../telemetry-attribution";
+import { applyConfiguredPreset, applyConfiguredSeverity, resolvePresetIds } from "../../lint/config";
+import { applyInlineSuppressions } from "../../lint/suppressions";
+import { getProvenance } from "../../provenance";
+import { runLexiconPostSynthChecks } from "./build";
 
 // Import config loader
 import { loadConfig, resolveRulesForFile, resolveConfiguredSeverity, findProjectRoot } from "../../lint/config";
@@ -130,6 +138,16 @@ function lexiconResolutionDiagnostic(projectRoot: string, error: Error): LintDia
   };
 }
 
+/**
+ * The diagnostic id `chant lint` reports a lint target that does not build
+ * under (chant #3750). The lexicons' post-synth checks read a build result, so
+ * when the build fails they cannot run; this says so instead of letting the
+ * lint pass in silence. Like {@link LEXICON_RESOLUTION_RULE_ID} it is not a
+ * rule: it has no severity setting and no disable form. The message is the
+ * build's own.
+ */
+export const BUILD_FAILURE_RULE_ID = "LEX002";
+
 /**
  * The plugins of lexicons that the project's source imports from and that are not in `configured`, for their
  * property-kind class names (#3184). A package that is not installed, or that fails to load, is skipped.
@@ -295,6 +313,13 @@ export interface LintOptions {
    * `sandbox` option (../../components/discover.ts).
    */
   sandbox?: boolean;
+  /**
+   * chant #3750 — run each loaded lexicon's post-synth checks over an
+   * in-memory build of the target (default `true`, what the CLI always does).
+   * `false` lints source alone; it exists for test harnesses that check an
+   * example's source rules, not for hiding findings from a user.
+   */
+  postSynth?: boolean;
 }
 
 /**
@@ -630,6 +655,135 @@ async function runOpCheckDiagnostics(
   return { diagnostics, suppressed };
 }
 
+/**
+ * Run each loaded lexicon's own post-synth checks (#3750), the ones `chant
+ * build` runs after it serializes, over an in-memory build of the lint target.
+ *
+ * The build is `chant build`'s: the same `build()` call with options from the
+ * same assembler (`../build-options.ts`), and the same per-lexicon scoping of
+ * outputs (`runLexiconPostSynthChecks`, ./build.ts). Nothing is written. It
+ * builds `infraPath`, the target the caller asked to lint, never the project
+ * root above it, so `chant lint <dir>` costs a build of `<dir>` and nothing
+ * more (the same scoping {@link runOpCheckDiagnostics} documents). It is
+ * skipped outright when no loaded lexicon ships post-synth checks, which keeps
+ * a project with no lexicon, and every core-only fixture, from building at
+ * all.
+ *
+ * A target that does not build reports each build error under
+ * {@link BUILD_FAILURE_RULE_ID} and skips the checks. Findings go through
+ * `lint.presets`, then `lint.rules`, then inline `chant-ignore` comments, the
+ * order `chant build` applies them in. A finding carries no line (see
+ * ../../lint/post-synth.ts's `PostSynthDiagnostic`), so it is reported at
+ * `1:1` in the file that declared its entity, or at the config file (the
+ * project root without one) when it names none.
+ */
+async function runLexiconPostSynthDiagnostics(
+  infraPath: string,
+  plugins: readonly LexiconPlugin[],
+  buildParams?: BuildParamProvenance[],
+  sandbox?: boolean,
+): Promise<{ diagnostics: LintDiagnostic[]; suppressed: Array<LintDiagnostic & { reason?: string }> }> {
+  const diagnostics: LintDiagnostic[] = [];
+  const suppressed: Array<LintDiagnostic & { reason?: string }> = [];
+  const withChecks = plugins.filter((plugin) => (plugin.postSynthChecks?.() ?? []).length > 0);
+  if (withChecks.length === 0) return { diagnostics, suppressed };
+
+  const projectRoot = findProjectRoot(infraPath);
+  const lintConfig = loadConfig(projectRoot);
+  // Where a finding that names no declared entity is reported: the config the
+  // build loads once it is known (past a lint-only fragment), else the nearest.
+  let fallbackFile = findProjectConfig(projectRoot).configPath ?? projectRoot;
+  const buildFailure = (message: string, at?: { file?: string; line?: number; column?: number }): LintDiagnostic => ({
+    file: at?.file ?? fallbackFile,
+    line: at?.line ?? 1,
+    column: at?.column ?? 1,
+    ruleId: BUILD_FAILURE_RULE_ID,
+    severity: "error",
+    message,
+  });
+
+  let result: Awaited<ReturnType<typeof build>>;
+  let env: string | undefined;
+  let telemetry: Awaited<ReturnType<typeof resolveTelemetryAttribution>>;
+  let configDir = infraPath;
+  let loadedConfig: Record<string, unknown> | undefined;
+  try {
+    const loaded = await loadChantConfigUpward(infraPath);
+    const config = loaded.config;
+    loadedConfig = config as unknown as Record<string, unknown>;
+    configDir = loaded.configPath ? dirname(loaded.configPath) : infraPath;
+    if (loaded.configPath) fallbackFile = loaded.configPath;
+    // The caller's parameters when it resolved them (the CLI does, from the
+    // same upward config walk); otherwise the declared defaults and `env`
+    // mappings of the config this build loads. Not lintCommand's own fallback:
+    // that one reads the config at the lint root, which may be a lint-only
+    // fragment with no `buildParams` (a `src/chant.config.json`).
+    const params = buildParams ?? resolveBuildParams(config.buildParams, { env: process.env }).provenance;
+    env = resolveOwnershipEnv(config, params);
+    telemetry = await resolveTelemetryAttribution(configDir, config as unknown as Record<string, unknown>, env);
+    // Every lexicon the lint loaded, as `chant build` serializes with every
+    // lexicon it loaded: a check may read another lexicon's entities, and the
+    // outputs are scoped per plugin below either way.
+    result = await build(
+      infraPath,
+      plugins.map((plugin) => plugin.serializer),
+      undefined,
+      resolveProjectBuildOptions({
+        config,
+        configDir,
+        plugins,
+        modes: resolveBuildModes(config, { sandbox }),
+        ownership: resolveOwnershipMarker(config, params),
+        buildParams: params,
+        telemetry,
+      }),
+    );
+  } catch (err) {
+    diagnostics.push(buildFailure(err instanceof Error ? err.message : String(err)));
+    return { diagnostics, suppressed };
+  }
+
+  if (result.errors.length > 0) {
+    const seen = new Set<string>();
+    for (const error of result.errors) {
+      const at = error as unknown as { file?: string; line?: number; column?: number };
+      const key = `${at.file ?? ""}:${at.line ?? ""}:${error.message}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      diagnostics.push(buildFailure(error.message, at));
+    }
+    return { diagnostics, suppressed };
+  }
+
+  const activityContracts = await loadActivityContracts(plugins);
+  const fileOf = (entity?: string): string => {
+    const declared = entity ? result.entities.get(entity) : undefined;
+    return (declared && getProvenance(declared)?.sourceFile) || fallbackFile;
+  };
+  const toLint = (d: { checkId: string; severity: LintDiagnostic["severity"]; message: string; entity?: string; lexicon?: string }): LintDiagnostic => ({
+    file: fileOf(d.entity),
+    line: 1,
+    column: 1,
+    ruleId: d.checkId,
+    severity: d.severity,
+    message: `${d.entity ? `[${d.entity}] ` : ""}${d.message}`,
+  });
+
+  for (const { plugin, diagnostics: raw } of runLexiconPostSynthChecks(withChecks, result, env, { activityContracts, telemetry, projectDir: configDir, ...(loadedConfig ? { projectConfig: loadedConfig } : {}) })) {
+    const presetIds = resolvePresetIds(plugin.lintPresets?.(), lintConfig.presets?.[plugin.name] ?? "recommended");
+    const afterPreset = applyConfiguredPreset(raw, presetIds, lintConfig.rules).diagnostics;
+    const afterConfig = applyConfiguredSeverity(afterPreset, lintConfig.rules).diagnostics;
+    const inline = applyInlineSuppressions(afterConfig, result.entities, lintConfig.rules);
+    for (const d of inline.diagnostics) diagnostics.push(toLint(d));
+    for (const d of inline.suppressed) suppressed.push({ ...toLint(d), reason: "chant-ignore" });
+    for (const m of inline.meta) {
+      diagnostics.push({ file: m.file, line: m.line, column: 1, ruleId: m.checkId, severity: m.severity, message: m.message });
+    }
+  }
+
+  return { diagnostics, suppressed };
+}
+
 /**
  * Apply fixes to a file
  */
@@ -817,6 +971,16 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
     suppressed.push(...postOpResult.suppressed);
   }
 
+  // chant #3750: each lexicon's own post-synth checks, over an in-memory
+  // build of the lint target. Run once, after any `--fix` above, so it sees
+  // the source as fixed; a post-synth finding has no fix of its own. Skipped
+  // when a lexicon failed to resolve, which LEX001 below already reports.
+  if (!loaded.lexiconError && options.postSynth !== false) {
+    const lexiconResult = await runLexiconPostSynthDiagnostics(infraPath, loaded.plugins, options.buildParams, options.sandbox);
+    diagnostics.push(...lexiconResult.diagnostics);
+    suppressed.push(...lexiconResult.suppressed);
+  }
+
   // chant #2222: a lexicon the project declared but this run could not
   // resolve. Appended here, after the `--fix` re-lint block above has finished
   // reassigning `diagnostics`, so it survives every path; it is a property of

package/src/cli/handlers/__snapshots__/build-member.test.ts.snap

@@ -12,7 +12,7 @@ env:
 jobs:
   shared-alb:
     runs-on: ubuntu-latest
-    container: node:22-slim
+    container: node:22
     steps:
       - uses: actions/checkout@v7
       - run: chant run --components shared-alb --env staging --dump-outputs shared-alb.outputs.json
@@ -25,7 +25,7 @@ jobs:
     runs-on: ubuntu-latest
     needs:
       - shared-alb
-    container: node:22-slim
+    container: node:22
     steps:
       - uses: actions/checkout@v7
       - name: Download shared-alb outputs

package/src/cli/handlers/gate-resume.ts

@@ -60,6 +60,7 @@ export async function resumeStanding(
   standing: PendingGateRecord,
   resolutions: readonly GateResolutionRecord[],
   opts: ResumeGateOptions = {},
+  pending: readonly PendingGateRecord[] = [standing],
 ): Promise<GateResumeReport> {
   const base = {
     op: standing.op,
@@ -67,7 +68,7 @@ export async function resumeStanding(
     ...(standing.environment !== undefined ? { environment: standing.environment } : {}),
     ...(standing.resume?.url ? { url: standing.resume.url } : {}),
   };
-  const answer = resolutionAnswering(resolutions, standing);
+  const answer = resolutionAnswering(resolutions, standing, pending);
   if (!answer) return { ...base, status: "not-approved", message: "no approval answers it yet" };
   const approvedBy = { approvedBy: answer.resolvedBy };
   if (!isGateRunLocator(standing.resume)) {
@@ -99,7 +100,7 @@ export async function resumeOpGates(op: string, gate: string | undefined, opts:
   const reports: GateResumeReport[] = [];
   for (const standing of standingFacts(ledger.pending, gate)) {
     if (isPendingGateExpired(standing, now)) continue;
-    reports.push(await resumeStanding(standing, ledger.resolutions, opts));
+    reports.push(await resumeStanding(standing, ledger.resolutions, opts, ledger.pending));
   }
   return reports;
 }

package/src/cli/handlers/operator.test.ts

@@ -77,6 +77,7 @@ vi.mock("../../op/gate-approval", async () => {
 
 // Imported after the mocks above are registered.
 const { runOperator, runOperatorStatus, runOperatorLog, runApprove } = await import("./operator");
+const { gateContextDigest } = await import("../../op/gate-approval");
 
 function ctx(args: Partial<ParsedArgs>) {
   return {
@@ -386,6 +387,16 @@ describe("runApprove", () => {
     errSpy.mockRestore();
   });
 
+  // #3760: --rule and --reason belong to an override of a denied plan.
+  test("refuses --rule and --reason on a gate that is not the override gate", async () => {
+    seedPending("fountain-apply", "rollout-gate", PLAN_A);
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", rules: ["no-drop"], reason: "why" }))).toBe(1);
+    expect(errSpy.mock.calls.flat().join("\n")).toMatch(/--rule and --reason override a denied plan: chant approve policy-override <subject>/);
+    expect(appendGateResolutionMock).not.toHaveBeenCalled();
+    errSpy.mockRestore();
+  });
+
   test("appends a gate-resolution record and pushes, resolving --actor over env fallbacks", async () => {
     seedPending("fountain-apply", "rollout-gate", PLAN_A);
     appendGateResolutionMock.mockResolvedValue({
@@ -1115,7 +1126,7 @@ describe("runApprove — a gate with an approval policy (#2508)", () => {
     expect(appendGateResolutionMock).toHaveBeenCalledWith(expect.objectContaining({
       approver: { kind: "agent" },
       policyDecision: {
-        policy: "ship", version: "sha256:v1", mode: "enforce",
+        policy: "ship", version: "sha256:v1", mode: "enforce", contextDigest: gateContextDigest({ risk: "low" }),
         decision: "allow", determining: ["agent-low-risk"], errors: [],
       },
     }));

package/src/cli/handlers/operator.ts

@@ -42,13 +42,13 @@ import {
   latestResolutionSince, latestPendingGate, isPendingGateExpired,
   resolveApprovalUrl, isApprovalUrl,
 } from "../../lifecycle/gate-ledger";
-import { isPlanDigest } from "../../lifecycle/plan-digest";
+import { isPlanDigest, samePlanDigest } from "../../lifecycle/plan-digest";
 import {
-  gatePolicyRequest, loadGatePolicyEvaluator,
+  gateContextDigest, gatePolicyRequest, loadGatePolicyEvaluator,
   type GateApprover, type GatePolicyDecision, type GatePolicyEvaluator, type ResolvedGateApproval,
 } from "../../op/gate-approval";
-import { approverOf, tallyGateApprovals } from "../../op/gate";
-import { FAN_OUT_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name";
+import { approverOf, humanQuorumSince, tallyGateApprovals } from "../../op/gate";
+import { FAN_OUT_GATE_OP, OVERRIDE_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name";
 import { PR_GATE_OP } from "../../pr-loop";
 import { pushLifecycleReport, requireLifecycleLedger } from "../../lifecycle/git";
 import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note";
@@ -888,6 +888,19 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     return 0;
   }
 
+  // #3760: an override of a denied plan names its rules and gives a reason.
+  if (opName === OVERRIDE_GATE_OP) {
+    const { runOverrideApprove } = await import("./override-approve");
+    return runOverrideApprove(ctx);
+  }
+  if (ctx.args.rules !== undefined || ctx.args.reason !== undefined) {
+    console.error(formatError({
+      message: `--rule and --reason override a denied plan: chant approve ${OVERRIDE_GATE_OP} <subject> --rule <id> --reason <text>`,
+      hint: `To approve gate "${gate}" on "${opName}", put any prose in --note.`,
+    }));
+    return 1;
+  }
+
   // `--approver` wins over `--actor`, the same precedence `chant run approve`
   // has applied since #2126 (`../handlers/run.ts`'s `runOpApprove`). Reading
   // only `--actor` here meant every README that teaches `--approver you`
@@ -1016,7 +1029,7 @@ export async function recordGateApproval(
   // `fan-out` is the op name every `chant components fan-out` gate is recorded
   // under (../handlers/fan-out.ts). It is a command rather than a declaration,
   // so there is no `*.op.ts` to find and nothing is wrong when none is there.
-  if (!ops.has(opName) && opName !== FAN_OUT_GATE_OP && opName !== WORKSPACE_UPGRADE_GATE_OP) {
+  if (!ops.has(opName) && opName !== FAN_OUT_GATE_OP && opName !== WORKSPACE_UPGRADE_GATE_OP && opName !== OVERRIDE_GATE_OP) {
     console.error(formatWarning({
       message: `Op "${opName}" was not found among discovered *.op.ts declarations — recording the resolution anyway`,
     }));
@@ -1260,6 +1273,7 @@ export async function recordGateApproval(
         policy: approval.policy.name,
         version: approval.policy.version,
         mode: approval.mode,
+        contextDigest: gateContextDigest(approval.context),
         decision: answer.decision,
         determining: answer.determining,
         errors: answer.errors,
@@ -1310,7 +1324,7 @@ export async function recordGateApproval(
     ));
   }
   if (approval) {
-    for (const line of describeApprovalProgress(approval, record, ledger.resolutions, standingForOrigin)) {
+    for (const line of describeApprovalProgress(approval, record, ledger.resolutions, standingForOrigin, ledger.pending)) {
       console.error(formatInfo(line));
     }
   }
@@ -1328,6 +1342,7 @@ export function describeApprovalProgress(
   record: GateResolutionRecord,
   prior: GateResolutionRecord[],
   standing: PendingGateRecord | undefined,
+  pending: readonly PendingGateRecord[] = standing ? [standing] : [],
 ): string[] {
   const lines: string[] = [];
   const decision = record.policyDecision;
@@ -1343,13 +1358,10 @@ export function describeApprovalProgress(
     for (const error of decision.errors) lines.push(`Policy evaluation error: ${error}`);
   }
 
-  const tally = tallyGateApprovals(
-    [...prior, record],
-    record.gate,
-    standing?.timestamp ?? new Date(0).toISOString(),
-    record.planDigest,
-    approval,
-  );
+  const since = standing?.timestamp ?? new Date(0).toISOString();
+  // #3206: count the humans the way the run will, back past facts re-recorded for this plan.
+  const humansSince = standing && samePlanDigest(standing.planDigest, record.planDigest) ? humanQuorumSince(pending, standing) : since;
+  const tally = tallyGateApprovals([...prior, record], record.gate, since, record.planDigest, approval, humansSince);
   const roles = approval.quorum?.roles ? ` with role ${approval.quorum.roles.join(" or ")}` : "";
   const who = tally.counted.map((r) => r.resolvedBy).join(", ") || "none yet";
   lines.push(`Quorum: ${tally.counted.length} of ${tally.need} human approval(s)${roles} for this plan (${who}).`);

package/src/cli/handlers/override-approve.test.ts

@@ -0,0 +1,87 @@
+/**
+ * #3760: `chant approve policy-override <subject> --rule <id> --reason <text>`
+ * records an override of the subject's recorded denial, for exactly that
+ * plan and those rules.
+ */
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import type { ParsedArgs } from "../registry";
+import { overrideDigest, overridePending, OVERRIDE_OP } from "../../override-gate";
+
+const recordGateApprovalMock = vi.fn();
+const readOverrideLedgerMock = vi.fn();
+const requireLifecycleLedgerMock = vi.fn();
+const originMock = vi.fn(() => "cli");
+
+vi.mock("./operator", () => ({ recordGateApproval: (...a: unknown[]) => recordGateApprovalMock(...a) }));
+vi.mock("../../lifecycle/override-ledger", () => ({ readOverrideLedger: (...a: unknown[]) => readOverrideLedgerMock(...a) }));
+vi.mock("../../lifecycle/git", () => ({ requireLifecycleLedger: (...a: unknown[]) => requireLifecycleLedgerMock(...a) }));
+vi.mock("../../lifecycle/gate-origin", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/gate-origin")>("../../lifecycle/gate-origin");
+  return { ...actual, currentGateOrigin: () => originMock() };
+});
+
+const { runOverrideApprove } = await import("./override-approve");
+
+const PLAN = `sha256:${"a".repeat(64)}`;
+const DENIAL = overridePending({ subject: "prod", planDigest: PLAN, rules: ["no-drop", "no-lock"], timestamp: "2026-10-11T10:00:00.000Z", expiresAt: "2099-01-01T00:00:00.000Z" });
+
+function ctx(args: Partial<ParsedArgs>) {
+  return {
+    args: { command: "approve", path: OVERRIDE_OP, extraPositional: "prod", format: "", fix: false, watch: false, verbose: false, help: false, live: false, ...args } as ParsedArgs,
+    plugins: [],
+    serializers: [],
+  };
+}
+
+let err: ReturnType<typeof vi.spyOn>;
+const printed = () => err.mock.calls.flat().join("\n");
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  err = vi.spyOn(console, "error").mockImplementation(() => undefined);
+  originMock.mockReturnValue("cli");
+  requireLifecycleLedgerMock.mockResolvedValue(undefined);
+  readOverrideLedgerMock.mockResolvedValue({ resolutions: [], pending: [DENIAL], applied: [] });
+  recordGateApprovalMock.mockResolvedValue({ ok: true, pushed: true, record: { version: 1, op: OVERRIDE_OP, gate: "prod", resolvedBy: "github:alice", timestamp: "2026-10-11T11:00:00.000Z" } });
+});
+
+describe("chant approve policy-override", () => {
+  test("approves the denial's override digest with the reason as its note", async () => {
+    const code = await runOverrideApprove(ctx({ rules: ["no-lock", "no-drop"], reason: " the table is empty ", actor: "github:alice", sign: true }));
+    expect(code).toBe(0);
+    expect(recordGateApprovalMock).toHaveBeenCalledWith(OVERRIDE_OP, "prod", expect.objectContaining({
+      actor: "github:alice", note: "the table is empty", plan: overrideDigest("prod", PLAN, ["no-drop", "no-lock"]), sign: true,
+    }));
+    expect(printed()).toMatch(/overrides the denial of prod by no-drop, no-lock for the plan sha256:a{64}/);
+  });
+
+  test("--note is the same field as --reason", async () => {
+    expect(await runOverrideApprove(ctx({ rules: ["no-drop", "no-lock"], note: "empty table" }))).toBe(0);
+    expect(recordGateApprovalMock).toHaveBeenCalledWith(OVERRIDE_OP, "prod", expect.objectContaining({ note: "empty table" }));
+    expect(await runOverrideApprove(ctx({ rules: ["no-drop", "no-lock"], note: "a", reason: "b" }))).toBe(1);
+  });
+
+  test.each<[string, Partial<ParsedArgs>, RegExp]>([
+    ["no rule", { reason: "why" }, /names each rule it overrides with --rule/],
+    ["no reason", { rules: ["no-drop", "no-lock"], reason: "  " }, /needs --reason/],
+    ["other rules", { rules: ["no-drop"], reason: "why" }, /denied by no-drop, no-lock; an override names exactly those rules, and --rule gave no-drop/],
+    ["another plan", { rules: ["no-drop", "no-lock"], reason: "why", plan: `sha256:${"b".repeat(64)}` }, /is not the plan denied for prod/],
+    ["an agent", { rules: ["no-drop", "no-lock"], reason: "why", agent: true }, /An override is a person.s/],
+    ["no denial", { rules: ["x"], reason: "why", extraPositional: "staging" }, /No denial of staging is recorded on policy-override; denied: prod/],
+  ])("refuses %s, and records nothing", async (_name, args, why) => {
+    expect(await runOverrideApprove(ctx(args))).toBe(1);
+    expect(printed()).toMatch(why);
+    expect(recordGateApprovalMock).not.toHaveBeenCalled();
+  });
+
+  test("is refused over MCP", async () => {
+    originMock.mockReturnValue("mcp");
+    expect(await runOverrideApprove(ctx({ rules: ["no-drop", "no-lock"], reason: "why" }))).toBe(1);
+    expect(recordGateApprovalMock).not.toHaveBeenCalled();
+  });
+
+  test("--plan may name the denied plan or the override digest", async () => {
+    expect(await runOverrideApprove(ctx({ rules: ["no-drop", "no-lock"], reason: "why", plan: PLAN }))).toBe(0);
+    expect(await runOverrideApprove(ctx({ rules: ["no-drop", "no-lock"], reason: "why", plan: DENIAL.planDigest }))).toBe(0);
+  });
+});

package/src/cli/handlers/override-approve.ts

@@ -0,0 +1,103 @@
+/**
+ * `chant approve policy-override <subject> --rule <id>... --reason <text>`
+ * (#3760): record a person's override of the denial a run recorded for
+ * `subject`. The override is an approval of the denial's override digest
+ * (`../../override-gate.ts`), with the reason as its note, written by the
+ * same `recordGateApproval` every `chant approve` uses, so `--sign`,
+ * `--actor`, `--relayed-by` and `--url` work as they do there.
+ *
+ * It names the rules it overrides, which must be exactly the rules the denial
+ * recorded: the approver says what they are letting through. Whether the
+ * override counts is decided by the run, against the overriders and signers
+ * at base; this command only warns when the checkout's own overriders file
+ * would not count it.
+ */
+
+import { currentGateOrigin, isModelAuthored } from "../../lifecycle/gate-origin";
+import { requireLifecycleLedger } from "../../lifecycle/git";
+import { readOverrideLedger } from "../../lifecycle/override-ledger";
+import { samePlanDigest } from "../../lifecycle/plan-digest";
+import { OVERRIDE_OP, OVERRIDERS_PATH, overrideCommand, overridersAt, recordedDenials, sortedRules } from "../../override-gate";
+import { formatError, formatInfo, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+import { recordGateApproval } from "./operator";
+
+const norm = (s: string): string => s.normalize("NFKC").trim().toLowerCase();
+
+export async function runOverrideApprove(ctx: CommandContext): Promise<number> {
+  const subject = ctx.args.extraPositional!;
+  const usage = overrideCommand(subject, ctx.args.rules?.length ? ctx.args.rules : ["<id>"]);
+  if (ctx.args.reason !== undefined && ctx.args.note !== undefined && ctx.args.reason.trim() !== ctx.args.note.trim()) {
+    console.error(formatError({ message: "Give the override's reason once: --reason <text> (--note is the same field)", hint: usage }));
+    return 1;
+  }
+  const reason = (ctx.args.reason ?? ctx.args.note)?.trim();
+  const rules = sortedRules(ctx.args.rules ?? []);
+  if (rules.length === 0) {
+    console.error(formatError({ message: `An override names each rule it overrides with --rule <id>`, hint: usage }));
+    return 1;
+  }
+  if (!reason) {
+    console.error(formatError({ message: `An override needs --reason <text>: why this plan goes out although the policy denies it`, hint: usage }));
+    return 1;
+  }
+  if (ctx.args.agent || isModelAuthored(currentGateOrigin())) {
+    console.error(formatError({ message: `An override is a person's: it is never recorded by an agent or over MCP or ACP`, hint: `${usage}, at a shell.` }));
+    return 1;
+  }
+
+  try {
+    await requireLifecycleLedger();
+  } catch (err) {
+    console.error(formatError({ message: `Cannot record the override: ${err instanceof Error ? err.message : String(err)}` }));
+    return 1;
+  }
+  const ledger = await readOverrideLedger();
+  const denials = recordedDenials(ledger.pending);
+  const denial = denials.find((d) => d.gate === subject);
+  if (!denial) {
+    console.error(formatError({
+      message: `No denial of ${subject} is recorded on ${OVERRIDE_OP}` + (denials.length ? `; denied: ${denials.map((d) => d.gate).join(", ")}` : ""),
+      hint: "A run records one when its policy denies the plan. An override answers that denial, for that plan.",
+    }));
+    return 1;
+  }
+  if (denial.rules.join("\n") !== rules.join("\n")) {
+    console.error(formatError({
+      message: `${subject} was denied by ${denial.rules.join(", ") || "no rule it named"}; an override names exactly those rules, and --rule gave ${rules.join(", ")}`,
+      hint: overrideCommand(subject, denial.rules),
+    }));
+    return 1;
+  }
+  if (ctx.args.plan !== undefined && !samePlanDigest(ctx.args.plan, denial.plan) && !samePlanDigest(ctx.args.plan, denial.planDigest)) {
+    console.error(formatError({
+      message: `--plan ${ctx.args.plan} is not the plan denied for ${subject}: the newest denial is of ${denial.plan || denial.planDigest}`,
+      hint: "Run the plan again, or override the denial that stands.",
+    }));
+    return 1;
+  }
+
+  const outcome = await recordGateApproval(OVERRIDE_OP, subject, {
+    actor: ctx.args.approver ?? ctx.args.actor,
+    note: reason,
+    url: ctx.args.url,
+    plan: denial.planDigest!,
+    allowSameOrigin: ctx.args.allowSameOrigin,
+    ...(ctx.args.roles ? { roles: ctx.args.roles } : {}),
+    ...(ctx.args.sign !== undefined ? { sign: ctx.args.sign } : {}),
+    ...(ctx.args.relayedBy !== undefined ? { relayedBy: ctx.args.relayedBy } : {}),
+  });
+  if (!outcome.ok) return 1;
+
+  console.error(formatInfo(
+    `This overrides the denial of ${subject} by ${rules.join(", ")} for the plan ${denial.plan || denial.planDigest}. ` +
+      `The next run that plans it applies it once; a plan that moves, or rules that change, need their own override.`,
+  ));
+  const here = overridersAt(process.cwd(), "HEAD");
+  if (!here.active) {
+    console.error(formatWarning({ message: `This checkout has no ${OVERRIDERS_PATH}: unless the run reads its overriders from elsewhere at base, no override counts` }));
+  } else if (!here.principals.map(norm).includes(norm(outcome.record.resolvedBy))) {
+    console.error(formatWarning({ message: `${outcome.record.resolvedBy} is not in ${OVERRIDERS_PATH} here (${here.principals.join(", ") || "nobody"}), so a run that reads it at base does not count this override` }));
+  }
+  return 0;
+}

package/src/cli/handlers/run-wave.ts

@@ -5,7 +5,9 @@
 
 import { readFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
+import { notifyOpWave } from "../../op/op-waves-notify";
 import { parseOpWavesSpec, recordOpWaveHeadPlans, runOpWave } from "../../op/op-waves-run";
+import type { OpWavesSpec } from "../../op/op-waves";
 import { formatError } from "../format";
 import type { CommandContext } from "../registry";
 
@@ -35,9 +37,11 @@ export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
     console.error(formatError({ message: "--decide and --share are two different jobs; pass one" }));
     return 1;
   }
+  let spec: OpWavesSpec | undefined;
+  const job = args.share !== undefined ? { share: args.share } : {};
   try {
     const path = resolve(specFile);
-    const spec = parseOpWavesSpec(readFileSync(path, "utf-8"), `--spec ${specFile}`);
+    spec = parseOpWavesSpec(readFileSync(path, "utf-8"), `--spec ${specFile}`);
     const result = await runOpWave({
       spec,
       specFile: relative(process.cwd(), path),
@@ -47,9 +51,13 @@ export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
       ...(args.base ? { base: args.base } : {}),
     });
     if (args.json) console.log(JSON.stringify(result, null, 2));
+    // #3761: tell people, when the spec says where. Delivery never changes the exit code.
+    await notifyOpWave(spec, args.wave, { result }, job);
     return result.exitCode;
   } catch (err) {
-    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(formatError({ message }));
+    if (spec) await notifyOpWave(spec, args.wave, { error: message }, job);
     return 1;
   }
 }

package/src/cli/main.test.ts

@@ -346,6 +346,14 @@ describe("parseArgs", () => {
     expect(result.url).toBe("https://github.com/org/repo/pull/1");
   });
 
+  test("parses --rule (repeated) and --reason for an override (#3760)", () => {
+    const result = parseArgs(["approve", "policy-override", "prod", "--rule", "no-drop", "--rule", "no-lock", "--reason", "the table is empty"]);
+    expect(result.rules).toEqual(["no-drop", "no-lock"]);
+    expect(result.reason).toBe("the table is empty");
+    expect(() => parseArgs(["approve", "policy-override", "prod", "--rule"])).toThrow(/--rule needs a rule id/);
+    expect(() => parseArgs(["approve", "policy-override", "prod", "--reason"])).toThrow(/--reason needs the text/);
+  });
+
   // ── --no-release-record (#597) ───────────────────────────────────────────
 
   test("--promote-to <env> sets promoteTo, and a missing value is refused (#2575)", () => {

package/src/cli/main.ts

@@ -696,6 +696,15 @@ export function parseArgs(args: string[]): ParsedArgs {
       result[arg.slice(2) as "unit" | "decision"] = value;
     } else if (arg === "--note") {
       result.note = args[++i];
+    } else if (arg === "--reason") {
+      // `chant approve policy-override <subject> --reason <text>` (#3760): why the denied plan goes out anyway.
+      result.reason = args[++i];
+      if (result.reason === undefined || result.reason.startsWith("-")) throw new Error("--reason needs the text of the reason: --reason <text>");
+    } else if (arg === "--rule") {
+      // `chant approve policy-override <subject> --rule <id>` (#3760), once per rule that denied the plan.
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error("--rule needs a rule id: --rule <id>");
+      (result.rules ??= []).push(value);
     } else if (arg === "--expire") {
       result.expire = true;
     } else if (arg === "--role") {
@@ -999,6 +1008,12 @@ Ops:
                         --resume then starts the CI job that waits at the
                         gate again (GitHub re-run, GitLab retry, Forgejo
                         dispatch) with CHANT_FORGE_TOKEN
+                        On op policy-override the gate is the subject a
+                        policy denied: --rule <id> names each rule that
+                        denied it and --reason <text> says why the plan goes
+                        out anyway; the next run that plans the same digest
+                        applies it once, if .chant/overriders at base lists
+                        --actor
 
   graph                 Show Op dependency graph (--stacks for cross-stack order,
                         --format ir|mermaid|dot|layout for the lint-gated graph IR,

package/src/cli/registry.ts

@@ -598,6 +598,10 @@ export interface ParsedArgs {
   once?: boolean;
   /** `chant approve <op> <gate> --note <text>` (#1485) — optional free-text prose recorded on the gate-resolution fact. The PR link belongs in `--url` since #2028; this is for everything that isn't the link. */
   note?: string;
+  /** `chant approve policy-override <subject> --reason <text>` (#3760): why a denied plan goes out anyway, recorded as the override's note. */
+  reason?: string;
+  /** `chant approve policy-override <subject> --rule <id>` (#3760), repeated: the rules that denied the plan, which the override names. */
+  rules?: string[];
   /** `chant approve <op> <gate> --expire` (#2119) — clear the gate's standing pending fact instead of approving it, so the next run decides the gate from scratch and records a fresh one. Writes no resolution: nothing is approved, the wait is only restarted. */
   expire?: boolean;
   /**