rungate 0.8.27 → 0.8.28

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.
@@ -0,0 +1,214 @@
1
+ /**
2
+ * The verdict a consumer's issue gets — SC-2782, ADR-020 Decision 1.
3
+ *
4
+ * THE one decider. `rungate consumer-triage` reads each open `from-consumer`
5
+ * issue that carries no verdict marker and asks {@link triageVerdict}; the
6
+ * CLI writes what it answered and decides nothing itself. The first verdict
7
+ * that fits wins, in the ADR's order:
8
+ *
9
+ * 1. **DUPLICATE #N** — the FindingArbiter's duplicate test
10
+ * (`duplicateCollisions`) matches an OLDER open issue. Older only, so two
11
+ * consumer reports of one problem cannot each be called the other's
12
+ * duplicate and both end up unplaced. A comment names #N; closing it stays
13
+ * a person's act.
14
+ * 2. **PLACED** — `issuePlacement`, the SC-2779 decider, names a phase. Never a
15
+ * second placement rule here.
16
+ * 3. **OVERLAPS #N** — its declared files meet an open issue's declared files
17
+ * or an open pull request's changed files (`lib/issue-file-overlap.ts`), or
18
+ * it names a criterion that issue names. It joins #N's milestone. Open work
19
+ * with no milestone is skipped: there is nothing to join, and joining
20
+ * "nothing" would leave the issue exactly where Ready never looks. No
21
+ * blocked-by link is written; a shared file is a conflict, not an order.
22
+ * 4. **ACTIVE** — none of the above. It joins `activeMilestone`'s answer, the
23
+ * SC-2741 decider Ready itself refills from.
24
+ *
25
+ * Two outcomes are not verdicts and leave no marker, so a later run asks again:
26
+ *
27
+ * - **LEFT** — the issue already has a milestone that the placement decider
28
+ * did not name. A person put it there, and nothing here moves a milestone a
29
+ * person set, the rule `issuePlacement` keeps too. `consumer-intake` (SC-2783)
30
+ * counts a milestone as an answer, so the issue is not lost.
31
+ * - **REFUSED** — the decider could not give a verdict without guessing: the
32
+ * phase it belongs in has no milestone, or no open issue sits in any phase.
33
+ */
34
+ import { activeMilestone } from "./board-ready-rule";
35
+ import { criterionAnswer } from "./board-mirror";
36
+ import { duplicateCollisions, type Finding } from "./finding-arbiter";
37
+ import { declaredFiles, sharedFiles } from "./issue-file-overlap";
38
+ import { issuePlacement, type PlacingFamily } from "./issue-repair";
39
+
40
+ /** The label a consumer's report carries — the one the reporting rule tells consumers to set. */
41
+ export const CONSUMER_LABEL = "from-consumer";
42
+
43
+ export const VERDICT_KINDS = ["DUPLICATE", "PLACED", "OVERLAPS", "ACTIVE"] as const;
44
+ export type VerdictKind = (typeof VERDICT_KINDS)[number];
45
+
46
+ /** An open issue, as little of one as the decider reads. */
47
+ export interface TriageIssue {
48
+ readonly number: number;
49
+ readonly title: string;
50
+ readonly body: string | null;
51
+ readonly milestone: string | null;
52
+ /** Its labels, when read; only the stopped-run check looks at them (#2364). */
53
+ readonly labels?: readonly string[];
54
+ /** True when the label list was cut at a page boundary, so an absent label is unread. */
55
+ readonly labelsTruncated?: boolean;
56
+ }
57
+
58
+ /** An open pull request: its changed files are what it shares. */
59
+ export interface OpenPull extends TriageIssue {
60
+ readonly files: readonly string[];
61
+ }
62
+
63
+ export type Verdict =
64
+ | { kind: "DUPLICATE"; of: number; keys: string[]; why: string }
65
+ | { kind: "PLACED"; milestone: string; why: string }
66
+ | { kind: "OVERLAPS"; of: number; ofKind: "issue" | "pull request"; milestone: string; shared: string[]; why: string }
67
+ | { kind: "ACTIVE"; milestone: string; why: string };
68
+
69
+ export type Triage = Verdict | { kind: "LEFT"; why: string } | { kind: "REFUSED"; why: string };
70
+
71
+ export interface TriageContext {
72
+ /** Every open issue, the one being triaged included or not. */
73
+ readonly openIssues: readonly TriageIssue[];
74
+ readonly openPulls: readonly OpenPull[];
75
+ /** Every opted-in family, as `placingFamilies` read them. */
76
+ readonly families: readonly PlacingFamily[];
77
+ /** `board.milestonePrefix`, the engine family Ready draws from first. */
78
+ readonly enginePrefix: string | null;
79
+ /**
80
+ * `board.queueLabel`, which a triage run writes BEFORE the milestone and
81
+ * the marker (review of #2367) — so a milestone a run set always has it
82
+ * beside it, and it is the only evidence that a run, not a person, set an
83
+ * unmarked issue's milestone (#2364). Null or absent: no such evidence.
84
+ */
85
+ readonly queueLabel?: string | null;
86
+ }
87
+
88
+ const asFinding = (i: TriageIssue): Finding => ({ id: String(i.number), title: i.title, body: i.body ?? "" });
89
+
90
+ export function triageVerdict(issue: TriageIssue, ctx: TriageContext): Triage {
91
+ // 1. DUPLICATE — of an older open issue only.
92
+ const older = ctx.openIssues.filter(o => o.number < issue.number).map(asFinding);
93
+ const dup = duplicateCollisions(asFinding(issue), older)[0];
94
+ if (dup !== undefined) {
95
+ return {
96
+ kind: "DUPLICATE",
97
+ of: Number(dup.id),
98
+ keys: dup.keys,
99
+ why: `the FindingArbiter's duplicate test matches #${dup.id} on ${dup.keys.length} shared key(s): ${dup.keys.slice(0, 6).join(", ")}`,
100
+ };
101
+ }
102
+
103
+ // 2. PLACED — the SC-2779 decider, never a second one.
104
+ const move = issuePlacement(issue, ctx.families);
105
+ if (move.kind === "move") return { kind: "PLACED", milestone: move.milestone, why: move.why };
106
+ if (move.kind === "stay" && issue.milestone !== null) return { kind: "PLACED", milestone: issue.milestone, why: move.why };
107
+ if (move.kind === "refuse") return { kind: "REFUSED", why: move.why };
108
+
109
+ if (issue.milestone !== null) {
110
+ // An unmarked issue a run set the milestone AND queue label on, then stopped
111
+ // before the marker (review of #2356): finish it. The label is the
112
+ // evidence; the recommendation matching is not, because a person's
113
+ // milestone can match by coincidence (#2364). Any other milestone was set by
114
+ // a person and is never moved.
115
+ const runLabelled = ctx.queueLabel != null && (issue.labels ?? []).includes(ctx.queueLabel);
116
+ // A cut label list cannot say the label is absent (review of #2367).
117
+ if (!runLabelled && ctx.queueLabel != null && issue.labelsTruncated === true) {
118
+ return {
119
+ kind: "REFUSED",
120
+ why: `its labels were cut at a page boundary without ${ctx.queueLabel}, so whether a run set "${issue.milestone}" is unread`,
121
+ };
122
+ }
123
+ const again = runLabelled ? unplacedVerdict({ ...issue, milestone: null }, ctx) : null;
124
+ if (again !== null && again.kind !== "REFUSED" && again.milestone === issue.milestone) {
125
+ return { ...again, why: `${again.why}; it already sits there, so this finishes a run that stopped before the marker` };
126
+ }
127
+ return { kind: "LEFT", why: `already in "${issue.milestone}", which a person set; a milestone a person set is never moved` };
128
+ }
129
+ return unplacedVerdict(issue, ctx);
130
+ }
131
+
132
+ /** Steps 3 and 4, for an issue no phase places: OVERLAPS, else ACTIVE. */
133
+ function unplacedVerdict(issue: TriageIssue, ctx: TriageContext): Extract<Triage, { kind: "OVERLAPS" | "ACTIVE" | "REFUSED" }> {
134
+ // 3. OVERLAPS — shared declared/changed files, or a shared named criterion.
135
+ const stated = [...new Set(ctx.families.flatMap(f => f.stated))];
136
+ const mineFiles = declaredFiles(issue.body ?? "");
137
+ const mineCriteria = criterionAnswer(issue, stated).names;
138
+ const others: { item: TriageIssue; kind: "issue" | "pull request"; files: readonly string[] }[] = [
139
+ ...ctx.openIssues.filter(o => o.number !== issue.number).map(o => ({ item: o, kind: "issue" as const, files: declaredFiles(o.body ?? "") })),
140
+ ...ctx.openPulls.map(p => ({ item: p as TriageIssue, kind: "pull request" as const, files: p.files })),
141
+ ].sort((a, b) => a.item.number - b.item.number);
142
+ for (const o of others) {
143
+ if (o.item.milestone === null) continue;
144
+ const files = mineFiles.length === 0 ? [] : sharedFiles(mineFiles, o.files);
145
+ const theirCriteria = new Set(criterionAnswer(o.item, stated).names);
146
+ const criteria = mineCriteria.filter(id => theirCriteria.has(id));
147
+ if (files.length === 0 && criteria.length === 0) continue;
148
+ return {
149
+ kind: "OVERLAPS",
150
+ of: o.item.number,
151
+ ofKind: o.kind,
152
+ milestone: o.item.milestone,
153
+ shared: [...files, ...criteria],
154
+ why: `shares ${[...files, ...criteria].join(", ")} with open ${o.kind} #${o.item.number}, so it joins "${o.item.milestone}"`,
155
+ };
156
+ }
157
+
158
+ // 4. ACTIVE — the focus Ready refills from.
159
+ const active = activeMilestone(ctx.openIssues, ctx.enginePrefix);
160
+ if (active.title === null) return { kind: "REFUSED", why: `nowhere to place it: ${active.why}` };
161
+ return { kind: "ACTIVE", milestone: active.title, why: active.why };
162
+ }
163
+
164
+ /** The marker's fixed opening. `consumer-intake` (SC-2783) reads it through {@link verdictIn}. */
165
+ const MARKER_OPEN = "<!-- rungate:consumer-triage:v1";
166
+ const MARKER = new RegExp(`${MARKER_OPEN} (${VERDICT_KINDS.join("|")}) -->`);
167
+
168
+ export function verdictMarker(kind: VerdictKind): string {
169
+ return `${MARKER_OPEN} ${kind} -->`;
170
+ }
171
+
172
+ /** One issue comment, with who wrote it. */
173
+ export interface IssueComment {
174
+ readonly body: string;
175
+ readonly author: string;
176
+ /** GitHub's `author_association`: OWNER, MEMBER, COLLABORATOR, CONTRIBUTOR, NONE, … */
177
+ readonly association: string;
178
+ }
179
+
180
+ /** The associations whose marker counts. A reporter cannot mark their own issue triaged. */
181
+ export const TRUSTED_ASSOCIATIONS: readonly string[] = ["OWNER", "MEMBER", "COLLABORATOR"];
182
+
183
+ /** The account a generated workflow's `GITHUB_TOKEN` posts as (SC-2784). */
184
+ export const WORKFLOW_BOT = "github-actions[bot]";
185
+
186
+ /**
187
+ * The comment bodies whose marker counts: written by someone with push access,
188
+ * or by the workflow that runs the triage. Anyone can comment on a public
189
+ * issue, so a marker from anyone else would let a reporter skip triage, and
190
+ * `consumer-intake` (SC-2783) would then read the issue as answered.
191
+ */
192
+ export function trustedBodies(comments: readonly IssueComment[]): string[] {
193
+ return comments.filter(c => TRUSTED_ASSOCIATIONS.includes(c.association) || c.author === WORKFLOW_BOT).map(c => c.body);
194
+ }
195
+
196
+ /** The verdict a set of comments records, or null when none carries a marker. Pass {@link trustedBodies}. */
197
+ export function verdictIn(comments: readonly string[]): VerdictKind | null {
198
+ for (const c of comments) {
199
+ const m = MARKER.exec(c);
200
+ if (m) return m[1] as VerdictKind;
201
+ }
202
+ return null;
203
+ }
204
+
205
+ /** The comment that records a verdict: the marker on the first line, then the reason. */
206
+ export function verdictComment(v: Verdict): string {
207
+ const head =
208
+ v.kind === "DUPLICATE"
209
+ ? `**Triage: DUPLICATE of #${v.of}.** Closing it is a person's call; nothing here closes it.`
210
+ : v.kind === "OVERLAPS"
211
+ ? `**Triage: OVERLAPS #${v.of}**, so it joins "${v.milestone}".`
212
+ : `**Triage: ${v.kind}** in "${v.milestone}".`;
213
+ return `${verdictMarker(v.kind)}\n${head}\n\nWhy: ${v.why}.\n\nWritten by \`rungate consumer-triage\` (ADR-020).`;
214
+ }
@@ -141,6 +141,7 @@ import {
141
141
  labelValues,
142
142
  } from "./issue-create-override";
