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
@@ -187,11 +187,21 @@ function toFindings(entries) {
187
187
  .filter(Boolean);
188
188
  }
189
189
 
190
+ const resultTextOf = (envelope) =>
191
+ typeof envelope?.result === 'string' ? envelope.result : '';
192
+
193
+ function isUsageLimited(result, envelope) {
194
+ const text = [result.stderr, resultTextOf(envelope), result.stdout];
195
+ return USAGE_LIMIT_RE.test(text.join('\n'));
196
+ }
197
+
198
+ function isRetryable(result, envelope) {
199
+ return Number.isInteger(result.status) && !isUsageLimited(result, envelope);
200
+ }
201
+
190
202
  function failureReason(result, envelope) {
191
- const resultText =
192
- typeof envelope?.result === 'string' ? envelope.result : '';
193
- const text = [result.stderr, resultText, result.stdout].join('\n');
194
- if (USAGE_LIMIT_RE.test(text)) {
203
+ const resultText = resultTextOf(envelope);
204
+ if (isUsageLimited(result, envelope)) {
195
205
  return 'the claude CLI account is out of quota (usage limit reached)';
196
206
  }
197
207
  if (result.status !== 0) {
@@ -237,19 +247,24 @@ function resultTextFindings(text) {
237
247
  /**
238
248
  * Verdict resolution: (a) a successful envelope's `structured_output`,
239
249
  * (b) the fallback parser over its `result` text, (c) no verdict.
250
+ * `retryable` excludes a usage limit and a `status: null` timeout.
240
251
  *
241
- * @param {{ status: number, stdout: string, stderr: string }} result
242
- * @returns {{ findings: Finding[] } | { reason: string }}
252
+ * @param {{ status: number|null, stdout: string, stderr: string }} result
253
+ * @returns {{ findings: Finding[] } | { reason: string, retryable: boolean }}
243
254
  */
244
255
  export function resolveVerdict(result) {
245
256
  const envelope = parseEnvelope(result.stdout);
257
+ const retryable = isRetryable(result, envelope);
246
258
  if (!isSuccess(result, envelope)) {
247
- return { reason: noVerdictReason(result, envelope) };
259
+ return { reason: noVerdictReason(result, envelope), retryable };
248
260
  }
249
261
  const entries =
250
262
  structuredFindings(envelope.structured_output) ??
251
263
  resultTextFindings(envelope.result);
252
264
  return entries
253
265
  ? { findings: toFindings(entries) }
254
- : { reason: 'the reviewer output did not parse as a findings verdict' };
266
+ : {
267
+ reason: 'the reviewer output did not parse as a findings verdict',
268
+ retryable,
269
+ };
255
270
  }
@@ -1,6 +1,6 @@
1
1
  /**
2
- * review-providers/code-review.js — a low-effort model bug review of the
3
- * Story diff through `claude --print --effort low`. It asks only for
2
+ * review-providers/code-review.js — a model bug review of the Story diff
3
+ * through `claude --print --effort <input.effort ?? low>`. It asks only for
4
4
  * merge-blocking problems, so every parsed finding is `critical` and halts
5
5
  * close before auto-merge. The reviewer is handed the diff range, the Story
6
6
  * id and the diff text — never `acceptance[]` or the self-eval verdict: this
@@ -10,14 +10,15 @@
10
10
  * OS temp cwd (no CLAUDE.md discovery), user-only settings, no MCP, no tools.
11
11
  *
12
12
  * A missing CLI throws at construction (the chain entry is optional). A
13
- * review with no verdict records one degraded gate via `getDegradations()`
14
- * and returns no findings, so "never ran" cannot read as "found nothing".
13
+ * transient failure is retried once; a review still with no verdict records
14
+ * one degraded gate via `getDegradations()` and returns no findings.
15
15
  * A diff over the cap is reviewed chunk by chunk (file-aligned, sequential,
16
16
  * findings merged). Source sections pack before tests and docs, and every
17
17
  * chunk is told it is a slice and handed the whole changed-file manifest so
18
- * a file changed in another chunk never reads as unchanged. What went unchecked — a truncated file, files past the
19
- * chunk bound, a chunk with no verdict, a capped `<callers>` block — is
20
- * recorded beside the findings, naming the files.
18
+ * a file changed in another chunk never reads as unchanged. What went
19
+ * unchecked — a truncated file, files past the chunk bound, a chunk with no
20
+ * verdict (`coverage-partial`), a capped `<callers>` block
21
+ * (`context-reduced`) — is recorded beside the findings, naming the files.
21
22
  *
22
23
  * @typedef {import('./types.js').Finding} Finding
23
24
  * @typedef {import('./types.js').ReviewInput} ReviewInput
@@ -28,7 +29,10 @@
28
29
  import fs from 'node:fs';
29
30
  import os from 'node:os';
30
31
  import path from 'node:path';
31
- import { spawnCaptureAsync } from '../../child-exec.js';
32
+ import {
33
+ spawnCaptureAsync,
34
+ spawnCaptureNullableAsync,
35
+ } from '../../child-exec.js';
32
36
  import { gitSpawn } from '../../git-utils.js';
33
37
  import { PROJECT_ROOT } from '../../project-root.js';
34
38
  import { buildCallersSection } from './callers-context.js';
@@ -43,10 +47,11 @@ import { renderDepthDirective } from './review-depth.js';
43
47
  import { renderGuidanceBlock } from './review-guidance.js';
44
48
  import { probeClaudeCli } from './security-review.js';
45
49
 
46
- const CLAUDE_ARGS = Object.freeze([
50
+ /** @param {string} effort */
51
+ const claudeArgs = (effort) => [
47
52
  '--print',
48
53
  '--effort',
49
- 'low',
54
+ effort,
50
55
  '--output-format',
51
56
  'json',
52
57
  '--json-schema',
@@ -56,7 +61,7 @@ const CLAUDE_ARGS = Object.freeze([
56
61
  '--strict-mcp-config',
57
62
  '--tools',
58
63
  '',
59
- ]);
64
+ ];
60
65
  const AUTH_ARGS = Object.freeze(['auth', 'status', '--json']);
61
66
  const INVOKE_TIMEOUT_MS = 10 * 60 * 1000;
62
67
  const AUTH_TIMEOUT_MS = 15 * 1000;
@@ -239,19 +244,22 @@ function quoteWindowsArg(arg) {
239
244
  * @param {{ cwd: string, input?: string, timeout: number, run?: Function, platform: string }} opts
240
245
  * @returns {Promise<{ status: number, stdout: string, stderr: string }>}
241
246
  */
242
- export function runClaude(args, { cwd, input, timeout, run, platform }) {
247
+ export function runClaude(args, opts) {
248
+ return spawnCaptureAsync('claude', ...claudeSpawn(args, opts));
249
+ }
250
+
251
+ /** `runClaude`, but a timeout, kill or spawn error stays `status: null`. */
252
+ function runClaudeNullable(args, opts) {
253
+ return spawnCaptureNullableAsync('claude', ...claudeSpawn(args, opts));
254
+ }
255
+
256
+ /** The argv and spawn options both runners share. */
257
+ function claudeSpawn(args, { cwd, input, timeout, run, platform }) {
243
258
  const shell = platform === 'win32';
244
- return spawnCaptureAsync(
245
- 'claude',
259
+ return [
246
260
  shell ? args.map(quoteWindowsArg) : [...args],
247
- {
248
- cwd,
249
- input: input ?? '',
250
- shell,
251
- timeout,
252
- ...(run ? { run } : {}),
253
- },
254
- );
261
+ { cwd, input: input ?? '', shell, timeout, ...(run ? { run } : {}) },
262
+ ];
255
263
  }
256
264
 
257
265
  /**
@@ -280,8 +288,8 @@ function runAuthStatus(runDir, deps) {
280
288
  });
281
289
  }
282
290
 
283
- function runReviewer(runDir, prompt, deps) {
284
- return runClaude(CLAUDE_ARGS, {
291
+ function runReviewer(runDir, prompt, effort, deps) {
292
+ return runClaudeNullable(claudeArgs(effort), {
285
293
  cwd: runDir,
286
294
  input: prompt,
287
295
  timeout: INVOKE_TIMEOUT_MS,
@@ -293,22 +301,35 @@ function runReviewer(runDir, prompt, deps) {
293
301
  /**
294
302
  * Preflight, then the review, both from a fresh OS temp dir removed after.
295
303
  *
296
- * @returns {Promise<{ findings: Finding[] } | { reason: string }>}
304
+ * @returns {Promise<{ findings: Finding[] } | { reason: string, retryable?: boolean }>}
297
305
  */
298
- async function reviewInTempDir(prompt, deps) {
306
+ async function reviewInTempDir(prompt, effort, deps) {
299
307
  const runDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mandrel-code-review-'));
300
308
  try {
301
309
  const auth = readAuthStatus(await runAuthStatus(runDir, deps));
302
310
  if (!auth.ok) return auth;
303
311
  deps.logger?.info?.(
304
- `[code-review] Invoking claude --print --effort low (${auth.detail})...`,
312
+ `[code-review] Invoking claude --print --effort ${effort} (${auth.detail})...`,
305
313
  );
306
- return resolveVerdict(await runReviewer(runDir, prompt, deps));
314
+ return resolveVerdict(await runReviewer(runDir, prompt, effort, deps));
307
315
  } finally {
308
316
  fs.rmSync(runDir, { recursive: true, force: true });
309
317
  }
310
318
  }
311
319
 
320
+ /** One invocation, re-run once when its failure is transient-shaped. */
321
+ async function reviewWithRetry(prompt, effort, deps) {
322
+ const first = await reviewInTempDir(prompt, effort, deps);
323
+ if (!first.retryable) return first;
324
+ deps.logger?.warn?.(
325
+ `[code-review] No verdict (${first.reason}); retrying once.`,
326
+ );
327
+ return reviewInTempDir(prompt, effort, deps);
328
+ }
329
+
330
+ /** @param {ReviewInput} input */
331
+ const effortOf = (input) => input.effort ?? 'low';
332
+
312
333
  function assertCliPresent(probeFn) {
313
334
  if (probeFn()) return;
314
335
  throw new Error(
@@ -339,18 +360,38 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
339
360
  let degradations = [];
340
361
 
341
362
  /** Record a not-checked slice without replacing the findings. */
342
- function noteDegradation(reason) {
343
- degradations.push({ ...DEGRADATION_BASE, reason });
363
+ function noteDegradation(reason, kind) {
364
+ degradations.push({ ...DEGRADATION_BASE, kind, reason });
344
365
  deps.logger?.warn?.(`[code-review] Not checked: ${reason}.`);
345
366
  }
346
367
 
347
368
  function settle(verdict) {
348
369
  if (!('reason' in verdict)) return verdict.findings;
349
- degradations.push({ ...DEGRADATION_BASE, reason: verdict.reason });
370
+ degradations.push({
371
+ ...DEGRADATION_BASE,
372
+ kind: 'verdict-missing',
373
+ reason: verdict.reason,
374
+ });
350
375
  deps.logger?.warn?.(`[code-review] No verdict: ${verdict.reason}.`);
351
376
  return [];
352
377
  }
353
378
 
379
+ /**
380
+ * No chunk with a verdict is a review with none: one record naming every
381
+ * file. Otherwise each chunk without one is a partial gap.
382
+ */
383
+ function noteChunkGaps(failed, total) {
384
+ if (failed.length > 0 && failed.length === total) {
385
+ const reasons = [...new Set(failed.map((f) => f.reason))].join('; ');
386
+ const files = failed.map((f) => f.files).join(', ');
387
+ noteDegradation(`no verdict for ${files}: ${reasons}`, 'verdict-missing');
388
+ return;
389
+ }
390
+ for (const { files, reason } of failed) {
391
+ noteDegradation(`no verdict for ${files}: ${reason}`, 'coverage-partial');
392
+ }
393
+ }
394
+
354
395
  /**
355
396
  * The `<callers>` block, guidance, the slice note and the manifest ride every chunk,
356
397
  * so they come out of the budget; chunk numbers are one digit, so the
@@ -376,15 +417,18 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
376
417
  noteDegradation(
377
418
  `review bounded at ${MAX_REVIEW_CHUNKS} chunks: ${overflow.length} ` +
378
419
  `file(s) not reviewed: ${overflow.join(', ')}`,
420
+ 'coverage-partial',
379
421
  );
380
422
  }
381
423
  const findings = [];
424
+ const failed = [];
382
425
  for (const [index, chunk] of chunks.entries()) {
383
426
  const files = chunk.sections.map((s) => s.file).join(', ');
384
427
  if (chunk.size > budget) {
385
428
  noteDegradation(
386
429
  `${files} truncated at ${budget} characters: ` +
387
430
  `${chunk.size - budget} characters not reviewed`,
431
+ 'coverage-partial',
388
432
  );
389
433
  }
390
434
  const prompt = buildPrompt(
@@ -394,13 +438,11 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
394
438
  budget,
395
439
  sliceNote(index + 1, chunks.length) + manifest,
396
440
  );
397
- const verdict = await reviewInTempDir(prompt, runDeps);
398
- if ('reason' in verdict) {
399
- noteDegradation(`no verdict for ${files}: ${verdict.reason}`);
400
- } else {
401
- findings.push(...verdict.findings);
402
- }
441
+ const verdict = await reviewWithRetry(prompt, effortOf(input), runDeps);
442
+ if ('reason' in verdict) failed.push({ files, reason: verdict.reason });
443
+ else findings.push(...verdict.findings);
403
444
  }
445
+ noteChunkGaps(failed, chunks.length);
404
446
  return dedupeFindings(findings);
405
447
  }
406
448
 
@@ -417,13 +459,14 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
417
459
  cwd: PROJECT_ROOT,
418
460
  gitSpawnFn,
419
461
  });
420
- if (callers.reason) noteDegradation(callers.reason);
462
+ if (callers.reason) noteDegradation(callers.reason, 'context-reduced');
421
463
  if (diff.text.length > MAX_DIFF_CHARS) {
422
464
  return reviewInChunks(input, diff.text, callers.text);
423
465
  }
424
466
  return settle(
425
- await reviewInTempDir(
467
+ await reviewWithRetry(
426
468
  buildPrompt(input, diff.text, callers.text),
469
+ effortOf(input),
427
470
  runDeps,
428
471
  ),
429
472
  );
@@ -256,6 +256,18 @@ function boundDegradation(skipped) {
256
256
  ];
257
257
  }
258
258
 
259
+ function voterContext(args) {
260
+ return {
261
+ baseRef: args.baseRef,
262
+ headRef: args.headRef,
263
+ cwd: args.cwd ?? PROJECT_ROOT,
264
+ spawnFn: args.spawnFn,
265
+ platform: args.platform ?? process.platform,
266
+ gitSpawnFn: args.gitSpawnFn ?? gitSpawn,
267
+ cliPresent: (args.probeFn ?? probeClaudeCli)(),
268
+ };
269
+ }
270
+
259
271
  /**
260
272
  * Verify every `critical` finding; findings below critical are never sent.
261
273
  * One verifier at `light`/`standard`, three at `deep`.
@@ -278,15 +290,7 @@ async function verifyCriticals(args) {
278
290
  }
279
291
  const checked = criticals.slice(0, MAX_VERIFIED_CRITICALS);
280
292
  const voters = args.depth === 'deep' ? 3 : 1;
281
- const ctx = {
282
- baseRef: args.baseRef,
283
- headRef: args.headRef,
284
- cwd: args.cwd ?? PROJECT_ROOT,
285
- spawnFn: args.spawnFn,
286
- platform: args.platform ?? process.platform,
287
- gitSpawnFn: args.gitSpawnFn ?? gitSpawn,
288
- cliPresent: (args.probeFn ?? probeClaudeCli)(),
289
- };
293
+ const ctx = voterContext(args);
290
294
  args.logger?.info?.(
291
295
  `[code-review] Verifying ${checked.length} critical(s) with ${voters} verifier(s) each...`,
292
296
  );
@@ -313,6 +317,56 @@ async function verifyCriticals(args) {
313
317
  };
314
318
  }
315
319
 
320
+ /** Whether the review gets a verifier: built-in, or injected seams. */
321
+ const hasVerifier = (opts) => Boolean(opts.verifier || !opts.reviewProvider);
322
+
323
+ /**
324
+ * Re-check earlier CRITICALs at the current head: one call each whatever the
325
+ * depth, the same pool and cap as `verifyCriticals`. Each result is the voter
326
+ * outcome; past the cap or with no verifier the outcome is `skipped`.
327
+ *
328
+ * @param {{ findings: Finding[], reviewInput: { baseRef: string,
329
+ * headRef: string }, opts: object }} args
330
+ * @returns {Promise<{ results: { outcome: string, reason: string }[],
331
+ * degradations: GateDegradation[], verification: VerificationSummary }>}
332
+ */
333
+ export async function recheckCriticals({ findings, reviewInput, opts }) {
334
+ const verification = emptyVerification();
335
+ if (findings.length === 0 || !hasVerifier(opts)) {
336
+ const reason = 'no verifier for this review';
337
+ return {
338
+ results: findings.map(() => ({ outcome: 'skipped', reason })),
339
+ degradations: [],
340
+ verification,
341
+ };
342
+ }
343
+ const checked = findings.slice(0, MAX_VERIFIED_CRITICALS);
344
+ const ctx = voterContext({
345
+ baseRef: reviewInput.baseRef,
346
+ headRef: reviewInput.headRef,
347
+ cwd: opts.cwd,
348
+ gitSpawnFn: opts.gitSpawnFn,
349
+ ...opts.verifier,
350
+ });
351
+ const votes = await runPooled(
352
+ checked.map((f) => () => runVoter(f, ctx)),
353
+ MAX_IN_FLIGHT,
354
+ );
355
+ for (const v of votes) verification[v.outcome] += 1;
356
+ verification.attempted = votes.length;
357
+ return {
358
+ results: findings.map(
359
+ (_, i) =>
360
+ votes[i] ?? { outcome: 'skipped', reason: 'verification cap reached' },
361
+ ),
362
+ degradations: [
363
+ ...checked.flatMap((f, i) => voteDegradations(f, [votes[i]])),
364
+ ...boundDegradation(findings.slice(MAX_VERIFIED_CRITICALS)),
365
+ ],
366
+ verification,
367
+ };
368
+ }
369
+
316
370
  /**
317
371
  * The pipeline step: ground every finding, then verify the CRITICALs left.
318
372
  * An injected review provider gets no verifier unless `opts.verifier` (the
@@ -337,8 +391,7 @@ export async function vetFindings({
337
391
  degradations,
338
392
  gitSpawnFn: opts.gitSpawnFn,
339
393
  });
340
- const verify =
341
- opts.verifier || !opts.reviewProvider ? verifyCriticals : skipVerification;
394
+ const verify = hasVerifier(opts) ? verifyCriticals : skipVerification;
342
395
  const verified = await verify({
343
396
  findings: grounded.findings,
344
397
  baseRef,
@@ -1,17 +1,29 @@
1
1
  /**
2
2
  * review-providers/degraded-gates.js — the "a gate did not run" channel,
3
- * travelling beside `Finding[]` so "never ran" cannot read as clean. It
4
- * reports rather than blocks: close already hard-gates `npm run lint`.
3
+ * travelling beside `Finding[]` so "never ran" cannot read as clean. Its
4
+ * `kind` blocks only under `delivery.codeReview.onNoVerdict: "block"`.
5
5
  */
6
6
 
7
7
  /**
8
+ * @typedef {'verdict-missing'|'coverage-partial'|'context-reduced'} DegradationKind
8
9
  * @typedef {object} GateDegradation
9
10
  * @property {string} tool
10
11
  * @property {string} gate
11
12
  * @property {string} surface Sub-surface that could not run.
13
+ * @property {DegradationKind} kind
12
14
  * @property {string} reason
13
15
  */
14
16
 
17
+ const DEGRADATION_KINDS = Object.freeze([
18
+ 'verdict-missing',
19
+ 'coverage-partial',
20
+ 'context-reduced',
21
+ ]);
22
+
23
+ /** An absent or unknown kind is the one kind that can never block. */
24
+ const kindOf = (kind) =>
25
+ DEGRADATION_KINDS.includes(kind) ? kind : 'context-reduced';
26
+
15
27
  /**
16
28
  * Keep only well-formed records, so a misbehaving provider cannot corrupt output.
17
29
  *
@@ -30,12 +42,95 @@ export function normalizeDegradations(input) {
30
42
  tool: typeof d.tool === 'string' ? d.tool : 'unknown',
31
43
  gate: typeof d.gate === 'string' ? d.gate : 'unknown',
32
44
  surface,
45
+ kind: kindOf(d.kind),
33
46
  reason,
34
47
  });
35
48
  }
36
49
  return out;
37
50
  }
38
51
 
52
+ /**
53
+ * Close's `gates.codeReview`: overridden > unreviewed > partial > degraded > passed.
54
+ *
55
+ * @param {unknown} degradations
56
+ * @param {{ overridden?: boolean }} [opts]
57
+ * @returns {'overridden'|'unreviewed'|'partial'|'degraded'|'passed'}
58
+ */
59
+ export function reviewGateValue(degradations, { overridden = false } = {}) {
60
+ if (overridden) return 'overridden';
61
+ const kinds = new Set(normalizeDegradations(degradations).map((d) => d.kind));
62
+ if (kinds.has('verdict-missing')) return 'unreviewed';
63
+ if (kinds.has('coverage-partial')) return 'partial';
64
+ return kinds.size > 0 ? 'degraded' : 'passed';
65
+ }
66
+
67
+ const REDUCED_CONTEXT =
68
+ '⚠️ Review ran DEGRADED — reviewed with reduced context, so the surface(s) ' +
69
+ 'above were not fully checked. The close is not blocked by reduced ' +
70
+ 'context, but nothing here vouches for those surfaces.';
71
+
72
+ const NOT_VOUCHED =
73
+ 'unless `delivery.codeReview.onNoVerdict` is `block`; nothing here vouches ' +
74
+ 'for those surfaces.';
75
+
76
+ /**
77
+ * @param {unknown} degradations
78
+ * @returns {string[]}
79
+ */
80
+ export function reviewGapLines(degradations) {
81
+ const gate = reviewGateValue(degradations);
82
+ if (gate === 'unreviewed') {
83
+ return [
84
+ `⚠️ Review UNREVIEWED — no verdict for the surface(s) above. The close is not blocked ${NOT_VOUCHED}`,
85
+ ];
86
+ }
87
+ if (gate === 'partial') {
88
+ return [
89
+ `⚠️ Review ran PARTIAL — part of the diff above was not reviewed. The close is not blocked ${NOT_VOUCHED}`,
90
+ ];
91
+ }
92
+ return gate === 'degraded' ? [REDUCED_CONTEXT] : [];
93
+ }
94
+
95
+ /** The fix each no-verdict cause needs; matched on the record, never on PII. */
96
+ const NO_VERDICT_FIXES = [
97
+ [/not logged in|auth status/, 'run `claude auth login`'],
98
+ [/out of quota|usage limit/, 'wait for the usage-limit reset'],
99
+ [/skipped/, 'install the `claude` or `codex` CLI'],
100
+ [/remote-base-ref-unresolved/, 'fetch the base ref'],
101
+ ];
102
+
103
+ function fixFor(reason) {
104
+ const hit = NO_VERDICT_FIXES.find(([re]) => re.test(reason));
105
+ return hit ? hit[1] : 'fix the cause';
106
+ }
107
+
108
+ /**
109
+ * Under `onNoVerdict: "block"`, a verdict-missing or coverage-partial record
110
+ * halts the review; context-reduced never does.
111
+ *
112
+ * @param {{ degradations: unknown, onNoVerdict?: string, storyId: number|string }} args
113
+ * @returns {{ halted: true, haltCause: 'no-verdict', blockerReason: string }|null}
114
+ */
115
+ export function resolveNoVerdictHalt({ degradations, onNoVerdict, storyId }) {
116
+ if (onNoVerdict !== 'block') return null;
117
+ const blocking = normalizeDegradations(degradations).filter(
118
+ (d) => d.kind !== 'context-reduced',
119
+ );
120
+ if (blocking.length === 0) return null;
121
+ const causes = blocking.map(
122
+ (d) => `${d.surface} [${d.kind}]: ${d.reason} — ${fixFor(d.reason)}`,
123
+ );
124
+ return {
125
+ halted: true,
126
+ haltCause: 'no-verdict',
127
+ blockerReason:
128
+ `code-review produced no verdict for part or all of the diff ` +
129
+ `(delivery.codeReview.onNoVerdict: block): ${causes.join('; ')}. ` +
130
+ `Then re-run \`node .agents/scripts/story-review-compute.js --story ${storyId}\`.`,
131
+ };
132
+ }
133
+
39
134
  /**
40
135
  * Feature-detected; a throw degrades to empty. MUST be called after
41
136
  * `runReview`, which is when a provider records its degradations.
@@ -152,7 +247,7 @@ export function renderDegradedGatesSection(degradations) {
152
247
  ];
153
248
  for (const d of rows) {
154
249
  lines.push(
155
- `- \`${d.gate}\` → \`${d.surface}\` could not execute — ${d.reason} (emitter: \`${d.tool}\`).`,
250
+ `- \`${d.gate}\` → \`${d.surface}\` (${d.kind}) could not execute — ${d.reason} (emitter: \`${d.tool}\`).`,
156
251
  );
157
252
  }
158
253
  lines.push('');
@@ -34,12 +34,16 @@ function normalizeTitle(title) {
34
34
 
35
35
  /**
36
36
  * First 12 hex chars of sha256 over class (else category), first instance
37
- * file and, for a class-less finding, its normalized title.
37
+ * file and, for a class-less finding, its normalized title. A finding carried
38
+ * forward from the review history keeps the id it was recorded under.
38
39
  *
39
40
  * @param {Finding} finding
40
41
  * @returns {string}
41
42
  */
42
- export function findingId(finding) {
43
+ export const findingId = (finding) => finding?.carriedId ?? contentId(finding);
44
+
45
+ /** @param {Finding} finding */
46
+ function contentId(finding) {
43
47
  const cls = finding?.class;
44
48
  const parts = [
45
49
  cls || finding?.category || 'bug',
@@ -115,10 +115,57 @@ function renderRepeatsSection(repeats) {
115
115
  ];
116
116
  }
117
117
 
118
- /** Fresh findings render in full per tier; repeats render collapsed. */
118
+ const EARLIER_STATUS = Object.freeze({
119
+ 'still-open': 'still open',
120
+ fixed: 'fixed',
121
+ refuted: 'refuted',
122
+ overridden: 'overridden',
123
+ });
124
+
125
+ /** @param {{ id: string, title: string|null, instances: object[], headSha: string, status: string, reason?: string }} e */
126
+ function renderEarlier(e) {
127
+ const where = e.instances.map((i) => `\`${formatLocation(i)}\``).join(', ');
128
+ const status = EARLIER_STATUS[e.status] ?? e.status;
129
+ return (
130
+ `- ${e.title ?? '(untitled)'} — \`${e.id}\`${where ? ` — ${where}` : ''}` +
131
+ ` — raised at \`${e.headSha}\` — **${status}**${e.reason ? `: ${e.reason}` : ''}`
132
+ );
133
+ }
134
+
135
+ /** Every earlier surviving CRITICAL, in history order, with its status. */
136
+ function renderEarlierSection(earlier) {
137
+ if (!Array.isArray(earlier) || earlier.length === 0) return [];
138
+ return [
139
+ `### 🔁 Earlier CRITICALs (${earlier.length})`,
140
+ '',
141
+ ...earlier.map(renderEarlier),
142
+ '',
143
+ ];
144
+ }
145
+
146
+ /**
147
+ * The findings, or the no-findings block unless an earlier CRITICAL is
148
+ * still open.
149
+ */
150
+ function renderBody(findings, totalKnown, degraded, earlier = []) {
151
+ if (totalKnown > 0) return renderFindingSections(findings);
152
+ return earlier.some((e) => e.status === 'still-open')
153
+ ? []
154
+ : renderNoFindingsBlock(degraded);
155
+ }
156
+
157
+ /** Rendered in full under its tier. */
158
+ const isFresh = (f) => f && !f.repeat && !f.carried;
159
+ /** Rendered collapsed under Previously raised. */
160
+ const isRepeat = (f) => f?.repeat && !f.carried;
161
+
162
+ /**
163
+ * Fresh findings render in full per tier; repeats render collapsed; carried
164
+ * ones render only under Earlier CRITICALs.
165
+ */
119
166
  function renderFindingSections(findings) {
120
167
  const lines = [];
121
- const fresh = findings.filter((f) => f && !f.repeat);
168
+ const fresh = findings.filter(isFresh);
122
169
  for (const sev of SEVERITY_ORDER) {
123
170
  const tierFindings = fresh.filter((f) => f.severity === sev);
124
171
  if (tierFindings.length === 0) continue;
@@ -126,7 +173,7 @@ function renderFindingSections(findings) {
126
173
  lines.push(`### ${meta.emoji} ${meta.label} (${tierFindings.length})`, '');
127
174
  for (const finding of tierFindings) lines.push(renderFinding(finding), '');
128
175
  }
129
- return [...lines, ...renderRepeatsSection(findings.filter((f) => f?.repeat))];
176
+ return [...lines, ...renderRepeatsSection(findings.filter(isRepeat))];
130
177
  }
131
178
 
132
179
  /**
@@ -160,6 +207,7 @@ function renderManualPromptsSection(messages) {
160
207
  * degradations?: ReadonlyArray<object>,
161
208
  * verification?: Record<string, number>,
162
209
  * skipped?: number,
210
+ * earlierCriticals?: ReadonlyArray<object>,
163
211
  * }} input
164
212
  * @returns {string}
165
213
  */
@@ -197,11 +245,10 @@ export function renderFindings(input) {
197
245
  ...renderDegradedGatesSection(degraded),
198
246
  ];
199
247
 
200
- if (totalKnown === 0) {
201
- lines.push(...renderNoFindingsBlock(degraded));
202
- } else {
203
- lines.push(...renderFindingSections(findings));
204
- }
248
+ lines.push(
249
+ ...renderEarlierSection(input.earlierCriticals),
250
+ ...renderBody(findings, totalKnown, degraded, input.earlierCriticals),
251
+ );
205
252
 
206
253
  const promptLines = renderManualPromptsSection(promptMessages ?? []);
207
254
  if (promptLines.length > 0) {
@@ -46,6 +46,7 @@ export function loadReviewGuidance({
46
46
  tool: 'review-guidance',
47
47
  gate: 'codeReview',
48
48
  surface: 'review-guidance',
49
+ kind: 'context-reduced',
49
50
  reason:
50
51
  `${file} truncated at ${MAX_GUIDANCE_CHARS} characters: ` +
51
52
  `${trimmed.length - MAX_GUIDANCE_CHARS} characters not rendered`,