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
@@ -273,8 +273,27 @@ export interface MirrorRow {
273
273
  readonly text: string;
274
274
  }
275
275
 
276
- /** The text used when an issue names no criterion at all. */
277
- export const NAMES_NONE = "";
276
+ /**
277
+ * The text used when an issue names no criterion at all — SC-2609.
278
+ *
279
+ * **This was `""` until #1716, and the reason it changed is worth keeping.**
280
+ * The original case read *"A cell reading 'none' sorts and filters as a
281
+ * value. Empty is absence."* Both halves are true and the conclusion is
282
+ * backwards: sorting and filtering as a value is the point, and *absence* is
283
+ * precisely the state a reader cannot act on. A blank cell says **not yet
284
+ * filled in**, **the tool could not tell** and **deliberately none** with the
285
+ * same zero bytes, so the one reading that means the board is in good order
286
+ * is indistinguishable from the two that mean it is not. 28 cells on the live
287
+ * board were blank on 2026-10-29 and nothing could say which kind they were.
288
+ *
289
+ * So the value is spelled, and a cell this module has never written stays
290
+ * `""`. That difference is the whole of SC-2609: `NAMES_NONE !== ""` is what
291
+ * lets a reader tell a judgement from a gap.
292
+ *
293
+ * It must not be mistakable for a criterion id — no `SC-`, no `CRC-`, nothing
294
+ * a reader scanning the column would try to look up.
295
+ */
296
+ export const NAMES_NONE = "serves no criterion";
278
297
 
279
298
  /**
280
299
  * Every id, never a summary.
@@ -397,42 +416,41 @@ export function openFrontier(
397
416
  }
398
417
 
399
418
  /**
400
- * READY means *pick this up next*, which is narrower than *nothing is
401
- * blocking it*.
419
+ * READY means *pick this up next*: open, nothing blocking it, nobody on it.
420
+ *
421
+ * ## The phase gate used to be here, and the cap replaced it
402
422
  *
403
423
  * The first run of this made 36 of 46 open issues Ready, because the
404
- * repository has almost no dependency edges and an issue with no blockers is
405
- * trivially unblocked. A lane holding 36 items is the backlog with a
406
- * different name, and it answers the question Jason actually asked — *what
407
- * can I pick up* — with "anything", which is the same as not answering.
408
- *
409
- * So readiness carries the phase order too: an issue is Ready when it is
410
- * unblocked, unassigned, AND sits in the earliest phase that still has open
411
- * work. Later phases are not ready because the spec says they come later,
412
- * and that ordering is data — the placement table — not a judgement made
413
- * here.
414
- *
415
- * An issue with no phase milestone is never Ready. That is not a
416
- * demotion: 19 of the 46 open issues are reviewer findings that serve no
417
- * criterion and belong to no phase (ADR-003), and putting them in the lane
418
- * that means "this is the next convergence work" would make the lane lie.
424
+ * repository has almost no dependency edges and an issue with no blockers
425
+ * is trivially unblocked. A lane holding 36 items is the backlog with a
426
+ * different name, and it answers *what can I pick up* with "anything",
427
+ * which is the same as not answering.
428
+ *
429
+ * The fix at the time was to require the earliest phase with open work.
430
+ * That made the lane small by making it **narrow**, and the two are not
431
+ * the same thing: an unblocked, unclaimed issue in a later phase could not
432
+ * enter Ready even when the lane sat under its depth and the earlier phase
433
+ * had nothing available. The lane refused to answer the question it exists
434
+ * for, and called that an ordering.
435
+ *
436
+ * Size is now `readyCap` in `lib/board-ready-rule.ts`, derived from
437
+ * measured throughput, and phase is `readyOrder` in the same file. The
438
+ * lane is small because it is capped and phase-ordered — so the gate was
439
+ * doing a job two other mechanisms already do, and taking it off is
440
+ * Jason's call of 2026-11-05 on #1758.
441
+ *
442
+ * **An issue with no phase milestone is now eligible.** This docblock used
443
+ * to say "never Ready", on the grounds that a reviewer finding serving no
444
+ * criterion would make the lane lie. It sorts last instead — `readyOrder`
445
+ * ranks a null phase behind every numbered one — which keeps the ordering
446
+ * claim true without refusing work that is genuinely pickable.
419
447
  */
