@intentius/chant 0.124.93 → 0.124.95

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/dist/ci-comment-commands.d.ts +12 -1
  2. package/dist/ci-comment-commands.d.ts.map +1 -1
  3. package/dist/ci-comment-commands.js +29 -0
  4. package/dist/ci-note-commands.d.ts +1 -1
  5. package/dist/ci-note-commands.d.ts.map +1 -1
  6. package/dist/ci-note-commands.js +11 -1
  7. package/dist/ci-product.d.ts +19 -1
  8. package/dist/ci-product.d.ts.map +1 -1
  9. package/dist/ci-product.js +25 -8
  10. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  11. package/dist/cli/handlers/pr-comment.js +11 -4
  12. package/dist/cli/handlers/run-wave.js +17 -3
  13. package/dist/cli/main.d.ts.map +1 -1
  14. package/dist/cli/main.js +4 -1
  15. package/dist/components/product-pipeline.d.ts.map +1 -1
  16. package/dist/components/product-pipeline.js +4 -2
  17. package/dist/components/product-plan.d.ts +6 -0
  18. package/dist/components/product-plan.d.ts.map +1 -1
  19. package/dist/components/product-plan.js +9 -1
  20. package/dist/floor-table.data.d.ts.map +1 -1
  21. package/dist/floor-table.data.js +15 -6
  22. package/dist/gate-resume-run.d.ts +7 -0
  23. package/dist/gate-resume-run.d.ts.map +1 -1
  24. package/dist/gate-resume-run.js +42 -3
  25. package/dist/lexicon.d.ts +47 -1
  26. package/dist/lexicon.d.ts.map +1 -1
  27. package/dist/lifecycle/gate-applied.d.ts +18 -0
  28. package/dist/lifecycle/gate-applied.d.ts.map +1 -1
  29. package/dist/op/before-merge-decide.d.ts +39 -2
  30. package/dist/op/before-merge-decide.d.ts.map +1 -1
  31. package/dist/op/before-merge-decide.js +59 -0
  32. package/dist/op/gate-run-locator.d.ts +17 -0
  33. package/dist/op/gate-run-locator.d.ts.map +1 -1
  34. package/dist/op/index.d.ts +3 -1
  35. package/dist/op/index.d.ts.map +1 -1
  36. package/dist/op/index.js +2 -1
  37. package/dist/op/op-waves-names.d.ts +40 -0
  38. package/dist/op/op-waves-names.d.ts.map +1 -1
  39. package/dist/op/op-waves-names.js +79 -0
  40. package/dist/op/op-waves-remainder.d.ts +110 -0
  41. package/dist/op/op-waves-remainder.d.ts.map +1 -0
  42. package/dist/op/op-waves-remainder.js +120 -0
  43. package/dist/op/op-waves-render-spec.d.ts +63 -5
  44. package/dist/op/op-waves-render-spec.d.ts.map +1 -1
  45. package/dist/op/op-waves-render-spec.js +68 -10
  46. package/dist/op/op-waves-run.d.ts +27 -1
  47. package/dist/op/op-waves-run.d.ts.map +1 -1
  48. package/dist/op/op-waves-run.js +192 -4
  49. package/dist/op/op-waves-split-resume.d.ts +57 -0
  50. package/dist/op/op-waves-split-resume.d.ts.map +1 -0
  51. package/dist/op/op-waves-split-resume.js +94 -0
  52. package/dist/op/op-waves.d.ts +26 -1
  53. package/dist/op/op-waves.d.ts.map +1 -1
  54. package/dist/op/op-waves.js +11 -2
  55. package/dist/release-floors.d.ts +13 -1
  56. package/dist/release-floors.d.ts.map +1 -1
  57. package/dist/release-floors.js +13 -1
  58. package/dist/wave-runtime.mjs +360 -360
  59. package/package.json +1 -1
  60. package/src/ci-comment-commands.test.ts +147 -0
  61. package/src/ci-comment-commands.ts +29 -1
  62. package/src/ci-note-commands.ts +12 -2
  63. package/src/ci-product.ts +28 -8
  64. package/src/cli/handlers/pr-comment.ts +10 -4
  65. package/src/cli/handlers/run-wave.ts +16 -3
  66. package/src/cli/main.ts +4 -1
  67. package/src/components/product-pipeline.ts +4 -2
  68. package/src/components/product-plan.ts +9 -2
  69. package/src/floor-table.data.ts +15 -6
  70. package/src/gate-resume-run.ts +38 -3
  71. package/src/lexicon.ts +47 -1
  72. package/src/lifecycle/gate-applied.ts +16 -0
  73. package/src/op/before-merge-decide.ts +74 -2
  74. package/src/op/gate-run-locator.ts +14 -0
  75. package/src/op/index.ts +5 -0
  76. package/src/op/op-waves-names.ts +80 -0
  77. package/src/op/op-waves-remainder.test.ts +341 -0
  78. package/src/op/op-waves-remainder.ts +146 -0
  79. package/src/op/op-waves-render-spec.test.ts +106 -0
  80. package/src/op/op-waves-render-spec.ts +81 -10
  81. package/src/op/op-waves-run.ts +200 -5
  82. package/src/op/op-waves-split-resume.test.ts +148 -0
  83. package/src/op/op-waves-split-resume.ts +109 -0
  84. package/src/op/op-waves.ts +33 -2
  85. package/src/release-floors.ts +19 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@intentius/chant",
3
- "version": "0.124.93",
3
+ "version": "0.124.95",
4
4
  "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://intentius.io/chant",
@@ -451,3 +451,150 @@ describe("the comment job's apply before merge on the waves (#4984)", () => {
451
451
  expect(() => commentJobsFromEnv(JSON.stringify({ ...jobs, wavesBeforeMerge: { ...bm, requires: ["green"] } }))).toThrow("requires is a list of approved, mergeable, undiverged, checks");
452
452
  });
453
453
  });
