@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,1028 @@
1
+ // review-core.mjs — the review body for PR review (#1349, per #1303's ruling
2
+ // on #1296). Read that ruling before touching this file.
3
+ //
4
+ // This file holds every host-independent declaration PR review needs: the
5
+ // two JSON schemas, `usableDiff`, `readRules`, `resolveTestCmd`,
6
+ // `decodeArgs`, `selectDimensions`, `resolveDimensions`, `snapshotMissing`,
7
+ // `unrunReason`/`unrunEntries`/`unrunCrashed`, `verdictFor`, `resumeFor`,
8
+ // and `runReview(host, args)` — the orchestration function itself.
9
+ //
10
+ // review-eval.mjs imports this file directly, a RELATIVE specifier: both
11
+ // ship together under the same Install root, so the Resolver is only needed
12
+ // ONCE, to find review-eval.mjs itself — never resolve this file's own path
13
+ // through the Resolver a second time; that would be two doors where
14
+ // CONTEXT.md's Resolver entry says there is exactly one.
15
+ //
16
+ // `runReview(host, args)` takes an injected `host` object (`agent`, `phase`,
17
+ // `log`, and optionally `pipeline`/`parallel`) rather than reading them as
18
+ // ambient globals: eval's `agent()` returns a HANDLE, not data, so
19
+ // review-eval.mjs's `ompAgent` wrapper adapts it to the synchronous,
20
+ // data-returning shape this file reads throughout (see review-eval.mjs's own
21
+ // header for that contract, and for why a crashed/rejected dispatch maps to
22
+ // `null`, which every guard here — `if (snap) {...}`, `unrunCrashed`,
23
+ // `verdictFor` — is written against).
24
+ //
25
+ // ONE import, added by #878: arg.mjs's isDigits(). This file is an ordinary
26
+ // module, so it consumes the repo's digits rule directly rather than
27
+ // declaring its own copy.
28
+ //
29
+ // `.mjs`, not `.js` (#1763): this file was `review-core.js` until then, and
30
+ // nothing that ships declares a `type`, so Node below 20.19.0/22.7.0 —
31
+ // inside the declared consumer floor — read it as CommonJS and
32
+ // review-eval.mjs's import of it failed. node-floor-sweep.test.mjs keeps a
33
+ // shipped `.mjs` from importing a relative module under any other extension.
34
+
35
+ import { isDigits } from "./arg.mjs";
36
+
37
+ // --- Schemas ----------------------------------------------------------
38
+ export const FINDINGS_SCHEMA = {
39
+ type: "object",
40
+ additionalProperties: false,
41
+ required: ["dimension", "scope_searched", "findings", "test_run"],
42
+ properties: {
43
+ dimension: { type: "string" },
44
+ scope_searched: {
45
+ type: "string",
46
+ description:
47
+ "The exact commands/paths this pass covered. Required so a negative claim is bounded: a grep that found nothing looks identical to a grep never run.",
48
+ },
49
+ test_run: {
50
+ type: "object",
51
+ additionalProperties: false,
52
+ required: ["command", "tests"],
53
+ description:
54
+ "The test run this pass performed. Report it even when it failed or produced nothing — `tests: 0` is how a dimension gets reported unrun, and an empty findings list cannot say it.",
55
+ properties: {
56
+ command: { type: "string", description: "The command as RUN, verbatim." },
57
+ tests: { type: "integer", description: "Tests the run reported. 0 means the command produced none — a failed run, not a pass." },
58
+ pass: { type: "integer" },
59
+ fail: { type: "integer" },
60
+ },
61
+ },
62
+ findings: {
63
+ type: "array",
64
+ items: {
65
+ type: "object",
66
+ additionalProperties: false,
67
+ required: ["severity", "claim", "evidence"],
68
+ properties: {
69
+ severity: { enum: ["critical", "important", "suggestion"] },
70
+ file: { type: "string" },
71
+ line: { type: "integer" },
72
+ claim: { type: "string", description: "One falsifiable sentence." },
73
+ evidence: {
74
+ type: "string",
75
+ description:
76
+ "What was RUN — command plus output — not what was reasoned. A claim with no command is a suggestion at best.",
77
+ },
78
+ suggested_fix: { type: "string" },
79
+ },
80
+ },
81
+ },
82
+ },
83
+ };
84
+
85
+ export const VERDICT_SCHEMA = {
86
+ type: "object",
87
+ additionalProperties: false,
88
+ required: ["refuted", "reason"],
89
+ properties: {
90
+ refuted: { type: "boolean" },
91
+ reason: { type: "string" },
92
+ counter_evidence: { type: "string", description: "Command + output, if any." },
93
+ },
94
+ };
95
+
96
+ export const SNAPSHOT_SCHEMA = {
97
+ type: "object",
98
+ additionalProperties: false,
99
+ required: ["runRoot", "path", "head", "pathVerified", "repoVerified"],
100
+ properties: {
101
+ runRoot: { type: "string" },
102
+ path: { type: "string" },
103
+ head: { type: "string" },
104
+ pathVerified: { type: "boolean" },
105
+ // #1056. `pathVerified` says the tree is THERE; this says the tree is
106
+ // MEASURABLE — that the snapshot is a git repository holding the reviewed
107
+ // commit's tree. Required for `pathVerified`'s reason: an omitted boolean
108
+ // must not read as a verified environment, because the whole defect was a
109
+ // measurement nothing in the payload said was taken somewhere else.
110
+ repoVerified: { type: "boolean" },
111
+ // Only when `repoVerified` is false: whichever SNAPSHOT_* line the block
112
+ // printed instead of SNAPSHOT_TREE_MATCH. Optional, because a verified
113
+ // snapshot has nothing to say here.
114
+ repoError: { type: "string" },
115
+ diffStats: { type: "string" },
116
+ diffPath: { type: "string" },
117
+ diffLines: { type: "integer" },
118
+ refHead: { type: "string" },
119
+ prHead: { type: "string" },
120
+ testCmd: { type: "string" },
121
+ testCmdError: { type: "string" },
122
+ },
123
+ };
124
+
125
+ // --- Dimension catalog --------------------------------------------------
126
+ // #1349, per #1303's gap 3: no dimension carries a `model`/`effort` field —
127
+ // dispatch tier lives ONLY in each fleet-owned agent definition's own
128
+ // frontmatter. `agentType` is a bare frontmatter `name:` (omp's native
129
+ // `agent()` lookup is an exact match on one).
130
+ export const DEFAULT_DIMENSIONS = [
131
+ {
132
+ key: "correctness",
133
+ agentType: "fleet-review-correctness",
134
+ prompt: "logic errors, missed cases, scope creep beyond the ticket",
135
+ },
136
+ {
137
+ key: "silent-failure",
138
+ agentType: "fleet-review-silent-failure",
139
+ prompt:
140
+ "swallowed errors, fallbacks that hide faults, catch blocks that mislabel what failed, and any NEW dereference the diff moved inside an existing try",
141
+ },
142
+ {
143
+ key: "tests",
144
+ agentType: "fleet-review-tests",
145
+ prompt:
146
+ "whether each test DISCRIMINATES: apply the mutation it should catch, confirm that test goes red, revert, then apply one it should NOT catch and confirm green. Vary the syntactic form — a guard catching `// whole-line` may let `code; // trailing` through",
147
+ },
148
+ {
149
+ key: "comments",
150
+ agentType: "fleet-review-comments",
151
+ prompt:
152
+ "every added factual assertion checked against the tree, INCLUDING comments in files this diff does not touch but whose claims it falsifies (test-name references, 'N of 3' counts, tracking-issue pointers)",
153
+ },
154
+ {
155
+ key: "types",
156
+ agentType: "fleet-review-types",
157
+ prompt: "invariants expressed vs merely documented; casts that erase conformance",
158
+ },
159
+ {
160
+ key: "simplify",
161
+ agentType: "fleet-review-simplify",
162
+ prompt:
163
+ "simplification opportunities — dead branches, redundant state, needless indirection. REPORT ONLY, read-only: a finding's claim is what to simplify, suggested_fix is the simpler form, severity 'suggestion'. Never edit a file. A simplification that changes observable behavior is a defect, not a suggestion",
164
+ },
165
+ ];
166
+
167
+ // #2102: the omp `fleet-review-runner` agent definition's `spawns:`
168
+ // frontmatter must allow exactly the agent types dispatched below (the
169
+ // snapshot agent, every DEFAULT_DIMENSIONS entry, and the verifier) — omp
170
+ // denies every spawn by default, and the runner declared no `spawns` at all
171
+ // until this fix. Exporting the two literal-only types (snapshot/verifier
172
+ // have no DEFAULT_DIMENSIONS entry of their own) plus the derived full set
173
+ // lets review-runner-spawns.test.mjs pin the frontmatter against what this
174
+ // file actually dispatches, instead of a hand-copied list that can drift.
175
+ export const SNAPSHOT_AGENT_TYPE = "fleet-review-snapshot";
176
+ export const VERIFIER_AGENT_TYPE = "fleet-review-verifier";
177
+ export const SPAWNED_AGENT_TYPES = [
178
+ SNAPSHOT_AGENT_TYPE,
179
+ ...DEFAULT_DIMENSIONS.map((d) => d.agentType),
180
+ VERIFIER_AGENT_TYPE,
181
+ ];
182
+
183
+ // `single-file` is `files === 1`, `small` is `loc < 30` (diff-stats.mjs's
184
+ // computeStats owns both thresholds).
185
+ export const SIZE_TIER_PROFILES = new Set(["single-file", "small"]);
186
+ // The refuter-budget floor: `correctness`/`silent-failure` miss silently and
187
+ // permanently; `comments` sits beside them for a different reason (#218).
188
+ // Keyed on recoverability of a MISS, never on tier — `verifiersFor` takes a
189
+ // severity and nothing else.
190
+ export const SIZE_TIER_DIMS = new Set(["correctness", "silent-failure", "comments"]);
191
+
192
+ // The refuter budget per severity, derived once per run from the caller's
193
+ // own `A.verifiers`/`A.verifiersBySeverity` overrides (or the defaults) and
194
+ // bound to a `(severity) => count` closure — `select-dimensions.test.mjs`
195
+ // imports this directly rather than re-deriving it from a lifted copy.
196
+ export function verifiersFor(A) {
197
+ const verifiers = A.verifiers || 2;
198
+ const by = A.verifiersBySeverity || { critical: verifiers, important: verifiers, suggestion: 0 };
199
+ return (sev) => by[sev] ?? verifiers;
200
+ }
201
+
202
+ // --- Pure functions -------------------------------------------------------
203
+ // Every function below was ported byte-identical (function body) from this
204
+ // repo's retired pre-cutover review workflow script's own declaration, before
205
+ // ADR 0014 retired that file — see this repo's git history for the full
206
+ // historical rationale on each; it is not repeated here to avoid a second
207
+ // copy of PROSE disconnecting the way this repo's own "recurring pin defect"
208
+ // comment warns a second copy of CODE does.
209
+
210
+ export function usableDiff(snap) {
211
+ if (!snap.diffPath) return null;
212
+ if (!snap.diffLines) return null;
213
+ // No head check here: `snapshotMissing` owns it and runs first in `runReview`.
214
+ return `${snap.runRoot}/pr.diff`;
215
+ }
216
+
217
+ export function readRules(diffPath, stats, snap) {
218
+ let change;
219
+ if (diffPath) {
220
+ change = `The PR's whole diff is at ${diffPath}. Read it FIRST, bounded — it is the
221
+ change you are reviewing, and the snapshot around it is context.`;
222
+ } else if (stats && stats.paths && stats.paths.length) {
223
+ const rejected = snap && snap.diffPath ? snap.diffPath : null;
224
+ const header = stats.truncated
225
+ ? `The PR touched at least these files — GitHub capped the list at ${stats.paths.length} of
226
+ ${stats.truncated}, so there are more it does not name:`
227
+ : `The PR touched exactly these files and no others:`;
228
+ change = `${
229
+ rejected
230
+ ? `A diff was captured at ${rejected} and REJECTED — ${
231
+ snap.diffLines === 0
232
+ ? "it is empty"
233
+ : "its line count was never reported, so nothing measured whether it holds the PR's whole change or nothing at all"
234
+ }. Do not read it.`
235
+ : "No diff file was captured."
236
+ } ${header}
237
+ ${stats.paths.map((p) => ` ${p.path} (${p.loc} changed)`).join("\n")}`;
238
+ } else {
239
+ change = `No diff file and no file list were captured. Locate the files your
240
+ dimension covers by searching the snapshot ('grep -rn', 'ls -R'), then read
241
+ them under the bounding rule below: 'wc -l' first.`;
242
+ }
243
+
244
+ return `${change}
245
+
246
+ The snapshot IS the source of truth: 'git archive HEAD', byte-identical to
247
+ 'git show HEAD:<path>' — verified when it was cut. No agent can contaminate it
248
+ and no git command settles what the PR contains any better. A finding that
249
+ disagrees with the snapshot is a probe artifact.
250
+
251
+ BOUND EVERY READ: an offset and a limit, or '| sed -n A,Bp'. Take a file whole
252
+ only after 'wc -l' says it is small — a count, not a feeling. An unbounded read
253
+ is never a one-off cost: it rides your prefix for every remaining turn,
254
+ re-billed as cache-read each time. Measured over one run, 88 unpiped whole-file
255
+ reads carried 434 KB.`;
256
+ }
257
+
258
+ // The step a missing Test entrypoint is derived by, named in the refusal so the
259
+ // caller — a controller or a reviewer — knows what to run rather than what went
260
+ // wrong (ADR 0015). derive-testcmd.sh's own refusals name the same step; this
261
+ // one covers the case where the snapshot agent reported no reason at all.
262
+ const DERIVATION_STEP =
263
+ "run the Recipe derivation step (run-team phase 0, before the first claim — ADR 0015) to derive, prove and write the Recipe cache";
264
+
265
+ export function resolveTestCmd(explicit, snap) {
266
+ if (explicit) return explicit;
267
+ if (snap && snap.testCmd) return snap.testCmd;
268
+ throw new Error(
269
+ `review-pr: no test command for this repository — ${(snap && snap.testCmdError) || `the snapshot agent read no Recipe cache; ${DERIVATION_STEP}`}. Pass args.testCmd to override.`,
270
+ );
271
+ }
272
+
273
+ export function decodeArgs(a) {
274
+ if (typeof a !== "string") return a || {};
275
+ try {
276
+ return JSON.parse(a);
277
+ } catch (e) {
278
+ throw new Error(`review-pr: args arrived as a string this could not parse (${e.message})`);
279
+ }
280
+ }
281
+
282
+ export function selectDimensions(all, stats) {
283
+ if (!stats || !stats.profile || stats.profile === "empty") return all;
284
+ if (stats.truncated) return all;
285
+ if (stats.docsOnly === true) {
286
+ const docsOnlyDims = all.filter((d) => d.key === "correctness" || d.key === "comments");
287
+ if (!docsOnlyDims.length) throw new Error("review-pr: selectDimensions produced an empty dimension set");
288
+ return docsOnlyDims;
289
+ }
290
+ let dims = all;
291
+ if (stats.hasTests === false) dims = dims.filter((d) => d.key !== "tests");
292
+ if (stats.hasSrc === false) {
293
+ const keepsSilentFailure =
294
+ SIZE_TIER_PROFILES.has(stats.profile) ||
295
+ (stats.profile === "tests-only" && stats.hasConfig === true) ||
296
+ (stats.profile === "production" && stats.hasTests === false && stats.hasConfig === true);
297
+ dims = dims.filter(
298
+ (d) => d.key !== "types" && d.key !== "simplify" && (d.key !== "silent-failure" || keepsSilentFailure),
299
+ );
300
+ }
301
+ if (SIZE_TIER_PROFILES.has(stats.profile))
302
+ dims = dims.filter((d) => SIZE_TIER_DIMS.has(d.key) || (d.key === "tests" && stats.hasTests === true));
303
+ if (!dims.length) throw new Error("review-pr: selectDimensions produced an empty dimension set");
304
+ return dims;
305
+ }
306
+
307
+ // The "Specialists" section of `commands/review-and-fix.md`
308
+ // documents `args.dimensions` as accepting "keys or dimension objects" — but
309
+ // until now only objects worked: a key array passed straight through and
310
+ // every dereference below (`d.key`, `d.prompt`, `d.agentType` — three) came
311
+ // back `undefined`, with no throw and no warning (#113). Resolve strings
312
+ // against the workflow's own catalog, and check every object has the three
313
+ // fields it REQUIRES AND that each of those is a string — presence alone let
314
+ // a non-string field reach the specialist dispatch machinery downstream
315
+ // instead of failing at this validated boundary. `model` is no longer a
316
+ // fourth optional field (#1349): an override entry that still sends one is
317
+ // refused outright, loudly, rather than silently accepted and ignored — see
318
+ // the check below.
319
+ // Anything unresolvable stops the run and names what was not recognised — a
320
+ // misconfigured review is worse than no review, because its findings look like
321
+ // findings.
322
+ export function resolveDimensions(override, all) {
323
+ if (override == null) return null;
324
+ if (!Array.isArray(override))
325
+ throw new Error("review-pr: args.dimensions must be an array of keys or dimension objects");
326
+ const REQUIRED = ["key", "prompt", "agentType"];
327
+ const kind = (v) => (v === null ? "null" : Array.isArray(v) ? "array" : typeof v);
328
+ const normalized = override.map((entry, i) => {
329
+ if (typeof entry === "string") {
330
+ const found = all.find((d) => d.key === entry);
331
+ if (!found) throw new Error(`review-pr: args.dimensions[${i}] named an unknown key "${entry}"`);
332
+ return found;
333
+ }
334
+ if (kind(entry) !== "object")
335
+ throw new Error(
336
+ `review-pr: args.dimensions[${i}] must be a key string or a dimension object, got ${kind(entry)}`,
337
+ );
338
+ const missing = REQUIRED.filter((f) => !entry[f]);
339
+ if (missing.length)
340
+ throw new Error(`review-pr: args.dimensions[${i}] is missing required field(s): ${missing.join(", ")}`);
341
+ const wrongType = REQUIRED.find((f) => typeof entry[f] !== "string");
342
+ if (wrongType)
343
+ throw new Error(
344
+ `review-pr: args.dimensions[${i}] field "${wrongType}" must be a string, got ${kind(entry[wrongType])}`,
345
+ );
346
+ if (entry.model !== undefined)
347
+ throw new Error(
348
+ `review-pr: args.dimensions[${i}] field "model" is no longer supported — dispatch tier lives in the fleet-owned agent definition's own frontmatter, never per call`,
349
+ );
350
+ return entry;
351
+ });
352
+ const byKey = new Map();
353
+ for (const [i, d] of normalized.entries()) {
354
+ const held = byKey.get(d.key);
355
+ if (held && (held.prompt !== d.prompt || held.agentType !== d.agentType))
356
+ throw new Error(`review-pr: args.dimensions[${i}] repeats key "${d.key}" with different fields`);
357
+ if (!held) byKey.set(d.key, d);
358
+ }
359
+ const resolved = [...byKey.values()];
360
+ if (!resolved.length) throw new Error("review-pr: args.dimensions resolved to no dimensions");
361
+ return resolved;
362
+ }
363
+
364
+ export function snapshotMissing(snap, runRootPrefix) {
365
+ if (!snap) return "the snapshot agent returned nothing (it died, or it exhausted its structured-output retries) — no tree to review";
366
+ if (!snap.path) return "the snapshot agent's report gives no `path` — no tree to review";
367
+ if (!snap.head) return "the snapshot agent's report gives no `head` — refusing to review a tree whose commit is unknown";
368
+ if (!snap.runRoot) return "the snapshot agent's report gives no `runRoot` — nothing says the tree belongs to THIS run";
369
+ if (!snap.runRoot.startsWith(runRootPrefix))
370
+ return `the snapshot agent reported a run root of ${snap.runRoot}, which is not under ${runRootPrefix} — refusing a tree this run did not provision`;
371
+ if (!snap.path.startsWith(`${snap.runRoot}/snapshot-`))
372
+ return `the snapshot at ${snap.path} is not under this run's own root ${snap.runRoot} — refusing a tree that may belong to another run`;
373
+ if (snap.path.includes("/../") || snap.path.endsWith("/.."))
374
+ return `the snapshot at ${snap.path} climbs out of ${snap.runRoot} with a \`..\` segment — the prefix says nothing about where it resolves`;
375
+ if (snap.pathVerified !== true)
376
+ return `the snapshot at ${snap.path} was not verified to exist — refusing to hand a possibly-missing tree to every specialist`;
377
+ if (snap.refHead && !snap.refHead.startsWith(snap.head) && !snap.head.startsWith(snap.refHead))
378
+ return `the tree at ${snap.path} is at ${snap.head}, and the PR's head is at ${snap.refHead} — refusing to review a commit that is not the PR`;
379
+ return null;
380
+ }
381
+
382
+ // #1056. What a suite run inside the snapshot is evidence ABOUT, in one
383
+ // paragraph every specialist prompt and the returned payload both carry.
384
+ //
385
+ // `repoVerified` false is deliberately NOT a refusal (`snapshotMissing` says
386
+ // nothing about it): the tree is still reviewable, and refusing would trade a
387
+ // wrong test count for no coverage at all — the expensive half of this defect,
388
+ // measured twice as a dimension withdrawing itself over a suite it could not
389
+ // attribute. What the review cannot do is present the count as a validation
390
+ // while nothing says the measurement happened somewhere else, so the fact
391
+ // travels with the payload instead.
392
+ //
393
+ // The verified branch states the synthetic history too, because making the
394
+ // snapshot a repository is what makes a git command answer there AT ALL: one
395
+ // commit, no ancestry, no remotes, so `git log`/`git diff` now return
396
+ // plausible output about the snapshot in place of the `fatal:` that used to
397
+ // stop that question being asked.
398
+ export function environmentNote(snap) {
399
+ if (snap && snap.repoVerified === true)
400
+ return `Test environment: the snapshot is a git repository whose single commit holds
401
+ the reviewed tree — its tree hash was compared against the commit under review
402
+ when the snapshot was cut. A suite run here collects and runs what a checkout at
403
+ that commit does, so a failing or skipped test is a fact about the tree, not
404
+ about this copy of it. Its history is that one synthetic commit: 'git log',
405
+ 'git diff' and every ancestry question answer about the snapshot and never about
406
+ the PR.`;
407
+ const cause = snap && snap.repoError;
408
+ if (cause && cause.startsWith("SNAPSHOT_TREE_MISMATCH"))
409
+ return `Test environment UNVERIFIED — ${cause}.
410
+ The init succeeded: the snapshot IS a git repository, but its tree is not the
411
+ commit under review — 'git init' committed the extraction, and the commit's
412
+ tree does not match. A suite run here still executes against a real checkout,
413
+ so its counts are real measurements, but of a DIFFERENT tree than the one
414
+ under review: a failure in it says nothing about the reviewed commit.`;
415
+ return `Test environment UNVERIFIED — ${cause || "the snapshot agent did not report a verified repository"}.
416
+ A 'git archive' extraction is not a git repository, and every test that needs
417
+ one skips or fails there for that reason alone, so a suite run here is NOT a
418
+ validation of the tree: its counts are snapshot-measured, and a failure in it
419
+ cannot be told apart from a regression.`;
420
+ }
421
+
422
+ export function unrunReason(review) {
423
+ if (!review) return "the reviewer returned nothing — spend limit, timeout, or terminal error";
424
+ const run = review.test_run;
425
+ if (!run) return "the reviewer reported no test run at all";
426
+ const cmd = run.command || "the test command";
427
+ if (!run.tests) return `\`${cmd}\` produced 0 tests — a failed run, not a pass`;
428
+ if (run.pass === 0 && !run.fail) return `\`${cmd}\` passed nothing and failed nothing — every test skipped, not a pass`;
429
+ const executed = run.pass + (run.fail ?? 0);
430
+ if (typeof run.pass === "number" && executed * 2 < run.tests)
431
+ return `\`${cmd}\` passed ${run.pass} and failed ${run.fail ?? 0} of the ${run.tests} tests it collected — most of what it collected never ran`;
432
+ if (run.fail > 0 && !review.findings?.length)
433
+ return `\`${cmd}\` reported ${run.fail} failing tests and the reviewer filed no findings about them`;
434
+ return null;
435
+ }
436
+
437
+ export function unrunEntries(review, dimension) {
438
+ const why = unrunReason(review);
439
+ return why ? [{ dimension, reason: why }] : [];
440
+ }
441
+
442
+ export function unrunCrashed(reviewed, dimensions) {
443
+ return reviewed.flatMap((r, i) => (r ? [] : unrunEntries(null, dimensions[i]?.key ?? `slot ${i}`)));
444
+ }
445
+
446
+ // #1433 gap: the CWD-AUDIT line the Review dispatch below asks a specialist
447
+ // to fold into `scope_searched` is a convention, not schema — FINDINGS_SCHEMA
448
+ // accepts any string there, so a specialist that satisfies the schema while
449
+ // never emitting the line, or misspelling it, produces a fully valid,
450
+ // undetected payload, and one that DOES emit `CWD-AUDIT: dirty <path>` has
451
+ // nothing downstream that reads for it either. This is the runtime backstop
452
+ // for both halves: it extracts the line the prompt's own wording requires
453
+ // (`CWD-AUDIT: clean|dirty|unrepo <path> …`), and reports the line's absence
454
+ // exactly as loudly as its presence, so `runReview` can fold the result into
455
+ // the payload below instead of the fact dead-ending inside a field nothing
456
+ // reads.
457
+ const CWD_AUDIT_LINE = /CWD-AUDIT:\s*(clean|dirty|unrepo)\b.*/;
458
+
459
+ export function cwdAuditFrom(text) {
460
+ const m = typeof text === "string" ? text.match(CWD_AUDIT_LINE) : null;
461
+ return m ? { state: m[1], line: m[0].trim() } : { state: "missing", line: null };
462
+ }
463
+
464
+ export function verdictFor(dispatched, votes) {
465
+ const live = votes.filter(Boolean);
466
+ const refuted = live.filter((v) => v.refuted).length;
467
+ let verdict;
468
+ if (live.length === 0) verdict = "unverified";
469
+ else verdict = refuted * 2 >= live.length ? "refuted" : "survived";
470
+ return { verdict, votes: live, refutersDispatched: dispatched };
471
+ }
472
+
473
+ // #1802. One in-run re-dispatch for a crashed dispatch, before the result is
474
+ // assembled — the specialist call and the refuter PAIR are the two units it
475
+ // wraps. `crashed(value)` says whether a settled first attempt counts as a
476
+ // crash; a THROWN first attempt is handed to it as `null`, because a
477
+ // rejection is a crash too (omp's `agent()` can reject before its handle
478
+ // exists). A crashed first attempt is dispatched exactly once more and that
479
+ // second answer is final, thrown or not, so the caller's existing crash
480
+ // handling still sees it.
481
+ export function retryCrashed(dispatch, crashed) {
482
+ const again = (first) => (crashed(first) ? dispatch() : first);
483
+ return Promise.resolve()
484
+ .then(() => dispatch())
485
+ .then(again, () => again(null));
486
+ }
487
+
488
+ // omp has no cached-replay mechanism (ADR 0004/0005, #1349 gap 1): a fresh
489
+ // review re-dispatches every agent() live rather than only the crashed
490
+ // legs, and the one re-dispatch this run gets was already spent in-run
491
+ // (#1802) — a crashed finding is reported and deferred, never resumed.
492
+ export function resumeFor(unverified) {
493
+ const crashed = unverified.filter((f) => f.refutersDispatched > 0);
494
+ if (!crashed.length) return { crashed, resume: null };
495
+ const claim =
496
+ "Findings in `unverified` with `refutersDispatched` above zero and no surviving vote had every refuter die, and die again on the in-run retry — nothing looked at them. ";
497
+ const verb =
498
+ "Defer them as crashed — reported, not acted on: omp's eval has no cached-replay mechanism (ADR 0004/0005, #1349 gap 1), so a fresh review re-dispatches every agent() live rather than only the crashed legs, and the in-run retry was this review's one re-dispatch. Re-run nothing for them.";
499
+ return { crashed, resume: claim + verb };
500
+ }
501
+
502
+ // #1802. The digest: every field a controller acts on, and nothing bulky.
503
+ // The result object LEADS with exactly these keys, in this order
504
+ // (`runReview`'s return below) — historically so the pre-cutover harness's
505
+ // ~8 KB inline `<result>` cut landed in the finding arrays, never in the
506
+ // digest; before this, `resume` was the last key and fell past the cut on a
507
+ // large review.
508
+ // omp's result goes to a file and the controller reads only named fields
509
+ // out of it with `jq` (review-and-fix.md § The review result file), so
510
+ // nothing here truncates on key order today — the order is kept for the
511
+ // same reason a struct's fields stay ordered: a reader scanning top-down
512
+ // meets the fields that matter first.
513
+ // `snapshot`, `survived`, `refuted` and `unverified` follow it.
514
+ export const DIGEST_KEYS = ["pr", "head", "resume", "testEnvironment", "dimensionsRun", "dimensionsUnrun", "cwdAudit", "counts"];
515
+
516
+ export function digestOf(result) {
517
+ return Object.fromEntries(DIGEST_KEYS.map((k) => [k, result[k]]));
518
+ }
519
+
520
+ // #1802. The digits refusal review-eval.mjs's `runReviewToFile` runs before
521
+ // its first attempt, so a dispatch mistake is refused once instead of being
522
+ // retried and sent to the fallback reviewer. It lives here, not there, because
523
+ // review-eval.mjs is a library and arg.mjs's `scripts/*.mjs` importers are its
524
+ // CLI roster, each one probed to refuse a stray flag
525
+ // (arg-header-probes-prose.test.mjs); this module already consumes the digits
526
+ // rule on the review path. Null when `pr` is a PR number.
527
+ export function runnerPrRefusal(pr) {
528
+ return isDigits(pr) ? null : `args.pr must be a PR number, got ${JSON.stringify(pr)}`;
529
+ }
530
+
531
+ // --- Orchestration ----------------------------------------------------
532
+ // `host` supplies `agent(prompt, opts)` (must resolve to PARSED DATA — a
533
+ // rejection or an unresolvable dispatch must resolve to `null`, the
534
+ // contract every guard below is written against), `phase(title)`,
535
+ // `log(message)`, and OPTIONALLY `pipeline`/`parallel` (see
536
+ // defaultPipeline/defaultParallel below for the omp shim's implementation
537
+ // of both, built from #1296 Q3's analysis).
538
+ function defaultParallel(fns) {
539
+ return Promise.all(fns.map((fn) => fn()));
540
+ }
541
+
542
+ // Per-item independence, INCLUDING the null short-circuit: a stage-1 throw
543
+ // or a stage-1 falsy result must land in the SAME null slot a stage-2 throw
544
+ // would, so `unrunCrashed`'s index-aligned read of the pipeline result sees
545
+ // one uniform shape for every crash cause (#1296 Q3).
546
+ async function defaultPipeline(items, stage1, stage2) {
547
+ return Promise.all(
548
+ items.map(async (item) => {
549
+ let r1;
550
+ try {
551
+ r1 = await stage1(item);
552
+ } catch {
553
+ r1 = null;
554
+ }
555
+ if (!r1) return null;
556
+ try {
557
+ return await stage2(r1, item);
558
+ } catch {
559
+ return null;
560
+ }
561
+ }),
562
+ );
563
+ }
564
+
565
+ export async function runReview(host, args) {
566
+ const { agent, phase, log } = host;
567
+ const pipeline = host.pipeline ?? defaultPipeline;
568
+ const parallel = host.parallel ?? defaultParallel;
569
+
570
+ const A = decodeArgs(args);
571
+ const pr = A.pr;
572
+ const branch = A.branch;
573
+ const worktree = A.worktree;
574
+ const scratch = A.scratch || `/tmp/review-pr-${pr}`;
575
+ const runRootParent = `${scratch}/pr${pr}`;
576
+ const runRootPrefix = `${runRootParent}/run-`;
577
+ const verifiersForRun = verifiersFor(A);
578
+
579
+ if (!pr || !worktree) throw new Error("review-pr: args.pr and args.worktree are required");
580
+
581
+ // #878. The truthiness check above is what made the CLI fail-open REACHABLE:
582
+ // `pr` is interpolated into `gh pr diff ${pr}`, `gh pr view ${pr}` and
583
+ // `diff-stats.mjs --pr ${pr}` in the snapshot prompt below, and a branch name
584
+ // passes all three — `gh` resolves a non-numeric ref as a BRANCH, so the
585
+ // snapshot is a real diff belonging to whatever PR that branch heads while
586
+ // every return value here still reports the string that was passed. It is
587
+ // also a PATH component by then (`scratch`, `runRootParent` above), so a
588
+ // value like `../x` names a run root outside the scratch tree.
589
+ //
590
+ // REFUSED, never coerced. `Number(pr)` would make a bad value the string
591
+ // "NaN" at every one of those interpolation sites — a plausible-looking
592
+ // scratch directory and a `gh pr view NaN` — which is the same fail-open one
593
+ // level up. Here rather than downstream for the reason stated beside
594
+ // `explicitDimensions` below: validating late buys a snapshot agent and a
595
+ // directory on disk before a one-character mistake can be refused.
596
+ //
597
+ // isDigits() coerces, so a caller passing the NUMBER 42 (the fleet's own
598
+ // shape) and one passing "42" both pass, and `null`/`undefined` answer false
599
+ // — which is why this sits BELOW the required-args throw and never merged
600
+ // into it: an absent `pr` is owed "required", not a complaint about digits.
601
+ if (!isDigits(pr)) throw new Error(`review-pr: args.pr must be a PR number, got ${JSON.stringify(pr)}`);
602
+
603
+ const explicitDimensions = resolveDimensions(A.dimensions, DEFAULT_DIMENSIONS);
604
+
605
+ phase("Snapshot");
606
+ const snap = await agent(
607
+ `In ${worktree}, cut an immutable review snapshot, then size the PR's diff.
608
+
609
+ unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_TEMPLATE_DIR
610
+ [ -n "${scratch}" ] || { echo SNAPSHOT_SCRATCH_UNSET; exit 1; }
611
+ mkdir -p "${runRootParent}" || { echo SNAPSHOT_RUNROOT_FAILED; exit 1; }
612
+ RUN=$(mktemp -d "${runRootPrefix}XXXXXXXX") || { echo SNAPSHOT_RUNROOT_FAILED; exit 1; }
613
+ echo SNAPSHOT_RUN_ROOT="$RUN"
614
+ find "${runRootParent}" -maxdepth 1 -type d -name 'run-*' -mtime +7 -exec rm -rf {} + || echo SNAPSHOT_PRUNE_FAILED
615
+ SHA=$(git -C ${worktree} rev-parse --short HEAD) || { echo SNAPSHOT_REVPARSE_FAILED; exit 1; }
616
+ SNAP="$RUN/snapshot-$SHA"
617
+ echo SNAPSHOT_DEST="$SNAP"
618
+ mkdir -p "$SNAP"
619
+ git -C ${worktree} archive HEAD | tar -x -C "$SNAP"
620
+ [ -n "$(ls -A "$SNAP")" ] && echo SNAPSHOT_NONEMPTY || echo SNAPSHOT_EMPTY
621
+ ( cd "$SNAP" && git init -q && git add -A -f && git -c user.name=fleet -c user.email=fleet@invalid commit -q --no-verify -m "review snapshot of $SHA" ) || echo SNAPSHOT_INIT_FAILED
622
+ SNAPTREE=$(git -C "$SNAP" rev-parse 'HEAD^{tree}' 2>/dev/null); SRCTREE=$(git -C ${worktree} rev-parse 'HEAD^{tree}')
623
+ { [ -d "$SNAP/.git" ] && [ -n "$SNAPTREE" ] && [ "$SNAPTREE" = "$SRCTREE" ]; } && echo SNAPSHOT_TREE_MATCH || echo SNAPSHOT_TREE_MISMATCH="snapshot $SNAPTREE vs commit $SRCTREE"
624
+ [ -d "$SNAP/.git" ] && printf 'node_modules\\n' >> "$SNAP/.git/info/exclude"
625
+ if [ -n "$SNAP" ] && [ -d ${worktree}/node_modules ]; then ln -s ${worktree}/node_modules "$SNAP/node_modules"; fi
626
+
627
+ Report \`pathVerified\` = true ONLY if the 'ls -A' line printed SNAPSHOT_NONEMPTY,
628
+ run in that order — BEFORE the 'git init' and BEFORE the symlink, never after
629
+ either. Both create an entry of their own, so a probe below them prints
630
+ SNAPSHOT_NONEMPTY on a 'git archive' that extracted nothing at all.
631
+
632
+ Report \`repoVerified\` = true ONLY if the last line above printed
633
+ SNAPSHOT_TREE_MATCH; otherwise report it false and put the line it printed
634
+ instead — SNAPSHOT_INIT_FAILED, or the whole SNAPSHOT_TREE_MISMATCH= value with
635
+ both hashes — in \`repoError\`. The init is what makes the snapshot MEASURABLE:
636
+ specialists run this repository's own suite in there, and a suite with tests
637
+ that need a working tree reports fewer passes and more failures in a bare
638
+ extraction than in a checkout at the same commit, with nothing in the payload
639
+ saying the measurement happened somewhere else (#1056). The tree-hash compare is
640
+ the verification: two commits whose trees hash the same hold byte-identical
641
+ content, so a match settles that the snapshot IS the reviewed tree — a stronger
642
+ check than reading a few files, and the reason the commit comes BEFORE the
643
+ node_modules symlink, which would otherwise enter the index and change the hash.
644
+
645
+ Report \`head\` = the full sha 'git -C ${worktree} rev-parse HEAD' prints — the
646
+ destination path carries only the short form. The byte-identity spot check this
647
+ step used to ask for is superseded by the tree-hash compare above, which settles
648
+ every file in the tree rather than a couple of them. Do not modify ${worktree}.
649
+
650
+ Every path in the block above is absolute or \`-C\`-anchored on purpose: this
651
+ dispatch carries no working directory of its own either, so you start in the
652
+ controller's own checkout, and a relative path — a \`tar -x\` with no \`-C\`, a
653
+ bare \`git\` — reads or writes THERE (#1433). Add nothing relative to it, and
654
+ chain a \`cd\` into "$RUN" or "$SNAP" for anything you run beyond it.
655
+
656
+ Then capture the PR's diff for the specialists, plus the three facts the caller
657
+ needs to judge whether it is usable:
658
+
659
+ gh pr diff ${pr} > "$RUN"/pr.diff
660
+ crossRepo=$(gh pr view ${pr} --json isCrossRepository -q .isCrossRepository)
661
+ branch=$(gh pr view ${pr} --json headRefName -q .headRefName)
662
+ ref=""
663
+ [ "$crossRepo" = "true" ] || ref=$(git -C ${worktree} ls-remote origin "refs/heads/$branch" | cut -f1)
664
+ [ -n "$ref" ] || ref=$(git -C ${worktree} ls-remote origin "refs/pull/${pr}/head" | cut -f1)
665
+ echo "$ref"
666
+ gh pr view ${pr} --json headRefOid -q .headRefOid
667
+ wc -l < "$RUN"/pr.diff
668
+
669
+ Report \`diffPath\` = the SNAPSHOT_RUN_ROOT value with '/pr.diff' appended, ONLY
670
+ if 'gh pr diff' exited 0. Report \`refHead\` = the sha the 'echo "$ref"' line
671
+ printed, \`prHead\` = the headRefOid and \`diffLines\` = the wc -l count. Which
672
+ read answers is chosen by \`isCrossRepository\`, not by whether the first read
673
+ comes back empty. A same-repo PR's branch cannot collide with anything else on
674
+ 'origin', so its branch ref is read and is the operand — one network read, same
675
+ as before. A cross-repo PR (a fork) skips the branch-ref read entirely and goes
676
+ straight to 'refs/pull/${pr}/head' — the base repo's own copy of the PR head —
677
+ because a fork's branch NAME is not guaranteed unique against the base
678
+ repository, and a same-named hit on 'origin' would silently answer for the
679
+ wrong repository rather than for the fork (#1616). The fallback to
680
+ 'refs/pull/${pr}/head' also still fires for a same-repo PR whose branch ref
681
+ came back empty, unchanged from before. Omit \`refHead\` when every read this
682
+ PR was entitled to came back empty or was skipped: an absent value is neither
683
+ a match nor a mismatch. Do not judge whether the diff is usable, and do not
684
+ withhold one field because another failed: report what you got and let the
685
+ caller decide.
686
+
687
+ Then read this repository's Test entrypoint out of its Recipe cache:
688
+
689
+ ~/.fleet/bin/fleet-run derive-testcmd.sh ${worktree} test
690
+
691
+ Report \`testCmd\` = its stdout ONLY if it exited 0. If it exited non-zero,
692
+ report \`testCmdError\` = its stderr and omit \`testCmd\`. Never derive or
693
+ guess a command yourself: a refusal names the step that writes the cache, and
694
+ the caller acts on it.
695
+
696
+ Then size the diff:
697
+
698
+ ~/.fleet/bin/fleet-run diff-stats.mjs --pr ${pr}
699
+
700
+ Report \`runRoot\` = the SNAPSHOT_RUN_ROOT value and \`path\` = the SNAPSHOT_DEST
701
+ value, both copied verbatim. Each ends in a component the shell substituted —
702
+ a 'mktemp' name, and a sha — so neither is readable off this prompt: do not
703
+ reconstruct it, and do not report a path the block did not print. The caller
704
+ checks both against the run root it provisioned and refuses the review when
705
+ they disagree, so a reconstructed path costs the run rather than sending six
706
+ specialists into another run's tree. Report the HEAD sha, and — in
707
+ \`diffStats\` — the SINGLE-LINE JSON object diff-stats.mjs prints to
708
+ STDOUT, copied verbatim. Only runRoot, path, head, pathVerified and repoVerified
709
+ are ever required — diffStats, diffPath, diffLines, refHead and prHead are each
710
+ omitted independently when their command failed, and repoError only accompanies
711
+ a false repoVerified.`,
712
+ { label: "snapshot", phase: "Snapshot", agentType: SNAPSHOT_AGENT_TYPE, schema: SNAPSHOT_SCHEMA },
713
+ );
714
+
715
+ if (snap) {
716
+ if (typeof snap.head === "string") snap.head = snap.head.trim().toLowerCase();
717
+ if (typeof snap.refHead === "string") snap.refHead = snap.refHead.trim().toLowerCase();
718
+ if (typeof snap.prHead === "string") snap.prHead = snap.prHead.trim().toLowerCase();
719
+ }
720
+
721
+ const missingReason = snapshotMissing(snap, runRootPrefix);
722
+ if (missingReason) throw new Error(`review-pr: ${missingReason}`);
723
+
724
+ log(`snapshot ${snap.head} at ${snap.path} — head ref ${snap.refHead || "(absent): head check SKIPPED"} — PR head ${snap.prHead ?? "(absent)"}`);
725
+ log(environmentNote(snap));
726
+
727
+ const testCmd = resolveTestCmd(A.testCmd, snap);
728
+ log(`testCmd ${A.testCmd ? "(caller override)" : "(derived)"} ${testCmd}`);
729
+
730
+ const usable = usableDiff(snap);
731
+ log(
732
+ usable
733
+ ? `diff ${usable} (${snap.diffLines} lines)`
734
+ : `no diff — diffPath=${snap.diffPath ?? "(absent)"} diffLines=${snap.diffLines ?? "(absent)"} refHead=${snap.refHead ?? "(absent)"} prHead=${snap.prHead ?? "(absent)"} head=${snap.head} — specialists get the fallback read rules`,
735
+ );
736
+
737
+ let stats = null;
738
+ if (snap.diffStats) {
739
+ try {
740
+ stats = JSON.parse(snap.diffStats);
741
+ } catch {
742
+ stats = null;
743
+ }
744
+ }
745
+ const dimensions = explicitDimensions || selectDimensions(DEFAULT_DIMENSIONS, stats);
746
+ log(
747
+ `dimensions ${dimensions.length}/${DEFAULT_DIMENSIONS.length} [${dimensions.map((d) => d.key).join(", ")}]` +
748
+ (stats && stats.profile ? ` — profile=${stats.profile}` : " — profile unknown, full set") +
749
+ (stats && SIZE_TIER_PROFILES.has(stats.profile) && !explicitDimensions ? " — size tier" : ""),
750
+ );
751
+ log(`agents dispatched ${dimensions.map((d) => `${d.key}=${d.agentType}`).join(" ")}`);
752
+
753
+ const dimensionsUnrun = [];
754
+ // #1433. Per-dimension record of the specialist's own CWD-AUDIT line (see
755
+ // `cwdAuditFrom` above) — `{dimension, state, line}`, `state` one of
756
+ // "clean"/"dirty"/"unrepo"/"missing". Populated for every dispatched
757
+ // review that returned at all (a crashed dispatch has nothing to audit,
758
+ // and is already named in `dimensionsUnrun` via `unrunCrashed` below), so
759
+ // a dirty checkout, or an omitted audit, reaches the payload instead of
760
+ // dead-ending inside `scope_searched`.
761
+ const cwdAudit = [];
762
+
763
+ // #1433. Both prompts below carry the inherited-cwd rule, and it is stated in
764
+ // each rather than shared: review-eval.mjs's own header holds the measurement
765
+ // and the reason this is prompt prose at all (no dispatch primitive takes a
766
+ // per-call cwd), and #496's brief rules the shared-source route out for
767
+ // exactly these blocks. Three parts, in this order, because the last two are
768
+ // inert without the first: the cwd the specialist starts in is NAMED as a
769
+ // tree it must not write to, `pwd` fixes which directory that is, and the
770
+ // `CWD-AUDIT:` line is what makes a clean run say so — an audit reported
771
+ // only when dirty is indistinguishable from one never run, the same reading
772
+ // `unrunReason` applies to a `test_run` that reports nothing.
773
+ phase("Review");
774
+ const reviewed = await pipeline(
775
+ dimensions,
776
+ // #1802: a crashed specialist (null or thrown) is re-dispatched once
777
+ // before it counts as unrun. A specialist that RETURNED is never re-run
778
+ // here, whatever its `test_run` says — that is `unrunEntries`' case.
779
+ (d) =>
780
+ retryCrashed(
781
+ () =>
782
+ agent(
783
+ `Review PR #${pr} (branch ${branch}) for: ${d.prompt}
784
+
785
+ READ ONLY FROM THE SNAPSHOT: ${snap.path} (HEAD ${snap.head}) — plus the diff
786
+ file named below, if one is given.
787
+ Never read or write ${worktree} — other agents are using it.
788
+ Run any mutation or probe work inside your own copy of the snapshot.
789
+
790
+ Your shell starts in NEITHER of those directories, and what it does start in is
791
+ a tree you must not write to: this dispatch carries no working directory of its
792
+ own, so you begin wherever the controller's own review cell is standing — its
793
+ checkout, the tree it reads instruments.sh, ci-state.mjs and every gate decision
794
+ out of. A relative path in any command lands THERE, not in the snapshot and not
795
+ in your scratch dir. Run \`pwd\` as your FIRST command and keep the path it
796
+ prints; that directory is a no-run zone from then on, and every command after it
797
+ chains its own \`cd\` into the snapshot or into your scratch dir, both named
798
+ in this prompt as absolute paths.
799
+
800
+ ${readRules(usableDiff(snap), stats, snap)}
801
+
802
+ Tests: from the snapshot's root, run exactly this — copy it verbatim:
803
+ ${testCmd}
804
+ Do not substitute a command of your own. In a repo that has a shared test stack,
805
+ a bare runner picks up a default config whose setup can tear a sibling's
806
+ container down mid-run; a guessed glob is worse in every repo, because one
807
+ matching nothing still exits 0 reporting 'tests 0' — a green that ran nothing.
808
+ Whatever you run, report it in \`test_run\` — the command verbatim and the counts
809
+ you saw — even when it failed or produced nothing.
810
+ 'tests 0' is a FAILED run, not a pass: \`tests: 0\` is how this dimension gets
811
+ reported unrun, and an empty findings list cannot say it for you. So is a run
812
+ that collected tests and did none of the work — 0 passes with no failures is
813
+ everything skipped. And a count well below what the whole tree reports means you
814
+ ran a PARTIAL copy: nothing downstream can catch that one for you, because only
815
+ your own run knows what the full tree reports. Run from the snapshot's root, and
816
+ report any of these as unrun.
817
+
818
+ ${environmentNote(snap)}
819
+
820
+ A failure you cannot separate from the environment is neither a finding nor a
821
+ reason to file nothing — say which it is, beside the counts, in \`test_run\`.
822
+ Scratch files go in ${snap.runRoot}/${d.key}/ and nowhere else. Chain the
823
+ directory change into the command, \`cd "$D" && git …\`, never
824
+ \`cd "$D"; git …\`, so a failed \`cd\` cannot leave a \`git\` command running in the
825
+ checkout — and bracket a fixture's own git with \`git rev-parse --show-toplevel\`:
826
+ before \`git init\` it must NOT resolve to the repository, and a fresh scratch
827
+ dir's \`fatal: not a git repository\` (exit 128) is the pass, not a failure;
828
+ before any \`git commit\` it must resolve to your scratch path — compare
829
+ resolved forms (\`realpath\`), since \`--show-toplevel\` can report
830
+ \`/private/tmp/…\` for a \`/tmp\` scratch dir on macOS.
831
+
832
+ Report only what you RAN. A claim you reasoned to but did not execute belongs
833
+ in 'suggestion', not 'critical'. State your search scope for every negative
834
+ claim.
835
+
836
+ Then audit the directory that first \`pwd\` printed, before you return:
837
+ \`git -C <that path> status --porcelain -uall\` — the explicit untracked mode,
838
+ never bare \`--porcelain\`, which a \`status.showUntrackedFiles=no\` config
839
+ silences into a false clean. Report the result in \`scope_searched\` as one line
840
+ beginning \`CWD-AUDIT:\` — \`CWD-AUDIT: clean <path>\` when it printed nothing,
841
+ \`CWD-AUDIT: dirty <path> — <what it printed>\` when it printed anything,
842
+ \`CWD-AUDIT: unrepo <path>\` when git answered \`fatal: not a git repository\` —
843
+ every run, clean or not: a clean tree is the result this check exists to
844
+ produce, and an omitted line reads exactly like a check never run. Three PRs
845
+ reviewed from one cell left four files modified in that checkout with nothing in
846
+ any payload saying so (#1433), so a path you cannot account for is still yours
847
+ to name.`,
848
+ { label: `review:${d.key}`, phase: "Review", agentType: d.agentType, schema: FINDINGS_SCHEMA },
849
+ ),
850
+ (review) => !review,
851
+ ),
852
+
853
+ (review, d) => {
854
+ dimensionsUnrun.push(...unrunEntries(review, d.key));
855
+ cwdAudit.push({ dimension: d.key, ...cwdAuditFrom(review && review.scope_searched) });
856
+ phase("Verify");
857
+ return parallel(
858
+ (review && review.findings ? review.findings : []).map((f, fi) => () => {
859
+ const n = verifiersForRun(f.severity);
860
+ if (n === 0) return Promise.resolve({ ...f, dimension: d.key, ...verdictFor(0, []) });
861
+ // #1802: a pair whose EVERY vote died (or whose dispatch threw) is
862
+ // re-dispatched once, as a pair, before `verdictFor` reads it — one
863
+ // live vote means the pair did not crash and is ruled on that vote.
864
+ return retryCrashed(
865
+ () =>
866
+ parallel(
867
+ Array.from({ length: n }, (_, i) => () =>
868
+ agent(
869
+ `Try to REFUTE this finding from PR #${pr}. Default to refuted=true if uncertain.
870
+
871
+ claim: ${f.claim}
872
+ where: ${f.file || "?"}:${f.line || "?"}
873
+ evidence: ${f.evidence}
874
+
875
+ Verify against the snapshot ${snap.path} by RUNNING something — compile it, run
876
+ the test, apply the mutation. Do not reason your way to agreement. Observe
877
+ that run synchronously — run the command, wait for it, read its exit code.
878
+ Never poll a log file for a completion marker: prefer ONE blocking run to a
879
+ poll loop, and treat its return as permission to look, never as the answer.
880
+ Reading a log the run has already finished writing is fine; waiting on one is
881
+ not. If you match a test reporter's own output, accepting both \`ℹ\` and \`#\`
882
+ is necessary but NOT sufficient — strip SGR escapes first as well. node's
883
+ prefix moves with the node version and with whether stdout is a TTY, and
884
+ color wraps the whole line so it begins with ESC and no prefix anchor matches
885
+ at all, which returns empty at exit 0 — indistinguishable from a hung run and
886
+ from a run of zero tests. For an uncolored baseline use \`env -u FORCE_COLOR\`;
887
+ \`FORCE_COLOR=\` empty still enables color, so it is not a control. State your
888
+ search scope AND what your pattern would have missed. A grep over one ref
889
+ does not support a claim about history; a pattern built from the token a diff
890
+ removed does not support a claim that the category is empty.
891
+
892
+ Chain the directory change into the command, \`cd "$D" && git …\`, never
893
+ \`cd "$D"; git …\`, so a failed \`cd\` cannot leave a \`git\` command running in the
894
+ checkout — and bracket a fixture's own git with \`git rev-parse --show-toplevel\`:
895
+ before \`git init\` it must NOT resolve to the repository, and a fresh scratch
896
+ dir's \`fatal: not a git repository\` (exit 128) is the pass, not a failure;
897
+ before any \`git commit\` it must resolve to your scratch path — compare
898
+ resolved forms (\`realpath\`), since \`--show-toplevel\` can report
899
+ \`/private/tmp/…\` for a \`/tmp\` scratch dir on macOS.
900
+
901
+ A failure injection with no positive control has produced NO result, never a
902
+ negative one. Before you read an injected fault — an env var, an argv word, a
903
+ mutant — as having had no effect, prove the injection reached the child: one run
904
+ whose output differs with it present versus absent, or the child echoing the
905
+ injected value back. Uncontrolled, the cell is unrun — say so in your verdict
906
+ instead of reporting a no-effect result. Build such an invocation as an array
907
+ expanded braced and quoted — \`cfg=(SETB=1 BADJ=1); env "\${cfg[@]}" sh
908
+ ./probe.sh\` — or inline the assignments literally — \`env SETB=1 BADJ=1 sh
909
+ ./probe.sh\`; NEVER from an unquoted scalar — \`cfg="SETB=1 BADJ=1"; env $cfg sh
910
+ ./probe.sh\` — which under zsh passes ONE argument, sets a variable literally
911
+ named \`SETB\` to \`1 BADJ=1\`, never sets \`BADJ\` at all, and still exits 0.
912
+ \`env $cfg[@]\` is not the portable spelling either: measured, bash
913
+ word-splits it into \`SETB=1\` and \`BADJ=1[@]\`, so the injection variable
914
+ is set to a corrupted value, while zsh behaves exactly as with the bare
915
+ \`$cfg\` — \`BADJ\` never set, exit 0.
916
+
917
+ ${readRules(usableDiff(snap), stats, snap)}
918
+
919
+ ${environmentNote(snap)}
920
+
921
+ Lens ${i + 1}: ${i === 0 ? "is the claim true of the code as merged?" : "is it already handled elsewhere, or does the evidence prove something weaker than the claim?"}
922
+ Scratch: ${snap.runRoot}/verify-${d.key}/f${fi + 1}-l${i + 1}/
923
+ Everything you write — mutants, fixtures, scratch repos — goes there and nowhere
924
+ else, and your shell does not start there: this dispatch carries no working
925
+ directory of its own, so you begin wherever the controller's own review cell is
926
+ standing — its checkout, the tree it reads every gate decision out of — and a
927
+ relative path in any command lands THERE. Run \`pwd\` as your FIRST command and
928
+ keep the path it prints; that directory is a no-run zone from then on, and the
929
+ snapshot and your scratch dir are both named above as absolute paths.
930
+ Then audit that directory before you return: \`git -C <that path> status
931
+ --porcelain -uall\` — the explicit untracked mode, never bare \`--porcelain\`,
932
+ which a \`status.showUntrackedFiles=no\` config silences into a false clean.
933
+ Report it in \`reason\` as one line beginning \`CWD-AUDIT:\` —
934
+ \`CWD-AUDIT: clean <path>\` when it printed nothing, \`CWD-AUDIT: dirty <path> —
935
+ <what it printed>\` when it printed anything, \`CWD-AUDIT: unrepo <path>\` when
936
+ git answered \`fatal: not a git repository\` — every run, clean or not: an
937
+ omitted line reads exactly like a check never run, and applying a mutation is
938
+ how three reviews from one cell left four files modified in that checkout
939
+ (#1433).`,
940
+ { label: `verify:${d.key}`, phase: "Verify", agentType: VERIFIER_AGENT_TYPE, schema: VERDICT_SCHEMA },
941
+ ),
942
+ ),
943
+ ),
944
+ (votes) => !(votes && votes.some(Boolean)),
945
+ ).then(
946
+ (votes) => ({ ...f, dimension: d.key, ...verdictFor(n, votes) }),
947
+ // #1813: a rejection here means retryCrashed's OWN final attempt
948
+ // rejected — both dispatches of this finding's refuter pair
949
+ // crashed, not just returned no votes. Left unhandled, that
950
+ // rejection propagates into the shared `parallel()` above (a bare
951
+ // Promise.all), which rejects the WHOLE dimension and is caught by
952
+ // the coarser per-dimension `catch` in `pipeline()` — discarding
953
+ // every OTHER finding in this dimension too, including ones whose
954
+ // refuters fully succeeded. Folding it into the same shape a
955
+ // live-but-empty vote array already produces (`verdictFor(n, [])`
956
+ // — verdict "unverified", refutersDispatched: n) keeps this
957
+ // finding's crash local: it still flows into `unverified`,
958
+ // `resumeFor`'s `crashed` bucket and `counts.crashed` exactly like
959
+ // a partial-vote crash does, instead of erasing its dimension-mates.
960
+ () => ({ ...f, dimension: d.key, ...verdictFor(n, []) }),
961
+ );
962
+ }),
963
+ );
964
+ },
965
+ );
966
+
967
+ dimensionsUnrun.push(...unrunCrashed(reviewed, dimensions));
968
+
969
+ const all = reviewed.flat().filter(Boolean);
970
+ const survived = all.filter((f) => f.verdict === "survived");
971
+ const refuted = all.filter((f) => f.verdict === "refuted");
972
+ const unverified = all.filter((f) => f.verdict === "unverified");
973
+
974
+ const { crashed, resume } = resumeFor(unverified);
975
+
976
+ log(
977
+ `${survived.length} survived, ${refuted.length} refuted, ${unverified.length} unverified ` +
978
+ `(${crashed.length} of those by crashed refuters), of ${all.length}`,
979
+ );
980
+
981
+ const rank = { critical: 0, important: 1, suggestion: 2 };
982
+ const bySeverity = (a, b) => (rank[a.severity] ?? 3) - (rank[b.severity] ?? 3);
983
+
984
+ // Refuted findings are RETURNED, not dropped. A refutation is itself a claim,
985
+ // and the controller has reversed a refutation on new evidence before.
986
+ // `unverified` are findings the adversarial pass did not settle — a suggestion
987
+ // that skipped it by policy, or one whose refuters all crashed — surfaced
988
+ // separately so the caller never mistakes "not checked" for "survived".
989
+ // `dimensionsRun` names what was DISPATCHED after the size trim: a trimmed
990
+ // fan-out must say so, never read as full coverage. It is not a coverage claim
991
+ // on its own and never was — a specialist can be dispatched and die, or run and
992
+ // never execute the suite — so `dimensionsUnrun` names which of those keys did
993
+ // not cover their ground, and why. A key in the first and NOT in the second ran
994
+ // a suite — not that it is covered (#535). `unrunReason` reads `test_run`'s
995
+ // counts and quotes `run.command` into its message; it never compares that
996
+ // command against the one the dispatch handed out, so a specialist that
997
+ // substituted a narrower runner is not classified unrun.
998
+ //
999
+ // The two are siblings rather than one filtered list because they answer
1000
+ // different questions. Subtracting the unrun ones from `dimensionsRun` would
1001
+ // make a crashed dimension indistinguishable from one the size tier never
1002
+ // dispatched — this ticket set's own defect, moved one field over.
1003
+ //
1004
+ // #1802. Digest first, in DIGEST_KEYS order, bulk last — see DIGEST_KEYS
1005
+ // above for why the order is the contract.
1006
+ return {
1007
+ pr,
1008
+ head: snap.head,
1009
+ // The recovery, next to the fields a controller reads first; null unless
1010
+ // a refuter pair crashed again after the in-run retry.
1011
+ resume,
1012
+ // #1056. Always present, in both regimes: a reader of this payload can
1013
+ // never be left unable to tell an environment artifact from a regression,
1014
+ // and that costs nothing when there is nothing wrong to report.
1015
+ testEnvironment: environmentNote(snap),
1016
+ dimensionsRun: dimensions.map((d) => d.key),
1017
+ dimensionsUnrun,
1018
+ // #1433. `cwdAuditFrom`'s per-dimension read of the specialist's own
1019
+ // CWD-AUDIT line — the fact a dirty or unrepo'd inherited checkout is
1020
+ // otherwise reported into `scope_searched` and read by nothing.
1021
+ cwdAudit,
1022
+ counts: { survived: survived.length, refuted: refuted.length, unverified: unverified.length, crashed: crashed.length },
1023
+ snapshot: snap.path,
1024
+ survived: survived.sort(bySeverity),
1025
+ refuted,
1026
+ unverified: unverified.sort(bySeverity),
1027
+ };
1028
+ }