rungate 0.8.2 → 0.8.3

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 (63) hide show
  1. package/bin/rungate.ts +11 -6
  2. package/config/prove-evidence.schema.json +21 -3
  3. package/gates/.gate-salt +1 -1
  4. package/gates/gate-executor.ts +153 -1
  5. package/gates/prove.test.ts +12 -6
  6. package/gates/schema.ts +69 -6
  7. package/gates/workflow.test.ts +12 -5
  8. package/hooks/DocHygiene.hook.ts +2 -1
  9. package/hooks/GateResultProtection.hook.ts +28 -7
  10. package/hooks/HookCurrency.hook.ts +48 -1
  11. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  12. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  13. package/lib/ai-review-jury.ts +725 -0
  14. package/lib/ai-review-rounds.ts +791 -4
  15. package/lib/ai-review-unmeasured.ts +361 -0
  16. package/lib/bash-write-guard.ts +1235 -102
  17. package/lib/cli-commands.ts +252 -11
  18. package/lib/closing-reference-audit.ts +163 -0
  19. package/lib/conformity.ts +12 -0
  20. package/lib/create-sc.ts +45 -12
  21. package/lib/derived-spec.ts +206 -0
  22. package/lib/file-claims.ts +335 -0
  23. package/lib/finding-arbiter.ts +502 -28
  24. package/lib/finding-jury.ts +48 -1
  25. package/lib/finding-pr-routing.ts +333 -0
  26. package/lib/frontmatter.ts +16 -0
  27. package/lib/gate-check-audit.ts +259 -0
  28. package/lib/generators/agents-md.ts +29 -0
  29. package/lib/github.ts +112 -7
  30. package/lib/hook-tree-currency.ts +494 -0
  31. package/lib/issue-closure-audit.ts +161 -14
  32. package/lib/issue-create-override.ts +53 -3
  33. package/lib/issue-filing-gate.ts +1073 -76
  34. package/lib/local-review-rounds.ts +523 -0
  35. package/lib/organize.ts +10 -0
  36. package/lib/project-state-shape.ts +56 -5
  37. package/lib/repo-path.ts +94 -0
  38. package/lib/report-provenance.ts +65 -3
  39. package/lib/risk-tier.ts +302 -0
  40. package/lib/rounds-to-pass.ts +274 -0
  41. package/lib/rule-row-drift.ts +199 -0
  42. package/lib/sc-claim-forms.ts +33 -5
  43. package/lib/sc-guard.ts +11 -1
  44. package/lib/sc-id-cross-tree.ts +17 -2
  45. package/lib/sc-ids.ts +71 -6
  46. package/lib/sc-reservations.ts +158 -14
  47. package/lib/scaffold/ai-review-findings.ts +1157 -18
  48. package/lib/scaffold/ai-review-step.ts +3798 -76
  49. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  50. package/lib/scaffold/owned-files.ts +14 -0
  51. package/lib/scaffold/steps.ts +83 -9
  52. package/lib/scratch-roots.ts +93 -3
  53. package/lib/spec-updater.ts +16 -0
  54. package/lib/validators/spec-validators.ts +28 -2
  55. package/package.json +2 -1
  56. package/scripts/ai-review-findings.ts +41 -1
  57. package/scripts/arbitrate-finding.ts +330 -12
  58. package/scripts/audit-specs.ts +225 -23
  59. package/scripts/create-sc.ts +11 -0
  60. package/scripts/detect-sc-drift.ts +10 -2
  61. package/scripts/record-ai-review-unmeasured.ts +370 -0
  62. package/scripts/split-spec.ts +12 -0
  63. package/scripts/sync-sc-status.ts +11 -0
@@ -63,8 +63,32 @@ export interface ClosedIssue {
63
63
  labels: string[];
64
64
  /** ISO-8601 close timestamp, used against `AUDIT_EPOCH`. */
65
65
  closedAt: string | null;
66
+ /**
67
+ * Numbers of MERGED pull requests that cross-reference this issue (#1279).
68
+ *
69
+ * This is the second reading, and it exists to split one bucket in two. A
70
+ * close with no closer tells you nobody linked the merge to the issue; it
71
+ * does not tell you whether a merge happened. Those are different facts
72
+ * and they need different work — see `classifyClosure`.
73
+ *
74
+ * Unmerged and closed-unmerged pull requests are deliberately absent: a
75
+ * draft that mentions an issue is not evidence the work shipped.
76
+ */
77
+ mergedReferences: number[];
66
78
  }
