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
@@ -11,9 +11,10 @@
11
11
 
12
12
  import { spawnSync } from 'node:child_process';
13
13
  import { resolveAgentrcRoot } from '../../config/git-roots.js';
14
- import { parseProviderFindings } from './parse-findings.js';
14
+ import { BUG_CLASS_RULE, parseProviderFindings } from './parse-findings.js';
15
15
  import { PROVIDER_SEVERITY_MAP } from './provider-severity.js';
16
16
  import { renderDepthDirective } from './review-depth.js';
17
+ import { renderGuidanceBlock } from './review-guidance.js';
17
18
 
18
19
  export const SECURITY_REVIEW_REMEDIATIONS = Object.freeze({
19
20
  install:
@@ -87,17 +88,23 @@ export function parseSecurityReviewFindings(rawStdout) {
87
88
  });
88
89
  }
89
90
 
90
- /** Wraps `/security-review` with an explicit JSON-emit instruction. */
91
+ /**
92
+ * Wraps `/security-review`: severity rules, then the class rule and any
93
+ * project guidance, then the JSON-emit instruction.
94
+ */
91
95
  const SECURITY_REVIEW_INVOKE_PROMPT =
92
96
  'Run /security-review against the diff `{baseRef}`...`{headRef}` ' +
93
- 'for {scopeLabel} #{ticketId}. {depthDirective} After the review, emit ' +
94
- 'ONLY a JSON array of findings on stdout with this exact shape:\n\n' +
95
- '```\n[{"severity":"critical|high|medium|suggestion","title":"...",' +
96
- '"body":"...","file":"...","line":1,"category":"security"}]\n```\n\n' +
97
+ 'for {scopeLabel} #{ticketId}. {depthDirective}\n\n' +
97
98
  'Use severity "critical" for blockers (must fix before merge), ' +
98
99
  '"high" for material risks, "medium" for issues worth fixing, and ' +
99
- '"suggestion" for advisory notes. Emit `[]` if you find nothing. ' +
100
- 'No prose around the JSON.';
100
+ `"suggestion" for advisory notes. ${BUG_CLASS_RULE}\n\n` +
101
+ '{guidance}' +
102
+ 'After the review, emit ONLY a JSON array of findings on stdout with ' +
103
+ 'this exact shape:\n\n' +
104
+ '```\n[{"severity":"critical|high|medium|suggestion","title":"...",' +
105
+ '"body":"...","file":"...","line":1,"category":"security",' +
106
+ '"class":"...","instances":[{"file":"...","line":1}]}]\n```\n\n' +
107
+ 'Emit `[]` if you find nothing. No prose around the JSON.';
101
108
 
