rungate 0.8.13 → 0.8.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/README.md +82 -0
  2. package/gates/.gate-salt +1 -1
  3. package/hooks/VerifyPhaseLock.hook.ts +3 -3
  4. package/lib/ai-review-rounds.ts +99 -0
  5. package/lib/ai-review-suppression.ts +200 -21
  6. package/lib/bash-write-guard.ts +50 -5
  7. package/lib/board-flow.ts +235 -0
  8. package/lib/board-lane-health.ts +381 -0
  9. package/lib/board-mirror.ts +53 -35
  10. package/lib/board-ready-fanout.ts +56 -13
  11. package/lib/board-ready-rule.ts +545 -0
  12. package/lib/board-throughput.ts +136 -0
  13. package/lib/board-walkthrough.ts +240 -0
  14. package/lib/body-evidence.ts +203 -0
  15. package/lib/branch-protection.ts +399 -9
  16. package/lib/conformity.ts +95 -2
  17. package/lib/filing-compliance.ts +367 -0
  18. package/lib/finding-arbiter.ts +79 -5
  19. package/lib/generators/agents-md.ts +149 -0
  20. package/lib/github.ts +79 -0
  21. package/lib/graphql-cursor.ts +80 -0
  22. package/lib/issue-create-override.ts +415 -3
  23. package/lib/issue-decomposition.ts +33 -3
  24. package/lib/issue-file-overlap.ts +340 -0
  25. package/lib/issue-filing-gate.ts +173 -8
  26. package/lib/issue-repair.ts +13 -9
  27. package/lib/issue-shape.ts +196 -0
  28. package/lib/scaffold/ai-review-findings.ts +9 -1
  29. package/lib/scaffold/ai-review-step.ts +35 -1
  30. package/lib/source-census.ts +108 -0
  31. package/lib/spec-deps.ts +34 -11
  32. package/lib/spec-placement.ts +108 -0
  33. package/lib/stage-ladder.ts +28 -3
  34. package/lib/work-status.ts +423 -0
  35. package/package.json +1 -1
  36. package/scripts/ai-review-findings.ts +8 -13
  37. package/scripts/ai-review-threads.ts +16 -17
  38. package/scripts/board-mirror.ts +221 -8
  39. package/scripts/generate-code-map.ts +1 -1
  40. package/scripts/plan-spec.ts +79 -1
