@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,186 @@
1
+ import { test } from "node:test";
2
+ import assert from "node:assert/strict";
3
+ import { readFileSync } from "node:fs";
4
+ import { join } from "node:path";
5
+ import { logicalLines } from "./prose-pin.mjs";
6
+
7
+ // #197. `review-and-fix.md` points at its own blocks by name — "see **X**" —
8
+ // and the emphasised block it names carried trailing content INSIDE the
9
+ // emphasis, so the name in the pointer was never the string on the target.
10
+ // That reads fine linearly and fails exactly one way: an agent that greps for
11
+ // the pointer string finds the pointer and nothing else, i.e. the citation
12
+ // resolves to itself. Same class as `review-pr-citation-prose.test.mjs`, one
13
+ // document inward — there the citation was a line number, here it is a name.
14
+ //
15
+ // THE CEILING: this proves every pointer NAME resolves to a distinct target,
16
+ // nothing about the target being the right block or saying the right thing. A
17
+ // pointer renamed in lockstep with its target stays green, correctly. The
18
+ // pointer LIST is derived from the document rather than hardcoded, so a pointer
19
+ // added later is covered without editing this file — and so this file cannot
20
+ // satisfy its own pins. Only the floor under that list, `PINNED` below, is a
21
+ // literal, because a derived count cannot notice itself shrinking.
22
+ //
23
+ // #1609: both scans below run over the document's LOGICAL lines, never its
24
+ // physical ones. Every regex here is single-line by necessity — a clause must
25
+ // not run past its own paragraph, and a target must lead its block — so a
26
+ // rewrap of the runbook used to move the document out from under them: pure
27
+ // reflow of step 4, not one word changed, took the pointer list from 5 names
28
+ // to 3 and retired two pins by deleting them. `logicalLines` puts the wrap
29
+ // tolerance in the INPUT so the regexes keep their bounds; `lineAt` maps a hit
30
+ // back to the physical line a reader opens.
31
+ const REPO = join(import.meta.dirname, "..");
32
+ const DOC = "commands/review-and-fix.md";
33
+ const TEXT = readFileSync(join(REPO, DOC), "utf8");
34
+
35
+ // A pointer clause is `see` plus one or more emphasised names joined by `and`,
36
+ // `or` or a comma, either of the last two optionally preceded by a comma —
37
+ // `see **A**, **B**, and **C** below`. Without the optional comma the last name
38
+ // of an Oxford list is dropped and never pinned at all.
39
+ const CLAUSE = /[Ss]ee ((?:\*\*[^*\n]+\*\*)(?:(?:,? and|,? or|,) \*\*[^*\n]+\*\*)*)/g;
40
+ const BOLD = /\*\*([^*\n]+)\*\*/g;
41
+
42
+ // Both scans over ONE document, as a function rather than straight-line module
43
+ // scope: the reflow pin at the bottom has to run this exact extraction over a
44
+ // rewrapped copy, and a second local copy of the scan would pin only itself
45
+ // while the real one reverted to physical lines.
46
+ function scan(doc) {
47
+ const { text: SCAN, lineAt } = logicalLines(doc);
48
+ const pointers = [];
49
+ for (const clause of SCAN.matchAll(CLAUSE)) {
50
+ const base = clause.index + clause[0].indexOf(clause[1]);
51
+ for (const name of clause[1].matchAll(BOLD)) {
52
+ pointers.push({ text: name[1], offset: base + name.index, line: lineAt(base + name.index) });
53
+ }
54
+ }
55
+
56
+ // A target is a BLOCK, so only block-leading emphasis is one. Matching ANY
57
+ // emphasis here is what makes this suite stop discriminating: every bold span
58
+ // CLAUSE does not recognise as a pointer would register as a target, so one
59
+ // pointer resolves to another pointer and the file greens on exactly the
60
+ // defect #197 was filed for. The offset exclusion below is belt-and-braces —
61
+ // a clause always has `see ` before its first name, so a pointer is never
62
+ // block-leading — and it holds the invariant independently of this regex.
63
+ //
64
+ // Scanning the joined view is what makes `^` mean block-leading rather than
65
+ // wrap-leading: on the raw bytes, a `**Bold**` a reflow happens to push to
66
+ // column 0 mid-paragraph registers as a target, and a pointer then resolves
67
+ // to a block the wrap invented — the same reflow, failing green not red.
68
+ const pointerOffsets = new Set(pointers.map((p) => p.offset));
69
+ const targets = new Map();
70
+ for (const span of SCAN.matchAll(/^\*\*([^*\n]+)\*\*/gm)) {
71
+ if (pointerOffsets.has(span.index)) continue;
72
+ if (!targets.has(span[1])) targets.set(span[1], lineAt(span.index));
73
+ }
74
+ for (const heading of SCAN.matchAll(/^#{1,6} +(.+?)\s*$/gm)) {
75
+ if (!targets.has(heading[1])) targets.set(heading[1], lineAt(heading.index));
76
+ }
77
+ return { pointers, targets };
78
+ }
79
+
80
+ const { pointers, targets } = scan(TEXT);
81
+
82
+ // The count, not merely non-emptiness: PARTIAL degradation is the real hole.
83
+ // Reword one clause's verb and that pointer's pin silently disappears while
84
+ // the survivors keep the suite green — measured, a single `see` → `consult`
85
+ // retires a pin with no signal at all. Bump this deliberately when a pointer
86
+ // is genuinely retired from the document; never to silence a red.
87
+ const PINNED = 5;
88
+ test("every pointer clause in the document is still recognised", () => {
89
+ assert.ok(
90
+ pointers.length >= PINNED,
91
+ `${DOC} yields ${pointers.length} pointer names, expected at least ${PINNED} — a drop means a pointer was rephrased OUT of the \`see **…**\` shape rather than removed from the document, so its pin below stopped running instead of failing. Restore the clause shape, or lower ${PINNED} only once you have confirmed the pointer is gone from ${DOC} for good.`,
92
+ );
93
+ });
94
+
95
+ for (const p of pointers) {
96
+ test(`the pointer to "${p.text}" at :${p.line} resolves to a target`, () => {
97
+ assert.ok(
98
+ targets.has(p.text),
99
+ `${DOC}:${p.line} points at **${p.text}**, but no block in the file is emphasised as exactly that string — a literal search for the pointer finds only the pointer. Move any trailing punctuation or trailing clause OUTSIDE the target's \`**…**\` so the emphasised span is verbatim what the pointer names.`,
100
+ );
101
+ });
102
+ }
103
+
104
+ // #1609, the pin the two above could not carry. Both of them read the document
105
+ // as it is checked in — one physical line per paragraph — so neither notices
106
+ // that every regex up there is `\n`-hostile by necessity. Measured against the
107
+ // physical-line scan this replaced, reflowing this file with not one word
108
+ // changed: at 80 columns the pointer list goes 5 names → 4, at 45 → 2, and
109
+ // the pins for the names it loses do not fail, they stop existing. Targets go
110
+ // the same way and vary more sharply by width, not a flat count — three
111
+ // block-leading `**…**` spans stop being targets at 80 columns, six at 60,
112
+ // and six again at 45, because the wrap lands inside the emphasis. At 45
113
+ // columns alone, up to four NEW ones also appear (`skipped`, `default`,
114
+ // `run-binding`, `critical/important`) because the wrap pushed a
115
+ // mid-paragraph bold to column 0. That last set is the silent direction: a
116
+ // pointer resolving to a block the reflow invented.
117
+ //
118
+ // Reflowed HERE rather than committed as a fixture: a checked-in rewrapped copy
119
+ // rots away from the real document the moment someone edits one and not the
120
+ // other, and this has to hold for the runbook's CURRENT words. The word-identity
121
+ // assert is what keeps the fixture honest — a `reflow` that garbled the text
122
+ // would make the comparison below trivially true against garbage on both sides.
123
+ // It is necessary and not sufficient: whitespace-normalised equality cannot see
124
+ // INDENT, and the first cut of this helper silently de-indented every wrapped
125
+ // paragraph's opening line while passing that assert. The target-set compare
126
+ // below is what caught it, which is the same thing it is here to catch.
127
+ const reflow = (text, cols) => {
128
+ const out = [];
129
+ let fenced = false;
130
+ for (const line of text.split("\n")) {
131
+ if (/^ {0,3}(?:```|~~~)/.test(line)) fenced = !fenced;
132
+ // A hard break is authored, not a wrap point — an editor does not reflow
133
+ // through one, and neither does `logicalLines`.
134
+ if (fenced || line.length <= cols || /(?:[ \t]{2}|\\)$/.test(line)) {
135
+ out.push(line);
136
+ continue;
137
+ }
138
+ // Two indents, not one. `lead` keeps the opening line where the author put
139
+ // it — dropping it promotes an indented continuation paragraph to a
140
+ // top-level one, a structural edit — and `indent` puts every wrapped line
141
+ // past a list marker, because wrapping a list item flush left would turn
142
+ // its tail into a new paragraph.
143
+ const lead = line.match(/^[ \t]*/)[0];
144
+ const indent = " ".repeat(line.match(/^(?:[ \t]*(?:[-*+]|\d+[.)])[ \t]+|[ \t]*)/)[0].length);
145
+ const words = line.slice(lead.length).split(" ").filter(Boolean);
146
+ let cur = lead + (words.shift() ?? "");
147
+ for (const word of words) {
148
+ if (`${cur} ${word}`.length > cols) {
149
+ out.push(cur);
150
+ cur = indent + word;
151
+ } else cur = `${cur} ${word}`;
152
+ }
153
+ out.push(cur);
154
+ }
155
+ return out.join("\n");
156
+ };
157
+
158
+ // Three widths: 80 is an ordinary editor wrap, 45 splits inside the emphasised
159
+ // names themselves, and 60 sits between and loses a DIFFERENT pointer than 80
160
+ // does. One width alone measures one accident of where the breaks landed.
161
+ for (const cols of [80, 60, 45]) {
162
+ test(`a pure reflow of ${DOC} at ${cols} columns changes no pointer and no target`, () => {
163
+ const rewrapped = reflow(TEXT, cols);
164
+ assert.notEqual(rewrapped, TEXT, `reflow at ${cols} columns changed nothing — this pin is not exercising a rewrap`);
165
+ assert.equal(
166
+ rewrapped.replace(/\s+/g, " ").trim(),
167
+ TEXT.replace(/\s+/g, " ").trim(),
168
+ "the reflow fixture changed the document's words, so the comparison below would prove nothing",
169
+ );
170
+ const after = scan(rewrapped);
171
+ assert.deepEqual(
172
+ after.pointers.map((p) => p.text),
173
+ pointers.map((p) => p.text),
174
+ `rewrapping ${DOC} at ${cols} columns changes which pointers this file finds — the scan is reading physical lines again, so an author who reflows a paragraph silently retires the pins for every pointer the wrap split.`,
175
+ );
176
+ // The other direction, and the one that fails GREEN: a target lost to the
177
+ // wrap takes its pointer's pin down as a spurious red, and a `**Bold**`
178
+ // that the wrap pushes to column 0 mid-paragraph is a target the reflow
179
+ // invented — one more block for a pointer to resolve to for free.
180
+ assert.deepEqual(
181
+ [...after.targets.keys()],
182
+ [...targets.keys()],
183
+ `rewrapping ${DOC} at ${cols} columns changes which blocks count as targets — block-leading emphasis is being read as "starts a physical line" rather than "starts a block".`,
184
+ );
185
+ });
186
+ }
@@ -0,0 +1,417 @@
1
+ #!/usr/bin/env node
2
+ // Report file/module/directory/prose-citation overlap between two PRs.
3
+ //
4
+ // This computes the four signals of run-merge-bot.md's hold rule. It REPORTS
5
+ // them and never reaches a verdict: "a fired signal is not a verdict — disprove
6
+ // it" is judgement, and a script that ruled would recreate the blind-obey
7
+ // failure the rule exists to prevent.
8
+ //
9
+ // Exit 0 for every verdict, `none` included. Exit 2 when the answer is unknown —
10
+ // bad usage, or a query failed. The fourth signal is the one exception to that
11
+ // last clause and says so in its own field: a `prose` scan that could not run
12
+ // degrades to `proseUnrun` rather than taking the other three down with it.
13
+
14
+ import { execFileSync } from "node:child_process";
15
+ import { gitEnv } from "./git-env.mjs";
16
+ import { basename, dirname, extname } from "node:path";
17
+ import { makeDie, defineFlags } from "./arg.mjs";
18
+
19
+ const NAME = "pr-overlap";
20
+
21
+ // die()/numArg() shared with the other fleet scripts — see arg.mjs for the
22
+ // fail-open (#61/#169/#878) and pipe-safety (#176/#328) rationale. `--a`/`--b`
23
+ // given trailing already died via the usage guard below — `undefined` is
24
+ // falsy — so this file was never a silent-widening site on its own. But `--a`
25
+ // given `--b` as its "value" (`pr-overlap.mjs --a --b 5`) was NOT caught that
26
+ // way: `a` becomes the string "--b", passes the falsy check, and only failed
27
+ // later as a confusing `gh pr diff --b` error — the shared arg() rejects it
28
+ // here, by name, instead.
29
+ //
30
+ // numArg() rather than arg() because the falsy check missed the other half
31
+ // too, and this file is why #878 could not be swept by grepping for
32
+ // `arg("pr")`: the same fail-open arrives here under `--a`/`--b`. Measured on
33
+ // the pre-fix tree, `--a abc --b def` printed `{"a":null,"b":null,…}` at exit
34
+ // 0 carrying a real `signal: "files"` verdict — `gh pr diff` resolves a
35
+ // non-numeric ref as a BRANCH, so the overlap underneath was genuine and
36
+ // about two PRs nobody named.
37
+ const die = makeDie(NAME);
38
+ const { numArg, sweep, stray } = defineFlags(die, { flags: { a: "value", b: "value" } });
39
+
40
+ // `=== null`, not `!a || !b`: numArg() returns a NUMBER, so `--a 0` — a value
41
+ // the caller did give — would otherwise draw the usage line, where gh answers
42
+ // it truthfully as no such PR. The usage line stays this file's own and names
43
+ // both flags at once, which is exactly why numArg() refuses only the
44
+ // MALFORMED half: an absent `--a` has no per-flag wording to give here.
45
+ const a = numArg("a");
46
+ const b = numArg("b");
47
+ if (a === null || b === null) die("usage: pr-overlap.mjs --a <pr> --b <pr>");
48
+ // #365, and here it is the WEAKER half of the fix: both flags are required,
49
+ // so a misspelling of either (`--aa 5 --b 6`) already fell through to the
50
+ // usage die above — refused, just never named. What was NOT refused is a
51
+ // stray alongside two good values (`--a 5 --b 6 --quiet`), silently ignored
52
+ // at exit 0. The sweep closes that and upgrades the first case's message from
53
+ // a usage dump to the offending token. Below the usage guard so the usage
54
+ // text still wins where it is the better answer; above the first gh call.
55
+ sweep();
56
+ // #463: sweep() above only refuses a `--`-prefixed token; a bare or
57
+ // single-dash one (`--a 5 --b 6 stray`) rode along in silence the same way.
58
+ // This file takes no positional, so any leftover token is a stray.
59
+ stray();
60
+
61
+ function changedFiles(pr) {
62
+ console.error(`$ gh pr diff ${pr} --name-only`);
63
+ let out;
64
+ try {
65
+ out = execFileSync("gh", ["pr", "diff", String(pr), "--name-only"], {
66
+ encoding: "utf8",
67
+ });
68
+ } catch (e) {
69
+ // Names the cause, never gh's stderr — execFileSync forwarded it already
70
+ // (no `stdio` above), so interpolating it emits every byte twice, and this
71
+ // is the biggest payload of the fleet scripts. `e.message` is the same
72
+ // string, not a fallback: Node builds it as `Command failed:\n<stderr>`.
73
+ // Three disjoint shapes — Node-aborted (ENOENT/ENOBUFS), signal, exit (#176).
74
+ die(
75
+ `gh pr diff ${pr} failed: ${
76
+ e.code ?? (e.signal ? `killed by ${e.signal}` : `exit ${e.status}`)
77
+ }`,
78
+ );
79
+ }
80
+ const files = out.split("\n").map((s) => s.trim()).filter(Boolean);
81
+ // Fail closed: a PR with no changed files is not a legitimate "no overlap"
82
+ // answer, it is a query that did not work. Silence must never read as data.
83
+ if (files.length === 0) die(`PR ${pr} reported zero changed files — refusing to answer`);
84
+ for (const f of files) console.error(` ${f}`);
85
+ return files;
86
+ }
87
+
88
+ const filesA = changedFiles(a);
89
+ const filesB = changedFiles(b);
90
+
91
+ const intersect = (xs, ys) => {
92
+ const set = new Set(ys);
93
+ return [...new Set(xs)].filter((v) => set.has(v)).sort();
94
+ };
95
+
96
+ // A repo mid-migration has src/…/foo.test.ts in one PR and
97
+ // tests/unit/…/foo.test.ts in the other: same module, zero shared paths. That
98
+ // migration case is what this signal exists for, and it is a TypeScript-module
99
+ // notion — so only files whose extension is actually stripped participate.
100
+ //
101
+ // Matching on bare basenames instead produces confident nonsense: two PRs each
102
+ // touching their own README.md, or their own hooks.json, reported as sharing a
103
+ // "module". Measured in the proving ground: README.md ×8, SKILL.md ×6,
104
+ // mcp-snippet.json ×9, hooks.json ×5 across unrelated directories. Returning
105
+ // null for those drops them from the signal entirely rather than caveating them.
106
+ const moduleOf = (f) => {
107
+ const b = basename(f);
108
+ if (b.endsWith(".test.ts")) return b.slice(0, -".test.ts".length);
109
+ if (b.endsWith(".ts")) return b.slice(0, -".ts".length);
110
+ return null;
111
+ };
112
+ const modulesOf = (fs) => fs.map(moduleOf).filter((m) => m !== null);
113
+
114
+ // Repo root is excluded: every top-level file shares it, so it fires on PRs
115
+ // with nothing whatsoever in common.
116
+ const dirsOf = (fs) => fs.map(dirname).filter((d) => d !== ".");
117
+
118
+ // #705: the three signals above compare paths, modules and directories. They
119
+ // are structurally blind to a coupling that lives in PROSE — one file naming
120
+ // another. The measured case is `docs/metrics/tier-outcomes.tsv`: it is
121
+ // append-only, so every fleet run produces a PR touching it, and the
122
+ // paragraph that reads it lives in `run-team/SKILL.md`. A PR appending rows
123
+ // and a PR rewriting that paragraph edit the same logical section from two
124
+ // different files — run-merge-bot.md's own soft signal — and this script
125
+ // answered `signal=none` on exactly that pair (#703 vs #704). The clearest
126
+ // output the tool has was the one that missed it, which is the dangerous
127
+ // direction: `none` licenses a merge.
128
+ //
129
+ // Derived from the two diffs rather than declared in a `data file → its prose
130
+ // consumers` table, because the table was already stale before it could be
131
+ // written. #705 recorded ONE consumer of `tier-outcomes` (measured at
132
+ // `e540e16`); at `ffa9026` there are eleven — `member-record.mjs`, four
133
+ // `*-prose.test.mjs` guards, three specs and run-team's own SKILL.md. A map
134
+ // seeded from that ticket would have shipped wrong on day one, which is
135
+ // exactly the rot the ticket predicted of it.
136
+
137
+ // Which files can be CITED, and which can carry a citation. Two explicit
138
+ // extension lists, deliberately narrow and deliberately not a file table:
139
+ // #705's own objection to deriving this signal is "a broad net and likely
140
+ // false positives", so the net is bounded and its bounds are printed with the
141
+ // verdict. An extension on neither list does not participate at all.
142
+ //
143
+ // Data side — an artifact whose meaning lives in prose somewhere else. A
144
+ // `.ts` module's consumers are already found by `files`/`modules` above. `.md`
145
+ // is deliberately absent: a doc citing a doc is what `dirs` fires on, and
146
+ // `SKILL.md` recurs 3× in this repo's 251 tracked files (measured), so it is
147
+ // the ambiguous-basename shape `moduleOf` above already refuses to guess at.
148
+ const DATA_EXT = new Set([".tsv", ".csv", ".json", ".jsonl", ".ndjson", ".yml", ".yaml", ".toml"]);
149
+ // Text side — prose, including prose inside a code comment. That half is not
150
+ // hypothetical: run-team/SKILL.md's review section records five production
151
+ // PRs whose whole substance was a comment in a `.js`/`.mjs`/`.sh` file.
152
+ //
153
+ // Disjoint from DATA_EXT on purpose. Adding an extension to both would let a
154
+ // file match its own hunks and fire against itself; keep them apart.
155
+ const TEXT_EXT = new Set([".md", ".mjs", ".js", ".cjs", ".ts", ".tsx", ".sh", ".bash", ".zsh", ".py", ".txt", ".rst"]);
156
+ // Asserted at startup, not only in this comment: an overlapping extension
157
+ // would let a file match its own hunks and fire against itself, silently,
158
+ // on whichever PR happens to touch it.
159
+ for (const ext of DATA_EXT) {
160
+ if (TEXT_EXT.has(ext)) throw new Error(`${NAME}: DATA_EXT and TEXT_EXT both claim ${ext}`);
161
+ }
162
+
163
+ const dataFiles = (fs) => fs.filter((f) => DATA_EXT.has(extname(f)));
164
+ const textFiles = (fs) => fs.filter((f) => TEXT_EXT.has(extname(f)));
165
+
166
+ // A bare basename is usable only when it names ONE file. This is `moduleOf`'s
167
+ // measurement one file type over — `types.ts` ×13 and `index.ts` ×10 in the
168
+ // proving ground, `README.md` ×8, `hooks.json` ×5 — and the same answer: a
169
+ // shared name is not a shared file, so drop it rather than caveat it. Counted
170
+ // off the tree instead of listed here, so a data file added tomorrow is
171
+ // covered the day it lands and there is nothing to keep up to date.
172
+ //
173
+ // `null` means the count could not be taken, which is NOT the same as "no
174
+ // ambiguity": it narrows matching to full paths and is reported.
175
+ let basenameCounts;
176
+ let trackedPaths;
177
+ let basenameCountsUnrun;
178
+ function trackedBasenameCounts() {
179
+ if (basenameCounts !== undefined) return basenameCounts;
180
+ console.error(`$ git ls-files -z`);
181
+ try {
182
+ // -z: a basename count must not be wrong about a path git would otherwise
183
+ // quote. maxBuffer explicitly, for the reason diffOf() states below.
184
+ //
185
+ // GIT_DIR/GIT_WORK_TREE scrubbed (#1599, gitEnv()): measured, an ambient
186
+ // GIT_DIR answers for a DIFFERENT repository regardless of `cwd`,
187
+ // silently, at exit 0 — the count this guard's verdict is based on then
188
+ // comes from whichever repository the ambient variable names, and a
189
+ // basename genuinely unique in the caller's own tree reads as ambiguous
190
+ // (or the reverse), dropping — or wrongly keeping — a citation's bare
191
+ // basename token below.
192
+ const out = execFileSync("git", ["ls-files", "-z"], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, env: gitEnv() });
193
+ const counts = new Map();
194
+ const paths = new Set();
195
+ for (const f of out.split("\0")) {
196
+ if (!f) continue;
197
+ paths.add(f);
198
+ const b = basename(f);
199
+ counts.set(b, (counts.get(b) ?? 0) + 1);
200
+ }
201
+ basenameCounts = counts;
202
+ trackedPaths = paths;
203
+ } catch (e) {
204
+ // Same three disjoint shapes changedFiles() and diffOf() name: a git
205
+ // failure with no captured reason is indistinguishable from a clean scan
206
+ // in unrunReasons, which is #705's own failure mode one level in.
207
+ basenameCounts = null;
208
+ trackedPaths = null;
209
+ basenameCountsUnrun = `git ls-files failed: ${
210
+ e.code ?? (e.signal ? `killed by ${e.signal}` : `exit ${e.status}`)
211
+ } — basenames unusable, full paths only`;
212
+ }
213
+ return basenameCounts;
214
+ }
215
+
216
+ // A citation names a file, and naming a file means naming its path or at
217
+ // least its extension. Measured on the case this signal exists for: every one
218
+ // of run-team/SKILL.md's nine references to the TSV is written
219
+ // `docs/metrics/tier-outcomes.tsv` (×7) or `tier-outcomes.tsv` (×2). A bare
220
+ // stem (`tier-outcomes`) is never matched — without an extension it is a word
221
+ // rather than a reference, and that is where the false positives live.
222
+ function tokensFor(dataFile) {
223
+ const tokens = [dataFile];
224
+ const bn = basename(dataFile);
225
+ if (bn === dataFile) return tokens;
226
+ const counts = trackedBasenameCounts();
227
+ if (counts === null) return tokens;
228
+ // Count OTHER owners of the basename: subtract dataFile itself when the
229
+ // pre-PR index already tracks it, so a file the PR merely modifies is not
230
+ // counted as its own rival, and a file the PR ADDS is compared against the
231
+ // full pre-PR set instead of getting a free pass because it isn't in it.
232
+ const others = (counts.get(bn) ?? 0) - (trackedPaths.has(dataFile) ? 1 : 0);
233
+ if (others === 0) tokens.push(bn);
234
+ return tokens;
235
+ }
236
+
237
+ // The whole patch, not `--name-only`. The question is not whether the citing
238
+ // file names the data file SOMEWHERE — run-team/SKILL.md always does, in nine
239
+ // places, so a whole-file read fires on every PR that touches it at all,
240
+ // permanently. The question is whether THIS PR is editing the part that names
241
+ // it. #703 touched SKILL.md and scored zero against those tokens in its own
242
+ // diff, which is how merge-bot-9 cleared the pair by hand; grepping the diff
243
+ // is that measurement, kept and automated.
244
+ //
245
+ // Context lines count along with added and removed ones, deliberately: prose
246
+ // being rewritten NEXT TO a citation is the hazard, and merge-bot-9's own
247
+ // clearing grep counted context too.
248
+ function diffOf(pr, known) {
249
+ console.error(`$ gh pr diff ${pr}`);
250
+ let out;
251
+ try {
252
+ out = execFileSync("gh", ["pr", "diff", String(pr)], {
253
+ encoding: "utf8",
254
+ // A run-artifact PR appends thousands of rows and blows execFileSync's
255
+ // 1 MiB default as ENOBUFS. This signal is ranked last and must never
256
+ // be the reason the three above become unavailable, so the cliff is
257
+ // raised here and a throw is reported rather than fatal.
258
+ maxBuffer: 64 * 1024 * 1024,
259
+ });
260
+ } catch (e) {
261
+ // Same three disjoint shapes changedFiles() names, and named the same way.
262
+ return {
263
+ hunks: null,
264
+ unrun: `gh pr diff ${pr} failed: ${
265
+ e.code ?? (e.signal ? `killed by ${e.signal}` : `exit ${e.status}`)
266
+ }`,
267
+ };
268
+ }
269
+ const hunks = new Map();
270
+ let unresolved = 0;
271
+ let file = null;
272
+ let inHunk = false;
273
+ for (const line of out.split("\n")) {
274
+ if (line.startsWith("diff --git ")) {
275
+ // Resolved against the authoritative `--name-only` list rather than
276
+ // parsed out of the header: a path containing a space splits a
277
+ // `a/<x> b/<x>` header ambiguously, and a path git chose to quote does
278
+ // not appear literally at all. An unresolvable header leaves `file`
279
+ // null so its hunks are skipped, and is counted — an uncovered file
280
+ // makes an empty result incomplete, not clean.
281
+ file = known.find((f) => line.endsWith(` b/${f}`)) ?? null;
282
+ if (file === null) unresolved++;
283
+ inHunk = false;
284
+ continue;
285
+ }
286
+ if (file === null) continue;
287
+ // `@@ ... @@` is the one line that reliably marks "metadata block ends,
288
+ // hunk body begins". Gating on that state — rather than testing each
289
+ // line's own text for `--- `/`+++ ` — means a hunk-BODY line whose
290
+ // content itself starts with `--` or `++` (a removed line beginning
291
+ // with a real `--` token, or an added one beginning with `++`) is never
292
+ // mistaken for a file header and silently dropped.
293
+ if (line.startsWith("@@")) {
294
+ inHunk = true;
295
+ continue;
296
+ }
297
+ if (!inHunk) continue;
298
+ if (!/^[+\- ]/.test(line)) continue;
299
+ const lines = hunks.get(file);
300
+ if (lines) lines.push(line);
301
+ else hunks.set(file, [line]);
302
+ }
303
+ return { hunks, unrun: unresolved ? `${pr}: ${unresolved} diff header(s) unresolved — those files were not searched` : null };
304
+ }
305
+
306
+ // One witness per (data file, citing file) pair, most specific token first, so
307
+ // a file naming the TSV by both its path and its basename reports once and
308
+ // reports the path — while a SECOND file naming it still gets its own witness.
309
+ // Stopping at the first token that matches anywhere would report only the one
310
+ // file, and it is the set of citing files the caller has to read.
311
+ const WITNESS_CAP = 120;
312
+ function proseHits(target, citer) {
313
+ const targets = dataFiles(target.files);
314
+ const citers = textFiles(citer.files);
315
+ // Nothing to look for, or nothing that could carry it: a complete answer,
316
+ // and the common case. No `gh pr diff` is spent reaching it.
317
+ if (targets.length === 0 || citers.length === 0) return { hits: [], unrun: null };
318
+ const { hunks, unrun } = diffOf(citer.pr, citer.files);
319
+ if (hunks === null) return { hits: [], unrun };
320
+ const hits = [];
321
+ for (const data of targets) {
322
+ const tokens = tokensFor(data);
323
+ for (const text of citers) {
324
+ const lines = hunks.get(text) ?? [];
325
+ for (const token of tokens) {
326
+ const line = lines.find((l) => l.includes(token));
327
+ if (!line) continue;
328
+ hits.push({
329
+ data,
330
+ citedBy: text,
331
+ token,
332
+ line: line.length > WITNESS_CAP ? `${line.slice(0, WITNESS_CAP)}…` : line,
333
+ });
334
+ break;
335
+ }
336
+ }
337
+ }
338
+ return { hits, unrun };
339
+ }
340
+
341
+ const files = intersect(filesA, filesB);
342
+ const modules = intersect(modulesOf(filesA), modulesOf(filesB));
343
+ const dirs = intersect(dirsOf(filesA), dirsOf(filesB));
344
+
345
+ // Both directions. Which PR holds the data and which holds the prose is not
346
+ // knowable in advance — #704 appended the rows and #703 held the paragraph,
347
+ // and the flags carry no such role.
348
+ const ab = proseHits({ pr: a, files: filesA }, { pr: b, files: filesB });
349
+ const ba = proseHits({ pr: b, files: filesB }, { pr: a, files: filesA });
350
+ const prose = [...ab.hits, ...ba.hits].sort((x, y) =>
351
+ x.data.localeCompare(y.data) || x.citedBy.localeCompare(y.citedBy) || x.token.localeCompare(y.token)
352
+ );
353
+ // Non-null means `prose` is not a complete answer — the scan was reached and
354
+ // could not cover what an empty array would otherwise claim. Without this
355
+ // field a failed diff read prints `prose: []`, byte-identical to a clean
356
+ // scan: #705's own failure mode — the clearest output being the one that
357
+ // misses it — reintroduced one level in. Same reason run-team/SKILL.md reads
358
+ // `dimensionsUnrun` beside `dimensionsRun`: an absence of findings is not
359
+ // coverage.
360
+ const unrunReasons = [ab.unrun, ba.unrun];
361
+ if (basenameCounts === null) unrunReasons.push(basenameCountsUnrun);
362
+ const proseUnrun = unrunReasons.filter(Boolean).join("; ") || null;
363
+
364
+ // Ranked BELOW `dirs`, so it can only ever turn a `none` into something. It
365
+ // never masks or downgrades one of the three above — and the bug it answers
366
+ // is precisely a `none` that should not have been one.
367
+ const signal = files.length
368
+ ? "files"
369
+ : modules.length
370
+ ? "modules"
371
+ : dirs.length
372
+ ? "dirs"
373
+ : prose.length
374
+ ? "prose"
375
+ : "none";
376
+
377
+ console.error(
378
+ `\n${NAME}: signal=${signal} files=${files.length} modules=${modules.length} dirs=${dirs.length} prose=${prose.length}`,
379
+ );
380
+ if (signal === "dirs") {
381
+ console.error(
382
+ `${NAME}: directory-only hit — weak evidence. A bare top-level directory\n` +
383
+ ` (docs, tests, src) fires on PRs with different subjects. Read the files.`,
384
+ );
385
+ }
386
+ if (signal === "modules") {
387
+ // The hold rule this mechanises calls a module match a verdict, on a par with
388
+ // a shared file. It is not one: `types.ts` ×13 and `index.ts` ×10 live in
389
+ // unrelated subtrees of the proving ground, so two PRs can share a "module"
390
+ // name and nothing else. Say so, because the caller's rule will not.
391
+ console.error(
392
+ `${NAME}: module-only hit — confirm before treating as a verdict. Common\n` +
393
+ ` TypeScript basenames (types.ts, index.ts) recur across unrelated\n` +
394
+ ` subtrees, so a shared name is not yet a shared module: ${modules.join(", ")}`,
395
+ );
396
+ }
397
+ // Keyed on the count, not on `signal`, unlike the two notes above: a prose
398
+ // hit under a `dirs` verdict is stronger evidence than the verdict, and the
399
+ // ladder would hide it. The caveat carries the witness because one read
400
+ // disproves it — which is how merge-bot-9 settled #703 vs #704 by hand.
401
+ if (prose.length) {
402
+ console.error(
403
+ `${NAME}: prose citation — the other PR's diff names a data file this one\n` +
404
+ ` changes. Weak evidence, like a directory hit: read the line. Searched\n` +
405
+ ` ${[...DATA_EXT].join(" ")} as cited, ${[...TEXT_EXT].join(" ")} as citing;\n` +
406
+ ` a bare stem with no extension is never matched.`,
407
+ );
408
+ for (const h of prose) console.error(` ${h.data} cited by ${h.citedBy} as "${h.token}"\n ${h.line}`);
409
+ }
410
+ if (proseUnrun) {
411
+ console.error(
412
+ `${NAME}: prose scan INCOMPLETE — ${proseUnrun}.\n` +
413
+ ` An empty prose[] does not clear the same-section case here.`,
414
+ );
415
+ }
416
+
417
+ console.log(JSON.stringify({ a, b, files, modules, dirs, prose, proseUnrun, signal }));