mandrel 2.110.0 → 2.112.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 (190) hide show
  1. package/.agents/agents/acceptance-critic.md +14 -0
  2. package/.agents/agents/auditor.md +14 -0
  3. package/.agents/agents/plan-critic.md +5 -0
  4. package/.agents/agents/story-worker.md +4 -1
  5. package/.agents/audit-checklists/state-machines.md +21 -0
  6. package/.agents/docs/agentrc-reference.json +23 -10
  7. package/.agents/docs/configuration.md +362 -15
  8. package/.agents/docs/execution-reference.md +11 -0
  9. package/.agents/docs/workflows.md +2 -1
  10. package/.agents/rules/ci-remediation.md +28 -4
  11. package/.agents/rules/git-conventions-reference.md +7 -0
  12. package/.agents/schemas/agentrc.schema.json +179 -13
  13. package/.agents/schemas/audit-rules.json +28 -0
  14. package/.agents/schemas/baselines/baseline-envelope.schema.json +16 -4
  15. package/.agents/schemas/baselines/bundle-size.schema.json +1 -0
  16. package/.agents/schemas/baselines/coverage.schema.json +1 -0
  17. package/.agents/schemas/baselines/crap.schema.json +37 -10
  18. package/.agents/schemas/baselines/duplication.schema.json +1 -0
  19. package/.agents/schemas/baselines/maintainability.schema.json +1 -0
  20. package/.agents/schemas/baselines/mutation.schema.json +1 -0
  21. package/.agents/schemas/crap-report.schema.json +6 -5
  22. package/.agents/schemas/story-deliver-terminal.schema.json +49 -3
  23. package/.agents/schemas/story-progress.schema.json +1 -1
  24. package/.agents/schemas/validation-evidence.schema.json +2 -2
  25. package/.agents/scripts/boot-sweep.js +41 -3
  26. package/.agents/scripts/coverage-capture.js +39 -3
  27. package/.agents/scripts/coverage-ratchet.js +106 -0
  28. package/.agents/scripts/evidence-gate.js +84 -21
  29. package/.agents/scripts/file-ci-gap.js +220 -10
  30. package/.agents/scripts/lib/audit-baselines/read.js +8 -1
  31. package/.agents/scripts/lib/audit-baselines/trend.js +2 -1
  32. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  33. package/.agents/scripts/lib/baseline-loader.js +4 -2
  34. package/.agents/scripts/lib/baselines/codec.js +57 -0
  35. package/.agents/scripts/lib/baselines/crap-preview-incremental.js +8 -3
  36. package/.agents/scripts/lib/baselines/crap-preview-scan.js +10 -16
  37. package/.agents/scripts/lib/baselines/crap-updater-cli.js +4 -13
  38. package/.agents/scripts/lib/baselines/kernel.js +19 -1
  39. package/.agents/scripts/lib/baselines/kinds/_crap-codec.js +171 -0
  40. package/.agents/scripts/lib/baselines/kinds/_crap-read.js +56 -16
  41. package/.agents/scripts/lib/baselines/kinds/_shared-metric.js +0 -59
  42. package/.agents/scripts/lib/baselines/kinds/crap.js +283 -319
  43. package/.agents/scripts/lib/baselines/preview-gates.js +29 -10
  44. package/.agents/scripts/lib/baselines/reader.js +36 -9
  45. package/.agents/scripts/lib/baselines/refresh-service.js +79 -18
  46. package/.agents/scripts/lib/baselines/seat-missing.js +173 -7
  47. package/.agents/scripts/lib/baselines/writer.js +36 -21
  48. package/.agents/scripts/lib/changed-files.js +70 -6
  49. package/.agents/scripts/lib/child-exec.js +10 -0
  50. package/.agents/scripts/lib/claude/agents-projection.js +5 -5
  51. package/.agents/scripts/lib/close-lock-events.js +8 -3
  52. package/.agents/scripts/lib/close-validation/ci-deferral.js +40 -0
  53. package/.agents/scripts/lib/close-validation/gates.js +156 -32
  54. package/.agents/scripts/lib/close-validation/process.js +16 -7
  55. package/.agents/scripts/lib/close-validation/projections/crap.js +43 -10
  56. package/.agents/scripts/lib/close-validation/runner.js +160 -41
  57. package/.agents/scripts/lib/close-validation/skip-branch-test.js +144 -0
  58. package/.agents/scripts/lib/close-validation/test-delta.js +33 -8
  59. package/.agents/scripts/lib/codex/agents-projection.js +6 -0
  60. package/.agents/scripts/lib/config/agentrc-overlay.js +9 -5
  61. package/.agents/scripts/lib/config/explain.js +5 -2
  62. package/.agents/scripts/lib/config/gates/coverage.schema.js +53 -0
  63. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  64. package/.agents/scripts/lib/config/git-roots.js +38 -4
  65. package/.agents/scripts/lib/config/handoff.js +24 -0
  66. package/.agents/scripts/lib/config/quality.js +28 -12
  67. package/.agents/scripts/lib/config/worktree-isolation.js +2 -5
  68. package/.agents/scripts/lib/config-resolver.js +22 -2
  69. package/.agents/scripts/lib/config-settings-schema-delivery.js +87 -4
  70. package/.agents/scripts/lib/config-settings-schema-quality.js +36 -1
  71. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  72. package/.agents/scripts/lib/coverage-capture-affected.js +1 -0
  73. package/.agents/scripts/lib/coverage-capture-delta.js +164 -32
  74. package/.agents/scripts/lib/coverage-capture-own-fix.js +232 -0
  75. package/.agents/scripts/lib/coverage-capture-usage.js +2 -2
  76. package/.agents/scripts/lib/coverage-capture.js +31 -0
  77. package/.agents/scripts/lib/coverage-deferral.js +96 -0
  78. package/.agents/scripts/lib/coverage-ratchet.js +187 -0
  79. package/.agents/scripts/lib/crap-baseline-join.js +5 -5
  80. package/.agents/scripts/lib/crap-engine.js +3 -3
  81. package/.agents/scripts/lib/crap-method-identity.js +104 -48
  82. package/.agents/scripts/lib/escomplex-anchor.js +135 -0
  83. package/.agents/scripts/lib/escomplex-kernel.js +30 -1
  84. package/.agents/scripts/lib/failure-rows.js +121 -0
  85. package/.agents/scripts/lib/full-suite-lock.js +44 -4
  86. package/.agents/scripts/lib/full-suite-queue.js +89 -13
  87. package/.agents/scripts/lib/generated/agentrc-validator.js +8 -2
  88. package/.agents/scripts/lib/gh-env.js +3 -6
  89. package/.agents/scripts/lib/gh-pr-rest.js +1 -0
  90. package/.agents/scripts/lib/git/base-sync-probe.js +182 -0
  91. package/.agents/scripts/lib/git-branch-lifecycle.js +9 -0
  92. package/.agents/scripts/lib/observability/close-telemetry.js +37 -2
  93. package/.agents/scripts/lib/observability/handoff-telemetry.js +170 -0
  94. package/.agents/scripts/lib/observability/review-dispositions.js +23 -6
  95. package/.agents/scripts/lib/observability/runtime-friction.js +17 -4
  96. package/.agents/scripts/lib/observability/source-classifier.js +3 -0
  97. package/.agents/scripts/lib/observability/story-outcome.js +393 -0
  98. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +2 -1
  99. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +19 -1
  100. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +84 -0
  101. package/.agents/scripts/lib/orchestration/check-baselines/phases/pipeline.js +14 -5
  102. package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js +3 -2
  103. package/.agents/scripts/lib/orchestration/check-baselines/phases/report.js +26 -6
  104. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +124 -23
  105. package/.agents/scripts/lib/orchestration/code-review.js +223 -19
  106. package/.agents/scripts/lib/orchestration/handoff-gates.js +217 -44
  107. package/.agents/scripts/lib/orchestration/handoff-rescore.js +169 -0
  108. package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +45 -0
  109. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -1
  110. package/.agents/scripts/lib/orchestration/plan-persist/source-rewrite.js +76 -4
  111. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +2 -2
  112. package/.agents/scripts/lib/orchestration/preflight-lanes.js +208 -0
  113. package/.agents/scripts/lib/orchestration/review-base-ref.js +40 -17
  114. package/.agents/scripts/lib/orchestration/review-deposit.js +38 -12
  115. package/.agents/scripts/lib/orchestration/review-depth.js +21 -0
  116. package/.agents/scripts/lib/orchestration/review-history.js +124 -20
  117. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +23 -8
  118. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +82 -39
  119. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +64 -11
  120. package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js +98 -3
  121. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +6 -2
  122. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +55 -8
  123. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +1 -0
  124. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +42 -15
  125. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  126. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +10 -1
  127. package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js +10 -0
  128. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +7 -4
  129. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +17 -2
  130. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +59 -2
  131. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +13 -1
  132. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +15 -4
  133. package/.agents/scripts/lib/orchestration/single-story-close/phases/land-review-record.js +213 -0
  134. package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +17 -2
  135. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +42 -20
  136. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +51 -26
  137. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +3 -1
  138. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +51 -15
  139. package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js +59 -11
  140. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +1 -0
  141. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-block.js +31 -13
  142. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +29 -6
  143. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-outcome.js +10 -12
  144. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +19 -4
  145. package/.agents/scripts/lib/orchestration/single-story-close/result.js +43 -13
  146. package/.agents/scripts/lib/orchestration/single-story-close/review-overlap.js +73 -39
  147. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +11 -2
  148. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +3 -2
  149. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +20 -8
  150. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +7 -0
  151. package/.agents/scripts/lib/orchestration/story-handoff.js +789 -196
  152. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  153. package/.agents/scripts/lib/pr-body-lines.js +32 -0
  154. package/.agents/scripts/lib/single-story/ci-ratchet-gate.js +140 -0
  155. package/.agents/scripts/lib/single-story/confirm-and-land.js +17 -7
  156. package/.agents/scripts/lib/single-story/confirm-merge.js +12 -3
  157. package/.agents/scripts/lib/single-story-sweep/report-stalled-executing.js +202 -0
  158. package/.agents/scripts/lib/standalone-ratchets.js +37 -0
  159. package/.agents/scripts/lib/suite-admission.js +20 -8
  160. package/.agents/scripts/lib/suite-sizing.js +146 -0
  161. package/.agents/scripts/lib/workspace-provisioner.js +2 -2
  162. package/.agents/scripts/merge-baseline.js +14 -3
  163. package/.agents/scripts/providers/github/comments.js +19 -3
  164. package/.agents/scripts/providers/github.js +1 -0
  165. package/.agents/scripts/review-dispositions-report.js +1 -1
  166. package/.agents/scripts/role-scope-guard.js +267 -0
  167. package/.agents/scripts/single-story-close.js +4 -4
  168. package/.agents/scripts/single-story-confirm-merge.js +31 -5
  169. package/.agents/scripts/single-story-init.js +24 -4
  170. package/.agents/scripts/story-handoff.js +3 -3
  171. package/.agents/scripts/story-outcomes-report.js +231 -0
  172. package/.agents/scripts/story-review-compute.js +9 -5
  173. package/.agents/scripts/update-coverage-baseline.js +12 -2
  174. package/.agents/scripts/update-crap-baseline.js +9 -1
  175. package/.agents/workflows/audit-state-machines.md +213 -0
  176. package/.agents/workflows/helpers/code-review.md +63 -9
  177. package/.agents/workflows/helpers/deliver-digest.md +53 -54
  178. package/.agents/workflows/helpers/deliver-reference.md +236 -63
  179. package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
  180. package/.agents/workflows/helpers/deliver-story.md +7 -2
  181. package/.agents/workflows/helpers/parallel-tooling.md +29 -0
  182. package/.agents/workflows/helpers/plan-reference.md +10 -2
  183. package/docs/CHANGELOG.md +56 -0
  184. package/lib/cli/doctor-checks/coverage-ratchet.js +54 -0
  185. package/lib/cli/doctor-checks/effective-agentrc.js +23 -0
  186. package/lib/cli/doctor-checks/llm-review.js +2 -11
  187. package/lib/cli/doctor-checks/sync-parity.js +5 -1
  188. package/lib/cli/doctor-checks/test-credit-path.js +7 -2
  189. package/lib/cli/registry.js +5 -0
  190. package/package.json +1 -1
