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,361 @@
1
+ /**
2
+ * WHICH kind of unmeasured a review round was (#1486).
3
+ *
4
+ * `lib/ai-review-rounds.ts` already keeps apart the two facts that matter
5
+ * most: `findings: []` is a round that was read and found nothing, and
6
+ * `findings: null` is a round nobody read. `readLedger` normalises the second
7
+ * into `measured: false`, and **this module does not touch that boolean.**
8
+ * Everything downstream reads it — `summariseRoundsToPass`, `priorFindings`,
9
+ * the eval runner — and the whole of this is additive beside it.
10
+ *
11
+ * What it adds is the next question down. UNMEASURED is at least three facts
12
+ * that cost the same and are fixed differently:
13
+ *
14
+ * | state | the tell | the cure |
15
+ * |---|---|---|
16
+ * | structural decline | the action's skip line is in the FULL job log | #1455 |
17
+ * | no-payload | no skip line; the action ran and wrote nothing | #1478 |
18
+ * | unparseable payload | a payload exists and does not parse | a contract bug |
19
+ *
20
+ * A row that cannot tell them apart is a row nobody can act on, and 48 of 117
21
+ * rounds across the 45 most recent pull requests are that row (#1485) — the
22
+ * single largest identified contributor to CRC-M11's 2.65 mean
23
+ * rounds-to-pass. Scoring only the measured rounds gives 1.58.
24
+ *
25
+ * ## The reading is the FULL log, and the two cheaper readings are both wrong
26
+ *
27
+ * **Not `--log-failed`.** It returns only the FAILING step's log, and the
28
+ * skip line is emitted by a step that SUCCEEDS — `Run the AI review` carries
29
+ * `continue-on-error: true` and the action exits zero on its own
30
+ * workflow-validation guard. So grepping `--log-failed` for the marker
31
+ * returns 0 by construction. Measured on run 40047304108, a declined run:
32
+ * `--log` is 733,973 bytes and contains the marker once; `--log-failed` is 0
33
+ * bytes. That mistake has produced four wrong public statements here.
34
+ *
35
+ * **Not the clock.** #1485 measured no-payload runs at 4m11s, 4m38s, 5m35s
36
+ * and 5m05s, a decline at ~16s, and a real review at 2m16s. The clock looks
37
+ * diagnostic, separates nothing, and is the reading every reader reaches for
38
+ * first.
39
+ *
40
+ * ## Why a job cannot do this for itself, which is why this is not in the step
41
+ *
42
+ * `lib/scaffold/ai-review-step.ts` would be the obvious home: the persist
43
+ * step writes the round, so it could write the discriminator in the same
44
+ * breath. It cannot read the evidence. A later step cannot read an earlier
45
+ * step's stdout — `AI_REVIEW_APP_INSTALL_CAUSE` settled that for #803 and
46
+ * says so in its own docblock — and the Actions log endpoint does not serve a
47
+ * job that is still running: `gh run view --log` refuses an in-progress run
48
+ * outright. `test/ai-review-payload-reading.test.ts` AC-6 separately forbids
49
+ * the action's skip prose anywhere in the generated script, because a check
50
+ * cannot tell a grep from a mention.
51
+ *
52
+ * So the evidence is only available from OUTSIDE the run, after it finishes
53
+ * and before its logs expire. That is what `scripts/record-ai-review-unmeasured.ts`
54
+ * does with this module, and the urgency in #1486 is the expiry: each day a
55
+ * round goes unclassified, another population becomes permanently
56
+ * unmeasurable.
57
+ *
58
+ * ## No imports, deliberately
59
+ *
60
+ * `test/ai-review-unmeasured-split.test.ts` AC-U4 builds a mutant by copying
61
+ * this file alone into an `mkdtemp`. A relative import added here resolves to
62
+ * nothing there, the mutant fails to LOAD, and a mutant that failed to load
63
+ * reports the same zero as a guard that held —
64
+ * `.claude/rules/self-referential-tests.md`, Tier 1. AC-U7 asserts the
65
+ * property rather than leaving it as a convention.
66
+ */
67
+
68
+ /**
69
+ * The bytes `anthropics/claude-code-action` writes when its anti-tampering
70
+ * guard declines the run.
71
+ *
72
+ * QUOTED, from run 40047304108's full job log, not paraphrased and not read
73
+ * off the action's source:
74
+ *
75
+ * ```
76
+ * ##[warning]Skipping action due to workflow validation: Workflow validation
77
+ * failed. The workflow file must exist and have identical content to the
78
+ * version on the default branch.
79
+ * ```
80
+ *
81
+ * Two spellings are in circulation here and both are real — the next line of
82
+ * that same log reads `Exiting due to workflow validation skip`, which is
83
+ * what `lib/scaffold/ai-review-step.ts` quotes. This one is used because it
84
+ * is the one #1486 measured the population with, and because a classifier
85
+ * that matched both would be two deciders that agree.
86
+ *
87
+ * The negative control is the half that matters. The generated workflow
88
+ * script is echoed into the job log in full, so a marker the script happens
89
+ * to mention matches on every run. Measured 2026-10-23 over seven full logs:
90
+ * present once on all three declined runs, absent on all four that reviewed.
91
+ * The script's own spelling is hyphenated (`workflow-validation`), which is
92
+ * why it does not collide.
93
+ */
94
+ export const AI_REVIEW_DECLINE_LOG_LINE = "Skipping action due to workflow validation";
95
+
96
+ /** The full job log was obtained. */
97
+ export const AI_REVIEW_JOB_LOG_READ = "AI_REVIEW_JOB_LOG_READ";
98
+
99
+ /**
100
+ * The full job log could NOT be obtained — expired, unauthorised, the run id
101
+ * is unknown, the request failed.
102
+ *
103
+ * It is a status and not an empty string, for the reason `readLedger` keeps
104
+ * ABSENT and UNREADABLE apart: a grep that could not run and a grep that
105
+ * found nothing are the two readings this module exists to separate, and an
106
+ * empty string is a perfectly good log of a run that was declined.
107
+ */
108
+ export const AI_REVIEW_JOB_LOG_UNREADABLE = "AI_REVIEW_JOB_LOG_UNREADABLE";
109
+
110
+ export type JobLogReading =
111
+ | { status: typeof AI_REVIEW_JOB_LOG_READ; text: string }
112
+ | { status: typeof AI_REVIEW_JOB_LOG_UNREADABLE; reason: string };
113
+
114
+ /** The action declined on its own workflow-validation guard. #1455's state. */
115
+ export const AI_REVIEW_UNMEASURED_DECLINED = "declined";
116
+
117
+ /**
118
+ * The action was not declined, ran, and no review came out of it. #1478's
119
+ * state.
120
+ *
121
+ * **Its boundary is honest and it is wider than its name.** This is the
122
+ * reading "a readable log with no skip line in it", so it also catches the
123
+ * third row of the table above — a payload that existed and did not parse —
124
+ * because that round is `findings: null` too and its log carries no skip
125
+ * line. Separating that needs a second positive marker, which would have to
126
+ * be one of this repository's OWN annotations rather than the action's; it is
127
+ * not done here and is recorded as the known boundary rather than hidden
128
+ * behind a confident name.
129
+ */
130
+ export const AI_REVIEW_UNMEASURED_NO_PAYLOAD = "no_payload";
131
+
132
+ /** The log could not be read, so WHICH state this round is in is unknown. */
133
+ export const AI_REVIEW_UNMEASURED_LOG_UNREADABLE = "log_unreadable";
134
+
135
+ /**
136
+ * The evidence was a shape this classifier has no rule for.
137
+ *
138
+ * #1486's first acceptance row, and the reason the field is a NAME and not a
139
+ * boolean: *"a fourth state nobody predicted must not be recorded as a
140
+ * decline."* A classifier whose last branch is `return DECLINED` or whose
141
+ * negation is written one branch too wide records a confident reading of
142
+ * something it never understood, and nothing afterwards can tell.
143
+ */
144
+ export const AI_REVIEW_UNMEASURED_UNCLASSIFIED = "unclassified";
145
+
146
+ /**
147
+ * The round carries no discriminator at all.
148
+ *
149
+ * Reader-side only — nothing ever WRITES this. It is every round written
150
+ * before #1486, and it is a fourth thing that is true: the discriminator was
151
+ * not recorded. Not a decline, not a no-payload, and not "the log could not
152
+ * be read" either, because nobody tried.
153
+ */
154
+ export const AI_REVIEW_UNMEASURED_NOT_RECORDED = "not_recorded";
155
+
156
+ /**
157
+ * The round carries a discriminator this reader does not know.
158
+ *
159
+ * Reader-side only. The same one-sided safety `AI_REVIEW_LEDGER_IDENTITY`
160
+ * buys: a later version of this module may add a state, and a ledger written
161
+ * by it must not be read under a rule that predates it. An unknown value
162
+ * reads as unknown rather than as the nearest thing.
163
+ */
164
+ export const AI_REVIEW_UNMEASURED_UNRECOGNISED = "unrecognised";
165
+
166
+ /** The four states this module can WRITE. */
167
+ export type UnmeasuredState =
168
+ | typeof AI_REVIEW_UNMEASURED_DECLINED
169
+ | typeof AI_REVIEW_UNMEASURED_NO_PAYLOAD
170
+ | typeof AI_REVIEW_UNMEASURED_LOG_UNREADABLE
171
+ | typeof AI_REVIEW_UNMEASURED_UNCLASSIFIED;
172
+
173
+ /** Everything a READER of a ledger round can meet, including the two above. */
174
+ export type RecordedUnmeasuredState =
175
+ | UnmeasuredState
176
+ | typeof AI_REVIEW_UNMEASURED_NOT_RECORDED
177
+ | typeof AI_REVIEW_UNMEASURED_UNRECOGNISED;
178
+
179
+ /** The closed set, so the reader can refuse anything outside it by name. */
180
+ const WRITABLE_STATES: readonly string[] = [
181
+ AI_REVIEW_UNMEASURED_DECLINED,
182
+ AI_REVIEW_UNMEASURED_NO_PAYLOAD,
183
+ AI_REVIEW_UNMEASURED_LOG_UNREADABLE,
184
+ AI_REVIEW_UNMEASURED_UNCLASSIFIED,
185
+ ];
186
+
187
+ /**
188
+ * The key the discriminator hangs off a ledger round under.
189
+ *
190
+ * Additive beside `findings`, never instead of it. A round carries
191
+ * `findings: null` exactly as before and this key beside it, so a reader that
192
+ * has never heard of #1486 behaves identically.
193
+ */
194
+ export const AI_REVIEW_LEDGER_UNMEASURED_KEY = "unmeasured";
195
+
196
+ /**
197
+ * Which kind of unmeasured round this is, from the FULL job log.
198
+ *
199
+ * THE SINGLE DECISION SITE. Every state recorded anywhere comes through this
200
+ * function, which is what makes `test/ai-review-unmeasured-split.test.ts`
201
+ * AC-U4's mutation a mutation of the whole feature: a caller that greps the
202
+ * log itself would bypass it, and the case would go green having witnessed a
203
+ * classifier it never ran. AC-U4 asserts the signature appears exactly once
204
+ * in this file for the same reason `SECURITY_REREVIEW_EXHAUSTED` asserts it
205
+ * about its own name.
206
+ *
207
+ * FAILS TOWARD UNCLASSIFIED. The order of the branches below is load-bearing:
208
+ * the unreadable reading is answered before anything looks for the marker, so
209
+ * "I could not grep" can never arrive at "I grepped and found nothing", and
210
+ * the final `return` is the no-payload reading only for an input that has
211
+ * already been established as a readable log with a string body.
212
+ */
213
+ export function classifyUnmeasuredRound(reading: unknown): UnmeasuredState {
214
+ if (typeof reading !== "object" || reading === null || Array.isArray(reading)) {
215
+ return AI_REVIEW_UNMEASURED_UNCLASSIFIED;
216
+ }
217
+ const r = reading as Record<string, unknown>;
218
+ if (r.status === AI_REVIEW_JOB_LOG_UNREADABLE) return AI_REVIEW_UNMEASURED_LOG_UNREADABLE;
219
+ if (r.status !== AI_REVIEW_JOB_LOG_READ) return AI_REVIEW_UNMEASURED_UNCLASSIFIED;
220
+ // A READ reading whose body is not text is not an empty log. It is a
221
+ // reading that claims to have succeeded and carries nothing, which is a
222
+ // shape nobody wrote a rule for — and calling it no-payload would be the
223
+ // same substitution one field over.
224
+ if (typeof r.text !== "string") return AI_REVIEW_UNMEASURED_UNCLASSIFIED;
225
+ if (r.text.includes(AI_REVIEW_DECLINE_LOG_LINE)) return AI_REVIEW_UNMEASURED_DECLINED;
226
+ return AI_REVIEW_UNMEASURED_NO_PAYLOAD;
227
+ }
228
+
229
+ /**
230
+ * What a ledger round says about itself, for a reader.
231
+ *
232
+ * `undefined` — no key at all — is NOT_RECORDED, which is true of every round
233
+ * written before #1486 and is a different fact from any of the four states. A
234
+ * value outside the closed set is UNRECOGNISED rather than the nearest match.
235
+ */
236
+ export function readRecordedUnmeasuredState(round: unknown): RecordedUnmeasuredState {
237
+ if (typeof round !== "object" || round === null || Array.isArray(round)) {
238
+ return AI_REVIEW_UNMEASURED_NOT_RECORDED;
239
+ }
240
+ const raw = (round as Record<string, unknown>)[AI_REVIEW_LEDGER_UNMEASURED_KEY];
241
+ if (raw === undefined) return AI_REVIEW_UNMEASURED_NOT_RECORDED;
242
+ if (typeof raw === "string" && WRITABLE_STATES.includes(raw)) {
243
+ return raw as UnmeasuredState;
244
+ }
245
+ return AI_REVIEW_UNMEASURED_UNRECOGNISED;
246
+ }
247
+
248
+ /** Is this ledger round one that recorded no review? */
249
+ function roundIsUnmeasured(round: Record<string, unknown>): boolean {
250
+ // The writer's own rule, restated rather than imported: `readLedger` calls
251
+ // a round measured exactly when its `findings` is an array. Anything else —
252
+ // `null`, absent, a string — is a round nobody read.
253
+ return !Array.isArray(round.findings);
254
+ }
255
+
256
+ export interface AnnotationReading {
257
+ /** The rounds, with the discriminator added where one was missing. */
258
+ rounds: unknown[];
259
+ /** How many rounds gained a reading on this pass. */
260
+ recorded: number;
261
+ /** State -> how many rounds now carry it, counting ones already recorded. */
262
+ counts: Record<string, number>;
263
+ }
264
+
265
+ /**
266
+ * Add the discriminator to every unmeasured round that does not have one.
267
+ *
268
+ * Synchronous and pure, with the log handed in. The fetch lives in the script
269
+ * because a function that fetches its own evidence cannot be given a negative
270
+ * control — the same argument `suppressRepeats` makes about `priorKeys`.
271
+ *
272
+ * THREE THINGS IT WILL NOT DO, and each is one of #1486's acceptance rows:
273
+ *
274
+ * - a round with a payload is untouched. No key is added at all, rather than
275
+ * a "not applicable" value: a reader asking `Object.hasOwn` gets a true
276
+ * answer, and a measured round has nothing to discriminate.
277
+ * - a round that already carries a reading is not reclassified, and does not
278
+ * even cost a log fetch. Re-running this must be free and must not let a
279
+ * later expiry overwrite a reading taken while the log still existed.
280
+ * - `findings` is never rewritten, so `measured` is what it always was.
281
+ */
282
+ export function annotateUnmeasuredRounds(
283
+ rounds: readonly unknown[],
284
+ evidenceFor: (round: Record<string, unknown>, index: number) => unknown,
285
+ ): AnnotationReading {
286
+ const out: unknown[] = [];
287
+ const counts: Record<string, number> = {};
288
+ let recorded = 0;
289
+
290
+ rounds.forEach((raw, i) => {
291
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
292
+ // A round entry that is not an object is one `readLedger` already
293
+ // counts and cannot read. Passed through byte-for-byte: this is a
294
+ // recorder, and dropping an entry it does not understand would shorten
295
+ // the history it exists to preserve.
296
+ out.push(raw);
297
+ return;
298
+ }
299
+ const round = raw as Record<string, unknown>;
300
+ if (!roundIsUnmeasured(round)) {
301
+ out.push(round);
302
+ return;
303
+ }
304
+ const existing = readRecordedUnmeasuredState(round);
305
+ if (existing !== AI_REVIEW_UNMEASURED_NOT_RECORDED) {
306
+ counts[existing] = (counts[existing] ?? 0) + 1;
307
+ out.push(round);
308
+ return;
309
+ }
310
+ const state = classifyUnmeasuredRound(evidenceFor(round, i));
311
+ counts[state] = (counts[state] ?? 0) + 1;
312
+ recorded++;
313
+ out.push({ ...round, [AI_REVIEW_LEDGER_UNMEASURED_KEY]: state });
314
+ });
315
+
316
+ return { rounds: out, recorded, counts };
317
+ }
318
+
319
+ /** The fence the ledger's machine-readable half sits inside. */
320
+ const LEDGER_FENCE = "```json";
321
+
322
+ /**
323
+ * Put a rewritten rounds document back into a ledger comment body, touching
324
+ * nothing outside the fenced block.
325
+ *
326
+ * `null` when the block cannot be located, and the caller must treat that as
327
+ * a REFUSAL rather than as a licence to compose a fresh body. A ledger
328
+ * holding seven rounds replaced by one holding this pass is the worst thing
329
+ * any writer here can do and is indistinguishable from a first round
330
+ * afterwards — the rule `buildPersistScript` is built around, restated for a
331
+ * writer that runs outside the job.
332
+ *
333
+ * It is a SPLICE, not a re-render. The prose above and below the fence is
334
+ * whatever the persist step wrote, including anything a later version of it
335
+ * adds, and a rewrite that regenerated the whole comment would silently
336
+ * discard it.
337
+ *
338
+ * The fence-finding here is deliberately the same shape as `readLedger`'s and
339
+ * is therefore a second reader of the same bytes. That is a risk this module
340
+ * cannot remove — it may not import `lib/ai-review-rounds.ts`, for the reason
341
+ * the header gives — so it is closed at the call site instead:
342
+ * `scripts/record-ai-review-unmeasured.ts` runs the real `readLedger` over
343
+ * the spliced body and refuses to send it unless the rounds read back.
344
+ */
345
+ export function replaceLedgerJsonBlock(body: unknown, doc: unknown): string | null {
346
+ if (typeof body !== "string") return null;
347
+ const fence = body.indexOf(LEDGER_FENCE);
348
+ if (fence === -1) return null;
349
+ const start = body.indexOf("\n", fence);
350
+ if (start === -1) return null;
351
+ const close = body.indexOf("\n```", start);
352
+ if (close === -1) return null;
353
+ // COMPACT, because `buildPersistScript` writes it with `jq -c` and the
354
+ // ledger is a 12-round window sized against GitHub's 65,536-character
355
+ // comment body limit. Pretty-printing inflates every round, so a rewrite
356
+ // that re-serialised with an indent would make the window start evicting
357
+ // earlier — and an eviction brought on by whitespace is indistinguishable
358
+ // from the ordinary truncation the `truncated` count describes. Caught on
359
+ // #1487 after the first real write, which did exactly that.
360
+ return `${body.slice(0, start + 1)}${JSON.stringify(doc)}${body.slice(close)}`;
361
+ }