@intentius/chant 0.124.27 → 0.124.29

package/src/cli/commands/check-lexicon.ts

@@ -457,12 +457,24 @@ export async function checkLexicon(dir: string): Promise<CheckResult> {
     pass: hasSerializerTest,
   });
 
+  // A lexicon whose src/codegen/docs.ts runs docsPipeline always has a page:
+  // the pipeline writes the overview (index.mdx) from the manifest. Inside the
+  // chant repository that page is generated into the main docs site rather
+  // than committed under docs/ (chant #3993), so k3d, whose docs are all
+  // generated, has no .mdx of its own to count.
   const mdxFiles = findFiles(join(dir, "docs"), (n) => n.endsWith(".mdx"));
+  const docsTs = join(dir, "src", "codegen", "docs.ts");
+  const pipelineOverview = existsSync(docsTs) && readFileSync(docsTs, "utf-8").includes("docsPipeline(");
   items.push({
     name: "At least 1 .mdx doc page",
     tier: 1,
-    pass: mdxFiles.length > 0,
-    detail: mdxFiles.length > 0 ? `${mdxFiles.length} page(s)` : undefined,
+    pass: mdxFiles.length > 0 || pipelineOverview,
+    detail:
+      mdxFiles.length > 0
+        ? `${mdxFiles.length} page(s)`
+        : pipelineOverview
+          ? "the docs pipeline's generated overview"
+          : undefined,
   });
 
   // Counting pages says nothing about whether a reader can find them.

package/src/cli/commands/init-lexicon/templates/docs.ts

@@ -1,7 +1,12 @@
 /**
- * Docs site template generators for init-lexicon scaffold.
+ * Docs site template generators for init-lexicon scaffold. The app files
+ * (package.json, tsconfig, Astro config, content config) are written only for a
+ * lexicon outside the chant repository; inside it, the lexicon's docs are a
+ * section of the main site (chant #3993).
  */
 
