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
@@ -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 { mayWrite, readDerivedDeclaration, skipLine } from "./derived-spec";
25
26
 
26
27
  // ── Types ────────────────────────────────────────────────────────
27
28
 
@@ -551,6 +552,15 @@ function updateInternalReferences(root: string, moveMap: Map<string, string>): v
551
552
  }
552
553
  }
553
554
 
555
+ // #1286: organize moves docs into `specs/`, `docs/` and `reference/` and
556
+ // then rewrites links INSIDE them. A moved file can be a spec a generator
557
+ // owns, and rewriting its links is discarded at the next regeneration.
558
+ const derived = readDerivedDeclaration(content);
559
+ if (changed && !mayWrite(derived)) {
560
+ console.warn(skipLine(newPath, derived));
561
+ continue;
562
+ }
563
+
554
564
  if (changed) {
555
565
  writeFileSync(fullPath, content);
556
566
  }
@@ -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
- * Ties keep array order with the later index first, which is the only
208
- * information left when two entries share a day — and several do.
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 m = ISO_DATE.exec(s.date ?? "");
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
- return { s, key: m === null ? "" : m[0], i };
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) => (a.key === b.key ? b.i - a.i : a.key < b.key ? 1 : -1));
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
  }