rungate 0.6.0 → 0.7.0

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 (113) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +81 -16
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-protection.ts +790 -0
  7. package/lib/brief-ac-alignment.ts +104 -0
  8. package/lib/brief-references.ts +205 -0
  9. package/lib/bun-version.ts +93 -14
  10. package/lib/check-remedy.ts +140 -0
  11. package/lib/ci-checkout.ts +17 -0
  12. package/lib/ci-history-depth.ts +159 -0
  13. package/lib/ci-setup-step.ts +96 -0
  14. package/lib/claude-code-action.ts +85 -0
  15. package/lib/claude-tool-vocabulary.ts +188 -0
  16. package/lib/cli-commands.ts +15 -0
  17. package/lib/commit-sha.ts +42 -0
  18. package/lib/commit-subject.ts +90 -0
  19. package/lib/compliance-report.ts +377 -45
  20. package/lib/compliance.ts +191 -17
  21. package/lib/config-loader.ts +39 -1
  22. package/lib/config-trackable.ts +391 -0
  23. package/lib/conformity.ts +1087 -100
  24. package/lib/containment.ts +238 -0
  25. package/lib/content-hash.ts +24 -0
  26. package/lib/create-sc.ts +249 -16
  27. package/lib/dev-liveness.ts +180 -0
  28. package/lib/discovery-branch-points.ts +432 -0
  29. package/lib/discovery-stability.ts +481 -0
  30. package/lib/distribution-currency.ts +186 -0
  31. package/lib/doc-routing.ts +157 -0
  32. package/lib/evidence-prevalidator.ts +224 -2
  33. package/lib/evidence-satisfiability.ts +534 -12
  34. package/lib/failure-intake.ts +317 -0
  35. package/lib/fallow-availability.ts +157 -0
  36. package/lib/fs-write-capabilities.ts +232 -0
  37. package/lib/gate-run-split.ts +147 -0
  38. package/lib/generators/agents-md.ts +140 -32
  39. package/lib/git-isolation.ts +140 -0
  40. package/lib/github.ts +15 -0
  41. package/lib/google-auth-action.ts +93 -0
  42. package/lib/harness-project.ts +48 -0
  43. package/lib/harness-provenance.ts +255 -0
  44. package/lib/hook-evidence.ts +235 -0
  45. package/lib/hook-scopes.ts +386 -0
  46. package/lib/hook-target-tree.ts +398 -0
  47. package/lib/hook-trees.ts +447 -0
  48. package/lib/js-top-level-code.ts +78 -10
  49. package/lib/junit-checks.ts +52 -0
  50. package/lib/launch-base.ts +253 -0
  51. package/lib/line-citation.ts +372 -0
  52. package/lib/orphan-reaper.ts +468 -0
  53. package/lib/parity-binding.ts +205 -0
  54. package/lib/per-test-timeouts.ts +219 -0
  55. package/lib/plan-coverage.ts +151 -0
  56. package/lib/prior-branch.ts +201 -8
  57. package/lib/process-table.ts +146 -0
  58. package/lib/project-state-derivation.ts +219 -0
  59. package/lib/project-state-root.ts +258 -0
  60. package/lib/published-artifact.ts +525 -0
  61. package/lib/readdir-sorted.ts +45 -0
  62. package/lib/review-execution-reading.ts +206 -0
  63. package/lib/review-tool-agreement.ts +433 -0
  64. package/lib/rule-promotion.ts +234 -0
  65. package/lib/rule-retirement.ts +525 -0
  66. package/lib/run-branch.ts +612 -0
  67. package/lib/rungate-schema.ts +19 -0
  68. package/lib/runner-home.ts +274 -0
  69. package/lib/sc-id-cross-tree.ts +19 -7
  70. package/lib/sc-ids.ts +121 -13
  71. package/lib/sc-reservations.ts +289 -0
  72. package/lib/scaffold/ai-review-findings.ts +403 -0
  73. package/lib/scaffold/ai-review-step.ts +4661 -64
  74. package/lib/scaffold/managed-workflow.ts +587 -192
  75. package/lib/scaffold/owned-files.ts +152 -45
  76. package/lib/scaffold/pre-push-hook.ts +49 -5
  77. package/lib/scaffold/steps.ts +1413 -244
  78. package/lib/scaffold/workflow-census.ts +217 -0
  79. package/lib/scaffold/workflow-drift.ts +217 -0
  80. package/lib/scaffold/write-steps.ts +4 -0
  81. package/lib/scan-budget.ts +247 -0
  82. package/lib/scanner.ts +43 -51
  83. package/lib/scratch-roots.ts +50 -5
  84. package/lib/screenshot-discovery.ts +121 -0
  85. package/lib/screenshot-upload.ts +41 -1
  86. package/lib/secret-patterns.ts +511 -8
  87. package/lib/ship-mode.ts +219 -0
  88. package/lib/source-slice.ts +294 -0
  89. package/lib/stale-cleanup.ts +37 -3
  90. package/lib/suite-flake.ts +278 -0
  91. package/lib/suite-measurement.ts +23 -4
  92. package/lib/suite-run-reading.ts +241 -1
  93. package/lib/suite-timeout-margin.ts +193 -0
  94. package/lib/test-case-bodies.ts +883 -0
  95. package/lib/test-case-deletion.ts +653 -0
  96. package/lib/test-census.ts +97 -29
  97. package/lib/test-command-positions.ts +274 -0
  98. package/lib/test-suite-lock.ts +159 -16
  99. package/lib/tool-probe.ts +31 -9
  100. package/lib/top-level-cd.ts +393 -0
  101. package/lib/tree-entries.ts +89 -0
  102. package/lib/ts-ast.ts +200 -0
  103. package/lib/walk-test-files.ts +97 -0
  104. package/lib/workflow-actions.ts +263 -0
  105. package/lib/worktree-collect.ts +177 -5
  106. package/lib/worktree-repo.ts +36 -1
  107. package/package.json +2 -1
  108. package/scripts/ai-review-findings.ts +45 -0
  109. package/scripts/create-sc.ts +21 -1
  110. package/scripts/extract-constraints.ts +107 -7
  111. package/scripts/generate-code-map.ts +23 -30
  112. package/scripts/scaffold-project.ts +8 -1
  113. package/scripts/sync-sc-status.ts +77 -16