@@ -31,14 +31,27 @@ import {
31
31
  const MAX_PRIOR_REDS = 10;
32
32
 
33
33
  /**
34
- * Verdicts earning the one same-SHA rerun: proven environment faults no
35
- * commit can fix. `pre-existing` is excluded — a real defect on `main`.
34
+ * Verdicts earning the one same-SHA green: proven environment faults no
35
+ * commit can fix, or a fresh run an operator-approved governance label
36
+ * started. `pre-existing` is excluded — a real defect on `main`.
36
37
  *
37
- * @type {readonly ['capacity', 'unreproducible-tier']}
38
+ * @type {readonly ['capacity', 'unreproducible-tier', 'governance-label']}
38
39
  */
39
- export const RERUN_ALLOWANCE_VERDICTS = Object.freeze([
40
+ const RERUN_ALLOWANCE_VERDICTS = Object.freeze([
40
41
  'capacity',
41
42
  'unreproducible-tier',
43
+ 'governance-label',
44
+ ]);
45
+
46
+ /** The audited recovery verdict: allowance only, never an intake filing. */
47
+ export const GOVERNANCE_LABEL_VERDICT = 'governance-label';
48
+
49
+ /** REST check-run conclusions that mean the run failed. */
50
+ const FAILED_REST_CONCLUSIONS = new Set([
51
+ 'failure',
52
+ 'timed_out',
53
+ 'action_required',
54
+ 'startup_failure',
42
55
  ]);
43
56
 
44
57
  /**
@@ -141,15 +154,25 @@ function resolvePrHeadShaRest({ prRef, cwd, spawnFn }) {
141
154
  return typeof sha === 'string' && sha.length > 0 ? sha : null;
142
155
  }
143
156
 
144
- /** `[{ name, link }]` for the PR head's check runs, as `gh pr checks --json` gives it. */
157
+ /** `gh pr checks` rows in {@link readCheckLinks}'s shape; `null` when unread. */
158
+ function readGhCheckRows({ prRef, cwd, spawnFn }) {
159
+ const rows = readGhJson(
160
+ ['pr', 'checks', prRef, '--json', 'name,link,bucket,completedAt'],
161
+ { cwd, spawnFn, anyExit: true },
162
+ );
163
+ if (!Array.isArray(rows)) return null;
164
+ return rows.map((e) => ({
165
+ name: e?.name,
166
+ link: e?.link ?? null,
167
+ failed: e?.bucket === 'fail',
168
+ passed: e?.bucket === 'pass',
169
+ completedAt: e?.completedAt ?? null,
170
+ }));
171
+ }
172
+
173
+ /** `[{ name, link, failed, passed, completedAt }]` for the PR head's check runs. */
145
174
  function readCheckLinks({ prRef, cwd, spawnFn }) {
146
- if (!prSurfaceUsesRest()) {
147
- return readGhJson(['pr', 'checks', prRef, '--json', 'name,link'], {
148
- cwd,
149
- spawnFn,
150
- anyExit: true,
151
- });
152
- }
175
+ if (!prSurfaceUsesRest()) return readGhCheckRows({ prRef, cwd, spawnFn });
153
176
  const sha = resolvePrHeadShaRest({ prRef, cwd, spawnFn });
154
177
  if (!sha) return null;
155
178
  const runs = readGhJson(
@@ -159,23 +182,72 @@ function readCheckLinks({ prRef, cwd, spawnFn }) {
159
182
  return (runs?.check_runs ?? []).map((run) => ({
160
183
  name: run?.name,
161
184
  link: run?.details_url ?? run?.html_url ?? null,
185
+ failed: FAILED_REST_CONCLUSIONS.has(
186
+ String(run?.conclusion ?? '').toLowerCase(),
187
+ ),
188
+ passed: String(run?.conclusion ?? '').toLowerCase() === 'success',
189
+ completedAt: run?.completed_at ?? null,
162
190
  }));
163
191
  }
164
192
 
193
+ function runIdOfLink(link) {
194
+ const m = link ? /\/runs\/(\d+)/.exec(String(link)) : null;
195
+ return m ? m[1] : null;
196
+ }
197
+
198
+ /** The hinted run when given, else the most recently completed one. */
199
+ function pickEntry(rows, runId) {
200
+ if (runId != null) {
201
+ return rows.find((e) => runIdOfLink(e.link) === String(runId)) ?? null;
202
+ }
203
+ const byRecency = [...rows].sort((a, b) =>
204
+ String(b.completedAt ?? '').localeCompare(String(a.completedAt ?? '')),
205
+ );
206
+ return byRecency[0] ?? null;
207
+ }
208
+
165
209
  /**
166
210
  * The failing check's run id and URL (the intake filing needs the link).
167
- * Best-effort.
211
+ * Only a FAILED entry qualifies — a same-name green run from another
212
+ * workflow run on the head is never blamed; none → nulls. Best-effort.
168
213
  *
214
+ * @param {{ prRef: string, checkName: string, runId?: string|number|null, cwd: string, spawnFn?: Function }} opts
169
215
  * @returns {{ runId: string|null, url: string|null }}
170
216
  */
171
- function resolveFailingCheckRun({ prRef, checkName, cwd, spawnFn }) {
217
+ function resolveFailingCheckRun({
218
+ prRef,
219
+ checkName,
220
+ runId = null,
221
+ cwd,
222
+ spawnFn,
223
+ }) {
172
224
  const parsed = readCheckLinks({ prRef, cwd, spawnFn });
173
- const entry = Array.isArray(parsed)
174
- ? parsed.find((e) => e?.name === checkName)
175
- : null;
176
- const link = entry?.link ? String(entry.link) : null;
177
- const m = link ? /\/runs\/(\d+)/.exec(link) : null;
178
- return { runId: m ? m[1] : null, url: link };
225
+ const failed = Array.isArray(parsed)
226
+ ? parsed.filter((e) => e?.name === checkName).filter((e) => e.failed)
227
+ : [];
228
+ const entry = pickEntry(failed, runId);
229
+ const url = entry?.link ? String(entry.link) : null;
230
+ return {
231
+ runId: runIdOfLink(url) ?? (runId != null ? String(runId) : null),
232
+ url,
233
+ };
234
+ }
235
+
236
+ /**
237
+ * The latest green run of `checkName` on the PR head — the governance-label
238
+ * recovery's audit names it. Best-effort; nulls when none.
239
+ *
240
+ * @param {{ prRef: string, checkName: string, cwd: string, spawnFn?: Function }} opts
241
+ * @returns {{ runId: string|null, url: string|null }}
242
+ */
243
+ export function resolvePassingCheckRun({ prRef, checkName, cwd, spawnFn }) {
244
+ const parsed = readCheckLinks({ prRef, cwd, spawnFn });
245
+ const passed = Array.isArray(parsed)
246
+ ? parsed.filter((e) => e?.name === checkName && e.passed)
247
+ : [];
248
+ const entry = pickEntry(passed, null);
249
+ const url = entry?.link ? String(entry.link) : null;
250
+ return { runId: runIdOfLink(url), url };
179
251
  }
180
252
 
181
253
  /**
@@ -312,8 +384,9 @@ function renderDigestMarkdown(digest, failures) {
312
384
  * @param {number|string|null} [opts.storyId] The v2 delivery scope.
313
385
  * @param {number} opts.prNumber
314
386
  * @param {string|null} [opts.headSha] PR head SHA at the moment of the red.
315
- * @param {Array<{name:string, outcome:string, required?:boolean}>} opts.failures
387
+ * @param {Array<{name:string, outcome:string, required?:boolean, runId?:string|number}>} opts.failures
316
388
  * `required` is recorded per entry; anything but `false` is stored as `true`.
389
+ * A `runId` names the red run itself.
317
390
  * @param {string} opts.tempRoot
318
391
  * @param {string} opts.cwd
319
392
  * @param {string} opts.prRef
@@ -345,8 +418,17 @@ export function writeCiDigest({
345
418
  outcome: 'failure',
346
419
  required: true,
347
420
  };
421
+ // A failure carrying its own run id (the close path's red rollup runs)
422
+ // pins the lookup to that run.
423
+ const hintedRunId = runIdOf(primary);
348
424
  const checkRun =
349
- checkRunFn({ prRef, checkName: primary.name, cwd, spawnFn }) ?? {};
425
+ checkRunFn({
426
+ prRef,
427
+ checkName: primary.name,
428
+ runId: hintedRunId,
429
+ cwd,
430
+ spawnFn,
431
+ }) ?? {};
350
432
  const logTail = logTailFn({ runId: checkRun.runId, cwd, spawnFn });
351
433
  const previous = readCiDigest({ storyId, tempRoot, cwd });
352
434
  const digest = {
@@ -374,6 +456,16 @@ export function writeCiDigest({
374
456
  return { jsonPath: paths.jsonPath, mdPath: paths.mdPath };
375
457
  }
376
458
 
459
+ /** A failure entry's own red run id as a string, else `null`. */
460
+ function runIdOf(failure) {
461
+ return failure.runId != null ? String(failure.runId) : null;
462
+ }
463
+
464
+ /** `{ evidence }` when given, else nothing — an audit-free allowance stays as before. */
465
+ function evidenceField(evidence) {
466
+ return evidence ? { evidence } : {};
467
+ }
468
+
377
469
  /**
378
470
  * Stamp the one-rerun allowance, called by `file-ci-gap.js` after filing.
379
471
  * Keyed on the digest's own head SHA so it cannot apply to a later head.
@@ -384,8 +476,9 @@ export function writeCiDigest({
384
476
  * verdict: string,
385
477
  * tempRoot: string,
386
478
  * cwd: string,
479
+ * evidence?: object|null,
387
480
  * now?: () => Date,
388
- * }} opts
481
+ * }} opts `evidence` — the verdict's audit facts, stored on the allowance.
389
482
  * @returns {{ verdict: string, headSha: string, recordedAt: string } | null}
390
483
  */
391
484
  export function recordRerunAllowance({
@@ -393,6 +486,7 @@ export function recordRerunAllowance({
393
486
  verdict,
394
487
  tempRoot,
395
488
  cwd,
489
+ evidence = null,
396
490
  now = () => new Date(),
397
491
  }) {
398
492
  if (!RERUN_ALLOWANCE_VERDICTS.includes(verdict)) return null;
@@ -403,6 +497,7 @@ export function recordRerunAllowance({
403
497
  verdict,
404
498
  headSha: digest.headSha,
405
499
  recordedAt: now().toISOString(),
500
+ ...evidenceField(evidence),
406
501
  };
407
502
  try {
408
503
  writeFileAtomic(
@@ -550,6 +645,12 @@ export function formatRerunViolation({ digest, headSha, prNumber, reason }) {
550
645
  ' verdict also records the one-rerun allowance for this head SHA, so a',
551
646
  ' single rerun of the failed job is then admitted; `pre-existing` does',
552
647
  ' not, because it names a real defect a rerun cannot remove.',
648
+ '3. When the green came from a fresh run that an operator-approved',
649
+ ' governance label (e.g. `migration:destructive-ok`) started on this',
650
+ ' head, record the audited recovery instead — `node',
651
+ ' .agents/scripts/file-ci-gap.js --story <id> --verdict governance-label',
652
+ ' --label <name>` — then resume. It proves the label was added after',
653
+ ' the red, files no intake issue, and admits this one green.',
553
654
  ].join('\n');
554
655
  }
555
656
 
@@ -2,25 +2,37 @@
2
2
  * lib/orchestration/code-review.js — in-process Story-scope code review:
3
3
  * load the configured review adapter (default `native`), collect its
4
4
  * `Finding[]`, render and post the `verification-results` comment (adapters
5
- * never post), and report `halted` on any surviving critical finding.
5
+ * never post), and report `halted` on any surviving critical finding or,
6
+ * under `onNoVerdict: "block"`, a missing verdict (`haltCause`).
6
7
  */
7
8
 
8
9
  import picomatch from 'picomatch';
9
10
  import { hasSurvivingCritical } from '../audit-suite/findings.js';
10
11
  import { resolveConfig } from '../config-resolver.js';
12
+ import { gitSpawn } from '../git-utils.js';
11
13
  import { PROJECT_ROOT } from '../project-root.js';
12
14
  import { computeChangeSet } from './change-set.js';
13
15
  import { remoteBaseRef } from './review-base-ref.js';
14
- import { deriveChangeLevel, resolveDepth } from './review-depth.js';
16
+ import {
17
+ deriveChangeLevel,
18
+ resolveDepth,
19
+ resolveReviewEffort,
20
+ } from './review-depth.js';
15
21
  import {
16
22
  appendReviewRun,
23
+ earlierCriticals,
17
24
  markRepeats,
25
+ raisedAgain,
18
26
  readReviewHistory,
19
27
  } from './review-history.js';
20
- import { vetFindings } from './review-providers/critical-verifier.js';
28
+ import {
29
+ recheckCriticals,
30
+ vetFindings,
31
+ } from './review-providers/critical-verifier.js';
21
32
  import {
22
33
  collectProviderDegradations,
23
34
  degradationEnvelope,
35
+ resolveNoVerdictHalt,
24
36
  } from './review-providers/degraded-gates.js';
25
37
  import { findingInstances } from './review-providers/finding-identity.js';
26
38
  import {
@@ -125,6 +137,7 @@ function resolveStoryScope(opts, config) {
125
137
  * postedCommentId: number|null,
126
138
  * commentTargetId: number,
127
139
  * halted: boolean,
140
+ * haltCause: 'critical'|'no-verdict'|null,
128
141
  * criticalByProvider?: Record<string, number>,
129
142
  * degraded: boolean, degradations: Array<object>,
130
143
  * blockerReason: string|null,
@@ -277,23 +290,44 @@ function resolveCriticalByProvider({ findings, providerName, severity }) {
277
290
  }
278
291
 
279
292
  /** Tally, halt verdict and per-provider criticals of grounded findings. */
280
- function scoreFindings(findings, providerName) {
293
+ function scoreFindings(findings, providerName, haltContext) {
281
294
  const severity = countBySeverity(findings);
282
295
  const halted = hasSurvivingCritical(severity);
283
296
  return {
284
297
  severity,
285
- halted,
286
298
  criticalByProvider: resolveCriticalByProvider({
287
299
  findings,
288
300
  providerName,
289
301
  severity,
290
302
  }),
291
- blockerReason: halted
292
- ? `code-review reported ${severity.critical} critical blocker(s)`
293
- : null,
303
+ ...resolveHalt(halted, severity, haltContext),
294
304
  };
295
305
  }
296
306
 
307
+ /**
308
+ * A surviving critical halts first; else `onNoVerdict: "block"` halts a
309
+ * review with a verdict-missing or coverage-partial degradation.
310
+ */
311
+ function resolveHalt(
312
+ critical,
313
+ severity,
314
+ { degradations, codeReviewConfig, ticketId },
315
+ ) {
316
+ if (critical) {
317
+ return {
318
+ halted: true,
319
+ haltCause: 'critical',
320
+ blockerReason: `code-review reported ${severity.critical} critical blocker(s)`,
321
+ };
322
+ }
323
+ const noVerdict = resolveNoVerdictHalt({
324
+ degradations,
325
+ onNoVerdict: codeReviewConfig?.onNoVerdict,
326
+ storyId: ticketId,
327
+ });
328
+ return noVerdict ?? { halted: false, haltCause: null, blockerReason: null };
329
+ }
330
+
297
331
  /**
298
332
  * Drop findings whose file, or every instance file, matches a `skipPaths`
299
333
  * glob. Config only: guidance prose cannot reach this.
@@ -319,17 +353,155 @@ function resolveHistoryDeps(opts, config) {
319
353
  return opts.reviewProvider ? null : { config };
320
354
  }
321
355
 
322
- /** Mark the findings an earlier run of this Story already raised. */
323
- function markAgainstHistory(findings, ticketId, historyDeps) {
324
- if (!historyDeps) return findings;
325
- return markRepeats(findings, readReviewHistory(ticketId, historyDeps));
356
+ /** How the current run settles an earlier CRITICAL it raised again, if it did. */
357
+ function settleInRun(entry, findings) {
358
+ const again = findings.filter((f) => raisedAgain(f, entry.finding));
359
+ if (again.some((f) => f.severity === 'critical')) {
360
+ return { status: 'still-open' };
361
+ }
362
+ const flagged = again.find((f) => f.unverified || f.ungrounded);
363
+ return flagged
364
+ ? { status: 'refuted', reason: flagged.unverified || flagged.ungrounded }
365
+ : null;
366
+ }
367
+
368
+ /** A stored history record as a CRITICAL the verifier can re-check. */
369
+ function storedCritical({ id, finding: f }) {
370
+ const optional = Object.entries({
371
+ file: f.file ?? f.instances?.[0]?.file,
372
+ line: f.line,
373
+ claim: f.claim,
374
+ class: f.class,
375
+ provider: f.provider,
376
+ }).filter(([, v]) => v != null);
377
+ return {
378
+ severity: 'critical',
379
+ title: f.title ?? `Earlier CRITICAL ${id}`,
380
+ body: f.body ?? '',
381
+ ...Object.fromEntries(optional),
382
+ instances: f.instances ?? [],
383
+ carriedId: id,
384
+ };
326
385
  }
327
386
 
387
+ /** Reporting only: did the instance files change since the raising head? */
388
+ function instanceFilesChanged({ finding, headSha }, headRef, opts) {
389
+ const files = (finding.instances ?? []).map((i) => i.file);
390
+ if (files.length === 0) return false;
391
+ try {
392
+ const out = (opts.gitSpawnFn ?? gitSpawn)(
393
+ opts.cwd ?? PROJECT_ROOT,
394
+ 'diff',
395
+ '--name-only',
396
+ headSha,
397
+ headRef,
398
+ '--',
399
+ ...files,
400
+ );
401
+ return out?.status === 0 && String(out.stdout ?? '').trim() !== '';
402
+ } catch {
403
+ return false;
404
+ }
405
+ }
406
+
407
+ /**
408
+ * Settle every open earlier CRITICAL: re-raised, refuted in this run, or else
409
+ * re-verified at the current head. Only a verifier refutation resolves an
410
+ * absent one; anything else carries it into this run's findings as blocking.
411
+ */
412
+ async function carryForward({ findings, history, reviewInput, opts }) {
413
+ const outcomes = [];
414
+ const absent = [];
415
+ for (const entry of earlierCriticals(history)) {
416
+ if (entry.status !== 'open') continue;
417
+ const inRun = settleInRun(entry, findings);
418
+ if (inRun) outcomes.push({ id: entry.id, ...inRun });
419
+ else absent.push(entry);
420
+ }
421
+ const stored = absent.map(storedCritical);
422
+ const checked = await recheckCriticals({
423
+ findings: stored,
424
+ reviewInput,
425
+ opts,
426
+ });
427
+ const carried = [];
428
+ absent.forEach((entry, i) => {
429
+ const { outcome, reason } = checked.results[i];
430
+ if (outcome === 'refuted') {
431
+ const fixed = instanceFilesChanged(entry, reviewInput.headRef, opts);
432
+ outcomes.push({
433
+ id: entry.id,
434
+ status: fixed ? 'fixed' : 'refuted',
435
+ reason,
436
+ });
437
+ return;
438
+ }
439
+ carried.push({ ...stored[i], carried: reason });
440
+ outcomes.push({ id: entry.id, status: 'still-open', reason });
441
+ });
442
+ return { ...checked, findings: [...findings, ...carried], outcomes };
443
+ }
444
+
445
+ /** Every earlier surviving CRITICAL with this run's status for the comment. */
446
+ function earlierSection(history, outcomes) {
447
+ const now = new Map(outcomes.map((o) => [o.id, o]));
448
+ return earlierCriticals(history).map((e) => {
449
+ const settled = now.get(e.id) ?? e;
450
+ return {
451
+ id: e.id,
452
+ title: e.finding.title ?? null,
453
+ instances: e.finding.instances ?? [],
454
+ headSha: e.headSha,
455
+ status: settled.status,
456
+ ...(settled.reason ? { reason: settled.reason } : {}),
457
+ };
458
+ });
459
+ }
460
+
461
+ /**
462
+ * Mark repeats, then carry forward the open earlier CRITICALs. Without a
463
+ * history seam the findings pass through unchanged.
464
+ */
465
+ async function applyHistory({
466
+ findings,
467
+ ticketId,
468
+ historyDeps,
469
+ reviewInput,
470
+ opts,
471
+ }) {
472
+ if (!historyDeps) {
473
+ return { findings, outcomes: null, earlier: [], degradations: [] };
474
+ }
475
+ const history = readReviewHistory(ticketId, historyDeps);
476
+ const carry = await carryForward({
477
+ findings: markRepeats(findings, history),
478
+ history,
479
+ reviewInput,
480
+ opts,
481
+ });
482
+ return { ...carry, earlier: earlierSection(history, carry.outcomes) };
483
+ }
484
+
485
+ /** Sum two verifier tallies; an absent second one adds nothing. */
486
+ const addVerification = (a, b = {}) =>
487
+ Object.fromEntries(Object.entries(a).map(([k, n]) => [k, n + (b[k] ?? 0)]));
488
+
328
489
  /** Best-effort: a history write failure never fails the review. */
329
- function recordRun({ ticketId, headRef, findings, historyDeps, logger }) {
490
+ function recordRun({
491
+ ticketId,
492
+ headRef,
493
+ findings,
494
+ outcomes,
495
+ historyDeps,
496
+ logger,
497
+ }) {
330
498
  if (!historyDeps) return;
331
499
  try {
332
- appendReviewRun(ticketId, { headSha: headRef, findings }, historyDeps);
500
+ appendReviewRun(
501
+ ticketId,
502
+ { headSha: headRef, findings, earlierCriticals: outcomes },
503
+ historyDeps,
504
+ );
333
505
  } catch (err) {
334
506
  logger?.warn?.(
335
507
  `[code-review] Could not record the review history: ${err?.message ?? err}`,
@@ -361,8 +533,19 @@ async function executeReviewPipeline({ opts, config, envelope }) {
361
533
  codeReviewConfig,
362
534
  root: opts.cwd ?? PROJECT_ROOT,
363
535
  });
536
+ const baseInput = buildReviewInput({
537
+ opts,
538
+ scope,
539
+ ticketId,
540
+ baseRef,
541
+ headRef,
542
+ });
364
543
  const reviewInput = {
365
- ...buildReviewInput({ opts, scope, ticketId, baseRef, headRef }),
544
+ ...baseInput,
545
+ effort: resolveReviewEffort(
546
+ baseInput.depth,
547
+ codeReviewConfig?.effortByDepth,
548
+ ),
366
549
  guidance: guidance.guidance,
367
550
  };
368
551
 
@@ -389,11 +572,23 @@ async function executeReviewPipeline({ opts, config, envelope }) {
389
572
  ...(guidance.degradation ? [guidance.degradation] : []),
390
573
  ],
391
574
  });
392
- const { degradations, verification } = vetted;
393
575
  const skip = applySkipPaths(vetted.findings, codeReviewConfig?.skipPaths);
394
576
  const historyDeps = resolveHistoryDeps(opts, config);
395
- const findings = markAgainstHistory(skip.findings, ticketId, historyDeps);
396
- const scored = scoreFindings(findings, providerName);
577
+ const carry = await applyHistory({
578
+ findings: skip.findings,
579
+ ticketId,
580
+ historyDeps,
581
+ reviewInput,
582
+ opts,
583
+ });
584
+ const { findings } = carry;
585
+ const degradations = [...vetted.degradations, ...carry.degradations];
586
+ const verification = addVerification(vetted.verification, carry.verification);
587
+ const scored = scoreFindings(findings, providerName, {
588
+ degradations,
589
+ codeReviewConfig,
590
+ ticketId,
591
+ });
397
592
  const report = renderFindingsFn({
398
593
  scope,
399
594
  ticketId,
@@ -405,8 +600,16 @@ async function executeReviewPipeline({ opts, config, envelope }) {
405
600
  degradations,
406
601
  verification,
407
602
  skipped: skip.skipped,
603
+ earlierCriticals: carry.earlier,
604
+ });
605
+ recordRun({
606
+ ticketId,
607
+ headRef,
608
+ findings,
609
+ outcomes: carry.outcomes,
610
+ historyDeps,
611
+ logger,
408
612
  });
409
- recordRun({ ticketId, headRef, findings, historyDeps, logger });
410
613
 
411
614
  const { posted, postedCommentId } = await postUnlessDeferred(opts, {
412
615
  upsertCommentFn,
@@ -426,6 +629,7 @@ async function executeReviewPipeline({ opts, config, envelope }) {
426
629
  postedCommentId,
427
630
  commentTargetId,
428
631
  halted: scored.halted,
632
+ haltCause: scored.haltCause,
429
633
  criticalByProvider: scored.criticalByProvider,
430
634
  ...degradationEnvelope(degradations),
431
635
  verification,