mandrel 2.110.0 → 2.112.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (190) hide show
  1. package/.agents/agents/acceptance-critic.md +14 -0
  2. package/.agents/agents/auditor.md +14 -0
  3. package/.agents/agents/plan-critic.md +5 -0
  4. package/.agents/agents/story-worker.md +4 -1
  5. package/.agents/audit-checklists/state-machines.md +21 -0
  6. package/.agents/docs/agentrc-reference.json +23 -10
  7. package/.agents/docs/configuration.md +362 -15
  8. package/.agents/docs/execution-reference.md +11 -0
  9. package/.agents/docs/workflows.md +2 -1
  10. package/.agents/rules/ci-remediation.md +28 -4
  11. package/.agents/rules/git-conventions-reference.md +7 -0
  12. package/.agents/schemas/agentrc.schema.json +179 -13
  13. package/.agents/schemas/audit-rules.json +28 -0
  14. package/.agents/schemas/baselines/baseline-envelope.schema.json +16 -4
  15. package/.agents/schemas/baselines/bundle-size.schema.json +1 -0
  16. package/.agents/schemas/baselines/coverage.schema.json +1 -0
  17. package/.agents/schemas/baselines/crap.schema.json +37 -10
  18. package/.agents/schemas/baselines/duplication.schema.json +1 -0
  19. package/.agents/schemas/baselines/maintainability.schema.json +1 -0
  20. package/.agents/schemas/baselines/mutation.schema.json +1 -0
  21. package/.agents/schemas/crap-report.schema.json +6 -5
  22. package/.agents/schemas/story-deliver-terminal.schema.json +49 -3
  23. package/.agents/schemas/story-progress.schema.json +1 -1
  24. package/.agents/schemas/validation-evidence.schema.json +2 -2
  25. package/.agents/scripts/boot-sweep.js +41 -3
  26. package/.agents/scripts/coverage-capture.js +39 -3
  27. package/.agents/scripts/coverage-ratchet.js +106 -0
  28. package/.agents/scripts/evidence-gate.js +84 -21
  29. package/.agents/scripts/file-ci-gap.js +220 -10
  30. package/.agents/scripts/lib/audit-baselines/read.js +8 -1
  31. package/.agents/scripts/lib/audit-baselines/trend.js +2 -1
  32. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  33. package/.agents/scripts/lib/baseline-loader.js +4 -2
  34. package/.agents/scripts/lib/baselines/codec.js +57 -0
  35. package/.agents/scripts/lib/baselines/crap-preview-incremental.js +8 -3
  36. package/.agents/scripts/lib/baselines/crap-preview-scan.js +10 -16
  37. package/.agents/scripts/lib/baselines/crap-updater-cli.js +4 -13
  38. package/.agents/scripts/lib/baselines/kernel.js +19 -1
  39. package/.agents/scripts/lib/baselines/kinds/_crap-codec.js +171 -0
  40. package/.agents/scripts/lib/baselines/kinds/_crap-read.js +56 -16
  41. package/.agents/scripts/lib/baselines/kinds/_shared-metric.js +0 -59
  42. package/.agents/scripts/lib/baselines/kinds/crap.js +283 -319
  43. package/.agents/scripts/lib/baselines/preview-gates.js +29 -10
  44. package/.agents/scripts/lib/baselines/reader.js +36 -9
  45. package/.agents/scripts/lib/baselines/refresh-service.js +79 -18
  46. package/.agents/scripts/lib/baselines/seat-missing.js +173 -7
  47. package/.agents/scripts/lib/baselines/writer.js +36 -21
  48. package/.agents/scripts/lib/changed-files.js +70 -6
  49. package/.agents/scripts/lib/child-exec.js +10 -0
  50. package/.agents/scripts/lib/claude/agents-projection.js +5 -5
  51. package/.agents/scripts/lib/close-lock-events.js +8 -3
  52. package/.agents/scripts/lib/close-validation/ci-deferral.js +40 -0
  53. package/.agents/scripts/lib/close-validation/gates.js +156 -32
  54. package/.agents/scripts/lib/close-validation/process.js +16 -7
  55. package/.agents/scripts/lib/close-validation/projections/crap.js +43 -10
  56. package/.agents/scripts/lib/close-validation/runner.js +160 -41
  57. package/.agents/scripts/lib/close-validation/skip-branch-test.js +144 -0
  58. package/.agents/scripts/lib/close-validation/test-delta.js +33 -8
  59. package/.agents/scripts/lib/codex/agents-projection.js +6 -0
  60. package/.agents/scripts/lib/config/agentrc-overlay.js +9 -5
  61. package/.agents/scripts/lib/config/explain.js +5 -2
  62. package/.agents/scripts/lib/config/gates/coverage.schema.js +53 -0
  63. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  64. package/.agents/scripts/lib/config/git-roots.js +38 -4
  65. package/.agents/scripts/lib/config/handoff.js +24 -0
  66. package/.agents/scripts/lib/config/quality.js +28 -12
  67. package/.agents/scripts/lib/config/worktree-isolation.js +2 -5
  68. package/.agents/scripts/lib/config-resolver.js +22 -2
  69. package/.agents/scripts/lib/config-settings-schema-delivery.js +87 -4
  70. package/.agents/scripts/lib/config-settings-schema-quality.js +36 -1
  71. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  72. package/.agents/scripts/lib/coverage-capture-affected.js +1 -0
  73. package/.agents/scripts/lib/coverage-capture-delta.js +164 -32
  74. package/.agents/scripts/lib/coverage-capture-own-fix.js +232 -0
  75. package/.agents/scripts/lib/coverage-capture-usage.js +2 -2
  76. package/.agents/scripts/lib/coverage-capture.js +31 -0
  77. package/.agents/scripts/lib/coverage-deferral.js +96 -0
  78. package/.agents/scripts/lib/coverage-ratchet.js +187 -0
  79. package/.agents/scripts/lib/crap-baseline-join.js +5 -5
  80. package/.agents/scripts/lib/crap-engine.js +3 -3
  81. package/.agents/scripts/lib/crap-method-identity.js +104 -48
  82. package/.agents/scripts/lib/escomplex-anchor.js +135 -0
  83. package/.agents/scripts/lib/escomplex-kernel.js +30 -1
  84. package/.agents/scripts/lib/failure-rows.js +121 -0
  85. package/.agents/scripts/lib/full-suite-lock.js +44 -4
  86. package/.agents/scripts/lib/full-suite-queue.js +89 -13
  87. package/.agents/scripts/lib/generated/agentrc-validator.js +8 -2
  88. package/.agents/scripts/lib/gh-env.js +3 -6
  89. package/.agents/scripts/lib/gh-pr-rest.js +1 -0
  90. package/.agents/scripts/lib/git/base-sync-probe.js +182 -0
  91. package/.agents/scripts/lib/git-branch-lifecycle.js +9 -0
  92. package/.agents/scripts/lib/observability/close-telemetry.js +37 -2
  93. package/.agents/scripts/lib/observability/handoff-telemetry.js +170 -0
  94. package/.agents/scripts/lib/observability/review-dispositions.js +23 -6
  95. package/.agents/scripts/lib/observability/runtime-friction.js +17 -4
  96. package/.agents/scripts/lib/observability/source-classifier.js +3 -0
  97. package/.agents/scripts/lib/observability/story-outcome.js +393 -0
  98. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +2 -1
  99. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +19 -1
  100. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +84 -0
  101. package/.agents/scripts/lib/orchestration/check-baselines/phases/pipeline.js +14 -5
  102. package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js +3 -2
  103. package/.agents/scripts/lib/orchestration/check-baselines/phases/report.js +26 -6
  104. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +124 -23
  105. package/.agents/scripts/lib/orchestration/code-review.js +223 -19
  106. package/.agents/scripts/lib/orchestration/handoff-gates.js +217 -44
  107. package/.agents/scripts/lib/orchestration/handoff-rescore.js +169 -0
  108. package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +45 -0
  109. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -1
  110. package/.agents/scripts/lib/orchestration/plan-persist/source-rewrite.js +76 -4
  111. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +2 -2
  112. package/.agents/scripts/lib/orchestration/preflight-lanes.js +208 -0
  113. package/.agents/scripts/lib/orchestration/review-base-ref.js +40 -17
  114. package/.agents/scripts/lib/orchestration/review-deposit.js +38 -12
  115. package/.agents/scripts/lib/orchestration/review-depth.js +21 -0
  116. package/.agents/scripts/lib/orchestration/review-history.js +124 -20
  117. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +23 -8
  118. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +82 -39
  119. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +64 -11
  120. package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js +98 -3
  121. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +6 -2
  122. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +55 -8
  123. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +1 -0
  124. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +42 -15
  125. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  126. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +10 -1
  127. package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js +10 -0
  128. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +7 -4
  129. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +17 -2
  130. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +59 -2
  131. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +13 -1
  132. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +15 -4
  133. package/.agents/scripts/lib/orchestration/single-story-close/phases/land-review-record.js +213 -0
  134. package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +17 -2
  135. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +42 -20
  136. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +51 -26
  137. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +3 -1
  138. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +51 -15
  139. package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js +59 -11
  140. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +1 -0
  141. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-block.js +31 -13
  142. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +29 -6
  143. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-outcome.js +10 -12
  144. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +19 -4
  145. package/.agents/scripts/lib/orchestration/single-story-close/result.js +43 -13
  146. package/.agents/scripts/lib/orchestration/single-story-close/review-overlap.js +73 -39
  147. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +11 -2
  148. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +3 -2
  149. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +20 -8
  150. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +7 -0
  151. package/.agents/scripts/lib/orchestration/story-handoff.js +789 -196
  152. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  153. package/.agents/scripts/lib/pr-body-lines.js +32 -0
  154. package/.agents/scripts/lib/single-story/ci-ratchet-gate.js +140 -0
  155. package/.agents/scripts/lib/single-story/confirm-and-land.js +17 -7
  156. package/.agents/scripts/lib/single-story/confirm-merge.js +12 -3
  157. package/.agents/scripts/lib/single-story-sweep/report-stalled-executing.js +202 -0
  158. package/.agents/scripts/lib/standalone-ratchets.js +37 -0
  159. package/.agents/scripts/lib/suite-admission.js +20 -8
  160. package/.agents/scripts/lib/suite-sizing.js +146 -0
  161. package/.agents/scripts/lib/workspace-provisioner.js +2 -2
  162. package/.agents/scripts/merge-baseline.js +14 -3
  163. package/.agents/scripts/providers/github/comments.js +19 -3
  164. package/.agents/scripts/providers/github.js +1 -0
  165. package/.agents/scripts/review-dispositions-report.js +1 -1
  166. package/.agents/scripts/role-scope-guard.js +267 -0
  167. package/.agents/scripts/single-story-close.js +4 -4
  168. package/.agents/scripts/single-story-confirm-merge.js +31 -5
  169. package/.agents/scripts/single-story-init.js +24 -4
  170. package/.agents/scripts/story-handoff.js +3 -3
  171. package/.agents/scripts/story-outcomes-report.js +231 -0
  172. package/.agents/scripts/story-review-compute.js +9 -5
  173. package/.agents/scripts/update-coverage-baseline.js +12 -2
  174. package/.agents/scripts/update-crap-baseline.js +9 -1
  175. package/.agents/workflows/audit-state-machines.md +213 -0
  176. package/.agents/workflows/helpers/code-review.md +63 -9
  177. package/.agents/workflows/helpers/deliver-digest.md +53 -54
  178. package/.agents/workflows/helpers/deliver-reference.md +236 -63
  179. package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
  180. package/.agents/workflows/helpers/deliver-story.md +7 -2
  181. package/.agents/workflows/helpers/parallel-tooling.md +29 -0
  182. package/.agents/workflows/helpers/plan-reference.md +10 -2
  183. package/docs/CHANGELOG.md +56 -0
  184. package/lib/cli/doctor-checks/coverage-ratchet.js +54 -0
  185. package/lib/cli/doctor-checks/effective-agentrc.js +23 -0
  186. package/lib/cli/doctor-checks/llm-review.js +2 -11
  187. package/lib/cli/doctor-checks/sync-parity.js +5 -1
  188. package/lib/cli/doctor-checks/test-credit-path.js +7 -2
  189. package/lib/cli/registry.js +5 -0
  190. package/package.json +1 -1
