@intentius/chant 0.124.27 → 0.124.28

package/src/workspace/commit-links.test.ts

@@ -0,0 +1,279 @@
+/**
+ * Which work item a commit belongs to (#4029): the one judgement, and where
+ * `workspace check --changes`, `ci list` and `ci tick` report it.
+ *
+ * - c0 declares the workspace, the decision s-001 and the work items W-001
+ *   and W-002, and a ci.green block.
+ * - c1 carries Chant-Record: work:W-001.
+ * - c2 carries only a Chant-Lease, whose token the lease history of W-002
+ *   on chant/lifecycle names.
+ * - c3 carries nothing.
+ * - c4 names work:W-999, which no record has.
+ * - c5 names decision:s-001, a record of a kind that is not the work kind.
+ * - c6 carries a Chant-Lease no lease history names.
+ * - c7 carries a Chant-Record that is not <kind>:<id>.
+ * - c8 names decision:s-001 and work:W-002, so the decision beside the work
+ *   item changes nothing.
+ * - m is a merge of a branch whose commit is not on the first-parent line.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { writeBlobToPath } from "../lifecycle/git";
+import { cleanScratch, contract, git, REPO, repo, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { checkChanges, type ChangesDocument } from "./changes";
+import { formatChanges } from "./changes-cli";
+import changesSchema from "./changes.schema.json";
+import { judgeCommitLink, type WorkIndex } from "./commit-links";
+import { ciList, ciTick, formatList, formatTick, whyWorkUnknown, type CiListDocument } from "./ci-green";
+import type { CiForge } from "./ci-green-forge";
+import ciListSchema from "./ci-list.schema.json";
+import { parseFrontMatter } from "./records";
+
+const REF = join(REPO, "reference-workspace");
+const DECISION = (() => {
+  const fm = parseFrontMatter(readFileSync(join(REF, "decisions", "ref-001-how-the-app-is-deployed.md"), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+})();
+
+const decision = (id: string) => `---\n${JSON.stringify({ ...DECISION, id, title: `Decision ${id}`, state: "decided", supersedes: [], evidence: [], constrains: ["path:app"] }, null, 2)}\n---\n\n# ${id}\n`;
+const work = (id: string) => `---\n${JSON.stringify({ schema: 1, id, title: `Work ${id}`, state: "open", implements: [], needs: [], constrains: ["path:app"], evidence: [], opened_on: "2026-10-01", source: { kind: "workspace", member: "app" }, supersedes: [] }, null, 2)}\n---\n\n# ${id}\n`;
+
+const TOKEN = "7a1e5c90-lease-token";
+const NOW = new Date("2026-10-01T13:00:00Z");
+const changes = contract(changesSchema);
+const list = contract(ciListSchema);
+type Result = Exclude<ChangesDocument, { error: unknown }>;
+type Listed = Extract<CiListDocument, { branch: string }>;
+
+let root: string;
+let origin: string;
+const sha: Record<string, string> = {};
+let tick = 0;
+
+function commit(message: string[]): string {
+  const date = `2026-10-01T12:00:${String(tick++).padStart(2, "0")}Z`;
+  process.env.GIT_AUTHOR_DATE = date;
+  process.env.GIT_COMMITTER_DATE = date;
+  try {
+    git(root, "add", "-A");
+    git(root, "commit", "-q", ...message.flatMap((m) => ["-m", m]));
+  } finally {
+    delete process.env.GIT_AUTHOR_DATE;
+    delete process.env.GIT_COMMITTER_DATE;
+  }
+  return git(root, "rev-parse", "HEAD");
+}
+
+function edit(name: string, message: string[]): string {
+  writeFiles(root, { "app/main.js": `export const n = ${tick};\n` });
+  return (sha[name] = commit(message));
+}
+
+beforeAll(async () => {
+  root = repo({
+    "chant.workspace.json": JSON.stringify({
+      name: "links",
+      schema: 1,
+      members: [{ name: "app", dir: "app", kind: "other", because: "the app" }],
+      records: [{ kind: "decisions/decision.kind.mjs" }, { kind: "work/work.kind.mjs" }],
+      ci: { green: { branch: "main", phases: { lint: ["lint"] }, require: ["lint"] } },
+    }),
+    "decisions/decision.kind.mjs": readFileSync(join(REF, "decisions", "decision.kind.mjs"), "utf-8"),
+    "decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
+    "decisions/s-001-app.md": decision("s-001"),
+    "work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
+    "work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
+    "work/W-001-one.md": work("W-001"),
+    "work/W-002-two.md": work("W-002"),
+    "app/main.js": "export const n = 0;\n",
+  });
+  git(root, "symbolic-ref", "HEAD", "refs/heads/main");
+  sha.c0 = commit(["the workspace"]);
+  edit("c1", ["one", "Chant-Record: work:W-001"]);
+  edit("c2", ["two", `Chant-Lease: ${TOKEN}`]);
+  edit("c3", ["three"]);
+  edit("c4", ["four", "Chant-Record: work:W-999"]);
+  edit("c5", ["five", "Chant-Record: decision:s-001"]);
+  edit("c6", ["six", "Chant-Lease: no-such-token"]);
+  edit("c7", ["seven", "Chant-Record: nonsense"]);
+  edit("c8", ["eight", "Chant-Record: decision:s-001\nChant-Record: work:W-002"]);
+  git(root, "checkout", "-q", "-b", "side");
+  writeFiles(root, { "app/side.js": "export const side = 1;\n" });
+  commit(["on a side branch"]);
+  git(root, "checkout", "-q", "main");
+  process.env.GIT_AUTHOR_DATE = process.env.GIT_COMMITTER_DATE = "2026-10-01T12:30:00Z";
+  try {
+    git(root, "merge", "-q", "--no-ff", "-m", "Merge side", "side");
+  } finally {
+    delete process.env.GIT_AUTHOR_DATE;
+    delete process.env.GIT_COMMITTER_DATE;
+  }
+  sha.m = git(root, "rev-parse", "HEAD");
+  const line = { version: 1, event: "claim", item: "W-002", holder: "factory", by: "factory", token: TOKEN, acquiredAt: "2026-10-01T12:00:00Z", expiresAt: "2026-10-01T12:10:00Z", timestamp: "2026-10-01T12:00:00Z" };
+  await writeBlobToPath("_leases", "W-002.jsonl", JSON.stringify(line), "Work lease claim: W-002", { cwd: root });
+});
+afterAll(cleanScratch);
+
+const RANGE = () => `${sha.c0}..${sha.m}`;
+
+async function check(severity?: "off" | "warn" | "fail"): Promise<{ doc: Result; failed: boolean }> {
+  const { doc, failed } = await checkChanges({ cwd: root, range: RANGE(), ...(severity ? { severity } : {}) });
+  changes.expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return { doc, failed };
+}
+
+describe("judging one commit's trailers", () => {
+  const index: WorkIndex = { kinds: new Map([["work", new Set(["W-1", "W-2"])]]), ledger: true };
+  const none = { records: [], lease: null };
+
+  test("a Chant-Record of a work kind with that record links, whatever else the commit names", () => {
+    expect(judgeCommitLink({ "Chant-Record": ["work:W-1"] }, { records: [{ kind: "work", id: "W-1" }], lease: null }, index)).toEqual({ state: "linked", ids: ["work:W-1"], problems: [] });
+    const both = judgeCommitLink({ "chant-record": ["decision:d-1", "work:W-2", "work:W-404"] }, { records: [{ kind: "decision", id: "d-1" }, { kind: "work", id: "W-2" }, { kind: "work", id: "W-404" }], lease: null }, index);
+    expect(both).toEqual({ state: "linked", ids: ["work:W-2"], problems: [] });
+  });
+
+  test("a Chant-Lease links through the work item its history names", () => {
+    expect(judgeCommitLink({ "Chant-Lease": ["t"] }, { records: [], lease: { token: "t", item: "W-2" } }, index)).toMatchObject({ state: "linked", ids: ["work:W-2"] });
+    expect(judgeCommitLink({ "Chant-Lease": ["t"] }, { records: [], lease: { token: "t", item: "W-404" } }, index)).toMatchObject({ state: "wrong" });
+    expect(judgeCommitLink({ "Chant-Lease": ["t"] }, { records: [], lease: { token: "t", item: null } }, index)).toMatchObject({ state: "wrong" });
+  });
+
+  test("a lease is not judged where the lease histories are not there to read", () => {
+    const link = judgeCommitLink({ "Chant-Lease": ["t"] }, { records: [], lease: { token: "t", item: null } }, { ...index, ledger: false });
+    expect(link).toEqual({ state: "linked", ids: [], problems: [] });
+  });
+
+  test("a commit with no trailer is unlinked, and a window match is not a trailer", () => {
+    expect(judgeCommitLink({}, none, index)).toEqual({ state: "unlinked", ids: [], problems: [] });
+    expect(judgeCommitLink({ "Chant-Agent": ["factory"], "Chant-Run": ["r-1"] }, none, index).state).toBe("unlinked");
+  });
+
+  test("each wrongly linked case says which trailer and why", () => {
+    const wrong = (value: string, ref: { kind: string; id: string } | null) => judgeCommitLink({ "Chant-Record": [value] }, { records: ref ? [ref] : [], lease: null }, index);
+    expect(wrong("work:W-9", { kind: "work", id: "W-9" })).toEqual({ state: "wrong", ids: [], problems: [{ trailer: "Chant-Record: work:W-9", message: "the work kind has no record W-9" }] });
+    expect(wrong("decision:d-1", { kind: "decision", id: "d-1" }).problems[0].message).toBe("decision is not a work kind (the work kinds are work)");
+    expect(wrong("nonsense", null).problems[0]).toEqual({ trailer: "Chant-Record: nonsense", message: "nonsense is not <kind>:<id>" });
+  });
+});
+
+describe("workspace check --changes (#4029)", () => {
+  test("judges the first-parent commits of the range, merges left out", async () => {
+    const { doc, failed } = await check();
+    expect(failed).toBe(false);
+    expect(doc.links!.kinds).toEqual(["work"]);
+    expect(doc.links!.commits.map((c) => [c.commit, c.state, c.ids])).toEqual([
+      [sha.c1, "linked", ["work:W-001"]],
+      [sha.c2, "linked", ["work:W-002"]],
+      [sha.c3, "unlinked", []],
+      [sha.c4, "wrong", []],
+      [sha.c5, "wrong", []],
+      [sha.c6, "wrong", []],
+      [sha.c7, "wrong", []],
+      [sha.c8, "linked", ["work:W-002"]],
+    ]);
+    expect(doc.links!.commits.find((c) => c.commit === sha.c4)!.problems).toEqual([{ trailer: "Chant-Record: work:W-999", message: "the work kind has no record W-999" }]);
+    expect(doc.links!.commits.find((c) => c.commit === sha.c5)!.problems[0].message).toContain("decision is not a work kind");
+    expect(doc.links!.commits.find((c) => c.commit === sha.c6)!.problems).toEqual([{ trailer: "Chant-Lease: no-such-token", message: "no lease history on chant/lifecycle names this token" }]);
+    expect(doc.links!.commits.find((c) => c.commit === sha.c7)!.problems[0].trailer).toBe("Chant-Record: nonsense");
+  });
+
+  test("reports an unlinked commit and each wrongly linked one with a fix line, at warn by default", async () => {
+    const { doc } = await check();
+    expect(doc.links!.findings.map((f) => [f.code, f.commit, f.severity])).toEqual([
+      ["commit-unlinked", sha.c3, "warn"],
+      ["commit-wrongly-linked", sha.c4, "warn"],
+      ["commit-wrongly-linked", sha.c5, "warn"],
+      ["commit-wrongly-linked", sha.c6, "warn"],
+      ["commit-wrongly-linked", sha.c7, "warn"],
+    ]);
+    expect(doc.links!.findings[0].id).toBe(`finding:commit-unlinked:${sha.c3}`);
+    expect(doc.links!.findings.every((f) => f.fix.includes("Chant-Record"))).toBe(true);
+    expect(doc.ok).toBe(true);
+    const text = formatChanges(doc);
+    expect(text).toContain("links     8 commits: 3 name a work item, 1 do not, 4 name one that is not there; work kinds: work");
+    expect(text).toContain(`warning   commit-unlinked: ${sha.c3.slice(0, 8)} "three" carries no Chant-Record trailer of a work kind and no Chant-Lease trailer`);
+    expect(text).toContain("          fix: add a `Chant-Record: work:<id>` trailer");
+    expect(text).toContain(`commit-wrongly-linked: ${sha.c4.slice(0, 8)} "four" names no work item that exists: Chant-Record: work:W-999 (the work kind has no record W-999)`);
+  });
+
+  test("--severity sets the level: fail fails the check, off reports no finding", async () => {
+    const fail = await check("fail");
+    expect(fail.failed).toBe(true);
+    expect(fail.doc.ok).toBe(false);
+    expect(fail.doc.links!.findings.every((f) => f.severity === "fail")).toBe(true);
+    expect(formatChanges(fail.doc)).toContain("error     commit-unlinked");
+    const off = await check("off");
+    expect(off.failed).toBe(false);
+    expect(off.doc.links!.findings).toEqual([]);
+    expect(off.doc.links!.commits).toHaveLength(8);
+  });
+
+  test("a range whose commits all name a work item has no finding", async () => {
+    const { doc } = await checkChanges({ cwd: root, range: `${sha.c0}..${sha.c2}` });
+    changes.expectValid(doc);
+    expect((doc as Result).links!.findings).toEqual([]);
+  });
+});
+
+describe("ci list and ci tick (#4029)", () => {
+  test("ci list --json marks each commit with its link, and merges as merge", async () => {
+    const doc = (await ciList({ cwd: root, now: NOW })) as Listed;
+    list.expectValid(doc);
+    const byCommit = Object.fromEntries(doc.commits.map((c) => [c.sha, c.work]));
+    expect(byCommit[sha.c1]).toEqual({ state: "linked", ids: ["work:W-001"], problems: [] });
+    expect(byCommit[sha.c2]).toMatchObject({ state: "linked", ids: ["work:W-002"] });
+    expect(byCommit[sha.c3]).toEqual({ state: "unlinked", ids: [], problems: [] });
+    expect(byCommit[sha.c4]).toMatchObject({ state: "wrong" });
+    expect(byCommit[sha.m]).toEqual({ state: "merge", ids: [], problems: [] });
+  });
+
+  test("ci list text gives the reason a commit's work item is unknown", async () => {
+    const doc = (await ciList({ cwd: root, now: NOW })) as Listed;
+    const text = formatList(doc).split("\n");
+    const line = (s: string) => text.find((l) => l.includes(s.slice(0, 12)))!;
+    expect(line(sha.c3)).toContain("; why unknown: no Chant-Record or Chant-Lease trailer names a work item");
+    expect(line(sha.c4)).toContain("; why unknown: the work item named is not there: Chant-Record: work:W-999");
+    expect(line(sha.c1)).not.toContain("why unknown");
+    expect(line(sha.m)).not.toContain("why unknown");
+  });
+
+  test("the field is null where the workspace declares no work kind", async () => {
+    const plain = scratchDir("chant-links-plain-");
+    git(plain, "init", "-q");
+    git(plain, "symbolic-ref", "HEAD", "refs/heads/main");
+    writeFiles(plain, {
+      "chant.workspace.json": JSON.stringify({ name: "plain", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "x" }], ci: { green: { branch: "main", phases: { lint: ["lint"] }, require: ["lint"] } } }),
+      "app/a.txt": "a\n",
+    });
+    git(plain, "add", "-A");
+    git(plain, "-c", "user.name=t", "-c", "user.email=t@example.com", "commit", "-q", "-m", "one");
+    const doc = (await ciList({ cwd: plain })) as Listed;
+    list.expectValid(doc);
+    expect(doc.commits.map((c) => c.work)).toEqual([null]);
+    expect(formatList(doc)).not.toContain("why unknown");
+  });
+
+  test("ci tick shows an unlinked commit with why unknown", async () => {
+    origin = scratchDir("chant-links-origin-");
+    git(origin, "init", "-q", "--bare");
+    git(root, "remote", "add", "origin", origin);
+    git(root, "push", "-q", "origin", "main");
+    const forge: CiForge = { kind: "github", checkRuns: async () => [] };
+    const result = await ciTick({ cwd: root, forge, now: NOW, dryRun: true });
+    const text = formatTick(result, true);
+    const line = (s: string) => text.split("\n").find((l) => l.includes(s.slice(0, 12)))!;
+    expect(line(sha.c3)).toMatch(/undecided: lint; why unknown: no Chant-Record or Chant-Lease trailer names a work item/);
+    expect(line(sha.c1)).not.toContain("why unknown");
+  });
+
+  test("whyWorkUnknown names nothing for a linked commit, a merge or no field", () => {
+    expect(whyWorkUnknown(null)).toBeUndefined();
+    expect(whyWorkUnknown(undefined)).toBeUndefined();
+    expect(whyWorkUnknown({ state: "linked", ids: ["work:W-1"], problems: [] })).toBeUndefined();
+    expect(whyWorkUnknown({ state: "merge", ids: [], problems: [] })).toBeUndefined();
+  });
+});

package/src/workspace/commit-links.ts

@@ -0,0 +1,183 @@
+/**
+ * Which work item a commit belongs to (#4029).
+ *
+ * A work item implements a decision, and a trunk commit says which work item
+ * it carries out in one of two ways:
+ *
+ * - a `Chant-Record: <kind>:<id>` trailer, where `<kind>` is a work kind the
+ *   declaration names (conventionally `work`) and the kind has a record `<id>`;
+ * - a `Chant-Lease` trailer whose token a lease history on `chant/lifecycle`
+ *   names a work item for, and that item is a record of a work kind.
+ *
+ * A window match (the intent graph's `worked` bucket) does not link a commit:
+ * the commit never said so itself. A commit is wrongly linked when it names a
+ * work record that does not exist, a record of a kind that is not a work
+ * kind, a lease that resolves to nothing, or a `Chant-Record` value that is
+ * not `<kind>:<id>`, and no trailer of it links to a work item.
+ *
+ * This is the one place that judgement is made. `workspace check --changes`
+ * reports it, `ci list` and `ci tick` show it, and later readers share
+ * {@link judgeCommitLink}. It reads trailers through `readTrailerJoins`,
+ * which `graph --intent` joins commits with, so both resolve a Chant-Record
+ * and a Chant-Lease the same way. Everything here reads local git.
+ */
+
+import { execFileSync } from "node:child_process";
+import { declaredRecordKinds, readDeclaration, WorkspaceReadError } from "./declaration";
+import { declaredKindFile } from "./declared-kinds";
+import { trailerValues } from "./intent-joins";
+import { commitDetails } from "./intent";
+import { loadRecordKind, RecordReadError } from "./records";
+import { readRecordsFor } from "./records-cli";
+import { readTrailerJoins } from "./trailer-joins";
+import { parseRecordRef, RECORD_TRAILER, LEASE_TRAILER } from "./trailers";
+import { locateWorkspace } from "./which-chant";
+
+/** `linked`, `unlinked` (no trailer names a work item), `wrong` (trailers name one that is not there), or `merge` (a merge commit carries no work of its own). */
+export type CommitLinkState = "linked" | "unlinked" | "wrong" | "merge";
+
+/** One trailer that does not link the commit, with why. */
+export interface CommitLinkProblem {
+  /** The trailer as written, such as `Chant-Record: decision:ws-075`. */
+  trailer: string;
+  message: string;
+}
+
+/** What {@link judgeCommitLink} says about one commit. */
+export interface CommitLink {
+  state: CommitLinkState;
+  /** The work records the commit's trailers name, as `<kind>:<id>`. Empty unless `linked`; also empty for a lease that could not be checked. */
+  ids: string[];
+  /** The trailers that do not link. Empty unless `wrong`. */
+  problems: CommitLinkProblem[];
+}
+
+/** The work records a revision has, by work kind. */
+export interface WorkIndex {
+  /** Each work kind's name, with the ids of its records. */
+  kinds: Map<string, Set<string>>;
+  /** Whether lease histories can be read: the local `chant/lifecycle` branch exists. Without it a lease is not judged. */
+  ledger: boolean;
+}
+
+/** The fix line for each state a check reports. */
+export const COMMIT_UNLINKED_FIX = "add a `Chant-Record: work:<id>` trailer when the commit is made (git commit --trailer \"Chant-Record: work:<id>\"), naming the work item the commit carries out";
+
+function workKindList(index: WorkIndex): string {
+  return [...index.kinds.keys()].join(", ") || "none";
+}
+
+/**
+ * Judge one commit from its trailers.
+ *
+ * `trailers` are the commit's parsed trailers, `joins` what
+ * `readTrailerJoins` made of them, and `index` the work records of the
+ * revision judged against. A commit is `linked` when any trailer names a
+ * work record; another trailer that names a decision or a typo beside it
+ * does not make it wrong.
+ */
+export function judgeCommitLink(trailers: Record<string, string[]>, joins: { records: { kind: string; id: string }[]; lease: { token: string; item: string | null } | null }, index: WorkIndex): CommitLink {
+  const ids: string[] = [];
+  const problems: CommitLinkProblem[] = [];
+  let unchecked = false;
+  const add = (id: string) => {
+    if (!ids.includes(id)) ids.push(id);
+  };
+  for (const value of trailerValues(trailers, RECORD_TRAILER)) {
+    const trailer = `${RECORD_TRAILER}: ${value}`;
+    const ref = parseRecordRef(value);
+    if (!ref) {
+      problems.push({ trailer, message: `${value} is not <kind>:<id>` });
+      continue;
+    }
+    const known = index.kinds.get(ref.kind);
+    if (!known) problems.push({ trailer, message: `${ref.kind} is not a work kind (the work kinds are ${workKindList(index)})` });
+    else if (!known.has(ref.id)) problems.push({ trailer, message: `the ${ref.kind} kind has no record ${ref.id}` });
+    else add(`${ref.kind}:${ref.id}`);
+  }
+  if (joins.lease) {
+    const trailer = `${LEASE_TRAILER}: ${joins.lease.token}`;
+    const item = joins.lease.item;
+    if (item === null) {
+      if (index.ledger) problems.push({ trailer, message: "no lease history on chant/lifecycle names this token" });
+      else unchecked = true;
+    } else {
+      const hits = [...index.kinds].filter(([, found]) => found.has(item)).map(([kind]) => kind);
+      if (hits.length === 1) add(`${hits[0]}:${item}`);
+      else problems.push({ trailer, message: hits.length === 0 ? `the lease was taken on ${item}, which no work kind has a record for` : `the lease was taken on ${item}, which ${hits.join(" and ")} both have, so it names no one work item` });
+    }
+  }
+  if (ids.length > 0 || unchecked) return { state: "linked", ids, problems: [] };
+  return problems.length > 0 ? { state: "wrong", ids: [], problems } : { state: "unlinked", ids: [], problems: [] };
+}
+
+/**
+ * Judge each commit by its own trailers. A commit in `merges` is `merge`:
+ * its work is the commits it brings. Reads the lease histories on the local
+ * `chant/lifecycle` branch once, and never fetches.
+ */
+export function judgeCommits(top: string, shas: string[], index: WorkIndex, merges: ReadonlySet<string> = new Set()): Map<string, CommitLink> {
+  const details = commitDetails(top, shas);
+  const joined = readTrailerJoins(
+    top,
+    shas.map((sha) => ({ sha, trailers: details.get(sha)?.trailers ?? {} })),
+  );
+  const out = new Map<string, CommitLink>();
+  for (const sha of shas) {
+    if (merges.has(sha)) {
+      out.set(sha, { state: "merge", ids: [], problems: [] });
+      continue;
+    }
+    out.set(sha, judgeCommitLink(details.get(sha)?.trailers ?? {}, joined.get(sha)!.joins, index));
+  }
+  return out;
+}
+
+/** Whether the lease histories can be read from this repository: the local `chant/lifecycle` branch exists. */
+export function hasLeaseLedger(top: string): boolean {
+  try {
+    execFileSync("git", ["rev-parse", "--verify", "--quiet", "refs/heads/chant/lifecycle"], { cwd: top, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Which of `shas` are merge commits. */
+export function mergeCommits(top: string, shas: string[]): Set<string> {
+  const out = new Set<string>();
+  if (shas.length === 0) return out;
+  const text = execFileSync("git", ["log", "--no-walk=unsorted", "--stdin", "--format=%H %P"], { cwd: top, encoding: "utf-8", input: `${shas.join("\n")}\n`, maxBuffer: 256 * 1024 * 1024 });
+  for (const line of text.split("\n")) {
+    const [sha, ...parents] = line.trim().split(" ");
+    if (sha && parents.length > 1) out.add(sha);
+  }
+  return out;
+}
+
+/**
+ * The work records the declaration's work kinds hold at `at` (a revision, or
+ * the working tree without one). Null when `cwd` is in no workspace, the
+ * declaration names no work kind, or a kind can't be read: the question
+ * "which work item" has no answer there.
+ */
+export async function readWorkIndex(cwd: string, top: string, at?: string): Promise<WorkIndex | null> {
+  try {
+    const located = locateWorkspace(cwd, at);
+    const declaration = readDeclaration(located.tree);
+    const kinds = new Map<string, Set<string>>();
+    for (const d of declaredRecordKinds(declaration)) {
+      const file = declaredKindFile(d, located.rootOnDisk);
+      const loaded = await loadRecordKind(file, cwd);
+      if (!loaded.kind.work) continue;
+      const read = await readRecordsFor({ kind: file, cwd, ...(at !== undefined ? { at } : {}) });
+      const ids = (kinds.get(loaded.kind.name) ?? new Set<string>());
+      for (const r of read.result.records) if (r.id !== null) ids.add(r.id);
+      kinds.set(loaded.kind.name, ids);
+    }
+    return kinds.size === 0 ? null : { kinds, ledger: hasLeaseLedger(top) };
+  } catch (err) {
+    if (err instanceof WorkspaceReadError || err instanceof RecordReadError) return null;
+    throw err;
+  }
+}

package/src/workspace/declaration.schema.json

@@ -1450,6 +1450,18 @@
           "items": {
             "$ref": "#/$defs/ciPhaseName"
           }
+        },
+        "signedSince": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$",
+          "description": "Added by #4031, read by chant 0.124.28 and newer. The full sha of the first commit on branch whose ci/green and ci/revoked tags must carry a DSSE statement in their annotation, signed by a key .chant/trust.json at base lists under runners for a principal holding the runner role. A tag on a strict first-parent ancestor of this commit counts unsigned, so existing tags keep working; a tag on any other commit, this one included, needs a statement. Position in history decides, never a date, which whoever makes a commit or a tag sets. A reader refuses a sha that names no commit in its clone with declaration-invalid. Absent, no tag needs a statement."
+        },
+        "source": {
+          "enum": [
+            "checks",
+            "runs"
+          ],
+          "description": "Added by #4044, read by chant 0.124.28 and newer, so a declaration that sets it sets minReader to 0.124.28 or newer. Where chant ci tick reads each phase's results. checks (the default): the forge's check runs, whose names the phases' patterns match. runs: chant's own Op runs, read from the run ledger on chant/lifecycle, for a project whose pipelines run as chant Ops, such as one on GitLab or Forgejo. A phase's patterns then match Op names, a run counts for the commit its record names as gitSha, and the latest run of each Op decides. A run counts only when its record carries a statement signed by a key .chant/trust.json at base lists under runners for a principal holding the runner role; the tick ignores and reports any other. A tick from runs signs every tag it makes, so it needs a runner key."
         }
       },
       "patternProperties": {

package/src/workspace/declaration.ts

@@ -205,9 +205,29 @@ export interface CiGreen {
   phases: CiPhase[];
   /** The phases a commit must pass, by name, in file order. */
   require: string[];
+  /**
+   * The full sha of the first commit on the branch whose ci tags need a
+   * statement signed by a runner key (#4031). A tag on a strict
+   * first-parent ancestor of it counts unsigned, and any other tag counts
+   * only with one. Readers refuse a sha that names no commit with
+   * `declaration-invalid`. Null when the declaration sets none, and then no
+   * tag needs a statement.
+   */
+  signedSince: string | null;
+  /**
+   * Where the tick reads each phase's results (#4044): `checks` (the
+   * default), the forge's check runs, whose names the phases' patterns
+   * match; or `runs`, chant's own Op runs on `chant/lifecycle`, whose Op
+   * names the patterns match, each counted only with a statement signed by
+   * a runner key.
+   */
+  source: CiSource;
   pointer: string;
 }
 
+/** Where `ci tick` reads phase results (#4044): forge check runs, or chant Op runs. */
+export type CiSource = "checks" | "runs";
+
 /** The declaration's `ci` block (#3573). */
 export interface CiDeclaration {
   green: CiGreen | null;
@@ -1029,7 +1049,7 @@ function identityOf(raw: unknown): IdentityPolicy | null {
  */
 function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): CiDeclaration | null {
   if (raw === undefined) return null;
-  const block = raw as { green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped }>; require: string[] } };
+  const block = raw as { green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped }>; require: string[]; signedSince?: string; source?: CiSource } };
   if (block.green === undefined) return { green: null };
   const g = block.green;
   const phases: CiPhase[] = Object.entries(g.phases).map(([name, p]) => ({
@@ -1046,7 +1066,7 @@ function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocatio
       at(`/ci/green/require/${i}`),
     );
   }
-  return { green: { branch: g.branch, window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], pointer: "/ci/green" } };
+  return { green: { branch: g.branch, window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" } };
 }
 
 function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {

package/src/workspace/identity-gate-rule.ts

@@ -14,7 +14,7 @@
  * else: no zod, no ajv, no package loading, so it bundles small.
  */
 
-import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, verifySshSignatureWith, type SealedGateApproval } from "./trust/gate-seal";
+import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, sshKeyFingerprint, sshSignatureKey, verifySshSignatureWith, type SealedGateApproval } from "./trust/gate-seal";
 import type { Signer } from "./trust/trust-files";
 
 /** The core classes, in the order a principal's roles are tried; `human` holds no role and is the rest. */
