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
@@ -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`,
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * review-providers/review-provider-factory.js — resolves
3
3
  * `codeReview.providers` into a `ChainProvider`. A failing entry throws
4
- * unless it is `optional`.
4
+ * unless it is `optional`; a skipped one records a `verdict-missing`.
5
5
  *
6
6
  * @typedef {import('./types.js').ReviewProvider} ReviewProvider
7
7
  * @typedef {import('./types.js').ManualPromptProvider} ManualPromptProvider
@@ -134,6 +134,8 @@ export function buildProviderChain(entries, ctx) {
134
134
  const inline = [];
135
135
  /** @type {PromptChainEntry[]} */
136
136
  const prompts = [];
137
+ /** Optional entries skipped at construction, with their gates. */
138
+ const skipped = [];
137
139
 
138
140
  for (const raw of entries) {
139
141
  if (!raw || typeof raw !== 'object' || typeof raw.name !== 'string') {
@@ -161,6 +163,7 @@ export function buildProviderChain(entries, ctx) {
161
163
  manualPrompt ? 'manual-prompt' : 'inline'
162
164
  } provider "${name}" in chain; skipping (optional=true).`,
163
165
  );
166
+ skipped.push({ name, gate, manualPrompt, why: 'not registered' });
164
167
  continue;
165
168
  }
166
169
  const supported = Object.keys(registry).sort().join(', ');
