rungate 0.8.13 → 0.8.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +182 -0
- package/gates/.gate-salt +1 -1
- package/hooks/HarnessAFKGate.hook.ts +5 -1
- package/hooks/HookCurrency.hook.ts +11 -8
- package/hooks/MergeGuard.hook.ts +7 -1
- package/hooks/StaleTTLCleanup.hook.ts +4 -4
- package/hooks/VerifyPhaseLock.hook.ts +3 -3
- package/hooks/lib/findWorkflow.ts +3 -2
- package/hooks/lib/paths.ts +14 -2
- package/hooks/lib/utils.ts +23 -3
- package/lib/active-milestone.ts +50 -0
- package/lib/ai-review-rounds.ts +99 -0
- package/lib/ai-review-suppression.ts +200 -21
- package/lib/bash-write-guard.ts +397 -23
- package/lib/board-flow.ts +280 -0
- package/lib/board-lane-health.ts +578 -0
- package/lib/board-mirror.ts +136 -39
- package/lib/board-ready-fanout.ts +297 -14
- package/lib/board-ready-rule.ts +1211 -0
- package/lib/board-throughput.ts +136 -0
- package/lib/board-walkthrough.ts +240 -0
- package/lib/body-evidence.ts +203 -0
- package/lib/branch-protection.ts +399 -9
- package/lib/bun-version.ts +36 -0
- package/lib/cli-commands.ts +75 -4
- package/lib/closing-reference-audit.ts +307 -6
- package/lib/config-loader.ts +254 -25
- package/lib/config-readers.ts +170 -10
- package/lib/config-trackable.ts +96 -57
- package/lib/conformity.ts +121 -7
- package/lib/create-sc.ts +25 -2
- package/lib/derived-spec.ts +21 -9
- package/lib/filing-compliance.ts +367 -0
- package/lib/filing-plan.ts +47 -21
- package/lib/finding-arbiter.ts +79 -5
- package/lib/finding-jury.ts +43 -4
- package/lib/finding-promotion.ts +1123 -0
- package/lib/generators/agents-md.ts +149 -0
- package/lib/git-isolation.ts +137 -1
- package/lib/github-api-base.ts +66 -0
- package/lib/github.ts +194 -9
- package/lib/graphql-cursor.ts +80 -0
- package/lib/hook-scopes.ts +78 -0
- package/lib/issue-create-override.ts +415 -3
- package/lib/issue-decomposition.ts +124 -7
- package/lib/issue-extraction.ts +9 -7
- package/lib/issue-file-overlap.ts +373 -0
- package/lib/issue-filing-gate.ts +1109 -52
- package/lib/issue-repair.ts +90 -9
- package/lib/issue-shape.ts +199 -0
- package/lib/live-issues.ts +31 -2
- package/lib/local-work.ts +423 -0
- package/lib/markdown-fence.ts +134 -0
- package/lib/milestone-title.ts +46 -0
- package/lib/scaffold/ai-review-findings.ts +148 -3
- package/lib/scaffold/ai-review-step.ts +65 -5
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
- package/lib/scaffold/steps.ts +115 -9
- package/lib/source-census.ts +108 -0
- package/lib/spec-deps.ts +55 -11
- package/lib/spec-placement.ts +203 -13
- package/lib/spec-registry.ts +75 -16
- package/lib/spec-source.ts +609 -0
- package/lib/spec-write-sweep.ts +4 -0
- package/lib/stage-ladder.ts +896 -3
- package/lib/state-claim-readings.ts +252 -0
- package/lib/success-doc.ts +7 -6
- package/lib/test-command-positions.ts +135 -1
- package/lib/work-status.ts +551 -0
- package/lib/worktree-repo.ts +14 -2
- package/package.json +7 -1
- package/scripts/ai-review-findings.ts +8 -13
- package/scripts/ai-review-threads.ts +16 -17
- package/scripts/audit-closing-references.ts +330 -0
- package/scripts/audit-specs.ts +59 -103
- package/scripts/board-conformance.ts +747 -40
- package/scripts/board-mirror.ts +594 -13
- package/scripts/board-ready.ts +979 -0
- package/scripts/board-snapshot.ts +464 -12
- package/scripts/claim-files.ts +578 -0
- package/scripts/criterion-inventory.ts +526 -50
- package/scripts/finding-promotion.ts +547 -0
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/plan-issues.ts +279 -40
- package/scripts/plan-spec.ts +105 -3
- package/scripts/sync-sc-status.ts +147 -7
- package/scripts/worktree-census.ts +958 -0
- package/scripts/worktree-sweep.ts +269 -0
|
@@ -0,0 +1,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
|
+
}
|