mandrel 2.111.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 (178) 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 +351 -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/preview-gates.js +29 -10
  38. package/.agents/scripts/lib/baselines/reader.js +36 -9
  39. package/.agents/scripts/lib/baselines/refresh-service.js +79 -18
  40. package/.agents/scripts/lib/baselines/seat-missing.js +173 -7
  41. package/.agents/scripts/lib/baselines/writer.js +36 -21
  42. package/.agents/scripts/lib/changed-files.js +70 -6
  43. package/.agents/scripts/lib/child-exec.js +10 -0
  44. package/.agents/scripts/lib/claude/agents-projection.js +5 -5
  45. package/.agents/scripts/lib/close-lock-events.js +8 -3
  46. package/.agents/scripts/lib/close-validation/ci-deferral.js +40 -0
  47. package/.agents/scripts/lib/close-validation/gates.js +111 -35
  48. package/.agents/scripts/lib/close-validation/process.js +16 -7
  49. package/.agents/scripts/lib/close-validation/projections/crap.js +43 -10
  50. package/.agents/scripts/lib/close-validation/runner.js +55 -23
  51. package/.agents/scripts/lib/close-validation/skip-branch-test.js +144 -0
  52. package/.agents/scripts/lib/close-validation/test-delta.js +33 -8
  53. package/.agents/scripts/lib/codex/agents-projection.js +6 -0
  54. package/.agents/scripts/lib/config/agentrc-overlay.js +9 -5
  55. package/.agents/scripts/lib/config/explain.js +5 -2
  56. package/.agents/scripts/lib/config/gates/coverage.schema.js +45 -1
  57. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  58. package/.agents/scripts/lib/config/git-roots.js +38 -4
  59. package/.agents/scripts/lib/config/handoff.js +24 -0
  60. package/.agents/scripts/lib/config/quality.js +26 -13
  61. package/.agents/scripts/lib/config/worktree-isolation.js +2 -5
  62. package/.agents/scripts/lib/config-resolver.js +22 -2
  63. package/.agents/scripts/lib/config-settings-schema-delivery.js +87 -4
  64. package/.agents/scripts/lib/config-settings-schema-quality.js +36 -1
  65. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  66. package/.agents/scripts/lib/coverage-capture-affected.js +1 -0
  67. package/.agents/scripts/lib/coverage-capture-delta.js +164 -32
  68. package/.agents/scripts/lib/coverage-capture-own-fix.js +232 -0
  69. package/.agents/scripts/lib/coverage-capture-usage.js +2 -2
  70. package/.agents/scripts/lib/coverage-capture.js +15 -0
  71. package/.agents/scripts/lib/coverage-deferral.js +96 -0
  72. package/.agents/scripts/lib/coverage-ratchet.js +187 -0
  73. package/.agents/scripts/lib/crap-baseline-join.js +5 -5
  74. package/.agents/scripts/lib/crap-engine.js +3 -3
  75. package/.agents/scripts/lib/crap-method-identity.js +104 -48
  76. package/.agents/scripts/lib/escomplex-anchor.js +135 -0
  77. package/.agents/scripts/lib/escomplex-kernel.js +30 -1
  78. package/.agents/scripts/lib/failure-rows.js +121 -0
  79. package/.agents/scripts/lib/full-suite-lock.js +44 -4
  80. package/.agents/scripts/lib/full-suite-queue.js +89 -13
  81. package/.agents/scripts/lib/generated/agentrc-validator.js +8 -2
  82. package/.agents/scripts/lib/gh-env.js +3 -6
  83. package/.agents/scripts/lib/gh-pr-rest.js +1 -0
  84. package/.agents/scripts/lib/git/base-sync-probe.js +182 -0
  85. package/.agents/scripts/lib/git-branch-lifecycle.js +9 -0
  86. package/.agents/scripts/lib/observability/close-telemetry.js +37 -2
  87. package/.agents/scripts/lib/observability/handoff-telemetry.js +170 -0
  88. package/.agents/scripts/lib/observability/review-dispositions.js +23 -6
  89. package/.agents/scripts/lib/observability/runtime-friction.js +17 -4
  90. package/.agents/scripts/lib/observability/source-classifier.js +3 -0
  91. package/.agents/scripts/lib/observability/story-outcome.js +393 -0
  92. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +2 -1
  93. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +19 -1
  94. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +84 -0
  95. package/.agents/scripts/lib/orchestration/check-baselines/phases/pipeline.js +14 -5
  96. package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js +3 -2
  97. package/.agents/scripts/lib/orchestration/check-baselines/phases/report.js +26 -6
  98. package/.agents/scripts/lib/orchestration/code-review.js +223 -19
  99. package/.agents/scripts/lib/orchestration/handoff-gates.js +129 -62
  100. package/.agents/scripts/lib/orchestration/handoff-rescore.js +169 -0
  101. package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +45 -0
  102. package/.agents/scripts/lib/orchestration/preflight-lanes.js +208 -0
  103. package/.agents/scripts/lib/orchestration/review-base-ref.js +40 -17
  104. package/.agents/scripts/lib/orchestration/review-deposit.js +38 -12
  105. package/.agents/scripts/lib/orchestration/review-depth.js +21 -0
  106. package/.agents/scripts/lib/orchestration/review-history.js +124 -20
  107. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +23 -8
  108. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +82 -39
  109. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +64 -11
  110. package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js +98 -3
  111. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +6 -2
  112. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +55 -8
  113. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +1 -0
  114. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +42 -15
  115. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  116. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +10 -1
  117. package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js +10 -0
  118. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +7 -4
  119. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +15 -3
  120. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +59 -2
  121. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +6 -0
  122. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +15 -4
  123. package/.agents/scripts/lib/orchestration/single-story-close/phases/land-review-record.js +213 -0
  124. package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +9 -12
  125. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +26 -12
  126. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +51 -26
  127. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +3 -2
  128. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +50 -17
  129. package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js +59 -11
  130. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +1 -0
  131. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-block.js +31 -13
  132. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +29 -6
  133. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-outcome.js +10 -12
  134. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +19 -4
  135. package/.agents/scripts/lib/orchestration/single-story-close/result.js +30 -13
  136. package/.agents/scripts/lib/orchestration/single-story-close/review-overlap.js +73 -39
  137. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +11 -3
  138. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +3 -2
  139. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +20 -8
  140. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +7 -0
  141. package/.agents/scripts/lib/orchestration/story-handoff.js +774 -196
  142. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  143. package/.agents/scripts/lib/pr-body-lines.js +32 -0
  144. package/.agents/scripts/lib/single-story/ci-ratchet-gate.js +140 -0
  145. package/.agents/scripts/lib/single-story/confirm-and-land.js +17 -7
  146. package/.agents/scripts/lib/single-story/confirm-merge.js +12 -3
  147. package/.agents/scripts/lib/single-story-sweep/report-stalled-executing.js +202 -0
  148. package/.agents/scripts/lib/standalone-ratchets.js +37 -0
  149. package/.agents/scripts/lib/suite-admission.js +20 -8
  150. package/.agents/scripts/lib/suite-sizing.js +146 -0
  151. package/.agents/scripts/lib/workspace-provisioner.js +2 -2
  152. package/.agents/scripts/merge-baseline.js +14 -3
  153. package/.agents/scripts/providers/github/comments.js +19 -3
  154. package/.agents/scripts/providers/github.js +1 -0
  155. package/.agents/scripts/review-dispositions-report.js +1 -1
  156. package/.agents/scripts/role-scope-guard.js +267 -0
  157. package/.agents/scripts/single-story-close.js +4 -4
  158. package/.agents/scripts/single-story-confirm-merge.js +31 -5
  159. package/.agents/scripts/single-story-init.js +24 -4
  160. package/.agents/scripts/story-handoff.js +3 -3
  161. package/.agents/scripts/story-outcomes-report.js +231 -0
  162. package/.agents/scripts/story-review-compute.js +9 -5
  163. package/.agents/scripts/update-coverage-baseline.js +12 -2
  164. package/.agents/scripts/update-crap-baseline.js +9 -1
  165. package/.agents/workflows/helpers/code-review.md +63 -9
  166. package/.agents/workflows/helpers/deliver-digest.md +53 -54
  167. package/.agents/workflows/helpers/deliver-reference.md +233 -67
  168. package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
  169. package/.agents/workflows/helpers/deliver-story.md +7 -2
  170. package/.agents/workflows/helpers/parallel-tooling.md +29 -0
  171. package/docs/CHANGELOG.md +46 -0
  172. package/lib/cli/doctor-checks/coverage-ratchet.js +54 -0
  173. package/lib/cli/doctor-checks/effective-agentrc.js +23 -0
  174. package/lib/cli/doctor-checks/llm-review.js +2 -11
  175. package/lib/cli/doctor-checks/sync-parity.js +5 -1
  176. package/lib/cli/doctor-checks/test-credit-path.js +7 -2
  177. package/lib/cli/registry.js +5 -0
  178. package/package.json +1 -1