@@ -0,0 +1,208 @@
1
+ /**
2
+ * preflight-lanes.js — the handoff preflight's opt-in concurrent path
3
+ * (`delivery.execution.preflightConcurrency` above 1): one unadmitted base
4
+ * lane plus up to N − 1 lanes that run close's independent deposited gates
5
+ * under a zero-wait suite admission. Findings settle in check order.
6
+ */
7
+
8
+ import { isIndependentGate } from '../close-validation/gates.js';
9
+ import {
10
+ ADMISSION_REFUSED_EXIT_CODE,
11
+ isFullSuiteLockEnabled,
12
+ SUITE_RESERVATION_ENV,
13
+ } from '../full-suite-lock.js';
14
+ import {
15
+ hashCommandConfig,
16
+ recordPass,
17
+ shouldSkip,
18
+ treeFingerprint,
19
+ } from '../validation-evidence.js';
20
+
21
+ const MISS_REASONS = Object.freeze({
22
+ [ADMISSION_REFUSED_EXIT_CODE]: 'admission refused',
23
+ });
24
+
25
+ /**
26
+ * The lane count to run, or `null` for the serial loop. Above 1 but
27
+ * unbounded by admission, one progress line names why it stays serial.
28
+ *
29
+ * @param {object} ctx
30
+ * @returns {number|null}
31
+ */
32
+ export function requestedLanes(ctx) {
33
+ const n = ctx.config?.delivery?.execution?.preflightConcurrency ?? 1;
34
+ if (!(n > 1)) return null;
35
+ const why = serialReason(ctx);
36
+ if (!why) return n;
37
+ ctx.progress(
38
+ 'preflight',
39
+ `running serially (preflightConcurrency ${n}): ${why}`,
40
+ );
41
+ return null;
42
+ }
43
+
44
+ function serialReason(ctx) {
45
+ if (!isFullSuiteLockEnabled({ config: ctx.config, env: ctx.env })) {
46
+ return 'suite admission is off';
47
+ }
48
+ if (ctx.env?.[SUITE_RESERVATION_ENV]) {
49
+ return 'the handoff already runs inside a suite reservation';
50
+ }
51
+ return null;
52
+ }
53
+
54
+ /** A deposited close gate close itself runs in its independent bucket. */
55
+ function isLaneEligible(check) {
56
+ return Boolean(check.deposit) && isIndependentGate(check.key);
57
+ }
58
+
59
+ /**
60
+ * Run `checks` over the base lane and `requested − 1` admitted lanes. No lane
61
+ * aborts a sibling; a check an admitted lane could not admit returns to the
62
+ * queue in check order and that lane retires.
63
+ *
64
+ * @param {object} ctx
65
+ * @param {object[]} checks
66
+ * @param {number} requested
67
+ * @param {(check: object, env?: object) => Promise<object|null>} runCheck
68
+ * @returns {Promise<{ findings: object[], admitted: string[] }>}
69
+ */
70
+ export async function runPreflightLanes(ctx, checks, requested, runCheck) {
71
+ const queue = checks.map((check, index) => ({ check, index }));
72
+ const findings = new Array(checks.length).fill(null);
73
+ const admitted = [];
74
+ const take = (eligible) => {
75
+ const at = queue.findIndex(({ check }) => eligible(check));
76
+ return at === -1 ? null : queue.splice(at, 1)[0];
77
+ };
78
+ const any = () => true;
79
+ const baseLane = async () => {
80
+ for (let item = take(any); item; item = take(any)) {
81
+ findings[item.index] = await runCheck(item.check);
82
+ }
83
+ };
84
+ const admittedLane = async () => {
85
+ for (let item = take(isLaneEligible); item; item = take(isLaneEligible)) {
86
+ const out = await admitAndRun(ctx, item.check, runCheck);
87
+ if (out.miss) {
88
+ queue.splice(
89
+ queue.findLastIndex((e) => e.index < item.index) + 1,
90
+ 0,
91
+ item,
92
+ );
93
+ ctx.progress(
94
+ 'preflight',
95
+ `↩ ${item.check.key} back to the serial lane: ${out.miss}`,
96
+ );
97
+ return;
98
+ }
99
+ admitted.push(item.index);
100
+ findings[item.index] = out.finding;
101
+ }
102
+ };
103
+ // The base lane starts first, so it takes the first check.
104
+ const lanes = [baseLane()];
105
+ for (let i = 1; i < requested; i++) lanes.push(admittedLane());
106
+ await settleAll(lanes);
107
+ // A check handed back after the base lane drained still runs, in order.
108
+ await baseLane();
109
+ checks.forEach((check, i) => {
110
+ if (findings[i] === null && check.deposit && !check.held) {
111
+ reconcileDeposit(ctx, check);
112
+ }
113
+ });
114
+ return {
115
+ findings: findings.filter(Boolean),
116
+ admitted: admitted.sort((a, b) => a - b).map((i) => checks[i].key),
117
+ };
118
+ }
119
+
120
+ /** Every lane settles before the first rejection, if any, is rethrown. */
121
+ async function settleAll(lanes) {
122
+ const settled = await Promise.allSettled(lanes);
123
+ const failed = settled.find((s) => s.status === 'rejected');
124
+ if (failed) throw failed.reason;
125
+ }
126
+
127
+ /**
128
+ * Admit `check` under close's argv with no wait and run it inside the
129
+ * reservation, so a nested admission spawns inside it.
130
+ *
131
+ * @returns {Promise<{ finding: object|null }|{ miss: string }>}
132
+ */
133
+ async function admitAndRun(ctx, check, runCheck) {
134
+ const crash = {};
135
+ let out;
136
+ try {
137
+ out = await ctx.admitSuite(
138
+ admissionOptions(ctx, check),
139
+ guardedRun(ctx, check, runCheck, crash),
140
+ );
141
+ } catch (err) {
142
+ // Only an admission-side throw hands the check back; its own throw escapes.
143
+ return admissionMiss(crash, err);
144
+ }
145
+ return typeof out === 'number' ? exitMiss(out) : out;
146
+ }
147
+
148
+ /** Close's argv for `check`, admitted with no wait. */
149
+ function admissionOptions(ctx, check) {
150
+ return {
151
+ argv: [check.deposit.cmd, ...check.deposit.args],
152
+ cwd: ctx.cwd,
153
+ env: ctx.env,
154
+ config: ctx.config,
155
+ log: () => {},
156
+ lockOptions: { waitMs: 0 },
157
+ };
158
+ }
159
+
160
+ /** Run `check` inside the reservation, flagging its own throw on `crash`. */
161
+ function guardedRun(ctx, check, runCheck, crash) {
162
+ return async ({ env }) => {
163
+ try {
164
+ return { finding: await runCheck(check, { ...ctx.env, ...env }) };
165
+ } catch (err) {
166
+ crash.err = err;
167
+ crash.thrown = true;
168
+ throw err;
169
+ }
170
+ };
171
+ }
172
+
173
+ function admissionMiss(crash, err) {
174
+ if (crash.thrown) throw crash.err;
175
+ return { miss: `admission failed: ${err?.message ?? err}` };
176
+ }
177
+
178
+ function exitMiss(out) {
179
+ return {
180
+ miss: `${MISS_REASONS[out] ?? 'not admitted without a wait'} (exit ${out})`,
181
+ };
182
+ }
183
+
184
+ /**
185
+ * Re-record a passed deposit two overlapping `evidence-gate.js` writes may
186
+ * have lost, hashed as close hashes it; best-effort, like `carryCredit`.
187
+ */
188
+ function reconcileDeposit(ctx, check) {
189
+ const configHash = hashCommandConfig({ ...check.deposit, cwd: ctx.cwd });
190
+ const opts = { cwd: ctx.evidenceCwd, standalone: true };
191
+ const key = { storyId: ctx.storyId, gateName: check.key, configHash };
192
+ try {
193
+ if (shouldSkip({ ...key, currentSha: ctx.head }, opts).skip) return;
194
+ recordPass(
195
+ {
196
+ ...key,
197
+ sha: ctx.head,
198
+ inputFingerprint: treeFingerprint(ctx.cwd, ctx.git),
199
+ },
200
+ opts,
201
+ );
202
+ } catch (err) {
203
+ ctx.progress(
204
+ 'preflight',
205
+ `⚠️ ${check.key} deposit not re-recorded: ${err?.message ?? err}`,
206
+ );
207
+ }
208
+ }
@@ -2,22 +2,26 @@
2
2
  * The base ref a Story-scope review measures against: `origin/<base>`, the ref