+import { DOCS_SITE_DEPENDENCIES } from "../../../../codegen/docs-in-site";
+
 export function generateDocsPackageJson(name: string): string {
   return JSON.stringify(
     {
@@ -14,11 +19,7 @@ export function generateDocsPackageJson(name: string): string {
         build: "astro build",
         preview: "astro preview",
       },
-      dependencies: {
-        "@astrojs/starlight": "^0.37.6",
-        astro: "^5.6.1",
-        sharp: "^0.34.2",
-      },
+      dependencies: { ...DOCS_SITE_DEPENDENCIES },
     },
     null,
     2,

package/src/cli/commands/init-lexicon.test.ts

@@ -78,6 +78,31 @@ describe("initLexiconCommand", () => {
     }
   });
 
+  // chant #3993: inside the chant repository the lexicon's docs are a section
+  // of the main site, so only docs/pages/ is scaffolded.
+  test("inside the chant repository it scaffolds docs/pages/ and no docs app", async () => {
+    mkdirSync(join(tmpDir, "docs"), { recursive: true });
+    writeFileSync(join(tmpDir, "docs", "package.json"), JSON.stringify({ name: "@intentius/chant-docs" }));
+    writeFileSync(join(tmpDir, "docs", "astro.config.mjs"), "export default {};\n");
+    const targetDir = join(tmpDir, "lexicons", "in-repo");
+    const result = await initLexiconCommand({ name: "in-repo", path: targetDir });
+
+    expect(result.success).toBe(true);
+    expect(existsSync(join(targetDir, "docs/pages/getting-started.mdx"))).toBe(true);
+    for (const file of ["docs/package.json", "docs/tsconfig.json", "docs/astro.config.mjs", "docs/src"]) {
+      expect(existsSync(join(targetDir, file)), file).toBe(false);
+    }
+  });
+
+  test("a standalone docs app pins the main site's Starlight and Astro", async () => {
+    const targetDir = join(tmpDir, "pins");
+    await initLexiconCommand({ name: "pins", path: targetDir });
+    const docsPkg = JSON.parse(readFileSync(join(targetDir, "docs/package.json"), "utf-8"));
+    const mainPkg = JSON.parse(readFileSync(join(__dirname, "..", "..", "..", "..", "..", "docs", "package.json"), "utf-8"));
+    expect(docsPkg.dependencies["@astrojs/starlight"]).toBe(mainPkg.dependencies["@astrojs/starlight"]);
+    expect(docsPkg.dependencies.astro).toBe(mainPkg.dependencies.astro);
+  });
+
   test("plugin.ts contains all 5 required lifecycle methods", async () => {
     const targetDir = join(tmpDir, "lifecycle");
     await initLexiconCommand({ name: "k8s", path: targetDir });

package/src/cli/commands/init-lexicon.ts

@@ -12,6 +12,7 @@ import { generatePackageJson, generateTsConfig, generateTsConfigBuild, generateJ
 import { generatePluginTestTs, generateSerializerTestTs, generateCompletionsTestTs, generateHoverTestTs } from "./init-lexicon/templates/tests";
 import { generateDocsPackageJson, generateDocsTsConfig, generateDocsAstroConfig, generateDocsContentConfig, generateDocsIndexMdx, generateDocsGettingStartedMdx } from "./init-lexicon/templates/docs";
 import { generateExamplePackageJson, generateExampleInfraTs } from "./init-lexicon/templates/examples";
+import { findChantDocsSite } from "../../codegen/docs-in-site";
 
 /**
  * Init-lexicon command options
@@ -101,6 +102,13 @@ export async function initLexiconCommand(options: InitLexiconOptions): Promise<I
     }
   }
 
+  // Inside the chant repository a lexicon's docs are a section of the main
+  // site (chant #3993): the pipeline writes its pages into docs/, so the
+  // lexicon gets only docs/pages/. Anywhere else it gets a standalone
+  // Starlight app of its own, as before.
+  const standaloneDocs = findChantDocsSite(targetDir) === undefined;
+  const standaloneDocsDirs = ["docs/src", "docs/src/content", "docs/src/content/docs"];
+
   // Create directory structure
   const dirs = [
     "",
@@ -112,9 +120,7 @@ export async function initLexiconCommand(options: InitLexiconOptions): Promise<I
     "src/lsp",
     "src/generated",
     "docs",
-    "docs/src",
-    "docs/src/content",
-    "docs/src/content/docs",
+    ...(standaloneDocs ? standaloneDocsDirs : []),
     "docs/pages",
     "examples/getting-started",
     "examples/getting-started/src",
@@ -157,11 +163,15 @@ export async function initLexiconCommand(options: InitLexiconOptions): Promise<I
     "justfile": generateJustfile(name),
     ".gitignore": generateGitignore(),
     "README.md": generateReadme(name, names),
-    "docs/package.json": generateDocsPackageJson(name),
-    "docs/tsconfig.json": generateDocsTsConfig(),
-    "docs/astro.config.mjs": generateDocsAstroConfig(name),
-    "docs/src/content.config.ts": generateDocsContentConfig(),
-    "docs/src/content/docs/index.mdx": generateDocsIndexMdx(name),
+    ...(standaloneDocs
+      ? {
+          "docs/package.json": generateDocsPackageJson(name),
+          "docs/tsconfig.json": generateDocsTsConfig(),
+          "docs/astro.config.mjs": generateDocsAstroConfig(name),
+          "docs/src/content.config.ts": generateDocsContentConfig(),
+          "docs/src/content/docs/index.mdx": generateDocsIndexMdx(name),
+        }
+      : {}),
     "docs/pages/getting-started.mdx": generateDocsGettingStartedMdx(name),
     "examples/getting-started/package.json": generateExamplePackageJson(name),
     "examples/getting-started/src/infra.ts": generateExampleInfraTs(name, names),

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

@@ -0,0 +1,84 @@
+/**
+ * `chant approve` on a release gate (#4045): the approval copies the release
+ * the pending fact names, with its plan and environment, so it counts for
+ * that release only. Against a temp repo; nothing is pushed.
+ */
+
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendPendingGate, readGateLedger } from "../../lifecycle/gate-ledger";
+import { resetGateOrigin } from "../../lifecycle/gate-origin";
+import { makeRelease, persistRelease } from "../../lifecycle/release-store";
+
+vi.mock("../../op/discover", () => ({ discoverOps: async () => ({ errors: [], ops: new Map() }) }));
+
+const { recordGateApproval } = await import("./approve");
+
+function git(args: string[], cwd: string): void {
+  spawnSync("git", args, { cwd, encoding: "utf-8" });
+}
+
+/** The release the gate binds. #4033: approve reads it to check its commit isn't revoked, so it is stored. */
+const STORED = makeRelease({ member: null, commit: "1".repeat(40), artifactDigests: [], targets: [{ env: "prod", templates: [], params: [] }] });
+const RELEASE = STORED.releaseDigest;
+const DOC = `jcs1-sha256:${"d".repeat(64)}`;
+
+async function repoWithReleaseGate(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "t@chant.dev"], dir);
+  git(["config", "user.name", "T"], dir);
+  writeFileSync(join(dir, "README.md"), "x\n");
+  git(["add", "."], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+  await persistRelease(STORED, [], { cwd: dir });
+  await appendPendingGate(
+    {
+      op: "release",
+      gate: "prod-release",
+      timestamp: "2026-10-16T00:00:00.000Z",
+      expiresAt: "2999-01-01T00:00:00.000Z",
+      planDigest: DOC,
+      environment: "prod",
+      releaseDigest: RELEASE,
+    },
+    { cwd: dir },
+  );
+}
+
+describe("chant approve on a release gate (#4045)", () => {
+  const cwd = process.cwd();
+  afterEach(() => {
+    process.chdir(cwd);
+    resetGateOrigin();
+    vi.restoreAllMocks();
+  });
+
+  test("the approval names the release, the environment and the change set the pending fact names", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    await withTestDir(async (dir) => {
+      await repoWithReleaseGate(dir);
+      process.chdir(dir);
+      const outcome = await recordGateApproval("release", "prod-release", { origin: "cli", actor: "alice", cwd: dir, environment: "prod" });
+      expect(outcome.ok).toBe(true);
+      const { resolutions } = await readGateLedger("release", { cwd: dir });
+      expect(resolutions).toEqual([expect.objectContaining({ resolvedBy: "alice", planDigest: DOC, environment: "prod", releaseDigest: RELEASE })]);
+    });
+  });
+
+  test("an approval of another plan names no release, so no release gate counts it", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    await withTestDir(async (dir) => {
+      await repoWithReleaseGate(dir);
+      process.chdir(dir);
+      const other = `jcs1-sha256:${"e".repeat(64)}`;
+      const outcome = await recordGateApproval("release", "prod-release", { origin: "cli", actor: "alice", cwd: dir, environment: "prod", plan: other });
+      expect(outcome.ok).toBe(true);
+      const { resolutions } = await readGateLedger("release", { cwd: dir });
+      expect(resolutions[0].planDigest).toBe(other);
+      expect(resolutions[0].releaseDigest).toBeUndefined();
+    });
+  });
+});

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

