mandrel 2.90.0 → 2.91.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 (169) hide show
  1. package/.agents/README.md +47 -7
  2. package/.agents/agents/story-worker.md +20 -0
  3. package/.agents/audit-checklists/lean.md +26 -0
  4. package/.agents/docs/agentrc-reference.json +5 -6
  5. package/.agents/docs/configuration.md +31 -30
  6. package/.agents/docs/workflows.md +7 -1
  7. package/.agents/instructions.md +3 -1
  8. package/.agents/runtime-deps.json +0 -2
  9. package/.agents/schemas/agentrc.schema.json +46 -45
  10. package/.agents/schemas/audit-rules.json +19 -0
  11. package/.agents/scripts/acceptance-eval.js +2 -6
  12. package/.agents/scripts/audit-exceptions.js +2 -4
  13. package/.agents/scripts/check-arch-cycles.js +1 -5
  14. package/.agents/scripts/check-context-budget.js +1 -5
  15. package/.agents/scripts/check-cyclomatic.js +1 -5
  16. package/.agents/scripts/check-dead-exports.js +23 -14
  17. package/.agents/scripts/check-doc-links.js +4 -4
  18. package/.agents/scripts/check-test-temp-hygiene.js +29 -33
  19. package/.agents/scripts/coverage-capture.js +14 -6
  20. package/.agents/scripts/diagnose-friction.js +8 -10
  21. package/.agents/scripts/generate-workflows-doc.js +5 -0
  22. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +2 -0
  23. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +36 -27
  24. package/.agents/scripts/lib/audit-exceptions/adapters/shortcut-markers.js +70 -0
  25. package/.agents/scripts/lib/audit-exceptions/adapters/source-scan.js +26 -0
  26. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  27. package/.agents/scripts/lib/baseline-schema-registry.js +3 -5
  28. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +11 -28
  29. package/.agents/scripts/lib/baselines/components.js +5 -5
  30. package/.agents/scripts/lib/baselines/crap-preview-scan.js +4 -1
  31. package/.agents/scripts/lib/baselines/crap-updater-cli.js +6 -4
  32. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -10
  33. package/.agents/scripts/lib/baselines/kinds/crap.js +4 -2
  34. package/.agents/scripts/lib/baselines/kinds/duplication.js +4 -2
  35. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +13 -6
  36. package/.agents/scripts/lib/baselines/refresh-service.js +10 -13
  37. package/.agents/scripts/lib/baselines/writer.js +4 -4
  38. package/.agents/scripts/lib/bdd-scenario-scanner.js +26 -31
  39. package/.agents/scripts/lib/bootstrap/gh-list.js +4 -5
  40. package/.agents/scripts/lib/bootstrap/gh-preflight.js +13 -8
  41. package/.agents/scripts/lib/child-exec.js +4 -4
  42. package/.agents/scripts/lib/claude/agents-projection.js +170 -0
  43. package/.agents/scripts/lib/claude/commands-projection.js +184 -0
  44. package/.agents/scripts/lib/close-validation/commands.js +28 -117
  45. package/.agents/scripts/lib/close-validation/gates.js +54 -48
  46. package/.agents/scripts/lib/close-validation/projections/crap.js +2 -1
  47. package/.agents/scripts/lib/close-validation/projections/maintainability.js +50 -15
  48. package/.agents/scripts/lib/config/agentrc-overlay.js +4 -7
  49. package/.agents/scripts/lib/config/commands.js +82 -7
  50. package/.agents/scripts/lib/config/explain.js +2 -1
  51. package/.agents/scripts/lib/config/gates/coverage.schema.js +39 -3
  52. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  53. package/.agents/scripts/lib/config/gates/crap.schema.js +5 -3
  54. package/.agents/scripts/lib/config/gates/duplication.schema.js +6 -11
  55. package/.agents/scripts/lib/config/gates/shared.js +2 -2
  56. package/.agents/scripts/lib/config/git-roots.js +120 -0
  57. package/.agents/scripts/lib/config/quality.js +46 -50
  58. package/.agents/scripts/lib/config/review-chain-default.js +4 -3
  59. package/.agents/scripts/lib/config/review-provider-clis.js +11 -0
  60. package/.agents/scripts/lib/config/temp-paths.js +3 -37
  61. package/.agents/scripts/lib/config-resolver.js +5 -9
  62. package/.agents/scripts/lib/config-settings-schema-delivery.js +2 -2
  63. package/.agents/scripts/lib/config-settings-schema-quality.js +3 -2
  64. package/.agents/scripts/lib/config-settings-schema.js +6 -7
  65. package/.agents/scripts/lib/coverage-baseline.js +2 -1
  66. package/.agents/scripts/lib/coverage-capture-affected.js +4 -3
  67. package/.agents/scripts/lib/coverage-capture-fullscope.js +3 -1
  68. package/.agents/scripts/lib/coverage-capture-passes.js +119 -34
  69. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  70. package/.agents/scripts/lib/coverage-capture.js +31 -20
  71. package/.agents/scripts/lib/coverage-utils.js +34 -16
  72. package/.agents/scripts/lib/cpu-pool.js +2 -4
  73. package/.agents/scripts/lib/crap-engine.js +19 -1
  74. package/.agents/scripts/lib/crap-utils.js +2 -1
  75. package/.agents/scripts/lib/dead-exports-knip.js +29 -11
  76. package/.agents/scripts/lib/detect-package-manager.js +13 -0
  77. package/.agents/scripts/lib/feedback-loop/graduator-gh.js +4 -2
  78. package/.agents/scripts/lib/full-suite-lock.js +25 -9
  79. package/.agents/scripts/lib/gates/baseline-store.js +2 -10
  80. package/.agents/scripts/lib/generated/agentrc-validator.js +4 -1
  81. package/.agents/scripts/lib/gh-env.js +72 -0
  82. package/.agents/scripts/lib/gh-exec.js +26 -1
  83. package/.agents/scripts/lib/maintainability-utils.js +8 -8
  84. package/.agents/scripts/lib/npm-scripts.js +1 -1
  85. package/.agents/scripts/lib/observability/signal-validator.js +2 -6
  86. package/.agents/scripts/lib/observability/terse-result.js +2 -6
  87. package/.agents/scripts/lib/orchestration/board-access-latch.js +19 -8
  88. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +10 -13
  89. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  90. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +3 -3
  91. package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js +2 -6
  92. package/.agents/scripts/lib/orchestration/light-suitability.js +5 -7
  93. package/.agents/scripts/lib/orchestration/pr-watch.js +7 -7
  94. package/.agents/scripts/lib/orchestration/project-meta-cache.js +2 -11
  95. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -9
  96. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +219 -0
  97. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +53 -5
  98. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +2 -2
  99. package/.agents/scripts/lib/orchestration/review-providers/llm-review.js +96 -0
  100. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  101. package/.agents/scripts/lib/orchestration/review-providers/native.js +13 -19
  102. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +3 -2
  103. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +2 -0
  104. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +11 -3
  105. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -3
  106. package/.agents/scripts/lib/orchestration/story-close/format-autofix.js +41 -15
  107. package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js +2 -4
  108. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +2 -13
  109. package/.agents/scripts/lib/orchestration/story-handoff.js +13 -5
  110. package/.agents/scripts/lib/orchestration/story-progress.js +3 -11
  111. package/.agents/scripts/lib/orchestration/ticketing/bulk.js +3 -5
  112. package/.agents/scripts/lib/orchestration/verify-credit.js +52 -28
  113. package/.agents/scripts/lib/single-story-sweep/protection-ctx.js +11 -11
  114. package/.agents/scripts/lib/single-story-sweep/protection.js +1 -9
  115. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +1 -5
  116. package/.agents/scripts/lib/source-extensions.js +30 -15
  117. package/.agents/scripts/lib/test-run-credit.js +1 -9
  118. package/.agents/scripts/lib/test-temp.js +22 -21
  119. package/.agents/scripts/lib/util/ajv.js +111 -0
  120. package/.agents/scripts/lib/util/atomic-write.js +30 -0
  121. package/.agents/scripts/lib/util/paths.js +51 -0
  122. package/.agents/scripts/lib/util/sleep.js +6 -0
  123. package/.agents/scripts/lib/util/slug.js +12 -0
  124. package/.agents/scripts/lib/validation-evidence.js +19 -40
  125. package/.agents/scripts/lib/worktree/lifecycle/force-drain.js +2 -1
  126. package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js +10 -28
  127. package/.agents/scripts/lib/worktree/lifecycle/reap.js +2 -2
  128. package/.agents/scripts/lib/worktree/node-modules-strategy.js +21 -14
  129. package/.agents/scripts/lint-issue-body.js +2 -2
  130. package/.agents/scripts/plan-context.js +2 -7
  131. package/.agents/scripts/providers/github/auth.js +3 -3
  132. package/.agents/scripts/providers/github/errors.js +3 -1
  133. package/.agents/scripts/providers/github/gh-token-diagnostics.js +10 -7
  134. package/.agents/scripts/providers/github/issues.js +6 -2
  135. package/.agents/scripts/providers/github/mappers.js +1 -5
  136. package/.agents/scripts/providers/github/projects-v2-graphql.js +11 -3
  137. package/.agents/scripts/providers/github/search-budget.js +3 -1
  138. package/.agents/scripts/resolve-doc-tiers.js +7 -20
  139. package/.agents/scripts/sync-agentrc.js +5 -14
  140. package/.agents/scripts/sync-claude-agents.js +38 -150
  141. package/.agents/scripts/sync-claude-commands.js +35 -218
  142. package/.agents/scripts/update-coverage-baseline.js +1 -1
  143. package/.agents/scripts/update-crap-baseline.js +1 -1
  144. package/.agents/scripts/update-duplication-baseline.js +2 -16
  145. package/.agents/scripts/validate-skills.js +6 -10
  146. package/.agents/skills/core/code-review-and-quality/SKILL.md +3 -18
  147. package/.agents/skills/core/documentation-and-adrs/SKILL.md +4 -14
  148. package/.agents/workflows/audit-exceptions.md +9 -0
  149. package/.agents/workflows/audit-lean.md +129 -0
  150. package/.agents/workflows/helpers/audit-lens-core.md +7 -0
  151. package/.agents/workflows/helpers/code-quality-guardrails.md +21 -0
  152. package/.agents/workflows/helpers/code-review.md +15 -1
  153. package/.agents/workflows/helpers/deliver-digest.md +1 -1
  154. package/.agents/workflows/helpers/deliver-reference.md +2 -2
  155. package/.agents/workflows/mandrel-plan.md +2 -2
  156. package/docs/CHANGELOG.md +35 -0
  157. package/lib/cli/doctor-checks/codex.js +6 -5
  158. package/lib/cli/doctor-checks/llm-review.js +102 -0
  159. package/lib/cli/doctor-checks/project-access.js +20 -10
  160. package/lib/cli/doctor-checks/sync-parity.js +65 -140
  161. package/lib/cli/doctor-checks/test-credit-path.js +69 -28
  162. package/lib/cli/doctor-checks/toolchain.js +5 -3
  163. package/lib/cli/registry.js +5 -0
  164. package/lib/migrations/helpers/retire-agentrc-key.js +3 -3
  165. package/lib/migrations/index.js +6 -0
  166. package/lib/migrations/steps/2.91.0-move-shared-crap-capture-script.js +84 -0
  167. package/lib/migrations/steps/2.91.0-retire-duplication-formats.js +23 -0
  168. package/lib/migrations/steps/2.91.0-unset-null-lint-command.js +54 -0
  169. package/package.json +1 -3
