@feigi/fleet-ctl 3.73.2 → 3.74.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.73.2",
3
+ "version": "3.74.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/pull.mjs CHANGED
@@ -53,19 +53,32 @@
53
53
  // the brief.
54
54
  // 4 Q2 decided `decided`, or a cause whose comment is posted and whose
55
55
  // label replaces `ready-for-agent`.
56
- // 5 Q3 collision the scan first: the brief's paths, and every path a
57
- // `paths <p>…` answer added, against each open PR's `gh pr diff
58
- // <M> --name-only` and each live worktree branch's `git diff
59
- // --name-only -z origin/main...<branch>` — `main` excepted, and
60
- // a branch whose upstream is gone, its PR already merged or
61
- // closed. A path matches a changed file of that path, one
62
- // under it as a directory, or, with no `/`, one of that name.
63
- // One line per PR or branch sharing a path, `no overlap` when
64
- // none, and `could not look: <which>` for one that could not be
65
- // read; the `#N` refs of the brief's Out of scope section are
66
- // printed as the behind-issue candidates. Then `clear`,
67
- // `behind-pr:#M`, `behind-issue:#M`, or `paths <p>…`, which
68
- // scans again and asks again. An exclusion is a ledger row.
56
+ // 5 Q3 collision the scan first: the brief's paths, its Out of scope
57
+ // section's excepted, and every path a `paths <p>…` answer
58
+ // added, against each open PR's `gh pr diff <M> --name-only`
59
+ // and each live worktree branch's `git diff --name-only -z
60
+ // origin/main...<branch>` — `main` excepted, and a branch whose
61
+ // upstream is gone, its PR already merged or closed. A path,
62
+ // its trailing `:N` or `:N-M` dropped, matches a changed file
63
+ // of that path, one under it as a directory, with no `/` one of
64
+ // that name, or, holding a `/` but not starting with one, one
65
+ // whose trailing whole segments it is or sits under. One line
66
+ // per PR or branch sharing a path, then, from its full diff
67
+ // (`gh pr diff <M>`, or `git diff origin/main...<branch>`),
68
+ // each shared file's hunks by base-side range, each with the
69
+ // Markdown headings its changed lines sit under in the file
70
+ // at the merge-base (a PR's head fetched as `pull/<M>/head`);
71
+ // ranges only for a file that is not Markdown or whose base
72
+ // could not be read, `(new file)` beside each range of a file
73
+ // new in the diff, and `no hunk in the diff` for a shared file
74
+ // the diff holds no hunk for. Each brief path with a line
75
+ // reference in a shared file follows, with its headings on
76
+ // origin/main. `no overlap` when none, and `could not look:
77
+ // <which>` for one that could not be read; the `#N` refs of
78
+ // the brief's Out of scope section are printed as the
79
+ // behind-issue candidates. Then `clear`, `behind-pr:#M`,
80
+ // `behind-issue:#M`, or `paths <p>…`, which scans again and
81
+ // asks again. An exclusion is a ledger row.
69
82
  // 6 claim `claim-ticket.sh <N> impl-<N> implementer --apply`.
70
83
  // 7 route `ticket-router.mjs route …`; a router that refuses releases
71
84
  // the claim, and a release that fails is exit 2 with the claim
@@ -99,7 +112,7 @@ import { gitEnv } from "./git-env.mjs";
99
112
  import { isCLI } from "./is-cli.mjs";
100
113
  import { memberTokens, premisesOf, tierValues } from "./ledger-grammar.mjs";
101
114
  import { sessionFromReceipt } from "./phase0-receipt.mjs";
102
- import { briefPaths, briefText } from "./ticket-router.mjs";
115
+ import { briefPaths, briefText, outOfScope } from "./ticket-router.mjs";
103
116
 
104
117
  const NAME = "pull";
105
118
  const SCRIPTS = dirname(fileURLToPath(import.meta.url));
