rungate 0.2.1 → 0.4.0

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 (129) hide show
  1. package/bin/rungate.ts +70 -0
  2. package/lib/aes-calculator.ts +66 -0
  3. package/lib/agent-audit.ts +139 -0
  4. package/lib/agent-brief-validation.ts +359 -0
  5. package/lib/agents-md-refs.ts +90 -0
  6. package/lib/bash-file-read.ts +197 -0
  7. package/lib/behavioral-cache.ts +78 -0
  8. package/lib/branch-cleanup.ts +234 -0
  9. package/lib/brief-context-parser.ts +35 -0
  10. package/lib/brief-precedence.ts +114 -0
  11. package/lib/canary.ts +117 -0
  12. package/lib/check-registry.ts +226 -0
  13. package/lib/ci-checkout.ts +426 -0
  14. package/lib/cli-commands.ts +137 -0
  15. package/lib/compliance-backfill.ts +232 -0
  16. package/lib/compliance-report.ts +605 -0
  17. package/lib/compliance.ts +361 -0
  18. package/lib/config-loader.ts +255 -0
  19. package/lib/config-readers.ts +86 -0
  20. package/lib/conformity.ts +2161 -137
  21. package/lib/container-provenance.ts +230 -0
  22. package/lib/create-brief.ts +150 -0
  23. package/lib/create-sc.ts +267 -0
  24. package/lib/decomposition-waves.ts +197 -0
  25. package/lib/deep-merge.ts +69 -0
  26. package/lib/dev-liveness.ts +214 -0
  27. package/lib/directive-extractor.ts +210 -0
  28. package/lib/distribution-standing.ts +113 -0
  29. package/lib/doc-hygiene.ts +238 -0
  30. package/lib/eval-criteria.ts +6 -0
  31. package/lib/evidence-portability.ts +123 -0
  32. package/lib/evidence-prevalidator.ts +390 -0
  33. package/lib/evidence-required.ts +150 -0
  34. package/lib/evidence-satisfiability.ts +288 -0
  35. package/lib/frontmatter.ts +163 -0
  36. package/lib/gap-scanner.ts +348 -0
  37. package/lib/gate-check-audit.ts +190 -0
  38. package/lib/gate-enforcement.ts +366 -0
  39. package/lib/generators/agent-briefs.ts +136 -0
  40. package/lib/generators/agents-md.ts +511 -0
  41. package/lib/generators/code-map.ts +60 -0
  42. package/lib/generators/types.ts +184 -0
  43. package/lib/git-ref-normalizer.ts +107 -0
  44. package/lib/github.ts +539 -0
  45. package/lib/harness-identity.ts +63 -0
  46. package/lib/hill-climb.ts +164 -0
  47. package/lib/instruction-effectiveness.ts +131 -0
  48. package/lib/issue-closure-audit.ts +225 -0
  49. package/lib/issue-create-override.ts +343 -0
  50. package/lib/issue-extraction.ts +368 -0
  51. package/lib/js-top-level-code.ts +250 -0
  52. package/lib/liveness-contradiction.ts +149 -0
  53. package/lib/organize.ts +505 -0
  54. package/lib/paths.ts +197 -6
  55. package/lib/phase2-decomposition.ts +270 -0
  56. package/lib/post-fix-verify.ts +157 -0
  57. package/lib/prior-branch.ts +512 -0
  58. package/lib/project-state-shape.ts +166 -0
  59. package/lib/promote-outputs.ts +156 -0
  60. package/lib/prove-label-gate.ts +128 -0
  61. package/lib/reachability.ts +302 -0
  62. package/lib/release-preflight.ts +288 -0
  63. package/lib/rule-health-pipeline.ts +264 -0
  64. package/lib/rule-health-trend.ts +161 -0
  65. package/lib/rule-provenance.ts +149 -0
  66. package/lib/rule-registry.ts +128 -0
  67. package/lib/rungate-schema.ts +127 -5
  68. package/lib/sc-claim-forms.ts +179 -0
  69. package/lib/sc-cover.ts +150 -0
  70. package/lib/sc-guard.ts +157 -0
  71. package/lib/sc-ids.ts +344 -0
  72. package/lib/scaffold/defaults.ts +165 -0
  73. package/lib/scaffold/managed-workflow.ts +370 -0
  74. package/lib/scaffold/owned-files.ts +265 -0
  75. package/lib/scaffold/pre-push-hook.ts +165 -0
  76. package/lib/scaffold/steps.ts +2621 -0
  77. package/lib/scanner.ts +701 -0
  78. package/lib/scope-denylist.ts +258 -0
  79. package/lib/screenshot-upload.ts +73 -0
  80. package/lib/secret-patterns.ts +112 -0
  81. package/lib/security-verdict.ts +616 -0
  82. package/lib/signal-phrases.ts +1 -0
  83. package/lib/spec-change-conformity.ts +80 -0
  84. package/lib/spec-files.ts +62 -0
  85. package/lib/spec-registry.ts +133 -0
  86. package/lib/spec-updater.ts +96 -0
  87. package/lib/stale-cleanup.ts +224 -0
  88. package/lib/stale-issue-scanner.ts +36 -0
  89. package/lib/strip-js-comments.ts +269 -0
  90. package/lib/suite-measurement.ts +228 -0
  91. package/lib/task-completion-checks.ts +224 -0
  92. package/lib/test-suite-lock.ts +1136 -0
  93. package/lib/transcript-checker.ts +1140 -0
  94. package/lib/typescript-project.ts +233 -0
  95. package/lib/validators/spec-validators.ts +171 -0
  96. package/lib/verdict-capture.ts +73 -0
  97. package/lib/verified-push.ts +535 -0
  98. package/lib/workflow-security.ts +174 -0
  99. package/lib/worktree-cleanup.ts +432 -0
  100. package/lib/worktree-collect.ts +283 -0
  101. package/lib/worktree-isolation.ts +82 -0
  102. package/lib/worktree-repo.ts +300 -0
  103. package/package.json +27 -3
  104. package/prompts/ac-adversary.md +14 -2
  105. package/prompts/aditi.md +5 -0
  106. package/prompts/blast-radius.md +5 -0
  107. package/prompts/container-verify.md +5 -0
  108. package/prompts/discovery.md +4 -0
  109. package/prompts/environment.md +5 -0
  110. package/prompts/evidence-hierarchy.md +5 -0
  111. package/prompts/evidence-validator.md +11 -0
  112. package/prompts/marcus.md +5 -0
  113. package/prompts/prevention.md +5 -0
  114. package/prompts/prove-reproducer.md +12 -0
  115. package/prompts/quinn-decision-tree.md +5 -0
  116. package/prompts/quinn-ui-brief.md +5 -0
  117. package/prompts/quinn.md +5 -0
  118. package/prompts/rca.md +5 -0
  119. package/prompts/read-before-write.md +4 -0
  120. package/prompts/regression.md +5 -0
  121. package/prompts/serena.md +5 -0
  122. package/scripts/audit-specs.ts +464 -0
  123. package/scripts/convert-spec.ts +293 -0
  124. package/scripts/create-sc.ts +92 -0
  125. package/scripts/create-spec.ts +166 -0
  126. package/scripts/extract-constraints.ts +4 -3
  127. package/scripts/generate-code-map.ts +1 -1
  128. package/scripts/scaffold-project.ts +138 -1426
  129. package/scripts/sync-spec-tests.ts +211 -126
