@intentius/chant 0.124.40 → 0.124.42

package/src/workspace/declaration.test.ts

@@ -436,6 +436,15 @@ describe("retention (#4036)", () => {
   });
 });
 
+describe("ci.locks (#4293)", () => {
+  test("apply or plan is read; absent leaves it out; anything else is declaration-invalid", () => {
+    expect(parse(base([], { ci: { locks: "plan" } })).ci).toEqual({ green: null, locks: "plan", reportUrl: null });
+    expect(parse(base([], { ci: { locks: "apply" } })).ci?.locks).toBe("apply");
+    expect(parse(base([], { ci: {} })).ci?.locks).toBeUndefined();
+    for (const locks of ["merge", true, ""]) expect(failure(base([], { ci: { locks } })).code).toBe("declaration-invalid");
+  });
+});
+
 describe("ci.reportUrl (#4160)", () => {
   test("an s3:// or file:// URL is read without its trailing slash, beside green or alone, and is null when absent", () => {
     expect(parse(base([])).ci).toBeNull();
@@ -489,3 +498,70 @@ describe("metrics (#4039)", () => {
     }
   });
 });
+
+describe("ci.branches and ci.labels (#4292)", () => {
+  const members = [
+    { name: "prod-eu", dir: "prod-eu", kind: "chant" },
+    { name: "api", dir: "api", kind: "chant" },
+  ];
+
+  test("both maps are read without their x- keys, and stay absent when unset", () => {
+    const d = parse(base(members, { ci: { branches: { release: ["prod-*"], "x-note": "ops" }, labels: { "plan:prod": ["prod-*"] } } }));
+    expect(d.ci?.branches).toEqual({ release: ["prod-*"] });
+    expect(d.ci?.labels).toEqual({ "plan:prod": ["prod-*"] });
+    expect(parse(base(members, { ci: {} })).ci).toEqual({ green: null, reportUrl: null });
+  });
+
+  test("a member two branches route is declaration-invalid at the second branch", () => {
+    const err = failure(base(members, { ci: { branches: { release: ["prod-*"], hotfix: ["prod-eu"] } } }));
+    expect(err.code).toBe("declaration-invalid");
+    expect(err.message).toBe("ci.branches routes member prod-eu to both release and hotfix; a member applies from one branch");
+  });
+
+  test("an empty glob list or a glob that is not a member-name glob is refused", () => {
+    expect(failure(base(members, { ci: { branches: { release: [] } } })).code).toBe("declaration-invalid");
+    expect(failure(base(members, { ci: { branches: { release: ["prod/eu"] } } })).code).toBe("declaration-invalid");
+    expect(failure(base(members, { ci: { labels: { "plan:prod": "prod-*" } } })).code).toBe("declaration-invalid");
+  });
+});
+
+describe("ci.identity.cloud (#4296)", () => {
+  const members = [{ name: "net", dir: "net", kind: "chant" }];
+  const aws = { region: "eu-west-1", "x-note": "ops", rules: [{ environments: ["prod"], members: ["net"], plan: "arn:aws:iam::1:role/plan", apply: "arn:aws:iam::1:role/apply", "x-why": "split" }] };
+
+  test("each cloud is read without its x- keys", () => {
+    const d = parse(base(members, { ci: { identity: { cloud: { aws, azure: { tenantId: "t", rules: [{ plan: "p", apply: "a" }] } } } } }));
+    expect(d.ci?.identity).toEqual({
+      cloud: {
+        aws: { region: "eu-west-1", rules: [{ environments: ["prod"], members: ["net"], plan: "arn:aws:iam::1:role/plan", apply: "arn:aws:iam::1:role/apply" }] },
+        azure: { tenantId: "t", rules: [{ plan: "p", apply: "a" }] },
+      },
+    });
+  });
+
+  test("a rule that plans as an identity some rule applies as is declaration-invalid at that rule", () => {
+    const err = failure(base(members, { ci: { identity: { cloud: { aws: { rules: [{ plan: "r", apply: "r" }] } } } } }));
+    expect(err.code).toBe("declaration-invalid");
+    expect(err.message).toContain("ci.identity.cloud.aws.rules[0] plans and applies as r");
+  });
+
+  test("the schema refuses a rule with no apply, an unknown cloud and a GCP provider that is not a provider's name", () => {
+    expect(failure(base(members, { ci: { identity: { cloud: { aws: { rules: [{ plan: "r" }] } } } } })).code).toBe("declaration-invalid");
+    expect(failure(base(members, { ci: { identity: { cloud: { oci: { rules: [] } } } } })).code).toBe("declaration-invalid");
+    expect(failure(base(members, { ci: { identity: { cloud: { gcp: { provider: "forge", rules: [{ plan: "p", apply: "a" }] } } } } })).code).toBe("declaration-invalid");
+  });
+});
+
+describe("ci.prEnvironment (#4298)", () => {
+  const members = [{ name: "api", dir: "api", kind: "chant" }];
+
+  test("is read with its template and a 72h TTL by default", () => {
+    expect(parse(base(members, { ci: { prEnvironment: { template: "staging" } } })).ci?.prEnvironment).toEqual({ template: "staging", ttl: "72h" });
+    expect(parse(base(members, { ci: { prEnvironment: { template: "staging", ttl: "7d" } } })).ci?.prEnvironment).toEqual({ template: "staging", ttl: "7d" });
+  });
+
+  test("a block with no template, or a TTL in another form, is declaration-invalid", () => {
+    expect(failure(base(members, { ci: { prEnvironment: {} } })).code).toBe("declaration-invalid");
+    expect(failure(base(members, { ci: { prEnvironment: { template: "staging", ttl: "1w" } } })).code).toBe("declaration-invalid");
+  });
+});

package/src/workspace/declaration.ts

@@ -19,6 +19,8 @@
 import { RETENTION_KINDS, type RetentionOverride } from "../lifecycle/retention-policy";
 import { parseReportUrl } from "../pr-report-url";
 import schema from "./declaration.schema.json" with { type: "json" };
+import { routeConflicts } from "./ci-branches";
+import { cloudIdentityProblems, CLOUDS, type CloudIdentityDeclaration } from "../ci-identity";
 import { expandGlob } from "./glob";
 import { EXAMPLES_KIND, holdsChantProject } from "./kinds";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
@@ -27,6 +29,8 @@ import type { SecurityGroup } from "./security";
 import { joinPath, type WorkspaceTree } from "./tree";
 import { loadAjv2020 } from "./ajv2020";
 import { readChantPackageVersion } from "../package-version";
+import { assertPrLoopHooks, type OpWaveHooks } from "../op/op-waves";
+import { assertGatePolicySettings, type GatePolicySettings } from "../gate-policy";
 
 export const DECLARATION_SCHEMA_ID = schema.$id;
 export const DECLARATION_FILES = ["chant.workspace.json", "chant.workspace.jsonc"] as const;
@@ -254,16 +258,30 @@ export type CiSource = "checks" | "runs";
  * A prescribed delivery workflow (#4168 section 7). `trunk-curated`: a merge
  * records the plan and deploys nothing, and releases are cut from green
  * commits and promoted through the environments. `trunk-curated+apply-on-merge`
- * adds the apply on merge as an opt-in. `chant workspace check` reports what a
- * member under one still lacks (./checks/ci-workflow.ts, WSP151).
+ * adds the apply on merge as an opt-in. `apply-before-merge` (#4301, ws-106)
+ * is `trunk-curated` with an open pull request's plan applied from its head
+ * on request, once it is approved, mergeable, undiverged and green. `chant
+ * workspace check` reports what a member under one still lacks
+ * (./checks/ci-workflow.ts, WSP151).
  */
-export type CiWorkflow = "trunk-curated" | "trunk-curated+apply-on-merge";
+export type CiWorkflow = "trunk-curated" | "trunk-curated+apply-on-merge" | "apply-before-merge";
+
+/**
+ * When a pull request takes its target locks (#4293, ../lifecycle/target-lock.ts).
+ * `apply`: its apply takes them, and `chant lock` does by hand. `plan`: its
+ * plan takes them too, through `chant lock --stage plan` in a job that runs
+ * the target branch's code. Under either, an apply refuses a target another
+ * open pull request holds.
+ */
+export type CiLocks = "apply" | "plan";
 
 /** The declaration's `ci` block (#3573). */
 export interface CiDeclaration {
   green: CiGreen | null;
   /** `ci.workflow` (#4168 step 6): the workflow every member follows unless it names its own; absent when the declaration sets none. */
   workflow?: CiWorkflow;
+  /** `ci.locks` (#4293): when a pull request takes its target locks; absent when the declaration sets none, and then nothing is locked. */
+  locks?: CiLocks;
   /**
    * `ci.reportUrl` (#4160): where the pull-request jobs copy their reports
    * and `chant ci run` keeps the run index, `<reportUrl>/runs/index.json`.
@@ -272,8 +290,56 @@ export interface CiDeclaration {
    * the declaration sets none.
    */
   reportUrl: string | null;
+  /**
+   * `ci.hooks` (#4288): the stage hooks the pull-request jobs run, in the
+   * shape an Op waves spec's `hooks` takes. `chant components pr-plan`,
+   * `pr-record` and `pr-apply` read them from the declaration at base.
+   * Absent when the declaration sets none.
+   */
+  hooks?: OpWaveHooks;
+  /**
+   * `ci.branches` (#4292): branch name to member-name globs. A member a glob
+   * matches applies from that branch alone; the others apply from every
+   * branch the map does not name (./ci-branches.ts). Absent when unset.
+   */
+  branches?: Record<string, string[]>;
+  /**
+   * `ci.labels` (#4292): pull request label to member-name globs. A labelled
+   * pull request plans only the members its labels match. Never a gate.
+   * Absent when unset.
+   */
+  labels?: Record<string, string[]>;
+  /**
+   * `ci.policy` (#4294): the policy engine the pull-request jobs run over
+   * the change set, read with the policy from the declaration at base.
+   * Absent when the declaration sets none.
+   */
+  policy?: GatePolicySettings;
+  /**
+   * `ci.identity` (#4296): `cloud` gives each cloud's plan and apply
+   * identities by environment and member globs (../ci-identity.ts).
+   * Absent when unset.
+   */
+  identity?: { cloud: CloudIdentityDeclaration };
+  /**
+   * `ci.prEnvironment` (#4298): an environment per open pull request,
+   * derived from `template`, torn down on close or after `ttl`
+   * (../components/pr-environment.ts). Absent when unset.
+   */
+  prEnvironment?: CiPrEnvironment;
 }
 
+/** The `ci.prEnvironment` block (#4298), with its default TTL. */
+export interface CiPrEnvironment {
+  /** The declared environment `pr-<n>` takes its endpoint from. */
+  template: string;
+  /** How long the environment lives after its last apply: `72h` when absent. */
+  ttl: string;
+}
+
+/** The default `ci.prEnvironment.ttl`. */
+export const DEFAULT_PR_ENVIRONMENT_TTL = "72h";
+
 export interface MemberRole {
   name: string;
   /** Relative to the member's directory, or null for the whole member. */
@@ -592,6 +658,8 @@ export interface Member {
   security: SecurityGroup[];
   /** The member's own `ci.workflow` (#4168 step 6), which wins over the top level's; null when it names none. */
   ciWorkflow: CiWorkflow | null;
+  /** The member's own `ci.hooks` (#4288), run after the top level's; null when it names none. */
+  ciHooks: OpWaveHooks | null;
   suppress: Suppression[];
   /** The entry's JSON Pointer in the file, for messages. */
   pointer: string;
@@ -889,6 +957,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       travel: e.travel === true,
       security: [...((e.security as SecurityGroup[] | undefined) ?? [])],
       ciWorkflow: ((e.ci as { workflow?: CiWorkflow } | undefined)?.workflow) ?? null,
+      ciHooks: ciHooksOf((e.ci as { hooks?: unknown } | undefined)?.hooks, `${pointer}/ci/hooks`, at),
       suppress,
       pointer,
     };
@@ -1013,6 +1082,15 @@ export function parseDeclaration(text: string, file: string, reader: string = re
   const tierSession = factoryTierSessionProblem(members, agents);
   if (tierSession) throw new WorkspaceReadError("declaration-invalid", tierSession.message, at(tierSession.pointer));
   const ci = ciOf(obj.ci, at);
+  // #4292: a member applies from one branch, so two branches may not both route it.
+  const [conflict] = routeConflicts(ci?.branches, members.map((m) => m.name));
+  if (conflict) {
+    throw new WorkspaceReadError(
+      "declaration-invalid",
+      `ci.branches routes member ${conflict.member} to both ${conflict.branches.join(" and ")}; a member applies from one branch`,
+      at(`/ci/branches/${pointerToken(conflict.branches[1]!)}`),
+    );
+  }
 
   const pins = ((obj.pins as Record<string, string>[] | undefined) ?? []).map((p) => ({
     package: p.package ?? null,
@@ -1134,10 +1212,67 @@ function retentionOf(raw: unknown): RetentionOverride | null {
   return out;
 }
 
+/** A `ci.hooks` block (#4288), refused when a pull-request job could not run it. Null when absent. */
+function ciHooksOf(raw: unknown, pointer: string, at: (pointer: string, key?: boolean) => ErrorLocation): OpWaveHooks | null {
+  if (raw === undefined) return null;
+  try {
+    assertPrLoopHooks(pointer.slice(1).replace(/\//g, "."), raw as OpWaveHooks);
+  } catch (err) {
+    throw new WorkspaceReadError("declaration-invalid", err instanceof Error ? err.message : String(err), at(pointer));
+  }
+  return structuredClone(raw as OpWaveHooks);
+}
+
+/** A `ci.branches` or `ci.labels` map, copied without its `x-` keys. */
+function globMap(raw: Record<string, string[]>): Record<string, string[]> {
+  return Object.fromEntries(Object.entries(raw).filter(([k]) => !k.startsWith("x-")).map(([k, v]) => [k, [...v]]));
+}
+
+/** A `ci.policy` block (#4294), refused when the pull-request jobs could not run it. Null when absent. */
+function ciPolicyOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): GatePolicySettings | null {
+  if (raw === undefined) return null;
+  try {
+    assertGatePolicySettings("ci.policy", raw);
+  } catch (err) {
+    throw new WorkspaceReadError("declaration-invalid", err instanceof Error ? err.message : String(err), at("/ci/policy"));
+  }
+  return structuredClone(raw);
+}
+
+/**
+ * `ci.identity.cloud` (#4296), copied without its `x-` keys. A rule that
+ * plans as an identity some rule applies as is refused: the plan runs the
+ * pull request's code.
+ */
+function cloudIdentityOf(raw: CloudIdentityDeclaration, at: (pointer: string, key?: boolean) => ErrorLocation): CloudIdentityDeclaration {
+  const out: CloudIdentityDeclaration = {};
+  for (const cloud of CLOUDS) {
+    const c = raw[cloud];
+    if (c === undefined) continue;
+    const kept = Object.fromEntries(Object.entries(c).filter(([k]) => !k.startsWith("x-")));
+    const rules = c.rules.map((r) => Object.fromEntries(Object.entries(r).filter(([k]) => !k.startsWith("x-")).map(([k, v]) => [k, Array.isArray(v) ? [...v] : v])));
+    (out as Record<string, unknown>)[cloud] = { ...kept, rules };
+  }
+  const [problem] = cloudIdentityProblems(out);
+  if (problem) throw new WorkspaceReadError("declaration-invalid", problem.message, at(problem.pointer));
+  return out;
+}
+
 function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): CiDeclaration | null {
   if (raw === undefined) return null;
-  const block = raw as { reportUrl?: string; workflow?: CiWorkflow; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource } };
-  const workflow = block.workflow !== undefined ? { workflow: block.workflow } : {};
+  const block = raw as { reportUrl?: string; workflow?: CiWorkflow; hooks?: unknown; identity?: { cloud?: CloudIdentityDeclaration }; branches?: Record<string, string[]>; labels?: Record<string, string[]>; locks?: CiLocks; policy?: unknown; prEnvironment?: { template: string; ttl?: string }; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource } };
+  const hooks = ciHooksOf(block.hooks, "/ci/hooks", at);
+  const policy = ciPolicyOf(block.policy, at);
+  const workflow = {
+    ...(block.workflow !== undefined ? { workflow: block.workflow } : {}),
+    ...(hooks ? { hooks } : {}),
+    ...(block.branches !== undefined ? { branches: globMap(block.branches) } : {}),
+    ...(block.labels !== undefined ? { labels: globMap(block.labels) } : {}),
+    ...(block.locks !== undefined ? { locks: block.locks } : {}),
+    ...(policy ? { policy } : {}),
+    ...(block.identity?.cloud !== undefined ? { identity: { cloud: cloudIdentityOf(block.identity.cloud, at) } } : {}),
+    ...(block.prEnvironment !== undefined ? { prEnvironment: { template: block.prEnvironment.template, ttl: block.prEnvironment.ttl ?? DEFAULT_PR_ENVIRONMENT_TTL } } : {}),
+  };
   let reportUrl: string | null = null;
   if (block.reportUrl !== undefined) {
     // #4160: refused here as pr-plan and ci run refuse the flag, so a reader never gets a URL no job can write to.

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

@@ -14,7 +14,7 @@
  * else: no zod, no ajv, no package loading, so it bundles small.
  */
 
-import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, sshKeyFingerprint, sshSignatureKey, verifySshSignatureWith, type SealedGateApproval } from "./trust/gate-seal";
+import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, sshKeyFingerprint, sshSignatureKey, verifySshSignatureWith, type SealedGateApproval } from "../lifecycle/gate-seal";
 import type { Signer } from "./trust/trust-files";
 
 /** The core classes, in the order a principal's roles are tried; `human` holds no role and is the rest. */

package/src/workspace/identity.ts

@@ -31,7 +31,7 @@ import { classesOf, coreClassRegistry, roleGrants, type ClassRegistry } from "./
 import type { ReasonCode } from "./reason-codes";
 import { normalisePrincipal } from "./records";
 import type { TrustPolicy } from "./trust/policy";
-import type { SealedGateApproval } from "./trust/gate-seal";
+import type { SealedGateApproval } from "../lifecycle/gate-seal";
 import { scopeSource } from "./write-scope";
 
 /** The forges a forge identity can name. */

package/src/workspace/lineage-upgrade.ts

@@ -42,6 +42,7 @@ import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { computePlanDigest } from "../lifecycle/plan-digest";
 import type { ResolvedGateApproval } from "../op/gate-approval";
+import { quorumRules, type GateQuorumSpec } from "../op/gate-quorum";
 import { checkLineage, findingKey, type CheckFinding } from "./lineage-check";
 import { dirLabel, git, parseDirSpec, parseTemplateSource, portableUrl, readTemplateDir, readTemplateTree, recordedDirPath } from "./lineage-init";
 import {
@@ -589,11 +590,13 @@ async function rulesAtHead(repo: string, paths: string[]): Promise<ResolvedGateA
       for (const { config, filePath } of ops.values()) {
         const rel = relative(repo, filePath).split(sep).join("/");
         if (!opFiles.has(rel)) continue;
+        // #4290: a quorum may be a list of rules; the strictest count is asked for.
         for (const approval of gateApprovals(config)) {
-          const need = approval.quorum?.count ?? 1;
-          if (need > count) {
-            count = need;
-            roles = approval.quorum?.roles;
+          for (const rule of quorumRules(approval.quorum)) {
+            if (rule.count > count) {
+              count = rule.count;
+              roles = rule.roles;
+            }
           }
         }
       }
@@ -602,10 +605,10 @@ async function rulesAtHead(repo: string, paths: string[]): Promise<ResolvedGateA
   return { mode: "log-only", quorum: { count, ...(roles && roles.length > 0 ? { roles } : {}) } };
 }
 
-type StepLike = { kind: string; approval?: { quorum?: { count: number; roles?: string[] } }; steps?: StepLike[] };
+type StepLike = { kind: string; approval?: { quorum?: GateQuorumSpec }; steps?: StepLike[] };
 
-function gateApprovals(config: { phases?: Array<{ steps: StepLike[] }>; onFailure?: Array<{ steps: StepLike[] }> }): Array<{ quorum?: { count: number; roles?: string[] } }> {
-  const out: Array<{ quorum?: { count: number; roles?: string[] } }> = [];
+function gateApprovals(config: { phases?: Array<{ steps: StepLike[] }>; onFailure?: Array<{ steps: StepLike[] }> }): Array<{ quorum?: GateQuorumSpec }> {
+  const out: Array<{ quorum?: GateQuorumSpec }> = [];
   const visit = (step: StepLike): void => {
     if (step.kind === "gate") out.push(step.approval ?? {});
     if (step.kind === "effect") (step.steps ?? []).forEach(visit);
@@ -1042,7 +1045,7 @@ export function describeStaged(staged: StagedUpgrade): string[] {
   }
   for (const s of staged.manualSteps) lines.push(`  manual step: ${at(s.path)} (${s.reason})`);
   if (staged.governance) {
-    const q = staged.governance.approval.quorum!;
+    const q = quorumRules(staged.governance.approval.quorum)[0]!;
     lines.push(
       `  governance: ${staged.governance.paths.join(", ")}; needs ${q.count} human approval(s)${q.roles ? ` with a role in ${q.roles.join(", ")}` : ""}, from the rules at ${staged.governance.rules.slice(0, 12)}`,
     );

package/src/workspace/member-pipeline.test.ts

@@ -178,3 +178,32 @@ describe("the generated-file record", () => {
     expect(readGeneratedRecord(dir).files.map((f) => f.path)).toEqual(["a.yml", "b.yml"]);
   });
 });
+
+describe("ci.branches routes a member's pull-request pipeline (#4292)", () => {
+  const routed = () => {
+    rmSync(repo, { recursive: true, force: true });
+    repo = twoMemberWorkspace({ extra: { ci: { branches: { release: ["api"] } } } });
+  };
+  const plan = (dir: string, branch?: string) =>
+    planMemberComponentPipeline({ projectDir: dir, found: findWorkspaceRoot(dir)!, lexicon: "github", env: "staging", prLoop: branch ? { branch } : {} })!;
+
+  test("a routed member's pipeline targets its branch, with or without --branch naming it", () => {
+    routed();
+    const dir = join(repo, "services/api");
+    expect(plan(dir).branch).toBe("release");
+    expect(plan(dir, "release").branch).toBe("release");
+    expect(plan(dir).command).toBe("chant build --components --generate github --env staging --pr-loop");
+  });
+
+  test("--branch may not move a routed member, nor put another member on a routed branch", () => {
+    routed();
+    expect(() => plan(join(repo, "services/api"), "main")).toThrow("--branch main: ci.branches routes member api to release, so its pull-request pipeline targets release");
+    expect(() => plan(join(repo, "apps/web"), "release")).toThrow("--branch release: ci.branches applies only the members its globs match from release, and member web is not one");
+  });
+
+  test("an unrouted member keeps --branch, or the generator's default", () => {
+    routed();
+    expect(plan(join(repo, "apps/web")).branch).toBeUndefined();
+    expect(plan(join(repo, "apps/web"), "trunk").branch).toBe("trunk");
+  });
+});

package/src/workspace/member-pipeline.ts

@@ -26,6 +26,7 @@ import { GENERATED_MARKER } from "../discovery/files";
 import type { PipelineMember } from "../lexicon";
 import type { WorkspaceRootSearch } from "../project-root";
 import { ownerOf, readDeclaration, resolveGroups, rootExclusions, WorkspaceReadError, type Declaration, type Member } from "./declaration";
+import { routedBranch } from "./ci-branches";
 import { gitTop, workingTree } from "./tree";
 
 /**
@@ -196,6 +197,12 @@ export interface MemberComponentPlan {
   /** The command that regenerates it, run in the member's directory. */
   command: string;
   env: string;
+  /**
+   * With `--pr-loop`, the branch the pipeline targets: `--branch`, else the
+   * branch `ci.branches` routes the member to (#4292). Undefined for the
+   * generator's default.
+   */
+  branch?: string;
 }
 
 export interface ComponentPlanInput {
@@ -234,6 +241,7 @@ export function planMemberComponentPipeline(input: ComponentPlanInput): MemberCo
   const ctx = resolveMemberContext(input.projectDir, input.found);
   if (!ctx) return undefined;
   const env = input.env ?? DEFAULT_ENV;
+  const branch = input.prLoop ? prLoopBranch(ctx, input.prLoop.branch) : undefined;
   let target: string;
   if (input.output) {
     target = resolve(input.output);
@@ -273,9 +281,31 @@ export function planMemberComponentPipeline(input: ComponentPlanInput): MemberCo
     target,
     command: parts.map(shellArg).join(" "),
     env,
+    ...(branch !== undefined ? { branch } : {}),
   };
 }
 
+/**
+ * The branch a member's pull-request pipeline targets (#4292): the one
+ * `ci.branches` routes it to, which `--branch` may repeat but not change.
+ * Without a route, `--branch` as given, which may not name a routed branch
+ * whose globs leave the member out.
+ */
+function prLoopBranch(ctx: MemberContext, flag: string | undefined): string | undefined {
+  const branches = ctx.declaration.ci?.branches;
+  const own = routedBranch(branches, ctx.member.name);
+  if (own !== null) {
+    if (flag !== undefined && flag !== own) {
+      throw new Error(`--branch ${flag}: ci.branches routes member ${ctx.member.name} to ${own}, so its pull-request pipeline targets ${own}`);
+    }
+    return own;
+  }
+  if (flag !== undefined && Object.prototype.hasOwnProperty.call(branches ?? {}, flag)) {
+    throw new Error(`--branch ${flag}: ci.branches applies only the members its globs match from ${flag}, and member ${ctx.member.name} is not one`);
+  }
+  return flag;
+}
+
 /** Write a member's pipeline with its header and record it as the member's generated file. */
 export function writeMemberComponentPipeline(plan: MemberComponentPlan, yaml: string): void {
   mkdirSync(dirname(plan.target), { recursive: true });

package/src/workspace/pr-report.schema.json

@@ -8,7 +8,7 @@
   "properties": {
     "$schema": { "const": "https://intentius.io/chant/schemas/workspace/pr-report/v1/pr-report.schema.json" },
     "contract": { "const": 1 },
-    "stage": { "enum": ["plan", "apply", "record"], "description": "plan: on the pull request. record (#4168, chant 0.124.33 and newer): on merge, the default; it plans the merged commit and writes the merge record, applying nothing. apply: on merge with --apply-on-merge." },
+    "stage": { "enum": ["plan", "apply", "record"], "description": "plan: on the pull request. record (#4168, chant 0.124.33 and newer): on merge, the default; it plans the merged commit and writes the merge record, applying nothing. apply: on merge with --apply-on-merge, or (#4301, chant 0.124.42 and newer) at an open pull request's head with --before-merge, when beforeMerge is set." },
     "pr": {
       "type": ["integer", "null"],
       "minimum": 1,
@@ -37,8 +37,8 @@
       "description": "planned: every member planned (plan stage). recorded (#4168, chant 0.124.33 and newer): every member planned on the merged commit and the merge record was written (record stage); approval says whether the plan is the approved one, and nothing applied. plan-failed: a member failed to plan, so nothing can apply. nothing: no component deploys what the change touches. applied: every member applied. failed: a member failed to apply and its dependents did not run. wave-applied (#4003, chant 0.124.32 and newer): with --wave-gate and --wave, the wave applied and a later wave is still to run. refused: nothing applied, see refusal. waiting (#3999): the approved plans applied except members held back after an upstream applied, which wait on an approval of the plan the last of rounds made."
     },
     "refusal": {
-      "enum": ["not-approved", "plan-changed", "not-a-reviewer", "author-approved", "no-pull-request", "wave-not-approved", "wave-plan-changed", "earlier-wave"],
-      "description": "Why an apply refused. plan-changed: an approval stands for another digest, so the plan changed after review. author-approved (#4000): under --require-review, an approval names the pull request's author or an author or committer of one of its commits. With --wave-gate (#4003, chant 0.124.32 and newer): wave-not-approved, a wave's new plan is not covered by the approved one and no approval of its gate stands for it; wave-plan-changed, an approval of its gate stands for another digest; earlier-wave, an earlier wave has work left or no record says it applied. The waves that applied before a wave refused stay applied; waves says which."
+      "enum": ["not-approved", "plan-changed", "not-a-reviewer", "author-approved", "no-pull-request", "wave-not-approved", "wave-plan-changed", "earlier-wave", "locked", "policy-denied", "policy-error", "requires-unmet", "before-merge-off"],
+      "description": "Why an apply refused. plan-changed: an approval stands for another digest, so the plan changed after review. author-approved (#4000): under --require-review, an approval names the pull request's author or an author or committer of one of its commits. With --wave-gate (#4003, chant 0.124.32 and newer): wave-not-approved, a wave's new plan is not covered by the approved one and no approval of its gate stands for it; wave-plan-changed, an approval of its gate stands for another digest; earlier-wave, an earlier wave has work left or no record says it applied. The waves that applied before a wave refused stay applied; waves says which. locked (#4293, chant 0.124.41 and newer): under ci.locks, another open pull request holds a lock on a target the apply reaches, and nothing applied. With ci.policy (#4294, chant 0.124.41 and newer): policy-denied, the policy at base denied the plan and no override counts; policy-error, the policy could not be run or gave no readable answer. With pr-apply --before-merge (#4301, chant 0.124.42 and newer): requires-unmet, the pull request is not approved, mergeable, undiverged or green, and beforeMerge says which; before-merge-off, the declaration at base does not set ci.workflow to apply-before-merge for the member. Nothing applied."
     },
     "message": { "type": "string", "description": "The refusal or failure as printed." },
     "resumed": {
@@ -77,6 +77,21 @@
         }
       }
     },
+    "overdue": {
+      "type": "array",
+      "description": "Added within contract version 1 by #4289, written by chant 0.124.41 and newer. Plan stage: the scheduled watch and reconcile Ops whose cron has fired at least twice since their job last ran, or since their pipeline file was added when no run is on record. Absent when none is overdue or the forge was not asked.",
+      "items": {
+        "type": "object",
+        "required": ["op", "cron", "since", "message"],
+        "properties": {
+          "op": { "type": "string" },
+          "cron": { "type": "string" },
+          "since": { "type": "string", "description": "The job's last run, or the pipeline file's first commit when neverRan, ISO 8601." },
+          "neverRan": { "type": "boolean" },
+          "message": { "type": "string", "description": "The warning as the plan note prints it." }
+        }
+      }
+    },
     "plannedOutputs": {
       "type": "object",
       "description": "Added within contract version 1 by #3999, written by chant 0.124.32 and newer. Per dependency in the change that a member was planned against, the names of the outputs its plan knows, sorted. An output a member reads that is not listed is known only after apply, and the member lists it under unknownInputs. Absent when no member read one.",
@@ -175,6 +190,82 @@
     "changeSet": {
       "type": "object",
       "description": "The change-set document over every member (change-set.schema.json). Its digest equals digest."
+    },
+    "hooks": {
+      "type": "array",
+      "description": "Added within contract version 1 by #4288, written by chant 0.124.41 and newer. The stage hooks the job ran, in order, from ci.hooks in the workspace declaration at base. Absent when it ran none.",
+      "items": {
+        "type": "object",
+        "required": ["moment", "name", "exit", "outcome"],
+        "additionalProperties": false,
+        "properties": {
+          "moment": { "enum": ["before-observe", "before-plan", "after-plan", "before-apply", "after-apply"] },
+          "name": { "type": "string" },
+          "target": { "type": "string", "description": "The component, for a perRun hook." },
+          "exit": { "type": "integer" },
+          "outcome": { "enum": ["passed", "failed", "held"], "description": "held: an onFailure approve hook failed, which the pull request's gate answers." }
+        }
+      }
+    },
+    "beforeMerge": {
+      "type": "object",
+      "required": ["requires"],
+      "description": "Added within contract version 1 by #4301, written by chant 0.124.42 and newer. pr-apply --before-merge: the requires checks the forge answered before anything planned (ws-106). Absent on every other stage.",
+      "properties": {
+        "requires": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "passed", "reason"],
+            "properties": {
+              "name": { "enum": ["approved", "mergeable", "undiverged", "checks"] },
+              "passed": { "type": "boolean" },
+              "pending": { "type": "boolean", "description": "The forge had not settled it when asked: a check still ran, or it had not worked out whether the pull request merges." },
+              "reason": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "description": "Added within contract version 1 by #4294, written by chant 0.124.41 and newer. What ci.policy in the workspace declaration at base said about the change set. Absent when the base sets no policy, or the stage reached no plan to judge.",
+      "required": ["result", "engine", "base", "denials", "holds", "warnings"],
+      "additionalProperties": false,
+      "properties": {
+        "result": { "enum": ["passed", "denied", "held", "error"], "description": "denied wins over held. error: the policy did not run or gave no readable answer, and nothing applies." },
+        "engine": { "enum": ["conftest", "opa"], "description": "The result shape read." },
+        "base": { "type": "string", "description": "The commit the settings and the policy were read at." },
+        "denials": { "type": "array", "items": { "$ref": "#/$defs/policyFinding" } },
+        "rules": { "type": "array", "items": { "type": "string" }, "description": "The ids of the rules that denied, sorted: what an override names." },
+        "holds": { "type": "array", "items": { "$ref": "#/$defs/policyFinding" }, "description": "Rules that hold the plan for a person's approval of its digest." },
+        "warnings": { "type": "array", "items": { "type": "string" } },
+        "error": { "type": "string" },
+        "override": {
+          "type": "object",
+          "required": ["by", "at", "reason", "digest"],
+          "additionalProperties": false,
+          "description": "The override on _gates/policy-override.jsonl that lets the denied plan through.",
+          "properties": {
+            "by": { "type": "string" },
+            "at": { "type": "string" },
+            "reason": { "type": "string" },
+            "digest": { "type": "string", "description": "The override digest: the op, the plan digest and the rules." }
+          }
+        },
+        "overrideCommand": { "type": "string", "description": "While denied: the command that overrides the denial." }
+      }
+    }
+  },
+  "$defs": {
+    "policyFinding": {
+      "type": "object",
+      "required": ["rule", "message"],
+      "additionalProperties": false,
+      "properties": {
+        "rule": { "type": "string", "description": "<package>.<rule>, such as main.deny_public_bucket." },
+        "message": { "type": "string" }
+      }
     }
   }
 }

package/src/workspace/reason-codes.ts

@@ -255,7 +255,7 @@ export const REASONS = {
   "ci-workflow-no-environments": "Under ci.workflow, a member's chant.config.ts declares no environments, so a release has nowhere to be promoted to.",
   "ci-workflow-ungated-env": "Under ci.workflow, a component has no gate, so a promote to the last environment waits on no approval.",
   "ci-workflow-pipeline-missing": "Under ci.workflow, no pipeline file runs the plan job, the merge job or chant ci tick.",
-  "ci-workflow-pipeline-differs": "Under ci.workflow, the merge job does not match the workflow: it applies under trunk-curated, or records under trunk-curated+apply-on-merge.",
+  "ci-workflow-pipeline-differs": "Under ci.workflow, the pipeline does not match the workflow: it applies on merge under trunk-curated, records under trunk-curated+apply-on-merge, or applies before merge, or fails to, against apply-before-merge.",
   "ci-workflow-publish-missing": "Under ci.workflow, no pipeline file runs chant release publish.",
   // A box that holds a credential (check, #2726). Each is also a WSP finding.
   "box-credential-declared": "A file in a box member's directory carries a literal secret: a credential's shape, or a literal where a credential goes. A variable or secret-manager reference is not one.",

package/src/workspace/security.ts

@@ -109,6 +109,10 @@ export const SECURITY_FEATURES: readonly SecurityFeature[] = [
   { feature: "Apply jobs require a runner-start statement", byDefault: "off", setting: "`--require-runner-start`", group: "isolated-runners", codes: ["security-runner-start-no-key", "security-runner-start-no-role", "security-trust-unreadable"] },
   { feature: "Secrets file", byDefault: "off", setting: "`--secrets`", group: null, codes: [] },
   { feature: "Env allowlist and log redaction", byDefault: "on: `ci run`'s contract, a listed exception", setting: "`--pass-env`", group: null, codes: [] },
+  // #4295: the plan job's steps never hold a forge token; the plan-note job posts. Part of the generated pipeline, so nothing turns it on.
+  { feature: "Plan steps hold no forge token", byDefault: "on: the plan job's contract, a listed exception", setting: "regenerate the pipeline", group: null, codes: [] },
+  // #4296: the plan job trades its OIDC token for the plan identity before the checkout, and the apply jobs take the apply identity.
+  { feature: "Separate plan and apply cloud identities", byDefault: "off: no job requests an OIDC token", setting: "`ci.identity.cloud`", group: null, codes: [] },
 ];
 
 /** The reference page's table of {@link SECURITY_FEATURES}, as markdown. */