@@ -57,7 +57,8 @@ export async function runPrePushPhases(ctx, deps) {
57
57
  progress,
58
58
  gitSpawn: deps.gitSpawn,
59
59
  });
60
- const baseSync = await runSyncStep(ctx, deps);
60
+ // biome-ignore lint/suspicious/noAssignInExpressions: the runner's envelope reads ctx.baseSync
61
+ const baseSync = (ctx.baseSync = await runSyncStep(ctx, deps));
61
62
  if (options.skipValidation) {
62
63
  progress('VALIDATE', '⏭ Skipped (--skip-validation).');
63
64
  return {
@@ -110,6 +111,6 @@ export async function runPrePushPhases(ctx, deps) {
110
111
  lockWait: validation?.lockWait ?? null,
111
112
  suiteTimings: validation?.suiteTimings ?? null,
112
113
  pending: validation?.pending === true,
113
- coverageDeferred: validation?.coverageDeferred === true,
114
+ coverageDeferred: validation?.coverageDeferred ?? null,
114
115
  };
115
116
  }
@@ -7,6 +7,10 @@
7
7
  * positively empty diff; an unenumerable diff fails open.
8
8
  */
9
9
 
10
+ import {
11
+ readDeferralMarker,
12
+ rewriteDeferralLines,
13
+ } from '../../../coverage-deferral.js';
10
14
  import { gh as defaultGh } from '../../../gh-exec.js';
11
15
  import { Logger } from '../../../Logger.js';
12
16
  import { computeChangeSet as defaultComputeChangeSet } from '../../change-set.js';
@@ -66,6 +70,26 @@ function emptyDiffError({ storyBranch, baseRef, storyId }) {
66
70
  );
67
71
  }