143
143
  import { headingFor, missingSections, requiredSections } from "./issue-shape";
144
+ import { parseSuccessDoc, readSuccessDoc, UNREADABLE as SUCCESS_UNREADABLE, unfilled } from "./success-doc";
144
145
  import { asIssueFiles, overlapNote } from "./issue-file-overlap";
145
146
  import { gitSource, plannedFiling, type PlanSource } from "./filing-plan";
146
147
  import { resolveShipPolicy, type ShipPolicy } from "./ship-mode";
@@ -278,14 +279,62 @@ export const SUCCESS_CLAIM_COUNT = 7;
278
279
  * often than a claim, and `SC-4`, which is a success criterion and a different
279
280
  * register entirely. The word has to be there.
280
281
  */
281
- export function namedClaim(text: string): number | null {
282
+ export function namedClaim(text: string, claims: ClaimReading = OWN_CLAIMS): number | null {
283
+ const valid = claimNumbers(claims);
282
284
  for (const m of text.matchAll(/\bclaims?\s*#?\s*(\d+)/gi)) {
283
285
  const n = Number(m[1]);
284
- if (n >= 1 && n <= SUCCESS_CLAIM_COUNT) return n;
286
+ if (valid.includes(n)) return n;
285
287
  }
286
288
  return null;
287
289
  }
288
290
 
291
+ /**
292
+ * The claims a filing may name — #2317. In a consumer they are the consumer's
293
+ * OWN `SUCCESS.md`, not this repository's seven: `Claim <1-7>` named claims
294
+ * that live in a different repository, and a consumer whose claims were still
295
+ * the template's TODO had no honest claim to name and was not told why.
296
+ *
297
+ * - `claims`: the filled claims, by number.
298
+ * - `unwritten`: a SUCCESS.md that states no filled claim — every filing is
299
+ * refused, and the refusal names `rungate create-success`.
300
+ * - `absent`: no SUCCESS.md at all. The old reading, 1..{@link SUCCESS_CLAIM_COUNT},
301
+ * so nothing that passed before is refused now; scaffold seeds the file, so
302
+ * this is the unscaffolded tree.
303
+ * - `unreadable`: present and could not be read. Refused — a gate that needs
304
+ * a read must not fail open when the read does.
305
+ */
306
+ export type ClaimReading =
307
+ | { kind: "claims"; numbers: number[] }
308
+ | { kind: "unwritten" }
309
+ | { kind: "absent" }
310
+ | { kind: "unreadable" };
311
+
312
+ /** This repository's own reading, and the absent-file default. */
313
+ const OWN_CLAIMS: ClaimReading = { kind: "absent" };
314
+
315
+ /** The claim numbers a reading accepts. */
316
+ function claimNumbers(claims: ClaimReading): number[] {
317
+ if (claims.kind === "claims") return claims.numbers;
318
+ if (claims.kind === "absent") return Array.from({ length: SUCCESS_CLAIM_COUNT }, (_, i) => i + 1);
319
+ return [];
320
+ }
321
+
322
+ /** A SUCCESS.md's text, or `null` for none, as a claim reading — #2317. */
323
+ export function claimsIn(text: string | null): ClaimReading {
324
+ if (text === null) return { kind: "absent" };
325
+ if (text === SUCCESS_UNREADABLE) return { kind: "unreadable" };
326
+ const numbers = [...new Set(parseSuccessDoc(text).claims.filter(c => !unfilled(c.statement)).map(c => c.number))].sort(
327
+ (a, b) => a - b,
328
+ );
329
+ return numbers.length === 0 ? { kind: "unwritten" } : { kind: "claims", numbers };
330
+ }
331
+
332
+ /** How a refusal spells the claims a reading accepts: `1-3` when contiguous, else a list. */
333
+ function claimRange(numbers: readonly number[]): string {
334
+ const contiguous = numbers.every((n, i) => n === numbers[0]! + i);
335
+ return contiguous && numbers.length > 1 ? `${numbers[0]}-${numbers[numbers.length - 1]}` : numbers.join(", ");
336
+ }
337
+
289
338
  /**
290
339
  * How many issues one run may file. **The gate (#1595, scope item 4).**
291
340
  *
@@ -788,11 +837,14 @@ export type NetGrowthBasis =
788
837
  * row cannot describe a different decision from the one enforced.
789
838
  *
790
839
  * - Not the direct-ship allowance (`allowance.direct` false): the cap
791
- * stands, records nothing, and **the count is never read**.
792
- * - Count unreadable, or the reader throws: the cap stands, and the reading
793
- * is recorded as UNMEASURED. Never the ceiling — the fail-closed direction.
794
- * - opened − closed ≤ 0: `NET_GROWTH_CEILING`.
795
- * - opened − closed > 0: the cap stands.
840
+ * stands, records nothing, and **the count is never read**. Harness mode
841
+ * keeps its ship-mode cap (SC-2785).
842
+ * - The direct-ship allowance: `NET_GROWTH_CEILING`, **whatever the count
843
+ * says** (ADR-020 Decision 4, SC-2785, Jason 2026-11-17). On 2026-11-17 the
844
+ * count fell back to 12 while consumer reports pushed opened above closed,
845
+ * and a release issue waited four hours behind it. The count is still read,
846
+ * so the refusal prints the day's opened and closed numbers; an unread count
847
+ * is recorded as UNMEASURED and changes nothing.
796
848
  *
797
849
  * **It takes a THUNK, and that is what keeps eligibility to one site.** With
798
850
  * a value, the caller has to decide whether to read before calling, and that
@@ -815,11 +867,10 @@ export async function netGrowthCeiling(
815
867
  const growth = await Promise.resolve()
816
868
  .then(read)
817
869
  .catch((e: unknown) => unmeasuredGrowth(`the trailing day's issues could not be read (${errorText(e)})`));
818
- if (growth.reading !== "MEASURED") return { cap: allowance.cap, basis: growth };
819
- const ceiling = growth.opened - growth.closed <= 0;
870
+ if (growth.reading !== "MEASURED") return { cap: NET_GROWTH_CEILING, basis: growth };
820
871
  return {
821
- cap: ceiling ? NET_GROWTH_CEILING : allowance.cap,
822
- basis: { reading: "MEASURED", opened: growth.opened, closed: growth.closed, ceiling },
872
+ cap: NET_GROWTH_CEILING,
873
+ basis: { reading: "MEASURED", opened: growth.opened, closed: growth.closed, ceiling: true },
823
874
  };
824
875
  }
825
876
 
@@ -962,18 +1013,16 @@ export function netGrowthSentence(basis: NetGrowthBasis | null | undefined): str
962
1013
  // none, and that row is a refusal with nothing to say about the ceiling.
963
1014
  if (basis === null || basis === undefined) return null;
964
1015
  const window = `${RUN_WINDOW_MS / 3_600_000}h`;
1016
+ const direct = `in direct-ship mode the cap is the ceiling of ${NET_GROWTH_CEILING} whatever the day's growth (ADR-020).`;
965
1017
  if (basis.reading === "UNMEASURED") {
966
- return (
967
- `Whether the repository closed as many issues as it opened in the last ${window} is UNMEASURED ` +
968
- `(${basis.why}), so the net-growth ceiling of ${NET_GROWTH_CEILING} does not apply and the cap is ` +
969
- "the ship-mode one (ADR-016)."
970
- );
1018
+ return `Whether the repository closed as many issues as it opened in the last ${window} is UNMEASURED (${basis.why}); ${direct}`;
971
1019
  }
972
1020
  const counts = `The repository opened ${basis.opened} and closed ${basis.closed} issue(s) in the last ${window}`;
1021
+ // `ceiling: false` is a row written before ADR-020, when a growing backlog
1022
+ // fell back to the ship-mode cap. It is rendered as what it was.
973
1023
  return basis.ceiling
974
- ? `${counts}, so the net-growth ceiling of ${NET_GROWTH_CEILING} applies (ADR-016).`
975
- : `${counts}: opening outran closing, so the net-growth ceiling of ${NET_GROWTH_CEILING} does not ` +
976
- "apply and the cap is the ship-mode one (ADR-016).";
1024
+ ? `${counts}; ${direct}`
1025
+ : `${counts}: opening outran closing, so the cap was the ship-mode one (ADR-016, before ADR-020).`;
977
1026
  }
978
1027
 
979
1028
  /**
@@ -2505,6 +2554,7 @@ export async function adjudicateFiling(
2505
2554
  readExisting: () => Promise<CorpusReading>,
2506
2555
  readBody: (path: string) => string | null = readBodyFile,
2507
2556
  readTarget: () => Promise<CommentTarget> = async () => UNRESOLVED_COMMENT_TARGET,
2557
+ claims: ClaimReading = OWN_CLAIMS,
2508
2558
  ): Promise<FilingAdjudication> {
2509
2559
  // ── where is the body? ──
2510
2560
  //
@@ -2679,14 +2729,21 @@ export async function adjudicateFiling(
2679
2729
  // label alone posts nothing, so a filing that really is cleanup needs the
2680
2730
  // declaration too. A half-recipe that still worked would be worse than
2681
2731
  // either.
2682
- if (namedClaim(`${attempt.title}\n${body}`) === null) {
2732
+ if (namedClaim(`${attempt.title}\n${body}`, claims) === null) {
2733
+ // #2317: say which claims THIS repository states, or why it states none.
2734
+ const ask =
2735
+ claims.kind === "unwritten"
2736
+ ? `This repository's SUCCESS.md states no claim yet — its claims are still the template's ` +
2737
+ `placeholders. Write them (\`rungate create-success\` seeds the file), then name one.`
2738
+ : claims.kind === "unreadable"
2739
+ ? `This repository's SUCCESS.md is present and could not be read, so no claim can be checked.`
2740
+ : `Name one as "Claim <${claimRange(claimNumbers(claims))}>" in the title or body.`;
2683
2741
  return {
2684
2742
  ...base,
2685
2743
  outcome: "REFUSE",
2686
2744
  refusal: "NO_CLAIM",
2687
2745
  reason:
2688
- `the filing is novel, and names no SUCCESS.md claim — nothing says what it moves. ` +
2689
- `Name one as "Claim <1-${SUCCESS_CLAIM_COUNT}>" in the title or body. Genuine cleanup ` +
2746
+ `the filing is novel, and names no SUCCESS.md claim — nothing says what it moves. ${ask} Genuine cleanup ` +
2690
2747
  `is still postable by a route that is deliberately not spelled in a refusal, and that ` +
2691
2748
  `route is recorded against this run and counted later`,
2692
2749
  };
@@ -2769,7 +2826,7 @@ export async function adjudicateFiling(
2769
2826
  refusal: null,
2770
2827
  reason:
2771
2828
  `no open issue shares this symptom, ${category} is not a dropped category, ` +
2772
- `it names SUCCESS.md claim ${namedClaim(`${attempt.title}\n${body}`)}, and it declares ` +
2829
+ `it names SUCCESS.md claim ${namedClaim(`${attempt.title}\n${body}`, claims)}, and it declares ` +
2773
2830
  `\`${declared}\` — ${COMMENT_EXEMPTIONS[declared]}`,
2774
2831
  };
2775
2832
  }
@@ -3482,6 +3539,9 @@ export async function filingGate(
3482
3539
  // The waiver's name, once per command for the same reason (SC-2735). `null`
3483
3540
  // waives nothing — `filingOverrideLabelFor`.
3484
3541
  const overrideLabel = filingOverrideLabelFor(() => readFilingOverrideLabel(root));
3542
+ // #2317: the claims THIS repository states, read once per command. A
3543
+ // consumer names its own claims, not this package's seven.
3544
+ const claims = claimsIn(readSuccessDoc(root));
3485
3545
  // Read once per TARGET TRACKER, not once per command and not once per
3486
3546
  // clause. Once per clause would adjudicate two creates against two
3487
3547
  // different snapshots; once per command would adjudicate a `--repo other/x`
@@ -3622,6 +3682,7 @@ export async function filingGate(
3622
3682
  () => readFor(attempt.repo),
3623
3683
  readBody,
3624
3684
  () => targetFor(attempt.repo),
3685
+ claims,
3625
3686
  );
3626
3687
  // The in-run class check, applied to anything the per-filing stages did
3627
3688
  // not already refuse. It converts an UNMEASURED as well as an ALLOW, and
@@ -131,6 +131,8 @@ export interface LiveIssue extends DepIssue {
131
131
  */
132
132
  readonly title: string;
133
133
  readonly body: string | null;
134
+ /** When the issue was filed (ISO 8601). Absent from a read that did not ask — SC-2783 needs it. */
135
+ readonly createdAt?: string;
134
136
  /**
135
137
  * True when the LABEL list was cut — a paged connection reporting another
136
138
  * page. Same reasoning as {@link DepIssue.blockedByTruncated}, and here
@@ -157,6 +159,7 @@ query($owner:String!,$name:String!,$states:[IssueState!],$after:String){
157
159
  state
158
160
  title
159
161
  body
162
+ createdAt
160
163
  milestone{title}
161
164
  labels(first:${ISSUE_PAGE}){pageInfo{hasNextPage} nodes{name}}
162
165
  blockedBy(first:${ISSUE_PAGE}){pageInfo{hasNextPage} nodes{number}}
@@ -173,6 +176,7 @@ interface IssuePage {
173
176
  state: string;
174
177
  title: string;
175
178
  body: string | null;
179
+ createdAt?: string;
176
180
  milestone: { title: string } | null;
177
181
  labels: { pageInfo: { hasNextPage: boolean }; nodes: { name: string }[] } | null;
178
182
  blockedBy: { pageInfo: { hasNextPage: boolean }; nodes: { number: number }[] } | null;
@@ -259,6 +263,7 @@ export async function readLiveIssues(
259
263
  // refuses rather than deriving from it: an unread blocker past the
260
264
  // boundary reads as missing and gets re-added.
261
265
  blockedByTruncated: n.blockedBy?.pageInfo.hasNextPage === true,
266
+ ...(typeof n.createdAt === "string" ? { createdAt: n.createdAt } : {}),
262
267
  });
263
268
  }
264
269
  if (!page.pageInfo.hasNextPage) return out;
@@ -28,6 +28,7 @@
28
28
  * acceptance step then refuses UNMEASURED, naming the key and why: a skipped
29
29
  * step reads as satisfied, and a missing family is not "nothing to place".
30
30
  */
31
+ import { boardProjectRun } from "./board-project-step";
31
32
 
32
33
  /** The file this module generates, under `.github/workflows/`. */
33
34
  export const ADR_ACCEPTED_WORKFLOW_FILE = "adr-accepted.yml";
@@ -84,6 +85,7 @@ export function buildAdrAcceptedWorkflow(opts: AdrAcceptedWorkflowOptions): stri
84
85
  const prefix = boardInput("milestonePrefix", opts.milestonePrefix);
85
86
  const missing = [spec, prefix].flatMap(i => (i.value === null ? [i.why] : []));
86
87
  const cli = `bunx rungate@${opts.version}`;
88
+ const indent = (script: string) => script.split("\n").map(l => (l === "" ? "" : ` ${l}`)).join("\n");
87
89
  // JSON is a YAML double-quoted scalar, so a quote or backslash in a value
88
90
  // stays inside it.
89
91
  const envValue = (i: BoardInput) => JSON.stringify(i.value ?? "");
@@ -208,11 +210,7 @@ ${opts.setupBunEnv}
208
210
  GITHUB_TOKEN: \${{ secrets.RUNGATE_PROJECT_TOKEN }}
209
211
  PROJECT_ID: \${{ vars.RUNGATE_PROJECT_ID }}
210
212
  run: |
211
- if [ -z "$PROJECT_ID" ]; then
212
- echo "::error::UNMEASURED — RUNGATE_PROJECT_ID is not set, so there is no board to write."
213
- exit 1
214
- fi
215
- ${cli} board-mirror --project "$PROJECT_ID" --write
213
+ ${indent(boardProjectRun(cli, "Criteria column", `${cli} board-mirror --project "$project" --write`))}
216
214
 
217
215
  - name: Top up Ready from the new issues
218
216
  if: \${{ !cancelled() && steps.accepted.outputs.any == 'true' }}
@@ -220,6 +218,7 @@ ${opts.setupBunEnv}
220
218
  BOARD_PROJECT_TOKEN: \${{ secrets.RUNGATE_PROJECT_TOKEN }}
221
219
  PROJECT_ID: \${{ vars.RUNGATE_PROJECT_ID }}
222
220
  ACTOR: \${{ github.actor }}
223
- run: ${cli} board-ready --repo "$GITHUB_REPOSITORY" --project "$PROJECT_ID" --actor "$ACTOR" --top-up --write
221
+ run: |
222
+ ${indent(boardProjectRun(cli, "Ready top-up", `${cli} board-ready --repo "$GITHUB_REPOSITORY" --project "$project" --actor "$ACTOR" --top-up --write`))}
224
223
  `;
225
224
  }
@@ -0,0 +1,49 @@
1
+ /**
2
+ * The board a generated step writes, or a warning that there is none.
3
+ *
4
+ * A step that writes the project board used to read only the
5
+ * `RUNGATE_PROJECT_ID` variable and exit 1 when it was empty. In a consumer
6
+ * with no board at all, that turned every push to `specs/` red, and every
7
+ * accepted ADR too. On 2026-11-17 the one live consumer held back from 0.8.27
8
+ * because of it.
9
+ *
10
+ * Two different states are kept apart here:
11
+ * - **no board configured.** No variable and no `board.id`. That is a warning
12
+ * annotation naming the state UNMEASURED, and exit 0, the way
13
+ * `board-intake.yml` reports it (#2166). There is nothing to write.
14
+ * - **a board, and something wrong with it.** `board-id` refusing for any
15
+ * other reason, or the write itself refusing. That stays red.
16
+ *
17
+ * The variable still wins when it is set, so a repository that configured it
18
+ * reads exactly what it read before.
19
+ */
20
+
21
+ import { NO_BOARD_REFUSAL } from "./board-ready-workflow";
22
+
23
+ /**
24
+ * Shell for one generated step: resolve the board's node id into `$project`,
25
+ * or end the step with a warning when none is configured, then run `command`.
26
+ * `cli` is the pinned `bunx rungate@<version>`. `title` names the annotation.
27
+ */
28
+ export function boardProjectRun(cli: string, title: string, command: string): string {
29
+ return [
30
+ `project="$PROJECT_ID"`,
31
+ `if [ -z "$project" ]; then`,
32
+ // The runner's own temp dir, cleaned per job, as board-intake.yml does: no
33
+ // mktemp to leak or to fail under `bash -e` (review of #2355).
34
+ ' err="$RUNNER_TEMP/board-id.stderr"',
35
+ ` code=0`,
36
+ ` project=$(${cli} board-id 2>"$err") || code=$?`,
37
+ ` cat "$err" >&2`,
38
+ // Only board-id's own no-board refusal is a warning. Its other refusals
39
+ // share the exit code, so the wording is what tells them apart.
40
+ // The one spelling of board-id's refusal, the one board-ready and board-intake read too.
41
+ ` if [ "$code" -ne 0 ] && grep -q '^${NO_BOARD_REFUSAL}' "$err"; then`,
42
+ ` echo "::warning title=${title}::UNMEASURED — no board is configured (board.id in the rungate config, or the RUNGATE_PROJECT_ID variable), so there is no board to write. Set board.id and this runs."`,
43
+ ` exit 0`,
44
+ ` fi`,
45
+ ` [ "$code" -eq 0 ] || exit "$code"`,
46
+ `fi`,
47
+ command,
48
+ ].join("\n");
49
+ }
@@ -32,6 +32,20 @@ export const REQUIRE_CLOSING_REF_VARIABLE = "RUNGATE_REQUIRE_CLOSING_REF";
32
32
  /** The process workflows whose jobs report a status on pull requests (ADR-014 decision 6's scope). */
33
33
  export const PROCESS_CHECK_WORKFLOWS = ["closing-references.yml"] as const;
34
34
 
35
+ /**
36
+ * Generated checks that must pass before a merge, one context each, owed only
37
+ * when the workflow defines that job (#2361). rungate's own `main` requires
38
+ * `test` and `ai-review` beside `closing-references`; GitHub's auto-merge, and
39
+ * any approve-on-green bot, waits only for checks branch protection requires,
40
+ * so a consumer that never required `ai-review` merged a PR mid-review. Named
41
+ * rather than every job of the workflow: `ci.yml`'s `test-shard` is a matrix
42
+ * whose contexts are not one name, and `test` is the job that speaks for them.
43
+ */
44
+ export const MERGE_GATE_CHECKS = [
45
+ { workflow: "ci.yml", context: "test" },
46
+ { workflow: "ai-review.yml", context: "ai-review" },
47
+ ] as const;
48
+
35
49
  export interface HumanStepReadings {
36
50
  /** `owner/name`; null when the origin remote names no GitHub repository; UNMEASURED when it could not be read (#2169). */
37
51
  slug: Reading<string | null>;
@@ -91,7 +105,7 @@ export function humanSteps(r: HumanStepReadings): string[] {
91
105
  for (const check of missing) {
92
106
  out.push(
93
107
  `OWED: gh api -X POST repos/${slug}/branches/${branch}/protection/required_status_checks/contexts ` +
94
- `-f 'contexts[]=${check}' # ${check} runs on every pull request and blocks nothing until it is required`,
108
+ `-f 'contexts[]=${check}' # ${check} runs on every pull request and blocks nothing until it is required; a merge bot of your own must wait for it too`,
95
109
  );
96
110
  }