@@ -186,23 +199,6 @@ export function chainHead(rows, n) {
186
199
 
187
200
  // ── the brief ────────────────────────────────────────────────────────────────
188
201
 
189
- /** The `Out of scope` section of `text`, heading to the next heading of its level or above; null when there is none. */
190
- export function outOfScope(text) {
191
- const all = text.split("\n");
192
- const at = all.findIndex((l) => /^#{1,6}\s*out of scope\b/i.test(l));
193
- if (at === -1) return null;
194
- const level = /^#+/.exec(all[at])[0].length;
195
- let end = all.length;
196
- for (let i = at + 1; i < all.length; i++) {
197
- const h = /^(#{1,6})\s/.exec(all[i]);
198
- if (h !== null && h[1].length <= level) {
199
- end = i;
200
- break;
201
- }
202
- }
203
- return all.slice(at, end).join("\n").trim();
204
- }
205
-
206
202
  /** The ticket's `Out of scope` section: the brief's, else the body's; null when neither holds one. */
207
203
  function scopeOf(issue) {
208
204
  return outOfScope(briefText(issue).trim()) ?? outOfScope(String(issue.body ?? ""));
@@ -214,6 +210,143 @@ export function issueRefs(section) {
214
210
  return [...new Set([...section.matchAll(/(?<![\w/.-])#(\d+)\b/g)].map((m) => `#${m[1]}`))];
215
211
  }
216
212
 
213
+ // ── the collision scan ───────────────────────────────────────────────────────
214
+
215
+ // A brief path's trailing line reference, `:N` or `:N-M`.
216
+ const LINE_REF = /:(\d+)(?:-(\d+))?$/;
217
+ const MARKDOWN = /\.(md|markdown|mdx)$/i;
218
+ // The byte each one-letter escape of a C-quoted diff path stands for.
219
+ const ESC = { n: 10, t: 9, '"': 34, "\\": 92, a: 7, b: 8, f: 12, r: 13, v: 11 };
220
+
221
+ /**
222
+ * Whether brief path `p` names changed file `f`, once a trailing `:N` or `:N-M`
223
+ * line reference is dropped: the same path, a directory above it (with or
224
+ * without its trailing `/`), or, with no `/`, a file by its name. A path that
225
+ * holds a `/` and does not start with one is also a suffix on whole segments,
226
+ * naming a file whose trailing segments equal it or one under a directory
227
+ * whose trailing segments do. A path starting with `/` is a slash command and
228
+ * is never a suffix.
229
+ */
230
+ export function pathHits(p, f) {
231
+ const t = p.replace(LINE_REF, "");
232
+ const q = t.replace(/\/+$/, "");
233
+ if (q === "") return false;
234
+ if (f === q || f.startsWith(`${q}/`)) return true;
235
+ if (!q.includes("/")) return f.split("/").pop() === q || (t !== q && f.includes(`/${q}/`));
236
+ return !t.startsWith("/") && (f.endsWith(`/${q}`) || f.includes(`/${q}/`));
237
+ }
238
+
239
+ /** A path as a diff header spells it: C-quoted when git quotes it, its trailing tab dropped. */
240
+ function diffPath(s) {
241
+ const raw = s.replace(/\t$/, "");
242
+ if (!raw.startsWith('"') || !raw.endsWith('"')) return raw;
243
+ const bytes = [];
244
+ for (let i = 1; i < raw.length - 1; i++) {
245
+ if (raw[i] !== "\\") {
246
+ const ch = String.fromCodePoint(raw.codePointAt(i));
247
+ bytes.push(...Buffer.from(ch));
248
+ i += ch.length - 1;
249
+ } else if (/[0-7]{3}/.test(raw.slice(i + 1, i + 4))) {
250
+ bytes.push(parseInt(raw.slice(i + 1, i + 4), 8));
251
+ i += 3;
252
+ } else {
253
+ i += 1;
254
+ bytes.push(ESC[raw[i]] ?? raw.charCodeAt(i));
255
+ }
256
+ }
257
+ return Buffer.from(bytes).toString("utf8");
258
+ }
259
+
260
+ /** The side of a `--- a/<p>` or `+++ b/<p>` line: the path, or null for `/dev/null`. */
261
+ function diffSide(s, prefix) {
262
+ const p = diffPath(s);
263
+ if (p === "/dev/null") return null;
264
+ return p.startsWith(prefix) ? p.slice(prefix.length) : p;
265
+ }
266
+
267
+ /**
268
+ * Every file of a unified git diff, `{ old, new, hunks }`: `old` the base-side
269
+ * path and `new` the other, null for `/dev/null`, and each hunk its base-side
270
+ * range `{ a, b }` from `@@ -a,b` with `from`..`to`, the base-side lines its
271
+ * changes touch — a removed line its own, an added line the one it follows, 0
272
+ * before the first — so its context lines are no part of it. A hunk's own
273
+ * lines are counted off its header, so a removed `-- x` line is never read as
274
+ * a file header.
275
+ */
276
+ export function diffHunks(text) {
277
+ const files = [];
278
+ let file = null;
279
+ let hunk = null;
280
+ let left = 0;
281
+ let right = 0;
282
+ let at = 0;
283
+ for (const line of text.split("\n")) {
284
+ if (left > 0 || right > 0) {
285
+ if (line.startsWith("-")) {
286
+ hunk.from ??= at;
287
+ hunk.to = at++;
288
+ left--;
289
+ } else if (line.startsWith("+")) {
290
+ hunk.from ??= at - 1;
291
+ hunk.to = at - 1;
292
+ right--;
293
+ } else if (!line.startsWith("\\")) {
294
+ at++;
295
+ left--;
296
+ right--;
297
+ }
298
+ continue;
299
+ }
300
+ if (line.startsWith("diff --git ")) {
301
+ file = { old: null, new: null, hunks: [] };
302
+ files.push(file);
303
+ continue;
304
+ }
305
+ if (file === null) continue;
306
+ const h = /^@@ -(\d+)(?:,(\d+))? \+\d+(?:,(\d+))? @@/.exec(line);
307
+ if (h !== null) {
308
+ const a = Number(h[1]);
309
+ const b = h[2] === undefined ? 1 : Number(h[2]);
310
+ hunk = { a, b, from: null, to: null };
311
+ file.hunks.push(hunk);
312
+ left = b;
313
+ right = h[3] === undefined ? 1 : Number(h[3]);
314
+ // An empty base range `-a,0` sits after line a, not on it.
315
+ at = b === 0 ? a + 1 : a;
316
+ } else if (line.startsWith("--- ")) file.old = diffSide(line.slice(4), "a/");
317
+ else if (line.startsWith("+++ ")) file.new = diffSide(line.slice(4), "b/");
318
+ }
319
+ return files;
320
+ }
321
+
322
+ /**
323
+ * The ATX headings of Markdown `text`, `{ line, text }`, 1-based, fenced code
324
+ * skipped. A fence closes only on a run of its own character at least as long
325
+ * with nothing after it but whitespace: a fence line carrying an info string
326
+ * inside a fence is code.
327
+ */
328
+ export function headings(text) {
329
+ const out = [];
330
+ let fence = null;
331
+ text.split("\n").forEach((l, i) => {
332
+ const f = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(l);
333
+ if (f !== null) {
334
+ if (fence === null) fence = f[1];
335
+ else if (f[1][0] === fence[0] && f[1].length >= fence.length && f[2].trim() === "") fence = null;
336
+ return;
337
+ }
338
+ if (fence === null && /^ {0,3}#{1,6}(\s|$)/.test(l)) out.push({ line: i + 1, text: l.trim() });
339
+ });
340
+ return out;
341
+ }
342
+
343
+ /** The heading lines `from`..`to` sit under: the one enclosing `from`, then each that starts after it, up to `to`. */
344
+ export function sectionsOf(hs, from, to) {
345
+ const above = hs.filter((h) => h.line <= from).at(-1);
346
+ const within = hs.filter((h) => h.line > from && h.line <= to);
347
+ return [above === undefined ? "(no heading above)" : above.text, ...within.map((h) => h.text)].join(" → ");
348
+ }
349
+
217
350
  // The placeholders the implementer's brief template declares. dispatch-prompt.mjs
218
351
  // refuses a value that spells one, and a ticket's text is a value: one that
219
352
  // names `<N>` would stop every render, with the claim standing.
@@ -240,6 +373,8 @@ export function defang(text, names) {
240
373
 
241
374
  const trimmed = (s) => String(s ?? "").trim();
242
375
  const cap = (s) => (s.length > RECORD_MAX ? `…${s.slice(-(RECORD_MAX - 1))}` : s);
376
+ // What the record keeps of a child whose stdout is a whole file or diff: its size.
377
+ const sized = (r) => `${Buffer.byteLength(r.stdout)} bytes`;
243
378
  const now = () => new Date().toISOString();
244
379
 
245
380
  function how(r) {
@@ -248,10 +383,10 @@ function how(r) {
248
383
  return `exit ${r.status}`;
249
384
  }
250
385
 
251
- /** `status` is the exit status, null when the child never ran or was killed (`how` says which). */
252
- function spawn(cmd, args, { cwd, env, timeoutMs } = {}) {
386
+ /** `status` is the exit status, null when the child never ran or was killed (`how` says which). `raw` keeps stdout as printed. */
387
+ function spawn(cmd, args, { cwd, env, timeoutMs, raw = false } = {}) {
253
388
  const r = spawnSync(cmd, args, { cwd, encoding: "utf8", maxBuffer: MAX_BUFFER, env: gitEnv(env), timeout: timeoutMs });
254
- const stdout = trimmed(r.stdout);
389
+ const stdout = raw ? String(r.stdout ?? "") : trimmed(r.stdout);
255
390
  const stderr = trimmed(r.stderr);
256
391
  return { status: r.error ? null : r.status, stdout, stderr, text: [stdout, stderr].filter(Boolean).join("\n"), how: how(r) };
257
392
  }
@@ -546,20 +681,70 @@ class Pull {
546
681
  ];
547
682
  }
548
683
 
549
- // The latest scan, line by line, and the behind-issue candidates.
684
+ // The latest scan, line by line, and the behind-issue candidates. A scan
685
+ // recorded before the hunk evidence holds no `evidence` and no `lineRefs`.
550
686
  collisionContext() {
551
- const { paths, overlaps, unread } = this.st.scans.at(-1);
687
+ const { paths, overlaps, lineRefs = [], unread } = this.st.scans.at(-1);
552
688
  const refs = issueRefs(scopeOf(this.issue()));
553
689
  const who = (o) => (o.branch === undefined ? `PR #${o.pr}` : `branch ${o.branch}${o.pr === null ? "" : ` (PR #${o.pr})`}`);
554
690
  return [
555
691
  `paths scanned: ${paths.length === 0 ? "(none)" : paths.join(" ")}`,
556
- ...overlaps.map((o) => `${who(o)}: ${o.paths.join(" ")}`),
692
+ ...overlaps.flatMap((o) => [`${who(o)}: ${o.paths.join(" ")}`, ...(o.evidence ?? [])]),
693
+ ...lineRefs,
557
694
  ...unread.map((u) => `could not look: ${u}`),
558
695
  ...(overlaps.length === 0 ? ["no overlap"] : []),
559
696
  `behind-issue candidates (Out of scope): ${refs.length === 0 ? "(none)" : refs.join(" ")}`,
560
697
  ];
561
698
  }
562
699
 
700
+ // A Markdown file's headings as it stands at `rev`, `{ hs }`, or `{ why }` it could not be read.
701
+ headingsAt(rev, path) {
702
+ const r = this.exec("collision", "git", "git", [], ["cat-file", "blob", `${rev}:${path}`], { raw: true }, sized);
703
+ return r.status === 0 ? { hs: headings(r.stdout) } : { why: `git cat-file blob ${rev}:${path}: ${failure(r)}` };
704
+ }
705
+
706
+ // The merge-base of origin/main and `rev`, `{ rev }`, or `{ why }` there is none.
707
+ mergeBase(rev) {
708
+ const r = this.exec("collision", "git", "git", [], ["merge-base", "origin/main", rev]);
709
+ return r.status === 0 && r.stdout !== "" ? { rev: r.stdout } : { why: `git merge-base origin/main ${rev}: ${failure(r)}` };
710
+ }
711
+
712
+ // The merge-base a PR's diff is taken against: its head fetched, then met with origin/main.
713
+ prBase(pr) {
714
+ const r = this.exec("collision", "git", "git", [], ["fetch", "-q", "origin", `pull/${pr}/head`], { timeoutMs: NETWORK_TIMEOUT_MS });
715
+ return r.status === 0 ? this.mergeBase("FETCH_HEAD") : { why: `git fetch origin pull/${pr}/head: ${failure(r)}` };
716
+ }
717
+
718
+ // Each shared file's hunks in `diff`, by base-side range, each with the
719
+ // headings its changed lines sit under in the base file `base()` names —
720
+ // ranges only for a file that is not Markdown or whose base could not be
721
+ // read, and `(new file)` beside each range of a file new in the diff. A
722
+ // shared file the diff holds no hunk for prints `no hunk in the diff`.
723
+ hunkLines(files, diff, base) {
724
+ const parsed = diffHunks(diff);
725
+ const lines = [];
726
+ let at;
727
+ for (const f of files) {
728
+ const d = parsed.find((x) => (x.new ?? x.old) === f);
729
+ if (d === undefined || d.hunks.length === 0) {
730
+ lines.push(` ${f}: no hunk in the diff`);
731
+ continue;
732
+ }
733
+ let hs = null;
734
+ if (d.old !== null && MARKDOWN.test(d.old)) {
735
+ at ??= base();
736
+ const read = at.rev === undefined ? at : this.headingsAt(at.rev, d.old);
737
+ if (read.hs === undefined) lines.push(` ${f}: base not read (${read.why})`);
738
+ else hs = read.hs;
739
+ }
740
+ for (const { a, b, from, to } of d.hunks) {
741
+ const where = d.old === null ? " (new file)" : hs === null ? "" : ` ${sectionsOf(hs, from, to)}`;
742
+ lines.push(` ${f} @@ -${a},${b} @@${where}`);
743
+ }
744
+ }
745
+ return lines;
746
+ }
747
+
563
748
  // ── the stages: each returns null to go on to the stage `stage` now names, or a result ──
564
749
  advance() {
565
750
  const { st } = this;
@@ -645,14 +830,11 @@ class Pull {
645
830
  const gone = goneBranches(refs.stdout);
646
831
 
647
832
  const paths = [...new Set([...briefPaths(briefText(this.issue()).trim()), ...st.addedPaths])];
648
- // A path names a changed file, a directory above it (with or without its trailing `/`), or, with no `/`, a file by its name.
649
- const hits = (p, f) => {
650
- const q = p.replace(/\/+$/, "");
651
- return f === q || f.startsWith(`${q}/`) || (!q.includes("/") && f.split("/").pop() === q);
652
- };
833
+ const sharedFiles = new Set();
834
+ // The brief paths a listing shares, and its files they name.
653
835
  const shared = (stdout, sep) => {
654
836
  const files = stdout.split(sep).filter((f) => f !== "");
655
- return paths.filter((p) => files.some((f) => hits(p, f)));
837
+ return { paths: paths.filter((p) => files.some((f) => pathHits(p, f))), files: files.filter((f) => paths.some((p) => pathHits(p, f))) };
656
838
  };
657
839
  const overlaps = [];
658
840
  const unread = [];
@@ -662,7 +844,15 @@ class Pull {
662
844
  if (d.status !== 0) unread.push(`gh pr diff ${pr} (${failure(d)})`);
663
845
  // Fail closed, as pr-overlap.mjs does: a PR with no changed file is a query that did not work, never "no overlap".
664
846
  else if (d.stdout === "") unread.push(`gh pr diff ${pr} (printed no file)`);
665
- else if (common.length > 0) overlaps.push({ pr, paths: common });
847
+ else if (common.paths.length > 0) {
848
+ for (const f of common.files) sharedFiles.add(f);
849
+ const full = this.gh("collision", ["pr", "diff", String(pr)], sized);
850
+ let evidence = [];
851
+ if (full.status !== 0) unread.push(`gh pr diff ${pr} (${failure(full)})`);
852
+ else if (full.stdout === "") unread.push(`gh pr diff ${pr} (printed no diff)`);
853
+ else evidence = this.hunkLines(common.files, full.stdout, () => this.prBase(pr));
854
+ overlaps.push({ pr, paths: common.paths, evidence });
855
+ }
666
856
  }
667
857
  const heads = new Map(prs.map((p) => [p.headRefName, p.number]));
668
858
  for (const branch of worktreeBranches(wt.stdout).filter((b) => b !== "main" && !gone.has(b)).sort()) {
@@ -671,9 +861,32 @@ class Pull {
671
861
  const d = this.exec("collision", "git", "git", [], ["diff", "--name-only", "-z", range, "--"]);
672
862
  const common = shared(d.stdout, "\0");
673
863
  if (d.status !== 0) unread.push(`git diff --name-only ${range} (${failure(d)})`);
674
- else if (common.length > 0) overlaps.push({ branch, pr: heads.get(branch) ?? null, paths: common });
864
+ else if (common.paths.length > 0) {
865
+ for (const f of common.files) sharedFiles.add(f);
866
+ const full = this.exec("collision", "git", "git", [], ["diff", "--no-color", "--no-ext-diff", "--no-textconv", "--src-prefix=a/", "--dst-prefix=b/", range, "--"], {}, sized);
867
+ let evidence = [];
868
+ if (full.status !== 0) unread.push(`git diff ${range} (${failure(full)})`);
869
+ else evidence = this.hunkLines(common.files, full.stdout, () => this.mergeBase(branch));
870
+ overlaps.push({ branch, pr: heads.get(branch) ?? null, paths: common.paths, evidence });
871
+ }
872
+ }
873
+ // A brief path carrying a line reference, in a shared file, with the headings it sits under on origin/main.
874
+ const lineRefs = [];
875
+ const onMain = new Map();
876
+ for (const p of paths) {
877
+ const ref = LINE_REF.exec(p);
878
+ if (ref === null) continue;
879
+ for (const f of [...sharedFiles].filter((x) => pathHits(p, x))) {
880
+ let where = "(not Markdown)";
881
+ if (MARKDOWN.test(f)) {
882
+ if (!onMain.has(f)) onMain.set(f, this.headingsAt("origin/main", f));
883
+ const read = onMain.get(f);
884
+ where = read.hs === undefined ? `(not read: ${read.why})` : sectionsOf(read.hs, Number(ref[1]), Number(ref[2] ?? ref[1]));
885
+ }
886
+ lineRefs.push(`brief ref ${p} (${f} on origin/main): ${where}`);
887
+ }
675
888
  }
676
- st.scans.push({ at: now(), paths, overlaps, unread });
889
+ st.scans.push({ at: now(), paths, overlaps, lineRefs, unread });
677
890
  return this.ask("collision", this.collisionContext());
678
891
  }
679
892
 
@@ -25,11 +25,18 @@
25
25
  // the home directory rather than a workspace's `.fleet/` because the bound is
26
26
  // host-wide and a review's snapshot is no repository. The holder stamps its own
27
27
  // pid and releases on exit; a holder killed without releasing is taken over by
28
- // the next waiter, so a SIGKILLed wrapper never wedges a slot. What the
29
- // takeover cannot clear — an empty or partial lock whose writer died before
30
- // stamping its pid, and a leftover `<i>.lock.reap` — is named on the way out
31
- // of an expired wait, for the operator to remove by hand once nothing is
32
- // running.
28
+ // the next waiter, so a SIGKILLed wrapper never wedges a slot. The takeover
29
+ // does not stop the dead holder's test run, so a wrapper killed with SIGKILL
30
+ // alone leaves its run going uncounted and the host over its bound until that
31
+ // run ends; stop a wrapper with SIGTERM, which it forwards to the `sh -c`
32
+ // running its entrypoint, releasing its slot once that shell exits. The run
33
+ // stops with it only if that shell execs the run, as `exec node --test` does;
34
+ // a compound entrypoint (`cd sub && make test`), or a script that neither
35
+ // execs nor relays the signal, can leave the run going past the release,
36
+ // uncounted as after a SIGKILL. What the takeover cannot clear — an empty or
37
+ // partial lock whose writer died before stamping its pid, and a leftover
38
+ // `<i>.lock.reap` — is named on the way out of an expired wait, for the
39
+ // operator to remove by hand once nothing is running.
33
40
  //
34
41
  // Environment:
35
42
  // FLEET_SUITE_SLOTS number of slots N, a positive integer. Default 2.
@@ -90,13 +90,36 @@ export function briefText(issue) {
90
90
  return String(issue.body ?? "");
91
91
  }
92
92
 
93
+ /** The line span `[at, end)` of `lines`' `Out of scope` section, heading to the next heading of its level or above; null when there is none. */
94
+ function outOfScopeSpan(lines) {
95
+ const at = lines.findIndex((l) => /^#{1,6}\s*out of scope\b/i.test(l));
96
+ if (at === -1) return null;
97
+ const level = /^#+/.exec(lines[at])[0].length;
98
+ for (let i = at + 1; i < lines.length; i++) {
99
+ const h = /^(#{1,6})\s/.exec(lines[i]);
100
+ if (h !== null && h[1].length <= level) return { at, end: i };
101
+ }
102
+ return { at, end: lines.length };
103
+ }
104
+
105
+ /** The `Out of scope` section of `text`, heading to the next heading of its level or above; null when there is none. */
106
+ export function outOfScope(text) {
107
+ const all = text.split("\n");
108
+ const span = outOfScopeSpan(all);
109
+ return span === null ? null : all.slice(span.at, span.end).join("\n").trim();
110
+ }
111
+
93
112
  /**
94
113
  * The file paths a brief names: every backticked token without whitespace that
95
- * holds a `/` or ends in an extension, in first-seen order, each once.
114
+ * holds a `/` or ends in an extension, in first-seen order, each once. The
115
+ * brief's `Out of scope` section names no target, so its tokens are skipped.
96
116
  */
97
117
  export function briefPaths(brief) {
118
+ const all = brief.split("\n");
119
+ const span = outOfScopeSpan(all);
120
+ const kept = span === null ? brief : [...all.slice(0, span.at), ...all.slice(span.end)].join("\n");
98
121
  const paths = new Set();
99
- for (const m of brief.matchAll(/`([^`\n]+)`/g)) {
122
+ for (const m of kept.matchAll(/`([^`\n]+)`/g)) {
100
123
  const tok = m[1];
101
124
  if (/\s/.test(tok)) continue;
102
125
  if (tok.includes("/") || /\.[A-Za-z][A-Za-z0-9]*$/.test(tok)) paths.add(tok);
@@ -189,8 +189,17 @@ terminating in exactly one dispatch or an empty shortlist:
189
189
  4. **Collision scan against open PRs and live branches** — `pull.mjs` runs it
190
190
  before Q3 and prints one line per open PR or live worktree branch that shares
191
191
  a path with the brief, `no overlap` when none, and `could not look: <which>`
192
- for one it could not read. Answer Q3 off those lines: an overlap →
193
- `behind-pr:#M`, a branch with no PR yet by its name; a target file the brief
192
+ for one it could not read. A path the brief names only in its `Out of scope`
193
+ section is no target and is not scanned. Under each line come the shared
194
+ files' hunks, each by its base-side range with the Markdown headings its
195
+ changed lines sit under, then each brief `path:line` reference in a shared
196
+ file with its headings on `origin/main`. A shared file is evidence, not a
197
+ verdict. Answer Q3 off those lines: `behind-pr:#M`, a branch with no PR yet
198
+ by its name, only when a construct the brief names, or a brief `path:line`
199
+ reference, lands in or next to a hunk of `#M`'s diff in a shared file — next
200
+ to is the same Markdown section, under the nearest heading above, or, in a
201
+ file with no headings, within 20 lines of the hunk; with no such evidence the
202
+ ticket does not collide, whatever files it shares. A target file the brief
194
203
  does not spell as a path → `paths <p>…`, which scans again and asks again. A
195
204
  PR the scan could not read is still yours to judge, and `behind-pr` on it is
196
205
  taken. `pr-overlap.mjs` is **PR-vs-PR only** — it runs `gh pr diff` on both
@@ -223,7 +232,7 @@ does:
223
232
  | brief names no *what* | relabel `needs-triage`, next entry |
224
233
  | genuine fork — options named, none ruled | relabel `ready-for-human`, next entry |
225
234
  | needs human hands — external access, manual testing, judgment during the work | relabel `ready-for-human`, next entry |
226
- | target files collide with an open PR or a live branch | exclude `behind-pr:#M`, next entry |
235
+ | a construct the brief names, or a brief `path:line` reference, lands in or next to a hunk of an open PR or a live branch | exclude `behind-pr:#M`, next entry |
227
236
  | `Out of scope` sequences it after an open ticket | exclude `behind-issue:#M`, next entry |
228
237
  | `claim-ticket.sh` exit 2 | taken, next entry |
229
238
  | decided, live, free, claimed | row, then dispatch (phase 2) |