@@ -0,0 +1,219 @@
1
+ /**
2
+ * review-providers/callers-context.js — the `<callers>` block for a `deep`
3
+ * review: lines outside the changed files that reference symbols the diff
4
+ * defines or removes, by `git grep` at the head ref. Every cap that drops
5
+ * context is reported so the provider records a degradation.
6
+ */
7
+
8
+ import { normalizeDepth } from './review-depth.js';
9
+
10
+ /** Widen after a measured review-time check. */
11
+ const CALLER_CONTEXT_DEPTHS = Object.freeze(['deep']);
12
+ const CALLERS_INSTRUCTION =
13
+ 'The <callers> block lists lines outside the diff that reference symbols ' +
14
+ 'the diff changes; a caller the change breaks is a finding.';
15
+
16
+ const CALLER_CAPS = Object.freeze({
17
+ maxSymbols: 20,
18
+ maxLinesPerSymbol: 25,
19
+ maxChars: 30_000,
20
+ });
21
+
22
+ const IDENT = '[A-Za-z_$][\\w$]*';
23
+ const DECLARATION_PATTERNS = Object.freeze([
24
+ new RegExp(`\\bfunction\\b\\s*\\*?\\s*(${IDENT})`, 'g'),
25
+ new RegExp(`\\bclass\\s+(${IDENT})`, 'g'),
26
+ new RegExp(`\\bexport\\s+(?:const|let|var)\\s+(${IDENT})`, 'g'),
27
+ ]);
28
+ const EXPORT_LIST = /\bexport\s*\{([^}]*)\}/g;
29
+ const NEW_FILE_HEADER = /^\+\+\+ b\/(.+)$/;
30
+ /** Comment prose ("the function returns…") declares nothing. */
31
+ const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*)/;
32
+
33
+ /** `export { A, B as C }` exports `A` and `C`. */
34
+ function exportListNames(list) {
35
+ const ident = new RegExp(`^${IDENT}$`);
36
+ return list
37
+ .split(',')
38
+ .map(
39
+ (entry) =>
40
+ entry
41
+ .trim()
42
+ .split(/\s+as\s+/)
43
+ .pop()
44
+ ?.trim() ?? '',
45
+ )
46
+ .filter((name) => ident.test(name) && name !== 'default');
47
+ }
48
+
49
+ function symbolsOnLine(line) {
50
+ const out = [];
51
+ for (const pattern of DECLARATION_PATTERNS) {
52
+ for (const match of line.matchAll(pattern)) out.push(match[1]);
53
+ }
54
+ for (const match of line.matchAll(EXPORT_LIST)) {
55
+ out.push(...exportListNames(match[1]));
56
+ }
57
+ return out;
58
+ }
59
+
60
+ /** Hunk bodies only, so `+++`/`---` headers never contribute. */
61
+ function scanDiff(diff) {
62
+ const found = new Set();
63
+ const files = [];
64
+ let inHunk = false;
65
+ for (const line of diff.split('\n')) {
66
+ if (line.startsWith('diff --git ')) {
67
+ inHunk = false;
68
+ continue;
69
+ }
70
+ if (!inHunk) {
71
+ const header = NEW_FILE_HEADER.exec(line);
72
+ if (header && !files.includes(header[1])) files.push(header[1]);
73
+ if (line.startsWith('@@')) inHunk = true;
74
+ continue;
75
+ }
76
+ for (const name of symbolsOnLine(changedCode(line))) found.add(name);
77
+ }
78
+ return { found, files };
79
+ }
80
+
81
+ /** The code of a `+`/`-` hunk line; `''` for context and comment-only lines. */
82
+ function changedCode(line) {
83
+ const body = line.slice(1);
84
+ if (!/^[+-]/.test(line) || COMMENT_LINE.test(body)) return '';
85
+ return body;
86
+ }
87
+
88
+ /** Longest first: short names grep noisily. */
89
+ function extractChangedSymbols(diff, maxSymbols = CALLER_CAPS.maxSymbols) {
90
+ const { found, files } = scanDiff(diff);
91
+ const ranked = [...found].sort(
92
+ (a, b) => b.length - a.length || a.localeCompare(b),
93
+ );
94
+ return {
95
+ symbols: ranked.slice(0, maxSymbols),
96
+ dropped: ranked.slice(maxSymbols),
97
+ files,
98
+ };
99
+ }
100
+
101
+ function callerGrepArgs(symbol, headRef, files) {
102
+ return [
103
+ 'grep',
104
+ '-n',
105
+ '-w',
106
+ '-F',
107
+ '-e',
108
+ symbol,
109
+ headRef,
110
+ '--',
111
+ '.',
112
+ ...files.map((file) => `:(exclude)${file}`),
113
+ ];
114
+ }
115
+
116
+ function formatHit(raw, headRef) {
117
+ const prefix = `${headRef}:`;
118
+ const rest = raw.startsWith(prefix) ? raw.slice(prefix.length) : raw;
119
+ const match = /^(.*?):(\d+):(.*)$/.exec(rest);
120
+ return match ? `${match[1]}:${match[2]}: ${match[3].trim()}` : null;
121
+ }
122
+
123
+ function readHits(result, headRef) {
124
+ if (result.status === 1) return [];
125
+ if (result.status !== 0) return null;
126
+ return result.stdout
127
+ .split('\n')
128
+ .map((raw) => formatHit(raw, headRef))
129
+ .filter((hit) => hit !== null);
130
+ }
131
+
132
+ function lookUpCallers({ symbols, files, headRef, cwd, gitSpawnFn, caps }) {
133
+ const sections = [];
134
+ const dropped = [];
135
+ let used = 0;
136
+ for (const symbol of symbols) {
137
+ const hits = readHits(
138
+ gitSpawnFn(cwd, ...callerGrepArgs(symbol, headRef, files)),
139
+ headRef,
140
+ );
141
+ if (hits === null) {
142
+ dropped.push(`${symbol} (lookup failed)`);
143
+ continue;
144
+ }
145
+ if (hits.length === 0) continue;
146
+ const kept = hits.slice(0, caps.maxLinesPerSymbol);
147
+ const section = `## ${symbol}\n${kept.join('\n')}\n`;
148
+ if (used + section.length > caps.maxChars) {
149
+ dropped.push(`${symbol} (total cap)`);
150
+ continue;
151
+ }
152
+ if (hits.length > kept.length) {
153
+ dropped.push(`${symbol} (${hits.length - kept.length} lines over cap)`);
154
+ }
155
+ sections.push(section);
156
+ used += section.length;
157
+ }
158
+ return { sections, dropped };
159
+ }
160
+
161
+ function buildCallersContext({
162
+ diff,
163
+ headRef,
164
+ cwd,
165
+ gitSpawnFn,
166
+ caps = CALLER_CAPS,
167
+ }) {
168
+ const extracted = extractChangedSymbols(diff, caps.maxSymbols);
169
+ const { sections, dropped } = lookUpCallers({
170
+ symbols: extracted.symbols,
171
+ files: extracted.files,
172
+ headRef,
173
+ cwd,
174
+ gitSpawnFn,
175
+ caps,
176
+ });
177
+ const body =
178
+ sections.length > 0
179
+ ? sections.join('\n')
180
+ : '(no references to changed symbols outside the changed files)\n';
181
+ return {
182
+ body,
183
+ dropped: [
184
+ ...extracted.dropped.map((symbol) => `${symbol} (symbol cap)`),
185
+ ...dropped,
186
+ ],
187
+ };
188
+ }
189
+
190
+ /**
191
+ * The instruction plus `<callers>` block at `deep` ('' below it), and a
192
+ * degradation `reason` when a cap or lookup left a symbol unchecked.
193
+ * `caps` overrides the 20 / 25 / 30,000 limits (tests).
194
+ */
195
+ export function buildCallersSection({
196
+ diff,
197
+ input,
198
+ cwd,
199
+ gitSpawnFn,
200
+ caps = CALLER_CAPS,
201
+ }) {
202
+ if (!CALLER_CONTEXT_DEPTHS.includes(normalizeDepth(input.depth))) {
203
+ return { text: '', reason: null };
204
+ }
205
+ const { body, dropped } = buildCallersContext({
206
+ diff,
207
+ headRef: input.headRef,
208
+ cwd,
209
+ gitSpawnFn,
210
+ caps,
211
+ });
212
+ return {
213
+ text: `\n${CALLERS_INSTRUCTION}\n\n<callers>\n${body}</callers>\n`,
214
+ reason:
215
+ dropped.length > 0
216
+ ? `callers block incomplete; not checked: ${dropped.join(', ')}`
217
+ : null,
218
+ };
219
+ }
@@ -12,6 +12,9 @@
12
12
  * A missing CLI throws at construction (the chain entry is optional). A
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
+ * A review that reached a verdict still records what it did not check — a
16
+ * truncated diff, a capped `<callers>` block (depth `deep` only) — beside
17
+ * its findings.
15
18
  *
