@intentius/chant 0.124.40 → 0.124.42

package/src/op/gate.ts

@@ -51,6 +51,10 @@ 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 {
+  quorumNeed, quorumRuleProgress, quorumRules, ruleNeedsProof, samePrincipal, trustQuorumJudge, UNPROVEN_JUDGE,
+  type GateQuorumJudge, type GateQuorumRuleProgress,
+} from "./gate-quorum";
 import { pushLifecycleReport, readBlobBySha, readBlobFromPath, readPathSha, requireLifecycleLedger, writeBlobToPath, RefCASConflictError } from "../lifecycle/git";
 import { parseDuration } from "./duration";
 import { ciRunIdFromEnv, resolveGateRunLocator } from "./gate-run-locator";
@@ -99,6 +103,14 @@ export interface GateLedgerPort {
    * Absent, every approval is judged as before.
    */
   approvalRule?(gate: string, at?: { base?: string }): Promise<GateApprovalRule | null>;
+  /**
+   * The judge a gate's approval rules are met by (#4290): which approvals
+   * prove their approver (a seal verified against the signers at base) and
+   * the roles `.chant/trust.json` at base gives them. `at.base` as for
+   * {@link GateLedgerPort.approvalRule}. Absent, no approval proves anyone,
+   * so a rule naming roles is never met.
+   */
+  quorumJudge?(gate: string, at?: { base?: string }): Promise<GateQuorumJudge>;
   /** The approvals a wave applied under (#3784), from `_gates/<op>/applied.jsonl`. Absent on a port that never spends approvals. */
   readApplied?(op: string): Promise<AppliedGateRecord[]>;
   /** Record that a wave is about to apply under an approval (#3784), which spends it. */
@@ -152,6 +164,12 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
       const { gateAdmission } = await import("../workspace/identity");
       return gateAdmission(opts?.cwd ?? process.cwd(), gate, at?.base);
     },
