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
@@ -0,0 +1,169 @@
1
+ /**
2
+ * handoff-rescore.js — the handoff runs close's own duplication re-score
3
+ * before any credit, so close's later re-score over the same tree no-ops;
4
+ * and names the duplication rows a branch raised in a post-capture finding.
5
+ */
6
+
7
+ import fs from 'node:fs';
8
+ import path from 'node:path';
9
+
10
+ import { getQuality } from '../config-resolver.js';
11
+ import { DEFAULT_BASELINE_REL_PATH } from './story-close/duplication-close-rescore.js';
12
+
13
+ /** Re-score reasons that settle `skipped`; every other reason is an error. */
14
+ const SKIP_REASONS = new Set(['gate-disabled', 'no-changed-files']);
15
+
16
+ const pct = (v) => (v === null || v === undefined ? 'none' : `${v}%`);
17
+
18
+ /**
19
+ * @param {Array<{ path: string, before: number|null, after: number|null }>} moved
20
+ * @returns {string}
21
+ */
22
+ function describeMoved(moved) {
23
+ return moved
24
+ .map((m) => `${m.path} ${pct(m.before)} → ${pct(m.after)}`)
25
+ .join(', ');
26
+ }
27
+
28
+ /** @returns {{ outcome: string, detail: string }} */
29
+ function settle(ctx, result, readHead) {
30
+ if (result?.committed) {
31
+ ctx.head = readHead() ?? ctx.head;
32
+ return {
33
+ outcome: 'ran',
34
+ detail: `re-scored ${describeMoved(result.moved ?? [])}; committed untagged ${result.sha}`,
35
+ };
36
+ }
37
+ if (result?.reason === 'unchanged') {
38
+ return { outcome: 'ran', detail: 'unchanged' };
39
+ }
40
+ if (SKIP_REASONS.has(result?.reason)) {
41
+ return { outcome: 'skipped', detail: result.reason };
42
+ }
43
+ return { outcome: 'error', detail: result?.reason ?? 'no result' };
44
+ }
45
+
46
+ /**
47
+ * Run the re-score once per HEAD; best-effort, it never stops the run. An
48
+ * `error` records nothing, so a re-run retries.
49
+ *
50
+ * @param {object} ctx the handoff context; `ctx.head` moves on a commit and
51
+ * `ctx.runDuplicationRescore` is close's `runDuplicationCloseRescore`.
52
+ * @param {() => string|null} readHead
53
+ * @returns {Promise<{ outcome: string, detail: string }>}
54
+ */
55
+ export async function rescoreDuplication(ctx, readHead) {
56
+ const prior = ctx.state.duplicationRescore;
57
+ if (prior?.head === ctx.head) {
58
+ return {
59
+ outcome: 'skipped',
60
+ detail: `already re-scored at ${ctx.head.slice(0, 12)}`,
61
+ };
62
+ }
63
+ const log = (m) => ctx.progress('duplication-rescore', m);
64
+ let result;
65
+ try {
66
+ result = await ctx.runDuplicationRescore({
67
+ cwd: ctx.cwd,
68
+ worktreePath: ctx.cwd,
69
+ storyId: ctx.storyId,
70
+ baseBranch: ctx.baseBranch,
71
+ storyBranch: ctx.branch,
72
+ config: ctx.config,
73
+ logger: { info: log, warn: log },
74
+ });
75
+ } catch (err) {
76
+ return { outcome: 'error', detail: `threw: ${err?.message ?? err}` };
77
+ }
78
+ const settled = settle(ctx, result, readHead);
79
+ if (settled.outcome !== 'error') {
80
+ ctx.state.duplicationRescore = {
81
+ head: ctx.head,
82
+ partners: result?.partners ?? {},
83
+ };
84
+ }
85
+ return settled;
86
+ }
87
+
88
+ /** @returns {string} the configured duplication baseline path. */
89
+ function baselineRelPath(config) {
90
+ try {
91
+ return (
92
+ getQuality(config)?.gates?.duplication?.baselinePath ??
93
+ DEFAULT_BASELINE_REL_PATH
94
+ );
95
+ } catch {
96
+ return DEFAULT_BASELINE_REL_PATH;
97
+ }
98
+ }
99
+
100
+ /** Path → percentage; `null` on any read or parse failure. */
101
+ function rowsOf(text) {
102
+ try {
103
+ const rows = JSON.parse(text)?.rows;
104
+ if (!Array.isArray(rows)) return null;
105
+ return new Map(rows.map((r) => [r?.path, r?.percentage ?? null]));
106
+ } catch {
107
+ return null;
108
+ }
109
+ }
110
+
111
+ /**
112
+ * The duplication rows the worktree's baseline raised over `baselineRef`,
113
+ * each with its recorded clone partners. Descriptive only: check-baselines
114
+ * stays the verdict, so an unreadable side yields `[]`.
115
+ *
116
+ * @param {object} ctx the handoff context.
117
+ * @param {{ baselineRef?: string, limit: number, readFile?: (p: string) => string }} opts
118
+ * @returns {string[]}
119
+ */
120
+ function raisedDuplicationRows(
121
+ ctx,
122
+ {
123
+ baselineRef = `origin/${ctx.baseBranch}`,
124
+ limit,
125
+ readFile = (p) => fs.readFileSync(p, 'utf8'),
126
+ },
127
+ ) {
128
+ const relPath = baselineRelPath(ctx.config);
129
+ const base = ctx.git(ctx.cwd, 'show', `${baselineRef}:${relPath}`);
130
+ const baseRows = base?.status === 0 ? rowsOf(base.stdout ?? '') : null;
131
+ let headRows = null;
132
+ try {
133
+ headRows = rowsOf(readFile(path.resolve(ctx.cwd, relPath)));
134
+ } catch {
135
+ headRows = null;
136
+ }
137
+ if (!baseRows || !headRows) return [];
138
+ const partners = ctx.state.duplicationRescore?.partners ?? {};
139
+ const lines = [];
140
+ for (const [file, head] of headRows) {
141
+ const before = baseRows.get(file) ?? null;
142
+ if (head === null || (before !== null && head <= before)) continue;
143
+ const clones = partners[file]?.length
144
+ ? ` (clones: ${partners[file].join(', ')})`
145
+ : '';
146
+ lines.push(`${file} ${pct(before)} → ${pct(head)}${clones}`);
147
+ }
148
+ return lines.slice(0, limit);
149
+ }
150
+
151
+ /**
152
+ * The post-capture finding's suffix naming raised duplication rows; `''` for
153
+ * a gate that does not score duplication or when nothing was raised.
154
+ *
155
+ * @param {object} ctx
156
+ * @param {{ scoresDuplication?: boolean, baselineRef?: string }} failed
157
+ * @param {number} limit
158
+ * @returns {string}
159
+ */
160
+ export function raisedDuplicationSuffix(ctx, failed, limit) {
161
+ if (!failed.scoresDuplication) return '';
162
+ const raised = raisedDuplicationRows(ctx, {
163
+ baselineRef: failed.baselineRef,
164
+ limit,
165
+ });
166
+ return raised.length > 0
167
+ ? `; raised duplication rows: ${raised.join('; ')}`
168
+ : '';
169
+ }
@@ -0,0 +1,45 @@
1
+ /**
2
+ * handoff-suite-of-record.js — the credited-run step under
3
+ * `coverage.suiteOfRecord: "ci"`, decided from config before any lock or spawn.
4
+ */
5
+
6
+ import { suiteOfRecord } from '../close-validation/gates.js';
7
+ import {
8
+ COVERAGE_DEFERRED_REASONS,
9
+ deferCoverage,
10
+ } from '../coverage-deferral.js';
11
+
12
+ const UNDECLARED_DETAIL =
13
+ 'delivery.quality.gates.coverage.suiteOfRecord is "ci" but delivery.quality.gates.coverage.ciRatchetCheck is unset — name the CI check that runs coverage-ratchet.js, or set suiteOfRecord to "local"';
14
+
15
+ /**
16
+ * The capture depositor's step under the `ci` posture: deferred to CI, or
17
+ * `blocked` when no `ciRatchetCheck` would take the ratchet. `null` when the
18
+ * posture is off or the depositor is `test`.
19
+ *
20
+ * @param {{ config: object, depositor: string, head: string, state: object }} ctx
21
+ * @param {string} name
22
+ * @returns {object|null}
23
+ */
24
+ export function settleSuiteOfRecord(ctx, name) {
25
+ const { ci, ciRatchetCheck } = suiteOfRecord(ctx.config);
26
+ if (!ci || ctx.depositor !== 'coverage-capture') return null;
27
+ const extra = { depositor: ctx.depositor };
28
+ if (!ciRatchetCheck) {
29
+ return {
30
+ name,
31
+ outcome: 'failed',
32
+ detail: UNDECLARED_DETAIL,
33
+ reason: 'ci-ratchet-undeclared',
34
+ stop: 'blocked',
35
+ ...extra,
36
+ };
37
+ }
38
+ deferCoverage(ctx.state, ctx.head, COVERAGE_DEFERRED_REASONS.suiteOfRecordCi);
39
+ return {
40
+ name,
41
+ outcome: 'deferred',
42
+ detail: `coverage deferred to CI (suiteOfRecord: ci, ratchet check "${ciRatchetCheck}") — nothing spawned and no credit was deposited`,
43
+ ...extra,
44
+ };
45
+ }
@@ -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
+ }