rungate 0.8.13 → 0.8.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/README.md +82 -0
  2. package/gates/.gate-salt +1 -1
  3. package/hooks/VerifyPhaseLock.hook.ts +3 -3
  4. package/lib/ai-review-rounds.ts +99 -0
  5. package/lib/ai-review-suppression.ts +200 -21
  6. package/lib/bash-write-guard.ts +50 -5
  7. package/lib/board-flow.ts +235 -0
  8. package/lib/board-lane-health.ts +381 -0
  9. package/lib/board-mirror.ts +53 -35
  10. package/lib/board-ready-fanout.ts +56 -13
  11. package/lib/board-ready-rule.ts +545 -0
  12. package/lib/board-throughput.ts +136 -0
  13. package/lib/board-walkthrough.ts +240 -0
  14. package/lib/body-evidence.ts +203 -0
  15. package/lib/branch-protection.ts +399 -9
  16. package/lib/conformity.ts +95 -2
  17. package/lib/filing-compliance.ts +367 -0
  18. package/lib/finding-arbiter.ts +79 -5
  19. package/lib/generators/agents-md.ts +149 -0
  20. package/lib/github.ts +79 -0
  21. package/lib/graphql-cursor.ts +80 -0
  22. package/lib/issue-create-override.ts +415 -3
  23. package/lib/issue-decomposition.ts +33 -3
  24. package/lib/issue-file-overlap.ts +340 -0
  25. package/lib/issue-filing-gate.ts +173 -8
  26. package/lib/issue-repair.ts +13 -9
  27. package/lib/issue-shape.ts +196 -0
  28. package/lib/scaffold/ai-review-findings.ts +9 -1
  29. package/lib/scaffold/ai-review-step.ts +35 -1
  30. package/lib/source-census.ts +108 -0
  31. package/lib/spec-deps.ts +34 -11
  32. package/lib/spec-placement.ts +108 -0
  33. package/lib/stage-ladder.ts +28 -3
  34. package/lib/work-status.ts +423 -0
  35. package/package.json +1 -1
  36. package/scripts/ai-review-findings.ts +8 -13
  37. package/scripts/ai-review-threads.ts +16 -17
  38. package/scripts/board-mirror.ts +221 -8
  39. package/scripts/generate-code-map.ts +1 -1
  40. package/scripts/plan-spec.ts +79 -1
