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
@@ -31,6 +31,9 @@
31
31
  * `AGENTS.md` rule 7 asks us to watch.
32
32
  */
33
33
 
34
+ import { headingOccurrencesOf } from "./issue-shape";
35
+ import type { MilestoneAction } from "./spec-placement";
36
+
34
37
  /** The section a repaired body carries. One spelling, by fiat. */
35
38
  export const CRITERIA_HEADING = "## Criteria this serves";
36
39
 
@@ -194,17 +197,19 @@ export function annotatedBody(body: string, criteria: readonly string[]): string
194
197
  *
195
198
  * Returns every occurrence, because more than one is a body
196
199
  * {@link multiplyAnnotated} refuses rather than a first match to edit.
200
+ *
201
+ * **#1741: the body of this is now `lib/issue-shape.ts`.** Everything above
202
+ * is why the obvious version is wrong, and that reasoning was correct and
203
+ * hard-won — but it lived here, bound to one hard-coded heading, while the
204
+ * filing gate and the issue forms were growing a need for the same reading
205
+ * of a different heading. Two heading parsers answering the same question
206
+ * about the same input is *two deciders that agree*
207
+ * (`.claude/rules/checks-must-be-able-to-fail.md`): no behavioural test can
208
+ * tell them apart and a mutation of either leaves the other holding the case
209
+ * up. One parser, parameterised by the heading.
197
210
  */
