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,240 @@
1
+ /**
2
+ * Increment 1 of `specs/BOARD-FLOW-SPEC.md`: drive ONE throwaway issue through
3
+ * every lane on REAL events and record what each lane did.
4
+ *
5
+ * ## Why this is an instrument and not a fix
6
+ *
7
+ * The outcome row it moves has no baseline, because nothing in this repository
8
+ * can observe a lane transition. Eight `test/board-*.test.ts` files assert
9
+ * functions against fixtures and **zero** drive a real event. That is how six
10
+ * consecutive faults in the Ready lane were each reported as fixed by somebody
11
+ * reading a diff: #1744, the wrong secret name, #1761, #1765, #1766 and the
12
+ * node-limit refusal in #1768. Four of them exited zero.
13
+ *
14
+ * So this file decides nothing about readiness and repairs nothing. It
15
+ * observes, and it refuses to call an unobserved lane working.
16
+ *
17
+ * ## The two verdicts that are not pass or fail
18
+ *
19
+ * Two lanes have no writer today, and the walk-through ships RED on those rows
20
+ * deliberately — a failing row naming the lane that did not move is worth more
21
+ * than the absence of a test. That needs a verdict that is not "fail", or the
22
+ * suite is red forever and stops being read.
23
+ *
24
+ * It also needs the opposite, and this is the half that is easy to forget:
25
+ * when a row marked `expectedRed` starts PASSING, that is the single most
26
+ * informative reading this instrument can produce — a lane began working and
27
+ * nobody has to be told. `UNEXPECTED_PASS` exists so that event cannot be
28
+ * silently absorbed into a green run. Without it, the day In progress starts
29
+ * working looks exactly like every day before it.
30
+ *
31
+ * ## The bounded wait is not a retry
32
+ *
33
+ * A lane that has not moved inside its wait is a FAILURE. Retrying until it
34
+ * moves converts "the writer is broken" into "the writer is slow", which is
35
+ * the sixth shape in `.claude/rules/checks-must-be-able-to-fail.md`: green on
36
+ * a signal that two different mechanisms produce.
37
+ */
38
+
39
+ /** The lanes this board has, plus the reading for an item on no board. */
40
+ export type Lane =
41
+ | "Backlog"
42
+ | "Ready"
43
+ | "In progress"
44
+ | "In review"
45
+ | "Done"
46
+ | "Cancelled"
47
+ | "(absent)";
48
+
49
+ export interface Step {
50
+ /** Row number in the spec's Increment 1 table. */
51
+ readonly n: number;
52
+ /** The real event performed, in the words the spec uses. */
53
+ readonly action: string;
54
+ /** The lane the item must be in afterwards. */
55
+ readonly expect: Lane;
56
+ /** What should have performed the move. `null` means nothing exists yet. */
57
+ readonly writer: string | null;
58
+ }
59
+
60
+ /**
61
+ * The six rows of Increment 1, plus the negative control.
62
+ *
63
+ * **The negative control is not optional.** Without row 7 the whole
64
+ * walk-through passes against a board that moves everything to Ready
65
+ * unconditionally — which is a board that lies in the other direction, and
66
+ * an instrument that cannot tell the two apart is measuring nothing.
67
+ */
68
+ /**
69
+ * **Rows 3 to 6 gained a writer on 2026-11-05, and these are the readings
70
+ * that say so.** Run `42124533332` reported rows 3 and 6 as
71
+ * `UNEXPECTED_PASS` — "expected RED and PASSED" — because this table still
72
+ * said nothing wrote them, which is the walk-through correctly refusing to
73
+ * let a silent improvement go unrecorded.
74
+ *
75
+ * The attribution below is not inferred from the merge of #1781. It is read
76
+ * from the logs of the four `board-flow.yml` runs that fired during that
77
+ * walk-through, each line a read-back after the write:
78
+ *
79
+ * 42124868007 #1787 -> "In progress" (assignment is this repository's declared starting act)
80
+ * 42124912993 #1787 -> "In review" (a non-draft pull request is finished work waiting on a reviewer)
81
+ * 42125576799 #1787 -> "Done" (closed as completed)
82
+ * 42125611826 #1789 -> "Cancelled" (closed as not_planned)
83
+ *
84
+ * Rows 4 and 5 used to read `GitHub native` and that is now wrong in a way
85
+ * worth naming: the built-ins that once covered them — "Pull request linked
86
+ * to issue" and "Item closed" — are both SWITCHED OFF, and run `42125045931`
87
+ * shows the merged pull request's own event declining with "no lane
88
+ * transition here". The issue's close is what writes Done.
89
+ *
90
+ * Only rows 1 and 7 are still GitHub's: the "Item added to project"
91
+ * built-in, which puts a new card in Backlog.
92
+ */
93
+ export const WALKTHROUGH_STEPS: readonly Step[] = [
94
+ { n: 1, action: "create issue A, and issue B blocked by A", expect: "Backlog", writer: "GitHub native" },
95
+ { n: 2, action: "close A", expect: "Ready", writer: "board-ready.yml" },
96
+ { n: 3, action: "B is started", expect: "In progress", writer: "board-flow.yml" },
97
+ { n: 4, action: "open a PR saying Fixes #B", expect: "In review", writer: "board-flow.yml" },
98
+ { n: 5, action: "merge the PR", expect: "Done", writer: "board-flow.yml" },
99
+ { n: 6, action: "close issue C as not_planned", expect: "Cancelled", writer: "board-flow.yml" },
100
+ { n: 7, action: "NEGATIVE CONTROL — D is blocked by an OPEN issue", expect: "Backlog", writer: "GitHub native" },
101
+ ];
102
+
103
+ /**
104
+ * `UNMEASURED` is the fourth verdict, and it is not a flag on `FAIL`.
105
+ *
106
+ * `ai-review` finding `04843009` on PR #1772: a row whose EVENT never
107
+ * happened was being recorded as a lane failure. A throwaway pull request
108
+ * that branch protection would not merge inside its budget made row 5 read
109
+ * "the Done writer did not move", naming a writer that was never given an
110
+ * event. The driver printed a warning saying exactly that, and the warning
111
+ * did not correct the verdict — **prose beside a reading is not a reading.**
112
+ *
113
+ * The two have opposite remedies, which is why they cannot share a value:
114
+ * `FAIL` means fix the writer, `UNMEASURED` means run it again with a bigger
115
+ * budget. Collapsing them sends every reader to the wrong place.
116
+ */
117
+ export type Verdict = "PASS" | "FAIL" | "EXPECTED_RED" | "UNEXPECTED_PASS" | "UNMEASURED";
118
+
119
+ /**
120
+ * What one row's reading means.
121
+ *
122
+ * `writer === null` is the whole of "expected red" — it is derived from the
123
+ * step rather than carried as a second field, so a row cannot claim to be
124
+ * expected-red while naming a writer that is supposed to exist. One fact, one
125
+ * place: the alternative is two fields that can disagree, and the disagreement
126
+ * reads as a tolerated failure.
127
+ */
128
+ export function stepVerdict(step: Step, observed: Lane): Verdict {
129
+ const matched = observed === step.expect;
130
+ const hasWriter = step.writer !== null;
131
+ if (matched) return hasWriter ? "PASS" : "UNEXPECTED_PASS";
132
+ return hasWriter ? "FAIL" : "EXPECTED_RED";
133
+ }
134
+
135
+ export interface Reading {
136
+ readonly step: Step;
137
+ readonly observed: Lane;
138
+ readonly verdict: Verdict;
139
+ /** True when the bounded wait expired without the lane reaching `expect`. */
140
+ readonly waitExpired: boolean;
141
+ /** Why this row measured nothing. Only ever set on an `UNMEASURED` row. */
142
+ readonly why?: string;
143
+ }
144
+
145
+ /**
146
+ * A row whose triggering event never happened.
147
+ *
148
+ * The lane is `(absent)` because nothing was observed — not because the item
149
+ * was off the board. The caller must say WHY in one clause, and the report
150
+ * prints it: "row 5 UNMEASURED" with no reason is the same dead end as the
151
+ * stack trace this driver used to produce.
152
+ */
153
+ export function unmeasuredReading(step: Step, why: string): Reading {
154
+ return { step, observed: "(absent)", verdict: "UNMEASURED", waitExpired: false, why };
155
+ }
156
+
157
+ /**
158
+ * The run's exit verdict.
159
+ *
160
+ * Only a `FAIL` fails the run. `EXPECTED_RED` is the declared state of a lane
161
+ * with no writer, and failing on it would make the walk-through unmergeable
162
+ * for exactly as long as the gaps it documents remain open — so it would be
163
+ * deleted rather than fixed.
164
+ *
165
+ * An empty reading list REFUSES. Zero rows produce zero failures, and a
166
+ * walk-through that drove nothing must never be the same reading as a
167
+ * walk-through where every lane worked.
168
+ *
169
+ * ## `abortedAt` was added because the refusal above was unreachable
170
+ *
171
+ * The first real dispatch (run `42092949455`) died on `404 POST /issues`
172
+ * and printed a Bun stack trace. The UNMEASURED branch directly above is
173
+ * tested and correct, and nothing in the program could reach it: the throw
174
+ * escaped the driver's `try` and the process ended before any verdict was
175
+ * computed. A case that proves a function refuses proves nothing about
176
+ * whether the program asks it to.
177
+ *
178
+ * An abort is a THIRD state, not a flavour of the first two. Four rows
179
+ * observed and then a throw is a partial measurement, and the verdict says
180
+ * both halves — which act died, and how many rows survived it — because
181
+ * otherwise the next reader has to re-run the whole thing to find out.
182
+ */
183
+ export function runVerdict(
184
+ readings: readonly Reading[],
185
+ abortedAt?: string,
186
+ ): {
187
+ readonly ok: boolean;
188
+ readonly why: string;
189
+ } {
190
+ if (abortedAt !== undefined) {
191
+ return {
192
+ ok: false,
193
+ why:
194
+ `UNMEASURED — the run died performing "${abortedAt}". ${readings.length} row(s) ` +
195
+ `were observed before it, and every lane after it is unmeasured rather than working`,
196
+ };
197
+ }
198
+ if (readings.length === 0) {
199
+ return { ok: false, why: "UNMEASURED — no step produced a reading, so nothing was observed" };
200
+ }
201
+ const failed = readings.filter(r => r.verdict === "FAIL");
202
+ if (failed.length > 0) {
203
+ const lanes = failed.map(r => `row ${r.step.n} (${r.step.expect}, writer ${r.step.writer})`);
204
+ return { ok: false, why: `a lane with a writer did not move: ${lanes.join("; ")}` };
205
+ }
206
+ // Checked AFTER failures, because a real lane failure is the more
207
+ // actionable finding and should be the headline when both are present.
208
+ // But an unmeasured row still refuses: a walk-through that did not
209
+ // observe Done has not shown Done works, and reporting that as success is
210
+ // the whole defect class this file exists inside.
211
+ const unmeasured = readings.filter(r => r.verdict === "UNMEASURED");
212
+ if (unmeasured.length > 0) {
213
+ const rows = unmeasured.map(r => `row ${r.step.n} (${r.step.expect}: ${r.why ?? "no reason given"})`);
214
+ return {
215
+ ok: false,
216
+ why:
217
+ `UNMEASURED — the event never happened for ${rows.join("; ")}. ` +
218
+ `This is not a lane failure; the writer was never given anything to react to`,
219
+ };
220
+ }
221
+ return { ok: true, why: `${readings.length} rows observed, no lane with a writer failed to move` };
222
+ }
223
+
224
+ /**
225
+ * The lines a run prints. Separated from the driver so the report itself can
226
+ * be asserted: a report that omits a row is the failure mode this whole
227
+ * increment exists to catch, and it is invisible if the formatting lives
228
+ * inside the I/O.
229
+ */
230
+ export function reportLines(readings: readonly Reading[]): string[] {
231
+ return readings.map(r => {
232
+ const wait = r.waitExpired ? " [bounded wait expired — a failure, not a retry]" : "";
233
+ const writer = r.step.writer ?? "NOTHING WRITES THIS LANE YET";
234
+ // The reason rides on the row rather than on a separate warning line,
235
+ // because a warning printed somewhere else in the log is how row 5 came
236
+ // to carry a verdict its own warning contradicted.
237
+ const why = r.why === undefined ? "" : ` [${r.why}]`;
238
+ return `row ${r.step.n} ${r.verdict.padEnd(15)} expected ${r.step.expect}, observed ${r.observed} — ${writer}${wait}${why}`;
239
+ });
240
+ }
@@ -0,0 +1,203 @@
1
+ /**
2
+ * Compare the figures in a pull request body against the suite run they claim
3
+ * to report (#1817).
4
+ *
5
+ * ## What this is for
6
+ *
7
+ * A measurement typed into a pull request body is a SECOND COPY of a number
8
+ * that already exists somewhere authoritative, and nothing in this repository
9
+ * compared the two. So the copy goes stale silently: the source is corrected,
10
+ * the body is not, and a reader has no way to tell which of the two is
11
+ * current. Every recorded instance has that shape — a figure read once off a
12
+ * summary, typed into prose, and never compared again.
13
+ *
14
+ * The write half of the problem was solved long ago and is worth reading
15
+ * before changing anything here, because it already refused the two obvious
16
+ * wrong answers: `scripts/record-suite-measurement.ts` has no `--failures`
17
+ * and no `--sha`, by name, because "a caller-supplied count" and "a
18
+ * caller-supplied commit" are both the comparison quietly answering itself.
19
+ * This module is the read half, and it inherits that rule: it never accepts a
20
+ * count as an argument. It accepts the RUN, parsed from the runner's own
21
+ * output by `lib/suite-run-reading.ts`.
22
+ *
23
+ * ## The rule, and why it is the weakest one that works
24
+ *
25
+ * The measured figure must appear somewhere among the body's figures
26
+ * of the same kind.
27
+ *
28
+ * Three stronger rules were considered and each is wrong:
29
+ *
30
+ * - *"The body must carry an evidence block."* That is a different issue. A
31
+ * body making no numeric claim has nothing to be wrong about, so AC-4
32
+ * pins silence as clean. A check that also demands evidence would be two
33
+ * deciders in one function and only one of them would be this one.
34
+ * - *"Every figure in the body must be current."* This refuses the normal
35
+ * spelling of a fix — `3 fail` before, `0 fail` after — and a guard that
36
+ * fires on correct bodies is a guard people switch off.
37
+ * - *"The figures must match in order/position."* Position is formatting, and
38
+ * a detector that a reformat defeats is the second shape in
39
+ * `.claude/rules/checks-must-be-able-to-fail.md`.
40
+ *
41
+ * Presence is what separates them. `1450 pass` over a run that measured 1283
42
+ * is refused because 1283 appears nowhere; `0 fail` beside `3 fail` over a
43
+ * clean run clears because 0 is there.
44
+ *
45
+ * ## The boundary this does not cover, stated rather than implied
46
+ *
47
+ * It reads `pass` and `fail` counts and nothing else. A coverage percentage, a
48
+ * byte count, a round count, a duration — all are the same defect in the same
49
+ * place and none is detected here. They are not a TODO hidden in a comment:
50
+ * widening the detector widens the false-positive surface onto every number in
51
+ * a body, and the counts are the population every recorded instance came from.
52
+ * A new kind should arrive with its own authoritative source to compare
53
+ * against, the way this one has `readSuiteRun`.
54
+ *
55
+ * It also cannot see a figure that is wrong in a way the run agrees with —
56
+ * two runs of the same suite at different commits both measuring 1283 are
57
+ * indistinguishable here. `lib/suite-measurement.ts` binds a count to the SHA
58
+ * it was measured at; that is the guard for currency, and this is the guard
59
+ * for agreement. Neither subsumes the other.
60
+ */
61
+ import type { SuiteRun } from "./suite-run-reading";
62
+
63
+ /**
64
+ * The one non-zero exit for this check.
65
+ *
66
+ * Exported, and the only place the value is written, so a mutation has a
67
+ * single site to flip and no refusal can bypass it by inlining a literal —
68
+ * `.claude/rules/checks-must-be-able-to-fail.md`.
69
+ */
70
+ export const BODY_EVIDENCE_EXIT = 1;
71
+
72
+ /** Which count a violation is about. */
73
+ export type EvidenceKind = "pass" | "fail" | "unmeasured";
74
+
75
+ export interface EvidenceViolation {
76
+ kind: EvidenceKind;
77
+ /** What the run actually measured, or null when there was no reading. */
78
+ measured: number | null;
79
+ /** Every figure of this kind the body stated, in the order it stated them. */
80
+ stated: number[];
81
+ /** A sentence carrying both numbers, because a reader must be able to act on it. */
82
+ message: string;
83
+ }
84
+
85
+ /**
86
+ * The spellings counted as a claim about a count.
87
+ *
88
+ * Deliberately a closed, short list rather than "a number near the word".
89
+ * `fail\b` does not match `failures`, so the suffixes are written out; adding
90
+ * one is a decision about the false-positive surface, not a typo fix.
91
+ */
92
+ const PATTERNS: Record<"pass" | "fail", RegExp> = {
93
+ pass: /(\d[\d,]*)\s+pass(?:es|ed|ing)?\b/gi,
94
+ fail: /(\d[\d,]*)\s+fail(?:s|ed|ing|ure|ures)?\b/gi,
95
+ };
96
+
97
+ /** Every figure of one kind stated in the body, in document order. */
98
+ export function statedCounts(body: string, kind: "pass" | "fail"): number[] {
99
+ const re = new RegExp(PATTERNS[kind].source, PATTERNS[kind].flags);
100
+ const out: number[] = [];
101
+ for (const m of body.matchAll(re)) {
102
+ const n = Number(m[1].replaceAll(",", ""));
103
+ if (Number.isFinite(n)) out.push(n);
104
+ }
105
+ return out;
106
+ }
107
+
108
+ /**
109
+ * The disagreements between a body's figures and the run it reports.
110
+ *
111
+ * THE one decider. Everything else in this module renders or wraps it, so
112
+ * there is a single binding to mutate and no second place that can hold a
113
+ * case up after the first regresses.
114
+ */
115
+ export function bodyEvidenceViolations(body: string, run: SuiteRun): EvidenceViolation[] {
116
+ const pass = statedCounts(body, "pass");
117
+ const fail = statedCounts(body, "fail");
118
+
119
+ // No claim, nothing to disagree with. This is the one case where silence is
120
+ // genuinely clean rather than merely unmeasured: the body asserts nothing.
121
+ if (pass.length === 0 && fail.length === 0) return [];
122
+
123
+ // A body full of figures over a run that produced no reading must NOT clear.
124
+ // "The result agreed" and "there was no result" are different facts, and
125
+ // only one of them is reportable — .claude/rules/config-access.md.
126
+ if (run.status === "UNMEASURED") {
127
+ return [
128
+ {
129
+ kind: "unmeasured",
130
+ measured: null,
131
+ stated: [...pass, ...fail],
132
+ message:
133
+ `the body states ${pass.length + fail.length} count(s) but the run is ` +
134
+ `UNMEASURED (${run.reason}), so there is nothing to compare them against. ` +
135
+ `A body cannot be cleared by a reading that was never taken.`,
136
+ },
137
+ ];
138
+ }
139
+
140
+ const out: EvidenceViolation[] = [];
141
+ for (const [kind, stated, measured] of [
142
+ ["pass", pass, run.pass],
143
+ ["fail", fail, run.fail],
144
+ ] as const) {
145
+ if (stated.length === 0) continue;
146
+ if (stated.includes(measured)) continue;
147
+ out.push({
148
+ kind,
149
+ measured,
150
+ stated,
151
+ message:
152
+ `the body states ${stated.join(", ")} ${kind}, and the run measured ` +
153
+ `${measured} ${kind}. The measured figure appears nowhere in the body, so ` +
154
+ `every ${kind} count in it is a second copy of a number nothing agrees with. ` +
155
+ `Quote the run, or re-run and quote that.`,
156
+ });
157
+ }
158
+ return out;
159
+ }
160
+
161
+ /**
162
+ * The evidence block to paste, composed from the run rather than typed.
163
+ *
164
+ * A block this renders must always clear `bodyEvidenceViolations` against the
165
+ * same run — asserted, not assumed, because an honest path that produces a
166
+ * violation is how a guard gets disabled.
167
+ */
168
+ export function renderEvidenceBlock(run: SuiteRun): string {
169
+ if (run.status === "UNMEASURED") {
170
+ // The reason is NOT interpolated, and that is the whole of #1819's second
171
+ // finding. `readSuiteRun` builds an unmeasured reason that quotes the
172
+ // runner's last output, so the reason is attacker-shaped free text — and
173
+ // an input as ordinary as `some harness note: 0 failing checks so far`
174
+ // produces an UNMEASURED run whose reason contains `0 failing`. Embedding
175
+ // it here put a figure-shaped phrase inside a block destined for a pull
176
+ // request body, and `bodyEvidenceViolations` then refused the block its
177
+ // own renderer had just written.
178
+ //
179
+ // Measured before the fix: violations 1, kind `unmeasured`. The composer
180
+ // and the checker disagreed about a block neither a human nor an agent
181
+ // had touched, which is the precise way an honest path teaches people to
182
+ // ignore a guard.
183
+ //
184
+ // The reason is not lost — `scripts/body-evidence.ts` prints it on
185
+ // stderr, where it is a diagnostic rather than a claim. A block that goes
186
+ // into a body may only contain text this module controls.
187
+ return (
188
+ "**Suite: UNMEASURED** — the run reported no result, so no count is quoted here. " +
189
+ "This is a run that measured nothing, not a run that found nothing wrong. " +
190
+ "The runner's reason is on stderr; it is kept out of this block because a " +
191
+ "free-text reason can contain a figure-shaped phrase, and a block carrying one " +
192
+ "is a block this module's own checker would refuse."
193
+ );
194
+ }
195
+ const parts = [`${run.pass} pass`, `${run.fail} fail`];
196
+ if (run.tests !== null) parts.push(`${run.tests} tests`);
197
+ if (run.files !== null) parts.push(`${run.files} files`);
198
+ const named =
199
+ run.failingTests.length > 0
200
+ ? `\n\nFailing:\n${run.failingTests.map(t => `- \`${t}\``).join("\n")}`
201
+ : "";
202
+ return `**Suite:** ${parts.join(" · ")}${named}`;
203
+ }