454
+
455
+ describe("lock and unlock before merge, by the reach line (#5061)", () => {
456
+ const bm = { workflow: "tf-apply.yml", plan: ["terragucci/plan"], pipelineFiles: [".github/workflows/"], locks: { gate: "tf-apply" } };
457
+ const jobs: CommentJobs = { applyOnMerge: true, waves: { op: "tf-apply", count: 2 }, wavesBeforeMerge: bm };
458
+
459
+ /** A checkout of the default branch whose origin is itself, so the base fetch works. */
460
+ async function checkout() {
461
+ const { spawnSync } = await import("node:child_process");
462
+ const { mkdtempSync, writeFileSync } = await import("node:fs");
463
+ const { tmpdir } = await import("node:os");
464
+ const { join } = await import("node:path");
465
+ const dir = mkdtempSync(join(tmpdir(), "chant-cc-locks-"));
466
+ const git = (...args: string[]) => {
467
+ const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8", env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" } });
468
+ if (r.status !== 0) throw new Error(r.stderr);
469
+ return r.stdout.trim();
470
+ };
471
+ git("init", "-q", "-b", "main");
472
+ writeFileSync(join(dir, "main.tf"), "1");
473
+ git("add", ".");
474
+ git("commit", "-q", "-m", "base");
475
+ git("remote", "add", "origin", dir);
476
+ const run: NonNullable<AnswerCommentOptions["beforeMerge"]>["git"] = (argv, o) => {
477
+ const r = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8", ...(o.cwd ? { cwd: o.cwd } : {}) });
478
+ return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
479
+ };
480
+ return { dir, baseSha: git("rev-parse", "HEAD"), git: run };
481
+ }
482
+
483
+ /** The comment job with the lock and unlock the handler gives it, each call kept. */
484
+ async function locking(body: string, o: { forge?: "github" | "forgejo"; pr?: Partial<PullRequestDetail>; jobs?: CommentJobs; held?: string; released?: string[]; reached?: string[]; permission?: string; event?: Record<string, unknown> } = {}) {
485
+ const c = await checkout();
486
+ const head = "c".repeat(40);
487
+ const s = setup({ pr: { state: "open", headSha: head, mergeCommit: undefined, ...o.pr }, ...(o.permission ? { permission: o.permission } : {}) }, o.jobs ?? jobs, body, { ...(o.forge ? { forge: o.forge } : {}), ...(o.event ? { event: o.event } : {}) });
488
+ const locked: Array<[number, string, string, string, string | undefined]> = [];
489
+ const unlocked: number[] = [];
490
+ const got = await answerProductComment({
491
+ ...s.opts,
492
+ beforeMerge: {
493
+ requires: async () => null,
494
+ statuses: async () => [],
495
+ git: c.git,
496
+ cwd: c.dir,
497
+ lock: async (pr, h, base, by, asked) => {
498
+ locked.push([pr, h, base, by, asked]);
499
+ return o.held ? { ok: false, text: o.held } : { ok: true, targets: o.reached ?? ["envs/dev", "envs/prod"] };
500
+ },
501
+ unlock: async (pr) => (unlocked.push(pr), o.released ?? ["envs/dev"]),
502
+ record: async () => {
503
+ throw new Error("a lock records no decision");
504
+ },
505
+ stop: async () => {
506
+ throw new Error("a lock writes no wave stop");
507
+ },
508
+ },
509
+ });
510
+ return { got, posted: s.posted, locked, unlocked, dispatched: s.dispatched, head, baseSha: c.baseSha };
511
+ }
512
+
513
+ for (const forge of ["github", "forgejo"] as const) {
514
+ test(`${forge}: /terragucci lock takes the locks of what the reach line prints, measured from the default branch, and applies nothing`, async () => {
515
+ const r = await locking("/terragucci lock", { forge });
516
+ expect(r.locked).toEqual([[12, r.head, r.baseSha, "alice", "lock"]]);
517
+ expect(r.dispatched).toEqual([]);
518
+ expect(r.got).toMatchObject({ command: "lock", ran: false, replied: true });
519
+ expect(r.posted).toEqual([`terragucci: locked \`envs/dev\`, \`envs/prod\` for pull request 12 at ${r.head.slice(0, 8)} for alice, and nothing is applied; the locks hold until it merges or closes, or \`/terragucci unlock\` releases them`]);
520
+ });
521
+
522
+ test(`${forge}: a lock another open pull request holds is refused with its holder named`, async () => {
523
+ const held = "`envs/dev` is locked by pull request 9 (alice, apply), so pull request 12 takes no lock. It can once that pull request merges or closes, or someone with write access unlocks it";
524
+ const r = await locking("/terragucci lock", { forge, held });
525
+ expect(r.posted).toEqual([`terragucci: ${held}`]);
526
+ expect(r.got.fail).toBeUndefined();
527
+ });
528
+
529
+ test(`${forge}: /terragucci unlock releases the pull request's locks`, async () => {
530
+ const r = await locking("/terragucci unlock", { forge });
531
+ expect(r.unlocked).toEqual([12]);
532
+ expect(r.locked).toEqual([]);
533
+ expect(r.posted).toEqual(["terragucci: released `envs/dev`, which pull request 12 held, for alice"]);
534
+ const none = await locking("/terragucci unlock", { forge, released: [] });
535
+ expect(none.posted).toEqual(["terragucci: pull request 12 holds no lock, so there is nothing to unlock"]);
536
+ });
537
+
538
+ test(`${forge}: a fork is refused, and someone without write access gets nothing`, async () => {
539
+ const fork = await locking("/terragucci lock", { forge, pr: { sameRepo: false } });
540
+ expect(fork.locked).toEqual([]);
541
+ expect(fork.posted).toEqual([`terragucci: ${tgInput.replies!.fork}`]);
542
+ const forkUnlock = await locking("/terragucci unlock", { forge, pr: { sameRepo: false } });
543
+ expect(forkUnlock.unlocked).toEqual([]);
544
+ const reader = await locking("/terragucci lock", forge === "github" ? { forge, permission: "read" } : { forge, event: { repository: { full_name: "acme/infra", default_branch: "main", permissions: { push: false } } } });
545
+ expect(reader.locked).toEqual([]);
546
+ expect(reader.posted).toEqual([]);
547
+ expect(reader.got.replied).toBe(false);
548
+ });
549
+ }
550
+
551
+ test("a closed pull request takes no lock, one into another branch neither, and reaching nothing locks nothing", async () => {
552
+ expect((await locking("/terragucci lock", { pr: { state: "closed" } })).posted).toEqual(["terragucci: pull request 12 is not open, so it takes no lock"]);
553
+ expect((await locking("/terragucci lock", { pr: { base: "release" } })).posted).toEqual(["terragucci: pull request 12 targets release, not the default branch main, so it takes no lock"]);
554
+ const r = await locking("/terragucci lock", { reached: [] });
555
+ expect(r.posted).toEqual([`terragucci: pull request 12 reaches nothing at ${r.head.slice(0, 8)}, so it takes no lock`]);
556
+ });
557
+
558
+ test("with the comment lock jobs of locks: \"plan\", or without the reach line, nothing changes", async () => {
559
+ const planLocks = await locking("/terragucci lock", { jobs: { ...jobs, locks: true } });
560
+ expect(planLocks.got).toMatchObject({ replied: false, reason: "another job answers this comment" });
561
+ expect(planLocks.locked).toEqual([]);
562
+ const { locks: _l, ...noReach } = bm;
563
+ const without = await locking("/terragucci unlock", { jobs: { ...jobs, wavesBeforeMerge: noReach } });
564
+ expect(without.unlocked).toEqual([]);
565
+ expect(without.posted).toEqual([`terragucci: ${tgInput.replies!.unlock}`]);
566
+ });
567
+
568
+ test("GitLab's note poll locks and unlocks the same way through chantNoteRuns", async () => {
569
+ const c = await checkout();
570
+ const head = "d".repeat(40);
571
+ const mr: PullRequestDetail = { number: 3, title: "", body: "", state: "open", head: "feature", headSha: head, base: "main", sameRepo: true };
572
+ const locked: unknown[] = [];
573
+ const unlocked: number[] = [];
574
+ const deps = {
575
+ requires: async () => null,
576
+ statuses: async () => [],
577
+ git: c.git,
578
+ cwd: c.dir,
579
+ lock: async (pr: number, h: string, base: string, by: string, asked?: "apply" | "lock") => (locked.push([pr, h, base, by, asked]), { ok: true as const, targets: ["envs/dev"] }),
580
+ unlock: async (pr: number) => (unlocked.push(pr), ["envs/dev"]),
581
+ record: async () => {
582
+ throw new Error("no decision");
583
+ },
584
+ stop: async () => {},
585
+ };
586
+ const glJobs = { applyOnMerge: true, waves: { op: "tf-apply", count: 2 }, wavesBeforeMerge: { plan: ["terragucci/plan"], pipelineFiles: [".gitlab-ci.yml"], locks: { gate: "tf-apply" } } };
587
+ const runs = chantNoteRuns(glJobs, { beforeMerge: deps });
588
+ const ask = (body: string, m = mr): Omit<NoteCommand, "parsed"> => ({ mr: m, note: { id: 41, body, system: false, author: "bob" }, role: "developer", base: "main", words: tg });
589
+ expect(await runs({ ...ask("/terragucci lock"), parsed: { kind: "lock" } })).toEqual({ kind: "reply", text: `locked \`envs/dev\` for !3 at ${head.slice(0, 8)} for bob, and nothing is applied; the locks hold until it merges or closes, or \`/terragucci unlock\` releases them` });
590
+ expect(locked).toEqual([[3, head, c.baseSha, "bob", "lock"]]);
591
+ expect(await runs({ ...ask("/terragucci unlock"), parsed: { kind: "unlock" } })).toEqual({ kind: "reply", text: "released `envs/dev`, which !3 held, for bob" });
592
+ expect(unlocked).toEqual([3]);
593
+ expect(await runs({ ...ask("/terragucci lock", { ...mr, sameRepo: false }), parsed: { kind: "lock" } })).toEqual({ kind: "reply", text: tgInput.replies!.fork });
594
+ // With locks: "plan" the lock job runs, as before; without the reach line the product's sentence.
595
+ expect((await chantNoteRuns({ ...glJobs, locks: true }, { beforeMerge: deps })({ ...ask("/terragucci lock"), parsed: { kind: "lock" } })).kind).toBe("pipeline");
596
+ const { lock: _lock, unlock: _unlock, ...noReach } = deps;
597
+ expect(await chantNoteRuns(glJobs, { beforeMerge: noReach })({ ...ask("/terragucci lock"), parsed: { kind: "lock" } })).toEqual({ kind: "reply", text: tgInput.replies!.lock });
598
+ expect(locked).toHaveLength(1);
599
+ });
600
+ });
@@ -36,6 +36,10 @@
36
36
  * open pull request: the decision before merge