3
3
  * base-sync merged — never the bare name, whose stale local ref would score
4
4
  * others' landed commits as this Story's. Resolved once and threaded to every
5
- * review arm. Unresolvable fails safe: a degradation record, no findings.
5
+ * review arm. Unresolvable fails safe: a `verdict-missing` degradation, no
6
+ * findings, and a halt under `delivery.codeReview.onNoVerdict: "block"`.
6
7
  */
7
8
 
9
+ import { remoteBaseRef as sharedRemoteBaseRef } from '../changed-files.js';
8
10
  import { gitSpawn } from '../git-utils.js';
9
- import { degradationEnvelope } from './review-providers/degraded-gates.js';
11
+ import {
12
+ degradationEnvelope,
13
+ resolveNoVerdictHalt,
14
+ } from './review-providers/degraded-gates.js';
10
15
 
11
16
  /**
12
- * `main` → `origin/main`; already-qualified input passes through.
17
+ * Re-export of the shared spelling in `changed-files.js`, kept for review
18
+ * importers.
13
19
  *
14
20
  * @param {unknown} baseBranch
15
- * @returns {string|null} the remote-tracking ref, or `null` when unnameable.
21
+ * @returns {string|null}
16
22
  */
17
23
  export function remoteBaseRef(baseBranch) {
18
- const base = typeof baseBranch === 'string' ? baseBranch.trim() : '';
19
- if (base.length === 0) return null;
20
- return base.startsWith('origin/') ? base : `origin/${base}`;
24
+ return sharedRemoteBaseRef(baseBranch);
21
25
  }