198
211
  export function headingOccurrences(body: string): number[] {
199
- const out: number[] = [];
200
- let fenced = false;
201
- let at = 0;
202
- for (const line of body.split("\n")) {
203
- if (/^\s*```/.test(line)) fenced = !fenced;
204
- else if (!fenced && line.trimEnd() === CRITERIA_HEADING) out.push(at);
205
- at += line.length + 1;
206
- }
207
- return out;
212
+ return headingOccurrencesOf(body, CRITERIA_HEADING);
208
213
  }
209
214
 
210
215
  /**
@@ -223,3 +228,79 @@ export function multiplyAnnotated(body: string): boolean {
223
228
  export function alreadyAnnotated(body: string, criteria: readonly string[]): boolean {
224
229
  return annotatedBody(body, criteria) === body;
225
230
  }
231
+
232
+ /** Where a repair row's issue belongs in one milestone family (#2042). */
233
+ export type RowPlacement =
234
+ | { kind: "place"; milestone: string; phase: number }
235
+ | { kind: "skip"; why: string }
236
+ | { kind: "refuse"; why: string };
237
+
238
+ /**
239
+ * Which `<prefix> Phase N` milestone a row's issue belongs in, read from the
240
+ * family spec's placement table through `milestonePlan`, the one decider of
241
+ * which criteria a phase holds.
242
+ *
243
+ * Opt-in per family (Jason, 2026-11-13). A repair table can mix families,
244
+ * as ADR-015's does, so a row the family's spec does not place is skipped,
245
+ * never moved on its Phase column alone. Disagreement is a refusal: the
246
+ * row's Phase column against the spec, criteria split across phases, or a
247
+ * row naming criteria both inside and outside the family, or one of the
248
+ * family's criteria that its spec places in no phase (`Blocked`, `Done` and
249
+ * the other `NON_PHASE_PLACEMENTS`) beside one it does. So is a phase
250
+ * whose milestone does not exist; `plan-spec` makes milestones, and this
251
+ * never does.
252
+ */
253
+ export function rowPlacement(
254
+ row: RepairRow,
255
+ plan: readonly MilestoneAction[],
256
+ prefix: string,
257
+ /** Every criterion the family spec states, placed in a phase or not. */
258
+ stated: ReadonlySet<string>,
259
+ ): RowPlacement {
260
+ const actionFor = new Map<string, MilestoneAction>();
261
+ for (const a of plan) for (const id of a.criteria) actionFor.set(id, a);
262
+ const placed = row.criteria.filter(id => actionFor.has(id));
263
+ const unphased = row.criteria.filter(id => stated.has(id) && !actionFor.has(id));
264
+ const outside = row.criteria.filter(id => !stated.has(id));
265
+ if (placed.length === 0 && unphased.length === 0) {
266
+ return { kind: "skip", why: `names nothing ${prefix}'s spec states — not placed in a ${prefix} phase` };
267
+ }
268
+ if (outside.length > 0) {
269
+ return {
270
+ kind: "refuse",
271
+ why:
272
+ `names ${[...placed, ...unphased].join(", ")} from ${prefix}'s spec and ${outside.join(", ")} ` +
273
+ "from outside it — one row cannot sit in two families",
274
+ };
275
+ }
276
+ if (placed.length === 0) {
277
+ return { kind: "skip", why: `${prefix}'s spec places ${unphased.join(", ")} in no phase, so there is no milestone to move into` };
278
+ }
279
+ if (unphased.length > 0) {
280
+ return {
281
+ kind: "refuse",
282
+ why: `${placed.join(", ")} sit in a phase and ${unphased.join(", ")} has no phase in ${prefix}'s spec`,
283
+ };
284
+ }
285
+ const actions = [...new Set(placed.map(id => actionFor.get(id)!))];
286
+ if (actions.length > 1) {
287
+ return {
288
+ kind: "refuse",
289
+ why: `its criteria sit in ${actions.map(a => `Phase ${a.phase}`).join(" and ")} of ${prefix}'s spec`,
290
+ };
291
+ }
292
+ const target = actions[0]!;
293
+ if (target.phase !== row.phase) {
294
+ return {
295
+ kind: "refuse",
296
+ why: `the plan says Phase ${row.phase} and ${prefix}'s spec places ${placed.join(", ")} in Phase ${target.phase}`,
297
+ };
298
+ }
299
+ if (!target.existing) {
300
+ return {
301
+ kind: "refuse",
302
+ why: `"${target.title}" has no milestone — run plan-spec for ${prefix}'s spec first; this never creates one`,
303
+ };
304
+ }
305
+ return { kind: "place", milestone: target.existing.title, phase: target.phase };
306
+ }
@@ -0,0 +1,199 @@
1
+ /**
2
+ * #1741 — what a valid issue looks like, decided in one place.
3
+ *
4
+ * ## Why this file exists at all
5
+ *
6
+ * Before it there was no decider and two half-answers.
7
+ * `.github/ISSUE_TEMPLATE/spec-work.yml` asked for five fields and
8
+ * `rungate plan-issues --decompose` emitted two of them, so a gate requiring
9
+ * the other three would have refused every row of every plan. That is why the
10
+ * recorded agreement (2026-11-03, `project-state.json`, the priority opening
11
+ * *PATH B HAS NO INTAKE*) says the form, the gate and the generator must land
12
+ * together: built apart, each grows its own notion of valid, and
13
+ * `.claude/rules/checks-must-be-able-to-fail.md`'s *two deciders that agree*
14
+ * says no behavioural test can then tell which one is live.
15
+ *
16
+ * ## The one decider is `requiredSections`
17
+ *
18
+ * Everything else in this file reads it, and every consumer reads one of
19
+ * those. `test/issue-shape.test.ts` binds all four consumers with an
20
+ * **equality** rather than a containment, which is the only form that goes
21
+ * red when this function is short-circuited to `return []` — every list
22
+ * contains the empty one, so a containment assertion certifies a decider that
23
+ * has stopped deciding.
24
+ *
25
+ * ## The second form, and what it is for
26
+ *
27
+ * `spec-work` requires *Criteria this serves*. A consumer agent reporting a
28
+ * problem upstream, and ordinary housekeeping, cannot know a criterion id —
29
+ * so until `everyday-work` existed there was no correct way to file anything
30
+ * that was not spec work, and the measured consequence was agents reaching
31
+ * for the `external-audit` label, which the same decision had ruled out.
32
+ *
33
+ * The two forms differ in exactly one field and `test/issue-shape.test.ts`
34
+ * asserts that by name. A second difference arriving later is a decision, not
35
+ * a tidy-up.
36
+ */
37
+
38
+ import { readFences } from "./markdown-fence";
39
+
40
+ /** The forms. The set is closed; adding one is an edit here and a file on disk. */
41
+ export const ISSUE_FORMS = ["spec-work", "everyday-work"] as const;
42
+
43
+ export type IssueForm = (typeof ISSUE_FORMS)[number];
44
+
45
+ export interface IssueSection {
46
+ /** The `id:` of the field in the issue form, and the key everything joins on. */
47
+ readonly id: string;
48
+ /**
49
+ * The field's `label:` in the form AND its heading in a rendered body.
50
+ *
51
+ * ONE string for both deliberately. Two would let the form ask for
52
+ * *Criteria this serves* while the parser looked for *Criteria*, which is
53
+ * the same class of defect this file exists to remove, one layer down.
54
+ */
55
+ readonly label: string;
56
+ /** The forms that SHOW this field. */
57
+ readonly forms: readonly IssueForm[];
58
+ /** The forms that REQUIRE it. Always a subset of `forms`. */
59
+ readonly required: readonly IssueForm[];
60
+ }
61
+
62
+ const BOTH = ISSUE_FORMS;
63
+
64
+ /**
65
+ * Every section, in the order a form shows them.
66
+ *
67
+ * The order is load-bearing for `formTemplatePath`'s files and for
68
+ * `decomposedBody`: a reader scanning a body top to bottom meets them in this
69
+ * order, and a generator that emits them in another makes two issues that say
70
+ * the same thing look different.
71
+ */
72
+ export const ISSUE_SECTIONS: readonly IssueSection[] = [
73
+ {
74
+ id: "outcome",
75
+ label: "What must become true",
76
+ forms: BOTH,
77
+ required: BOTH,
78
+ },
79
+ {
80
+ id: "criteria",
81
+ label: "Criteria this serves",
82
+ forms: ["spec-work"],
83
+ required: ["spec-work"],
84
+ },
85
+ {
86
+ id: "files",
87
+ label: "Files this will change",
88
+ forms: BOTH,
89
+ required: BOTH,
90
+ },
91
+ {
92
+ id: "blocked-by",
93
+ label: "Blocked by",
94
+ forms: BOTH,
95
+ // Required by neither, and that is the design: empty is what puts an
96
+ // issue in the pickable set, so demanding the field would make every
97
+ // filer invent an ordering and the board would then lie about it.
98
+ required: [],
99
+ },
100
+ {
101
+ id: "proof",
102
+ label: "How we will know",
103
+ forms: BOTH,
104
+ required: BOTH,
105
+ },
106
+ ];
107
+
108
+ /**
109
+ * **THE DECIDER.** What a body must carry to be a valid issue of this form.
110
+ *
111
+ * Short-circuit this to `return []` and all four consumers go red. If one
112
+ * stays green it is a second decider and the work is not done —
113
+ * `test/issue-shape.test.ts`'s header carries the battery's terms.
114
+ */
115
+ export function requiredSections(form: IssueForm): readonly IssueSection[] {
116
+ return ISSUE_SECTIONS.filter(s => s.required.includes(form));
117
+ }
118
+
119
+ /** Every section a form shows, required or not. */
120
+ export function sectionsOf(form: IssueForm): readonly IssueSection[] {
121
+ return ISSUE_SECTIONS.filter(s => s.forms.includes(form));
122
+ }
123
+
124
+ /** The markdown heading that opens a section in a body. */
125
+ export function headingFor(section: IssueSection): string {
126
+ return `## ${section.label}`;
127
+ }
128
+
129
+ /** Where the form lives, relative to the repository root. */
130
+ export function formTemplatePath(form: IssueForm): string {
131
+ return `.github/ISSUE_TEMPLATE/${form}.yml`;
132
+ }
133
+
134
+ /**
135
+ * Every offset at which `heading` OPENS A LINE, outside any fenced block.
136
+ *
137
+ * Generalised out of `lib/issue-repair.ts`, which held the only correct
138
+ * version and held it for one hard-coded string. Its docblock records why the
139
+ * obvious `body.indexOf` is wrong, and the answer is worth keeping in one
140
+ * place: these bodies quote markdown and shell constantly, so an unanchored
141
+ * match reads *"add a `## Criteria this serves` section"* in prose, and a
142
+ * fence-blind one reads a template pasted into a code block. That was caught
143
+ * by a security review rather than by a test, and the repair it would have
144
+ * made was to REPLACE everything from the quotation to the next heading —
145
+ * which in those bodies is the measurements the repair exists to preserve.
146
+ *
147
+ * Any heading level opens a section. A body that writes `### Files this will
148
+ * change` has named the section; refusing it would be a decider narrower than
149
+ * what it detects, with nothing gained.
150
+ */
151
+ export function headingOccurrencesOf(body: string, heading: string): number[] {
152
+ const text = heading.replace(/^#+\s*/, "");
153
+ const opens = new RegExp(`^#{1,6}\\s+${escapeRegExp(text)}\\s*$`);
154
+ const out: number[] = [];
155
+ const lines = body.split("\n");
156
+ // `~~~` fences too, and a fence closes only on its own marker (#2130).
157
+ const { roles } = readFences(lines);
158
+ let at = 0;
159
+ for (let i = 0; i < lines.length; i++) {
160
+ if (roles[i] === "prose" && opens.test(lines[i]!.trimEnd())) out.push(at);
161
+ at += lines[i]!.length + 1;
162
+ }
163
+ return out;
164
+ }
165
+
166
+ function escapeRegExp(s: string): string {
167
+ return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
168
+ }
169
+
170
+ /**
171
+ * The headings a body is short, for `form`. Empty means well-formed.
172
+ *
173
+ * **A heading over nothing does not count.** A body somebody pasted the
174
+ * template into and did not fill in carries every heading and answers no
175
+ * question, and to a check that only looks for the string it is
176
+ * indistinguishable from a complete one — *assertions that hold vacuously*,
177
+ * in `.claude/rules/checks-must-be-able-to-fail.md`. So a section is present
178
+ * when there is non-blank text between its heading and the next one.
179
+ *
180
+ * Returns headings rather than ids, because the only reader that matters is
181
+ * an agent reading a refusal, and the heading is what they have to type.
182
+ */
183
+ export function missingSections(body: string, form: IssueForm): string[] {
184
+ return requiredSections(form)
185
+ .filter(s => !hasContent(body, headingFor(s)))
186
+ .map(headingFor);
187
+ }
188
+
189
+ /** True when `heading` opens a section with non-blank text under it. */
190
+ function hasContent(body: string, heading: string): boolean {
191
+ for (const at of headingOccurrencesOf(body, heading)) {
192
+ const rest = body.slice(at).split("\n").slice(1);
193
+ for (const line of rest) {
194
+ if (/^#{1,6}\s+\S/.test(line)) break; // the next section, with nothing between
195
+ if (line.trim() !== "") return true;
196
+ }
197
+ }
198
+ return false;
199
+ }
@@ -117,6 +117,20 @@ export function readMilestonePrefix(raw: string | undefined): MilestonePrefixRea
117
117
  export interface LiveIssue extends DepIssue {
118
118
  /** Every label name on the issue, as GitHub spells them. */
119
119
  readonly labels: readonly string[];
120
+ /**
121
+ * The issue's title and body, for reading which criteria it names — SC-2616.
122
+ *
123
+ * ADR-003 step 3 says an issue declares what it serves as plain text in its
124
+ * body, so `criteriaNamedBy` needs both. Neither is a paged connection, so
125
+ * neither carries a truncation flag: GitHub returns a body whole or not at
126
+ * all.
127
+ *
128
+ * `body` is `null` when the issue has none, which is a real state and not a
129
+ * read that failed — an issue with an empty body names no criterion, which
130
+ * is exactly what `criteria-named` is there to report.
131
+ */
132
+ readonly title: string;
133
+ readonly body: string | null;
120
134
  /**
121
135
  * True when the LABEL list was cut — a paged connection reporting another
122
136
  * page. Same reasoning as {@link DepIssue.blockedByTruncated}, and here
@@ -141,6 +155,8 @@ query($owner:String!,$name:String!,$states:[IssueState!],$after:String){
141
155
  nodes{
142
156
  number
143
157
  state
158
+ title
159
+ body
144
160
  milestone{title}
145
161
  labels(first:${ISSUE_PAGE}){pageInfo{hasNextPage} nodes{name}}
146
162
  blockedBy(first:${ISSUE_PAGE}){pageInfo{hasNextPage} nodes{number}}
@@ -155,6 +171,8 @@ interface IssuePage {
155
171
  nodes: {
156
172
  number: number;
157
173
  state: string;
174
+ title: string;
175
+ body: string | null;
158
176
  milestone: { title: string } | null;
159
177
  labels: { pageInfo: { hasNextPage: boolean }; nodes: { name: string }[] } | null;
160
178
  blockedBy: { pageInfo: { hasNextPage: boolean }; nodes: { number: number }[] } | null;
@@ -168,12 +186,21 @@ interface IssuePage {
168
186
  * overwriting one key with `undefined` leaves the key PRESENT in the object
169
187
  * Bun hands the child, and `gh` prefers `GH_TOKEN` to its own keychain
170
188
  * whenever the variable exists at all.
189
+ *
190
+ * ## `cwd`, because that is what `gh` infers the repository from
191
+ *
192
+ * With no `--repo`, `gh` reads the git remote of the directory it runs in.
193
+ * A caller that was told which tree to work on by an argument — rather than
194
+ * by having been launched in it — would otherwise read one repository's
195
+ * tracker while reporting about another's files, and nothing in either
196
+ * reading would say so. Raised in review of #1878. Absent means the
197
+ * process's own directory, which is what every existing caller gets.
171
198
  */
172
- export function ghWithoutGhToken(args: readonly string[]): string {
199
+ export function ghWithoutGhToken(args: readonly string[], opts: { cwd?: string } = {}): string {
173
200
  const env: Record<string, string> = {};
174
201
  for (const [k, v] of Object.entries(process.env)) if (v !== undefined) env[k] = v;
175
202
  delete env.GH_TOKEN;
176
- const proc = Bun.spawnSync(["gh", ...args], { env });
203
+ const proc = Bun.spawnSync(["gh", ...args], { env, ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }) });
177
204
  if (proc.exitCode !== 0) {
178
205
  throw new Error(new TextDecoder().decode(proc.stderr).trim().slice(0, 300));
179
206
  }
@@ -222,6 +249,8 @@ export async function readLiveIssues(
222
249
  out.push({
223
250
  number: n.number,
224
251
  state: n.state,
252
+ title: n.title,
253
+ body: n.body,
225
254
  milestone: n.milestone?.title ?? null,
226
255
  labels: (n.labels?.nodes ?? []).map(l => l.name),
227
256
  labelsTruncated: n.labels?.pageInfo.hasNextPage === true,