@@ -0,0 +1,235 @@
1
+ /**
2
+ * Which lane does a GitHub event mean?
3
+ *
4
+ * Covers SC-2690, SC-2691, SC-2692 (specs/BOARD-FLOW-SPEC.md).
5
+ *
6
+ * ## Why this is a module and not three `if`s in YAML
7
+ *
8
+ * `specs/BOARD-FLOW-SPEC.md` settled every lane's entry and exit as a named
9
+ * GitHub event, on the rule that a condition no event can decide is a
10
+ * condition a person applies by hand. This file is the whole of that
11
+ * mapping, in one place, so there is **one decider per transition**.
12
+ *
13
+ * That is not tidiness. Two guards answering the same question about the
14
+ * same input are behaviourally ONE guard: a mutation of either leaves the
15
+ * other holding the case up, both read as covered, and nobody can see which
16
+ * is dead. The board had exactly that — GitHub's built-in project
17
+ * automations and our workflows both writing Status — and the walk-through
18
+ * caught it as row 4 landing in `In progress` when it expected `In review`.
19
+ *
20
+ * **So two built-ins are switched off**, and the project settings page is
21
+ * the only place that is visible. `.github/workflows/board-flow.yml` names
22
+ * them; this file names them too, because a reader who finds only one of
23
+ * the two statements has no way to know the other exists.
24
+ *
25
+ * ## Every lane here is an ISSUE's card
26
+ *
27
+ * Two of the events below are pull-request events, and they still move the
28
+ * card of the ISSUE the pull request closes — which is what
29
+ * `specs/BOARD-FLOW-SPEC.md`'s lane table says: In review's entry is "a
30
+ * linked PR is not a draft", and the walk-through's row 4 expects issue B
31
+ * in In review after a PR saying `Fixes #B`.
32
+ *
33
+ * The PULL REQUEST's own card is `board-intake.yml`'s, which moves it to In
34
+ * review on `opened`/`ready_for_review`. Same lane name, different item, so
35
+ * this is not a second decider — nothing here ever writes a PR's card and
36
+ * nothing there ever writes an issue's.
37
+ *
38
+ * ## It decides, it does not write
39
+ *
40
+ * No network, no project id, no token. `scripts/board-flow.ts` performs the
41
+ * write. A decider that also writes cannot be exercised without a board,
42
+ * and a transition nobody can test offline is a transition that gets tested
43
+ * in production — which is how six consecutive Ready-lane failures went
44
+ * unnoticed.
45
+ */
46
+
47
+ /** The board lanes, as `specs/BOARD-FLOW-SPEC.md` names them. */
48
+ export type Lane = "Backlog" | "Ready" | "In progress" | "In review" | "Done" | "Cancelled";
49
+
50
+ /**
51
+ * Every event kind this decider answers for.
52
+ *
53
+ * Exported so a test can enumerate the decider's own domain rather than
54
+ * restating it — a second hand-written list would drift, and the drift
55
+ * would be invisible exactly when a new event was added.
56
+ */
57
+ export const LANE_EVENTS = [
58
+ "issue_assigned",
59
+ "issue_closed",
60
+ "issue_reopened",
61
+ "pr_ready",
62
+ "pr_closed_unmerged",
63
+ ] as const;
64
+
65
+ export interface LaneEvent {
66
+ readonly kind: (typeof LANE_EVENTS)[number];
67
+ /**
68
+ * GitHub's `state_reason`, for `issue_closed` only.
69
+ *
70
+ * Read as GraphQL spells it — `COMPLETED`, `NOT_PLANNED`, `DUPLICATE`.
71
+ * The caller normalises; this compares exactly, because a loose
72
+ * comparison on the field that separates "delivered" from "abandoned" is
73
+ * the one place a near-match must not pass.
74
+ */
75
+ readonly stateReason?: string | null;
76
+ }
77
+
78
+ export interface LaneDecision {
79
+ /** The lane to write, or `null` to write nothing and say why. */
80
+ readonly lane: Lane | null;
81
+ readonly why: string;
82
+ }
83
+
84
+ /**
85
+ * The closure reasons that mean the work was abandoned rather than done.
86
+ *
87
+ * Both, because `specs/BOARD-FLOW-SPEC.md` defines Cancelled's entry as
88
+ * "closed as `not_planned` or `duplicate`" and `lib/work-status.ts` already
89
+ * maps both to ABANDONED. Counting only the first reads a cancellation as a
90
+ * delivery.
91
+ */
92
+ const ABANDONED = new Set(["NOT_PLANNED", "DUPLICATE"]);
93
+
94
+ /**
95
+ * The lanes a pull-request event may not pull an issue out of.
96
+ *
97
+ * Done and Cancelled are terminal: the work either shipped or was decided
98
+ * against, and in both cases the clock has stopped. `specs/BOARD-FLOW-SPEC.md`
99
+ * puts the whole forecast on that — Done defines throughput, Cancelled
100
+ * protects Little's Law's second assumption — so a card leaving either one
101
+ * by accident is not a cosmetic error.
102
+ */
103
+ const TERMINAL: readonly string[] = ["Done", "Cancelled"];
104
+
105
+ /**
106
+ * May a PULL REQUEST event write this issue's card, given where it sits now?
107
+ *
108
+ * **Authorisation and the target set are answered by different parties**,
109
+ * which is the confused deputy. `.github/workflows/board-flow.yml` gates on
110
+ * the ACTOR: for `opened` and `ready_for_review` that is the pull request's
111
+ * author, so an outside contributor is refused outright. For `closed` it is
112
+ * whoever closed it — ordinarily a maintainer — while the closing references
113
+ * naming which issues to move still come from the contributor's body.
114
+ *
115
+ * So a drive-by pull request saying `Fixes #N` would pull #N out of Done the
116
+ * moment anybody with write access closed it. The refusal below is also
117
+ * right on the merits: work that shipped did not become unshipped because
118
+ * somebody else's branch was abandoned.
119
+ *
120
+ * ISSUE events are deliberately not subject to this. An issue reopening IS
121
+ * the legitimate way out of Done, it is the spec's own rule, and the actor
122
+ * who reopens is the actor the gate authorised.
123
+ *
124
+ * `null` — a card with no Status at all — is allowed through. It is not a
125
+ * terminal lane, and refusing it would make an unset column unreachable.
126
+ */
127
+ export function prEventMayWrite(currentLane: string | null): { allowed: boolean; why: string } {
128
+ if (currentLane !== null && TERMINAL.includes(currentLane)) {
129
+ return {
130
+ allowed: false,
131
+ why:
132
+ `the card is in ${currentLane}, which is terminal. A pull request event may not move ` +
133
+ `it out: the closing references that name this issue are authored by the pull ` +
134
+ `request, while the permission check answered for whoever closed it. Reopen the ` +
135
+ `issue if the work is genuinely not finished.`,
136
+ };
137
+ }
138
+ return { allowed: true, why: `${currentLane ?? "(no status)"} is not a terminal lane` };
139
+ }
140
+
141
+ /**
142
+ * Which identities must clear the permission check before this event writes?
143
+ *
144
+ * **Authorise the party that chose the targets, not only the one who fired.**
145
+ * `prEventMayWrite` above removes the worst outcome of the confused deputy
146
+ * and does not close it: a drive-by pull request saying `Fixes #N`, where #N
147
+ * sits in Backlog, Ready, In progress or In review, still moves #N the moment
148
+ * any maintainer closes that pull request. The lane is not terminal, the
149
+ * guard passes it, and the card churns on a reference nobody with write
150
+ * access wrote.
151
+ *
152
+ * So a pull request event authorises two identities: the actor who fired it,
153
+ * and the author of the body the closing references came from. An issue event
154
+ * authorises one, because an issue event carries no contributor-authored
155
+ * target set — the issue IS the target — and demanding a second there would
156
+ * refuse ordinary maintainer work.
157
+ *
158
+ * `null` is UNMEASURED: a pull request event whose author could not be read.
159
+ * Falling back to the actor alone would be the silent default, turning an
160
+ * author nobody could read into an author nobody checked.
161
+ *
162
+ * Duplicates are collapsed, so a maintainer closing their own pull request
163
+ * is one permission call rather than two identical ones.
164
+ */
165
+ export function identitiesToAuthorise(
166
+ kind: LaneEvent["kind"],
167
+ actor: string,
168
+ prAuthor: string | null,
169
+ ): string[] | null {
170
+ if (kind.startsWith("issue_")) return [actor];
171
+ if (prAuthor === null || prAuthor === "") return null;
172
+ return actor === prAuthor ? [actor] : [actor, prAuthor];
173
+ }
174
+
175
+ export function laneFor(e: LaneEvent): LaneDecision {
176
+ switch (e.kind) {
177
+ case "issue_assigned":
178
+ // Assignment, and only because `.claude/rules/parallel-sessions.md`
179
+ // already requires a worker to claim an issue by assigning themselves
180
+ // BEFORE writing code. Industry is consistent that assignment is not
181
+ // a start signal; what differs here is that ours is the first
182
+ // physical act rather than a statement of future ownership. If that
183
+ // rule is ever relaxed, this case has to change with it.
184
+ return { lane: "In progress", why: "assignment is this repository's declared starting act" };
185
+
186
+ case "pr_ready":
187
+ // The LINKED ISSUE's card, not the pull request's — see the header.
188
+ // The caller filters drafts out, so reaching here means a pull
189
+ // request that is genuinely waiting on a reviewer. In review has to
190
+ // mean that or it cannot measure the constraint it exists to measure.
191
+ return { lane: "In review", why: "a non-draft pull request is finished work waiting on a reviewer" };
192
+
193
+ case "issue_reopened":
194
+ case "pr_closed_unmerged":
195
+ // **One rule for everything that goes backwards.** An item that went
196
+ // backwards has a blocker graph nobody has re-checked, and Ready's
197
+ // entry condition is precisely a claim about that graph — so going
198
+ // straight back to Ready would assert something nobody verified.
199
+ // Backlog is not a penalty: `board-ready.yml` re-tests eligibility
200
+ // and re-promotes on its own.
201
+ return {
202
+ lane: "Backlog",
203
+ why: "work moving backwards has an unverified blocker graph, so eligibility is re-checked",
204
+ };
205
+
206
+ case "issue_closed": {
207
+ const reason = e.stateReason;
208
+ if (reason === "COMPLETED") return { lane: "Done", why: "closed as completed" };
209
+ if (typeof reason === "string" && ABANDONED.has(reason)) {
210
+ return { lane: "Cancelled", why: `closed as ${reason.toLowerCase()}` };
211
+ }
212
+ // **A reason this file does not know is not a completed close.**
213
+ // Absent, misspelled, or a value GitHub adds after this was written —
214
+ // all three are unknown, and writing Done for an unknown outcome
215
+ // overstates throughput and contaminates every cycle-time percentile,
216
+ // silently, because a card in Done looks like a card in Done. The
217
+ // refusal names the value so the run is actionable rather than quiet.
218
+ return {
219
+ lane: null,
220
+ why:
221
+ `state_reason ${JSON.stringify(reason)} is not one this decider knows, so the ` +
222
+ `outcome is UNKNOWN rather than completed and nothing is written`,
223
+ };
224
+ }
225
+
226
+ default:
227
+ // An event kind nobody added a case for. Refusing names it; falling
228
+ // through to a default lane would move a card on a rule that does not
229
+ // exist.
230
+ return {
231
+ lane: null,
232
+ why: `no rule for event kind ${JSON.stringify((e as LaneEvent).kind)}`,
233
+ };
234
+ }
235
+ }
@@ -0,0 +1,381 @@
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.
28
+ */
29
+
30
+ import { READY_TOLERANCE_DAYS, readyCap, readyTarget, type Throughput } from "./board-ready-rule";
31
+
32
+ /** Every lane name the board uses, in flow order. */
33
+ export const LANES: readonly string[] = [
34
+ "Backlog",
35
+ "Ready",
36
+ "In progress",
37
+ "In review",
38
+ "Done",
39
+ "Cancelled",
40
+ ];
41
+
42
+ export type LaneHealth =
43
+ /** Holding what it should, measured against a denominator. */
44
+ | "OK"
45
+ /** Has a writer and a denominator, and is below it. */
46
+ | "SHORT"
47
+ /**
48
+ * Above its denominator.
49
+ *
50
+ * Only reachable since Ready gained a cap, and it appeared on the first
51
+ * live run: the lane held 5 against a derived depth of 4, filled under
52
+ * the uncapped rule. Before the cap, `count > against` could not happen
53
+ * for any lane with a repo-wide denominator, so OK absorbed it.
54
+ *
55
+ * It is a verdict of its own for the reason SHORT and UNWRITTEN are:
56
+ * **the remedy is different.** SHORT means promote more, OVER means stop
57
+ * promoting and let the queue drain. Reporting an over-full commitment
58
+ * point as OK is the lane lying in the other direction, which is exactly
59
+ * what the negative control in the walk-through exists to catch.
60
+ */
61
+ | "OVER"
62
+ /**
63
+ * Empty while its denominator is not.
64
+ *
65
+ * **It does not mean "nothing writes this lane", and it used to say so.**
66
+ * That sentence named a mechanism the census never looked at, and it was
67
+ * false from 2026-11-05: `lib/board-flow.ts` moves an issue to Cancelled
68
+ * on a `not_planned` close, with a recorded run, while this row still
69
+ * reported the lane unwritten. An empty lane has at least two causes —
70
+ * no writer, or a writer whose population the denominator does not
71
+ * share — and only the second was true (SC-2731).
72
+ */
73
+ | "UNWRITTEN"
74
+ /** No denominator exists, so the count is reported and nothing is judged. */
75
+ | "NO_TARGET"
76
+ /** The census could not be taken. Never the same as OK. */
77
+ | "UNMEASURED";
78
+
79
+ export interface LaneCensus {
80
+ /** Lane name to the number of items the board shows in it. */
81
+ readonly counts: ReadonlyMap<string, number>;
82
+ /**
83
+ * Open issues that are unblocked and unclaimed **on this board**.
84
+ *
85
+ * Board-scoped like the others. Today the cap hides the difference —
86
+ * `readyTarget` takes the smaller of this and the depth, and this is far
87
+ * the larger — but a board holding fewer pickable issues than the cap
88
+ * would read SHORT against work that does not exist.
89
+ */
90
+ readonly pickable: number;
91
+ /**
92
+ * Open issues with at least one assignee **that are on this board**.
93
+ *
94
+ * Scoped for the same reason `cancelledClosed` is: the numerator counts
95
+ * board items, so a denominator counting repository issues reports a gap
96
+ * no writer could close. Read repo-wide it said `In progress 1 of 10`
97
+ * while the board held far fewer assigned issues than the repository did
98
+ * (SC-2730).
99
+ */
100
+ readonly openAssigned: number;
101
+ /**
102
+ * Issues **on this board** closed as `NOT_PLANNED` or `DUPLICATE`, or
103
+ * `null` when the count could not be taken.
104
+ *
105
+ * ## On this board, because the numerator is
106
+ *
107
+ * It used to be the repository-wide count, and that made the row compare
108
+ * a board lane against a population the board's writer never sees. On
109
+ * 2026-11-05 it read `Cancelled 0 of 23 UNWRITTEN`, and all 23 were
110
+ * issues closed before `lib/board-flow.ts` had a Cancelled branch or
111
+ * never added to the board at all. A denominator that counts things the
112
+ * numerator cannot contain reports a gap that no writer could close
113
+ * (SC-2730).
114
+ *
115
+ * **Both reasons, because the spec's condition is both.**
116
+ * `specs/BOARD-FLOW-SPEC.md` defines Cancelled's entry as "closed as
117
+ * `not_planned` or `duplicate`" and `lib/work-status.ts` already maps both
118
+ * to ABANDONED. Counting only the first turns a lane that is SHORT by
119
+ * however many duplicates exist into one that reads OK — ai-review round 1,
120
+ * finding 1.
121
+ *
122
+ * **`null` rather than `0`**, because they are opposite facts wearing the
123
+ * same digit: zero cancellations makes Cancelled correct, and a read that
124
+ * failed makes it unknown. Collapsing them produces a green lane out of a
125
+ * measurement that never happened — security review of the pushed commit,
126
+ * finding 1.
127
+ */
128
+ readonly cancelledClosed: number | null;
129
+ /**
130
+ * How much the repository delivered, over how long — or `null` when that
131
+ * could not be read.
132
+ *
133
+ * Ready's denominator is **capped**, and the cap is derived from this
134
+ * rather than typed in (`lib/board-ready-rule.ts`). Before 2026-11-05 the
135
+ * row compared the lane against every pickable issue in the repository
136
+ * with no bound at all, which is how it came to report `SHORT by 30`
137
+ * against a writer that could never promote more than 3.
138
+ *
139
+ * It is a required field rather than an optional one so that every caller
140
+ * has to say what it measured. `null` makes the row UNMEASURED; there is
141
+ * no fallback depth, because a built-in default substituted for a failed
142
+ * read is indistinguishable from a real one.
143
+ */
144
+ readonly throughput: Throughput | null;
145
+ /**
146
+ * False when the board could not be paged in full.
147
+ *
148
+ * A partial page and an empty lane produce the same count, and that
149
+ * ambiguity is the whole subject here — so an incomplete census refuses
150
+ * every row rather than reporting the numbers it happens to hold.
151
+ */
152
+ readonly complete: boolean;
153
+ }
154
+
155
+ export interface LaneReading {
156
+ readonly lane: string;
157
+ readonly count: number;
158
+ /** What the lane should hold. `null` when nothing cheap can say. */
159
+ readonly against: number | null;
160
+ readonly health: LaneHealth;
161
+ readonly why: string;
162
+ }
163
+
164
+ /**
165
+ * The denominator for each lane that has one, and why it is that one.
166
+ *
167
+ * ## The denominators are board-scoped, reversing an earlier decision
168
+ *
169
+ * They were repo-wide, deliberately: the security review of the pushed
170
+ * commit (finding 3) argued that scoping them to board items would hide a
171
+ * more important failure — an eligible issue that never reached the board
172
+ * at all — so the mismatch was declared rather than removed.
173
+ *
174
+ * **That traded a readable row for an unreadable one, and the cost showed
175
+ * up on 2026-11-05.** The Cancelled row read `0 of 23 UNWRITTEN — nothing
176
+ * writes it`, which says the writer is broken. The writer was fine; all 23
177
+ * were issues the board had never held. A row whose two numbers describe
178
+ * different populations cannot be read correctly by anyone, and declaring
179
+ * the mismatch in a label does not fix that — the label said "repo-wide"
180
+ * the whole time and the row was still misread, by me, for a day.
181
+ *
182
+ * The earlier concern was right about the failure being important and
183
+ * wrong about where it belongs: **it is a fact about board MEMBERSHIP, not
184
+ * about any lane.** It is now its own reading — `offBoard` — so both
185
+ * survive and neither is inferred from the other. One row, one population.
186
+ *
187
+ * `undefined` means this lane has no denominator; `null` inside one means
188
+ * the denominator exists but could not be read.
189
+ */
190
+ function target(lane: string, c: LaneCensus): { against: number | null; label: string } | undefined {
191
+ if (lane === "Ready") {
192
+ // **The cap is half the denominator, and it is why this row stopped
193
+ // lying.** Ready is a commitment point, not a mirror of the backlog, so
194
+ // what it SHOULD hold is the smaller of "everything eligible" and "the
195
+ // depth the queue is allowed". Comparing against the eligible set alone
196
+ // made a correctly-sized lane read SHORT forever.
197
+ const cap = c.throughput === null ? null : readyCap(c.throughput);
198
+ return {
199
+ against: readyTarget(c.pickable, cap),
200
+ label:
201
+ cap === null
202
+ ? "throughput, which Ready's depth is derived from,"
203
+ : `allowed in the queue — ${c.pickable} unblocked and unclaimed on this board, capped at a ` +
204
+ `depth of ${cap} derived from ${READY_TOLERANCE_DAYS} day(s) of live throughput`,
205
+ };
206
+ }
207
+ if (lane === "In progress") {
208
+ return { against: c.openAssigned, label: "on this board are open and assigned" };
209
+ }
210
+ if (lane === "Cancelled") {
211
+ return {
212
+ against: c.cancelledClosed,
213
+ label: "on this board are closed as not_planned or duplicate",
214
+ };
215
+ }
216
+ return undefined;
217
+ }
218
+
219
+ /**
220
+ * One reading per lane, in flow order.
221
+ *
222
+ * A lane the board never mentioned reads `0`, which is correct: the board
223
+ * showing no items in a lane and the board having no such lane are the same
224
+ * fact from the outside, and both mean nothing is in it.
225
+ */
226
+ export function laneHealth(c: LaneCensus): LaneReading[] {
227
+ // **Every key the census holds gets a row, and nothing is excluded by
228
+ // spelling.** Mapping over LANES alone meant a lane the board has and this
229
+ // file does not know about contributed items to no row at all, so the
230
+ // report stayed confident and complete-looking while part of the board was
231
+ // simply absent from it. Adding a lane on the board is two clicks and
232
+ // nobody would think to mirror it here. Security review of the pushed
233
+ // commit, finding 4.
234
+ //
235
+ // The first fix for that swept unknown keys up but skipped any beginning
236
+ // `"("`, which put the caller's own `"(no status)"` marker straight back
237
+ // into the hole it had just closed — the SAME omission, one line below the
238
+ // sweep written to stop it. Found independently by ai-review round 1 and
239
+ // by the security review of the pushed commit. A prefix exclusion is also
240
+ // forgeable: a lane somebody genuinely names `"(parked)"` on the board
241
+ // would be suppressed by impersonating a marker. So there is no exclusion
242
+ // left — a key that is not a known lane is reported, whatever it says.
243
+ const unknown = [...c.counts.keys()].filter(k => !LANES.includes(k)).sort();
244
+ const known = LANES.map(lane => {
245
+ const count = c.counts.get(lane) ?? 0;
246
+ if (!c.complete) {
247
+ return {
248
+ lane,
249
+ count,
250
+ against: null,
251
+ health: "UNMEASURED" as const,
252
+ why: "the board could not be paged in full, so this count is a floor and not a reading",
253
+ };
254
+ }
255
+ const t = target(lane, c);
256
+ if (t === undefined) {
257
+ return {
258
+ lane,
259
+ count,
260
+ against: null,
261
+ health: "NO_TARGET" as const,
262
+ why: "no second source says what should be here, so the count is reported and nothing is judged",
263
+ };
264
+ }
265
+ // The denominator exists but could not be read. A failed search is not
266
+ // a repository with nothing in it.
267
+ if (t.against === null) {
268
+ return {
269
+ lane,
270
+ count,
271
+ against: null,
272
+ health: "UNMEASURED" as const,
273
+ why: `the ${t.label} count could not be read, so this lane has no denominator to judge against`,
274
+ };
275
+ }
276
+ if (count === 0 && t.against > 0) {
277
+ return {
278
+ lane,
279
+ count,
280
+ against: t.against,
281
+ health: "UNWRITTEN" as const,
282
+ // States what was counted, not why. A census over two numbers
283
+ // cannot see whether a writer exists, and the previous wording
284
+ // asserted it did not.
285
+ why:
286
+ `${t.against} ${t.label}, and this lane is empty — either nothing moves them ` +
287
+ `or whatever does has not run`,
288
+ };
289
+ }
290
+ if (count < t.against) {
291
+ return {
292
+ lane,
293
+ count,
294
+ against: t.against,
295
+ health: "SHORT" as const,
296
+ why: `${t.against} ${t.label}, so up to ${t.against - count} are missing from this lane`,
297
+ };
298
+ }
299
+ if (count > t.against) {
300
+ return {
301
+ lane,
302
+ count,
303
+ against: t.against,
304
+ health: "OVER" as const,
305
+ why: `${t.against} ${t.label}, and the lane holds ${count} — ${count - t.against} too many`,
306
+ };
307
+ }
308
+ return {
309
+ lane,
310
+ count,
311
+ against: t.against,
312
+ health: "OK" as const,
313
+ why: `${t.against} ${t.label}, and the lane holds ${count}`,
314
+ };
315
+ });
316
+ return [
317
+ ...known,
318
+ ...unknown.map(lane => ({
319
+ lane,
320
+ count: c.counts.get(lane) ?? 0,
321
+ against: null,
322
+ health: "UNMEASURED" as const,
323
+ // **One sentence for every unknown key, whatever it is spelled.** A
324
+ // first pass branched this on `startsWith("(")` to word the caller's
325
+ // own `"(no status)"` marker differently. No row was suppressed by
326
+ // it, so it was misleading text rather than a drop — but a board lane
327
+ // genuinely named `"(parked)"` would have been told its items are in
328
+ // no lane, which is false, and the commit that removed the exclusion
329
+ // claimed nothing was classified by spelling. Carrying that
330
+ // distinction honestly means typed census fields, which is a change
331
+ // to the caller and not to this decider. Round 2 security review.
332
+ why: `this report does not know the lane "${lane}", so its items are unaccounted for above`,
333
+ })),
334
+ ];
335
+ }
336
+
337
+ /**
338
+ * The lines the report prints.
339
+ *
340
+ * Separated from the caller so the report itself can be asserted. A lane
341
+ * missing from the printed output is the failure this exists to catch, and
342
+ * it is invisible when the formatting lives inside the I/O.
343
+ */
344
+ /**
345
+ * `offBoard` is **a required parameter and not a census field**, because it
346
+ * was briefly both.
347
+ *
348
+ * It was declared on `LaneCensus`, documented at length, and never read —
349
+ * the printed line came from this parameter, and the two agreed only
350
+ * because one caller passed the same variable to each. A caller using the
351
+ * one-argument form, which the optional default allowed, would have
352
+ * printed `UNMEASURED` with the correct value sitting on the census it had
353
+ * just built. A field with no reader and a default that invents a reading,
354
+ * in the change written to remove exactly that. ai-review round 2 of
355
+ * #1802.
356
+ *
357
+ * Required, so there is no form of this call that can omit the reading;
358
+ * `null` has to be passed deliberately and still means UNMEASURED.
359
+ */
360
+ export function laneHealthLines(
361
+ readings: readonly LaneReading[],
362
+ offBoard: number | null,
363
+ ): string[] {
364
+ const lines = readings.map(r => {
365
+ const against = r.against === null ? "" : ` of ${r.against}`;
366
+ return ` ${r.lane.padEnd(12)} ${String(r.count).padStart(4)}${against.padEnd(8)} ${r.health.padEnd(11)} ${r.why}`;
367
+ });
368
+ // **Printed whatever it reads, including zero.** Omitting the line when
369
+ // nothing is off the board makes "none are missing" and "nobody looked"
370
+ // the same output, which is the distinction every other row here exists
371
+ // to keep (SC-2730). `null` is the third state and says so.
372
+ lines.push(
373
+ offBoard === null
374
+ ? ` (board membership UNMEASURED — whether any open issue is missing from the board was not read)`
375
+ : offBoard === 0
376
+ ? ` every open issue is on the board`
377
+ : ` ${offBoard} open issue(s) are NOT on the board at all — no lane writer can move them, ` +
378
+ `and no row above counts them`,
379
+ );
380
+ return lines;
381
+ }