22
26
 
23
27
  /**
@@ -56,9 +60,32 @@ export function resolveSharedBaseRef({
56
60
  return { ref: null, resolved: false, remoteRef };
57
61
  }
58
62
 
63
+ /** @param {string} surface */
64
+ function unresolvedBaseDegradations(surface) {
65
+ return [
66
+ {
67
+ tool: 'story-scope-review',
68
+ gate: 'base-ref-resolution',
69
+ surface,
70
+ kind: 'verdict-missing',
71
+ reason: 'remote-base-ref-unresolved',
72
+ },
73
+ ];
74
+ }
75
+
76
+ /** A halt under `onNoVerdict: "block"`, else none. */
77
+ function haltFields(args) {
78
+ const halt = resolveNoVerdictHalt(args);
79
+ return {
80
+ halted: halt !== null,
81
+ haltCause: halt?.haltCause ?? null,
82
+ blockerReason: halt?.blockerReason ?? null,
83
+ };
84
+ }
85
+
59
86
  /**
60
87
  * A completed-review-shaped envelope whose `degraded` flag keeps "no findings"
61
- * from reading as "clean". Reported, not blocking.
88
+ * from reading as "clean". Reported, or halting under `onNoVerdict: "block"`.
62
89
  *
63
90
  * @param {{
64
91
  * storyId: number|string,
@@ -66,6 +93,7 @@ export function resolveSharedBaseRef({
66
93
  * remoteRef: string|null,
67
94
  * progress: (tag: string, msg: string) => void,
68
95
  * progressTag?: string,
96
+ * onNoVerdict?: string,
69
97
  * }} args
70
98
  * @returns {object}
71
99
  */
