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,280 @@
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
+ // Not a GitHub webhook action. `blocked_by_added` reaches the REST
64
+ // timeline and emits no `issues` event at all — measured on #1495, where
65
+ // the edge landed at 02:01:08Z and zero workflow runs started, against
66
+ // four unfiltered `issues` subscribers that would have fired (#1929). So
67
+ // the event is `board-ready`'s own walk noticing an incumbent that no
68
+ // longer meets Ready's entry condition. It is spelled `issue_` because it
69
+ // is about one issue and authorises one identity, like the rest.
70
+ "issue_blocked_in_ready",
71
+ ] as const;
72
+
73
+ /**
74
+ * The subset `scripts/board-flow.ts` may be handed on `--event`.
75
+ *
76
+ * **`LANE_EVENTS` stopped being one list the moment a derived kind joined
77
+ * it** (#1929, ai-review round 1). Every other kind is a webhook action: the
78
+ * event IS the evidence, and `board-flow.ts` can write the lane `laneFor`
79
+ * returns after checking only the actor's permission.
80
+ * `issue_blocked_in_ready` is not. It means *my caller has already verified
81
+ * the card is in Ready, open, and has a live blocker* — three conditions
82
+ * `incumbentDecisions` checks and `board-flow.ts` does not. Validating
83
+ * `--event` against the full list made `--event issue_blocked_in_ready
84
+ * --issue N` demote any issue to Backlog with none of them performed.
85
+ *
86
+ * Unreachable through the wired automation today, because
87
+ * `.github/workflows/board-flow.yml`'s case statement emits only the real
88
+ * webhook kinds. That is why it is worth closing now rather than later: the
89
+ * cost is a derived list, and the thing it prevents is a future trigger, a
90
+ * `workflow_dispatch`, or a copied case statement quietly skipping the
91
+ * verification this feature exists to provide.
92
+ *
93
+ * Derived by subtraction, not written out. A second hand-written list would
94
+ * agree with this one on every input anybody tests, and adding a kind to
95
+ * `LANE_EVENTS` would silently leave it out of both.
96
+ */
97
+ export const DERIVED_LANE_EVENTS = ["issue_blocked_in_ready"] as const;
98
+
99
+ export const WEBHOOK_LANE_EVENTS = LANE_EVENTS.filter(
100
+ (e): e is Exclude<(typeof LANE_EVENTS)[number], (typeof DERIVED_LANE_EVENTS)[number]> =>
101
+ !(DERIVED_LANE_EVENTS as readonly string[]).includes(e),
102
+ );
103
+
104
+ export interface LaneEvent {
105
+ readonly kind: (typeof LANE_EVENTS)[number];
106
+ /**
107
+ * GitHub's `state_reason`, for `issue_closed` only.
108
+ *
109
+ * Read as GraphQL spells it — `COMPLETED`, `NOT_PLANNED`, `DUPLICATE`.
110
+ * The caller normalises; this compares exactly, because a loose
111
+ * comparison on the field that separates "delivered" from "abandoned" is
112
+ * the one place a near-match must not pass.
113
+ */
114
+ readonly stateReason?: string | null;
115
+ }
116
+
117
+ export interface LaneDecision {
118
+ /** The lane to write, or `null` to write nothing and say why. */
119
+ readonly lane: Lane | null;
120
+ readonly why: string;
121
+ }
122
+
123
+ /**
124
+ * The closure reasons that mean the work was abandoned rather than done.
125
+ *
126
+ * Both, because `specs/BOARD-FLOW-SPEC.md` defines Cancelled's entry as
127
+ * "closed as `not_planned` or `duplicate`" and `lib/work-status.ts` already
128
+ * maps both to ABANDONED. Counting only the first reads a cancellation as a
129
+ * delivery.
130
+ */
131
+ const ABANDONED = new Set(["NOT_PLANNED", "DUPLICATE"]);
132
+
133
+ /**
134
+ * The lanes a pull-request event may not pull an issue out of.
135
+ *
136
+ * Done and Cancelled are terminal: the work either shipped or was decided
137
+ * against, and in both cases the clock has stopped. `specs/BOARD-FLOW-SPEC.md`
138
+ * puts the whole forecast on that — Done defines throughput, Cancelled
139
+ * protects Little's Law's second assumption — so a card leaving either one
140
+ * by accident is not a cosmetic error.
141
+ */
142
+ const TERMINAL: readonly string[] = ["Done", "Cancelled"];
143
+
144
+ /**
145
+ * May a PULL REQUEST event write this issue's card, given where it sits now?
146
+ *
147
+ * **Authorisation and the target set are answered by different parties**,
148
+ * which is the confused deputy. `.github/workflows/board-flow.yml` gates on
149
+ * the ACTOR: for `opened` and `ready_for_review` that is the pull request's
150
+ * author, so an outside contributor is refused outright. For `closed` it is
151
+ * whoever closed it — ordinarily a maintainer — while the closing references
152
+ * naming which issues to move still come from the contributor's body.
153
+ *
154
+ * So a drive-by pull request saying `Fixes #N` would pull #N out of Done the
155
+ * moment anybody with write access closed it. The refusal below is also
156
+ * right on the merits: work that shipped did not become unshipped because
157
+ * somebody else's branch was abandoned.
158
+ *
159
+ * ISSUE events are deliberately not subject to this. An issue reopening IS
160
+ * the legitimate way out of Done, it is the spec's own rule, and the actor
161
+ * who reopens is the actor the gate authorised.
162
+ *
163
+ * `null` — a card with no Status at all — is allowed through. It is not a
164
+ * terminal lane, and refusing it would make an unset column unreachable.
165
+ */
166
+ export function prEventMayWrite(currentLane: string | null): { allowed: boolean; why: string } {
167
+ if (currentLane !== null && TERMINAL.includes(currentLane)) {
168
+ return {
169
+ allowed: false,
170
+ why:
171
+ `the card is in ${currentLane}, which is terminal. A pull request event may not move ` +
172
+ `it out: the closing references that name this issue are authored by the pull ` +
173
+ `request, while the permission check answered for whoever closed it. Reopen the ` +
174
+ `issue if the work is genuinely not finished.`,
175
+ };
176
+ }
177
+ return { allowed: true, why: `${currentLane ?? "(no status)"} is not a terminal lane` };
178
+ }
179
+
180
+ /**
181
+ * Which identities must clear the permission check before this event writes?
182
+ *
183
+ * **Authorise the party that chose the targets, not only the one who fired.**
184
+ * `prEventMayWrite` above removes the worst outcome of the confused deputy
185
+ * and does not close it: a drive-by pull request saying `Fixes #N`, where #N
186
+ * sits in Backlog, Ready, In progress or In review, still moves #N the moment
187
+ * any maintainer closes that pull request. The lane is not terminal, the
188
+ * guard passes it, and the card churns on a reference nobody with write
189
+ * access wrote.
190
+ *
191
+ * So a pull request event authorises two identities: the actor who fired it,
192
+ * and the author of the body the closing references came from. An issue event
193
+ * authorises one, because an issue event carries no contributor-authored
194
+ * target set — the issue IS the target — and demanding a second there would
195
+ * refuse ordinary maintainer work.
196
+ *
197
+ * `null` is UNMEASURED: a pull request event whose author could not be read.
198
+ * Falling back to the actor alone would be the silent default, turning an
199
+ * author nobody could read into an author nobody checked.
200
+ *
201
+ * Duplicates are collapsed, so a maintainer closing their own pull request
202
+ * is one permission call rather than two identical ones.
203
+ */
204
+ export function identitiesToAuthorise(
205
+ kind: LaneEvent["kind"],
206
+ actor: string,
207
+ prAuthor: string | null,
208
+ ): string[] | null {
209
+ if (kind.startsWith("issue_")) return [actor];
210
+ if (prAuthor === null || prAuthor === "") return null;
211
+ return actor === prAuthor ? [actor] : [actor, prAuthor];
212
+ }
213
+
214
+ export function laneFor(e: LaneEvent): LaneDecision {
215
+ switch (e.kind) {
216
+ case "issue_assigned":
217
+ // Assignment, and only because `.claude/rules/parallel-sessions.md`
218
+ // already requires a worker to claim an issue by assigning themselves
219
+ // BEFORE writing code. Industry is consistent that assignment is not
220
+ // a start signal; what differs here is that ours is the first
221
+ // physical act rather than a statement of future ownership. If that
222
+ // rule is ever relaxed, this case has to change with it.
223
+ return { lane: "In progress", why: "assignment is this repository's declared starting act" };
224
+
225
+ case "pr_ready":
226
+ // The LINKED ISSUE's card, not the pull request's — see the header.
227
+ // The caller filters drafts out, so reaching here means a pull
228
+ // request that is genuinely waiting on a reviewer. In review has to
229
+ // mean that or it cannot measure the constraint it exists to measure.
230
+ return { lane: "In review", why: "a non-draft pull request is finished work waiting on a reviewer" };
231
+
232
+ case "issue_reopened":
233
+ case "pr_closed_unmerged":
234
+ // A card in Ready that has acquired an open blocker is moving backwards
235
+ // for the same reason the two above are: Ready's entry condition is a
236
+ // claim about the blocker graph, and that claim is now false. It shares
237
+ // their answer rather than carrying its own, so there is one rule for
238
+ // everything that goes backwards and one site to mutate (#1929).
239
+ case "issue_blocked_in_ready":
240
+ // **One rule for everything that goes backwards.** An item that went
241
+ // backwards has a blocker graph nobody has re-checked, and Ready's
242
+ // entry condition is precisely a claim about that graph — so going
243
+ // straight back to Ready would assert something nobody verified.
244
+ // Backlog is not a penalty: `board-ready.yml` re-tests eligibility
245
+ // and re-promotes on its own.
246
+ return {
247
+ lane: "Backlog",
248
+ why: "work moving backwards has an unverified blocker graph, so eligibility is re-checked",
249
+ };
250
+
251
+ case "issue_closed": {
252
+ const reason = e.stateReason;
253
+ if (reason === "COMPLETED") return { lane: "Done", why: "closed as completed" };
254
+ if (typeof reason === "string" && ABANDONED.has(reason)) {
255
+ return { lane: "Cancelled", why: `closed as ${reason.toLowerCase()}` };
256
+ }
257
+ // **A reason this file does not know is not a completed close.**
258
+ // Absent, misspelled, or a value GitHub adds after this was written —
259
+ // all three are unknown, and writing Done for an unknown outcome
260
+ // overstates throughput and contaminates every cycle-time percentile,
261
+ // silently, because a card in Done looks like a card in Done. The
262
+ // refusal names the value so the run is actionable rather than quiet.
263
+ return {
264
+ lane: null,
265
+ why:
266
+ `state_reason ${JSON.stringify(reason)} is not one this decider knows, so the ` +
267
+ `outcome is UNKNOWN rather than completed and nothing is written`,
268
+ };
269
+ }
270
+
271
+ default:
272
+ // An event kind nobody added a case for. Refusing names it; falling
273
+ // through to a default lane would move a card on a rule that does not
274
+ // exist.
275
+ return {
276
+ lane: null,
277
+ why: `no rule for event kind ${JSON.stringify((e as LaneEvent).kind)}`,
278
+ };
279
+ }
280
+ }