rungate 0.8.13 → 0.8.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/README.md +182 -0
  2. package/gates/.gate-salt +1 -1
  3. package/hooks/HarnessAFKGate.hook.ts +5 -1
  4. package/hooks/HookCurrency.hook.ts +11 -8
  5. package/hooks/MergeGuard.hook.ts +7 -1
  6. package/hooks/StaleTTLCleanup.hook.ts +4 -4
  7. package/hooks/VerifyPhaseLock.hook.ts +3 -3
  8. package/hooks/lib/findWorkflow.ts +3 -2
  9. package/hooks/lib/paths.ts +14 -2
  10. package/hooks/lib/utils.ts +23 -3
  11. package/lib/active-milestone.ts +50 -0
  12. package/lib/ai-review-rounds.ts +99 -0
  13. package/lib/ai-review-suppression.ts +200 -21
  14. package/lib/bash-write-guard.ts +397 -23
  15. package/lib/board-flow.ts +280 -0
  16. package/lib/board-lane-health.ts +578 -0
  17. package/lib/board-mirror.ts +136 -39
  18. package/lib/board-ready-fanout.ts +297 -14
  19. package/lib/board-ready-rule.ts +1211 -0
  20. package/lib/board-throughput.ts +136 -0
  21. package/lib/board-walkthrough.ts +240 -0
  22. package/lib/body-evidence.ts +203 -0
  23. package/lib/branch-protection.ts +399 -9
  24. package/lib/bun-version.ts +36 -0
  25. package/lib/cli-commands.ts +75 -4
  26. package/lib/closing-reference-audit.ts +307 -6
  27. package/lib/config-loader.ts +254 -25
  28. package/lib/config-readers.ts +170 -10
  29. package/lib/config-trackable.ts +96 -57
  30. package/lib/conformity.ts +121 -7
  31. package/lib/create-sc.ts +25 -2
  32. package/lib/derived-spec.ts +21 -9
  33. package/lib/filing-compliance.ts +367 -0
  34. package/lib/filing-plan.ts +47 -21
  35. package/lib/finding-arbiter.ts +79 -5
  36. package/lib/finding-jury.ts +43 -4
  37. package/lib/finding-promotion.ts +1123 -0
  38. package/lib/generators/agents-md.ts +149 -0
  39. package/lib/git-isolation.ts +137 -1
  40. package/lib/github-api-base.ts +66 -0
  41. package/lib/github.ts +194 -9
  42. package/lib/graphql-cursor.ts +80 -0
  43. package/lib/hook-scopes.ts +78 -0
  44. package/lib/issue-create-override.ts +415 -3
  45. package/lib/issue-decomposition.ts +124 -7
  46. package/lib/issue-extraction.ts +9 -7
  47. package/lib/issue-file-overlap.ts +373 -0
  48. package/lib/issue-filing-gate.ts +1109 -52
  49. package/lib/issue-repair.ts +90 -9
  50. package/lib/issue-shape.ts +199 -0
  51. package/lib/live-issues.ts +31 -2
  52. package/lib/local-work.ts +423 -0
  53. package/lib/markdown-fence.ts +134 -0
  54. package/lib/milestone-title.ts +46 -0
  55. package/lib/scaffold/ai-review-findings.ts +148 -3
  56. package/lib/scaffold/ai-review-step.ts +65 -5
  57. package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
  58. package/lib/scaffold/steps.ts +115 -9
  59. package/lib/source-census.ts +108 -0
  60. package/lib/spec-deps.ts +55 -11
  61. package/lib/spec-placement.ts +203 -13
  62. package/lib/spec-registry.ts +75 -16
  63. package/lib/spec-source.ts +609 -0
  64. package/lib/spec-write-sweep.ts +4 -0
  65. package/lib/stage-ladder.ts +896 -3
  66. package/lib/state-claim-readings.ts +252 -0
  67. package/lib/success-doc.ts +7 -6
  68. package/lib/test-command-positions.ts +135 -1
  69. package/lib/work-status.ts +551 -0
  70. package/lib/worktree-repo.ts +14 -2
  71. package/package.json +7 -1
  72. package/scripts/ai-review-findings.ts +8 -13
  73. package/scripts/ai-review-threads.ts +16 -17
  74. package/scripts/audit-closing-references.ts +330 -0
  75. package/scripts/audit-specs.ts +59 -103
  76. package/scripts/board-conformance.ts +747 -40
  77. package/scripts/board-mirror.ts +594 -13
  78. package/scripts/board-ready.ts +979 -0
  79. package/scripts/board-snapshot.ts +464 -12
  80. package/scripts/claim-files.ts +578 -0
  81. package/scripts/criterion-inventory.ts +526 -50
  82. package/scripts/finding-promotion.ts +547 -0
  83. package/scripts/generate-code-map.ts +1 -1
  84. package/scripts/plan-issues.ts +279 -40
  85. package/scripts/plan-spec.ts +105 -3
  86. package/scripts/sync-sc-status.ts +147 -7
  87. package/scripts/worktree-census.ts +958 -0
  88. package/scripts/worktree-sweep.ts +269 -0
