@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,276 @@
1
+ // #532. A worktree re-created for a carried-over PR sat at a pre-rebase commit
2
+ // and a full review ran against it. The mechanism is `git worktree add <path>
3
+ // <branch>` preferring a leftover LOCAL branch over the remote ref that is the
4
+ // PR — measured in a scratch repo, and settled before it was written down.
5
+ //
6
+ // The paragraph these pins hold is an INSTRUCTION the controller executes, and
7
+ // its two halves fail differently on deletion: drop the `--detach origin/` form
8
+ // and the controller writes the bug back; drop the verify-and-refuse pair and it
9
+ // keeps the bug but stops noticing. Both are pinned, and so is the asymmetry
10
+ // that explains why this one is worth the words at all — a missing runner fails
11
+ // loudly, a stale base fails silently.
12
+ //
13
+ // #1168 moved the verify's OPERAND. It compared the worktree head against
14
+ // `gh pr view --json headRefOid` — the one field that lags the ref it is meant
15
+ // to describe. Both operands go stale in the same direction during that lag, so
16
+ // the compare reads EQUAL on a worktree cut from a stale remote-tracking ref and
17
+ // dispatches into the superseded commit this paragraph exists to catch; a
18
+ // settle-window re-read of the lagging field, which is what the ticket proposed,
19
+ // fires only where the two disagree and never reaches that half. So the pins
20
+ // below hold WHICH SOURCE the refusal turns on, not merely that a comparison
21
+ // exists — the shape the old pin could not tell apart, measured: with the
22
+ // operand swapped this file was 6/6 green on both wordings, because the
23
+ // `headRefOid` command survives in the paragraph either way.
24
+ //
25
+ // Bound at both ends via prose-pin.mjs's between(): unbounded, the slice runs to
26
+ // EOF, where phase 5's finisher head-equality block restates enough of this
27
+ // vocabulary (`rev-parse HEAD`, `headRefOid`, worktree, refuse) to satisfy these
28
+ // assertions with the phase-1 paragraph deleted outright.
29
+ //
30
+ // CEILING: presence pins plus two mapping pins over a bounded slice. A later
31
+ // sentence contradicting the paragraph stays green. `phrase()` matches across
32
+ // any run of whitespace, so a rewrap of the same sentence stays green by design.
33
+ import { test } from "node:test";
34
+ import assert from "node:assert/strict";
35
+ import { readFileSync } from "node:fs";
36
+ import { join } from "node:path";
37
+ import { between, phrase } from "./prose-pin.mjs";
38
+
39
+ const REPO = join(import.meta.dirname, "..");
40
+ const RUN_TEAM = readFileSync(join(REPO, "skills", "run-team", "SKILL.md"), "utf8");
41
+
42
+ // Starts inside this paragraph's own lead, not at the reused-runner paragraph
43
+ // above it: the two are siblings and a slice spanning both lets the runner
44
+ // paragraph's wording satisfy assertions about this one. The start anchor is the
45
+ // shortest fragment that is unique file-wide rather than the whole lead
46
+ // sentence, because `between()` throws "update this test" when its anchor moves
47
+ // — a rename of the anchor reds every test in this file at once, which is loud
48
+ // but says nothing about which claim was lost. A shorter anchor is less of that.
49
+ const slice = () => between(RUN_TEAM, "on the wrong COMMIT", "## Phase 2", "run-team/SKILL.md phase 1");
50
+
51
+ // Narrower than `slice()`: just the verify + empty-read bullet, ending before
52
+ // the headRefOid-read bullet starts. A presence-only pin on the compare
53
+ // sentence's command string stays green if a mutant admits `headRefOid` as a
54
+ // second acceptable operand through different wording (finding 3) — this
55
+ // bound is what lets a bare `doesNotMatch(/headRefOid/)` mean "nowhere in
56
+ // this bullet, under any phrasing" instead of "not this one exact string."
57
+ const compareBulletSlice = () =>
58
+ between(
59
+ RUN_TEAM,
60
+ "Then verify against the branch REF",
61
+ "- **Read `gh pr view",
62
+ "run-team/SKILL.md phase 1 ref-compare + empty-read bullet",
63
+ );
64
+
65
+ // The cause, not the symptom. A controller told only "the worktree may be stale"
66
+ // has no reason to prefer one `worktree add` form over another.
67
+ test("phase 1 names why a reused worktree lands on the wrong commit", () => {
68
+ assert.match(slice(), phrase("checks out the existing LOCAL branch and never consults the remote"));
69
+ });
70
+
71
+ // Why reading the `git worktree add` output is not a check: it quotes the
72
+ // subject, and a rebase preserves the subject. Without this the controller
73
+ // reasonably believes it already verified the commit.
74
+ test("phase 1 says the printed subject survives the rebase and settles nothing", () => {
75
+ assert.match(slice(), phrase("the same subject the PR head carries, because a rebase preserves it"));
76
+ });
77
+
78
+ // Prevention (#532's option 2). The bare branch name is the defect; the
79
+ // `--detach origin/` form is the fix, and pinning the flag alone would stay
80
+ // green on `git worktree add --detach <path> <branch>`, which is still wrong.
81
+ //
82
+ // The command alone is not unique to this bullet: it recurs verbatim twice
83
+ // more in this same between()-bounded slice (the fail-open measurement, the
84
+ // retry clause), so a pin on the command string alone stays green with this
85
+ // whole bullet deleted — measured: `node --test --test-name-pattern="phase 1
86
+ // gives the creation form" plugin/scripts/worktree-head-prose.test.mjs`
87
+ // stayed green (1 pass) with lines 603-606 removed entirely. The anchor below
88
+ // adds the command's own immediately-following clause, which occurs nowhere
89
+ // else in the slice.
90
+ test("phase 1 gives the creation form that cannot inherit a stale local ref", () => {
91
+ assert.match(
92
+ slice(),
93
+ phrase(
94
+ "git worktree add --detach <path> origin/<branch>`. Same scratch repo, same moment: this landed on the remote's commit",
95
+ ),
96
+ );
97
+ });
98
+
99
+ // Verification (#532's option 1) and its operand (#1168). The two commands are
100
+ // what makes it runnable; BOTH commits in the report is what makes the refusal
101
+ // actionable, since the subjects are identical and a report naming one sha
102
+ // cannot be told from a report about the right tree.
103
+ //
104
+ // The operand is pinned as a MAPPING — which source the worktree head is
105
+ // compared AGAINST — because every presence pin here stays green on the
106
+ // superseded wording: `rev-parse HEAD` is unchanged by that revert and the
107
+ // `headRefOid` read is still in the paragraph as the recorded diagnostic. The
108
+ // `doesNotMatch` is the superseded operand verbatim, in the one position that
109
+ // matters (the compared-against side), so a mutant naming BOTH sources as
110
+ // acceptable operands reds here even though the positive pin above it passes.
111
+ test("phase 1 compares the worktree head against the branch ref, and refuses on mismatch", () => {
112
+ assert.match(
113
+ slice(),
114
+ phrase("Compare `git -C <path> rev-parse HEAD` against `git ls-remote origin refs/heads/<branch> | cut -f1`"),
115
+ );
116
+ assert.match(slice(), phrase("dispatch nothing into that worktree"));
117
+ assert.match(slice(), phrase("naming BOTH commits"));
118
+ assert.doesNotMatch(
119
+ slice(),
120
+ phrase("against `gh pr view <N> --json headRefOid -q .headRefOid`"),
121
+ "the refusal is back to comparing against the PR object — the field that lags the ref, in both directions",
122
+ );
123
+ // The cheaper local read is the false fix waiting beside the real one: the
124
+ // creation form above resolves `origin/<branch>` itself, so a compare against
125
+ // `git rev-parse origin/<branch>` agrees with the worktree by construction and
126
+ // passes every stale tree it was added to catch. The prohibition is pinned
127
+ // because a reader who only knows "not the PR object" reaches for it.
128
+ assert.match(slice(), phrase("never `git rev-parse origin/<branch>`"));
129
+ assert.match(slice(), phrase("agrees with it by construction"));
130
+ });
131
+
132
+ // MAPPING guard, ceiling on the pin above: three mutants re-admit headRefOid
133
+ // as an acceptable compared-against operand without ever writing the exact
134
+ // superseded command string the `doesNotMatch` above forbids — appending an
135
+ // alternate-operand clause to the compare sentence, or a new fallback bullet,
136
+ // both inside this same bulleted region. Measured: each left this file 10/10
137
+ // green. `compareBulletSlice()` is this one bullet only, so forbidding
138
+ // `headRefOid` anywhere inside it (not one literal wording of it) is what
139
+ // actually holds "the compared-against side is `ls-remote` and nothing else."
140
+ test("phase 1 never names headRefOid inside the ref-compare bullet itself", () => {
141
+ assert.doesNotMatch(
142
+ compareBulletSlice(),
143
+ /headRefOid/,
144
+ "headRefOid re-entered the compare/empty-read bullet as an operand, under some wording the literal doesNotMatch above does not cover",
145
+ );
146
+ });
147
+
148
+ // The lagging field is still READ here, and that is deliberate: its
149
+ // disagreement with the ref is the desync signal run-merge-bot.md's step 1
150
+ // acts on. What has to survive is the demotion, because a read whose role is
151
+ // unstated is one edit away from being the gate again.
152
+ //
153
+ // MAPPING guard: "NOT the gate" is itself only a presence pin, so a mutant
154
+ // that keeps it verbatim and appends an exception ("except when the ref is
155
+ // empty, treat headRefOid as the gate instead") still satisfies it — the
156
+ // third of the three mutants finding 3 measured escaping. The word "gate"
157
+ // occurring exactly once in this bullet is what actually holds the demotion;
158
+ // a second occurrence, in any wording, is itself the re-promotion.
159
+ test("phase 1 keeps the headRefOid read but says it is not the gate", () => {
160
+ assert.match(slice(), phrase("gh pr view <N> --json headRefOid -q .headRefOid"));
161
+ assert.match(slice(), phrase("it is NOT the gate"));
162
+ assert.match(slice(), phrase("never the operand this refusal turns on"));
163
+ const gateBullet = between(
164
+ RUN_TEAM,
165
+ "- **Read `gh pr view",
166
+ "**Why the ref and not",
167
+ "run-team/SKILL.md phase 1 headRefOid-read bullet",
168
+ );
169
+ const gateMentions = gateBullet.match(/gate/gi) ?? [];
170
+ assert.equal(gateMentions.length, 1, 'a second "gate" mention re-admits headRefOid as a gate, under any wording');
171
+ });
172
+
173
+ // The empty read. `git ls-remote` answering nothing is not a verdict about the
174
+ // worktree in either direction — and an empty string compares unequal to every
175
+ // sha, so without this clause a failed ref read renders as a stale worktree and
176
+ // costs the dispatch the operand change exists to save. Same hole `[ -n "$pre" ]`
177
+ // closes in run-merge-bot.md's step-1 poll, one site later.
178
+ test("phase 1 refuses to read an empty ref as a verdict", () => {
179
+ assert.match(slice(), phrase("An empty read is neither equal nor a mismatch"));
180
+ assert.match(slice(), phrase("report the ref as unreadable"));
181
+ });
182
+
183
+ // The fail-open half — #1168's own ticket assumed this site could only fail
184
+ // closed ("a spurious refusal costs a dispatch, it cannot merge a stale head"),
185
+ // and the measurement contradicted it. Pinned because it is the whole reason
186
+ // the operand changed instead of the verdict gaining a settle window: a reader
187
+ // left with only the false-refusal story re-applies the ticket's suggested
188
+ // re-read and restores the hole.
189
+ //
190
+ // THE CEILING: the measurement sentence beside these clauses is deliberately
191
+ // unpinned — the two shas and the two re-poll attempt numbers are one run's
192
+ // readings, and re-measuring must not turn a test red.
193
+ test("phase 1 says the PR-object compare fails open too, and that a re-read cannot fix it", () => {
194
+ assert.match(slice(), phrase("both operands go stale in the SAME direction"));
195
+ assert.match(slice(), phrase("fails OPEN as readily as it fails closed"));
196
+ assert.match(
197
+ slice(),
198
+ phrase("Re-reading `headRefOid` on a settle window does not reach that half at all"),
199
+ );
200
+ });
201
+
202
+ // The remedy for a real mismatch, and its bound. Two clauses that fail
203
+ // independently: without the fetch-and-re-create the ordinary cause (this
204
+ // clone has not fetched) costs a dispatch it need not cost, and without the
205
+ // bound the same instruction reads as "keep fetching until it agrees" — the
206
+ // unbounded loop run-merge-bot.md's step 1 already had to have written out of
207
+ // it once.
208
+ //
209
+ // The instruction also has to survive being carried out literally: the path
210
+ // is already occupied by the tree the first bullet just created, so
211
+ // re-running `git worktree add --detach <path> origin/<branch>` on it exits
212
+ // 128 without `git worktree remove --force <path>` first — measured in a
213
+ // scratch repo (git 2.50.1). That removal is pinned by name, the same form
214
+ // phase 5's own scratch-worktree duty already uses.
215
+ test("phase 1 retries a mismatch once through a fetch, and says it is once", () => {
216
+ assert.match(slice(), phrase("git worktree remove --force <path>"));
217
+ assert.match(slice(), phrase("fetch and re-create once before reporting it"));
218
+ assert.match(slice(), phrase("Bounded at one retry"));
219
+ });
220
+
221
+ // The asymmetry, pinned as a MAPPING rather than as two presences. Both words
222
+ // live in the same short paragraph, so `/LOUDLY/` + `/SILENTLY/` stay green with
223
+ // the two swapped — which inverts the whole point, since the reader would then
224
+ // treat the silent failure as the one that announces itself. `[^.]` keeps each
225
+ // match inside one sentence and the lookahead is what makes a swap red.
226
+ test("phase 1 binds the loud failure to the runner and the silent one to the base", () => {
227
+ assert.match(slice(), /missing\s+runner(?:(?!SILENTLY)[^.])*?LOUDLY/);
228
+ assert.match(slice(), /stale\s+base(?:(?!LOUDLY)[^.])*?SILENTLY/);
229
+ });
230
+
231
+ // The backstop's SCOPE. "review-core.mjs refuses" alone reads as coverage and makes
232
+ // the phase-1 verify look redundant — the exact reasoning that would delete it.
233
+ // What has to survive is that a hand-dispatched worktree is outside that net,
234
+ // and that the net covering the other path is still not a substitute for the
235
+ // compare in this one.
236
+ //
237
+ // #1168 wove that net from the lagging field, and this paragraph said so. #1513
238
+ // moved `review-core.mjs`'s own operand to the same `ls-remote` read this bullet
239
+ // uses, which makes the old sentence FALSE — and false in the direction that
240
+ // costs something, since a controller told the workflow check is unsound has a
241
+ // reason to distrust a review that refused for a real mismatch. So the claim is
242
+ // pinned in its new form AND the superseded one is forbidden by name: a revert
243
+ // to it satisfies every positive pin here word for word.
244
+ test("phase 1 keeps the workflow backstop from reading as full coverage", () => {
245
+ // The paragraph's OPENING claim, and a measured gap: with only the pins that
246
+ // follow, reverting this clause to "whose head is not the PR head" left this
247
+ // file 11/11 green. The bolded `That backstop now compares…` sentence then
248
+ // contradicts it, and a reader takes the operand from whichever they hit
249
+ // first.
250
+ assert.match(slice(), phrase("refuses a snapshot whose head is not the branch ref's"));
251
+ assert.match(slice(), phrase("A worktree you hand to an agent directly is not"));
252
+ assert.match(slice(), phrase("That backstop now compares against the same ref this bullet does"));
253
+ assert.match(slice(), phrase("never a reason to skip the ref compare"));
254
+ assert.doesNotMatch(
255
+ slice(),
256
+ /backstop compares against `headRefOid`/,
257
+ "the paragraph has the workflow backstop comparing against the PR object again — #1513 moved it to the branch ref, and a controller reading the stale claim distrusts a check that is now sound",
258
+ );
259
+ });
260
+
261
+ // The run-log marker this paragraph QUOTES is a verbatim copy of a string in
262
+ // `review-core.mjs`, which is the disconnect this repo files as a defect in its own
263
+ // right: a prose-only presence pin stays green while the code's marker moves,
264
+ // and a controller then hunts a run log for a line it will never find. Compared
265
+ // against the source, so either side moving reds.
266
+ test("phase 1's quoted run-log marker is the one review-core.mjs actually prints", () => {
267
+ assert.match(slice(), phrase("head ref (absent): head check SKIPPED"));
268
+ const line = readFileSync(join(REPO, "scripts", "review-core.mjs"), "utf8")
269
+ .split("\n")
270
+ .find((l) => l.includes("log(`snapshot "));
271
+ assert.ok(line, "review-core.mjs's snapshot run-log line is gone — the marker this paragraph quotes is printed nowhere");
272
+ assert.ok(
273
+ line.includes("head ref ") && line.includes("(absent): head check SKIPPED"),
274
+ `phase 1 quotes a run-log marker review-core.mjs no longer prints:\n ${line}`,
275
+ );
276
+ });
@@ -0,0 +1,217 @@
1
+ // Regression gate for #551, and the durable half of its enumeration.
2
+ //
3
+ // A worktree path may legally contain a newline (APFS and ext4 both allow it),
4
+ // and `git worktree list --porcelain` terminates every attribute with one — so
5
+ // one record becomes two, `substr($0,10)` truncates the path at the newline, and
6
+ // every consumer downstream is handed a path that is not on disk. #185 fixed
7
+ // that in inflight.sh. #551 is the observation that three sibling scripts
8
+ // carried the same shape — and the ticket named ONE parse site per script while
9
+ // reap.sh and release-ticket.sh each read the listing at several, including the
10
+ // post-removal registry re-read and the fresh listing a halted release is judged
11
+ // from, neither of which any ticket mentions.
12
+ //
13
+ // So the pin is not "the three named sites were fixed" — that is exactly the
14
+ // fix that ships without closing its own ticket. It is the property: no fleet
15
+ // shell script reads the worktree listing raw. A read added tomorrow, at a site
16
+ // nobody has thought of yet, fails here rather than silently truncating.
17
+ //
18
+ // The two files allowed their own `git worktree list`, each with its reason:
19
+ //
20
+ // worktree.sh IS the reader — `wt_listing`, `--porcelain -z` into a temp
21
+ // file, then `tr '\n\000' '\001\n'`.
22
+ // inflight.sh carries its own copy of that shape, landed by #185 and named
23
+ // by #551 as the reference implementation and out of scope.
24
+ // Its read is `-z` already, so it is not the defect; folding it
25
+ // into worktree.sh is a separate change with its own risk, and
26
+ // this gate would notice if someone did fold it.
27
+ //
28
+ // Zero deps: `node --test plugin/scripts/worktree-listing-sweep.test.mjs`.
29
+
30
+ import { test } from "node:test";
31
+ import assert from "node:assert/strict";
32
+ import { readFileSync } from "node:fs";
33
+ import { join } from "node:path";
34
+ import { fileURLToPath } from "node:url";
35
+ import { repoRoot, skipWithoutRepo, trackedShellScripts } from "./repo-root.mjs";
36
+
37
+ const DIR = fileURLToPath(new URL(".", import.meta.url));
38
+
39
+ // Needs an ambient git working tree: this gate asks git what ships rather than
40
+ // walking the directory. `repoRoot` answers `null` where there is none — a bare
41
+ // `git archive` extraction, which is how review specialists used to measure the
42
+ // suite (#1056; the review snapshot is a repository from its cut onward now) —
43
+ // and the tests below then DECLINE with a reason instead of running, because the
44
+ // tree they would police is not reachable from here. Until #1149 this threw at
45
+ // module load and node could only report it as one synthetic failing test at
46
+ // line 1.
47
+ const ROOT = repoRoot(DIR);
48
+ const SKIP_WITHOUT_REPO = skipWithoutRepo(ROOT, "this sweep over what ships");
49
+
50
+ /**
51
+ * Every tracked `*.sh` in the repo, so a new script cannot join unnoticed.
52
+ *
53
+ * Empty ONLY because the root lookup could not answer, in which case every test
54
+ * below is skipped. A root that answers and lists nothing is a different
55
+ * condition — the wrong repository, or a broken glob — and it must reach the
56
+ * non-vacuity test below and fail there.
57
+ */
58
+ const SHELL_SCRIPTS = ROOT === null ? [] : trackedShellScripts(ROOT);
59
+
60
+ /**
61
+ * `src` as LOGICAL lines: a trailing backslash folds the next physical line in,
62
+ * and the pair keeps the number of the line the statement STARTED on.
63
+ *
64
+ * A gate that scans physical lines pins one way of typing the defect rather than
65
+ * the defect. Measured: `git worktree \` + ` list --porcelain` is valid POSIX
66
+ * sh, reads the listing exactly as rawly as the one-line spelling, and walked
67
+ * through this whole file green — the three words simply never appeared on one
68
+ * line for the scan to see.
69
+ */
70
+ function logicalLines(src) {
71
+ const out = [];
72
+ const phys = src.split("\n");
73
+ let buf = "";
74
+ let start = 0;
75
+ for (let i = 0; i < phys.length; i++) {
76
+ if (buf === "") start = i + 1;
77
+ const line = buf === "" ? phys[i] : phys[i].replace(/^\s+/, "");
78
+ const joined = buf === "" ? line : `${buf} ${line}`;
79
+ if (/\\$/.test(line)) {
80
+ buf = joined.slice(0, -1);
81
+ continue;
82
+ }
83
+ out.push([start, joined]);
84
+ buf = "";
85
+ }
86
+ if (buf !== "") out.push([start, buf]);
87
+ return out;
88
+ }
89
+
90
+ /**
91
+ * Is the character at `idx` inside a quoted string?
92
+ *
93
+ * A scan rather than "is there a quote before the phrase", which is what this
94
+ * asked and is a different question with the same answer only by luck. Measured:
95
+ * `raw=$(cd "$HOME" && git worktree list --porcelain)` is a raw read, and the
96
+ * quotes around `$HOME` — closed long before `git` — excluded it. Every real
97
+ * invocation here expands or redirects through a quote somewhere, so any test
98
+ * that keys on a quote's mere presence ahead of the phrase excludes the very
99
+ * population being scanned for. Parity is what separates the two: an OPEN quote
100
+ * at the phrase means the phrase is text, a closed one means it is code.
101
+ */
102
+ function quoted(line, idx) {
103
+ let q = null;
104
+ for (let i = 0; i < idx; i++) {
105
+ const c = line[i];
106
+ if (q) {
107
+ if (c === q) q = null;
108
+ } else if (c === '"' || c === "'") {
109
+ q = c;
110
+ }
111
+ }
112
+ return q !== null;
113
+ }
114
+
115
+ /** `git` with any options between it and the subcommand — `git -C "$d" worktree list`. */
116
+ const INVOCATION = /\bgit\b.*?\bworktree\s+list\b/;
117
+
118
+ /**
119
+ * Logical lines of `src` that INVOKE `git worktree list`, as opposed to naming
120
+ * it.
121
+ *
122
+ * Two exclusions, both load-bearing, and both for lines that NAME the command
123
+ * without running it. A comment describes git's output shape, and these scripts
124
+ * do that constantly — including in the comments this fix wrote — so a scan that
125
+ * counts them reports every file. The other is the phrase sitting inside an open
126
+ * quote: that is a banner `echo "\$ git worktree list …"` printing the command
127
+ * for an operator, or a diagnostic string naming what failed. Both are inert
128
+ * text, and worktree.sh and worktree-audit.sh each carry one.
129
+ *
130
+ * The match itself allows options between `git` and its subcommand. `git -C
131
+ * "$dir" worktree list` is a raw read by any measure and the literal three-word
132
+ * phrase does not occur in it — and `git -C` is the dominant git spelling in
133
+ * these scripts, so it is the form the next person reaches for.
134
+ */
135
+ function invocations(src) {
136
+ return logicalLines(src)
137
+ .filter(([, line]) => !/^\s*#/.test(line))
138
+ .map(([n, line]) => [n, line, INVOCATION.exec(line)])
139
+ .filter(([, , m]) => m !== null)
140
+ .filter(([, line, m]) => !quoted(line, m.index))
141
+ .map(([n, line]) => [n, line]);
142
+ }
143
+
144
+ const ALLOWED = ["plugin/scripts/worktree.sh", "plugin/scripts/inflight.sh"];
145
+
146
+ // A guard on the guard, and the half the skip above leans on: a bad glob, a
147
+ // moved directory or a `git ls-files` that answers nothing turns the two
148
+ // sweeping tests below into vacuous passes over an empty list — green, and
149
+ // blind. The skip is allowed to empty that list for ONE reason (no working
150
+ // tree); every other reason has to land here as a failure. The allowed readers
151
+ // are the named subjects, so they are what this asserts is present.
152
+ test("the sweep sees the scripts it is supposed to police", { skip: SKIP_WITHOUT_REPO }, () => {
153
+ for (const f of ALLOWED) {
154
+ assert.ok(
155
+ SHELL_SCRIPTS.includes(f),
156
+ `${f} is not in the tracked-script list — the glob or the root above is broken, not the script`,
157
+ );
158
+ }
159
+ });
160
+
161
+ test("only worktree.sh and inflight.sh read the worktree listing directly", { skip: SKIP_WITHOUT_REPO }, () => {
162
+ const offenders = SHELL_SCRIPTS
163
+ .filter((f) => !ALLOWED.includes(f))
164
+ .flatMap((f) => invocations(readFileSync(join(ROOT, f), "utf8")).map(([n, l]) => `${f}:${n}: ${l.trim()}`));
165
+ assert.deepEqual(
166
+ offenders,
167
+ [],
168
+ "every other script must read through wt_listing — a raw read truncates a path holding a newline (#551)",
169
+ );
170
+ });
171
+
172
+ // The other direction. Without it the assertion above passes just as happily
173
+ // over a tree where NOTHING reads the listing at all — a `wt_listing` deleted,
174
+ // or an `ALLOWED` entry that has stopped being a reader — and the gate would be
175
+ // pinning the absence of a feature rather than the shape of one.
176
+ test("the two allowed readers really do read it, and both read it -z", { skip: SKIP_WITHOUT_REPO }, () => {
177
+ for (const f of ALLOWED) {
178
+ const src = readFileSync(join(ROOT, f), "utf8");
179
+ const calls = invocations(src);
180
+ assert.ok(calls.length > 0, `${f} is listed as a reader but invokes nothing`);
181
+ for (const [n, line] of calls) {
182
+ assert.match(
183
+ line,
184
+ /--porcelain -z/,
185
+ `${f}:${n} must read NUL-terminated — the plain porcelain ends a record on a newline inside a path`,
186
+ );
187
+ }
188
+ }
189
+ });
190
+
191
+ // `awk -v RS='\0'` is the form #185 proposed and measurement rejected: macOS
192
+ // BWK awk 20200816 stops at the first NUL and reports ONE record for a listing
193
+ // of any length, in all three spellings — which would have made inflight.sh
194
+ // refuse every ticket. It reads like the obvious way to consume `-z` output, so
195
+ // the next person to touch either reader will reach for it.
196
+ //
197
+ // Any `RS=` at all, not only one spelled with a literal `\0`. The separator has
198
+ // no other use in this tree — no script sets `RS` for any reason today — so the
199
+ // blunt scan costs nothing and the narrow one measurably missed the defect:
200
+ // `sep=$(printf '\0'); awk -v RS="$sep"` reintroduces the identical one-record
201
+ // read (measured on BWK awk 20200816: NR=1, against 3 for the same file through
202
+ // `tr`), and the literal-`\0` pattern never saw it. A legitimate `RS=` arriving
203
+ // later fails here loudly and is answered by naming it, which is the direction
204
+ // worth erring in for a scan whose whole job is catching what nobody expected.
205
+ test("no script consumes the -z listing with awk's record separator", { skip: SKIP_WITHOUT_REPO }, () => {
206
+ for (const f of SHELL_SCRIPTS) {
207
+ const src = readFileSync(join(ROOT, f), "utf8");
208
+ for (const [n, line] of logicalLines(src)) {
209
+ if (/^\s*#/.test(line)) continue;
210
+ assert.doesNotMatch(
211
+ line,
212
+ /\bRS\s*=/,
213
+ `${f}:${n}: BWK awk reports one record for the whole listing — swap the separators with tr instead`,
214
+ );
215
+ }
216
+ }
217
+ });