67
79
 
80
+ /**
81
+ * The GraphQL alias the cross-reference timeline is read under.
82
+ *
83
+ * One declaring position, on purpose. `toClosedIssue` reads this key and
84
+ * `scripts/audit-issue-closures.ts` interpolates this same constant into its
85
+ * query, so a reader and a producer naming different fields is a build-time
86
+ * impossibility rather than a silent `[]` — which is #530's shape exactly:
87
+ * a consumer reading a name nothing writes, with no error anywhere, because
88
+ * an absent key and an empty list are the same reading.
89
+ */
90
+ export const CROSS_REFERENCE_FIELD = "crossReferences";
91
+
68
92
  /**
69
93
  * The date this control went live. Issues closed before it are not findings.
70
94
  *
@@ -99,13 +123,30 @@ export const AUDIT_EPOCH = "2026-10-13T00:00:00Z";
99
123
  * resolves to the Commit or the PullRequest responsible, and to `null` when
100
124
  * GitHub has nothing to attribute the close to. REST's `state_reason` cannot
101
125
  * distinguish those, and the timeline endpoint is one request per issue.
126
+ *
127
+ * The cross-reference timeline is read under its own alias rather than by
128
+ * widening the `CLOSED_EVENT` selection (#1279). Widening it would have put
129
+ * the closer behind `last: N` on a mixed list, so an issue with N later
130
+ * cross-references would lose its `ClosedEvent` and read as a hand-typed
131
+ * close — a false finding manufactured by the instrument that was supposed
132
+ * to classify findings.
102
133
  */
