mandrel 2.111.0 → 2.113.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 (183) 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/docs/agentrc-reference.json +22 -10
  6. package/.agents/docs/configuration.md +367 -37
  7. package/.agents/docs/execution-reference.md +11 -0
  8. package/.agents/rules/git-conventions-reference.md +7 -0
  9. package/.agents/schemas/agentrc.schema.json +174 -14
  10. package/.agents/schemas/baselines/baseline-envelope.schema.json +16 -4
  11. package/.agents/schemas/baselines/bundle-size.schema.json +1 -0
  12. package/.agents/schemas/baselines/coverage.schema.json +1 -0
  13. package/.agents/schemas/baselines/crap.schema.json +37 -10
  14. package/.agents/schemas/baselines/duplication.schema.json +1 -0
  15. package/.agents/schemas/baselines/maintainability.schema.json +1 -0
  16. package/.agents/schemas/baselines/mutation.schema.json +1 -0
  17. package/.agents/schemas/crap-report.schema.json +6 -5
  18. package/.agents/schemas/story-deliver-terminal.schema.json +41 -2
  19. package/.agents/schemas/story-progress.schema.json +1 -1
  20. package/.agents/schemas/validation-evidence.schema.json +2 -2
  21. package/.agents/scripts/boot-sweep.js +41 -3
  22. package/.agents/scripts/coverage-capture.js +37 -3
  23. package/.agents/scripts/coverage-ratchet.js +106 -0
  24. package/.agents/scripts/evidence-gate.js +84 -21
  25. package/.agents/scripts/lib/audit-baselines/read.js +8 -1
  26. package/.agents/scripts/lib/audit-baselines/trend.js +2 -1
  27. package/.agents/scripts/lib/baseline-loader.js +4 -2
  28. package/.agents/scripts/lib/baselines/codec.js +57 -0
  29. package/.agents/scripts/lib/baselines/crap-preview-incremental.js +8 -3
  30. package/.agents/scripts/lib/baselines/crap-preview-scan.js +10 -16
  31. package/.agents/scripts/lib/baselines/crap-updater-cli.js +4 -13
  32. package/.agents/scripts/lib/baselines/kernel.js +19 -1
  33. package/.agents/scripts/lib/baselines/kinds/_crap-codec.js +171 -0
  34. package/.agents/scripts/lib/baselines/kinds/_crap-read.js +56 -16
  35. package/.agents/scripts/lib/baselines/kinds/_shared-metric.js +0 -59
  36. package/.agents/scripts/lib/baselines/kinds/crap.js +283 -319
  37. package/.agents/scripts/lib/baselines/merge-envelopes.js +46 -1
  38. package/.agents/scripts/lib/baselines/preview-gates.js +29 -10
  39. package/.agents/scripts/lib/baselines/reader.js +36 -9
  40. package/.agents/scripts/lib/baselines/refresh-service.js +93 -21
  41. package/.agents/scripts/lib/baselines/seat-missing.js +173 -7
  42. package/.agents/scripts/lib/baselines/writer.js +36 -21
  43. package/.agents/scripts/lib/changed-files.js +70 -6
  44. package/.agents/scripts/lib/child-exec.js +10 -0
  45. package/.agents/scripts/lib/claude/agents-projection.js +5 -5
  46. package/.agents/scripts/lib/close-lock-events.js +8 -3
  47. package/.agents/scripts/lib/close-validation/ci-deferral.js +40 -0
  48. package/.agents/scripts/lib/close-validation/gates.js +111 -35
  49. package/.agents/scripts/lib/close-validation/process.js +16 -7
  50. package/.agents/scripts/lib/close-validation/projections/crap.js +43 -10
  51. package/.agents/scripts/lib/close-validation/runner.js +55 -23
  52. package/.agents/scripts/lib/close-validation/skip-branch-test.js +144 -0
  53. package/.agents/scripts/lib/close-validation/test-delta.js +33 -8
  54. package/.agents/scripts/lib/codex/agents-projection.js +6 -0
  55. package/.agents/scripts/lib/config/agentrc-overlay.js +9 -5
  56. package/.agents/scripts/lib/config/explain.js +5 -2
  57. package/.agents/scripts/lib/config/gates/coverage.schema.js +45 -1
  58. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  59. package/.agents/scripts/lib/config/git-roots.js +38 -4
  60. package/.agents/scripts/lib/config/handoff.js +24 -0
  61. package/.agents/scripts/lib/config/quality.js +26 -13
  62. package/.agents/scripts/lib/config/worktree-isolation.js +2 -5
  63. package/.agents/scripts/lib/config-resolver.js +22 -2
  64. package/.agents/scripts/lib/config-settings-schema-delivery.js +87 -4
  65. package/.agents/scripts/lib/config-settings-schema-quality.js +36 -1
  66. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  67. package/.agents/scripts/lib/coverage-capture-affected.js +1 -0
  68. package/.agents/scripts/lib/coverage-capture-delta.js +164 -32
  69. package/.agents/scripts/lib/coverage-capture-own-fix.js +232 -0
  70. package/.agents/scripts/lib/coverage-capture-usage.js +2 -2
  71. package/.agents/scripts/lib/coverage-capture.js +15 -0
  72. package/.agents/scripts/lib/coverage-deferral.js +96 -0
  73. package/.agents/scripts/lib/coverage-ratchet.js +187 -0
  74. package/.agents/scripts/lib/crap-baseline-join.js +5 -5
  75. package/.agents/scripts/lib/crap-engine.js +3 -3
  76. package/.agents/scripts/lib/crap-method-identity.js +104 -48
  77. package/.agents/scripts/lib/error-redactor.js +20 -0
  78. package/.agents/scripts/lib/escomplex-anchor.js +135 -0
  79. package/.agents/scripts/lib/escomplex-kernel.js +30 -1
  80. package/.agents/scripts/lib/failure-rows.js +121 -0
  81. package/.agents/scripts/lib/full-suite-lock.js +44 -4
  82. package/.agents/scripts/lib/full-suite-queue.js +89 -13
  83. package/.agents/scripts/lib/generated/agentrc-validator.js +8 -2
  84. package/.agents/scripts/lib/gh-env.js +3 -6
  85. package/.agents/scripts/lib/gh-pr-rest.js +1 -0
  86. package/.agents/scripts/lib/git/base-sync-probe.js +182 -0
  87. package/.agents/scripts/lib/git/baseline-conflict-rows.js +60 -0
  88. package/.agents/scripts/lib/git/sync-from-base.js +18 -9
  89. package/.agents/scripts/lib/git-branch-lifecycle.js +9 -0
  90. package/.agents/scripts/lib/observability/close-telemetry.js +37 -2
  91. package/.agents/scripts/lib/observability/handoff-telemetry.js +170 -0
  92. package/.agents/scripts/lib/observability/review-dispositions.js +23 -6
  93. package/.agents/scripts/lib/observability/runtime-friction.js +17 -4
  94. package/.agents/scripts/lib/observability/source-classifier.js +3 -0
  95. package/.agents/scripts/lib/observability/story-outcome.js +393 -0
  96. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +2 -1
  97. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +19 -1
  98. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +84 -0
  99. package/.agents/scripts/lib/orchestration/check-baselines/phases/pipeline.js +14 -5
  100. package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js +3 -2
  101. package/.agents/scripts/lib/orchestration/check-baselines/phases/report.js +26 -6
  102. package/.agents/scripts/lib/orchestration/code-review.js +223 -19
  103. package/.agents/scripts/lib/orchestration/handoff-gates.js +129 -62
  104. package/.agents/scripts/lib/orchestration/handoff-rescore.js +170 -0
  105. package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +45 -0
  106. package/.agents/scripts/lib/orchestration/preflight-lanes.js +208 -0
  107. package/.agents/scripts/lib/orchestration/review-base-ref.js +40 -17
  108. package/.agents/scripts/lib/orchestration/review-deposit.js +38 -12
  109. package/.agents/scripts/lib/orchestration/review-depth.js +21 -0
  110. package/.agents/scripts/lib/orchestration/review-history.js +124 -20
  111. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +41 -12
  112. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +90 -39
  113. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +64 -11
  114. package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js +102 -3
  115. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +6 -2
  116. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +55 -8
  117. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +1 -0
  118. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +42 -15
  119. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  120. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +10 -1
  121. package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js +10 -0
  122. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +7 -4
  123. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +16 -3
  124. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +59 -2
  125. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +6 -0
  126. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +15 -4
  127. package/.agents/scripts/lib/orchestration/single-story-close/phases/land-review-record.js +213 -0
  128. package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +9 -12
  129. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +26 -12
  130. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +51 -26
  131. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-gate-steps.js +2 -1
  132. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +3 -2
  133. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +50 -17
  134. package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js +59 -11
  135. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +1 -0
  136. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-block.js +31 -13
  137. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +29 -6
  138. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-outcome.js +10 -12
  139. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +19 -4
  140. package/.agents/scripts/lib/orchestration/single-story-close/result.js +30 -13
  141. package/.agents/scripts/lib/orchestration/single-story-close/review-overlap.js +73 -39
  142. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +11 -3
  143. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +3 -2
  144. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +77 -15
  145. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +7 -0
  146. package/.agents/scripts/lib/orchestration/story-handoff.js +796 -196
  147. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  148. package/.agents/scripts/lib/pr-body-lines.js +32 -0
  149. package/.agents/scripts/lib/single-story/ci-ratchet-gate.js +140 -0
  150. package/.agents/scripts/lib/single-story/confirm-and-land.js +17 -7
  151. package/.agents/scripts/lib/single-story/confirm-merge.js +12 -3
  152. package/.agents/scripts/lib/single-story-sweep/report-stalled-executing.js +202 -0
  153. package/.agents/scripts/lib/standalone-ratchets.js +37 -0
  154. package/.agents/scripts/lib/suite-admission.js +20 -8
  155. package/.agents/scripts/lib/suite-sizing.js +146 -0
  156. package/.agents/scripts/lib/workspace-provisioner.js +2 -2
  157. package/.agents/scripts/merge-baseline.js +14 -3
  158. package/.agents/scripts/providers/github/comments.js +19 -3
  159. package/.agents/scripts/providers/github.js +1 -0
  160. package/.agents/scripts/review-dispositions-report.js +1 -1
  161. package/.agents/scripts/role-scope-guard.js +267 -0
  162. package/.agents/scripts/single-story-close.js +4 -4
  163. package/.agents/scripts/single-story-confirm-merge.js +31 -5
  164. package/.agents/scripts/single-story-init.js +24 -4
  165. package/.agents/scripts/story-handoff.js +3 -3
  166. package/.agents/scripts/story-outcomes-report.js +231 -0
  167. package/.agents/scripts/story-review-compute.js +9 -5
  168. package/.agents/scripts/update-coverage-baseline.js +12 -2
  169. package/.agents/scripts/update-crap-baseline.js +9 -1
  170. package/.agents/workflows/helpers/code-review.md +63 -9
  171. package/.agents/workflows/helpers/deliver-digest.md +53 -54
  172. package/.agents/workflows/helpers/deliver-reference.md +233 -67
  173. package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
  174. package/.agents/workflows/helpers/deliver-story.md +7 -2
  175. package/.agents/workflows/helpers/parallel-tooling.md +29 -0
  176. package/docs/CHANGELOG.md +55 -0
  177. package/lib/cli/doctor-checks/coverage-ratchet.js +54 -0
  178. package/lib/cli/doctor-checks/effective-agentrc.js +23 -0
  179. package/lib/cli/doctor-checks/llm-review.js +2 -11
  180. package/lib/cli/doctor-checks/sync-parity.js +5 -1
  181. package/lib/cli/doctor-checks/test-credit-path.js +7 -2
  182. package/lib/cli/registry.js +5 -0
  183. package/package.json +1 -1