37
37
  * (./op/before-merge-decide.ts) records the head on `chant/lifecycle`
38
38
  * and dispatches the waves workflow on the default branch for it.
39
+ * - with `wavesBeforeMerge`, the product plan's reach line and no comment
40
+ * lock jobs (#5061), `/<product> lock` and `/<product> unlock`: the lock
41
+ * takes the locks of what the reach line prints at stage apply without
42
+ * applying, and the unlock releases the pull request's locks.
39
43
  *
40
44
  * Who asked comes first. On GitHub the commenter's permission is read from
41
45
  * the forge; Forgejo answers 403 when a job's token asks for another user's
@@ -113,7 +117,17 @@ export interface CommentJobs extends Omit<ChantNoteJobs, "members"> {
113
117
  }
114
118
 
115
119
  /** What the decision before merge reads and writes with (#4984), the comment job's handler's. */
116
- export type CommentBeforeMerge = Pick<DecideBeforeMergeInput, "requires" | "statuses" | "git" | "cwd" | "lock" | "record" | "stop" | "now">;
120
+ export type CommentBeforeMerge = Pick<DecideBeforeMergeInput, "requires" | "statuses" | "git" | "cwd" | "lock" | "unlock" | "record" | "stop" | "now">;
121
+
122
+ /**
123
+ * Whether `/<product> lock` and `/<product> unlock` are the comment job's
124
+ * (the note poll's on GitLab) under the waves before merge (#5061): the
125
+ * pipeline has the product plan's reach line and no comment lock jobs of
126
+ * `locks: "plan"`, and the job has the lock and unlock to answer with.
127
+ */
128
+ export function locksBeforeMerge(jobs: Pick<CommentJobs, "locks" | "wavesBeforeMerge">, deps: Pick<CommentBeforeMerge, "lock" | "unlock"> | undefined): deps is Required<Pick<CommentBeforeMerge, "lock" | "unlock">> {
129
+ return !jobs.locks && jobs.wavesBeforeMerge?.locks !== undefined && deps?.lock !== undefined && deps.unlock !== undefined;
130
+ }
117
131
 
118
132
  /** Writes a wave stop for op `op` at `sha` on `chant/lifecycle`, or clears it (#4979). */
119
133
  export type CommentWaveStops = (op: string, sha: string, stop: { through: number; at: string; by?: string; pr?: number } | null) => Promise<void>;
@@ -298,6 +312,20 @@ export async function answerProductComment(o: AnswerCommentOptions): Promise<Com
298
312
  }
299
313
  // A command another job answers starts that job on this same comment.
300
314
  if (parsed.kind !== "apply" && answeredElsewhere(parsed, o.jobs, true)) return silent("another job answers this comment", command);
