@intentius/chant 0.124.46 → 0.124.49

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

@@ -50,10 +50,10 @@ import { describePlanDigest, samePlanDigest } from "../lifecycle/plan-digest";
 import { isModelAuthored } from "../lifecycle/gate-origin";
 import { appliedGatePath, isApprovalSpent, parseAppliedGateLines, type AppliedGateRecord } from "../lifecycle/gate-applied";
 import { sortedJsonReplacer } from "../utils";
-import { gateContextDigest, type GateApprover, type ResolvedGateApproval } from "./gate-approval";
+import { gateContextDigest, type GateApprover, type GateBaseApproval, 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,13 @@ 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. `policy`,
+   * `mode` and `context` (#4404) are read the same way. Each is absent or
+   * null when the entry sets none.
+   */
+  requirement: { gate: string; class: string | null; quorum?: GateQuorumSpec | null } & GateBaseApproval;
   /** Why `approval` doesn't count, or null when it does. */
   refuses(approval: GateResolutionRecord): string | null;
 }
@@ -318,6 +324,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 +383,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 +478,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 +812,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 +883,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 +924,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,

package/src/op/local-executor.ts

@@ -35,13 +35,14 @@ import { contentDigest } from "../content-digest";
 import { parseDuration } from "./duration";
 import { stepLabel, withRunConsole, withStepConsole } from "./step-console";
 import { stepTimeoutProblem } from "./activity-profiles";
-import { describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "./gate";
+import { describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort, type GateApprovalRule, type GateCheck, type GateLedgerPort, type WorkspaceGateStandIn } from "./gate";
+import { resolveWorkspaceRun, type WorkspaceRunCitation } from "./workspace-run-env";
 import { gateName } from "./gate-name";
 import { resolveGateAliases } from "./gate-alias";
 import { gatePointOf } from "./gate-point";
 import { evaluatePointGate, workspaceGatePointAsker, type GatePointAsker } from "./gate-point-run";
-import type { ResolvedGateApproval } from "./gate-approval";
-import { quorumRules, quorumRulesFor } from "./gate-quorum";
+import type { GateBaseApproval, ResolvedGateApproval } from "./gate-approval";
+import { quorumRules, quorumRulesFor, type GateQuorumSpec } from "./gate-quorum";
 import { GATE_PLAN_CONTEXT_KEY, gatePlanSummaryOfResult } from "./gate-plan-context";
 import { withOpRunContext, type OpRunContext, type PassedGate } from "./run-context";
 import type { GateAnswerRef, PendingGateRecord } from "../lifecycle/gate-ledger";
@@ -109,8 +110,11 @@ export interface StepRecord {
     /**
      * On a gate with an `approval` block (#2508): whether a quorum or a policy permit passed it. `"point"` on a gate that asks a decision point (#3170).
      * `"alias"` (#3949) when an approval recorded under one of the gate's aliases counted, on any gate.
+     * `"workspace"` (#2554) when a workspace gate's approval stood in for it.
      */
-    via?: "quorum" | "policy" | "point" | "alias" | "empty";
+    via?: "quorum" | "policy" | "point" | "alias" | "empty" | "workspace";
+    /** With `via: "workspace"` (#2554): the workspace gate and the digest of the member plans its approval covers. */
+    workspaceGate?: { gate: string; digest: string };
     /** On a gate with a quorum (#2508): every approver who counted toward it. */
     approvers?: string[];
     /** On a gate that asks a decision point (#3170): the answer record that passed it, which the gate ledger's resolution cites too. */
@@ -612,6 +616,8 @@ interface GateContext {
   onRecord?: (record: StepRecord) => void;
   /** Where the run's events go (#4041): a step's start, its settle and its gate's decision. */
   emit?: RunEventSink;
+  /** A workspace gate that may stand in for this run's gates (#2554). Absent outside a workspace run started with a gate. */
+  workspace?: WorkspaceGateStandIn;
   /** The run context's list of passed gates (#2522). A gate that passes is appended here. */
   passed?: PassedGate[];
   /** The run's hold on its work item's lease (#2748). Absent in compensation phases, which run whatever the lease did. */
@@ -729,14 +735,43 @@ function gateFn(step: GateStep): string {
  * returned, the same walk `plan` goes through. A reference that resolves to
  * nothing is dropped rather than failing the run, so a policy reading it sees
  * the attribute as absent.
+ *
+ * #4324: the quorum is `identity.gates.<gate>.quorum` in the workspace
+ * declaration at base (`atBase`) whenever that sets one, and the Op's own
+ * `approval.quorum` is not read then, so a change can't lower the quorum its
+ * own run needs. The base quorum applies to a gate whose Op declares no
+ * `approval` block too. With none at base, the Op's quorum applies as before.
+ *
+ * #4404: `policy`, `mode` and `context` are read the same way, each from its
+ * own `identity.gates.<gate>` field (`baseApproval`). A field the entry sets
+ * replaces the Op's. The base `context` wins key by key: a change can't edit a
+ * key the entry declares, but a key only the Op declares (often a step output
+ * the run computes) still reaches the policy. A field the entry leaves out
+ * still comes from the Op, and `chant workspace check` (WSP153) reports it.
  */
-function resolveGateApproval(
+export function resolveGateApproval(
   step: GateStep,
   resultsById: ReadonlyMap<string, unknown>,
   env?: string,
+  atBase?: GateQuorumSpec | null,
+  baseApproval?: GateBaseApproval | null,
 ): ResolvedGateApproval | undefined {
-  const authored = step.approval;
-  if (!authored) return undefined;
+  const baseQuorum = atBase ?? undefined;
+  const base = {
+    policy: baseApproval?.policy ?? undefined,
+    mode: baseApproval?.mode ?? undefined,
+    context: baseApproval?.context ?? undefined,
+  };
+  const anyBase = baseQuorum !== undefined || base.policy !== undefined || base.mode !== undefined || base.context !== undefined;
+  const opApproval = step.approval ?? (anyBase ? {} : undefined);
+  if (!opApproval) return undefined;
+  const authored = {
+    ...opApproval,
+    ...(base.policy !== undefined ? { policy: base.policy } : {}),
+    ...(base.mode !== undefined ? { mode: base.mode } : {}),
+    ...(base.context !== undefined ? { context: { ...(opApproval.context ?? {}), ...base.context } } : {}),
+  };
+  const quorum = baseQuorum ?? authored.quorum;
   let context: Record<string, unknown> | undefined;
   if (authored.context) {
     context = {};
@@ -755,10 +790,10 @@ function resolveGateApproval(
   // #4290: the rules this run's gate takes, by its environment. A rule with
   // `targets` never covers a run with no environment. One rule with no
   // `targets` keeps its own shape, so a standing pending fact still matches.
-  const single = authored.quorum !== undefined && !Array.isArray(authored.quorum) && (authored.quorum as { targets?: unknown }).targets === undefined;
-  const rules = authored.quorum ? quorumRulesFor(quorumRules(authored.quorum), env !== undefined ? [env] : []) : [];
+  const single = quorum !== undefined && !Array.isArray(quorum) && (quorum as { targets?: unknown }).targets === undefined;
+  const rules = quorum ? quorumRulesFor(quorumRules(quorum), env !== undefined ? [env] : []) : [];
   return {
-    ...(single ? { quorum: authored.quorum } : rules.length > 0 ? { quorum: rules } : {}),
+    ...(single ? { quorum } : rules.length > 0 ? { quorum: rules } : {}),
     ...(authored.policy ? { policy: authored.policy } : {}),
     mode: authored.mode ?? "log-only",
     ...(context ? { context } : {}),
@@ -786,7 +821,16 @@ async function runGateStep(
   // a run over a missing digest.
   const resolvedPlan = resolveStepOutputRefs(step.plan, resultsById);
   const planDigest = typeof resolvedPlan === "string" && resolvedPlan !== "" ? resolvedPlan : undefined;
-  const approval = resolveGateApproval(step, resultsById, gates.env);
+  // #4324, #4404: the workspace's rule for this gate at base, read once: its quorum, policy, mode and context
+  // replaces the Op's, and evaluateGate judges approvals by it. A read that
+  // fails ends the step as a failing record, as a ledger read does below.
+  let rule: GateApprovalRule | null;
+  try {
+    rule = (await gates.port.approvalRule?.(gateName(step))) ?? null;
+  } catch (err) {
+    return { record: { phase: phaseName, fn: gateFn(step), args: {}, status: "fail", durationMs: Date.now() - start, error: errMessage(err) } };
+  }
+  const approval = resolveGateApproval(step, resultsById, gates.env, rule?.requirement.quorum, rule?.requirement);
   // #3947: a gate that resumes stores the outputs the steps after it read.
   const resumeAt = gates.resume?.gates.get(step);
   let checkpoint: GateCheckpoint | undefined;
@@ -814,9 +858,11 @@ async function runGateStep(
       ...(gates.gitSha ? { gitSha: gates.gitSha } : {}),
       ...(planDigest !== undefined ? { planDigest } : {}),
       ...(approval ? { approval } : {}),
+      rule,
       ...(gates.now ? { now: gates.now } : {}),
       ...(checkpoint ? { checkpoint } : {}),
       ...(step.aliases?.length ? { aliases: resolveGateAliases(step, gates.op) } : {}),
+      ...(gates.workspace ? { workspace: gates.workspace } : {}),
     });
   } catch (err) {
     // Deciding a gate reads and writes the `chant/lifecycle` branch, so it
@@ -847,6 +893,7 @@ async function runGateStep(
       timestamp: resolution.timestamp,
       ...(resolution.url ? { url: resolution.url } : {}),
       ...(check.via ? { via: check.via } : {}),
+      ...(resolution.workspaceGate ? { workspaceGate: resolution.workspaceGate } : {}),
       ...(check.approvals ? { approvers: check.approvals.map((r) => r.resolvedBy) } : {}),
       ...(check.carried?.length
         ? { carriedFrom: check.carried.map((r) => ({ op: r.carriedFrom!.op, gate: r.carriedFrom!.gate, resolvedBy: r.resolvedBy, timestamp: r.carriedFrom!.timestamp })) }
@@ -1278,6 +1325,18 @@ export interface RunOpOptions {
   gates?: GateLedgerPort;
   /** Working directory for the default git-backed gate ledger. */
   cwd?: string;
+  /**
+   * The workspace run that started this run (#2554). Defaults to the one the
+   * environment names (`CHANT_WORKSPACE_RUN`, `./workspace-run-env.ts`). The
+   * run record cites it.
+   */
+  workspaceRun?: WorkspaceRunCitation;
+  /**
+   * The workspace gate that may stand in for this run's gates (#2554). Defaults
+   * to the gate the workspace run names, read from the workspace ledger with
+   * the member's opt-in at base; a test passes a stub.
+   */
+  workspaceGate?: WorkspaceGateStandIn;
   /** ISO-8601 "now", so a gate decision is deterministic under test. */
   now?: string;
   /** Identifies this run on any pending fact it records. */
@@ -1492,6 +1551,8 @@ async function runOpInTurn(
   const commit = options.commit ?? (await resolveCommitSha(options.cwd ? { cwd: options.cwd } : {}));
   // #4020: the CI run this one is in, in the shape a deploy record carries it.
   const ciRun = resolveCiRun();
+  // #2554: the workspace run that started this one, which its record cites.
+  const workspaceRun = options.workspaceRun ?? resolveWorkspaceRun();
   // #4041: the run's events name it the way its run record does: its own id,
   // the commit, and the CI run it is in.
   // #4042: a run that writes to the ledger also keeps its events on this host,
@@ -1535,6 +1596,11 @@ async function runOpInTurn(
     passed: run.passedGates,
     points: options.points ?? workspaceGatePointAsker(options.cwd ?? process.cwd()),
     ...(options.env !== undefined ? { env: options.env } : {}),
+    ...(options.workspaceGate
+      ? { workspace: options.workspaceGate }
+      : workspaceRun?.gate
+        ? { workspace: lazyWorkspaceGate(options.cwd ?? process.cwd(), workspaceRun.gate) }
+        : {}),
   };
 
   // Effect steps are ordered (read-compare-run-write): refuse them in a
@@ -1658,6 +1724,7 @@ async function runOpInTurn(
       ...(resumed ? { resumed } : {}),
       ...(commit ? { gitSha: commit } : {}),
       ...(options.runner ? { runOrigin: options.runner.runOrigin } : ciRun ? { runOrigin: ciRun.runOrigin } : {}),
+      ...(workspaceRun ? { workspaceRun: { id: workspaceRun.id, ...(workspaceRun.gate ? { gate: workspaceRun.gate } : {}) } } : {}),
       phaseDurations,
     });
     if (status === "fail" && options.describeFailure) {
@@ -1954,3 +2021,16 @@ function phaseVerdict(records: readonly StepRecord[]): "ok" | "fail" | "skipped"
 function errMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
+
+/**
+ * The workspace gate stand-in for a member run (#2554), loading the workspace
+ * code only when a gate is asked about it.
+ */
+function lazyWorkspaceGate(cwd: string, gate: string): WorkspaceGateStandIn {
+  return {
+    async standIn(q) {
+      const { memberGateStandIn } = await import("../workspace/workspace-gates");
+      return memberGateStandIn(cwd, gate, q);
+    },
+  };
+}