@@ -6,34 +6,82 @@
6
6
  * `core.hooksPath` is relative, so the invocation directory decides which
7
7
  * tree `pre-push` measures (the main checkout gave false greens). With no
8
8
  * worktree, the main checkout is the pushed tree.
9
+ * A no-op push still starts `pre-push`, so origin already at the tip skips.
9
10
  */
10
11
 
11
- import { gitSync as defaultGitSync } from '../../../git-utils.js';
12
+ import { remoteBranchSha } from '../../../git-branch-lifecycle.js';
13
+ import {
14
+ gitSpawn as defaultGitSpawn,
15
+ gitSync as defaultGitSync,
16
+ } from '../../../git-utils.js';
17
+
18
+ function localTip(cwd, branch, gitSpawn) {
19
+ const res = gitSpawn(cwd, 'rev-parse', `refs/heads/${branch}`);
20
+ return res?.status === 0 ? `${res.stdout ?? ''}`.trim() || null : null;
21
+ }
22
+
23
+ function originAtLocalTip(cwd, branch, gitSpawn) {
24
+ try {
25
+ const sha = localTip(cwd, branch, gitSpawn);
26
+ const remote = sha && remoteBranchSha(cwd, branch, gitSpawn);
27
+ return Boolean(remote?.reachable && remote.sha === sha);
28
+ } catch {
29
+ return false;
30
+ }
31
+ }
32
+
33
+ function push(cwd, storyBranch, gitSync, progress) {
34
+ progress('GIT', `Pushing ${storyBranch} to origin...`);
35
+ try {
36
+ // Never bypass hooks: under `--skip-validation`, `pre-push` is the only gate.
37
+ gitSync(cwd, 'push', '-u', 'origin', storyBranch);
38
+ progress('GIT', `✅ Pushed ${storyBranch}.`);
39
+ } catch (err) {
40
+ throw new Error(
41
+ `[single-story-close] git push failed for ${storyBranch}: ${err?.message ?? err}`,
42
+ );
43
+ }
44
+ return { outcome: 'pushed' };
45
+ }
46
+
47
+ function settlePush({ pushCwd, storyBranch, skipValidation, ...git }) {
48
+ if (skipValidation || !originAtLocalTip(pushCwd, storyBranch, git.gitSpawn)) {
49
+ return push(pushCwd, storyBranch, git.gitSync, git.progress);
50
+ }
51
+ git.progress(
52
+ 'GIT',
53
+ `⏭ origin/${storyBranch} already at HEAD — push skipped.`,
54
+ );
55
+ return { outcome: 'skipped-already-at-head' };
56
+ }
12
57
 
