@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,74 @@
1
+ // #1150. The PR that landed this repo's two-sided scratch-partition rule —
2
+ // "any member that dispatches a child writes an absolute directory under its
3
+ // own partition into that child's prompt, one per child and never shared, and
4
+ // a child never derives its own" (run-team/SKILL.md's "Scratchpad paths need
5
+ // two levels" bullet) and its twin in references/isolation.md's "The axis is
6
+ // two-sided" paragraph — shipped with NO test coverage for either sentence.
7
+ // Measured directly: `grep -rn "and a child never derives its own\|any member
8
+ // that dispatches a child writes" plugin/scripts` found zero matches before
9
+ // this file, and inverting the rule in a scratch copy ("a member that
10
+ // dispatches a child may let the child derive its own directory under the
11
+ // shared partition") left every test in all five of that PR's diff-touched
12
+ // files green — the defect #1150 exists to rule out has no pin anywhere.
13
+ //
14
+ // This mirrors dispatch-block-pins-prose.test.mjs's treatment of the
15
+ // identical invariant in fleet-implementer.agent.md's child-dispatch block
16
+ // (that file pins the *implementer's* own instance of this rule; this one
17
+ // pins the two general statements of it that the implementer, fix-applier
18
+ // and review-side members are all read against).
19
+ //
20
+ // THE CEILING: a phrase()-based presence pin over one paragraph each. A
21
+ // carve-out sentence appended AFTER the pinned clause, or a rewording that
22
+ // keeps every pinned word but drops the parent-writes/child-never-derives
23
+ // relationship between them, is not caught here — see dispatch-block-golden-
24
+ // prose.test.mjs for that stronger, whole-block mechanism; this file's job is
25
+ // only to stop the clause from being deleted or inverted unnoticed, which is
26
+ // the shape #1150 measured.
27
+ import { test } from "node:test";
28
+ import assert from "node:assert/strict";
29
+ import { readFileSync } from "node:fs";
30
+ import { join } from "node:path";
31
+ import { between, phrase } from "./prose-pin.mjs";
32
+
33
+ const REPO = join(import.meta.dirname, "..");
34
+ const read = (...p) => readFileSync(join(REPO, ...p), "utf8");
35
+ const RUN_TEAM = read("skills", "run-team", "SKILL.md");
36
+ const ISOLATION = read("skills", "run-team", "references", "isolation.md");
37
+
38
+ const SKILL_BULLET = () =>
39
+ between(
40
+ RUN_TEAM,
41
+ "**Scratchpad paths need two levels",
42
+ "**IDE/harness diagnostics attribute",
43
+ "run-team/SKILL.md's scratchpad-paths bullet",
44
+ );
45
+
46
+ const SKILL_CLAUSE =
47
+ "any member that dispatches a child writes an absolute directory under its own partition into that child's prompt, one per child and never shared, and a child never derives its own";
48
+
49
+ test("run-team/SKILL.md's scratchpad-paths bullet pins the parent-writes, child-never-derives rule", () => {
50
+ assert.match(
51
+ SKILL_BULLET(),
52
+ phrase(SKILL_CLAUSE),
53
+ "the bullet no longer states that any member dispatching a child writes an absolute directory into that child's prompt, one per child and never shared, with the child never deriving its own — the exact rule #1150 exists to establish, and inverting it left the diff-touched suite green before this pin existed",
54
+ );
55
+ });
56
+
57
+ const ISOLATION_PARAGRAPH = () =>
58
+ between(
59
+ ISOLATION,
60
+ "The axis is two-sided",
61
+ "## IDE/harness diagnostics attribute",
62
+ "references/isolation.md's two-sided-axis paragraph",
63
+ );
64
+
65
+ const ISOLATION_CLAUSE =
66
+ "every agent it dispatches gets a directory under that one, unique to that child and never shared, written into the child's prompt as an absolute path; a child never derives its own";
67
+
68
+ test("references/isolation.md's two-sided-axis paragraph pins the same parent-writes, child-never-derives rule", () => {
69
+ assert.match(
70
+ ISOLATION_PARAGRAPH(),
71
+ phrase(ISOLATION_CLAUSE),
72
+ "the paragraph no longer states that every dispatched agent gets a directory under its parent's own, unique and never shared, written in as an absolute path with the child never deriving its own — isolation.md's statement of the same #1150 rule SKILL.md's bullet carries",
73
+ );
74
+ });
@@ -0,0 +1,73 @@
1
+ // #1378. Documentation and test-file headers across this repo cited the test
2
+ // suite as living at `scripts/<file>` — a path that does not exist. The real
3
+ // suite root is `plugin/scripts/`. 32 tracked files carried the stale form
4
+ // before this ticket corrected every one: 27 test-file header comments
5
+ // citing themselves, 2 comments in non-test source files (`repo-root.mjs`
6
+ // citing its sibling `repo-root.test.mjs`, `strip-comments.mjs` inside an
7
+ // example string) rather than a test file citing itself, one prose citation
8
+ // in `references/reaping.md`, and the load-bearing pair in
9
+ // `commands/review-and-fix.md` and `skills/run-team/SKILL.md` that hand the
10
+ // command to a dispatched agent as an instruction, not a comment. This file
11
+ // is what keeps the stale form from creeping back in one file at a time,
12
+ // the way it crept in 32 times before anyone swept for it.
13
+ //
14
+ // A DIFFERENT citation class from #516's own sweep
15
+ // (citation-sweep-prose.test.mjs, `path.ext:NNN` line numbers) and does not
16
+ // reach it: that file polices a fixed per-file table of stale/live pairs,
17
+ // this one asks git what ships and reads every one of them, because
18
+ // enumerating by hand is the shape that let this exact defect recur 32 times
19
+ // silently.
20
+ //
21
+ // Composed, never written contiguously: the two fragments the check joins
22
+ // below only spell the stale citation once concatenated, so this file's own
23
+ // source — itself tracked under `plugin/` — cannot satisfy the check it
24
+ // performs. A plain string literal holding the whole stale form would report
25
+ // this file as its own first offender the moment it landed under `plugin/`.
26
+ //
27
+ // repo-root.mjs's `trackedPaths`, not a directory walk: an untracked scratch
28
+ // file must never become a false positive, and a tracked file that moves out
29
+ // of `plugin/` must fall out of the sweep with it — same premise `repo-root.mjs`
30
+ // states for the sibling `*-sweep.test.mjs` files in this directory.
31
+ //
32
+ // KNOWN LIMIT, same as those siblings: needs an ambient `.git` to ask what
33
+ // ships. Absent one — a bare `git archive` extraction, how review specialists
34
+ // used to measure this very suite (#1056; the review snapshot carries a `.git`
35
+ // since then) — the tests below DECLINE with a reason rather than running;
36
+ // nothing here polices a tree it cannot see.
37
+ //
38
+ // Zero deps: `node --test plugin/scripts/scripts-path-citation-sweep.test.mjs`.
39
+
40
+ import { test } from "node:test";
41
+ import assert from "node:assert/strict";
42
+ import { readFileSync } from "node:fs";
43
+ import { join } from "node:path";
44
+ import { fileURLToPath } from "node:url";
45
+ import { repoRoot, skipWithoutRepo, trackedPaths } from "./repo-root.mjs";
46
+
47
+ const DIR = fileURLToPath(new URL(".", import.meta.url));
48
+ const ROOT = repoRoot(DIR);
49
+ const SKIP_WITHOUT_REPO = skipWithoutRepo(ROOT, "the sweep for the nonexistent scripts/ citation");
50
+
51
+ // Never written as one literal — see the header's "composed" note.
52
+ const STALE_CITATION = ["node --test", " scripts/"].join("");
53
+
54
+ /** Every tracked path under `plugin/`, repo-relative — what actually ships. */
55
+ const FILES = ROOT === null ? [] : trackedPaths(ROOT, ["plugin"]);
56
+
57
+ test("the sweep sees the tree it is supposed to police", { skip: SKIP_WITHOUT_REPO }, () => {
58
+ assert.ok(
59
+ FILES.length > 150,
60
+ `trackedPaths(ROOT, ["plugin"]) returned only ${FILES.length} entries — too few to be this plugin's real tree, and the check below would pass vacuously over an empty or near-empty list`,
61
+ );
62
+ });
63
+
64
+ test("no tracked file under plugin/ cites the nonexistent scripts/ suite root", { skip: SKIP_WITHOUT_REPO }, () => {
65
+ const offenders = FILES.filter((relPath) =>
66
+ readFileSync(join(ROOT, relPath), "utf8").includes(STALE_CITATION),
67
+ );
68
+ assert.deepEqual(
69
+ offenders,
70
+ [],
71
+ `these files cite a bare "scripts/" test path that does not exist — the suite root is "plugin/scripts/": ${offenders.join(", ")}`,
72
+ );
73
+ });
@@ -0,0 +1,378 @@
1
+ // #753. `section()` was a name-invisible twin of prose-pin.mjs's exported
2
+ // `between(text, from, to, what)`, duplicated byte-for-byte in
3
+ // implementer-model-tier.test.mjs and review-path-default.test.mjs, and with
4
+ // `RUN_TEAM` closed over instead of taken as an argument in
5
+ // fleet-tick-prose.test.mjs, within-run-pair-prose.test.mjs, and
6
+ // member-outcomes-prose.test.mjs. All five survived #751's own extraction
7
+ // because every sweep of that PR searched for the NAME `between` — this one
8
+ // searches for the SHAPE instead: `indexOf` -> `assert.notEqual(_, -1)` ->
9
+ // `indexOf(_, at + from.length)` -> `assert.notEqual(_, -1)` -> `return
10
+ // src.slice(at, end)`, the five statements `between()`'s body is built from,
11
+ // independent of what the function, its parameters, or its captured
12
+ // variables are called.
13
+ //
14
+ // NOT scoped to a reusable (parameterized) definition — an earlier revision
15
+ // of this file was, on the theory that a closure over a module-level
16
+ // constant is a distinct, already-blessed pattern (#608: "a file-local test
17
+ // fixture... drift produced no false green and no wrong behaviour"). That
18
+ // theory under-caught: within-run-pair-prose.test.mjs's own closure-shaped
19
+ // `section(startAnchor, endAnchor, label)` is exactly as much a twin of
20
+ // `between()` as the two parameterized copies were, and #608's own reasoning
21
+ // is about a fixture with ONE consumer, not about whether the five
22
+ // statements happen to close over an outer name instead of taking it as an
23
+ // argument. The shape below no longer cares which.
24
+ //
25
+ // Two near-misses in this same directory are NOT twins, and must not match,
26
+ // because each changes what the function DOES relative to `between()`
27
+ // (measured against this file's own detector, not asserted):
28
+ //
29
+ // dispatch-block-pins-prose.test.mjs's `region()` and
30
+ // finisher-pin-race-prose.test.mjs's `causeBlock()` both return
31
+ // `SRC.slice(at + START.length, end)` — the start anchor STRIPPED, not
32
+ // kept. `member-prompt-prose.test.mjs`'s inlined `memberBlocks()` was the
33
+ // same divergence when #753 cited it: `between()` keeps the start anchor;
34
+ // these need it gone, and swapping in `between()` un-stripped changes their
35
+ // output. #1465 rewrote `memberBlocks()` onto `anchorAt()`/`phrase()`, so it
36
+ // no longer has an `indexOf`/`assert.notEqual` shape at all and is excluded
37
+ // from this file's own detector by construction, not by this near-miss.
38
+ //
39
+ // finisher-own-tree-prose.test.mjs's `between()` returns
40
+ // `flat(RUN_TEAM.slice(at, to))` — flattened before return, not a bare
41
+ // slice. Its own caller needs the flattening; a shared `between()` does not
42
+ // do it and could not without changing every other caller's output too.
43
+ //
44
+ // cross-repo-citation-prose.test.mjs's `slice(text, startAnchor,
45
+ // endAnchor, what, { endsFile })` threads an `if (end === -1 && endsFile)
46
+ // return text.slice(at);` branch between the second `indexOf` and the
47
+ // second `assert.notEqual` — the five statements are no longer adjacent,
48
+ // and the function does something (`endsFile`'s EOF tolerance) `between()`
49
+ // cannot.
50
+ //
51
+ // finisher-pin-race-prose.test.mjs's `fallbackSection()` and
52
+ // review-pr-citation-prose.test.mjs's `specialists()` looked like two more —
53
+ // a search from `at` instead of `at + start.length`, and a literal-anchor
54
+ // call this detector cannot even see, respectively — but a before/after
55
+ // byte comparison against their real inputs (RUN_TEAM / REVIEW_AND_FIX)
56
+ // proved both output-identical to `between()`: neither pair's end anchor
57
+ // ever occurs inside its own start anchor's text, so the narrower contract
58
+ // `fallbackSection()`'s own header once claimed never actually diverges.
59
+ // Both are now `import { between }` call sites like every other consumer,
60
+ // not documented exceptions.
61
+ //
62
+ // THE FLOOR: an empty or near-empty directory listing (a broken glob, or
63
+ // this file moved to the wrong place) would make the main assertion below
64
+ // pass vacuously — nothing scanned, nothing found. `SCRIPTS.length` is
65
+ // asserted against a conservative floor to catch that before it hides a real
66
+ // regression.
67
+ import { test } from "node:test";
68
+ import assert from "node:assert/strict";
69
+ import { readdirSync, readFileSync } from "node:fs";
70
+ import { join } from "node:path";
71
+ import { stripComments } from "./strip-comments.mjs";
72
+
73
+ const DIR = import.meta.dirname;
74
+ const SELF = "section-between-guard-prose.test.mjs";
75
+ const PROSE_PIN = "prose-pin.mjs";
76
+
77
+ // The five statements `between()`'s body is built from, as one pattern:
78
+ // const AT = SRC.indexOf(FROM);
79
+ // assert.notEqual(AT, -1, ...);
80
+ // const END = SRC.indexOf(TO, AT + FROM.length);
81
+ // assert.notEqual(END, -1, ...);
82
+ // return SRC.slice(AT, END);
83
+ // captured over a `function name(...)` declaration, a `(...) => {` arrow
84
+ // bound with `const`, `let`, or `var`, or a bare method-shorthand
85
+ // `name(...) {` (the name position excludes the JS control-flow keywords —
86
+ // `if`/`for`/`while`/`switch`/`catch`/`do`/`with`/`else` — so an ordinary
87
+ // control-flow block is never mistaken for a twin), with every identifier
88
+ // free to vary (matched by backreference, not by name) and free to be
89
+ // either a parameter or a closed-over outer constant — `between`,
90
+ // `section`, and any future reintroduction's own choice of names and
91
+ // scoping all satisfy it identically. `const`, `let`, and `var` are all
92
+ // accepted for the two inner declarations for the same reason: nothing
93
+ // about the shape depends on which keyword binds `at` and `end`.
94
+ // The exact offset (`AT + FROM.length`) in the second `indexOf` call used
95
+ // to be mandatory. That meant an offset-less reintroduction — exactly
96
+ // `fallbackSection()`'s own historical shape (a search from `AT` instead
97
+ // of `AT + FROM.length`) — passed this detector completely undetected:
98
+ // #1422 (item 2) measured this live, writing that exact historical shape
99
+ // as a real scanned file and finding zero offenders reported, which is a
100
+ // genuine detection gap, not a documented exclusion — the ticket's own
101
+ // stated rationale is that this shape is exactly what the guard exists to
102
+ // catch. Fixed here by making the offset argument optional rather than
103
+ // mandatory: the second `indexOf` may now take no offset argument, a bare
104
+ // `AT`, or the full `AT + FROM.length`, and all three still bind the same
105
+ // two variable names. The dedicated `offsetOnly` positive control (see the
106
+ // "fires" test below) isolates this on its own — everywhere else identical
107
+ // to `between()` — and is now correctly flagged as a twin. The two
108
+ // return-shape near-misses below (`strippedStart`, `flattenedReturn`)
109
+ // remain excluded regardless, because their divergence is in the return
110
+ // statement, not the offset.
111
+ //
112
+ // Comments are stripped before matching (`strip-comments.mjs`, the same
113
+ // helper candidates.test.mjs and the review-pr-*.test.mjs pins already
114
+ // share): this repo's own style routinely puts a `//` line between two of
115
+ // the five statements (cross-repo-citation-prose.test.mjs), and the `\s*`
116
+ // separators above do not span a real comment's text — measured directly,
117
+ // an un-stripped scan misses a reintroduced twin written that way.
118
+ // `strip-comments.mjs` only blanks WHOLE-LINE comments by design (its own
119
+ // header's documented ceiling — candidates.test.mjs and the review-pr-*
120
+ // pins depend on trailing comment text surviving); a TRAILING `stmt; //
121
+ // note` therefore reaches TWIN_SHAPE unstripped. #1422: measured live, a
122
+ // trailing-commented twin appended to a real scanned file passed the sweep
123
+ // below undetected. Fixed here, not in the shared helper, with an optional
124
+ // `(?:[ \t]*\/\/[^\n]*)?` after each of the five statements' own `;` —
125
+ // scoped to this file's own separator so the shared helper's ceiling, and
126
+ // everything measured against it, is untouched.
127
+ //
128
+ // SCOPE, and not reopened after this round: the shape above is matched
129
+ // under function, const/let/var arrow, and method-shorthand declarations
130
+ // and no others — generator functions, computed method names, decorators,
131
+ // and any spelling past those are deliberately unattempted, because a
132
+ // regex-based structural guard cannot enumerate every JS declaration syntax
133
+ // and only needs to outlast the spellings a reintroduction has actually
134
+ // taken, not every one it could someday take.
135
+ //
136
+ // KNOWN-OPEN, deliberately not chased this round (#1422's own boundary: a
137
+ // test-only guard has diminishing returns from hunting every regex edge
138
+ // case): a `//` comment on the declaration line right after the opening
139
+ // `{`; a trailing `/* ... */` block comment in place of `//` after any of
140
+ // the five statements; a `//` or `/* ... */` comment inside the second
141
+ // `indexOf`'s own argument list, between `\5.length` and its closing `)`.
142
+ // All three bypass this detector entirely — measured directly against the
143
+ // regex below, not asserted. None occur in this repo's own style today
144
+ // (see the `commented` and `trailingComment` fixtures above for the style
145
+ // that does occur); revisit only if a real file is measured to use one.
146
+ const TWIN_SHAPE = /(?:function\s+\w+\s*\(([^)]*)\)|(?:const|let|var)\s+\w+\s*=\s*\(([^)]*)\)\s*=>|\b(?!function\b|if\b|for\b|while\b|switch\b|catch\b|do\b|with\b|else\b)\w+\s*\((?:[^)]*)\))\s*\{\s*(?:const|let|var)\s+(\w+)\s*=\s*(\w+)\.indexOf\((\w+)\);(?:[ \t]*\/\/[^\n]*)?\s*assert\.notEqual\(\3,\s*-1,[\s\S]*?\);(?:[ \t]*\/\/[^\n]*)?\s*(?:const|let|var)\s+(\w+)\s*=\s*\4\.indexOf\((\w+)(?:,\s*\3(?:\s*\+\s*\5\.length)?)?\);(?:[ \t]*\/\/[^\n]*)?\s*assert\.notEqual\(\6,\s*-1,[\s\S]*?\);(?:[ \t]*\/\/[^\n]*)?\s*return\s+\4\.slice\(\3,\s*\6\);(?:[ \t]*\/\/[^\n]*)?\s*\}/g;
147
+
148
+ /** Every `between()`-shaped definition in `text`, wherever it lives. */
149
+ function twinDefinitions(text) {
150
+ return [...stripComments(text).matchAll(TWIN_SHAPE)].map((m) => ({ src: m[4], from: m[5], to: m[7] }));
151
+ }
152
+
153
+ const SCRIPTS = readdirSync(DIR).filter((f) => f.endsWith(".mjs") && f !== SELF && f !== PROSE_PIN);
154
+
155
+ test("the sweep sees the scripts it is supposed to police", () => {
156
+ // A floor, not a count: this directory carries ~150 `.mjs` files today and
157
+ // a regression here (an empty/near-empty listing) would make the twin
158
+ // sweep below pass over nothing rather than over the tree.
159
+ assert.ok(SCRIPTS.length >= 100, `expected the plugin/scripts .mjs files, found ${SCRIPTS.length}`);
160
+ });
161
+
162
+ test("the shape detector fires on the exact bodies #753 removed, by construction", () => {
163
+ // Positive control, parameterized form (implementer-model-tier.test.mjs
164
+ // and review-path-default.test.mjs's own removed shape).
165
+ const parameterized = `
166
+ function section(source, startAnchor, endAnchor, label) {
167
+ const at = source.indexOf(startAnchor);
168
+ assert.notEqual(at, -1, \`\${label}: '\${startAnchor}' moved\`);
169
+ const end = source.indexOf(endAnchor, at + startAnchor.length);
170
+ assert.notEqual(end, -1, \`\${label}: '\${endAnchor}' moved\`);
171
+ return source.slice(at, end);
172
+ }`;
173
+ assert.deepEqual(twinDefinitions(parameterized), [{ src: "source", from: "startAnchor", to: "endAnchor" }]);
174
+
175
+ // Positive control, closure form (fleet-tick-prose.test.mjs,
176
+ // within-run-pair-prose.test.mjs, and member-outcomes-prose.test.mjs's own
177
+ // removed shape) — the source text is a free variable, not a parameter,
178
+ // and must fire exactly as readily.
179
+ const closure = `
180
+ const RUN_TEAM = "…";
181
+ function section(startAnchor, endAnchor, label) {
182
+ const at = RUN_TEAM.indexOf(startAnchor);
183
+ assert.notEqual(at, -1, label);
184
+ const end = RUN_TEAM.indexOf(endAnchor, at + startAnchor.length);
185
+ assert.notEqual(end, -1, label);
186
+ return RUN_TEAM.slice(at, end);
187
+ }`;
188
+ assert.deepEqual(twinDefinitions(closure), [{ src: "RUN_TEAM", from: "startAnchor", to: "endAnchor" }]);
189
+
190
+ // prose-pin.mjs's own `between` — an arrow-function reintroduction under a
191
+ // different name must be caught exactly as readily as a `function` one.
192
+ const arrowForm = `
193
+ const clone = (text, from, to, what) => {
194
+ const at = text.indexOf(from);
195
+ assert.notEqual(at, -1, what);
196
+ const end = text.indexOf(to, at + from.length);
197
+ assert.notEqual(end, -1, what);
198
+ return text.slice(at, end);
199
+ };`;
200
+ assert.deepEqual(twinDefinitions(arrowForm), [{ src: "text", from: "from", to: "to" }]);
201
+
202
+ // A `//` comment between two of the five statements, and `let` instead of
203
+ // `const` for both inner declarations — this repo's own style
204
+ // (cross-repo-citation-prose.test.mjs) and a measured miss: an earlier
205
+ // revision of TWIN_SHAPE matched none of this against the unstripped
206
+ // source.
207
+ const commented = `
208
+ function twin(text, from, to, what) {
209
+ let at = text.indexOf(from);
210
+ // explain why this search runs first
211
+ assert.notEqual(at, -1, what);
212
+ let end = text.indexOf(to, at + from.length);
213
+ assert.notEqual(end, -1, what);
214
+ return text.slice(at, end);
215
+ }`;
216
+ assert.deepEqual(twinDefinitions(commented), [{ src: "text", from: "from", to: "to" }]);
217
+
218
+ // #1422: a TRAILING `//` comment on one of the five statement lines, not
219
+ // a comment on its own line — `strip-comments.mjs` only blanks whole-line
220
+ // comments (its own documented ceiling), so this reaches TWIN_SHAPE with
221
+ // the comment text still attached to the statement. Measured miss: an
222
+ // earlier revision of TWIN_SHAPE matched none of this. TWIN_SHAPE has a
223
+ // separate optional trailing-comment allowance after each of its five
224
+ // statements; each case below isolates one, so deleting any single
225
+ // allowance turns exactly that one case red without disturbing the
226
+ // other four — measured directly, one position at a time.
227
+ const trailingCommentExpected = [{ src: "text", from: "from", to: "to" }];
228
+ const trailingCommentCases = {
229
+ "first indexOf": `
230
+ function twin(text, from, to, what) {
231
+ let at = text.indexOf(from); // note
232
+ assert.notEqual(at, -1, what);
233
+ let end = text.indexOf(to, at + from.length);
234
+ assert.notEqual(end, -1, what);
235
+ return text.slice(at, end);
236
+ }`,
237
+ "first assert.notEqual": `
238
+ function twin(text, from, to, what) {
239
+ let at = text.indexOf(from);
240
+ assert.notEqual(at, -1, what); // note
241
+ let end = text.indexOf(to, at + from.length);
242
+ assert.notEqual(end, -1, what);
243
+ return text.slice(at, end);
244
+ }`,
245
+ "second indexOf": `
246
+ function twin(text, from, to, what) {
247
+ let at = text.indexOf(from);
248
+ assert.notEqual(at, -1, what);
249
+ let end = text.indexOf(to, at + from.length); // note
250
+ assert.notEqual(end, -1, what);
251
+ return text.slice(at, end);
252
+ }`,
253
+ "second assert.notEqual": `
254
+ function twin(text, from, to, what) {
255
+ let at = text.indexOf(from);
256
+ assert.notEqual(at, -1, what);
257
+ let end = text.indexOf(to, at + from.length);
258
+ assert.notEqual(end, -1, what); // note
259
+ return text.slice(at, end);
260
+ }`,
261
+ return: `
262
+ function twin(text, from, to, what) {
263
+ let at = text.indexOf(from);
264
+ assert.notEqual(at, -1, what);
265
+ let end = text.indexOf(to, at + from.length);
266
+ assert.notEqual(end, -1, what);
267
+ return text.slice(at, end); // note
268
+ }`,
269
+ };
270
+ for (const [label, source] of Object.entries(trailingCommentCases)) {
271
+ assert.deepEqual(twinDefinitions(source), trailingCommentExpected, `trailing comment after ${label}`);
272
+ }
273
+
274
+ // Positive control, method-shorthand form — no real removed twin took
275
+ // this shape, but a bare `name(...) { ... }` inside an object literal or
276
+ // class must fire exactly as readily as a `function` declaration or an
277
+ // arrow, and must not be confused with an ordinary control-flow block
278
+ // (see the "does not fire" test below for that half of the guard).
279
+ const methodShorthand = `
280
+ const helper = {
281
+ grab(text, from, to, what) {
282
+ const at = text.indexOf(from);
283
+ assert.notEqual(at, -1, what);
284
+ const end = text.indexOf(to, at + from.length);
285
+ assert.notEqual(end, -1, what);
286
+ return text.slice(at, end);
287
+ },
288
+ };`;
289
+ assert.deepEqual(twinDefinitions(methodShorthand), [{ src: "text", from: "from", to: "to" }]);
290
+
291
+ // Positive control, `var`-declared form — both the arrow-style
292
+ // declaration and the two inner offset variables must fire when bound
293
+ // with `var` instead of `const`/`let`, the same reasoning carried one
294
+ // keyword further.
295
+ const varForm = `
296
+ var twin = (text, from, to, what) => {
297
+ var at = text.indexOf(from);
298
+ assert.notEqual(at, -1, what);
299
+ var end = text.indexOf(to, at + from.length);
300
+ assert.notEqual(end, -1, what);
301
+ return text.slice(at, end);
302
+ };`;
303
+ assert.deepEqual(twinDefinitions(varForm), [{ src: "text", from: "from", to: "to" }]);
304
+
305
+ // Positive control, offset-less form — #1422: TWIN_SHAPE's second
306
+ // `indexOf` used to require the `AT + FROM.length` offset exactly;
307
+ // `fallbackSection()`'s own historical shape searched from `AT` alone
308
+ // and reached this detector completely undetected (measured live: zero
309
+ // offenders reported for that exact shape as a real scanned file). The
310
+ // offset argument is now optional, so a bare `AT` (or no offset at all)
311
+ // must fire exactly as readily as the full `AT + FROM.length` form,
312
+ // while the return-shape near-misses below remain excluded.
313
+ const offsetOnly = `
314
+ function offsetless(text, from, to, what) {
315
+ const at = text.indexOf(from);
316
+ assert.notEqual(at, -1, what);
317
+ const end = text.indexOf(to, at);
318
+ assert.notEqual(end, -1, what);
319
+ return text.slice(at, end);
320
+ }`;
321
+ assert.deepEqual(twinDefinitions(offsetOnly), [{ src: "text", from: "from", to: "to" }]);
322
+ });
323
+
324
+ test("the shape detector does not fire on the measured near-misses", () => {
325
+ // Each changes one thing between() does not: stripped start anchor, or a
326
+ // flattened return. See the header for which file each is modeled on.
327
+ // Neither isolates the offset backreference on its own — that's the
328
+ // `offsetOnly` positive control in the "fires" test above, now that the
329
+ // offset argument is optional rather than mandatory.
330
+ const strippedStart = `
331
+ function region() {
332
+ const at = RUN_TEAM.indexOf(START);
333
+ assert.notEqual(at, -1, "x");
334
+ const end = RUN_TEAM.indexOf(END, at);
335
+ assert.notEqual(end, -1, "y");
336
+ return RUN_TEAM.slice(at + START.length, end);
337
+ }`;
338
+ assert.deepEqual(twinDefinitions(strippedStart), []);
339
+
340
+ const flattenedReturn = `
341
+ function between(start, end) {
342
+ const at = RUN_TEAM.indexOf(start);
343
+ assert.notEqual(at, -1, "x");
344
+ const to = RUN_TEAM.indexOf(end, at);
345
+ assert.notEqual(to, -1, "y");
346
+ return flat(RUN_TEAM.slice(at, to));
347
+ }`;
348
+ assert.deepEqual(twinDefinitions(flattenedReturn), []);
349
+
350
+ // A control-flow block shaped exactly like the five statements must not
351
+ // be mistaken for a method-shorthand twin — the third TWIN_SHAPE
352
+ // alternative excludes JS keywords from the name position for exactly
353
+ // this reason.
354
+ const ifBlock = `
355
+ if (x) {
356
+ const at = RUN_TEAM.indexOf(x);
357
+ assert.notEqual(at, -1, "x");
358
+ const end = RUN_TEAM.indexOf(y, at + x.length);
359
+ assert.notEqual(end, -1, "y");
360
+ return RUN_TEAM.slice(at, end);
361
+ }`;
362
+ assert.deepEqual(twinDefinitions(ifBlock), []);
363
+ });
364
+
365
+ test("no file outside prose-pin.mjs defines a second between()-shaped slicer", () => {
366
+ const offenders = [];
367
+ for (const file of SCRIPTS) {
368
+ const text = readFileSync(join(DIR, file), "utf8");
369
+ for (const twin of twinDefinitions(text)) {
370
+ offenders.push(`${file} (src: ${twin.src}, from: ${twin.from}, to: ${twin.to})`);
371
+ }
372
+ }
373
+ assert.deepEqual(
374
+ offenders,
375
+ [],
376
+ `reintroduced a between()-shaped slicer outside prose-pin.mjs — import { between } instead:\n${offenders.join("\n")}`,
377
+ );
378
+ });