mandrel 2.105.0 → 2.107.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 (39) hide show
  1. package/.agents/docs/configuration.md +3 -0
  2. package/.agents/schemas/agentrc.schema.json +38 -0
  3. package/.agents/schemas/story-deliver-terminal.schema.json +4 -0
  4. package/.agents/scripts/lib/audit-suite/selector.js +13 -5
  5. package/.agents/scripts/lib/audit-suite/sensitive-paths.js +39 -0
  6. package/.agents/scripts/lib/child-stream.js +17 -11
  7. package/.agents/scripts/lib/close-validation/process.js +16 -8
  8. package/.agents/scripts/lib/config-settings-schema-quality.js +31 -0
  9. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  10. package/.agents/scripts/lib/observability/metrics-ledger.js +1 -1
  11. package/.agents/scripts/lib/observability/review-dispositions.js +208 -0
  12. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  13. package/.agents/scripts/lib/orchestration/code-review.js +77 -12
  14. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -0
  15. package/.agents/scripts/lib/orchestration/review-depth.js +9 -3
  16. package/.agents/scripts/lib/orchestration/review-history.js +182 -0
  17. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +22 -2
  18. package/.agents/scripts/lib/orchestration/review-providers/claim-grounding.js +38 -14
  19. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +12 -0
  20. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +97 -19
  21. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +26 -5
  22. package/.agents/scripts/lib/orchestration/review-providers/codex.js +4 -2
  23. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +357 -0
  24. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +53 -0
  25. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +85 -15
  26. package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +40 -1
  27. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +68 -0
  28. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +25 -10
  29. package/.agents/scripts/lib/orchestration/review-providers/types.js +8 -2
  30. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +3 -0
  31. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +14 -2
  32. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +1 -0
  33. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +24 -1
  34. package/.agents/scripts/lib/process-group.js +20 -1
  35. package/.agents/scripts/lib/supervised-suite.js +12 -11
  36. package/.agents/scripts/review-dispositions-report.js +129 -0
  37. package/.agents/workflows/helpers/code-review.md +53 -0
  38. package/docs/CHANGELOG.md +27 -0
  39. package/package.json +1 -1
@@ -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,11 +52,13 @@ 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
  }
58
59
 
60
+ const NOT_BLOCKING = ['ungrounded', 'unverified'];
61
+
59
62
  /**
60
63
  * Report lines saying why a finding did not block, or was reviewed blind.
61
64
  *
@@ -63,16 +66,15 @@ export function buildClaim(raw) {
63
66
  * @returns {string[]}
64
67
  */
65
68
  export function groundingNotes(finding) {
66
- const notes = [];
67
- if (finding.ungrounded) {
68
- notes.push(`_Not blocking: ungrounded — ${finding.ungrounded}._`);
69
- }
69
+ const notes = NOT_BLOCKING.filter((key) => finding[key]).map(
70
+ (key) => `_Not blocking: ${key} — ${finding[key]}._`,
71
+ );
70
72
  if (finding.context) notes.push(`_Context: ${finding.context}._`);
71
73
  return notes;
72
74
  }
73
75
 
74
76
  /** @returns {string|null} evidence when the path exists at `headRef`. */
