rungate 0.8.16 → 0.8.17

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/gates/.gate-salt CHANGED
@@ -1 +1 @@
1
- eae3d899be4a8464ebf582bcba421f8e6660953f898adc3e5967ce30abf41a5b
1
+ 59ff9d2ffba3c61eb5cb8df8a3d5dcb4ca20c72e578589fd317a5ecac368d2c2
@@ -125,6 +125,14 @@ export interface ProtectionFacts {
125
125
  * excuse `strict: true`.
126
126
  */
127
127
  mergeQueueEnabled: boolean | null;
128
+ /**
129
+ * Which of the three states the branch is in, when the probe established it
130
+ * (#2154). Only `required-checks` accepts a POST to `…/contexts`; an
131
+ * unprotected branch needs the protection created, and a protected one
132
+ * with no required checks cannot take that POST either. Absent when the
133
+ * reading was not taken.
134
+ */
135
+ statusChecks?: "unprotected" | "no-required-checks" | "required-checks";
128
136
  /**
129
137
  * `required_conversation_resolution`, or null when the payload said nothing
130
138
  * either way — CRC-C3, #1650.
@@ -541,7 +549,7 @@ export const githubProtectionProbe: ProtectionProbe = async (slug) => {
541
549
  // Reading it as `null` would call that unestablished when it is the one
542
550
  // case the endpoint lets us establish without admin (#1650).
543
551
  if (!isProtected) {
544
- return { slug, branch, strict: false, ownerType, contexts: [], mergeQueueEnabled: null, conversationResolution: false, unreadable: null };
552
+ return { slug, branch, strict: false, ownerType, contexts: [], mergeQueueEnabled: null, conversationResolution: false, unreadable: null, statusChecks: "unprotected" };
545
553
  }
546
554
 
547
555
  try {
@@ -582,7 +590,7 @@ export function protectionFactsFromPayload(
582
590
  // No required_status_checks block: protection exists but requires no
583
591
  // checks, so there is no strictness and nothing to be out of date against.
584
592
  if (!rsc || typeof rsc !== "object") {
585
- return { slug, branch, strict: false, ownerType, contexts: [], mergeQueueEnabled: mergeQueueFrom(d), conversationResolution: conversationResolutionFrom(d), unreadable: null };
593
+ return { slug, branch, strict: false, ownerType, contexts: [], mergeQueueEnabled: mergeQueueFrom(d), conversationResolution: conversationResolutionFrom(d), unreadable: null, statusChecks: "no-required-checks" };
586
594
  }
587
595
 
588
596
  const strict = typeof rsc.strict === "boolean" ? rsc.strict : null;
@@ -596,7 +604,7 @@ export function protectionFactsFromPayload(
596
604
  (c: unknown): c is string => typeof c === "string" && c.length > 0,
597
605
  );
598
606
 
599
- return { slug, branch, strict, ownerType, contexts, mergeQueueEnabled: mergeQueueFrom(d), conversationResolution: conversationResolutionFrom(d), unreadable: null };
607
+ return { slug, branch, strict, ownerType, contexts, mergeQueueEnabled: mergeQueueFrom(d), conversationResolution: conversationResolutionFrom(d), unreadable: null, statusChecks: "required-checks" };
600
608
  }
601
609
 
602
610
  function mergeQueueFrom(d: Record<string, any>): boolean | null {
@@ -270,8 +270,9 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
270
270
  script: "scripts/board-ready.ts",
271
271
  summary: "Move the work a closed blocker freed, or the top of the backlog, into the board's Ready lane",
272
272
  usage:
273
- "rungate board-ready --repo <owner/name> --project <node-id> [--closed-issue <n>] [--top-up] " +
274
- "[--moving-issue <n>] [--actor <login>] [--write] (at least one of --closed-issue, --top-up)",
273
+ "rungate board-ready --repo <owner/name> [--project <node-id>] [--project-root <dir>] [--closed-issue <n>] " +
274
+ "[--top-up] [--moving-issue <n>] [--actor <login>] [--write] (at least one of --closed-issue, --top-up; " +
275
+ "--project defaults to board.id in the rungate config)",
275
276
  },
276
277
  // Reads a `gh pr view`-shaped payload on stdin, which the dispatcher passes
277
278
  // through (`stdio: "inherit"`), or `--fixture` offline.
@@ -11,6 +11,7 @@ import { existsSync, readFileSync } from "fs";
11
11
  import { join } from "path";
12
12
  import type { ProjectScan } from "./types";
13
13
  import { OWNED_FILES, ownedFilesTable } from "../scaffold/owned-files";
14
+ import { ALIGNMENT_PROCESS_RULE_FILE, alignmentProcessRule } from "../scaffold/process-rules";
14
15
  import { commandRoutingTable } from "../cli-commands";
15
16
  import { isHarnessItself } from "../harness-identity";
16
17
  import { typecheckDecision } from "../typescript-project";
@@ -339,6 +340,7 @@ description: Shared behavioral principles for all agents working in this project
339
340
  - Skip ACs without rationale
340
341
  - Commit secrets or credentials
341
342
  - Spawn subagents for single-file tasks — do the work directly
343
+ - Hand-patch what a process tool's \`--write\` left red — that is a tool defect; fix the tool
342
344
  `,
343
345
  });
344
346
 
@@ -441,6 +443,14 @@ ${commandRoutingTable()}
441
443
  `,
442
444
  });
443
445
 
446
+ // #2049, ADR-014 decision 4: the four-step process, from the one source
447
+ // this repository's own rule 9 is checked against. Scoped only here, where
448
+ // AGENTS.md already carries rule 9 at launch — `lib/scaffold/process-rules.ts`.
449
+ rules.push({
450
+ filename: ALIGNMENT_PROCESS_RULE_FILE,
451
+ content: alignmentProcessRule({ scoped: isHarnessItself(scan.root) }),
452
+ });
453
+
444
454
  rules.push({
445
455
  filename: "harness-managed.md",
446
456
  content: `---
@@ -636,6 +646,17 @@ nobody can interpret becomes a number nobody lowers.
636
646
  `,
637
647
  });
638
648
 
649
+ // The filing gate runs from this repository's own hooks and no consumer's
650
+ // defaults install it, so the line would name machinery a consumer lacks
651
+ // (review of #2155).
652
+ const filingLine = isHarnessItself(scan.root)
653
+ ? `
654
+ **Filing:** \`gh issue create\` without \`--repo\`, from a session launched in
655
+ the project root. The filing gate reads its config from the launch directory,
656
+ and a \`--repo\` filing gets no queue raise.
657
+ `
658
+ : "";
659
+
639
660
  rules.push({
640
661
  filename: "parallel-sessions.md",
641
662
  content: `---
@@ -652,7 +673,7 @@ gh issue edit <N> --add-assignee @me # then start
652
673
  The issue tracker is the claim registry. It is the only place every session can
653
674
  see, so a claim that lives anywhere else — a message, another session's
654
675
  context, a branch nobody pushed — is not a claim.
655
-
676
+ ${filingLine}
656
677
  **Why this is a rule and not a nicety:** an issue reading "open" while the work
657
678
  is finished is indistinguishable from an issue nobody has started. That is not
658
679
  hypothetical. On 2026-10-06 one session described #70 as "unclaimed, small,
@@ -666,6 +687,9 @@ collided with a branch they could not see.
666
687
  When the work is done and CI is green: push, open a PR, merge it. Do not hold a
667
688
  finished branch pending approval, and do not ask whether to push.
668
689
 
690
+ Wait on checks with \`gh pr checks <N> --watch --fail-fast\`: the first red
691
+ ends the wait, not the whole suite.
692
+
669
693
  **Why:** unpushed finished work is invisible. It makes the tracker lie, it
670
694
  makes other sessions duplicate effort, and it is lost entirely if the session
671
695
  or the worktree goes away. Review happens on the PR, where it is durable and
package/lib/github.ts CHANGED
@@ -111,6 +111,15 @@ export interface GitHubClient {
111
111
  */
112
112
  listForRef: (params: { owner: string; repo: string; ref: string; per_page?: number }) => Promise<{ data: { total_count: number; check_runs: any[] } }>;
113
113
  };
