rungate 0.8.2 → 0.8.4
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/BunTestPathGuard.hook.ts +106 -0
- package/hooks/DocHygiene.hook.ts +2 -1
- package/hooks/GateResultProtection.hook.ts +28 -7
- package/hooks/HookCurrency.hook.ts +48 -1
- package/hooks/TopLevelCdGuard.hook.ts +38 -6
- 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/bun-test-paths.ts +253 -0
- package/lib/cli-commands.ts +252 -11
- package/lib/closing-reference-audit.ts +163 -0
- package/lib/conformity.ts +17 -1
- 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 +61 -5
- package/lib/finding-pr-routing.ts +333 -0
- package/lib/frontmatter.ts +16 -0
- package/lib/gate-check-audit.ts +646 -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 +21 -1
- package/lib/project-state-shape.ts +56 -5
- package/lib/release-preflight.ts +90 -1
- package/lib/repo-path.ts +94 -0
- package/lib/report-provenance.ts +218 -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 +1369 -27
- package/lib/scaffold/ai-review-step.ts +4095 -119
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +100 -9
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +22 -2
- package/lib/spec-write-ast.ts +728 -0
- package/lib/spec-write-sweep.ts +470 -0
- package/lib/test-suite-lock.ts +127 -13
- package/lib/ts-ast.ts +26 -0
- package/lib/validators/spec-validators.ts +36 -7
- package/lib/write-spec.ts +138 -0
- 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 -24
- package/scripts/convert-spec.ts +7 -2
- package/scripts/create-sc.ts +14 -2
- package/scripts/create-spec.ts +5 -2
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +17 -4
- package/scripts/sync-sc-status.ts +14 -2
|
@@ -0,0 +1,523 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Bounding the LOCAL review loop (#1342).
|
|
3
|
+
*
|
|
4
|
+
* The loop a person drives: run the local review, relay what it found, the
|
|
5
|
+
* agent pushes a fix, run the local review again. On 2026-10-23 it went five
|
|
6
|
+
* rounds on #1304 and **four of the five pushes were triggered by review
|
|
7
|
+
* output rather than by anything the implementing agent found**. Nothing
|
|
8
|
+
* ended it except the lead noticing, and a lead who is AFK is not a mechanism.
|
|
9
|
+
*
|
|
10
|
+
* ## This module reimplements neither half of what it joins
|
|
11
|
+
*
|
|
12
|
+
* - **Is there a round left in the budget?** `lib/ai-review-rounds.ts`'s
|
|
13
|
+
* `roundOutcome` already answers that, and already fails closed on a budget
|
|
14
|
+
* nobody can read. It is called, not restated, so the two cannot be changed
|
|
15
|
+
* apart and a mutation of its `spent < cap` is observable through here.
|
|
16
|
+
* - **Do two findings describe one symptom?** `lib/finding-arbiter.ts`'s
|
|
17
|
+
* `duplicateOverlap` already answers that, over a key set tuned on a
|
|
18
|
+
* 40-issue corpus with its false positives listed by number rather than
|
|
19
|
+
* tuned away. It is called, not restated.
|
|
20
|
+
*
|
|
21
|
+
* What is added is the one thing neither has an opinion about: **when the
|
|
22
|
+
* loop has stopped learning anything.**
|
|
23
|
+
*
|
|
24
|
+
* ## Why a round counter alone is the wrong fix, in the issue's own words
|
|
25
|
+
*
|
|
26
|
+
* "If round N returns a new *class*, that is information worth having and the
|
|
27
|
+
* cap should not eat it. If it returns a variant of a class already resolved,
|
|
28
|
+
* the loop is done."
|
|
29
|
+
*
|
|
30
|
+
* Those are two separate corrections to a counter and they point opposite
|
|
31
|
+
* ways, which is why neither is reachable by moving the cap:
|
|
32
|
+
*
|
|
33
|
+
* - A counter is **too slow**. Rounds 2-5 on #1304 returned variants of one
|
|
34
|
+
* class — *"the gate reads a different value than `gh`"* — and a counter
|
|
35
|
+
* with a cap of three happily spends rounds 2 and 3 on them. After the
|
|
36
|
+
* first pass a repeat tells you about the reviewer, not about the code, so
|
|
37
|
+
* `SETTLED` is reachable at round 2 here and does not wait for the cap.
|
|
38
|
+
* - A counter is **too blunt**. A round past the cap that raises a class no
|
|
39
|
+
* earlier round raised is the one case where continuing was right, and a
|
|
40
|
+
* counter either loops on it forever or throws it away.
|
|
41
|
+
*
|
|
42
|
+
* `AT_CAP` is the answer to the second, and it is deliberately not silence:
|
|
43
|
+
* the reading **carries the new classes out** in `newClasses`. The cap bounds
|
|
44
|
+
* the LOOP, never the INFORMATION — what changes past the cap is that a new
|
|
45
|
+
* class is filed rather than fixed-pushed-and-re-reviewed. That is the same
|
|
46
|
+
* shape `atCapInstruction` takes for the CI reviewer (it keeps speaking, it
|
|
47
|
+
* stops enumerating) and the same shape `record-security-verdict.ts` gives
|
|
48
|
+
* `EXHAUSTED` (its own verdict, because a spent cap is neither a pass nor a
|
|
49
|
+
* finding).
|
|
50
|
+
*
|
|
51
|
+
* ## The one invariant that keeps the two mechanisms from fighting
|
|
52
|
+
*
|
|
53
|
+
* **The class rule can only ever end the loop SOONER. It never outlives the
|
|
54
|
+
* cap.** A round full of findings too thin to key is all-new by construction —
|
|
55
|
+
* that is `suppressRepeats`'s direction-of-error rule, kept here — so without
|
|
56
|
+
* this invariant an unkeyable reviewer would loop forever. `AC-LR6` in
|
|
57
|
+
* `test/local-review-rounds.test.ts` walks eight rounds of brand-new classes,
|
|
58
|
+
* the most favourable input the class rule has, and the cap still stops it.
|
|
59
|
+
*/
|
|
60
|
+
|
|
61
|
+
import {
|
|
62
|
+
AI_REVIEW_ROUND_AT_CAP,
|
|
63
|
+
AI_REVIEW_ROUND_CAP,
|
|
64
|
+
AI_REVIEW_ROUNDS_UNMEASURED,
|
|
65
|
+
roundOutcome,
|
|
66
|
+
} from "./ai-review-rounds.ts";
|
|
67
|
+
import { duplicateOverlap, UNFILED_ID, type Finding } from "./finding-arbiter.ts";
|
|
68
|
+
import { ghRepoTarget } from "./issue-filing-gate.ts";
|
|
69
|
+
import { homedir } from "os";
|
|
70
|
+
import { join } from "path";
|
|
71
|
+
|
|
72
|
+
/** Another round is worth spending: this one raised something new. */
|
|
73
|
+
export const LOCAL_REVIEW_CONTINUE = "LOCAL_REVIEW_CONTINUE";
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* The loop is done because it converged, at whatever round that happened.
|
|
77
|
+
*
|
|
78
|
+
* Either the review raised nothing, or everything it raised is a restatement
|
|
79
|
+
* of a class an earlier round already raised.
|
|
80
|
+
*/
|
|
81
|
+
export const LOCAL_REVIEW_SETTLED = "LOCAL_REVIEW_SETTLED";
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* The loop is done because the budget is spent, and it had not converged.
|
|
85
|
+
*
|
|
86
|
+
* Kept apart from `SETTLED` rather than folded into it, for the reason
|
|
87
|
+
* `roundOutcome` keeps `REVIEW_CURRENT` apart from exhaustion: the two mean
|
|
88
|
+
* opposite things, and a reading that collapsed them would report every
|
|
89
|
+
* converged loop as a truncated one and every truncated one as converged.
|
|
90
|
+
*/
|
|
91
|
+
export const LOCAL_REVIEW_AT_CAP = "LOCAL_REVIEW_AT_CAP";
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* The rounds could not be read, so this is not a reading.
|
|
95
|
+
*
|
|
96
|
+
* A REFUSAL and not a warning, on `roundOutcome`'s own reasoning: a history
|
|
97
|
+
* nobody can read makes round 12 indistinguishable from round 1, and reading
|
|
98
|
+
* it as round 1 resets the bound on every call — a cap that can never be
|
|
99
|
+
* reached. `runAnotherRound` says no to it, so an unreadable history stops
|
|
100
|
+
* the loop rather than licensing it.
|
|
101
|
+
*/
|
|
102
|
+
export const LOCAL_REVIEW_UNMEASURED = "LOCAL_REVIEW_UNMEASURED";
|
|
103
|
+
|
|
104
|
+
export type LocalRoundDecision =
|
|
105
|
+
| typeof LOCAL_REVIEW_CONTINUE
|
|
106
|
+
| typeof LOCAL_REVIEW_SETTLED
|
|
107
|
+
| typeof LOCAL_REVIEW_AT_CAP
|
|
108
|
+
| typeof LOCAL_REVIEW_UNMEASURED;
|
|
109
|
+
|
|
110
|
+
export interface RepeatedFinding {
|
|
111
|
+
/** The finding this round raised. */
|
|
112
|
+
finding: Finding;
|
|
113
|
+
/** The earlier finding it restates. */
|
|
114
|
+
of: Finding;
|
|
115
|
+
/** The symptom keys the two share, so the suppression is reviewable. */
|
|
116
|
+
keys: string[];
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
export interface LocalRoundReading {
|
|
120
|
+
decision: LocalRoundDecision;
|
|
121
|
+
/** The round the reading is about, or null when the history was unreadable. */
|
|
122
|
+
round: number | null;
|
|
123
|
+
/**
|
|
124
|
+
* Findings this round raised that no earlier round did.
|
|
125
|
+
*
|
|
126
|
+
* **Populated on `AT_CAP` too.** That is the point of the verdict: the loop
|
|
127
|
+
* ends and the classes do not.
|
|
128
|
+
*/
|
|
129
|
+
newClasses: Finding[];
|
|
130
|
+
/** Findings this round raised that an earlier one already had. */
|
|
131
|
+
repeats: RepeatedFinding[];
|
|
132
|
+
/** Why this is not an ordinary CONTINUE. Never empty. */
|
|
133
|
+
reason: string;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** A round of the loop, as the caller records it. */
|
|
137
|
+
export interface LocalRound {
|
|
138
|
+
findings: Finding[];
|
|
139
|
+
[k: string]: unknown;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Read one finding, or say why it could not be read.
|
|
144
|
+
*
|
|
145
|
+
* `title` and `body` must BOTH be strings. `symptomKeys` reads them and
|
|
146
|
+
* nothing else, so a finding missing either is a finding whose class is
|
|
147
|
+
* partly unobservable — and a key formed from half the evidence does not
|
|
148
|
+
* fail, it silently compares two different things.
|
|
149
|
+
*
|
|
150
|
+
* A missing `id` becomes `UNFILED_ID`. The id is only ever used by
|
|
151
|
+
* `duplicateOverlap`'s cross-citation escape, which needs a digit string to
|
|
152
|
+
* fire at all, so an absent one costs nothing and refusing it would reject
|
|
153
|
+
* every reviewer payload that does not file issues.
|
|
154
|
+
*/
|
|
155
|
+
function readFinding(raw: unknown, where: string): Finding | string {
|
|
156
|
+
if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
|
|
157
|
+
return `${where} is ${describe(raw)} rather than a finding object`;
|
|
158
|
+
}
|
|
159
|
+
const f = raw as Record<string, unknown>;
|
|
160
|
+
const id = typeof f.id === "string" ? f.id : UNFILED_ID;
|
|
161
|
+
|
|
162
|
+
// The arbiter's own shape, when a caller already has one.
|
|
163
|
+
if (typeof f.title === "string" && typeof f.body === "string") {
|
|
164
|
+
return { id, title: f.title, body: f.body };
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
// THE SHAPE A REAL REVIEWER WRITES, and the one this module existed
|
|
168
|
+
// without reading for two pushes. `AI_REVIEW_FINDING_FIELDS` is
|
|
169
|
+
// `{severity, file, line, summary, failure_scenario}` — no `title` and no
|
|
170
|
+
// `body` — so a reader that accepts only the arbiter's shape refuses every
|
|
171
|
+
// genuine payload, on every round, and the mechanism is unreachable on
|
|
172
|
+
// real input while every test of it passes. A caller that exists and can
|
|
173
|
+
// never be fed is the same defect as no caller at all, one level in.
|
|
174
|
+
//
|
|
175
|
+
// `summary` is the title because it is the one sentence stating the
|
|
176
|
+
// defect, which is what `symptomKeys` reads a title for. The body is
|
|
177
|
+
// SYNTHESISED rather than taken from one field, and the two halves are
|
|
178
|
+
// load-bearing on different inputs — measured, because the first draft of
|
|
179
|
+
// this comment claimed both were load-bearing everywhere and half of that
|
|
180
|
+
// was false:
|
|
181
|
+
//
|
|
182
|
+
// * dropping `failure_scenario` reddens the ordinary rows at once. It
|
|
183
|
+
// carries the measured integers, and `sameSymptom` needs two shared
|
|
184
|
+
// quantities before anything else matters.
|
|
185
|
+
// * dropping the bare `file` path reddens NOTHING on findings whose
|
|
186
|
+
// prose shares backticked symbols — those already supply the one
|
|
187
|
+
// location key the rule asks for. It is load-bearing only for a pair
|
|
188
|
+
// of plain-prose findings naming no symbols, where the `file:` key
|
|
189
|
+
// `pathsIn` extracts is the only location key there is. `AC-LL12` is
|
|
190
|
+
// that pair, and it exists because without it this half of the
|
|
191
|
+
// synthesis was unfalsifiable.
|
|
192
|
+
//
|
|
193
|
+
// Either way the failure mode is the same and it looks like success: the
|
|
194
|
+
// loop still runs, it just stops settling, two rounds later.
|
|
195
|
+
if (typeof f.summary === "string") {
|
|
196
|
+
const file = typeof f.file === "string" ? f.file : "";
|
|
197
|
+
const scenario = typeof f.failure_scenario === "string" ? f.failure_scenario : "";
|
|
198
|
+
return { id, title: f.summary, body: `${f.summary}\n\n${scenario}\n\n${file}` };
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
return (
|
|
202
|
+
`${where} carries neither shape this reader knows: no \`summary\` (the reviewer ` +
|
|
203
|
+
`contract's) and no \`title\`/\`body\` pair (the arbiter's). A finding naming no defect ` +
|
|
204
|
+
`cannot be compared against anything, and recording it as a round that found nothing ` +
|
|
205
|
+
`would clear the loop on an unread finding`
|
|
206
|
+
);
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/** Read the whole history, or say why it could not be read. */
|
|
210
|
+
function readRounds(raw: unknown): LocalRound[] | string {
|
|
211
|
+
if (!Array.isArray(raw)) {
|
|
212
|
+
return (
|
|
213
|
+
`the review history is ${describe(raw)} rather than an array of rounds, so this call ` +
|
|
214
|
+
`cannot tell a first review from a twelfth`
|
|
215
|
+
);
|
|
216
|
+
}
|
|
217
|
+
if (raw.length === 0) {
|
|
218
|
+
return (
|
|
219
|
+
`the review history holds no rounds at all. A decision about "this round" needs the ` +
|
|
220
|
+
`round it is about, and an empty history is the absence of one rather than a reading ` +
|
|
221
|
+
`that the loop has settled`
|
|
222
|
+
);
|
|
223
|
+
}
|
|
224
|
+
const out: LocalRound[] = [];
|
|
225
|
+
for (let i = 0; i < raw.length; i++) {
|
|
226
|
+
const entry = raw[i];
|
|
227
|
+
if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
|
|
228
|
+
return `round ${i + 1} is ${describe(entry)} rather than a round object`;
|
|
229
|
+
}
|
|
230
|
+
const list = (entry as Record<string, unknown>).findings;
|
|
231
|
+
if (!Array.isArray(list)) {
|
|
232
|
+
// Counted as unreadable rather than as a round that found nothing. The
|
|
233
|
+
// two are the same shape downstream and only one of them is a reading:
|
|
234
|
+
// `toLedgerRound` makes the same distinction for the CI ledger, and for
|
|
235
|
+
// the same reason — a round that vanishes makes a five-round loop look
|
|
236
|
+
// like a four-round one.
|
|
237
|
+
return (
|
|
238
|
+
`round ${i + 1} records its findings as ${describe(list)} rather than an array, so ` +
|
|
239
|
+
`whether that round raised anything is unknown — which is not the same fact as its ` +
|
|
240
|
+
`having raised nothing`
|
|
241
|
+
);
|
|
242
|
+
}
|
|
243
|
+
const findings: Finding[] = [];
|
|
244
|
+
for (let j = 0; j < list.length; j++) {
|
|
245
|
+
const read = readFinding(list[j], `round ${i + 1}, finding ${j + 1},`);
|
|
246
|
+
if (typeof read === "string") return read;
|
|
247
|
+
findings.push(read);
|
|
248
|
+
}
|
|
249
|
+
out.push({ ...(entry as Record<string, unknown>), findings });
|
|
250
|
+
}
|
|
251
|
+
return out;
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
function unmeasured(reason: string): LocalRoundReading {
|
|
255
|
+
return { decision: LOCAL_REVIEW_UNMEASURED, round: null, newClasses: [], repeats: [], reason };
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
/**
|
|
259
|
+
* Should the loop spend another round?
|
|
260
|
+
*
|
|
261
|
+
* `rounds` is every round so far, oldest first, the one just returned
|
|
262
|
+
* included; the reading is about the last entry. It is a PARAMETER and not
|
|
263
|
+
* something fetched here, deliberately: a function that fetches its own
|
|
264
|
+
* evidence cannot be given a negative control.
|
|
265
|
+
*/
|
|
266
|
+
export function localRoundReading(
|
|
267
|
+
rounds: unknown,
|
|
268
|
+
cap: unknown = AI_REVIEW_ROUND_CAP,
|
|
269
|
+
): LocalRoundReading {
|
|
270
|
+
const read = readRounds(rounds);
|
|
271
|
+
if (typeof read === "string") return unmeasured(read);
|
|
272
|
+
|
|
273
|
+
const n = read.length;
|
|
274
|
+
const latest = read[n - 1].findings;
|
|
275
|
+
const budget = roundOutcome(n, cap);
|
|
276
|
+
|
|
277
|
+
// n is this array's length, so it is always a positive integer and this
|
|
278
|
+
// branch is unreachable today. Checked anyway rather than assumed: if the
|
|
279
|
+
// round number ever stops being derived from the array, an unreadable one
|
|
280
|
+
// must refuse here and not fall through to a CONTINUE.
|
|
281
|
+
if (budget.decision === AI_REVIEW_ROUNDS_UNMEASURED) {
|
|
282
|
+
return unmeasured(budget.reason ?? "the round budget could not be read");
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
if (latest.length === 0) {
|
|
286
|
+
return {
|
|
287
|
+
decision: LOCAL_REVIEW_SETTLED,
|
|
288
|
+
round: n,
|
|
289
|
+
newClasses: [],
|
|
290
|
+
repeats: [],
|
|
291
|
+
reason: `review round ${n} raised nothing, so there is nothing left for a round ${n + 1} to be about`,
|
|
292
|
+
};
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
// Everything any earlier round raised, plus the classes already accepted as
|
|
296
|
+
// new WITHIN this round — a reviewer listing one defect twice in one payload
|
|
297
|
+
// is the same waste as one listing it on two rounds, and only the first
|
|
298
|
+
// occurrence is a new class.
|
|
299
|
+
const seen: Finding[] = read.slice(0, n - 1).flatMap(r => r.findings);
|
|
300
|
+
const newClasses: Finding[] = [];
|
|
301
|
+
const repeats: RepeatedFinding[] = [];
|
|
302
|
+
|
|
303
|
+
for (const finding of latest) {
|
|
304
|
+
let matched: RepeatedFinding | null = null;
|
|
305
|
+
for (const prior of seen) {
|
|
306
|
+
const overlap = duplicateOverlap(finding, prior);
|
|
307
|
+
if (overlap.duplicate) {
|
|
308
|
+
matched = { finding, of: prior, keys: overlap.keys };
|
|
309
|
+
break;
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
if (matched) {
|
|
313
|
+
repeats.push(matched);
|
|
314
|
+
continue;
|
|
315
|
+
}
|
|
316
|
+
newClasses.push(finding);
|
|
317
|
+
seen.push(finding);
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
// Checked BEFORE the cap. Both end the loop, and a round that converged is
|
|
321
|
+
// a different fact from one that was cut off — see LOCAL_REVIEW_AT_CAP.
|
|
322
|
+
if (newClasses.length === 0) {
|
|
323
|
+
return {
|
|
324
|
+
decision: LOCAL_REVIEW_SETTLED,
|
|
325
|
+
round: n,
|
|
326
|
+
newClasses,
|
|
327
|
+
repeats,
|
|
328
|
+
reason:
|
|
329
|
+
`every one of the ${repeats.length} finding(s) review round ${n} raised restates a ` +
|
|
330
|
+
`class an earlier round already raised, so this round is evidence about the reviewer ` +
|
|
331
|
+
`rather than about the code and the loop is done`,
|
|
332
|
+
};
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
if (budget.decision === AI_REVIEW_ROUND_AT_CAP) {
|
|
336
|
+
return {
|
|
337
|
+
decision: LOCAL_REVIEW_AT_CAP,
|
|
338
|
+
round: n,
|
|
339
|
+
newClasses,
|
|
340
|
+
repeats,
|
|
341
|
+
reason:
|
|
342
|
+
`review round ${n} raised ${newClasses.length} class(es) no earlier round raised, and ` +
|
|
343
|
+
`the round budget is spent (${budget.reason ?? "no rounds left"}). The loop ends here ` +
|
|
344
|
+
`and the classes do not: file them, rather than fixing and re-reviewing. A cap that ` +
|
|
345
|
+
`ate a new class would truncate the one case where continuing was right`,
|
|
346
|
+
};
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
return {
|
|
350
|
+
decision: LOCAL_REVIEW_CONTINUE,
|
|
351
|
+
round: n,
|
|
352
|
+
newClasses,
|
|
353
|
+
repeats,
|
|
354
|
+
reason:
|
|
355
|
+
`review round ${n} raised ${newClasses.length} class(es) no earlier round raised` +
|
|
356
|
+
(repeats.length > 0 ? `, and ${repeats.length} restatement(s) of earlier ones` : "") +
|
|
357
|
+
`, so another round is worth spending`,
|
|
358
|
+
};
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
/* ───────────────────────── the history the loop keeps ─────────────────────
|
|
362
|
+
*
|
|
363
|
+
* #1342 shipped the decision above and no caller, which is the shape #1381 is
|
|
364
|
+
* open about one subsystem over: a decision function nobody calls is
|
|
365
|
+
* indistinguishable from one that works. This is the half that makes the
|
|
366
|
+
* rounds exist.
|
|
367
|
+
*
|
|
368
|
+
* ## Why this is a local file and not the ai-review ledger comment
|
|
369
|
+
*
|
|
370
|
+
* The CI ledger (`AI_REVIEW_LEDGER_COMMENT_MARKER`) was the obvious store and
|
|
371
|
+
* is the wrong one, for a reason that is about the budget rather than about
|
|
372
|
+
* convenience. **A CI round and a local round are not the same round.** They
|
|
373
|
+
* read the same tree with different instruments, and a shared counter means
|
|
374
|
+
* CI rounds spend the local reviewer's budget — silencing the local loop for
|
|
375
|
+
* rounds it did not cause. Separate stores is the statement that they are
|
|
376
|
+
* separate budgets, and it is a decision rather than an omission.
|
|
377
|
+
*
|
|
378
|
+
* Two consequences worth knowing. The local history never leaves the machine
|
|
379
|
+
* that drove the loop, which is correct for a loop a local plugin drives and
|
|
380
|
+
* useless to anyone else. And it does not survive a cleaned work directory,
|
|
381
|
+
* which reads as ABSENT — round 1 — rather than as a refusal, because a store
|
|
382
|
+
* that is genuinely not there is a measured absence.
|
|
383
|
+
*/
|
|
384
|
+
|
|
385
|
+
/** No history file. A MEASURED reading of nothing: this is round 1. */
|
|
386
|
+
export const LOCAL_HISTORY_ABSENT = "LOCAL_HISTORY_ABSENT";
|
|
387
|
+
|
|
388
|
+
/**
|
|
389
|
+
* A history is there and could not be read. NOT the same as absent.
|
|
390
|
+
*
|
|
391
|
+
* `lib/config-loader.ts` makes this distinction about an absent config versus
|
|
392
|
+
* a corrupt one, `readLedger` makes it about the CI ledger, and it matters
|
|
393
|
+
* most here: a corrupt history read as empty restarts the count at 1 on every
|
|
394
|
+
* turn, which is a cap that can never be reached. That is `roundOutcome`'s
|
|
395
|
+
* unreadable-budget fail-open arriving through a different door.
|
|
396
|
+
*/
|
|
397
|
+
export const LOCAL_HISTORY_UNREADABLE = "LOCAL_HISTORY_UNREADABLE";
|
|
398
|
+
|
|
399
|
+
/** The history was read. */
|
|
400
|
+
export const LOCAL_HISTORY_READ = "LOCAL_HISTORY_READ";
|
|
401
|
+
|
|
402
|
+
export type HistoryReading =
|
|
403
|
+
| { status: typeof LOCAL_HISTORY_ABSENT }
|
|
404
|
+
| { status: typeof LOCAL_HISTORY_UNREADABLE; reason: string }
|
|
405
|
+
| { status: typeof LOCAL_HISTORY_READ; rounds: unknown[] };
|
|
406
|
+
|
|
407
|
+
/**
|
|
408
|
+
* Parse a history file's contents. `null` means the file is not there.
|
|
409
|
+
*
|
|
410
|
+
* **An empty file is UNREADABLE, not absent.** It is the one case where the
|
|
411
|
+
* two genuinely look alike, and it is the signature of a write that was
|
|
412
|
+
* interrupted — a file that exists holding nothing is a file something was
|
|
413
|
+
* writing. Treating it as round 1 discards however many rounds it held.
|
|
414
|
+
*/
|
|
415
|
+
export function parseHistory(raw: string | null): HistoryReading {
|
|
416
|
+
if (raw === null) return { status: LOCAL_HISTORY_ABSENT };
|
|
417
|
+
if (raw.trim() === "") {
|
|
418
|
+
return {
|
|
419
|
+
status: LOCAL_HISTORY_UNREADABLE,
|
|
420
|
+
reason:
|
|
421
|
+
`the review history file exists and is empty, which is a write that did not finish ` +
|
|
422
|
+
`rather than a loop that has not started — it is not being read as round 1`,
|
|
423
|
+
};
|
|
424
|
+
}
|
|
425
|
+
let parsed: unknown;
|
|
426
|
+
try {
|
|
427
|
+
parsed = JSON.parse(raw);
|
|
428
|
+
} catch (e) {
|
|
429
|
+
return {
|
|
430
|
+
status: LOCAL_HISTORY_UNREADABLE,
|
|
431
|
+
reason:
|
|
432
|
+
`the review history could not be parsed (${e instanceof Error ? e.message : String(e)}), ` +
|
|
433
|
+
`so how many rounds this loop has already spent is unknown`,
|
|
434
|
+
};
|
|
435
|
+
}
|
|
436
|
+
if (!Array.isArray(parsed)) {
|
|
437
|
+
return {
|
|
438
|
+
status: LOCAL_HISTORY_UNREADABLE,
|
|
439
|
+
reason:
|
|
440
|
+
`the review history is ${describe(parsed)} rather than an array of rounds, so how ` +
|
|
441
|
+
`many rounds this loop has already spent is unknown`,
|
|
442
|
+
};
|
|
443
|
+
}
|
|
444
|
+
return { status: LOCAL_HISTORY_READ, rounds: parsed };
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
/** One round, as the history records it. */
|
|
448
|
+
export interface RecordedRound {
|
|
449
|
+
/** When the round happened. */
|
|
450
|
+
at: string;
|
|
451
|
+
findings: unknown[];
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
/**
|
|
455
|
+
* The history with this round appended, or the reason it may not be.
|
|
456
|
+
*
|
|
457
|
+
* **An UNREADABLE history refuses rather than being replaced.** Starting a
|
|
458
|
+
* fresh array over one is the cheapest repair and the worst: it destroys the
|
|
459
|
+
* only evidence of how many rounds had already happened, at exactly the
|
|
460
|
+
* moment nothing can tell that it did — and it does so silently, every turn,
|
|
461
|
+
* so the loop that most needs the bound is the one that loses it.
|
|
462
|
+
*/
|
|
463
|
+
export function appendRound(
|
|
464
|
+
reading: HistoryReading,
|
|
465
|
+
findings: unknown[],
|
|
466
|
+
at: string,
|
|
467
|
+
): { rounds: unknown[] } | { refusal: string } {
|
|
468
|
+
if (reading.status === LOCAL_HISTORY_UNREADABLE) return { refusal: reading.reason };
|
|
469
|
+
const prior = reading.status === LOCAL_HISTORY_READ ? reading.rounds : [];
|
|
470
|
+
const round: RecordedRound = { at, findings };
|
|
471
|
+
return { rounds: [...prior, round] };
|
|
472
|
+
}
|
|
473
|
+
|
|
474
|
+
/**
|
|
475
|
+
* Where a pull request's local-round history lives.
|
|
476
|
+
*
|
|
477
|
+
* `RUNGATE_LOCAL_REVIEW_HISTORY` overrides the directory outright, and every
|
|
478
|
+
* test sets it. That is not only for isolation: anything sitting at the
|
|
479
|
+
* default path was put there by a real loop on this machine, so a test that
|
|
480
|
+
* wrote to it would become indistinguishable from data.
|
|
481
|
+
*
|
|
482
|
+
* Returns null for a repo that is not an `owner/name` — `ghRepoTarget` is the
|
|
483
|
+
* one binding for that question and is not restated here. Null is a refusal
|
|
484
|
+
* at the caller; it is never silently replaced with the working directory's
|
|
485
|
+
* slug, which would file one pull request's rounds under another's.
|
|
486
|
+
*/
|
|
487
|
+
export function localHistoryPath(repo: string, pr: unknown): string | null {
|
|
488
|
+
const slug = ghRepoTarget(repo);
|
|
489
|
+
if (slug === null) return null;
|
|
490
|
+
const n = typeof pr === "number" ? pr : typeof pr === "string" && /^[0-9]+$/.test(pr.trim()) ? Number.parseInt(pr.trim(), 10) : null;
|
|
491
|
+
if (n === null || !Number.isSafeInteger(n) || n < 1) return null;
|
|
492
|
+
const base =
|
|
493
|
+
process.env.RUNGATE_LOCAL_REVIEW_HISTORY ||
|
|
494
|
+
process.env.RUNGATE_WORK_DIR ||
|
|
495
|
+
process.env.PAI_WORK_DIR ||
|
|
496
|
+
join(homedir(), ".rungate");
|
|
497
|
+
return join(base, "local-review", slug.replace("/", "__"), `pr-${n}.json`);
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
/**
|
|
501
|
+
* May the loop run another round?
|
|
502
|
+
*
|
|
503
|
+
* The ONE binding for that question, so the CLI's exit code and any other
|
|
504
|
+
* caller cannot drift apart. Only `CONTINUE` is a yes — `UNMEASURED` is a no,
|
|
505
|
+
* because a history nobody could read is not a budget with room left in it.
|
|
506
|
+
*/
|
|
507
|
+
export function runAnotherRound(reading: LocalRoundReading): boolean {
|
|
508
|
+
return reading.decision === LOCAL_REVIEW_CONTINUE;
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
/** One line for a human watching the loop. */
|
|
512
|
+
export function summarise(reading: LocalRoundReading): string {
|
|
513
|
+
const where = reading.round === null ? "round unknown" : `round ${reading.round}`;
|
|
514
|
+
return `${reading.decision} (${where}) — ${reading.reason}`;
|
|
515
|
+
}
|
|
516
|
+
|
|
517
|
+
function describe(v: unknown): string {
|
|
518
|
+
if (v === undefined) return "nothing";
|
|
519
|
+
if (v === null) return "null";
|
|
520
|
+
if (Array.isArray(v)) return `an array of ${v.length}`;
|
|
521
|
+
if (typeof v === "object") return "an object";
|
|
522
|
+
return JSON.stringify(v);
|
|
523
|
+
}
|
package/lib/organize.ts
CHANGED
|
@@ -22,6 +22,7 @@ import {
|
|
|
22
22
|
import { join, relative, dirname, basename } from "path";
|
|
23
23
|
import { loadComplianceConfig, type OrganizeExternalSource } from "./config-loader.js";
|
|
24
24
|
import { matchesAnyAlias, projectAliases } from "./project-aliases.js";
|
|
25
|
+
import { maySpecBeReplaced, writeSpec } from "./write-spec";
|
|
25
26
|
|
|
26
27
|
// ── Types ────────────────────────────────────────────────────────
|
|
27
28
|
|
|
@@ -482,6 +483,17 @@ function executeProposals(root: string, proposals: OrganizeProposal[]): void {
|
|
|
482
483
|
|
|
483
484
|
if (!existsSync(srcPath)) continue;
|
|
484
485
|
|
|
486
|
+
// #1552: `renameSync` below REPLACES its destination silently, and
|
|
487
|
+
// `organizeProjectReport` picks a target from the filename alone — a
|
|
488
|
+
// stray `API-SPEC.md` at the root is proposed onto `specs/API-SPEC.md`,
|
|
489
|
+
// annihilating a generator-owned spec without any write primitive ever
|
|
490
|
+
// touching it. Ask who owns the destination, not the source.
|
|
491
|
+
const dest = maySpecBeReplaced(tgtPath, { label: proposal.target });
|
|
492
|
+
if (!dest.allowed) {
|
|
493
|
+
console.warn(dest.refusal!);
|
|
494
|
+
continue;
|
|
495
|
+
}
|
|
496
|
+
|
|
485
497
|
const tgtDir = dirname(tgtPath);
|
|
486
498
|
if (!existsSync(tgtDir)) {
|
|
487
499
|
mkdirSync(tgtDir, { recursive: true });
|
|
@@ -551,8 +563,16 @@ function updateInternalReferences(root: string, moveMap: Map<string, string>): v
|
|
|
551
563
|
}
|
|
552
564
|
}
|
|
553
565
|
|
|
566
|
+
// #1286: organize moves docs into `specs/`, `docs/` and `reference/` and
|
|
567
|
+
// then rewrites links INSIDE them. A moved file can be a spec a generator
|
|
568
|
+
// owns, and rewriting its links is discarded at the next regeneration.
|
|
569
|
+
// #1552: the refusal is no longer restated here — `writeSpec` asks the
|
|
570
|
+
// one decider and hands back the line to print. The target is a moved
|
|
571
|
+
// document, which the static sweep cannot see is a spec path, so this
|
|
572
|
+
// site is routed by hand rather than because a check demanded it.
|
|
554
573
|
if (changed) {
|
|
555
|
-
|
|
574
|
+
const result = writeSpec(fullPath, content, { label: newPath });
|
|
575
|
+
if (result.refusal) console.warn(result.refusal);
|
|
556
576
|
}
|
|
557
577
|
}
|
|
558
578
|
}
|
|
@@ -186,6 +186,20 @@ export interface SessionSelection<T> {
|
|
|
186
186
|
|
|
187
187
|
const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})\b/;
|
|
188
188
|
|
|
189
|
+
/**
|
|
190
|
+
* The session number inside a free-form `date` — `2026-10-24 session 62`.
|
|
191
|
+
*
|
|
192
|
+
* This is the only field in the entry that tells two sessions on one calendar
|
|
193
|
+
* day apart, so it is the second sort key (#1517). 50 of the live file's 51
|
|
194
|
+
* entries carry one; the exception is `2026-10-06 AFK pipeline-readiness run`,
|
|
195
|
+
* which is dated and unnumbered and therefore ranks below every numbered
|
|
196
|
+
* session on its day rather than being treated as unorderable.
|
|
197
|
+
*/
|
|
198
|
+
const SESSION_NUMBER = /\bsession\s+(\d+)/i;
|
|
199
|
+
|
|
200
|
+
/** Ranks below every real session number. No session is numbered below 1. */
|
|
201
|
+
const UNNUMBERED = -1;
|
|
202
|
+
|
|
189
203
|
/**
|
|
190
204
|
* The `limit` NEWEST sessions, chosen by date (#572).
|
|
191
205
|
*
|
|
@@ -204,8 +218,38 @@ const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})\b/;
|
|
|
204
218
|
* position. Choosing by date removes the position from the question
|
|
205
219
|
* entirely, so where an entry is written stops mattering.
|
|
206
220
|
*
|
|
207
|
-
*
|
|
208
|
-
*
|
|
221
|
+
* Two sessions on one day are ordered by their session number, not by where
|
|
222
|
+
* they sit in the array (#1517). The date alone tied them, and the tie-break
|
|
223
|
+
* was `b.i - a.i` — later index first — so `main` rendered `session 61` above
|
|
224
|
+
* `session 62`.
|
|
225
|
+
*
|
|
226
|
+
* **Fixing the tie-break instead was considered and rejected.** `a.i - b.i`
|
|
227
|
+
* is one character and it repairs the reported case, but it reinstates the
|
|
228
|
+
* defect this function was written to remove: it makes correctness depend on
|
|
229
|
+
* the array having one direction, and the array does not have one. Measured
|
|
230
|
+
* on the live file at `edb12c93`: 16 adjacent pairs descend, 13 ascend, and
|
|
231
|
+
* the direction flips at index 26 — the head is newest-first as the DA writes
|
|
232
|
+
* it, the tail is append order. The case that settles it is 2026-10-23, which
|
|
233
|
+
* holds sessions 60, 58 and 59 at indices 2, 49 and 50: no function of the
|
|
234
|
+
* index alone can order that group, in either direction. It would also
|
|
235
|
+
* contradict SC-1961 — "the position in the array decides nothing" — by
|
|
236
|
+
* making position decide exactly the case that criterion never exercises.
|
|
237
|
+
*
|
|
238
|
+
* Ordering, in full:
|
|
239
|
+
*
|
|
240
|
+
* 1. ISO date, newest first.
|
|
241
|
+
* 2. Session number, highest first. An entry with a date but no number ranks
|
|
242
|
+
* below every numbered entry on its day.
|
|
243
|
+
* 3. Later array index first — the original tie-break, unchanged. It is kept,
|
|
244
|
+
* not reverted to, and only where the first two tiers have nothing to say:
|
|
245
|
+
* entries tying on date AND number, and entries that are wholly undated.
|
|
246
|
+
* It is right there for the same reason it was wrong above. Every real
|
|
247
|
+
* same-number group in the live file — `session 32`/`32b`, three rows
|
|
248
|
+
* numbered 34, two numbered 39 — is one session recorded as several rows,
|
|
249
|
+
* and all of them sit in the array's append-ordered tail, where the later
|
|
250
|
+
* index genuinely is the newer row. Making this tier stable instead breaks
|
|
251
|
+
* all four, and `sessions capped at 3, newest first` in
|
|
252
|
+
* test/update-project-state.test.ts catches it.
|
|
209
253
|
*/
|
|
210
254
|
export function selectRecentSessions<T extends { date: string }>(
|
|
211
255
|
sessions: readonly T[],
|
|
@@ -213,13 +257,20 @@ export function selectRecentSessions<T extends { date: string }>(
|
|
|
213
257
|
): SessionSelection<T> {
|
|
214
258
|
const undated: T[] = [];
|
|
215
259
|
const ranked = sessions.map((s, i) => {
|
|
216
|
-
const
|
|
260
|
+
const date = s.date ?? "";
|
|
261
|
+
const m = ISO_DATE.exec(date);
|
|
217
262
|
if (m === null) undated.push(s);
|
|
263
|
+
const n = SESSION_NUMBER.exec(date);
|
|
218
264
|
// An undated entry sorts below every dated one. `""` is less than any
|
|
219
265
|
// ISO date, so the comparison needs no second branch — and a branch
|
|
220
266
|
// that exists only for the empty case is a branch no fixture reaches.
|
|
221
|
-
|
|
267
|
+
// That still holds with the number tier below it: the date is compared
|
|
268
|
+
// first, so no session number can promote an undated entry past a dated
|
|
269
|
+
// one. Asserted, not reasoned about, in test/project-state-shape.test.ts.
|
|
270
|
+
return { s, key: m === null ? "" : m[0], seq: n === null ? UNNUMBERED : Number(n[1]), i };
|
|
222
271
|
});
|
|
223
|
-
ranked.sort((a, b) =>
|
|
272
|
+
ranked.sort((a, b) =>
|
|
273
|
+
a.key !== b.key ? (a.key < b.key ? 1 : -1) : a.seq !== b.seq ? b.seq - a.seq : b.i - a.i,
|
|
274
|
+
);
|
|
224
275
|
return { rendered: ranked.slice(0, limit).map(d => d.s), undated };
|
|
225
276
|
}
|