@feigi/fleet-ctl 0.0.0

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 (245) hide show
  1. package/.claude-plugin/plugin.json +9 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +18 -0
  4. package/agents/fleet-finisher.agent.md +7 -0
  5. package/agents/fleet-implementer-alt.agent.md +210 -0
  6. package/agents/fleet-implementer.agent.md +210 -0
  7. package/agents/fleet-merge-bot.agent.md +7 -0
  8. package/agents/fleet-review-comments.agent.md +40 -0
  9. package/agents/fleet-review-correctness.agent.md +43 -0
  10. package/agents/fleet-review-runner.agent.md +73 -0
  11. package/agents/fleet-review-silent-failure.agent.md +49 -0
  12. package/agents/fleet-review-simplify.agent.md +46 -0
  13. package/agents/fleet-review-snapshot.agent.md +24 -0
  14. package/agents/fleet-review-tests.agent.md +46 -0
  15. package/agents/fleet-review-types.agent.md +41 -0
  16. package/agents/fleet-review-verifier.agent.md +29 -0
  17. package/commands/review-and-fix.md +98 -0
  18. package/commands/run-merge-bot.md +357 -0
  19. package/commands/run-team-help.md +17 -0
  20. package/package.json +23 -0
  21. package/scripts/agent-test-dir-prose.test.mjs +59 -0
  22. package/scripts/agent-test.test.mjs +1636 -0
  23. package/scripts/ambient-git-vars-mjs-prose.test.mjs +354 -0
  24. package/scripts/ambient-git-vars-prose.test.mjs +192 -0
  25. package/scripts/ancestry-check-position-prose.test.mjs +175 -0
  26. package/scripts/apply-ruleset.test.mjs +420 -0
  27. package/scripts/arg-header-probes-prose.test.mjs +393 -0
  28. package/scripts/arg.mjs +600 -0
  29. package/scripts/arg.test.mjs +1354 -0
  30. package/scripts/board-cli.test.mjs +694 -0
  31. package/scripts/board-identity.test.mjs +429 -0
  32. package/scripts/board-liveness-banner.test.mjs +119 -0
  33. package/scripts/board-prev-shape.test.mjs +229 -0
  34. package/scripts/board-tryparse-null.test.mjs +119 -0
  35. package/scripts/board.html +471 -0
  36. package/scripts/board.mjs +2037 -0
  37. package/scripts/board.test.mjs +3086 -0
  38. package/scripts/brief-after-cut-prose.test.mjs +53 -0
  39. package/scripts/candidates-exit3-prose.test.mjs +302 -0
  40. package/scripts/candidates.mjs +674 -0
  41. package/scripts/candidates.test.mjs +2101 -0
  42. package/scripts/caveat-unification-prose.test.mjs +98 -0
  43. package/scripts/ci-comment-rot-prose.test.mjs +2025 -0
  44. package/scripts/ci-completes-premise-prose.test.mjs +257 -0
  45. package/scripts/ci-state-prose.test.mjs +113 -0
  46. package/scripts/ci-state.mjs +761 -0
  47. package/scripts/ci-state.test.mjs +1640 -0
  48. package/scripts/ci-vacuous-green.test.mjs +368 -0
  49. package/scripts/citation-sweep-prose.test.mjs +1572 -0
  50. package/scripts/claim-lifecycle.test.mjs +185 -0
  51. package/scripts/claim-ticket.sh +417 -0
  52. package/scripts/claim-ticket.test.mjs +1121 -0
  53. package/scripts/closing-keyword-prose.test.mjs +193 -0
  54. package/scripts/cockpit-launch-idempotent-prose.test.mjs +165 -0
  55. package/scripts/cockpit-tick-nonblocking.test.mjs +210 -0
  56. package/scripts/compute-board.mjs +579 -0
  57. package/scripts/compute-board.test.mjs +1060 -0
  58. package/scripts/compute-spend.mjs +329 -0
  59. package/scripts/compute-spend.test.mjs +451 -0
  60. package/scripts/cross-repo-citation-prose.test.mjs +156 -0
  61. package/scripts/cwd-isolation-pins.mjs +83 -0
  62. package/scripts/dedupe-guard-prose.test.mjs +243 -0
  63. package/scripts/derive-testcmd.sh +239 -0
  64. package/scripts/derive-testcmd.test.mjs +380 -0
  65. package/scripts/diff-stats.mjs +231 -0
  66. package/scripts/diff-stats.test.mjs +408 -0
  67. package/scripts/dispatch-block-golden-prose.test.mjs +1024 -0
  68. package/scripts/dispatch-block-pins-prose.test.mjs +615 -0
  69. package/scripts/drop-merged-label.sh +173 -0
  70. package/scripts/drop-merged-label.test.mjs +480 -0
  71. package/scripts/expected-jobs-prose.test.mjs +80 -0
  72. package/scripts/filing-bar-seat-prose.test.mjs +242 -0
  73. package/scripts/filing-claim-bar-prose.test.mjs +166 -0
  74. package/scripts/finisher-dispatch-premise-prose.test.mjs +312 -0
  75. package/scripts/finisher-halt-prose.test.mjs +106 -0
  76. package/scripts/finisher-name-prose.test.mjs +134 -0
  77. package/scripts/finisher-own-tree-prose.test.mjs +285 -0
  78. package/scripts/finisher-pin-race-prose.test.mjs +339 -0
  79. package/scripts/fix-applier-correction-rules-prose.test.mjs +201 -0
  80. package/scripts/fix-applier-result-file-prose.test.mjs +100 -0
  81. package/scripts/fleet-bootstrap +155 -0
  82. package/scripts/fleet-heartbeat.mjs +272 -0
  83. package/scripts/fleet-heartbeat.test.mjs +450 -0
  84. package/scripts/fleet-provenance +207 -0
  85. package/scripts/fleet-provenance.test.mjs +64 -0
  86. package/scripts/fleet-run +148 -0
  87. package/scripts/fleet-run.test.mjs +90 -0
  88. package/scripts/fleet-state.mjs +400 -0
  89. package/scripts/fleet-state.test.mjs +373 -0
  90. package/scripts/fleet-tick-prose.test.mjs +299 -0
  91. package/scripts/fleet-tick.mjs +832 -0
  92. package/scripts/fleet-tick.test.mjs +1332 -0
  93. package/scripts/force-with-lease-reason-prose.test.mjs +184 -0
  94. package/scripts/frontmatter-allowlist.json +64 -0
  95. package/scripts/frontmatter-check.mjs +256 -0
  96. package/scripts/frontmatter-check.test.mjs +436 -0
  97. package/scripts/git-env.mjs +124 -0
  98. package/scripts/git-env.test.mjs +149 -0
  99. package/scripts/git-status-untracked-mode-sweep.test.mjs +216 -0
  100. package/scripts/gone-walk.test.mjs +213 -0
  101. package/scripts/gp-sep-invariant-prose.test.mjs +188 -0
  102. package/scripts/head-moved-after-label-prose.test.mjs +233 -0
  103. package/scripts/immutable-body-claim-prose.test.mjs +413 -0
  104. package/scripts/implementer-model-tier.test.mjs +643 -0
  105. package/scripts/inflight-citation-prose.test.mjs +144 -0
  106. package/scripts/inflight-exit2-prose.test.mjs +81 -0
  107. package/scripts/inflight-probe-guard-prose.test.mjs +109 -0
  108. package/scripts/inflight-scan-scope-prose.test.mjs +57 -0
  109. package/scripts/inflight.sh +1106 -0
  110. package/scripts/inflight.test.mjs +2984 -0
  111. package/scripts/injection-control-prose.test.mjs +404 -0
  112. package/scripts/install-root-audit.test.mjs +464 -0
  113. package/scripts/instrument-check-prose.test.mjs +235 -0
  114. package/scripts/instruments.sh +394 -0
  115. package/scripts/instruments.test.mjs +787 -0
  116. package/scripts/issue-tracker-prose.test.mjs +71 -0
  117. package/scripts/json.sh +248 -0
  118. package/scripts/json.test.mjs +364 -0
  119. package/scripts/ledger-dispatch.test.mjs +516 -0
  120. package/scripts/ledger-grammar.mjs +85 -0
  121. package/scripts/ledger-grammar.test.mjs +142 -0
  122. package/scripts/ledger-read-require-file.test.mjs +197 -0
  123. package/scripts/ledger.mjs +1753 -0
  124. package/scripts/ledger.test.mjs +3554 -0
  125. package/scripts/line-distance-prose.test.mjs +245 -0
  126. package/scripts/liveness-rationale-prose.test.mjs +83 -0
  127. package/scripts/locale-pin-prose.test.mjs +189 -0
  128. package/scripts/member-outcome-prose.test.mjs +167 -0
  129. package/scripts/member-outcomes-header.test.mjs +148 -0
  130. package/scripts/member-outcomes-prose.test.mjs +63 -0
  131. package/scripts/member-outcomes.mjs +231 -0
  132. package/scripts/member-outcomes.test.mjs +507 -0
  133. package/scripts/member-prompt-prose.test.mjs +161 -0
  134. package/scripts/member-record.mjs +605 -0
  135. package/scripts/member-record.test.mjs +516 -0
  136. package/scripts/member-write-guard.mjs +279 -0
  137. package/scripts/member-write-guard.test.mjs +211 -0
  138. package/scripts/merge-commit-probe-prose.test.mjs +122 -0
  139. package/scripts/merge-gate.mjs +262 -0
  140. package/scripts/merge-gate.test.mjs +613 -0
  141. package/scripts/muted-git-guard-sweep.test.mjs +493 -0
  142. package/scripts/net-ssh-precedence-prose.test.mjs +91 -0
  143. package/scripts/net-watchdog-prose.test.mjs +79 -0
  144. package/scripts/net.sh +409 -0
  145. package/scripts/net.test.mjs +211 -0
  146. package/scripts/no-ci-gate-prose.test.mjs +108 -0
  147. package/scripts/no-undo-audit.sh +1134 -0
  148. package/scripts/no-undo-audit.test.mjs +3965 -0
  149. package/scripts/no-wave.test.mjs +138 -0
  150. package/scripts/node-floor-sweep.test.mjs +611 -0
  151. package/scripts/pointer-target-prose.test.mjs +186 -0
  152. package/scripts/pr-overlap.mjs +417 -0
  153. package/scripts/pr-overlap.test.mjs +695 -0
  154. package/scripts/printf-die-sweep.test.mjs +384 -0
  155. package/scripts/prompt-renderer.mjs +39 -0
  156. package/scripts/prompt-renderer.test.mjs +68 -0
  157. package/scripts/prose-pin.mjs +808 -0
  158. package/scripts/prose-pin.test.mjs +1034 -0
  159. package/scripts/prove-merge.sh +228 -0
  160. package/scripts/prove-merge.test.mjs +995 -0
  161. package/scripts/pull-table-relabel-prose.test.mjs +60 -0
  162. package/scripts/quiet-payload-prose.test.mjs +222 -0
  163. package/scripts/reap.sh +1768 -0
  164. package/scripts/reap.test.mjs +4395 -0
  165. package/scripts/reaping-prose.test.mjs +159 -0
  166. package/scripts/refuter-scratch-prose.test.mjs +135 -0
  167. package/scripts/release-label-required-prose.test.mjs +71 -0
  168. package/scripts/release-label-split-prose.test.mjs +169 -0
  169. package/scripts/release-ticket.sh +1716 -0
  170. package/scripts/release-ticket.test.mjs +5106 -0
  171. package/scripts/renovate-release-contract.test.mjs +379 -0
  172. package/scripts/repo-root.mjs +544 -0
  173. package/scripts/repo-root.test.mjs +873 -0
  174. package/scripts/reporter-output-rule-prose.test.mjs +208 -0
  175. package/scripts/review-agent-report-only.test.mjs +49 -0
  176. package/scripts/review-core-cwd-isolation.test.mjs +374 -0
  177. package/scripts/review-core-reads.test.mjs +478 -0
  178. package/scripts/review-core-refuter-scratch.test.mjs +148 -0
  179. package/scripts/review-core-snapshot-path.test.mjs +777 -0
  180. package/scripts/review-core-specialist-scratch.test.mjs +189 -0
  181. package/scripts/review-core-testcmd.test.mjs +288 -0
  182. package/scripts/review-core-unrun.test.mjs +530 -0
  183. package/scripts/review-core-unverified-discriminant.test.mjs +208 -0
  184. package/scripts/review-core.mjs +1028 -0
  185. package/scripts/review-eval-resolver-path.test.mjs +55 -0
  186. package/scripts/review-eval.mjs +197 -0
  187. package/scripts/review-host-fixture.mjs +73 -0
  188. package/scripts/review-in-run-retry.test.mjs +187 -0
  189. package/scripts/review-no-vendor-dispatch.test.mjs +45 -0
  190. package/scripts/review-path-default.test.mjs +796 -0
  191. package/scripts/review-runner-spawns.test.mjs +93 -0
  192. package/scripts/review-runner.test.mjs +155 -0
  193. package/scripts/review-tier-audit.test.mjs +140 -0
  194. package/scripts/run-artifact-pr-prose.test.mjs +341 -0
  195. package/scripts/run-merge-bot-prose.test.mjs +1391 -0
  196. package/scripts/scratch-partition-invariant-prose.test.mjs +74 -0
  197. package/scripts/scripts-path-citation-sweep.test.mjs +73 -0
  198. package/scripts/section-between-guard-prose.test.mjs +378 -0
  199. package/scripts/select-dimensions.test.mjs +674 -0
  200. package/scripts/shared-refusal.test.mjs +388 -0
  201. package/scripts/shell-traps-prose.test.mjs +507 -0
  202. package/scripts/shortlist.mjs +355 -0
  203. package/scripts/shortlist.test.mjs +366 -0
  204. package/scripts/slow-transport.mjs +72 -0
  205. package/scripts/snapshot-repo.test.mjs +772 -0
  206. package/scripts/snapshot-runner-audience-prose.test.mjs +129 -0
  207. package/scripts/spend-view.test.mjs +312 -0
  208. package/scripts/staleness-qualifier-prose.test.mjs +251 -0
  209. package/scripts/staleness-verdict-prose.test.mjs +142 -0
  210. package/scripts/staleness.mjs +414 -0
  211. package/scripts/staleness.test.mjs +893 -0
  212. package/scripts/stalled-member-liveness-prose.test.mjs +219 -0
  213. package/scripts/stash-prohibition-prose.test.mjs +313 -0
  214. package/scripts/strip-comments.mjs +44 -0
  215. package/scripts/tier-check.mjs +468 -0
  216. package/scripts/tier-check.test.mjs +726 -0
  217. package/scripts/tier-guard-gate-prose.test.mjs +216 -0
  218. package/scripts/tier-outcomes-header.test.mjs +586 -0
  219. package/scripts/tier-outcomes.mjs +441 -0
  220. package/scripts/tier-outcomes.test.mjs +342 -0
  221. package/scripts/tier-roles.mjs +250 -0
  222. package/scripts/tier-roles.test.mjs +316 -0
  223. package/scripts/tracker-block-copy-prose.test.mjs +288 -0
  224. package/scripts/triage-labels-gloss-prose.test.mjs +97 -0
  225. package/scripts/unattended-git-sweep.test.mjs +142 -0
  226. package/scripts/verify-sha-exit2-prose.test.mjs +269 -0
  227. package/scripts/verify-sha.sh +117 -0
  228. package/scripts/verify-sha.test.mjs +693 -0
  229. package/scripts/watcher-degraded-block.test.mjs +372 -0
  230. package/scripts/watcher-key-prose.test.mjs +106 -0
  231. package/scripts/within-run-pair-prose.test.mjs +208 -0
  232. package/scripts/worktree-audit.sh +482 -0
  233. package/scripts/worktree-audit.test.mjs +1407 -0
  234. package/scripts/worktree-head-prose.test.mjs +276 -0
  235. package/scripts/worktree-listing-sweep.test.mjs +217 -0
  236. package/scripts/worktree-model-prose.test.mjs +216 -0
  237. package/scripts/worktree.sh +470 -0
  238. package/skills/next-ticket/SKILL.md +138 -0
  239. package/skills/run-team/SKILL.md +3603 -0
  240. package/skills/run-team/references/ci-and-staleness.md +75 -0
  241. package/skills/run-team/references/correction-tickets.md +37 -0
  242. package/skills/run-team/references/isolation.md +23 -0
  243. package/skills/run-team/references/member-lifecycle.md +73 -0
  244. package/skills/run-team/references/reaping.md +73 -0
  245. package/skills/sizing-a-ticket/SKILL.md +39 -0
