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,578 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Is each board lane holding what it is supposed to hold?
|
|
3
|
+
*
|
|
4
|
+
* Covers SC-2670 (specs/BOARD-FLOW-SPEC.md).
|
|
5
|
+
*
|
|
6
|
+
* ## Why a count alone is not a reading
|
|
7
|
+
*
|
|
8
|
+
* `scripts/work-status.ts` can already say how many items sit in each lane.
|
|
9
|
+
* That number is worthless on its own: Ready holding 6 is excellent if 6 is
|
|
10
|
+
* everything that could be ready, and total failure if 34 things could be.
|
|
11
|
+
* **A lane is healthy or not only against what SHOULD be in it**, so every
|
|
12
|
+
* row here carries its denominator or admits it has none.
|
|
13
|
+
*
|
|
14
|
+
* The three comparisons come from the spec's own outcomes table and are not
|
|
15
|
+
* invented here:
|
|
16
|
+
*
|
|
17
|
+
* | Lane | Against | Because |
|
|
18
|
+
* |---|---|---|
|
|
19
|
+
* | Ready | unblocked and unclaimed issues, **capped** at a depth derived from live throughput | Ready is Anderson's replenishment COMMITMENT POINT, so a Ready far below what it is allowed to hold means the ordering decision has relocated into each puller's private Backlog heuristic, leaving no reviewable record. It is capped because the commitment point is a queue, not a mirror of the backlog: comparing the lane against every eligible issue made a correctly-sized Ready read `SHORT by 30` on 2026-11-05 and would have forever |
|
|
20
|
+
* | In progress | open AND assigned issues | somebody is working it; a lane that does not say so makes active work invisible and makes cycle time ABSENT rather than approximate |
|
|
21
|
+
* | Cancelled | issues closed as `not_planned` | work that left without being done. Off the board entirely is worse than merged into Done: the cancellation rate becomes unobservable and Little's Law's second assumption breaks, so every forecast is unsound rather than merely imprecise |
|
|
22
|
+
*
|
|
23
|
+
* Backlog, In review and Done get no denominator, and say so rather than
|
|
24
|
+
* reading OK. Backlog is a DISPLAY — five of the six lanes are mechanisms
|
|
25
|
+
* and it is the exception — and the other two have no cheap second source to
|
|
26
|
+
* compare against. **An unmeasured lane must not spell the same as a healthy
|
|
27
|
+
* one**, which is the defect this whole area keeps producing. In review does
|
|
28
|
+
* have one cheap reading that is not a denominator: `handPlacedInReview`
|
|
29
|
+
* names the issue cards no open pull request accounts for (SC-2759).
|
|
30
|
+
*/
|
|
31
|
+
|
|
32
|
+
import { READY_TOLERANCE_DAYS, readyCap, readyTarget, type Throughput } from "./board-ready-rule";
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Is anybody actually working this issue? #1941.
|
|
36
|
+
*
|
|
37
|
+
* ## The assignee is a self-declaration and nothing asks it for evidence
|
|
38
|
+
*
|
|
39
|
+
* Measured 2026-11-09: six issues were assigned to `hornjason` and NONE had
|
|
40
|
+
* an open pull request. Five had no pushed branch at all. The one with real
|
|
41
|
+
* work, #1931, had it as commit `3bd05a14` sitting unpushed in a local
|
|
42
|
+
* worktree — invisible to every GitHub reading there is.
|
|
43
|
+
*
|
|
44
|
+
* So the board was reporting six in progress, one of which was happening,
|
|
45
|
+
* and the one that WAS happening was the one GitHub could see least about.
|
|
46
|
+
*
|
|
47
|
+
* ## Four readings, because `null` is a reading
|
|
48
|
+
*
|
|
49
|
+
* Each field is `true`, `false`, or `null` for **not read**, and the
|
|
50
|
+
* distinction is the whole point — `.claude/rules/config-access.md`, Silent
|
|
51
|
+
* Default Substitution. `PARKED` is the verdict that releases somebody's
|
|
52
|
+
* claim, so it is the one that must not be reachable from an absence: a
|
|
53
|
+
* caller that never looked for local commits and a caller that looked and
|
|
54
|
+
* found none are different facts, and only the second may release.
|
|
55
|
+
*
|
|
56
|
+
* `scripts/board-status-sweep.ts` runs in GitHub Actions, on a machine that
|
|
57
|
+
* has never seen the worktree where #1931's commit lives. It therefore
|
|
58
|
+
* **cannot** reach `PARKED` and must not pretend to. That is not a defect in
|
|
59
|
+
* this function; it is the finding, made legible.
|
|
60
|
+
*/
|
|
61
|
+
export type WorkVerdict =
|
|
62
|
+
/** A pushed branch or an open pull request. The board can see it. */
|
|
63
|
+
| "WORKING"
|
|
64
|
+
/** Commits on this machine and nowhere else — real work, board-invisible. */
|
|
65
|
+
| "INVISIBLE"
|
|
66
|
+
/** An assignee and nothing else: a claim nobody can falsify. */
|
|
67
|
+
| "PARKED"
|
|
68
|
+
/** At least one reading was not taken, so no verdict is honest. */
|
|
69
|
+
| "UNMEASURED";
|
|
70
|
+
|
|
71
|
+
/** What a run was able to observe. `null` is *not read*, never *no*. */
|
|
72
|
+
export interface WorkEvidence {
|
|
73
|
+
/** An open pull request declaring it closes this issue. */
|
|
74
|
+
readonly openPullRequest: boolean | null;
|
|
75
|
+
/** A branch on `origin` carrying commits for it. */
|
|
76
|
+
readonly pushedBranch: boolean | null;
|
|
77
|
+
/** Commits on this machine that are on no pushed ref. */
|
|
78
|
+
readonly localCommits: boolean | null;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* The ONE decider, read by the lane-health row and by the stale sweep.
|
|
83
|
+
*
|
|
84
|
+
* Two deciders answering this question would be behaviourally one guard and
|
|
85
|
+
* no behavioural test could tell them apart
|
|
86
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`). There is one, and
|
|
87
|
+
* `test/board-lane-health.test.ts` asserts the callers reach it.
|
|
88
|
+
*
|
|
89
|
+
* **Order matters and is not arbitrary.** Visible work wins over invisible
|
|
90
|
+
* work, because a pushed branch is the stronger claim and the cheaper one to
|
|
91
|
+
* verify. Invisible work wins over every absence, because releasing a claim
|
|
92
|
+
* backed by real commits is the expensive mistake and leaving a dead claim
|
|
93
|
+
* one more day is the cheap one.
|
|
94
|
+
*/
|
|
95
|
+
export function workVerdict(e: WorkEvidence): { verdict: WorkVerdict; why: string } {
|
|
96
|
+
if (e.openPullRequest === true) {
|
|
97
|
+
return { verdict: "WORKING", why: "an open pull request declares it closes this" };
|
|
98
|
+
}
|
|
99
|
+
if (e.pushedBranch === true) {
|
|
100
|
+
return { verdict: "WORKING", why: "a branch with commits is pushed to origin" };
|
|
101
|
+
}
|
|
102
|
+
if (e.localCommits === true) {
|
|
103
|
+
return {
|
|
104
|
+
verdict: "INVISIBLE",
|
|
105
|
+
why:
|
|
106
|
+
"commits exist on this machine and on no pushed ref — real work the board cannot " +
|
|
107
|
+
"see. Push the branch and open a draft pull request",
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
// Every positive reading has been tried. Only now does an absence mean
|
|
111
|
+
// anything, and only if every absence was actually LOOKED FOR.
|
|
112
|
+
const unread = (
|
|
113
|
+
[
|
|
114
|
+
["an open pull request", e.openPullRequest],
|
|
115
|
+
["a pushed branch", e.pushedBranch],
|
|
116
|
+
["local commits", e.localCommits],
|
|
117
|
+
] as const
|
|
118
|
+
)
|
|
119
|
+
.filter(([, v]) => v === null)
|
|
120
|
+
.map(([name]) => name);
|
|
121
|
+
if (unread.length > 0) {
|
|
122
|
+
// "a, b and c" rather than "a and b and c". The list is read by a human
|
|
123
|
+
// deciding whether to trust a release, so it is written for one.
|
|
124
|
+
const named =
|
|
125
|
+
unread.length <= 1
|
|
126
|
+
? unread.join("")
|
|
127
|
+
: `${unread.slice(0, -1).join(", ")} and ${unread[unread.length - 1]}`;
|
|
128
|
+
return {
|
|
129
|
+
verdict: "UNMEASURED",
|
|
130
|
+
why:
|
|
131
|
+
`UNMEASURED — ${named} ${unread.length === 1 ? "was" : "were"} not read, ` +
|
|
132
|
+
`so this is PARKED or INVISIBLE and nothing here can tell them apart. A claim is ` +
|
|
133
|
+
`not released on a reading nobody took`,
|
|
134
|
+
};
|
|
135
|
+
}
|
|
136
|
+
return {
|
|
137
|
+
verdict: "PARKED",
|
|
138
|
+
why: "an assignee and nothing else — no pull request, no pushed branch, no local commits",
|
|
139
|
+
};
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** Every lane name the board uses, in flow order. */
|
|
143
|
+
export const LANES: readonly string[] = [
|
|
144
|
+
"Backlog",
|
|
145
|
+
"Ready",
|
|
146
|
+
"In progress",
|
|
147
|
+
"In review",
|
|
148
|
+
"Done",
|
|
149
|
+
"Cancelled",
|
|
150
|
+
];
|
|
151
|
+
|
|
152
|
+
export type LaneHealth =
|
|
153
|
+
/** Holding what it should, measured against a denominator. */
|
|
154
|
+
| "OK"
|
|
155
|
+
/** Has a writer and a denominator, and is below it. */
|
|
156
|
+
| "SHORT"
|
|
157
|
+
/**
|
|
158
|
+
* Above its denominator.
|
|
159
|
+
*
|
|
160
|
+
* Only reachable since Ready gained a cap, and it appeared on the first
|
|
161
|
+
* live run: the lane held 5 against a derived depth of 4, filled under
|
|
162
|
+
* the uncapped rule. Before the cap, `count > against` could not happen
|
|
163
|
+
* for any lane with a repo-wide denominator, so OK absorbed it.
|
|
164
|
+
*
|
|
165
|
+
* It is a verdict of its own for the reason SHORT and UNWRITTEN are:
|
|
166
|
+
* **the remedy is different.** SHORT means promote more, OVER means stop
|
|
167
|
+
* promoting and let the queue drain. Reporting an over-full commitment
|
|
168
|
+
* point as OK is the lane lying in the other direction, which is exactly
|
|
169
|
+
* what the negative control in the walk-through exists to catch.
|
|
170
|
+
*/
|
|
171
|
+
| "OVER"
|
|
172
|
+
/**
|
|
173
|
+
* Empty while its denominator is not.
|
|
174
|
+
*
|
|
175
|
+
* **It does not mean "nothing writes this lane", and it used to say so.**
|
|
176
|
+
* That sentence named a mechanism the census never looked at, and it was
|
|
177
|
+
* false from 2026-11-05: `lib/board-flow.ts` moves an issue to Cancelled
|
|
178
|
+
* on a `not_planned` close, with a recorded run, while this row still
|
|
179
|
+
* reported the lane unwritten. An empty lane has at least two causes —
|
|
180
|
+
* no writer, or a writer whose population the denominator does not
|
|
181
|
+
* share — and only the second was true (SC-2731).
|
|
182
|
+
*/
|
|
183
|
+
| "UNWRITTEN"
|
|
184
|
+
/** No denominator exists, so the count is reported and nothing is judged. */
|
|
185
|
+
| "NO_TARGET"
|
|
186
|
+
/** The census could not be taken. Never the same as OK. */
|
|
187
|
+
| "UNMEASURED";
|
|
188
|
+
|
|
189
|
+
export interface LaneCensus {
|
|
190
|
+
/** Lane name to the number of items the board shows in it. */
|
|
191
|
+
readonly counts: ReadonlyMap<string, number>;
|
|
192
|
+
/**
|
|
193
|
+
* Open issues that are unblocked and unclaimed **on this board**.
|
|
194
|
+
*
|
|
195
|
+
* Board-scoped like the others. Today the cap hides the difference —
|
|
196
|
+
* `readyTarget` takes the smaller of this and the depth, and this is far
|
|
197
|
+
* the larger — but a board holding fewer pickable issues than the cap
|
|
198
|
+
* would read SHORT against work that does not exist.
|
|
199
|
+
*/
|
|
200
|
+
readonly pickable: number;
|
|
201
|
+
/**
|
|
202
|
+
* Open issues with at least one assignee **that are on this board**.
|
|
203
|
+
*
|
|
204
|
+
* Scoped for the same reason `cancelledClosed` is: the numerator counts
|
|
205
|
+
* board items, so a denominator counting repository issues reports a gap
|
|
206
|
+
* no writer could close. Read repo-wide it said `In progress 1 of 10`
|
|
207
|
+
* while the board held far fewer assigned issues than the repository did
|
|
208
|
+
* (SC-2730).
|
|
209
|
+
*/
|
|
210
|
+
readonly openAssigned: number;
|
|
211
|
+
/**
|
|
212
|
+
* Issues **on this board** closed as `NOT_PLANNED` or `DUPLICATE`, or
|
|
213
|
+
* `null` when the count could not be taken.
|
|
214
|
+
*
|
|
215
|
+
* ## On this board, because the numerator is
|
|
216
|
+
*
|
|
217
|
+
* It used to be the repository-wide count, and that made the row compare
|
|
218
|
+
* a board lane against a population the board's writer never sees. On
|
|
219
|
+
* 2026-11-05 it read `Cancelled 0 of 23 UNWRITTEN`, and all 23 were
|
|
220
|
+
* issues closed before `lib/board-flow.ts` had a Cancelled branch or
|
|
221
|
+
* never added to the board at all. A denominator that counts things the
|
|
222
|
+
* numerator cannot contain reports a gap that no writer could close
|
|
223
|
+
* (SC-2730).
|
|
224
|
+
*
|
|
225
|
+
* **Both reasons, because the spec's condition is both.**
|
|
226
|
+
* `specs/BOARD-FLOW-SPEC.md` defines Cancelled's entry as "closed as
|
|
227
|
+
* `not_planned` or `duplicate`" and `lib/work-status.ts` already maps both
|
|
228
|
+
* to ABANDONED. Counting only the first turns a lane that is SHORT by
|
|
229
|
+
* however many duplicates exist into one that reads OK — ai-review round 1,
|
|
230
|
+
* finding 1.
|
|
231
|
+
*
|
|
232
|
+
* **`null` rather than `0`**, because they are opposite facts wearing the
|
|
233
|
+
* same digit: zero cancellations makes Cancelled correct, and a read that
|
|
234
|
+
* failed makes it unknown. Collapsing them produces a green lane out of a
|
|
235
|
+
* measurement that never happened — security review of the pushed commit,
|
|
236
|
+
* finding 1.
|
|
237
|
+
*/
|
|
238
|
+
readonly cancelledClosed: number | null;
|
|
239
|
+
/**
|
|
240
|
+
* How much the repository delivered, over how long — or `null` when that
|
|
241
|
+
* could not be read.
|
|
242
|
+
*
|
|
243
|
+
* Ready's denominator is **capped**, and the cap is derived from this
|
|
244
|
+
* rather than typed in (`lib/board-ready-rule.ts`). Before 2026-11-05 the
|
|
245
|
+
* row compared the lane against every pickable issue in the repository
|
|
246
|
+
* with no bound at all, which is how it came to report `SHORT by 30`
|
|
247
|
+
* against a writer that could never promote more than 3.
|
|
248
|
+
*
|
|
249
|
+
* It is a required field rather than an optional one so that every caller
|
|
250
|
+
* has to say what it measured. `null` makes the row UNMEASURED; there is
|
|
251
|
+
* no fallback depth, because a built-in default substituted for a failed
|
|
252
|
+
* read is indistinguishable from a real one.
|
|
253
|
+
*/
|
|
254
|
+
readonly throughput: Throughput | null;
|
|
255
|
+
/**
|
|
256
|
+
* False when the board could not be paged in full.
|
|
257
|
+
*
|
|
258
|
+
* A partial page and an empty lane produce the same count, and that
|
|
259
|
+
* ambiguity is the whole subject here — so an incomplete census refuses
|
|
260
|
+
* every row rather than reporting the numbers it happens to hold.
|
|
261
|
+
*/
|
|
262
|
+
readonly complete: boolean;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
export interface LaneReading {
|
|
266
|
+
readonly lane: string;
|
|
267
|
+
readonly count: number;
|
|
268
|
+
/** What the lane should hold. `null` when nothing cheap can say. */
|
|
269
|
+
readonly against: number | null;
|
|
270
|
+
readonly health: LaneHealth;
|
|
271
|
+
readonly why: string;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/**
|
|
275
|
+
* The denominator for each lane that has one, and why it is that one.
|
|
276
|
+
*
|
|
277
|
+
* ## The denominators are board-scoped, reversing an earlier decision
|
|
278
|
+
*
|
|
279
|
+
* They were repo-wide, deliberately: the security review of the pushed
|
|
280
|
+
* commit (finding 3) argued that scoping them to board items would hide a
|
|
281
|
+
* more important failure — an eligible issue that never reached the board
|
|
282
|
+
* at all — so the mismatch was declared rather than removed.
|
|
283
|
+
*
|
|
284
|
+
* **That traded a readable row for an unreadable one, and the cost showed
|
|
285
|
+
* up on 2026-11-05.** The Cancelled row read `0 of 23 UNWRITTEN — nothing
|
|
286
|
+
* writes it`, which says the writer is broken. The writer was fine; all 23
|
|
287
|
+
* were issues the board had never held. A row whose two numbers describe
|
|
288
|
+
* different populations cannot be read correctly by anyone, and declaring
|
|
289
|
+
* the mismatch in a label does not fix that — the label said "repo-wide"
|
|
290
|
+
* the whole time and the row was still misread, by me, for a day.
|
|
291
|
+
*
|
|
292
|
+
* The earlier concern was right about the failure being important and
|
|
293
|
+
* wrong about where it belongs: **it is a fact about board MEMBERSHIP, not
|
|
294
|
+
* about any lane.** It is now its own reading — `offBoard` — so both
|
|
295
|
+
* survive and neither is inferred from the other. One row, one population.
|
|
296
|
+
*
|
|
297
|
+
* `undefined` means this lane has no denominator; `null` inside one means
|
|
298
|
+
* the denominator exists but could not be read.
|
|
299
|
+
*/
|
|
300
|
+
function target(lane: string, c: LaneCensus): { against: number | null; label: string } | undefined {
|
|
301
|
+
if (lane === "Ready") {
|
|
302
|
+
// **The cap is half the denominator, and it is why this row stopped
|
|
303
|
+
// lying.** Ready is a commitment point, not a mirror of the backlog, so
|
|
304
|
+
// what it SHOULD hold is the smaller of "everything eligible" and "the
|
|
305
|
+
// depth the queue is allowed". Comparing against the eligible set alone
|
|
306
|
+
// made a correctly-sized lane read SHORT forever.
|
|
307
|
+
const cap = c.throughput === null ? null : readyCap(c.throughput);
|
|
308
|
+
return {
|
|
309
|
+
against: readyTarget(c.pickable, cap),
|
|
310
|
+
label:
|
|
311
|
+
cap === null
|
|
312
|
+
? "throughput, which Ready's depth is derived from,"
|
|
313
|
+
: `allowed in the queue — ${c.pickable} unblocked and unclaimed on this board, capped at a ` +
|
|
314
|
+
`depth of ${cap} derived from ${READY_TOLERANCE_DAYS} day(s) of live throughput`,
|
|
315
|
+
};
|
|
316
|
+
}
|
|
317
|
+
if (lane === "In progress") {
|
|
318
|
+
return { against: c.openAssigned, label: "on this board are open and assigned" };
|
|
319
|
+
}
|
|
320
|
+
if (lane === "Cancelled") {
|
|
321
|
+
return {
|
|
322
|
+
against: c.cancelledClosed,
|
|
323
|
+
label: "on this board are closed as not_planned or duplicate",
|
|
324
|
+
};
|
|
325
|
+
}
|
|
326
|
+
return undefined;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/**
|
|
330
|
+
* One reading per lane, in flow order.
|
|
331
|
+
*
|
|
332
|
+
* A lane the board never mentioned reads `0`, which is correct: the board
|
|
333
|
+
* showing no items in a lane and the board having no such lane are the same
|
|
334
|
+
* fact from the outside, and both mean nothing is in it.
|
|
335
|
+
*/
|
|
336
|
+
export function laneHealth(c: LaneCensus): LaneReading[] {
|
|
337
|
+
// **Every key the census holds gets a row, and nothing is excluded by
|
|
338
|
+
// spelling.** Mapping over LANES alone meant a lane the board has and this
|
|
339
|
+
// file does not know about contributed items to no row at all, so the
|
|
340
|
+
// report stayed confident and complete-looking while part of the board was
|
|
341
|
+
// simply absent from it. Adding a lane on the board is two clicks and
|
|
342
|
+
// nobody would think to mirror it here. Security review of the pushed
|
|
343
|
+
// commit, finding 4.
|
|
344
|
+
//
|
|
345
|
+
// The first fix for that swept unknown keys up but skipped any beginning
|
|
346
|
+
// `"("`, which put the caller's own `"(no status)"` marker straight back
|
|
347
|
+
// into the hole it had just closed — the SAME omission, one line below the
|
|
348
|
+
// sweep written to stop it. Found independently by ai-review round 1 and
|
|
349
|
+
// by the security review of the pushed commit. A prefix exclusion is also
|
|
350
|
+
// forgeable: a lane somebody genuinely names `"(parked)"` on the board
|
|
351
|
+
// would be suppressed by impersonating a marker. So there is no exclusion
|
|
352
|
+
// left — a key that is not a known lane is reported, whatever it says.
|
|
353
|
+
const unknown = [...c.counts.keys()].filter(k => !LANES.includes(k)).sort();
|
|
354
|
+
const known = LANES.map(lane => {
|
|
355
|
+
const count = c.counts.get(lane) ?? 0;
|
|
356
|
+
if (!c.complete) {
|
|
357
|
+
return {
|
|
358
|
+
lane,
|
|
359
|
+
count,
|
|
360
|
+
against: null,
|
|
361
|
+
health: "UNMEASURED" as const,
|
|
362
|
+
why: "the board could not be paged in full, so this count is a floor and not a reading",
|
|
363
|
+
};
|
|
364
|
+
}
|
|
365
|
+
const t = target(lane, c);
|
|
366
|
+
if (t === undefined) {
|
|
367
|
+
return {
|
|
368
|
+
lane,
|
|
369
|
+
count,
|
|
370
|
+
against: null,
|
|
371
|
+
health: "NO_TARGET" as const,
|
|
372
|
+
why: "no second source says what should be here, so the count is reported and nothing is judged",
|
|
373
|
+
};
|
|
374
|
+
}
|
|
375
|
+
// The denominator exists but could not be read. A failed search is not
|
|
376
|
+
// a repository with nothing in it.
|
|
377
|
+
if (t.against === null) {
|
|
378
|
+
return {
|
|
379
|
+
lane,
|
|
380
|
+
count,
|
|
381
|
+
against: null,
|
|
382
|
+
health: "UNMEASURED" as const,
|
|
383
|
+
why: `the ${t.label} count could not be read, so this lane has no denominator to judge against`,
|
|
384
|
+
};
|
|
385
|
+
}
|
|
386
|
+
if (count === 0 && t.against > 0) {
|
|
387
|
+
return {
|
|
388
|
+
lane,
|
|
389
|
+
count,
|
|
390
|
+
against: t.against,
|
|
391
|
+
health: "UNWRITTEN" as const,
|
|
392
|
+
// States what was counted, not why. A census over two numbers
|
|
393
|
+
// cannot see whether a writer exists, and the previous wording
|
|
394
|
+
// asserted it did not.
|
|
395
|
+
why:
|
|
396
|
+
`${t.against} ${t.label}, and this lane is empty — either nothing moves them ` +
|
|
397
|
+
`or whatever does has not run`,
|
|
398
|
+
};
|
|
399
|
+
}
|
|
400
|
+
if (count < t.against) {
|
|
401
|
+
return {
|
|
402
|
+
lane,
|
|
403
|
+
count,
|
|
404
|
+
against: t.against,
|
|
405
|
+
health: "SHORT" as const,
|
|
406
|
+
why: `${t.against} ${t.label}, so up to ${t.against - count} are missing from this lane`,
|
|
407
|
+
};
|
|
408
|
+
}
|
|
409
|
+
if (count > t.against) {
|
|
410
|
+
return {
|
|
411
|
+
lane,
|
|
412
|
+
count,
|
|
413
|
+
against: t.against,
|
|
414
|
+
health: "OVER" as const,
|
|
415
|
+
why: `${t.against} ${t.label}, and the lane holds ${count} — ${count - t.against} too many`,
|
|
416
|
+
};
|
|
417
|
+
}
|
|
418
|
+
return {
|
|
419
|
+
lane,
|
|
420
|
+
count,
|
|
421
|
+
against: t.against,
|
|
422
|
+
health: "OK" as const,
|
|
423
|
+
why: `${t.against} ${t.label}, and the lane holds ${count}`,
|
|
424
|
+
};
|
|
425
|
+
});
|
|
426
|
+
return [
|
|
427
|
+
...known,
|
|
428
|
+
...unknown.map(lane => ({
|
|
429
|
+
lane,
|
|
430
|
+
count: c.counts.get(lane) ?? 0,
|
|
431
|
+
against: null,
|
|
432
|
+
health: "UNMEASURED" as const,
|
|
433
|
+
// **One sentence for every unknown key, whatever it is spelled.** A
|
|
434
|
+
// first pass branched this on `startsWith("(")` to word the caller's
|
|
435
|
+
// own `"(no status)"` marker differently. No row was suppressed by
|
|
436
|
+
// it, so it was misleading text rather than a drop — but a board lane
|
|
437
|
+
// genuinely named `"(parked)"` would have been told its items are in
|
|
438
|
+
// no lane, which is false, and the commit that removed the exclusion
|
|
439
|
+
// claimed nothing was classified by spelling. Carrying that
|
|
440
|
+
// distinction honestly means typed census fields, which is a change
|
|
441
|
+
// to the caller and not to this decider. Round 2 security review.
|
|
442
|
+
why: `this report does not know the lane "${lane}", so its items are unaccounted for above`,
|
|
443
|
+
})),
|
|
444
|
+
];
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
/**
|
|
448
|
+
* What `handPlacedInReview` reads. #1921, SC-2759.
|
|
449
|
+
*/
|
|
450
|
+
export interface InReviewCensus {
|
|
451
|
+
/** Open issues whose card's Status is In review. */
|
|
452
|
+
readonly inReview: readonly number[];
|
|
453
|
+
/**
|
|
454
|
+
* Issues on this repository that an OPEN pull request declares it closes,
|
|
455
|
+
* through `closingIssuesReferences` — declares, not mentions. Drafts count:
|
|
456
|
+
* a ready pull request converted back to draft leaves its issue in In
|
|
457
|
+
* review with no event to move it, so that card was not placed by hand.
|
|
458
|
+
*/
|
|
459
|
+
readonly declaredClosing: ReadonlySet<number>;
|
|
460
|
+
/** Open pull requests whose closing list did not fit one page. */
|
|
461
|
+
readonly closingTruncated: readonly number[];
|
|
462
|
+
/** False when the board could not be paged in full. */
|
|
463
|
+
readonly complete: boolean;
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
export type HandPlacedReading =
|
|
467
|
+
| {
|
|
468
|
+
readonly kind: "read";
|
|
469
|
+
/**
|
|
470
|
+
* How many distinct In-review issue cards were checked. Carried so an
|
|
471
|
+
* empty lane and a lane checked and found covered never print the same
|
|
472
|
+
* sentence — "every card has a pull request" over zero cards is
|
|
473
|
+
* vacuously true (review round 1 of #2134).
|
|
474
|
+
*/
|
|
475
|
+
readonly checked: number;
|
|
476
|
+
readonly issues: readonly number[];
|
|
477
|
+
}
|
|
478
|
+
| { readonly kind: "unmeasured"; readonly why: string };
|
|
479
|
+
|
|
480
|
+
/**
|
|
481
|
+
* Issue cards in In review that no open pull request declares it closes.
|
|
482
|
+
* #1921, SC-2759.
|
|
483
|
+
*
|
|
484
|
+
* In review's entry condition in `specs/BOARD-FLOW-SPEC.md` is a ready pull
|
|
485
|
+
* request, and `lib/board-flow.ts` resolves `pr_ready`'s target through the
|
|
486
|
+
* pull request's closing references. Measured on #1921: no writer in this
|
|
487
|
+
* repository puts an issue card in In review without one, and with none, no
|
|
488
|
+
* event will ever move it out — the lane's exits resolve through the same
|
|
489
|
+
* declaration. So the card was placed by hand, or its pull request stopped
|
|
490
|
+
* declaring it after it entered; either way only a person can move it.
|
|
491
|
+
*
|
|
492
|
+
* **A second source for a lane the header above gives none**, without being
|
|
493
|
+
* a denominator: the In review row stays NO_TARGET and this names cards.
|
|
494
|
+
* #1717 sat there a week with no link ever on its timeline, and the only
|
|
495
|
+
* visible symptom was In progress reading SHORT — blaming the wrong lane.
|
|
496
|
+
*
|
|
497
|
+
* UNMEASURED, never an empty list, when either input is partial: a board
|
|
498
|
+
* read in part may be missing the card, and a cut closing list reads the
|
|
499
|
+
* issue it would have declared as having none.
|
|
500
|
+
*/
|
|
501
|
+
export function handPlacedInReview(c: InReviewCensus): HandPlacedReading {
|
|
502
|
+
if (!c.complete) {
|
|
503
|
+
return {
|
|
504
|
+
kind: "unmeasured",
|
|
505
|
+
why: "the board could not be paged in full, so a card in In review may be missing from it",
|
|
506
|
+
};
|
|
507
|
+
}
|
|
508
|
+
if (c.closingTruncated.length > 0) {
|
|
509
|
+
const cut = [...c.closingTruncated].sort((a, b) => a - b).map(n => `#${n}`).join(", ");
|
|
510
|
+
return {
|
|
511
|
+
kind: "unmeasured",
|
|
512
|
+
why: `the closing list of ${cut} did not fit one page, so an issue it declares would read as having no pull request`,
|
|
513
|
+
};
|
|
514
|
+
}
|
|
515
|
+
const cards = [...new Set(c.inReview)];
|
|
516
|
+
const issues = cards.filter(n => !c.declaredClosing.has(n)).sort((a, b) => a - b);
|
|
517
|
+
return { kind: "read", checked: cards.length, issues };
|
|
518
|
+
}
|
|
519
|
+
|
|
520
|
+
/** The line the report prints for `handPlacedInReview`, one per state. */
|
|
521
|
+
export function handPlacedInReviewLine(r: HandPlacedReading): string {
|
|
522
|
+
if (r.kind === "unmeasured") return ` (hand-placed In review cards UNMEASURED — ${r.why})`;
|
|
523
|
+
if (r.checked === 0) return ` no issue card is in In review, so none is hand-placed`;
|
|
524
|
+
if (r.issues.length === 0) {
|
|
525
|
+
return ` all ${r.checked} issue card(s) in In review have an open pull request declaring it closes the issue`;
|
|
526
|
+
}
|
|
527
|
+
return (
|
|
528
|
+
` ${r.issues.length} issue card(s) in In review are hand-placed — no open pull request declares it ` +
|
|
529
|
+
`closes them, nothing in this repository writes In review without one, and no event will move them ` +
|
|
530
|
+
`out: ${r.issues.map(n => `#${n}`).join(", ")}`
|
|
531
|
+
);
|
|
532
|
+
}
|
|
533
|
+
|
|
534
|
+
/**
|
|
535
|
+
* The lines the report prints.
|
|
536
|
+
*
|
|
537
|
+
* Separated from the caller so the report itself can be asserted. A lane
|
|
538
|
+
* missing from the printed output is the failure this exists to catch, and
|
|
539
|
+
* it is invisible when the formatting lives inside the I/O.
|
|
540
|
+
*/
|
|
541
|
+
/**
|
|
542
|
+
* `offBoard` is **a required parameter and not a census field**, because it
|
|
543
|
+
* was briefly both.
|
|
544
|
+
*
|
|
545
|
+
* It was declared on `LaneCensus`, documented at length, and never read —
|
|
546
|
+
* the printed line came from this parameter, and the two agreed only
|
|
547
|
+
* because one caller passed the same variable to each. A caller using the
|
|
548
|
+
* one-argument form, which the optional default allowed, would have
|
|
549
|
+
* printed `UNMEASURED` with the correct value sitting on the census it had
|
|
550
|
+
* just built. A field with no reader and a default that invents a reading,
|
|
551
|
+
* in the change written to remove exactly that. ai-review round 2 of
|
|
552
|
+
* #1802.
|
|
553
|
+
*
|
|
554
|
+
* Required, so there is no form of this call that can omit the reading;
|
|
555
|
+
* `null` has to be passed deliberately and still means UNMEASURED.
|
|
556
|
+
*/
|
|
557
|
+
export function laneHealthLines(
|
|
558
|
+
readings: readonly LaneReading[],
|
|
559
|
+
offBoard: number | null,
|
|
560
|
+
): string[] {
|
|
561
|
+
const lines = readings.map(r => {
|
|
562
|
+
const against = r.against === null ? "" : ` of ${r.against}`;
|
|
563
|
+
return ` ${r.lane.padEnd(12)} ${String(r.count).padStart(4)}${against.padEnd(8)} ${r.health.padEnd(11)} ${r.why}`;
|
|
564
|
+
});
|
|
565
|
+
// **Printed whatever it reads, including zero.** Omitting the line when
|
|
566
|
+
// nothing is off the board makes "none are missing" and "nobody looked"
|
|
567
|
+
// the same output, which is the distinction every other row here exists
|
|
568
|
+
// to keep (SC-2730). `null` is the third state and says so.
|
|
569
|
+
lines.push(
|
|
570
|
+
offBoard === null
|
|
571
|
+
? ` (board membership UNMEASURED — whether any open issue is missing from the board was not read)`
|
|
572
|
+
: offBoard === 0
|
|
573
|
+
? ` every open issue is on the board`
|
|
574
|
+
: ` ${offBoard} open issue(s) are NOT on the board at all — no lane writer can move them, ` +
|
|
575
|
+
`and no row above counts them`,
|
|
576
|
+
);
|
|
577
|
+
return lines;
|
|
578
|
+
}
|