@intentius/chant 0.124.45 → 0.124.48

package/src/op/gate-approval.test.ts

@@ -504,7 +504,7 @@ describe("gate approval — a permit counts only under the context it was given
 describe("gate approval — the request a policy is asked (#2508)", () => {
   test("carries the approver, the gate and the context, with the plan digest", () => {
     expect(gatePolicyRequest({
-      op: "release", gate: "ship", resolvedBy: "release-bot", approver: { kind: "agent", roles: ["deployer"] },
+      op: "release", gate: "ship", resolvedBy: "release-bot", approver: { kind: "agent" }, roles: ["deployer"],
       planDigest: PLAN_A, context: { risk: "low" },
     })).toEqual({
       principal: { kind: "agent", name: "release-bot", roles: ["deployer"] },
@@ -513,6 +513,11 @@ describe("gate approval — the request a policy is asked (#2508)", () => {
       context: { risk: "low", planDigest: PLAN_A },
     });
   });
+
+  test("never carries the roles the approver claims (#4324)", () => {
+    const request = gatePolicyRequest({ op: "release", gate: "ship", resolvedBy: "github:sam", approver: { kind: "human", roles: ["maintainer"] } });
+    expect(request.principal.roles).toEqual([]);
+  });
 });
 
 describe("gate approval — the approval block is checked where it is written (#2508)", () => {

package/src/op/gate-approval.ts

@@ -33,10 +33,10 @@
  * permit counts only while the run resolves that same context (#3774).
  *
  * A resolution is a local fact, not a signed one (`../lifecycle/gate-ledger.ts`).
- * Roles on it are what the approver claimed, and since #4290 the quorum
- * never reads them: a role counts only when `.chant/trust.json` at base
- * grants it and a seal proves the approver (`./gate-quorum.ts`). A policy
- * still sees the claimed roles in its request.
+ * Roles on it are what the approver claimed, and nothing trusts them: since
+ * #4290 the quorum counts a role only when `.chant/trust.json` at base grants
+ * it and a seal proves the approver (`./gate-quorum.ts`), and since #4324 a
+ * policy's request carries those same roles, never the claimed ones.
  */
 
 import { createHash } from "node:crypto";
@@ -282,17 +282,23 @@ export async function loadGatePolicyEvaluator(lexicon: string): Promise<GatePoli
   return mod as GatePolicyEvaluator;
 }
 
-/** The request a policy is asked about one approval. */
+/**
+ * The request a policy is asked about one approval. `roles` are the ones
+ * `.chant/trust.json` at base gives a proven approver (#4324), as a quorum
+ * judge reads them (`trustQuorumJudge` in `./gate-quorum.ts`). The roles the
+ * approver claims on `approver` are never read. Absent, the principal has none.
+ */
 export function gatePolicyRequest(input: {
   op: string;
   gate: string;
   resolvedBy: string;
   approver: GateApprover;
+  roles?: readonly string[];
   planDigest?: string;
   context?: Record<string, unknown>;
 }): GatePolicyRequest {
   return {
-    principal: { kind: input.approver.kind, name: input.resolvedBy, roles: input.approver.roles ?? [] },
+    principal: { kind: input.approver.kind, name: input.resolvedBy, roles: [...(input.roles ?? [])] },
     action: "PassGate",
     resource: { op: input.op, gate: input.gate },
     context: {

package/src/op/gate-quorum-at-base.test.ts

@@ -0,0 +1,211 @@
+/**
+ * #4324: an Op gate's quorum is `identity.gates.<gate>.quorum` in the
+ * workspace declaration at base, so a change can't lower the quorum its own
+ * run needs, and a gate policy's `principal.roles` come from
+ * `.chant/trust.json` at base for a proven approver, never from `chant
+ * approve --role`.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "vitest";
+import type { GateStep, OpConfig } from "./types";
+import type { ActivityFn } from "./activity-registry";
+import { resolveGateApproval, runOpLocally } from "./local-executor";
+import { gitGateLedgerPort, memoryGateLedgerPort, type GateLedgerPort } from "./gate";
+import type { GatePolicyEvaluator, GatePolicyRef, GatePolicyRequest } from "./gate-approval";
+import { appendPendingGate, type GateResolutionInput } from "../lifecycle/gate-ledger";
+import { resetGateOrigin } from "../lifecycle/gate-origin";
+import { sealGateApproval } from "../workspace/trust/seal";
+import { hasSshKeygen, TestRepo, type Key } from "../workspace/trust/test-repo";
+import { recordGateApproval } from "../cli/handlers/approve";
+
+const repos: TestRepo[] = [];
+const home = process.cwd();
+afterEach(() => {
+  process.chdir(home);
+  resetGateOrigin();
+  while (repos.length) repos.pop()!.cleanup();
+});
+
+let keys: TestRepo;
+let alice: Key;
+let bob: Key;
+beforeAll(() => {
+  if (!hasSshKeygen) return;
+  keys = new TestRepo("4324-keys");
+  alice = keys.key("alice");
+  bob = keys.key("bob");
+});
+afterAll(() => keys?.cleanup());
+
+/** A repository whose `main` is the base, with a git identity the ledger writes can use. */
+function repo(label: string, files: Record<string, string>): TestRepo {
+  const r = new TestRepo(label);
+  repos.push(r);
+  r.git(["config", "user.email", "t@example.test"]);
+  r.git(["config", "user.name", "t"]);
+  r.git(["config", "commit.gpgsign", "false"]);
+  for (const [path, text] of Object.entries(files)) r.write(path, text);
+  r.commit("base");
+  return r;
+}
+
+const declaration = (gates: Record<string, unknown>): string =>
+  JSON.stringify({ name: "acme", schema: 1, members: [], identity: { gates } });
+
+describe("resolveGateApproval reads the quorum at base (#4324)", () => {
+  const step = (approval?: GateStep["approval"]): GateStep => ({ kind: "gate", gate: "ship", ...(approval ? { approval } : {}) }) as GateStep;
+
+  test("the base quorum replaces the Op's own", () => {
+    expect(resolveGateApproval(step({ quorum: { count: 1 } }), new Map(), undefined, { count: 2 })).toEqual({ quorum: { count: 2 }, mode: "log-only" });
+  });
+
+  test("a gate whose Op dropped its approval block still takes the base quorum", () => {
+    expect(resolveGateApproval(step(), new Map(), undefined, { count: 2 })).toEqual({ quorum: { count: 2 }, mode: "log-only" });
+  });
+
+  test("a base list is matched against the run's environment", () => {
+    const atBase = [{ targets: ["prod"], count: 2 }, { count: 1 }];
+    expect(resolveGateApproval(step({ quorum: { count: 1 } }), new Map(), "prod", atBase)?.quorum).toEqual(atBase);
+    expect(resolveGateApproval(step({ quorum: { count: 1 } }), new Map(), "dev", atBase)?.quorum).toEqual([{ count: 1 }]);
+  });
+
+  test("with no quorum at base, the Op's own applies", () => {
+    expect(resolveGateApproval(step({ quorum: { count: 3 } }), new Map(), undefined, null)).toEqual({ quorum: { count: 3 }, mode: "log-only" });
+    expect(resolveGateApproval(step(), new Map(), undefined, null)).toBeUndefined();
+  });
+});
+
+describe.skipIf(!hasSshKeygen)("an Op gate's quorum at base (#4324)", () => {
+  const NOW = "2026-10-23T12:00:00.000Z";
+  const config = (count: number): OpConfig => ({
+    name: "release",
+    overview: "",
+    phases: [
+      { name: "Gate", steps: [{ kind: "gate", gate: "ship", approval: { quorum: { count } } }] },
+      { name: "Apply", steps: [{ kind: "activity", fn: "ship", args: {} }] },
+    ],
+  });
+  const activities = new Map<string, ActivityFn>([["ship", async () => ({})]]);
+
+  test("a change that lowers its own quorum still needs the quorum at base", async () => {
+    const r = repo("4324-quorum", {
+      "chant.workspace.json": declaration({ ship: { quorum: { count: 2 } } }),
+      ".chant/allowed_signers": `github:alice ${alice.pub}\ngithub:bob ${bob.pub}\n`,
+    });
+    // The pull request lowers both the declaration's quorum and the Op's.
+    r.git(["checkout", "-q", "-b", "lower-quorum"]);
+    r.write("chant.workspace.json", declaration({ ship: { quorum: { count: 1 } } }));
+    r.commit("lower the quorum");
+
+    const memory = memoryGateLedgerPort();
+    const git = gitGateLedgerPort({ cwd: r.dir });
+    const gates: GateLedgerPort = { ...memory, approvalRule: git.approvalRule, quorumJudge: git.quorumJudge };
+    const approve = async (by: string, key: Key, timestamp: string) => {
+      const line = { op: "release", gate: "ship", resolvedBy: by, timestamp, approver: { kind: "human" as const } };
+      const input: GateResolutionInput = { ...line, seal: sealGateApproval(key.file, line) };
+      await memory.appendResolution!(input);
+    };
+
+    const first = await runOpLocally(config(1), activities, {}, undefined, { gates, now: NOW });
+    expect(first.status).toBe("gated");
+    expect(first.gate?.approval?.quorum).toEqual({ count: 2 });
+    expect(memory.appended[0]?.approval?.quorum).toEqual({ count: 2 });
+
+    await approve("github:alice", alice, "2026-10-23T12:01:00.000Z");
+    const second = await runOpLocally(config(1), activities, {}, undefined, { gates, now: "2026-10-23T12:02:00.000Z" });
+    expect(second.status).toBe("gated");
+
+    await approve("github:bob", bob, "2026-10-23T12:03:00.000Z");
+    const third = await runOpLocally(config(1), activities, {}, undefined, { gates, now: "2026-10-23T12:04:00.000Z" });
+    expect(third.status).toBe("ok");
+    expect(third.records.find((rec) => rec.fn === "gate:ship")?.approval).toMatchObject({ via: "quorum", approvers: ["github:alice", "github:bob"] });
+  });
+
+  test("a gate the declaration names with no quorum keeps the Op's", async () => {
+    const r = repo("4324-no-quorum", {
+      "chant.workspace.json": declaration({ ship: {} }),
+      ".chant/allowed_signers": `github:alice ${alice.pub}\n`,
+    });
+    const git = gitGateLedgerPort({ cwd: r.dir });
+    const gates: GateLedgerPort = { ...memoryGateLedgerPort(), approvalRule: git.approvalRule };
+    const run = await runOpLocally(config(3), activities, {}, undefined, { gates, now: NOW });
+    expect(run.gate?.approval?.quorum).toEqual({ count: 3 });
+  });
+});
+
+describe.skipIf(!hasSshKeygen)("a gate policy's roles come from trust.json at base (#4324)", () => {
+  const POLICY: GatePolicyRef = { kind: "gate-policy", lexicon: "cedar", name: "ship", version: "sha256:v1", text: "permit when maintainer" };
+  /** Permits only a principal with the maintainer role, and remembers what it was asked. */
+  function maintainersOnly(): GatePolicyEvaluator & { asked: GatePolicyRequest[] } {
+    const asked: GatePolicyRequest[] = [];
+    return {
+      asked,
+      evaluateGatePolicy: (_policy, request) => {
+        asked.push(request);
+        return request.principal.roles.includes("maintainer")
+          ? { decision: "allow", determining: ["maintainers"], errors: [] }
+          : { decision: "deny", determining: [], errors: [] };
+      },
+    };
+  }
+
+  async function gated(): Promise<TestRepo> {
+    const r = repo("4324-policy", {
+      "README.md": "x\n",
+      ".chant/allowed_signers": `github:alice ${alice.pub}\n`,
+      ".chant/trust.json": JSON.stringify({ schema: 1, roles: { maintainer: ["github:alice"] } }),
+    });
+    await appendPendingGate(
+      {
+        op: "release",
+        gate: "ship",
+        timestamp: "2026-10-23T12:00:00.000Z",
+        origin: "cli",
+        expiresAt: "2999-01-01T00:00:00.000Z",
+        approval: { policy: POLICY, mode: "enforce" },
+      },
+      { cwd: r.dir },
+    );
+    process.chdir(r.dir);
+    return r;
+  }
+
+  test("a claimed --role the trust file does not grant fails a policy that requires it", async () => {
+    const r = await gated();
+    const evaluator = maintainersOnly();
+    const outcome = await recordGateApproval("release", "ship", { origin: "cli", actor: "github:sam", roles: ["maintainer"], evaluator, cwd: r.dir });
+    expect(outcome.ok).toBe(true);
+    expect(evaluator.asked[0]?.principal).toEqual({ kind: "human", name: "github:sam", roles: [] });
+    if (!outcome.ok) return;
+    expect(outcome.record.policyDecision?.decision).toBe("deny");
+    // The claim is still recorded, as data nothing trusts.
+    expect(outcome.record.approver).toEqual({ kind: "human", roles: ["maintainer"] });
+  });
+
+  test("an unsealed approval by a granted principal gets no roles either", async () => {
+    const r = await gated();
+    const evaluator = maintainersOnly();
+    const outcome = await recordGateApproval("release", "ship", { origin: "cli", actor: "github:alice", roles: ["maintainer"], evaluator, cwd: r.dir });
+    expect(evaluator.asked[0]?.principal.roles).toEqual([]);
+    expect(outcome.ok && outcome.record.policyDecision?.decision).toBe("deny");
+  });
+
+  test("a sealed approval gets the roles trust.json at base grants, and only those", async () => {
+    const r = await gated();
+    const evaluator = maintainersOnly();
+    const outcome = await recordGateApproval("release", "ship", { origin: "cli", actor: "github:alice", roles: ["admin"], sign: alice.file, evaluator, cwd: r.dir });
+    expect(evaluator.asked[0]?.principal).toEqual({ kind: "human", name: "github:alice", roles: ["maintainer"] });
+    expect(outcome.ok && outcome.record.policyDecision?.decision).toBe("allow");
+  });
+
+  test("a grant the change adds to trust.json does not count until it is at base", async () => {
+    const r = await gated();
+    r.git(["checkout", "-q", "-b", "grant-sam"]);
+    r.write(".chant/allowed_signers", `github:alice ${alice.pub}\ngithub:bob ${bob.pub}\n`);
+    r.write(".chant/trust.json", JSON.stringify({ schema: 1, roles: { maintainer: ["github:alice", "github:bob"] } }));
+    r.commit("grant bob");
+    const evaluator = maintainersOnly();
+    await recordGateApproval("release", "ship", { origin: "cli", actor: "github:bob", sign: bob.file, evaluator, cwd: r.dir });
+    expect(evaluator.asked[0]?.principal.roles).toEqual([]);
+  });
+});

package/src/op/gate-quorum.ts

@@ -18,10 +18,16 @@
  * approver counts toward `roles`, and as someone who is not the author, only
  * when the approval proves who they are: a seal that verifies against the
  * signers file at base, or under `pr-review` the forge review of the merged
- * pull request. The judge of a gate decides that ({@link GateQuorumJudge});
+ * pull request, or a review a product recorded on a ledger the spec at base
+ * names (#4333). The judge of a gate decides that ({@link GateQuorumJudge});
  * with none, no approval proves anything, so a rule naming roles or
  * `notAuthor` is never met.
  *
+ * `notAuthor` reads who was involved in the change (#4333): the pull
+ * request's author, each login a `Requested-by:` trailer on its commits
+ * names, and the accounts an agent acts as. With `excludeInvolved`, an
+ * approval by any of them does not count at all.
+ *
  * This module is pure: no git, no file reads, no package, so
  * `@intentius/chant/gate-decision` bundles it. The judge is built by the
  * caller from the trust policy it read at base ({@link trustQuorumJudge}).
@@ -51,8 +57,14 @@ export interface QuorumJudgement {
   proven: boolean;
   /** The roles `.chant/trust.json` at base gives the approver. Empty unless `proven`. */
   roles: string[];
-  /** Whether the approver is the change's author. Undefined when nobody knows who the author is. */
+  /**
+   * Whether the approver was involved in the change: its author, or anyone
+   * else {@link TrustQuorumInput.involved} names. Undefined when nobody knows
+   * who the author is and the approver is not named as involved otherwise.
+   */
   author?: boolean;
+  /** Why the approval does not count at all (#4333): the approver was involved and the judge excludes everyone involved. */
+  excluded?: string;
 }
 
 /** Judges one approval for the rules. */
@@ -174,7 +186,7 @@ export function quorumRuleProgress(rule: GateQuorumRule, approvers: readonly Quo
   const seen = new Set<string>();
   const counted: QuorumApprover[] = [];
   for (const a of [...approvers].sort((x, y) => Date.parse(x.at) - Date.parse(y.at))) {
-    if (seen.has(norm(a.who))) continue;
+    if (seen.has(norm(a.who)) || a.judged.excluded !== undefined) continue;
     if (rule.roles?.length && !(a.judged.proven && a.judged.roles.some((r) => rule.roles!.includes(r)))) continue;
     seen.add(norm(a.who));
     counted.push(a);
@@ -216,6 +228,118 @@ export function quorumWaiting(progress: readonly GateQuorumRuleProgress[]): stri
 /** Whether a rule needs a proven approver: it names roles, or `notAuthor`. */
 export const ruleNeedsProof = (rule: GateQuorumRule): boolean => (rule.roles?.length ?? 0) > 0 || rule.notAuthor === true;
 
+/** Someone involved in a change (#4333), and why: `github:bob asked for abc1234`. */
+export interface QuorumInvolvement {
+  who: string;
+  why: string;
+}
+
+/** A login as a forge allows it, and a GitHub App's `[bot]` suffix. */
+const LOGIN = /^[A-Za-z0-9][A-Za-z0-9._-]*(\[bot\])?$/;
+
+/**
+ * The logins `Requested-by:` trailers on a commit message name, each once.
+ * Any line of the message counts, since a squash merge keeps the trailers of
+ * the commits it squashed in its body.
+ */
+export function requestedByTrailers(message: string): string[] {
+  const out: string[] = [];
+  for (const line of message.replace(/\r\n/g, "\n").split("\n")) {
+    const m = /^requested-by:\s*(\S+)\s*$/i.exec(line.trim());
+    if (m && LOGIN.test(m[1]!) && !out.some((o) => samePrincipal(o, m[1]!))) out.push(m[1]!);
+  }
+  return out;
+}
+
+/**
+ * The names a principal goes by: itself, and for a forge principal
+ * (`github:alice`, `gitlab@gitlab.acme.com:bob`) the login after the colon,
+ * so a trailer's bare login and an approval's principal name one person.
+ */
+export function principalNames(who: string): string[] {
+  const m = /^(?:github|gitlab|forgejo|gitea|codeberg)(?:@[^:\s]+)?:(.+)$/i.exec(who.trim());
+  return m ? [who, m[1]!] : [who];
+}
+
+/** Why `who` was involved in the change, or undefined when `involved` does not name them. */
+export function involvedWhy(involved: readonly QuorumInvolvement[], who: string): string | undefined {
+  const names = principalNames(who);
+  return involved.find((p) => principalNames(p.who).some((a) => names.some((b) => samePrincipal(a, b))))?.why;
+}
+
+/**
+ * Everyone involved in a change (#4333): the pull request's `author`, each
+ * login a `Requested-by:` trailer on `commits` names, and the `agents`'
+ * accounts. `principal` turns a trailer's login into the principal the
+ * forge's approvals name (`github:<login>`); absent, the login stands.
+ */
+export function changeInvolvement(o: {
+  author?: string;
+  commits?: readonly { sha: string; message: string }[];
+  agents?: readonly string[];
+  principal?: (login: string) => string;
+}): QuorumInvolvement[] {
+  const out: QuorumInvolvement[] = [];
+  const add = (who: string, why: string): void => {
+    if (who.trim() && !out.some((p) => samePrincipal(p.who, who))) out.push({ who, why });
+  };
+  if (o.author) add(o.author, `${o.author} opened the change`);
+  for (const c of o.commits ?? []) {
+    for (const login of requestedByTrailers(c.message)) add(o.principal ? o.principal(login) : login, `${login} asked for ${c.sha.slice(0, 7)}`);
+  }
+  for (const a of o.agents ?? []) add(a, `${a} is an account an agent acts as`);
+  return out;
+}
+
+/**
+ * A review a product recorded on its own ledger (#4333), as terragucci does
+ * under `pr-review`: a resolution with `via: "pr-review"`, the reviewed
+ * `head`, and the `reviewers` who approved it, by forge login. One line
+ * names every reviewer, so `resolvedBy` is not one person.
+ */
+export interface RecordedReview {
+  pr?: number;
+  head: string;
+  reviewers: string[];
+}
+
+/** The review a ledger line records, when it is a product's review line; null otherwise. */
+export function recordedReviewOf(r: GateResolutionRecord): RecordedReview | null {
+  const x = r as unknown as { via?: unknown; head?: unknown; reviewers?: unknown; pr?: unknown };
+  if (x.via !== "pr-review" || typeof x.head !== "string" || x.head === "") return null;
+  if (!Array.isArray(x.reviewers) || x.reviewers.length === 0 || x.reviewers.some((v) => typeof v !== "string" || v === "")) return null;
+  return { ...(typeof x.pr === "number" ? { pr: x.pr } : {}), head: x.head, reviewers: [...(x.reviewers as string[])] };
+}
+
+/**
+ * The approvals a product's review lines stand for (#4333): each line
+ * {@link recordedReviewOf} reads becomes one approval per reviewer, named by
+ * `principal(login)` (the login itself when absent), a human's, with the
+ * review on it. A seal on the line is dropped: it signs the line, not any
+ * one reviewer. Every other line is kept as it is. `reviews` lists the
+ * reviews read, for {@link TrustQuorumInput.recorded}.
+ */
+export function recordedReviewApprovals(
+  records: readonly GateResolutionRecord[],
+  principal: (login: string) => string = (login) => login,
+): { records: GateResolutionRecord[]; reviews: { head: string; approvers: string[] }[] } {
+  const out: GateResolutionRecord[] = [];
+  const reviews: { head: string; approvers: string[] }[] = [];
+  for (const r of records) {
+    const review = recordedReviewOf(r);
+    if (!review) {
+      out.push(r);
+      continue;
+    }
+    const approvers = review.reviewers.map(principal);
+    reviews.push({ head: review.head, approvers });
+    const { seal: _seal, ...rest } = r;
+    const base = Object.fromEntries(Object.entries(rest).filter(([k]) => !["via", "reviewers", "head", "pr", "excluded"].includes(k))) as unknown as GateResolutionRecord;
+    for (const who of approvers) out.push({ ...base, resolvedBy: who, approver: { kind: "human" }, review: { pr: review.pr ?? 0, head: review.head, approvers } });
+  }
+  return { records: out, reviews };
+}
+
 /** What {@link trustQuorumJudge} judges by. */
 export interface TrustQuorumInput {
   /** The signers at base: an approval whose seal verifies for its approver against them is proven. */
@@ -224,6 +348,22 @@ export interface TrustQuorumInput {
   roles: Readonly<Record<string, readonly string[]>>;
   /** The change's authors, as principals. Absent, nobody knows who they are. */
   authors?: readonly string[];
+  /**
+   * Everyone else involved in the change (#4333), from {@link
+   * changeInvolvement}: an approver named here is judged as an author, for
+   * `notAuthor`, whether or not `authors` is known.
+   */
+  involved?: readonly QuorumInvolvement[];
+  /** An approval by an author or anyone `involved` names does not count at all (#4333), toward any rule. */
+  excludeInvolved?: boolean;
+  /**
+   * Reviews a product recorded on the ledger the spec at base names (#4333),
+   * from {@link recordedReviewApprovals}: a resolution that names one's head
+   * and one of its approvers as `resolvedBy` is proven, as for `review`. Pass
+   * them only under `pr-review`, as the product proves its reviewers only
+   * then.
+   */
+  recorded?: readonly { head: string; approvers: readonly string[] }[];
   /**
    * Under `pr-review`, the merged pull request's review, read from the forge
    * in this run: a resolution that names this review's head and one of its
@@ -232,17 +372,25 @@ export interface TrustQuorumInput {
   review?: { head: string; approvers: readonly string[] };
 }
 
-/** The judge a gate's rules are met by: proof from a seal or the live review, roles from trust.json at base. */
+/**
+ * The judge a gate's rules are met by: proof from a seal, the live review or
+ * a review a product recorded, roles from trust.json at base, and the
+ * change's authors and everyone else involved in it left out.
+ */
 export function trustQuorumJudge(input: TrustQuorumInput): GateQuorumJudge {
+  const named = (list: readonly string[], who: string) => list.some((a) => samePrincipal(a, who));
   return (r) => {
     const sealed = r.seal !== undefined && r.seal !== null && gateSealRefusal(input.signers, r) === null;
-    const reviewed =
-      input.review !== undefined && r.review?.head === input.review.head && input.review.approvers.some((a) => samePrincipal(a, r.resolvedBy));
-    const proven = sealed || reviewed;
+    const reviewed = input.review !== undefined && r.review?.head === input.review.head && named(input.review.approvers, r.resolvedBy);
+    const recorded = r.review !== undefined && (input.recorded ?? []).some((x) => x.head === r.review!.head && named(x.approvers, r.resolvedBy));
+    const proven = sealed || reviewed || recorded;
+    const authored = input.authors !== undefined && input.authors.some((a) => samePrincipal(a, r.resolvedBy));
+    const why = authored ? `${r.resolvedBy} wrote the change` : involvedWhy(input.involved ?? [], r.resolvedBy);
     return {
       proven,
       roles: proven ? rolesOf(r.resolvedBy, input.roles) : [],
-      ...(input.authors !== undefined ? { author: input.authors.some((a) => samePrincipal(a, r.resolvedBy)) } : {}),
+      ...(why !== undefined ? { author: true } : input.authors !== undefined ? { author: false } : {}),
+      ...(why !== undefined && input.excludeInvolved ? { excluded: `${why}, so ${r.resolvedBy}'s approval does not count` } : {}),
     };
   };
 }

package/src/op/gate-review.ts

@@ -300,6 +300,20 @@ export function reviewSourceFromEnv(env: Record<string, string | undefined> = pr
   return forgejo ? forgejoReviews(opts) : githubReviews(opts);
 }
 
+/**
+ * The principal a forge login on the CI job's forge goes by (#4333):
+ * `github:<login>` on github.com, `gitlab@<host>:<login>` on another host,
+ * as {@link reviewSourceFromEnv}'s reviews name their approvers. A product
+ * records its reviewers and its `Requested-by:` trailers by login, and this
+ * reads them as the approvals they stand beside. A value that already has a
+ * forge's prefix is kept.
+ */
+export function forgePrincipalFromEnv(env: Record<string, string | undefined> = process.env): (login: string) => string {
+  const kind: ForgeKind = env.GITLAB_CI === "true" ? "gitlab" : env.FORGEJO_ACTIONS === "true" || env.GITEA_ACTIONS === "true" ? "forgejo" : "github";
+  const host = kind === "gitlab" ? (env.CI_SERVER_HOST ?? hostOf(env.CI_SERVER_URL, "gitlab.com")) : hostOf(env.GITHUB_SERVER_URL, "github.com");
+  return (login) => (/^(?:github|gitlab|forgejo|gitea|codeberg)(?:@[^:\s]+)?:/i.test(login.trim()) ? login : forgePrincipalOf(kind, host, login));
+}
+
 /**
  * The head of the pull request a CI job runs for, from its environment: the
  * event payload's `pull_request.head.sha` on GitHub and Forgejo (whose

package/src/op/gate.ts

@@ -53,7 +53,7 @@ import { sortedJsonReplacer } from "../utils";
 import { gateContextDigest, type GateApprover, type ResolvedGateApproval } from "./gate-approval";
 import {
   quorumNeed, quorumRuleProgress, quorumRules, ruleNeedsProof, samePrincipal, trustQuorumJudge, UNPROVEN_JUDGE,
-  type GateQuorumJudge, type GateQuorumRuleProgress,
+  type GateQuorumJudge, type GateQuorumRuleProgress, type GateQuorumSpec,
 } from "./gate-quorum";
 import { pushLifecycleReport, readBlobBySha, readBlobFromPath, readPathSha, requireLifecycleLedger, writeBlobToPath, RefCASConflictError } from "../lifecycle/git";
 import { parseDuration } from "./duration";
@@ -128,7 +128,12 @@ export interface GateLedgerPort {
 
 /** A workspace's rule for which approvals of a gate count (#3163): a signed approval, from a class when it names one. */
 export interface GateApprovalRule {
-  requirement: { gate: string; class: string | null };
+  /**
+   * `quorum` (#4324) is the entry's `identity.gates.<gate>.quorum` at base:
+   * the rules an Op gate of that name takes in place of its own. Absent or
+   * null when the entry sets none.
+   */
+  requirement: { gate: string; class: string | null; quorum?: GateQuorumSpec | null };
   /** Why `approval` doesn't count, or null when it does. */
   refuses(approval: GateResolutionRecord): string | null;
 }
@@ -318,6 +323,12 @@ export interface GateCheckInput {
    * and the merged pull request's review.
    */
   judge?: GateQuorumJudge;
+  /**
+   * The port's {@link GateLedgerPort.approvalRule} for this gate, when the
+   * caller already read it (#4324): the Op executor reads it first, for the
+   * quorum at base. Absent, it is read here; null means none applies.
+   */
+  rule?: GateApprovalRule | null;
   /** ISO-8601 "now" — supplied by the caller, so the decision is deterministic under test. */
   now?: string;
   /**
@@ -371,6 +382,31 @@ export interface GateCheckInput {
    * no `empty` resolution counts.
    */
   verifyEmpty?: (planDigest: string) => Promise<boolean>;
+  /**
+   * A workspace gate that may stand in for this gate (#2554, #2524 D17,
+   * ws-039). Read only on a gate bound to a plan, and only when the gate's
+   * own approvals don't pass it. The stand-in decides: it answers an approval
+   * only when the member opted in at base and the workspace approval's
+   * digest covers this member's plan. Absent, a workspace gate never
+   * satisfies this gate.
+   */
+  workspace?: WorkspaceGateStandIn;
+}
+
+/** What a workspace gate approval that stands in for a member gate names (#2554). */
+export interface WorkspaceGateStood {
+  /** The workspace gate's name. */
+  gate: string;
+  /** The digest of the member plans the approval covers. */
+  digest: string;
+  approvedBy: string;
+  /** When the workspace approval was recorded. */
+  timestamp: string;
+}
+
+/** See {@link GateCheckInput.workspace}. */
+export interface WorkspaceGateStandIn {
+  standIn(q: { op: string; gate: string; planDigest: string; environment?: string }): Promise<WorkspaceGateStood | null>;
 }
 
 /**
@@ -441,9 +477,10 @@ export type GateCheck =
        * under one of the gate's aliases counted, on any gate. `"empty"`
        * (#4045) when a release gate passed over an empty change set, on the
        * `empty: true` resolution the promote wrote, after the stored
-       * document was read back and found empty.
+       * document was read back and found empty. `"workspace"` (#2554) when a
+       * workspace gate's approval stood in for it ({@link GateCheckInput.workspace}).
        */
-      via?: "quorum" | "policy" | "alias" | "empty";
+      via?: "quorum" | "policy" | "alias" | "empty" | "workspace";
       /** Every approval that counted toward the quorum. Set with `via`. */
       approvals?: GateResolutionRecord[];
       /** The approvals this run carried from an alias and wrote under the gate's name (#3949). Set when `via` is `"alias"`. */
@@ -774,7 +811,7 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   // newest one since the standing fact comes back as a mismatch instead.
   const forOtherRelease = (r: GateResolutionRecord) => r.gate === input.gate && r.releaseDigest !== input.releaseDigest;
   // #3163: a gate the workspace's identity.gates names counts only signed approvals from its class.
-  const rule = (await port.approvalRule?.(input.gate)) ?? null;
+  const rule = input.rule !== undefined ? input.rule : ((await port.approvalRule?.(input.gate)) ?? null);
   const standing = latestPendingGate(pending, input.gate);
   const since = standing?.timestamp ?? EPOCH;
 
@@ -845,9 +882,8 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
         ? humanQuorumSince(pending, standing)
         : since;
     // #4290: who an approval proves, and their roles at base, for rules that read them.
-    const judge = quorumRules(input.approval.quorum).some(ruleNeedsProof)
-      ? (input.judge ?? (await port.quorumJudge?.(input.gate)) ?? UNPROVEN_JUDGE)
-      : UNPROVEN_JUDGE;
+    // #4333: a caller's judge applies to every rule, since it may leave out everyone involved in the change.
+    const judge = input.judge ?? (quorumRules(input.approval.quorum).some(ruleNeedsProof) ? ((await port.quorumJudge?.(input.gate)) ?? UNPROVEN_JUDGE) : UNPROVEN_JUDGE);
     const tally = tallyGateApprovals(resolutions, input.gate, since, input.planDigest, input.approval, humansSince, judge);
     if (tally.permit) {
       return { satisfied: true, resolution: tally.permit, via: "policy", approvals: tally.counted };
@@ -887,6 +923,29 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
     mismatched = found.mismatched;
   }
 
+  // #2554, ws-039: a workspace gate stands in only when the member opted in
+  // at base and the workspace approval's digest covers this plan.
+  if (input.workspace && input.planDigest !== undefined) {
+    const stood = await input.workspace.standIn({ op: input.op, gate: input.gate, planDigest: input.planDigest, ...(env !== undefined ? { environment: env } : {}) });
+    if (stood) {
+      return {
+        satisfied: true,
+        via: "workspace",
+        resolution: {
+          version: 1,
+          kind: "resolution",
+          op: input.op,
+          gate: input.gate,
+          resolvedBy: stood.approvedBy,
+          timestamp: stood.timestamp,
+          planDigest: input.planDigest,
+          ...(env !== undefined ? { environment: env } : {}),
+          workspaceGate: { gate: stood.gate, digest: stood.digest },
+        },
+      };
+    }
+  }
+
   // #4045: an approval of this gate for another release stands as a mismatch
   // when nothing closer does, so the refusal says an approval exists.
   if (!mismatched && input.planDigest !== undefined) {

package/src/op/index.ts

@@ -69,7 +69,7 @@ export {
   opWaveRecordPath,
   opWaveShare,
 } from "./op-waves";
-export type { OpWave, OpWaveApplyHooksRunner, OpWaveGatePolicy, OpWaveHook, OpWaveHookFailure, OpWaveHookMoment, OpWaveHooks, OpWaveJob, OpWaveRun, OpWavesDigest, OpWavesOverride, OpWavesSpec } from "./op-waves";
+export type { OpWave, OpWaveApplyHooksRunner, OpWaveGatePolicy, OpWaveHook, OpWaveHookFailure, OpWaveHookMoment, OpWaveHooks, OpWaveJob, OpWaveRun, OpWavesApprovals, OpWavesDigest, OpWavesInvolved, OpWavesOverride, OpWavesSpec } from "./op-waves";
 export {
   OP_WAVE_APPLY_OUTCOMES,
   OP_WAVE_MAX_REPLANS,
@@ -142,9 +142,10 @@ export type {
 } from "./gate-approval";
 export {
   quorumRules, quorumRulesFor, quorumNeed, quorumProblems, quorumRuleProgress, quorumRuleLine, quorumWaiting, rolesOf, trustQuorumJudge, UNPROVEN_JUDGE,
+  changeInvolvement, involvedWhy, principalNames, recordedReviewApprovals, recordedReviewOf, requestedByTrailers,
 } from "./gate-quorum";
 export type {
-  GateQuorumRule, GateQuorumSpec, GateQuorumJudge, GateQuorumRuleProgress, QuorumJudgement, QuorumApprover, TrustQuorumInput,
+  GateQuorumRule, GateQuorumSpec, GateQuorumJudge, GateQuorumRuleProgress, QuorumJudgement, QuorumApprover, TrustQuorumInput, QuorumInvolvement, RecordedReview,
 } from "./gate-quorum";
 export {
   gatePlanSummary, gatePlanSummaryOfResult, changeSetOfResult, GATE_PLAN_CONTEXT_KEY, GATE_PLAN_ADDRESS_LIMIT,