@@ -0,0 +1,340 @@
1
+ /**
2
+ * #1743 — two issues editing the same file both sit in the pickable set with
3
+ * nothing saying so.
4
+ *
5
+ * ## The measurement
6
+ *
7
+ * Over the 20 open issues carrying no milestone on 2026-11-03: 16 declare at
8
+ * least one file, and there are 10 overlapping pairs — among them a cluster of
9
+ * four, #1407, #1425, #1585 and #1355, all rewriting one file. Hand four
10
+ * agents the unblocked, unassigned set and four of them collide. Rule 2 in
11
+ * `AGENTS.md` already makes every issue name its files; nothing reads them.
12
+ *
13
+ * ## A conflict is not a dependency, and the edge is a borrowed primitive
14
+ *
15
+ * 20 of the 23 milestone-less issues are genuinely unblocked, and inventing an
16
+ * ordering for them would make the board lie about what is pickable — which is
17
+ * exactly why `lib/issue-shape.ts` leaves the *Blocked by* field optional. What
18
+ * these issues have is a file conflict. `blocked by` is the output only because
19
+ * it is the one primitive GitHub gives us for *not these two at once*, and the
20
+ * note this file composes says so in words rather than filing the edge itself.
21
+ *
22
+ * **Nothing here blocks a filing.** The gate appends a note; a human or an
23
+ * agent decides. A warning that refused would turn every second issue about a
24
+ * busy file into an argument with a tool.
25
+ *
26
+ * ## Where the heading comes from
27
+ *
28
+ * `lib/issue-shape.ts`, and nowhere else. Spelling the file-list heading here
29
+ * as well would be *two deciders that agree* from
30
+ * `.claude/rules/checks-must-be-able-to-fail.md`: a mutation of either would
31
+ * leave the other holding every case up, and both would read as covered.
32
+ * `FO-10` in `test/issue-file-overlap.test.ts` asserts the string is absent
33
+ * from this source.
34
+ */
35
+
36
+ import { ISSUE_SECTIONS, headingFor, headingOccurrencesOf } from "./issue-shape";
37
+
38
+ /** An issue reduced to the thing this file reasons about. */
39
+ export interface IssueFiles {
40
+ readonly id: number;
41
+ readonly files: readonly string[];
42
+ }
43
+
44
+ /** One file, and the open issues contending for it. */
45
+ export interface FileContention {
46
+ /** The path they all declare. */
47
+ readonly file: string;
48
+ /** The issue to do FIRST. Lowest number, so a re-run names the same one. */
49
+ readonly lead: number;
50
+ /** The rest, ascending — the ones a `blocked by` edge would point at. */
51
+ readonly blocked: readonly number[];
52
+ }
53
+
54
+ const FILES_SECTION = ISSUE_SECTIONS.find(s => s.id === "files");
55
+
56
+ if (FILES_SECTION === undefined) {
57
+ // Loud at import rather than an empty reading at call time. A section id the
58
+ // decider no longer knows is a decision somebody made; it must not surface
59
+ // as "no issue declares any file", which is indistinguishable from a quiet
60
+ // board.
61
+ throw new Error("lib/issue-file-overlap.ts: lib/issue-shape.ts declares no `files` section");
62
+ }
63
+
64
+ const FILES_HEADING = headingFor(FILES_SECTION);
65
+
66
+ /**
67
+ * The paths an issue body declares, in the order it declares them.
68
+ *
69
+ * Reads ONLY the section the decider names, and stops at the next heading: the
70
+ * sections either side are prose about the change, and a census that runs past
71
+ * its own boundary grows a population nobody declared.
72
+ *
73
+ * **The direction this is allowed to be wrong in is toward reading FEWER
74
+ * files.** A path it misses costs a warning nobody gets. A path it invents —
75
+ * a word out of a sentence — costs a collision report against a file that does
76
+ * not exist, which is how a warning channel becomes noise people skip. So a
77
+ * candidate must be a single word that looks like a path.
78
+ */
79
+ export function declaredFiles(body: string): string[] {
80
+ const out: string[] = [];
81
+ for (const line of filesSectionLines(body)) {
82
+ for (const path of pathsOnLine(line)) if (!out.includes(path)) out.push(path);
83
+ }
84
+ return out;
85
+ }
86
+
87
+ /** The lines under the file-list heading, outside any fenced block. */
88
+ function filesSectionLines(body: string): string[] {
89
+ const at = headingOccurrencesOf(body, FILES_HEADING)[0];
90
+ if (at === undefined) return [];
91
+
92
+ const out: string[] = [];
93
+ let fenced = false;
94
+ for (const line of body.slice(at).split("\n").slice(1)) {
95
+ if (/^\s*```/.test(line)) {
96
+ fenced = !fenced;
97
+ continue;
98
+ }
99
+ if (fenced) continue;
100
+ if (/^#{1,6}\s+\S/.test(line)) break; // the next section
101
+ out.push(line);
102
+ }
103
+ return out;
104
+ }
105
+
106
+ /**
107
+ * The path a list line names, or null when the line is prose.
108
+ *
109
+ * A path is **a single word containing a `/` and ending in an alphabetic
110
+ * extension of two to five characters**, and every backticked span on the line
111
+ * is offered to that rule rather than only the first.
112
+ *
113
+ * ## The separator is there because four rounds of review said so
114
+ *
115
+ * Three of this PR's five review rounds asked one question — *which token is a
116
+ * path* — and each found a token the then-current rule let through:
117
+ *
118
+ * | round | token | what was admitting it |
119
+ * |---|---|---|
120
+ * | 1 | `2.0`, `v2.1`, `i.e` | any dotted word counted |
121
+ * | 2 | `N/A` | a `/` alone counted, with nothing else checked |
122
+ * | 4 | `Node.js`, `GitHub.com` | an extension alone counted |
123
+ *
124
+ * Round 2's `N/A` was the costly one: the files section is REQUIRED and
125
+ * `missingSections` demands content under the heading, so *N/A* is exactly
126
+ * what somebody writes when they have nothing to put there, and every issue
127
+ * that wrote it collided with every other one.
128
+ *
129
+ * Rounds 1 and 2 were repaired by widening and narrowing one predicate, and
130
+ * round 4 arrived on the half the last repair had loosened. `AGENTS.md` rule 5
131
+ * says stop repairing at the third round and re-scope, so: **a path needs both
132
+ * halves — a separator AND an extension — and the class is closed.** There is
133
+ * no third shape left for a fifth token to arrive through. The alternative was
134
+ * a fourth special case, and a predicate accumulating special cases is the
135
+ * `stripHeredocs` shape from #1808, which cost four rounds before it was
136
+ * deleted.
137
+ *
138
+ * ## What this MISSES, said out loud
139
+ *
140
+ * - **Every root file** — `package.json`, `AGENTS.md`, `CLAUDE.md`. The
141
+ * deliberate cost of the separator, and the one real loss: those files are
142
+ * contested often. Buying them back needs a mechanism rather than a
143
+ * heuristic — the repository's own tracked-file list, which this module
144
+ * cannot see and should not grow a repo handle for at round five. That is a
145
+ * second issue, not a fourth branch.
146
+ * - An extension-less file — `Makefile`, `lib/issue-shape` — and a dotfile
147
+ * like `.gitignore`.
148
+ * - A URL is rejected outright on `://`, so a link to a file in another
149
+ * repository is not read as a file in this one.
150
+ *
151
+ * `FO-52` and `FO-57` assert the misses rather than leaving them in prose,
152
+ * because an earlier version of this comment claimed `Makefile` was read while
153
+ * the code rejected it.
154
+ *
155
+ * Every one of those is the direction `declaredFiles` declares two paragraphs
156
+ * up: this reader may read too few files, never a file that does not exist. A
157
+ * missed path costs a warning nobody gets; an invented one costs a collision
158
+ * report against a file that is not there, which is how the channel becomes
159
+ * noise people skip.
160
+ */
161
+ function pathsOnLine(line: string): string[] {
162
+ const bare = line.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, "").trim();
163
+ const quoted = [...bare.matchAll(/`([^`]+)`/g)].map(m => m[1].trim());
164
+ const candidates = quoted.length > 0 ? quoted : [bare];
165
+
166
+ return candidates.filter(isPath).map(c => c.replace(/^\.\//, ""));
167
+ }
168
+
169
+ /**
170
+ * One word, containing a `/`, ending in an alphabetic extension.
171
+ *
172
+ * **A repo-relative path, and nothing else.** The separator is the whole of
173
+ * the rule that was missing. See `pathsOnLine` for why it is here rather than
174
+ * a fourth special case.
175
+ */
176
+ function isPath(candidate: string): boolean {
177
+ if (candidate === "" || /\s/.test(candidate)) return false;
178
+ if (candidate.includes("://")) return false; // a URL, not a file
179
+ return candidate.includes("/") && /[A-Za-z][^/]*\.[A-Za-z]{2,5}$/.test(candidate);
180
+ }
181
+
182
+ /**
183
+ * The paths both issues declare, in the first one's order.
184
+ *
185
+ * Exact paths. Deliberately no stem matching between a source file and its
186
+ * test: they are edited together constantly and by the SAME issue, so treating
187
+ * them as one file would make nearly every pair collide and the warning would
188
+ * be worth nothing.
189
+ */
190
+ export function sharedFiles(a: readonly string[], b: readonly string[]): string[] {
191
+ return a.filter(p => b.includes(p));
192
+ }
193
+
194
+ /**
195
+ * Every file more than one of these issues declares, lowest lead first.
196
+ *
197
+ * **The unit is a FILE, and that is the correction this went through.** The
198
+ * first version clustered ISSUES by transitive union: two issues sharing
199
+ * nothing directly landed in one group when both collided with a third, and
200
+ * the group then carried the union of everyone's contested paths. Reported to
201
+ * a reader it over-claimed — #100 on `lib/a.ts` and a filing on `lib/b.ts`
202
+ * were told they shared work, on the strength of a #200 that declares both.
203
+ *
204
+ * A file is the thing two issues actually contend for, so it is the thing this
205
+ * reading is keyed on. Every id in a row declares that row's path. There is
206
+ * nothing left to over-claim with, and the union-find went with it.
207
+ *
208
+ * `lead` is the LOWEST number, which is the oldest issue and the one the rest
209
+ * queue behind. Stable by construction: a reading whose lead moved between
210
+ * runs would hand out a different set of edges each time and the board would
211
+ * churn.
212
+ */
213
+ export function contestedFiles(issues: readonly IssueFiles[]): FileContention[] {
214
+ const by = new Map<string, number[]>();
215
+ for (const issue of issues) {
216
+ for (const path of new Set(issue.files)) {
217
+ by.set(path, [...(by.get(path) ?? []), issue.id]);
218
+ }
219
+ }
220
+
221
+ return [...by.entries()]
222
+ .filter(([, ids]) => ids.length > 1)
223
+ .map(([file, ids]) => {
224
+ const sorted = [...ids].sort((a, b) => a - b);
225
+ return { file, lead: sorted[0], blocked: sorted.slice(1) };
226
+ })
227
+ .sort((a, b) => a.lead - b.lead || a.file.localeCompare(b.file));
228
+ }
229
+
230
+ /**
231
+ * Corpus rows as the thing this file reasons about.
232
+ *
233
+ * Takes the structural shape rather than importing `Finding`, so the direction
234
+ * of the dependency stays one way: `lib/issue-filing-gate.ts` reads this file,
235
+ * and this file knows nothing about the gate.
236
+ *
237
+ * **A row whose id is not a number is dropped, not coerced.** The corpus also
238
+ * carries in-command siblings keyed by position and the `new` marker for an
239
+ * unfiled finding, and `Number("new")` is `NaN` — an id that would print as
240
+ * `#NaN` in a warning and point at nothing.
241
+ */
242
+ export function asIssueFiles(rows: readonly { id: string; body: string }[]): IssueFiles[] {
243
+ const out: IssueFiles[] = [];
244
+ for (const row of rows) {
245
+ const id = Number(row.id);
246
+ if (!Number.isInteger(id) || id <= 0) continue;
247
+ const files = declaredFiles(row.body);
248
+ if (files.length > 0) out.push({ id, files });
249
+ }
250
+ return out;
251
+ }
252
+
253
+ /**
254
+ * The open issues this body shares a file with, and WHICH files, ascending.
255
+ *
256
+ * **DIRECT overlap, and the word is load-bearing.** The first version ran the
257
+ * body through a transitive clustering with the rest and reported the group it
258
+ * landed in, on the argument that everything in a contested set costs the same
259
+ * to pick up. The review of this PR showed that argument is false, with a case
260
+ * I had written no test for:
261
+ *
262
+ * #100 declares lib/a.ts
263
+ * #200 declares lib/a.ts AND lib/b.ts
264
+ * the filing declares lib/b.ts
265
+ *
266
+ * One group, transitively — and the note then told the filer they shared
267
+ * `lib/a.ts` with #100, which neither of them is true of, and offered
268
+ * `--add-blocked-by 100` on that basis. A warning that names a file the reader
269
+ * never wrote is the fastest way to teach them to skip the channel. `FO-45`
270
+ * and `FG-229` are that case.
271
+ *
272
+ * Transitivity is still right for the question `contestedFiles` answers —
273
+ * *what does the pickable set look like* — because there every id in a row
274
+ * declares that row's path. It is wrong for *what does THIS body collide
275
+ * with*, and those are two questions.
276
+ */
277
+ export function collisionsWith(body: string, corpus: readonly IssueFiles[]): IssueFiles[] {
278
+ const mine = declaredFiles(body);
279
+ if (mine.length === 0) return [];
280
+
281
+ return corpus
282
+ .map(issue => ({ id: issue.id, files: sharedFiles(mine, issue.files) }))
283
+ .filter(hit => hit.files.length > 0)
284
+ .sort((a, b) => a.id - b.id);
285
+ }
286
+
287
+ /**
288
+ * The note an agent reads when the body they are filing collides, or null.
289
+ *
290
+ * Null rather than an empty string: `lib/issue-filing-gate.ts` joins its
291
+ * notes, so an empty one is blank space in a refusal nobody can account for,
292
+ * and a channel that always has something in it is a channel people skip.
293
+ *
294
+ * **Every path printed here is one the filing itself declared**, and it is
295
+ * attributed to an issue that declared it too — `collisionsWith` carries the
296
+ * intersection rather than either side's whole list, so there is nothing for
297
+ * this function to over-claim with.
298
+ *
299
+ * It names the remedy. A warning that does not say what to type is a warning
300
+ * nobody can act on — `.claude/rules/config-access.md` makes that point about
301
+ * UNMEASURED and it is true of every channel this gate writes to.
302
+ *
303
+ * The closing line is `contestedFiles` over the OPEN corpus alone, with this
304
+ * body nowhere in it: a file two or more issues already contend for is a queue
305
+ * the filer is joining, not a pair they are forming, and the oldest is the one
306
+ * the rest go behind. `FO-46` pins the count at three where four issues would
307
+ * be the tempting number.
308
+ */
309
+ export function overlapNote(body: string, corpus: readonly IssueFiles[]): string | null {
310
+ const collisions = collisionsWith(body, corpus);
311
+ if (collisions.length === 0) return null;
312
+
313
+ const flags = collisions.map(c => `--add-blocked-by ${c.id}`).join(" ");
314
+ const mine = new Set(collisions.flatMap(c => c.files));
315
+ const queues = contestedFiles(corpus)
316
+ .filter(c => mine.has(c.file))
317
+ .map(
318
+ c =>
319
+ `\`${c.file}\` already has ${c.blocked.length + 1} open issues on it — ` +
320
+ `#${c.lead} is the oldest.`,
321
+ );
322
+
323
+ return [
324
+ `**${plural(collisions.length)} already open ${collisions.length === 1 ? "names" : "name"} ` +
325
+ "a file this one names:**",
326
+ "",
327
+ ...collisions.map(c => `- #${c.id} — ${c.files.map(f => `\`${f}\``).join(", ")}`),
328
+ ...(queues.length > 0 ? ["", ...queues] : []),
329
+ "",
330
+ "Two sessions editing one file, with nothing on the tracker saying so, is",
331
+ "the conflict this is warning about — it is NOT a dependency, and the board",
332
+ "should not grow an ordering nobody meant. Order them only if you do:",
333
+ "",
334
+ ` gh issue edit <this issue> ${flags}`,
335
+ ].join("\n");
336
+ }
337
+
338
+ function plural(n: number): string {
339
+ return n === 1 ? "An issue" : `${n} issues`;
340
+ }
@@ -127,7 +127,19 @@ import {
127
127
  type JuryReading,
128
128
  type Severity,
129
129
  } from "./finding-jury";
130
- import { clauses, createsIssue, flagValues, labelValues } from "./issue-create-override";
130
+ import {
131
+ apiFilingRepo,
132
+ apiRestFields,
133
+ clauses,
134
+ filingDirectory,
135
+ createsIssue,
136
+ flagValues,
137
+ graphqlDocument,
138
+ graphqlVariables,
139
+ labelValues,
140
+ } from "./issue-create-override";
141
+ import { headingFor, missingSections, requiredSections } from "./issue-shape";
142
+ import { asIssueFiles, overlapNote } from "./issue-file-overlap";
131
143
  import { gitSource, plannedFiling, type PlanSource } from "./filing-plan";
132
144
  import { resolveShipPolicy, type ShipPolicy } from "./ship-mode";
133
145
  import { tryLoadRungateConfig } from "./config-loader";
@@ -1035,6 +1047,32 @@ export type CommentExemption = keyof typeof COMMENT_EXEMPTIONS;
1035
1047
  */
1036
1048
  export const EXEMPTION_PREFIX = "Cannot be a comment:";
1037
1049
 
1050
+ /**
1051
+ * The `MALFORMED` sentence, naming every section the body is short (#1741).
1052
+ *
1053
+ * Composed here rather than at the refusal site so the refusal carries one
1054
+ * string the suite can assert on, and so the list comes from
1055
+ * `requiredSections` rather than being retyped — a refusal that names a
1056
+ * different set of sections from the one that produced it is a refusal an
1057
+ * agent cannot satisfy.
1058
+ *
1059
+ * **It names the headings, not the field ids.** The heading is what an agent
1060
+ * has to type into the body; an id is a fact about a YAML file they are not
1061
+ * editing.
1062
+ */
1063
+ export function malformedReason(missing: readonly string[]): string {
1064
+ const both = requiredSections("everyday-work").map(headingFor);
1065
+ return (
1066
+ `the body is short ${missing.length} section(s) every issue needs: ${missing.join(", ")}. ` +
1067
+ `An issue naming no files cannot be checked against rule 2 and cannot be scanned for the ` +
1068
+ `file overlaps that put four agents on one file, and an issue with no "how we will know" ` +
1069
+ `is one nobody can close on evidence. The floor is ${both.join(", ")} — spec work also ` +
1070
+ `needs ${headingFor(requiredSections("spec-work").find(s => s.id === "criteria")!)}, ` +
1071
+ `which the form asks for and this gate does not, because a consumer reporting a problem ` +
1072
+ `upstream cannot know a criterion id`
1073
+ );
1074
+ }
1075
+
1038
1076
  /**
1039
1077
  * Which declaration a filing makes, or `null` for none.
1040
1078
  *
@@ -1585,7 +1623,60 @@ export function ghRepoTarget(value: string): string | null {
1585
1623
  * corpus, finds nothing, and the filing is allowed. `--repo` IS read,
1586
1624
  * because it is in the clause and costs one more query.
1587
1625
  */
1626
+ /**
1627
+ * A `title:` / `body:` argument inside a GraphQL document, resolved.
1628
+ *
1629
+ * Two spellings, because both are ordinary. A literal — `title: "…"` — is
1630
+ * read out of the document. A variable — `title: $title` — is looked up in
1631
+ * the fields the clause passes alongside the query, which is the form
1632
+ * `gh`'s own documentation recommends because it avoids escaping quotes by
1633
+ * hand. ai-review round 1 of #1805: reading only the literal left the
1634
+ * idiomatic form resolving to an empty title, counted as a filing and
1635
+ * compared against nothing.
1636
+ *
1637
+ * Crude on purpose beyond those two: the alternative is a GraphQL parser,
1638
+ * and what the gate needs is the two strings it compares and scans. A
1639
+ * document this cannot read yields `null`, the attempt resolves empty, and
1640
+ * the gate lands on its existing "names no symbol" arm — the same place an
1641
+ * unreadable `--body-file` already lands.
1642
+ */
1643
+ function graphqlArgument(doc: string, name: string, vars: Map<string, string>): string | null {
1644
+ const m = new RegExp(`\\b${name}\\s*:\\s*(?:"((?:[^"\\\\]|\\\\.)*)"|\\$(\\w+))`).exec(doc);
1645
+ if (m === null) return null;
1646
+ if (m[2] !== undefined) return vars.get(m[2]) ?? null;
1647
+ return m[1].replace(/\\(.)/g, "$1");
1648
+ }
1649
+
1588
1650
  export function resolveFiling(tokens: string[]): FilingAttempt {
1651
+ const doc = graphqlDocument(tokens);
1652
+ if (doc !== null) {
1653
+ const vars = graphqlVariables(tokens) ?? new Map<string, string>();
1654
+ return {
1655
+ title: graphqlArgument(doc, "title", vars) ?? "",
1656
+ body: graphqlArgument(doc, "body", vars) ?? "",
1657
+ labels: [],
1658
+ bodyFile: null,
1659
+ // A createIssue carries `repositoryId`, an opaque node id rather than
1660
+ // a slug, so this is honestly unknown rather than guessed. `null` is
1661
+ // what a `gh issue create` with no `--repo` already resolves to.
1662
+ repo: null,
1663
+ repeatedValueFlag: false,
1664
+ };
1665
+ }
1666
+ const apiRest = apiRestFields(tokens);
1667
+ if (apiRest !== null) {
1668
+ return {
1669
+ title: apiRest.get("title") ?? "",
1670
+ body: apiRest.get("body") ?? "",
1671
+ labels: (apiRest.get("labels") ?? "")
1672
+ .split(",")
1673
+ .map(l => l.trim())
1674
+ .filter(l => l !== ""),
1675
+ bodyFile: null,
1676
+ repo: apiFilingRepo(tokens),
1677
+ repeatedValueFlag: false,
1678
+ };
1679
+ }
1589
1680
  const titles = flagValues(tokens, TITLE_FLAG);
1590
1681
  const bodies = flagValues(tokens, BODY_FLAG);
1591
1682
  const bodyFiles = flagValues(tokens, BODY_FILE_FLAG);
@@ -1903,6 +1994,39 @@ export async function adjudicateFiling(
1903
1994
  };
1904
1995
  }
1905
1996
 
1997
+ // ── it belongs on the tracker. is it READABLE by the things that read it? ──
1998
+ //
1999
+ // **#1741, and it is LAST for the reason every late stage here is last.**
2000
+ // Only an ALLOW reaches this line, so it can mask nothing: a duplicate is
2001
+ // still refused as DUPLICATE, an unreadable ledger is still UNMEASURED_CAP,
2002
+ // and a filing with no declaration still hears about the comment default
2003
+ // first. Placing a cheap string check ahead of those would convert every
2004
+ // one of them into "your body is short a heading", which is the mask
2005
+ // measured at 34 of 78 cases when `NO_CLAIM` was briefly moved first.
2006
+ //
2007
+ // **The floor is the EVERYDAY form, not the spec-work one.** The two forms
2008
+ // differ in exactly one field — `Criteria this serves`, which a consumer
2009
+ // reporting upstream cannot know — so the sections common to both are the
2010
+ // only ones this gate can demand without refusing a legitimate consumer
2011
+ // report. The spec-work form enforces its extra field where it belongs, on
2012
+ // the form. A gate that demanded it would be a second, stricter decider
2013
+ // sitting over the first.
2014
+ //
2015
+ // This is the half of #1741 that could not be built before the other two
2016
+ // consumers: `plan-issues --decompose` emitted two of the form's five
2017
+ // sections, so this check on the day it was written would have refused
2018
+ // every row of every decomposed plan. `test/issue-shape.test.ts`'s IS-31
2019
+ // is the standing proof that it no longer does.
2020
+ const malformed = missingSections(body, "everyday-work");
2021
+ if (malformed.length > 0) {
2022
+ return {
2023
+ ...base,
2024
+ outcome: "REFUSE",
2025
+ refusal: "MALFORMED",
2026
+ reason: malformedReason(malformed),
2027
+ };
2028
+ }
2029
+
1906
2030
  return {
1907
2031
  ...base,
1908
2032
  outcome: "ALLOW",
@@ -2553,13 +2677,27 @@ export async function filingGate(
2553
2677
 
2554
2678
  const at = options.now ?? new Date().toISOString();
2555
2679
  const read = options.readExisting ?? openFindings;
2556
- const planSource = options.readPlan ?? gitSource(options.projectRoot);
2680
+ // **Where the command ran, which is not necessarily where the session
2681
+ // lives** (#1833). `options.projectRoot` is the caller's directory — for
2682
+ // the live caller, `hooks/VerifyPhaseLock.hook.ts`, that is the session's
2683
+ // launch directory. Every stage below reads this instead, because every
2684
+ // one of them is asking about the checkout the filing was made FROM: its
2685
+ // config, its tracker, its branch's PR, its run id, and the plans on its
2686
+ // `origin/main`. See `filingDirectory` for why the answer is in the
2687
+ // command text and for the two cases it cannot resolve.
2688
+ const root = filingDirectory(cmd, options.projectRoot);
2689
+ // A relative `--body-file` is relative to the command's directory too, and
2690
+ // this is the one place that can say so. `"-"` is stdin and has no path to
2691
+ // resolve; `readBodyFile` is what decides that, so it stays its decision.
2692
+ const readBody = (path: string): string | null =>
2693
+ readBodyFile(path === "-" ? path : resolve(root, path));
2694
+ const planSource = options.readPlan ?? gitSource(root);
2557
2695
  // The run's allowance, resolved ONCE per command. Per clause would let two
2558
2696
  // clauses of one command be adjudicated against two different caps if the
2559
2697
  // config moved underneath them, which is the shape `readFor` is cached to
2560
2698
  // avoid one line below. A config that cannot be read resolves to the
2561
2699
  // STRICT cap — `filingsPerRunFor`.
2562
- const allowance = filingsPerRunFor(() => tryLoadRungateConfig(options.projectRoot));
2700
+ const allowance = filingsPerRunFor(() => tryLoadRungateConfig(root));
2563
2701
  const cap = allowance.cap;
2564
2702
  // Read once per TARGET TRACKER, not once per command and not once per
2565
2703
  // clause. Once per clause would adjudicate two creates against two
@@ -2572,7 +2710,7 @@ export async function filingGate(
2572
2710
  const key = repo ?? "";
2573
2711
  const hit = cached.get(key);
2574
2712
  if (hit !== undefined) return hit;
2575
- const started = read(options.projectRoot, repo);
2713
+ const started = read(root, repo);
2576
2714
  cached.set(key, started);
2577
2715
  return started;
2578
2716
  };
@@ -2588,7 +2726,7 @@ export async function filingGate(
2588
2726
  const key = repo ?? "";
2589
2727
  const hit = targets.get(key);
2590
2728
  if (hit !== undefined) return hit;
2591
- const started = readTarget(options.projectRoot, repo);
2729
+ const started = readTarget(root, repo);
2592
2730
  targets.set(key, started);
2593
2731
  return started;
2594
2732
  };
@@ -2670,7 +2808,7 @@ export async function filingGate(
2670
2808
  // directory that simply has no origin, which is an answer and buckets.
2671
2809
  // Without the split the timeout silently re-keys a real checkout into the
2672
2810
  // shared allowance, which is the denominator changing underneath the count.
2673
- const reading = runIdFor(options.projectRoot, options.readRemote);
2811
+ const reading = runIdFor(root, options.readRemote);
2674
2812
  const run = reading.run ?? NON_CHECKOUT_RUN;
2675
2813
  const nowMs = Date.parse(at);
2676
2814
  const uncountable = priorRows === null || reading.run === null;
@@ -2691,7 +2829,7 @@ export async function filingGate(
2691
2829
  const read1 = await adjudicateFiling(
2692
2830
  attempt,
2693
2831
  () => readFor(attempt.repo),
2694
- readBodyFile,
2832
+ readBody,
2695
2833
  () => targetFor(attempt.repo),
2696
2834
  );
2697
2835
  // The in-run class check, applied to anything the per-filing stages did
@@ -2700,7 +2838,7 @@ export async function filingGate(
2700
2838
  // tracker is no reason to let one command file a class twice. The note
2701
2839
  // below is keyed off `read1` rather than `verdict` so the unreadable
2702
2840
  // tracker is still said out loud when that happens.
2703
- const { finding } = filingFinding(attempt);
2841
+ const { finding } = filingFinding(attempt, readBody);
2704
2842
  // **The cap is applied before anything READS THE TRACKER'S ANSWER, and
2705
2843
  // it converts an UNMEASURED.** Every other
2706
2844
  // UNMEASURED arm in this file allows, which is right for a reading about
@@ -2970,6 +3108,33 @@ export async function filingGate(
2970
3108
  // the honest filer who labels the override and the filer who reworded
2971
3109
  // until it passed stop producing the same ledger.
2972
3110
  else if (prior !== null && verdict.outcome !== "REFUSE") notes.push(refiledNote(attempt.title, prior));
3111
+
3112
+ // ── #1743: this body names a file an open issue already names ──────────
3113
+ //
3114
+ // **A NOTE, never a refusal.** `AGENTS.md` rule 2 already makes every
3115
+ // issue name its files and nothing read them, so two issues rewriting one
3116
+ // file both sit in the pickable set with nothing saying so. Measured over
3117
+ // the 20 milestone-less open issues on 2026-11-03: 16 declare a file, 10
3118
+ // pairs overlap, and four of them — #1407, #1425, #1585, #1355 — rewrite
3119
+ // the same one.
3120
+ //
3121
+ // A refusal here would be wrong twice. It would argue with every second
3122
+ // issue about a busy file, and it would be a reading about OTHER issues
3123
+ // deciding whether THIS one may exist. The gate's refusals are all about
3124
+ // the filing in hand.
3125
+ //
3126
+ // **Only on a clause that is actually filing**, and only on a MEASURED
3127
+ // corpus. A warning derived from a tracker nobody could read would be a
3128
+ // reading presented as a fact — `unmeasuredNote` above already says the
3129
+ // corpus was unreadable, and saying "no overlap" in the same breath is
3130
+ // the silent default `.claude/rules/config-access.md` names.
3131
+ if (cleared) {
3132
+ const corpus = await readFor(attempt.repo);
3133
+ if (corpus.reading === "MEASURED") {
3134
+ const note = overlapNote(finding.body, asIssueFiles(corpus.findings));
3135
+ if (note !== null) notes.push(note);
3136
+ }
3137
+ }
2973
3138
  }
2974
3139
 
2975
3140
  // ── A refusal blocks the COMMAND, and every clean clause is NAMED in the
@@ -31,6 +31,8 @@
31
31
  * `AGENTS.md` rule 7 asks us to watch.
32
32
  */
33
33
 
34
+ import { headingOccurrencesOf } from "./issue-shape";
35
+
34
36
  /** The section a repaired body carries. One spelling, by fiat. */
35
37
  export const CRITERIA_HEADING = "## Criteria this serves";
36
38
 
@@ -194,17 +196,19 @@ export function annotatedBody(body: string, criteria: readonly string[]): string
194
196
  *
195
197
  * Returns every occurrence, because more than one is a body
196
198
  * {@link multiplyAnnotated} refuses rather than a first match to edit.
199
+ *
200
+ * **#1741: the body of this is now `lib/issue-shape.ts`.** Everything above
201
+ * is why the obvious version is wrong, and that reasoning was correct and
202
+ * hard-won — but it lived here, bound to one hard-coded heading, while the
203
+ * filing gate and the issue forms were growing a need for the same reading
204
+ * of a different heading. Two heading parsers answering the same question
205
+ * about the same input is *two deciders that agree*
206
+ * (`.claude/rules/checks-must-be-able-to-fail.md`): no behavioural test can
207
+ * tell them apart and a mutation of either leaves the other holding the case
208
+ * up. One parser, parameterised by the heading.
197
209
  */
198
210
  export function headingOccurrences(body: string): number[] {
199
- const out: number[] = [];
200
- let fenced = false;
201
- let at = 0;
202
- for (const line of body.split("\n")) {
203
- if (/^\s*```/.test(line)) fenced = !fenced;
204
- else if (!fenced && line.trimEnd() === CRITERIA_HEADING) out.push(at);
205
- at += line.length + 1;
206
- }
207
- return out;
211
+ return headingOccurrencesOf(body, CRITERIA_HEADING);
208
212
  }
209
213
 
210
214
  /**