@@ -182,6 +185,12 @@ export function buildProviderChain(entries, ctx) {
182
185
  err?.message ?? err
183
186
  }`,
184
187
  );
188
+ skipped.push({
189
+ name,
190
+ gate,
191
+ manualPrompt,
192
+ why: 'unavailable on this host',
193
+ });
185
194
  continue;
186
195
  }
187
196
  throw err;
@@ -194,9 +203,32 @@ export function buildProviderChain(entries, ctx) {
194
203
  }
195
204
  }
196
205
 
197
- return { inline, prompts };
206
+ return { inline, prompts, skipped };
198
207
  }
199
208
 
209
+ /**
210
+ * @param {ReadonlyArray<{ name: string, gate: ProviderGate, manualPrompt: boolean, why: string }>} skipped
211
+ * @param {ProviderGateContext} ctx
212
+ * @returns {Array<object>}
213
+ */
214
+ function skippedDegradations(skipped, ctx) {
215
+ return skipped
216
+ .filter((entry) => !entry.manualPrompt && entry.gate(ctx))
217
+ .map(({ name, why }) => ({
218
+ tool: 'review-provider-factory',
219
+ gate: 'codeReview',
220
+ surface: name,
221
+ kind: 'verdict-missing',
222
+ reason: `optional provider "${name}" skipped: ${why}`,
223
+ }));
224
+ }
225
+
226
+ /** @param {ReviewInput} input @returns {ProviderGateContext} */
227
+ const gateContextOf = (input) => ({
228
+ scope: input?.scope,
229
+ labels: /** @type {any} */ (input)?.labels ?? [],
230
+ });
231
+
200
232
  /**
201
233
  * @param {Finding[]} findings
202
234
  * @param {string} name
@@ -220,6 +252,7 @@ function stampProvider(findings, name) {
220
252
  */
221
253
  export function createChainProvider(chain, opts = {}) {
222
254
  const logger = opts.logger;
255
+ let skippedRows = [];
223
256
 
224
257
  return {
225
258
  chain,
@@ -230,12 +263,8 @@ export function createChainProvider(chain, opts = {}) {
230
263
  async runReview(input) {
231
264
  /** @type {Finding[]} */
232
265
  const merged = [];
233
- const ctx = {
234
- scope: input?.scope,
235
- labels: /** @type {ReadonlyArray<string>} */ (
236
- /** @type {any} */ (input)?.labels ?? []
237
- ),
238
- };
266
+ const ctx = gateContextOf(input);
267
+ skippedRows = skippedDegradations(chain.skipped ?? [], ctx);
239
268
  for (const entry of chain.inline) {
240
269
  if (!entry.gate(ctx)) {
241
270
  logger?.info?.(
@@ -259,7 +288,10 @@ export function createChainProvider(chain, opts = {}) {
259
288
  * @returns {Promise<Array<object>>}
260
289
  */
261
290
  async getDegradations() {
262
- return mergeChainDegradations(chain.inline, logger);
291
+ return [
292
+ ...skippedRows,
293
+ ...(await mergeChainDegradations(chain.inline, logger)),
294
+ ];
263
295
  },
264
296
  /**
265
297
  * @param {ReviewInput} input
@@ -267,12 +299,7 @@ export function createChainProvider(chain, opts = {}) {
267
299
  */
268
300
  async getPromptMessages(input) {
269
301
  const messages = [];
270
- const ctx = {
271
- scope: input?.scope,
272
- labels: /** @type {ReadonlyArray<string>} */ (
273
- /** @type {any} */ (input)?.labels ?? []
274
- ),
275
- };
302
+ const ctx = gateContextOf(input);
276
303
  for (const entry of chain.prompts) {
277
304
  if (!entry.gate(ctx)) {
278
305
  logger?.info?.(
@@ -19,6 +19,8 @@
19
19
  * @property {string=} class - Kebab-case bug class.
20
20
  * @property {{ file: string, line?: number }[]=} instances - Every location; the first is `file`/`line`.
21
21
  * @property {boolean=} repeat - An earlier run of this Story raised it.
22
+ * @property {string=} carried - An earlier CRITICAL kept blocking; the re-check's reason.
23
+ * @property {string=} carriedId - A carried finding's recorded id.
22
24
  *
23
25
  * @typedef {object} FindingClaim
24
26
  * @property {'path-absent'|'symbol-referenced'|'file-unchanged'} kind
@@ -36,6 +38,8 @@
36
38
  * @property {string} headRef
37
39
  * @property {ReviewDepth=} depth - Diff-derived thoroughness lever; LLM-backed
38
40
  * providers MUST render it into their prompt. Absent → `standard`.
41
+ * @property {string=} effort - `claude --effort` level resolved from `depth`;
42
+ * absent → `low`.
39
43
  * @property {(string|null)=} guidance - Project review guidance; LLM-backed
40
44
  * providers render it via `renderGuidanceBlock`.
41
45
  *
@@ -70,6 +74,8 @@
70
74
  * @typedef {object} ProviderChain
71
75
  * @property {InlineChainEntry[]} inline
72
76
  * @property {PromptChainEntry[]} prompts
77
+ * @property {Array<{ name: string, gate: ProviderGate, manualPrompt: boolean, why: string }>} [skipped]
78
+ * Optional entries skipped at construction.
73
79
  */
74
80
 
75
81
  export {};
@@ -92,6 +92,15 @@ function nextCommandFor(err, storyId) {
92
92
  return typeof tagged === 'string' ? tagged : NEXT_COMMANDS.recover(storyId);
93
93
  }
94
94
 
95
+ /** `baselinesKinds` only when close-validation tagged the failing kinds. */
96
+ function failureFor(err) {
97
+ const kinds = err?.closeBaselinesKinds;
98
+ return {
99
+ reason: String(err?.message ?? err),
100
+ ...(kinds?.length ? { baselinesKinds: kinds } : {}),
101
+ };
102
+ }
103
+
95
104
  /**
96
105
  * Never throws: a build failure here must not replace the original error as
97
106
  * the run's reported cause, so it returns null and the caller rethrows.
@@ -116,7 +125,7 @@ export function failedTerminalFor(err, args = {}) {
116
125
  ...args,
117
126
  observedGates: err?.closeGates ?? null,
118
127
  }),
119
- failure: { reason: String(err?.message ?? err) },
128
+ failure: failureFor(err),
120
129
  nextCommand: nextCommandFor(err, storyId),
121
130
  elapsedSeconds: 0,
122
131
  phaseDurations: err?.closePhaseDurations ?? undefined,
@@ -12,6 +12,7 @@ import path from 'node:path';
12
12
 
13
13
  import { orchestrationLogDir } from '../../config/temp-paths.js';
14
14
  import { Logger, resolveLevel } from '../../Logger.js';
15
+ import { parseGateFailLine } from '../check-baselines/phases/report.js';
15
16
 
16
17
  /** Trailing lines replayed on failure; a failed gate's evidence sits at the end. */
17
18
  export const REPLAY_TAIL_LINES = 200;
@@ -39,6 +40,7 @@ class GateLogSink {
39
40
  this._flush = flush ?? (() => Promise.resolve());
40
41
  this._emit = emit;
41
42
  this._tail = [];
43
+ this._failedKinds = new Set();
42
44
  }
43
45
 
44
46
  /**
@@ -52,6 +54,9 @@ class GateLogSink {
52
54
  this.lineCount += 1;
53
55
  this._tail.push(line);
54
56
  if (this._tail.length > REPLAY_TAIL_LINES) this._tail.shift();
57
+ // Every line, not the tail: parallel lint output can push these out.
58
+ const kind = parseGateFailLine(line);
59
+ if (kind) this._failedKinds.add(kind);
55
60
  this._write(line);
56
61
  if (this.streamInline) this._emit(line);
57
62
  };
@@ -66,6 +71,11 @@ class GateLogSink {
66
71
  return this._flush();
67
72
  }
68
73
 
74
+ /** @returns {string[]} the check-baselines kinds any line reported FAIL. */
75
+ baselinesKinds() {
76
+ return [...this._failedKinds];
77
+ }
78
+
69
79
  /**
70
80
  * @returns {string}
71
81
  */
@@ -10,7 +10,7 @@
10
10
  import { getQuality } from '../../../config/quality.js';
11
11
  import { resolveConfig } from '../../../config-resolver.js';
12
12
  import { filterSuiteInputPaths } from '../../../coverage-capture.js';
13
- import { syncBranchFromBase } from '../../../git/sync-from-base.js';
13
+ import { syncFromBaseByMode } from '../../../git/base-sync-probe.js';
14
14
  import { Logger } from '../../../Logger.js';
15
15
  import { AGENT_LABELS } from '../../../label-constants.js';
16
16
  import { NEXT_COMMANDS } from '../../story-deliver-terminal.js';
@@ -31,11 +31,12 @@ import {
31
31
  * storyBranch: string,
32
32
  * storyId: number,
33
33
  * provider: object,
34
- * injectedSync?: typeof syncBranchFromBase,
34
+ * injectedSync?: typeof syncFromBaseByMode,
35
35
  * resolveConfigImpl?: typeof resolveConfig,
36
36
  * progress: (tag: string, msg: string) => void,
37
37
  * }} args
38
- * @returns {Promise<{ changedPaths: string[], creditedCommit: string|null }>} The pre-sync head is the credited commit.
38
+ * @returns {Promise<{ changedPaths: string[], creditedCommit: string|null, baselineRef?: string, decision: object|null }>}
39
+ * The pre-sync head is the credited commit; a skipped sync pins `baselineRef`.
39
40
  */
40
41
  export async function runBaseSyncPhase({
41
42
  cwd,
@@ -54,7 +55,7 @@ export async function runBaseSyncPhase({
54
55
  'SYNC',
55
56
  `Syncing ${storyBranch} from origin/${baseBranch} in ${syncCwd}...`,
56
57
  );
57
- const syncFn = injectedSync ?? syncBranchFromBase;
58
+ const syncFn = injectedSync ?? syncFromBaseByMode;
58
59
  const syncResult = await syncFn({
59
60
  cwd: syncCwd,
60
61
  baseBranch,
@@ -95,6 +96,8 @@ export async function runBaseSyncPhase({
95
96
  ? syncResult.changedPaths
96
97
  : [],
97
98
  creditedCommit: syncResult.preSyncHead ?? null,
99
+ baselineRef: syncResult.baselineRef,
100
+ decision: syncResult.decision ?? null,
98
101
  };
99
102
  }
100
103
 
@@ -14,7 +14,10 @@ import {
14
14
  sourcedTimings,
15
15
  summarizeLockEvents,
16
16
  } from '../../../close-lock-events.js';
17
- import { buildDefaultGates as defaultBuildDefaultGates } from '../../../close-validation/gates.js';
17
+ import {
18
+ BASELINES_GATE_NAMES,
19
+ buildDefaultGates as defaultBuildDefaultGates,
20
+ } from '../../../close-validation/gates.js';
18
21
  import { runCloseValidation as defaultRunCloseValidation } from '../../../close-validation/runner.js';
19
22
  import { applyTestDelta as defaultApplyTestDelta } from '../../../close-validation/test-delta.js';
20
23
  import { LOCK_WAIT_EXPIRED_EXIT_CODE } from '../../../full-suite-lock.js';
@@ -33,7 +36,7 @@ import { runPreGateSteps as defaultRunPreGateSteps } from './pre-gate-steps.js';
33
36
  * baseBranch: string,
34
37
  * storyBranch?: string,
35
38
  * storyId: number,
36
- * baseSync?: { changedPaths: string[], creditedCommit: string|null }|null,
39
+ * baseSync?: { changedPaths: string[], creditedCommit: string|null, baselineRef?: string }|null,
37
40
  * progress: (tag: string, msg: string) => void,
38
41
  * runCloseValidation?: typeof defaultRunCloseValidation,
39
42
  * buildDefaultGates?: typeof defaultBuildDefaultGates,
@@ -83,6 +86,7 @@ export async function runCloseValidationPhase({
83
86
  storyId,
84
87
  baseBranch,
85
88
  storyBranch,
89
+ baselineRef: baseSync?.baselineRef,
86
90
  config,
87
91
  progress,
88
92
  runScopedFormatAutofix,
@@ -100,6 +104,7 @@ export async function runCloseValidationPhase({
100
104
  log: gateLog.log,
101
105
  storyId,
102
106
  evidenceCwd: cwd,
107
+ baselineRef: baseSync?.baselineRef,
103
108
  };
104
109
  const gateList = applyTestDelta(buildDefaultGates(gateOpts), {
105
110
  ...gateOpts,
@@ -134,7 +139,7 @@ export async function runCloseValidationPhase({
134
139
  lockWait,
135
140
  suiteTimings: sourcedTimings(timings, 'close'),
136
141
  pending: false,
137
- coverageDeferred: (validation.deferred ?? []).length > 0,
142
+ coverageDeferred: validation.deferred?.[0]?.reason ?? null,
138
143
  };
139
144
  }
140
145
 
@@ -191,6 +196,13 @@ async function runGateChain({
191
196
  * }} args
192
197
  * @returns {{ gates: null, lockWait: object, suiteTimings: null, pending: true }}
193
198
  */
199
+ /** A failed check-baselines entry names the kinds its output reported FAIL. */
200
+ function tagBaselinesKinds(err, gateName, gateLog) {
201
+ if (!Object.values(BASELINES_GATE_NAMES).includes(gateName)) return;
202
+ const kinds = gateLog.baselinesKinds();
203
+ if (kinds.length > 0) err.closeBaselinesKinds = kinds;
204
+ }
205
+
194
206
  function settleFailedValidation({ validation, lockWait, gateLog, progress }) {
195
207
  const [first] = validation.failed;
196
208
  const { gate, status, cwd: gateCwd } = first;
@@ -207,6 +219,7 @@ function settleFailedValidation({ validation, lockWait, gateLog, progress }) {
207
219
  (gate.hint ? ` ${gate.hint}` : ''),
208
220
  );
209
221
  err.closeGate = gate.name;
222
+ tagBaselinesKinds(err, gate.name, gateLog);
210
223
  throw err;
211
224
  }
212
225
 
@@ -13,7 +13,10 @@ import {
13
13
  resolveSharedBaseRef,
14
14
  unresolvedBaseReviewOutcome,
15
15
  } from '../../review-base-ref.js';
16
- import { degradationEnvelope } from '../../review-providers/degraded-gates.js';
16
+ import {
17
+ degradationEnvelope,
18
+ resolveNoVerdictHalt,
19
+ } from '../../review-providers/degraded-gates.js';
17
20
  import { runStoryReviewCore } from '../../story-close/phases/review-core.js';
18
21
  import { postStructuredComment } from '../../ticketing/state.js';
19
22
  import {
@@ -91,6 +94,45 @@ async function postStoryReviewCrossRef({
91
94
  return false;
92
95
  }
93
96
 
97
+ /** @param {object} [config] */
98
+ const onNoVerdictOf = (config) => config?.delivery?.codeReview?.onNoVerdict;
99
+
100
+ /** @param {unknown} prUrl */
101
+ const prNumberDegradation = (prUrl) => ({
102
+ tool: 'story-scope-review',
103
+ gate: 'pr-number',
104
+ surface: String(prUrl ?? 'pull-request'),
105
+ kind: 'verdict-missing',
106
+ reason: 'pr-number-unparseable',
107
+ });
108
+
109
+ /** @param {object|null} halt */
110
+ const haltFieldsOf = (halt) => ({
111
+ halted: halt !== null,
112
+ haltCause: halt?.haltCause ?? null,
113
+ blockerReason: halt?.blockerReason ?? null,
114
+ });
115
+
116
+ const ZERO_SEVERITY = Object.freeze({
117
+ critical: 0,
118
+ high: 0,
119
+ medium: 0,
120
+ suggestion: 0,
121
+ });
122
+
123
+ /** No PR number means no review ran: a verdict-missing record, not a pass. */
124
+ function unparseablePrOutcome({ prUrl, storyId, config }) {
125
+ const degradations = [prNumberDegradation(prUrl)];
126
+ const onNoVerdict = onNoVerdictOf(config);
127
+ const halt = resolveNoVerdictHalt({ degradations, onNoVerdict, storyId });
128
+ return {
129
+ ...haltFieldsOf(halt),
130
+ skipped: true,
131
+ severity: { ...ZERO_SEVERITY },
132
+ ...degradationEnvelope(degradations),
133
+ };
134
+ }
135
+
94
136
  /**
95
137
  * Run the review against `headRef`; `deferPost` holds the report unposted.
96
138
  *
@@ -108,6 +150,7 @@ export async function computeStoryScopeReview({
108
150
  runCodeReviewFn,
109
151
  gitSpawnFn,
110
152
  progress,
153
+ config,
111
154
  }) {
112
155
  const base = resolveSharedBaseRef({ baseBranch, cwd, gitSpawnFn });
113
156
  if (!base.resolved) {
@@ -117,6 +160,7 @@ export async function computeStoryScopeReview({
117
160
  baseBranch,
118
161
  remoteRef: base.remoteRef,
119
162
  progress,
163
+ onNoVerdict: onNoVerdictOf(config),
120
164
  }),
121
165
  };
122
166
  }
@@ -144,6 +188,14 @@ export async function computeStoryScopeReview({
144
188
  return { result };
145
189
  }
146
190
 
191
+ /** A result computed before `haltCause` existed halted on a critical. */
192
+ function haltCauseOf({ halted, haltCause, blockerReason }) {
193
+ return {
194
+ haltCause: haltCause ?? (halted ? 'critical' : null),
195
+ blockerReason: blockerReason ?? null,
196
+ };
197
+ }
198
+
147
199
  /**
148
200
  * Settle a computed review on the PR: post a held report via `postReportFn`,
149
201
  * report the tally, cross-reference the Story.
@@ -198,6 +250,7 @@ export async function settleStoryScopeReview({
198
250
 
199
251
  return {
200
252
  halted: !!result.halted,
253
+ ...haltCauseOf(result),
201
254
  severity: sev,
202
255
  criticalByProvider: result.criticalByProvider,
203
256
  // The override records these ids so a re-review does not halt on them.
@@ -224,9 +277,11 @@ export async function settleStoryScopeReview({
224
277
  * runCodeReviewFn: Function,
225
278
  * gitSpawnFn?: Function,
226
279
  * progress: (tag: string, msg: string) => void,
280
+ * config?: object,
227
281
  * }} args
228
282
  * @returns {Promise<{
229
283
  * halted: boolean,
284
+ * haltCause?: 'critical'|'no-verdict'|null,
230
285
  * skipped?: boolean,
231
286
  * severity?: { critical: number, high: number, medium: number, suggestion: number },
232
287
  * criticalByProvider?: Record<string, number>,
@@ -249,13 +304,14 @@ export async function runStoryScopeReview({
249
304
  runCodeReviewFn,
250
305
  gitSpawnFn,
251
306
  progress,
307
+ config,
252
308
  }) {
253
309
  if (prNumber == null) {
254
310
  progress(
255
311
  'REVIEW',
256
312
  `⏭ Story-scope review skipped: could not parse PR number from URL ${prUrl}.`,
257
313
  );
258
- return { halted: false, skipped: true };
314
+ return unparseablePrOutcome({ prUrl, storyId, config });
259
315
  }
260
316
  const computed = await computeStoryScopeReview({
261
317
  cwd,
@@ -267,6 +323,7 @@ export async function runStoryScopeReview({
267
323
  runCodeReviewFn,
268
324
  gitSpawnFn,
269
325
  progress,
326
+ config,
270
327
  });
271
328
  return settleStoryScopeReview({
272
329
  computed,
@@ -24,6 +24,7 @@
24
24
  import { getCiDelivery } from '../../../config/ci.js';
25
25
  import { createGh, prTransportOf } from '../../../gh-exec.js';
26
26
  import { REST_MERGE_ON_GREEN } from '../../../gh-pr-rest.js';
27
+ import { ratchetWaitOutcome } from '../../../single-story/ci-ratchet-gate.js';
27
28
  import {
28
29
  confirmStoryMerged as defaultConfirmStoryMerged,
29
30
  readPrMergeState as defaultReadPrMergeState,
@@ -1074,6 +1075,8 @@ async function onMergeObserved({
1074
1075
  sleepFn,
1075
1076
  });
1076
1077
 
1078
+ const held = ratchetWaitOutcome(confirmation, { prProbe, elapsedSeconds });
1079
+ if (held) return held;
1077
1080
  if (confirmation.merged && confirmation.action === 'flip-failed') {
1078
1081
  // Block explicitly (confirmed:true would strand it at agent::closing),
1079
1082
  // but not as unlanded — the merge landed.
@@ -1099,6 +1102,9 @@ async function onMergeObserved({
1099
1102
  progress?.('CONFIRM', `✅ Story #${storyId} merge confirmed — agent::done.`);