68
72
 
73
+ /**
74
+ * A reused PR must carry this run's deferral marker, or confirm-merge skips
75
+ * the CI ratchet. A null reason may mean "not measured", so no strip.
76
+ */
77
+ async function syncDeferralMarker({ gh, url, body, coverageDeferred }) {
78
+ if (!coverageDeferred || readDeferralMarker(body) === coverageDeferred) {
79
+ return;
80
+ }
81
+ try {
82
+ await gh.pr.edit(url, [
83
+ '--body',
84
+ rewriteDeferralLines(body, coverageDeferred),
85
+ ]);
86
+ } catch (err) {
87
+ throw new Error(
88
+ `[single-story-close] could not write \`Coverage-deferred: ${coverageDeferred}\` onto ${url}: ${err?.message ?? err}`,
89
+ );
90
+ }
91
+ }
92
+
69
93
  /**
70
94
  * @param {{
71
95
  * cwd: string,
@@ -78,7 +102,7 @@ function emptyDiffError({ storyBranch, baseRef, storyId }) {
78
102
  * gh?: ReturnType<typeof import('../../../gh-exec.js').createGh>,
79
103
  * computeChangeSetFn?: typeof defaultComputeChangeSet,
80
104
  * progress?: (tag: string, msg: string) => void,
81
- * coverageDeferred?: boolean,
105
+ * coverageDeferred?: 'over-budget'|'suite-of-record-ci'|null,
82
106
  * }} args
83
107
  * @returns {Promise<{ url: string, alreadyMerged: boolean, created: boolean }>}
84
108
  */
@@ -93,33 +117,42 @@ export async function ensurePullRequestWith({
93
117
  gh = defaultGh,
94
118
  computeChangeSetFn = defaultComputeChangeSet,
95
119
  progress = () => {},
96
- coverageDeferred = false,
120
+ coverageDeferred = null,
97
121
  }) {
98
122
  // `gh-exec` spawns `gh` in the process cwd, not `_cwd`.
123
+ let rows = [];
124
+ let existing = null;
99
125
  try {
100
126
  // `--state all`, not `open`: a merged PR must be seen.
101
- const rows = await gh.pr.list(
127
+ rows = await gh.pr.list(
102
128
  ['--head', storyBranch, '--state', 'all'],
103
- ['url', 'state', 'mergedAt'],
129
+ ['url', 'state', 'mergedAt', 'body'],
104
130
  );
105
- const existing = pickHeadPullRequest(rows);
106
- if (existing?.state === 'OPEN') {
107
- progress('PR', `Reusing existing PR: ${existing.url}`);
108
- return { url: existing.url, alreadyMerged: false, created: false };
109
- }
110
- if (existing?.state === 'MERGED') {
111
- progress(
112
- 'PR',
113
- `✅ PR for ${storyBranch} is already MERGED: ${existing.url} — ` +
114
- 'reporting that outcome instead of opening a second PR.',
115
- );
116
- return { url: existing.url, alreadyMerged: true, created: false };
117
- }
131
+ existing = pickHeadPullRequest(rows);
118
132
  } catch (err) {
119
133
  Logger.warn?.(
120
134
  `[single-story-close] ⚠️ \`gh pr list\` probe failed (continuing to create): ${err?.message ?? err}`,
121
135
  );
122
136
  }
137
+ if (existing?.state === 'OPEN') {
138
+ progress('PR', `Reusing existing PR: ${existing.url}`);
139
+ const row = rows.find((r) => String(r?.url ?? '').trim() === existing.url);
140
+ await syncDeferralMarker({
141
+ gh,
142
+ url: existing.url,
143
+ body: row?.body,
144
+ coverageDeferred,
145
+ });
146
+ return { url: existing.url, alreadyMerged: false, created: false };
147
+ }
148
+ if (existing?.state === 'MERGED') {
149
+ progress(
150
+ 'PR',
151
+ `✅ PR for ${storyBranch} is already MERGED: ${existing.url} — ` +
152
+ 'reporting that outcome instead of opening a second PR.',
153
+ );
154
+ return { url: existing.url, alreadyMerged: true, created: false };
155
+ }
123
156
 
124
157
  const emptyDiff = probeEmptyDiff({
125
158
  cwd: _cwd ?? process.cwd(),
@@ -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,