13
58
  /**
14
59
  * @param {{
15
60
  * cwd: string,
16
61
  * worktreePath?: string|null,
17
62
  * storyBranch: string,
63
+ * skipValidation?: boolean,
18
64
  * gitSync?: typeof defaultGitSync,
65
+ * gitSpawn?: typeof defaultGitSpawn,
19
66
  * progress: (tag: string, msg: string) => void,
20
67
  * }} args
68
+ * @returns {{ outcome: 'pushed'|'skipped-already-at-head' }}
21
69
  */
22
70
  export function pushStoryBranch({
23
71
  cwd,
24
72
  worktreePath = null,
25
73
  storyBranch,
74
+ skipValidation = false,
26
75
  gitSync = defaultGitSync,
76
+ gitSpawn = defaultGitSpawn,
27
77
  progress,
28
78
  }) {
29
- progress('GIT', `Pushing ${storyBranch} to origin...`);
30
- try {
31
- // Never bypass hooks: under `--skip-validation`, `pre-push` is the only gate.
32
- gitSync(worktreePath ?? cwd, 'push', '-u', 'origin', storyBranch);
33
- progress('GIT', `✅ Pushed ${storyBranch}.`);
34
- } catch (err) {
35
- throw new Error(
36
- `[single-story-close] git push failed for ${storyBranch}: ${err?.message ?? err}`,
37
- );
38
- }
79
+ return settlePush({
80
+ pushCwd: worktreePath ?? cwd,
81
+ storyBranch,
82
+ skipValidation,
83
+ gitSync,
84
+ gitSpawn,
85
+ progress,
86
+ });
39
87
  }