420
- export function isReady(
421
- item: {
422
- readonly state: string;
423
- readonly phase: number | null;
424
- readonly blockedByOpen: number;
425
- readonly assignees: number;
426
- },
427
- frontier: number | null,
428
- ): boolean {
448
+ export function isReady(item: {
449
+ readonly state: string;
450
+ readonly blockedByOpen: number;
451
+ readonly assignees: number;
452
+ }): boolean {
429
453
  if (item.state !== "OPEN") return false;
430
- // No separate `item.phase === null` guard. It was here, and the mutation
431
- // battery removed it with every case still green: `null !== frontier` is
432
- // already false for any non-null frontier, so the two lines were one
433
- // decider spelled twice, and no behavioural test could ever tell which of
434
- // them was live (`.claude/rules/checks-must-be-able-to-fail.md`).
435
- if (frontier === null) return false;
436
- if (item.phase !== frontier) return false;
437
454
  return isUnblocked({ blockedBy: item.blockedByOpen }, item.assignees);
438
455
  }
456
+
@@ -29,7 +29,7 @@
29
29
  * ## What this file deliberately does NOT do
30
30
  *
31
31
  * **It does not decide readiness.** `isReady` does, and it carries the
32
- * phase-frontier rule that stopped the Ready lane holding 36 of 46 open
32
+ * cap and ordering that stop the Ready lane holding 36 of 46 open
33
33
  * issues. A second decider here would agree with it on every input anybody
34
34
  * thought to test, so no behavioural case could tell which was live and a
35
35
  * mutation of either would leave the other holding the case up. `BR-7`
@@ -47,6 +47,16 @@ export interface Dependent {
47
47
  /** `OPEN` or `CLOSED`, as GraphQL spells it. */
48
48
  readonly state: string;
49
49
  readonly phase: number | null;
50
+ /**
51
+ * Every label on the issue, verbatim — the ordering's SECOND source
52
+ * (#1853). An empty array means the issue carries none; this script never
53
+ * reads a page that can truncate labels, so there is no third state.
54
+ *
55
+ * It is not filtered to the ranked set here. `placementOf` owns which
56
+ * labels rank, and filtering on the way in would put a second opinion
57
+ * about that in this file.
58
+ */
59
+ readonly labels: readonly string[];
50
60
  /**
51
61
  * OPEN blockers only — the lifetime count never goes back down.
52
62
  *
@@ -92,19 +102,35 @@ export type FanoutDecision =
92
102
  * after `isReady` has already returned false, so a wrong or incomplete reason
93
103
  * costs a confusing log line and cannot move an issue. Keeping that ordering
94
104
  * is what stops it becoming the second decider described above.
105
+ *
106
+ * ## There is no "did not anticipate it" fallback, and that is deliberate
107
+ *
108
+ * One stood here until the phase gate was removed. With the two phase
109
+ * branches gone the remaining tests enumerate every input `isReady` reads,
110
+ * so the fallback became a line that could not run — the shape
111
+ * `.claude/rules/checks-must-be-able-to-fail.md` names, reading as a live
112
+ * safety net while catching nothing. ai-review round 1 of #1796.
113
+ *
114
+ * **Removing it required fixing a real gap first.** `isUnblocked` refuses
115
+ * anything that is not exactly `0`, and these guards asked `> 0`, so a
116
+ * negative count — which no GraphQL response produces, but nothing here
117
+ * rejected either — made `isReady` false and reached the fallback. The
118
+ * guards now match the contract they explain, which is what makes the
119
+ * enumeration genuinely exhaustive rather than nearly so.
120
+ *
121
+ * Exhaustiveness is asserted over the whole input grid in
122
+ * `test/board-ready-fanout.test.ts`, not claimed here: a condition added to
123
+ * `isReady` and not to this list makes a row return the wrong reason, and
124
+ * that row goes red.
95
125
  */
96
- function whyNotReady(d: Dependent, frontier: number | null): string {
126
+ export function whyNotReady(d: Dependent): string {
97
127
  if (d.state !== "OPEN") return `the issue is ${d.state}`;
98
128
  if (d.blockedByOpen === null) return "UNMEASURED — the dependency summary could not be read";
99
- if (d.blockedByOpen > 0) {
129
+ if (d.blockedByOpen !== 0) {
100
130
  return `${d.blockedByOpen} open blocker${d.blockedByOpen === 1 ? "" : "s"} remain`;
101
131
  }
102
132
  if (d.assignees === null) return "UNMEASURED — the assignee count could not be read";
103
- if (d.assignees > 0) return "somebody has claimed it";
104
- if (frontier === null) return "no phase has open work, so nothing is next";
105
- if (d.phase === null) return "no phase milestone — it serves no criterion (ADR-003)";
106
- if (d.phase !== frontier) return `phase ${d.phase} is behind the frontier at phase ${frontier}`;
107
- return "isReady said no and this reason list did not anticipate it";
133
+ return "somebody has claimed it";
108
134
  }
109
135
 
110
136
  /**
@@ -112,7 +138,6 @@ function whyNotReady(d: Dependent, frontier: number | null): string {
112
138
  */
113
139
  export function fanoutDecisions(
114
140
  dependents: readonly Dependent[],
115
- frontier: number | null,
116
141
  readyColumn: string,
117
142
  ): FanoutDecision[] {
118
143
  return dependents.map((d): FanoutDecision => {
@@ -142,11 +167,11 @@ export function fanoutDecisions(
142
167
  // answered false. Refusing before the decider is what keeps `isReady` the
143
168
  // only thing that says yes.
144
169
  if (d.blockedByOpen === null || d.assignees === null) {
145
- return { number: d.number, move: false, why: whyNotReady(d, frontier) };
170
+ return { number: d.number, move: false, why: whyNotReady(d) };
146
171
  }
147
172
  const measured = { ...d, blockedByOpen: d.blockedByOpen, assignees: d.assignees };
148
- if (!isReady(measured, frontier)) {
149
- return { number: d.number, move: false, why: whyNotReady(d, frontier) };
173
+ if (!isReady(measured)) {
174
+ return { number: d.number, move: false, why: whyNotReady(d) };
150
175
  }
151
176
  return { number: d.number, move: true };
152
177
  });
@@ -201,10 +226,28 @@ export function truncatedReadings(
201
226
  * Its `permission` field is one of `admin`, `write`, `read`, `none`, and an
202
227
  * unreadable response is `null` — which is UNMEASURED and refuses, because
203
228
  * a permission we could not read is not a permission we were granted.
229
+ *
230
+ * ## And the endpoint cannot answer about the owner
231
+ *
232
+ * `GITHUB_TOKEN` cannot read `collaborators/{actor}/permission` — it needs
233
+ * admin access — so on a run triggered by the repository owner the read comes
234
+ * back unreadable and `null` refuses the person who owns the board. Run
235
+ * `42080290624` is the record: the first execution of this lane that got as
236
+ * far as the decider, refusing `hornjason` on `hornjason/rungate`.
237
+ *
238
+ * The owner is trusted by identity rather than by a permission read, because
239
+ * the identity is a fact the run already holds and the permission is one it
240
+ * cannot obtain. An EMPTY actor never satisfies it: absent-and-absent are the
241
+ * same empty string, and `"" === ""` would hand a write to a run that
242
+ * identified nobody (BR-45).
204
243
  */
205
244
  export const WRITING_PERMISSIONS: readonly string[] = ["admin", "write", "maintain"];
206
245
 
207
- export function actorMayWrite(permission: string | null): boolean {
246
+ export function actorMayWrite(
247
+ permission: string | null,
248
+ identity: { readonly actor: string; readonly owner: string },
249
+ ): boolean {
250
+ if (identity.actor !== "" && identity.actor === identity.owner) return true;
208
251
  if (permission === null) return false;
209
252
  return WRITING_PERMISSIONS.includes(permission);
210
253
  }