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.
- package/README.md +82 -0
- package/gates/.gate-salt +1 -1
- package/hooks/VerifyPhaseLock.hook.ts +3 -3
- package/lib/ai-review-rounds.ts +99 -0
- package/lib/ai-review-suppression.ts +200 -21
- package/lib/bash-write-guard.ts +50 -5
- package/lib/board-flow.ts +235 -0
- package/lib/board-lane-health.ts +381 -0
- package/lib/board-mirror.ts +53 -35
- package/lib/board-ready-fanout.ts +56 -13
- package/lib/board-ready-rule.ts +545 -0
- package/lib/board-throughput.ts +136 -0
- package/lib/board-walkthrough.ts +240 -0
- package/lib/body-evidence.ts +203 -0
- package/lib/branch-protection.ts +399 -9
- package/lib/conformity.ts +95 -2
- package/lib/filing-compliance.ts +367 -0
- package/lib/finding-arbiter.ts +79 -5
- package/lib/generators/agents-md.ts +149 -0
- package/lib/github.ts +79 -0
- package/lib/graphql-cursor.ts +80 -0
- package/lib/issue-create-override.ts +415 -3
- package/lib/issue-decomposition.ts +33 -3
- package/lib/issue-file-overlap.ts +340 -0
- package/lib/issue-filing-gate.ts +173 -8
- package/lib/issue-repair.ts +13 -9
- package/lib/issue-shape.ts +196 -0
- package/lib/scaffold/ai-review-findings.ts +9 -1
- package/lib/scaffold/ai-review-step.ts +35 -1
- package/lib/source-census.ts +108 -0
- package/lib/spec-deps.ts +34 -11
- package/lib/spec-placement.ts +108 -0
- package/lib/stage-ladder.ts +28 -3
- package/lib/work-status.ts +423 -0
- package/package.json +1 -1
- package/scripts/ai-review-findings.ts +8 -13
- package/scripts/ai-review-threads.ts +16 -17
- package/scripts/board-mirror.ts +221 -8
- package/scripts/generate-code-map.ts +1 -1
- 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
|
+
}
|
package/lib/issue-filing-gate.ts
CHANGED
|
@@ -127,7 +127,19 @@ import {
|
|
|
127
127
|
type JuryReading,
|
|
128
128
|
type Severity,
|
|
129
129
|
} from "./finding-jury";
|
|
130
|
-
import {
|
|
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
|
-
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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
|
-
|
|
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
|
package/lib/issue-repair.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
/**
|