mandrel 2.104.0 → 2.106.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.
@@ -7,6 +7,7 @@ import { StringDecoder } from 'node:string_decoder';
7
7
 
8
8
  import {
9
9
  groupSpawnOptions,
10
+ spawnSupervised,
10
11
  superviseGroup,
11
12
  TIMEOUT_EXIT_CODE,
12
13
  } from './process-group.js';
@@ -71,13 +72,23 @@ export function streamChild(file, args, opts = {}) {
71
72
  const stdout = createTail(tailBytes);
72
73
  const stderr = createTail(tailBytes);
73
74
  let child;
75
+ let supervisor;
74
76
  try {
75
- child = spawnImpl(file, args, {
76
- ...rest,
77
- ...groupSpawnOptions(),
78
- shell: false,
79
- stdio: ['pipe', 'pipe', 'pipe'],
80
- });
77
+ ({ child, supervisor } = spawnSupervised(
78
+ () =>
79
+ spawnImpl(file, args, {
80
+ ...rest,
81
+ ...groupSpawnOptions(),
82
+ shell: false,
83
+ stdio: ['pipe', 'pipe', 'pipe'],
84
+ }),
85
+ (c) =>
86
+ superviseGroup(c, {
87
+ timeoutMs,
88
+ abortSignal: signal,
89
+ signalOnParentSignal: 'SIGTERM',
90
+ }),
91
+ ));
81
92
  } catch (err) {
82
93
  resolve({
83
94
  status: 1,
@@ -88,11 +99,6 @@ export function streamChild(file, args, opts = {}) {
88
99
  });
89
100
  return;
90
101
  }
91
- const supervisor = superviseGroup(child, {
92
- timeoutMs,
93
- abortSignal: signal,
94
- signalOnParentSignal: 'SIGTERM',
95
- });
96
102
  let spawnError = null;
97
103
  let settled = false;
98
104
  const settle = (code) => {
@@ -8,7 +8,11 @@ import {
8
8
  resolveFullSuiteLockBudget,
9
9
  withFullSuiteLockAsync,
10
10
  } from '../full-suite-lock.js';
11
- import { groupSpawnOptions, TIMEOUT_EXIT_CODE } from '../process-group.js';
11
+ import {
12
+ groupSpawnOptions,
13
+ spawnSupervised,
14
+ TIMEOUT_EXIT_CODE,
15
+ } from '../process-group.js';
12
16
  import { gateSupervision } from '../supervised-suite.js';
13
17
 
14
18
  /**
@@ -87,7 +91,7 @@ function isBiomeNoFilesProcessed(output) {
87
91
  *
88
92
  * @param {string} cmd
89
93
  * @param {string[]} args
90
- * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string>, tolerateNoFilesProcessed?: boolean, fullSuiteLock?: boolean, timeoutMs?: number, lockOptions?: object, onLockEvent?: (event: object) => void, skipIfSatisfied?: () => {status: number}|undefined }} opts
94
+ * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string>, tolerateNoFilesProcessed?: boolean, fullSuiteLock?: boolean, timeoutMs?: number, lockOptions?: object, onLockEvent?: (event: object) => void, skipIfSatisfied?: () => {status: number}|undefined, spawnImpl?: typeof spawn }} opts
91
95
  * @returns {Promise<{ status: number }>}
92
96
  */
93
97
  export function defaultGateRunner(cmd, args, opts = {}) {
@@ -132,11 +136,15 @@ function refusedGateStatus() {
132
136
  */
133
137
  function spawnGate(cmd, args, opts, lock) {
134
138
  const supervision = gateSupervision(opts, lock);
135
- const child = spawnGateChild(cmd, args, opts.cwd, supervision.env);
136
139
  const output = gateOutput(opts);
137
- pipePrefixed(child.stdout, output.prefix, output.tap);
138
- pipePrefixed(child.stderr, output.prefix, output.tap);
139
- const supervisor = supervision.supervise(child, output);
140
+ const { child, supervisor } = spawnSupervised(
141
+ () => spawnGateChild(cmd, args, opts.cwd, supervision.env, opts.spawnImpl),
142
+ (c) => {
143
+ pipePrefixed(c.stdout, output.prefix, output.tap);
144
+ pipePrefixed(c.stderr, output.prefix, output.tap);
145
+ return supervision.supervise(c, output);
146
+ },
147
+ );
140
148
  return new Promise((resolve) => {
141
149
  // 'close', not 'exit': only 'close' waits for both pipes to drain.
142
150
  child.on('close', (code, sig) => {
@@ -162,8 +170,8 @@ function spawnGate(cmd, args, opts, lock) {
162
170
  * @param {string} cwd
163
171
  * @param {Record<string, string>} [env]
164
172
  */
165
- function spawnGateChild(cmd, args, cwd, env) {
166
- return spawn(cmd, args, {
173
+ function spawnGateChild(cmd, args, cwd, env, spawnImpl = spawn) {
174
+ return spawnImpl(cmd, args, {
167
175
  cwd,
168
176
  shell: process.platform === 'win32',
169
177
  stdio: ['ignore', 'pipe', 'pipe'],
@@ -80,11 +80,14 @@ function resolveStoryScope(opts, config) {
80
80
  /**
81
81
  * Run a Story-scope review. `headRef` is required; `baseRef` defaults to
82
82
  * the remote base branch; `commentTargetId` (e.g. a PR number) overrides
83
- * the post target while `ticketId` still labels the header.
83
+ * the post target while `ticketId` still labels the header. `cwd` is the
84
+ * reviewed repository the diff and claim grounding run in; unset, they fall
85
+ * back to `process.cwd()`.
84
86
  *
85
87
  * @param {{
86
88
  * scope?: 'story',
87
89
  * ticketId: number,
90
+ * cwd?: string,
88
91
  * baseRef?: string|null,
89
92
  * headRef?: string|null,
90
93
  * commentTargetId?: number|null,
@@ -144,8 +147,12 @@ function resolveProviderName(codeReviewConfig, reviewProvider) {
144
147
  */
145
148
  function resolveInjectedChangedFiles({ opts, baseRef, headRef }) {
146
149
  if (opts.changedFiles === undefined) {
147
- return computeChangeSet({ baseRef, headRef, gitSpawnFn: opts.gitSpawnFn })
148
- .files;
150
+ return computeChangeSet({
151
+ baseRef,
152
+ headRef,
153
+ cwd: opts.cwd,
154
+ gitSpawnFn: opts.gitSpawnFn,
155
+ }).files;
149
156
  }
150
157
  return Array.isArray(opts.changedFiles) ? opts.changedFiles : null;
151
158
  }
@@ -258,6 +265,24 @@ function resolveCriticalByProvider({ findings, providerName, severity }) {
258
265
  return tally;
259
266
  }
260
267
 
268
+ /** Tally, halt verdict and per-provider criticals of grounded findings. */
269
+ function scoreFindings(findings, providerName) {
270
+ const severity = countBySeverity(findings);
271
+ const halted = hasSurvivingCritical(severity);
272
+ return {
273
+ severity,
274
+ halted,
275
+ criticalByProvider: resolveCriticalByProvider({
276
+ findings,
277
+ providerName,
278
+ severity,
279
+ }),
280
+ blockerReason: halted
281
+ ? `code-review reported ${severity.critical} critical blocker(s)`
282
+ : null,
283
+ };
284
+ }
285
+
261
286
  async function executeReviewPipeline({ opts, config, envelope }) {
262
287
  const {
263
288
  provider,
@@ -300,23 +325,15 @@ async function executeReviewPipeline({ opts, config, envelope }) {
300
325
  );
301
326
 
302
327
  // Degraded gates ride beside the findings, never inside them.
303
- const degradations = await collectProviderDegradations(
304
- reviewProvider,
305
- logger,
306
- );
307
- const findings = groundFindings({
328
+ const { findings, degradations } = groundFindings({
308
329
  findings: rawFindings,
309
330
  headRef,
310
- degradations,
331
+ baseRef,
332
+ cwd: opts.cwd,
333
+ degradations: await collectProviderDegradations(reviewProvider, logger),
311
334
  gitSpawnFn: opts.gitSpawnFn,
312
335
  });
313
- const severity = countBySeverity(findings);
314
- const halted = hasSurvivingCritical(severity);
315
- const criticalByProvider = resolveCriticalByProvider({
316
- findings,
317
- providerName,
318
- severity,
319
- });
336
+ const scored = scoreFindings(findings, providerName);
320
337
  const report = renderFindingsFn({
321
338
  scope,
322
339
  ticketId,
@@ -338,19 +355,17 @@ async function executeReviewPipeline({ opts, config, envelope }) {
338
355
 
339
356
  return {
340
357
  status: 'ok',
341
- severity,
358
+ severity: scored.severity,
342
359
  findings,
343
360
  providerName,
344
361
  report,
345
362
  posted,
346
363
  postedCommentId,
347
364
  commentTargetId,
348
- halted,
349
- criticalByProvider,
365
+ halted: scored.halted,
366
+ criticalByProvider: scored.criticalByProvider,
350
367
  ...degradationEnvelope(degradations),
351
- blockerReason: halted
352
- ? `code-review reported ${severity.critical} critical blocker(s)`
353
- : null,
368
+ blockerReason: scored.blockerReason,
354
369
  };
355
370
  }
356
371
 
@@ -12,7 +12,8 @@ import { gitSpawn } from '../../git-utils.js';
12
12
  import { isObject } from '../../json-utils.js';
13
13
 
14
14
  const TRUNCATED_CONTEXT = 'reviewed-with-truncated-context';
15
- const CLAIM_KINDS = ['path-absent', 'symbol-referenced'];
15
+ const CLAIM_KINDS = ['path-absent', 'symbol-referenced', 'file-unchanged'];
16
+ const PATH_KINDS = new Set(['path-absent', 'file-unchanged']);
16
17
 
17
18
  /** The optional `claim` property of the Claude findings schema. */
18
19
  export const CLAIM_SCHEMA = {
@@ -51,7 +52,7 @@ export function buildClaim(raw) {
51
52
  if (!isObject(raw)) return null;
52
53
  const path = nonBlank(raw.path);
53
54
  const symbol = nonBlank(raw.symbol);
54
- if (raw.kind === 'path-absent' && path) return { kind: raw.kind, path };
55
+ if (PATH_KINDS.has(raw.kind)) return path ? { kind: raw.kind, path } : null;
55
56
  if (raw.kind !== 'symbol-referenced' || !symbol) return null;
56
57
  return path ? { kind: raw.kind, symbol, path } : { kind: raw.kind, symbol };
57
58
  }
@@ -72,7 +73,7 @@ export function groundingNotes(finding) {
72
73
  }
73
74
 
74
75
  /** @returns {string|null} evidence when the path exists at `headRef`. */
75
- function refutePathAbsent(claim, headRef, git) {
76
+ function refutePathAbsent(claim, { headRef }, git) {
76
77
  const result = git('cat-file', '-e', `${headRef}:${claim.path}`);
77
78
  return result?.status === 0 ? `git cat-file found ${claim.path}` : null;
78
79
  }
@@ -101,7 +102,7 @@ function isDeclaration(hit, claim) {
101
102
  }
102
103
 
103
104
  /** @returns {string|null} evidence when every hit is the declaration. */
104
- function refuteSymbolReferenced(claim, headRef, git) {
105
+ function refuteSymbolReferenced(claim, { headRef }, git) {
105
106
  const result = git(
106
107
  'grep',
107
108
  '-n',
@@ -123,18 +124,32 @@ function refuteSymbolReferenced(claim, headRef, git) {
123
124
  : 'git grep found no references';
124
125
  }
125
126
 
127
+ /**
128
+ * `git diff --quiet` exits 1 only when the path differs across the range; 0,
129
+ * any other status or no base proves nothing.
130
+ *
131
+ * @returns {string|null} evidence when the path changed in base...head.
132
+ */
133
+ function refuteFileUnchanged(claim, { baseRef, headRef }, git) {
134
+ const range = `${baseRef}...${headRef}`;
135
+ const changed =
136
+ baseRef && git('diff', '--quiet', range, '--', claim.path)?.status === 1;
137
+ return changed ? `git diff ${range} changes ${claim.path}` : null;
138
+ }
139
+
126
140
  const REFUTERS = {
127
141
  'path-absent': refutePathAbsent,
128
142
  'symbol-referenced': refuteSymbolReferenced,
143
+ 'file-unchanged': refuteFileUnchanged,
129
144
  };
130
145
 
131
146
  /** @returns {Finding} */
132
- function groundFinding(finding, headRef, git) {
133
- const refute = REFUTERS[finding?.claim?.kind];
134
- if (finding?.severity !== 'critical' || !refute) return finding;
147
+ function groundFinding(finding, refs, git) {
148
+ if (!isGroundable(finding)) return finding;
149
+ const refute = REFUTERS[finding.claim.kind];
135
150
  let evidence = null;
136
151
  try {
137
- evidence = refute(finding.claim, headRef, git);
152
+ evidence = refute(finding.claim, refs, git);
138
153
  } catch {
139
154
  evidence = null;
140
155
  }
@@ -142,6 +157,40 @@ function groundFinding(finding, headRef, git) {
142
157
  return { ...finding, severity: 'suggestion', ungrounded: evidence };
143
158
  }
144
159
 
160
+ const isGroundable = (finding) =>
161
+ finding?.severity === 'critical' && Boolean(REFUTERS[finding?.claim?.kind]);
162
+
163
+ function headResolves(git, headRef) {
164
+ try {
165
+ return (
166
+ git('rev-parse', '--verify', '--quiet', `${headRef}^{commit}`)?.status ===
167
+ 0
168
+ );
169
+ } catch {
170
+ return false;
171
+ }
172
+ }
173
+
174
+ /**
175
+ * `cat-file` exits 128 for a missing path and an unknown ref alike, so the
176
+ * head is checked on its own: an unresolvable head means every claim stays
177
+ * unrefuted for want of a repository, and that is reported, not silent.
178
+ * Probes only when some finding is groundable.
179
+ *
180
+ * @returns {import('./degraded-gates.js').GateDegradation[]}
181
+ */
182
+ function headDegradations({ findings, headRef, cwd, git }) {
183
+ if (!findings.some(isGroundable) || headResolves(git, headRef)) return [];
184
+ return [
185
+ {
186
+ tool: 'claim-grounding',
187
+ gate: 'claim-grounding',
188
+ surface: 'head-ref',
189
+ reason: `head ${headRef} not resolvable in ${cwd}`,
190
+ },
191
+ ];
192
+ }
193
+
145
194
  /** Names a degradation reason carries, split on its list punctuation. */
146
195
  function reasonTokens(degradations) {
147
196
  return new Set(
@@ -155,29 +204,51 @@ function annotateContext(finding, tokens) {
155
204
  return { ...finding, context: TRUNCATED_CONTEXT };
156
205
  }
157
206
 
207
+ function groundEach(findings, refs, git, tokens) {
208
+ return findings.map((finding) => {
209
+ const grounded = groundFinding(finding, refs, git);
210
+ return grounded && tokens.size > 0
211
+ ? annotateContext(grounded, tokens)
212
+ : grounded;
213
+ });
214
+ }
215
+
158
216
  /**
217
+ * Ground every finding in `cwd`, the reviewed repository; `baseRef` is
218
+ * needed only to refute a `file-unchanged` claim. `degradations`
219
+ * comes back with the head check's record appended when the head does not
220
+ * resolve there.
221
+ *
159
222
  * @param {{
160
223
  * findings: Finding[],
161
224
  * headRef: string,
225
+ * baseRef?: string|null,
162
226
  * degradations?: ReadonlyArray<{ reason: string }>,
163
227
  * cwd?: string,
164
228
  * gitSpawnFn?: typeof gitSpawn,
165
229
  * }} args
166
- * @returns {Finding[]}
230
+ * @returns {{ findings: Finding[], degradations: Array<{ reason: string }> }}
167
231
  */
168
232
  export function groundFindings({
169
233
  findings,
170
234
  headRef,
235
+ baseRef,
171
236
  degradations = [],
172
237
  cwd = process.cwd(),
173
238
  gitSpawnFn = gitSpawn,
174
239
  }) {
175
240
  const git = (...args) => gitSpawnFn(cwd, ...args);
176
- const tokens = reasonTokens(degradations);
177
- return findings.map((finding) => {
178
- const grounded = groundFinding(finding, headRef, git);
179
- return grounded && tokens.size > 0
180
- ? annotateContext(grounded, tokens)
181
- : grounded;
182
- });
241
+ const all = [
242
+ ...degradations,
243
+ ...headDegradations({ findings, headRef, cwd, git }),
244
+ ];
245
+ return {
246
+ findings: groundEach(
247
+ findings,
248
+ { baseRef, headRef },
249
+ git,
250
+ reasonTokens(all),
251
+ ),
252
+ degradations: all,
253
+ };
183
254
  }
@@ -13,7 +13,9 @@
13
13
  * review with no verdict records one degraded gate via `getDegradations()`
14
14
  * and returns no findings, so "never ran" cannot read as "found nothing".
15
15
  * A diff over the cap is reviewed chunk by chunk (file-aligned, sequential,
16
- * findings merged); what went unchecked — a truncated file, files past the
16
+ * findings merged). Source sections pack before tests and docs, and every
17
+ * chunk is told it is a slice and handed the whole changed-file manifest so
18
+ * a file changed in another chunk never reads as unchanged. What went unchecked — a truncated file, files past the
17
19
  * chunk bound, a chunk with no verdict, a capped `<callers>` block — is
18
20
  * recorded beside the findings, naming the files.
19
21
  *
@@ -77,17 +79,50 @@ const PROMPT_HEAD =
77
79
  'input, command or test that exposes it). A `shortcut:` comment naming ' +
78
80
  'its ceiling and trigger is a decision, not a finding, unless this diff ' +
79
81
  'itself crosses the ceiling.\n\n' +
80
- 'The diff below is authoritative — files on disk may not reflect it. ' +
82
+ '{scopeNote}' +
81
83
  'Answer with a JSON object of this exact shape, no prose around it:\n\n' +
82
84
  '{"findings":[{"title":"...","body":"Why it is wrong: ... How to show it ' +
83
85
  'fails: ...","file":"...","line":1,"category":"bug","claim":null}]}\n\n' +
84
86
  'Set `claim` when the problem rests on a checkable fact: ' +
85
87
  '{"kind":"path-absent","path":"<file>"} when a file the change needs is ' +
86
88
  'missing, or {"kind":"symbol-referenced","symbol":"<name>","path":"<its ' +
87
- 'definition file>"} when a removed or renamed symbol still has callers. ' +
88
- 'Otherwise leave it null.\n\n' +
89
+ 'definition file>"} when a removed or renamed symbol still has callers, ' +
90
+ 'or {"kind":"file-unchanged","path":"<file>"} when the problem is that ' +
91
+ 'another file was not updated. Otherwise leave it null.\n\n' +
89
92
  'Emit {"findings":[]} if there is nothing you would block the merge for.\n\n';
90
93
 
94
+ const WHOLE_DIFF_NOTE =
95
+ 'The diff below is authoritative — files on disk may not reflect it. ';
96
+
97
+ /** @param {number} index - 1-based. @param {number} total */
98
+ const sliceNote = (index, total) =>
99
+ `The diff below is chunk ${index} of ${total} of one change, split for ` +
100
+ 'size; files on disk may not reflect it. Every file in <manifest> is ' +
101
+ 'changed by this change, even when its hunks sit in another chunk: never ' +
102
+ 'report a listed file as unchanged or missing, and set a file-unchanged ' +
103
+ 'claim on any problem that rests on another file not being updated. ';
104
+
105
+ const TEST_PATH =
106
+ /(?:^|\/)(?:__tests__|tests?|e2e|features)\/|\.(?:test|spec)\.|\.feature$/;
107
+ const DOCS_PATH = /(?:^|\/)docs\/|\.(?:md|mdx|txt)$/i;
108
+
109
+ /** Pack order: 0 source, 1 tests, 2 docs — the chunk bound falls on the last. */
110
+ function tierOf(file) {
111
+ if (TEST_PATH.test(file)) return 1;
112
+ return DOCS_PATH.test(file) ? 2 : 0;
113
+ }
114
+
115
+ const compareText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
116
+
117
+ /** Tier, then directory, then path. */
118
+ function compareSections(a, b) {
119
+ return (
120
+ a.tier - b.tier ||
121
+ compareText(path.posix.dirname(a.file), path.posix.dirname(b.file)) ||
122
+ compareText(a.file, b.file)
123
+ );
124
+ }
125
+
91
126
  /**
92
127
  * Split a diff at `diff --git` boundaries into per-file sections.
93
128
  *
@@ -107,7 +142,18 @@ function splitSections(diff) {
107
142
  }
108
143
 
109
144
  /**
110
- * First-fit, in diff order, into chunks of at most `budget` characters; a
145
+ * The first chunk with room for `section` at or after the last chunk holding
146
+ * an earlier tier, so no test or doc sits in a chunk ahead of a source section.
147
+ */
148
+ function openChunk(chunks, section, budget) {
149
+ const floor = chunks.findLastIndex((c) => c.tier < section.tier);
150
+ return chunks
151
+ .slice(Math.max(floor, 0))
152
+ .find((c) => c.size + section.text.length <= budget);
153
+ }
154
+
155
+ /**
156
+ * First-fit, tier by tier, into chunks of at most `budget` characters; a
111
157
  * section over the budget gets a chunk of its own (truncated when reviewed).
112
158
  *
113
159
  * @param {{ file: string, text: string }[]} sections
@@ -115,14 +161,17 @@ function splitSections(diff) {
115
161
  */
116
162
  function packChunks(sections, budget) {
117
163
  const chunks = [];
118
- for (const section of sections) {
164
+ const ordered = sections
165
+ .map((s) => ({ ...s, tier: tierOf(s.file) }))
166
+ .sort(compareSections);
167
+ for (const section of ordered) {
119
168
  const size = section.text.length;
120
- const open = chunks.find((c) => c.size + size <= budget);
169
+ const open = openChunk(chunks, section, budget);
121
170
  if (open) {
122
171
  open.sections.push(section);
123
172
  open.size += size;
124
173
  } else {
125
- chunks.push({ sections: [section], size });
174
+ chunks.push({ sections: [section], size, tier: section.tier });
126
175
  }
127
176
  }
128
177
  return chunks;
@@ -144,15 +193,23 @@ function dedupeFindings(findings) {
144
193
  * @param {string} diff
145
194
  * @param {string} callers - the `<callers>` section, or '' below `deep`.
146
195
  * @param {number} [cap]
196
+ * @param {string} [scope] - the slice note and `<manifest>` of a chunk.
147
197
  * @returns {string}
148
198
  */
149
- function buildPrompt(input, diff, callers, cap = MAX_DIFF_CHARS) {
199
+ function buildPrompt(
200
+ input,
201
+ diff,
202
+ callers,
203
+ cap = MAX_DIFF_CHARS,
204
+ scope = WHOLE_DIFF_NOTE,
205
+ ) {
150
206
  const truncated = diff.length > cap;
151
207
  const body = truncated ? diff.slice(0, cap) : diff;
152
208
  const note = truncated ? `\n[diff truncated at ${cap} characters]\n` : '';
153
209
  const head = PROMPT_HEAD.replace('{baseRef}', input.baseRef)
154
210
  .replace('{headRef}', input.headRef)
155
211
  .replace('{ticketId}', String(input.ticketId))
212
+ .replace('{scopeNote}', scope)
156
213
  .replace('{depthDirective}', renderDepthDirective(input.depth));
157
214
  return `${head}<diff>\n${body}${note}\n</diff>\n${callers}`;
158
215
  }
@@ -288,10 +345,23 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
288
345
  return [];
289
346
  }
290
347
 
291
- /** The `<callers>` block rides every chunk, so it comes out of the budget. */
348
+ /**
349
+ * The `<callers>` block, the slice note and the manifest ride every chunk,
350
+ * so they come out of the budget; chunk numbers are one digit, so the
351
+ * note's length is fixed before packing.
352
+ */
292
353
  async function reviewInChunks(input, text, callers) {
293
- const budget = MAX_DIFF_CHARS - callers.length;
294
- const chunks = packChunks(splitSections(text), budget);
354
+ const sections = splitSections(text).filter((s) => s.text.length > 0);
355
+ const files = sections
356
+ .map((s) => s.file)
357
+ .filter((file) => file !== '(unnamed)');
358
+ const manifest = `<manifest>\n${files.join('\n')}\n</manifest>\n`;
359
+ const budget =
360
+ MAX_DIFF_CHARS -
361
+ callers.length -
362
+ manifest.length -
363
+ sliceNote(MAX_REVIEW_CHUNKS, MAX_REVIEW_CHUNKS).length;
364
+ const chunks = packChunks(sections, budget);
295
365
  const overflow = chunks
296
366
  .splice(MAX_REVIEW_CHUNKS)
297
367
  .flatMap((c) => c.sections.map((s) => s.file));
@@ -302,7 +372,7 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
302
372
  );
303
373
  }
304
374
  const findings = [];
305
- for (const chunk of chunks) {
375
+ for (const [index, chunk] of chunks.entries()) {
306
376
  const files = chunk.sections.map((s) => s.file).join(', ');
307
377
  if (chunk.size > budget) {
308
378
  noteDegradation(
@@ -315,6 +385,7 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
315
385
  chunk.sections.map((s) => s.text).join(''),
316
386
  callers,
317
387
  budget,
388
+ sliceNote(index + 1, chunks.length) + manifest,
318
389
  );
319
390
  const verdict = await reviewInTempDir(prompt, runDeps);
320
391
  if ('reason' in verdict) {
@@ -17,8 +17,8 @@
17
17
  * @property {string=} provider - Chain entry that raised it.
18
18
  *
19
19
  * @typedef {object} FindingClaim
20
- * @property {'path-absent'|'symbol-referenced'} kind
21
- * @property {string=} path - Absent path, or the symbol's definition file.
20
+ * @property {'path-absent'|'symbol-referenced'|'file-unchanged'} kind
21
+ * @property {string=} path - Absent or unchanged path, or the symbol's definition file.
22
22
  * @property {string=} symbol
23
23
  *
24
24
  * @typedef {'story'} ReviewScope
@@ -129,6 +129,7 @@ export async function computeStoryScopeReview({
129
129
  );
130
130
  const result = await runStoryReviewCore({
131
131
  storyId,
132
+ cwd,
132
133
  baseRef: base.ref,
133
134
  headRef,
134
135
  commentTargetId,
@@ -7,6 +7,11 @@ import { gitSpawn } from '../../../git-utils.js';
7
7
  import { computeChangeSet } from '../../change-set.js';
8
8
  import { runCodeReview } from '../../code-review.js';
9
9
 
10
+ const progressLogger = (progress, tag) => ({
11
+ info: (m) => progress(tag, m),
12
+ warn: (m) => progress(tag, `⚠️ ${m}`),
13
+ });
14
+
10
15
  /**
11
16
  * Run `runCodeReview` over one change set and return the review result.
12
17
  * Throws propagate; the caller picks the advisory posture. Review depth is
@@ -18,8 +23,12 @@ import { runCodeReview } from '../../code-review.js';
18
23
  * commit lands in between. An unenumerable diff injects `null` ("already
19
24
  * tried"), which the review honours without re-spawning git.
20
25
  *
26
+ * `cwd` is the reviewed repository: both the diff and claim grounding run
27
+ * there, never in the process cwd.
28
+ *
21
29
  * @param {{
22
30
  * storyId: number|string,
31
+ * cwd?: string,
23
32
  * baseRef: string,
24
33
  * headRef: string,
25
34
  * commentTargetId?: number|null,
@@ -35,6 +44,7 @@ import { runCodeReview } from '../../code-review.js';
35
44
  */
36
45
  export async function runStoryReviewCore({
37
46
  storyId,
47
+ cwd,
38
48
  baseRef,
39
49
  headRef,
40
50
  commentTargetId = null,
@@ -45,20 +55,18 @@ export async function runStoryReviewCore({
45
55
  computeChangeSetFn = computeChangeSet,
46
56
  runCodeReviewFn = runCodeReview,
47
57
  }) {
48
- const changeSet = computeChangeSetFn({ baseRef, headRef, gitSpawnFn });
58
+ const changeSet = computeChangeSetFn({ baseRef, headRef, cwd, gitSpawnFn });
49
59
 
50
60
  const opts = {
51
61
  scope: 'story',
52
62
  ticketId: Number(storyId),
63
+ cwd,
53
64
  baseRef,
54
65
  headRef,
55
66
  provider,
56
67
  changedFiles: changeSet.files,
57
68
  gitSpawnFn,
58
- logger: {
59
- info: (m) => progress(progressTag, m),
60
- warn: (m) => progress(progressTag, `⚠️ ${m}`),
61
- },
69
+ logger: progressLogger(progress, progressTag),
62
70
  };
63
71
  if (commentTargetId != null) {
64
72
  opts.commentTargetId = commentTargetId;
@@ -92,6 +92,25 @@ function stopForwarding() {
92
92
  detach?.();
93
93
  }
94
94
 
95
+ function disarmIfIdle() {
96
+ if (supervised.size === 0) stopForwarding();
97
+ }
98
+
99
+ /**
100
+ * Spawn and supervise with forwarding armed first: a signal landing
101
+ * between the two is queued until this synchronous span ends, by when the
102
+ * child is registered and its group is killed. A throwing spawn disarms.
103
+ */
104
+ export function spawnSupervised(spawnChild, supervise) {
105
+ startForwarding(process);
106
+ try {
107
+ const child = spawnChild();
108
+ return { child, supervisor: supervise(child) };
109
+ } finally {
110
+ disarmIfIdle();
111
+ }
112
+ }
113
+
95
114
  /**
96
115
  * Kill the group on timeout, abort or parent signal; `release()` on exit.
97
116
  *
@@ -137,7 +156,7 @@ export function superviseGroup(
137
156
  if (timer) clearTimeout(timer);
138
157
  abortSignal?.removeEventListener('abort', onAbort);
139
158
  supervised.delete(child);
140
- if (supervised.size === 0) stopForwarding();
159
+ disarmIfIdle();
141
160
  },
142
161
  };
143
162
  }
@@ -13,6 +13,7 @@ import path from 'node:path';
13
13
  import {
14
14
  groupSpawnOptions,
15
15
  killProcessGroup,
16
+ spawnSupervised,
16
17
  superviseGroup,
17
18
  TIMEOUT_EXIT_CODE,
18
19
  } from './process-group.js';
@@ -198,17 +199,17 @@ export function runSupervisedSuite(opts) {
198
199
  const { cmd, args, cwd, env = {}, spawnImpl = spawn } = opts;
199
200
  const handshake = suiteReadyHandshake();
200
201
  return new Promise((resolve) => {
201
- const child = spawnImpl(cmd, args, {
202
- cwd,
203
- env: { ...process.env, ...env, ...handshake.env },
204
- stdio: 'inherit',
205
- shell: process.platform === 'win32',
206
- ...groupSpawnOptions(),
207
- });
208
- const supervisor = superviseSuite(child, {
209
- ...opts,
210
- readyFile: handshake.file,
211
- });
202
+ const { child, supervisor } = spawnSupervised(
203
+ () =>
204
+ spawnImpl(cmd, args, {
205
+ cwd,
206
+ env: { ...process.env, ...env, ...handshake.env },
207
+ stdio: 'inherit',
208
+ shell: process.platform === 'win32',
209
+ ...groupSpawnOptions(),
210
+ }),
211
+ (c) => superviseSuite(c, { ...opts, readyFile: handshake.file }),
212
+ );
212
213
  let settled = false;
213
214
  const settle = (code) => {
214
215
  if (settled) return;
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,25 @@ All notable changes to this project will be documented in this file.
15
15
  -->
16
16
  <!-- markdownlint-disable-file MD004 MD012 MD037 -->
17
17
 
18
+ ## [2.106.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.105.0...mandrel-v2.106.0) (2026-10-26)
19
+
20
+
21
+ ### Added
22
+
23
+ * held code review: tell each chunk it is a slice, ground "file unchanged" claims, and pack source before tests ([#5912](https://github.com/dsj1984/mandrel/issues/5912)) ([#5914](https://github.com/dsj1984/mandrel/issues/5914)) ([4a86123](https://github.com/dsj1984/mandrel/commit/4a8612322467cdd8cc8fa70f0081f59e558d8b81))
24
+
25
+
26
+ ### Fixed
27
+
28
+ * process groups: arm parent-signal forwarding before spawning, so a SIGTERM during spawn never leaks the child's group ([#5913](https://github.com/dsj1984/mandrel/issues/5913)) ([#5916](https://github.com/dsj1984/mandrel/issues/5916)) ([87201fe](https://github.com/dsj1984/mandrel/commit/87201fe15038c5f236fc6c8084a0791ad5254719))
29
+
30
+ ## [2.105.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.104.0...mandrel-v2.105.0) (2026-10-26)
31
+
32
+
33
+ ### Fixed
34
+
35
+ * ground held-review claims in the reviewed repository's cwd, not the process cwd ([#5909](https://github.com/dsj1984/mandrel/issues/5909)) ([#5910](https://github.com/dsj1984/mandrel/issues/5910)) ([a86c601](https://github.com/dsj1984/mandrel/commit/a86c60138abc68ed3ec9c6ffd332cc4d98c5a37c))
36
+
18
37
  ## [2.104.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.103.0...mandrel-v2.104.0) (2026-10-25)
19
38
 
20
39
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.104.0",
3
+ "version": "2.106.0",
4
4
  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
5
5
  "files": [
6
6
  ".agents/",