75
- function refutePathAbsent(claim, headRef, git) {
77
+ function refutePathAbsent(claim, { headRef }, git) {
76
78
  const result = git('cat-file', '-e', `${headRef}:${claim.path}`);
77
79
  return result?.status === 0 ? `git cat-file found ${claim.path}` : null;
78
80
  }
@@ -101,7 +103,7 @@ function isDeclaration(hit, claim) {
101
103
  }
102
104
 
103
105
  /** @returns {string|null} evidence when every hit is the declaration. */
104
- function refuteSymbolReferenced(claim, headRef, git) {
106
+ function refuteSymbolReferenced(claim, { headRef }, git) {
105
107
  const result = git(
106
108
  'grep',
107
109
  '-n',
@@ -123,18 +125,32 @@ function refuteSymbolReferenced(claim, headRef, git) {
123
125
  : 'git grep found no references';
124
126
  }
125
127
 
128
+ /**
129
+ * `git diff --quiet` exits 1 only when the path differs across the range; 0,
130
+ * any other status or no base proves nothing.
131
+ *
132
+ * @returns {string|null} evidence when the path changed in base...head.
133
+ */
134
+ function refuteFileUnchanged(claim, { baseRef, headRef }, git) {
135
+ const range = `${baseRef}...${headRef}`;
136
+ const changed =
137
+ baseRef && git('diff', '--quiet', range, '--', claim.path)?.status === 1;
138
+ return changed ? `git diff ${range} changes ${claim.path}` : null;
139
+ }
140
+
126
141
  const REFUTERS = {
127
142
  'path-absent': refutePathAbsent,
128
143
  'symbol-referenced': refuteSymbolReferenced,
144
+ 'file-unchanged': refuteFileUnchanged,
129
145
  };
130
146
 
131
147
  /** @returns {Finding} */
132
- function groundFinding(finding, headRef, git) {
148
+ function groundFinding(finding, refs, git) {
133
149
  if (!isGroundable(finding)) return finding;
134
150
  const refute = REFUTERS[finding.claim.kind];
135
151
  let evidence = null;
136
152
  try {
137
- evidence = refute(finding.claim, headRef, git);
153
+ evidence = refute(finding.claim, refs, git);
138
154
  } catch {
139
155
  evidence = null;
140
156
  }
@@ -189,9 +205,9 @@ function annotateContext(finding, tokens) {
189
205
  return { ...finding, context: TRUNCATED_CONTEXT };
190
206
  }
191
207
 
192
- function groundEach(findings, headRef, git, tokens) {
208
+ function groundEach(findings, refs, git, tokens) {
193
209
  return findings.map((finding) => {
194
- const grounded = groundFinding(finding, headRef, git);
210
+ const grounded = groundFinding(finding, refs, git);
195
211
  return grounded && tokens.size > 0
196
212
  ? annotateContext(grounded, tokens)
197
213
  : grounded;
@@ -199,13 +215,15 @@ function groundEach(findings, headRef, git, tokens) {
199
215
  }
200
216
 
201
217
  /**
202
- * Ground every finding in `cwd`, the reviewed repository. `degradations`
218
+ * Ground every finding in `cwd`, the reviewed repository; `baseRef` is
219
+ * needed only to refute a `file-unchanged` claim. `degradations`
203
220
  * comes back with the head check's record appended when the head does not
204
221
  * resolve there.
205
222
  *
206
223
  * @param {{
207
224
  * findings: Finding[],
208
225
  * headRef: string,
226
+ * baseRef?: string|null,
209
227
  * degradations?: ReadonlyArray<{ reason: string }>,
210
228
  * cwd?: string,
211
229
  * gitSpawnFn?: typeof gitSpawn,
@@ -215,6 +233,7 @@ function groundEach(findings, headRef, git, tokens) {
215
233
  export function groundFindings({
216
234
  findings,
217
235
  headRef,
236
+ baseRef,
218
237
  degradations = [],
219
238
  cwd = process.cwd(),
220
239
  gitSpawnFn = gitSpawn,
@@ -225,7 +244,12 @@ export function groundFindings({
225
244
  ...headDegradations({ findings, headRef, cwd, git }),
226
245
  ];
227
246
  return {
228
- findings: groundEach(findings, headRef, git, reasonTokens(all)),
247
+ findings: groundEach(
248
+ findings,
249
+ { baseRef, headRef },
250
+ git,
251
+ reasonTokens(all),
252
+ ),
229
253
  degradations: all,
230
254
  };
231
255
  }
@@ -22,6 +22,18 @@ export const FINDINGS_SCHEMA_JSON = JSON.stringify({
22
22
  file: { type: 'string' },
23
23
  line: { type: 'integer' },
24
24
  category: { type: 'string' },
25
+ class: { type: 'string' },
26
+ instances: {
27
+ type: 'array',
28
+ items: {
29
+ type: 'object',
30
+ properties: {
31
+ file: { type: 'string' },
32
+ line: { type: 'integer' },
33
+ },
34
+ required: ['file'],
35
+ },
36
+ },
25
37
  claim: CLAIM_SCHEMA,
26
38
  },
27
39
  required: ['title', 'body'],
@@ -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
  *
@@ -36,7 +38,9 @@ import {
36
38
  resolveVerdict,
37
39
  } from './claude-verdict.js';
38
40
  import { readDiff } from './generated-diff.js';
41
+ import { BUG_CLASS_RULE } from './parse-findings.js';
39
42
  import { renderDepthDirective } from './review-depth.js';
43
+ import { renderGuidanceBlock } from './review-guidance.js';
40
44
  import { probeClaudeCli } from './security-review.js';
41
45
 
42
46
  const CLAUDE_ARGS = Object.freeze([
@@ -77,17 +81,52 @@ const PROMPT_HEAD =
77
81
  'input, command or test that exposes it). A `shortcut:` comment naming ' +
78
82
  'its ceiling and trigger is a decision, not a finding, unless this diff ' +
79
83
  'itself crosses the ceiling.\n\n' +
80
- 'The diff below is authoritative — files on disk may not reflect it. ' +
81
- 'Answer with a JSON object of this exact shape, no prose around it:\n\n' +
82
- '{"findings":[{"title":"...","body":"Why it is wrong: ... How to show it ' +
83
- 'fails: ...","file":"...","line":1,"category":"bug","claim":null}]}\n\n' +
84
+ `${BUG_CLASS_RULE}\n\n` +
84
85
  'Set `claim` when the problem rests on a checkable fact: ' +
85
86
  '{"kind":"path-absent","path":"<file>"} when a file the change needs is ' +
86
87
  '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' +
88
+ 'definition file>"} when a removed or renamed symbol still has callers, ' +
89
+ 'or {"kind":"file-unchanged","path":"<file>"} when the problem is that ' +
90
+ 'another file was not updated. Otherwise leave it null.\n\n' +
91
+ '{scopeNote}{guidance}' +
92
+ 'Answer with a JSON object of this exact shape, no prose around it:\n\n' +
93
+ '{"findings":[{"title":"...","body":"Why it is wrong: ... How to show it ' +
94
+ 'fails: ...","file":"...","line":1,"category":"bug","class":"...",' +
95
+ '"instances":[{"file":"...","line":1}],"claim":null}]}\n\n' +
89
96
  'Emit {"findings":[]} if there is nothing you would block the merge for.\n\n';
90
97
 
98
+ const WHOLE_DIFF_NOTE =
99
+ 'The diff below is authoritative — files on disk may not reflect it. ';
100
+
101
+ /** @param {number} index - 1-based. @param {number} total */
102
+ const sliceNote = (index, total) =>
103
+ `The diff below is chunk ${index} of ${total} of one change, split for ` +
104
+ 'size; files on disk may not reflect it. Every file in <manifest> is ' +
105
+ 'changed by this change, even when its hunks sit in another chunk: never ' +
106
+ 'report a listed file as unchanged or missing, and set a file-unchanged ' +
107
+ 'claim on any problem that rests on another file not being updated. ';
108
+
109
+ const TEST_PATH =
110
+ /(?:^|\/)(?:__tests__|tests?|e2e|features)\/|\.(?:test|spec)\.|\.feature$/;
111
+ const DOCS_PATH = /(?:^|\/)docs\/|\.(?:md|mdx|txt)$/i;
112
+
113
+ /** Pack order: 0 source, 1 tests, 2 docs — the chunk bound falls on the last. */
114
+ function tierOf(file) {
115
+ if (TEST_PATH.test(file)) return 1;
116
+ return DOCS_PATH.test(file) ? 2 : 0;
117
+ }
118
+
119
+ const compareText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
120
+
121
+ /** Tier, then directory, then path. */
122
+ function compareSections(a, b) {
123
+ return (
124
+ a.tier - b.tier ||
125
+ compareText(path.posix.dirname(a.file), path.posix.dirname(b.file)) ||
126
+ compareText(a.file, b.file)
127
+ );
128
+ }
129
+
91
130
  /**
92
131
  * Split a diff at `diff --git` boundaries into per-file sections.
93
132
  *
@@ -107,7 +146,18 @@ function splitSections(diff) {
107
146
  }
108
147
 
109
148
  /**
110
- * First-fit, in diff order, into chunks of at most `budget` characters; a
149
+ * The first chunk with room for `section` at or after the last chunk holding
150
+ * an earlier tier, so no test or doc sits in a chunk ahead of a source section.
151
+ */
152
+ function openChunk(chunks, section, budget) {
153
+ const floor = chunks.findLastIndex((c) => c.tier < section.tier);
154
+ return chunks
155
+ .slice(Math.max(floor, 0))
156
+ .find((c) => c.size + section.text.length <= budget);
157
+ }
158
+
159
+ /**
160
+ * First-fit, tier by tier, into chunks of at most `budget` characters; a
111
161
  * section over the budget gets a chunk of its own (truncated when reviewed).
112
162
  *
113
163
  * @param {{ file: string, text: string }[]} sections
@@ -115,14 +165,17 @@ function splitSections(diff) {
115
165
  */
116
166
  function packChunks(sections, budget) {
117
167
  const chunks = [];
118
- for (const section of sections) {
168
+ const ordered = sections
169
+ .map((s) => ({ ...s, tier: tierOf(s.file) }))
170
+ .sort(compareSections);
171
+ for (const section of ordered) {
119
172
  const size = section.text.length;
120
- const open = chunks.find((c) => c.size + size <= budget);
173
+ const open = openChunk(chunks, section, budget);
121
174
  if (open) {
122
175
  open.sections.push(section);
123
176
  open.size += size;
124
177
  } else {
125
- chunks.push({ sections: [section], size });
178
+ chunks.push({ sections: [section], size, tier: section.tier });
126
179
  }
127
180
  }
128
181
  return chunks;
@@ -144,16 +197,25 @@ function dedupeFindings(findings) {
144
197
  * @param {string} diff
145
198
  * @param {string} callers - the `<callers>` section, or '' below `deep`.
146
199
  * @param {number} [cap]
200
+ * @param {string} [scope] - the slice note and `<manifest>` of a chunk.
147
201
  * @returns {string}
148
202
  */
149
- function buildPrompt(input, diff, callers, cap = MAX_DIFF_CHARS) {
203
+ function buildPrompt(
204
+ input,
205
+ diff,
206
+ callers,
207
+ cap = MAX_DIFF_CHARS,
208
+ scope = WHOLE_DIFF_NOTE,
209
+ ) {
150
210
  const truncated = diff.length > cap;
151
211
  const body = truncated ? diff.slice(0, cap) : diff;
152
212
  const note = truncated ? `\n[diff truncated at ${cap} characters]\n` : '';
153
213
  const head = PROMPT_HEAD.replace('{baseRef}', input.baseRef)
154
214
  .replace('{headRef}', input.headRef)
155
215
  .replace('{ticketId}', String(input.ticketId))
156
- .replace('{depthDirective}', renderDepthDirective(input.depth));
216
+ .replace('{scopeNote}', scope)
217
+ .replace('{depthDirective}', renderDepthDirective(input.depth))
218
+ .replace('{guidance}', () => renderGuidanceBlock(input.guidance));
157
219
  return `${head}<diff>\n${body}${note}\n</diff>\n${callers}`;
158
220
  }
159
221
 
@@ -170,13 +232,14 @@ function quoteWindowsArg(arg) {
170
232
  }
171
233
 
172
234
  /**
173
- * Async, so close's concurrent gate children keep draining.
235
+ * Async, so close's concurrent gate children keep draining. Shared with the
236
+ * critical verifier.
174
237
  *
175
238
  * @param {ReadonlyArray<string>} args
176
239
  * @param {{ cwd: string, input?: string, timeout: number, run?: Function, platform: string }} opts
177
240
  * @returns {Promise<{ status: number, stdout: string, stderr: string }>}
178
241
  */
179
- function runClaude(args, { cwd, input, timeout, run, platform }) {
242
+ export function runClaude(args, { cwd, input, timeout, run, platform }) {
180
243
  const shell = platform === 'win32';
181
244
  return spawnCaptureAsync(
182
245
  'claude',
@@ -288,10 +351,24 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
288
351
  return [];
289
352
  }
290
353
 
291
- /** The `<callers>` block rides every chunk, so it comes out of the budget. */
354
+ /**
355
+ * The `<callers>` block, guidance, the slice note and the manifest ride every chunk,
356
+ * so they come out of the budget; chunk numbers are one digit, so the
357
+ * note's length is fixed before packing.
358
+ */
292
359
  async function reviewInChunks(input, text, callers) {
293
- const budget = MAX_DIFF_CHARS - callers.length;
294
- const chunks = packChunks(splitSections(text), budget);
360
+ const sections = splitSections(text).filter((s) => s.text.length > 0);
361
+ const files = sections
362
+ .map((s) => s.file)
363
+ .filter((file) => file !== '(unnamed)');
364
+ const manifest = `<manifest>\n${files.join('\n')}\n</manifest>\n`;
365
+ const budget =
366
+ MAX_DIFF_CHARS -
367
+ callers.length -
368
+ renderGuidanceBlock(input.guidance).length -
369
+ manifest.length -
370
+ sliceNote(MAX_REVIEW_CHUNKS, MAX_REVIEW_CHUNKS).length;
371
+ const chunks = packChunks(sections, budget);
295
372
  const overflow = chunks
296
373
  .splice(MAX_REVIEW_CHUNKS)
297
374
  .flatMap((c) => c.sections.map((s) => s.file));
@@ -302,7 +379,7 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
302
379
  );
303
380
  }
304
381
  const findings = [];
305
- for (const chunk of chunks) {
382
+ for (const [index, chunk] of chunks.entries()) {
306
383
  const files = chunk.sections.map((s) => s.file).join(', ');
307
384
  if (chunk.size > budget) {
308
385
  noteDegradation(
@@ -315,6 +392,7 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
315
392
  chunk.sections.map((s) => s.text).join(''),
316
393
  callers,
317
394
  budget,
395
+ sliceNote(index + 1, chunks.length) + manifest,
318
396
  );
319
397
  const verdict = await reviewInTempDir(prompt, runDeps);
320
398
  if ('reason' in verdict) {
@@ -18,8 +18,10 @@ import { resolveAgentrcRoot } from '../../config/git-roots.js';
18
18
  import { resolvedTempRoot } from '../../config/temp-paths.js';
19
19
  import { resolveConfig } from '../../config-resolver.js';
20
20
  import { STRICT_CLAIM_SCHEMA } from './claim-grounding.js';
21
+ import { BUG_CLASS_RULE } from './parse-findings.js';
21
22
  import { PROVIDER_SEVERITY_MAP } from './provider-severity.js';
22
23
  import { renderDepthDirective } from './review-depth.js';
24
+ import { renderGuidanceBlock } from './review-guidance.js';
23
25
 
24
26
  const PROBE_TIMEOUT_MS = 5000;
25
27
  const INVOKE_TIMEOUT_MS = 15 * 60 * 1000;
@@ -55,6 +57,8 @@ const FINDINGS_SCHEMA = Object.freeze({
55
57
  'file',
56
58
  'line',
57
59
  'category',
60
+ 'class',
61
+ 'instances',
58
62
  'claim',
59
63
  ],
60
64
  properties: {
@@ -64,6 +68,19 @@ const FINDINGS_SCHEMA = Object.freeze({
64
68
  file: { type: ['string', 'null'] },
65
69
  line: { type: ['integer', 'null'] },
66
70
  category: { type: 'string' },
71
+ class: { type: ['string', 'null'] },
72
+ instances: {
73
+ type: ['array', 'null'],
74
+ items: {
75
+ type: 'object',
76
+ additionalProperties: false,
77
+ required: ['file', 'line'],
78
+ properties: {
79
+ file: { type: 'string' },
80
+ line: { type: ['integer', 'null'] },
81
+ },
82
+ },
83
+ },
67
84
  claim: STRICT_CLAIM_SCHEMA,
68
85
  },
69
86
  },
@@ -91,10 +108,11 @@ export function defaultProbeCodexCommand(opts = {}) {
91
108
  }
92
109
 
93
110
  /**
94
- * @param {{ baseRef: string, headRef: string, depth?: ReviewDepth }} args
111
+ * @param {{ baseRef: string, headRef: string, depth?: ReviewDepth,
112
+ * guidance?: string|null }} args
95
113
  * @returns {string}
96
114
  */
97
- function buildReviewPrompt({ baseRef, headRef, depth }) {
115
+ function buildReviewPrompt({ baseRef, headRef, depth, guidance }) {
98
116
  return (
99
117
  `Review the code changes in the git diff \`${baseRef}...${headRef}\` ` +
100
118
  `of this repository (run \`git diff ${baseRef}...${headRef}\` to read ` +
@@ -103,8 +121,10 @@ function buildReviewPrompt({ baseRef, headRef, depth }) {
103
121
  'the change introduces. For each one give the file and line in the new ' +
104
122
  'version when attributable (otherwise null), a short title, a markdown ' +
105
123
  'body explaining why it is wrong and how to fix it, and a category. ' +
106
- 'Do not modify any file. Report findings ONLY through the required ' +
107
- 'output schema; an empty `findings` array means no problems.\n'
124
+ `Do not modify any file.\n\n${BUG_CLASS_RULE}\n\n` +
125
+ renderGuidanceBlock(guidance) +
126
+ 'Report findings ONLY through the required output schema; an empty ' +
127
+ '`findings` array means no problems.\n'
108
128
  );
109
129
  }
110
130
 
@@ -125,7 +145,8 @@ function readIfPresent(file) {
125
145
  * tempRoot (removed afterwards). The prompt rides stdin; the last-message
126
146
  * file becomes `stdout`.
127
147
  *
128
- * @param {{ baseRef: string, headRef: string, depth?: ReviewDepth }} args
148
+ * @param {{ baseRef: string, headRef: string, depth?: ReviewDepth,
149
+ * guidance?: string|null }} args
129
150
  * @param {{ run?: Function, tempRoot?: string, cwd?: string }} [deps]
130
151
  * @returns {Promise<InvokeResult>}
131
152
  */
@@ -66,7 +66,7 @@ export function parseCodexFindings(rawOutput) {
66
66
  /**
67
67
  * @param {{
68
68
  * probeFn?: () => boolean,
69
- * invokeFn?: (args: { baseRef: string, headRef: string, scope: string, ticketId: number, depth?: import('./types.js').ReviewDepth }) => { status: number, stdout: string, stderr: string } | Promise<{ status: number, stdout: string, stderr: string }>,
69
+ * invokeFn?: (args: { baseRef: string, headRef: string, scope: string, ticketId: number, depth?: import('./types.js').ReviewDepth, guidance?: string|null }) => { status: number, stdout: string, stderr: string } | Promise<{ status: number, stdout: string, stderr: string }>,
70
70
  * logger?: { info?: Function, warn?: Function, error?: Function },
71
71
  * }} [deps]
72
72
  * @returns {ReviewProvider}
@@ -86,7 +86,8 @@ export function createCodexProvider(deps = {}) {
86
86
  * @returns {Promise<Finding[]>}
87
87
  */
88
88
  async runReview(input) {
89
- const { scope, ticketId, baseRef, headRef, depth } = input ?? {};
89
+ const { scope, ticketId, baseRef, headRef, depth, guidance } =
90
+ input ?? {};
90
91
  if (!baseRef || !headRef) {
91
92
  throw new TypeError(
92
93
  '[codex-review] runReview requires baseRef and headRef.',
@@ -109,6 +110,7 @@ export function createCodexProvider(deps = {}) {
109
110
  scope,
110
111
  ticketId,
111
112
  depth,
113
+ guidance,
112
114
  });
113
115
  if (result.status !== 0) {
114
116
  throw new Error(