16
19
  * @typedef {import('./types.js').Finding} Finding
17
20
  * @typedef {import('./types.js').ReviewInput} ReviewInput
@@ -25,6 +28,7 @@ import path from 'node:path';
25
28
  import { spawnCaptureAsync } from '../../child-exec.js';
26
29
  import { gitSpawn } from '../../git-utils.js';
27
30
  import { PROJECT_ROOT } from '../../project-root.js';
31
+ import { buildCallersSection } from './callers-context.js';
28
32
  import {
29
33
  clip,
30
34
  FINDINGS_SCHEMA_JSON,
@@ -51,7 +55,7 @@ const CLAUDE_ARGS = Object.freeze([
51
55
  const AUTH_ARGS = Object.freeze(['auth', 'status', '--json']);
52
56
  const INVOKE_TIMEOUT_MS = 10 * 60 * 1000;
53
57
  const AUTH_TIMEOUT_MS = 15 * 1000;
54
- /** Larger diffs are truncated; the reviewer is told so. */
58
+ /** Larger diffs are truncated; the reviewer is told so and a degradation is recorded. */
55
59
  const MAX_DIFF_CHARS = 200_000;
56
60
  const DEGRADATION_BASE = Object.freeze({
57
61
  tool: 'code-review',
@@ -67,19 +71,45 @@ const PROMPT_HEAD =
67
71
  'caller. Do not report style, naming, refactoring ideas, missing tests or ' +
68
72
  'anything you would merge anyway. For each problem give the file, the ' +
69
73
  'line in the new version, why it is wrong, and how to show it fails (an ' +
70
- 'input, command or test that exposes it).\n\n' +
74
+ 'input, command or test that exposes it). A `shortcut:` comment naming ' +
75
+ 'its ceiling and trigger is a decision, not a finding, unless this diff ' +
76
+ 'itself crosses the ceiling.\n\n' +
71
77
  'The diff below is authoritative — files on disk may not reflect it. ' +
72
78
  'Answer with a JSON object of this exact shape, no prose around it:\n\n' +
73
79
  '{"findings":[{"title":"...","body":"Why it is wrong: ... How to show it ' +
74
80
  'fails: ...","file":"...","line":1,"category":"bug"}]}\n\n' +
75
81
  'Emit {"findings":[]} if there is nothing you would block the merge for.\n\n';
76
82
 
83
+ /**
84
+ * The truncation degradation reason, or null when the diff fits: the
85
+ * unreviewed character count and the files whose first header is past the cut.
86
+ *
87
+ * @param {string} diff
88
+ * @returns {string|null}
89
+ */
90
+ function truncationReason(diff) {
91
+ if (diff.length <= MAX_DIFF_CHARS) return null;
92
+ const firstHeader = new Map();
93
+ for (const match of diff.matchAll(/^\+\+\+ b\/(.+)$/gm)) {
94
+ if (!firstHeader.has(match[1])) firstHeader.set(match[1], match.index);
95
+ }
96
+ const unreviewedFiles = [...firstHeader.values()].filter(
97
+ (index) => index >= MAX_DIFF_CHARS,
98
+ ).length;
99
+ return (
100
+ `diff truncated at ${MAX_DIFF_CHARS} characters: ` +
101
+ `${diff.length - MAX_DIFF_CHARS} characters and ${unreviewedFiles} ` +
102
+ 'file(s) not reviewed'
103
+ );
104
+ }
105
+
77
106
  /**
78
107
  * @param {ReviewInput} input
79
108
  * @param {string} diff
109
+ * @param {string} callers - the `<callers>` section, or '' below `deep`.
80
110
  * @returns {string}
81
111
  */
82
- function buildPrompt(input, diff) {
112
+ function buildPrompt(input, diff, callers) {
83
113
  const truncated = diff.length > MAX_DIFF_CHARS;
84
114
  const body = truncated ? diff.slice(0, MAX_DIFF_CHARS) : diff;
85
115
  const note = truncated
@@ -89,7 +119,7 @@ function buildPrompt(input, diff) {
89
119
  .replace('{headRef}', input.headRef)
90
120
  .replace('{ticketId}', String(input.ticketId))
91
121
  .replace('{depthDirective}', renderDepthDirective(input.depth));
92
- return `${head}<diff>\n${body}${note}\n</diff>\n`;
122
+ return `${head}<diff>\n${body}${note}\n</diff>\n${callers}`;
93
123
  }
94
124
 
95
125
  /**
@@ -222,6 +252,12 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
222
252
  /** @type {GateDegradation[]} */
223
253
  let degradations = [];
224
254
 
255
+ /** Record a not-checked slice without replacing the findings. */
256
+ function noteDegradation(reason) {
257
+ degradations.push({ ...DEGRADATION_BASE, reason });
258
+ deps.logger?.warn?.(`[code-review] Not checked: ${reason}.`);
259
+ }
260
+
225
261
  function settle(verdict) {
226
262
  if (!('reason' in verdict)) return verdict.findings;
227
263
  degradations.push({ ...DEGRADATION_BASE, reason: verdict.reason });
@@ -236,8 +272,20 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
236
272
  const diff = readDiff(gitSpawnFn, input);
237
273
  if ('reason' in diff) return settle(diff);
238
274
  if (diff.text.trim().length === 0) return [];
275
+ const truncation = truncationReason(diff.text);
276
+ if (truncation) noteDegradation(truncation);
277
+ const callers = buildCallersSection({
278
+ diff: diff.text,
279
+ input,
280
+ cwd: PROJECT_ROOT,
281
+ gitSpawnFn,
282
+ });
283
+ if (callers.reason) noteDegradation(callers.reason);
239
284
  return settle(
240
- await reviewInTempDir(buildPrompt(input, diff.text), runDeps),
285
+ await reviewInTempDir(
286
+ buildPrompt(input, diff.text, callers.text),
287
+ runDeps,
288
+ ),
241
289
  );
242
290
  },
243
291
  getDegradations() {
@@ -14,9 +14,9 @@
14
14
  import fs from 'node:fs';
15
15
  import path from 'node:path';
16
16
  import { spawnCaptureAsync, spawnChild } from '../../child-exec.js';
17
+ import { resolveAgentrcRoot } from '../../config/git-roots.js';
17
18
  import { resolvedTempRoot } from '../../config/temp-paths.js';
18
19
  import { resolveConfig } from '../../config-resolver.js';
19
- import { PROJECT_ROOT } from '../../project-root.js';
20
20
  import { PROVIDER_SEVERITY_MAP } from './provider-severity.js';
21
21
  import { renderDepthDirective } from './review-depth.js';
22
22
 
@@ -130,7 +130,7 @@ export async function invokeCodexExec(args, deps = {}) {
130
130
  const execArgs = ['exec', '--sandbox', 'read-only', '--ephemeral'];
131
131
  execArgs.push('--output-schema', schemaPath, '-o', lastMessagePath, '-');
132
132
  const result = await spawnCaptureAsync('codex', execArgs, {
133
- cwd: deps.cwd ?? PROJECT_ROOT,
133
+ cwd: deps.cwd ?? resolveAgentrcRoot(),
134
134
  input: buildReviewPrompt(args),
135
135
  shell: IS_WINDOWS,
136
136
  timeout: INVOKE_TIMEOUT_MS,
@@ -0,0 +1,96 @@
1
+ /**
2
+ * review-providers/llm-review.js — the default chain's host-portable LLM
3
+ * review: the first available of `code-review` (`claude --print`) then
4
+ * `codex` (`codex exec`), chosen once at construction. First-available, not
5
+ * both-optional, so a host with both CLIs pays for one LLM review per Story.
6
+ * Neither CLI throws, so an `optional: true` entry skips with one warning.
7
+ *
8
+ * @typedef {import('./types.js').ReviewProvider} ReviewProvider
9
+ * @typedef {import('./degraded-gates.js').GateDegradation} GateDegradation
10
+ */
11
+
12
+ import { REVIEW_PROVIDER_CLIS } from '../../config/review-provider-clis.js';
13
+ import { createCodeReviewProviderForRegistry } from './code-review.js';
14
+ import {
15
+ CODEX_REMEDIATIONS,
16
+ createCodexProvider,
17
+ defaultProbeCodexCommand,
18
+ } from './codex.js';
19
+ import { probeClaudeCli } from './security-review.js';
20
+
21
+ /** The delegate each CLI serves: what it probes and what it runs. */
22
+ const DELEGATE_BY_CLI = Object.freeze({
23
+ claude: { name: 'code-review', cli: 'claude', runs: 'claude --print' },
24
+ codex: { name: 'codex', cli: 'codex', runs: 'codex exec' },
25
+ });
26
+
27
+ /**
28
+ * @returns {Error}
29
+ */
30
+ export function buildLlmReviewUnavailableError() {
31
+ return new Error(
32
+ '[ReviewProviderFactory] codeReview provider "llm-review" found neither ' +
33
+ 'the `claude` CLI nor the `codex` CLI on PATH. Install the Claude Code ' +
34
+ 'CLI so `claude --version` succeeds. Or: ' +
35
+ `${CODEX_REMEDIATIONS.install} ${CODEX_REMEDIATIONS.fallback}`,
36
+ );
37
+ }
38
+
39
+ /**
40
+ * The first delegate whose CLI answers, or null.
41
+ *
42
+ * @param {{ probeClaudeFn?: () => boolean, probeCodexFn?: () => boolean }} [deps]
43
+ * @returns {(typeof DELEGATE_BY_CLI)[keyof typeof DELEGATE_BY_CLI] | null}
44
+ */
45
+ export function resolveLlmReviewDelegate(deps = {}) {
46
+ const probes = {
47
+ claude: deps.probeClaudeFn ?? probeClaudeCli,
48
+ codex: deps.probeCodexFn ?? defaultProbeCodexCommand,
49
+ };
50
+ const cli = REVIEW_PROVIDER_CLIS['llm-review'].find((c) => probes[c]());
51
+ return DELEGATE_BY_CLI[cli] ?? null;
52
+ }
53
+
54
+ /**
55
+ * @param {{
56
+ * probeClaudeFn?: () => boolean,
57
+ * probeCodexFn?: () => boolean,
58
+ * createCodeReviewFn?: (deps: object) => ReviewProvider,
59
+ * createCodexFn?: (deps: object) => ReviewProvider,
60
+ * logger?: { info?: Function, warn?: Function },
61
+ * }} [deps] - the `create*Fn` seams build the chosen delegate; it is handed
62
+ * a pre-passed probe so the CLI is not probed twice.
63
+ * @returns {ReviewProvider & { delegate: string, getDegradations: () => GateDegradation[] }}
64
+ */
65
+ export function createLlmReviewProvider(deps = {}) {
66
+ const chosen = resolveLlmReviewDelegate(deps);
67
+ if (!chosen) throw buildLlmReviewUnavailableError();
68
+ const build =
69
+ chosen.name === 'code-review'
70
+ ? (deps.createCodeReviewFn ?? createCodeReviewProviderForRegistry)
71
+ : (deps.createCodexFn ?? createCodexProvider);
72
+ const delegate = build({ probeFn: () => true, logger: deps.logger });
73
+ const logger = deps.logger;
74
+
75
+ return {
76
+ delegate: chosen.name,
77
+ async runReview(input) {
78
+ logger?.info?.(
79
+ `[llm-review] Reviewing through ${chosen.name} (${chosen.runs}).`,
80
+ );
81
+ return delegate.runReview(input);
82
+ },
83
+ getDegradations() {
84
+ return typeof delegate.getDegradations === 'function'
85
+ ? delegate.getDegradations()
86
+ : [];
87
+ },
88
+ };
89
+ }
90
+
91
+ /**
92
+ * @returns {ReviewProvider}
93
+ */
94
+ export function createLlmReviewProviderForRegistry() {
95
+ return createLlmReviewProvider();
96
+ }
@@ -13,7 +13,7 @@ import { isIgnoredByGlobs } from '../../maintainability-utils.js';
13
13
  * scoring nothing would silently retire the dimension.
14
14
  *
15
15
  * @param {{ resolveConfigFn?: typeof resolveConfig, getQualityFn?: typeof getQuality }} [deps]
16
- * @returns {string[]} minimatch patterns; `[]` when unset or unresolvable.
16
+ * @returns {string[]} picomatch patterns; `[]` when unset or unresolvable.
17
17
  */
18
18
  export function resolveMaintainabilityIgnoreGlobs({
19
19
  resolveConfigFn = resolveConfig,
@@ -29,7 +29,7 @@ export function resolveMaintainabilityIgnoreGlobs({
29
29
 
30
30
  /**
31
31
  * Matches through `isIgnoredByGlobs`, the same rule the baseline uses; a
32
- * local `minimatch` would let the two surfaces disagree.
32
+ * local `picomatch` would let the two surfaces disagree.
33
33
  *
34
34
  * @param {string[]} files
35
35
  * @param {string[]} ignoreGlobs
@@ -9,7 +9,6 @@
9
9
  * @typedef {import('./types.js').ReviewProvider} ReviewProvider
10
10
  */
11
11
 
12
- import path from 'node:path';
13
12
  import { POOL_SERIAL_THRESHOLD, runOnPool } from '../../cpu-pool.js';
14
13
  import { gitSpawn } from '../../git-utils.js';
15
14
  import {
@@ -17,6 +16,7 @@ import {
17
16
  classifyReport,
18
17
  } from '../../maintainability-engine.js';
19
18
  import { PROJECT_ROOT } from '../../project-root.js';
19
+ import { isScorableSourceFile } from '../../source-extensions.js';
20
20
  import { transpileForReport } from '../../transpile.js';
21
21
  import {
22
22
  resolveMaintainabilityIgnoreGlobs,
@@ -28,11 +28,9 @@ const MAINTAINABILITY_REPORT_WORKER_URL = new URL(
28
28
  import.meta.url,
29
29
  );
30
30
 
31
- /** Below this JS-file count scoring runs in-process; at or above, on the worker pool. */
31
+ /** Below this scorable-file count scoring runs in-process; at or above, on the worker pool. */
32
32
  export const SERIAL_THRESHOLD = POOL_SERIAL_THRESHOLD;
33
33
 
34
- const JS_MAINTAINABILITY_EXTS = new Set(['.js', '.mjs', '.cjs']);
35
-
36
34
  /**
37
35
  * Read the file at `headRef`, never from disk: close runs from the main
38
36
  * checkout, where disk holds the BASE content. `null` when absent at head.
@@ -142,10 +140,6 @@ function accumulateClassified(results, classified) {
142
140
  if (mediumFinding) results.mediumFindings.push(mediumFinding);
143
141
  }
144
142
 
145
- function isJsMaintainabilityFile(relPath) {
146
- return JS_MAINTAINABILITY_EXTS.has(path.extname(relPath));
147
- }
148
-
149
143
  /**
150
144
  * Pooled at or above `serialThreshold`. An injected `reportFn` forces the
151
145
  * serial path (a closure cannot cross the worker boundary).
@@ -174,11 +168,11 @@ export async function analyzeChangedFiles(
174
168
  mediumFindings: [],
175
169
  };
176
170
 
177
- const jsFiles = changedFiles.filter(isJsMaintainabilityFile);
178
- results.jsFiles = jsFiles.length;
179
- if (jsFiles.length === 0) return results;
171
+ const scorableFiles = changedFiles.filter(isScorableSourceFile);
172
+ results.jsFiles = scorableFiles.length;
173
+ if (scorableFiles.length === 0) return results;
180
174
 
181
- const sources = jsFiles.map((relPath) =>
175
+ const sources = scorableFiles.map((relPath) =>
182
176
  headRef == null ? '' : readHeadSourceFn(relPath, headRef, gitSpawnFn),
183
177
  );
184
178
 
@@ -186,9 +180,9 @@ export async function analyzeChangedFiles(
186
180
  reportFn ?? ((source, relPath) => scoreSourceReport(source, relPath));
187
181
  const customReportFn = reportFn != null;
188
182
 
189
- if (jsFiles.length < serialThreshold || customReportFn) {
190
- for (let i = 0; i < jsFiles.length; i += 1) {
191
- const relPath = jsFiles[i];
183
+ if (scorableFiles.length < serialThreshold || customReportFn) {
184
+ for (let i = 0; i < scorableFiles.length; i += 1) {
185
+ const relPath = scorableFiles[i];
192
186
  const source = sources[i];
193
187
  if (source == null) continue;
194
188
  accumulateClassified(
@@ -204,10 +198,10 @@ export async function analyzeChangedFiles(
204
198
 
205
199
  // Send head content (not a disk path) so the worker scores what the serial path does.
206
200
  const poolItems = [];
207
- const poolIndex = []; // poolItems[k] corresponds to jsFiles[poolIndex[k]]
208
- for (let i = 0; i < jsFiles.length; i += 1) {
201
+ const poolIndex = []; // poolItems[k] corresponds to scorableFiles[poolIndex[k]]
202
+ for (let i = 0; i < scorableFiles.length; i += 1) {
209
203
  if (sources[i] == null) continue;
210
- poolItems.push({ source: sources[i], label: jsFiles[i] });
204
+ poolItems.push({ source: sources[i], label: scorableFiles[i] });
211
205
  poolIndex.push(i);
212
206
  }
213
207
  if (poolItems.length === 0) return results;
@@ -217,7 +211,7 @@ export async function analyzeChangedFiles(
217
211
  poolItems,
218
212
  );
219
213
  for (let k = 0; k < poolIndex.length; k += 1) {
220
- const relPath = jsFiles[poolIndex[k]];
214
+ const relPath = scorableFiles[poolIndex[k]];
221
215
  const poolEntry = poolResults[k];
222
216
  // A pool error or null report drops the file, as a serial throw does.
223
217
  if (!poolEntry || poolEntry.__cpuPoolError || poolEntry.report == null) {
@@ -21,7 +21,8 @@ const DEPTH_DIRECTIVES = Object.freeze({
21
21
  'Review depth: DEEP. Cover all review pillars at full thoroughness, then ' +
22
22
  'make a second adversarial pass over the diff specifically hunting for ' +
23
23
  'integration regressions and security-relevant edges before finalizing ' +
24
- 'findings.',
24
+ 'findings. Check every caller in the callers block against the new ' +
25
+ 'signature or shape.',
25
26
  });
26
27
 
27
28
  /**
@@ -30,7 +31,7 @@ const DEPTH_DIRECTIVES = Object.freeze({
30
31
  * @param {unknown} depth
31
32
  * @returns {ReviewDepth}
32
33
  */
33
- function normalizeDepth(depth) {
34
+ export function normalizeDepth(depth) {
34
35
  return depth === 'light' || depth === 'deep' ? depth : 'standard';
35
36
  }
36
37
 
@@ -18,6 +18,7 @@ import { DEFAULT_REVIEW_PROVIDERS } from '../../config/review-chain-default.js';
18
18
  import { createCodeReviewProviderForRegistry } from './code-review.js';
19
19
  import { createCodexProviderForRegistry } from './codex.js';
20
20
  import { mergeChainDegradations } from './degraded-gates.js';
21
+ import { createLlmReviewProviderForRegistry } from './llm-review.js';
21
22
  import { createNativeProviderForRegistry } from './native.js';
22
23
  import { createSecurityReviewProviderForRegistry } from './security-review.js';
23
24
  import { createUltrareviewProviderForRegistry } from './ultrareview.js';
@@ -26,6 +27,7 @@ import { createUltrareviewProviderForRegistry } from './ultrareview.js';
26
27
  const INLINE_PROVIDERS = Object.freeze({
27
28
  'code-review': createCodeReviewProviderForRegistry,
28
29
  codex: createCodexProviderForRegistry,
30
+ 'llm-review': createLlmReviewProviderForRegistry,
29
31
  native: createNativeProviderForRegistry,
30
32
  'security-review': createSecurityReviewProviderForRegistry,
31
33
  });
@@ -10,6 +10,7 @@
10
10
  */
11
11
 
12
12
  import { spawnSync } from 'node:child_process';
13
+ import { resolveAgentrcRoot } from '../../config/git-roots.js';
13
14
  import { parseProviderFindings } from './parse-findings.js';
14
15
  import { PROVIDER_SEVERITY_MAP } from './provider-severity.js';
15
16
  import { renderDepthDirective } from './review-depth.js';
@@ -118,12 +119,16 @@ export function buildSecurityReviewPrompt(input) {
118
119
  }
119
120
 
120
121
  /**
122
+ * Spawns in the reviewed checkout: the tree this process judges.
123
+ *
121
124
  * @param {ReviewInput} input
125
+ * @param {typeof spawnSync} [spawnFn]
122
126
  * @returns {{ status: number, stdout: string, stderr: string }}
123
127
  */
124
- function defaultInvokeSecurityReview(input) {
128
+ function defaultInvokeSecurityReview(input, spawnFn = spawnSync) {
125
129
  const prompt = buildSecurityReviewPrompt(input);
126
- const result = spawnSync('claude', ['--print', prompt], {
130
+ const result = spawnFn('claude', ['--print', prompt], {
131
+ cwd: resolveAgentrcRoot(),
127
132
  encoding: 'utf-8',
128
133
  shell: process.platform === 'win32',
129
134
  timeout: 10 * 60 * 1000,
@@ -155,6 +160,7 @@ export function buildUnparseableFallbackFinding() {
155
160
  * @param {{
156
161
  * probeFn?: () => boolean,
157
162
  * invokeFn?: (input: ReviewInput) => { status: number, stdout: string, stderr: string },
163
+ * spawnFn?: Function,
158
164
  * logger?: { info?: Function, warn?: Function, error?: Function },
159
165
  * }} [deps]
160
166
  * @returns {ReviewProvider}
@@ -164,7 +170,9 @@ export function createSecurityReviewProvider(deps = {}) {
164
170
  if (!probeFn()) {
165
171
  throw buildSecurityReviewUnavailableError();
166
172
  }
167
- const invokeFn = deps.invokeFn ?? defaultInvokeSecurityReview;
173
+ const invokeFn =
174
+ deps.invokeFn ??
175
+ ((input) => defaultInvokeSecurityReview(input, deps.spawnFn));
168
176
  const logger = deps.logger;
169
177
 
170
178
  return {
@@ -31,6 +31,7 @@ import {
31
31
  import { getQuality } from '../../config-resolver.js';
32
32
  import { gitSync as defaultGitSync } from '../../git-utils.js';
33
33
  import { Logger as DefaultLogger } from '../../Logger.js';
34
+ import { isScorableSourceFile } from '../../source-extensions.js';
34
35
  import {
35
36
  currentBranch,
36
37
  listChangedFiles,
@@ -44,8 +45,6 @@ const KIND = 'maintainability';
44
45
  /** Matches the drift detector's maintainability default tolerance. */
45
46
  const DEFAULT_TOLERANCE = 0.5;
46
47
 
47
- const SCORABLE = /\.(?:m?[jt]sx?)$/i;
48
-
49
48
  /**
50
49
  * Skips that fire before any scoring, so `ran: false` means exactly "a guard
51
50
  * stopped this"; outcome reasons are deliberately absent.
@@ -323,7 +322,7 @@ export async function runBaselineUpwardWriteback({
323
322
  baseBranch: resolveScopeBase({ workTree, git, baseBranch }),
324
323
  storyBranch,
325
324
  git,
326
- }).filter((file) => SCORABLE.test(file));
325
+ }).filter(isScorableSourceFile);
327
326
 
328
327
  const writePath = resolveWritePath({ cwd: workTree });
329
328
  const relPath = path.relative(workTree, writePath).split(path.sep).join('/');