@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/lexicon-symbols.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Symbol resolvers from a member's lexicon (#3313): `graph --intent
+ * path#symbol` on a file in a member whose lexicon exports a resolver.
+ *
+ * The workspace has a chant member `db` whose chant.config.json declares a
+ * lexicon by module path, `lexicon/plugin.mjs`, which resolves `create table`
+ * and `create function` statements in `.sql` files. A loader stands in for
+ * the plugin in the unit cases; one case loads the module path the way any
+ * command does.
+ */
+
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, git, repo } from "./__fixtures__/contract-repo";
+import { intentGraph, type IntentDocument, type RegionNode } from "./intent";
+import intentSchema from "./intent.schema.json";
+import { memberSymbolResolvers, type SymbolPluginLoader } from "./lexicon-symbols";
+import { resolveSymbol, type SymbolDeclaration, type SymbolResolver } from "./symbols";
+
+afterAll(cleanScratch);
+
+const intent = contract(intentSchema);
+
+/** A tiny SQL resolver: each `create table|function <name>` up to the line ending in `;`. */
+const SQL_RESOLVER_SOURCE = `
+export const sqlResolver = {
+  language: "SQL",
+  extensions: [".sql"],
+  declarations(path, text) {
+    const lines = text.split("\\n");
+    const out = [];
+    lines.forEach((line, i) => {
+      const m = /^create\\s+(table|function)\\s+([a-z_.]+)/i.exec(line);
+      if (!m) return;
+      let end = i;
+      while (end < lines.length - 1 && !lines[end].trimEnd().endsWith(";")) end++;
+      out.push({ qualified: m[2], kind: m[1].toLowerCase(), lines: { start: i + 1, end: end + 1 } });
+    });
+    return out;
+  },
+};
+`;
+
+const PLUGIN = `${SQL_RESOLVER_SOURCE}
+export const plugin = {
+  name: "sqlish",
+  serializer: { name: "sqlish", rulePrefix: "SQI", serialize: () => "" },
+  async generate() {},
+  async validate() {},
+  async coverage() {},
+  async package() {},
+  symbolResolvers: () => [sqlResolver],
+};
+`;
+
+const SCHEMA = ["-- the app's schema", "create table app.users (", "  id int primary key", ");", "", "create function app.touch()", "  returns void as $$ select 1 $$ language sql;", ""].join("\n");
+
+async function sqlResolver(): Promise<SymbolResolver> {
+  const mod = (await import(`data:text/javascript,${encodeURIComponent(SQL_RESOLVER_SOURCE)}`)) as { sqlResolver: SymbolResolver };
+  return mod.sqlResolver;
+}
+
+function workspace(): string {
+  const root = repo(
+    {
+      "chant.workspace.json": `${JSON.stringify({
+        name: "demo",
+        schema: 1,
+        members: [
+          { name: "db", dir: "db", kind: "chant" },
+          { name: "notes", dir: "notes", kind: "other", because: "prose" },
+        ],
+      })}\n`,
+      "db/chant.config.json": `${JSON.stringify({ lexicons: [{ name: "sqlish", module: "../lexicon/plugin.mjs" }] })}\n`,
+      "db/schema.sql": SCHEMA,
+      "db/main.ts": "export const x = 1;\n",
+      "lexicon/plugin.mjs": PLUGIN,
+      "notes/schema.sql": SCHEMA,
+    },
+    true,
+  );
+  git(root, "branch", "-M", "main");
+  return root;
+}
+
+const region = (doc: IntentDocument) => {
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc.nodes.find((n) => n.kind === "region") as RegionNode;
+};
+
+describe("a lexicon's symbol resolvers (#3313)", () => {
+  test("resolveSymbol uses an extra resolver for its extensions, and core's for .ts", async () => {
+    const sql = await sqlResolver();
+    expect(resolveSymbol("db/schema.sql", SCHEMA, "app.users", [sql])).toEqual({ ok: true, declaration: { qualified: "app.users", kind: "table", lines: { start: 2, end: 4 } } });
+    expect(resolveSymbol("db/schema.sql", SCHEMA, "users", [sql])).toMatchObject({ ok: true, declaration: { qualified: "app.users" } });
+    expect(resolveSymbol("db/schema.sql", SCHEMA, "app.users")).toMatchObject({ ok: false, reason: "unsupported" });
+    // A lexicon's resolver never takes .ts from core's.
+    const greedy: SymbolResolver = { language: "greedy", extensions: [".ts"], declarations: (): SymbolDeclaration[] => [{ qualified: "x", kind: "lie", lines: { start: 9, end: 9 } }] };
+    expect(resolveSymbol("a.ts", "export const x = 1;\n", "x", [greedy])).toMatchObject({ ok: true, declaration: { kind: "variable", lines: { start: 1, end: 1 } } });
+  });
+
+  test("graph --intent path#symbol resolves through the member's lexicon", async () => {
+    const root = workspace();
+    const sql = await sqlResolver();
+    const load: SymbolPluginLoader = async (name) => {
+      expect(name).toBe("sqlish");
+      return { name, symbolResolvers: () => [sql] };
+    };
+    const { doc } = await intentGraph({ cwd: root, region: "db/schema.sql#app.touch", loadLexicon: load });
+    intent.expectValid(doc);
+    expect(region(doc)).toMatchObject({ path: "db/schema.sql", lines: { start: 6, end: 7 }, member: "db", symbol: { name: "app.touch", qualified: "app.touch", kind: "function" } });
+  });
+
+  test("loads the lexicon the member's config declares, by module path, as any command does", async () => {
+    const root = workspace();
+    const { doc } = await intentGraph({ cwd: root, region: "db/schema.sql#app.users" });
+    intent.expectValid(doc);
+    expect(region(doc)).toMatchObject({ lines: { start: 2, end: 4 }, symbol: { qualified: "app.users", kind: "table" } });
+  });
+
+  test("a file in a member with no such lexicon, or whose lexicon fails, stays intent-symbol-unsupported and says why", async () => {
+    const root = workspace();
+    const other = await intentGraph({ cwd: root, region: "notes/schema.sql#app.users" });
+    intent.expectValid(other.doc);
+    expect("error" in other.doc && other.doc.error.code).toBe("intent-symbol-unsupported");
+    const broken = await intentGraph({
+      cwd: root,
+      region: "db/schema.sql#app.users",
+      loadLexicon: async () => {
+        throw new Error("Cannot find package");
+      },
+    });
+    expect("error" in broken.doc && broken.doc.error).toMatchObject({ code: "intent-symbol-unsupported", message: expect.stringContaining('lexicon "sqlish" could not be loaded: Cannot find package') });
+  });
+
+  test("a malformed resolver or bad declarations are dropped, not read as lines", async () => {
+    const root = workspace();
+    const got = await memberSymbolResolvers(join(root, "db"), async () => ({
+      symbolResolvers: () => [
+        { language: "bad", extensions: ["sql"], declarations: () => [] },
+        { language: "ok", extensions: [".sql"], declarations: () => [{ qualified: "t", kind: "table", lines: { start: 3, end: 1 } }, { qualified: "u", kind: "table", lines: { start: 1, end: 2 } }] },
+      ],
+    }));
+    expect(got.problems).toEqual([expect.stringContaining("not { language, extensions")]);
+    expect(got.resolvers).toHaveLength(1);
+    expect(got.resolvers[0].declarations("x.sql", "")).toEqual([{ qualified: "u", kind: "table", lines: { start: 1, end: 2 } }]);
+  });
+});

