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
@@ -1,17 +1,29 @@
1
1
  /**
2
2
  * review-providers/degraded-gates.js — the "a gate did not run" channel,
3
- * travelling beside `Finding[]` so "never ran" cannot read as clean. It
4
- * reports rather than blocks: close already hard-gates `npm run lint`.
3
+ * travelling beside `Finding[]` so "never ran" cannot read as clean. Its
4
+ * `kind` blocks only under `delivery.codeReview.onNoVerdict: "block"`.
5
5
  */
6
6
 
7
7
  /**
8
+ * @typedef {'verdict-missing'|'coverage-partial'|'context-reduced'} DegradationKind
8
9
  * @typedef {object} GateDegradation
9
10
  * @property {string} tool
10
11
  * @property {string} gate
11
12
  * @property {string} surface Sub-surface that could not run.
13
+ * @property {DegradationKind} kind
12
14
  * @property {string} reason
13
15
  */
14
16
 
17
+ const DEGRADATION_KINDS = Object.freeze([
18
+ 'verdict-missing',
19
+ 'coverage-partial',
20
+ 'context-reduced',
21
+ ]);
22
+
23
+ /** An absent or unknown kind is the one kind that can never block. */
24
+ const kindOf = (kind) =>
25
+ DEGRADATION_KINDS.includes(kind) ? kind : 'context-reduced';
26
+
15
27
  /**
16
28
  * Keep only well-formed records, so a misbehaving provider cannot corrupt output.
17
29
  *
@@ -30,12 +42,95 @@ export function normalizeDegradations(input) {
30
42
  tool: typeof d.tool === 'string' ? d.tool : 'unknown',
31
43
  gate: typeof d.gate === 'string' ? d.gate : 'unknown',
32
44
  surface,
45
+ kind: kindOf(d.kind),
33
46
  reason,
34
47
  });
35
48
  }
36
49
  return out;
37
50
  }
38
51
 
52
+ /**
53
+ * Close's `gates.codeReview`: overridden > unreviewed > partial > degraded > passed.
54
+ *
55
+ * @param {unknown} degradations
56
+ * @param {{ overridden?: boolean }} [opts]
57
+ * @returns {'overridden'|'unreviewed'|'partial'|'degraded'|'passed'}
58
+ */
59
+ export function reviewGateValue(degradations, { overridden = false } = {}) {
60
+ if (overridden) return 'overridden';
61
+ const kinds = new Set(normalizeDegradations(degradations).map((d) => d.kind));
62
+ if (kinds.has('verdict-missing')) return 'unreviewed';
63
+ if (kinds.has('coverage-partial')) return 'partial';
64
+ return kinds.size > 0 ? 'degraded' : 'passed';
65
+ }
66
+
67
+ const REDUCED_CONTEXT =
68
+ '⚠️ Review ran DEGRADED — reviewed with reduced context, so the surface(s) ' +
69
+ 'above were not fully checked. The close is not blocked by reduced ' +
70
+ 'context, but nothing here vouches for those surfaces.';
71
+
72
+ const NOT_VOUCHED =
73
+ 'unless `delivery.codeReview.onNoVerdict` is `block`; nothing here vouches ' +
74
+ 'for those surfaces.';
75
+
76
+ /**
77
+ * @param {unknown} degradations
78
+ * @returns {string[]}
79
+ */
80
+ export function reviewGapLines(degradations) {
81
+ const gate = reviewGateValue(degradations);
82
+ if (gate === 'unreviewed') {
83
+ return [
84
+ `⚠️ Review UNREVIEWED — no verdict for the surface(s) above. The close is not blocked ${NOT_VOUCHED}`,
85
+ ];
86
+ }
87
+ if (gate === 'partial') {
88
+ return [
89
+ `⚠️ Review ran PARTIAL — part of the diff above was not reviewed. The close is not blocked ${NOT_VOUCHED}`,
90
+ ];
91
+ }
92
+ return gate === 'degraded' ? [REDUCED_CONTEXT] : [];
93
+ }
94
+
95
+ /** The fix each no-verdict cause needs; matched on the record, never on PII. */
96
+ const NO_VERDICT_FIXES = [
97
+ [/not logged in|auth status/, 'run `claude auth login`'],
98
+ [/out of quota|usage limit/, 'wait for the usage-limit reset'],
99
+ [/skipped/, 'install the `claude` or `codex` CLI'],
100
+ [/remote-base-ref-unresolved/, 'fetch the base ref'],
101
+ ];
102
+
103
+ function fixFor(reason) {
104
+ const hit = NO_VERDICT_FIXES.find(([re]) => re.test(reason));
105
+ return hit ? hit[1] : 'fix the cause';
106
+ }
107
+
108
+ /**
109
+ * Under `onNoVerdict: "block"`, a verdict-missing or coverage-partial record
110
+ * halts the review; context-reduced never does.
111
+ *
112
+ * @param {{ degradations: unknown, onNoVerdict?: string, storyId: number|string }} args
113
+ * @returns {{ halted: true, haltCause: 'no-verdict', blockerReason: string }|null}
114
+ */
115
+ export function resolveNoVerdictHalt({ degradations, onNoVerdict, storyId }) {
116
+ if (onNoVerdict !== 'block') return null;
117
+ const blocking = normalizeDegradations(degradations).filter(
118
+ (d) => d.kind !== 'context-reduced',
119
+ );
120
+ if (blocking.length === 0) return null;
121
+ const causes = blocking.map(
122
+ (d) => `${d.surface} [${d.kind}]: ${d.reason} — ${fixFor(d.reason)}`,
123
+ );
124
+ return {
125
+ halted: true,
126
+ haltCause: 'no-verdict',
127
+ blockerReason:
128
+ `code-review produced no verdict for part or all of the diff ` +
129
+ `(delivery.codeReview.onNoVerdict: block): ${causes.join('; ')}. ` +
130
+ `Then re-run \`node .agents/scripts/story-review-compute.js --story ${storyId}\`.`,
131
+ };
132
+ }
133
+
39
134
  /**
40
135
  * Feature-detected; a throw degrades to empty. MUST be called after
41
136
  * `runReview`, which is when a provider records its degradations.
@@ -152,7 +247,7 @@ export function renderDegradedGatesSection(degradations) {
152
247
  ];
153
248
  for (const d of rows) {
154
249
  lines.push(
155
- `- \`${d.gate}\` → \`${d.surface}\` could not execute — ${d.reason} (emitter: \`${d.tool}\`).`,
250
+ `- \`${d.gate}\` → \`${d.surface}\` (${d.kind}) could not execute — ${d.reason} (emitter: \`${d.tool}\`).`,
156
251
  );
157
252
  }
158
253
  lines.push('');
@@ -34,12 +34,16 @@ function normalizeTitle(title) {
34
34
 
35
35
  /**
36
36
  * First 12 hex chars of sha256 over class (else category), first instance
37
- * file and, for a class-less finding, its normalized title.
37
+ * file and, for a class-less finding, its normalized title. A finding carried
38
+ * forward from the review history keeps the id it was recorded under.
38
39
  *
39
40
  * @param {Finding} finding
40
41
  * @returns {string}
41
42
  */
