@feigi/fleet-ctl 3.136.14 → 3.137.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.
@@ -19,7 +19,7 @@ Your scratch directory is `<scratch>/`; you write only under
19
19
 
20
20
  Your report is the one file you write outside it: `<scratch>/reports/merge-bot-<n>.json`,
21
21
  the path your brief names, giving every PR queued when you were dispatched
22
- exactly one verdict — `merged`, `held`, `conflictHold` or `refused` — as
22
+ exactly one verdict — `merged`, `conflictHold` or `refused` — as
23
23
  run-merge-bot.md's **One verdict per queued PR** says. Your final
24
24
  message is the one line your brief gives, `merge-bot-<n>: done <path>`. A Label map
25
25
  refusal follows that line with what `show` printed.
@@ -1,12 +1,12 @@
1
1
  ---
2
- description: merge every ready-to-merge open PR in numeric order — rebase, wait green, merge, never jumping a related PR
2
+ description: merge every ready-to-merge open PR in numeric order — rebase, wait green, merge
3
3
  ---
4
4
 
5
5
  Label names in this file are roles; the Label map gives the string to type; a member never derives the map.
6
6
 
7
7
  Set the goal, then work it until no open PR is left:
8
8
 
9
- `/goal Merge all of this repo's open PRs in numeric order if labeled ready-to-merge. Rebase -> Wait for checks green -> check for the ready-to-merge label -> merge if labeled. Never merge past a lower-numbered PR whose work is related — wait for its label instead.`
9
+ `/goal Merge all of this repo's open PRs in numeric order if labeled ready-to-merge. Rebase -> Wait for checks green -> check for the ready-to-merge label -> merge if labeled.`
10
10
 
11
11
  Only `ready-to-merge` PRs are in scope — it is the author's sign-off. Never add the label yourself. A PR-body line `main-gain-removal: <path> <key> - <why>` is a second sign-off, scoped to one file and one landing source: it lets through the removal of lines `main` gained after the PR began in that file from that source, and nothing else (step 3's `main-gain-removed`).
12
12
 
@@ -19,45 +19,15 @@ Only `ready-to-merge` PRs are in scope — it is the author's sign-off. Never ad
19
19
  - **A bot a controller dispatched** holds no grace. Read the queue your dispatch recorded, which needs no map — `~/.fleet/bin/fleet-run ledger.mjs read | jq -c '.queued["merge-bot-<n>"]'` — and write your one report giving every PR there `refused` with `reason` `label-map-refused`; an empty or absent queue gives every list empty. Validate it as **One verdict per queued PR** says, then send your final line followed by what `show` printed.
20
20
  - **The top-level invocation** prints what `show` printed and stops. It writes no report.
21
21
 
22
- ## Order, and the hold rule
22
+ ## Order
23
23
 
24
- Lowest number first. But the label alone does not authorize a merge: **a labeled PR must not jump a lower-numbered open PR touching related work.** Numeric order is the author's intended order; jumping it silently rebases the lower PR onto changes it was never written against.
25
-
26
- Before touching labeled PR `N`, list every open PR below `N` lacking the label. For each, decide related or not:
27
-
28
- ```bash
29
- ~/.fleet/bin/fleet-run pr-overlap.mjs --a <lower-pr> --b <N>
30
- ```
31
-
32
- **Any** of its four signals (`files`, `modules`, `dirs`, `prose`) firing means related. Path equality alone is too weak: a repo mid-migration has `src/…/test_foo.py` in one PR and `tests/unit/…/test_foo.py` in the other — same module, zero shared paths. A module is a test file's name with its test affix and extension removed, in any language (`foo.test.ts`, `foo_test.go` and `test_foo.py` are all `foo`); other files are not modules.
33
-
34
- Two false positives in signal 3:
35
-
36
- - **Repo root (`.`) is excluded above.** Every top-level file shares it, so it fires on PRs with nothing in common.
37
- - **A bare top-level directory (`docs`, `tests`, `src`) is weak evidence.** Two PRs editing different documents under `docs/` are unrelated. Look at the actual files first: same document, module, or config → related. Different subjects sharing an ancestor → not related; proceed and say so.
38
-
39
- **Signal 4, `prose`, is the one `signal=none` used to miss, and the only one that reads content rather than paths.** It fires when one PR changes a data file (`.tsv`, `.json`, `.yml`, …) whose path or basename appears in the other PR's own diff — the append-vs-rewrite collision `docs/metrics/tier-outcomes.tsv` has with `run-team/SKILL.md`'s tier guard by construction, since the file is append-only and every run produces a PR touching it. Weak evidence, on a par with a directory hit, and it prints its witness — the cited file, the citing file, the token and the line — because one read disproves it. It is ranked LAST, so it only ever converts a `none`: a `files`, `modules` or `dirs` verdict still reads exactly as it did before, with `prose=<n>` on the summary line beside it.
40
-
41
- **`prose=0` is a clear only when `proseUnrun` is `null`.** A non-null `proseUnrun` means the scan was reached and could not cover the diff, so an empty `prose[]` there is silence rather than data — read the reason it names and settle the pair by hand.
42
-
43
- Directory-only and prose-only hits prompt investigation. Shared *files* and *module names* are verdicts.
44
-
45
- - **Related → HOLD `N`.** Do not rebase, do not merge. Report `held-behind-#<lower>` and move on. The watcher picks it up once the lower PR is signed off and merged.
46
- - **Unrelated → proceed**, and report that it went ahead of `#<lower>` and on what evidence.
47
-
48
- Also **related** even with an empty file intersection when:
49
-
50
- - both reference the same issue, or were split from one
51
- - one branch is stacked on the other, or their names share an issue/cluster
52
- - they change the same exported symbol, config key, or docs section from different files — signal 4 mechanises the half of this where the section is a **data file** cited by name, so read `prose` before reaching for this bullet; a bare symbol or key name is still yours to read, and the measurement in the next paragraph is why it stays that way
53
-
54
- Genuinely unclear → **hold**. Waiting costs a label; merging out of order costs a conflict resolution on someone else's branch, and the loser is the PR already reviewed.
55
-
56
- **A fired signal is not a verdict — disprove it.** Soft signals fire on deliberately-partitioned PRs. Observed: two PRs sharing two issue refs and all of `reset_hint=` / `resetHint` / `terminalFailure`, provably unrelated — one handed the other a specific emit site in its own body, their exact-string pins were punctuation-distinct so neither could match the other's site, and **both were test-only**. That generalizes: **a test-only PR cannot invalidate what another PR asserts**, and neither can a docs-only one.
57
-
58
- **`git merge-tree --write-tree <branch-a> <branch-b>` disproves a fired signal without inference.** It performs the merge in-memory and writes a tree, exiting non-zero with the conflicting paths on stdout only when the merge genuinely conflicts. That is a real answer, not an inference from a behind-count — being behind is not evidence of conflict. `rc=0` with a written tree means the two branches merge clean; run it on `files` before holding. It answers only whether the two trees conflict textually, not whether one PR's content invalidates the other's — the same-issue, stacked-branch, and shared-symbol conditions still decide that.
59
-
60
- Obeying a fired signal blindly stalls the queue on a non-conflict; ignoring one is sloppy. Do the work, report which evidence settled it.
24
+ Lowest number first, among the PRs that carry the label. A labelled PR never
25
+ waits on an open PR without it, however related their work: if merging it
26
+ leaves that PR conflicting, the conflict is that PR's to clear, as after any
27
+ merge — a fleet run's tick hands one on a PR it tracks to a fix-applier, and
28
+ any other PR's author clears it. Waiting would not avoid the conflict, only
29
+ move it onto the labelled PR, where clearing it changes the change the label
30
+ was given for, and the label no longer covers it.
61
31
 
62
32
  ## The labelled head
63
33
 
@@ -94,7 +64,7 @@ What this gate deliberately does not answer. It does not ask *who* audited — a
94
64
 
95
65
  ## Per-PR sequence
96
66
 
97
- For each labeled PR clearing the hold rule, lowest first:
67
+ For each labeled PR, lowest first:
98
68
 
99
69
  **Before step 1, check the ledger for an unresolved conflict hold on this PR.** Read the ticket row that names it — the same lookup step 4 below uses (`ledger.mjs read`). A `conflict-hold:#<pr>` token with no `fix-pr-<n>` settled (`applied:`/`no-op`) *after* it — reading the row left to right, past whatever dispatched after the LATEST hold token — is unresolved: a fix-applier already owns this PR's conflict, whether the hold came from this pass, an earlier one, or the controller off the tick's `CONFLICT` line. **Skip it**: do not rebase, do not touch the row, do not report `rebase-fallback-#<pr>` again. Report `conflict-held-#<pr>` and move to the next labeled PR. Only once a fix-applier dispatched after the hold has settled does it clear — proceed through the sequence below as normal from there.
100
70
 
@@ -295,8 +265,8 @@ Measured over one three-merge pass: the next queue member went 0 → 2 → 7 →
295
265
 
296
266
  **A PR whose heavy jobs have only ever `skipped` is getting its first real verification from your rebase.** Reviewers may legitimately have labelled on the checks that did run plus local evidence, saying so explicitly. When your post-rebase run finally executes those suites, treat a red there as a **genuine first result**, not a regression you caused — read the failing job before concluding, and do not hand it back as "the rebase broke it".
297
267
 
298
- Report merged / skipped-unlabeled / held-behind-#X / worktree-diverged-#X / head-moved-after-label-#X / rebase-carry-#X (merged or not, with the labelled and accepted SHAs) / main-gain-removed:<path>-#X / label-drop-failed-#X / label-read-failed-#X / branch-delete-failed-#X / branch-kept-#X (X the open PR that keeps the merged branch — a keep, not a failure) / rebase-fallback-#X / instrument-set-changed-#X / ci-wait-timeout-#X (with the run id and its `status`) / `<reason>-#X` for any other gate refusal / blocked after the pass — a dispatched bot once, at exit, after its grace (**Grace, then one report**, below). Every acknowledged main-gain removal the gate passed is named in the report, with its reason.
299
- In the report file, every PR queued when you were dispatched is listed under exactly one of `merged`, `held`, `conflictHold` or `refused` — those four lists are its verdict, the tokens above are not — and a settle check refuses a report that leaves one out (**One verdict per queued PR**, under **Grace, then one report**).
268
+ Report merged / skipped-unlabeled / worktree-diverged-#X / head-moved-after-label-#X / rebase-carry-#X (merged or not, with the labelled and accepted SHAs) / main-gain-removed:<path>-#X / label-drop-failed-#X / label-read-failed-#X / branch-delete-failed-#X / branch-kept-#X (X the open PR that keeps the merged branch — a keep, not a failure) / rebase-fallback-#X / instrument-set-changed-#X / ci-wait-timeout-#X (with the run id and its `status`) / `<reason>-#X` for any other gate refusal / blocked after the pass — a dispatched bot once, at exit, after its grace (**Grace, then one report**, below). Every acknowledged main-gain removal the gate passed is named in the report, with its reason.
269
+ In the report file, every PR queued when you were dispatched is listed under exactly one of `merged`, `conflictHold` or `refused` — those lists are its verdict, the tokens above are not — and a settle check refuses a report that leaves one out (**One verdict per queued PR**, under **Grace, then one report**).
300
270
 
