rungate 0.3.0 → 0.4.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/lib/brief-precedence.ts +114 -0
- package/lib/ci-checkout.ts +27 -1
- package/lib/compliance-backfill.ts +16 -4
- package/lib/compliance-report.ts +109 -8
- package/lib/config-readers.ts +86 -0
- package/lib/conformity.ts +364 -27
- package/lib/create-sc.ts +20 -25
- package/lib/decomposition-waves.ts +197 -0
- package/lib/gate-check-audit.ts +190 -0
- package/lib/generators/agents-md.ts +10 -5
- package/lib/issue-extraction.ts +368 -0
- package/lib/phase2-decomposition.ts +270 -0
- package/lib/prior-branch.ts +24 -1
- package/lib/prove-label-gate.ts +93 -0
- package/lib/release-preflight.ts +102 -0
- package/lib/rungate-schema.ts +13 -1
- package/lib/scaffold/pre-push-hook.ts +165 -0
- package/lib/scaffold/steps.ts +42 -101
- package/lib/scope-denylist.ts +258 -0
- package/lib/task-completion-checks.ts +50 -3
- package/lib/typescript-project.ts +233 -0
- package/lib/verified-push.ts +179 -2
- package/lib/worktree-cleanup.ts +201 -19
- package/lib/worktree-repo.ts +300 -0
- package/package.json +4 -2
|
@@ -0,0 +1,368 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reading a goal and its acceptance criteria out of an issue body (#210, #202).
|
|
3
|
+
*
|
|
4
|
+
* `scripts/precompute-goal.ts` replaces two ceremony agents with two regexes
|
|
5
|
+
* run over the raw markdown of a GitHub issue. Both were wrong in the same
|
|
6
|
+
* way, and the shared cause is worth stating before either case:
|
|
7
|
+
*
|
|
8
|
+
* **The extractor had no model of the document it was reading.** It matched
|
|
9
|
+
* lines. A line inside a fenced code block, a line under a "Scope" heading,
|
|
10
|
+
* and a line the harness itself wrote into the issue are all just lines.
|
|
11
|
+
*
|
|
12
|
+
* Two measured instances:
|
|
13
|
+
*
|
|
14
|
+
* - **#210.** Shipping #209, the criteria list came back as exactly one AC:
|
|
15
|
+
* ``SC-N: `workflows/ship.js` executes [MARKER-NAME]``. That is an
|
|
16
|
+
* illustration inside a fenced block showing the SYNTAX of a proposed SC.
|
|
17
|
+
* Marcus was about to be briefed with one acceptance criterion made
|
|
18
|
+
* entirely of placeholders, and nothing downstream would have asked.
|
|
19
|
+
* - **#202.** When a run rescopes an issue for the 6-AC limit it PREPENDS a
|
|
20
|
+
* blockquote banner, which then becomes the first paragraph and therefore
|
|
21
|
+
* the goal. Measured on #200: 414 characters describing the split, none
|
|
22
|
+
* describing the defect. The harness degraded its own input, and only on
|
|
23
|
+
* the LARGE issues where the goal statement matters most.
|
|
24
|
+
*
|
|
25
|
+
* ## Why this is a module and not twenty lines in the script
|
|
26
|
+
*
|
|
27
|
+
* It was twenty lines in the script, at module top level, so none of it was
|
|
28
|
+
* reachable from a test — which is why both defects were found by reading
|
|
29
|
+
* pipeline output by hand rather than by the suite. The functions here take a
|
|
30
|
+
* string and return a value; every case below is a fixture.
|
|
31
|
+
*
|
|
32
|
+
* ## The direction these are allowed to be wrong in
|
|
33
|
+
*
|
|
34
|
+
* Toward extracting LESS and saying so. A criterion missed costs Discovery
|
|
35
|
+
* writing one, which is the designed path. A criterion invented out of
|
|
36
|
+
* documentation is briefed to an agent as a thing to build.
|
|
37
|
+
*/
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* Markers that identify a blockquote as harness-authored metadata rather than
|
|
41
|
+
* the author's prose.
|
|
42
|
+
*
|
|
43
|
+
* Exported and asserted against `workflows/ship.js`'s decompose prompt by
|
|
44
|
+
* `test/issue-extraction.test.ts`, which is the "fails loudly" half: the
|
|
45
|
+
* banner is written by an agent told to use this wording, so a change to the
|
|
46
|
+
* instruction and no change here turns the suite red instead of silently
|
|
47
|
+
* handing the banner back as a goal (#202).
|
|
48
|
+
*
|
|
49
|
+
* A leading blockquote carrying NONE of these is kept. That is the positive
|
|
50
|
+
* control, and it is the whole difficulty of the case: a parser that
|
|
51
|
+
* discarded every leading blockquote would pass the banner cases for free and
|
|
52
|
+
* lose the goal of any issue whose author opens with a quote.
|
|
53
|
+
*/
|
|
54
|
+
export const HARNESS_BANNER_MARKERS = [
|
|
55
|
+
"Rescoped to Phase",
|
|
56
|
+
"Sub-issues:",
|
|
57
|
+
] as const;
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Line prefixes that make a leading paragraph harness-written front matter.
|
|
61
|
+
*
|
|
62
|
+
* Found by this change rather than reported: `test/fixtures/github/issue-48.json`
|
|
63
|
+
* is a sub-issue, sub-issue bodies open with `Parent: #47`, and the old regex
|
|
64
|
+
* took the first paragraph. So **every decomposed run has briefed its agent
|
|
65
|
+
* with the goal "Parent: #N"** — eleven characters of cross-reference. Same
|
|
66
|
+
* defect as #202's banner, one producer earlier and far more frequent: the
|
|
67
|
+
* banner fires only on a rescope, this fires on every sub-issue.
|
|
68
|
+
*
|
|
69
|
+
* `workflows/ship.js`'s decompose step is told to write both lines, and
|
|
70
|
+
* `test/issue-extraction.test.ts` asserts they are still in that prompt.
|
|
71
|
+
*
|
|
72
|
+
* A paragraph is skipped only when EVERY line in it is one of these and short.
|
|
73
|
+
* An author writing a sentence that begins "Spec: the contract says…" keeps
|
|
74
|
+
* their goal.
|
|
75
|
+
*/
|
|
76
|
+
export const HARNESS_PREAMBLE_MARKERS = [
|
|
77
|
+
"Parent: #",
|
|
78
|
+
"Spec: ",
|
|
79
|
+
] as const;
|
|
80
|
+
|
|
81
|
+
/** Above this, a line is prose that happens to start with a marker. */
|
|
82
|
+
const MAX_PREAMBLE_LINE_CHARS = 120;
|
|
83
|
+
|
|
84
|
+
/** A goal shorter than this is a failed extraction, not a terse author. */
|
|
85
|
+
export const MIN_GOAL_CHARS = 40;
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* The one exit code every refusal in `scripts/precompute-goal.ts` routes
|
|
89
|
+
* through, per `.claude/rules/checks-must-be-able-to-fail.md`. Declared once
|
|
90
|
+
* so the test can build a mutant copy of the script with it set to `0` and
|
|
91
|
+
* watch the refusals stop refusing.
|
|
92
|
+
*
|
|
93
|
+
* Not `1`: `1` is the usage error the script already exits with for missing
|
|
94
|
+
* arguments, and a caller that cannot tell "you called me wrong" from "this
|
|
95
|
+
* issue cannot be read" learns nothing from either.
|
|
96
|
+
*/
|
|
97
|
+
export const GOAL_REFUSE_EXIT = 3;
|
|
98
|
+
|
|
99
|
+
export interface GoalReading {
|
|
100
|
+
/** The goal paragraph, or null when nothing usable was left. */
|
|
101
|
+
goal: string | null;
|
|
102
|
+
/** Non-null when the body yielded no goal a brief could be written from. */
|
|
103
|
+
refusal: string | null;
|
|
104
|
+
/** True when a harness banner was recognised and stepped over. */
|
|
105
|
+
skippedBanner: boolean;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export interface CriteriaReading {
|
|
109
|
+
criteria: string[];
|
|
110
|
+
/** Where they came from, so "none found" can say which question it answered. */
|
|
111
|
+
source: "success-criteria-section" | "none";
|
|
112
|
+
/** Non-null when what was found cannot be briefed — see `isPlaceholder`. */
|
|
113
|
+
refusal: string | null;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Blank out code so a line inside it cannot be read as content.
|
|
118
|
+
*
|
|
119
|
+
* Lines are REPLACED with empty lines rather than removed: every caller below
|
|
120
|
+
* reasons about headings and ordering, and silently renumbering the document
|
|
121
|
+
* would make a section boundary land somewhere else than the author put it.
|
|
122
|
+
*
|
|
123
|
+
* Indented code is only recognised outside a list. Four-space indentation is
|
|
124
|
+
* also how a nested checkbox is written, and `- [ ] SC-2` nested under a
|
|
125
|
+
* bullet is an acceptance criterion in every issue in this repo — treating it
|
|
126
|
+
* as code would delete real criteria to catch a rare fake one, which is the
|
|
127
|
+
* wrong direction for this module to be wrong in.
|
|
128
|
+
*/
|
|
129
|
+
export function stripCodeBlocks(body: string): string {
|
|
130
|
+
const lines = String(body ?? "").split("\n");
|
|
131
|
+
const out: string[] = [];
|
|
132
|
+
let fence: string | null = null;
|
|
133
|
+
let inList = false;
|
|
134
|
+
|
|
135
|
+
for (const line of lines) {
|
|
136
|
+
if (fence !== null) {
|
|
137
|
+
// A closing fence is the same character, at least as long, alone on its
|
|
138
|
+
// line. Anything else is content.
|
|
139
|
+
const close = line.match(/^\s{0,3}(`{3,}|~{3,})\s*$/);
|
|
140
|
+
out.push("");
|
|
141
|
+
if (close && close[1]![0] === fence[0] && close[1]!.length >= fence.length) fence = null;
|
|
142
|
+
continue;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
const open = line.match(/^\s{0,3}(`{3,}|~{3,})/);
|
|
146
|
+
if (open) {
|
|
147
|
+
fence = open[1]!;
|
|
148
|
+
out.push("");
|
|
149
|
+
continue;
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
if (line.trim() === "") {
|
|
153
|
+
inList = false;
|
|
154
|
+
out.push(line);
|
|
155
|
+
continue;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
// Indentation is checked BEFORE the list marker, and only outside a list.
|
|
159
|
+
// An indented bullet is a nested list item when a list is open and an
|
|
160
|
+
// indented code block when one is not, and the two are the same bytes —
|
|
161
|
+
// the only thing that tells them apart is what came before.
|
|
162
|
+
if (!inList && /^(?: {4,}|\t)/.test(line)) {
|
|
163
|
+
out.push("");
|
|
164
|
+
continue;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
if (/^\s*(?:[-*+]|\d+[.)])\s/.test(line)) {
|
|
168
|
+
inList = true;
|
|
169
|
+
out.push(line);
|
|
170
|
+
continue;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
out.push(line);
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
return out.join("\n");
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/** `## Heading` → its level, or 0 for a line that is not a heading. */
|
|
180
|
+
function headingLevel(line: string): number {
|
|
181
|
+
const m = line.match(/^(#{1,6})\s+\S/);
|
|
182
|
+
return m ? m[1]!.length : 0;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/**
|
|
186
|
+
* The lines under the Success Criteria heading, or null when there is none.
|
|
187
|
+
*
|
|
188
|
+
* Ends at the next heading of the SAME OR HIGHER level, so a `### Phase 2`
|
|
189
|
+
* subsection inside the criteria is kept and the next `## Acceptance` is not.
|
|
190
|
+
*/
|
|
191
|
+
export function successCriteriaSection(body: string): string | null {
|
|
192
|
+
const lines = String(body ?? "").split("\n");
|
|
193
|
+
for (let i = 0; i < lines.length; i++) {
|
|
194
|
+
const level = headingLevel(lines[i]!);
|
|
195
|
+
if (!level) continue;
|
|
196
|
+
if (!/^#{1,6}\s+success\s+criteria\b/i.test(lines[i]!)) continue;
|
|
197
|
+
const taken: string[] = [];
|
|
198
|
+
for (let j = i + 1; j < lines.length; j++) {
|
|
199
|
+
const nextLevel = headingLevel(lines[j]!);
|
|
200
|
+
if (nextLevel > 0 && nextLevel <= level) break;
|
|
201
|
+
taken.push(lines[j]!);
|
|
202
|
+
}
|
|
203
|
+
return taken.join("\n");
|
|
204
|
+
}
|
|
205
|
+
return null;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Is this criterion made of placeholders rather than of a requirement?
|
|
210
|
+
*
|
|
211
|
+
* `SC-N`, `[MARKER-NAME]` and `<thing>` are how this repo writes a TEMPLATE.
|
|
212
|
+
* An AC list consisting of them is the #210 reading exactly, and it reached
|
|
213
|
+
* the point of being briefed.
|
|
214
|
+
*/
|
|
215
|
+
export function isPlaceholder(text: string): boolean {
|
|
216
|
+
const s = String(text ?? "").trim();
|
|
217
|
+
if (!s) return true;
|
|
218
|
+
// SC- followed by anything that is not a digit: SC-N, SC-X, SC-NNN.
|
|
219
|
+
if (/\bSC-(?![0-9])[A-Za-z]/.test(s) && !/\bSC-A\d/.test(s)) return true;
|
|
220
|
+
// A bracketed ALL-CAPS slug, which is this repo's template notation.
|
|
221
|
+
if (/\[[A-Z][A-Z0-9_-]{2,}\]/.test(s)) return true;
|
|
222
|
+
// An angle-bracketed placeholder that is not an HTML tag or an email.
|
|
223
|
+
if (/<[a-z][a-z0-9 _-]*>/i.test(s) && !/<\/|@/.test(s)) return true;
|
|
224
|
+
if (/\b(?:TBD|TODO|FIXME|XXX)\b/.test(s)) return true;
|
|
225
|
+
return false;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
/**
|
|
229
|
+
* Acceptance criteria, from the Success Criteria section only.
|
|
230
|
+
*
|
|
231
|
+
* **Section-scoped, not body-scoped.** The ship skill's own contract says
|
|
232
|
+
* "all lines matching `- [ ] SC-` … under '## Success Criteria'"; the regex
|
|
233
|
+
* it replaced ignored the heading and matched the whole document, so a
|
|
234
|
+
* checklist under "Scope" or "Open questions" was silently promoted to an
|
|
235
|
+
* acceptance criterion (#210).
|
|
236
|
+
*
|
|
237
|
+
* **No section is `[]`, not a refusal.** Most issues in this repo have none,
|
|
238
|
+
* and Discovery authoring the ACs is the designed path. The refusal is for
|
|
239
|
+
* criteria that were found and cannot be briefed.
|
|
240
|
+
*/
|
|
241
|
+
export function extractSuccessCriteria(body: string): CriteriaReading {
|
|
242
|
+
const section = successCriteriaSection(stripCodeBlocks(body));
|
|
243
|
+
if (section === null) {
|
|
244
|
+
return { criteria: [], source: "none", refusal: null };
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
const criteria: string[] = [];
|
|
248
|
+
// `SC-` is required, not decorative. The old pattern's `|.+` branch made
|
|
249
|
+
// every `- [ ]` line qualify, so the prefix tested nothing.
|
|
250
|
+
const line = /^\s*-\s*\[[ xX]\]\s*(.+)$/gm;
|
|
251
|
+
let m: RegExpExecArray | null;
|
|
252
|
+
while ((m = line.exec(section)) !== null) {
|
|
253
|
+
const text = m[1]!.trim();
|
|
254
|
+
if (text) criteria.push(text);
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
if (criteria.length === 0) {
|
|
258
|
+
return { criteria, source: "success-criteria-section", refusal: null };
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
const fake = criteria.filter(isPlaceholder);
|
|
262
|
+
if (fake.length === criteria.length) {
|
|
263
|
+
return {
|
|
264
|
+
criteria: [],
|
|
265
|
+
source: "success-criteria-section",
|
|
266
|
+
refusal:
|
|
267
|
+
`every acceptance criterion read from this issue is a placeholder — ` +
|
|
268
|
+
`${JSON.stringify(fake)}. Briefing an agent with a criterion made of ` +
|
|
269
|
+
`placeholders is worse than briefing it with none, because Discovery ` +
|
|
270
|
+
`writes criteria when there are none and accepts these when there are (#210).`,
|
|
271
|
+
};
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
return { criteria, source: "success-criteria-section", refusal: null };
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/** Does this blockquote carry a marker that makes it harness metadata? */
|
|
278
|
+
function isHarnessBanner(block: string): boolean {
|
|
279
|
+
return HARNESS_BANNER_MARKERS.some(marker => block.includes(marker));
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/**
|
|
283
|
+
* The goal paragraph: the first prose paragraph the author wrote.
|
|
284
|
+
*
|
|
285
|
+
* Steps over a leading blockquote ONLY when it carries a harness banner
|
|
286
|
+
* marker, so an author who opens with a quote keeps their goal (#202 AC-3 —
|
|
287
|
+
* the parser has to be correct for prose it did not write, because consumer
|
|
288
|
+
* repos have their own conventions).
|
|
289
|
+
*/
|
|
290
|
+
export function extractGoal(body: string, title: string): GoalReading {
|
|
291
|
+
const stripped = stripCodeBlocks(body);
|
|
292
|
+
const lines = stripped.split("\n");
|
|
293
|
+
let i = 0;
|
|
294
|
+
let skippedBanner = false;
|
|
295
|
+
|
|
296
|
+
const skipBanner = () => {
|
|
297
|
+
while (i < lines.length && lines[i]!.trim() === "") i++;
|
|
298
|
+
if (i >= lines.length || !/^\s*>/.test(lines[i]!)) return false;
|
|
299
|
+
const start = i;
|
|
300
|
+
while (i < lines.length && (/^\s*>/.test(lines[i]!) || lines[i]!.trim() === "")) {
|
|
301
|
+
// A blank line ends the quote unless the next line resumes it.
|
|
302
|
+
if (lines[i]!.trim() === "" && !/^\s*>/.test(lines[i + 1] ?? "")) break;
|
|
303
|
+
i++;
|
|
304
|
+
}
|
|
305
|
+
const block = lines.slice(start, i).join("\n");
|
|
306
|
+
if (isHarnessBanner(block)) return true;
|
|
307
|
+
i = start; // the author's own quote — keep it
|
|
308
|
+
return false;
|
|
309
|
+
};
|
|
310
|
+
|
|
311
|
+
if (skipBanner()) skippedBanner = true;
|
|
312
|
+
|
|
313
|
+
/** The next paragraph's lines, without consuming them. */
|
|
314
|
+
const peekParagraph = (from: number): { lines: string[]; next: number } => {
|
|
315
|
+
let k = from;
|
|
316
|
+
while (k < lines.length && lines[k]!.trim() === "") k++;
|
|
317
|
+
const taken: string[] = [];
|
|
318
|
+
for (; k < lines.length; k++) {
|
|
319
|
+
if (lines[k]!.trim() === "") break;
|
|
320
|
+
if (headingLevel(lines[k]!) > 0) break;
|
|
321
|
+
taken.push(lines[k]!);
|
|
322
|
+
}
|
|
323
|
+
return { lines: taken, next: k };
|
|
324
|
+
};
|
|
325
|
+
|
|
326
|
+
// Step over harness front matter the same way, and for the same reason. A
|
|
327
|
+
// paragraph counts only if EVERY line is a short marker line, so prose that
|
|
328
|
+
// opens with one of the words is kept.
|
|
329
|
+
for (;;) {
|
|
330
|
+
const { lines: para, next } = peekParagraph(i);
|
|
331
|
+
if (para.length === 0) break;
|
|
332
|
+
const allMetadata = para.every(
|
|
333
|
+
l =>
|
|
334
|
+
l.trim().length <= MAX_PREAMBLE_LINE_CHARS &&
|
|
335
|
+
HARNESS_PREAMBLE_MARKERS.some(marker => l.trim().startsWith(marker)),
|
|
336
|
+
);
|
|
337
|
+
if (!allMetadata) break;
|
|
338
|
+
skippedBanner = true;
|
|
339
|
+
i = next;
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
const paragraph = peekParagraph(i).lines;
|
|
343
|
+
const goal = paragraph.join("\n").trim();
|
|
344
|
+
|
|
345
|
+
if (!goal) {
|
|
346
|
+
return {
|
|
347
|
+
goal: null,
|
|
348
|
+
skippedBanner,
|
|
349
|
+
refusal:
|
|
350
|
+
`this issue body yielded no goal paragraph${skippedBanner ? " after its harness banner" : ""} — ` +
|
|
351
|
+
`the title alone is not a problem statement, and a brief written from it would ` +
|
|
352
|
+
`describe the work by its name rather than by what is wrong (#202).`,
|
|
353
|
+
};
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
if (goal.length < MIN_GOAL_CHARS) {
|
|
357
|
+
return {
|
|
358
|
+
goal: null,
|
|
359
|
+
skippedBanner,
|
|
360
|
+
refusal:
|
|
361
|
+
`the goal paragraph read from this issue is ${goal.length} characters, under the ` +
|
|
362
|
+
`${MIN_GOAL_CHARS} a problem statement needs — ${JSON.stringify(goal)}. A short goal and a ` +
|
|
363
|
+
`missing goal are not the same state, and neither is a goal (#202).`,
|
|
364
|
+
};
|
|
365
|
+
}
|
|
366
|
+
|
|
367
|
+
return { goal, refusal: null, skippedBanner };
|
|
368
|
+
}
|
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Phase 2 issue has to carry the ACs it was given (#79).
|
|
3
|
+
*
|
|
4
|
+
* When discovery produces more than `MAX_ACS_PER_ISSUE` ACs, `workflows/
|
|
5
|
+
* ship.js` asks an agent to group them and open a sub-issue for each group
|
|
6
|
+
* after the first. The agent returns a STRUCTURED list — `{number, phase,
|
|
7
|
+
* acIds}` — and separately writes the issue BODY as free prose. Nothing
|
|
8
|
+
* compared the two.
|
|
9
|
+
*
|
|
10
|
+
* On #70 they disagreed completely. The structured list said:
|
|
11
|
+
*
|
|
12
|
+
* AC-7 a greenfield scaffold writes a roles.json with at least three
|
|
13
|
+
* agent role entries that survive a read-back
|
|
14
|
+
* AC-8 hook registrations stored in hooks.json drive consumer hook
|
|
15
|
+
* deployment under the directory layout
|
|
16
|
+
* AC-9 the existing scaffold and scanner test files still pass
|
|
17
|
+
*
|
|
18
|
+
* and the body of #75 described AC-7/8/9 as doc-path cleanup — a restatement
|
|
19
|
+
* of AC-5, which was already in Phase 1. Both halves are internally
|
|
20
|
+
* plausible: the ids line up, the spec cited is real, the line numbers are
|
|
21
|
+
* real. A human or an agent picking up #75 reads the prose, not the list, so
|
|
22
|
+
* the deferral would have re-fixed Phase 1's work, shipped it as complete,
|
|
23
|
+
* and closed the parent while `roles.json` and `hooks.json` went on being
|
|
24
|
+
* written empty for every greenfield consumer — the defect that opened #70.
|
|
25
|
+
*
|
|
26
|
+
* That is scope loss that LOOKS COMPLETE. The sub-issue exists, is linked to
|
|
27
|
+
* its parent, and has well-formed ACs. Nothing is visibly missing, which is
|
|
28
|
+
* why the fix has to be a comparison rather than a better prompt.
|
|
29
|
+
*
|
|
30
|
+
* WHAT THIS MODULE REFUSES, AND WHY EACH ONE IS SEPARATE
|
|
31
|
+
*
|
|
32
|
+
* `decompositionRefusal` reads the structure alone; `phase2BodyViolations`
|
|
33
|
+
* reads a body against the ACs it is supposed to carry. They are separate
|
|
34
|
+
* because they fail separately: a grouping can be sound and the body still
|
|
35
|
+
* describe something else (#70's case), and a body can quote its ACs
|
|
36
|
+
* perfectly while the grouping has silently dropped one.
|
|
37
|
+
*
|
|
38
|
+
* Every refusal here is a refusal rather than a repair. A decomposition the
|
|
39
|
+
* harness "fixes" is an acceptance criterion nobody reviewed, which is the
|
|
40
|
+
* #217 lesson one layer up.
|
|
41
|
+
*/
|
|
42
|
+
|
|
43
|
+
/** An AC as discovery produced it. `statement` is the text that must survive. */
|
|
44
|
+
export interface DecomposedAc {
|
|
45
|
+
id: string;
|
|
46
|
+
statement: string;
|
|
47
|
+
specElement?: string;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** One group the decompose agent proposed. `number` is set once it exists. */
|
|
51
|
+
export interface SubIssuePlan {
|
|
52
|
+
number?: number;
|
|
53
|
+
phase?: string;
|
|
54
|
+
acIds?: string[];
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Everything wrong with a proposed decomposition, or an empty list.
|
|
59
|
+
*
|
|
60
|
+
* Returns a LIST, not a boolean or a first error: a decomposition that drops
|
|
61
|
+
* one AC and duplicates another has two problems, and reporting one of them
|
|
62
|
+
* invites a second round that discovers the other.
|
|
63
|
+
*/
|
|
64
|
+
export function decompositionRefusal(
|
|
65
|
+
allAcs: readonly DecomposedAc[] | null | undefined,
|
|
66
|
+
phase1AcIds: readonly string[] | null | undefined,
|
|
67
|
+
subIssues: readonly SubIssuePlan[] | null | undefined,
|
|
68
|
+
): string[] {
|
|
69
|
+
const acs = Array.isArray(allAcs) ? allAcs : [];
|
|
70
|
+
const phase1 = Array.isArray(phase1AcIds) ? phase1AcIds : [];
|
|
71
|
+
const groups = Array.isArray(subIssues) ? subIssues : [];
|
|
72
|
+
const out: string[] = [];
|
|
73
|
+
|
|
74
|
+
if (acs.length === 0) return ["decomposition was asked for with no ACs to decompose"];
|
|
75
|
+
|
|
76
|
+
const known = new Set<string>();
|
|
77
|
+
for (const ac of acs) {
|
|
78
|
+
if (ac?.id) known.add(ac.id);
|
|
79
|
+
if (ac?.specElement) for (const s of ac.specElement.split(",")) known.add(s.trim());
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
// Phase 1 holding nothing is not a decomposition, it is a deferral of the
|
|
83
|
+
// whole issue — and it reads as success because sub-issues were created.
|
|
84
|
+
if (phase1.length === 0) out.push("no AC was kept for Phase 1 — the whole issue was deferred");
|
|
85
|
+
|
|
86
|
+
for (const id of phase1) {
|
|
87
|
+
if (!known.has(id)) out.push(`Phase 1 keeps ${id}, which discovery never produced`);
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** Which groups claim each id — the shape both duplicate cases need. */
|
|
91
|
+
const claimedBy = new Map<string, string[]>();
|
|
92
|
+
for (const [i, g] of groups.entries()) {
|
|
93
|
+
const label = g?.number ? `#${g.number}` : (g?.phase || `group ${i + 1}`);
|
|
94
|
+
const ids = Array.isArray(g?.acIds) ? g.acIds : [];
|
|
95
|
+
if (ids.length === 0) out.push(`${label} was created carrying no ACs`);
|
|
96
|
+
for (const id of ids) {
|
|
97
|
+
if (!known.has(id)) out.push(`${label} claims ${id}, which discovery never produced`);
|
|
98
|
+
claimedBy.set(id, [...(claimedBy.get(id) ?? []), label]);
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
// AC-3. The #70 failure mode exactly: a deferred AC that restates one
|
|
103
|
+
// already being shipped. Flagged, never written.
|
|
104
|
+
const phase1Set = new Set(phase1);
|
|
105
|
+
for (const [id, labels] of claimedBy) {
|
|
106
|
+
if (phase1Set.has(id)) {
|
|
107
|
+
out.push(`${id} is in Phase 1 AND deferred to ${labels.join(" and ")} — a deferral that duplicates shipped work`);
|
|
108
|
+
}
|
|
109
|
+
if (labels.length > 1) {
|
|
110
|
+
out.push(`${id} is claimed by ${labels.join(" and ")} — two phases cannot both own one AC`);
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
// The silent half. An AC in neither Phase 1 nor any sub-issue has been
|
|
115
|
+
// dropped, and every count the run prints still adds up.
|
|
116
|
+
for (const ac of acs) {
|
|
117
|
+
const ids: string[] = [ac.id, ...(ac.specElement ? ac.specElement.split(",").map((s: string) => s.trim()) : [])].filter(Boolean);
|
|
118
|
+
const placed = ids.some(id => phase1Set.has(id) || claimedBy.has(id));
|
|
119
|
+
if (!placed) out.push(`${ac.id} was neither kept nor deferred — it is gone, and nothing else would say so`);
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
return out;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* The ACs one group owns, in discovery's order.
|
|
127
|
+
*
|
|
128
|
+
* One function, so the body comparison and the issue that was created cannot
|
|
129
|
+
* disagree about which ACs belong to a group. Matches on `id` or on any
|
|
130
|
+
* comma-separated `specElement`, because the decompose agent returns either
|
|
131
|
+
* — the same tolerance `workflows/ship.js` already applies when it filters
|
|
132
|
+
* Phase 1, and splitting it in two is how the two would drift.
|
|
133
|
+
*/
|
|
134
|
+
export function acsForGroup(
|
|
135
|
+
acs: readonly DecomposedAc[] | null | undefined,
|
|
136
|
+
group: SubIssuePlan | null | undefined,
|
|
137
|
+
): DecomposedAc[] {
|
|
138
|
+
const ids = new Set<string>(Array.isArray(group?.acIds) ? group!.acIds : []);
|
|
139
|
+
if (ids.size === 0) return [];
|
|
140
|
+
// Annotated because `Array.isArray` narrows a `readonly T[]` to `any[]`,
|
|
141
|
+
// and an `any` here would silently turn every field access below into an
|
|
142
|
+
// unchecked one.
|
|
143
|
+
const list: readonly DecomposedAc[] = Array.isArray(acs) ? acs : [];
|
|
144
|
+
return list.filter(ac => {
|
|
145
|
+
if (ids.has(ac.id)) return true;
|
|
146
|
+
if (!ac.specElement) return false;
|
|
147
|
+
return ac.specElement.split(",").some((s: string) => ids.has(s.trim()));
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* Wrap a string so a POSIX shell passes it through untouched.
|
|
153
|
+
*
|
|
154
|
+
* AC statements routinely contain backticks, double quotes and `$`. A
|
|
155
|
+
* single-quoted shell word is literal for every character except `'`, which
|
|
156
|
+
* is closed, escaped and reopened. This is the only quoting in the data path
|
|
157
|
+
* and it exists because the reference copy of the statements must reach disk
|
|
158
|
+
* WITHOUT passing through the model — a model that reworded both the body
|
|
159
|
+
* and the thing the body is compared against would pass any comparison.
|
|
160
|
+
*/
|
|
161
|
+
export function shellSingleQuote(value: string): string {
|
|
162
|
+
return `'${String(value).replace(/'/g, `'\\''`)}'`;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* The AC list as it appears in the decompose prompt.
|
|
167
|
+
*
|
|
168
|
+
* The prompt used to list no ACs at all, so the agent wrote each sub-issue
|
|
169
|
+
* body by reconstructing the scope from memory — which is exactly how #75's
|
|
170
|
+
* body came to describe Phase 1's work. The statements are now in front of
|
|
171
|
+
* it, verbatim, in the form it is asked to copy.
|
|
172
|
+
*/
|
|
173
|
+
export function acListBlock(acs: readonly DecomposedAc[]): string {
|
|
174
|
+
return acs.map(ac => `- [ ] ${ac.id}: ${ac.statement}`).join("\n");
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* The command that writes the comparison's reference copy of the ACs.
|
|
179
|
+
*
|
|
180
|
+
* Emitted into the prompt for the agent to run verbatim, the way every other
|
|
181
|
+
* `bun -e` in this workflow is. The payload is the harness's own validated
|
|
182
|
+
* discovery output, shell-quoted here rather than composed by the model.
|
|
183
|
+
*/
|
|
184
|
+
export function phase2AcsCommand(harnessRoot: string, workDir: string, acs: readonly DecomposedAc[]): string {
|
|
185
|
+
const payload = JSON.stringify(acs.map(a => ({ id: a.id, statement: a.statement, specElement: a.specElement })));
|
|
186
|
+
return (
|
|
187
|
+
`cd ${harnessRoot} && bun -e 'require("fs").writeFileSync(process.argv[1], process.argv[2])' ` +
|
|
188
|
+
`${workDir}/phase2-acs.json ${shellSingleQuote(payload)}`
|
|
189
|
+
);
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/** The heading the comparison reads under. Must match what the prompt asks for. */
|
|
193
|
+
export const SC_HEADING = "## Success Criteria";
|
|
194
|
+
|
|
195
|
+
/**
|
|
196
|
+
* Normalise for comparison WITHOUT making the comparison meaningless.
|
|
197
|
+
*
|
|
198
|
+
* Markdown wraps, so a statement written across two lines is the same
|
|
199
|
+
* statement; collapsing runs of whitespace is therefore required rather than
|
|
200
|
+
* lenient. Nothing else is touched — not case, not punctuation, not the
|
|
201
|
+
* backticks around an identifier. A looser comparison here is how a body
|
|
202
|
+
* that paraphrases its AC would start passing, which is the whole defect.
|
|
203
|
+
*/
|
|
204
|
+
function normalise(text: string): string {
|
|
205
|
+
return text.replace(/\s+/g, " ").trim();
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Everything wrong with a Phase 2 body, given the ACs it is supposed to carry.
|
|
210
|
+
*
|
|
211
|
+
* Covers #79 AC-1 (same ids) and AC-2 (statements verbatim, by string
|
|
212
|
+
* equality after whitespace collapsing). The id check alone would have passed
|
|
213
|
+
* #75 — its body listed AC-7, AC-8 and AC-9 — so the statement check is the
|
|
214
|
+
* load-bearing half and the id check is there for the case where a body
|
|
215
|
+
* silently carries one fewer.
|
|
216
|
+
*/
|
|
217
|
+
export function phase2BodyViolations(
|
|
218
|
+
body: string | null | undefined,
|
|
219
|
+
acs: readonly DecomposedAc[] | null | undefined,
|
|
220
|
+
): string[] {
|
|
221
|
+
const text = typeof body === "string" ? body : "";
|
|
222
|
+
const expected = Array.isArray(acs) ? acs : [];
|
|
223
|
+
const out: string[] = [];
|
|
224
|
+
|
|
225
|
+
if (expected.length === 0) return ["no ACs were supplied to compare the body against"];
|
|
226
|
+
if (normalise(text) === "") return ["the issue body is empty"];
|
|
227
|
+
|
|
228
|
+
const headingAt = text.indexOf(SC_HEADING);
|
|
229
|
+
if (headingAt < 0) {
|
|
230
|
+
return [`the body has no "${SC_HEADING}" section, so there is nothing to compare the AC list against`];
|
|
231
|
+
}
|
|
232
|
+
// Everything from the heading to the next H2, which is the section the
|
|
233
|
+
// prompt asks for. Reading the WHOLE body would let an AC id mentioned in
|
|
234
|
+
// passing somewhere else satisfy the check.
|
|
235
|
+
const rest = text.slice(headingAt + SC_HEADING.length);
|
|
236
|
+
const nextH2 = rest.search(/^## /m);
|
|
237
|
+
const section = nextH2 < 0 ? rest : rest.slice(0, nextH2);
|
|
238
|
+
const flat = normalise(section);
|
|
239
|
+
|
|
240
|
+
for (const ac of expected) {
|
|
241
|
+
if (!new RegExp(`(^|[^A-Za-z0-9-])${ac.id}([^A-Za-z0-9-]|$)`).test(flat)) {
|
|
242
|
+
out.push(`${ac.id} is in the deferred list and not in the body's ${SC_HEADING} section`);
|
|
243
|
+
continue;
|
|
244
|
+
}
|
|
245
|
+
const statement = normalise(ac.statement ?? "");
|
|
246
|
+
if (statement === "") {
|
|
247
|
+
out.push(`${ac.id} has no statement in discovery, so the body cannot be checked against it`);
|
|
248
|
+
continue;
|
|
249
|
+
}
|
|
250
|
+
if (!flat.includes(statement)) {
|
|
251
|
+
out.push(
|
|
252
|
+
`${ac.id}'s statement is not carried verbatim. discovery: "${statement}" — ` +
|
|
253
|
+
`the body describes something else, which is #70's defect: the ids lined up and the work did not`,
|
|
254
|
+
);
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
// The other direction. A body carrying an id that was never deferred to it
|
|
259
|
+
// is the #75 shape read from the body's side: plausible, well-formed, and
|
|
260
|
+
// about different work.
|
|
261
|
+
const expectedIds = new Set(expected.map(a => a.id));
|
|
262
|
+
for (const found of flat.matchAll(/(?:^|[^A-Za-z0-9-])(AC-\d+)(?![A-Za-z0-9-])/g)) {
|
|
263
|
+
const id = found[1]!;
|
|
264
|
+
if (!expectedIds.has(id)) {
|
|
265
|
+
out.push(`the body's ${SC_HEADING} section lists ${id}, which was not deferred to this issue`);
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
return out;
|
|
270
|
+
}
|
package/lib/prior-branch.ts
CHANGED
|
@@ -120,7 +120,30 @@ export function issueReference(issueNumber: number): (text: unknown) => boolean
|
|
|
120
120
|
`issueReference needs a non-negative integer issue number, got ${JSON.stringify(issueNumber)}`,
|
|
121
121
|
)
|
|
122
122
|
}
|
|
123
|
-
|
|
123
|
+
// The bound is on HEX digits and `_`, not on decimal digits alone (#433).
|
|
124
|
+
//
|
|
125
|
+
// `[^\d]` was right about the case it was written for — it stops `55`
|
|
126
|
+
// matching `550` — and wrong about the case this repo actually generates.
|
|
127
|
+
// Workflow fan-out branches are named `worktree-wf_<runid>-<n>` with a hex
|
|
128
|
+
// run id, and in `worktree-wf_55baa4aa-a00-9` the `55` is preceded by `_`
|
|
129
|
+
// and followed by `b`. Both are non-digits, so it matched, and
|
|
130
|
+
// `detectPriorBranch` reported a stranger's fan-out worktree as issue 55's
|
|
131
|
+
// prior work. There were 149 such branches here when this was found.
|
|
132
|
+
//
|
|
133
|
+
// The bound is `\b`, which is what "word-boundary matching" meant all
|
|
134
|
+
// along. A hand-rolled hex class was tried first and a mutation scored
|
|
135
|
+
// ZERO against widening it to all letters — the fixtures could not tell
|
|
136
|
+
// the two apart, because every real form separates the number with
|
|
137
|
+
// punctuation. The zero was the finding: the narrower class was buying
|
|
138
|
+
// nothing over the broader one, and `\b` IS the broader one, already
|
|
139
|
+
// treating `_` and every letter as a word character.
|
|
140
|
+
//
|
|
141
|
+
// `\b55\b` rejects `worktree-wf_55baa4aa-a00-9` (`_` and `b` are word
|
|
142
|
+
// characters, so neither side is a boundary) and `550-matcher-registry`
|
|
143
|
+
// (`0` likewise), and accepts `209-deep-modules`, `fix/55`, `Closes #209`
|
|
144
|
+
// and `fix(#209):`. All of them are asserted in
|
|
145
|
+
// test/prior-branch-reference.test.ts rather than trusted to this comment.
|
|
146
|
+
const pattern = new RegExp(`\\b${issueNumber}\\b`)
|
|
124
147
|
return (text: unknown) => typeof text === 'string' && pattern.test(text)
|
|
125
148
|
}
|
|
126
149
|
|