@@ -0,0 +1,155 @@
+/**
+ * #4033 (ws-105): when a commit is revoked, the release cut from it is
+ * revoked, and its pending release gate refuses approval. Against temp repos;
+ * nothing is pushed.
+ */
+
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendPendingGate, readGateLedger } from "../../lifecycle/gate-ledger";
+import { resetGateOrigin } from "../../lifecycle/gate-origin";
+import { appendCut, makeRelease, persistRelease, type Release } from "../../lifecycle/release-store";
+
+vi.mock("../../op/discover", () => ({ discoverOps: async () => ({ errors: [], ops: new Map() }) }));
+
+const { recordGateApproval } = await import("./approve");
+
+function git(cwd: string, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+const DOC = `jcs1-sha256:${"d".repeat(64)}`;
+const GREEN = { branch: "main", phases: { test: ["test"] }, require: ["test"] };
+
+function declaration(dir: string, green: Record<string, unknown>): void {
+  writeFileSync(
+    join(dir, "chant.workspace.json"),
+    JSON.stringify({ name: "acme", schema: 1, members: [{ name: "root", dir: ".", kind: "other", because: "the release fixture" }], ci: { green } }, null, 2),
+  );
+}
+
+/** A green commit, a release cut from it as v1.0.0, and a release gate pending for it in prod. */
+async function releaseWaitingAtGate(dir: string): Promise<{ sha: string; release: Release }> {
+  git(dir, "init", "-q", "-b", "main");
+  git(dir, "config", "user.email", "t@chant.dev");
+  git(dir, "config", "user.name", "T");
+  declaration(dir, GREEN);
+  git(dir, "add", ".");
+  git(dir, "commit", "-q", "-m", "init");
+  const sha = git(dir, "rev-parse", "HEAD");
+  git(dir, "tag", "-a", "-m", "ci: green", `ci/green/${sha}`, sha);
+  const release = makeRelease({
+    member: null,
+    commit: sha,
+    artifactDigests: [],
+    targets: [{ env: "prod", templates: [{ component: "api", path: "t.json", digest: `sha256:${"c".repeat(64)}` }], params: [] }],
+  });
+  await persistRelease(release, [], { cwd: dir });
+  await appendCut({ releaseDigest: release.releaseDigest, label: "v1.0.0", actor: "alice", timestamp: "2026-10-16T10:00:00.000Z", runOrigin: null }, { cwd: dir });
+  await appendPendingGate(
+    {
+      op: "release",
+      gate: "prod-release",
+      timestamp: "2026-10-16T11:00:00.000Z",
+      expiresAt: "2999-01-01T00:00:00.000Z",
+      planDigest: DOC,
+      environment: "prod",
+      releaseDigest: release.releaseDigest,
+      gitSha: sha,
+    },
+    { cwd: dir },
+  );
+  return { sha, release };
+}
+
+/** ci tick's revoked tag for a run from chant runs (#4044): the run's id is null and the Op run is named in opRun. */
+function revoke(dir: string, sha: string): void {
+  const record = {
+    schema: 1,
+    tag: "revoked",
+    commit: sha,
+    branch: "main",
+    at: "2026-10-16T12:00:00.000Z",
+    source: "runs",
+    phase: "test",
+    run: { name: "smoke", id: null, conclusion: "failure", url: null, opRun: { id: "r-12", env: "staging", signer: "runner:ci", statement: null } },
+  };
+  git(dir, "tag", "-a", "-m", `ci: phase test failed in smoke (failure)\n\n${JSON.stringify(record, null, 2)}\n`, `ci/revoked/${sha}`, sha);
+}
+
+describe("chant approve on the gate of a revoked release (#4033)", () => {
+  const cwd = process.cwd();
+  afterEach(() => {
+    process.chdir(cwd);
+    resetGateOrigin();
+    vi.restoreAllMocks();
+  });
+
+  test("revoke a commit, and its release's pending gate refuses approval with release-revoked and the fix line", async () => {
+    const errors: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((...m: unknown[]) => { errors.push(m.join(" ")); });
+    await withTestDir(async (dir) => {
+      const { sha } = await releaseWaitingAtGate(dir);
+      process.chdir(dir);
+      revoke(dir, sha);
+      const outcome = await recordGateApproval("release", "prod-release", { origin: "cli", actor: "alice", cwd: dir, environment: "prod" });
+      expect(outcome.ok).toBe(false);
+      const said = errors.join("\n");
+      expect(said).toContain(`release v1.0.0 was cut from commit ${sha.slice(0, 12)}, which ci/revoked/${sha} revokes (phase test failed in smoke (Op run r-12 in staging))`);
+      expect(said).toContain("[release-revoked]");
+      expect(said).toContain("chant approve release prod-release --expire");
+      expect((await readGateLedger("release", { cwd: dir })).resolutions).toEqual([]);
+
+      // Naming the plan outright doesn't get round it.
+      const named = await recordGateApproval("release", "prod-release", { origin: "cli", actor: "alice", cwd: dir, environment: "prod", plan: DOC });
+      expect(named.ok).toBe(false);
+      expect((await readGateLedger("release", { cwd: dir })).resolutions).toEqual([]);
+    });
+  });
+
+  test("before the commit is revoked, the same gate takes the approval", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    await withTestDir(async (dir) => {
+      const { release } = await releaseWaitingAtGate(dir);
+      process.chdir(dir);
+      const outcome = await recordGateApproval("release", "prod-release", { origin: "cli", actor: "alice", cwd: dir, environment: "prod" });
+      expect(outcome.ok).toBe(true);
+      expect((await readGateLedger("release", { cwd: dir })).resolutions).toEqual([expect.objectContaining({ releaseDigest: release.releaseDigest })]);
+    });
+  });
+
+  test("with ci.green.signedSince, a hand-pushed revoked tag is ignored and revokes nothing", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    await withTestDir(async (dir) => {
+      const { sha } = await releaseWaitingAtGate(dir);
+      // The release's own commit is the pivot, so a tag on it needs a statement; this one has none.
+      declaration(dir, { ...GREEN, signedSince: sha });
+      git(dir, "commit", "-q", "-am", "require signed ci tags");
+      revoke(dir, sha);
+      process.chdir(dir);
+      const outcome = await recordGateApproval("release", "prod-release", { origin: "cli", actor: "alice", cwd: dir, environment: "prod" });
+      expect(outcome.ok).toBe(true);
+    });
+  });
+
+  test("a gate whose release can't be read refuses, since whether it is revoked is unknown", async () => {
+    const errors: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((...m: unknown[]) => { errors.push(m.join(" ")); });
+    await withTestDir(async (dir) => {
+      await releaseWaitingAtGate(dir);
+      await appendPendingGate(
+        { op: "release", gate: "prod-release", timestamp: "2026-10-16T13:00:00.000Z", expiresAt: "2999-01-01T00:00:00.000Z", planDigest: DOC, environment: "prod", releaseDigest: `jcs1-sha256:${"e".repeat(64)}` },
+        { cwd: dir },
+      );
+      process.chdir(dir);
+      const outcome = await recordGateApproval("release", "prod-release", { origin: "cli", actor: "alice", cwd: dir, environment: "prod" });
+      expect(outcome.ok).toBe(false);
+      expect(errors.join("\n")).toContain("[release-unreadable]");
+    });
+  });
+});