@@ -0,0 +1,616 @@
1
+ /**
2
+ * The security review's gate verdict — the thing #129 is about.
3
+ *
4
+ * Twice in production rook returned `{"result":"FAIL"}` with a reproduced HIGH
5
+ * guard bypass and the workflow returned SHIPPED and opened a PR. The verdict
6
+ * was computed, logged and graded; nothing that could stop the run ever read
7
+ * it. A review whose verdict goes nowhere is worse than no review, because it
8
+ * manufactures the appearance of coverage.
9
+ *
10
+ * SOURCE OF TRUTH. `workflows/ship.js` carries inlined copies of every
11
+ * function below — `rookReviewSha`, `rookScopeCommand`, `rookGateVerdict` and
12
+ * `reviewIsCurrent` — because the Workflow sandbox provides no module loading
13
+ * — a top-level `require()` there killed every ship run before it spawned a
14
+ * single agent (#69). The copies must stay behaviourally identical to these:
15
+ * test/security-verdict-blocks.test.ts runs both over the same input matrix
16
+ * and fails on any divergence. Change one, change the other.
17
+ *
18
+ * The same duplication has already drifted once in this repo — computeACHash
19
+ * sorted its input and the inlined copy did not, so the "extracted" function
20
+ * had never matched the code it replaced. That is what the agreement test is
21
+ * for.
22
+ */
23
+
24
+ /** A commit SHA: 7-40 hex, case-insensitive. Normalised to lowercase. */
25
+ const SHA = /^[0-9a-f]{7,40}$/i;
26
+
27
+ export interface SecurityVerdict {
28
+ /** Whether the security agent returned anything at all. */
29
+ spawned: boolean;
30
+ /** PASS only when a real scope was reviewed and the reviewer passed it. */
31
+ verdict: "PASS" | "FAIL";
32
+ /** One entry per blocking problem. Non-empty whenever verdict is FAIL. */
33
+ failures: string[];
34
+ /**
35
+ * Present only when this PASS replaced an earlier FAIL (#244). What the
36
+ * findings were, which commit they were about, and which review cleared
37
+ * them.
38
+ *
39
+ * A verdict is never overwritten wholesale. The first attempt at #244
40
+ * (`46034035`, reverted by `44ac641d`) assigned the re-review's result over
41
+ * `securityVerdict` and the original findings stopped existing — so a
42
+ * reader of the run could not tell a branch that had never been flagged
43
+ * from one whose findings were erased by a review that never read them.
44
+ */
45
+ cleared?: ClearedFindings;
46
+ }
47
+
48
+ /** The record a cleared stale FAIL leaves behind (#244, SC-4). */
49
+ export interface ClearedFindings {
50
+ /** Always FAIL — there is nothing else a clearing can undo. */
51
+ priorVerdict: "FAIL";
52
+ /** The findings the earlier review raised, verbatim. */
53
+ priorFailures: string[];
54
+ /** The commit they were about. Null when it was never readable. */
55
+ priorSha: string | null;
56
+ /** The commit the clearing review read. */
57
+ clearedBySha: string;
58
+ /** Which re-review round cleared it. */
59
+ clearedByRound: number;
60
+ /** Always `full`. A diff-scoped review may not clear a FAIL — see resolveReReview. */
61
+ scope: typeof REVIEW_SCOPE_FULL;
62
+ }
63
+
64
+ /**
65
+ * The commit the review is pinned to, or null.
66
+ *
67
+ * The value this is given comes back from an agent, so it is validated before
68
+ * it is interpolated anywhere. Returning null rather than a fallback is the
69
+ * point: there is no safe default commit to review, and "review HEAD" is
70
+ * precisely the bug — rook's worktree is cut from origin/main, so HEAD there
71
+ * yields an empty diff.
72
+ */
73
+ export function rookReviewSha(value: unknown): string | null {
74
+ if (typeof value !== "string") return null;
75
+ const trimmed = value.trim();
76
+ return SHA.test(trimmed) ? trimmed.toLowerCase() : null;
77
+ }
78
+
79
+ export interface ReviewCurrency {
80
+ /** True only when both SHAs are real and name the same commit. */
81
+ current: boolean;
82
+ /** Why the review is not current. Null — and only null — when it is. */
83
+ reason: string | null;
84
+ }
85
+
86
+ /**
87
+ * Does the recorded security review still describe the commit the run ends at?
88
+ *
89
+ * #129 gave the review a real scope and made its verdict block the run. It did
90
+ * not make the verdict follow the branch. On the #164 run `agents.rook.testedSha`
91
+ * was 3fe336f1 while the branch tip was ef998b73, and the diff between them
92
+ * rewrote all four files rook had reviewed — 236 insertions, 254 deletions. The
93
+ * review was real, it read the right files, and then those files were replaced
94
+ * by the regression remediation loop. Nothing compared the two SHAs, so the run
95
+ * reported SHIPPED carrying a PASS for code that no longer existed.
96
+ *
97
+ * FAILS CLOSED. Missing, non-string, malformed and mismatched all return
98
+ * `current: false`. There is no default-to-current branch and nothing here
99
+ * throws: this is called on the path that decides whether a run may ship, so a
100
+ * throw would be a refusal the caller's error handling could turn back into a
101
+ * ship. The reason always names both operands so the refusal says which commit
102
+ * was reviewed and which one the branch ended at.
103
+ *
104
+ * An abbreviation counts as a match in either direction, because the two values
105
+ * reach this function from different places — `testedSha` comes back through an
106
+ * agent via the scope report, `headSha` from `git rev-parse` — and either may be
107
+ * shortened. Prefix matching is deliberately not symmetric-length: `3fe336f1`
108
+ * against `3192a75c...` shares no prefix and is stale, which is exactly the #164
109
+ * case. Two full SHAs are a prefix of each other only when equal.
110
+ */
111
+ export function reviewIsCurrent(testedSha: unknown, headSha: unknown): ReviewCurrency {
112
+ const tested = rookReviewSha(testedSha);
113
+ const head = rookReviewSha(headSha);
114
+
115
+ if (!tested && !head) {
116
+ return {
117
+ current: false,
118
+ reason:
119
+ `no security review is current: the tested commit is ${describe(testedSha)} and ` +
120
+ `the head commit is ${describe(headSha)} — neither is a commit SHA, so there is ` +
121
+ `nothing to compare`,
122
+ };
123
+ }
124
+ if (!tested) {
125
+ return {
126
+ current: false,
127
+ reason:
128
+ `no security review is current: the tested commit is ${describe(testedSha)}, not a ` +
129
+ `commit SHA, so it cannot be compared against head ${head}`,
130
+ };
131
+ }
132
+ if (!head) {
133
+ return {
134
+ current: false,
135
+ reason:
136
+ `no security review is current: the head commit is ${describe(headSha)}, not a ` +
137
+ `commit SHA, so the review pinned to ${tested} cannot be confirmed against it`,
138
+ };
139
+ }
140
+
141
+ const abbreviates = tested.startsWith(head) || head.startsWith(tested);
142
+ if (!abbreviates) {
143
+ return {
144
+ current: false,
145
+ reason:
146
+ `the security review is stale: it was pinned to ${tested} but the branch now ends ` +
147
+ `at ${head} — the reviewed code is not the code this run would ship`,
148
+ };
149
+ }
150
+
151
+ return { current: true, reason: null };
152
+ }
153
+
154
+ /** The review still describes the commit the branch ends at. Nothing re-runs. */
155
+ export const REVIEW_CURRENT = "CURRENT";
156
+ /** The review is stale and a re-review round remains. Rook runs again. */
157
+ export const RE_REVIEW = "RE_REVIEW";
158
+ /**
159
+ * The review is stale, or unreadable, and there is no round left to fix it.
160
+ *
161
+ * DECLARED ONCE, as an exported constant, and asserted to be spelled once in
162
+ * this file by test/security-verdict-blocks.test.ts. A second spelling is a
163
+ * second refusal path, reachable by code the first one's tests never visit —
164
+ * which is how a refusal comes to exist that nothing has ever proved can fire.
165
+ */
166
+ export const SECURITY_REREVIEW_EXHAUSTED = "SECURITY_REREVIEW_EXHAUSTED";
167
+
168
+ export type ReReviewDecision =
169
+ | typeof REVIEW_CURRENT
170
+ | typeof RE_REVIEW
171
+ | typeof SECURITY_REREVIEW_EXHAUSTED;
172
+
173
+ export interface ReReviewOutcome {
174
+ /** Exactly one of the three verdicts above. */
175
+ decision: ReReviewDecision;
176
+ /** Why the review is not current. Null — and only null — when it is. */
177
+ reason: string | null;
178
+ }
179
+
180
+ /**
181
+ * Is a value a ReviewCurrency, read strictly enough to act on?
182
+ *
183
+ * Returns null for anything that is not one, including the two self-
184
+ * contradictory shapes: current with a reason attached, and stale without one.
185
+ * Neither is a currency a decision can be built from — "current, and here is
186
+ * why it is not" is the same contradiction as a PASS carrying broken ids, and
187
+ * reading it as either answer picks one of the two things it says at random.
188
+ *
189
+ * Wrapped in try/catch because the value reaches here through the workflow from
190
+ * an agent's report, and a property access on a hostile or half-parsed object
191
+ * can throw. A throw on this path is a refusal the caller's error handling can
192
+ * turn back into a ship.
193
+ */
194
+ function readCurrency(v: unknown): ReviewCurrency | null {
195
+ try {
196
+ if (!isRecord(v)) return null;
197
+ const current = v.current;
198
+ const reason = v.reason;
199
+ if (typeof current !== "boolean") return null;
200
+ if (current) return reason === null ? { current: true, reason: null } : null;
201
+ if (typeof reason !== "string" || reason.trim() === "") return null;
202
+ return { current: false, reason };
203
+ } catch {
204
+ return null;
205
+ }
206
+ }
207
+
208
+ /** A usable count of rounds: a non-negative integer, and nothing else. */
209
+ function readCount(v: unknown): number | null {
210
+ if (typeof v !== "number") return null;
211
+ if (!Number.isInteger(v)) return null; // NaN, Infinity and 1.5 all land here
212
+ if (v < 0) return null;
213
+ return v;
214
+ }
215
+
216
+ /**
217
+ * Should the stale review be re-run, or is the run out of rope? (#171)
218
+ *
219
+ * #169 made a stale review stop the run. Stopping is correct and it is also
220
+ * not the whole story: every #164-shaped run ends at SHIP_FAILED with a branch
221
+ * that is one review away from shippable. Run `wf_6fbfa028-14e` on #239 spent
222
+ * 87.7 minutes and 1,287,510 subagent tokens across 22 agents and merged
223
+ * nothing — rook passed, and the verify gate's self-heal loop then committed
224
+ * 992 insertions over the reviewed commit. That loop fires whenever the first
225
+ * verify attempt leaves anything to fix, so a refusal there makes the common
226
+ * path the failing one.
227
+ *
228
+ * This is the function that decides whether one more review is worth spending,
229
+ * and it returns exactly one of the three verdict constants above:
230
+ * REVIEW_CURRENT, RE_REVIEW, or the exhaustion one. (Spelled without quotes or
231
+ * backticks on purpose — a test asserts the exhaustion name appears in a string
232
+ * literal exactly once in this file, and prose that quotes it is a second
233
+ * spelling the assertion cannot distinguish from a second declaration.)
234
+ *
235
+ * FAILS CLOSED. Anything it cannot read positively as "stale, with a round
236
+ * still available" is the exhaustion verdict: an unreadable currency, an
237
+ * unreadable count, a cap of zero, a spend at or past the cap. A budget nobody
238
+ * can read is not a budget with room left in it.
239
+ */
240
+ export function reReviewDecision(
241
+ currency: unknown,
242
+ roundsSpent: unknown,
243
+ maxRounds: unknown,
244
+ ): ReReviewOutcome {
245
+ const read = readCurrency(currency);
246
+ if (!read) {
247
+ return {
248
+ decision: SECURITY_REREVIEW_EXHAUSTED,
249
+ reason:
250
+ `the review-currency reading is ${describe(currency)}, not an answer about a commit — ` +
251
+ `there is nothing a re-review could be aimed at, so the cycle ran out of attempts ` +
252
+ `before spending one`,
253
+ };
254
+ }
255
+ if (read.current) return { decision: REVIEW_CURRENT, reason: null };
256
+
257
+ const spent = readCount(roundsSpent);
258
+ const cap = readCount(maxRounds);
259
+ if (spent === null || cap === null) {
260
+ return {
261
+ decision: SECURITY_REREVIEW_EXHAUSTED,
262
+ reason:
263
+ `${read.reason} — and the re-review budget is unreadable ` +
264
+ `(${describe(roundsSpent)} spent of ${describe(maxRounds)}), so the cycle ran out ` +
265
+ `of attempts rather than guessing at one`,
266
+ };
267
+ }
268
+ if (spent < cap) return { decision: RE_REVIEW, reason: read.reason };
269
+
270
+ return {
271
+ decision: SECURITY_REREVIEW_EXHAUSTED,
272
+ reason:
273
+ `${read.reason} — and the re-review cycle ran out of attempts after ${spent} of ` +
274
+ `${cap} round(s), so this run ends holding code nobody reviewed`,
275
+ };
276
+ }
277
+
278
+ /**
279
+ * The command the workflow hands the scope step.
280
+ *
281
+ * Throws rather than quoting when the SHA is not a SHA. A value needing
282
+ * quoting here is not a commit SHA, and three consecutive security reviews of
283
+ * this area each found a hole in a filter that tried to sanitise its way to
284
+ * safety instead of refusing (shape allowlist → absolute paths → traversal →
285
+ * `.env`). Refusal has no fourth hole.
286
+ *
287
+ * `base` is #171's: a re-review reads the diff between the commit the previous
288
+ * review read and the tip the remediation round just pushed, so the second
289
+ * review's subject is the code that was written after the first one. It is
290
+ * refused on the same terms as `sha` — the workflow passes a recorded
291
+ * `testedSha`, and a ref name there would reintroduce the #129 empty diff one
292
+ * argument over. Omitted, the script's own `origin/main` default stands.
293
+ *
294
+ * `projectRoot`, `harnessRoot` and `outPath` are workflow-supplied constants,
295
+ * not agent output, and are interpolated as-is.
296
+ */
297
+ export function rookScopeCommand(
298
+ projectRoot: string,
299
+ harnessRoot: string,
300
+ sha: string,
301
+ outPath: string,
302
+ base?: string | null,
303
+ ): string {
304
+ const pinned = rookReviewSha(sha);
305
+ if (!pinned) {
306
+ throw new Error(
307
+ `rookScopeCommand: "${String(sha).slice(0, 80)}" is not a commit SHA — ` +
308
+ `refusing to build a scope command the review cannot be pinned to`,
309
+ );
310
+ }
311
+ let pinnedBase: string | null = null;
312
+ if (base !== undefined && base !== null && base !== "") {
313
+ pinnedBase = rookReviewSha(base);
314
+ if (!pinnedBase) {
315
+ throw new Error(
316
+ `rookScopeCommand: "${String(base).slice(0, 80)}" is not a commit SHA — ` +
317
+ `refusing to build a re-review scope command against a base it cannot pin`,
318
+ );
319
+ }
320
+ }
321
+ // Quoted even though every path here is a workflow argument rather than
322
+ // agent-reported text. ship.js:377 records an unquoted path that was
323
+ // "obviously safe" until what fed it changed, and #155's own fix introduced
324
+ // the same hole one layer out. A path with a space is the ordinary case this
325
+ // also fixes. The SHA is refused above rather than quoted: a SHA that needs
326
+ // quoting is not a SHA.
327
+ const q = (w: string) => `'${String(w).replace(/'/g, "'\\''")}'`;
328
+ return (
329
+ `cd ${q(projectRoot)} && bun ${q(`${harnessRoot}/scripts/rook-review-scope.ts`)} ` +
330
+ `--project ${q(projectRoot)} --sha ${pinned}` +
331
+ (pinnedBase ? ` --base ${pinnedBase}` : "") +
332
+ ` --out ${q(outPath)}`
333
+ );
334
+ }
335
+
336
+ function isRecord(v: unknown): v is Record<string, unknown> {
337
+ return typeof v === "object" && v !== null && !Array.isArray(v);
338
+ }
339
+
340
+ // ── A stale FAIL needs a different review than a stale PASS (#244) ───────
341
+
342
+ /** The re-review read the whole tip. Only this can clear a FAIL. */
343
+ export const REVIEW_SCOPE_FULL = "full";
344
+ /** The re-review read `base..tip` — what #171 ships for a stale PASS. */
345
+ export const REVIEW_SCOPE_DIFF = "diff";
346
+
347
+ export type ReviewScope = typeof REVIEW_SCOPE_FULL | typeof REVIEW_SCOPE_DIFF;
348
+
349
+ /**
350
+ * Was this verdict positively readable as a PASS?
351
+ *
352
+ * Deliberately narrow and deliberately one function: every decision below
353
+ * turns on it, and "not a PASS" has to include the unreadable cases rather
354
+ * than only the literal FAIL.
355
+ */
356
+ function heldIsPass(held: unknown): boolean {
357
+ return isRecord(held) && held.verdict === "PASS";
358
+ }
359
+
360
+ /**
361
+ * Which scope must the re-review use, given the verdict being carried?
362
+ *
363
+ * **This is the whole of #244.** #171's re-review is diff-scoped: it reads
364
+ * the diff between the commit the previous review read and the tip the
365
+ * remediation just pushed. That is correct for a stale PASS — the base was
366
+ * read and found clean, so only what came after needs reading.
367
+ *
368
+ * It is WRONG for a stale FAIL, and the first attempt at this issue
369
+ * (`46034035`, reverted by `44ac641d`) shipped exactly that. A background
370
+ * security review flagged it within minutes as `fail-open-security-gate`.
371
+ * The sequence:
372
+ *
373
+ * 1. Rook FAILs commit A on a finding in A.
374
+ * 2. A remediation commits B, touching something else.
375
+ * 3. The verdict is stale, so it enters the re-review loop.
376
+ * 4. Rook reads `A..B`, sees nothing wrong, returns PASS.
377
+ * 5. The run ships. The original finding was never looked at.
378
+ *
379
+ * `base..tip` does not contain the code the finding was about. So a FAIL
380
+ * gets a FULL review of the tip.
381
+ *
382
+ * FAILS CLOSED TOWARD READING MORE. Anything not positively readable as a
383
+ * PASS gets the full review — an unreadable verdict, a missing one, a string
384
+ * nobody recognises. The failure mode of being wrong here is one extra review
385
+ * of a whole tip; the failure mode of the other default is the revert above.
386
+ */
387
+ export function reReviewScope(held: unknown): ReviewScope {
388
+ return heldIsPass(held) ? REVIEW_SCOPE_DIFF : REVIEW_SCOPE_FULL;
389
+ }
390
+
391
+ /**
392
+ * The `base` argument the re-review should be pinned to, or null for a full
393
+ * review of the tip.
394
+ *
395
+ * Null is not a fallback here, it is the answer: `rookScopeCommand` omits
396
+ * `--base` when it gets one, and `scripts/rook-review-scope.ts` then reads
397
+ * the whole branch against its own `origin/main` default. That is the review
398
+ * a stale FAIL requires.
399
+ */
400
+ export function reReviewBaseFor(held: unknown, testedSha: unknown): string | null {
401
+ if (reReviewScope(held) === REVIEW_SCOPE_FULL) return null;
402
+ return rookReviewSha(testedSha);
403
+ }
404
+
405
+ /**
406
+ * The verdict a run holds after one re-review round. Never a wholesale
407
+ * overwrite (#244, SC-4).
408
+ *
409
+ * Four cases, and the third is the one the revert exists to prevent:
410
+ *
411
+ * - the re-review returned nothing → FAIL, naming that
412
+ * - the re-review returned FAIL → that FAIL, with its own findings
413
+ * - a FAIL cleared by a DIFF-scoped pass → **FAIL**, refusing the clearing
414
+ * - a FAIL cleared by a FULL pass → PASS carrying `cleared`
415
+ *
416
+ * The third case cannot be reached through `reReviewBaseFor`, which already
417
+ * returns null for a FAIL. It is checked anyway, because the two decisions
418
+ * are made in different places and a later change to the base selection would
419
+ * otherwise reopen `46034035` with nothing in the way. A security clearing is
420
+ * not somewhere to rely on an invariant holding one call site away.
421
+ */
422
+ export function resolveReReview(
423
+ held: unknown,
424
+ reReviewed: unknown,
425
+ scope: unknown,
426
+ round: number,
427
+ priorSha?: unknown,
428
+ reviewedSha?: unknown,
429
+ ): SecurityVerdict {
430
+ const fresh = isRecord(reReviewed) ? reReviewed : null;
431
+ const spawned = fresh?.spawned === true;
432
+ const failures = Array.isArray(fresh?.failures)
433
+ ? fresh.failures.map(f => String(f)).filter(f => f.trim() !== "")
434
+ : [];
435
+
436
+ if (!fresh || (fresh.verdict !== "PASS" && fresh.verdict !== "FAIL")) {
437
+ return {
438
+ spawned,
439
+ verdict: "FAIL",
440
+ failures: [
441
+ `the re-review returned ${describe(isRecord(reReviewed) ? reReviewed.verdict : reReviewed)}, ` +
442
+ `not a verdict — round ${round} cleared nothing`,
443
+ ],
444
+ };
445
+ }
446
+
447
+ if (fresh.verdict === "FAIL") {
448
+ return {
449
+ spawned,
450
+ verdict: "FAIL",
451
+ failures: failures.length > 0
452
+ ? failures
453
+ : [`the re-review returned FAIL with no findings attached — round ${round}`],
454
+ };
455
+ }
456
+
457
+ // A PASS replacing a PASS is #171's case and carries nothing extra.
458
+ if (heldIsPass(held)) return { spawned, verdict: "PASS", failures: [] };
459
+
460
+ const priorFailures = isRecord(held) && Array.isArray(held.failures)
461
+ ? held.failures.map(f => String(f)).filter(f => f.trim() !== "")
462
+ : [];
463
+
464
+ if (scope !== REVIEW_SCOPE_FULL) {
465
+ return {
466
+ spawned,
467
+ verdict: "FAIL",
468
+ failures: [
469
+ `a ${describe(scope)}-scoped re-review passed, but the verdict it would clear is a ` +
470
+ `FAIL — a diff against the flagged commit does not contain the flagged code, so ` +
471
+ `this PASS says nothing about it (#244). Original findings stand: ` +
472
+ (priorFailures.join("; ") || "none were recorded"),
473
+ ...priorFailures,
474
+ ],
475
+ };
476
+ }
477
+
478
+ const clearedBySha = rookReviewSha(isRecord(fresh) ? fresh.testedSha : null)
479
+ ?? rookReviewSha(reviewedSha);
480
+ if (!clearedBySha) {
481
+ return {
482
+ spawned,
483
+ verdict: "FAIL",
484
+ failures: [
485
+ "a full re-review passed but did not say which commit it read, so there is nothing " +
486
+ "to record the clearing against (#244). Original findings stand: " +
487
+ (priorFailures.join("; ") || "none were recorded"),
488
+ ...priorFailures,
489
+ ],
490
+ };
491
+ }
492
+
493
+ return {
494
+ spawned,
495
+ verdict: "PASS",
496
+ failures: [],
497
+ cleared: {
498
+ priorVerdict: "FAIL",
499
+ priorFailures,
500
+ priorSha: rookReviewSha(priorSha),
501
+ clearedBySha,
502
+ clearedByRound: round,
503
+ scope: REVIEW_SCOPE_FULL,
504
+ },
505
+ };
506
+ }
507
+
508
+ /**
509
+ * Exhaustion holding findings is a different fact from exhaustion holding a
510
+ * clean review (#244, SC-3).
511
+ *
512
+ * "We ran out of rounds and the last thing we knew was a finding" and "…and
513
+ * the last thing we knew was clean" refuse for different reasons and want
514
+ * different next steps, so they refuse under different names. Spelled without
515
+ * reusing the other constant's text, because a test asserts that one appears
516
+ * exactly once as a string literal and a name containing it would be a second
517
+ * spelling the assertion cannot tell from a second declaration.
518
+ */
519
+ export const SECURITY_FINDINGS_OUTLIVED_REREVIEW = "SECURITY_FINDINGS_OUTLIVED_REREVIEW";
520
+
521
+ /**
522
+ * The name a non-PASS verdict refuses under.
523
+ *
524
+ * This decides the WORDING of a refusal, never whether one happens. The
525
+ * caller's `verdict !== 'PASS'` check stays unconditional — conditioning that
526
+ * on currency was the second finding against `46034035`, because a run whose
527
+ * currency could not be established would have skipped an immediate refusal.
528
+ */
529
+ export function securityRefusalName(held: unknown, roundsSpent: unknown): string {
530
+ const spent = readCount(roundsSpent) ?? 0;
531
+ return !heldIsPass(held) && spent > 0
532
+ ? SECURITY_FINDINGS_OUTLIVED_REREVIEW
533
+ : "SECURITY_REVIEW_DID_NOT_PASS";
534
+ }
535
+
536
+ /**
537
+ * Combine the git-derived scope and the reviewer's answer into one verdict.
538
+ *
539
+ * FAILS CLOSED EVERYWHERE. Every branch that cannot positively establish both
540
+ * "a real, non-empty scope was determined by git" and "the reviewer read it
541
+ * and passed it" returns FAIL. A missing field, a malformed field, a reviewer
542
+ * that returned nothing, a verdict string nobody recognises — all of them are
543
+ * the absence of evidence that the code is safe, and absence of evidence is
544
+ * what this function is not allowed to read as evidence of absence.
545
+ *
546
+ * The scope is checked first and independently of the reviewer, because the
547
+ * production failure was a PASS over zero files. "Found no problems in nothing"
548
+ * and "found no problems" serialise to the same object.
549
+ */
550
+ export function rookGateVerdict(scope: unknown, rook: unknown): SecurityVerdict {
551
+ const failures: string[] = [];
552
+
553
+ if (!isRecord(scope)) {
554
+ failures.push(
555
+ `the review scope was never established: the scope step returned ${describe(scope)}`,
556
+ );
557
+ } else if (scope.exitCode !== 0) {
558
+ failures.push(
559
+ `the review scope could not be established: scripts/rook-review-scope.ts reported ` +
560
+ `exit ${describe(scope.exitCode)}`,
561
+ );
562
+ } else if (!Array.isArray(scope.files)) {
563
+ failures.push(
564
+ `the review scope is not a list of files (got ${describe(scope.files)}) — ` +
565
+ `refusing to treat an unreadable scope as a reviewed one`,
566
+ );
567
+ } else if (scope.files.filter(f => typeof f === "string" && f.trim() !== "").length === 0) {
568
+ // Counted, not `.length`. A report of `[""]` or `[null]` is the same
569
+ // absence of a reviewed scope as `[]`, and length cannot tell them apart —
570
+ // a fail-open inside the one function whose contract is to fail closed
571
+ // everywhere. Entries are filtered rather than the whole report rejected:
572
+ // git produces clean paths, so a stray blank beside a real path is noise,
573
+ // not evidence that nothing was reviewed.
574
+ failures.push(
575
+ "the review scope is empty — the security review read zero files, so its verdict " +
576
+ "says nothing about this change (#129)",
577
+ );
578
+ }
579
+
580
+ const spawned = isRecord(rook);
581
+ if (!spawned) {
582
+ failures.push("the security review did not run");
583
+ } else if (rook.result === "FAIL") {
584
+ const detail = Array.isArray(rook.failures)
585
+ ? rook.failures.map(f => String(f)).filter(f => f.trim() !== "")
586
+ : [];
587
+ if (detail.length > 0) {
588
+ failures.push(...detail);
589
+ } else {
590
+ // gates/SCHEMA-GUIDE.md: a FAIL must carry a non-empty failures list.
591
+ // A FAIL with nothing attached blocks the run without naming what to
592
+ // fix, so say that much rather than recording an empty list.
593
+ failures.push(
594
+ "the security review returned FAIL with no findings attached — see the rook transcript",
595
+ );
596
+ }
597
+ } else if (rook.result !== "PASS") {
598
+ failures.push(
599
+ `the security review returned no usable verdict (got ${describe(rook.result)})`,
600
+ );
601
+ }
602
+
603
+ return {
604
+ spawned,
605
+ verdict: failures.length === 0 ? "PASS" : "FAIL",
606
+ failures,
607
+ };
608
+ }
609
+
610
+ function describe(v: unknown): string {
611
+ if (v === undefined) return "nothing";
612
+ if (v === null) return "null";
613
+ if (Array.isArray(v)) return `an array of ${v.length}`;
614
+ if (typeof v === "object") return "an object";
615
+ return JSON.stringify(v);
616
+ }
@@ -4,4 +4,5 @@ export const SIGNAL_PHRASE_PATTERNS = [
4
4
  /\b(explicitly prefers?|not dependent on|single chokepoint|no new).+?[.;\n]/gim,
5
5
  /\b(intentional|by design|anti-pattern|permanently disabled|do not change|do not remove|do not regress)\b.+?[.;\n]/gim,
6
6
  /\b(only on|only from|only when|only in|permanent[^l]|every \d+[hm]\b).+?[.;\n]/gim,
7
+ /^\d+\.\s+\*\*[^*]+\*\*.*/gim,
7
8
  ] as const;