package/src/workspace/lexicon-symbols.ts

@@ -0,0 +1,125 @@
+/**
+ * Symbol resolvers a member's lexicons contribute (#3313), for
+ * `chant workspace graph --intent <path>#<symbol>` on a file core's own
+ * resolver does not read (`symbols.ts`).
+ *
+ * The lexicons are the ones the member's `chant.config.ts` (or `.json`)
+ * names, read without running the config when it can be read statically
+ * (`../config-static.ts`), and by loading it as `chant run` does otherwise.
+ * Each is loaded as any command loads it (`loadPlugin`), and its plugin's
+ * `symbolResolvers()` answers. A lexicon that can't be loaded, or whose
+ * resolvers are malformed, contributes nothing, and the reason is kept so a
+ * refusal can say why the file has no resolver.
+ */
+
+import { join } from "node:path";
+import { lexiconNames } from "../lexicon-module";
+import type { SymbolDeclaration, SymbolResolver } from "./symbols";
+
+/** Loads a lexicon plugin by name; `loadPlugin` from the CLI unless a test swaps it. */
+export type SymbolPluginLoader = (name: string) => Promise<{ name?: string; symbolResolvers?: () => unknown }>;
+
+export interface MemberSymbolResolvers {
+  resolvers: SymbolResolver[];
+  /** Why a lexicon contributed nothing it may have meant to: its config or plugin couldn't be read, or a resolver was malformed. */
+  problems: string[];
+}
+
+const firstLine = (err: unknown): string => (err instanceof Error ? err.message : String(err)).split("\n")[0];
+
+/** A resolver a plugin returned, checked: a language, extensions starting with a dot, and a declarations function. */
+function checked(lexicon: string, value: unknown, problems: string[]): SymbolResolver | undefined {
+  const r = value as Partial<SymbolResolver> | null;
+  const ok =
+    r !== null &&
+    typeof r === "object" &&
+    typeof r.language === "string" &&
+    Array.isArray(r.extensions) &&
+    r.extensions.length > 0 &&
+    r.extensions.every((e) => typeof e === "string" && /^\.[^./\\]+$/.test(e)) &&
+    typeof r.declarations === "function";
+  if (!ok) {
+    problems.push(`lexicon "${lexicon}" returned a symbol resolver that is not { language, extensions: [".ext", ...], declarations(path, text) }`);
+    return undefined;
+  }
+  const declarations = r.declarations!.bind(r);
+  return {
+    language: `${r.language} (lexicon ${lexicon})`,
+    extensions: [...r.extensions!],
+    // A resolver's output is checked where it is used, so a bad entry is dropped rather than read as lines.
+    declarations(path: string, text: string): SymbolDeclaration[] {
+      const out = declarations(path, text);
+      if (!Array.isArray(out)) return [];
+      return out.filter(
+        (d) =>
+          d !== null &&
+          typeof d === "object" &&
+          typeof d.qualified === "string" &&
+          d.qualified !== "" &&
+          typeof d.kind === "string" &&
+          Number.isInteger(d.lines?.start) &&
+          Number.isInteger(d.lines?.end) &&
+          d.lines.start >= 1 &&
+          d.lines.end >= d.lines.start,
+      );
+    },
+  };
+}
+
+/** The lexicon names a member's config declares: read statically when it can be, else by loading the config. */
+async function memberLexicons(dir: string): Promise<string[]> {
+  const { readLexiconDeclarationsStatically } = await import("../config-static");
+  const read = readLexiconDeclarationsStatically(dir);
+  if (read.status === "no-config") return [];
+  if (read.status === "read") {
+    const { registerLexiconDeclarations } = await import("../lexicon-module");
+    const { dirname } = await import("node:path");
+    registerLexiconDeclarations(read.entries, dirname(read.configPath));
+    return lexiconNames(read.entries);
+  }
+  const { loadChantConfig } = await import("../config");
+  const { config } = await loadChantConfig(dir);
+  return lexiconNames(config.lexicons ?? []);
+}
+
+/** The symbol resolvers the lexicons of the member at `dir` (on disk) contribute, in config order. */
+export async function memberSymbolResolvers(dir: string, load?: SymbolPluginLoader): Promise<MemberSymbolResolvers> {
+  const problems: string[] = [];
+  let names: string[];
+  try {
+    names = await memberLexicons(dir);
+  } catch (err) {
+    return { resolvers: [], problems: [`its chant.config could not be read: ${firstLine(err)}`] };
+  }
+  const loader = load ?? ((await import("../cli/plugins")).loadPlugin as SymbolPluginLoader);
+  const resolvers: SymbolResolver[] = [];
+  for (const name of names) {
+    let plugin: Awaited<ReturnType<SymbolPluginLoader>>;
+    try {
+      plugin = await loader(name);
+    } catch (err) {
+      problems.push(`lexicon "${name}" could not be loaded: ${firstLine(err)}`);
+      continue;
+    }
+    if (typeof plugin.symbolResolvers !== "function") continue;
+    let listed: unknown;
+    try {
+      listed = plugin.symbolResolvers();
+    } catch (err) {
+      problems.push(`lexicon "${name}" symbolResolvers() threw: ${firstLine(err)}`);
+      continue;
+    }
+    if (!Array.isArray(listed)) {
+      problems.push(`lexicon "${name}" symbolResolvers() did not return a list`);
+      continue;
+    }
+    for (const r of listed) {
+      const ok = checked(name, r, problems);
+      if (ok) resolvers.push(ok);
+    }
+  }
+  return { resolvers, problems };
+}
+
+/** The member directory on disk for a member's `dir` under the workspace root. */
+export const memberDirOnDisk = (root: string, dir: string): string => (dir === "." ? root : join(root, ...dir.split("/")));