102
109
  /**
103
110
  * @param {ReviewInput} input
@@ -115,7 +122,8 @@ export function buildSecurityReviewPrompt(input) {
115
122
  .replace('{headRef}', headRef)
116
123
  .replace('{scopeLabel}', scopeLabel)
117
124
  .replace('{ticketId}', ticketId)
118
- .replace('{depthDirective}', renderDepthDirective(input?.depth));
125
+ .replace('{depthDirective}', renderDepthDirective(input?.depth))
126
+ .replace('{guidance}', () => renderGuidanceBlock(input?.guidance));
119
127
  }
120
128
 
121
129
  /**
@@ -197,7 +205,14 @@ export function createSecurityReviewProvider(deps = {}) {
197
205
  `[security-review] Invoking /security-review for ${scope} #${ticketId} (${baseRef}...${headRef})...`,
198
206
  );
199
207
 
200
- const result = invokeFn({ scope, ticketId, baseRef, headRef });
208
+ const result = invokeFn({
209
+ scope,
210
+ ticketId,
211
+ baseRef,
212
+ headRef,
213
+ depth: input.depth,
214
+ guidance: input.guidance,
215
+ });
201
216
  if (result.status !== 0) {
202
217
  throw new Error(
203
218
  `[security-review] claude --print /security-review exited with ` +
@@ -13,12 +13,16 @@
13
13
  * @property {string=} category - e.g. 'security', 'lint'.
14
14
  * @property {FindingClaim=} claim - Structured, checkable claim.
15
15
  * @property {string=} ungrounded - Why a refuted critical was downgraded.
16
+ * @property {string=} unverified - The verifier's reason for refuting a critical.
16
17
  * @property {string=} context - 'reviewed-with-truncated-context'.
17
18
  * @property {string=} provider - Chain entry that raised it.
19
+ * @property {string=} class - Kebab-case bug class.
20
+ * @property {{ file: string, line?: number }[]=} instances - Every location; the first is `file`/`line`.
21
+ * @property {boolean=} repeat - An earlier run of this Story raised it.
18
22
  *
19
23
  * @typedef {object} FindingClaim
20
- * @property {'path-absent'|'symbol-referenced'} kind
21
- * @property {string=} path - Absent path, or the symbol's definition file.
24
+ * @property {'path-absent'|'symbol-referenced'|'file-unchanged'} kind
25
+ * @property {string=} path - Absent or unchanged path, or the symbol's definition file.
22
26
  * @property {string=} symbol
23
27
  *
24
28
  * @typedef {'story'} ReviewScope
@@ -32,6 +36,8 @@
32
36
  * @property {string} headRef
33
37
  * @property {ReviewDepth=} depth - Diff-derived thoroughness lever; LLM-backed
34
38
  * providers MUST render it into their prompt. Absent → `standard`.
39
+ * @property {(string|null)=} guidance - Project review guidance; LLM-backed
40
+ * providers render it via `renderGuidanceBlock`.
35
41
  *
36
42
  * @typedef {object} ReviewProvider
37
43
  * @property {(input: ReviewInput) => Promise<Finding[]>} runReview
@@ -200,6 +200,8 @@ export async function settleStoryScopeReview({
200
200
  halted: !!result.halted,
201
201
  severity: sev,
202
202
  criticalByProvider: result.criticalByProvider,
203
+ // The override records these ids so a re-review does not halt on them.
204
+ findings: Array.isArray(result.findings) ? result.findings : [],
203
205
  posted: result.posted,
204
206
  postedCommentId: result.postedCommentId ?? null,
205
207
  ...degradationEnvelope(result.degradations),
@@ -228,6 +230,7 @@ export async function settleStoryScopeReview({
228
230
  * skipped?: boolean,
229
231
  * severity?: { critical: number, high: number, medium: number, suggestion: number },
230
232
  * criticalByProvider?: Record<string, number>,
233
+ * findings?: Array<object>,
231
234
  * posted?: boolean,
232
235
  * postedCommentId?: number|null,
233
236
  * degraded?: boolean,
@@ -12,6 +12,7 @@ import path from 'node:path';
12
12
 
13
13
  import { gitSpawn as defaultGitSpawn } from '../../../git-utils.js';
14
14
  import { Logger } from '../../../Logger.js';
15
+ import { recordStoryDispositions as defaultRecordStoryDispositions } from '../../../observability/review-dispositions.js';
15
16
  import {
16
17
  emitCloseRecoveredFriction as defaultEmitCloseRecoveredFriction,
17
18
  emitRecoveredFrictionMarker as defaultEmitRecoveredFrictionMarker,
@@ -395,7 +396,8 @@ async function runLockedLocalSteps({
395
396
 
396
397
  /**
397
398
  * Run the post-land tail: friction markers, then the GitHub steps and the
398
- * locked local steps concurrently, then temp purge, then lease release.
399
+ * locked local steps concurrently, then review dispositions, temp purge and
400
+ * lease release.
399
401
  *
400
402
  * @param {object} args
401
403
  * @param {number} args.storyId
@@ -418,7 +420,8 @@ async function runLockedLocalSteps({
418
420
  * @param {Function} [args.reapPlanRunLabelsForStoryFn]
419
421
  * @param {Function} [args.rollUpEpicForStoryFn]
420
422
  * @param {Function} [args.reapWorktreePhaseFn]
421
- * @returns {Promise<{ followUps: boolean, statusResync: boolean, worktreeReap: boolean, refCleanup: boolean, baseFastForward: boolean, tempPurge: boolean, leaseRelease: boolean, epicRollup: boolean, details: Record<string, string|null> }>}
423
+ * @param {Function} [args.recordStoryDispositionsFn]
424
+ * @returns {Promise<{ followUps: boolean, statusResync: boolean, worktreeReap: boolean, refCleanup: boolean, baseFastForward: boolean, reviewDispositions: boolean, tempPurge: boolean, leaseRelease: boolean, epicRollup: boolean, details: Record<string, string|null> }>}
422
425
  */
