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.
- package/README.md +182 -0
- package/gates/.gate-salt +1 -1
- package/hooks/HarnessAFKGate.hook.ts +5 -1
- package/hooks/HookCurrency.hook.ts +11 -8
- package/hooks/MergeGuard.hook.ts +7 -1
- package/hooks/StaleTTLCleanup.hook.ts +4 -4
- package/hooks/VerifyPhaseLock.hook.ts +3 -3
- package/hooks/lib/findWorkflow.ts +3 -2
- package/hooks/lib/paths.ts +14 -2
- package/hooks/lib/utils.ts +23 -3
- package/lib/active-milestone.ts +50 -0
- package/lib/ai-review-rounds.ts +99 -0
- package/lib/ai-review-suppression.ts +200 -21
- package/lib/bash-write-guard.ts +397 -23
- package/lib/board-flow.ts +280 -0
- package/lib/board-lane-health.ts +578 -0
- package/lib/board-mirror.ts +136 -39
- package/lib/board-ready-fanout.ts +297 -14
- package/lib/board-ready-rule.ts +1211 -0
- package/lib/board-throughput.ts +136 -0
- package/lib/board-walkthrough.ts +240 -0
- package/lib/body-evidence.ts +203 -0
- package/lib/branch-protection.ts +399 -9
- package/lib/bun-version.ts +36 -0
- package/lib/cli-commands.ts +75 -4
- package/lib/closing-reference-audit.ts +307 -6
- package/lib/config-loader.ts +254 -25
- package/lib/config-readers.ts +170 -10
- package/lib/config-trackable.ts +96 -57
- package/lib/conformity.ts +121 -7
- package/lib/create-sc.ts +25 -2
- package/lib/derived-spec.ts +21 -9
- package/lib/filing-compliance.ts +367 -0
- package/lib/filing-plan.ts +47 -21
- package/lib/finding-arbiter.ts +79 -5
- package/lib/finding-jury.ts +43 -4
- package/lib/finding-promotion.ts +1123 -0
- package/lib/generators/agents-md.ts +149 -0
- package/lib/git-isolation.ts +137 -1
- package/lib/github-api-base.ts +66 -0
- package/lib/github.ts +194 -9
- package/lib/graphql-cursor.ts +80 -0
- package/lib/hook-scopes.ts +78 -0
- package/lib/issue-create-override.ts +415 -3
- package/lib/issue-decomposition.ts +124 -7
- package/lib/issue-extraction.ts +9 -7
- package/lib/issue-file-overlap.ts +373 -0
- package/lib/issue-filing-gate.ts +1109 -52
- package/lib/issue-repair.ts +90 -9
- package/lib/issue-shape.ts +199 -0
- package/lib/live-issues.ts +31 -2
- package/lib/local-work.ts +423 -0
- package/lib/markdown-fence.ts +134 -0
- package/lib/milestone-title.ts +46 -0
- package/lib/scaffold/ai-review-findings.ts +148 -3
- package/lib/scaffold/ai-review-step.ts +65 -5
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
- package/lib/scaffold/steps.ts +115 -9
- package/lib/source-census.ts +108 -0
- package/lib/spec-deps.ts +55 -11
- package/lib/spec-placement.ts +203 -13
- package/lib/spec-registry.ts +75 -16
- package/lib/spec-source.ts +609 -0
- package/lib/spec-write-sweep.ts +4 -0
- package/lib/stage-ladder.ts +896 -3
- package/lib/state-claim-readings.ts +252 -0
- package/lib/success-doc.ts +7 -6
- package/lib/test-command-positions.ts +135 -1
- package/lib/work-status.ts +551 -0
- package/lib/worktree-repo.ts +14 -2
- package/package.json +7 -1
- package/scripts/ai-review-findings.ts +8 -13
- package/scripts/ai-review-threads.ts +16 -17
- package/scripts/audit-closing-references.ts +330 -0
- package/scripts/audit-specs.ts +59 -103
- package/scripts/board-conformance.ts +747 -40
- package/scripts/board-mirror.ts +594 -13
- package/scripts/board-ready.ts +979 -0
- package/scripts/board-snapshot.ts +464 -12
- package/scripts/claim-files.ts +578 -0
- package/scripts/criterion-inventory.ts +526 -50
- package/scripts/finding-promotion.ts +547 -0
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/plan-issues.ts +279 -40
- package/scripts/plan-spec.ts +105 -3
- package/scripts/sync-sc-status.ts +147 -7
- package/scripts/worktree-census.ts +958 -0
- 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
|
+
|
package/lib/worktree-repo.ts
CHANGED
|
@@ -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
|
-
|
|
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.
|
|
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
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
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
|