97
111
  } else if (missing.length > 0 && statusChecks === "unprotected") {
@@ -125,6 +139,27 @@ export function humanSteps(r: HumanStepReadings): string[] {
125
139
  return out;
126
140
  }
127
141
 
142
+ /**
143
+ * Which contexts each workflow owes: `null` is every job in it, a set is only
144
+ * those. Entries for one file MERGE — a second context is added, and an
145
+ * all-jobs entry is never narrowed by a single-context one — so a workflow
146
+ * that gains a second tracked job cannot silently drop the first (review of
147
+ * #2362).
148
+ */
149
+ export function wantedChecks(
150
+ allJobs: readonly string[],
151
+ gates: readonly { workflow: string; context: string }[],
152
+ ): Map<string, Set<string> | null> {
153
+ const wanted = new Map<string, Set<string> | null>();
154
+ for (const f of allJobs) wanted.set(f, null);
155
+ for (const g of gates) {
156
+ const had = wanted.get(g.workflow);
157
+ if (had === null) continue;
158
+ wanted.set(g.workflow, new Set([...(had ?? []), g.context]));
159
+ }
160
+ return wanted;
161
+ }
162
+
128
163
  /**
129
164
  * The job names of the process checks present in `root`'s workflows, and the
130
165
  * workflows that are present but could not be read (#2161). A directory, a
@@ -134,7 +169,7 @@ export function humanSteps(r: HumanStepReadings): string[] {
134
169
  export function processChecksIn(root: string): { checks: string[]; unreadable: string[] } {
135
170
  const checks: string[] = [];
136
171
  const unreadable: string[] = [];
137
- for (const file of PROCESS_CHECK_WORKFLOWS) {
172
+ for (const [file, only] of wantedChecks(PROCESS_CHECK_WORKFLOWS, MERGE_GATE_CHECKS)) {
138
173
  const rel = `.github/workflows/${file}`;
139
174
  const p = join(root, ".github", "workflows", file);
140
175
  // The stat decides absence, and only its ENOENT counts: existsSync also
@@ -149,7 +184,8 @@ export function processChecksIn(root: string): { checks: string[]; unreadable: s
149
184
  continue;
150
185
  }
151
186
  try {
152
- checks.push(...jobContextNames(readFileSync(p, "utf-8")));
187
+ const jobs = jobContextNames(readFileSync(p, "utf-8"));
188
+ checks.push(...(only === null ? jobs : jobs.filter(j => only.has(j))));
153
189
  } catch (e) {
154
190
  unreadable.push(`${rel} could not be read (${(e as Error).message})`);
155
191
  }