@intentius/chant 0.124.40 → 0.124.41

package/src/op/op-waves-run.ts

@@ -68,11 +68,16 @@ import type { GateAnswerRef, PendingGateRecord } from "../lifecycle/gate-ledger"
 import type { GatePointAsker } from "../point-decision";
 import type { WaitingPoint } from "./steward-points";
 import { isApprovalSpent, type AppliedGateRecord } from "../lifecycle/gate-applied";
+import { samePlanDigest } from "../lifecycle/plan-digest";
 import { isLifecycleLocalNote } from "../lifecycle/local-note";
 import type { HeadPlans, MergedReview, ReviewSource } from "./gate-review";
 import type { TrustPolicy } from "../workspace/trust/policy";
-import type { GateSigners } from "../workspace/trust/gate-seal";
+import type { GateSigners } from "../lifecycle/gate-seal";
 import { ciRunIdFromEnv } from "./gate-run-locator";
+import {
+  quorumProblems, quorumRuleLine, quorumRulesFor, quorumWaiting, ruleNeedsProof, samePrincipal, trustQuorumJudge,
+  type GateQuorumRule, type GateQuorumRuleProgress,
+} from "./gate-quorum";
 import {
   OP_WAVE_DEFAULT_APPLY,
   OP_WAVE_GATE_POLICIES,
@@ -83,6 +88,7 @@ import {
   opWaveApplyHooksRunBy,
   opWaveGateName,
   opWaveHooksAt,
+  opWaveHookRuns,
   opWavePointAt,
   opWavePointProblems,
   opWaveRecordPath,
@@ -113,6 +119,13 @@ export interface OpWavePlanFile {
    * plan digest and these rules counts (`@intentius/chant/override-gate`).
    */
   denied?: { rules: string[]; reason?: string };
+  /**
+   * The product's policy holds this plan for a person (#4294): the ids of
+   * the hold rules that matched. The wave waits for an approval of its set
+   * digest whatever its gate policy says, as a hook with `onFailure:
+   * approve` holds it. `@intentius/chant/gate-policy` gives the rules.
+   */
+  held?: { rules: string[]; reason?: string };
 }
 
 /** What a wave-level plan command writes to `{plans}` (#3762): one plan per run, by target. The array alone is read too. */
@@ -170,6 +183,8 @@ export interface OpWaveMember extends WaveMember {
   denied?: { rules: string[]; reason?: string };
   /** The override that lets the denied plan through (#3821). */
   override?: { by: string; at: string; digest: string; reason: string };
+  /** The product's policy holds the plan for a person (#4294). */
+  held?: { rules: string[]; reason?: string };
 }
 
 /** Where a wave's policy came from. */
@@ -207,6 +222,10 @@ export interface OpWaveDecision {
   point?: OpWavePoint & { question?: WaitingPoint; answer?: GateAnswerRef };
   /** The review that approved the wave, or why the review did not, under `pr-review`. */
   review?: { pr?: number; head?: string; approvers?: string[]; url?: string; reason?: string };
+  /** The approval rules at base the wave's targets take (#4290). Absent when it takes none. */
+  quorum?: GateQuorumRule[];
+  /** Where each of those rules stands (#4290), while the wave waits. */
+  quorumProgress?: GateQuorumRuleProgress[];
   /** The command that approves this digest, when waiting. */
   approve?: string;
   /** The hooks read at base (#3762), which a wide wave's share jobs run too. Absent when there are none. */
@@ -489,6 +508,10 @@ export interface OpWaveBaseRules {
   point?: OpWavePoint;
   /** Set when the point at base cannot be asked: the wave fails rather than fall back to the ledger (#3836). */
   pointRefused?: string;
+  /** The approval rules at base (#4290), `approvals.quorum`. */
+  quorum?: GateQuorumRule[];
+  /** Set when the rules at base cannot be read: the wave fails rather than wait on fewer approvers than they ask. */
+  quorumRefused?: string;
 }
 
 const noHooks = (): Record<OpWaveHookMoment, OpWaveHook[]> =>
@@ -521,7 +544,7 @@ export function readOpWavePolicy(
   const spend = (spec as { approvals?: { spend?: unknown } }).approvals?.spend === true;
   const neverOverMcp = (spec as { neverOverMcp?: unknown }).neverOverMcp === true;
   // #3836: the gate's decision point, the spec's for a wave the base does not have yet.
-  const asks = pointAtBase(spec, name, `${specFile} at ${sha.slice(0, 12)}`);
+  const asks = { ...pointAtBase(spec, name, `${specFile} at ${sha.slice(0, 12)}`), ...quorumAtBase(spec, `${specFile} at ${sha.slice(0, 12)}`) };
   const wave = spec.waves.find((w) => w.name === name);
   if (!wave) return { ...absent, spend, neverOverMcp, ...asks };
   const policy = wave.gate ?? "always";
@@ -540,6 +563,15 @@ export function readOpWavePolicy(
   return rules;
 }
 
+/** The approval rules at base (#4290), or why they cannot be read. A spec at base with none has none. */
+function quorumAtBase(spec: OpWavesSpec, where: string): Pick<OpWaveBaseRules, "quorum" | "quorumRefused"> {
+  const raw = (spec as { approvals?: { quorum?: unknown } }).approvals?.quorum;
+  if (raw === undefined) return {};
+  const problems = Array.isArray(raw) ? quorumProblems(raw, "approvals.quorum", { notAuthor: true }) : ["`approvals.quorum` must be a list of rules"];
+  if (problems.length > 0) return { quorumRefused: `the approval rules in ${where} cannot be read (${problems.join("; ")})` };
+  return (raw as GateQuorumRule[]).length > 0 ? { quorum: raw as GateQuorumRule[] } : {};
+}
+
 /** The point wave `name` asks at base (#3836), or why it cannot be asked. */
 function pointAtBase(spec: OpWavesSpec, name: string, where: string): Pick<OpWaveBaseRules, "point" | "pointRefused"> {
   const raw = spec.waves.find((w) => w.name === name)?.point ?? spec.point;
@@ -674,11 +706,12 @@ function planRun(opts: { spec: OpWavesSpec; wave: number; cwd: string; exec: OpW
 }
 
 function member(target: string, op: string, file: OpWavePlanFile): OpWaveMember {
-  const denied = file.denied as unknown;
-  if (denied !== undefined) {
-    const d = denied as { rules?: unknown; reason?: unknown } | null;
+  for (const key of ["denied", "held"] as const) {
+    const value = file[key] as unknown;
+    if (value === undefined) continue;
+    const d = value as { rules?: unknown; reason?: unknown } | null;
     if (!d || typeof d !== "object" || !Array.isArray(d.rules) || d.rules.length === 0 || !d.rules.every((r) => typeof r === "string" && r.trim() !== "") || (d.reason !== undefined && typeof d.reason !== "string")) {
-      throw new Error(`the plan of ${target} has denied ${JSON.stringify(denied)}; a denial is { "rules": ["<rule id>", ...], "reason"?: "<text>" }`);
+      throw new Error(`the plan of ${target} has ${key} ${JSON.stringify(value)}; ${key === "denied" ? "a denial" : "a hold"} is { "rules": ["<rule id>", ...], "reason"?: "<text>" }`);
     }
   }
   return {
@@ -688,6 +721,7 @@ function member(target: string, op: string, file: OpWavePlanFile): OpWaveMember
     ...(file.destructive === true ? { destructive: true } : {}),
     ...(file.empty === true ? { empty: true } : {}),
     ...(file.denied ? { denied: { rules: file.denied.rules, ...(file.denied.reason ? { reason: file.denied.reason } : {}) } } : {}),
+    ...(file.held ? { held: { rules: [...new Set(file.held.rules)].sort(), ...(file.held.reason ? { reason: file.held.reason } : {}) } } : {}),
   };
 }
 
@@ -768,7 +802,7 @@ function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string;
   const members = runs.map((run) => {
     const m = member(run.target, run.op ?? spec.op, byTarget.get(run.target)!);
     const path = join(cwd, opWavePlanPath(spec, k, run.target));
-    writeFileSync(path, JSON.stringify({ planDigest: m.planDigest, ...(m.destructive ? { destructive: true } : {}), ...(m.empty ? { empty: true } : {}), ...(m.denied ? { denied: m.denied } : {}) }) + "\n");
+    writeFileSync(path, JSON.stringify({ planDigest: m.planDigest, ...(m.destructive ? { destructive: true } : {}), ...(m.empty ? { empty: true } : {}), ...(m.denied ? { denied: m.denied } : {}), ...(m.held ? { held: m.held } : {}) }) + "\n");
     return m;
   });
   const overriders = Array.isArray(parsed) ? undefined : (parsed as { overriders?: unknown }).overriders;
@@ -884,6 +918,8 @@ interface HookPlace {
   cwd: string;
   exec: OpWaveExec;
   log: (line: string) => void;
+  /** Where a hook writes a hold on another gate (`CHANT_HOLD`). Default: under the wave's directory. */
+  holdPath?: string;
 }
 
 /**
@@ -903,12 +939,18 @@ function runHookList(
   if (!hooks || hooks.length === 0) return out;
   const { name: specName, op, waveName, k, cwd, exec, log } = at;
   // #3821: a hook that holds the wave on another gate names it in this file.
-  const holdPath = `.chant/op-waves/${specName}/wave-${k}/hold.json`;
+  const holdPath = at.holdPath ?? `.chant/op-waves/${specName}/wave-${k}/hold.json`;
   const env = { CHANT_OP_WAVES: specName, CHANT_WAVE: waveName, CHANT_WAVE_NUMBER: String(k), CHANT_HOOK: moment, CHANT_RUNS: runsPath, CHANT_HOLD: holdPath, ...extraEnv };
   for (const hook of hooks) {
     const name = hook.name ?? (hook.command.join(" ").length > 60 ? `${hook.command.join(" ").slice(0, 57)}...` : hook.command.join(" "));
+    // #4288: a hook with `targets` is for the runs they match. Once for the wave, it runs when one matches or no run is known yet.
+    const mine = opWaveHookRuns(hook, runs);
+    if (hook.targets && (hook.perRun ? mine.length === 0 : mine.length === 0 && runs.length > 0)) {
+      log(`${moment} hook ${name}: no run matches its targets (${hook.targets.join(", ")}), so it did not run`);
+      continue;
+    }
     const calls = hook.perRun
-      ? runs.map((run) => ({
+      ? mine.map((run) => ({
           target: run.target as string | undefined,
           argv: opWaveArgv(hook.command, { op: run.op, wave: waveName, target: run.target, runs: runsPath, ...(run.plan ? { plan: run.plan } : {}) }),
           env: { ...env, CHANT_TARGET: run.target, ...(run.plan ? { CHANT_PLAN: run.plan } : {}) } as Record<string, string>,
@@ -1034,6 +1076,64 @@ async function runHooks(
   return back;
 }
 
+/** The options of {@link runStageHooks} (#4288). */
+export interface RunStageHooksOptions {
+  /** What the hooks belong to: `CHANT_OP_WAVES`, and the `{op}` of a hook that runs once. */
+  name: string;
+  op: string;
+  /** `{wave}` and `CHANT_WAVE`. */
+  wave: string;
+  /** `CHANT_WAVE_NUMBER`. Default 0. */
+  k?: number;
+  /** The runs a `perRun` hook runs for and `targets` match against. */
+  runs: readonly OpWaveHookRun[];
+  /** `{runs}` and `CHANT_RUNS`, relative to `cwd`; the caller writes it. */
+  runsFile: string;
+  /** `CHANT_HOLD`, relative to `cwd`. */
+  holdFile: string;
+  /** Added to every hook's environment. */
+  env?: Record<string, string>;
+  cwd?: string;
+  exec?: OpWaveExec;
+  log?: (line: string) => void;
+}
+
+/** What {@link runStageHooks} gave. */
+export interface StageHooksRun {
+  outcomes: OpWaveHookOutcome[];
+  /** Set when a hook with `onFailure: fail` failed; the hooks after it did not run. */
+  failed?: string;
+  /** The `onFailure: approve` hooks that failed. A hold on another gate counts as one here. */
+  holds: string[];
+}
+
+/**
+ * Run one moment's hooks outside an Op waves job (#4288): the pull-request
+ * jobs, or a product's own stage, with the same `targets`, `perRun`,
+ * `onFailure` and argv filling a wave job uses. A hook that holds on another
+ * gate (`CHANT_HOLD`) is counted as a plain hold; settling that gate is the
+ * caller's.
+ */
+export function runStageHooks(moment: OpWaveHookMoment, hooks: readonly OpWaveHook[] | undefined, options: RunStageHooksOptions): StageHooksRun {
+  const cwd = options.cwd ?? process.cwd();
+  const log = options.log ?? ((line: string) => console.error(line));
+  const place: HookPlace = { name: options.name, op: options.op, waveName: options.wave, k: options.k ?? 0, cwd, exec: options.exec ?? spawnExec, log, holdPath: options.holdFile };
+  const out = runHookList(place, moment, hooks, options.runs, options.runsFile, options.env);
+  return { outcomes: out.outcomes, ...(out.failed ? { failed: out.failed } : {}), holds: [...out.holds, ...out.otherGates.map((g) => `${g.label} (on ${g.request.op ?? options.name} / ${g.request.gate})`)] };
+}
+
+/**
+ * The hooks that run before a job plans (#4288): `before-observe`, then
+ * `before-plan`. A failure or a hold on another gate in the first ends it
+ * there; the holds of both add up.
+ */
+async function runBeforePlanHooks(ctx: WaveContext, hooks: Partial<Record<OpWaveHookMoment, OpWaveHook[]>> | undefined, runs: readonly OpWaveRun[]): Promise<HooksOutcome> {
+  const observe = await runHooks(ctx, "before-observe", hooks?.["before-observe"], runs);
+  if (observe.failed || observe.waitingOn) return observe;
+  const plan = await runHooks(ctx, "before-plan", hooks?.["before-plan"], runs);
+  return { ...plan, holds: [...observe.holds, ...plan.holds] };
+}
+
 /** How many gates one hook call holds a wave on in turn (#3847): the first hold and the holds its approved re-runs ask for. */
 export const OP_WAVE_MAX_CHAINED_HOLDS = 10;
 
@@ -1396,7 +1496,7 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
       log(`${part} of wave ${k} (${wave.name}) holds none of the wave's runs; nothing to apply`);
       return { end: result };
     }
-    const before = await runHooks(ctx, "before-plan", decision.hooks?.["before-plan"], slice);
+    const before = await runBeforePlanHooks(ctx, decision.hooks, slice);
     if (before.failed) return { end: failed(ctx, `a hook before the plan failed, so nothing in ${part} of wave ${k} was planned or applied`) };
     if (before.waitingOn) return { end: await waitOnOther(ctx, decision, before.waitingOn) };
     const { members } = planRuns(ctx, slice);
@@ -1415,6 +1515,12 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
   noteHooksAtBase(ctx, rules);
   // #3836: a point at base that cannot be asked fails the wave; the ledger never stands in for it.
   if (rules.pointRefused) return { end: failed(ctx, `wave ${k} (${wave.name}): ${rules.pointRefused}, so nothing in it was planned or applied`) };
+  // #4290: rules at base that cannot be read fail the wave; fewer approvers never stand in for them.
+  if (rules.quorumRefused) return { end: failed(ctx, `wave ${k} (${wave.name}): ${rules.quorumRefused}, so nothing in it was planned or applied`) };
+  if (rules.quorum && rules.point) return { end: failed(ctx, `wave ${k} (${wave.name}): approvals.quorum and a decision point are both set at ${base.slice(0, 12)}; a gate that asks a point takes its deciders from the point, so nothing in it was planned or applied`) };
+  if (JSON.stringify(spec.approvals?.quorum ?? null) !== JSON.stringify(rules.quorum ?? null)) {
+    log(`wave ${k} (${wave.name}): its approval rules are read at ${base.slice(0, 12)}, and this change's differ; the ones at base hold`);
+  }
   const own = opWavePointAt(spec, wave.name);
   if (JSON.stringify(own) !== JSON.stringify(rules.point)) {
     log(`wave ${k} (${wave.name}): its gate's decision point is read at ${base.slice(0, 12)} (${rules.point?.name ?? "none"}), and this change's differs (${own?.name ?? "none"}); the one at base holds`);
@@ -1445,7 +1551,7 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
     ...(neverOverMcp ? { neverOverMcp: true as const } : {}),
     ...(rules.point ? { point: { ...rules.point } } : {}),
   };
-  const before = await runHooks(ctx, "before-plan", rules.hooks["before-plan"], wave.runs);
+  const before = await runBeforePlanHooks(ctx, rules.hooks, wave.runs);
   if (before.failed) return { end: failed(ctx, `a hook before the plan failed, so nothing in wave ${k} was planned or applied`) };
   if (before.waitingOn) return { end: await decided(ctx, decision, recordPath, before.waitingOn) };
   const { members, pending, overriders, overridersSource, extras, waves: found } = planRuns(ctx, wave.runs, wave.discover === true);
@@ -1519,11 +1625,16 @@ async function decideOpWave(
   const { policy, source, base } = planned.rules;
   decision.digest = digest;
   decision.members = members;
+  // #4290: the rules at base whose targets glob matches one of the wave's runs.
+  const takes = planned.rules.quorum ? quorumRulesFor(planned.rules.quorum, members.map((m) => m.member)) : [];
+  if (takes.length > 0) decision.quorum = takes;
   if (extras) decision.extras = extras;
   if (pending) decision.pending = pending;
   const after = await runHooks(ctx, "after-plan", planned.rules.hooks["after-plan"], wave.runs, planned.planned, digest);
   if (after.failed) return { end: failed(ctx, `a hook after the plan failed, so nothing in wave ${k} was applied`) };
   holds.push(...planned.before, ...after.holds);
+  // #4294: a run the product's policy holds makes the wave wait for a person, as a held hook does.
+  for (const m of members) if (m.held) holds.push(`policy on ${m.member} (${m.held.rules.join(", ")})${m.held.reason ? `: ${m.held.reason}` : ""}`);
   if (holds.length > 0) decision.heldBy = holds;
   if (after.waitingOn) return { end: await decided(ctx, decision, recordPath, after.waitingOn) };
   // #3821: a run the product's policy denied applies only under an override; with none the wave is refused, and no approval is waited for.
@@ -1779,6 +1890,7 @@ function failed(ctx: WaveContext, line: string): RunOpWaveResult {
  */
 async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision): Promise<void> {
   if (decision.point) return settlePointGate(options, ctx, decision, decision.point);
+  if (decision.quorum?.length) return settleQuorumGate(options, ctx, decision, decision.quorum);
   const { spec, k, wave, cwd } = ctx;
   const { gate, digest, approval, base, policy, members } = decision;
   const { ledger, port } = await gatePort(options, cwd, gate, approval, base);
@@ -1833,6 +1945,116 @@ async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision:
   decision.approve = approveCommand(spec.name, gate, undefined, digest, approval === "sealed");
 }
 
+/**
+ * Decide a gate under approval rules (#4290): the rules at base the wave's
+ * targets take, each met by distinct human approvers of the digest. Roles
+ * come from `.chant/trust.json` at base, for an approver a seal proves, or
+ * under `pr-review` the merged pull request's review read from the forge in
+ * this run. That review is written to the ledger once per approving
+ * reviewer, so each counts on their own. `notAuthor` reads the author from
+ * the same pull request; with none, no approver can show they are someone
+ * else and the rule waits.
+ */
+async function settleQuorumGate(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision, rules: GateQuorumRule[]): Promise<void> {
+  const { spec, k, wave, cwd, log } = ctx;
+  const { gate, digest, approval, base, policy, members } = decision;
+  const { ledger, port } = await gatePort(options, cwd, gate, approval, base);
+  const now = options.now ?? new Date().toISOString();
+  const spent: AppliedGateRecord[] | undefined = decision.spend === "base" ? ((await ledger.readApplied?.(spec.name)) ?? []).filter((a) => a.gate === gate) : undefined;
+  const review = await import("./gate-review");
+  const trust = (options.trust ?? ((b) => review.trustPolicyAt(cwd, b)))(base);
+  const label = `wave ${k} (${wave.name})`;
+
+  // The merged pull request: its author for notAuthor, and its review under pr-review.
+  let merged: MergedReview | null = null;
+  let unknown: string | undefined;
+  const asks = approval === "pr-review" || rules.some((r) => r.notAuthor);
+  const head = asks ? (options.head ?? execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8" }).trim()) : "";
+  if (asks) {
+    try {
+      merged = await (options.reviews ?? review.reviewSourceFromEnv()).mergedReview(head);
+      if (!merged) unknown = `no merged pull request produced ${head.slice(0, 12)}`;
+    } catch (err) {
+      unknown = `the forge's review could not be read: ${err instanceof Error ? err.message : String(err)}`;
+    }
+  }
+  if (unknown && rules.some((r) => r.notAuthor)) log(`${label}: ${unknown}, so the change's author is not known`);
+  if (approval === "pr-review" && unknown) decision.review = { reason: unknown };
+
+  let reviewed: { head: string; approvers: string[] } | undefined;
+  if (approval === "pr-review" && merged) {
+    const plans = merged.approvers.length === 0 ? null : await (options.headPlans ?? ((name, h) => readHeadPlans(name, h, cwd)))(spec.name, merged.head);
+    const { reviewApproval } = await import("../gate-decision");
+    const outcome = reviewApproval(merged, plans?.waves.find((w) => w.wave === k)?.digest, digest);
+    decision.review = outcome.review;
+    const reviewSpent = spent !== undefined && isApprovalSpent(spent, { gate, planDigest: digest, review: { head: merged.head } });
+    if (reviewSpent) decision.review = { ...outcome.review, reason: `a wave already applied ${digest} under the review of #${merged.pr} at ${merged.head.slice(0, 12)}, so the review is spent` };
+    if (outcome.approved && !reviewSpent) {
+      reviewed = { head: merged.head, approvers: merged.approvers };
+      // Each approving reviewer once, so the rules count them one by one.
+      const had = (await ledger.read(spec.name)).resolutions.filter((r) => r.gate === gate && r.review?.head === merged!.head && samePlanDigest(r.planDigest, digest));
+      const note = `approved by the review of #${merged.pr} at ${merged.head.slice(0, 12)}: ${merged.approvers.join(", ")}`;
+      for (const who of merged.approvers) {
+        if (had.some((r) => samePrincipal(r.resolvedBy, who))) continue;
+        await ledger.appendResolution?.({
+          op: spec.name,
+          gate,
+          resolvedBy: who,
+          timestamp: now,
+          planDigest: digest,
+          approver: { kind: "human" },
+          gitSha: head,
+          ...(ciRunIdFromEnv() ? { runId: ciRunIdFromEnv()! } : {}),
+          note,
+          ...(merged.url ? { url: merged.url } : {}),
+          review: { pr: merged.pr, head: merged.head, approvers: merged.approvers },
+        });
+      }
+    }
+  }
+
+  const judge = trustQuorumJudge({
+    signers: trust,
+    roles: trust.roles,
+    ...(merged ? { authors: [merged.author] } : {}),
+    ...(reviewed ? { review: reviewed } : {}),
+  });
+  const held = decision.heldBy?.length ? `, held by ${decision.heldBy.join(", ")}` : "";
+  const check = await decideWaveGate(port, {
+    op: spec.name,
+    gate,
+    digest,
+    description: (typeof decision.pending?.description === "string" ? decision.pending.description : undefined) ?? `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}, approval ${approval}${held}`,
+    now,
+    ...(spent ? { spent } : {}),
+    fields: { ...decision.pending, approvalMode: approval },
+    ...(decision.neverOverMcp ? { neverOverMcp: true } : {}),
+    approval: { quorum: rules, mode: "log-only" },
+    judge,
+  });
+  if (check.satisfied) {
+    const by = (check.approvals ?? [check.resolution]).map((r) => r.resolvedBy);
+    decision.status = "approved";
+    decision.via = reviewed && check.resolution.review?.head === reviewed.head ? "pr-review" : "ledger";
+    decision.approvedBy = by.join(", ");
+    decision.approvedAt = check.resolution.timestamp;
+    log(`${label}: the approval rules at ${base.slice(0, 12)} are met by ${by.join(", ")}`);
+    return;
+  }
+  logRefused(log, label, check);
+  decision.pendingFact = check.pending;
+  decision.recorded = check.recorded;
+  decision.waitingSince = check.pending.timestamp;
+  if (check.mismatch) decision.mismatch = check.mismatch;
+  if (check.quorum?.rules) {
+    decision.quorumProgress = check.quorum.rules;
+    for (const p of check.quorum.rules) log(`${label}: approval rule ${quorumRuleLine(p)}`);
+    log(`${label}: the approval rules at ${base.slice(0, 12)} are not met (${quorumWaiting(check.quorum.rules)}), so it waits for more approvals of ${digest}`);
+  }
+  decision.status = "waiting";
+  decision.approve = approveCommand(spec.name, gate, undefined, digest, approval === "sealed" || rules.some(ruleNeedsProof));
+}
+
 /**
  * Decide a gate that asks a decision point (#3836), as an Op gate with a
  * `point` is decided (#3170): ask it with `gate.planDigest` set to the set

package/src/op/op-waves.ts

@@ -43,6 +43,14 @@
  * `chant/lifecycle`, as terragucci's wave gate does, and that approval is
  * spent: the same digest needs a new approval to apply again.
  *
+ * ## Approval rules (#4290)
+ *
+ * With `approvals: { quorum: [...] }` (read at base), a wave takes each rule
+ * whose `targets` glob matches one of its runs' targets and waits until each
+ * is met: `count` distinct people, from `roles` when it names them (granted
+ * in `.chant/trust.json` at base), one of them not the author with
+ * `notAuthor`. See `./gate-quorum.ts`.
+ *
  * ## Wave-level commands and hooks (#3762)
  *
  * A product whose tool plans a whole wave in one call (Terragrunt's `run
@@ -69,6 +77,7 @@
 import type { OpEnvironment, OpSetupStep } from "../lexicon";
 import type { CiRunner } from "../ci-jobs";
 import { gatePointProblems, type GatePoint } from "./gate-point";
+import { quorumProblems, type GateQuorumRule } from "./gate-quorum";
 import { notifyConfigProblem, type NotifyConfig } from "../notify";
 import { WAVE_GATE_NAME_PATTERN, waveGateNameFrom, waveShare } from "../wave-layout";
 
@@ -156,20 +165,30 @@ export interface OpWaveHook {
   onFailure?: OpWaveHookFailure;
   /** Run once per run of the wave, rather than once for the wave. */
   perRun?: boolean;
+  /**
+   * The runs the hook is for (#4288): targets, or patterns where `*` matches
+   * within one `/` segment and `**` across segments, as a job group's `runs`.
+   * A `perRun` hook runs for the matching runs only. A hook that runs once
+   * for the wave runs when any run matches, or when no run is known yet (a
+   * `discover` wave before its plan). Absent: every run.
+   */
+  targets?: string[];
 }
 
 /** The stages a hook runs around. */
-export type OpWaveHookStage = "plan" | "apply" | "gate";
+export type OpWaveHookStage = "observe" | "plan" | "apply" | "gate";
 
 /** When a hook runs. */
-export type OpWaveHookMoment = "before-plan" | "after-plan" | "after-gate" | "before-apply" | "after-apply";
+export type OpWaveHookMoment = "before-observe" | "before-plan" | "after-plan" | "after-gate" | "before-apply" | "after-apply";
 
 /**
- * Every moment, in the order a wave reaches them. `after-gate` (#3821) runs
+ * Every moment, in the order a wave reaches them. `before-observe` (#4288)
+ * runs before anything reads live state: ahead of `before-plan` in every job
+ * that plans, the deciding job's and each share's. `after-gate` (#3821) runs
  * once the gate decided, whatever it decided: approved, let through,
  * waiting, or refused by a policy denial.
  */
-export const OP_WAVE_HOOK_MOMENTS: readonly OpWaveHookMoment[] = ["before-plan", "after-plan", "after-gate", "before-apply", "after-apply"];
+export const OP_WAVE_HOOK_MOMENTS: readonly OpWaveHookMoment[] = ["before-observe", "before-plan", "after-plan", "after-gate", "before-apply", "after-apply"];
 
 /**
  * Who runs the `before.apply` and `after.apply` hooks (#3804). `chant`: the
@@ -183,7 +202,8 @@ export const OP_WAVE_APPLY_HOOKS_RUNNERS: readonly OpWaveApplyHooksRunner[] = ["
 
 /** Stage hooks (#3762), read from the spec at the base commit like the gate policy. */
 export interface OpWaveHooks {
-  before?: { plan?: OpWaveHook[]; apply?: OpWaveHook[] };
+  /** `before.observe` (#4288) runs before anything reads live state, ahead of `before.plan`. */
+  before?: { observe?: OpWaveHook[]; plan?: OpWaveHook[]; apply?: OpWaveHook[] };
   /** `after.gate` (#3821) runs once the gate decided, whatever it decided, with the decision in its environment. */
   after?: { plan?: OpWaveHook[]; gate?: OpWaveHook[]; apply?: OpWaveHook[] };
   /** Who runs the apply-stage hooks (#3804). Default `{ runBy: "chant" }`. A wave's own setting wins over the spec's. */
@@ -456,6 +476,18 @@ export interface OpWavesApprovals {
    * approval of a digest passes that digest as often as it is planned.
    */
   spend?: boolean;
+  /**
+   * Approval rules (#4290): a wave takes each rule whose `targets` glob
+   * matches one of its runs' targets (a rule with no `targets` covers every
+   * wave), and applies once each is met by distinct human approvers of its
+   * set digest. Read at the base commit, with the roles from
+   * `.chant/trust.json` there, so a change cannot loosen the rules its own
+   * wave is judged by. A role, or `notAuthor`, counts only a proven
+   * approver: a seal that verifies against the signers at base, or under
+   * `pr-review` the merged pull request's review. `notAuthor` reads the
+   * author from that pull request. See `./gate-quorum.ts`.
+   */
+  quorum?: GateQuorumRule[];
 }
 
 /** The scheduled resume job of an Op waves pipeline (#3683). */
@@ -543,11 +575,21 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
   }
   if (spec.approvals !== undefined) {
     const a = spec.approvals as unknown;
-    if (a === null || typeof a !== "object" || Array.isArray(a)) throw new Error(`${where}: \`approvals\` must be { "spend"?: true | false }.`);
+    if (a === null || typeof a !== "object" || Array.isArray(a)) throw new Error(`${where}: \`approvals\` must be { "spend"?: true | false, "quorum"?: [...] }.`);
     for (const [key, value] of Object.entries(a as Record<string, unknown>)) {
-      if (key !== "spend") throw new Error(`${where}: approvals.${key} is not a setting; the one there is approvals.spend.`);
+      if (key === "quorum") {
+        // #4290: approval rules, read at base like the policy.
+        if (!Array.isArray(value)) throw new Error(`${where}: approvals.quorum must be a list of rules, each { "targets"?, "count", "roles"?, "notAuthor"? }.`);
+        const problems = quorumProblems(value, "approvals.quorum", { notAuthor: true });
+        if (problems.length > 0) throw new Error(`${where}: ${problems.join("; ")}.`);
+        continue;
+      }
+      if (key !== "spend") throw new Error(`${where}: approvals.${key} is not a setting; the ones there are approvals.spend and approvals.quorum.`);
       if (typeof value !== "boolean") throw new Error(`${where}: approvals.spend must be true or false.`);
     }
+    if ((a as OpWavesApprovals).quorum?.length && (spec.point !== undefined || spec.waves.some((w) => w.point !== undefined))) {
+      throw new Error(`${where}: approvals.quorum and a decision point are both set; a gate that asks a point takes its deciders and quorum from the point, so drop one of them.`);
+    }
   }
   if (spec.gateName !== undefined) {
     if (typeof spec.gateName !== "string" || !spec.gateName.includes("{k}") || /\s/.test(spec.gateName)) {
@@ -720,6 +762,15 @@ export function opWaveRunMatches(pattern: string, target: string): boolean {
   return new RegExp(`^${re}$`).test(target);
 }
 
+/**
+ * The runs of `runs` hook `hook` is for (#4288): those its `targets` match,
+ * or every run when it names none.
+ */
+export function opWaveHookRuns<T extends { target: string }>(hook: Pick<OpWaveHook, "targets">, runs: readonly T[]): T[] {
+  if (!hook.targets) return [...runs];
+  return runs.filter((run) => hook.targets!.some((pattern) => opWaveRunMatches(pattern, run.target)));
+}
+
 /** The runs of `runs` that job group `group` holds (#3914). */
 export function opWaveGroupRuns<T extends { target: string }>(group: Pick<OpWaveJobGroup, "runs">, runs: readonly T[]): T[] {
   return runs.filter((run) => group.runs.some((pattern) => opWaveRunMatches(pattern, run.target)));
@@ -748,7 +799,7 @@ function assertArgv(where: string, field: string, argv: unknown): void {
 export function assertOpWaveHooks(where: string, hooks: OpWaveHooks | undefined): void {
   if (hooks === undefined) return;
   if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks)) {
-    throw new Error(`${where}: \`hooks\` must be { "before"?: { "plan"?, "apply"? }, "after"?: { "plan"?, "apply"? } }.`);
+    throw new Error(`${where}: \`hooks\` must be { "before"?: { "observe"?, "plan"?, "apply"? }, "after"?: { "plan"?, "gate"?, "apply"? } }.`);
   }
   for (const [side, stages] of Object.entries(hooks as Record<string, unknown>)) {
     if (side === "apply") {
@@ -766,7 +817,8 @@ export function assertOpWaveHooks(where: string, hooks: OpWaveHooks | undefined)
     for (const [stage, list] of Object.entries(stages as Record<string, unknown>)) {
       const at = `hooks.${side}.${stage}`;
       if (stage === "gate" && side === "before") throw new Error(`${where}: ${at} is not a moment; a hook runs after the gate (hooks.after.gate), or before the plan or the apply.`);
-      if (stage !== "plan" && stage !== "apply" && stage !== "gate") throw new Error(`${where}: ${at} is not a stage; a hook runs before or after plan or apply, or after the gate.`);
+      if (stage === "observe" && side === "after") throw new Error(`${where}: ${at} is not a moment; a hook runs before the observe (hooks.before.observe), or after the plan, which reads what the observe saw.`);
+      if (stage !== "observe" && stage !== "plan" && stage !== "apply" && stage !== "gate") throw new Error(`${where}: ${at} is not a stage; a hook runs before the observe, before or after plan or apply, or after the gate.`);
       if (!Array.isArray(list)) throw new Error(`${where}: ${at} must be a list of hooks.`);
       list.forEach((hook: OpWaveHook, i: number) => {
         const which = `${at}[${i}]${hook && typeof hook === "object" && typeof hook.name === "string" ? ` (${hook.name})` : ""}`;
@@ -782,10 +834,13 @@ export function assertOpWaveHooks(where: string, hooks: OpWaveHooks | undefined)
           throw new Error(`${where}: ${which} has onFailure "approve", but the gate has already decided when it runs. Use "fail", or hold the wave from an after.plan hook.`);
         }
         if (hook.perRun !== undefined && typeof hook.perRun !== "boolean") throw new Error(`${where}: ${which}.perRun must be true or false.`);
+        if (hook.targets !== undefined && (!Array.isArray(hook.targets) || hook.targets.length === 0 || !hook.targets.every((t) => typeof t === "string" && t !== ""))) {
+          throw new Error(`${where}: ${which}.targets must be a non-empty list of targets or patterns, such as ["prod/*"].`);
+        }
         if (!hook.perRun) {
           const named = hook.command.find((part) => part.includes("{target}") || part.includes("{plan}"));
           if (named) throw new Error(`${where}: ${which} runs once for the wave, so it has no {target} or {plan} ("${named}"). Set "perRun": true, or read the runs from {runs}.`);
-        } else if (side === "before" && stage === "plan" && hook.command.some((part) => part.includes("{plan}"))) {
+        } else if (side === "before" && (stage === "plan" || stage === "observe") && hook.command.some((part) => part.includes("{plan}"))) {
           throw new Error(`${where}: ${which} runs before the plan, so it has no {plan} yet.`);
         }
       });
@@ -793,6 +848,24 @@ export function assertOpWaveHooks(where: string, hooks: OpWaveHooks | undefined)
   }
 }
 
+/**
+ * The moments a pull-request job runs hooks at (#4288): `pr-plan` and
+ * `pr-record` run the observe and plan moments, and `pr-apply` the apply
+ * moments too. The pull request's gate has no `after-gate` moment.
+ */
+export const PR_LOOP_HOOK_MOMENTS: readonly OpWaveHookMoment[] = ["before-observe", "before-plan", "after-plan", "before-apply", "after-apply"];
+
+/**
+ * Refuse `ci.hooks` a pull-request job could not run (#4288): what
+ * {@link assertOpWaveHooks} refuses, plus `after.gate` and `apply.runBy`,
+ * since chant itself runs a pull request's apply.
+ */
+export function assertPrLoopHooks(where: string, hooks: OpWaveHooks | undefined): void {
+  assertOpWaveHooks(where, hooks);
+  if (hooks?.after?.gate !== undefined) throw new Error(`${where}: hooks.after.gate runs in an Op waves job only; a pull-request job runs hooks before the observe, before and after the plan, and before and after the apply.`);
+  if (hooks?.apply !== undefined) throw new Error(`${where}: hooks.apply.runBy is for an Op waves spec; chant runs a pull request's apply, so it runs the apply-stage hooks itself.`);
+}
+
 /** The hooks of each moment for wave `name`: the spec's, then the wave's own. */
 export function opWaveHooksAt(spec: Pick<OpWavesSpec, "hooks" | "waves">, name: string): Record<OpWaveHookMoment, OpWaveHook[]> {
   const wave = spec.waves.find((w) => w.name === name);