package/src/cli/handlers/approve.ts

@@ -21,7 +21,7 @@ import {
   type GateApprover, type GatePolicyDecision, type GatePolicyEvaluator, type ResolvedGateApproval,
 } from "../../op/gate-approval";
 import { approverOf, humanQuorumSince, tallyGateApprovals } from "../../op/gate";
-import { FAN_OUT_GATE_OP, OVERRIDE_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name";
+import { FAN_OUT_GATE_OP, OVERRIDE_GATE_OP, RELEASE_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";
@@ -112,6 +112,8 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
       timestamp: now,
       expiresAt: now,
       ...(standing.description ? { description: standing.description } : {}),
+      ...(standing.runId ? { runId: standing.runId } : {}),
+      ...(standing.gitSha ? { gitSha: standing.gitSha } : {}),
     });
     const push = await reportedPush(
       `The expiry is recorded locally on ${LIFECYCLE_BRANCH}. Until it reaches the remote, ` +
@@ -127,6 +129,8 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
           ? `The next \`chant components pr-apply\` decides this gate from scratch and records a fresh pending fact.`
           : opName === WORKSPACE_UPGRADE_GATE_OP
           ? `The next \`chant workspace upgrade ${gate}\` decides this gate from scratch and records a fresh pending fact.`
+          : opName === RELEASE_GATE_OP
+          ? `The next \`chant components promote --release\` decides this gate from scratch and records a fresh pending fact.`
           : `The next \`chant run ${opName}\` decides this gate from scratch and records a fresh pending fact.`,
     ));
     return 0;
