rungate 0.8.13 → 0.8.16

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 (88) hide show
  1. package/README.md +182 -0
  2. package/gates/.gate-salt +1 -1
  3. package/hooks/HarnessAFKGate.hook.ts +5 -1
  4. package/hooks/HookCurrency.hook.ts +11 -8
  5. package/hooks/MergeGuard.hook.ts +7 -1
  6. package/hooks/StaleTTLCleanup.hook.ts +4 -4
  7. package/hooks/VerifyPhaseLock.hook.ts +3 -3
  8. package/hooks/lib/findWorkflow.ts +3 -2
  9. package/hooks/lib/paths.ts +14 -2
  10. package/hooks/lib/utils.ts +23 -3
  11. package/lib/active-milestone.ts +50 -0
  12. package/lib/ai-review-rounds.ts +99 -0
  13. package/lib/ai-review-suppression.ts +200 -21
  14. package/lib/bash-write-guard.ts +397 -23
  15. package/lib/board-flow.ts +280 -0
  16. package/lib/board-lane-health.ts +578 -0
  17. package/lib/board-mirror.ts +136 -39
  18. package/lib/board-ready-fanout.ts +297 -14
  19. package/lib/board-ready-rule.ts +1211 -0
  20. package/lib/board-throughput.ts +136 -0
  21. package/lib/board-walkthrough.ts +240 -0
  22. package/lib/body-evidence.ts +203 -0
  23. package/lib/branch-protection.ts +399 -9
  24. package/lib/bun-version.ts +36 -0
  25. package/lib/cli-commands.ts +75 -4
  26. package/lib/closing-reference-audit.ts +307 -6
  27. package/lib/config-loader.ts +254 -25
  28. package/lib/config-readers.ts +170 -10
  29. package/lib/config-trackable.ts +96 -57
  30. package/lib/conformity.ts +121 -7
  31. package/lib/create-sc.ts +25 -2
  32. package/lib/derived-spec.ts +21 -9
  33. package/lib/filing-compliance.ts +367 -0
  34. package/lib/filing-plan.ts +47 -21
  35. package/lib/finding-arbiter.ts +79 -5
  36. package/lib/finding-jury.ts +43 -4
  37. package/lib/finding-promotion.ts +1123 -0
  38. package/lib/generators/agents-md.ts +149 -0
  39. package/lib/git-isolation.ts +137 -1
  40. package/lib/github-api-base.ts +66 -0
  41. package/lib/github.ts +194 -9
  42. package/lib/graphql-cursor.ts +80 -0
  43. package/lib/hook-scopes.ts +78 -0
  44. package/lib/issue-create-override.ts +415 -3
  45. package/lib/issue-decomposition.ts +124 -7
  46. package/lib/issue-extraction.ts +9 -7
  47. package/lib/issue-file-overlap.ts +373 -0
  48. package/lib/issue-filing-gate.ts +1109 -52
  49. package/lib/issue-repair.ts +90 -9
  50. package/lib/issue-shape.ts +199 -0
  51. package/lib/live-issues.ts +31 -2
  52. package/lib/local-work.ts +423 -0
  53. package/lib/markdown-fence.ts +134 -0
  54. package/lib/milestone-title.ts +46 -0
  55. package/lib/scaffold/ai-review-findings.ts +148 -3
  56. package/lib/scaffold/ai-review-step.ts +65 -5
  57. package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
  58. package/lib/scaffold/steps.ts +115 -9
  59. package/lib/source-census.ts +108 -0
  60. package/lib/spec-deps.ts +55 -11
  61. package/lib/spec-placement.ts +203 -13
  62. package/lib/spec-registry.ts +75 -16
  63. package/lib/spec-source.ts +609 -0
  64. package/lib/spec-write-sweep.ts +4 -0
  65. package/lib/stage-ladder.ts +896 -3
  66. package/lib/state-claim-readings.ts +252 -0
  67. package/lib/success-doc.ts +7 -6
  68. package/lib/test-command-positions.ts +135 -1
  69. package/lib/work-status.ts +551 -0
  70. package/lib/worktree-repo.ts +14 -2
  71. package/package.json +7 -1
  72. package/scripts/ai-review-findings.ts +8 -13
  73. package/scripts/ai-review-threads.ts +16 -17
  74. package/scripts/audit-closing-references.ts +330 -0
  75. package/scripts/audit-specs.ts +59 -103
  76. package/scripts/board-conformance.ts +747 -40
  77. package/scripts/board-mirror.ts +594 -13
  78. package/scripts/board-ready.ts +979 -0
  79. package/scripts/board-snapshot.ts +464 -12
  80. package/scripts/claim-files.ts +578 -0
  81. package/scripts/criterion-inventory.ts +526 -50
  82. package/scripts/finding-promotion.ts +547 -0
  83. package/scripts/generate-code-map.ts +1 -1
  84. package/scripts/plan-issues.ts +279 -40
  85. package/scripts/plan-spec.ts +105 -3
  86. package/scripts/sync-sc-status.ts +147 -7
  87. package/scripts/worktree-census.ts +958 -0
  88. package/scripts/worktree-sweep.ts +269 -0
