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,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
+ }