301
271
  ## No-undo audit (before every rebase)
302
272
 
@@ -328,8 +298,8 @@ Three dots, never two: a two-dot diff on a stale branch renders `main`'s gains a
328
298
 
329
299
  **Only a bot a controller dispatched holds a grace** (`/skill:run-team`, or any caller that says it owns the watcher); the top-level invocation arms its Monitor instead (**Then stay armed**). You were dispatched on the first `ready-to-merge` label, never after anyone's report, and a label landing minutes after your last merge is the common case — so the pass does not end the moment the queue empties. It drains, then waits **15 minutes** for late labels, then reports once:
330
300
 
331
- - Grace starts once no labelled PR is actionable — every one merged, skipped or held. Seed the labelled set then, the way **Then stay armed** seeds its Monitor, so a PR you already handled does not re-fire.
332
- - Every 60s, poll `gh pr list --state open --label "<ready-to-merge string>" --limit 200 --json number`. A number not in the seed → **re-run selection from the top**, hold rule included, drain what it makes actionable, and restart the grace after that drain. A failed poll is no reading: keep the seed and poll again. A poll that returns 200 numbers is not a whole reading either — gh stops at `--limit` with exit 0 and no warning, so a label past it is unseen: act on the numbers it did return, and name `poll-capped-at-200` in the report, so the controller knows the grace's silence covered only the first 200.
301
+ - Grace starts once no labelled PR is actionable — every one merged, skipped or conflict-held. Seed the labelled set then, the way **Then stay armed** seeds its Monitor, so a PR you already handled does not re-fire.
302
+ - Every 60s, poll `gh pr list --state open --label "<ready-to-merge string>" --limit 200 --json number`. A number not in the seed → **re-run selection from the top**, drain what it makes actionable, and restart the grace after that drain. A failed poll is no reading: keep the seed and poll again. A poll that returns 200 numbers is not a whole reading either — gh stops at `--limit` with exit 0 and no warning, so a label past it is unseen: act on the numbers it did return, and name `poll-capped-at-200` in the report, so the controller knows the grace's silence covered only the first 200.
333
303
  - At grace start and on every 60s poll after it, also read `gh pr list --state open --limit 1 --json number`. An empty list (no PR open at all, any author, labelled or not) ends the grace: report and exit now. A failed read is no reading: keep waiting. It applies draining or not, and again after a late-label drain restarts the grace.
334
304
  - 15 minutes with no new label → report and exit.
335
305
 
@@ -337,9 +307,9 @@ The wait:
337
307
 
338
308
  `bash` backgrounds any call past about 60s even with `timeout` set — hold the whole grace in one Python `eval` cell that polls `gh` through `subprocess.run`, its cell `timeout` at 1000s or more; never `bash` plus `wait`, which then returns "Skipped due to a queued background completion".
339
309
 
340
- **One report, at exit, and none before it** — every PR this pass touched, in the vocabulary above, a pass that merged nothing included. The controller reaps on that report and records each `held-behind-#<lower>` on the held ticket's row, so a report sent mid-pass is one it acts on too early.
310
+ **One report, at exit, and none before it** — every PR this pass touched, in the vocabulary above, a pass that merged nothing included. The controller reaps on that report, so a report sent mid-pass is one it acts on too early.
341
311
 
342
- **One verdict per queued PR, in the report file.** A dispatched bot's report file (`<scratch>/reports/merge-bot-<n>.json`) gives every PR that carried `ready-to-merge` when you were dispatched exactly one verdict — the last it reached in the pass: `merged`, `held` (a `held-behind-#<lower>`), `conflictHold` (a `conflict-held-#<pr>`, or a `rebase-fallback-#<pr>` you recorded as a conflict hold), or `refused` with the token above as its `reason` (`main-gain-removed:<path>`, `head-moved-after-label`, `ci-wait-timeout`, any other gate refusal). A PR you never reached is still `refused`, with the reason you stopped short of it; a PR refused `behind:<n>` and merged later in the same pass is only `merged`. `branchKept` is not a verdict. Two checks enforce this, not the rule alone: `report-schema.mjs validate merge-bot` answers `invalid` for a PR named twice, in one list or in two, and for a `refused` entry whose `reason` is empty or only whitespace; and `ledger.mjs settle merge-bot-<n> --from-report`, which `fleet-event.mjs merge-bot-report` runs, judges the report against the queue `ledger.mjs dispatch merge-bot` recorded on your `## Dispatched` entry — never a list your report supplies — and refuses it, naming each PR, when a PR from that queue that is still open and carries `ready-to-merge` has no verdict. A PR labelled after your dispatch, or one that left the queue before the settle, never fails it. Each `refused` entry lands in the ledger's `## Ruled` as `merge-bot-<n> refused #<pr>: <reason>`, the reason trimmed, a record only: it moves no label and holds nothing.
312
+ **One verdict per queued PR, in the report file.** A dispatched bot's report file (`<scratch>/reports/merge-bot-<n>.json`) gives every PR that carried `ready-to-merge` when you were dispatched exactly one verdict — the last it reached in the pass: `merged`, `conflictHold` (a `conflict-held-#<pr>`, or a `rebase-fallback-#<pr>` you recorded as a conflict hold), or `refused` with the token above as its `reason` (`main-gain-removed:<path>`, `head-moved-after-label`, `ci-wait-timeout`, any other gate refusal). A PR you never reached is still `refused`, with the reason you stopped short of it; a PR refused `behind:<n>` and merged later in the same pass is only `merged`. `branchKept` is not a verdict. Two checks enforce this, not the rule alone: `report-schema.mjs validate merge-bot` answers `invalid` for a PR named twice, in one list or in two, and for a `refused` entry whose `reason` is empty or only whitespace; and `ledger.mjs settle merge-bot-<n> --from-report`, which `fleet-event.mjs merge-bot-report` runs, judges the report against the queue `ledger.mjs dispatch merge-bot` recorded on your `## Dispatched` entry — never a list your report supplies — and refuses it, naming each PR, when a PR from that queue that is still open and carries `ready-to-merge` has no verdict. A PR labelled after your dispatch, or one that left the queue before the settle, never fails it. Each `refused` entry lands in the ledger's `## Ruled` as `merge-bot-<n> refused #<pr>: <reason>`, the reason trimmed, a record only: it moves no label and holds nothing.
343
313
 
344
314
  Your `task` result is the report, delivered when you exit.
345
315
 