42
- export function findingId(finding) {
43
+ export const findingId = (finding) => finding?.carriedId ?? contentId(finding);
44
+
45
+ /** @param {Finding} finding */
46
+ function contentId(finding) {
43
47
  const cls = finding?.class;
44
48
  const parts = [
45
49
  cls || finding?.category || 'bug',
@@ -115,10 +115,57 @@ function renderRepeatsSection(repeats) {
115
115
  ];
116
116
  }
117
117
 
118
- /** Fresh findings render in full per tier; repeats render collapsed. */
118
+ const EARLIER_STATUS = Object.freeze({
119
+ 'still-open': 'still open',
120
+ fixed: 'fixed',
121
+ refuted: 'refuted',
122
+ overridden: 'overridden',
123
+ });
124
+
125
+ /** @param {{ id: string, title: string|null, instances: object[], headSha: string, status: string, reason?: string }} e */
126
+ function renderEarlier(e) {
127
+ const where = e.instances.map((i) => `\`${formatLocation(i)}\``).join(', ');
128
+ const status = EARLIER_STATUS[e.status] ?? e.status;
129
+ return (
130
+ `- ${e.title ?? '(untitled)'} — \`${e.id}\`${where ? ` — ${where}` : ''}` +
131
+ ` — raised at \`${e.headSha}\` — **${status}**${e.reason ? `: ${e.reason}` : ''}`
132
+ );
133
+ }
134
+
135
+ /** Every earlier surviving CRITICAL, in history order, with its status. */
136
+ function renderEarlierSection(earlier) {
137
+ if (!Array.isArray(earlier) || earlier.length === 0) return [];
138
+ return [
139
+ `### 🔁 Earlier CRITICALs (${earlier.length})`,
140
+ '',
141
+ ...earlier.map(renderEarlier),
142
+ '',
143
+ ];
144
+ }
145
+
146
+ /**
147
+ * The findings, or the no-findings block unless an earlier CRITICAL is
148
+ * still open.
149
+ */
150
+ function renderBody(findings, totalKnown, degraded, earlier = []) {
151
+ if (totalKnown > 0) return renderFindingSections(findings);
152
+ return earlier.some((e) => e.status === 'still-open')
153
+ ? []
154
+ : renderNoFindingsBlock(degraded);
155
+ }
156
+
157
+ /** Rendered in full under its tier. */
158
+ const isFresh = (f) => f && !f.repeat && !f.carried;
159
+ /** Rendered collapsed under Previously raised. */
160
+ const isRepeat = (f) => f?.repeat && !f.carried;
161
+
162
+ /**
163
+ * Fresh findings render in full per tier; repeats render collapsed; carried
164
+ * ones render only under Earlier CRITICALs.
165
+ */
119
166
  function renderFindingSections(findings) {
120
167
  const lines = [];
121
- const fresh = findings.filter((f) => f && !f.repeat);
168
+ const fresh = findings.filter(isFresh);
122
169
  for (const sev of SEVERITY_ORDER) {
123
170
  const tierFindings = fresh.filter((f) => f.severity === sev);
124
171
  if (tierFindings.length === 0) continue;
@@ -126,7 +173,7 @@ function renderFindingSections(findings) {
126
173
  lines.push(`### ${meta.emoji} ${meta.label} (${tierFindings.length})`, '');
127
174
  for (const finding of tierFindings) lines.push(renderFinding(finding), '');
128
175
  }
129
- return [...lines, ...renderRepeatsSection(findings.filter((f) => f?.repeat))];
176
+ return [...lines, ...renderRepeatsSection(findings.filter(isRepeat))];
130
177
  }
131
178
 
132
179
  /**
@@ -160,6 +207,7 @@ function renderManualPromptsSection(messages) {
160
207
  * degradations?: ReadonlyArray<object>,
161
208
  * verification?: Record<string, number>,
162
209
  * skipped?: number,
210
+ * earlierCriticals?: ReadonlyArray<object>,
163
211
  * }} input
164
212
  * @returns {string}
165
213
  */
@@ -197,11 +245,10 @@ export function renderFindings(input) {
197
245
  ...renderDegradedGatesSection(degraded),
198
246
  ];
199
247
 
200
- if (totalKnown === 0) {
201
- lines.push(...renderNoFindingsBlock(degraded));
202
- } else {
203
- lines.push(...renderFindingSections(findings));
204
- }
248
+ lines.push(
249
+ ...renderEarlierSection(input.earlierCriticals),
250
+ ...renderBody(findings, totalKnown, degraded, input.earlierCriticals),
251
+ );
205
252
 
206
253
  const promptLines = renderManualPromptsSection(promptMessages ?? []);
207
254
  if (promptLines.length > 0) {
@@ -46,6 +46,7 @@ export function loadReviewGuidance({
46
46
  tool: 'review-guidance',
47
47
  gate: 'codeReview',
48
48
  surface: 'review-guidance',
49
+ kind: 'context-reduced',
49
50
  reason:
50
51
  `${file} truncated at ${MAX_GUIDANCE_CHARS} characters: ` +
51
52
  `${trimmed.length - MAX_GUIDANCE_CHARS} characters not rendered`,
@@ -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,
@@ -100,6 +103,7 @@ export async function runCloseValidationPhase({
100
103
  log: gateLog.log,
101
104
  storyId,
102
105
  evidenceCwd: cwd,
106
+ baselineRef: baseSync?.baselineRef,
103
107
  };
104
108
  const gateList = applyTestDelta(buildDefaultGates(gateOpts), {
105
109
  ...gateOpts,
@@ -134,7 +138,7 @@ export async function runCloseValidationPhase({
134
138
  lockWait,
135
139
  suiteTimings: sourcedTimings(timings, 'close'),
136
140
  pending: false,
137
- coverageDeferred: (validation.deferred ?? []).length > 0,
141
+ coverageDeferred: validation.deferred?.[0]?.reason ?? null,
138
142
  };
139
143
  }
140
144
 
@@ -191,6 +195,13 @@ async function runGateChain({
191
195
  * }} args
192
196
  * @returns {{ gates: null, lockWait: object, suiteTimings: null, pending: true }}
193
197
  */
198
+ /** A failed check-baselines entry names the kinds its output reported FAIL. */
199
+ function tagBaselinesKinds(err, gateName, gateLog) {
200
+ if (!Object.values(BASELINES_GATE_NAMES).includes(gateName)) return;
201
+ const kinds = gateLog.baselinesKinds();
202
+ if (kinds.length > 0) err.closeBaselinesKinds = kinds;
203
+ }
204
+
194
205
  function settleFailedValidation({ validation, lockWait, gateLog, progress }) {
195
206
  const [first] = validation.failed;
196
207
  const { gate, status, cwd: gateCwd } = first;
@@ -207,6 +218,7 @@ function settleFailedValidation({ validation, lockWait, gateLog, progress }) {
207
218
  (gate.hint ? ` ${gate.hint}` : ''),
208
219
  );
209
220
  err.closeGate = gate.name;
221
+ tagBaselinesKinds(err, gate.name, gateLog);
210
222
  throw err;
211
223
  }
212
224