@@ -0,0 +1,262 @@
1
+ #!/usr/bin/env node
2
+ // The merge bot's pre-merge gate as one read-only conjunction (#1800; spec
3
+ // docs/specs/2026-09-24-slot-based-fleet-loop-design.md § 5, ADR 0012
4
+ // Decision 3).
5
+ //
6
+ // merge-gate.mjs --pr <n> --pre <sha> [--post <sha>] [--out <path>]
7
+ //
8
+ // Runs, in order, `instruments.sh --repo <main checkout>`, `gh pr view <n>
9
+ // --json labels,reviewDecision,headRefOid` and `ci-state.mjs --pr <n>
10
+ // --declare-no-ci`, then answers the conjunction. All three run on every
11
+ // call, whatever the earlier ones said, so the JSON line carries every field
12
+ // that was read. It never merges, labels, rebases or waits: the merge bot
13
+ // runs it once before any wait and once immediately before `gh pr merge`, and
14
+ // merges only on that second exit 0.
15
+ //
16
+ // `--pre` is the labelled head, `--post` the head the bot's own
17
+ // `gh pr update-branch --rebase` produced; omitted, it is `--pre` (the
18
+ // no-rebase path). `--out` also writes the JSON line to that path, creating
19
+ // its directory. Omitted, the line goes to stdout only: the path the merge bot
20
+ // uses, `<scratch>/pr<N>/merge-bot-<n>/ci.json`, names a scratch root and a
21
+ // member number only the bot knows, so the bot passes it and this script never
22
+ // guesses it (controller ruling on #1800).
23
+ //
24
+ // Stdout: exactly one JSON line, `{pr, verdict, reason, head, pre, post,
25
+ // behind, instruments, ci}`. Stderr: the children's own diagnostics, passed
26
+ // straight through and never folded into stdout.
27
+ //
28
+ // Exit vocabulary — the same three-way contract as inflight.sh, prove-merge.sh
29
+ // and staleness.mjs:
30
+ //
31
+ // 0 mergeable every check holds
32
+ // 1 blocked a verdict about this PR, now → skip it, report
33
+ // `<reason>-#<pr>`
34
+ // 2 unknown a finding about the tree, the tooling → stop and report
35
+ // or the API — never about the PR
36
+ //
37
+ // The rows, checked in this order; the first that fails is the `reason`. A
38
+ // row whose input could not be read is skipped, and that input's own
39
+ // could-not-evaluate row fires further down instead:
40
+ //
41
+ // label `ready-to-merge` absent 1 label-pulled
42
+ // reviewDecision CHANGES_REQUESTED 1 changes-requested
43
+ // PR head not in {pre, post} 1 head-moved-after-label
44
+ // ci-state exit 1 (not-green) 1 ci:<first entry of ci.reasons>
45
+ // ci.behind > 0 1 behind:<n>
46
+ // ci-state payload rate-limited/unusable 2 rate-limited / ci-unreadable
47
+ // ci.behind === null 2 behind-unknown
48
+ // instruments.sh exit 1 2 instrument-set-changed
49
+ // instruments.sh any other failure 2 instruments-unanswerable
50
+ // gh pr view fails or misparses 2 pr-unreadable
51
+ //
52
+ // An instrument change is 2, not 1: a changed instrument says nothing about
53
+ // the PR, and the response is stop-and-report like every other 2.
54
+
55
+ import { spawnSync } from "node:child_process";
56
+ import { mkdirSync, writeFileSync } from "node:fs";
57
+ import { dirname, join } from "node:path";
58
+ import { fileURLToPath } from "node:url";
59
+ import { makeDie, defineFlags, writeAll } from "./arg.mjs";
60
+ import { gitEnv, workspaceDirFromGitCommonDir } from "./git-env.mjs";
61
+
62
+ const NAME = "merge-gate";
63
+
64
+ // The two instruments are this script's siblings in the install root the
65
+ // Resolver ran it from — the same resolution fleet-tick.mjs uses for
66
+ // candidates.mjs — so the gate always reads the ci-state and instrument set
67
+ // that shipped with it, never another install's.
68
+ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
69
+
70
+ const die = makeDie(NAME);
71
+ const { arg, numArg, sweep, stray } = defineFlags(die, {
72
+ flags: { pr: "value", pre: "value", post: "value", out: "value" },
73
+ });
74
+
75
+ const USAGE = "usage: merge-gate.mjs --pr <n> --pre <sha> [--post <sha>] [--out <path>]";
76
+
77
+ const pr = numArg("pr");
78
+ const preArg = arg("pre");
79
+ const postArg = arg("post");
80
+ const out = arg("out");
81
+ if (pr === null || preArg === null) die(USAGE);
82
+
83
+ // `--declare-no-ci` is deliberately NOT a flag here: the gate passes it to
84
+ // ci-state.mjs on every call (see readCi), so the sweep refuses it by name
85
+ // rather than letting a caller believe it changed anything.
86
+ sweep();
87
+ stray();
88
+
89
+ // Full SHAs only. The head check is an exact comparison against what gh
90
+ // reports, which is always the full lowercase SHA, so an abbreviated `--pre`
91
+ // could never match and would skip a mergeable PR as `head-moved-after-label`
92
+ // — a wrong verdict about the PR where a refusal is a finding about the call.
93
+ // Case is folded rather than refused: `ABC…` names the same commit.
94
+ function sha(name, value) {
95
+ const v = value.toLowerCase();
96
+ if (!/^[0-9a-f]{40}$/.test(v)) die(`--${name} needs a full 40-character commit SHA, got ${value}`);
97
+ return v;
98
+ }
99
+ const pre = sha("pre", preArg);
100
+ const post = postArg === null ? null : sha("post", postArg);
101
+ const heads = new Set([pre, post ?? pre]);
102
+
103
+ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
104
+
105
+ // Children's stdout is captured for parsing; their stderr goes straight to
106
+ // ours, so nothing a child says on fd 2 can reach a parse.
107
+ const CHILD = { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] };
108
+
109
+ // --- instruments.sh -------------------------------------------------------
110
+ // `--repo` is the directory holding the git COMMON dir — the main checkout,
111
+ // where the run's baseline `.fleet/instruments.sha` lives — never the cwd's
112
+ // own top level: from a worktree that has no baseline, and instruments.sh
113
+ // exits 2 on a missing baseline instead of comparing anything. gitEnv():
114
+ // an ambient GIT_DIR would otherwise answer `--git-common-dir` for a
115
+ // different repository, and the gate would certify that tree's instruments.
116
+ // `--repo` locates the baseline only; the baseline itself names the tree to
117
+ // audit, so a workspace that does not track `plugin/…` still reaches a
118
+ // verdict over the checkout its run pinned — no flag here repoints it.
119
+ function readInstruments() {
120
+ const common = spawnSync("git", ["rev-parse", "--git-common-dir"], { ...CHILD, env: gitEnv() });
121
+ const root = common.error || common.status !== 0 ? null : workspaceDirFromGitCommonDir(common.stdout);
122
+ if (root === null) return { exit: null, digest: null };
123
+ const r = spawnSync("sh", [join(SCRIPT_DIR, "instruments.sh"), "--repo", root], CHILD);
124
+ const digest = (r.stdout ?? "").trim().split("\n")[0] || null;
125
+ if (r.error || r.signal) return { exit: null, digest };
126
+ // An exit 0 that printed no digest compared nothing it can show, so it is
127
+ // not taken as "unchanged". instruments.sh prints the digest on both of its
128
+ // answering paths (0 and 1) before it exits.
129
+ if (r.status === 0 && !/^[0-9a-f]{64}$/.test(digest ?? "")) return { exit: null, digest };
130
+ return { exit: r.status, digest };
131
+ }
132
+
133
+ // --- gh pr view -----------------------------------------------------------
134
+ // null for anything that is not the three fields in their gh shapes: a parse
135
+ // that succeeds on the wrong shape must not reach a check that reads it.
136
+ function readPr() {
137
+ const r = spawnSync("gh", ["pr", "view", String(pr), "--json", "labels,reviewDecision,headRefOid"], CHILD);
138
+ if (r.error || r.status !== 0) return null;
139
+ let v;
140
+ try {
141
+ v = JSON.parse(r.stdout);
142
+ } catch {
143
+ return null;
144
+ }
145
+ if (!isObject(v)) return null;
146
+ if (!Array.isArray(v.labels) || !v.labels.every((l) => isObject(l) && typeof l.name === "string")) return null;
147
+ // gh answers `""` when the repo requires no review; null is tolerated the
148
+ // same way. Anything else is not a decision gh would give.
149
+ if (!Object.hasOwn(v, "reviewDecision") || (v.reviewDecision !== null && typeof v.reviewDecision !== "string")) return null;
150
+ if (typeof v.headRefOid !== "string" || !/^[0-9a-f]{40}$/.test(v.headRefOid)) return null;
151
+ return v;
152
+ }
153
+
154
+ // --- ci-state.mjs ---------------------------------------------------------
155
+ // `--declare-no-ci` on every call, with no option on this script's surface.
156
+ // It moves exactly one arm of ci-state's gate — `no-ci` — and cannot relax
157
+ // green/not-green; a no-CI PR whose label was pulled is still refused,
158
+ // because the label row runs first. `ci.verdict: "no-ci"` in the output says
159
+ // which arm cleared.
160
+ //
161
+ // The payload decides, and the exit code has to agree with it. Node exits 1
162
+ // for a crash, a syntax error or a missing module — ci-state's own code for
163
+ // not-green — so an exit 1 with no not-green payload is not a CI verdict. An
164
+ // exit 0 whose payload is `{}` or empty is the vacuous gate the merge bot's
165
+ // hand-written `jq` checks used to pass. Both read as `ci-unreadable`.
166
+ // The `validated` field is null whenever `usable` is false — mirroring
167
+ // readPr()'s null-on-any-shape-violation pattern — so decide() below reads
168
+ // off `validated`, not the raw (possibly malformed) `ci` payload, for every
169
+ // check gated on usability. That makes decide()'s safety independent of
170
+ // statement ORDER: a future edit that moved the `!usable` row below
171
+ // `validated.behind === null` would crash on a null dereference instead of
172
+ // silently answering `behind-unknown` for an unreadable payload. `ci` itself
173
+ // is kept only for the output line's diagnostic echo (e.g. a rate-limited
174
+ // payload's `ci.verdict`).
175
+ function readCi() {
176
+ const r = spawnSync(process.execPath, [join(SCRIPT_DIR, "ci-state.mjs"), "--pr", String(pr), "--declare-no-ci"], CHILD);
177
+ let payload = null;
178
+ try {
179
+ payload = JSON.parse(r.stdout ?? "");
180
+ } catch {
181
+ payload = null;
182
+ }
183
+ const ci = isObject(payload) ? payload : null;
184
+ const unusable = (rateLimited = false) => ({ ci, validated: null, usable: false, rateLimited });
185
+ if (r.error || r.signal || ci === null) return unusable();
186
+ if (r.status === 2) return unusable(ci.verdict === "rate-limited");
187
+ const agrees =
188
+ (r.status === 0 && (ci.verdict === "green" || ci.verdict === "no-ci")) ||
189
+ (r.status === 1 && ci.verdict === "not-green" && Array.isArray(ci.reasons) && typeof ci.reasons[0] === "string");
190
+ if (!agrees) return unusable();
191
+ if (!Array.isArray(ci.reasons) || typeof ci.prHead !== "string" || ci.prHead === "") return unusable();
192
+ // Absent is not null: null is ci-state's reading "could not count", while
193
+ // an absent `behind` (undefined, failing the integer test) comes from a
194
+ // payload that never carried the field.
195
+ if (ci.behind !== null && !(Number.isInteger(ci.behind) && ci.behind >= 0)) return unusable();
196
+ return { ci, validated: ci, usable: true, rateLimited: false, notGreen: r.status === 1 };
197
+ }
198
+
199
+ // --- the conjunction ------------------------------------------------------
200
+ function decide(instruments, prView, ciRead) {
201
+ const blocked = (reason) => ({ verdict: "blocked", reason });
202
+ const unknown = (reason) => ({ verdict: "unknown", reason });
203
+ const { validated, usable } = ciRead;
204
+ if (prView !== null) {
205
+ if (!prView.labels.some((l) => l.name === "ready-to-merge")) return blocked("label-pulled");
206
+ if (prView.reviewDecision === "CHANGES_REQUESTED") return blocked("changes-requested");
207
+ if (!heads.has(prView.headRefOid)) return blocked("head-moved-after-label");
208
+ }
209
+ // ci-state reads the head a second time, a few seconds after gh pr view
210
+ // above, and binds its run to THAT read. A push in between would have its
211
+ // own CI judged here while the label's audit belongs to the tree before it,
212
+ // so the same row applies to ci-state's reading too.
213
+ if (usable && !heads.has(validated.prHead)) return blocked("head-moved-after-label");
214
+ if (usable && ciRead.notGreen) return blocked(`ci:${validated.reasons[0]}`);
215
+ if (usable && validated.behind > 0) return blocked(`behind:${validated.behind}`);
216
+ if (!usable) return unknown(ciRead.rateLimited ? "rate-limited" : "ci-unreadable");
217
+ if (validated.behind === null) return unknown("behind-unknown");
218
+ if (instruments.exit === 1) return unknown("instrument-set-changed");
219
+ if (instruments.exit !== 0) return unknown("instruments-unanswerable");
220
+ if (prView === null) return unknown("pr-unreadable");
221
+ return { verdict: "mergeable", reason: null };
222
+ }
223
+
224
+ const EXIT = { mergeable: 0, blocked: 1, unknown: 2 };
225
+
226
+ // Node exits 1 on an uncaught throw, and 1 here means "blocked" — a verdict
227
+ // about the PR. Nothing below may reach it by accident: any failure of the
228
+ // gate itself is exit 2.
229
+ try {
230
+ const instruments = readInstruments();
231
+ const prView = readPr();
232
+ const ciRead = readCi();
233
+ const { verdict, reason } = decide(instruments, prView, ciRead);
234
+ const line = `${JSON.stringify({
235
+ pr,
236
+ verdict,
237
+ reason,
238
+ head: prView?.headRefOid ?? null,
239
+ pre,
240
+ post,
241
+ behind: ciRead.usable ? ciRead.ci.behind : null,
242
+ instruments: instruments.digest,
243
+ ci: ciRead.ci,
244
+ })}\n`;
245
+ // The file first: if it cannot be written, the gate refuses (exit 2)
246
+ // before any verdict reaches stdout, rather than printing a verdict the
247
+ // file the caller asked for does not carry.
248
+ if (out !== null) {
249
+ try {
250
+ mkdirSync(dirname(out), { recursive: true });
251
+ writeFileSync(out, line);
252
+ } catch (e) {
253
+ die(`cannot write --out ${out}: ${e.code ?? e.message}`);
254
+ }
255
+ }
256
+ // writeAll's false return is ignored for ci-state.mjs's reason: a lost
257
+ // write must not also move the process to a different exit code.
258
+ writeAll(1, line);
259
+ process.exit(EXIT[verdict]);
260
+ } catch (e) {
261
+ die(`gate failed: ${e.code ?? e.message} — could not evaluate`);
262
+ }