+    async quorumJudge(_gate, at) {
+      // #4290: the signers and role grants at base, never the approver's claim.
+      const { scopeSource } = await import("../workspace/write-scope");
+      const { policy } = scopeSource(opts?.cwd ?? process.cwd(), at?.base);
+      return trustQuorumJudge({ signers: policy, roles: policy.roles });
+    },
     async appendResolution(input) {
       const { record } = await appendGateResolution(input, opts);
       return { record, ...(await pushLifecycleReport(opts)) };
@@ -293,6 +311,13 @@ export interface GateCheckInput {
    * it so `chant approve` can evaluate the policy.
    */
   approval?: ResolvedGateApproval;
+  /**
+   * Judges approvals for `approval.quorum`'s rules (#4290). Absent, the
+   * port's {@link GateLedgerPort.quorumJudge} at its default base, else no
+   * approval proves anyone. A wave passes one that knows the change's author
+   * and the merged pull request's review.
+   */
+  judge?: GateQuorumJudge;
   /** ISO-8601 "now" — supplied by the caller, so the decision is deterministic under test. */
   now?: string;
   /**
@@ -399,6 +424,8 @@ export interface GateQuorumProgress {
   /** Approvers whose approval counts toward the quorum, oldest first. */
   approvers: string[];
   need: number;
+  /** Where each approval rule the gate takes stands (#4290). Absent when it takes none. */
+  rules?: GateQuorumRuleProgress[];
 }
 
 /** Either the gate is answered, or it is a standing fact. */
@@ -464,8 +491,12 @@ export function approverOf(record: GateResolutionRecord): GateApprover {
 export interface GateTally {
   /** Distinct human approvers of this plan who count toward the quorum, one record each (their newest), oldest first. */
   counted: GateResolutionRecord[];
-  /** The quorum's count, 1 when the gate declares none. */
+  /** The most approvers a rule needs, 1 when the gate declares none. */
   need: number;
+  /** Every rule is met (#4290); with no rules, one human approved. */
+  met: boolean;
+  /** Where each rule stands (#4290). Absent when the gate takes no rule. */
+  rules?: GateQuorumRuleProgress[];
   /** The newest approval whose recorded permit passes the gate on its own. Only in `enforce` mode, only for a permit recorded under `enforce`, and only under the gate's current policy version and resolved context. */
   permit?: GateResolutionRecord;
   /** The newest approval of this gate for a different plan, when the gate binds one. */
@@ -483,8 +514,12 @@ export interface GateTally {
  * pending fact re-recorded for a changed mode or context keeps a partly
  * filled quorum (#3206). It defaults to `sinceIso`.
  *
- * Of those, only a human's counts toward the quorum, once per `resolvedBy`,
- * and only with one of the quorum's roles when it names any. An agent counts
+ * Of those, only a human's counts toward the quorum, once per `resolvedBy`.
+ * The quorum is a list of rules (#4290, `./gate-quorum.ts`), already the ones
+ * the gate takes: each is met by distinct humans, counting toward `roles`
+ * only an approver `judge` proves and gives one of them (roles from
+ * `.chant/trust.json` at base, never the approver's claim), and the gate
+ * passes when every rule is met. With no rule, one human passes it. An agent counts
  * only through a recorded `allow` in `enforce` mode, evaluated under the
  * policy version the gate declares now, recorded while the gate was in
  * `enforce` (#2512), and evaluated under the context the gate resolves now
@@ -499,14 +534,16 @@ export function tallyGateApprovals(
   planDigest: string | undefined,
   approval: ResolvedGateApproval,
   humansSinceIso: string = sinceIso,
+  judge: GateQuorumJudge = UNPROVEN_JUDGE,
 ): GateTally {
   const since = new Date(sinceIso).getTime();
   const humansSince = Math.min(since, new Date(humansSinceIso).getTime());
   const at = (r: GateResolutionRecord) => new Date(r.timestamp).getTime();
-  const roles = approval.quorum?.roles;
+  const rules = quorumRules(approval.quorum);
   const context = gateContextDigest(approval.context);
 
-  const byActor = new Map<string, GateResolutionRecord>();
+  // Each human once: their newest approval, or their newest proven one when they have one.
+  const byActor = new Map<string, { record: GateResolutionRecord; proven: boolean }>();
   let permit: GateResolutionRecord | undefined;
   let mismatched: GateResolutionRecord | undefined;
   for (const r of records) {
@@ -534,20 +571,20 @@ export function tallyGateApprovals(
       permit = r;
     }
 
-    const approver = approverOf(r);
-    if (approver.kind !== "human") continue;
-    if (roles && !(approver.roles ?? []).some((role) => roles.includes(role))) continue;
-    const prior = byActor.get(r.resolvedBy);
-    if (!prior || at(r) >= at(prior)) byActor.set(r.resolvedBy, r);
+    if (approverOf(r).kind !== "human") continue;
+    const key = r.resolvedBy.normalize("NFKC").trim().toLowerCase();
+    const proven = rules.some(ruleNeedsProof) && judge(r).proven;
+    const prior = byActor.get(key);
+    if (!prior || (proven && !prior.proven) || (proven === prior.proven && at(r) >= at(prior.record))) byActor.set(key, { record: r, proven });
   }
 
-  const counted = [...byActor.values()].sort((a, b) => at(a) - at(b));
-  return {
-    counted,
-    need: approval.quorum?.count ?? 1,
-    ...(permit ? { permit } : {}),
-    ...(mismatched ? { mismatched } : {}),
-  };
+  const humans = [...byActor.values()].map((v) => v.record).sort((a, b) => at(a) - at(b));
+  const extra = { ...(permit ? { permit } : {}), ...(mismatched ? { mismatched } : {}) };
+  if (rules.length === 0) return { counted: humans, need: 1, met: humans.length >= 1, ...extra };
+  const approvers = humans.map((r) => ({ who: r.resolvedBy, at: r.timestamp, judged: judge(r) }));
+  const progress = rules.map((rule) => quorumRuleProgress(rule, approvers));
+  const counted = humans.filter((r) => progress.some((p) => p.approvers.some((a) => samePrincipal(a, r.resolvedBy))));
+  return { counted, need: quorumNeed(rules), met: progress.every((p) => p.met), rules: progress, ...extra };
 }
 
 /**
@@ -807,11 +844,15 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
       standing.approval?.policy?.version === input.approval.policy?.version
         ? humanQuorumSince(pending, standing)
         : since;
-    const tally = tallyGateApprovals(resolutions, input.gate, since, input.planDigest, input.approval, humansSince);
+    // #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;
+    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 };
     }
-    if (tally.counted.length >= tally.need) {
+    if (tally.met) {
       return {
         satisfied: true,
         resolution: tally.counted[tally.counted.length - 1]!,
@@ -820,19 +861,19 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
       };
     }
     mismatched = tally.mismatched;
-    quorum = { approvers: tally.counted.map((r) => r.resolvedBy), need: tally.need };
+    quorum = { approvers: tally.counted.map((r) => r.resolvedBy), need: tally.need, ...(tally.rules ? { rules: tally.rules } : {}) };
     // #3949: old and new approvals add up toward one quorum, each approver once.
     const counted = new Set(tally.counted.map((r) => r.resolvedBy));
     const extra = fromAliases.filter((r) => !counted.has(r.resolvedBy));
     if (extra.length > 0) {
       const asCarried = new Map(extra.map((r) => [{ version: 1, ...carriedApproval(r, input.op, input.gate, now) } as GateResolutionRecord, r]));
-      const combined = tallyGateApprovals([...resolutions, ...asCarried.keys()], input.gate, since, input.planDigest, input.approval, humansSince);
-      if (combined.counted.length >= combined.need) {
+      const combined = tallyGateApprovals([...resolutions, ...asCarried.keys()], input.gate, since, input.planDigest, input.approval, humansSince, judge);
+      if (combined.met) {
         const written = await carry(combined.counted.filter((r) => asCarried.has(r)).map((r) => asCarried.get(r)!));
         const approvals = [...combined.counted.filter((r) => !asCarried.has(r)), ...written];
         return { satisfied: true, resolution: written[written.length - 1]!, via: "alias", approvals, carried: written };
       }
-      quorum = { approvers: combined.counted.map((r) => r.resolvedBy), need: combined.need };
+      quorum = { approvers: combined.counted.map((r) => r.resolvedBy), need: combined.need, ...(combined.rules ? { rules: combined.rules } : {}) };
     }
   } else {
     const found = latestResolutionForPlan(resolutions, input.gate, since, input.planDigest);

package/src/op/index.ts

@@ -1,5 +1,5 @@
 export { Op, phase, activity, gate, effect, build, kubectlApply, helmInstall, helmInstallPinned, waitForStack, waitForReady,
-         gitlabPipeline, lifecycleSnapshot, shell, sourceArchive, releasePlan, releaseRecord, composeChangeSet, lifecyclePlanChangeSet, readChangeSetPart, releaseRollbackPlan, releaseRollbackRecord, decide, ensureSecret, teardown, envTeardown, k3dUp, k3dDown,
+         gitlabPipeline, lifecycleSnapshot, shell, sourceArchive, releasePlan, releaseRecord, composeChangeSet, lifecyclePlanChangeSet, readChangeSetPart, reviewAgent, releaseRollbackPlan, releaseRollbackRecord, decide, ensureSecret, teardown, envTeardown, k3dUp, k3dDown,
          k3sInstall, k3sUninstall, flociUp, flociDown,
          flociAzUp, flociAzDown, flociGcpUp, flociGcpDown, httpCheck,
          azGroupEnsure, azGroupDelete, azApply, azDelete, awsApply, awsDelete, gcpApply, gcpDelete, policyGate,
@@ -57,10 +57,13 @@ export {
   OP_WAVE_DEFAULT_GATE_NAME,
   OP_WAVE_GATE_POLICIES,
   OP_WAVE_HOOK_MOMENTS,
+  PR_LOOP_HOOK_MOMENTS,
   assertOpWaveHooks,
   assertOpWavesSpec,
+  assertPrLoopHooks,
   opWaveApplyHooksRunBy,
   opWaveGateName,
+  opWaveHookRuns,
   opWaveHooksAt,
   opWaveJobs,
   opWaveRecordPath,
@@ -71,6 +74,7 @@ export {
   OP_WAVE_APPLY_OUTCOMES,
   OP_WAVE_MAX_REPLANS,
   opWaveHooksAtBase,
+  runStageHooks,
   opWaveNeedsApproval,
   opWavePlansPath,
   opWaveRunsPath,
@@ -102,6 +106,8 @@ export type {
   OpWaveShowAtBase,
   RecordHeadPlansOptions,
   RunOpWaveApplyHooksOptions,
+  RunStageHooksOptions,
+  StageHooksRun,
   RunOpWaveOptions,
   RunOpWaveResult,
 } from "./op-waves-run";
@@ -130,6 +136,12 @@ export type {
   GateApproval, GateApprovalMode, GateApprover, GateContextValue, GatePolicyAnswer, GatePolicyDecision,
   GatePolicyEvaluator, GatePolicyRef, GatePolicyRequest, GateQuorum, ResolvedGateApproval,
 } from "./gate-approval";
+export {
+  quorumRules, quorumRulesFor, quorumNeed, quorumProblems, quorumRuleProgress, quorumRuleLine, quorumWaiting, rolesOf, trustQuorumJudge, UNPROVEN_JUDGE,
+} from "./gate-quorum";
+export type {
+  GateQuorumRule, GateQuorumSpec, GateQuorumJudge, GateQuorumRuleProgress, QuorumJudgement, QuorumApprover, TrustQuorumInput,
+} from "./gate-quorum";
 export {
   gatePlanSummary, gatePlanSummaryOfResult, changeSetOfResult, GATE_PLAN_CONTEXT_KEY, GATE_PLAN_ADDRESS_LIMIT,
 } from "./gate-plan-context";

package/src/op/local-executor.ts

@@ -41,6 +41,7 @@ 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 { 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";
@@ -732,6 +733,7 @@ function gateFn(step: GateStep): string {
 function resolveGateApproval(
   step: GateStep,
   resultsById: ReadonlyMap<string, unknown>,
+  env?: string,
 ): ResolvedGateApproval | undefined {
   const authored = step.approval;
   if (!authored) return undefined;
@@ -750,8 +752,13 @@ function resolveGateApproval(
     const summary = gatePlanSummaryOfResult(resultsById.get(step.plan.step));
     if (summary) context = { ...(context ?? {}), [GATE_PLAN_CONTEXT_KEY]: summary };
   }
+  // #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] : []) : [];
   return {
-    ...(authored.quorum ? { quorum: authored.quorum } : {}),
+    ...(single ? { quorum: authored.quorum } : rules.length > 0 ? { quorum: rules } : {}),
     ...(authored.policy ? { policy: authored.policy } : {}),
     mode: authored.mode ?? "log-only",
     ...(context ? { context } : {}),
@@ -779,7 +786,7 @@ 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);
+  const approval = resolveGateApproval(step, resultsById, gates.env);
   // #3947: a gate that resumes stores the outputs the steps after it read.
   const resumeAt = gates.resume?.gates.get(step);
   let checkpoint: GateCheckpoint | undefined;

package/src/op/op-waves-hook-targets.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Hook `targets` and the `before.observe` moment (#4288), in an Op waves
+ * job and through `runStageHooks`.
+ */
+import { describe, expect, test } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { assertOpWaveHooks, assertPrLoopHooks, opWaveHookRuns, opWaveHooksAt, OP_WAVE_HOOK_MOMENTS, type OpWavesSpec } from "./op-waves";
+import { runOpWave, runStageHooks, type OpWaveExec, type OpWaveShowAtBase } from "./op-waves-run";
+import { memoryGateLedgerPort } from "./gate";
+
+const digest = (n: string) => `sha256:${n.repeat(64)}`;
+
+describe("hook targets and before.observe in the spec (#4288)", () => {
+  test("before.observe is the first moment, and opWaveHooksAt reads it", () => {
+    expect(OP_WAVE_HOOK_MOMENTS[0]).toBe("before-observe");
+    const hooks = opWaveHooksAt({ hooks: { before: { observe: [{ command: ["init"] }] } }, waves: [{ name: "prod", runs: [] }] }, "prod");
+    expect(hooks["before-observe"]).toEqual([{ command: ["init"] }]);
+  });
+
+  test("the spec refuses after.observe, {plan} before the observe and targets that are not a list of names", () => {
+    expect(() => assertOpWaveHooks("w", { after: { observe: [{ command: ["x"] }] } } as never)).toThrow(/hooks.after.observe is not a moment/);
+    expect(() => assertOpWaveHooks("w", { before: { observe: [{ command: ["x", "{plan}"], perRun: true }] } })).toThrow(/no \{plan\} yet/);
+    expect(() => assertOpWaveHooks("w", { before: { plan: [{ command: ["x"], targets: [] }] } })).toThrow(/targets must be a non-empty list/);
+    expect(() => assertOpWaveHooks("w", { before: { plan: [{ command: ["x"], targets: ["prod/*", 3] as never }] } })).toThrow(/targets must be a non-empty list/);
+    expect(() => assertOpWaveHooks("w", { before: { observe: [{ command: ["x"], targets: ["prod/**"], onFailure: "approve" }] } })).not.toThrow();
+  });
+
+  test("a pull-request job refuses after.gate and apply.runBy", () => {
+    expect(() => assertPrLoopHooks("ci.hooks", { after: { gate: [{ command: ["x"] }] } })).toThrow(/after.gate runs in an Op waves job only/);
+    expect(() => assertPrLoopHooks("ci.hooks", { apply: { runBy: "apply" } })).toThrow(/runBy is for an Op waves spec/);
+    expect(() => assertPrLoopHooks("ci.hooks", { before: { observe: [{ command: ["x"] }], apply: [{ command: ["y"] }] } })).not.toThrow();
+  });
+
+  test("targets match a run by name or by a pattern, as a job group's runs do", () => {
+    const runs = [{ target: "prod/eu" }, { target: "prod/us/east" }, { target: "dev" }];
+    expect(opWaveHookRuns({}, runs).map((r) => r.target)).toEqual(["prod/eu", "prod/us/east", "dev"]);
+    expect(opWaveHookRuns({ targets: ["prod/*"] }, runs).map((r) => r.target)).toEqual(["prod/eu"]);
+    expect(opWaveHookRuns({ targets: ["prod/**", "dev"] }, runs).map((r) => r.target)).toEqual(["prod/eu", "prod/us/east", "dev"]);
+  });
+});
+
+describe("runOpWave with targets and before.observe (#4288)", () => {
+  const spec: OpWavesSpec = {
+    name: "roots",
+    op: "tf",
+    plan: ["tool", "plan", "{target}", "{plan}"],
+    apply: ["tool", "apply", "{target}", "{plan}"],
+    hooks: {
+      before: {
+        observe: [{ name: "init", command: ["hook", "init", "{target}"], perRun: true, targets: ["eu/*"] }],
+        plan: [{ name: "us-only", command: ["hook", "us", "{runs}"], targets: ["us/*"] }],
+      },
+      after: { plan: [{ name: "eu-check", command: ["hook", "eu-check", "{runs}"], targets: ["eu/*"] }] },
+    },
+    waves: [{ name: "prod", runs: [{ target: "eu/a" }, { target: "eu/b" }, { target: "asia/c" }], gate: "never" }],
+  };
+
+  function harness(fails: string[] = []) {
+    const cwd = mkdtempSync(join(tmpdir(), "op-waves-targets-"));
+    const calls: Array<{ argv: string; env?: Record<string, string> }> = [];
+    const exec: OpWaveExec = (argv, dir, env) => {
+      calls.push({ argv: argv.join(" "), ...(env ? { env } : {}) });
+      if (argv[1] === "plan") writeFileSync(join(dir, argv[3]!), JSON.stringify({ planDigest: digest(argv[2]!.endsWith("a") ? "1" : "2") }));
+      return fails.some((f) => argv.join(" ").startsWith(f)) ? 1 : 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(spec) });
+    return { cwd, calls, exec, show, argv: () => calls.map((c) => c.argv), done: () => rmSync(cwd, { recursive: true, force: true }) };
+  }
+
+  test("before-observe runs ahead of before-plan, each hook only for the runs its targets match", async () => {
+    const h = harness();
+    const logs: string[] = [];
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort(), log: (l) => logs.push(l) });
+    expect(result.exitCode).toBe(0);
+    expect(h.argv().filter((c) => c.startsWith("hook") || c.startsWith("tool plan"))).toEqual([
+      "hook init eu/a",
+      "hook init eu/b",
+      "tool plan eu/a .chant/op-waves/roots/wave-1/eu_a.plan.json",
+      "tool plan eu/b .chant/op-waves/roots/wave-1/eu_b.plan.json",
+      "tool plan asia/c .chant/op-waves/roots/wave-1/asia_c.plan.json",
+      "hook eu-check .chant/op-waves/roots/wave-1/runs.json",
+    ]);
+    expect(h.calls[0]!.env).toMatchObject({ CHANT_HOOK: "before-observe", CHANT_TARGET: "eu/a" });
+    expect(logs).toContain("before-plan hook us-only: no run matches its targets (us/*), so it did not run");
+    expect(result.hooks.map((o) => `${o.moment} ${o.name}${o.target ? ` ${o.target}` : ""} ${o.outcome}`)).toEqual([
+      "before-observe init eu/a passed",
+      "before-observe init eu/b passed",
+      "after-plan eu-check passed",
+    ]);
+    h.done();
+  });
+
+  test("a failed before-observe hook stops the wave before anything plans", async () => {
+    const h = harness(["hook init eu/b"]);
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort(), log: () => {} });
+    expect(result.exitCode).toBe(1);
+    expect(h.argv().some((c) => c.startsWith("tool"))).toBe(false);
+    h.done();
+  });
+});
+
+describe("runStageHooks (#4288)", () => {
+  test("runs one moment's hooks for the runs given, with targets, and counts an approve failure as a hold", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "stage-hooks-"));
+    const calls: string[] = [];
+    const exec: OpWaveExec = (argv) => {
+      calls.push(argv.join(" "));
+      return argv[1] === "gate" ? 1 : 0;
+    };
+    const ran = runStageHooks(
+      "before-plan",
+      [
+        { name: "each", command: ["hook", "each", "{target}", "{op}"], perRun: true, targets: ["api"] },
+        { name: "gate", command: ["hook", "gate", "{wave}"], onFailure: "approve" },
+      ],
+      { name: "pr-7", op: "pr-7", wave: "prod", runs: [{ target: "api", op: "pr-7" }, { target: "web", op: "pr-7" }], runsFile: "runs.json", holdFile: "hold.json", cwd, exec, log: () => {} },
+    );
+    expect(calls).toEqual(["hook each api pr-7", "hook gate prod"]);
+    expect(ran.failed).toBeUndefined();
+    expect(ran.holds).toEqual(["before-plan hook gate"]);
+    expect(ran.outcomes.map((o) => o.outcome)).toEqual(["passed", "held"]);
+    rmSync(cwd, { recursive: true, force: true });
+  });
+});

