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.
- package/bin/rungate.ts +11 -6
- package/config/prove-evidence.schema.json +21 -3
- package/gates/.gate-salt +1 -1
- package/gates/gate-executor.ts +153 -1
- package/gates/prove.test.ts +12 -6
- package/gates/schema.ts +69 -6
- package/gates/workflow.test.ts +12 -5
- package/hooks/DocHygiene.hook.ts +2 -1
- package/hooks/GateResultProtection.hook.ts +28 -7
- package/hooks/HookCurrency.hook.ts +48 -1
- package/hooks/VerifyPhaseLock.hook.ts +25 -8
- package/hooks/WorkflowStateGuard.hook.ts +24 -7
- package/lib/ai-review-jury.ts +725 -0
- package/lib/ai-review-rounds.ts +791 -4
- package/lib/ai-review-unmeasured.ts +361 -0
- package/lib/bash-write-guard.ts +1235 -102
- package/lib/cli-commands.ts +252 -11
- package/lib/closing-reference-audit.ts +163 -0
- package/lib/conformity.ts +12 -0
- package/lib/create-sc.ts +45 -12
- package/lib/derived-spec.ts +206 -0
- package/lib/file-claims.ts +335 -0
- package/lib/finding-arbiter.ts +502 -28
- package/lib/finding-jury.ts +48 -1
- package/lib/finding-pr-routing.ts +333 -0
- package/lib/frontmatter.ts +16 -0
- package/lib/gate-check-audit.ts +259 -0
- package/lib/generators/agents-md.ts +29 -0
- package/lib/github.ts +112 -7
- package/lib/hook-tree-currency.ts +494 -0
- package/lib/issue-closure-audit.ts +161 -14
- package/lib/issue-create-override.ts +53 -3
- package/lib/issue-filing-gate.ts +1073 -76
- package/lib/local-review-rounds.ts +523 -0
- package/lib/organize.ts +10 -0
- package/lib/project-state-shape.ts +56 -5
- package/lib/repo-path.ts +94 -0
- package/lib/report-provenance.ts +65 -3
- package/lib/risk-tier.ts +302 -0
- package/lib/rounds-to-pass.ts +274 -0
- package/lib/rule-row-drift.ts +199 -0
- package/lib/sc-claim-forms.ts +33 -5
- package/lib/sc-guard.ts +11 -1
- package/lib/sc-id-cross-tree.ts +17 -2
- package/lib/sc-ids.ts +71 -6
- package/lib/sc-reservations.ts +158 -14
- package/lib/scaffold/ai-review-findings.ts +1157 -18
- package/lib/scaffold/ai-review-step.ts +3798 -76
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +83 -9
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +16 -0
- package/lib/validators/spec-validators.ts +28 -2
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +41 -1
- package/scripts/arbitrate-finding.ts +330 -12
- package/scripts/audit-specs.ts +225 -23
- package/scripts/create-sc.ts +11 -0
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +12 -0
- 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
|
-
/**
|
|
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
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
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
|
-
/**
|
|
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
|
|
219
|
-
|
|
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
|
|
223
|
-
|
|
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[] = [];
|