103
134
  export function toClosedIssue(node: any): ClosedIssue {
104
135
  const closer = node?.timelineItems?.nodes?.[0]?.closer ?? null;
105
136
  let closedBy: string | null = null;
106
137
  if (closer?.__typename === "Commit") closedBy = `commit ${closer.oid}`;
107
138
  else if (closer?.__typename === "PullRequest") closedBy = `pull request #${closer.number}`;
139
+ const xrefs: number[] = [];
140
+ for (const item of node?.[CROSS_REFERENCE_FIELD]?.nodes ?? []) {
141
+ const source = item?.source;
142
+ // `merged` is the whole discriminator. An open or an abandoned pull
143
+ // request mentioning an issue is not evidence that anything shipped, and
144
+ // counting one would move a genuinely untraceable close into the bucket
145
+ // nobody re-reads.
146
+ if (source?.merged === true && typeof source.number === "number") xrefs.push(source.number);
147
+ }
108
148
  return {
149
+ mergedReferences: [...new Set(xrefs)].sort((a, b) => a - b),
109
150
  number: node.number,
110
151
  title: node.title ?? "",
111
152
  // GraphQL shouts its enums. The decision compares against `not_planned`,
@@ -119,9 +160,34 @@ export function toClosedIssue(node: any): ClosedIssue {
119
160
  };
120
161
  }
121
162
 
122
- /** A finding: one issue, and why it was flagged. */
163
+ /**
164
+ * Which of the two things a hand-typed close actually is (#1279).
165
+ *
166
+ * Both are findings. Both break
167
+ * `.claude/rules/ship-workflow.md`'s *"Let the PR close the issue. Do not run
168
+ * `gh issue close` yourself."* The split is not about who is at fault, it is
169
+ * about what the remedy costs:
170
+ *
171
+ * - `LINK_LOST` — a merged pull request in this repository references the
172
+ * issue, so the work is on `main` and only the attribution was dropped. The
173
+ * remedy is to name the PR. Nobody needs to re-do anything.
174
+ * - `NO_TRACE` — no merged pull request references it at all. Nothing in the
175
+ * merge history records that this work ever happened, which is the state
176
+ * the audit exists to surface.
177
+ *
178
+ * Before the split there was one bucket. Measured over this repository's 299
179
+ * issues closed between 2026-10-19 and 2026-10-23, 95 were findings and
180
+ * **79 of them were `LINK_LOST`** — so the 16 rows that are the real signal
181
+ * sat at one in six of a list people had learnt to scroll past. The count is
182
+ * the argument: a check is worth what it can discriminate, not what it can
183
+ * count.
184
+ */
185
+ export type FindingKind = "LINK_LOST" | "NO_TRACE";
186
+
187
+ /** A finding: one issue, which kind it is, and why it was flagged. */
123
188
  export interface ClosureFinding {
124
189
  issue: ClosedIssue;
190
+ kind: FindingKind;
125
191
  reason: string;
126
192
  }
127
193
 
@@ -147,6 +213,55 @@ export const NOT_PLANNED = "not_planned";
147
213
  export const EXEMPT_LABEL = "closed-by-hand";
148
214
  export const FINDING_LABEL = "closed-without-ship";
149
215
 
216
+ /**
217
+ * The label a `LINK_LOST` finding gets instead (#1279).
218
+ *
219
+ * A second finding label, not a second exemption. It exists so the split is
220
+ * queryable on the tracker and not only in a job log — `is:closed
221
+ * label:ship-link-lost` is a list of attributions somebody can repair, and
222
+ * `is:closed label:closed-without-ship` stops being 83% of that.
223
+ *
224
+ * Both finding labels suppress re-reporting, for the reason the two-label
225
+ * comment above gives: an audit that reads its own mark as new work reports
226
+ * the same issue every morning until somebody switches it off.
227
+ */
228
+ export const LINK_LOST_LABEL = "ship-link-lost";
229
+
230
+ /** The label each kind is reported under. One row per kind, so a new kind is a build error. */
231
+ export const LABEL_FOR_KIND: Record<FindingKind, string> = {
232
+ LINK_LOST: LINK_LOST_LABEL,
233
+ NO_TRACE: FINDING_LABEL,
234
+ };
235
+
236
+ /**
237
+ * The single place that decides which kind a finding is, and the evidence.
238
+ *
239
+ * Returns both together so there is one derivation. `report` and the labeller
240
+ * switch on `kind` and never re-read `mergedReferences` to re-decide — a
241
+ * second comparison of the same facts would survive any mutation of this one
242
+ * and the guard would go green for an unrelated reason
243
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
244
+ */
245
+ export function classifyClosure(issue: ClosedIssue): { kind: FindingKind; reason: string } {
246
+ const shipped = issue.mergedReferences ?? [];
247
+ if (shipped.length > 0) {
248
+ return {
249
+ kind: "LINK_LOST",
250
+ reason:
251
+ `closed by hand, but merged ${shipped.map(n => `#${n}`).join(", ")} ` +
252
+ `reference${shipped.length === 1 ? "s" : ""} it — the work is on the default branch ` +
253
+ `and only the closing link was lost. Repair the attribution; do not re-do the work`,
254
+ };
255
+ }
256
+ return {
257
+ kind: "NO_TRACE",
258
+ reason:
259
+ `closed with nothing to attribute it to, no ${NOT_PLANNED} reason, no ` +
260
+ `${EXEMPT_LABEL} label and no merged pull request referencing it — nothing ` +
261
+ `records that this work was ever done`,
262
+ };
263
+ }
264
+
150
265
  /**
151
266
  * The single place that decides. One exported function, so there is one
152
267
  * binding to mutate; a second comparison of the same facts elsewhere would
@@ -172,13 +287,14 @@ export function closedWithoutRecord(
172
287
  if (issue.closedBy !== null) continue;
173
288
  if (issue.stateReason === NOT_PLANNED) continue;
174
289
  if (issue.labels.includes(EXEMPT_LABEL)) continue;
175
- if (issue.labels.includes(FINDING_LABEL)) continue; // already reported
176
- out.push({
177
- issue,
178
- reason:
179
- `closed with nothing to attribute it to, no ${NOT_PLANNED} reason and no ` +
180
- `${EXEMPT_LABEL} label — nothing records that it went through the ship pipeline`,
181
- });
290
+ // Already reported, under either finding label (#1279).
291
+ if (issue.labels.some(l => l === FINDING_LABEL || l === LINK_LOST_LABEL)) continue;
292
+ // Both kinds are findings. The classification says what the remedy is; it
293
+ // never decides whether to report. A `continue` here for LINK_LOST is the
294
+ // cheapest wrong fix for this issue — the list shrinks by 83% and a
295
+ // hand-typed close of an issue somebody else's PR happens to mention
296
+ // becomes invisible.
297
+ out.push({ issue, ...classifyClosure(issue) });
182
298
  }
183
299
  return out;
184
300
  }
@@ -210,16 +326,47 @@ export function shouldReopen(finding: ClosureFinding, reopenEnabled: boolean): b
210
326
  return finding.issue.labels.some(l => PROTECTED_LABELS.includes(l));
211
327
  }
212
328
 
213
- /** The job summary, as text. Empty findings say so rather than printing nothing. */
329
+ /**
330
+ * The heading each kind is reported under. One row per kind, so a new kind is
331
+ * a build error rather than a silently unsectioned finding.
332
+ */
333
+ export const SECTION_FOR_KIND: Record<FindingKind, string> = {
334
+ NO_TRACE: "NO_TRACE — no merged pull request references these, so nothing records that the work happened",
335
+ LINK_LOST: "LINK_LOST — these shipped and the closing link was lost; repair the attribution, do not re-do the work",
336
+ };
337
+
338
+ /**
339
+ * The order the sections print in. `NO_TRACE` leads because it is the signal
340
+ * and `LINK_LOST` is 83% of the volume — a report that interleaves them puts
341
+ * the actionable rows one in six, which is the state #1279 is about.
342
+ */
343
+ export const KIND_ORDER: FindingKind[] = ["NO_TRACE", "LINK_LOST"];
344
+
345
+ /**
346
+ * The job summary, as text. Empty findings say so rather than printing nothing.
347
+ *
348
+ * Sections are keyed off `finding.kind` and nothing else. Re-deriving the kind
349
+ * here from `mergedReferences` would be a second decider for a question
350
+ * `classifyClosure` already answers, and the two would always agree right up
351
+ * until one of them was mutated.
352
+ */
214
353
  export function report(findings: ClosureFinding[], scanned: number): string {
215
354
  if (findings.length === 0) {
216
355
  return `Issue closure audit: ${scanned} closed issues scanned, none closed without a record.`;
217
356
  }
218
- const lines = findings.map(
219
- f => `- #${f.issue.number} ${f.issue.title} — ${f.reason}`,
220
- );
357
+ const counts = KIND_ORDER.map(k => `${k} ${findings.filter(f => f.kind === k).length}`).join(", ");
358
+ const blocks: string[] = [];
359
+ for (const kind of KIND_ORDER) {
360
+ const of = findings.filter(f => f.kind === kind);
361
+ if (of.length === 0) continue;
362
+ blocks.push(
363
+ `${SECTION_FOR_KIND[kind]}\n` +
364
+ of.map(f => `- #${f.issue.number} ${f.issue.title} — ${f.reason}`).join("\n"),
365
+ );
366
+ }
221
367
  return (
222
- `Issue closure audit: ${findings.length} of ${scanned} closed issues have no ship record.\n\n` +
223
- lines.join("\n")
368
+ `Issue closure audit: ${findings.length} of ${scanned} closed issues have no ship record ` +
369
+ `(${counts}).\n\n` +
370
+ blocks.join("\n\n")
224
371
  );
225
372
  }
@@ -1,3 +1,5 @@
1
+ import { interpreterPrograms, stripHeredocs } from "./bash-write-guard";
2
+
1
3
  /**
2
4
  * Whether a `gh issue create` may run during VERIFY, and why not (#365).
3
5
  *
@@ -59,14 +61,27 @@
59
61
  * - Variable indirection — `GH=gh; $GH issue create`. Resolving it means
60
62
  * tracking assignments across clauses, which is the shell interpreter this
61
63
  * file is explicitly not, and nobody reaches for `$GH` by reflex.
62
- * - Here-strings and here-documents — `bash <<< "gh issue create …"`. Same
63
- * reason: a deliberate construction, not a reflex.
64
64
  * - A caller who writes a script and runs it.
65
+ * - A `cd` in an earlier clause, which retargets the tracker invisibly.
66
+ * Resolving it needs directory state across clauses, same reason as above.
65
67
  *
66
68
  * Each of those takes a decision to get around the lock, and an agent that
67
69
  * has made that decision is a problem no matcher fixes. Chasing them trades
68
70
  * false refusals — which teach people to work around a guard — for
69
71
  * protection against someone already doing so.
72
+ *
73
+ * **Here-strings and here-documents left this list in #1302, and the entry is
74
+ * kept here rather than deleted because the reason it gave was wrong.** It
75
+ * read "a deliberate construction, not a reflex" — an argument about how
76
+ * often a shape is typed, which is not a property of the input and cannot be
77
+ * measured. What settled it was that the body of a heredoc had to be parsed
78
+ * either way: `clauses` was reading the bodies that go into FILES, which is
79
+ * the one case that is certainly not a command, and refusing real work for
80
+ * it. Once `stripHeredocs` removes those, `interpreterPrograms` has to put
81
+ * the executable ones back, and that binding returns herestrings in the same
82
+ * list. So the scope widened as a consequence of fixing a false refusal, and
83
+ * narrowing it again would mean writing a second decider that disagrees with
84
+ * `lib/bash-write-guard.ts`. See `heredocView` below.
70
85
  */
71
86
 
72
87
  /** Labels that permit an issue to be filed mid-VERIFY, and what each means. */
@@ -197,7 +212,7 @@ const SEPARATORS = new Set(OPERATORS);
197
212
  */
198
213
  export function clauses(cmd: string, depth = 0): string[][] {
199
214
  const flat: string[][] = [[]];
200
- for (const t of tokenize(cmd)) {
215
+ for (const t of tokenize(heredocView(cmd))) {
201
216
  if (SEPARATORS.has(t)) flat.push([]);
202
217
  else flat[flat.length - 1].push(t);
203
218
  }
@@ -212,6 +227,41 @@ export function clauses(cmd: string, depth = 0): string[][] {
212
227
  return out;
213
228
  }
214
229
 
230
+ /**
231
+ * The command text, with heredoc bodies routed by where they GO (#1302).
232
+ *
233
+ * A heredoc body handed to an interpreter is a program and is parsed. A body
234
+ * going anywhere else — `cat > doc.md <<'EOF'`, `tee`, `gh --body-file -` —
235
+ * is a DOCUMENT and is removed, because text on its way into a file is not a
236
+ * command however exactly it is spelled.
237
+ *
238
+ * **Both halves come from `lib/bash-write-guard.ts`, which already decided
239
+ * this and proved it over 5,060 real commands in #1240.** Writing the split
240
+ * again here would be two deciders on one question — the fourth shape in
241
+ * `.claude/rules/checks-must-be-able-to-fail.md` — and they were already
242
+ * disagreeing: `BashWriteGuard` read the interpreter body and stripped the
243
+ * document body, and this parser did the exact inverse. The inverse is the
244
+ * one that false-positives, and it blocked real work: a `cat > probe.ts`
245
+ * whose body quoted a filing was refused as though it were one.
246
+ *
247
+ * It is the same expression `decideBashWrite` builds its own view from, so
248
+ * the two guards now read a command the same way by construction rather than
249
+ * by agreement.
250
+ *
251
+ * Two behaviours worth knowing, both inherited and both in the safe
252
+ * direction. An UNTERMINATED heredoc is left in place, so a filing hidden
253
+ * behind an unclosed delimiter does not become invisible. And a herestring
254
+ * to a shell — `bash <<< '…'` — now parses where it did not before. That
255
+ * last one is a DOCUMENTED boundary being reversed, not an oversight being
256
+ * corrected: the module docblock listed it as out of scope and
257
+ * `test/verify-phase-lock.test.ts` asserted the allow. Both are updated in
258
+ * the same commit, with the reason, because a boundary that moves silently
259
+ * is worse than either position.
260
+ */
261
+ function heredocView(cmd: string): string {
262
+ return [stripHeredocs(cmd), ...interpreterPrograms(cmd).map(p => p.program)].join("\n");
263
+ }
264
+
215
265
  /** Arguments of this clause that are themselves commands. */
216
266
  function commandArguments(tokens: string[]): string[] {
217
267
  const out: string[] = [];