@@ -177,6 +181,8 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
           ? `The pull request's apply (\`chant components pr-apply\`) walks through gate "${gate}" when it plans this same digest.`
           : opName === WORKSPACE_UPGRADE_GATE_OP
           ? `Repeat \`chant workspace upgrade ${gate}\` with the same target, and it applies the patch this approval names.`
+          : opName === RELEASE_GATE_OP
+          ? `Repeat the same \`chant components promote --release\`, and it walks through gate "${gate}" when it plans this same change set for this release.`
           : `Run \`chant run ${opName}\` and it walks through gate "${gate}".`),
   ));
   return 0;
@@ -249,6 +255,46 @@ export type GateApprovalOutcome =
   | { ok: true; record: GateResolutionRecord; pushed: boolean }
   | { ok: false };
 
+/**
+ * Refuse the approval of a release gate whose release is revoked (#4033,
+ * ws-105): its commit carries a `ci/revoked/<sha>` tag that counts, read from
+ * local tags as `release cut` reads them. Prints the refusal and returns true
+ * when it refuses. A release file that can't be read, or tags that can't be
+ * judged, refuse too, since whether the release is revoked is then unknown.
+ */
+async function refuseRevokedRelease(opName: string, gate: string, releaseDigest: string, cwd: string): Promise<boolean> {
+  const { readRelease, readCuts, labelsByDigest } = await import("../../lifecycle/release-store");
+  const { readRevokedCommits, revocationOf, revokedRefusal } = await import("../../lifecycle/release-revocation");
+  const release = await readRelease(releaseDigest, { cwd }).catch(() => null);
+  if (!release) {
+    console.error(formatError({
+      message: `Gate "${gate}" on "${opName}" binds release ${releaseDigest}, which can't be read from ${LIFECYCLE_BRANCH}, so whether it is revoked is unknown [release-unreadable]`,
+      hint: `Fetch the ledger branch (git fetch origin ${LIFECYCLE_BRANCH}:${LIFECYCLE_BRANCH}) and approve again from the member's directory.`,
+    }));
+    return true;
+  }
+  let revoked: Awaited<ReturnType<typeof readRevokedCommits>>;
+  try {
+    revoked = await readRevokedCommits(cwd);
+  } catch (err) {
+    console.error(formatError({
+      message: `Gate "${gate}" on "${opName}" binds release ${releaseDigest}, and the ci tags can't be judged: ${err instanceof Error ? err.message : String(err)} [declaration-invalid]`,
+      hint: "Fix ci.green in chant.workspace.json at base; chant workspace check names the problem.",
+    }));
+    return true;
+  }
+  const r = revocationOf(release, revoked);
+  if (!r) return false;
+  const label = labelsByDigest((await readCuts({ cwd }).catch(() => ({ cuts: [] }))).cuts).get(releaseDigest) ?? null;
+  console.error(formatError(revokedRefusal(
+    { releaseDigest, label },
+    r,
+    `Clear the pending gate with \`chant approve ${opName} ${gate} --expire\`, then promote a release cut from a green commit: ` +
+      "`chant ci last-green` names the newest, and `chant release list` marks the revoked releases.",
+  )));
+  return true;
+}
+
 /**
  * The ledger write behind `chant approve` — extracted so `chant run approve`
  * (#2121) records the identical fact before waking the runtime that hosts the
@@ -283,7 +329,7 @@ export async function recordGateApproval(
   // so there is no `*.op.ts` to find and nothing is wrong when none is there.
   // #3949: a gate that lists this one as an alias, after an Op was restructured.
   const successor = aliasingGate([...ops.values()].map((o) => o.config), opName, gate);
-  if (!successor && !ops.has(opName) && opName !== FAN_OUT_GATE_OP && opName !== WORKSPACE_UPGRADE_GATE_OP && opName !== OVERRIDE_GATE_OP) {
+  if (!successor && !ops.has(opName) && opName !== FAN_OUT_GATE_OP && opName !== WORKSPACE_UPGRADE_GATE_OP && opName !== OVERRIDE_GATE_OP && opName !== RELEASE_GATE_OP) {
     console.error(formatWarning({
       message: `Op "${opName}" was not found among discovered *.op.ts declarations — recording the resolution anyway`,
     }));
@@ -389,6 +435,18 @@ export async function recordGateApproval(
     standing?.checkpointDigest !== undefined && samePlanDigest(planDigest, standing.planDigest)
       ? standing.checkpointDigest
       : undefined;
+  // #4045: a release gate's fact names the release its change set was
+  // planned for. An approval of that fact's plan is for that release too; an
+  // approval of another plan names none, and no release gate counts it.
+  const releaseDigest =
+    standing?.releaseDigest !== undefined && samePlanDigest(planDigest, standing.planDigest) ? standing.releaseDigest : undefined;
+  // #4033 (ws-105): a release gate whose release was cut from a revoked
+  // commit is superseded. Its promote refuses the release, so an approval of
+  // it would count for nothing; refuse it here, whatever plan is named.
+  if (standing?.releaseDigest !== undefined) {
+    const refused = await refuseRevokedRelease(opName, gate, standing.releaseDigest, opts.cwd ?? process.cwd());
+    if (refused) return { ok: false };
+  }
 
   // chant#2384 — the gate's whole value is that its two halves have different
   // authors. At a shell they do: a person runs, reads the plan, and approves.
@@ -587,6 +645,10 @@ export async function recordGateApproval(
     ...(planDigest !== undefined ? { planDigest } : {}),
     ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
     ...(environment !== undefined ? { environment } : {}),
+    ...(releaseDigest !== undefined ? { releaseDigest } : {}),
+    // #4020: the commit and run the gate waited on, off the fact this approves.
+    ...(standing?.gitSha ? { gitSha: standing.gitSha } : {}),
+    ...(standing?.runId ? { runId: standing.runId } : {}),
     origin,
     ...(refusal && opts.allowSameOrigin ? { sameOriginOverride: true } : {}),
   });
@@ -607,6 +669,7 @@ export async function recordGateApproval(
     console.error(formatInfo(
       `This approves the plan ${record.planDigest}` +
         (record.environment !== undefined ? ` in environment "${record.environment}"` : "") +
+        (record.releaseDigest !== undefined ? ` for release ${record.releaseDigest}` : "") +
         ", and only that plan. A run whose fresh plan differs refuses rather than applying it.",
     ));
   }

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

@@ -70,6 +70,37 @@ describe("runBuild --components --generate (chant #1108 build-time parameters)",
     vi.restoreAllMocks();
   });
 
+  test("--promote-to that skips a step of the declared promotion order is refused, and generates nothing (#4030)", async () => {
+    loadChantConfigUpwardMock.mockResolvedValue({ config: { environments: ["dev", "staging", "prod"] } });
+    const stderr = makeStderrSpy();
+    const exit = await runBuild({ args: makeArgs({ env: "dev", promoteTo: "prod" }), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    expect(generateComponentsPipelineMock).not.toHaveBeenCalled();
+    const out = stderr.join("\n");
+    expect(out).toMatch(/\[promote-skips-environment\]/);
+    expect(out).toMatch(/--allow-skip/);
+  });
+
+  test("--promote-to the next step of the order generates as before (#4030)", async () => {
+    loadChantConfigUpwardMock.mockResolvedValue({ config: { environments: ["dev", "staging", "prod"] } });
+    generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "x", stages: [], jobs: [] });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    const exit = await runBuild({ args: makeArgs({ env: "staging", promoteTo: "prod" }), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    expect(generateComponentsPipelineMock.mock.calls[0][2]).toEqual({ env: "staging", promoteTo: "prod" });
+  });
+
+  test("--allow-skip lets the skip through and the promote job passes it on (#4030)", async () => {
+    loadChantConfigUpwardMock.mockResolvedValue({ config: { environments: ["dev", "staging", "prod"] } });
+    generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "x", stages: [], jobs: [] });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    const exit = await runBuild({ args: makeArgs({ env: "dev", promoteTo: "prod", allowSkip: true }), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    expect(generateComponentsPipelineMock.mock.calls[0][2]).toMatchObject({
+      promoteCommand: ["chant", "components", "promote", "--from", "dev", "--to", "prod", "--allow-skip"],
+    });
+  });
+
   test("--promote-to is forwarded to the generator as promoteTo (#2575)", async () => {
     generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "stages: []", stages: [], jobs: [] });
     vi.spyOn(console, "log").mockImplementation(() => {});
@@ -81,6 +112,42 @@ describe("runBuild --components --generate (chant #1108 build-time parameters)",
     vi.restoreAllMocks();
   });
 
+  test("--image and each --before-script are forwarded to the generator, in order (#4002)", async () => {
+    generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "stages: []", stages: [], jobs: [] });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const exit = await runBuild({
+      args: makeArgs({ generate: "forgejo", prLoop: true, image: "node:22-bookworm", beforeScript: ["npm ci", "npm run setup"] }),
+      plugins: [],
+      serializers: [],
+    });
+
+    expect(exit).toBe(0);
+    expect(generateComponentsPipelineMock).toHaveBeenCalledWith(
+      ".",
+      "forgejo",
+      { env: undefined, prLoop: {}, image: "node:22-bookworm", beforeScript: ["npm ci", "npm run setup"] },
+      undefined,
+      [],
+    );
+    vi.restoreAllMocks();
+  });
+
+  test("--pr-loop with --events-json and --report-url asks the generated jobs for both (#4007)", async () => {
+    generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "stages: []", stages: [], jobs: [] });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const exit = await runBuild({
+      args: makeArgs({ generate: "github", prLoop: true, eventsJson: true, reportUrl: "s3://reports/acme" }),
+      plugins: [],
+      serializers: [],
+    });
+
+    expect(exit).toBe(0);
+    expect(generateComponentsPipelineMock).toHaveBeenCalledWith(".", "github", { env: undefined, prLoop: { events: true, reportUrl: "s3://reports/acme" } }, undefined, []);
+    vi.restoreAllMocks();
+  });
+
   test("chant.config.ts's declared buildParams resolve, log, and are forwarded to generateComponentsPipeline", async () => {
     loadChantConfigUpwardMock.mockResolvedValue({
       config: { buildParams: { tier: { type: "string", default: "light" } } },