@@ -78,17 +78,101 @@ export function grantedClasses(classes: readonly ClassGrant[], roles: Readonly<R
  */
 export function admitApprover(rule: GateAdmissionRule, a: SealedGateApproval): string | null {
   const { gate, signers } = rule;
-  const want = rule.class;
-  if (want !== null && !rule.classes.some((c) => c.name === want)) {
-    return `identity.gates.${gate} names the class ${want}, which ${rule.unknownClass ?? "no pinned package supplies"}, so no approval can show it is in that class (known classes: ${rule.classes.map((c) => c.name).join(", ")})`;
-  }
+  const unknown = unknownClassRefusal(rule, "approval");
+  if (unknown !== null) return unknown;
   if (!signers.active) return `gate ${gate} needs a signed approval, and there is no signers file (${signers.signersPath}) at base to check one against`;
   const seal = sealRefusal(gate, signers, a);
   if (seal !== null) return seal;
+  return classRefusal(rule, a.resolvedBy);
+}
+
+/** Why no signature can show a principal is in the rule's class: the class is one the rule does not know. Null otherwise. */
+function unknownClassRefusal(rule: GateAdmissionRule, what: string): string | null {
+  const want = rule.class;
+  if (want === null || rule.classes.some((c) => c.name === want)) return null;
+  return `identity.gates.${rule.gate} names the class ${want}, which ${rule.unknownClass ?? "no pinned package supplies"}, so no ${what} can show it is in that class (known classes: ${rule.classes.map((c) => c.name).join(", ")})`;
+}
+
+/** Why `principal` is not in the rule's class, or null when it is or the rule names none. */
+function classRefusal(rule: GateAdmissionRule, principal: string): string | null {
+  const want = rule.class;
   if (want === null) return null;
-  const granted = grantedClasses(rule.classes, rule.roles, a.resolvedBy);
+  const granted = grantedClasses(rule.classes, rule.roles, principal);
   const inClass = want === "human" ? granted.length === 0 : granted.includes(want);
-  return inClass ? null : `${a.resolvedBy} is not in the class ${want} that gate ${gate} needs: no role grant at base puts them there`;
+  return inClass ? null : `${principal} is not in the class ${want} that gate ${rule.gate} needs: no role grant at base puts them there`;
+}
+
+// ── release cuts (#4031) ─────────────────────────────────────────────────
+
+/** The gate whose `identity.gates` entry says who may cut a release (#4031). */
+export const RELEASE_GATE = "release";
+
+/** The ssh signature namespace of a release cut's signature (#4031), so no other signature can stand in for one. */
+export const RELEASE_SEAL_NAMESPACE = "chant-release";
+
+/** A cut line's fields its signature covers (#4031), and the signature. */
+export interface SignedReleaseCut {
+  releaseDigest: string;
+  label: string | null;
+  actor: string;
+  timestamp: string;
+  /** The armored ssh signature, or null for an unsigned cut. */
+  signature: string | null;
+}
+
+/**
+ * The bytes a release cut's signature signs (#4031): the release digest,
+ * the label (empty for none), the actor who cut it and the cut's time,
+ * joined by LF with no final newline.
+ */
+export function releaseSealPayload(cut: Omit<SignedReleaseCut, "signature">): Buffer {
+  return Buffer.from(`${cut.releaseDigest}\n${cut.label ?? ""}\n${cut.actor}\n${cut.timestamp}`, "utf-8");
+}
+
+/** Why the cut's signature does not verify for its actor against the signers at base, or null when it does. */
+function releaseSignatureRefusal(signers: GateAdmissionRule["signers"], cut: SignedReleaseCut): string | null {
+  if (cut.signature === null) return `the cut by ${cut.actor} is not signed`;
+  if (!signers.active) return `there is no signers file (${signers.signersPath}) at base to check the cut's signature against`;
+  const where = `${signers.signersPath} at base`;
+  const listed = signers.signers.filter((s) => normalise(s.principal) === normalise(cut.actor));
+  if (listed.length === 0) return `${cut.actor} has no key in ${where}, so the cut's signature can't count`;
+  const keys = listed.filter((s) => namespaceAllowed(s.namespaces, RELEASE_SEAL_NAMESPACE)).map((s) => Buffer.from(s.key.split(" ")[1] ?? "", "base64"));
+  const r = verifySshSignatureWith(cut.signature, releaseSealPayload(cut), RELEASE_SEAL_NAMESPACE, keys);
+  return r.ok ? null : `the cut's signature does not verify for ${cut.actor} against ${where}: ${r.reason}`;
+}
+
+/**
+ * Why `cut` may not be made under the `release` gate's rule, or null when
+ * it may (#4031): its signature verifies for its actor against the signers
+ * at base and, when the gate names a class, the role grants at base put the
+ * actor in it. The same rule {@link admitApprover} applies to an approval,
+ * over the cut's own signed bytes.
+ */
+export function admitReleaseCut(rule: GateAdmissionRule, cut: SignedReleaseCut): string | null {
+  const unknown = unknownClassRefusal(rule, "cut");
+  if (unknown !== null) return unknown;
+  const seal = releaseSignatureRefusal(rule.signers, cut);
+  if (seal !== null) return `${seal}; identity.gates.${rule.gate} needs a release cut signed with chant release cut --sign`;
+  return classRefusal(rule, cut.actor);
+}
+
+/** Whether a cut's signature verifies, as `release list` and `workspace status` report it (#4031). */
+export interface ReleaseSignatureCheck {
+  /** `verified`: it verifies for the actor, who is in the release gate's class when it names one. `unsigned`: the cut has none. `unverified`: it does not, and `reason` says why. */
+  status: "verified" | "unsigned" | "unverified";
+  /** The fingerprint of the key in the signature, or null for an unsigned cut or one that can't be read. */
+  key: string | null;
+  reason: string;
+}
+
+/** Judge a stored cut's signature against `rule`, read at base. A rule with no class checks the signature alone. */
+export function checkReleaseSignature(rule: GateAdmissionRule, cut: SignedReleaseCut): ReleaseSignatureCheck {
+  if (cut.signature === null) return { status: "unsigned", key: null, reason: "the cut carries no signature" };
+  const blob = sshSignatureKey(cut.signature);
+  const key = blob ? sshKeyFingerprint(blob) : null;
+  const why = unknownClassRefusal(rule, "cut") ?? releaseSignatureRefusal(rule.signers, cut) ?? classRefusal(rule, cut.actor);
+  if (why !== null) return { status: "unverified", key, reason: why };
+  return { status: "verified", key, reason: `signed by ${cut.actor}${rule.class !== null ? `, in the class ${rule.class}` : ""}` };
 }
 
 /** The seal step, worded as `checkGateSeal` (`./trust/seal.ts`) words it against an active signers file at base. */