@@ -0,0 +1,219 @@
1
+ /**
2
+ * Every construct in a test file that raises the per-test budget above the
3
+ * one `bunfig.toml` declares (#968, from #804/#621).
4
+ *
5
+ * ## The subject, and why it is wider than one spelling
6
+ *
7
+ * `timeoutProximityViolations` in `lib/junit-checks.ts` compares each case's
8
+ * measured duration against ONE number — the budget in force. A case that
9
+ * carries a budget of its own leaves that reading two ways: it is never
10
+ * killed at the global budget, so the `was KILLED` row cannot fire; and once
11
+ * it runs past the global budget the proximity row cannot fire either, since
12
+ * that row requires `ms < timeoutMs`. That is the mechanism by which #802's
13
+ * `}, 60_000)` took the SC-6 scan out of the one instrument that would have
14
+ * warned before the kill — the headline finding of #804.
15
+ *
16
+ * The detector this replaces, in `test/scan-budget.test.ts`, was
17
+ * `/\}\s*,\s*([0-9_]+)\s*\)\s*;/g`. MEASURED on bun 1.3.14 against a
18
+ * `--timeout 300` budget, with a case that sleeps 600ms: the no-override
19
+ * control is killed at 300ms, and all five of these run to completion.
20
+ *
21
+ * | form | raises the budget | old regex |
22
+ * |---|---|---|
23
+ * | `}, 60_000);` | yes | matched |
24
+ * | `}, TIMEOUT);` | yes | **missed** |
25
+ * | `}, 60 * 1000);` | yes | **missed** |
26
+ * | `}, 60_000)` no `;` | yes | **missed** |
27
+ * | `}, { timeout: 5000 });` | yes | **missed** |
28
+ * | `setDefaultTimeout(…)` | yes | **missed** |
29
+ *
30
+ * So the guard against reintroducing #802's override was walked around by
31
+ * extracting the number into a constant. Four of the five ways to write the
32
+ * exact defect it was written for went unseen.
33
+ *
34
+ * ## What it reports, and what it deliberately does not
35
+ *
36
+ * It reports DECLARATIONS, not values. `}, TIMEOUT)` is reported as the text
37
+ * `TIMEOUT`, with no attempt to resolve it — resolving constants would be a
38
+ * second interpreter, and the question here is "does this case have a budget
39
+ * of its own", which the declaration answers on its own. A declaration that
40
+ * happens to equal the global budget is still a declaration, and still takes
41
+ * the case out of the `was KILLED` row.
42
+ *
43
+ * `null` means the source did not parse. That is a REFUSAL, distinct from
44
+ * `[]`, and the caller must keep them distinct — a parser that stopped
45
+ * parsing reports exactly as clean as a file with no overrides, which is the
46
+ * defect class #968 exists to close.
47
+ *
48
+ * ## Import aliases are resolved, because matching the local name was a hole
49
+ *
50
+ * The review of this PR found the defect class reproduced in its own fix:
51
+ * `CASE_ROOTS` matched the LOCAL identifier, so
52
+ * `import { test as t } from "bun:test"` silently defeated the detector —
53
+ * MEASURED at 0 declarations for `t("slow", () => {}, 60_000)`, and the same
54
+ * for `setDefaultTimeout as sdt` and `beforeAll as bA`. Callees are now
55
+ * resolved through the module's import bindings to the name bun:test
56
+ * exports, so the alias, the namespace form (`import * as bt`, `bt.test(…)`)
57
+ * and the injected global are one question.
58
+ *
59
+ * ## WHAT THIS DOES NOT COVER (stated rather than implied)
60
+ *
61
+ * MEASURED to return `[]`:
62
+ *
63
+ * - **An indirection through a variable.** `const t = test; t("a", fn, 1000)`.
64
+ * Only import bindings are resolved, not assignments.
65
+ * - **Computed member access.** `bt["test"](…)` on a namespace import.
66
+ * - **A wrapper that declares the budget for you.** A local
67
+ * `slowTest(name, fn)` that calls `test(name, fn, 60_000)` internally IS
68
+ * reported, at the call inside the wrapper — but only because that call
69
+ * is in the same module. A wrapper imported from elsewhere is not.
70
+ *
71
+ * None of these appear in this repo: the 594-file census in the PR found no
72
+ * aliased, namespaced or indirected case declaration.
73
+ */
74
+
75
+ import {
76
+ type AstNode,
77
+ calleeRoot,
78
+ importBindings,
79
+ parseTsModule,
80
+ rootProperty,
81
+ walkNodes,
82
+ } from "./ts-ast";
83
+
84
+ /** The callees that declare a test case and accept a per-test budget. */
85
+ const CASE_ROOTS = new Set(["test", "it"]);
86
+
87
+ /**
88
+ * The hooks that accept a budget of their own.
89
+ *
90
+ * Included because a hook that is killed is reported as `(unnamed)` in
91
+ * bun's JUnit output — MEASURED on 1.3.14 — so work moved into a hook with
92
+ * a budget of its own is as far out of `timeoutProximityViolations`'s reach
93
+ * as a case with one. Same AST rule, different root set; leaving them out
94
+ * would be a gap for the sake of a shorter list.
95
+ */
96
+ const HOOK_ROOTS = new Set(["beforeAll", "beforeEach", "afterAll", "afterEach"]);
97
+
98
+ /** The bun:test call that raises the default budget for a whole file. */
99
+ const DEFAULT_TIMEOUT_FN = "setDefaultTimeout";
100
+
101
+ /** How a budget was raised. */
102
+ export type TimeoutKind =
103
+ /** A third argument to a `test`/`it` call: `}, 60_000)`, `}, { timeout: 60_000 })`. */
104
+ | "per-test"
105
+ /** A second argument to a `beforeAll`/`afterEach`/… call. */
106
+ | "hook"
107
+ /** A `setDefaultTimeout(…)` call, which raises it for every case in the file. */
108
+ | "file-default";
109
+
110
+ /** One construct that gives a case a budget other than the declared one. */
111
+ export interface TimeoutDeclaration {
112
+ kind: TimeoutKind;
113
+ /**
114
+ * The source text of the declaration, as it appears in the TRANSPILED
115
+ * module. Reported rather than evaluated — see the module comment.
116
+ */
117
+ expression: string;
118
+ /** The case name when it is a string literal, else `null`. */
119
+ caseName: string | null;
120
+ }
121
+
122
+ function literalString(node: unknown): string | null {
123
+ const n = node as AstNode | undefined;
124
+ if (n?.type === "Literal" && typeof n.value === "string") return n.value;
125
+ return null;
126
+ }
127
+
128
+ /**
129
+ * Every per-test and file-default budget declaration in `source`, in document
130
+ * order. `null` when the source does not parse.
131
+ */
132
+ export function perTestTimeoutDeclarations(source: string): TimeoutDeclaration[] | null {
133
+ const parsed = parseTsModule(source);
134
+ if (parsed === null) return null;
135
+ const bindings = importBindings(parsed.tree);
136
+
137
+ /**
138
+ * The bun:test name a callee resolves to, following import aliases.
139
+ *
140
+ * Matching the LOCAL identifier was the alias hole this closes:
141
+ * `import { test as t } from "bun:test"` made the detector report clean on
142
+ * its own subject (MEASURED: 0 declarations for `t("slow", () => {}, 60_000)`).
143
+ *
144
+ * Three cases, in order:
145
+ * - the local name is bound by a bun:test import → its EXPORTED name,
146
+ * so `t` resolves to `test`;
147
+ * - the local name is a bun:test NAMESPACE binding → the property called
148
+ * on it, so `bt.test(…)` resolves to `test`;
149
+ * - the local name is bound by some OTHER import → `null`, because
150
+ * `import { test } from "./helpers"` is not bun:test's;
151
+ * - otherwise the bare name, which is how bun's injected globals work in
152
+ * a file that imports nothing from bun:test.
153
+ */
154
+ function resolved(callee: unknown): string | null {
155
+ const root = calleeRoot(callee);
156
+ if (root === null) return null;
157
+ const binding = bindings.get(root);
158
+ if (binding === undefined) return root;
159
+ if (binding.module !== "bun:test") return null;
160
+ if (binding.imported === "*") return rootProperty(callee);
161
+ return binding.imported;
162
+ }
163
+
164
+ const out: TimeoutDeclaration[] = [];
165
+ for (const node of walkNodes(parsed.tree)) {
166
+ if (node.type !== "CallExpression") continue;
167
+ const args = node.arguments as AstNode[] | undefined;
168
+ if (!Array.isArray(args)) continue;
169
+ const root = resolved(node.callee);
170
+
171
+ if (root === DEFAULT_TIMEOUT_FN && args.length >= 1) {
172
+ out.push({
173
+ kind: "file-default",
174
+ expression: parsed.js.slice(args[0]!.start, args[0]!.end),
175
+ caseName: null,
176
+ });
177
+ continue;
178
+ }
179
+
180
+ // A per-test budget is the THIRD argument of a call rooted at test/it.
181
+ // Rooted, so `test.only`, `test.skip`, `test.if(x)` and
182
+ // `test.each([…])(…)` are all the same question rather than a list of
183
+ // spellings. `test.each([1])` on its own has one argument and is not a
184
+ // case declaration, so the arity check excludes it without naming it.
185
+ if (root !== null && CASE_ROOTS.has(root) && args.length >= 3) {
186
+ const arg = args[2]!;
187
+ out.push({
188
+ kind: "per-test",
189
+ expression: parsed.js.slice(arg.start, arg.end),
190
+ caseName: literalString(args[0]),
191
+ });
192
+ continue;
193
+ }
194
+
195
+ // A hook takes its budget as the SECOND argument, there being no name.
196
+ if (root !== null && HOOK_ROOTS.has(root) && args.length >= 2) {
197
+ const arg = args[1]!;
198
+ out.push({
199
+ kind: "hook",
200
+ expression: parsed.js.slice(arg.start, arg.end),
201
+ caseName: root,
202
+ });
203
+ }
204
+ }
205
+ return out;
206
+ }
207
+
208
+ /** One line per declaration, for a failure message that names the repair. */
209
+ export function describeTimeoutDeclarations(found: TimeoutDeclaration[]): string {
210
+ return found
211
+ .map(d =>
212
+ d.kind === "file-default"
213
+ ? `setDefaultTimeout(${d.expression}) raises the budget for every case in the file`
214
+ : d.kind === "hook"
215
+ ? `a ${d.caseName} hook declares a budget of ${d.expression}, and a killed hook is reported as \`(unnamed)\``
216
+ : `${d.caseName === null ? "a case" : `"${d.caseName}"`} declares a per-test budget of ${d.expression}`,
217
+ )
218
+ .join("\n");
219
+ }
@@ -0,0 +1,151 @@
1
+ /**
2
+ * Does a decomposition's plan allocate every file discovery said the issue
3
+ * touches? (#751)
4
+ *
5
+ * `workflows/ship.js` interpolates `discovery.filesToModify` into the
6
+ * to-issues prompt as "Files to modify" and then validates the answer two
7
+ * ways: no sub-issue may claim an out-of-scope file, and no two sub-issues
8
+ * may claim the same one. **Nothing compared the UNION of the sub-issues'
9
+ * `filesToModify` against the list it had just asked about.** The prompt
10
+ * asks; nothing checked that the answer covers it — the same gap the comment
11
+ * beside `denylistViolations` names for the deny-list and was never extended
12
+ * past.
13
+ *
14
+ * On the consumer run that motivated #751, the file the issue was *about* was
15
+ * claimed by no sub-issue, edited by two worktrees, and the run reached
16
+ * Commit before SC-413 refused with *"no worktree claimed that file"* —
17
+ * 2h06m and 2.03M subagent tokens of correct work ending `SHIP_FAILED` /
18
+ * `NO_PR`. The run is named on the issue; naming a consumer repository in
19
+ * harness source is what `test/anti.test.ts` SC-A1 refuses, and it is right
20
+ * to — this module ships to every project rungate scaffolds. That
21
+ * refusal is correct and is not loosened here; widening it is the documented
22
+ * cheapest wrong fix for this family (`.claude/rules/checks-must-be-able-to-fail.md`,
23
+ * the #627 section). This moves the detection to plan time, where it costs
24
+ * nothing.
25
+ *
26
+ * ## The decision #751 asked to be made out loud
27
+ *
28
+ * Three candidates, all precedented in `ship.js`. **Option 1: refuse the
29
+ * parallel plan and fall back to single-agent implement** — the same branch
30
+ * `hasOverlap` already takes, one line away.
31
+ *
32
+ * - **Not auto-claim (option 2).** The decomposer had the file list and chose
33
+ * not to allocate it. Assigning the file by a heuristic — same directory,
34
+ * first sub-issue, largest — hands work to an agent whose brief never
35
+ * mentions it, and whose claim audit then PASSES while the allocation is
36
+ * wrong. It converts a loud, early, correct refusal into a quiet
37
+ * misallocation, which is strictly worse than the state being fixed.
38
+ * - **Not warn-and-proceed (option 3).** That is the status quo, and the
39
+ * status quo is a run spending its whole agent budget to discover at Commit
40
+ * what was knowable before the first agent spawned.
41
+ * - **Option 1 loses nothing.** The single-agent path may modify every file,
42
+ * so the work still ships; what is given up is parallelism, which is an
43
+ * optimisation and not a requirement. The failure is moved from the end of
44
+ * the run to the start of it.
45
+ *
46
+ * ## An empty discovery list is UNMEASURED, not "fully covered"
47
+ *
48
+ * The union of nothing covers nothing perfectly — the third shape, and #751
49
+ * names it as the cheapest wrong fix for this check specifically: *treat an
50
+ * absent or empty `discovery.filesToModify` as satisfied*. It silences every
51
+ * synthetic fixture and leaves exactly the #1585 case uncaught, because the
52
+ * thing that needs covering is a list nobody is obliged to produce.
53
+ *
54
+ * **That branch is unreachable from today's call site, and saying so is the
55
+ * point** (#492). `ship.js` only decomposes when
56
+ * `discovery.sizing === 'M' && (discovery.filesToModify || []).length >= 3`,
57
+ * so every live plan arrives with at least three files and the empty reading
58
+ * cannot occur. It is reported anyway, because the precondition is one `if`
59
+ * in another function that nothing holds still, and a branch that only exists
60
+ * while an unrelated guard keeps its shape is a branch that goes silently
61
+ * wrong the day that guard moves.
62
+ */
63
+
64
+ import { normalisePath } from "./scope-denylist";
65
+
66
+ export interface PlanSubIssue {
67
+ title?: string;
68
+ filesToModify?: string[];
69
+ }
70
+
71
+ export interface PlanCoverageReading {
72
+ reading: "MEASURED" | "UNMEASURED";
73
+ unmeasuredReasons: string[];
74
+ /** Discovered files no sub-issue claims, in the spelling discovery used. */
75
+ uncovered: string[];
76
+ /** How many files were compared, so a PASS can report its own coverage. */
77
+ discovered: number;
78
+ /** How many distinct files the plan allocates, including any not discovered. */
79
+ claimed: number;
80
+ }
81
+
82
+ /**
83
+ * Compare the plan's union against what discovery found.
84
+ *
85
+ * Path equality goes through `normalisePath`, the same binding the deny-list
86
+ * uses, so `./lib/a.ts` and `lib/a.ts` are one file here exactly as they are
87
+ * there. A second notion of "same path" in the same workflow would agree on
88
+ * every input anyone has and diverge on the one that matters.
89
+ */
90
+ export function planCoverage(
91
+ discoveryFiles: string[] | undefined | null,
92
+ subIssues: PlanSubIssue[] | undefined | null,
93
+ ): PlanCoverageReading {
94
+ const discovered = (discoveryFiles || []).map(f => String(f)).filter(f => f.trim() !== "");
95
+ const subs = subIssues || [];
96
+
97
+ const claimedSet = new Set<string>();
98
+ for (const s of subs) {
99
+ for (const f of s.filesToModify || []) {
100
+ const n = normalisePath(f);
101
+ if (n !== "") claimedSet.add(n);
102
+ }
103
+ }
104
+
105
+ const reasons: string[] = [];
106
+ if (discovered.length === 0) {
107
+ reasons.push(
108
+ "discovery named no files to modify, so there is nothing to compare the plan against. " +
109
+ 'The union of an empty list is covered by any plan at all, which is not "the plan is ' +
110
+ 'complete" — it is "nobody looked" (#751).',
111
+ );
112
+ }
113
+ if (subs.length === 0) {
114
+ reasons.push(
115
+ "the decomposition produced no sub-issues, so there is no plan to compare. An empty " +
116
+ "plan agrees with every discovery.",
117
+ );
118
+ }
119
+
120
+ return {
121
+ reading: reasons.length === 0 ? "MEASURED" : "UNMEASURED",
122
+ unmeasuredReasons: reasons,
123
+ uncovered:
124
+ reasons.length === 0 ? discovered.filter(f => !claimedSet.has(normalisePath(f))) : [],
125
+ discovered: discovered.length,
126
+ claimed: claimedSet.size,
127
+ };
128
+ }
129
+
130
+ /**
131
+ * The sentence `ship.js` logs when the plan must not be used, or `null`.
132
+ *
133
+ * One binding so there is one thing to mutate, and so the refusal and the
134
+ * reading cannot disagree about whether a plan is usable. An UNMEASURED
135
+ * reading refuses too: a plan nobody could check is not a plan that passed.
136
+ */
137
+ export function planCoverageRefusal(r: PlanCoverageReading): string | null {
138
+ if (r.reading === "UNMEASURED") {
139
+ return (
140
+ `PLAN COVERAGE UNMEASURED: ${r.unmeasuredReasons.join(" ")} ` +
141
+ `Falling back to single-agent implement, which may touch any file.`
142
+ );
143
+ }
144
+ if (r.uncovered.length === 0) return null;
145
+ return (
146
+ `PLAN COVERAGE: ${r.uncovered.length} of ${r.discovered} discovered file(s) are claimed by ` +
147
+ `no sub-issue — ${r.uncovered.join(", ")}. A file nobody claims is a file two worktrees ` +
148
+ `may both edit, and the SC-413 claim audit refuses it at Commit after the whole agent ` +
149
+ `budget is spent (#751). Falling back to single-agent implement.`
150
+ );
151
+ }
@@ -94,12 +94,32 @@ export interface DetectExistingPROptions {
94
94
  * Does this text reference issue N? One binding, used by both detectors
95
95
  * and by anything that reads a PR body (#223).
96
96
  *
97
- * The bound is on DIGITS, not on a `#`: the three places this has to match
98
- * spell the reference three ways — `Closes #209` in a PR body, `fix(#209):`
99
- * in the subject ship.js writes, and `209-deep-modules` in a branch name.
100
- * The digit bound is what stops `515` matching `5150`, and it is the whole
101
- * of the correctness condition; the `#` is decoration that two of the three
102
- * forms do not have.
97
+ * ## This is the IDENTIFIER form. Prose has its own binding below.
98
+ *
99
+ * The bound is on DIGITS and not on a `#`, which is right for the thing this
100
+ * now reads and ONLY that thing: a branch name. `209-deep-modules` carries no
101
+ * `#` and never will, because a ref is a structured identifier whose whole
102
+ * content is chosen to name the work. The digit bound is what stops `515`
103
+ * matching `5150`.
104
+ *
105
+ * It used to read PR titles and bodies too, and that was wrong in a way no
106
+ * amount of tightening the digit bound could reach (#687). A body is FREE
107
+ * TEXT. Ship run `wf_4b5a4d83-fa4` for issue #631 refused with
108
+ * `PRIOR_WORK_OPEN_PR — Issue #631 already has open PR #686`; PR #686 is
109
+ * #644's work, and what matched was line 42 of its body:
110
+ *
111
+ * and projectRoot is on rungate/run-631 ...
112
+ *
113
+ * a sample refusal message quoted as evidence. So a PR that merely MENTIONS
114
+ * another issue's branch name became that issue's prior work, and that issue
115
+ * could not be shipped until the PR closed. Not rare prose — this repository
116
+ * writes cross-session handoff notes, quoted refusals and "adjacent to #631"
117
+ * paragraphs into PR bodies deliberately.
118
+ *
119
+ * `detectExistingPR`'s own comment names the hazard two lines above the call:
120
+ * matching `pr.number` "is a false positive on the one path where a false
121
+ * positive stops a correct run from ever starting". That is exactly what a
122
+ * bare-number body reading is, and it sat beneath that sentence.
103
123
  *
104
124
  * Total over non-strings. It runs over `pr.body`, which GitHub returns as
105
125
  * `null` for a PR opened with an empty body, and a throw on that path is a
@@ -147,6 +167,147 @@ export function issueReference(issueNumber: number): (text: unknown) => boolean
147
167
  return (text: unknown) => typeof text === 'string' && pattern.test(text)
148
168
  }
149
169
 
170
+ /**
171
+ * Does this PROSE reference issue N? The second binding, and the narrow one.
172
+ *
173
+ * A PR title, a PR body and a commit subject are sentences people write. A
174
+ * bare number in one of them is a number, not a claim — it is a line count, a
175
+ * SHA prefix, a quoted branch name, a port. What makes it a REFERENCE is the
176
+ * `#`, and every form this repository actually produces in prose has one:
177
+ * `Closes #209` and `Fixes #209`, which ship.js writes into every body it
178
+ * opens, and `fix(#209):`, which it writes into every subject it commits.
179
+ *
180
+ * So the `#` is not decoration here. It is the entire difference between the
181
+ * two populations, and requiring it loses nothing: a PR with no `#` reference
182
+ * anywhere in its prose is still found through its HEAD REF by
183
+ * `issueReference` above, which is the identifier reading and keeps its bare
184
+ * number. Two readings, two bounds, named separately — because the fields
185
+ * have different grammars and one pattern over all three cannot be right for
186
+ * all three.
187
+ *
188
+ * `#209\b` rejects `rungate/run-631` for 631 (no `#`), rejects `#2091` (`1`
189
+ * is a word character, so there is no boundary) and rejects `#1209` (the
190
+ * character before `209` is `1`, not `#`). All asserted in
191
+ * `test/prior-branch-reference.test.ts` rather than trusted to this comment.
192
+ *
193
+ * Total over non-strings, for the same reason as above: GitHub returns `null`
194
+ * for the body of a PR opened without one.
195
+ */
196
+ export function issueProseReference(issueNumber: number): (text: unknown) => boolean {
197
+ if (!Number.isSafeInteger(issueNumber) || issueNumber < 0) {
198
+ throw new TypeError(
199
+ `issueProseReference needs a non-negative integer issue number, got ${JSON.stringify(issueNumber)}`,
200
+ )
201
+ }
202
+ const pattern = new RegExp(`#${issueNumber}\\b`)
203
+ return (text: unknown) => typeof text === 'string' && pattern.test(text)
204
+ }
205
+
206
+ /**
207
+ * Does this PR BODY declare that it closes issue N? The third binding, and
208
+ * the narrowest (#887).
209
+ *
210
+ * `issueProseReference` above requires a `#`, which is the right bound for a
211
+ * COMMIT SUBJECT and far too wide for a PR body. Citing another issue in a
212
+ * body is not an edge case in these repositories, it is the house style:
213
+ * measured over this repository's 120 most recent PRs, 103 of them cite
214
+ * issues they do not close, 417 citations in all. Treating any of those as
215
+ * prior work stops a correct run from ever starting, and it fires late --
216
+ * A consumer run for issue #1624 refused after 9 agents, 716k tokens and
217
+ * naming a PR with zero file overlap.
218
+ *
219
+ * The signal that separates the populations already exists and the harness
220
+ * already writes it: `Fixes #${ISSUE}`, which ship.js puts in every body it
221
+ * opens, and which is also what GitHub itself reads to link a PR to an issue.
222
+ *
223
+ * Two deliberate choices, both of which cost something if taken the other
224
+ * way:
225
+ *
226
+ * - **Every GitHub variant, case-insensitively.** `close`/`closes`/`closed`,
227
+ * `fix`/`fixes`/`fixed`, `resolve`/`resolves`/`resolved`. Matching only
228
+ * ship.js's own spelling would stop detecting hand-written PRs, and the
229
+ * issue would go back to being shipped twice -- #209, the defect this
230
+ * module exists to prevent.
231
+ * - **A backtick does not disarm it.** GitHub closes `#N` from a quoted
232
+ * `` `Fixes #N` `` in a body, so a detector that skipped code spans would
233
+ * disagree with GitHub about which PR closes what. Match the same text
234
+ * GitHub does, including the false positive GitHub itself has.
235
+ *
236
+ * There is deliberately NO fallback to the bare reading when no closing
237
+ * keyword is found. A fallback would reintroduce #887 exactly; "no closing
238
+ * keyword in any open body" reads as no prior work, which is the true answer
239
+ * for #1624 today. A PR whose body says nothing is still found through its
240
+ * head ref and its subject.
241
+ *
242
+ * Total over non-strings: GitHub returns `null` for a body opened without one.
243
+ */
244
+ export function issueClosingReference(issueNumber: number): (text: unknown) => boolean {
245
+ if (!Number.isSafeInteger(issueNumber) || issueNumber < 0) {
246
+ throw new TypeError(
247
+ `issueClosingReference needs a non-negative integer issue number, got ${JSON.stringify(issueNumber)}`,
248
+ )
249
+ }
250
+ // The forms GitHub itself honours, not just the one ship.js writes. A
251
+ // detector NARROWER than GitHub's grammar fails in the dangerous
252
+ // direction: a PR saying `Fixes: #209` or `Closes GH-209` really does
253
+ // close the issue, this would not see it, and the issue gets shipped
254
+ // twice -- #209, which is the defect the module exists to prevent. Found
255
+ // by security review of the first draft, which required a bare `#`.
256
+ //
257
+ // keyword, optional colon, whitespace, then one of:
258
+ // #209 GH-209 https://github.com/<owner>/<repo>/issues/209
259
+ const ref = `(?:#|GH-|https?://github\\.com/[^/\\s]+/[^/\\s]+/issues/)${issueNumber}`
260
+ const pattern = new RegExp(
261
+ `\\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\\s*:?\\s+${ref}\\b`,
262
+ 'i',
263
+ )
264
+ return (text: unknown) => typeof text === 'string' && pattern.test(text)
265
+ }
266
+
267
+ /**
268
+ * Does this PR TITLE name issue N as its SUBJECT? The fourth binding (#887).
269
+ *
270
+ * A title is one sentence, so the body's problem is smaller here but it is
271
+ * the same problem: measured over this repository's 120 most recent PRs, 107
272
+ * titles carry a `#N` and 6 carry more than one -- `docs(#837): record the
273
+ * #836 battery` is #837's PR, and under a whole-title reading it was also
274
+ * #836's.
275
+ *
276
+ * What separates them is POSITION, not spelling. The conventional-commit
277
+ * subject -- everything before the first colon -- is where this repository
278
+ * writes the issue a change is FOR, every time: `fix(#209):`, `#795:`,
279
+ * `#640 + #644:`. A number after the colon is prose.
280
+ *
281
+ * A title with no colon in its first 40 characters declares no subject issue
282
+ * and matches nothing. That is deliberately not a fallback to the whole
283
+ * string: a fallback is how the body reading got as wide as it did, and the
284
+ * honest answer for a title that does not name an issue in its subject is
285
+ * that it does not say. The PR is still found by head ref or by body.
286
+ */
287
+ export function issueSubjectReference(issueNumber: number): (text: unknown) => boolean {
288
+ if (!Number.isSafeInteger(issueNumber) || issueNumber < 0) {
289
+ throw new TypeError(
290
+ `issueSubjectReference needs a non-negative integer issue number, got ${JSON.stringify(issueNumber)}`,
291
+ )
292
+ }
293
+ const pattern = new RegExp(`#${issueNumber}\\b`)
294
+ return (text: unknown) => {
295
+ if (typeof text !== 'string') return false
296
+ const colon = text.indexOf(':')
297
+ if (colon < 0 || colon > SUBJECT_PREFIX_LIMIT) return false
298
+ return pattern.test(text.slice(0, colon))
299
+ }
300
+ }
301
+
302
+ /**
303
+ * How far into a title the conventional-commit colon may sit (#887).
304
+ *
305
+ * Long enough for `docs(#837)` and `#640 + #644`, short enough that a colon
306
+ * in an ordinary sentence -- "the reading says: nothing" -- does not turn the
307
+ * first half of a prose title into a subject.
308
+ */
309
+ const SUBJECT_PREFIX_LIMIT = 40
310
+
150
311
  function git(args: string[], cwd: string, timeout = 15_000) {
151
312
  return spawnSync('git', args, { cwd, encoding: 'utf-8', timeout })
152
313
  }
@@ -332,9 +493,13 @@ export async function detectPriorBranch(opts: DetectOptions): Promise<PriorBranc
332
493
  // becomes findable. Scratch refs are still excluded upstream by
333
494
  // `isHarnessScratchRef`: a subject match widens which REAL branches are
334
495
  // found, it does not readmit the ones #185 ruled out.
496
+ // Two readings, because a ref and a subject have different grammars. The
497
+ // ref is an identifier and carries the bare number; the subject is a
498
+ // sentence and must carry `#` (#687).
335
499
  const refs = issueReference(issueNumber)
500
+ const prose = issueProseReference(issueNumber)
336
501
  const matches = listCandidateRefs(projectRoot)
337
- .filter(c => refs(c.branch) || refs(c.subject))
502
+ .filter(c => refs(c.branch) || prose(c.subject))
338
503
  if (matches.length === 0) return null
339
504
 
340
505
  // Most recent wins; a local head breaks a tie with its origin twin.
@@ -400,6 +565,23 @@ const PR_PAGE_SIZE = 100
400
565
  * says which issue the PR is for. A head-ref-only reading could not match the
401
566
  * PRs this workflow opens.
402
567
  *
568
+ * Three fields, three grammars, three readings — see `issueReference`,
569
+ * `issueSubjectReference` and `issueClosingReference`. One pattern over all
570
+ * three has now been wrong twice:
571
+ *
572
+ * - **#687**: a bare-number reading matched `rungate/run-631` quoted as
573
+ * evidence in a body, and issue 631's run refused. Fixed by requiring `#`.
574
+ * - **#887**: `#N` is still what a CITATION looks like. A consumer run for
575
+ * issue #1624 refused after 9 agents, 716k tokens and 26 minutes, naming a PR
576
+ * with zero file overlap that mentioned it in two sentences of prose —
577
+ * and three other open PRs cited it too, so removing one would have handed
578
+ * the refusal to the next. The body must now DECLARE that it closes the
579
+ * issue, and the title is read at its subject rather than whole.
580
+ *
581
+ * Both narrowings cost nothing in recall because the three readings are a
582
+ * disjunction over fields that rarely all stay silent: measured over this
583
+ * repository's 120 most recent PRs, the new rule loses no true pair.
584
+ *
403
585
  * Returns `null` for "no open PR", a PR for "this one", and `{unreadable}`
404
586
  * for "could not look". Never conflate the first and the last.
405
587
  */
@@ -423,10 +605,21 @@ export async function detectExistingPR(opts: DetectExistingPROptions | DetectExi
423
605
  // matching it made PR #209 the prior work for issue #209 whatever it was
424
606
  // about, which is a false positive on the one path where a false positive
425
607
  // stops a correct run from ever starting.
608
+ // THREE readings, because the three fields have three grammars and one
609
+ // pattern over all of them has now been wrong twice (#687, #887).
426
610
  const refs = issueReference(issueNumber)
611
+ const subject = issueSubjectReference(issueNumber)
612
+ const closes = issueClosingReference(issueNumber)
427
613
  const match = prs.find((pr: any) => {
428
614
  const headRef = pr?.head?.ref || pr?.headRefName || ''
429
- return refs(headRef) || refs(pr?.title) || refs(pr?.body)
615
+ // - the HEAD REF is an identifier: bare number, unchanged.
616
+ // - the TITLE is read at its conventional-commit SUBJECT, before the
617
+ // first colon, which is where this repository names the issue a change
618
+ // is FOR. `docs(#837): record the #836 battery` is 837's, not 836's.
619
+ // - the BODY must DECLARE that it closes the issue. A bare `#N` in a
620
+ // body is a citation, and 103 of this repository's 120 most recent PRs
621
+ // carry 417 of them.
622
+ return refs(headRef) || subject(pr?.title) || closes(pr?.body)
430
623
  })
431
624
 
432
625
  if (!match) return null