@@ -75,6 +103,7 @@ export function unresolvedBaseReviewOutcome({
75
103
  remoteRef,
76
104
  progress,
77
105
  progressTag = 'REVIEW',
106
+ onNoVerdict,
78
107
  }) {
79
108
  const surface = remoteRef ?? `origin/${baseBranch}`;
80
109
  progress(
@@ -85,20 +114,14 @@ export function unresolvedBaseReviewOutcome({
85
114
  'findings are raised. Fetch the base ref (or re-run without ' +
86
115
  '--skip-sync) to restore the review.',
87
116
  );
117
+ const degradations = unresolvedBaseDegradations(surface);
88
118
  return {
89
- halted: false,
119
+ ...haltFields({ degradations, onNoVerdict, storyId }),
90
120
  skipped: true,
91
121
  severity: { critical: 0, high: 0, medium: 0, suggestion: 0 },
92
122
  posted: false,
93
123
  postedCommentId: null,
94
- ...degradationEnvelope([
95
- {
96
- tool: 'story-scope-review',
97
- gate: 'base-ref-resolution',
98
- surface,
99
- reason: 'remote-base-ref-unresolved',
100
- },
101
- ]),
124
+ ...degradationEnvelope(degradations),
102
125
  crossRefPosted: false,
103
126
  };
104
127
  }
@@ -2,11 +2,12 @@
2
2
  * review-deposit.js — the held Story-scope review a worker computes at push
3
3
  * time, and its identity.
4
4
  *
5
- * The identity is the **diff digest**: a sha256 of the exact
6
- * `git diff --no-color <base>...<head>` text, less generated files. A clean
7
- * base-sync merge moves HEAD without changing that text, while any commit
8
- * that changes the diff changes it — so close adopts a deposit, and posts a
9
- * held result, on digest equality, never on SHA equality.
5
+ * The identity is the **diff digest**: a sha256 of the
6
+ * `git diff --no-color <base>...<head>` text, less generated files, `index`
7
+ * lines and hunk-header offsets (`git patch-id --stable`'s sameness). A
8
+ * base-sync merge that only moves merge-base blobs or line positions keeps
9
+ * it; any changed `+`, `-` or context line moves it — so close adopts a
10
+ * deposit, and posts a held result, on digest equality, never on SHA equality.
10
11
  *
11
12
  * The file lives beside the terminal envelope; nothing deletes it but the
12
13
  * Story temp purge. A mismatched deposit is simply not adopted.
@@ -46,7 +47,17 @@ export function resolveRefSha({ cwd, ref, gitSpawnFn }) {
46
47
  }
47
48
  }
48
49
 
49
- /** Generated sections dropped; end-trimmed as the runner trims stdout. */
50
+ /** A section less its `index` lines, each hunk header reduced to `@@`. */
51
+ function identityOf(section) {
52
+ return section
53
+ .trimEnd()
54
+ .split('\n')
55
+ .filter((line) => !line.startsWith('index '))
56
+ .map((line) => (/^@@ -\d/.test(line) ? '@@' : line))
57
+ .join('\n');
58
+ }
59
+
60
+ /** Generated sections dropped, the rest reduced to their identity. */
50
61
  function reviewedText(diff, deps) {
51
62
  const sections = diffSections(diff);
52
63
  const generated = generatedPaths(
@@ -55,13 +66,13 @@ function reviewedText(diff, deps) {
55
66
  );
56
67
  return sections
57
68
  .filter((s) => !generated.has(sectionPath(s)))
58
- .map((s) => s.trimEnd())
69
+ .map(identityOf)
59
70
  .join('\n');
60
71
  }
61
72
 
62
73
  /**
63
- * sha256 of the three-dot diff text, spawned exactly as the review provider
64
- * spawns it. `null` when the diff cannot be read — an unknown identity that
74
+ * sha256 of the three-dot diff's identity, spawned exactly as the review
75
+ * provider spawns it (the provider still receives the raw diff). `null` when the diff cannot be read — an unknown identity that
65
76
  * never matches anything.
66
77
  *
67
78
  * @param {{ cwd: string, baseRef: string|null, headRef: string|null,
@@ -85,6 +96,12 @@ export function computeReviewDiffDigest({ cwd, baseRef, headRef, gitSpawnFn }) {
85
96
  }
86
97
  }
87
98
 
99
+ /** A halt recorded before `haltCause` existed was a critical one. */
100
+ function haltCauseOf(record) {
101
+ if (!record.halted) return null;
102
+ return record.haltCause === 'no-verdict' ? 'no-verdict' : 'critical';
103
+ }
104
+
88
105
  /**
89
106
  * Flatten a computed review `result` into the deposit record.
90
107
  *
@@ -110,6 +127,7 @@ export function buildReviewDeposit({
110
127
  provider: result.providerName ?? null,
111
128
  severity: result.severity,
112
129
  halted: !!result.halted,
130
+ haltCause: haltCauseOf(result),
113
131
  criticalByProvider: result.criticalByProvider ?? {},
114
132
  findings: Array.isArray(result.findings) ? result.findings : [],
115
133
  report: result.report ?? '',
@@ -138,6 +156,7 @@ export function depositAsComputedReview(deposit) {
138
156
  posted: false,
139
157
  postedCommentId: null,
140
158
  halted: deposit.halted,
159
+ haltCause: haltCauseOf(deposit),
141
160
  criticalByProvider: deposit.criticalByProvider,
142
161
  degraded: deposit.degraded,
143
162
  degradations: deposit.degradations,
@@ -183,7 +202,7 @@ function isDeposit(record, storyId) {
183
202
  * @returns {object|null} the Story's deposit, or `null` when absent or
184
203
  * malformed.
185
204
  */
186
- function readReviewDeposit(storyId, { config, fsImpl = nodeFs } = {}) {
205
+ export function readReviewDeposit(storyId, { config, fsImpl = nodeFs } = {}) {
187
206
  try {
188
207
  const raw = fsImpl.readFileSync(
189
208
  storyReviewDepositPath(storyId, config),
@@ -226,6 +245,13 @@ export function probeHeldReviewDiff({
226
245
  const deposit = diffDigest
227
246
  ? readDepositFn(Number(storyId), { config })
228
247
  : null;
229
- const matches = deposit?.diffDigest === diffDigest;
230
- return { baseRef, diffDigest, deposit: matches ? deposit : null };
248
+ const held = adoptable(deposit, diffDigest) ? deposit : null;
249
+ return { baseRef, diffDigest, deposit: held };
250
+ }
251
+
252
+ /** A missing verdict reflects the provider's state, not the diff. */
253
+ function adoptable(deposit, diffDigest) {
254
+ return (
255
+ deposit?.diffDigest === diffDigest && deposit.haltCause !== 'no-verdict'
256
+ );
231
257
  }
@@ -8,6 +8,7 @@
8
8
  */
9
9
 
10
10
  import { selectSensitivePathClasses } from '../audit-suite/selector.js';
11
+ import { normalizeDepth } from './review-providers/review-depth.js';
11
12
 
12
13
  /** Classify review diff width only — not planning sizing ceilings. */
13
14
  export const DEFAULT_DIFF_WIDTH = Object.freeze({
@@ -102,3 +103,23 @@ export function resolveDepth(input = {}) {
102
103
  if (derivedLevel === 'low' && isSmall) return 'light';
103
104
  return 'standard';
104
105
  }
106
+
107
+ /** Shipped depth → `claude --effort`; `delivery.codeReview.effortByDepth` overrides per depth. */
108
+ const DEFAULT_EFFORT_BY_DEPTH = Object.freeze({
109
+ light: 'low',
110
+ standard: 'low',
111
+ deep: 'high',
112
+ });
113
+
114
+ /**
115
+ * Anything but `light`/`deep` (including no depth) resolves as `standard`.
116
+ *
117
+ * @param {ReviewDepth|undefined} depth
118
+ * @param {Partial<Record<ReviewDepth, string>>|null|undefined} effortByDepth
119
+ * @returns {string}
120
+ */
121
+ export function resolveReviewEffort(depth, effortByDepth) {
122
+ return { ...DEFAULT_EFFORT_BY_DEPTH, ...effortByDepth }[
123
+ normalizeDepth(depth)
124
+ ];
125
+ }
@@ -7,9 +7,16 @@
7
7
  * @typedef {import('./review-providers/types.js').Finding} Finding
8
8
  * @typedef {{ id: string, severity: string, provider: string|null,
9
9
  * class: string|null, instances: { file: string, line?: number }[],
10
- * ungrounded?: string, unverified?: string }} HistoryFinding
11
- * @typedef {{ runs: { headSha: string, findings: HistoryFinding[] }[],
10
+ * ungrounded?: string, unverified?: string, carried?: string,
11
+ * title?: string, body?: string, file?: string, line?: number,
12
+ * claim?: object }} HistoryFinding
13
+ * @typedef {{ id: string, status: 'still-open'|'fixed'|'refuted',
14
+ * reason?: string }} EarlierOutcome
15
+ * @typedef {{ runs: { headSha: string, findings: HistoryFinding[],
16
+ * earlierCriticals?: EarlierOutcome[] }[],
12
17
  * overridden: string[], overrideReason?: string }} ReviewHistory
18
+ * @typedef {{ id: string, finding: HistoryFinding, headSha: string,
19
+ * status: 'open'|'fixed'|'refuted'|'overridden', reason?: string }} EarlierCritical
13
20
  */
14
21
 
15
22
  import nodeFs from 'node:fs';
@@ -28,6 +35,8 @@ const KIND = 'story-review-history';
28
35
  const LINE_WINDOW = 10;
29
36
  /** Same bound as the `review-block-overridden` friction signal. */
30
37
  const OVERRIDE_REASON_LIMIT = 500;
38
+ /** A stored CRITICAL body is clipped to this many characters. */
39
+ const BODY_LIMIT = 4000;
31
40
 
32
41
  /**
33
42
  * @param {number} storyId
@@ -86,6 +95,31 @@ function updateReviewHistory(storyId, update, deps = {}) {
86
95
  );
87
96
  }
88
97
 
98
+ /** Keep the set entries of `fields`; an empty string is unset. */
99
+ const present = (fields) =>
100
+ Object.fromEntries(
101
+ Object.entries(fields).filter(([, v]) => v != null && v !== ''),
102
+ );
103
+
104
+ const flags = (f) =>
105
+ present({
106
+ ungrounded: f.ungrounded,
107
+ unverified: f.unverified,
108
+ carried: f.carried,
109
+ });
110
+
111
+ /** What the verifier needs to re-check a CRITICAL without its original run. */
112
+ const criticalContent = (f) =>
113
+ f.severity === 'critical'
114
+ ? present({
115
+ title: f.title,
116
+ body: typeof f.body === 'string' ? f.body.slice(0, BODY_LIMIT) : null,
117
+ file: f.file,
118
+ line: f.line,
119
+ claim: f.claim,
120
+ })
121
+ : {};
122
+
89
123
  /** @param {Finding} f @returns {HistoryFinding} */
90
124
  function toHistoryFinding(f) {
91
125
  return {
@@ -94,27 +128,89 @@ function toHistoryFinding(f) {
94
128
  provider: f.provider ?? null,
95
129
  class: f.class ?? null,
96
130
  instances: findingInstances(f),
97
- ...(f.ungrounded ? { ungrounded: f.ungrounded } : {}),
98
- ...(f.unverified ? { unverified: f.unverified } : {}),
131
+ ...flags(f),
132
+ ...criticalContent(f),
99
133
  };
100
134
  }
101
135
 
102
136
  /**
103
137
  * @param {number} storyId
104
- * @param {{ headSha: string, findings: Finding[] }} run
138
+ * @param {{ headSha: string, findings: Finding[],
139
+ * earlierCriticals?: EarlierOutcome[] }} run
105
140
  * @param {{ config?: object, fsImpl?: typeof nodeFs }} [deps]
106
141
  */
107
- export function appendReviewRun(storyId, { headSha, findings }, deps) {
108
- updateReviewHistory(
109
- storyId,
110
- (h) => ({
111
- ...h,
112
- runs: [...h.runs, { headSha, findings: findings.map(toHistoryFinding) }],
113
- }),
114
- deps,
142
+ export function appendReviewRun(
143
+ storyId,
144
+ { headSha, findings, earlierCriticals },
145
+ deps,
146
+ ) {
147
+ const run = toHistoryRun(headSha, findings, earlierCriticals);
148
+ updateReviewHistory(storyId, (h) => ({ ...h, runs: [...h.runs, run] }), deps);
149
+ }
150
+
151
+ function toHistoryRun(headSha, findings, earlierCriticals) {
152
+ const run = { headSha, findings: findings.map(toHistoryFinding) };
153
+ if (Array.isArray(earlierCriticals)) run.earlierCriticals = earlierCriticals;
154
+ return run;
155
+ }
156
+
157
+ const list = (v) => (Array.isArray(v) ? v : []);
158
+ const RESOLVED = new Set(['fixed', 'refuted']);
159
+
160
+ /** Raised as `critical` and survived grounding and verification. */
161
+ const survived = (f) =>
162
+ f?.severity === 'critical' && !f.unverified && !f.ungrounded;
163
+
164
+ /**
165
+ * Every CRITICAL that survived grounding and verification in some run, in
166
+ * first-raised order, with its current status. A run's `fixed`/`refuted`
167
+ * outcome closes it; surviving again re-opens it; overridden ids end
168
+ * `overridden`. A carried record keeps the head it was first raised at.
169
+ *
170
+ * @param {ReviewHistory} history
171
+ * @returns {EarlierCritical[]}
172
+ */
173
+ export function earlierCriticals(history) {
174
+ const byId = new Map();
175
+ for (const run of list(history?.runs)) {
176
+ list(run?.earlierCriticals).forEach((o) => {
177
+ resolveEntry(byId, o);
178
+ });
179
+ list(run?.findings)
180
+ .filter(survived)
181
+ .forEach((f) => {
182
+ openEntry(byId, f, run.headSha);
183
+ });
184
+ }
185
+ return markOverridden([...byId.values()], list(history?.overridden));
186
+ }
187
+
188
+ /** Overridden ids end `overridden`. */
189
+ function markOverridden(entries, ids) {
190
+ const overridden = new Set(ids);
191
+ return entries.map((e) =>
192
+ overridden.has(e.id) ? { ...e, status: 'overridden' } : e,
115
193
  );
116
194
  }
117
195
 
196
+ /** A run's `fixed`/`refuted` outcome closes an entry. */
197
+ function resolveEntry(byId, outcome) {
198
+ const entry = byId.get(outcome?.id);
199
+ if (!entry || !RESOLVED.has(outcome.status)) return;
200
+ Object.assign(entry, { status: outcome.status, reason: outcome.reason });
201
+ }
202
+
203
+ /** A surviving CRITICAL (re-)opens its entry; carried keeps the first head. */
204
+ function openEntry(byId, finding, headSha) {
205
+ const prev = byId.get(finding.id);
206
+ byId.set(finding.id, {
207
+ id: finding.id,
208
+ finding,
209
+ headSha: finding.carried && prev ? prev.headSha : headSha,
210
+ status: 'open',
211
+ });
212
+ }
213
+
118
214
  /**
119
215
  * @param {number} storyId
120
216
  * @param {string[]} ids - the overridden CRITICALs.
@@ -148,6 +244,19 @@ function overlaps(now, before) {
148
244
  return now.some((a) => before.some((b) => sameLocation(a, b)));
149
245
  }
150
246
 
247
+ /**
248
+ * Whether `finding` is `earlier` raised again: same id, overlapping location.
249
+ *
250
+ * @param {Finding} finding
251
+ * @param {HistoryFinding} earlier
252
+ */
253
+ export function raisedAgain(finding, earlier) {
254
+ return (
255
+ findingId(finding) === earlier?.id &&
256
+ overlaps(findingInstances(finding), earlier.instances ?? [])
257
+ );
258
+ }
259
+
151
260
  /**
152
261
  * Mark each finding an earlier run raised (same id, overlapping location) as
153
262
  * a `repeat`. A repeat of an overridden CRITICAL is downgraded so it does not
@@ -163,13 +272,8 @@ export function markRepeats(findings, history) {
163
272
  );
164
273
  const overridden = new Set(history.overridden);
165
274
  return findings.map((f) => {
166
- const id = findingId(f);
167
- const instances = findingInstances(f);
168
- const seen = earlier.some(
169
- (e) => e?.id === id && overlaps(instances, e.instances ?? []),
170
- );
171
- if (!seen) return f;
172
- if (f.severity === 'critical' && overridden.has(id)) {
275
+ if (!earlier.some((e) => raisedAgain(f, e))) return f;
276
+ if (f.severity === 'critical' && overridden.has(findingId(f))) {
173
277
  return {
174
278
  ...f,
175
279
  severity: 'suggestion',