423
426
  export async function runPostLandTail({
424
427
  storyId,
@@ -441,6 +444,7 @@ export async function runPostLandTail({
441
444
  reapPlanRunLabelsForStoryFn = defaultReapPlanRunLabelsForStory,
442
445
  rollUpEpicForStoryFn = defaultRollUpEpicForStory,
443
446
  reapWorktreePhaseFn = defaultReapWorktreePhase,
447
+ recordStoryDispositionsFn = defaultRecordStoryDispositions,
444
448
  }) {
445
449
  progress?.('POST-LAND', `🧾 Running land tail for Story #${storyId}...`);
446
450
 
@@ -522,6 +526,12 @@ export async function runPostLandTail({
522
526
  ]);
523
527
  const { worktreeReap, refCleanup, baseFastForward } = local;
524
528
 
529
+ // Before the purge, which reaps the review history it reads.
530
+ const reviewDispositions = await step(
531
+ () => recordStoryDispositionsFn({ storyId, config, progress }),
532
+ { name: 'review dispositions', progress },
533
+ );
534
+
525
535
  // After every step that reads the temp artifacts; `signals.ndjson` survives.
526
536
  const tempPurge = await step(
527
537
  () => stepTempPurge({ storyId, config, purgeStoryTempArtifactsFn }),
@@ -546,6 +556,7 @@ export async function runPostLandTail({
546
556
  worktreeReap: worktreeReap.ok,
547
557
  refCleanup: refCleanup.ok,
548
558
  baseFastForward: baseFastForward.ok,
559
+ reviewDispositions: reviewDispositions.ok,
549
560
  tempPurge: tempPurge.ok,
550
561
  leaseRelease: leaseRelease.ok,
551
562
  epicRollup: epicRollup.ok,
@@ -555,6 +566,7 @@ export async function runPostLandTail({
555
566
  worktreeReap: worktreeReap.detail,
556
567
  refCleanup: refCleanup.detail,
557
568
  baseFastForward: baseFastForward.detail,
569
+ reviewDispositions: reviewDispositions.detail,
558
570
  tempPurge: tempPurge.detail,
559
571
  leaseRelease: leaseRelease.detail,
560
572
  epicRollup: epicRollup.detail,
@@ -27,6 +27,7 @@ export async function resolveReviewHalt(
27
27
  criticalCount,
28
28
  criticalByProvider: reviewOutcome.criticalByProvider,
29
29
  reason: ctx.options.overrideReviewBlock,
30
+ findings: reviewOutcome.findings ?? [],
30
31
  config: deps.config,
31
32
  });
32
33
  }
@@ -9,6 +9,8 @@ import {
9
9
  emitRuntimeFriction,
10
10
  RUNTIME_FRICTION_CATEGORIES,
11
11
  } from '../../../observability/runtime-friction.js';
12
+ import { recordOverriddenIds } from '../../review-history.js';
13
+ import { findingId } from '../../review-providers/finding-identity.js';
12
14
  import {
13
15
  postStructuredComment,
14
16
  upsertStructuredComment,
@@ -55,9 +57,27 @@ async function postAuditRecord({ post, surface }) {
55
57
  }
56
58
  }
57
59
 
60
+ /**
61
+ * Remember the overridden CRITICALs so a re-review does not halt on them
62
+ * again, and the reason so the land-time disposition record carries it.
63
+ *
64
+ * @param {{ storyId: number, findings: Array<object>, reason: string, config?: object }} args
65
+ */
66
+ function recordOverrides({ storyId, findings, ...deps }) {
67
+ const ids = findings.filter((f) => f?.severity === 'critical').map(findingId);
68
+ if (ids.length === 0) return;
69
+ try {
70
+ recordOverriddenIds(storyId, ids, deps);
71
+ } catch (err) {
72
+ Logger.warn(
73
+ `[single-story-close] failed to record overridden review ids: ${err?.message ?? err}`,
74
+ );
75
+ }
76
+ }
77
+
58
78
  /**
59
79
  * Records to the Story (upsert, so re-runs don't stack), the PR (append-only,
60
- * where reviewers look), and the friction stream.
80
+ * where reviewers look), the friction stream, and the review history.
61
81
  *
62
82
  * @param {{
63
83
  * provider: object,
@@ -67,6 +87,7 @@ async function postAuditRecord({ post, surface }) {
67
87
  * criticalCount: number,
68
88
  * criticalByProvider?: Record<string, number>,
69
89
  * reason: string,
90
+ * findings?: Array<object>,
70
91
  * config?: object,
71
92
  * emitFrictionFn?: typeof emitRuntimeFriction,
72
93
  * }} args
@@ -80,6 +101,7 @@ export async function handleOverriddenReviewBlock({
80
101
  criticalCount,
81
102
  criticalByProvider = {},
82
103
  reason,
104
+ findings = [],
83
105
  config,
84
106
  emitFrictionFn = emitRuntimeFriction,
85
107
  }) {
@@ -112,5 +134,6 @@ export async function handleOverriddenReviewBlock({
112
134
  },
113
135
  config,
114
136
  });
137
+ recordOverrides({ storyId, findings, reason, config });
115
138
  return { overridden: true, reason, criticalCount };
116
139
  }
@@ -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;
@@ -0,0 +1,129 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * review-dispositions-report.js — summarize the local review-dispositions
5
+ * ledger: per provider and per severity, the count and rate of each
6
+ * disposition, plus the precision and false-blocker proxies. Read-only;
7
+ * exits 0 on an empty or absent ledger.
8
+ */
9
+
10
+ import { parseArgs } from 'node:util';
11
+
12
+ import { runAsCli } from './lib/cli-utils.js';
13
+ import { resolveConfig } from './lib/config-resolver.js';
14
+ import {
15
+ DISPOSITIONS,
16
+ readDispositions,
17
+ summarizeDispositions,
18
+ } from './lib/observability/review-dispositions.js';
19
+
20
+ const USAGE = {
21
+ invocation:
22
+ 'node .agents/scripts/review-dispositions-report.js [--since <YYYY-MM-DD>] [--json]',
23
+ summary:
24
+ 'Summarize the review-dispositions ledger (<tempRoot>/review-dispositions.ndjson): count and rate of each disposition per provider and per severity, with precision ((fixed-on-branch + open-at-merge) / all) and false-blocker ((overridden + refuted-by-verifier + downgraded-ungrounded) / criticals) proxies.',
25
+ flags: [
26
+ ['--since <YYYY-MM-DD>', 'Only records written on or after this date.'],
27
+ ['--json', 'Emit the summary as JSON instead of a table.'],
28
+ ],
29
+ };
30
+
31
+ const DATE = /^\d{4}-\d{2}-\d{2}$/;
32
+
33
+ /** @param {number|null} r */
34
+ const pct = (r) => (r === null ? '-' : `${(r * 100).toFixed(1)}%`);
35
+
36
+ /** @param {string} label @param {Record<string, object>} groups */
37
+ function renderTable(label, groups) {
38
+ const header = [label, 'total', ...DISPOSITIONS, 'precision', 'false-blk'];
39
+ const rows = Object.entries(groups).map(([key, t]) => [
40
+ key,
41
+ String(t.total),
42
+ ...DISPOSITIONS.map((d) => `${t.counts[d]} (${pct(t.rates[d])})`),
43
+ pct(t.precision),
44
+ pct(t.falseBlocker),
45
+ ]);
46
+ return alignRows([header, ...rows]).join('\n');
47
+ }
48
+
49
+ /** @param {string[][]} rows @returns {string[]} space-padded columns. */
50
+ function alignRows(rows) {
51
+ const widths = [];
52
+ for (const row of rows) {
53
+ row.forEach((cell, i) => {
54
+ widths[i] = Math.max(widths[i] ?? 0, cell.length);
55
+ });
56
+ }
57
+ return rows.map((row) =>
58
+ row
59
+ .map((cell, i) => cell.padEnd(widths[i]))
60
+ .join(' ')
61
+ .trimEnd(),
62
+ );
63
+ }
64
+
65
+ /**
66
+ * @param {string[]} [argv]
67
+ * @param {{
68
+ * resolveConfigImpl?: typeof resolveConfig,
69
+ * stdout?: { write: (s: string) => void },
70
+ * cwd?: string,
71
+ * }} [deps]
72
+ * @returns {Promise<object|null>} the summary, or null when nothing recorded.
73
+ */
74
+ export async function runReviewDispositionsReport(
75
+ argv = process.argv.slice(2),
76
+ deps = {},
77
+ ) {
78
+ const {
79
+ resolveConfigImpl = resolveConfig,
80
+ stdout = process.stdout,
81
+ cwd = process.cwd(),
82
+ } = deps;
83
+ const { values } = parseArgs({
84
+ args: argv,
85
+ options: { since: { type: 'string' }, json: { type: 'boolean' } },
86
+ });
87
+ if (values.since !== undefined && !DATE.test(values.since)) {
88
+ throw new Error(
89
+ `review-dispositions-report: --since must be YYYY-MM-DD (got "${values.since}").`,
90
+ );
91
+ }
92
+ const config = resolveConfigImpl({ cwd });
93
+ const records = await readDispositions({
94
+ config,
95
+ since: values.since ?? null,
96
+ });
97
+ if (records.length === 0) {
98
+ stdout.write('[review-dispositions-report] no dispositions recorded.\n');
99
+ return null;
100
+ }
101
+ const summary = summarizeDispositions(records);
102
+ if (values.json) {
103
+ stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
104
+ return summary;
105
+ }
106
+ stdout.write(
107
+ [
108
+ renderTable('provider', summary.byProvider),
109
+ '',
110
+ renderTable('severity', summary.bySeverity),
111
+ '',
112
+ renderTable('all', { all: summary.overall }),
113
+ '',
114
+ ].join('\n'),
115
+ );
116
+ return summary;
117
+ }
118
+
119
+ async function main() {
120
+ await runReviewDispositionsReport();
121
+ return 0;
122
+ }
123
+
124
+ runAsCli(import.meta.url, main, {
125
+ source: 'review-dispositions-report',
126
+ propagateExitCode: true,
127
+ errorPrefix: '[review-dispositions-report] ❌ Fatal error',
128
+ usage: USAGE,
129
+ });
@@ -91,6 +91,55 @@ size, and there is no "review harder" knob a deterministic scorer can turn (its
91
91
  module JSDoc documents this). When you (the host LLM) perform the Step 2 pillar
92
92
  review yourself, honor the `depth` semantics above directly.
93
93
 
94
+ ### Project review guidance and skip paths
95
+
96
+ A consumer tells the Story-scope reviewer what failure looks like in its own
97
+ codebase with a root `REVIEW.md`, or the file
98
+ `delivery.codeReview.guidanceFile` names. Keep it **short, project-specific
99
+ and evidence-required**: name the defect classes this codebase actually ships
100
+ (a retry loop without a bound, a query built without the tenant filter), each
101
+ with the file or pattern that shows it, and ask for proof rather than
102
+ suspicion. Generic advice the framework prompt already carries only dilutes it.
103
+ The review reads it once and renders it into every LLM provider's prompt
104
+ after the framework's severity and anti-gaming rules, under a fixed sentence:
105
+ guidance can add failure classes and paths worth skipping, but cannot lower a
106
+ severity rule, excuse a `shortcut:` comment, or change the output shape. Over
107
+ 8,000 characters it is truncated and recorded as a degraded gate.
108
+
109
+ Prose cannot silence a finding. Only `delivery.codeReview.skipPaths`
110
+ (picomatch globs) drops findings, after grounding and verification and before
111
+ severity is counted; the report states how many were dropped.
112
+
113
+ ### Bug classes, instances and repeats
114
+
115
+ Each LLM finding names its bug `class` and lists every `instances` location of
116
+ the same defect in the diff, rendered as one finding with an `Instances:`
117
+ list. Its stable id (class or category, first instance file, and for a
118
+ class-less finding its title; never a line number) rides a hidden
119
+ `<!-- finding:<id> -->` marker. A per-Story review history records every run;
120
+ a re-review renders a finding it already raised at an overlapping location
121
+ collapsed under **Previously raised**. A repeat still halts unless an operator
122
+ overrode that CRITICAL with `--override-review-block` earlier, in which case
123
+ it is downgraded to a suggestion.
124
+
125
+ ### Review dispositions
126
+
127
+ When a Story lands, the post-land tail (before the temp purge reaps the
128
+ history) appends one record per finding id the Story's reviews raised to the
129
+ local, never-committed `<tempRoot>/review-dispositions.ndjson` (rotated at
130
+ 1 MB, one `.1` generation kept). Precedence, with the last run as the final
131
+ review: `overridden` (an operator overrode it; the record carries the
132
+ redacted reason, clipped to 500 characters), `downgraded-ungrounded` and
133
+ `refuted-by-verifier` (flagged in the final run), `open-at-merge` (in the
134
+ final run otherwise), `fixed-on-branch` (raised earlier, absent from the
135
+ final run). A record holds ids, provider, severity, class and run count only,
136
+ never a title, body, path or excerpt; a Story already recorded appends
137
+ nothing. Summarize with
138
+ `node .agents/scripts/review-dispositions-report.js [--since <YYYY-MM-DD>] [--json]`:
139
+ per provider and severity, each disposition's count and rate, the precision
140
+ proxy (fixed-on-branch + open-at-merge over all) and the false-blocker proxy
141
+ (overridden + refuted + downgraded over all criticals).
142
+
94
143
  ## Step 0 — Resolve Context
95
144
 
96
145
  1. Resolve `[TICKET_ID]` from `ticketId` (the Story for live `scope: story`).
@@ -350,6 +399,10 @@ Hard cutover per
350
399
  [`rules/git-conventions.md`](../../rules/git-conventions.md) § Contract
351
400
  Cutovers — no back-compat flag; `high` is opt-in to the old routing.
352
401
 
402
+ A finding with several `instances` is **one defect in several places**: it
403
+ counts as fixed only when every instance is fixed, so one fix round clears
404
+ the class.
405
+
353
406
  ### 🔴 / 🟠 findings — per-finding ceremony (unchanged)
354
407
 
355
408
  For each 🔴 / 🟠 finding from Step 4, decide between two paths and keep the
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,33 @@ 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.107.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.106.0...mandrel-v2.107.0) (2026-10-27)
19
+
20
+
21
+ ### Added
22
+
23
+ * code review: consumer review guidance (REVIEW.md), bug-class findings with every instance, and no repeat findings ([#5920](https://github.com/dsj1984/mandrel/issues/5920)) ([#5925](https://github.com/dsj1984/mandrel/issues/5925)) ([120b8d3](https://github.com/dsj1984/mandrel/commit/120b8d3c88ba253550c7c5f1540643a6b51c10df))
24
+ * held review: an independent fresh-context verifier confirms each CRITICAL before it can halt ([#5919](https://github.com/dsj1984/mandrel/issues/5919)) ([#5923](https://github.com/dsj1984/mandrel/issues/5923)) ([d58f454](https://github.com/dsj1984/mandrel/commit/d58f454f1fd16906d1e13c5e41c9f91056279f40))
25
+ * review depth: let a consumer declare its own sensitive paths, merged over the shipped manifest ([#5917](https://github.com/dsj1984/mandrel/issues/5917)) ([#5922](https://github.com/dsj1984/mandrel/issues/5922)) ([ae22338](https://github.com/dsj1984/mandrel/commit/ae223384120ef4866716dec21bc08f5c8973974a))
26
+ * review dispositions: record what happened to every Story-scope finding, with per-provider and per-severity rates ([#5918](https://github.com/dsj1984/mandrel/issues/5918)) ([#5926](https://github.com/dsj1984/mandrel/issues/5926)) ([9afe0d6](https://github.com/dsj1984/mandrel/commit/9afe0d65d01b7dc6fb4fee8add6a743dde1524aa))
27
+
28
+
29
+ ### Fixed
30
+
31
+ * held review: &lt;callers&gt; symbol extraction reads code only, never prose in strings, comments or docs ([#5927](https://github.com/dsj1984/mandrel/issues/5927)) ([#5928](https://github.com/dsj1984/mandrel/issues/5928)) ([70ef990](https://github.com/dsj1984/mandrel/commit/70ef990dc3ba408db95e47f2ad45d5362d86ad1c))
32
+
33
+ ## [2.106.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.105.0...mandrel-v2.106.0) (2026-10-26)
34
+
35
+
36
+ ### Added
37
+
38
+ * 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))
39
+
40
+
41
+ ### Fixed
42
+
43
+ * 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))
44
+
18
45
  ## [2.105.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.104.0...mandrel-v2.105.0) (2026-10-26)
19
46
 
20
47
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.105.0",
3
+ "version": "2.107.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/",