114
+ /**
115
+ * Repository Actions settings, read by `lib/scaffold/human-steps.ts`
116
+ * (#2051). Both 404 when the secret or variable is not set, which is a
117
+ * reading; anything else is not.
118
+ */
119
+ actions: {
120
+ getRepoSecret: (params: { owner: string; repo: string; secret_name: string }) => Promise<{ data: any }>;
121
+ getRepoVariable: (params: { owner: string; repo: string; name: string }) => Promise<{ data: { value?: string } }>;
122
+ };
114
123
  };
115
124
  /**
116
125
  * The GraphQL endpoint, for the handful of operations REST does not expose.
@@ -0,0 +1,219 @@
1
+ /**
2
+ * `.github/workflows/adr-accepted.yml`, generated — #2046, ADR-014 row 3,
3
+ * SC-2744.
4
+ *
5
+ * Merging an ADR whose status changes to accepted places its plan on the board
6
+ * with no command typed by hand (SC-2738, ADR-013 rule 9 step 3). The file was
7
+ * hand-written and caller-owned, and it ran `bun scripts/…` — paths a consumer
8
+ * does not have. Rule 9 is every consumer's process, so the scaffold now
9
+ * writes it, and this repository's copy is the generated one (ADR-014
10
+ * decision 1).
11
+ *
12
+ * ## It calls the published CLI
13
+ *
14
+ * A consumer has `node_modules/rungate`, not `scripts/` (ADR-014 decision 2),
15
+ * so every step runs `bunx rungate@<version> <command>`, at the generating
16
+ * version — the same reading every other `bunx` pin takes.
17
+ *
18
+ * ## The engine's spec and family are read at scaffold time
19
+ *
20
+ * The hand-written file read `board.engineSpec` and `board.milestonePrefix`
21
+ * at run time by importing `./lib/config-readers`, which a consumer does not
22
+ * have either. They are read here instead, through the one loader, and
23
+ * written into the job's `env:`. A config change is a re-scaffold, and the
24
+ * workflow drift check sees a committed file that no longer matches.
25
+ *
26
+ * A value that is unset, or one that would be read as something other than
27
+ * itself — a newline, or an Actions expression — is not written. The
28
+ * acceptance step then refuses UNMEASURED, naming the key and why: a skipped
29
+ * step reads as satisfied, and a missing family is not "nothing to place".
30
+ */
31
+
32
+ /** The file this module generates, under `.github/workflows/`. */
33
+ export const ADR_ACCEPTED_WORKFLOW_FILE = "adr-accepted.yml";
34
+
35
+ /** The one job in it. */
36
+ export const ADR_ACCEPTED_JOB = "place-the-plan";
37
+
38
+ /**
39
+ * The five commands, in the order each needs the one before it, after the
40
+ * acceptance read (`plan-issues --accepted-since`). Each must be registered in
41
+ * `lib/cli-commands.ts`, or the workflow calls a command `bin/rungate.ts`
42
+ * refuses (#675's defect).
43
+ */
44
+ export const ADR_ACCEPTED_COMMANDS = ["plan-issues", "plan-spec", "plan-deps", "board-mirror", "board-ready"] as const;
45
+
46
+ /** One engine input as the generator will write it, or why it will not. */
47
+ export type BoardInput = { value: string } | { value: null; why: string };
48
+
49
+ /**
50
+ * Whether `raw` can be written into the job's `env:` as itself. A newline
51
+ * could forge a second key wherever a step echoes it, and `${{` is evaluated
52
+ * by Actions before the shell sees it — either way the step would read
53
+ * something the config does not say.
54
+ */
55
+ export function boardInput(key: string, raw: string | null): BoardInput {
56
+ if (raw === null) return { value: null, why: `board.${key} is not set` };
57
+ if (/[\r\n]/.test(raw)) return { value: null, why: `board.${key} contains a newline` };
58
+ if (raw.includes("${{")) return { value: null, why: `board.${key} contains an Actions expression marker, a dollar sign and two braces` };
59
+ return { value: raw };
60
+ }
61
+
62
+ export interface AdrAcceptedWorkflowOptions {
63
+ /** The `runs-on:` value, already JSON-quoted by the caller. */
64
+ runsOn: string;
65
+ /** The pinned `actions/checkout` reference. */
66
+ checkout: string;
67
+ /** The pinned `oven-sh/setup-bun` reference. */
68
+ setupBun: string;
69
+ /** The `with:` body of that step, at ten spaces — the project's single bun declaration (#622). */
70
+ setupBunWith: string;
71
+ /** The step's `env:` block, from `setupBunEnv` (#2039). */
72
+ setupBunEnv: string;
73
+ /** The published harness version every step runs through `bunx`. */
74
+ version: string;
75
+ /** `board.engineSpec`, read through `readBoardInputs`. */
76
+ engineSpec: string | null;
77
+ /** `board.milestonePrefix`, read through `readBoardInputs`. */
78
+ milestonePrefix: string | null;
79
+ }
80
+
81
+ /** The whole `adr-accepted.yml` body. */
82
+ export function buildAdrAcceptedWorkflow(opts: AdrAcceptedWorkflowOptions): string {
83
+ const spec = boardInput("engineSpec", opts.engineSpec);
84
+ const prefix = boardInput("milestonePrefix", opts.milestonePrefix);
85
+ const missing = [spec, prefix].flatMap(i => (i.value === null ? [i.why] : []));
86
+ const cli = `bunx rungate@${opts.version}`;
87
+ // JSON is a YAML double-quoted scalar, so a quote or backslash in a value
88
+ // stays inside it.
89
+ const envValue = (i: BoardInput) => JSON.stringify(i.value ?? "");
90
+ const refusal =
91
+ missing.length === 0
92
+ ? ""
93
+ : `
94
+ echo "::error::UNMEASURED — ${missing.join("; ")}, so this push's plan has no milestones to land in. Nothing was written. Set board.engineSpec and board.milestonePrefix in the rungate config and re-run rungate scaffold."
95
+ exit 1`;
96
+
97
+ return `# Managed by rungate — do not edit. Set board.engineSpec and board.milestonePrefix
98
+ # in .claude/rungate/config.json and re-run \`rungate scaffold\`.
99
+ #
100
+ # SC-2738 (ADR-013 row 5): merging an ADR whose status changes to accepted
101
+ # places its plan on the board, with no command typed by hand. Generated since
102
+ # #2046 (ADR-014 row 3), so a consumer gets step 3 of the four-step process and
103
+ # this repository's copy is the generated one.
104
+ #
105
+ # The five commands, in the order each needs the one before it:
106
+ #
107
+ # plan-spec the engine spec's milestones, so every row's milestone exists
108
+ # plan-issues the ADR's Decomposition rows become issues, with blocked-by
109
+ # plan-deps the phase-order links between milestones
110
+ # board-mirror the Criteria column on the board
111
+ # board-ready a Ready top-up, because issues created with GITHUB_TOKEN
112
+ # fire no \`issues: opened\` run of board-ready.yml
113
+ #
114
+ # Every one is idempotent, so a re-run writes only what is missing. An edit to
115
+ # an ADR that was ALREADY accepted lists nothing and every later step is skipped.
116
+ #
117
+ # CREDENTIALS, SPLIT BY STEP. The issue, milestone and edge writes use the
118
+ # job's own GITHUB_TOKEN, passed as GITHUB_TOKEN because plan-issues drops
119
+ # GH_TOKEN. RUNGATE_PROJECT_TOKEN reaches only the two board steps, in their
120
+ # own env (#1761). The first \`bunx\` runs in the acceptance step, which holds
121
+ # no token, so the package is fetched before any step that holds the PAT.
122
+ name: ADR accepted — place its plan on the board
123
+
124
+ on:
125
+ push:
126
+ branches: [main]
127
+ paths: ["docs/adr/**"]
128
+
129
+ permissions:
130
+ contents: read
131
+ # Issues, milestones and blocked-by edges. Nothing else this job writes is
132
+ # reachable with GITHUB_TOKEN.
133
+ issues: write
134
+
135
+ # Two merges in quick succession must not race each other's issue creation:
136
+ # the second run reads the tracker the first one wrote.
137
+ concurrency:
138
+ group: adr-accepted
139
+ cancel-in-progress: false
140
+
141
+ jobs:
142
+ ${ADR_ACCEPTED_JOB}:
143
+ runs-on: ${opts.runsOn}
144
+ env:
145
+ SPEC: ${envValue(spec)}
146
+ PREFIX: ${envValue(prefix)}
147
+ steps:
148
+ # fetch-depth 0: the acceptance read compares each ADR with the commit
149
+ # before this push, and refuses when that commit is not in the clone.
150
+ - uses: ${opts.checkout}
151
+ with:
152
+ fetch-depth: 0
153
+ - uses: ${opts.setupBun}
154
+ with:
155
+ ${opts.setupBunWith}
156
+ ${opts.setupBunEnv}
157
+ - id: accepted
158
+ name: Which ADRs did this push accept?
159
+ env:
160
+ BEFORE: \${{ github.event.before }}
161
+ run: |
162
+ ${cli} plan-issues --accepted-since "$BEFORE" > accepted.txt
163
+ echo "Accepted by this push:"
164
+ cat accepted.txt
165
+ if [ ! -s accepted.txt ]; then
166
+ echo "any=false" >> "$GITHUB_OUTPUT"
167
+ exit 0
168
+ fi${refusal}
169
+ echo "any=true" >> "$GITHUB_OUTPUT"
170
+
171
+ - name: Milestones from the engine spec's placement table
172
+ if: steps.accepted.outputs.any == 'true'
173
+ env:
174
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
175
+ run: ${cli} plan-spec "$SPEC" --repo "$GITHUB_REPOSITORY" --prefix "$PREFIX" --write
176
+
177
+ # One ADR at a time; \`bash -e\` stops at the first refusal, so a plan the
178
+ # filing tool refuses is a red run naming the ADR.
179
+ - name: Issues and blocked-by edges from each accepted ADR
180
+ if: steps.accepted.outputs.any == 'true'
181
+ env:
182
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
183
+ run: |
184
+ while IFS= read -r adr; do
185
+ echo "== $adr"
186
+ ${cli} plan-issues --decompose "$adr" --repo "$GITHUB_REPOSITORY" --write
187
+ done < accepted.txt
188
+
189
+ - name: Phase-order links between milestones
190
+ if: steps.accepted.outputs.any == 'true'
191
+ env:
192
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
193
+ run: ${cli} plan-deps --repo "$GITHUB_REPOSITORY" --milestone-prefix "$PREFIX" --write
194
+
195
+ # The board steps. THE SECRET IS \`RUNGATE_PROJECT_TOKEN\`: board-mirror
196
+ # reads it as GITHUB_TOKEN, board-ready as BOARD_PROJECT_TOKEN. An absent
197
+ # secret is the empty string with no error, so each command's own
198
+ # UNMEASURED refusal is what reports it.
199
+ - name: Criteria column on the board
200
+ if: steps.accepted.outputs.any == 'true'
201
+ env:
202
+ GITHUB_TOKEN: \${{ secrets.RUNGATE_PROJECT_TOKEN }}
203
+ PROJECT_ID: \${{ vars.RUNGATE_PROJECT_ID }}
204
+ run: |
205
+ if [ -z "$PROJECT_ID" ]; then
206
+ echo "::error::UNMEASURED — RUNGATE_PROJECT_ID is not set, so there is no board to write."
207
+ exit 1
208
+ fi
209
+ ${cli} board-mirror --project "$PROJECT_ID" --write
210
+
211
+ - name: Top up Ready from the new issues
212
+ if: steps.accepted.outputs.any == 'true'
213
+ env:
214
+ BOARD_PROJECT_TOKEN: \${{ secrets.RUNGATE_PROJECT_TOKEN }}
215
+ PROJECT_ID: \${{ vars.RUNGATE_PROJECT_ID }}
216
+ ACTOR: \${{ github.actor }}
217
+ run: ${cli} board-ready --repo "$GITHUB_REPOSITORY" --project "$PROJECT_ID" --actor "$ACTOR" --top-up --write
218
+ `;
219
+ }
@@ -0,0 +1,168 @@
1
+ /**
2
+ * `.github/workflows/closing-references.yml`, generated — #2045, ADR-014 row 2,
3
+ * SC-2743.
4
+ *
5
+ * The check refuses a pull request whose closing keyword GitHub will never
6
+ * act on, or that closes no issue, or whose issue has not answered the
7
+ * criterion question (ADR-013 rule 9 step 4). It was hand-written and
8
+ * NOT-OWNED on the reasoning that it was this repository's policy about its
9
+ * own pull request bodies. Rule 9 made it every consumer's policy, so the
10
+ * scaffold now writes it, and this repository's copy is the generated one
11
+ * (ADR-014 decision 1): the bytes here are the bytes a consumer gets.
12
+ *
13
+ * ## It calls the published CLI
14
+ *
15
+ * A consumer has `node_modules/rungate`, not `scripts/` (ADR-014 decision 2),
16
+ * so the step runs `bunx rungate@<version> audit-closing-references`. The
17
+ * version is the generating one, the same reading every other `bunx` pin
18
+ * takes, so a tree ahead of npm emits a command the registry cannot satisfy
19
+ * until the release ships. `docs/guides/RELEASING.md` is the sequence.
20
+ *
21
+ * ## It runs in a merge queue too, and reads a real pull request there
22
+ *
23
+ * A required check with no `merge_group` trigger hangs a queue
24
+ * (`test/merge-group-trigger.test.ts`). A queue run has no pull request in
25
+ * its payload, but its ref names one — `gh-readonly-queue/<base>/pr-<N>-<sha>`
26
+ * — so the step reads that pull request rather than reporting a reading it
27
+ * did not take. A ref naming none is UNMEASURED and red.
28
+ */
29
+
30
+ /** The file this module generates, under `.github/workflows/`. */
31
+ export const CLOSING_REFERENCES_WORKFLOW_FILE = "closing-references.yml";
32
+
33
+ /** The one job in it, which is also the required status context's name. */
34
+ export const CLOSING_REFERENCES_JOB = "closing-references";
35
+
36
+ /**
37
+ * The CLI command the step runs. `lib/cli-commands.ts` must register it, or
38
+ * the workflow calls a command `bin/rungate.ts` refuses (#675's defect).
39
+ */
40
+ export const CLOSING_REFERENCES_COMMAND = "audit-closing-references";
41
+
42
+ /**
43
+ * ONE query, with each issue body on the `closingIssuesReferences` node GitHub
44
+ * returned (SC-2737). `files` is the diff the session-record exemption is
45
+ * decided from; `totalCount` travels with the issues and the commits so the
46
+ * command can refuse a list that was cut short.
47
+ */
48
+ const QUERY_LINES = [
49
+ "query($owner: String!, $name: String!, $number: Int!) {",
50
+ "repository(owner: $owner, name: $name) { pullRequest(number: $number) {",
51
+ "number body",
52
+ "files(first: 100) { nodes { path } }",
53
+ "closingIssuesReferences(first: 100) { totalCount",
54
+ "nodes { number title body repository { name owner { login } } } }",
55
+ "commits(first: 250) { totalCount nodes { commit { oid message } } }",
56
+ "} } }",
57
+ ];
58
+
59
+ /**
60
+ * The step's `run:` body. Exported so `test/closing-references-workflow.test.ts`
61
+ * executes THIS text against a stub `gh` and `bunx`, rather than a paraphrase.
62
+ *
63
+ * `pipefail` because `run:` is `bash -e`, which takes a pipeline's status from
64
+ * its LAST command: a failed query would hand the command an empty stdin and
65
+ * the step's status would be the command's. No `|| true` and no
66
+ * `2>/dev/null` for the same reason.
67
+ */
68
+ export function buildClosingReferencesScript(version: string): string {
69
+ return `set -o pipefail
70
+ # A pull request run carries its number. A merge-queue run does not, but its
71
+ # ref names the pull request: gh-readonly-queue/<base>/pr-<N>-<sha>.
72
+ number="\${PR:-}"
73
+ if [ -z "$number" ]; then
74
+ number=$(printf '%s' "\${QUEUE_REF:-}" | sed -n 's|^.*/pr-\\([0-9][0-9]*\\)-[0-9a-f][0-9a-f]*$|\\1|p')
75
+ fi
76
+ if [ -z "$number" ]; then
77
+ echo "::error::UNMEASURED — this run carries no pull request number and its ref (\${QUEUE_REF:-none}) names none, so there is no pull request body to check. Nothing was read."
78
+ exit 1
79
+ fi
80
+ # GitHub's answer is the input: the command never computes its own idea of
81
+ # whether an issue is linked. --repo because a bare number is not an identity.
82
+ gh api graphql -f query="$QUERY" \\
83
+ -f owner="\${GITHUB_REPOSITORY%/*}" -f name="\${GITHUB_REPOSITORY#*/}" -F number="$number" \\
84
+ --jq '.data.repository.pullRequest | {number, body, files: .files.nodes, closingIssuesReferences: .closingIssuesReferences.nodes, closingIssuesTotal: .closingIssuesReferences.totalCount, commits: [.commits.nodes[].commit | {sha: .oid, message}], commitsTotal: .commits.totalCount}' \\
85
+ | bunx rungate@${version} ${CLOSING_REFERENCES_COMMAND} --repo "$GITHUB_REPOSITORY"
86
+ `;
87
+ }
88
+
89
+ export interface ClosingReferencesWorkflowOptions {
90
+ /** The `runs-on:` value, already JSON-quoted by the caller. */
91
+ runsOn: string;
92
+ /** The pinned `actions/checkout` reference. */
93
+ checkout: string;
94
+ /** The pinned `oven-sh/setup-bun` reference. */
95
+ setupBun: string;
96
+ /** The `with:` body of that step, at ten spaces — the project's single bun declaration (#622). */
97
+ setupBunWith: string;
98
+ /** The step's `env:` block, from `setupBunEnv` (#2039). */
99
+ setupBunEnv: string;
100
+ /** The published harness version the step runs through `bunx`. */
101
+ version: string;
102
+ }
103
+
104
+ /**
105
+ * The whole `closing-references.yml` body.
106
+ *
107
+ * It checks out the pull request's tree because the command reads `specs/`
108
+ * for its fourth refusal (a closed issue naming a criterion the tree leaves
109
+ * unticked). The trigger is `pull_request`, never `pull_request_target`, and
110
+ * every permission is read-only, so a fork's code runs with no write token.
111
+ */
112
+ export function buildClosingReferencesWorkflow(opts: ClosingReferencesWorkflowOptions): string {
113
+ const indent = (text: string, pad: string) =>
114
+ text
115
+ .trimEnd()
116
+ .split("\n")
117
+ .map(line => (line === "" ? "" : `${pad}${line}`))
118
+ .join("\n");
119
+
120
+ return `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
121
+ #
122
+ # A closing keyword GitHub cannot see, and a pull request that closes no issue
123
+ # (#1362, ADR-013 rule 9 step 4). Generated since #2045: rule 9 is every
124
+ # consumer's policy, so the scaffold writes this file and this repository's
125
+ # copy is the generated one.
126
+ #
127
+ # RUNGATE_REQUIRE_CLOSING_REF turns the last two refusals on when it is the
128
+ # string \`true\`, and at no other value; otherwise they are a warning
129
+ # annotation. Make \`${CLOSING_REFERENCES_JOB}\` a required check to enforce it.
130
+ name: Closing references
131
+
132
+ on:
133
+ # \`edited\` is ADR-013 decision 4: adding "Fixes #N" to the description is
134
+ # the remedy the refusal prints, so editing the body re-runs it.
135
+ pull_request:
136
+ types: [opened, synchronize, reopened, edited]
137
+ # A required check must report in a merge queue or the queue waits for it
138
+ # forever. The queue run reads the pull request its ref names.
139
+ merge_group:
140
+
141
+ permissions:
142
+ contents: read
143
+ # \`closingIssuesReferences\` resolves through the GraphQL API and reads the
144
+ # linked ISSUES, not just the pull request, so both are needed.
145
+ pull-requests: read
146
+ issues: read
147
+
148
+ jobs:
149
+ ${CLOSING_REFERENCES_JOB}:
150
+ runs-on: ${opts.runsOn}
151
+ steps:
152
+ - uses: ${opts.checkout}
153
+ - uses: ${opts.setupBun}
154
+ with:
155
+ ${opts.setupBunWith}
156
+ ${opts.setupBunEnv}
157
+ - name: A closing keyword GitHub cannot see, and a pull request that closes no issue
158
+ env:
159
+ GH_TOKEN: \${{ github.token }}
160
+ PR: \${{ github.event.pull_request.number }}
161
+ QUEUE_REF: \${{ github.event.merge_group.head_ref }}
162
+ RUNGATE_REQUIRE_CLOSING_REF: \${{ vars.RUNGATE_REQUIRE_CLOSING_REF }}
163
+ QUERY: >-
164
+ ${indent(QUERY_LINES.join("\n"), " ")}
165
+ run: |
166
+ ${indent(buildClosingReferencesScript(opts.version), " ")}
167
+ `;
168
+ }