@@ -14,8 +14,11 @@
14
14
  * reformat moves — measured on #1616 as 11 threads for 3 findings. A thread
15
15
  * is GitHub's own answer to the same question, so AC-1 moved the gate onto
16
16
  * it: `priorKeysFrom` reads the list the carry step fetched and nothing else.
17
- * The ledger reader is kept as `ledgerPriorKeysFrom`, called by no production
18
- * path, until AC-5 stops writing the snapshot it parses.
17
+ * The ledger reader that used to sit beside it is GONE — AC-5 stopped writing
18
+ * the snapshot it parsed and `ledgerPriorKeysFrom`, `readSnapshot` and
19
+ * `carryStateOf` were deleted with it. `test/ai-review-suppression.test.ts`
20
+ * (AS-0b) asserts all three stay absent, so this paragraph cannot go stale
21
+ * again in the other direction.
19
22
  *
20
23
  * ## Why the prior state arrives as a file and not as a fetch
21
24
  *
@@ -56,7 +59,10 @@ import { isAbsolute, resolve, sep } from "path";
56
59
 
57
60
  import {
58
61
  AI_REVIEW_PRIOR_MEASURED,
62
+ anchorOnlyKey,
63
+ anchorTextOf,
59
64
  carryKey,
65
+ normaliseLineText,
60
66
  priorFindings,
61
67
  readLedger,
62
68
  type ReviewFinding,
@@ -81,6 +87,15 @@ export interface SuppressionInputs {
81
87
  threads: string | null;
82
88
  /** The text at a finding's cited line NOW, or `undefined`. */
83
89
  lineTextFor: (finding: ReviewFinding) => string | undefined;
90
+ /**
91
+ * How many lines of `file` carry `normalisedText`, or `undefined` when the
92
+ * file could not be read (#1861).
93
+ *
94
+ * Optional, and absent means the anchor rule never fires. A caller that has
95
+ * not been rewired keeps the behaviour it had before the rule existed,
96
+ * which is the direction this module is allowed to be wrong in.
97
+ */
98
+ anchorOccurrences?: (file: string, normalisedText: string) => number | undefined;
84
99
  }
85
100
 
86
101
  /** A prior set that was established, or the sentence saying it was not. */
@@ -144,6 +159,35 @@ export function priorKeysFrom(threads: string | null): PriorKeys {
144
159
  return { status: "MEASURED", keys: reading.threads.map(t => t.key) };
145
160
  }
146
161
 
162
+ /**
163
+ * Does this anchor identify ONE line of the file it names (#1861 round 3)?
164
+ *
165
+ * The screen the round-3 review asked for, and deliberately NOT the one it
166
+ * suggested. A minimum anchor length was the obvious fix and the measurement
167
+ * refuses it: of the five ambiguous anchors in the 60-finding corpus, four
168
+ * normalise to over twenty characters and the worst is forty-five. Length
169
+ * does not predict distinctiveness; counting the occurrences measures it.
170
+ *
171
+ * Every reading that is not exactly `1` answers `false`, including every way
172
+ * of failing to read. A caller with no counter, a file that is not there, a
173
+ * key whose text cannot be recovered and a path with two matching lines all
174
+ * mean the same thing here: this anchor cannot be shown to name one place,
175
+ * so nothing is suppressed on it.
176
+ */
177
+ function uniqueAnchor(
178
+ inputs: SuppressionInputs,
179
+ finding: ReviewFinding,
180
+ anchorKey: string,
181
+ ): boolean {
182
+ const count = inputs.anchorOccurrences;
183
+ if (count === undefined) return false;
184
+ const text = anchorTextOf(anchorKey);
185
+ if (text === null || text === "") return false;
186
+ const file = finding.file;
187
+ if (typeof file !== "string" || file === "") return false;
188
+ return count(file, text) === 1;
189
+ }
190
+
147
191
  /**
148
192
  * Build the gate the adjudicator is handed, or `null` when nothing is plumbed.
149
193
  *
@@ -165,26 +209,126 @@ export function aiReviewSuppressionGate(inputs: SuppressionInputs): AiReviewSupp
165
209
  // `AiReviewJuryGate`'s docblock names. `carryKey` is the shared rule and
166
210
  // the within-round half is the growing `seen` set, exactly as
167
211
  // `suppressRepeats` spells it.
212
+ // The keys an EARLIER round posted, kept apart from the growing set
213
+ // below so the two sentences can say which of them matched (#1861 round
214
+ // 3). They used to be one set, and the message said "an earlier round"
215
+ // for a duplicate that came from this round's own payload.
216
+ const priorSet = new Set<string>(prior.keys);
168
217
  const seen = new Set<string>(prior.keys);
218
+ // #1168. The same prior set read with the wording dropped. Built from the
219
+ // SAME strings rather than from the threads a second time: two derivations
220
+ // of one identity are two deciders that agree, and a mutation of either
221
+ // leaves the other holding every case up.
222
+ const anchors = new Set<string>();
223
+ for (const k of prior.keys) {
224
+ const a = anchorOnlyKey(k);
225
+ if (a !== null) anchors.add(a);
226
+ }
169
227
  const repeat = candidates.map(c => {
170
228
  const key = carryKey(c, inputs.lineTextFor(c as ReviewFinding));
171
229
  // Unkeyable CARRIES. It cannot be shown to be a repeat, and the
172
230
  // direction this is allowed to be wrong in is toward reporting.
173
231
  if (key === null) return null;
174
- if (!seen.has(key)) {
175
- seen.add(key);
176
- return null;
177
- }
178
232
  const f = c as ReviewFinding;
179
- return (
180
- `${String(f.file ?? "(no file)")}: ${String(f.summary ?? "(no summary)")} — already ` +
181
- `raised on an earlier round of this pull request, so it is not raised again`
182
- );
233
+ const where = String(f.file ?? "(no file)");
234
+ const what = String(f.summary ?? "(no summary)");
235
+ if (seen.has(key)) {
236
+ // WHICH set matched is the difference between two true sentences and
237
+ // one false one. `priorSet` is fixed at the prior round's keys;
238
+ // anything else in `seen` was added by a sibling a few lines below.
239
+ return priorSet.has(key)
240
+ ? `${where}: ${what} — already ` +
241
+ `raised on an earlier round of this pull request, so it is not raised again`
242
+ : `${where}: ${what} — listed more than once in this round's own ` +
243
+ `report, word for word, so it is reported once`;
244
+ }
245
+ const anchor = anchorOnlyKey(key);
246
+ // The wording differs and the anchor does not. Measured at #1168: of
247
+ // eight such collisions across 25 merged pull requests, eight were the
248
+ // same defect restated and none was a new finding at an old line. This
249
+ // is a JUDGEMENT rather than an identity, so it says so — the sentence
250
+ // is what lets a reader appeal it.
251
+ //
252
+ // And it fires only on an anchor that identifies ONE line of the file.
253
+ // `}` and `return null;` key the same anchor wherever they recur, so a
254
+ // new finding at a second occurrence would be suppressed as a
255
+ // restatement of a defect somewhere else entirely. Measured at #1861:
256
+ // 5 of 60 anchors in the corpus — 8.3% — recur in their own file. An
257
+ // unreadable file counts as NOT unique, because "I could not look" and
258
+ // "it appears once" must not be the same reading.
259
+ if (anchor !== null && anchors.has(anchor) && uniqueAnchor(inputs, f, anchor)) {
260
+ return (
261
+ `${where}: ${what} — an earlier round of this pull request already ` +
262
+ `raised a finding at the same line of text in this file, in different words, ` +
263
+ `so this is read as the same finding restated and is not raised again`
264
+ );
265
+ }
266
+ seen.add(key);
267
+ // `anchors` is NOT grown here, and the asymmetry with `seen` above is
268
+ // deliberate (#1861 round 1).
269
+ //
270
+ // `seen` growing is the established within-round rule and is safe on an
271
+ // EXACT key: two candidates with the same file, anchor AND wording are
272
+ // the same finding listed twice. The anchor key drops the wording, so
273
+ // growing it would suppress a second, differently-worded finding at the
274
+ // same line because a SIBLING in this very round cited it — and the
275
+ // sentence above, which says "an earlier round", would be false.
276
+ //
277
+ // It is also unmeasured: #1168's reading characterises cross-round
278
+ // collisions only, 8 of 8 restatements. It says nothing about two
279
+ // findings a reviewer raises at one line while looking at it once,
280
+ // which is the more plausible place for two genuine defects to share an
281
+ // anchor. Suppressing on evidence that was never taken is the thing
282
+ // this whole increment is a correction for.
283
+ return null;
183
284
  });
184
285
  return { repeat, unmeasured: null };
185
286
  };
186
287
  }
187
288
 
289
+ /**
290
+ * THE ONE PLACE A PRODUCTION `SuppressionInputs` IS ASSEMBLED (#1861 round 4).
291
+ *
292
+ * Two commands form this gate — `scripts/ai-review-findings.ts`, which decides
293
+ * the exit code, and `scripts/ai-review-threads.ts`, which posts the threads.
294
+ * `ai-review-threads.ts`' own comment states the invariant: the gate is *"the
295
+ * same function the adjudicator builds, over the same file, which is what
296
+ * makes 'already raised' one decision rather than two that agree until they
297
+ * do not"*. They ran BEFORE this existed as two hand-written object literals,
298
+ * and the round-4 review found the predicted consequence: `anchorOccurrences`
299
+ * was added to one of them, so the whole anchor rule was dead in the poster —
300
+ * the half that produces #1168's actual symptom, 11 threads for 3 findings.
301
+ *
302
+ * Returning the reader alongside the gate is the other half. The poster needs
303
+ * `lineTextFor` again for the key it writes INTO each thread, and it used to
304
+ * build a second `checkoutLineText` with a second cache. One reader, one
305
+ * cache, one normalisation — and nothing left for a future field to be wired
306
+ * into unevenly.
307
+ *
308
+ * `gate` is `null` when no thread list is plumbed, which is each command's
309
+ * pre-existing behaviour and is NOT the same as a gate that finds no repeats.
310
+ * `test/ai-review-suppression.test.ts` (AS-15) asserts neither command
311
+ * assembles its own.
312
+ */
313
+ export function productionSuppression(
314
+ threadsPath: string | undefined,
315
+ root: string,
316
+ ): {
317
+ gate: AiReviewSuppressionGate | null;
318
+ lineTextFor: (finding: ReviewFinding) => string | undefined;
319
+ } {
320
+ const reader = checkoutLineReader(root);
321
+ const gate =
322
+ threadsPath === undefined || threadsPath === ""
323
+ ? null
324
+ : aiReviewSuppressionGate({
325
+ threads: readOrNull(threadsPath),
326
+ lineTextFor: reader.lineTextFor,
327
+ anchorOccurrences: reader.occurrencesOf,
328
+ });
329
+ return { gate, lineTextFor: reader.lineTextFor };
330
+ }
331
+
188
332
  /**
189
333
  * THE KEY-SYMMETRY HALF. The text at a finding's cited line, read out of the
190
334
  * checkout.
@@ -208,16 +352,35 @@ export function aiReviewSuppressionGate(inputs: SuppressionInputs): AiReviewSupp
208
352
  * RESOLVED path and not on the spelling.
209
353
  */
210
354
  export function checkoutLineText(root: string): (finding: ReviewFinding) => string | undefined {
355
+ return checkoutLineReader(root).lineTextFor;
356
+ }
357
+
358
+ /**
359
+ * Both readings of the checkout, over ONE file cache.
360
+ *
361
+ * `lineTextFor` is the key-symmetry half documented above. `occurrencesOf`
362
+ * is the distinctiveness half #1861 added: how many lines of a file carry a
363
+ * given normalised text. They share a cache because they read the same files
364
+ * on the same run, and they share `normaliseLineText` with `carryKey`
365
+ * because a counter normalising differently from the key would count
366
+ * occurrences of a string the key never built.
367
+ *
368
+ * `undefined` from `occurrencesOf` is "I could not look" — an unreadable
369
+ * file, an absolute path, an escape out of the checkout — and the caller
370
+ * reads it as not-unique. Zero is a different fact (the file was read and
371
+ * the text is not in it) and is also not one, so both refuse.
372
+ */
373
+ export function checkoutLineReader(root: string): {
374
+ lineTextFor: (finding: ReviewFinding) => string | undefined;
375
+ occurrencesOf: (file: string, normalisedText: string) => number | undefined;
376
+ } {
211
377
  const base = resolve(root);
212
378
  const cache = new Map<string, string[] | null>();
213
- return (finding: ReviewFinding) => {
214
- const file = finding.file;
215
- const line = finding.line;
216
- if (typeof file !== "string" || file === "") return undefined;
217
- if (typeof line !== "number" || !Number.isInteger(line) || line < 1) return undefined;
218
- if (isAbsolute(file)) return undefined;
379
+ const linesOf = (file: string): string[] | null => {
380
+ if (typeof file !== "string" || file === "") return null;
381
+ if (isAbsolute(file)) return null;
219
382
  const path = resolve(base, file);
220
- if (path !== base && !path.startsWith(base + sep)) return undefined;
383
+ if (path !== base && !path.startsWith(base + sep)) return null;
221
384
  if (!cache.has(path)) {
222
385
  try {
223
386
  cache.set(path, readFileSync(path, "utf-8").split("\n"));
@@ -225,10 +388,26 @@ export function checkoutLineText(root: string): (finding: ReviewFinding) => stri
225
388
  cache.set(path, null);
226
389
  }
227
390
  }
228
- const lines = cache.get(path) ?? null;
229
- if (lines === null) return undefined;
230
- const text = lines[line - 1];
231
- return typeof text === "string" && text.trim() !== "" ? text : undefined;
391
+ return cache.get(path) ?? null;
392
+ };
393
+ return {
394
+ lineTextFor: (finding: ReviewFinding) => {
395
+ const file = finding.file;
396
+ const line = finding.line;
397
+ if (typeof file !== "string") return undefined;
398
+ if (typeof line !== "number" || !Number.isInteger(line) || line < 1) return undefined;
399
+ const lines = linesOf(file);
400
+ if (lines === null) return undefined;
401
+ const text = lines[line - 1];
402
+ return typeof text === "string" && text.trim() !== "" ? text : undefined;
403
+ },
404
+ occurrencesOf: (file: string, normalisedText: string) => {
405
+ const lines = linesOf(file);
406
+ if (lines === null) return undefined;
407
+ let n = 0;
408
+ for (const l of lines) if (normaliseLineText(l) === normalisedText) n++;
409
+ return n;
410
+ },
232
411
  };
233
412
  }
234
413