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.
- package/README.md +82 -0
- package/gates/.gate-salt +1 -1
- package/hooks/VerifyPhaseLock.hook.ts +3 -3
- package/lib/ai-review-rounds.ts +99 -0
- package/lib/ai-review-suppression.ts +200 -21
- package/lib/bash-write-guard.ts +50 -5
- package/lib/board-flow.ts +235 -0
- package/lib/board-lane-health.ts +381 -0
- package/lib/board-mirror.ts +53 -35
- package/lib/board-ready-fanout.ts +56 -13
- package/lib/board-ready-rule.ts +545 -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/conformity.ts +95 -2
- package/lib/filing-compliance.ts +367 -0
- package/lib/finding-arbiter.ts +79 -5
- package/lib/generators/agents-md.ts +149 -0
- package/lib/github.ts +79 -0
- package/lib/graphql-cursor.ts +80 -0
- package/lib/issue-create-override.ts +415 -3
- package/lib/issue-decomposition.ts +33 -3
- package/lib/issue-file-overlap.ts +340 -0
- package/lib/issue-filing-gate.ts +173 -8
- package/lib/issue-repair.ts +13 -9
- package/lib/issue-shape.ts +196 -0
- package/lib/scaffold/ai-review-findings.ts +9 -1
- package/lib/scaffold/ai-review-step.ts +35 -1
- package/lib/source-census.ts +108 -0
- package/lib/spec-deps.ts +34 -11
- package/lib/spec-placement.ts +108 -0
- package/lib/stage-ladder.ts +28 -3
- package/lib/work-status.ts +423 -0
- package/package.json +1 -1
- package/scripts/ai-review-findings.ts +8 -13
- package/scripts/ai-review-threads.ts +16 -17
- package/scripts/board-mirror.ts +221 -8
- package/scripts/generate-code-map.ts +1 -1
- 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
|
+
}
|