package/src/op/op-waves-policy-hold.test.ts

@@ -0,0 +1,66 @@
+/**
+ * A plan the product's policy holds (#4294): the wave waits for a person's
+ * approval of its set digest whatever its gate policy says, and applies
+ * once one stands.
+ */
+
+import { describe, expect, test } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { OpWavesSpec } from "./op-waves";
+import { runOpWave, type OpWaveExec, type OpWaveShowAtBase } from "./op-waves-run";
+import { memoryGateLedgerPort } from "./gate";
+import { waveSetDigest } from "../gated-waves";
+
+const spec: OpWavesSpec = {
+  name: "roots",
+  op: "tf",
+  plan: ["tool", "plan", "{target}", "--out", "{plan}"],
+  apply: ["tool", "apply", "{target}", "--plan", "{plan}"],
+  waves: [{ name: "dev", runs: [{ target: "vpc" }], gate: "never" }],
+};
+
+const digest = (n: string) => `sha256:${n.repeat(64)}`;
+
+function harness(plan: Record<string, unknown>) {
+  const cwd = mkdtempSync(join(tmpdir(), "op-waves-hold-"));
+  const calls: string[] = [];
+  const exec: OpWaveExec = (argv, dir) => {
+    calls.push(argv.join(" "));
+    if (argv[1] === "plan") writeFileSync(join(dir, argv[4]!), JSON.stringify(plan));
+    return 0;
+  };
+  const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(spec) });
+  return { cwd, calls, exec, show, done: () => rmSync(cwd, { recursive: true, force: true }) };
+}
+
+describe("a policy hold on an Op waves plan (#4294)", () => {
+  test("a held run makes a gate: never wave wait, and an approval of its digest lets it apply", async () => {
+    const h = harness({ planDigest: digest("1"), held: { rules: ["main.hold_iam", "main.hold_iam"], reason: "an IAM change" } });
+    const waiting = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(waiting.exitCode).toBe(3);
+    expect(waiting.decision).toMatchObject({ status: "waiting", policy: "never", heldBy: ["policy on vpc (main.hold_iam): an IAM change"] });
+    expect(waiting.decision!.members[0]).toMatchObject({ member: "vpc", held: { rules: ["main.hold_iam"] } });
+    expect(h.calls.some((c) => c.startsWith("tool apply"))).toBe(false);
+
+    const set = waveSetDigest([{ member: "vpc", planDigest: digest("1") }]);
+    const gates = memoryGateLedgerPort({ resolutions: [{ version: 1, op: "roots", gate: "roots-wave-1", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: set }] });
+    const approved = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates });
+    expect(approved).toMatchObject({ exitCode: 0, applied: ["vpc"], decision: { status: "approved", approvedBy: "alice" } });
+    h.done();
+  });
+
+  test("a run with no hold under gate: never needs no approval", async () => {
+    const h = harness({ planDigest: digest("2") });
+    const free = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(free).toMatchObject({ exitCode: 0, applied: ["vpc"], decision: { status: "not-required" } });
+    h.done();
+  });
+
+  test("a hold that names no rule is refused", async () => {
+    const h = harness({ planDigest: digest("3"), held: { rules: [] } });
+    await expect(runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() })).rejects.toThrow(/a hold is \{ "rules"/);
+    h.done();
+  });
+});