package/src/workspace/lineage-upgrade.test.ts

@@ -194,6 +194,69 @@ describe("chant workspace upgrade", () => {
     expect(git(proj, ["status", "--porcelain"])).toBe("");
   });
 
+  describe("a CI workflow a chant member builds is rebuilt with this chant (#3244)", () => {
+    const WS = JSON.stringify({ name: "proj", schema: 1, members: [{ name: "delivery", dir: "delivery", kind: "chant" }] }, null, 2) + "\n";
+    const PKG = JSON.stringify({ name: "delivery", scripts: { "ci:build": "chant build ci --lexicon github -o ../.github/workflows/ci.yml", "ci:check": "npm run ci:build && git diff --exit-code ../.github/workflows/ci.yml", "agents": "chant build agents --lexicon fountain -o ../.studio/agents.yaml" } }, null, 2) + "\n";
+    const OLD = "steps:\n  - uses: actions/checkout@v4\n";
+    const NEW = "steps:\n  - uses: actions/checkout@v7\n";
+    /** A chant whose github lexicon now emits @v7: `build` writes NEW where -o points. */
+    const builds = (calls: Array<{ command: string; cwd: string; args?: readonly string[] }>, output = NEW): ChantRunner => async (command, cwd, args) => {
+      calls.push({ command, cwd, args });
+      const o = args?.indexOf("-o") ?? -1;
+      if (o >= 0) put(cwd, args![o + 1], output);
+      return { exitCode: 0, output: "" };
+    };
+
+    beforeEach(() => {
+      release("v2.0.0", { "chant.workspace.json": WS, "delivery/chant.config.ts": "export default {};\n", "delivery/package.json": PKG, ".github/workflows/ci.yml": OLD });
+    });
+
+    test("an upgrade to the same version puts the rebuilt workflow in the patch, and only the CI workflow", async () => {
+      // A box planted at v2.0.0 with the chant of then.
+      const port = ledger();
+      const staged0 = await upgradeCommand({ root: proj, to: "v2.0.0", runChant: passing, ledger: port, now: "2026-10-03T00:00:00.000Z" });
+      port.approve(staged0.staged!.digest, "2026-10-03T00:01:00.000Z");
+      expect((await upgradeCommand({ root: proj, to: "v2.0.0", runChant: passing, ledger: port, now: "2026-10-03T00:02:00.000Z" })).outcome).toBe("applied");
+      commitProject("at v2");
+      expect(read(proj, ".github/workflows/ci.yml")).toBe(OLD);
+
+      // chant is upgraded; the template is not. The workflow ci.ts builds now differs.
+      const calls: Array<{ command: string; cwd: string; args?: readonly string[] }> = [];
+      const staged = await stageUpgrade({ root: proj, to: "v2.0.0", runChant: builds(calls) });
+      try {
+        expect(staged.workflows).toEqual([{ member: "delivery", script: "ci:build", path: ".github/workflows/ci.yml", command: "chant build ci --lexicon github -o ../.github/workflows/ci.yml", status: "rebuilt" }]);
+        expect(calls[0]).toEqual({ command: "build", cwd: join(staged.worktreeProject, "delivery"), args: ["ci", "--lexicon", "github", "-o", "../.github/workflows/ci.yml"] });
+        // The agents script writes no CI workflow, so it is not run.
+        expect(calls.some((c) => c.args?.includes("agents"))).toBe(false);
+        expect(staged.changed).toBe(true);
+        expect(staged.changedPaths).toEqual([".github/workflows/ci.yml"]);
+        expect(staged.governance?.paths).toEqual([".github/workflows/ci.yml"]);
+        expect(read(proj, ".github/workflows/ci.yml")).toBe(OLD);
+      } finally {
+        staged.dispose();
+      }
+
+      // Once it is committed as built, the next upgrade finds nothing to do.
+      put(proj, ".github/workflows/ci.yml", NEW);
+      commitProject("ci:build");
+      const again = await stageUpgrade({ root: proj, to: "v2.0.0", runChant: builds([]) });
+      try {
+        expect(again.workflows.map((w) => w.status)).toEqual(["unchanged"]);
+        expect(again.changed).toBe(false);
+      } finally {
+        again.dispose();
+      }
+    });
+
+    test("a workflow that does not build fails the build check and stays as it was", async () => {
+      const failing: ChantRunner = async (_command, _cwd, args) => (args?.length ? { exitCode: 1, output: "cannot find @intentius/chant-lexicon-github\n" } : { exitCode: 0, output: "" });
+      const result = await upgradeCommand({ root: proj, to: "v2.0.0", runChant: failing });
+      expect(result.outcome).toBe("checks-failed");
+      expect(result.staged!.workflows.map((w) => w.status)).toEqual(["failed"]);
+      expect(result.staged!.checks).toEqual(expect.arrayContaining([expect.objectContaining({ name: "build", status: "failed", member: "delivery", detail: expect.stringMatching(/\.github\/workflows\/ci\.yml could not be rebuilt[\s\S]*cannot find/) })]));
+    });
+  });
+
   test("gates on the patch digest, then applies exactly the approved patch", async () => {
     release("v2.0.0", { "README.md": "starter v2\n" });
     const port = ledger();

package/src/workspace/lineage-upgrade.ts

@@ -21,6 +21,9 @@
  * 4. Merge per file (ws-005): an edited file takes the new version only when
  *    every hunk merges cleanly. Otherwise it stays as it was, with one manual
  *    step. The worktree never holds conflict markers.
+ *    Then rebuild each CI workflow a chant member's package.json builds with
+ *    `chant build ... -o <workflow>` (#3244), with the chant doing the
+ *    upgrade, so the committed workflow follows that chant's composites.
  * 5. Check the worktree: `chant build` and `chant lint` when the project is a
  *    chant project, and the lineage checks of `chant workspace check`.
  * 6. Bind the gate to the digest of the resulting patch: the pending fact and
@@ -34,7 +37,7 @@
  */
 
 import { execFileSync, spawn } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { computePlanDigest } from "../lifecycle/plan-digest";
@@ -64,6 +67,7 @@ import { pathsInsideNested } from "./nesting";
 import { carryParameters, readManifest, substituteParameters } from "./template-manifest";
 import { repinSubstituted, type RepinnedRecord } from "./template-pins";
 import { workingTree } from "./tree";
+import { splitCommandLine } from "./checks/generated";
 
 /** The kind the patch digest is taken under, so it never collides with another kind of plan. */
 export const UPGRADE_PLAN_KIND = "workspace-upgrade";
@@ -86,22 +90,26 @@ export interface UpgradeCheck {
   member?: string;
 }
 
-/** Runs `chant build` or `chant lint` in a directory. */
-export type ChantRunner = (command: "build" | "lint", cwd: string) => Promise<{ exitCode: number; output: string }>;
+/**
+ * Runs `chant build` or `chant lint` in a directory, with `args` after the
+ * command when given (a workflow rebuild's `ci --lexicon github -o <file>`,
+ * #3244).
+ */
+export type ChantRunner = (command: "build" | "lint", cwd: string, args?: readonly string[]) => Promise<{ exitCode: number; output: string }>;
 
 /**
  * The default runner: this same chant, in a child process. The child sees the
  * worktree's sources and resolves packages the way the project does, since the
  * worktree sits inside the project.
  */
-export const spawnChant: ChantRunner = (command, cwd) =>
+export const spawnChant: ChantRunner = (command, cwd, args = []) =>
   new Promise((resolvePromise, reject) => {
     const entry = process.argv[1];
     if (!entry) {
       reject(new UpgradeError("cannot find the chant entry point to run build and lint in the worktree"));
       return;
     }
-    const child = spawn(process.execPath, [...process.execArgv, entry, command], { cwd, stdio: ["ignore", "pipe", "pipe"], env: process.env });
+    const child = spawn(process.execPath, [...process.execArgv, entry, command, ...args], { cwd, stdio: ["ignore", "pipe", "pipe"], env: process.env });
     const out: Buffer[] = [];
     child.stdout.on("data", (c: Buffer) => out.push(c));
     child.stderr.on("data", (c: Buffer) => out.push(c));
@@ -139,6 +147,121 @@ export interface UpgradeOptions {
   runChant?: ChantRunner;
 }
 
+/**
+ * A CI workflow a chant member's package.json builds, and what rebuilding it
+ * did (#3244). `rebuilt`: the workflow chant builds now differs from the one
+ * committed, and the patch carries the new one. `unchanged`: it is the same.
+ * `failed`: the build failed, the file is left as the merge left it, and the
+ * upgrade's `build` check fails with the output.
+ */
+export interface RebuiltWorkflow {
+  /** The chant member whose package.json script builds it. */
+  member: string;
+  /** The script's name, such as `ci:build`. */
+  script: string;
+  /** The workflow, relative to the repository root. */
+  path: string;
+  /** The command line, as the script has it. */
+  command: string;
+  status: "rebuilt" | "unchanged" | "failed";
+  /** The tail of the build's output, when it failed. */
+  detail?: string;
+}
+
+/** A CI workflow path a forge reads, relative to the repository root. The governance list's pipeline entries. */
+const CI_WORKFLOW = [/(^|\/)\.github\/workflows\/[^/]+\.ya?ml$/, /(^|\/)\.forgejo\/workflows\/[^/]+\.ya?ml$/, /(^|\/)\.gitea\/workflows\/[^/]+\.ya?ml$/, /(^|\/)\.gitlab-ci\.ya?ml$/];
+
+/**
+ * The CI workflows the chant members under `worktreeProject` build: each
+ * package.json script that is one `chant build ... -o <file>` command (no
+ * shell, no `&&`), whose output is a committed CI workflow inside the scope.
+ * The studio kit's template has `"ci:build": "chant build ci --lexicon github
+ * -o ../.github/workflows/ci.yml"` in delivery/, and its CI fails when the
+ * committed workflow differs from what ci/ci.ts builds.
+ */
+function workflowBuilds(worktree: string, worktreeProject: string, scopeRepoPath: string): Array<{ member: string; script: string; command: string; args: string[]; abs: string; path: string }> {
+  const out: Array<{ member: string; script: string; command: string; args: string[]; abs: string; path: string }> = [];
+  for (const member of chantMemberDirs(worktreeProject)) {
+    const dir = member === "." ? worktreeProject : join(worktreeProject, member);
+    let scripts: Record<string, unknown>;
+    try {
+      scripts = (JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as { scripts?: Record<string, unknown> }).scripts ?? {};
+    } catch {
+      continue;
+    }
+    for (const [script, line] of Object.entries(scripts)) {
+      if (typeof line !== "string") continue;
+      const words = splitCommandLine(line);
+      if (!words || words[0] !== "chant" || words[1] !== "build") continue;
+      const flag = words.findIndex((w) => w === "-o" || w === "--output");
+      const target = flag >= 0 ? words[flag + 1] : words.find((w) => w.startsWith("--output="))?.slice("--output=".length);
+      if (!target) continue;
+      const abs = resolve(dir, target);
+      const path = relative(worktree, abs).split(sep).join("/");
+      if (path.startsWith("../") || !CI_WORKFLOW.some((re) => re.test(path))) continue;
+      if (scopeRepoPath !== "." && !path.startsWith(`${scopeRepoPath}/`)) continue;
+      if (!existsSync(abs)) continue;
+      out.push({ member, script, command: line, args: words.slice(2), abs, path });
+    }
+  }
+  return out;
+}
+
+/**
+ * Rebuild the CI workflows {@link workflowBuilds} finds (#3244), each in its
+ * member's directory of the staging worktree with that member's node_modules
+ * linked in from the project. A workflow is built from the member's sources
+ * through the lexicon's composites, so upgrading chant can change it with no
+ * change to the sources (#2621 moved Checkout and SetupNode from v4 to v7),
+ * and a committed copy then fails the project's own ci:check. Rebuilding it
+ * here puts the new workflow in the patch the gate approves. The links are
+ * removed before the patch is taken. A build that fails leaves the file as
+ * the merge left it.
+ */
+async function rebuildWorkflows(root: string, worktree: string, worktreeProject: string, scopeRepoPath: string, run: ChantRunner): Promise<RebuiltWorkflow[]> {
+  const builds = workflowBuilds(worktree, worktreeProject, scopeRepoPath);
+  if (builds.length === 0) return [];
+  const linked: string[] = [];
+  const results: RebuiltWorkflow[] = [];
+  try {
+    for (const member of new Set(builds.map((b) => b.member))) {
+      if (member === ".") continue;
+      const from = join(root, member, "node_modules");
+      const to = join(worktreeProject, member, "node_modules");
+      if (existsSync(from) && !existsSync(to) && existsSync(dirname(to))) {
+        symlinkSync(from, to, "dir");
+        linked.push(to);
+      }
+    }
+    for (const b of builds) {
+      const before = readFileSync(b.abs);
+      const r = await run("build", b.member === "." ? worktreeProject : join(worktreeProject, b.member), b.args);
+      const base = { member: b.member, script: b.script, path: b.path, command: b.command };
+      if (r.exitCode !== 0) {
+        writeFileSync(b.abs, before);
+        results.push({ ...base, status: "failed", detail: tail(r.output) });
+        continue;
+      }
+      const after = existsSync(b.abs) ? readFileSync(b.abs) : null;
+      if (after === null) {
+        writeFileSync(b.abs, before);
+        results.push({ ...base, status: "failed", detail: `\`${b.command}\` exited 0 and wrote no ${b.path}` });
+        continue;
+      }
+      results.push({ ...base, status: after.equals(before) ? "unchanged" : "rebuilt" });
+    }
+  } finally {
+    for (const l of linked) {
+      try {
+        if (lstatSync(l).isSymbolicLink()) unlinkSync(l);
+      } catch {
+        // Already gone.
+      }
+    }
+  }
+  return results;
+}
+
 export interface GovernanceChange {
   /** Changed governance paths, relative to the repository root. */
   paths: string[];
@@ -166,6 +289,8 @@ export interface StagedUpgrade {
   migrations: string[];
   /** The migrations chant ships (./chant-migrations.ts) that found something to move, applied or not. */
   chantMigrations: ChantMigrationReport[];
+  /** The CI workflows a chant member builds, rebuilt with this chant before the patch was taken (#3244). */
+  workflows: RebuiltWorkflow[];
   written: string[];
   merged: string[];
   removed: string[];
@@ -694,6 +819,10 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
     writeLock(worktreeProject, next);
     const lockText = renderLock(next);
 
+    // The CI workflows a chant member builds, rebuilt with this chant (#3244),
+    // before the patch is taken so the gate approves them with the rest.
+    const workflows = lineage.kind === "template" ? await rebuildWorkflows(root, worktree, worktreeProject, scopeRepoPath, options.runChant ?? spawnChant) : [];
+
     // The patch, taken before anything else runs in the worktree.
     gitOut(worktree, ["add", "-A"]);
     if (!lockTracked) gitOut(worktree, ["rm", "--cached", "-q", "--ignore-unmatch", "--", lockRepoPath]);
@@ -730,6 +859,14 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
 
     // 5. Checks.
     const checks: UpgradeCheck[] = [];
+    for (const w of workflows.filter((w) => w.status === "failed")) {
+      checks.push({
+        name: "build",
+        status: "failed",
+        member: w.member,
+        detail: `${w.path} could not be rebuilt with \`${w.command}\` (the ${w.script} script), so it may differ from what this chant builds:\n${w.detail ?? ""}`,
+      });
+    }
     for (const m of chantMigrations.filter((m) => !m.applied)) {
       checks.push({
         name: "migration",
@@ -783,6 +920,7 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
       ...(upstream.commit ? { commit: { ...(lineage.address?.commit ? { from: lineage.address.commit } : {}), to: upstream.commit } } : {}),
       migrations: [...plan.chain.map((m) => m.migration.id), ...chantMigrations.filter((m) => m.applied).map((m) => m.id)],
       chantMigrations,
+      workflows,
       written: result.written,
       merged: result.merged,
       removed: result.removed,
@@ -885,6 +1023,9 @@ export function describeStaged(staged: StagedUpgrade): string[] {
     for (const n of m.notMoved) lines.push(`    not moved: ${n.what} -> ${n.where}`);
     for (const c of m.conflicts) lines.push(`    conflict: ${at(c.path)}: ${c.reason}`);
   }
+  for (const w of staged.workflows) {
+    if (w.status !== "unchanged") lines.push(`  workflow ${w.status === "rebuilt" ? "rebuilt" : "not rebuilt"}: ${w.path} (${w.script}: ${w.command})`);
+  }
   for (const p of staged.written) lines.push(`  updated: ${at(p)}`);
   for (const p of staged.merged) lines.push(`  merged: ${at(p)}`);
   for (const p of staged.removed) lines.push(`  removed: ${at(p)}`);