@@ -0,0 +1,551 @@
1
+ /**
2
+ * The two decisions `scripts/work-status.ts` makes, as functions, so they can
3
+ * be mutated and watched to fail.
4
+ *
5
+ * Both exist because of the same defect: a status reading that is wrong while
6
+ * looking healthy. Jason, 2026-11-03 — *"we get hallucinated status readings
7
+ * at all times"* — and the first draft of that script proved the point by
8
+ * being wrong about 44 issues.
9
+ */
10
+
11
+ import type { LaneReading } from "./board-lane-health";
12
+ import type { NetGrowthBasis } from "./issue-filing-gate";
13
+ import { readyOccupancy, undispatchableRemedy } from "./board-ready-rule";
14
+ import { ladderViolations, nextStage, retrosOwed, type ItemScope, type Stage } from "./stage-ladder";
15
+
16
+ /**
17
+ * Is this issue something anybody may pick up right now?
18
+ *
19
+ * **Takes the blockers, never a search qualifier.** One query string,
20
+ * `is:open -is:blocked no:assignee`, measured against this repository on
21
+ * 2026-11-03 across three transports:
22
+ *
23
+ * | transport | returned |
24
+ * |---|---|
25
+ * | `gh issue list --search` | 33 — correct |
26
+ * | GraphQL `search` | 77 — `-is:blocked` dropped |
27
+ * | REST `/search/issues` | 77 — `-is:blocked` dropped |
28
+ *
29
+ * Neither wrong path errors; both return a larger set that reads as fine. The
30
+ * ground truth is `GET /issues/{n}/dependencies/blocked_by` per issue, and
31
+ * that is what the caller must hand to this function.
32
+ *
33
+ * A CLOSED blocker does not block. That is the distinction the qualifier gets
34
+ * right and a naive `blockers.length > 0` gets wrong — an issue whose one
35
+ * dependency has already landed is pickable, and treating it otherwise parks
36
+ * finished chains forever.
37
+ */
38
+ export function isPickable(issue: {
39
+ readonly state: string;
40
+ readonly assignees: readonly unknown[];
41
+ readonly blockers: readonly { readonly state: string }[];
42
+ }): boolean {
43
+ if (issue.state !== "open") return false;
44
+ if (issue.assignees.length > 0) return false;
45
+ return !issue.blockers.some(b => b.state === "open");
46
+ }
47
+
48
+ /**
49
+ * The bucket for issues carrying no milestone — A LANE, NOT A GAP.
50
+ *
51
+ * Measured on this repository 2026-11-06: of 82 open issues, **26 carry no
52
+ * milestone at all**. They are maintenance and backlog work, they are real,
53
+ * and a report that groups by milestone and silently omits them loses the
54
+ * single largest group it has. Jason, 2026-11-06: *"not all issues will have
55
+ * milestones right, like there's stuff that's just maintenance stuff in the
56
+ * backlog — how do we track that"*.
57
+ *
58
+ * So it is a named row with its own count, and `--milestone none` focuses on
59
+ * it exactly as a title does. The parenthesis is deliberate: GitHub cannot
60
+ * have a milestone of this name, so the row can never collide with a real
61
+ * one.
62
+ */
63
+ export const NO_MILESTONE = "(no milestone)";
64
+
65
+ /** One milestone's standing, in the numbers that decide what to do next. */
66
+ export type MilestoneRow = {
67
+ readonly milestone: string;
68
+ readonly open: number;
69
+ /**
70
+ * Closed `completed`. **NOT every closed issue** — closed and done are
71
+ * different facts (an issue closed `not_planned` was never done), and the first
72
+ * version of this table reintroduced it one function later: it printed
73
+ * `closed` under a header reading `done`, so a lane that abandoned four of
74
+ * ten closures reported ten completed. Caught in review of #1825.
75
+ */
76
+ readonly done: number;
77
+ /** Closed for any other reason, or none: `not_planned`, `duplicate`, null. */
78
+ readonly dropped: number;
79
+ /** Open AND assigned — somebody says they are on it. */
80
+ readonly claimed: number;
81
+ /** Open with at least one OPEN blocker. A closed blocker does not block. */
82
+ readonly blocked: number;
83
+ /** Open, unclaimed, unblocked — anybody may start it today. */
84
+ readonly pickable: number;
85
+ };
86
+
87
+ /** An issue as this module needs it: the five fields, and nothing else. */
88
+ export type RollupIssue = {
89
+ readonly number: number;
90
+ readonly state: string;
91
+ readonly milestone?: { readonly title?: string | null } | null;
92
+ readonly assignees?: readonly unknown[] | null;
93
+ readonly pull_request?: unknown;
94
+ /** REST's `state_reason`. Absent and `null` both mean nobody said. */
95
+ readonly state_reason?: string | null;
96
+ /** From `GET /issues/{n}/dependencies/blocked_by` — never a search qualifier. */
97
+ readonly blockers: readonly { readonly state: string }[];
98
+ };
99
+
100
+ /** The milestone an issue belongs to, with absence spelled as a lane. */
101
+ export function milestoneOf(issue: RollupIssue): string {
102
+ const t = issue.milestone?.title;
103
+ return typeof t === "string" && t.trim() !== "" ? t : NO_MILESTONE;
104
+ }
105
+
106
+ /**
107
+ * Every milestone's standing, including the one that is not a milestone.
108
+ *
109
+ * Pull requests are dropped: `/issues` returns them too, and a PR counted as
110
+ * an issue inflates every lane it touches. `isPickable` is reused rather
111
+ * than re-derived — "what may anybody start" has one owner, and a second
112
+ * spelling here would be two deciders over one question with nothing
113
+ * comparing them.
114
+ *
115
+ * Sorted by open count descending, then by name, so the biggest pile of
116
+ * unfinished work is the first thing read. `NO_MILESTONE` sorts with the
117
+ * rest rather than being pinned anywhere: it is a lane.
118
+ */
119
+ export function milestoneRollup(issues: readonly RollupIssue[]): MilestoneRow[] {
120
+ type Counts = { open: number; done: number; dropped: number; claimed: number; blocked: number; pickable: number };
121
+ const rows = new Map<string, Counts>();
122
+ for (const i of issues) {
123
+ if (i.pull_request) continue;
124
+ const key = milestoneOf(i);
125
+ const r = rows.get(key) ?? { open: 0, done: 0, dropped: 0, claimed: 0, blocked: 0, pickable: 0 };
126
+ if (i.state === "open") {
127
+ r.open += 1;
128
+ if ((i.assignees?.length ?? 0) > 0) r.claimed += 1;
129
+ if (i.blockers.some(b => b.state === "open")) r.blocked += 1;
130
+ if (isPickable({ state: i.state, assignees: i.assignees ?? [], blockers: i.blockers })) {
131
+ r.pickable += 1;
132
+ }
133
+ } else if (i.state_reason === "completed") {
134
+ r.done += 1;
135
+ } else {
136
+ // CLOSED FAILS CLOSED: an
137
+ // unknown reason and a `null` one are NOT completions. Over-reporting
138
+ // `done` is the reading that makes a lane look finished.
139
+ r.dropped += 1;
140
+ }
141
+ rows.set(key, r);
142
+ }
143
+ return [...rows]
144
+ .map(([milestone, r]) => ({ milestone, ...r }))
145
+ .sort((a, b) => b.open - a.open || a.milestone.localeCompare(b.milestone));
146
+ }
147
+
148
+ /** What `--milestone` resolved to, including the two ways it can fail. */
149
+ export type Focus =
150
+ | { readonly kind: "all" }
151
+ | { readonly kind: "one"; readonly title: string }
152
+ | { readonly kind: "unknown"; readonly asked: string; readonly known: readonly string[] };
153
+
154
+ /**
155
+ * Resolve `--milestone`, and REFUSE a name that matches nothing.
156
+ *
157
+ * This is the whole reason it is a function. A focus that quietly selects
158
+ * zero issues prints a correct-looking report with an empty body, and a typo
159
+ * is then indistinguishable from a milestone whose work is finished — the
160
+ * *Silent Default Substitution* shape in `.claude/rules/config-access.md`,
161
+ * in a tool whose entire purpose is that the status is not hallucinated.
162
+ *
163
+ * `unknown` carries the names that DO exist, because a refusal that does not
164
+ * say what was available is a refusal nobody can act on.
165
+ *
166
+ * Absent means `all`. That is the change of 2026-11-06: the default used to
167
+ * be one hardcoded title, `"Issue intake"`, which on that day was 1 open
168
+ * issue of 82 — so 81 were invisible in the report the status was read from.
169
+ */
170
+ export function resolveFocus(asked: string | undefined, known: readonly string[]): Focus {
171
+ // **Absent is `all`. Present-and-empty is a REFUSAL.** The condition used
172
+ // to read `asked === undefined || asked.trim() === ""`, and `--milestone`
173
+ // typed as the last argument arrives here as the empty string — a mistake
174
+ // that then printed the unpinned report and read as if the pin had been
175
+ // honoured.
176
+ //
177
+ // Nothing more is needed: an empty name matches no milestone and neither
178
+ // keyword, so it falls through to the refusal at the bottom like any other
179
+ // name that does not exist. A branch of its own here WAS written, and a
180
+ // mutant deleting it left the suite 45 pass / 0 fail — a second decider
181
+ // over a question this function already answers
182
+ // (`.claude/rules/checks-must-be-able-to-fail.md`).
183
+ if (asked === undefined) return { kind: "all" };
184
+
185
+ // **A REAL milestone wins over the keyword that spells it.** GitHub titles
186
+ // are free text, so a milestone named `all` or `none` is legal, and
187
+ // checking the keywords first made one permanently unreachable — the
188
+ // keyword answered, the real lane was never consulted, and nothing said
189
+ // so. Caught in review of #1825.
190
+ if (known.includes(asked)) return { kind: "one", title: asked };
191
+
192
+ // `none` and the rendered label both reach the unmilestoned lane, so a
193
+ // reader can copy the name out of the table and pass it straight back.
194
+ if (asked === "none" || asked === NO_MILESTONE) return { kind: "one", title: NO_MILESTONE };
195
+ if (asked === "all") return { kind: "all" };
196
+ return { kind: "unknown", asked, known: [...known].sort() };
197
+ }
198
+
199
+ /** What a Ready reading means for whether the script may exit 0 — #1842. */
200
+ export type ReadyVerdict =
201
+ /** The lane is below its depth, or empty while its depth is positive. */
202
+ | "REFUSE"
203
+ /** The lane's state could not be established. NEVER the same as fine. */
204
+ | "UNMEASURED";
205
+
206
+ export interface ReadyRefusal {
207
+ readonly verdict: ReadyVerdict;
208
+ readonly count: number;
209
+ readonly against: number | null;
210
+ readonly why: string;
211
+ }
212
+
213
+ /**
214
+ * Whether the Ready lane's reading lets this run exit 0 — #1842.
215
+ *
216
+ * The ONE decider. The script restates its answer and spells no condition of
217
+ * its own: a second condition there would be two deciders over one input, and
218
+ * a mutation of either would leave the other holding every case up
219
+ * (`.claude/rules/checks-must-be-able-to-fail.md`).
220
+ *
221
+ * ## UNWRITTEN refuses, and the first version of this missed it
222
+ *
223
+ * `laneHealth` returns `UNWRITTEN`, not `SHORT`, when `count === 0` and the
224
+ * denominator is positive — so **the SHORT branch is unreachable at zero**
225
+ * and a gate keyed on SHORT alone exits 0 on a completely empty Ready lane,
226
+ * which is the single case it exists for. Worse, the first control written
227
+ * for this asserted that pass as correct, which is the "case that goes green
228
+ * under the wrong fix" shape: it would have certified the bypass.
229
+ *
230
+ * Caught by the automated security review of the pushed commit, not by the
231
+ * battery — the battery varied the health value and never asked which value
232
+ * the producer emits at the boundary.
233
+ *
234
+ * ## UNMEASURED is its own answer, not silence
235
+ *
236
+ * A census that could not be taken is not a lane that is fine, and returning
237
+ * `null` for it would make those two states the same bytes — the exact
238
+ * confusion this whole report exists to remove. It gets its own verdict and
239
+ * its own exit code at the call site.
240
+ *
241
+ * `NO_TARGET` is different and is NOT a refusal: it means no denominator
242
+ * exists, so there is nothing the lane could be short OF. `OK` and `OVER` are
243
+ * the lane working and the lane over-full; neither leaves a session with
244
+ * nothing to start.
245
+ *
246
+ * ## The switch is exhaustive on purpose
247
+ *
248
+ * `LaneHealth` is the producer's own type and the `never` arm makes adding a
249
+ * member a COMPILE error here rather than a silent pass. A `!==` test, or a
250
+ * `Set` of strings, would let a seventh health value default to "fine" — and
251
+ * that is precisely how UNWRITTEN slipped through the first time.
252
+ */
253
+ export function readyRefusal(
254
+ readings: readonly LaneReading[],
255
+ /**
256
+ * Open issues in the Ready column — the SAME number the report prints as
257
+ * startable.
258
+ *
259
+ * The lane's own count is every board item in the column, closed ones
260
+ * included, so a Ready holding three closed cards read `3 of 3 OK` while
261
+ * the startable list showed nothing. The gate passed with no work to
262
+ * start, which is the state it exists to catch. The count and the list
263
+ * must come from one number or the report can disagree with itself inside
264
+ * one page.
265
+ */
266
+ openInReady: number,
267
+ /**
268
+ * Cards in Ready this board reading could NOT see as issues — a draft, a
269
+ * pull request. **Required, and there is no default** (ai-review round 1 of
270
+ * #1857).
271
+ *
272
+ * `readyOccupancy`'s `cards` means every physical card in the lane, and the
273
+ * only number this file had was issues-only: `boardStatus()` keeps items
274
+ * whose content is an Issue and buckets the rest into `unseenByLane`, which
275
+ * never reached here. So the gate read the live 2026-11-07 lane — one open
276
+ * issue and one draft at a depth of 2 — as `1 of 2, one free slot, ROOM`,
277
+ * while `scripts/board-ready.ts`, counting every card, read it as full.
278
+ * **The exact disagreement #1852 exists to end survived inside the fix.**
279
+ *
280
+ * A default of `0` would have let a caller stay silent and be wrong, which
281
+ * is how it was wrong in the first place. A caller that genuinely cannot
282
+ * take the count must say so by other means; it may not say zero.
283
+ */
284
+ unseenInReady: number,
285
+ ): ReadyRefusal | null {
286
+ const ready = readings.find(r => r.lane === "Ready");
287
+ // A board with no Ready row cannot be judged, and must not read as fine.
288
+ if (ready === undefined) {
289
+ return {
290
+ verdict: "UNMEASURED",
291
+ count: 0,
292
+ against: null,
293
+ why: "the board reading contains no Ready lane at all",
294
+ };
295
+ }
296
+ // **The subtraction is `readyOccupancy`'s, not this file's** (#1852). It
297
+ // used to be spelled here as `ready.count - openInReady`, which made this
298
+ // the SECOND place that decided how full Ready is — and the two then
299
+ // disagreed in production: on 2026-11-07 the writer read `2 of 2, full`
300
+ // over every card while this read `1 of 2, SHORT` over open issues, and
301
+ // no single site a mutation could move said which was right.
302
+ //
303
+ // Named rather than silently subtracted, as before: the lane disagreeing
304
+ // with itself is a board defect somebody has to clear, and a gate that
305
+ // quietly corrects for it hides the thing to fix.
306
+ // **`ready.count` is issues only; the lane is not.** The sum is the whole
307
+ // of the lane, and it is taken here rather than in the caller so the one
308
+ // thing `readyOccupancy` is handed is the population its contract names.
309
+ const occ = readyOccupancy(ready.count + unseenInReady, openInReady, ready.against);
310
+ const why =
311
+ occ.undispatchable > 0
312
+ ? `${ready.why} — and ${occ.undispatchable} of the ${occ.cards} card(s) in this lane ` +
313
+ `${occ.undispatchable === 1 ? "is" : "are"} not an open issue, so only ` +
314
+ `${occ.dispatchable} can be started` +
315
+ // The REMEDY, which is the half a count cannot carry. NOT
316
+ // `heldReason` — that one answers the promoters' question, and its
317
+ // ROOM arm says "Ready is at its depth", which is false of a lane
318
+ // this gate is refusing for being SHORT. One reading, two renderings.
319
+ `. ${undispatchableRemedy(occ)}`
320
+ : ready.why;
321
+ const seen = { count: openInReady, against: ready.against, why };
322
+ // Judged on the OPEN count, so a lane filled with closed cards cannot
323
+ // clear the gate on a number nobody can act on.
324
+ if (ready.against !== null && openInReady < ready.against && ready.health !== "UNMEASURED") {
325
+ return { verdict: "REFUSE", ...seen };
326
+ }
327
+ switch (ready.health) {
328
+ case "SHORT":
329
+ case "UNWRITTEN":
330
+ return { verdict: "REFUSE", ...seen };
331
+ case "UNMEASURED":
332
+ return { verdict: "UNMEASURED", ...seen };
333
+ case "OK":
334
+ case "OVER":
335
+ case "NO_TARGET":
336
+ return null;
337
+ default: {
338
+ const unhandled: never = ready.health;
339
+ throw new Error(
340
+ `readyRefusal: unclassified lane health ${JSON.stringify(unhandled)}. ` +
341
+ "Every LaneHealth must be sorted into refuse, unmeasured or fine — " +
342
+ "defaulting a new one to fine is how UNWRITTEN bypassed this gate.",
343
+ );
344
+ }
345
+ }
346
+ }
347
+
348
+ /**
349
+ * One open item of the plan, as the report prints it.
350
+ *
351
+ * `reading` is the field that earns this type. An item with a command and an
352
+ * item with `verify: null` are both "not done", and printing them as one list
353
+ * says nine things are startable when three are: six of the nine open on
354
+ * 2026-11-11 had no command at all, so no run of `/stage-audit` could ever
355
+ * tick them. `.claude/rules/checks-must-be-able-to-fail.md` calls this the
356
+ * sixth shape — two states behind one observable — and the fix is to give
357
+ * them two spellings rather than a count.
358
+ */
359
+ export interface LadderRow {
360
+ /** `B4` — the stage letter and the 1-based position. */
361
+ readonly id: string;
362
+ readonly stage: string;
363
+ readonly what: string;
364
+ /** `OPEN` carries a command that can tick it. `UNVERIFIABLE` does not. */
365
+ readonly reading: "OPEN" | "UNVERIFIABLE";
366
+ /** Where the command can run. Absent in the document means `repo`. */
367
+ readonly scope: ItemScope;
368
+ }
369
+
370
+ export type LadderReport =
371
+ | { readonly kind: "UNMEASURED"; readonly why: string }
372
+ | {
373
+ readonly kind: "READ";
374
+ /** The stage id `nextStage` names, or `null` when every stage is complete. */
375
+ readonly next: string | null;
376
+ /** `nextStage`'s precondition, verbatim. `null` when nothing blocks it. */
377
+ readonly blocked: string | null;
378
+ /** Every open item of every stage, in ladder order. */
379
+ readonly open: readonly LadderRow[];
380
+ /** Stage ids complete with no retro — rule 10's gate. */
381
+ readonly retrosOwed: readonly string[];
382
+ };
383
+
384
+ /**
385
+ * The plan, read rather than transcribed — #1984.
386
+ *
387
+ * `scripts/work-status.ts` took **zero** reads of `project-state.json` before
388
+ * this. Its "THE AGREED ORDER" section printed a hand-typed array whose own
389
+ * docblock called itself a known defect, and the stage ladder AGENTS.md rule
390
+ * 10 names as the only place the plan lives appeared in no report at all. On
391
+ * 2026-11-11 that hid nine open items — B4, D4, E1 through E5, F1, F2 — from
392
+ * every session that read the report to decide what to work on.
393
+ *
394
+ * **Takes the source text, not a path.** The three ways this reading fails —
395
+ * the file is absent, the file is not JSON, the document is not a well-formed
396
+ * ladder — are different facts, and a function handed a parsed object cannot
397
+ * tell the first two apart. Each gets its own `why`, because *Silent Default
398
+ * Substitution* (`.claude/rules/config-access.md`) in this position prints an
399
+ * empty plan, which is byte-identical to a plan with nothing left to do.
400
+ *
401
+ * **Well-formedness is `ladderViolations`, which is already the one decider
402
+ * for it.** A second validator here would be two deciders over one fact: a
403
+ * mutation of either leaves the other holding every case up, and neither
404
+ * reads as dead.
405
+ */
406
+ export function ladderReport(source: string | null, where: string): LadderReport {
407
+ if (source === null) {
408
+ return { kind: "UNMEASURED", why: `${where} could not be read, so the plan was not consulted` };
409
+ }
410
+ let doc: unknown;
411
+ try {
412
+ doc = JSON.parse(source);
413
+ } catch (e) {
414
+ return {
415
+ kind: "UNMEASURED",
416
+ why: `${where} is not valid JSON (${e instanceof Error ? e.message : String(e)})`,
417
+ };
418
+ }
419
+ const violations = ladderViolations(doc);
420
+ if (violations.length > 0) {
421
+ return {
422
+ kind: "UNMEASURED",
423
+ why: `${where} is not a well-formed plan: ${violations.join("; ")}`,
424
+ };
425
+ }
426
+ // `ladderViolations` returning empty is what establishes the shape. The
427
+ // cast is the assertion it already made, not a second opinion about it.
428
+ const stages = (doc as { stages: Stage[] }).stages;
429
+
430
+ const open: LadderRow[] = [];
431
+ for (const stage of stages) {
432
+ for (const item of stage.items) {
433
+ if (item.done) continue;
434
+ open.push({
435
+ id: item.id,
436
+ stage: stage.id,
437
+ what: item.what,
438
+ reading: typeof item.verify === "string" && item.verify.trim() !== "" ? "OPEN" : "UNVERIFIABLE",
439
+ scope: item.scope ?? "repo",
440
+ });
441
+ }
442
+ }
443
+
444
+ const next = nextStage(stages);
445
+ return {
446
+ kind: "READ",
447
+ next: next === null ? null : (next.stage?.id ?? null),
448
+ blocked: next === null ? null : next.blocked,
449
+ open,
450
+ retrosOwed: retrosOwed(stages),
451
+ };
452
+ }
453
+
454
+ /**
455
+ * The plan section of the report, as lines — #1984.
456
+ *
457
+ * A printer, not a decider: every fact here is `ladderReport`'s, and the only
458
+ * choice made is how two different facts look different. OPEN and
459
+ * UNVERIFIABLE get their own words on every row, because a reader scanning the
460
+ * list for something to start must not pick an item no command can tick.
461
+ * UNMEASURED prints its reason and no list at all — an empty list under a
462
+ * heading is byte-identical to a plan with nothing left to do.
463
+ */
464
+ export function ladderLines(r: LadderReport): string[] {
465
+ // The plan is repository content any pull request can change, so its text
466
+ // reaches a terminal only with control characters removed: an escape code in
467
+ // an item could otherwise redraw the rows above it (security review, #2014).
468
+ const clean = (s: string) => s.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ");
469
+ if (r.kind === "UNMEASURED") return [` UNMEASURED — ${clean(r.why)}`];
470
+ const out: string[] = [];
471
+ out.push(` Next stage: ${r.next ?? "none — every stage is complete"}`);
472
+ if (r.blocked !== null) out.push(` Blocked: ${clean(r.blocked)}`);
473
+ const runnable = r.open.filter(o => o.reading === "OPEN").length;
474
+ out.push(
475
+ ` Open items (${r.open.length}): ${runnable} can be ticked by a command, ` +
476
+ `${r.open.length - runnable} are UNVERIFIABLE (verify: null)`,
477
+ );
478
+ for (const o of r.open) {
479
+ const text = clean(o.what);
480
+ const what = text.length > 90 ? `${text.slice(0, 89)}…` : text;
481
+ const scope = o.scope === "repo" ? "" : ` (${o.scope})`;
482
+ out.push(` ${o.reading.padEnd(12)} ${o.id.padEnd(4)} ${what}${scope}`);
483
+ }
484
+ out.push(` Retros owed: ${r.retrosOwed.length > 0 ? r.retrosOwed.join(", ") : "none"}`);
485
+ return out;
486
+ }
487
+
488
+ /**
489
+ * The FILING CAP line (#2087, SC-2764): the trailing day's opened and closed
490
+ * issue counts and the cap they set, under ADR-016.
491
+ *
492
+ * It formats a decision and decides nothing. The cap and its basis come from
493
+ * `netGrowthCeiling` in lib/issue-filing-gate.ts, the gate's own decider, so
494
+ * the board cannot report a cap the gate does not enforce. The numbers it
495
+ * needs beyond that are passed in rather than imported, which keeps this
496
+ * module free of the gate's runtime dependencies.
497
+ */
498
+ export function netGrowthLine(
499
+ decision: { cap: number; basis: NetGrowthBasis | null },
500
+ caps: {
501
+ shipCap: number;
502
+ ceiling: number;
503
+ queueCap: number;
504
+ /**
505
+ * The cap setting the gate could not read, or null. A corrupt `ship`
506
+ * block or a malformed `board.filingsPerRun` falls back to the strict cap,
507
+ * and that fallback must read as UNMEASURED, never as a setting (review of
508
+ * #2089; `.claude/rules/config-access.md`, Silent Default Substitution).
509
+ */
510
+ unreadable: string | null;
511
+ /**
512
+ * Why the COMMITTED config could not be read at all — no `origin/main`
513
+ * resolved, so nothing was read (#1964). Wins over `unreadable`: there is
514
+ * no setting to name, and the repair is a fetch, not a config edit.
515
+ */
516
+ committedUnmeasured?: string | null;
517
+ },
518
+ ): string {
519
+ const head = `Filing cap: ${decision.cap}`;
520
+ const queue = decision.cap < caps.queueCap ? ` (${caps.queueCap} for an engine-labelled filing)` : "";
521
+ const basis = decision.basis;
522
+ if (basis === null && typeof caps.committedUnmeasured === "string") {
523
+ return (
524
+ `${head}${queue} — UNMEASURED: ${caps.committedUnmeasured}, so the gate fell back to its strict cap ` +
525
+ "and the net-growth ceiling does not apply. The repair is a `git fetch`, not a config edit."
526
+ );
527
+ }
528
+ if (basis === null && caps.unreadable !== null) {
529
+ return (
530
+ `${head}${queue} — ${caps.unreadable} could not be read, so the gate fell back to its strict cap; ` +
531
+ "that cap is UNMEASURED as a setting, and the net-growth ceiling does not apply."
532
+ );
533
+ }
534
+ if (basis === null) {
535
+ return `${head}${queue} — set by ship mode or board.filingsPerRun, so the net-growth ceiling does not apply.`;
536
+ }
537
+ if (basis.reading === "UNMEASURED") {
538
+ return (
539
+ `${head}${queue} — the trailing day's issue counts are UNMEASURED (${basis.why}), ` +
540
+ `so the ceiling of ${caps.ceiling} does not apply.`
541
+ );
542
+ }
543
+ const counts = `the repo opened ${basis.opened} and closed ${basis.closed} issue(s) in the last 24h`;
544
+ if (basis.ceiling) return `${head}${queue} — ${counts}, so the net-growth ceiling applies (ADR-016).`;
545
+ const net = basis.opened - basis.closed;
546
+ return (
547
+ `${head}${queue} — ${counts} (net +${net}), so the cap stays at the ship-mode ${caps.shipCap}; ` +
548
+ `it rises to ${caps.ceiling} once closes catch up (ADR-016).`
549
+ );
550
+ }
551
+
@@ -186,7 +186,19 @@ export function readWorktreeRemote(worktreePath: string): RemoteReading {
186
186
  if (typeof worktreePath !== "string" || !worktreePath.trim()) {
187
187
  return { url: null, error: "no worktree path was given", missing: false };
188
188
  }
189
- const got = spawnSync("git", ["-C", worktreePath, "remote", "get-url", "origin"], {
189
+ // The CONFIGURED url, not `git remote get-url`, which applies any
190
+ // `url.<base>.insteadOf` rewrite (#2095, Jason's call of 2026-11-14). Run
191
+ // identity answers "which repository is this a checkout of", and a rewrite
192
+ // is a transport detail: it lets the filing gate's fixtures reach a local
193
+ // bare repository while still naming `owner/name`, and it means an agent
194
+ // cannot change which allowance it spends by adding one. Measured: with a
195
+ // rewrite set, `get-url` printed the `file://` path and this printed the
196
+ // https one. `--get-all` and the first line, because `--get` on a remote
197
+ // with two URLs prints the LAST, and fetch uses the first (review of #2140).
198
+ // `--local`, as `absentOrigin` below already is: unscoped, a
199
+ // `remote.origin.url` in the global config is listed FIRST and would choose
200
+ // the run (review of #2140; `get-url`, main's read before, did the same).
201
+ const got = spawnSync("git", ["-C", worktreePath, "config", "--local", "--get-all", "remote.origin.url"], {
190
202
  timeout: 10_000,
191
203
  encoding: "utf-8",
192
204
  });
@@ -203,7 +215,7 @@ export function readWorktreeRemote(worktreePath: string): RemoteReading {
203
215
  const said = String(got.stderr || "").trim().split("\n")[0] || `git exited ${got.status}`;
204
216
  return { url: null, error: redactRemote(said), missing: absentOrigin(worktreePath) };
205
217
  }
206
- const url = String(got.stdout || "").trim();
218
+ const url = (String(got.stdout || "").split("\n")[0] ?? "").trim();
207
219
  return url
208
220
  ? { url, error: null, missing: false }
209
221
  : { url: null, error: "git printed no url", missing: false };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.8.13",
3
+ "version": "0.8.16",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
6
  "repository": {
@@ -34,18 +34,24 @@
34
34
  "scripts/board-snapshot.ts",
35
35
  "scripts/plan-deps.ts",
36
36
  "scripts/plan-issues.ts",
37
+ "scripts/board-ready.ts",
38
+ "scripts/audit-closing-references.ts",
37
39
  "scripts/create-spec.ts",
38
40
  "scripts/create-success.ts",
39
41
  "scripts/create-sc.ts",
40
42
  "scripts/ai-review-findings.ts",
41
43
  "scripts/ai-review-threads.ts",
42
44
  "scripts/record-ai-review-unmeasured.ts",
45
+ "scripts/finding-promotion.ts",
46
+ "scripts/claim-files.ts",
43
47
  "scripts/arbitrate-finding.ts",
44
48
  "scripts/split-spec.ts",
45
49
  "scripts/sync-sc-status.ts",
46
50
  "scripts/audit-transcript.ts",
47
51
  "scripts/detect-sc-drift.ts",
48
52
  "scripts/check-installed-hook-currency.ts",
53
+ "scripts/worktree-sweep.ts",
54
+ "scripts/worktree-census.ts",
49
55
  "package.json"
50
56
  ],
51
57
  "exports": {
@@ -92,11 +92,7 @@
92
92
  * `specs/CODE-REVIEW-CONVERGENCE-SPEC.md`.
93
93
  */
94
94
  import { aiReviewJuryGate } from "../lib/ai-review-jury";
95
- import {
96
- aiReviewSuppressionGate,
97
- checkoutLineText,
98
- readOrNull,
99
- } from "../lib/ai-review-suppression";
95
+ import { productionSuppression } from "../lib/ai-review-suppression";
100
96
  import { main } from "../lib/scaffold/ai-review-findings";
101
97
  import { AI_REVIEW_BALLOT_DIR_ENV, AI_REVIEW_THREADS_PATH_VAR } from "../lib/scaffold/ai-review-step";
102
98
 
@@ -106,14 +102,13 @@ const jury =
106
102
  ? null
107
103
  : (blocking: readonly unknown[]) => aiReviewJuryGate(blocking, ballotDir);
108
104
 
109
- const threadsPath = process.env[AI_REVIEW_THREADS_PATH_VAR];
110
- const suppress =
111
- threadsPath === undefined || threadsPath === ""
112
- ? null
113
- : aiReviewSuppressionGate({
114
- threads: readOrNull(threadsPath),
115
- lineTextFor: checkoutLineText(process.cwd()),
116
- });
105
+ // Assembled in `lib/`, not here. This command and `ai-review-threads.ts` must
106
+ // form the SAME gate from the same file, and two hand-written literals is how
107
+ // `anchorOccurrences` reached one of them and not the other (#1861 round 4).
108
+ const { gate: suppress } = productionSuppression(
109
+ process.env[AI_REVIEW_THREADS_PATH_VAR],
110
+ process.cwd(),
111
+ );
117
112
 
118
113
  // One line, and `process.exit(main(` is load-bearing text: AC-4 in
119
114
  // `test/ai-review-findings-command.test.ts` reads it to prove this file