package/src/op/op-waves-quorum.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { assertOpWavesSpec, type OpWavesSpec } from "./op-waves";
+import { runOpWave, type OpWaveExec, type OpWaveShowAtBase } from "./op-waves-run";
+import { memoryGateLedgerPort } from "./gate";
+import { waveSetDigest } from "../gated-waves";
+import type { TrustPolicy } from "../workspace/trust/policy";
+import type { MergedReview, ReviewSource } from "./gate-review";
+
+const digest = (n: string) => `sha256:${n.repeat(64)}`;
+
+const spec: OpWavesSpec = {
+  name: "migrations",
+  op: "migrate",
+  plan: ["tool", "plan", "{target}", "--out", "{plan}"],
+  apply: ["tool", "apply", "{target}", "--plan", "{plan}"],
+  waves: [{ name: "prod", runs: [{ target: "prod-eu" }, { target: "prod-us" }] }],
+};
+const set = waveSetDigest([
+  { member: "prod-eu", planDigest: digest("e") },
+  { member: "prod-us", planDigest: digest("u") },
+]);
+
+function harness(atBase: OpWavesSpec) {
+  const cwd = mkdtempSync(join(tmpdir(), "op-waves-quorum-"));
+  const calls: string[] = [];
+  const exec: OpWaveExec = (argv, dir) => {
+    calls.push(argv.join(" "));
+    if (argv[1] === "plan") writeFileSync(join(dir, argv[4]!), JSON.stringify({ planDigest: digest(argv[2] === "prod-eu" ? "e" : "u") }));
+    return 0;
+  };
+  const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(atBase) });
+  return { cwd, exec, show, applies: () => calls.filter((c) => c.startsWith("tool apply")).length, done: () => rmSync(cwd, { recursive: true, force: true }) };
+}
+
+const trust = (roles: Record<string, string[]>): (() => TrustPolicy) => () =>
+  ({ base: "b".repeat(40), signersPath: ".chant/allowed_signers", active: false, signers: [], excluded: [], roles, adopted: [], runners: [], excludedRunners: [], admitted: {}, problems: [] }) as TrustPolicy;
+
+const reviews = (merged: MergedReview | null): ReviewSource => ({ kind: "github", mergedReview: async () => merged });
+const approval = (who: string, at: string) => ({ version: 1 as const, op: "migrations", gate: "migrations-wave-1", resolvedBy: who, timestamp: at, planDigest: set });
+
+describe("Op waves approval rules (#4290)", () => {
+  test("the spec checks approvals.quorum, and refuses it beside a decision point", () => {
+    expect(() => assertOpWavesSpec({ ...spec, approvals: { quorum: [{ targets: ["prod-*"], count: 2, roles: ["platform"], notAuthor: true }] } })).not.toThrow();
+    expect(() => assertOpWavesSpec({ ...spec, approvals: { quorum: [{ count: 0 }] } })).toThrow(/approvals.quorum\[0\].count/);
+    expect(() => assertOpWavesSpec({ ...spec, approvals: { quorum: { count: 1 } } } as unknown as OpWavesSpec)).toThrow(/must be a list of rules/);
+    expect(() => assertOpWavesSpec({ ...spec, point: "ship", approvals: { quorum: [{ count: 1 }] } })).toThrow(/both set/);
+  });
+
+  test("a rule at base whose glob matches a run holds the wave until two people approve", async () => {
+    const atBase: OpWavesSpec = { ...spec, approvals: { quorum: [{ targets: ["prod-*"], count: 2 }, { targets: ["dev"], count: 5 }] } };
+    const h = harness(atBase);
+    const gates = memoryGateLedgerPort({ resolutions: [approval("alice", "2026-10-22T01:00:00Z")] });
+    const logs: string[] = [];
+    // The change drops the rule; the one at base holds.
+    const one = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-22T02:00:00Z", log: (l) => logs.push(l) });
+    expect(one.exitCode).toBe(3);
+    expect(one.decision?.quorum).toEqual([{ targets: ["prod-*"], count: 2 }]);
+    expect(one.decision?.quorumProgress?.[0]).toMatchObject({ approvers: ["alice"], met: false });
+    expect(logs.some((l) => /the ones at base hold/.test(l))).toBe(true);
+    // Approvals made while the wave waits count, each person once.
+    const two = memoryGateLedgerPort({ resolutions: [approval("alice", "2026-10-22T02:30:00Z"), approval("alice", "2026-10-22T02:45:00Z"), approval("bob", "2026-10-22T03:00:00Z")], pending: gates.appended });
+    const done = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: two, now: "2026-10-22T04:00:00Z" });
+    expect(done.exitCode).toBe(0);
+    expect(done.decision?.approvedBy).toBe("alice, bob");
+    expect(h.applies()).toBe(2);
+    h.done();
+  });
+
+  test("a claimed role never counts; a role from trust.json at base counts for a reviewer of the merged pull request", async () => {
+    const atBase: OpWavesSpec = { ...spec, waves: [{ ...spec.waves[0]!, approval: "pr-review" }], approvals: { quorum: [{ count: 1, roles: ["platform"], notAuthor: true }] } };
+    const h = harness(atBase);
+    const claimed = memoryGateLedgerPort({ resolutions: [{ ...approval("github:carol", "2026-10-22T01:00:00Z"), approver: { kind: "human", roles: ["platform"] } }] });
+    const merged: MergedReview = { pr: 7, head: "h".repeat(40), author: "github:dana", approvers: ["github:alice"], refused: [] };
+    const headPlans = async () => ({ version: 1 as const, name: "migrations", head: merged.head, timestamp: "2026-10-22T00:00:00Z", waves: [{ wave: 1, name: "prod", digest: set }] });
+    const base = { spec: atBase, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, head: "m".repeat(40), headPlans, now: "2026-10-22T02:00:00Z" };
+    // carol claims the role and is not proven; nobody reviewed.
+    const waiting = await runOpWave({ ...base, gates: claimed, reviews: reviews({ ...merged, approvers: [] }), trust: trust({ platform: ["github:alice", "github:carol"] }) });
+    expect(waiting.exitCode).toBe(3);
+    // alice reviewed and holds the role at base; dana wrote the change.
+    const gates = memoryGateLedgerPort();
+    const passed = await runOpWave({ ...base, gates, reviews: reviews(merged), trust: trust({ platform: ["github:alice"] }) });
+    expect(passed.exitCode).toBe(0);
+    expect(passed.decision).toMatchObject({ via: "pr-review", approvedBy: "github:alice" });
+    expect(gates.resolved.map((r) => r.resolvedBy)).toEqual(["github:alice"]);
+    // The author reviewing their own change never meets notAuthor.
+    const own = await runOpWave({ ...base, gates: memoryGateLedgerPort(), reviews: reviews({ ...merged, author: "github:alice" }), trust: trust({ platform: ["github:alice"] }) });
+    expect(own.exitCode).toBe(3);
+    h.done();
+  });
+
+  test("rules at base that cannot be read fail the wave", async () => {
+    const h = harness({ ...spec, approvals: { quorum: [{ count: 0 }] } });
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort() });
+    expect(result.exitCode).toBe(1);
+    expect(h.applies()).toBe(0);
+    h.done();
+  });
+});