@@ -68,6 +68,7 @@ async function reconcileFromMergedHead(ctx, deps, progress) {
68
68
  cwd: ctx.options.cwd,
69
69
  config: deps.config,
70
70
  progress,
71
+ injectedGh: deps.gh,
71
72
  injectedNotify: deps.notify,
72
73
  prState: { state: 'MERGED', mergedAt: null },
73
74
  sleepFn: deps.sleep,
@@ -5,27 +5,45 @@ import {
5
5
  upsertStructuredComment,
6
6
  } from '../../ticketing.js';
7
7
 
8
- /**
9
- * Record a critical code-review halt as authoritative blocked state before
10
- * close releases the Story lease and returns non-zero.
11
- */
12
- export async function handleCriticalReviewBlock({
13
- provider,
14
- storyId,
15
- prUrl,
16
- criticalCount,
17
- }) {
18
- const body = [
19
- '### Code review blocked delivery',
20
- '',
8
+ /** What halted: a critical count, or the no-verdict cause and its fix. */
9
+ function haltLines({ prUrl, criticalCount, noVerdictReason }) {
10
+ if (noVerdictReason) {
11
+ return [
12
+ `The Story-scope review on ${prUrl} produced **no verdict** for part or all of the diff, and \`delivery.codeReview.onNoVerdict\` is \`block\`.`,
13
+ '',
14
+ noVerdictReason,
15
+ ];
16
+ }
17
+ return [
21
18
  `The Story-scope review reported **${criticalCount} critical blocker(s)** on ${prUrl}.`,
22
19
  'Remediate the posted findings, then re-run `/mandrel-deliver`.',
20
+ ];
21
+ }
22
+
23
+ /** @param {{ prUrl: string, criticalCount: number, noVerdictReason?: string|null }} halt */
24
+ function blockBody(halt) {
25
+ return [
26
+ '### Code review blocked delivery',
27
+ '',
28
+ ...haltLines(halt),
23
29
  '',
24
30
  'If you have reviewed a finding and judged it wrong, re-run close with',
25
31
  '`--override-review-block "<reason>"` rather than merging by hand — see',
26
32
  '`phases/review-override.js`. The override is recorded on the Story, on the',
27
33
  'PR, and as friction telemetry.',
28
34
  ].join('\n');
35
+ }
36
+
37
+ /**
38
+ * Record a code-review halt (critical or no-verdict) as authoritative
39
+ * blocked state before close releases the Story lease and returns non-zero.
40
+ */
41
+ export async function handleCriticalReviewBlock({
42
+ provider,
43
+ storyId,
44
+ ...halt
45
+ }) {
46
+ const body = blockBody(halt);
29
47
  try {
30
48
  await upsertStructuredComment(provider, storyId, 'friction', body);
31
49
  } catch (err) {
@@ -2,6 +2,31 @@ import { emitReviewBlockedFriction } from '../../../observability/close-telemetr
2
2
  import { handleCriticalReviewBlock } from './review-block.js';
3
3
  import { handleOverriddenReviewBlock } from './review-override.js';
4
4
 
5
+ /**
6
+ * The thrown message for a halt: a critical count, or the no-verdict blocker.
7
+ *
8
+ * @param {{ prUrl: string, criticalCount: number, noVerdictReason: string|null }} args
9
+ * @returns {string}
10
+ */
11
+ function haltMessage({ prUrl, criticalCount, noVerdictReason }) {
12
+ const head = noVerdictReason
13
+ ? `[single-story-close] Story-scope review produced no verdict on PR ${prUrl}: ${noVerdictReason} ` +
14
+ 'Auto-merge was not enabled. '
15
+ : `[single-story-close] Story-scope review reported ${criticalCount} critical blocker(s) on PR ${prUrl}. ` +
16
+ 'Auto-merge was not enabled. Remediate the findings posted to the PR and re-run `/mandrel-deliver`. ';
17
+ return (
18
+ head +
19
+ 'If you have reviewed a finding and judged it wrong, re-run with ' +
20
+ '`--override-review-block "<reason>"` rather than merging by hand.'
21
+ );
22
+ }
23
+
24
+ /** @param {{ haltCause?: string, blockerReason?: string|null }} outcome */
25
+ function noVerdictReasonOf({ haltCause, blockerReason }) {
26
+ if (haltCause !== 'no-verdict') return null;
27
+ return blockerReason ?? 'no verdict';
28
+ }
29
+
5
30
  /**
6
31
  * An overridden Story proceeds; anything else emits friction, blocks, throws.
7
32
  *
@@ -17,6 +42,7 @@ export async function resolveReviewHalt(
17
42
  ) {
18
43
  const { storyId } = ctx;
19
44
  const criticalCount = reviewOutcome.severity?.critical ?? 0;
45
+ const noVerdictReason = noVerdictReasonOf(reviewOutcome);
20
46
  // Checked before the blocked transition: an overridden Story proceeds.
21
47
  if (ctx.options.overrideReviewBlock) {
22
48
  return await handleOverriddenReviewBlock({
@@ -27,6 +53,7 @@ export async function resolveReviewHalt(
27
53
  criticalCount,
28
54
  criticalByProvider: reviewOutcome.criticalByProvider,
29
55
  reason: ctx.options.overrideReviewBlock,
56
+ noVerdictReason,
30
57
  findings: reviewOutcome.findings ?? [],
31
58
  config: deps.config,
32
59
  });
@@ -43,11 +70,7 @@ export async function resolveReviewHalt(
43
70
  storyId,
44
71
  prUrl,
45
72
  criticalCount,
73
+ noVerdictReason,
46
74
  });
47
- throw new Error(
48
- `[single-story-close] Story-scope review reported ${criticalCount} critical blocker(s) on PR ${prUrl}. ` +
49
- 'Auto-merge was not enabled. Remediate the findings posted to the PR and re-run `/mandrel-deliver`. ' +
50
- 'If you have reviewed a finding and judged it wrong, re-run with ' +
51
- '`--override-review-block "<reason>"` rather than merging by hand.',
52
- );
75
+ throw new Error(haltMessage({ prUrl, criticalCount, noVerdictReason }));
53
76
  }
@@ -1,11 +1,14 @@
1
1
  /**
2
2
  * phases/review-outcome.js — renders the review outcome, always stating the
3
3
  * degraded gates (`none` when healthy) so "never ran" cannot read as
4
- * "found nothing". Degraded is reported, not blocking — and never claim
5
- * another gate covered the surface; this module cannot see that.
4
+ * "found nothing". It never claims another gate covered the surface; this
5
+ * module cannot see that.
6
6
  */
7
7
 
8
- import { summarizeDegradations } from '../../review-providers/degraded-gates.js';
8
+ import {
9
+ reviewGapLines,
10
+ summarizeDegradations,
11
+ } from '../../review-providers/degraded-gates.js';
9
12
 
10
13
  /**
11
14
  * @param {{ severity: { critical: number, high: number, medium: number, suggestion: number }, degradations?: unknown }} args
@@ -35,13 +38,8 @@ export function formatReviewOutcomeLines({
35
38
  posted,
36
39
  }) {
37
40
  const tally = buildOutcomeTally({ severity, degradations });
38
- const lines = [`Findings — ${tally}. Posted to PR #${prNumber}: ${posted}.`];
39
- if (summarizeDegradations(degradations) !== 'none') {
40
- lines.push(
41
- '⚠️ Review ran DEGRADED — the surface(s) above were not reviewed. The close ' +
42
- 'is not blocked — a secondary review does not gate the merge — but ' +
43
- 'nothing here vouches for those surfaces.',
44
- );
45
- }
46
- return lines;
41
+ return [
42
+ `Findings — ${tally}. Posted to PR #${prNumber}: ${posted}.`,
43
+ ...reviewGapLines(degradations),
44
+ ];
47
45
  }
@@ -18,15 +18,23 @@ import {
18
18
 
19
19
  const REASON_SIGNAL_LIMIT = 500;
20
20
 
21
+ /** The halt being overridden, as one sentence. */
22
+ function haltSummary({ prUrl, criticalCount, noVerdictReason }) {
23
+ if (noVerdictReason) {
24
+ return `The Story-scope review produced **no verdict** on ${prUrl}: ${noVerdictReason}`;
25
+ }
26
+ return `The Story-scope review reported **${criticalCount} critical blocker(s)** on ${prUrl}.`;
27
+ }
28
+
21
29
  /**
22
- * @param {{ prUrl: string, criticalCount: number, reason: string }} args
30
+ * @param {{ prUrl: string, criticalCount: number, reason: string, noVerdictReason?: string|null }} args
23
31
  * @returns {string}
24
32
  */
25
- function buildReviewOverrideBody({ prUrl, criticalCount, reason }) {
33
+ function buildReviewOverrideBody({ reason, ...halt }) {
26
34
  return [
27
35
  '### Code-review blocker overridden by operator',
28
36
  '',
29
- `The Story-scope review reported **${criticalCount} critical blocker(s)** on ${prUrl}.`,
37
+ haltSummary(halt),
30
38
  'The operator reviewed and rejected the finding(s) and authorized delivery',
31
39
  'with `--override-review-block`; auto-merge was armed.',
32
40
  '',
@@ -87,6 +95,7 @@ function recordOverrides({ storyId, findings, ...deps }) {
87
95
  * criticalCount: number,
88
96
  * criticalByProvider?: Record<string, number>,
89
97
  * reason: string,
98
+ * noVerdictReason?: string|null,
90
99
  * findings?: Array<object>,
91
100
  * config?: object,
92
101
  * emitFrictionFn?: typeof emitRuntimeFriction,
@@ -101,11 +110,17 @@ export async function handleOverriddenReviewBlock({
101
110
  criticalCount,
102
111
  criticalByProvider = {},
103
112
  reason,
113
+ noVerdictReason = null,
104
114
  findings = [],
105
115
  config,
106
116
  emitFrictionFn = emitRuntimeFriction,
107
117
  }) {
108
- const body = buildReviewOverrideBody({ prUrl, criticalCount, reason });
118
+ const body = buildReviewOverrideBody({
119
+ prUrl,
120
+ criticalCount,
121
+ reason,
122
+ noVerdictReason,
123
+ });
109
124
  Logger.warn(
110
125
  `[single-story-close] ⚠️ Story-scope review reported ${criticalCount} critical blocker(s) on ` +
111
126
  `PR ${prUrl} — OVERRIDDEN by operator: ${reason}`,
@@ -1,9 +1,10 @@
1
1
  import { BASELINES_GATE_NAMES } from '../../close-validation/gates.js';
2
2
  import { Logger } from '../../Logger.js';
3
3
  import { recordCloseTelemetry } from '../../observability/close-telemetry.js';
4
- import { emitTerminalFriction } from '../../observability/runtime-friction.js';
4
+ import { finishCloseTerminal } from '../../observability/story-outcome.js';
5
5
  import { emitTerseResult } from '../../observability/terse-result.js';
6
6
  import { MERGED_FLIP_FAILED_BLOCK_CLASS } from '../lifecycle/emit-merge-flip-failed.js';
7
+ import { reviewGateValue } from '../review-providers/degraded-gates.js';
7
8
  import {
8
9
  buildTerminalEnvelope,
9
10
  emitTerminalEnvelope,
@@ -34,6 +35,7 @@ export async function emitTerminal({
34
35
  config,
35
36
  phaseTimer = UNTIMED,
36
37
  worker = NO_WORKER,
38
+ provider,
37
39
  }) {
38
40
  phaseTimer.stamp(terminal);
39
41
  await recordCloseTelemetry({ terminal, result, config, ...worker });
@@ -52,7 +54,7 @@ export async function emitTerminal({
52
54
  });
53
55
  }
54
56
  emitTerminalEnvelope(terminal, { config });
55
- await emitTerminalFriction({ envelope: terminal, config });
57
+ await finishCloseTerminal({ terminal, result, config, worker, provider });
56
58
  }
57
59
 
58
60
  /**
@@ -180,38 +182,51 @@ function deferredCaptureGate(validationGates) {
180
182
  }
181
183
 
182
184
  /**
183
- * `overridden` > `degraded` > `passed`: an override records the human
184
- * decision on a failed review; `degraded` says a review surface produced no
185
- * verdict (reported, not blocking — a secondary review does not gate merge).
185
+ * Derived from the review's degradation kinds, never the bare `degraded` flag;
186
+ * `skipped` when this run reviewed nothing (an already-merged PR).
186
187
  *
187
188
  * @param {object|null} reviewOverride
188
- * @param {boolean} [reviewDegraded]
189
- * @returns {'overridden'|'degraded'|'passed'}
189
+ * @param {ReadonlyArray<object>} [reviewDegradations]
190
+ * @param {boolean} [reviewSkipped]
191
+ * @returns {string}
190
192
  */
191
- function codeReviewGate(reviewOverride, reviewDegraded) {
192
- if (reviewOverride) return 'overridden';
193
- return reviewDegraded ? 'degraded' : 'passed';
193
+ function codeReviewGate(reviewOverride, reviewDegradations, reviewSkipped) {
194
+ if (isUnreviewed(reviewOverride, reviewSkipped)) return 'skipped';
195
+ return reviewGateValue(reviewDegradations, { overridden: !!reviewOverride });
194
196
  }
195
197
 
198
+ /**
199
+ * @param {object|null} reviewOverride
200
+ * @param {boolean} [reviewSkipped]
201
+ */
202
+ const isUnreviewed = (reviewOverride, reviewSkipped) =>
203
+ !reviewOverride && !!reviewSkipped;
204
+
196
205
  /**
197
206
  * @param {{ skipValidation?: boolean, skipSync?: boolean }} options
198
207
  * @param {Record<string, string>|null} validationGates
199
208
  * @param {object|null} reviewOverride
200
- * @param {boolean} [reviewDegraded]
209
+ * @param {ReadonlyArray<object>} [reviewDegradations]
210
+ * @param {{ reviewSkipped?: boolean }} [review]
201
211
  * @returns {Record<string, string>}
202
212
  */
203
213
  export function closeEnvelopeGates(
204
214
  options,
205
215
  validationGates,
206
216
  reviewOverride,
207
- reviewDegraded,
217
+ reviewDegradations,
218
+ { reviewSkipped = false } = {},
208
219
  ) {
209
220
  return {
210
221
  validation: options.skipValidation ? 'skipped' : 'passed',
211
222
  ...baselinesEnvelopeGates(validationGates),
212
223
  ...deferredCaptureGate(validationGates),
213
224
  baseSync: options.skipSync ? 'skipped' : 'passed',
214
- codeReview: codeReviewGate(reviewOverride, reviewDegraded),
225
+ codeReview: codeReviewGate(
226
+ reviewOverride,
227
+ reviewDegradations,
228
+ reviewSkipped,
229
+ ),
215
230
  };
216
231
  }
217
232
 
@@ -248,6 +263,7 @@ export function closeResult({
248
263
  waitedForMerge = false,
249
264
  merged = false,
250
265
  landCompleted = merged,
266
+ pushOutcome,
251
267
  }) {
252
268
  return {
253
269
  storyId,
@@ -257,6 +273,7 @@ export function closeResult({
257
273
  prUrl,
258
274
  prNumber,
259
275
  pushed: true,
276
+ pushOutcome,
260
277
  autoMergeEnabled,
261
278
  autoMergeReason,
262
279
  worktreeReaped,
@@ -1,19 +1,23 @@
1
1
  /**
2
2
  * The Story-scope review, overlapped with the close-validation gates: started
3
3
  * once the pre-gate self-heal commits land and held (computed, never posted)
4
- * until the PR exists. A worker deposit whose diff digest matches the diff at
5
- * that point **is** the held result, so nothing is computed. After PR-open a
6
- * pushed diff with a different digest discards it for a serial review — a
7
- * clean base-sync merge moves HEAD without changing the digest. The held
8
- * promise never rejects, so an abandoned review leaves no unhandled rejection.
4
+ * until the PR exists. A deposit whose diff digest matches the diff at that
5
+ * point **is** the held result, so nothing is computed. After PR-open a
6
+ * pushed diff with a different digest discards it for a serial review of the
7
+ * pushed SHA — a base-sync merge that moves only offsets keeps the digest.
8
+ * Every non-degraded review close computes is deposited when it settles, so a
9
+ * retry on the same diff adopts it. The held promise never rejects, so an
10
+ * abandoned review leaves no unhandled rejection.
9
11
  */
10
12
 
11
13
  import { postReviewComment } from '../code-review.js';
12
14
  import {
15
+ buildReviewDeposit,
13
16
  computeReviewDiffDigest,
14
17
  depositAsComputedReview,
15
18
  probeHeldReviewDiff,
16
19
  resolveRefSha,
20
+ writeReviewDeposit,
17
21
  } from '../review-deposit.js';
18
22
  import { upsertStructuredComment } from '../ticketing.js';
19
23
  import {
@@ -29,33 +33,76 @@ function resolveBranchSha({ cwd, storyBranch, gitSpawnFn }) {
29
33
  return resolveRefSha({ cwd, ref: storyBranch, gitSpawnFn });
30
34
  }
31
35
 
32
- /** A held result already in hand: the worker deposit. */
36
+ /** A held result already in hand: the deposit. */
33
37
  function adoptedSettlement(deposit, atMs) {
34
38
  const value = depositAsComputedReview(deposit);
35
39
  return Promise.resolve({ ok: true, value, endedAtMs: atMs });
36
40
  }
37
41
 
38
- /** Compute the review of `sha`, held unposted; never rejects. */
39
- function computeHeldReview({ sha, nowMs, ...args }) {
42
+ /** Deposit a computed result; a failed write is a warning, never a failure. */
43
+ function depositReview(args, held, result) {
44
+ if (!result || result.degraded || !held.diffDigest) return;
45
+ const { writeDepositFn = writeReviewDeposit, progress } = args;
46
+ try {
47
+ const deposit = buildReviewDeposit({
48
+ storyId: Number(args.storyId),
49
+ headSha: held.sha,
50
+ baseRef: held.baseRef,
51
+ diffDigest: held.diffDigest,
52
+ result,
53
+ });
54
+ writeDepositFn(deposit, { config: args.config });
55
+ } catch (err) {
56
+ progress(
57
+ 'REVIEW',
58
+ `⚠️ Could not deposit the Story-scope review: ${err?.message ?? err}`,
59
+ );
60
+ }
61
+ }
62
+
63
+ /** Compute the review of `held.sha`, held unposted; never rejects. */
64
+ function computeHeldReview(args, held) {
65
+ const { nowMs = Date.now } = args;
40
66
  return computeStoryScopeReview({
41
67
  ...args,
42
- headRef: sha,
68
+ headRef: held.sha,
43
69
  deferPost: true,
44
70
  }).then(
45
- (value) => ({ ok: true, value, endedAtMs: nowMs() }),
71
+ (value) => {
72
+ const endedAtMs = nowMs();
73
+ depositReview(args, held, value.result);
74
+ return { ok: true, value, endedAtMs };
75
+ },
46
76
  (error) => ({ ok: false, error, endedAtMs: nowMs() }),
47
77
  );
48
78
  }
49
79
 
80
+ /** Adopt the matching deposit for `sha`, else compute (and deposit) it. */
81
+ function holdReview(args, sha) {
82
+ const { progress, nowMs = Date.now } = args;
83
+ const { baseRef, diffDigest, deposit } = probeHeldReviewDiff({
84
+ ...args,
85
+ sha,
86
+ });
87
+ const startedAtMs = nowMs();
88
+ const held = { sha, baseRef, diffDigest, adopted: !!deposit, startedAtMs };
89
+ if (deposit) {
90
+ progress('REVIEW', `♻️ Adopting the deposited review; none computed.`);
91
+ return { ...held, settled: adoptedSettlement(deposit, startedAtMs) };
92
+ }
93
+ return { ...held, settled: computeHeldReview(args, held) };
94
+ }
95
+
50
96
  /**
51
97
  * @param {{ cwd: string, storyId: number, storyBranch: string,
52
98
  * baseBranch: string, provider: object, runCodeReviewFn: Function,
53
99
  * gitSpawnFn: Function, progress: Function, config?: object,
54
- * readDepositFn?: Function, nowMs?: () => number }} args
100
+ * readDepositFn?: Function, writeDepositFn?: Function,
101
+ * nowMs?: () => number }} args
55
102
  * @returns {HeldReview|null} null when the SHA is unresolvable.
56
103
  */
57
104
  export function startHeldReview(args) {
58
- const { cwd, storyBranch, gitSpawnFn, progress, nowMs = Date.now } = args;
105
+ const { cwd, storyBranch, gitSpawnFn, progress } = args;
59
106
  const sha = resolveBranchSha({ cwd, storyBranch, gitSpawnFn });
60
107
  if (!sha) {
61
108
  progress(
@@ -64,18 +111,7 @@ export function startHeldReview(args) {
64
111
  );
65
112
  return null;
66
113
  }
67
- const { baseRef, diffDigest, deposit } = probeHeldReviewDiff({
68
- ...args,
69
- sha,
70
- });
71
- const startedAtMs = nowMs();
72
- const held = { sha, baseRef, diffDigest, adopted: !!deposit, startedAtMs };
73
- if (deposit) {
74
- progress('REVIEW', `♻️ Adopting the worker's held review; none computed.`);
75
- return { ...held, settled: adoptedSettlement(deposit, startedAtMs) };
76
- }
77
- const settled = computeHeldReview({ ...args, sha, nowMs });
78
- return { ...held, settled };
114
+ return holdReview(args, sha);
79
115
  }
80
116
 
81
117
  /** Drop a held review unposted. */
@@ -115,19 +151,28 @@ async function postHeldReview(held, args) {
115
151
  }
116
152
  }
117
153
 
154
+ /** Review `sha` and post it; the branch name only when no SHA or PR. */
155
+ function reviewSerially(args, sha) {
156
+ if (args.prNumber == null || !sha) return runStoryScopeReview(args);
157
+ args.pauseTimer();
158
+ return postHeldReview(holdReview(args, sha), args);
159
+ }
160
+
118
161
  /**
119
- * Post a held review whose diff digest matches the pushed diff (phase
120
- * untimed: it records its own wall time), else run the serial review.
162
+ * Post a held review whose diff digest matches the pushed diff, else review
163
+ * the pushed SHA serially (deposited before it posts). Either phase is
164
+ * untimed: the review records its own wall time.
121
165
  *
122
166
  * @returns {Promise<object>} the review outcome.
123
167
  */
124
168
  export async function reviewAfterPrOpen(args) {
125
169
  const { held, setPhase, progress } = args;
170
+ const sha = resolveBranchSha(args);
126
171
  if (held && args.prNumber != null) {
127
172
  const pushedDigest = computeReviewDiffDigest({
128
173
  cwd: args.cwd,
129
174
  baseRef: held.baseRef,
130
- headRef: resolveBranchSha(args),
175
+ headRef: sha,
131
176
  gitSpawnFn: args.gitSpawnFn,
132
177
  });
133
178
  if (pushedDigest !== null && pushedDigest === held.diffDigest) {
@@ -146,16 +191,5 @@ export async function reviewAfterPrOpen(args) {
146
191
  );
147
192
  }
148
193
  setPhase('code-review');
149
- return await runStoryScopeReview({
150
- cwd: args.cwd,
151
- storyId: args.storyId,
152
- storyBranch: args.storyBranch,
153
- baseBranch: args.baseBranch,
154
- prUrl: args.prUrl,
155
- prNumber: args.prNumber,
156
- provider: args.provider,
157
- runCodeReviewFn: args.runCodeReviewFn,
158
- gitSpawnFn: args.gitSpawnFn,
159
- progress,
160
- });
194
+ return await reviewSerially(args, sha);
161
195
  }
@@ -363,13 +363,18 @@ function landedPrePush(ctx) {
363
363
  lockWait: null,
364
364
  suiteTimings: null,
365
365
  pending: false,
366
- coverageDeferred: false,
366
+ coverageDeferred: null,
367
367
  };
368
368
  return null;
369
369
  }
370
370
 
371
371
  function landedPr(ctx) {
372
- ctx.pr = { ...ctx.landedPr, alreadyMerged: true, reviewOverride: null };
372
+ ctx.pr = {
373
+ ...ctx.landedPr,
374
+ alreadyMerged: true,
375
+ reviewOverride: null,
376
+ reviewSkipped: true,
377
+ };
373
378
  return null;
374
379
  }
375
380
 
@@ -449,12 +454,15 @@ function buildPrContext(ctx, deps) {
449
454
  phaseTimer: ctx.phaseTimer,
450
455
  worker: ctx.worker,
451
456
  lockWait: ctx.prePush.lockWait,
457
+ baseSync: ctx.baseSync?.decision ?? null,
458
+ pushOutcome: ctx.pr.pushOutcome ?? null,
452
459
  suiteTimings: envelopeSuiteTimings(ctx, deps),
453
460
  gates: closeEnvelopeGates(
454
461
  options,
455
462
  ctx.prePush.validationGates,
456
463
  ctx.pr.reviewOverride,
457
- ctx.pr.reviewDegraded,
464
+ ctx.pr.reviewDegradations,
465
+ { reviewSkipped: ctx.pr.reviewSkipped === true },
458
466
  ),
459
467
  };
460
468
  }
@@ -7,8 +7,9 @@
7
7
  * Invariants:
8
8
  * 1. Only classifier `improvements` are written — a regression never enters
9
9
  * the written set, so it still fails the gate.
10
- * 2. Maintainability only: CRAP rows re-key on `method@startLine` when code
11
- * above moves, so write-back there is churn.
10
+ * 2. Maintainability only: CRAP is coverage-derived and flaps under
11
+ * non-deterministic V8 instrumentation, so writing its improvements
12
+ * back would ratchet the baseline on noise.
12
13
  * 3. Changed files only — a full-scope write would absorb other branches'
13
14
  * drift into whichever PR lands next.
14
15
  * 4. Idempotent: no empty commit.