@@ -396,6 +366,5 @@ Arm with `persistent: true`, description `ready-to-merge label on this repo's PR
396
366
  - **A full page is not a whole reading either.** `gh pr list` stops at its `--limit` — 30 when the flag is absent — with exit 0 and no warning, so `poll` passes an explicit one (`cap`, one variable for the flag and the check), and `capcheck` says once when a poll fills it and once when one comes back under it: the DEGRADED/RECOVERED latch `run-team/SKILL.md`'s CI Monitor uses for the same cause, and never a line per tick. The numbers a capped poll did return are still real events; the line is for the labels past them, which fire nothing while it holds.
397
367
  - **The per-PR loop is heredoc-fed on purpose — `for n in $cur` is the one form that cannot work here.** This runs under zsh, which word-splits an unquoted command substitution's result but *not* an unquoted parameter expansion, and `cur` is a parameter. Measured on zsh 5.9 with `seen` holding two PR numbers and `cur` those two plus a third: the bare form runs **one** iteration with the whole list glued into a single value and emits one `ready-to-merge label added:` event with all three numbers glued into it, one nonsense event naming no PR, while the real new PR is never reported; the heredoc form emits the third alone. `run-team/references/shell-traps.md`'s **Shell traps** carries the mechanism and the `</dev/null` trap that bites the next command added inside this loop, and that file carries the remedy table. Note the contrast with step 1's `for _ in $(seq 1 60)`: that is a command substitution, it splits, and it is correct as written.
398
368
  - 60s poll — remote API, stay off rate limits.
399
- - A held PR stays in `seen`, so its own label will not re-fire. Fine: what unblocks it is the **lower** PR getting labeled, which does fire, and step 4's re-evaluation picks up both in numeric order.
400
369
 
401
- On an event, do not merge that PR on sight — **re-run selection from the top**, hold rule included. Report each outcome and leave the monitor armed. One watch per session; stop it with `proc://<id>/kill`.
370
+ On an event, do not merge that PR on sight — **re-run selection from the top**. Report each outcome and leave the monitor armed. One watch per session; stop it with `proc://<id>/kill`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.136.14",
3
+ "version": "3.137.0",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
package/scripts/arg.mjs CHANGED
@@ -262,21 +262,17 @@ export function makeHas(die) {
262
262
  // ci-state.mjs alone, and the identical shape stayed live in its siblings.
263
263
  // Measured on the pre-fix tree against a stub `gh` that ANSWERS, the way a
264
264
  // real one does for a branch ref: `diff-stats.mjs --pr abc` reached
265
- // `gh pr view abc` and printed `{"pr":null,…}` at exit 0, and
266
- // `pr-overlap.mjs --a abc --b def` printed `{"a":null,"b":null,…}` at exit 0
267
- // under a real `signal: "files"` verdict. Each payload's only identifying
268
- // field was built with `Number()`, and `JSON.stringify(NaN)` is `null` — a
269
- // report that cannot be attributed to the PR it answered for, at the exit code
270
- // the fleet gates on. `gh pr view` resolves a non-numeric ref as a BRANCH, so
271
- // the answer underneath was genuine and about a different PR.
272
- //
273
- // The class is NOT bounded by the `arg("pr")` spelling — pr-overlap.mjs reads
274
- // `--a`/`--b` — so it is enumerated by SHAPE: an argument checked for
275
- // truthiness alone, then handed to `gh` as a ref AND to `Number()` in a
276
- // payload field. Its members are ci-state.mjs, diff-stats.mjs and
277
- // pr-overlap.mjs, and all three now route through numArg() below. A sweep for
278
- // the flag NAME finds two of the three, which is how the third stayed open
279
- // through that first fix's review.
265
+ // `gh pr view abc` and printed `{"pr":null,…}` at exit 0. The payload's only
266
+ // identifying field was built with `Number()`, and `JSON.stringify(NaN)` is
267
+ // `null` — a report that cannot be attributed to the PR it answered for, at
268
+ // the exit code the fleet gates on. `gh pr view` resolves a non-numeric ref as
269
+ // a BRANCH, so the answer underneath was genuine and about a different PR.
270
+ //
271
+ // The class is NOT bounded by the `arg("pr")` spelling — a script may take its
272
+ // PR under any flag name — so it is enumerated by SHAPE: an argument checked
273
+ // for truthiness alone, then handed to `gh` as a ref AND to `Number()` in a
274
+ // payload field. Every member routes through numArg() below. A sweep for the
275
+ // flag NAME misses a member that spells its flag otherwise.
280
276
  //
281
277
  // Stated here rather than a third time at the call sites, because the
282
278
  // invariant had no single expression: ci-state.mjs spelled it `/^[0-9]+$/`
@@ -326,9 +322,9 @@ export function isDigits(value) {
326
322
  // specific wording wins — the same ordering rule sweep() states below.
327
323
  //
328
324
  // Absent returns null and is never refused here. That half does not decompose:
329
- // pr-overlap.mjs's usage line names `--a` and `--b` at once, so its absent
330
- // case has no per-flag wording to give. So only the MALFORMED refusal travels,
331
- // and it is flag-named because all three callers mean one thing by it, while
325
+ // a usage line that names several flags at once has no per-flag wording to
326
+ // give an absent one. So only the MALFORMED refusal travels, and it is
327
+ // flag-named because every caller means one thing by it, while
332
328
  // each caller keeps its own absent refusal above its own usage text — the
333
329
  // header's "what travels is the RULE, never the refusal text", applied to a
334
330
  // product whose two refusals genuinely differ in that respect.
@@ -259,8 +259,8 @@ const saw = (obj, key) => {
259
259
  // belongs to.
260
260
  //
261
261
  // The rule itself lives in arg.mjs's numArg(), because the identical
262
- // shape was still live in diff-stats.mjs and pr-overlap.mjs and a fourth
263
- // spelling of it here is what the fix had to stop. What stays this file's own
262
+ // shape was still live in this file's siblings and another spelling of it
263
+ // here is what the fix had to stop. What stays this file's own
264
264
  // is the usage line below — absent and malformed are different mistakes, and
265
265
  // numArg() refuses only the second.
266
266
  //
@@ -28,7 +28,7 @@
28
28
  // not off the card's own row — a ticket retried under a new PR has that PR's
29
29
  // tokens on another row. A fallback `#M` row for a PR a ticket row's latest
30
30
  // attempt claims is that card's other half and renders no card of its own:
31
- // its row-level signals (`ledger-error`, held-behind, the cause words, a live
31
+ // its row-level signals (`ledger-error`, the cause words, a live
32
32
  // member) are the claiming card's.
33
33
  // fleet-tick.mjs's I/O and main() never run here, main() being guarded on
34
34
  // argv[1].
@@ -43,7 +43,7 @@ import { implementerCell, modelsEqual } from "./tier-roles.mjs";
43
43
 
44
44
  // A ledger row is freeform, controller-authored text. Two example shapes:
45
45
  // #<n> impl-<n>=PR#<m> → PR#<m> → MERGED 73b356de
46
- // #<n> impl-<n>=PR#<m> → PR#<m> · fix-pr-<m> · ruled:6-applies · held-behind:#<k>
46
+ // #<n> impl-<n>=PR#<m> → PR#<m> · fix-pr-<m> · ruled:6-applies
47
47
  // Extract by token, never by position — the controller reorders and appends
48
48
  // tokens freely. Unknown text is ignored, never fatal.
49
49
  //
@@ -140,7 +140,6 @@ export function parseRow(row) {
140
140
  if (!issueM) return null;
141
141
  const ticket = Number(issueM[1]);
142
142
  const mergedM = row.match(/\bMERGED\s+([0-9a-f]{7,40})\b/i);
143
- const heldM = row.match(/\bheld-behind[:\s]+#?(\d+)\b/i);
144
143
  const causes = [];
145
144
  for (const t of ["KILLED", "BLOCKED", "SHA-OFF-BRANCH"]) {
146
145
  if (new RegExp(`\\b${t}\\b`).test(row)) causes.push(t.toLowerCase());
@@ -228,7 +227,6 @@ export function parseRow(row) {
228
227
  pr,
229
228
  merged: !!mergedM,
230
229
  sha: mergedM ? mergedM[1] : null,
231
- heldBehind: heldM ? Number(heldM[1]) : null,
232
230
  causes,
233
231
  malformed,
234
232
  };
@@ -278,7 +276,6 @@ export function deriveFlags(parsed, ctx) {
278
276
  const flags = [];
279
277
  if (parsed.malformed) flags.push("ledger-error");
280
278
  if (ctx.ci === "red") flags.push("red-ci");
281
- if (parsed.heldBehind != null) flags.push(`held-behind:#${parsed.heldBehind}`);
282
279
  for (const c of parsed.causes) flags.push(c); // killed | blocked | sha-off-branch
283
280
  const o = parsed.implOutcome;
284
281
  if ((o === "killed" || o === "tier-mismatch" || o === "blocked") && !flags.includes(o)) flags.push(o);
@@ -515,10 +512,7 @@ const FLAG_SEVERITY = {
515
512
  };
516
513
  function severity(flags) {
517
514
  let s = 0;
518
- for (const f of flags) {
519
- if (f.startsWith("held-behind")) s = Math.max(s, 2);
520
- else s = Math.max(s, FLAG_SEVERITY[f] ?? 0);
521
- }
515
+ for (const f of flags) s = Math.max(s, FLAG_SEVERITY[f] ?? 0);
522
516
  return s;
523
517
  }
524
518
 
@@ -697,7 +691,6 @@ export function computeBoard(inputs) {
697
691
  const claimer = p.impl === null && p.pr === p.issue ? claimedBy.get(p.pr) : undefined;
698
692
  if (claimer === undefined) { cards.push(p); continue; }
699
693
  claimer.malformed ||= p.malformed;
700
- claimer.heldBehind ??= p.heldBehind;
701
694
  for (const c of p.causes) if (!claimer.causes.includes(c)) claimer.causes.push(c);
702
695
  claimer.agent = p.agent ?? claimer.agent;
703
696
  claimer.merged ||= p.merged;
@@ -41,25 +41,12 @@ export const isTestDir = (p) => /(^|\/)(__tests__|tests?|e2e|__mocks__)\//i.test
41
41
  // suffix is a naming heuristic: it also claims a production component named like
42
42
  // `ABTest.tsx`, which is the accepted cost of recognising `FooTest.java` without
43
43
  // naming a language.
44
- //
45
- // Each shape captures the basename with its affix and extension removed, so
46
- // `testSubject` names what the test is about from the same patterns this
47
- // predicate judges by: `foo.test.ts`, `foo_test.go`, `test_foo.py` and
48
- // `foo.spec.rb` give `foo`, and `FooTest.java` gives `Foo`. The first shape
49
- // that matches decides. `null` means no test name.
50
44
  const TEST_NAME_SHAPES = [
51
- /(?:^|\/)([^/]*)[._](?:test|spec)\.[^/.]+$/i,
52
- /(?:^|\/)test_([^/]*?)(?:\.[^/.]+)?$/i,
53
- /(?:^|\/)([^/]*[A-Za-z0-9])Tests?\.[^/.]+$/,
45
+ /(?:^|\/)[^/]*[._](?:test|spec)\.[^/.]+$/i,
46
+ /(?:^|\/)test_[^/]*$/i,
47
+ /(?:^|\/)[^/]*[A-Za-z0-9]Tests?\.[^/.]+$/,
54
48
  ];
55
- export const testSubject = (p) => {
56
- for (const shape of TEST_NAME_SHAPES) {
57
- const m = shape.exec(p);
58
- if (m) return m[1];
59
- }
60
- return null;
61
- };
62
- export const isTestName = (p) => testSubject(p) !== null;
49
+ const isTestName = (p) => TEST_NAME_SHAPES.some((shape) => shape.test(p));
63
50
 
64
51
  // Only a prose or config extension, or a conventional name, makes a file docs or
65
52
  // config — which those already do anywhere, so neither `docs/` nor `.github/` has
@@ -70,7 +57,7 @@ export const isTestName = (p) => testSubject(p) !== null;
70
57
  // claims a non-JS module named like `app.config.py`.
71
58
  export const isDocs = (p) => /\.(md|mdx|markdown|txt|rst|adoc)$/i.test(p) || /(^|\/)(README|CHANGELOG|LICENSE|CONTRIBUTING)(\.|$)/i.test(p);
72
59
  export const isMarkdown = (p) => /\.(md|markdown)$/i.test(p);
73
- export const isConfig = (p) =>
60
+ const isConfig = (p) =>
74
61
  /\.(ya?ml|toml|ini|cfg|conf|json|json5|lock|env)$/i.test(p) ||
75
62
  /\.config\.[^/.]+$/i.test(p) ||
76
63
  /(^|\/)\.[a-z]+rc$/i.test(p);
@@ -223,7 +210,7 @@ function main() {
223
210
  // came back empty gets a refusal here, never the cwd fallback an empty `-R ""`
224
211
  // would be.
225
212
  const repo = arg("repo");
226
- // The misspelled-flag sweep, weaker here for the same reason as pr-overlap.mjs: `--pr` is
213
+ // The misspelled-flag sweep, the weaker half of the fix here: `--pr` is
227
214
  // required, so a misspelled `--prr 5` already fell through to the usage die
228
215
  // above. What was silently ignored at exit 0 is a stray riding along with a
229
216
  // good `--pr` (`--pr 5 --base main`), and that is what this closes.
@@ -74,9 +74,7 @@
74
74
  // carries it.
75
75
  // A settle that refuses on `ready-to-merge` — missing from the PR or from the read-back — is the case the tick's `DISPATCH finisher PR#<M>` catches next: settle it `ledger.mjs settle finisher-pr-<M>=labelled` as reported, and `ledger.mjs filed <N> "<subject>"` for each `unrecorded` entry.
76
76
  // merge-bot-report <merge-bot-n>
77
- // `ledger.mjs token <pr> held-behind:#<behind>` for each `held[]` entry
78
- // of the report the PR's rows do not already carry, then `ledger.mjs
79
- // token <pr> parked=<head>:<body digest>:<reason>` for each `refused[]`
77
+ // `ledger.mjs token <pr> parked=<head>:<body digest>:<reason>` for each `refused[]`
80
78
  // entry whose reason is `main-gain-removed:<path>`, bound to the head
81
79
  // and body digest the bot's gate reading `<scratch>/pr<pr>/<merge-bot-n>/ci.json`
82
80
  // records it refused, unless the rows already carry it (a reading that
@@ -84,7 +82,6 @@
84
82
  // `settle --from-report`.
85
83
  // Every other refusal reason writes nothing. The reap and the reclaim
86
84
  // run under the tick's `--apply`.
87
- // The verdict moves no label and leaves nothing in the repo, so the row is the only place the tick can read a `held-behind` from.
88
85
  // The reap and the reclaim run once for every merge bot settled `done`, always, even when the pass merged nothing, and again on the next tick after an `APPLY FAILED` line, and on every tick while this run has no controller record to remember the pass by.
89
86
  // The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in the same pass, before reporting: a token the bot wrote in that pass, never one `reap.sh` writes.
90
87
  // review-result <pr> <path>
@@ -670,16 +667,6 @@ function finisherReport(ev, member) {
670
667
 
671
668
  function mergeBotReport(ev, member) {
672
669
  const read = ev.report(member);
673
- for (const { pr, behind } of read.state === "ok" ? read.report.held : []) {
674
- const tok = `held-behind:#${behind}`;
675
- if (prWords(ev.ledger, pr).includes(tok)) {
676
- ev.note(`#${pr} already ${tok}`);
677
- continue;
678
- }
679
- const r = node("ledger.mjs", ["token", String(pr), tok]);
680
- if (r.status === 0) ev.note(`#${pr} ${tok}`);
681
- else ev.refuse(`token #${pr} ${tok}`, r);
682
- }
683
670
  for (const { pr, reason } of read.state === "ok" ? read.report.refused : []) {
684
671
  if (PARKS.test(reason)) park(ev, member, pr, reason);
685
672
  }
@@ -28,8 +28,8 @@
28
28
  // it once recorded only that someone was dispatched. Live
29
29
  // implementers, live reviewer units (in-flight `review=` plus
30
30
  // unsettled `fix-pr-`), the merge bot (`## Dispatched`), merge
31
- // holds (`held-behind:#M`, and `conflict-hold:#<pr>`, written by
32
- // the merge bot or by the controller off a `CONFLICT` line),
31
+ // holds (`conflict-hold:#<pr>`, written by the merge bot or by
32
+ // the controller off a `CONFLICT` line),
33
33
  // merge parks (`parked=<head>:<body digest>:<reason>`, written by
34
34
  // `fleet-event.mjs merge-bot-report`), tier mismatches and the
35
35
  // drain marker
@@ -463,10 +463,9 @@ function mergeBot(s) {
463
463
  if (s.mergeBotLive >= 1) return row("AT CAP");
464
464
  if (s.mergeQueue === 0) return row("IDLE OK");
465
465
  // `ready-to-merge` is the author's sign-off and nothing more. A bot
466
- // dispatched against a queue whose candidates are all held — behind a lower
467
- // open PR, or on a conflict merge-bot already refused to force — or parked
468
- // on a refusal only a human edit clears spends a whole member re-deriving a
469
- // verdict already recorded.
466
+ // dispatched against a queue whose candidates are all held — on a conflict
467
+ // merge-bot already refused to force — or parked on a refusal only a human
468
+ // edit clears spends a whole member re-deriving a verdict already recorded.
470
469
  if (s.mergeQueue - s.mergeHeld - parked.length <= 0) {
471
470
  if (parked.length > 0) {
472
471
  return row(`HOLD (parked ${parked.map((p) => `#${p.pr} ${p.reason}`).join(", ")})`, {
@@ -474,8 +473,7 @@ function mergeBot(s) {
474
473
  + (s.mergeHeld > 0 ? `; ${s.mergeHeld} more held` : ""),
475
474
  });
476
475
  }
477
- const why = s.mergeConflictHeld ? "behind a lower PR or on a merge conflict no fix-pr has cleared" : "behind a lower PR";
478
- return row("HOLD", { extra: `every queued candidate is held ${why}` });
476
+ return row("HOLD", { extra: "every queued candidate is held on a merge conflict no fix-pr has cleared" });
479
477
  }
480
478
  return row("DISPATCH merge-bot", { acts: true });
481
479
  }
@@ -591,12 +589,10 @@ export class LedgerError extends Error {}
591
589
  // nothing can tell which review a dispositions verdict answered. Only a ledger
592
590
  // written before the plugin update and read after it can hold one.
593
591
  const REVIEWED_RUNLESS = /^reviewed=[0-9a-fA-F]{7,40}:\d+\/\d+\/\d+$/;
594
- export const HELD = /^held-behind[:-]#?(\d+)$/;
595
592
  // The durable record that a PR conflicts — written onto the held PR's own
596
593
  // row by the merge bot, when its local-rebase fallback hits a conflict it would
597
- // not force, or by the controller off this tick's `CONFLICT` line — and
598
- // spelled like `held-behind` so the two read alike. Distinct from an
599
- // Exclusion, which gates a ticket's claim; this gates a PR's merge.
594
+ // not force, or by the controller off this tick's `CONFLICT` line. Distinct
595
+ // from an Exclusion, which gates a ticket's claim; this gates a PR's merge.
600
596
  export const CONFLICT_HOLD = /^conflict-hold[:-]#?(\d+)$/;
601
597
  // The durable record that a merge bot refused a PR on a main-gain hit — a
602
598
  // refusal only a human edit clears — written onto the PR's own row by
@@ -791,8 +787,8 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
791
787
  // for a member found mismatched after it had already settled some other way
792
788
  // (a live one is settled `tier-mismatch` instead). Neither parses as a member
793
789
  // token nor as `review=`/`reviewed=`, so both always reach this loop's own
794
- // `else` branch below, alongside HELD/CONFLICT_HOLD — one pass over every
795
- // row's tokens covers all four.
790
+ // `else` branch below, alongside CONFLICT_HOLD — one pass over every row's
791
+ // tokens covers them all.
796
792
  // `tier-unverifiable=<member>:no-transcript` is the third: a settled member
797
793
  // with nothing to check, which clears the unchecked hold and nothing else.
798
794
  const verdicts = { ok: new Set(), mismatch: new Set(), unverifiable: new Set() };
@@ -847,7 +843,7 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
847
843
  // CONFLICT line off, since it may be pushing to the branch right now.
848
844
  const st = (pr !== null && byPr.get(pr)) || {
849
845
  inFlight: false, reviewedAny: false, survived: 0, unverified: 0, reviewFixed: false,
850
- fixMembers: new Set(), fixLanded: new Set(), conflictLanded: new Set(), held: [],
846
+ fixMembers: new Set(), fixLanded: new Set(), conflictLanded: new Set(),
851
847
  conflictOpen: false, reviewedHead: null, reviewedRun: null, pastPinHalt: false, dispositions: [], workers: new Set(),
852
848
  finishers: new Set(), parked: [],
853
849
  };
@@ -950,8 +946,6 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
950
946
  if (!lenient) throw new LedgerError(`${where}: '${tok}' is not label-off=<finisher-pr member> — fix the row with \`ledger.mjs row\``);
951
947
  malformed.add(i);
952
948
  } else {
953
- const h = HELD.exec(tok);
954
- if (h) st.held.push(Number(h[1]));
955
949
  // Every park the PR's rows carry: the tick matches each against the
956
950
  // PR's current head and body, so a stale one is never cleared here.
957
951
  const k = PARKED.exec(tok);
@@ -985,8 +979,7 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
985
979
  if (premises !== null) {
986
980
  // An `excluded` row claims its ticket only while its
987
981
  // premise still holds. Lifted here only when EVERY premise is a
988
- // verifiable, now-closed `behind-pr:#M` — the same rule a
989
- // `held-behind` merge hold uses — since a mixed or `behind-issue`
982
+ // verifiable, now-closed `behind-pr:#M`, since a mixed or `behind-issue`
990
983
  // premise needs a live gh probe this pure half cannot make;
991
984
  // unclaimed() covers that case once the refreshed shortlist re-admits
992
985
  // the ticket.
@@ -1106,9 +1099,7 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1106
1099
  const queued = prs.filter(isQueued);
1107
1100
  const asc = (a, b) => a - b;
1108
1101
  const state = (n) => byPr.get(n);
1109
- const heldBehind = (st) => (st?.held ?? []).some((n) => open.has(n));
1110
1102
  const conflictHeld = (st) => st !== undefined && st.conflictOpen;
1111
- const mergeHeldOn = (p) => heldBehind(state(p.number)) || conflictHeld(state(p.number));
1112
1103
  // The latest park on a queued PR whose head and body still match it, or
1113
1104
  // undefined: a new head or an edited body lifts every earlier park.
1114
1105
  const parkOn = (p) => {
@@ -1205,17 +1196,13 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1205
1196
  && (!state(p.number)?.reviewedAny || pastPinDue(state(p.number), p.headRefOid)))
1206
1197
  .map((p) => p.number).sort(asc),
1207
1198
  mergeQueue: queued.length,
1208
- // A `held-behind` hold lifts once its premise PR has left the open list —
1209
- // MERGED or CLOSED, the same lift rule as a `behind-pr` Exclusion. A
1210
- // conflict hold lifts only once a fix-applier after it has SETTLED
1199
+ // A conflict hold lifts only once a fix-applier after it has SETTLED
1211
1200
  // `applied:`/`no-op` — never on dispatch alone.
1212
- mergeHeld: queued.filter(mergeHeldOn).length,
1213
- // How many of those are conflict holds — the HOLD row's wording, no field.
1214
- mergeConflictHeld: queued.filter((p) => conflictHeld(state(p.number))).length,
1201
+ mergeHeld: queued.filter((p) => conflictHeld(state(p.number))).length,
1215
1202
  // Each queued PR no hold counts that a park still matches, `{pr, reason}`
1216
1203
  // ascending: the merge bot would only refuse it again.
1217
1204
  mergeParked: queued.flatMap((p) => {
1218
- const k = mergeHeldOn(p) ? undefined : parkOn(p);
1205
+ const k = conflictHeld(state(p.number)) ? undefined : parkOn(p);
1219
1206
  return k === undefined ? [] : [{ pr: p.number, reason: k.reason }];
1220
1207
  }).sort((a, b) => a.pr - b.pr),
1221
1208
  // Finishers settled `labelled` on an open PR without the label.
@@ -13,7 +13,7 @@
13
13
  //
14
14
  // Rows stay freeform text. Only a token whose name part is a member name is
15
15
  // claimed as a member here; everything else a row carries (`class=routine`,
16
- // `ports=`, `ci=`, `held-behind:#M`, `conflict-hold:#<pr>`, the
16
+ // `ports=`, `ci=`, `conflict-hold:#<pr>`, the
17
17
  // `review=`/`reviewed=` pair, the `→ PR#M` arrow) is not a member. The
18
18
  // review pair has a grammar of its own below, REVIEW and REVIEWED, which
19
19
  // `ledger.mjs review` writes and `ledger.mjs row` checks a write against
@@ -64,7 +64,7 @@ import { makeDie, isFlagLike, hasEqualsForm, isDigits, writeAll } from "./arg.mj
64
64
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
65
65
  import { readReceipt } from "./phase0-receipt.mjs";
66
66
  import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, settledOnLedger, retiredOnLedger, retiredName, readRetired, agentDefinition, expectedDefinition, CELL, POLICY_CELL, tierValues, cellValues, decidingCell, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, HALT_CAUSES, ROWS, DISPATCHED, ROUTED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, BRIEFS, briefsArchiveName, memberRole, parseDispatchedEntry, dispatchedEntry, parseRouting, parseRoutedEntry, routedEntry, headerRe, escapeText, ledgerSection, nextReviewerName, isOmpSessionDirName } from "./ledger-grammar.mjs";
67
- import { deriveRun, LedgerError, labelOffMember, HELD, CONFLICT_HOLD, PARKED } from "./fleet-tick.mjs";
67
+ import { deriveRun, LedgerError, labelOffMember, CONFLICT_HOLD, PARKED } from "./fleet-tick.mjs";
68
68
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
69
69
  import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
70
70
  import { attemptLock, releaseLockFile, reapPathOf } from "./pid-lock.mjs";
@@ -2702,7 +2702,7 @@ function recordFiled(id, subject) {
2702
2702
  // evidence is not empty
2703
2703
  // merge-bot-n=done every merged[].pr reads MERGED; every PR the
2704
2704
  // bot's `## Dispatched` entry records as queued=
2705
- // at dispatch has a verdict in merged, held,
2705
+ // at dispatch has a verdict in merged,
2706
2706
  // conflictHold or refused, or no longer reads
2707
2707
  // OPEN with ready-to-merge
2708
2708
  //
@@ -2951,7 +2951,7 @@ async function runSettleFromReport() {
2951
2951
  for (const pr of unjudged) {
2952
2952
  const v = prView(pr, "state,labels");
2953
2953
  const left = v.state !== "OPEN" || !v.labels.some((l) => l?.name === ready);
2954
- check(`PR #${pr}, queued at dispatch, has a verdict in merged, held, conflictHold or refused, or has left the queue`, left);
2954
+ check(`PR #${pr}, queued at dispatch, has a verdict in merged, conflictHold or refused, or has left the queue`, left);
2955
2955
  }
2956
2956
  for (const { pr, reason } of report.refused) ruledLines.push(`${member} refused #${pr}: ${reason.trim()}`);
2957
2957
  }
@@ -3131,8 +3131,8 @@ function withTier(line, tok) {
3131
3131
  // token is `dispatch`'s or `settle`'s, a review token `review`'s. A word
3132
3132
  // shaped like a member that the grammar cannot parse, a `tier=` that is not
3133
3133
  // a cell, a `tier=` naming a second tier in one call, any `cell=` (the row
3134
- // step's, never a token), a `held-behind`,
3135
- // `conflict-hold` or `parked` token the tick cannot read, and a lone `→` — an
3134
+ // step's, never a token), a `conflict-hold` or `parked` token the tick cannot
3135
+ // read, and a lone `→` — an
3136
3136
  // arrow with no PR beside it points at nothing — are refused. Every other
3137
3137
  // word is a freeform token.
3138
3138
  function tokenRefusal(tok, earlier) {
@@ -3150,10 +3150,8 @@ function tokenRefusal(tok, earlier) {
3150
3150
  if (MEMBER_FAMILIES.some((family) => name.startsWith(`${family}-`))) {
3151
3151
  return "is shaped like a member token this grammar cannot parse — a member is impl-<N>, fix-pr-<M>, finisher-pr-<M> or merge-bot-<n>, a retry suffix allowed";
3152
3152
  }
3153
- for (const [prefix, shape] of [["held-behind", HELD], ["conflict-hold", CONFLICT_HOLD]]) {
3154
- if (tok.startsWith(prefix) && !shape.test(tok)) {
3155
- return `is not ${prefix}:#<M> — the tick reads only ${prefix}:#<number> and would ignore this one`;
3156
- }
3153
+ if (tok.startsWith("conflict-hold") && !CONFLICT_HOLD.test(tok)) {
3154
+ return "is not conflict-hold:#<M> — the tick reads only conflict-hold:#<number> and would ignore this one";
3157
3155
  }
3158
3156
  if (tok.startsWith("parked=") && !PARKED.test(tok)) {
3159
3157
  return "is not parked=<head>:<body digest>:main-gain-removed:<path> — the tick reads only a 40-hex head, a 12-hex body digest and a main-gain-removed reason, and would ignore this one";
package/scripts/pull.mjs CHANGED
@@ -872,7 +872,7 @@ class Pull {
872
872
  const d = this.gh("collision", ["pr", "diff", String(pr), "--name-only"]);
873
873
  const common = shared(d.stdout, "\n");
874
874
  if (d.status !== 0) unread.push(`gh pr diff ${pr} (${failure(d)})`);
875
- // Fail closed, as pr-overlap.mjs does: a PR with no changed file is a query that did not work, never "no overlap".
875
+ // Fail closed: a PR with no changed file is a query that did not work, never "no overlap".
876
876
  else if (d.stdout === "") unread.push(`gh pr diff ${pr} (printed no file)`);
877
877
  else if (common.paths.length > 0) {
878
878
  for (const f of common.files) sharedFiles.add(f);
@@ -9,15 +9,22 @@
9
9
  // reclaim-scratch.mjs --siblings --root <abs> [--apply]
10
10
  //
11
11
  // Dry run by default; `--apply` removes. `--root` is required, an absolute
12
- // path to an existing directory: the controller passes the path
13
- // scratch-root.mjs prints.
12
+ // path to an existing directory, and the root sweep and `--siblings` require
13
+ // it to be this workspace's own scratch root (the path scratch-root.mjs
14
+ // prints, computed from the cwd): the controller passes that path. Both
15
+ // refuse any other, dry run included, before reading anything under it;
16
+ // `--pr` mode reads no ledger and asks GitHub nothing, and does not check it.
14
17
  //
15
- // `--siblings` is the sibling pass, its own invocation: `--root` names the live
16
- // key, which must be this workspace's own scratch root (the path
17
- // scratch-root.mjs prints), and the pass judges the other key-shaped
18
- // directories beside it by age alone (judgeSiblings below), judging each again
19
- // just before `--apply` removes it. It reads no ledger and is never combined
20
- // with --pr or --after-rotate.
18
+ // The root sweep reads the ledger, the claim worktrees and GitHub of the
19
+ // repository the cwd is in, so another workspace's key judged there would be
20
+ // judged against this one's numbers.
21
+ //
22
+ // `--siblings` is the sibling pass, its own invocation: `--root` names the
23
+ // live key, and the pass judges the other key-shaped directories beside it by
24
+ // age alone (judgeSiblings below), judging each again just before `--apply`
25
+ // removes it. Any other key passed as `--root` would put the real live key
26
+ // among the judged siblings. It reads no ledger and is never combined with
27
+ // --pr or --after-rotate.
21
28
  //
22
29
  // THE ROOT SWEEP judges every entry directly under `--root`:
23
30
  // pr<M>/, dispositions-fix-pr-<M>[-x].json
@@ -99,8 +106,10 @@
99
106
  // `removed` naming what --apply would remove.
100
107
  // Exit 0 whenever the receipt is printed, failures included; 2 for a refused
101
108
  // invocation — bad arguments, no --root, a root that is not a directory, a
102
- // root sweep with no ledger and no --after-rotate, a ledger that cannot be
103
- // read for any reason other than ENOENT. Nothing is removed before a refusal.
109
+ // root sweep or sibling pass whose --root is not this workspace's own scratch
110
+ // root or whose own scratch root cannot be resolved, a root sweep with no
111
+ // ledger and no --after-rotate, a ledger that cannot be read for any reason
112
+ // other than ENOENT. Nothing is removed before a refusal.
104
113
 
105
114
  import { spawnSync } from "node:child_process";
106
115
  import { lstatSync, readdirSync, realpathSync, statSync } from "node:fs";
@@ -539,15 +548,21 @@ function main() {
539
548
  if (siblings) {
540
549
  if (pr !== null) die("--siblings and --pr are separate passes");
541
550
  if (afterRotate) die("--after-rotate is the root sweep's; --siblings reads no ledger");
542
- // The live key is never judged, so it must be this workspace's own: any other
543
- // key passed here would put the real live key among the judged siblings.
551
+ }
552
+ if (pr === null) {
553
+ // Only this workspace's own scratch root: the header says why, per pass.
554
+ const [judges, why] = siblings
555
+ ? ["--siblings judges the keys beside", "--siblings judges the keys beside the live one"]
556
+ : ["the root sweep judges", "the root sweep judges entries against this workspace's ledger, worktrees and GitHub repository"];
544
557
  let own;
545
558
  try {
546
559
  own = scratchRoot();
547
560
  } catch (e) {
548
- die(`--siblings judges the keys beside this workspace's scratch root, which could not be resolved: ${e.message}`);
561
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
562
+ die(`${judges} this workspace's scratch root, which could not be resolved: ${e.message}`);
549
563
  }
550
- if (root !== own) die(`--siblings judges the keys beside the live one: --root must be this workspace's scratch root ${own}, got ${root}`);
564
+ if (!isAbsolute(own)) die(`${judges} this workspace's scratch root, which could not be resolved: ${own} is not absolute, so HOME is empty or relative`);
565
+ if (root !== own) die(`${why}: --root must be this workspace's scratch root ${own}, got ${root}`);
551
566
  }
552
567
 
553
568
  const now = Date.now();
@@ -168,7 +168,6 @@ export const SCHEMAS = {
168
168
  "merge-bot": report({
169
169
  member: str,
170
170
  merged: listOf({ pr: id, sha }),
171
- held: listOf({ pr: id, behind: id }),
172
171
  conflictHold: { type: "array", items: id },
173
172
  // A refusal is a verdict only with a reason: the reason is the record
174
173
  // `## Ruled` gets, so one with no text but whitespace is invalid.
@@ -178,12 +177,12 @@ export const SCHEMAS = {
178
177
  };
179
178
 
180
179
  // Every verdict a merge-bot report gives, as `{pr, path}`, `path` the entry's
181
- // PR field: `merged`, `held`, `conflictHold`, then `refused`, each in report
182
- // order. `branchKept` gives none: it names a merged PR's branch and the open
183
- // PR keeping it.
180
+ // PR field: `merged`, `conflictHold`, then `refused`, each in report order.
181
+ // `branchKept` gives none: it names a merged PR's branch and the open PR
182
+ // keeping it.
184
183
  export function mergeBotVerdicts(report) {
185
184
  return [
186
- ...["merged", "held"].flatMap((k) => report[k].map((e, i) => ({ pr: e.pr, path: `$.${k}[${i}].pr` }))),
185
+ ...report.merged.map((e, i) => ({ pr: e.pr, path: `$.merged[${i}].pr` })),
187
186
  ...report.conflictHold.map((pr, i) => ({ pr, path: `$.conflictHold[${i}]` })),
188
187
  ...report.refused.map((e, i) => ({ pr: e.pr, path: `$.refused[${i}].pr` })),
189
188
  ];
@@ -198,7 +197,7 @@ export function mergeBotVerdicts(report) {
198
197
  // settle checks. For a fix-pr report: an `applied` outcome names its
199
198
  // `testRun`, the run behind the commit, and a `refuted` deferral, under any
200
199
  // outcome, names the `dispositionsRecord` settle reads its reason from. For a
201
- // merge-bot report: each PR gets one verdict — merged, held, conflict-held or
200
+ // merge-bot report: each PR gets one verdict — merged, conflict-held or
202
201
  // refused — the last it reached in the pass, so a PR named twice, in one list
203
202
  // or in two, is a violation at its second entry.
204
203
  export function reportViolation(family, value) {
@@ -805,7 +805,6 @@ Match the failure to its row in the table below and run that response; where the
805
805
  | Implementer blocked or ambiguous *mid-implementation* | Free the slot. A `blocked` report settles on the **Implementer report** wake, no label moved; with no report, `ledger.mjs settle impl-<N> blocked`, its Ending still `hollow`. Leave `in-progress`, report — the ticket is not In flight and waits for a human; its `NEED derive-recipe` is phase 0's mid-run trigger |
806
806
  | `review-pr` workflow throws or returns no tree | Retry once under the next letter (`review-pr-<pr#>-b`); still failing, report and leave the PR at review-due. Never enqueue the PR as reviewed — the workflow is not a member, so no other row here covers it |
807
807
  | Reviewer, fix-applier or red-check fixer cannot reach green | Report, leave the PR unlabeled, free the slot — the last two settle `failed`; a wake's `NEED derive-recipe` is phase 0's mid-run trigger |
808
- | Merge bot hits the hold rule | Report `held-behind-#<lower>`, PR stays queued |
809
808
  | Merge bot finds the worktree ahead of the PR head **on the local-rebase fallback** | `worktree-diverged-#<pr>`, PR stays queued. Read the stray commit; push-or-discard is yours, and the maintainer's if the evidence cannot settle it |
810
809
  | Merge bot finds the head moved after `ready-to-merge` was applied | The label binds to the head's net change, not to one SHA: a proven rebase-carry keeps the label — the bot proceeds and reports `rebase-carry-#<pr>` with the labelled and accepted SHAs, and nothing is dispatched. Any other move is `head-moved-after-label-#<pr>`, PR stays queued, label untouched. Dispatch a **fresh** finisher against the new head — the first audit verified a different tree |
811
810
  | Merge bot cannot resolve a rebase safely | Stop that PR, report, continue. On a conflict the bot has already appended `conflict-hold:#<pr>` to the PR's row; the tick prints `DISPATCH fix-pr PR#<pr>` and holds the merge until that fix-applier settles. A PR that conflicts before any bot reaches it is the tick's `CONFLICT PR#<pr>` line, whose hold you record |
@@ -68,7 +68,7 @@ One line per ticket, rewritten in place (`ledger.mjs row <ticket> <text>`; `ledg
68
68
 
69
69
  ```
70
70
  #<t1> impl-<t1>=PR#<p1> → PR#<p1> → MERGED 73b356de
71
- #<t2> impl-<t2>=PR#<p2> → PR#<p2> · fix-pr-<p2> · ports=16<t2> · ruled:6-applies · held-behind:#<t3>
71
+ #<t2> impl-<t2>=PR#<p2> → PR#<p2> · fix-pr-<p2> · ports=16<t2> · ruled:6-applies
72
72
  #<t3> impl-<t3> · tier=task-high
73
73
  #<t4> excluded · behind-pr:#<p2>
74
74
  #<t5> excluded · behind-issue:#<t3>
@@ -80,7 +80,7 @@ A row's cell is its `tier=` (the cell a draw picked), else its `cell=` (the cell
80
80
 
81
81
  A member that dies between spawn and write is invisible — and members die in batches.
82
82
 
83
- `dispatch merge-bot` also records the queue the bot is dispatched against: its `## Dispatched` entry carries `queued=<pr>,<pr>…` (`queued=none` for an empty queue), the open `ready-to-merge` PRs gh lists at that moment. A gh that cannot answer refuses the dispatch, nothing written. `settle merge-bot-<n> --from-report` judges the bot's report against that queue, not against anything the report names: a PR from it that is still open and carries the label, with no verdict in `merged`, `held`, `conflictHold` or `refused`, fails the settle at exit 3, naming the PR, and an entry without `queued=` cannot be judged (exit 2) — settle that bot by hand.
83
+ `dispatch merge-bot` also records the queue the bot is dispatched against: its `## Dispatched` entry carries `queued=<pr>,<pr>…` (`queued=none` for an empty queue), the open `ready-to-merge` PRs gh lists at that moment. A gh that cannot answer refuses the dispatch, nothing written. `settle merge-bot-<n> --from-report` judges the bot's report against that queue, not against anything the report names: a PR from it that is still open and carries the label, with no verdict in `merged`, `conflictHold` or `refused`, fails the settle at exit 3, naming the PR, and an entry without `queued=` cannot be judged (exit 2) — settle that bot by hand.
84
84
 
85
85
  `dispatch impl-<N>` also records the definition it prints: the implementer's `## Dispatched` entry ends with `agent=<definition>` (`agent=fleet-implementer-<cell>`), and `ledger.mjs read` prints it under `agents`, by member name. tier-check judges the implementer against that record, falling back to the row's `tier=` (else `cell=`) for an entry without one, so a `tier=` replaced after the implementer settled does not change what it is judged against. `settle` and `rotate` keep the word with its entry. A value that is not `[a-z0-9]` words joined by `-` makes the entry malformed, and the ledger is refused.
86
86
 
@@ -96,9 +96,9 @@ A member that dies between spawn and write is invisible — and members die in b
96
96
 
97
97
  `label-off=<finisher-pr-M[-x]>` is written before you take `ready-to-merge` off PR M on purpose (taking it off before you approve a push, or clearing one left on a moved head), naming that PR's latest finisher attempt: the tick reads a missing label as a finisher's miss only after the last attempt a `label-off=` names, so without it your own removal reads as one.
98
98
 
99
- `ci=<run-id>:<attempt>:<conclusion>` and `held-behind:#<lower>` are row tokens the same way, and so is `conflict-hold:#<pr>` — written by the merge bot itself (`run-merge-bot.md` step 1), or by you off the tick's `CONFLICT` line, naming the row's own PR. It is not an Exclusion: that gates a ticket's claim, this a PR's merge.
99
+ `ci=<run-id>:<attempt>:<conclusion>` is a row token the same way, and so is `conflict-hold:#<pr>` — written by the merge bot itself (`run-merge-bot.md` step 1), or by you off the tick's `CONFLICT` line, naming the row's own PR. It is not an Exclusion: that gates a ticket's claim, this a PR's merge.
100
100
 
101
- `parked=<head>:<body digest>:main-gain-removed:<path>` is a row token too, written by `fleet-event.mjs merge-bot-report` off a merge bot's `main-gain-removed` refusal, binding the head and a digest of the body the bot's gate refused, read from its gate reading `<scratch>/pr<N>/merge-bot-<n>/ci.json`: while both still match, the tick counts the PR parked beside the held ones, so it alone never prints `DISPATCH merge-bot`, and a new head or an edited body lifts it with no write. No other refusal reason parks.
101
+ `parked=<head>:<body digest>:main-gain-removed:<path>` is a row token too, written by `fleet-event.mjs merge-bot-report` off a merge bot's `main-gain-removed` refusal, binding the head and a digest of the body the bot's gate refused, read from its gate reading `<scratch>/pr<N>/merge-bot-<n>/ci.json`: while both still match, the tick counts the PR parked beside the conflict-held ones, so it alone never prints `DISPATCH merge-bot`, and a new head or an edited body lifts it with no write. No other refusal reason parks.
102
102
 
103
103
  PR stays queued, label untouched, and no member is dispatched to restore the lines — the removal may be deliberate. A hit line's `kind` is `modified` when its hunk also adds lines, `deleted` when it only removes lines; a gained line cleared by in-place pairing, a token-keeping re-wrap of its hunk or the retraction of a forward reference to a ticket the PR closes is in `mainGain.edited[]` with its `rule`, not a hit. The `ruled` record the main-gain-hit row restores an acknowledgement from lasts only the run that wrote it — `ledger.mjs rotate` carries no `ruled` line into the next ledger — so a later run puts the question again.
104
104
 
@@ -233,8 +233,7 @@ terminating in exactly one dispatch or an empty shortlist:
233
233
  ticket does not collide, whatever files it shares. A target file the brief
234
234
  does not spell as a path → `paths <p>…`, which scans again and asks again. A
235
235
  PR the scan could not read is still yours to judge, and `behind-pr` on it is
236
- taken. `pr-overlap.mjs` is **PR-vs-PR only** — it runs `gh pr diff` on both
237
- args and errors on an issue number, so never run it on a ticket here.
236
+ taken.
238
237
  5. **Sequence check** — the `#N` refs of the brief's `Out of scope` section are
239
238
  printed beside Q3 as the candidates: one naming an open ticket this one
240
239
  sequences after → `behind-issue:#M`. No overlap and no such ticket →
@@ -104,7 +104,7 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
104
104
  unchecked tier, the In-flight bound reached (`HOLD (in-flight <n>/<B>)` —
105
105
  nothing to do unless its detail names a replacement to dispatch, else a
106
106
  merge brings n below B), or every
107
- queued merge candidate held behind a lower PR or on a conflict hold no
107
+ queued merge candidate held on a conflict hold no
108
108
  fix-applier has cleared. An unchecked tier is `tick --apply`'s to check, and
109
109
  the hold stays while the check writes no verdict (its `tier-ok=`, or
110
110
  `tier-unverifiable=` for a member settled `killed` or `released` with no
@@ -1,423 +0,0 @@
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 { isConfig, isDocs, testSubject } from "./diff-stats.mjs";
18
- import { makeDie, defineFlags } from "./arg.mjs";
19
-
20
- const NAME = "pr-overlap";
21
-
22
- // die()/numArg() shared with the other fleet scripts — see arg.mjs for the
23
- // fail-open and pipe-safety rationale. `--a`/`--b`
24
- // given trailing already died via the usage guard below — `undefined` is
25
- // falsy — so this file was never a silent-widening site on its own. But `--a`
26
- // given `--b` as its "value" (`pr-overlap.mjs --a --b 5`) was NOT caught that
27
- // way: `a` becomes the string "--b", passes the falsy check, and only failed
28
- // later as a confusing `gh pr diff --b` error — the shared arg() rejects it
29
- // here, by name, instead.
30
- //
31
- // numArg() rather than arg() because the falsy check missed the other half
32
- // too, and this file is why the numArg() fix could not be swept by grepping for
33
- // `arg("pr")`: the same fail-open arrives here under `--a`/`--b`. Measured on
34
- // the pre-fix tree, `--a abc --b def` printed `{"a":null,"b":null,…}` at exit
35
- // 0 carrying a real `signal: "files"` verdict — `gh pr diff` resolves a
36
- // non-numeric ref as a BRANCH, so the overlap underneath was genuine and
37
- // about two PRs nobody named.
38
- const die = makeDie(NAME);
39
- const { numArg, sweep, stray } = defineFlags(die, { flags: { a: "value", b: "value" } });
40
-
41
- // `=== null`, not `!a || !b`: numArg() returns a NUMBER, so `--a 0` — a value
42
- // the caller did give — would otherwise draw the usage line, where gh answers
43
- // it truthfully as no such PR. The usage line stays this file's own and names
44
- // both flags at once, which is exactly why numArg() refuses only the
45
- // MALFORMED half: an absent `--a` has no per-flag wording to give here.
46
- const a = numArg("a");
47
- const b = numArg("b");
48
- if (a === null || b === null) die("usage: pr-overlap.mjs --a <pr> --b <pr>");
49
- // The misspelled-flag sweep, and here it is the WEAKER half of the fix: both
50
- // flags are required, so a misspelling of either (`--aa 5 --b 6`) already
51
- // fell through to the usage die above — refused, just never named. What was
52
- // NOT refused is a stray alongside two good values (`--a 5 --b 6 --quiet`),
53
- // silently ignored at exit 0. The sweep closes that and upgrades the first
54
- // case's message from a usage dump to the offending token. Below the usage
55
- // guard so the usage text still wins where it is the better answer; above
56
- // the first gh call.
57
- sweep();
58
- // sweep() above only refuses a `--`-prefixed token; a bare or
59
- // single-dash one (`--a 5 --b 6 stray`) rode along in silence the same way.
60
- // This file takes no positional, so any leftover token is a stray.
61
- stray();
62
-
63
- function changedFiles(pr) {
64
- console.error(`$ gh pr diff ${pr} --name-only`);
65
- let out;
66
- try {
67
- out = execFileSync("gh", ["pr", "diff", String(pr), "--name-only"], {
68
- encoding: "utf8",
69
- });
70
- } catch (e) {
71
- // Names the cause, never gh's stderr — execFileSync forwarded it already
72
- // (no `stdio` above), so interpolating it emits every byte twice, and this
73
- // is the biggest payload of the fleet scripts. `e.message` is the same
74
- // string, not a fallback: Node builds it as `Command failed:\n<stderr>`.
75
- // Three disjoint shapes — Node-aborted (ENOENT/ENOBUFS), signal, exit.
76
- die(
77
- `gh pr diff ${pr} failed: ${
78
- e.code ?? (e.signal ? `killed by ${e.signal}` : `exit ${e.status}`)
79
- }`,
80
- );
81
- }
82
- const files = out.split("\n").map((s) => s.trim()).filter(Boolean);
83
- // Fail closed: a PR with no changed files is not a legitimate "no overlap"
84
- // answer, it is a query that did not work. Silence must never read as data.
85
- if (files.length === 0) die(`PR ${pr} reported zero changed files — refusing to answer`);
86
- for (const f of files) console.error(` ${f}`);
87
- return files;
88
- }
89
-
90
- const filesA = changedFiles(a);
91
- const filesB = changedFiles(b);
92
-
93
- const intersect = (xs, ys) => {
94
- const set = new Set(ys);
95
- return [...new Set(xs)].filter((v) => set.has(v)).sort();
96
- };
97
-
98
- // A repo mid-migration has src/…/foo.test.ts in one PR and
99
- // tests/unit/…/foo.test.ts in the other: same module, zero shared paths. That
100
- // migration case is what this signal exists for, and it is a test-file notion
101
- // in any language — so only a file whose name has a test shape participates,
102
- // judged by diff-stats.mjs's own patterns, and its module is that name with
103
- // the test affix and extension removed: `foo_test.go`, `test_foo.py` and
104
- // `foo.test.ts` all give `foo`, `FooTest.java` gives `Foo`. Modules compare
105
- // case-sensitively, as `files` compares paths.
106
- //
107
- // A non-test source file never participates, `.ts` included: `types.ts` ×13
108
- // and `index.ts` ×10 live in unrelated subtrees of the proving ground, and
109
- // telling a shared module from a shared stock name would need a list of names.
110
- // Docs and config never participate either, a test-shaped name included
111
- // (`docs/test_plan.md`): matching their basenames produces confident nonsense,
112
- // two PRs each touching their own README.md, or their own hooks.json, reported
113
- // as sharing a "module". Measured in the proving ground: README.md ×8,
114
- // SKILL.md ×6, mcp-snippet.json ×9, hooks.json ×5 across unrelated
115
- // directories. Returning null for those drops them from the signal entirely
116
- // rather than caveating them.
117
- const moduleOf = (f) => (isDocs(f) || isConfig(f) ? null : testSubject(f) || null);
118
- const modulesOf = (fs) => fs.map(moduleOf).filter((m) => m !== null);
119
-
120
- // Repo root is excluded: every top-level file shares it, so it fires on PRs
121
- // with nothing whatsoever in common.
122
- const dirsOf = (fs) => fs.map(dirname).filter((d) => d !== ".");
123
-
124
- // The three signals above compare paths, modules and directories. They
125
- // are structurally blind to a coupling that lives in PROSE — one file naming
126
- // another. The measured case is `docs/metrics/tier-outcomes.tsv`: it is
127
- // append-only, so every fleet run produces a PR touching it, and the
128
- // paragraph that reads it lives in `run-team/SKILL.md`. A PR appending rows
129
- // and a PR rewriting that paragraph edit the same logical section from two
130
- // different files — run-merge-bot.md's own soft signal — and this script
131
- // answered `signal=none` on exactly that pair of PRs. The clearest
132
- // output the tool has was the one that missed it, which is the dangerous
133
- // direction: `none` licenses a merge.
134
- //
135
- // Derived from the two diffs rather than declared in a `data file → its prose
136
- // consumers` table, because the table was already stale before it could be
137
- // written. The ticket asking for this signal recorded ONE consumer of
138
- // `tier-outcomes` (measured at `e540e16`); at `ffa9026` there are eleven,
139
- // among them `member-record.mjs`, four prose-pin test guards, three specs
140
- // and run-team's own SKILL.md. A map seeded from that ticket would have
141
- // shipped wrong on day one, which is exactly the rot the ticket predicted
142
- // of it.
143
-
144
- // Which files can be CITED, and which can carry a citation. Two explicit
145
- // extension lists, deliberately narrow and deliberately not a file table:
146
- // that ticket's own objection to deriving this signal is "a broad net and
147
- // likely false positives", so the net is bounded and its bounds are printed
148
- // with the verdict. An extension on neither list does not participate at all.
149
- //
150
- // Data side — an artifact whose meaning lives in prose somewhere else. A
151
- // `.ts` module's consumers are already found by `files` above. `.md`
152
- // is deliberately absent: a doc citing a doc is what `dirs` fires on, and
153
- // `SKILL.md` recurs 3× in this repo's 251 tracked files (measured), so it is
154
- // the ambiguous-basename shape `moduleOf` above already refuses to guess at.
155
- const DATA_EXT = new Set([".tsv", ".csv", ".json", ".jsonl", ".ndjson", ".yml", ".yaml", ".toml"]);
156
- // Text side — prose, including prose inside a code comment. That half is not
157
- // hypothetical: run-team/SKILL.md's review section records five production
158
- // PRs whose whole substance was a comment in a `.js`/`.mjs`/`.sh` file.
159
- //
160
- // Disjoint from DATA_EXT on purpose. Adding an extension to both would let a
161
- // file match its own hunks and fire against itself; keep them apart.
162
- const TEXT_EXT = new Set([".md", ".mjs", ".js", ".cjs", ".ts", ".tsx", ".sh", ".bash", ".zsh", ".py", ".txt", ".rst"]);
163
- // Asserted at startup, not only in this comment: an overlapping extension
164
- // would let a file match its own hunks and fire against itself, silently,
165
- // on whichever PR happens to touch it.
166
- for (const ext of DATA_EXT) {
167
- if (TEXT_EXT.has(ext)) throw new Error(`${NAME}: DATA_EXT and TEXT_EXT both claim ${ext}`);
168
- }
169
-
170
- const dataFiles = (fs) => fs.filter((f) => DATA_EXT.has(extname(f)));
171
- const textFiles = (fs) => fs.filter((f) => TEXT_EXT.has(extname(f)));
172
-
173
- // A bare basename is usable only when it names ONE file. This is `moduleOf`'s
174
- // measurement one file type over — `types.ts` ×13 and `index.ts` ×10 in the
175
- // proving ground, `README.md` ×8, `hooks.json` ×5 — and the same answer: a
176
- // shared name is not a shared file, so drop it rather than caveat it. Counted
177
- // off the tree instead of listed here, so a data file added tomorrow is
178
- // covered the day it lands and there is nothing to keep up to date.
179
- //
180
- // `null` means the count could not be taken, which is NOT the same as "no
181
- // ambiguity": it narrows matching to full paths and is reported.
182
- let basenameCounts;
183
- let trackedPaths;
184
- let basenameCountsUnrun;
185
- function trackedBasenameCounts() {
186
- if (basenameCounts !== undefined) return basenameCounts;
187
- console.error(`$ git ls-files -z`);
188
- try {
189
- // -z: a basename count must not be wrong about a path git would otherwise
190
- // quote. maxBuffer explicitly, for the reason diffOf() states below.
191
- //
192
- // GIT_DIR/GIT_WORK_TREE scrubbed (gitEnv()): measured, an ambient
193
- // GIT_DIR answers for a DIFFERENT repository regardless of `cwd`,
194
- // silently, at exit 0 — the count this guard's verdict is based on then
195
- // comes from whichever repository the ambient variable names, and a
196
- // basename genuinely unique in the caller's own tree reads as ambiguous
197
- // (or the reverse), dropping — or wrongly keeping — a citation's bare
198
- // basename token below.
199
- const out = execFileSync("git", ["ls-files", "-z"], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, env: gitEnv() });
200
- const counts = new Map();
201
- const paths = new Set();
202
- for (const f of out.split("\0")) {
203
- if (!f) continue;
204
- paths.add(f);
205
- const b = basename(f);
206
- counts.set(b, (counts.get(b) ?? 0) + 1);
207
- }
208
- basenameCounts = counts;
209
- trackedPaths = paths;
210
- } catch (e) {
211
- // Same three disjoint shapes changedFiles() and diffOf() name: a git
212
- // failure with no captured reason is indistinguishable from a clean scan
213
- // in unrunReasons, which is the missed-pair failure mode above one level in.
214
- basenameCounts = null;
215
- trackedPaths = null;
216
- basenameCountsUnrun = `git ls-files failed: ${
217
- e.code ?? (e.signal ? `killed by ${e.signal}` : `exit ${e.status}`)
218
- } — basenames unusable, full paths only`;
219
- }
220
- return basenameCounts;
221
- }
222
-
223
- // A citation names a file, and naming a file means naming its path or at
224
- // least its extension. Measured on the case this signal exists for: every one
225
- // of run-team/SKILL.md's nine references to the TSV is written
226
- // `docs/metrics/tier-outcomes.tsv` (×7) or `tier-outcomes.tsv` (×2). A bare
227
- // stem (`tier-outcomes`) is never matched — without an extension it is a word
228
- // rather than a reference, and that is where the false positives live.
229
- function tokensFor(dataFile) {
230
- const tokens = [dataFile];
231
- const bn = basename(dataFile);
232
- if (bn === dataFile) return tokens;
233
- const counts = trackedBasenameCounts();
234
- if (counts === null) return tokens;
235
- // Count OTHER owners of the basename: subtract dataFile itself when the
236
- // pre-PR index already tracks it, so a file the PR merely modifies is not
237
- // counted as its own rival, and a file the PR ADDS is compared against the
238
- // full pre-PR set instead of getting a free pass because it isn't in it.
239
- const others = (counts.get(bn) ?? 0) - (trackedPaths.has(dataFile) ? 1 : 0);
240
- if (others === 0) tokens.push(bn);
241
- return tokens;
242
- }
243
-
244
- // The whole patch, not `--name-only`. The question is not whether the citing
245
- // file names the data file SOMEWHERE — run-team/SKILL.md always does, in nine
246
- // places, so a whole-file read fires on every PR that touches it at all,
247
- // permanently. The question is whether THIS PR is editing the part that names
248
- // it. One PR of the measured pair touched SKILL.md and scored zero against
249
- // those tokens in its own diff, which is how merge-bot-9 cleared the pair by
250
- // hand; grepping the diff is that measurement, kept and automated.
251
- //
252
- // Context lines count along with added and removed ones, deliberately: prose
253
- // being rewritten NEXT TO a citation is the hazard, and merge-bot-9's own
254
- // clearing grep counted context too.
255
- function diffOf(pr, known) {
256
- console.error(`$ gh pr diff ${pr}`);
257
- let out;
258
- try {
259
- out = execFileSync("gh", ["pr", "diff", String(pr)], {
260
- encoding: "utf8",
261
- // A run-artifact PR appends thousands of rows and blows execFileSync's
262
- // 1 MiB default as ENOBUFS. This signal is ranked last and must never
263
- // be the reason the three above become unavailable, so the cliff is
264
- // raised here and a throw is reported rather than fatal.
265
- maxBuffer: 64 * 1024 * 1024,
266
- });
267
- } catch (e) {
268
- // Same three disjoint shapes changedFiles() names, and named the same way.
269
- return {
270
- hunks: null,
271
- unrun: `gh pr diff ${pr} failed: ${
272
- e.code ?? (e.signal ? `killed by ${e.signal}` : `exit ${e.status}`)
273
- }`,
274
- };
275
- }
276
- const hunks = new Map();
277
- let unresolved = 0;
278
- let file = null;
279
- let inHunk = false;
280
- for (const line of out.split("\n")) {
281
- if (line.startsWith("diff --git ")) {
282
- // Resolved against the authoritative `--name-only` list rather than
283
- // parsed out of the header: a path containing a space splits a
284
- // `a/<x> b/<x>` header ambiguously, and a path git chose to quote does
285
- // not appear literally at all. An unresolvable header leaves `file`
286
- // null so its hunks are skipped, and is counted — an uncovered file
287
- // makes an empty result incomplete, not clean.
288
- file = known.find((f) => line.endsWith(` b/${f}`)) ?? null;
289
- if (file === null) unresolved++;
290
- inHunk = false;
291
- continue;
292
- }
293
- if (file === null) continue;
294
- // `@@ ... @@` is the one line that reliably marks "metadata block ends,
295
- // hunk body begins". Gating on that state — rather than testing each
296
- // line's own text for `--- `/`+++ ` — means a hunk-BODY line whose
297
- // content itself starts with `--` or `++` (a removed line beginning
298
- // with a real `--` token, or an added one beginning with `++`) is never
299
- // mistaken for a file header and silently dropped.
300
- if (line.startsWith("@@")) {
301
- inHunk = true;
302
- continue;
303
- }
304
- if (!inHunk) continue;
305
- if (!/^[+\- ]/.test(line)) continue;
306
- const lines = hunks.get(file);
307
- if (lines) lines.push(line);
308
- else hunks.set(file, [line]);
309
- }
310
- return { hunks, unrun: unresolved ? `${pr}: ${unresolved} diff header(s) unresolved — those files were not searched` : null };
311
- }
312
-
313
- // One witness per (data file, citing file) pair, most specific token first, so
314
- // a file naming the TSV by both its path and its basename reports once and
315
- // reports the path — while a SECOND file naming it still gets its own witness.
316
- // Stopping at the first token that matches anywhere would report only the one
317
- // file, and it is the set of citing files the caller has to read.
318
- const WITNESS_CAP = 120;
319
- function proseHits(target, citer) {
320
- const targets = dataFiles(target.files);
321
- const citers = textFiles(citer.files);
322
- // Nothing to look for, or nothing that could carry it: a complete answer,
323
- // and the common case. No `gh pr diff` is spent reaching it.
324
- if (targets.length === 0 || citers.length === 0) return { hits: [], unrun: null };
325
- const { hunks, unrun } = diffOf(citer.pr, citer.files);
326
- if (hunks === null) return { hits: [], unrun };
327
- const hits = [];
328
- for (const data of targets) {
329
- const tokens = tokensFor(data);
330
- for (const text of citers) {
331
- const lines = hunks.get(text) ?? [];
332
- for (const token of tokens) {
333
- const line = lines.find((l) => l.includes(token));
334
- if (!line) continue;
335
- hits.push({
336
- data,
337
- citedBy: text,
338
- token,
339
- line: line.length > WITNESS_CAP ? `${line.slice(0, WITNESS_CAP)}…` : line,
340
- });
341
- break;
342
- }
343
- }
344
- }
345
- return { hits, unrun };
346
- }
347
-
348
- const files = intersect(filesA, filesB);
349
- const modules = intersect(modulesOf(filesA), modulesOf(filesB));
350
- const dirs = intersect(dirsOf(filesA), dirsOf(filesB));
351
-
352
- // Both directions. Which PR holds the data and which holds the prose is not
353
- // knowable in advance, and the flags carry no such role.
354
- const ab = proseHits({ pr: a, files: filesA }, { pr: b, files: filesB });
355
- const ba = proseHits({ pr: b, files: filesB }, { pr: a, files: filesA });
356
- const prose = [...ab.hits, ...ba.hits].sort((x, y) =>
357
- x.data.localeCompare(y.data) || x.citedBy.localeCompare(y.citedBy) || x.token.localeCompare(y.token)
358
- );
359
- // Non-null means `prose` is not a complete answer — the scan was reached and
360
- // could not cover what an empty array would otherwise claim. Without this
361
- // field a failed diff read prints `prose: []`, byte-identical to a clean
362
- // scan: the missed-pair failure mode — the clearest output being the one that
363
- // misses it — reintroduced one level in. Same reason run-team/SKILL.md reads
364
- // `dimensionsUnrun` beside `dimensionsRun`: an absence of findings is not
365
- // coverage.
366
- const unrunReasons = [ab.unrun, ba.unrun];
367
- if (basenameCounts === null) unrunReasons.push(basenameCountsUnrun);
368
- const proseUnrun = unrunReasons.filter(Boolean).join("; ") || null;
369
-
370
- // Ranked BELOW `dirs`, so it can only ever turn a `none` into something. It
371
- // never masks or downgrades one of the three above — and the bug it answers
372
- // is precisely a `none` that should not have been one.
373
- const signal = files.length
374
- ? "files"
375
- : modules.length
376
- ? "modules"
377
- : dirs.length
378
- ? "dirs"
379
- : prose.length
380
- ? "prose"
381
- : "none";
382
-
383
- console.error(
384
- `\n${NAME}: signal=${signal} files=${files.length} modules=${modules.length} dirs=${dirs.length} prose=${prose.length}`,
385
- );
386
- if (signal === "dirs") {
387
- console.error(
388
- `${NAME}: directory-only hit — weak evidence. A bare top-level directory\n` +
389
- ` (docs, tests, src) fires on PRs with different subjects. Read the files.`,
390
- );
391
- }
392
- if (signal === "modules") {
393
- // The hold rule this mechanises calls a module match a verdict, on a par with
394
- // a shared file. It is not one: two unrelated test files can share a name
395
- // (a `test_utils.py` in each of two packages), so two PRs can share a
396
- // "module" name and nothing else. Say so, because the caller's rule will not.
397
- console.error(
398
- `${NAME}: module-only hit — confirm before treating as a verdict. Unrelated\n` +
399
- ` test files can share a name (test_utils.py in two packages), so a\n` +
400
- ` shared name is not yet a shared module: ${modules.join(", ")}`,
401
- );
402
- }
403
- // Keyed on the count, not on `signal`, unlike the two notes above: a prose
404
- // hit under a `dirs` verdict is stronger evidence than the verdict, and the
405
- // ladder would hide it. The caveat carries the witness because one read
406
- // disproves it — which is how merge-bot-9 settled the measured pair by hand.
407
- if (prose.length) {
408
- console.error(
409
- `${NAME}: prose citation — the other PR's diff names a data file this one\n` +
410
- ` changes. Weak evidence, like a directory hit: read the line. Searched\n` +
411
- ` ${[...DATA_EXT].join(" ")} as cited, ${[...TEXT_EXT].join(" ")} as citing;\n` +
412
- ` a bare stem with no extension is never matched.`,
413
- );
414
- for (const h of prose) console.error(` ${h.data} cited by ${h.citedBy} as "${h.token}"\n ${h.line}`);
415
- }
416
- if (proseUnrun) {
417
- console.error(
418
- `${NAME}: prose scan INCOMPLETE — ${proseUnrun}.\n` +
419
- ` An empty prose[] does not clear the same-section case here.`,
420
- );
421
- }
422
-
423
- console.log(JSON.stringify({ a, b, files, modules, dirs, prose, proseUnrun, signal }));