1100
1103
  const tail = await runPostLandTailFn({
1101
1104
  storyId,
1105
+ prNumber,
1106
+ prUrl,
1107
+ gh: injectedGh,
1102
1108
  storyBranch,
1103
1109
  baseBranch,
1104
1110
  cwd,
@@ -129,8 +129,7 @@ export async function finishWithMergeWait(prCtx, deps) {
129
129
  autoMergeEnabled: prCtx.autoMergeEnabled,
130
130
  autoMergeReason: prCtx.autoMergeReason,
131
131
  gates: prCtx.gates,
132
- lockWait: prCtx.lockWait,
133
- suiteTimings: prCtx.suiteTimings,
132
+ ...closeEnvelopeFields(prCtx),
134
133
  elapsedSeconds: elapsedSecondsSince(prCtx.startedAtMs),
135
134
  });
136
135
  const result = closeResult({
@@ -145,6 +144,7 @@ export async function finishWithMergeWait(prCtx, deps) {
145
144
  // Released by the post-land tail only; any other ending keeps the claim.
146
145
  leaseReleased: waitOutcome.tail?.leaseRelease === true,
147
146
  localCleanupDeferred: prCtx.localCleanupDeferred,
147
+ pushOutcome: prCtx.pushOutcome,
148
148
  directMerged: prCtx.directMerged,
149
149
  waitedForMerge: true,
150
150
  merged: deriveObservedMerge({
@@ -159,11 +159,22 @@ export async function finishWithMergeWait(prCtx, deps) {
159
159
  config: prCtx.config,
160
160
  phaseTimer: prCtx.phaseTimer,
161
161
  worker: prCtx.worker,
162
+ provider: deps.provider,
162
163
  });
163
164
  reportWaitTerminal(terminal, { storyId: prCtx.storyId, prUrl: prCtx.prUrl });
164
165
  return { success: terminal.status === 'landed', result, terminal };
165
166
  }
166
167
 
168
+ /** The close-only envelope fields both finishes carry. */
169
+ function closeEnvelopeFields({
170
+ lockWait,
171
+ suiteTimings,
172
+ baseSync,
173
+ pushOutcome,
174
+ }) {
175
+ return { lockWait, suiteTimings, baseSync, pushOutcome };
176
+ }
177
+
167
178
  /**
168
179
  * The no-wait ending: a human owns the land, so it is `pending` with one
169
180
  * command to finish it. A direct merge by the arm is still observed.
@@ -184,6 +195,7 @@ export async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
184
195
  autoMergeReason: prCtx.autoMergeReason,
185
196
  leaseReleased: false,
186
197
  localCleanupDeferred: prCtx.localCleanupDeferred,
198
+ pushOutcome: prCtx.pushOutcome,
187
199
  directMerged: prCtx.directMerged,
188
200
  merged,
189
201
  // The flip, issue close and tail belong to `nextCommand`.
@@ -203,8 +215,7 @@ export async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
203
215
  autoMergeReason: prCtx.autoMergeReason ?? null,
204
216
  },
205
217
  gates: prCtx.gates,
206
- lockWait: prCtx.lockWait,
207
- suiteTimings: prCtx.suiteTimings,
218
+ ...closeEnvelopeFields(prCtx),
208
219
  nextCommand: NEXT_COMMANDS.confirmMerge(prCtx.storyId),
209
220
  elapsedSeconds: elapsedSecondsSince(prCtx.startedAtMs),
210
221
  });