315
+ // #5061: the waves before merge with the reach line and no plan locks: the lock and unlock are this job's.
316
+ if ((parsed.kind === "lock" || parsed.kind === "unlock") && o.beforeMerge && locksBeforeMerge(o.jobs, o.beforeMerge)) {
317
+ let pr: PullRequestDetail | undefined;
318
+ try {
319
+ pr = await o.reads.pullRequest(n);
320
+ } catch (err) {
321
+ return broke(`could not read ${t.at(n)} (${message(err)})`, command);
322
+ }
323
+ if (!pr) return broke(`the forge has no ${t.at(n)}`, command);
324
+ const { decideLocksBeforeMerge } = await import("./op/before-merge-decide");
325
+ const bm = o.beforeMerge;
326
+ const done = await decideLocksBeforeMerge({ forge: o.forge, pr, user, base: o.base, kind: parsed.kind, words: o.words, git: bm.git, ...(bm.cwd ? { cwd: bm.cwd } : {}), lock: bm.lock!, unlock: bm.unlock! });
327
+ return done.kind === "fail" ? broke(done.reason, command) : reply(done.text);
328
+ }
301
329
  switch (parsed.kind) {
302
330
  case "plan":
303
331
  case "lock":
@@ -498,7 +498,7 @@ export interface ChantNoteJobs {
498
498
  /** What {@link chantNoteRuns} reads and writes with besides the jobs (#4984). */
499
499
  export interface ChantNoteRunsOptions {
500
500
  /** With `jobs.wavesBeforeMerge`: what the decision before merge reads and writes with. */
501
- beforeMerge?: Pick<DecideBeforeMergeInput, "requires" | "statuses" | "git" | "cwd" | "lock" | "record" | "stop" | "now">;
501
+ beforeMerge?: Pick<DecideBeforeMergeInput, "requires" | "statuses" | "git" | "cwd" | "lock" | "unlock" | "record" | "stop" | "now">;
502
502
  }
503
503
 
504
504
  /**
@@ -543,10 +543,20 @@ export function chantNoteRuns(jobs: ChantNoteJobs, opts: ChantNoteRunsOptions =
543
543
  if (!mr.mergeCommit) return { kind: "fail", reason: `${at} has no merge commit` };
544
544
  return { kind: "retry", sha: mr.mergeCommit, ...(jobs.waves ? { stop: { op: jobs.waves.op, through: parsed.wave !== undefined && parsed.wave < jobs.waves.count ? parsed.wave : null } } : {}) };
545
545
  case "lock":
546
- case "unlock":
546
+ case "unlock": {
547
+ // #5061: the waves before merge with the reach line and no plan locks: the poll locks and unlocks here.
548
+ const bm = opts.beforeMerge;
549
+ if (!jobs.locks && jobs.wavesBeforeMerge?.locks !== undefined && bm?.lock && bm.unlock) {
550
+ const { lock, unlock } = bm;
551
+ return import("./op/before-merge-decide").then(async ({ decideLocksBeforeMerge }) => {
552
+ const done = await decideLocksBeforeMerge({ forge: "gitlab", pr: mr, user: note.author ?? "", base, kind: parsed.kind as "lock" | "unlock", words, git: bm.git, ...(bm.cwd ? { cwd: bm.cwd } : {}), lock, unlock });
553
+ return done.kind === "fail" ? { kind: "fail" as const, reason: done.reason } : { kind: "reply" as const, text: done.text };
554
+ });
555
+ }
547
556
  if (!jobs.locks) return { kind: "reply", text: notRunReply(words, parsed.kind, "gitlab") };
548
557
  if (parsed.kind === "lock" && !open) return { kind: "reply", text: `${at} is not open, so it takes no lock` };
549
558
  return { kind: "pipeline", ref: base, variables: { [parsed.kind === "lock" ? GITLAB_LOCK_PR_VAR : GITLAB_UNLOCK_PR_VAR]: iid }, doing: `${parsed.kind} the ${words.noun[1]} of ${at}` };
559
+ }
550
560
  case "agent":
551
561
  if (!jobs.agent) return { kind: "reply", text: notRunReply(words, "agent", "gitlab") };
552
562
  if (!open) return { kind: "reply", text: `${at} is not open, so the agent does not run` };
package/src/ci-product.ts CHANGED
@@ -13,7 +13,6 @@ import type { CiProductWords, CiProductWordsInput } from "./ci-product-words";
13
13
  import type { ProductMcpHook } from "./cli/mcp/product-tools";
14
14
  import type { ProductWaveHook } from "./op/op-waves-after-plan";
15
15
  import { OTLP_EXPORTER_FLOOR } from "./otlp";
16
- import { NEXT_RELEASE } from "./release-floors";
17
16
 
18
17
  /**
19
18
  * The first chant with the product pipeline (#4550): the words, the
@@ -278,33 +277,48 @@ export const PRODUCT_JOB_NAMES_FLOOR = "0.124.92";
278
277
  /**
279
278
  * The first chant whose Op waves run from the repository's default branch by the name the forge gives it at run time (#5032): the spec's `defaultBranch: true`, with or without `branches` beside it. Every job's guard admits the default branch (GitLab's `CI_DEFAULT_BRANCH`; on GitHub and Forgejo `CHANT_DEFAULT_BRANCH`, which each guarded job sets from `github.event.repository.default_branch`) and the named branches, every GitLab rule matches `$CI_DEFAULT_BRANCH` (the push's, the before-merge and the follow-on pipelines', the evidence, status, control and stale-notes jobs'), the GitHub and Forgejo jobs' `if:` names it when the product gives no `runIf`, and the stand-down counts a newer commit on it. Without it the waves run from `branches`, default `main`, as before.
280
279
  */
281
- export const OP_WAVES_DEFAULT_BRANCH_FLOOR = NEXT_RELEASE;
280
+ export const OP_WAVES_DEFAULT_BRANCH_FLOOR = "0.124.93";
282
281
 
283
282
  /**
284
283
  * The first chant whose Op waves generators take `firstWaveNeeds` (#5032): the product's own jobs, such as terragucci's `check`, that the first wave's own or deciding job (and before merge its plan job, and on GitLab its policy job) needs, so a push that fails the product's check applies nothing. GitHub and Forgejo: each must pass, or, in a dispatched run, not have run, and it goes with `runIf`; GitLab: optional needs, each to pass. Absent, the jobs render as before.
285
284
  */
286
- export const OP_WAVES_FIRST_WAVE_NEEDS_FLOOR = NEXT_RELEASE;
285
+ export const OP_WAVES_FIRST_WAVE_NEEDS_FLOOR = "0.124.93";
287
286
 
288
287
  /**
289
288
  * The first chant whose notify config takes `relayName` (#5033): the relay's name as people mention it in Teams, a plain value, which `sendNotify` (and so a wave's and a drift notice's messages) passes to the Teams card over the product's words' own, so a waiting wave's card spells out `reply @<name> approve <token>`. Without it the messages are as before.
290
289
  */
291
- export const NOTIFY_RELAY_NAME_FLOOR = NEXT_RELEASE;
290
+ export const NOTIFY_RELAY_NAME_FLOOR = "0.124.93";
292
291
 
293
292
  /**
294
293
  * The first chant whose Op waves resume keeps a product's names (#5034): `resumeWorkflowFile` names the GitHub and Forgejo resume workflow's file (such as terragucci's `terragucci-resume.yml`; default `<spec>-resume.yml`, refused on GitLab and when it is the waves' own file), and `jobNames` is called for the resume job with the role `resume` (GitHub and Forgejo `resume`, GitLab `<spec>-resume` by default). Without them the files render as before.
295
294
  */
296
- export const OP_WAVES_RESUME_NAMES_FLOOR = NEXT_RELEASE;
295
+ export const OP_WAVES_RESUME_NAMES_FLOOR = "0.124.93";
297
296
 
298
297
  /**
299
298
  * The first chant whose Op waves before merge take `beforeMerge.environment` (#5037): the forge environment the job after the last wave runs in, so a merge token scoped to it reaches that job alone (GitLab `environment: { name, action: access }`, GitHub `environment: <name>`; Forgejo refuses it), with the product pipeline's `wavesBeforeMerge.environment` carried through `waves.pipeline`. Without it the job is as before.
300
299
  */
301
- export const WAVES_BEFORE_MERGE_ENVIRONMENT_FLOOR = NEXT_RELEASE;
300
+ export const WAVES_BEFORE_MERGE_ENVIRONMENT_FLOOR = "0.124.93";
302
301
 
303
302
  /**
304
303
  * The first chant whose GitLab note poll keeps a product's names (#5038): the product pipeline's `noteCommandsJob` gives its job's name (default `note-commands`), its stage (default the job's name) and the variable and value a pipeline schedule starts it with (default `CHANT_NOTE_COMMANDS=1`), such as terragucci's `comments` job and `TERRAGUCCI_SCHEDULE=comments`, rendered in the job, its stage, its rule, its resource group and the workflow's rules. Refused on GitHub and Forgejo, without `noteCommands`, and on a name another job has. Without it the pipeline is as before.
305
304
  */
306
- export const NOTE_POLL_NAMES_FLOOR = NEXT_RELEASE;
307
- export { opWavesArtifacts, opWavesDispatchInputs, opWavesNamer, opWavesResumeWorkflowFile, opWavesWorkflowFile, type OpWavesArtifactNames, type OpWavesDispatchInput, type OpWavesJobNames, type OpWavesJobRef, type OpWavesJobRole, type OpWavesStageNames, type OpWavesStageRef } from "./op/op-waves-names";
305
+ export const NOTE_POLL_NAMES_FLOOR = "0.124.93";
306
+
307
+ /**
308
+ * The first chant whose Op waves generators take `commandToken` (#5044), GitHub and Forgejo: the jobs that run only the default branch's code (a push's wave, deciding, share and job group jobs; a split wave's gate and record jobs) hand their command step the job's token as `GITHUB_TOKEN`, so the spec's `respond` posts a refused wave's diff and a failed apply's triage and a product's hooks can read the forge, and ask for `permissions` beside chant's own. A split wave's plan and applying jobs never get it; GitLab refuses it. Without it no wave job holds a token, as before.
309
+ */
310
+ export const OP_WAVES_COMMAND_TOKEN_FLOOR = "0.124.94";
311
+
312
+ /**
313
+ * The first chant whose GitLab Op waves generator takes `cache` (#5045): the `cache:` entry or entries of each job that runs the wave's command (the wave's own, deciding, share and job group jobs, the policy job, a split wave's plan and applying jobs), such as terragucci's Terragrunt sources and providers cache. The gate and record jobs take none; GitHub and Forgejo refuse it, since a wave's `setup` step does this there. Without it no wave job has a cache, as before.
314
+ */
315
+ export const OP_WAVES_GITLAB_CACHE_FLOOR = "0.124.94";
316
+
317
+ /**
318
+ * The first chant whose Op waves generators take `controlGroup` and `resumeGroup` (#5053): the control job's group (GitHub and Forgejo `concurrency` with `cancel-in-progress: false`, GitLab `resource_group`), with `{commit}` standing for the commit it tells the control repo about, so a push's run and a resume's run send one dispatch per commit; and the GitLab resume job's `resource_group`. Without them neither job has a group, as before.
319
+ */
320
+ export const OP_WAVES_GROUPS_FLOOR = "0.124.94";
321
+ export { opWavesArtifacts, opWavesCommandToken, opWavesControlGroup, opWavesDispatchInputs, opWavesGitlabCache, opWavesNamer, opWavesResumeGroup, opWavesResumeWorkflowFile, opWavesWorkflowFile, type OpWavesArtifactNames, type OpWavesCommandToken, type OpWavesDispatchInput, type OpWavesJobNames, type OpWavesJobRef, type OpWavesJobRole, type OpWavesStageNames, type OpWavesStageRef } from "./op/op-waves-names";
308
322
 
309
323
  /**
310
324
  * Day-2 actions in the product pipeline (#4654): the `action` comment
@@ -517,6 +531,12 @@ export type { ProductMcpContext, ProductMcpHook } from "./cli/mcp/product-tools"
517
531
  * and `destructiveHint`, and a contribution's `annotations` add the rest.
518
532
  */
519
533
  export { MCP_TOOL_ANNOTATIONS_FLOOR, PRODUCT_MCP_PROPOSE_FLOOR, PRODUCT_TOOL_PROPOSE_WORDS } from "./cli/mcp/product-tools";
534
+ /** #5047: the Op waves keep the stopped-apply record (`approvals.remainder`, `approvals.spendStanding`), in place of a product's own. */
535
+ export { OP_WAVES_REMAINDER_FLOOR } from "./release-floors";
536
+ export { OP_WAVES_SPLIT_RESUME_FLOOR } from "./release-floors";
537
+ export { OP_WAVES_REMAINDER_PARITY_FLOOR } from "./release-floors";
538
+ /** #5061: the waves before merge lock and unlock on a comment by the reach line. */
539
+ export { WAVES_BEFORE_MERGE_LOCKS_FLOOR } from "./release-floors";
520
540
  export type { McpToolContribution, ToolAnnotations } from "./mcp/types";
521
541
  export {
522
542
  activeOtlp,
@@ -106,13 +106,14 @@ export async function beforeMergeDeps(forge: PrForge, jobs: CommentJobs, env: No
106
106
  const { checkPrRequires, unmetRequires } = await import("../../pr-requires");
107
107
  const { productStatusContext, activeProductWords } = await import("../../ci-product-words");
108
108
  const { LOCK_REACH_ENV, reachedTargets } = await import("../../lifecycle/reach-locks");
109
- const { takeTargetLocks, describeHeldTargetLocks } = await import("../../lifecycle/target-lock");
109
+ const { takeTargetLocks, releaseTargetLocks, describeHeldTargetLocks } = await import("../../lifecycle/target-lock");
110
110
  const { recordBeforeMerge } = await import("../../op/before-merge-store");
111
111
  const { setWaveStop } = await import("../../op/wave-stop");
112
112
  const { PR_APPLY_GATE } = await import("../../pr-loop");
113
113
  const words = activeProductWords();
114
114
  const line = env[LOCK_REACH_ENV];
115
115
  const name = (n: number) => (forge.kind === "gitlab" ? `!${n}` : `pull request ${n}`);
116
+ const gate = bm.locks?.gate ?? PR_APPLY_GATE;
116
117
  return {
117
118
  // The plan and apply statuses never hold the apply back: the plan status is asked for by name (#5003: the product plan's own names too).
118
119
  requires: async (pr, head) => unmetRequires(await checkPrRequires(forge, pr, head, { ignore: [...new Set([productStatusContext(words, "apply"), productStatusContext(words, "plan"), `${productStatusContext(words, "plan")}/`, ...bm.plan])], ...(bm.requires ? { only: bm.requires } : {}) })),
@@ -124,18 +125,23 @@ export async function beforeMergeDeps(forge: PrForge, jobs: CommentJobs, env: No
124
125
  // #4979's reach line says what the change reaches; the locks go up at stage apply, refused while another holds one.
125
126
  ...(line && line.trim()
126
127
  ? {
127
- lock: async (pr: number, head: string, base: string, by: string) => {
128
+ lock: async (pr: number, head: string, base: string, by: string, asked: "apply" | "lock" = "apply") => {
128
129
  const reached = reachedTargets({ forge: forge.kind, pr, head, base, line });
129
130
  if ("error" in reached) throw new Error(reached.error);
130
- if ("moved" in reached) return { ok: false as const, text: `${name(pr)} moved while this comment was read, so nothing is ${words.verbs.apply[1]}; comment again once its checks pass` };
131
+ const nothing = asked === "lock" ? "nothing is locked" : `nothing is ${words.verbs.apply[1]}`;
132
+ if ("moved" in reached) return { ok: false as const, text: `${name(pr)} moved while this comment was read, so ${nothing}; comment again once its checks pass` };
131
133
  const isOpen = forge.pullRequestOpen?.bind(forge);
132
- const r = await takeTargetLocks(bm.locks?.gate ?? PR_APPLY_GATE, reached.targets, { pr, by, at: new Date().toISOString(), stage: "apply", head }, { ...(isOpen ? { isOpen } : {}) });
134
+ const r = await takeTargetLocks(gate, reached.targets, { pr, by, at: new Date().toISOString(), stage: "apply", head }, { ...(isOpen ? { isOpen } : {}) });
133
135
  if (!r.ok) {
134
136
  const request = forge.kind === "gitlab" ? "merge request" : "pull request";
137
+ // #5061: a lock comment is refused as an apply is, with the holder named.
138
+ if (asked === "lock") return { ok: false as const, text: `${describeHeldTargetLocks(r.held, name)}, so ${name(pr)} takes no lock. It can once that ${request} merges or closes, or someone with write access unlocks it` };
135
139
  return { ok: false as const, text: `${describeHeldTargetLocks(r.held, name)}, so ${name(pr)} is not ${words.verbs.apply[1]}. It ${words.verbs.apply[0]}s once that ${request} merges or closes, or someone with write access unlocks it` };
136
140
  }
137
141
  return { ok: true as const, targets: r.taken };
138
142
  },
143
+ // #5061: `/<product> unlock` releases every lock the pull request holds in the reach line's lock file.
144
+ unlock: async (pr: number) => (await releaseTargetLocks(gate, pr)).released,
139
145
  }
140
146
  : {}),
141
147
  record: (d) => recordBeforeMerge(op, d),
@@ -131,9 +131,22 @@ async function runOpWaveJobCommand(ctx: CommandContext): Promise<number> {
131
131
  if (args.renderSpec) {
132
132
  const at = await import("../../op/op-waves-render-spec");
133
133
  const file = relative(process.cwd(), path);
134
- show = at.renderedSpecShow(file, at.commandSpecRender(at.opWavesSpecCommandFromEnv(), file, process.cwd()), gitShowAtBase);
135
- spec = at.renderOpWavesSpecFile({ specFile: file, base: args.base ?? "HEAD^1", cwd: process.cwd(), show, parse: parseOpWavesSpec }).spec;
136
- const missing = at.renderedJobMissing(spec, args.wave, job);
134
+ const command = at.opWavesSpecCommandFromEnv();
135
+ // #5046: with CHANT_WAVES_SPEC_RUNS=head the runs come from the applied commit; the gate and record jobs take them from the saved plan.
136
+ const runsAtHead = at.opWavesSpecRunsAtHead() && phase !== "gate" && phase !== "record";
137
+ const rendered = at.renderOpWavesJobSpec({
138
+ specFile: file,
139
+ base: args.base ?? "HEAD^1",
140
+ cwd: process.cwd(),
141
+ render: at.commandSpecRender(command, file, process.cwd()),
142
+ fallback: gitShowAtBase,
143
+ parse: parseOpWavesSpec,
144
+ ...(runsAtHead ? { runsAtHead, headRender: (baseSha: string) => at.commandSpecRender(command, file, process.cwd(), { [at.OP_WAVES_SPEC_BASE_ENV]: baseSha }) } : {}),
145
+ });
146
+ show = rendered.show;
147
+ spec = rendered.spec;
148
+ if (runsAtHead) console.error(`${spec.name}: the runs come from the spec rendered at ${rendered.sha.slice(0, 12)}, the applied commit; the rules from the one rendered at base`);
149
+ const missing = at.renderedJobMissing(spec, args.wave, job, rendered.at);
137
150
  if (missing) {
138
151
  console.error(`${missing}, so this job has nothing to apply`);
139
152
  return 0;
package/src/cli/main.ts CHANGED
@@ -618,7 +618,10 @@ Ops:
618
618
  --render-spec runs the command CHANT_WAVES_SPEC_COMMAND
619
619
  names (a JSON argv) with CHANT_WAVES_SPEC_AT set to
620
620
  the base, writes the spec it prints over --spec, and
621
- reads the rules at base from it (#4982).
621
+ reads the rules at base from it (#4982). With
622
+ CHANT_WAVES_SPEC_RUNS=head the spec it writes is
623
+ printed at HEAD, with CHANT_WAVES_SPEC_BASE set to
624
+ the base, and the rules still come from base (#5046).
622
625
  --phase plan|gate|apply|record: one of a wave's four
623
626
  jobs before merge (#4987). plan saves the plan and
624
627
  writes nothing to chant/lifecycle; gate decides the
@@ -455,7 +455,8 @@ export function productWavesSpec(spec: OpWavesSpec, wordsIn: CiProductWordsInput
455
455
  export function productPipelineJobs(forge: ForgeKind, env: string, options: ProductPipelineOptions): ProductPipelineJobs {
456
456
  const jobs: CiProductCommand[] = ["plan"];
457
457
  if (options.applyBeforeMerge || options.waves || options.componentWaves) jobs.push("apply");
458
- if (options.locks === "plan") jobs.push("lock", "unlock");
458
+ // #5061: the waves before merge with the reach line lock and unlock on a comment, in the comment job or the note poll.
459
+ if (options.locks === "plan" || (options.wavesBeforeMerge && options.productPlan?.reach)) jobs.push("lock", "unlock");
459
460
  if (options.agent) jobs.push("agent");
460
461
  if (options.commits?.length) jobs.push("commit");
461
462
  // #4654: the action command, answered by the product's own workflow (`actions`) or by the pipeline's action job.
@@ -507,7 +508,8 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
507
508
  const locks = prCommentLockJobs(forge, { locks: options.locks, words });
508
509
  if (locks.length > 0) out.locks = locks.map((job) => ({ ...job, ...defaultRunner }));
509
510
  // #4979: the product plan's reach says what the lock job locks.
510
- const reachLock = productPlan ? productPlanReachLock(forge, { ...prLoop, plan: productPlan }, words) : undefined;
511
+ // #5061: with the waves before merge the reach line is the comment job's (the note poll's), so it needs no locks: "plan".
512
+ const reachLock = productPlan ? productPlanReachLock(forge, { ...prLoop, plan: productPlan, ...(wavesBeforeMerge ? { beforeMerge: true } : {}) }, words) : undefined;
511
513
  if (reachLock) out.reachLock = reachLock;
512
514
  const action = prActionJob(forge, prLoop);
513
515
  if (action) out.action = { ...action, ...(prLoopRunner(options, "apply") !== undefined ? { runner: prLoopRunner(options, "apply")! } : {}) };
@@ -441,17 +441,24 @@ export interface ProductPlanReachLock {
441
441
  * --reach` through the words' bin, with the reach line as
442
442
  * {@link LOCK_REACH_ENV}. On GitHub and Forgejo it locks the pull request of
443
443
  * the event; on GitLab every open merge request into the branch.
444
+ *
445
+ * With `beforeMerge` (#5061, the product pipeline's `wavesBeforeMerge`) the
446
+ * reach line is also what the comment job (the note poll on GitLab) locks
447
+ * when it decides an apply or answers `/<product> lock`, so without
448
+ * `locks: "plan"` the reach is checked and no lock job is written.
444
449
  */
445
- export function productPlanReachLock(forge: ForgeKind, loop: Pick<PrLoopPipelineOptions, "locks" | "runners"> & { plan: Pick<ProductPlanOptions, "reach"> }, words: CiProductWords): ProductPlanReachLock | undefined {
450
+ export function productPlanReachLock(forge: ForgeKind, loop: Pick<PrLoopPipelineOptions, "locks" | "runners"> & { plan: Pick<ProductPlanOptions, "reach">; beforeMerge?: boolean }, words: CiProductWords): ProductPlanReachLock | undefined {
446
451
  const reach = loop.plan.reach;
447
452
  if (!reach) return undefined;
448
- if (loop.locks !== "plan") throw new Error("the product plan's reach says what the lock job locks, and there is none without locks: \"plan\"; set locks: \"plan\", or drop reach");
453
+ if (loop.locks !== "plan" && !loop.beforeMerge) throw new Error("the product plan's reach says what the lock job locks, and there is none without locks: \"plan\"; set locks: \"plan\", or drop reach");
449
454
  if (!reach.command.trim()) throw new Error("the product plan's reach.command is empty; give the line that prints the targets a change reaches");
450
455
  if (/[\r\n]/.test(reach.command)) throw new Error("the product plan's reach.command is one shell line");
451
456
  if (reach.gate !== undefined) {
452
457
  // The lock file's name, as ../lifecycle/target-lock.ts takes it.
453
458
  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(reach.gate)) throw new Error(`the product plan's reach.gate ${JSON.stringify(reach.gate)} is not a lock file name: letters, digits, '.', '_' and '-', starting with a letter or digit`);
454
459
  }
460
+ // #5061: the waves before merge lock by the reach line themselves; there is no plan lock job to write.
461
+ if (loop.locks !== "plan") return undefined;
455
462
  const gate = reach.gate !== undefined ? ["--gate", reach.gate] : [];
456
463
  const github = forge !== "gitlab";
457
464
  const line = github
@@ -56,12 +56,15 @@ export const FLOOR_ROWS: readonly FloorRow[] = [
56
56
  { name: "PR_HEAD_SHA_FLOOR", version: "0.124.92", gates: "The first chant whose pull request jobs on GitHub and Forgejo name the pull request's head, `github.event.pull_request.head.sha`, where `github.sha` named the merge preview (#5020): the product plan's pending step (`CHANT_PENDING_SHA`), the note job's `HEAD_SHA` (the product plan's, the pull request loop's and the product pipeline's) and the `env-post` job's.", issue: "#5020", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
57
57
  { name: "OP_WAVES_NAMES_FLOOR", version: "0.124.92", gates: "The first chant whose Op waves generators keep a product's own names (#5022): `jobNames` (every job they write: a wave's, deciding, share and job group jobs, a split wave's plan, gate, apply and record jobs, the policy and evidence jobs, the apply status, stale, before-merge done and control jobs; `needs:`, `if:`, `{job}` and `--from-job` follow it), `stageNames` (GitLab), `artifactNames` (the outcome, decision, saved plan and check claims artifacts, and the pattern a wave job downloads the earlier outcomes with), `workflowFile` (the generators' file and the follow-on's dispatch), `runIf` (the jobs go in the product's own workflow, each running on a push it admits or a before-merge or follow-on dispatch, with its own permissions; on GitLab joined to every rule) and `dispatchInputs` (the dispatch inputs' names, which the comment job's dispatch and the follow-on use), with `buildForgejoOpWavesDoc` for the Forgejo jobs, and whose product pipeline's `wavesBeforeMerge` takes `workflowFile` and `dispatchInputs`.", issue: "#5022", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
58
58
  { name: "PRODUCT_JOB_NAMES_FLOOR", version: "0.124.92", gates: "The first chant whose product pipeline names its comment job and its waves' jobs as the product does (#5027): `commentJob: { jobName }` (default `comment`, such as terragucci's `apply-comment`), refused when another job of the workflow has the name, and `wavesJobNames`, the Op waves generators' `jobNames`, which `waves.pipeline` carries to the generator and `waves.jobs` takes, and under which the comment job's re-run of a merged pull request's apply looks for the waves' jobs (`CHANT_COMMENT_JOBS` `applyJobs`, `rerunApplyJobs`), so terragucci's `apply-wave-<k>`, `-share-<n>`, group jobs and `apply-rest` run again.", issue: "#5027", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
59
- { name: "OP_WAVES_DEFAULT_BRANCH_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves run from the repository's default branch by the name the forge gives it at run time (#5032): the spec's `defaultBranch: true`, with or without `branches` beside it.", issue: "#5032", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
60
- { name: "OP_WAVES_FIRST_WAVE_NEEDS_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves generators take `firstWaveNeeds` (#5032): the product's own jobs, such as terragucci's `check`, that the first wave's own or deciding job (and before merge its plan job, and on GitLab its policy job) needs, so a push that fails the product's check applies nothing.", issue: "#5032", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
61
- { name: "NOTIFY_RELAY_NAME_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose notify config takes `relayName` (#5033): the relay's name as people mention it in Teams, a plain value, which `sendNotify` (and so a wave's and a drift notice's messages) passes to the Teams card over the product's words' own, so a waiting wave's card spells out `reply @<name> approve <token>`.", issue: "#5033", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
62
- { name: "OP_WAVES_RESUME_NAMES_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves resume keeps a product's names (#5034): `resumeWorkflowFile` names the GitHub and Forgejo resume workflow's file (such as terragucci's `terragucci-resume.yml`; default `<spec>-resume.yml`, refused on GitLab and when it is the waves' own file), and `jobNames` is called for the resume job with the role `resume` (GitHub and Forgejo `resume`, GitLab `<spec>-resume` by default).", issue: "#5034", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
63
- { name: "WAVES_BEFORE_MERGE_ENVIRONMENT_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves before merge take `beforeMerge.environment` (#5037): the forge environment the job after the last wave runs in, so a merge token scoped to it reaches that job alone (GitLab `environment: { name, action: access }`, GitHub `environment: <name>`; Forgejo refuses it), with the product pipeline's `wavesBeforeMerge.environment` carried through `waves.pipeline`.", issue: "#5037", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
64
- { name: "NOTE_POLL_NAMES_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose GitLab note poll keeps a product's names (#5038): the product pipeline's `noteCommandsJob` gives its job's name (default `note-commands`), its stage (default the job's name) and the variable and value a pipeline schedule starts it with (default `CHANT_NOTE_COMMANDS=1`), such as terragucci's `comments` job and `TERRAGUCCI_SCHEDULE=comments`, rendered in the job, its stage, its rule, its resource group and the workflow's rules.", issue: "#5038", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
59
+ { name: "OP_WAVES_DEFAULT_BRANCH_FLOOR", version: "0.124.93", gates: "The first chant whose Op waves run from the repository's default branch by the name the forge gives it at run time (#5032): the spec's `defaultBranch: true`, with or without `branches` beside it.", issue: "#5032", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
60
+ { name: "OP_WAVES_FIRST_WAVE_NEEDS_FLOOR", version: "0.124.93", gates: "The first chant whose Op waves generators take `firstWaveNeeds` (#5032): the product's own jobs, such as terragucci's `check`, that the first wave's own or deciding job (and before merge its plan job, and on GitLab its policy job) needs, so a push that fails the product's check applies nothing.", issue: "#5032", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
61
+ { name: "NOTIFY_RELAY_NAME_FLOOR", version: "0.124.93", gates: "The first chant whose notify config takes `relayName` (#5033): the relay's name as people mention it in Teams, a plain value, which `sendNotify` (and so a wave's and a drift notice's messages) passes to the Teams card over the product's words' own, so a waiting wave's card spells out `reply @<name> approve <token>`.", issue: "#5033", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
62
+ { name: "OP_WAVES_RESUME_NAMES_FLOOR", version: "0.124.93", gates: "The first chant whose Op waves resume keeps a product's names (#5034): `resumeWorkflowFile` names the GitHub and Forgejo resume workflow's file (such as terragucci's `terragucci-resume.yml`; default `<spec>-resume.yml`, refused on GitLab and when it is the waves' own file), and `jobNames` is called for the resume job with the role `resume` (GitHub and Forgejo `resume`, GitLab `<spec>-resume` by default).", issue: "#5034", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
63
+ { name: "WAVES_BEFORE_MERGE_ENVIRONMENT_FLOOR", version: "0.124.93", gates: "The first chant whose Op waves before merge take `beforeMerge.environment` (#5037): the forge environment the job after the last wave runs in, so a merge token scoped to it reaches that job alone (GitLab `environment: { name, action: access }`, GitHub `environment: <name>`; Forgejo refuses it), with the product pipeline's `wavesBeforeMerge.environment` carried through `waves.pipeline`.", issue: "#5037", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
64
+ { name: "NOTE_POLL_NAMES_FLOOR", version: "0.124.93", gates: "The first chant whose GitLab note poll keeps a product's names (#5038): the product pipeline's `noteCommandsJob` gives its job's name (default `note-commands`), its stage (default the job's name) and the variable and value a pipeline schedule starts it with (default `CHANT_NOTE_COMMANDS=1`), such as terragucci's `comments` job and `TERRAGUCCI_SCHEDULE=comments`, rendered in the job, its stage, its rule, its resource group and the workflow's rules.", issue: "#5038", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
65
+ { name: "OP_WAVES_COMMAND_TOKEN_FLOOR", version: "0.124.94", gates: "The first chant whose Op waves generators take `commandToken` (#5044), GitHub and Forgejo: the jobs that run only the default branch's code (a push's wave, deciding, share and job group jobs; a split wave's gate and record jobs) hand their command step the job's token as `GITHUB_TOKEN`, so the spec's `respond` posts a refused wave's diff and a failed apply's triage and a product's hooks can read the forge, and ask for `permissions` beside chant's own.", issue: "#5044", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
66
+ { name: "OP_WAVES_GITLAB_CACHE_FLOOR", version: "0.124.94", gates: "The first chant whose GitLab Op waves generator takes `cache` (#5045): the `cache:` entry or entries of each job that runs the wave's command (the wave's own, deciding, share and job group jobs, the policy job, a split wave's plan and applying jobs), such as terragucci's Terragrunt sources and providers cache.", issue: "#5045", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
67
+ { name: "OP_WAVES_GROUPS_FLOOR", version: "0.124.94", gates: "The first chant whose Op waves generators take `controlGroup` and `resumeGroup` (#5053): the control job's group (GitHub and Forgejo `concurrency` with `cancel-in-progress: false`, GitLab `resource_group`), with `{commit}` standing for the commit it tells the control repo about, so a push's run and a resume's run send one dispatch per commit; and the GitLab resume job's `resource_group`.", issue: "#5053", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
65
68
  { name: "PRODUCT_ACTIONS_FLOOR", version: "0.124.58", gates: "Day-2 actions in the product pipeline (#4654): the `action` comment command counted as answered by the product's own workflow (`productPipelineJobs(forge, env, { words, actions: true })`), or the pipeline's own action job (`actionJob`, `build --pr-loop --action-job`), which answers the comment and a dispatch with a member and an action input, and runs the product's action verb with `--from-event`.", issue: "#4654", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
66
69
  { name: "APPROVAL_STATUS_FLOOR", version: "0.124.56", gates: "The approval status before merge (#4630): under a `pr-review` wave, the op waves generators add a job that posts `<product>/approval` on each open pull request's head.", issue: "#4630", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
67
70
  { name: "APPROVAL_STATUS_PULL_REQUEST_FLOOR", version: "0.124.56", gates: "The approval status for `pull-request` waves too (#4630, 2026-10-28 ruling): the generators add the record-plans and approval-status jobs for a spec whose waves take the pull request's own approval, and the status reads that approval's coverage of each wave's change set.", issue: "#4630", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
@@ -234,6 +237,12 @@ export const FLOOR_ROWS: readonly FloorRow[] = [
234
237
  { name: "BEFORE_MERGE_REF_GATE_FLOOR", version: "0.124.89", gates: "The first chant whose `chant components pr-apply --before-merge` waits for the ref gate's status: the status the policy at base sets for the target branch is passed as `require` to the `checks` require (#4966).", issue: "#4966", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
235
238
  { name: "TARGET_SIGNED_CHECKS_FLOOR", version: "0.124.89", gates: "The first chant whose product plan with `targets` and `evidence` signs each target's plan job as `plan:<target>` and `policy:<target>` (`ci evidence sign --member <target>`, `targetEvidenceCheck`, `productPlanEvidenceChecks`), and whose `refGateInitPlan` takes `targets` and names those checks in the `refs` rule (#4978).", issue: "#4978", file: "release-floors.ts", modules: ["@intentius/chant/ci-evidence-jobs","@intentius/chant/ref-gate-init","@intentius/chant/release-floors"] },
236
239
  { name: "RUNTIME_WAVES_SPEC_FLOOR", version: "0.124.89", gates: "The first chant whose Op waves generators take `renderSpec` (the wave jobs run `chant run wave --render-spec`, and `CHANT_WAVES_SPEC_COMMAND` names the product command that prints the spec at the commit in `CHANT_WAVES_SPEC_AT`), so a product whose spec is built from its config at base renders its wave jobs, policy step, evidence job and cloud trade through chant (#4982).", issue: "#4982", file: "release-floors.ts", modules: ["@intentius/chant/op","@intentius/chant/op/index","@intentius/chant/op/op-waves-render-spec","@intentius/chant/release-floors"] },
240
+ { name: "RUNTIME_WAVES_SPEC_RUNS_AT_HEAD_FLOOR", version: "0.124.94", gates: "The first chant whose Op waves `renderSpec` takes `runsAtHead` (the jobs carry `CHANT_WAVES_SPEC_RUNS=head`): the job's own spec is rendered at the applied commit, with `CHANT_WAVES_SPEC_BASE` set to the base commit beside `CHANT_WAVES_SPEC_AT`, so the runs a change adds apply at its merge, while the gate policy, holds, hooks and evidence rules still come from the render at base (#5046).", issue: "#5046", file: "release-floors.ts", modules: ["@intentius/chant/op","@intentius/chant/op/index","@intentius/chant/op/op-waves-render-spec","@intentius/chant/release-floors"] },
241
+ { name: "OP_WAVES_REMAINDER_FLOOR", version: "0.124.94", gates: "The first chant whose Op waves keep the record of an apply under an approval themselves (#5047): with `approvals.spend`, `approvals.remainder` writes each change the approved plans make, the commit and the run on the applied line (a split wave's gate job writes it), the job that applies the whole wave or the record job writes how the apply ended, and a wave run again at that commit applies the rest under the same approval when its plans make only changes the stopped apply did not finish; a wave that plans no change closes a stopped apply, and `approvals.spendStanding` spends an approval of the digest a wave its gate let through applies.", issue: "#5047", file: "release-floors.ts", modules: ["@intentius/chant/ci-product","@intentius/chant/op","@intentius/chant/op/index","@intentius/chant/op/op-waves-remainder","@intentius/chant/release-floors"] },
242
+ { name: "OP_WAVES_SPLIT_RESUME_FLOOR", version: "0.124.94", gates: "The first chant whose `chant run resume` starts a killed split apply again on GitLab and Forgejo (#5052): under `approvals.remainder` the gate job's applied line names its run there too, GitLab's with the wave's applying and record jobs by name (`retry`), which the resume retries, and Forgejo's with the run's dispatch inputs (`inputs`), which the resume dispatches with, so the new run applies the rest at the same decided head or commit.", issue: "#5052", file: "release-floors.ts", modules: ["@intentius/chant/ci-product","@intentius/chant/op/op-waves-split-resume","@intentius/chant/release-floors"] },
243
+ { name: "OP_WAVES_REMAINDER_PARITY_FLOOR", version: "0.124.94", gates: "The first chant whose `approvals.remainder` resumes the waves terragucci's own records resume (#5056): the terraform step gives a live choudoufu root's plan (`live-plan-set`) its `resourceDigests`, so its applied line names the changes, and the cover leaves out the cost member `(monthly cost)`, whose digest follows from the plans, on both sides.", issue: "#5056", file: "release-floors.ts", modules: ["@intentius/chant/ci-product","@intentius/chant/op/op-waves-remainder","@intentius/chant/release-floors"] },
244
+ { name: "OP_WAVES_CONTROL_BEFORE_MERGE_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves generators, in a product's workflow (`runIf`) with `beforeMerge` and a spec `control`, run the control job on the default branch's push, outside the product's `runIf` and after its `firstWaveNeeds` jobs, and tell the control repo the waves applied at the pushed commit without adding up outcomes, on GitHub, Forgejo and GitLab (#5060).", issue: "#5060", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
245
+ { name: "WAVES_BEFORE_MERGE_LOCKS_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose waves before merge lock and unlock on a comment by the product plan's reach line (#5061): with `wavesBeforeMerge` and `productPlan.reach`, and no `locks: \"plan\"`, the comment job (GitHub, Forgejo) and the note poll (GitLab, `chantNoteRuns`) answer `/<product> lock` on an open pull request by taking the locks of what the reach line prints at stage `apply` in `_locks/<reach.gate>.json` without applying (`decideLocksBeforeMerge`), refused with the holder named, and `/<product> unlock` by releasing the pull request's locks; and the product plan takes `reach` without `locks: \"plan\"` under `wavesBeforeMerge`, writing no reach lock job.", issue: "#5061", file: "release-floors.ts", modules: ["@intentius/chant/ci-product","@intentius/chant/release-floors"] },
237
246
  { name: "GITLAB_WAVE_EVIDENCE_RETRY_FLOOR", version: "0.124.89", gates: "The first chant whose `chant run resume` (`resumeGateRun`) on GitLab retries a wave job's `<wave job>-evidence` with the wave job when the evidence job already ran, and whose `ci evidence sign --from-job` waits for a job it reads to finish, so a resumed wave's evidence job signs from the new try (#4978).", issue: "#4978", file: "release-floors.ts", modules: ["@intentius/chant/ci-evidence-jobs","@intentius/chant/release-floors"] },
238
247
  { name: "TERRAFORM_COMMAND_TRACE_FLOOR", version: "0.124.91", gates: "The first chant whose terraform lexicon's engine runs carry what a product's own command tracing read: `runBinary` and the engine runner's `exec` and `execSync` answer stderr apart (`Ran.stderr`) and a spawn failure's message (`Ran.error`), a hook's `after` gets a binary that could not be started as a null code with `error`, `commandTrace` ends that span with the message, and `composeCommandHooks` runs a product's own hook and `commandTrace` as one `onCommand` (#5007).", issue: "#5007", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
239
248
  { name: "RUN_EVENT_FLOOR", version: "0.124.28", gates: "The first chant that writes contract version 1 of the run-event stream.", file: "run-event.ts", modules: ["@intentius/chant","@intentius/chant/index","@intentius/chant/run-event"] },