@navels/neal 0.3.3 → 0.4.0

package/dist/neal/adjudicator/execute.js

@@ -3,6 +3,7 @@ import { runCoderResponseRound, runReviewerRound } from '../agents.js';
 import { readOnlyReviewerNeedsInlinedDiff } from '../context/inline-review-context.js';
 import { buildAndPersistReviewerContextPacket } from '../context/reviewer-context.js';
 import { getReviewStuckWindow } from '../config.js';
+import { getDiffForRangePaths } from '../git.js';
 import { EXECUTE_FINALIZATION_PHASE } from '../execute-finalization.js';
 import { classifyAlreadySatisfiedTopLevelScopeAcceptance, classifyEmptyDerivedParentAdvance, getExecutionPlanPath, getParentScopeLabel, renderRecentAcceptedScopesSummary, } from '../scopes.js';
 import { getScopeReviewerScratchDir } from '../storage-paths.js';
@@ -297,6 +298,11 @@ export async function runExecuteReviewerAdjudication(args) {
     const inlinedRangeDiff = readOnlyReviewerNeedsInlinedDiff(args.state.agentConfig.reviewer)
         ? await args.getDiffForRange(args.state.cwd, args.state.baseCommit, headCommit)
         : null;
+    const earlierScopeChanges = await collectEarlierScopeChanges({
+        state: args.state,
+        changedFiles,
+        getDiffForRangePaths: args.getDiffForRangePaths ?? getDiffForRangePaths,
+    });
     const reviewerResult = await (args.runReviewerRound ?? runReviewerRound)({
         reviewer: args.state.agentConfig.reviewer,
         // Resume the reviewer's own session. The handle persists across review
@@ -322,6 +328,7 @@ export async function runExecuteReviewerAdjudication(args) {
         scratchDir,
         reviewerContext: await buildAndPersistReviewerContextPacket({ state: args.state }),
         inlinedRangeDiff,
+        earlierScopeChanges,
         unattended: args.state.unattended,
         logger: args.logger,
     });
@@ -334,6 +341,37 @@ export async function runExecuteReviewerAdjudication(args) {
         reviewerResult,
     };
 }
+// Files in the current scope's diff that an earlier accepted scope also
+// changed, each paired with that earlier scope's diff restricted to the file.
+// The reviewer session is the only long-lived memory across scopes, and its
+// record of an earlier scope is the coder's summary; this turns "scope 3's
+// file moved during scope 6" into something it reads instead of something it
+// has to remember. Only accepted scopes count, and a scope replaced by a
+// derived plan is skipped because its work was reset. Scopes with no
+// recorded commit range are skipped.
+export async function collectEarlierScopeChanges(args) {
+    const currentFiles = new Set(args.changedFiles);
+    const changes = [];
+    for (const scope of args.state.completedScopes) {
+        if (scope.result !== 'accepted' || scope.replacedByDerivedPlanPath || !scope.baseCommit || !scope.finalCommit) {
+            continue;
+        }
+        for (const file of scope.changedFiles) {
+            if (!currentFiles.has(file)) {
+                continue;
+            }
+            const diff = await args.getDiffForRangePaths(args.state.cwd, scope.baseCommit, scope.finalCommit, [file]);
+            changes.push({
+                file,
+                scopeNumber: scope.number,
+                baseCommit: scope.baseCommit,
+                finalCommit: scope.finalCommit,
+                diff,
+            });
+        }
+    }
+    return changes;
+}
 function classifyReviewerParentAdvance(args) {
     if (args.meaningfulProgressAction !== 'advance_parent' && args.meaningfulProgressAction !== 'block_for_operator') {
         return null;

package/dist/neal/agents/structured-json.js

@@ -1,6 +1,16 @@
 import { NealProviderError } from '../providers/types.js';
 const SUMMARY_MAX_LENGTH = 800;
-const ORIGINAL_RESPONSE_MAX_LENGTH = 12000;
+// Bound on the original response echoed into a repair prompt. A real
+// `neal review` payload with nine findings ended at ~14,400 chars, so the old
+// 12,000 cap handed the repair model a JSON object cut off mid-finding and it
+// invented a "truncated" warning and dropped a finding (#11). 60,000 leaves
+// about 4x headroom over that payload while still bounding a runaway response.
+const ORIGINAL_RESPONSE_MAX_LENGTH = 60000;
+// Any fenced block, with or without a language label, that is the only
+// non-whitespace content of a response. Accepted with raw-JSON tolerance
+// because repair turns render "raw whole-response JSON object" as a ```json
+// fence and that payload is otherwise complete.
+const GENERIC_OPENING_FENCE_PATTERN = /^[ \t]*```[ \t]*[A-Za-z0-9_-]*[ \t]*$/;
 const NEAL_JSON_OPENING_FENCE_PATTERN = /^[ \t]*```[ \t]*neal-json[ \t]*$/;
 const CLOSING_FENCE_PATTERN = /^[ \t]*```[ \t]*$/;
 export function buildStructuredJsonPrompt(basePrompt, protocol) {
@@ -67,12 +77,16 @@ export function guardStructuredJsonOutputFormatLines(lines, label) {
 export function extractStructuredJsonPayload(assistantText) {
     const blocks = findNealJsonBlocks(assistantText);
     if (blocks.length > 1) {
+        // Still a failure, but hand the first block's JSON to the repair prompt so
+        // the repair model works from the real payload instead of a truncated
+        // transcript. The first block is the one the prompt contract asked for;
+        // later blocks are usually echoes or rewrites of it (#11).
         return {
             ok: false,
             errorKind: 'multiple_control_blocks',
             errorSummary: `Expected exactly one final neal-json control block, but found ${blocks.length}.`,
             prose: assistantText.trim(),
-            rawJson: null,
+            rawJson: blocks[0].rawJson,
         };
     }
     if (blocks.length === 1) {
@@ -96,6 +110,15 @@ export function extractStructuredJsonPayload(assistantText) {
         });
     }
     const trimmed = assistantText.trim();
+    const loneFencedJson = extractLoneFencedJson(trimmed);
+    if (loneFencedJson !== null) {
+        return parseExtractedJson({
+            source: 'raw-json',
+            prose: '',
+            rawJson: loneFencedJson,
+            malformedSummaryPrefix: 'The fenced JSON response was invalid',
+        });
+    }
     if (!looksLikeRawJsonObject(trimmed)) {
         return {
             ok: false,
@@ -524,6 +547,24 @@ function parseExtractedJson(args) {
 function looksLikeRawJsonObject(trimmed) {
     return trimmed.startsWith('{') || trimmed.startsWith('[');
 }
+// Returns the inner text when the whole (trimmed) response is exactly one
+// fenced block: an opening fence line, content with no fence lines inside, and
+// a closing fence as the last line. Null otherwise, including when anything
+// sits outside the fence; that case keeps its existing error.
+function extractLoneFencedJson(trimmed) {
+    const lines = trimmed.split(/\r?\n/);
+    if (lines.length < 3) {
+        return null;
+    }
+    if (!GENERIC_OPENING_FENCE_PATTERN.test(lines[0]) || !CLOSING_FENCE_PATTERN.test(lines[lines.length - 1])) {
+        return null;
+    }
+    const inner = lines.slice(1, -1);
+    if (inner.some((line) => /^[ \t]*```/.test(line))) {
+        return null;
+    }
+    return inner.join('\n');
+}
 function isJsonObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }

package/dist/neal/context/reviewer-context.js

@@ -5,6 +5,10 @@ export const REVIEWER_CONTEXT_JSON = 'REVIEWER_CONTEXT.json';
 export const REVIEWER_CONTEXT_MARKDOWN = 'REVIEWER_CONTEXT.md';
 const COMPLETED_SCOPE_LIMIT = 12;
 const FINDING_LIMIT = 24;
+// Files listed per completed scope. The full list stays in RUN_STATE.json;
+// the packet carries enough for the reviewer to see which files an earlier
+// scope owned, with an explicit count when the list is cut.
+const COMPLETED_SCOPE_CHANGED_FILE_LIMIT = 20;
 export async function buildAndPersistReviewerContextPacket(args) {
     const packet = buildReviewerContextPacket(args);
     await mkdir(args.state.runDir, { recursive: true });
@@ -23,6 +27,8 @@ export function buildReviewerContextPacket(args) {
         marker: scope.marker,
         finalCommit: scope.finalCommit,
         summary: scope.summary ?? null,
+        changedFiles: scope.changedFiles.slice(0, COMPLETED_SCOPE_CHANGED_FILE_LIMIT),
+        changedFileCount: scope.changedFiles.length,
         reviewRounds: scope.reviewRounds,
         findings: scope.findings,
         residualReviewDebt: scope.residualReviewDebt?.length ?? 0,
@@ -110,7 +116,7 @@ function buildReviewerContextCitations(state) {
 }
 export function renderReviewerContextMarkdown(packet) {
     const scopeLines = packet.completedScopes.length
-        ? packet.completedScopes.map((scope) => `- Scope ${scope.number}: ${scope.result}; marker=${scope.marker}; finalCommit=${scope.finalCommit ?? 'none'}; reviewRounds=${scope.reviewRounds}; findings=${scope.findings}; residualDebt=${scope.residualReviewDebt}; summary=${scope.summary ?? 'none'}`)
+        ? packet.completedScopes.map((scope) => `- Scope ${scope.number}: ${scope.result}; marker=${scope.marker}; finalCommit=${scope.finalCommit ?? 'none'}; reviewRounds=${scope.reviewRounds}; findings=${scope.findings}; residualDebt=${scope.residualReviewDebt}; files=${formatCompletedScopeFiles(scope)}; summary=${scope.summary ?? 'none'}`)
         : ['- none'];
     const findingLines = packet.findings.length
         ? packet.findings.map((finding) => `- ${finding.canonicalId} (${finding.id}): ${finding.severity}/${finding.status}; source=${finding.source}; files=${finding.files.join(', ') || 'none'}; claim=${finding.claim}; requiredAction=${finding.requiredAction}`)
@@ -157,6 +163,13 @@ export function renderReviewerContextMarkdown(packet) {
         ...packet.citations.map((citation) => `- ${citation.label}: ${citation.path}`),
     ].join('\n');
 }
+function formatCompletedScopeFiles(scope) {
+    if (scope.changedFiles.length === 0) {
+        return 'none';
+    }
+    const omitted = scope.changedFileCount - scope.changedFiles.length;
+    return omitted > 0 ? `${scope.changedFiles.join(', ')} (+${omitted} more)` : scope.changedFiles.join(', ');
+}
 function runIdFromDir(runDir) {
     const normalized = runDir.replace(/\/+$/, '');
     return normalized.slice(normalized.lastIndexOf('/') + 1);

package/dist/neal/git.js

@@ -197,6 +197,14 @@ export async function getDiffForRange(cwd, base, head) {
     }
     return runGit(['diff', '--find-renames', `${base}..${head}`], cwd);
 }
+// Range diff restricted to the given paths. Fixed argv with a `--` separator,
+// never a shell string, so a path can never be read as a revision or option.
+export async function getDiffForRangePaths(cwd, base, head, paths) {
+    if (base === head || paths.length === 0) {
+        return '';
+    }
+    return runGit(['diff', '--find-renames', `${base}..${head}`, '--', ...paths], cwd);
+}
 export async function getChangedFilesForRange(cwd, base, head) {
     if (base === head) {
         return [];

package/dist/neal/orchestrator/phases/review.js

@@ -1,7 +1,7 @@
 import { ReviewerRoundError } from '../../agents.js';
 import { runExecuteReviewerAdjudication, synthesizeExecuteReviewerState, } from '../../adjudicator/execute.js';
 import { assertAdjudicationTransitionSignal } from '../../adjudicator/specs.js';
-import { getChangedFilesForRange, getCommitRange, getDiffForRange, getDiffStatForRange, getHeadCommit, } from '../../git.js';
+import { getChangedFilesForRange, getCommitRange, getDiffForRange, getDiffForRangePaths, getDiffStatForRange, getHeadCommit, } from '../../git.js';
 import { writeDetail } from '../../diagnostic.js';
 import { saveState } from '../../state.js';
 import { writeExecutionArtifacts } from '../artifacts.js';
@@ -41,6 +41,7 @@ export async function runReviewPhase(state, statePath, logger) {
             getDiffStatForRange,
             getChangedFilesForRange,
             getDiffForRange,
+            getDiffForRangePaths,
         }));
         reviewerSynthesis = synthesizeExecuteReviewerState({
             state,

package/dist/neal/prompts/execute.js

@@ -1,4 +1,4 @@
-import { renderInlinedRangeDiffSection } from '../context/inline-review-context.js';
+import { renderInlinedRangeDiffSection, truncateInlineSectionBody } from '../context/inline-review-context.js';
 import { AUTONOMY_BLOCKED, AUTONOMY_DONE, AUTONOMY_SCOPE_DONE, AUTONOMY_SPLIT_PLAN, buildProgressSection, getCanonicalPlanContractLines, getDerivedPlanSectionContractLines, getExecuteScopeProgressPayloadContractLines, getProtocolMarkerArtifactProhibitionLines, getStandalonePlanPayloadSourceOfTruthLines, getTerminalMarkerArtifactBoundaryLines, getUnattendedAutonomyLines, } from './shared.js';
 import { assertPromptBuilder } from './assert-builder.js';
 import { getUserGuidanceLines } from './guidance.js';
@@ -107,6 +107,11 @@ export function buildLegacyScopePrompt(planDoc, progressText) {
         `- ${AUTONOMY_SPLIT_PLAN}`,
     ].join('\n');
 }
+export const EARLIER_SCOPE_CHANGES_SECTION_HEADING = '## Earlier-scope changes to files in this diff';
+// Rendered for every execute-scope review, with or without an overlap: a
+// tool-access reviewer can find earlier-scope history itself, and the rule
+// about what that history means must not depend on whether Neal inlined it.
+const EARLIER_SCOPE_PRESERVATION_LINE = "A change to a file that an earlier accepted scope signed off must preserve what that scope's review accepted. Weakening or removing a test, assertion, or check that an earlier scope introduced is a blocking finding unless the plan explicitly calls for it.";
 export function buildReviewerPrompt(args) {
     const spec = assertPromptBuilder('scope_reviewer', 'buildReviewerPrompt', PROMPT_MODULE_PATH);
     const primaryVariant = spec.variants.find((variant) => variant.kind === 'primary');
@@ -166,6 +171,7 @@ export function buildReviewerPrompt(args) {
         ...getFindingQualityLines(),
         ...skepticismLines,
         ...regressionLines,
+        EARLIER_SCOPE_PRESERVATION_LINE,
         ...preexistingLines,
         args.previousHeadCommit
             ? `Previous reviewer head was ${args.previousHeadCommit}. Focus especially on changes since that commit, while still considering the full current state.`
@@ -214,6 +220,30 @@ export function buildReviewerPrompt(args) {
                 }),
             ]
             : []),
+        ...(args.earlierScopeChanges && args.earlierScopeChanges.length > 0
+            ? ['', renderEarlierScopeChangesSection(args.earlierScopeChanges)]
+            : []),
+    ].join('\n');
+}
+// Earlier accepted scopes' per-file diffs for files the current diff touches
+// again. The body shares the inlined-diff bound (truncateInlineSectionBody),
+// which appends an explicit truncation marker instead of dropping content
+// silently.
+function renderEarlierScopeChangesSection(changes) {
+    const body = changes
+        .map((change) => [
+        `### ${change.file} (scope ${change.scopeNumber}, ${change.baseCommit}..${change.finalCommit})`,
+        '',
+        change.diff.trim() === '' ? '(empty diff)' : change.diff,
+    ].join('\n'))
+        .join('\n\n');
+    return [
+        EARLIER_SCOPE_CHANGES_SECTION_HEADING,
+        '',
+        'The files below were changed by an earlier accepted scope in this run and appear again in the current diff. Each entry shows what that earlier scope did to the file, so what the current scope alters is something you read here rather than something you have to remember.',
+        'Check the current diff against each entry before accepting.',
+        '',
+        truncateInlineSectionBody(body),
     ].join('\n');
 }
 function getReviewerContextLines(reviewerContext) {

package/dist/neal/prompts/specs.js

@@ -65,6 +65,7 @@ const SCOPE_REVIEWER_CONTEXT = context('ScopeReviewerPromptContext', [
     field('recentHistorySummary', 'review_history', true, 'Accepted-scope history for the active parent objective.'),
     field('reviewMarkdownPath', 'run_artifact', true, 'Review artifact that carries prior findings and coder responses.'),
     field('scratchDir', 'run_artifact', true, 'Run-local reviewer scratch directory for temporary verification artifacts.'),
+    field('earlierScopeChanges', 'repository_state', false, 'Files in the current scope diff that an earlier accepted scope also changed, each with that scope number, commit range, and per-file diff. Computed from completedScopes in run state; omitted when there is no overlap.'),
     field('accessMode', 'orchestrator_state', false, "Two-way reviewer doctrine access mode derived from the reviewer provider's structured-advisor tool access: 'tool-access' (inspect and execute) or 'read-only' (read tools only; no command execution, test runs, or scratch work). Defaults to 'tool-access' when absent."),
 ]);
 const COMPLETION_CODER_CONTEXT = context('CompletionCoderPromptContext', [
@@ -383,7 +384,7 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'scope_reviewer',
-        version: 2,
+        version: 3,
         changelog: [
             {
                 version: 1,
@@ -393,6 +394,10 @@ export const PROMPT_SPECS = [
                 version: 2,
                 renderSha: '431a75ad341a531535606af607187239a31d12cf921575eb17774b317ad639a0',
             },
+            {
+                version: 3,
+                renderSha: '4b75fab01367f0e4e263bc7635f8753e8e73c08b3ca46cf6bb6e695a67da31a4',
+            },
         ],
         role: 'reviewer',
         purpose: 'Review execute-scope results for correctness, verification coverage, and meaningful progress toward the active parent objective.',
@@ -416,11 +421,13 @@ export const PROMPT_SPECS = [
                 field('reviewMarkdownPath', 'run_artifact', true, 'Review history artifact path.'),
                 field('progressJustification', 'review_history', true, 'Coder progress-justification payload.'),
                 field('scratchDir', 'run_artifact', true, 'Run-local scratch directory for reviewer verification artifacts.'),
+                field('earlierScopeChanges', 'repository_state', false, 'Earlier accepted scopes\' per-file diffs for files the current diff touches again; absent when there is no overlap.'),
             ]),
         },
         providerVariants: SHARED_PROVIDER_VARIANTS,
         evaluationNotes: [
             'Render tests should assert reviewer prompts include shared adversarial falsification, verification skepticism, concrete finding-quality doctrine, meaningful-progress instructions, and parent-objective history.',
+            'Render tests should assert the earlier-scope preservation line renders in every cell and the earlier-scope changes section renders only when an overlap is supplied.',
             'Future fixture cases should cover cases where local correctness differs from parent-objective convergence.',
         ],
         firstMigrationPriority: 2,

package/dist/neal/providers/anthropic-claude.js

@@ -612,6 +612,7 @@ function buildClaudeCoreQueryOptions(spec) {
         ...(spec.model ? { model: spec.model } : {}),
         ...(spec.effort ? { effort: spec.effort } : {}),
         tools: spec.tools,
+        ...(spec.strictMcpConfig ? { strictMcpConfig: true } : {}),
         ...(spec.hooks ? { hooks: spec.hooks } : {}),
         // Under compat qualification only, run Claude in the SDK's isolation mode
         // (load no filesystem settings). Left unset, the SDK loads ~/.claude and any
@@ -658,6 +659,7 @@ function buildClaudeQueryOptions(args, defaultModel, claudeExecutablePath = getC
         model: args.model ?? defaultModel,
         effort: defaultEffort,
         tools: ['Read', 'Grep', 'Glob'],
+        strictMcpConfig: true,
         resumeHandle: args.resumeHandle,
         claudeExecutablePath,
         outputSchema: args.schema,
@@ -686,6 +688,7 @@ function buildClaudeJsonBlockQueryOptions(args, defaultModel, claudeExecutablePa
         model: args.model ?? defaultModel,
         effort: defaultEffort,
         tools: ['Read', 'Grep', 'Glob'],
+        strictMcpConfig: true,
         resumeHandle: args.resumeHandle,
         claudeExecutablePath,
         events: args.events,
@@ -707,6 +710,7 @@ function buildClaudeJsonBlockRepairQueryOptions(args, defaultModel, claudeExecut
         model: args.model ?? defaultModel,
         effort: defaultEffort,
         tools: [],
+        strictMcpConfig: true,
         claudeExecutablePath,
         events: args.events,
         stderrRole: 'structured-advisor',

package/dist/neal/review-findings/artifacts.js

@@ -108,45 +108,63 @@ export async function writeReviewFindingsFinal(paths, finalMarkdown, acceptedRou
         '',
     ].join('\n'));
 }
-// The reviewer/draft turns run through the Claude Agent SDK, whose sessions are
-// persisted to ~/.claude/projects but deliberately hidden from the interactive
-// `/resume` picker — they are only resumable by id. Surface those ids so an
-// operator can reopen the reviewer's full context to ask "why did it conclude
-// X". Returns [] when no handles were captured (e.g. non-SDK/test providers).
+// The draft and reviewer turns run through provider SDKs (Claude Agent SDK,
+// Codex SDK). Those sessions are persisted by each CLI but hidden from its
+// interactive resume picker, so they are only resumable by id. Surface the ids
+// with the right command per provider so an operator can reopen the full
+// context and ask "why did it conclude X". Returns [] when no handles were
+// captured (e.g. non-SDK/test providers).
 export function formatReviewResumeSection(cwd, round) {
-    const resumable = collectResumableHandles(round);
+    const resumable = collectResumableSessions(round);
     if (resumable.length === 0) {
         return [];
     }
     return [
         '## Resume Sessions',
         '',
-        `These reviewer/coder turns ran through the Claude Agent SDK. Such sessions do not appear in the interactive \`/resume\` picker, but you can resume one by id from the reviewed directory (${cwd}):`,
+        `These draft/reviewer turns ran through provider SDKs. Their sessions do not appear in the interactive resume pickers, but you can resume one by id from the reviewed directory (${cwd}):`,
         '',
-        ...resumable.map(([label, handle]) => `- ${label}: \`claude --resume ${handle}\``),
+        ...resumable.map((session) => `- ${formatResumeSessionLine(session)}`),
     ];
 }
 // Compact one-line resume hint for stdout, preferring the reviewer session
-// (the one most useful for interrogating the verdict). Null when no handle was
-// captured.
+// (the one most useful for interrogating the verdict) and skipping any session
+// whose provider has no known resume command. Null when nothing is resumable.
 export function formatReviewResumeStdoutLine(cwd, round) {
-    const reviewer = nonEmptyHandle(round.reviewSessionHandle);
-    const draft = nonEmptyHandle(round.draftSessionHandle);
-    const handle = reviewer ?? draft;
-    if (!handle) {
+    const session = collectResumableSessions(round).find((candidate) => resumeCommand(candidate) !== null);
+    if (!session) {
         return null;
     }
-    const which = reviewer ? 'reviewer' : 'draft';
-    return `Resume the ${which} session: (cd ${cwd} && claude --resume ${handle})`;
+    return `Resume the ${session.role} session: (cd ${cwd} && ${resumeCommand(session)})`;
+}
+// CLI resume commands by provider id. A provider missing here still gets its
+// session id listed, just without a command. openai-compatible never surfaces
+// handles (no session resume), so it never reaches this table.
+const RESUME_COMMANDS = {
+    'anthropic-claude': (handle) => `claude --resume ${handle}`,
+    'openai-codex': (handle) => `codex resume ${handle}`,
+};
+function resumeCommand(session) {
+    const build = session.provider ? RESUME_COMMANDS[session.provider] : undefined;
+    return build ? build(session.handle) : null;
+}
+function formatResumeSessionLine(session) {
+    const command = resumeCommand(session);
+    const who = session.provider ? `${session.label} (${session.provider})` : session.label;
+    if (command) {
+        return `${who}: \`${command}\``;
+    }
+    return `${who}: session id \`${session.handle}\` (no known resume command for this provider)`;
 }
-function collectResumableHandles(round) {
-    const entries = [
-        ['Reviewer', round.reviewSessionHandle],
-        ['Draft (coder)', round.draftSessionHandle],
+function collectResumableSessions(round) {
+    const candidates = [
+        ['reviewer', 'Reviewer', round.reviewSessionHandle, round.reviewSessionProvider],
+        ['draft', 'Draft (coder)', round.draftSessionHandle, round.draftSessionProvider],
     ];
-    return entries
-        .map(([label, handle]) => [label, nonEmptyHandle(handle)])
-        .filter((entry) => entry[1] !== null);
+    return candidates.flatMap(([role, label, handle, provider]) => {
+        const nonEmpty = nonEmptyHandle(handle);
+        return nonEmpty ? [{ role, label, handle: nonEmpty, provider: provider?.trim() ? provider : null }] : [];
+    });
 }
 function nonEmptyHandle(handle) {
     return typeof handle === 'string' && handle.trim() !== '' ? handle : null;

package/dist/neal/review-findings/prompts.js

@@ -1,4 +1,15 @@
 const DIFF_PREVIEW_LIMIT = 12000;
+// The accepted findings artifact is read by a human who was not part of the
+// review and may not know the codebase, so both the draft fields and the
+// reviewer's finalMarkdown must be written in plain language. Precision is not
+// negotiable: paths, identifiers, numbers, and SHAs stay exact; only the
+// wording around them gets simpler.
+export const REVIEW_FINDINGS_PLAIN_LANGUAGE_RULES = [
+    'Write for a human reader who was not part of this review and may not know the codebase: short sentences, one idea per sentence, everyday words.',
+    'Do not use jargon, shorthand, or undefined abbreviations when a plain phrase says the same thing. When a technical term is necessary, say in plain words what it means for the reader the first time you use it.',
+    'Keep exact file paths, identifiers, numbers, commit SHAs, and command names. Plain wording must not drop, blur, or soften a technical fact.',
+    'State each claim as what happens and why it matters. State each requiredAction as a concrete step a maintainer can take without re-reading the diff.',
+];
 export const REVIEW_FINDINGS_READ_ONLY_RULES = [
     'Do not mutate the repository.',
     'Do not make commits, amend commits, rebase, reset, squash, or rewrite history.',
@@ -65,6 +76,10 @@ export function buildReviewFindingsDraftPrompt(context, draftContext = {}) {
         '## Read-Only Rules',
         '',
         ...REVIEW_FINDINGS_READ_ONLY_RULES.map((rule) => `- ${rule}`),
+        '',
+        '## Plain Language',
+        '',
+        ...REVIEW_FINDINGS_PLAIN_LANGUAGE_RULES.map((rule) => `- ${rule}`),
         ...(reviewFindings.length > 0
             ? [
                 '',
@@ -86,19 +101,23 @@ export function buildReviewFindingsDraftPrompt(context, draftContext = {}) {
         '',
         renderContextSummary(context),
         '',
-        'Return a summary, concrete findings, and warnings only. Each finding needs severity, files, claim, evidence, and requiredAction. Do not suggest that Neal applied fixes.',
+        'Return a summary, concrete findings, and warnings only. Each finding needs severity, files, claim, evidence, and requiredAction. Write the summary, every claim, evidence, requiredAction, and warning under the Plain Language rules above. Do not suggest that Neal applied fixes.',
     ].join('\n');
 }
 export function buildReviewFindingsReviewPrompt(context, draft, round = 1) {
     return [
         '# Neal Review Findings Review',
         '',
-        `Review findings draft round ${round} for missing important findings, weak evidence, false positives, wrong severity, unclear required actions, and insufficient test or integration analysis.`,
+        `Review findings draft round ${round} for missing important findings, weak evidence, false positives, wrong severity, unclear required actions, wording that breaks the Plain Language rules below, and insufficient test or integration analysis.`,
         '',
         '## Read-Only Rules',
         '',
         ...REVIEW_FINDINGS_READ_ONLY_RULES.map((rule) => `- ${rule}`),
         '',
+        '## Plain Language',
+        '',
+        ...REVIEW_FINDINGS_PLAIN_LANGUAGE_RULES.map((rule) => `- ${rule}`),
+        '',
         '## Review Instruction',
         '',
         context.instruction,
@@ -111,7 +130,7 @@ export function buildReviewFindingsReviewPrompt(context, draft, round = 1) {
         '',
         renderDraftSummary(draft),
         '',
-        'Return verdict=`accepted` only when the final findings artifact is ready. Return verdict=`revise` with concrete findings when another draft is required. Return verdict=`blocked` only when a safe read-only review cannot be produced. Keep accepted finalMarkdown read-only and artifact-ready. Return empty strings for finalMarkdown or blockedReason when they do not apply.',
+        'Return verdict=`accepted` only when the final findings artifact is ready. Return verdict=`revise` with concrete findings when another draft is required. Return verdict=`blocked` only when a safe read-only review cannot be produced. Keep accepted finalMarkdown read-only, artifact-ready, and written under the Plain Language rules above. Return empty strings for finalMarkdown or blockedReason when they do not apply.',
     ].join('\n');
 }
 function renderContextSummary(context) {

package/dist/neal/review-findings/provider.js

@@ -41,7 +41,7 @@ class AgentReviewFindingsProviderAdapter {
             }),
             logger: this.args.logger,
         });
-        args.onSessionHandle?.(result.sessionHandle ?? null);
+        args.onSessionHandle?.(result.sessionHandle ?? null, this.args.agentConfig.coder.provider);
         return validateReviewFindingsDraft(result.structured);
     }
     async reviewDraft(args) {
@@ -94,7 +94,7 @@ class AgentReviewFindingsProviderAdapter {
                 events,
             }),
         });
-        args.onSessionHandle?.(result.sessionHandle ?? null);
+        args.onSessionHandle?.(result.sessionHandle ?? null, this.args.agentConfig.reviewer.provider);
         return validateReviewFindingsReview(result.structured);
     }
 }

package/dist/neal/review-findings/run.js

@@ -74,14 +74,16 @@ export async function runNealReviewCli(args) {
                 maxRounds,
             });
             let draftSessionHandle = null;
+            let draftSessionProvider = null;
             const draftResponse = await provider.draftFindings({
                 context,
                 round: roundNumber,
                 previousDraft,
                 reviewFindings,
                 prompt: draftPrompt,
-                onSessionHandle: (handle) => {
+                onSessionHandle: (handle, sessionProvider) => {
                     draftSessionHandle = handle;
+                    draftSessionProvider = sessionProvider ?? null;
                 },
             });
             await assertReviewReadOnlyStateUnchanged(cwd, beforeState);
@@ -97,13 +99,15 @@ export async function runNealReviewCli(args) {
             });
             const reviewPrompt = buildReviewFindingsReviewPrompt(context, draft, roundNumber);
             let reviewSessionHandle = null;
+            let reviewSessionProvider = null;
             const reviewResponse = await provider.reviewDraft({
                 context,
                 round: roundNumber,
                 draft,
                 prompt: reviewPrompt,
-                onSessionHandle: (handle) => {
+                onSessionHandle: (handle, sessionProvider) => {
                     reviewSessionHandle = handle;
+                    reviewSessionProvider = sessionProvider ?? null;
                 },
             });
             await assertReviewReadOnlyStateUnchanged(cwd, beforeState);
@@ -118,7 +122,9 @@ export async function runNealReviewCli(args) {
                 // Only record handles when captured, so artifacts stay byte-identical
                 // for non-SDK providers.
                 ...(draftSessionHandle ? { draftSessionHandle } : {}),
+                ...(draftSessionHandle && draftSessionProvider ? { draftSessionProvider } : {}),
                 ...(reviewSessionHandle ? { reviewSessionHandle } : {}),
+                ...(reviewSessionHandle && reviewSessionProvider ? { reviewSessionProvider } : {}),
             };
             rounds.push(loopRound);
             await writeReviewFindingsEvent(paths, 'review.review_completed', {

package/docs/prompt-specs.md

@@ -56,7 +56,7 @@ All schema targets are `structured_json` with provider surface
 | `plan_author` | `buildPlanningPrompt`, `buildCoderPlanResponsePrompt` (`reviewMode=plan`, `reviewMode=derived-plan`) | `runCoderPlanRound`, `runCoderPlanResponseRound` | Primary planning: `buildCoderPlanSchema` / `validateCoderPlanPayload`. Response rounds: `buildCoderPlanResponseSchema` / `validateCoderPlanResponsePayload`. | Primary planning routes new/resumed structured sessions by persisted `plannerSessionProtocol`. Legacy marker parsing is retained only for active `legacy_marker_v1` sessions. |
 | `plan_reviewer` | `buildPlanReviewerPrompt` (`mode=plan`, `mode=derived-plan`) | `runPlanReviewerRound` | `buildPlanReviewerSchema` / `PlanReviewerPayload` | Execution-shape confirmation is part of the contract. Reviews material approach, scope, sequencing, and verification defects without turning the plan into an implementation inventory. |
 | `scope_coder` | `buildScopePrompt`, `buildCoderResponsePrompt` | `runCoderScopeRound`, `runCoderResponseRound` | Primary execution: `buildCoderScopeSchema` / `validateCoderScopePayload`. Response rounds: `buildCoderResponseSchema` / `validateCoderResponsePayload`. | Primary execution routes new/resumed structured sessions by persisted `coderSessionProtocol`. Legacy marker and progress-payload parsing is retained only for active `legacy_marker_v1` sessions. Also carries an `adjacent`-status blocked-recovery `response` variant (see below). |
-| `scope_reviewer` | `buildReviewerPrompt` | `runReviewerRound` | `buildReviewerSchema` / `ReviewerPayload` | Execute-scope review only. `neal review` external ranges use the separate read-only review-findings loop. Meaningful-progress remains a capability variant of `scope_reviewer`, not a new top-level id. Context includes a run-local `scratchDir`, but read-only reviewer prompts omit it. |
+| `scope_reviewer` | `buildReviewerPrompt` | `runReviewerRound` | `buildReviewerSchema` / `ReviewerPayload` | Execute-scope review only. `neal review` external ranges use the separate read-only review-findings loop. Meaningful-progress remains a capability variant of `scope_reviewer`, not a new top-level id. Context includes a run-local `scratchDir`, but read-only reviewer prompts omit it. Context also includes `earlierScopeChanges` when the current diff touches a file an earlier accepted scope changed (see below). |
 | `completion_coder` | `buildFinalCompletionSummaryPrompt` | `runCoderFinalCompletionSummaryRound` | `buildFinalCompletionSummarySchema` / `parseFinalCompletionSummaryPayload` | Structured advisor round, but still a coder-owned role/task. The completion packet includes aggregate review context when neal can compute it. |
 | `completion_reviewer` | `buildFinalCompletionReviewerPrompt` | `runReviewerFinalCompletionRound` | `buildFinalCompletionReviewerSchema` / `parseFinalCompletionReviewerPayload` | Whole-plan aggregate review remains distinct from ordinary scope review and keeps its final-completion verdict schema. Context includes a run-local `scratchDir`, but read-only reviewer prompts omit it. |
 | `consultant` | `buildConsultantPrompt` | `runConsultantRound` | `buildConsultantSchema` / `validateConsultantVerdictPayload` | Single no-read-safe variant for the read-only consultant. It judges entirely from neal-inlined context and its static instructions pass the shared no-read guard. |
@@ -125,6 +125,26 @@ When adding or changing a prompt spec:
 
 Final completion has one additional context assembly rule: `buildFinalCompletionPacket()` includes `aggregateReviewContext` for the whole implementation range from `initialBaseCommit` to the resolved final commit. When the range can be read, the packet carries commit subjects, diff stat, and changed files. When it cannot, it carries an explicit `unavailableReason` so the reviewer treats the missing aggregate range as evidence to consider instead of silently accepting completion.
 
+Execute-scope review has one more context assembly rule. The reviewer session
+persists across scopes while the coder session resets, so the reviewer is the
+only participant that remembers earlier scopes, and its record of each one is
+the coder's own summary in the continuity packet. To keep that memory honest,
+`runExecuteReviewerAdjudication` computes `earlierScopeChanges`: for every file
+in the current scope diff that an earlier accepted scope also changed (from
+`completedScopes[].changedFiles` in run state; blocked scopes and scopes
+replaced by a derived plan are skipped), it collects that earlier scope's diff
+restricted to the file (`git diff <scope.baseCommit>..<scope.finalCommit> --
+<file>`, a fixed-argv helper in `src/neal/git.ts`). `buildReviewerPrompt`
+renders them under "Earlier-scope changes to files in this diff", bounded by
+the same inline-section limit as the inlined range diff, and renders nothing
+when there is no overlap. The prompt always carries the matching doctrine line:
+a change to a file an earlier accepted scope signed off must preserve what that
+review accepted, and weakening or removing a test, assertion, or check an
+earlier scope introduced is a blocking finding unless the plan calls for it.
+The continuity packet lists each completed scope's changed files (capped per
+scope, with a count of what was cut) so the reviewer can also see which files
+an earlier scope owned.
+
 Execute-scope and final-completion reviewer context includes a deterministic
 run-local `scratchDir` under `.neal/runs/<run-id>/scratch/`. A `tool-access`
 prompt tells the reviewer to use that directory for temporary verification

package/docs/providers.md

@@ -104,8 +104,10 @@ Current built-in capabilities are intentionally conservative:
 
 The `coder` capability describes adapter paths, not a global promise that every
 writer-run workflow is read-only: writer-run coder turns use provider SDKs with
-broad local permissions. The separate public `neal review` command enforces its
-own read-only boundary in the review command flow.
+broad local permissions. That includes the public `neal review` command's
+draft turn, which runs on the coder capability with full tools and is
+read-only by prompt rules and an after-the-fact worktree check, not by
+mechanism (see [Review boundary](#review-boundary)).
 
 ### Coder tool policy enforcement
 
@@ -151,6 +153,35 @@ Two consequences follow from no reviewer holding shell access:
 - Reviewers never mutate the checkout. A review produces a verdict and findings,
   not edits.
 
+### What the invariant does and does not cover
+
+The invariant covers the tools neal itself hands the reviewer. Beyond that
+it is best effort. What is enforced mechanically today, per provider:
+
+- `anthropic-claude`: the SDK `tools` allowlist is exactly `Read`, `Grep`,
+  `Glob` (empty for the prompt-only repair turn), and `strictMcpConfig` is set
+  so the SDK ignores MCP servers from the operator's user settings, plugins,
+  and project `.mcp.json`. Without that flag those servers load into the
+  reviewer session on top of the allowlist, and they often include tools that
+  write (Jira edits, Drive file writes, a browser).
+- `openai-codex`: every structured-advisor thread runs under the Codex
+  `read-only` sandbox. That sandbox covers shell and filesystem access. neal
+  does not restrict MCP servers configured in the operator's own Codex config,
+  and whether the sandbox applies to them is up to Codex, not neal.
+- `openai-compatible`: the reviewer only ever sees neal's own read-only
+  toolset. There is no MCP or other tool path into that loop.
+
+What is not covered, on any provider:
+
+- The reviewer runs in the same checkout as the coder. There is no separate
+  worktree. Read-only comes from which tools the reviewer has, not from a
+  separate copy of the tree.
+- Prompt instructions ("do not mutate the repository") are instructions to
+  the model, not enforcement. A read-only claim that rests only on prompt text
+  is best effort.
+- Anything the provider adds on its own (its own configured tools,
+  extensions, or network access) is outside the invariant.
+
 Usage reporting is `opportunistic`: providers emit usage only when the SDK
 event or result supplies it.
 
@@ -311,9 +342,13 @@ neal's shared `neal-json-block-v1` runtime appends provider-neutral transport
 instructions requiring optional useful prose followed by exactly one final
 fenced `neal-json` JSON block. It then extracts, parses, validates, and repairs
 that control object with the caller-supplied schema label, schema, validator,
-and repair limit. Raw whole-response JSON objects are accepted only as a
-compatibility tolerance for older mocks and pre-migration paths. The prompt
-contract remains prose plus one final `neal-json` block. State-facing
+and repair limit. Raw whole-response JSON objects, and a single fenced JSON
+object (any fence label) that is the whole response, are accepted only as a
+compatibility tolerance for older mocks, pre-migration paths, and repair turns
+that render the payload as a ```json fence. The prompt contract remains prose
+plus one final `neal-json` block. When a response carries more than one
+`neal-json` block it is still rejected, but the first block's JSON is passed
+to the repair prompt so repair works from the real payload. State-facing
 `structured_output_received` telemetry is emitted only after neal validation
 succeeds.
 
@@ -782,17 +817,22 @@ Two distinct read-only guarantees apply here, and they should not be conflated:
 - The provider-capability invariant (see
   [The read-only reviewer invariant](#the-read-only-reviewer-invariant)):
   every supported `structured-advisor` capability has `write: false` and
-  `shell: false`, so a writer-run reviewer/structured-advisor round cannot
-  write or run shell by capability. This holds for both writer runs and
-  `neal review`.
-- The `neal review` command's additional artifact-boundary guard: the command
-  checks protected writer state and worktree changes after provider rounds and
-  fails if anything outside its review artifacts changed. This post-round guard
-  is owned by the `neal review` command flow, not by a provider capability, and
-  is specific to `neal review`. A writer run does not perform this artifact
-  diff.
-
-So the capability invariant guarantees reviewers never write or run shell in
-any mode, while `neal review` adds its own command-level enforcement on top.
-Do not treat the `neal review` artifact-boundary guard as a provider capability,
-and do not assume a writer run performs that post-round artifact check.
+  `shell: false`, so the adjudication round cannot write or run shell by
+  capability. This covers the reviewer's adjudication round only. The draft
+  round runs on the coder capability with the coder's full tools (shell,
+  file writes, `gh`, the operator's MCP servers) because drafting needs to
+  read things like pull requests and Jira issues. For that round, read-only is
+  a prompt instruction, not a mechanism.
+- The `neal review` command's artifact-boundary guard: the command snapshots
+  protected writer state (`.neal/current.json`, queue pointers, run-local
+  `RUN_STATE.json` files) and `git status` before the loop, compares them after
+  each round, and fails if anything outside its review artifacts changed. This
+  is detection after the fact. It does not prevent a change and does not
+  revert one. It is owned by the `neal review` command flow, not by a provider
+  capability, and a writer run does not perform it.
+
+So the capability invariant guarantees the adjudication round never writes or
+runs shell, the draft round is read-only as best effort, and `neal review`
+detects (but cannot undo) a violation. Do not treat the
+artifact-boundary guard as a provider capability, and do not assume a writer
+run performs that post-round check.

package/docs/storage.md

@@ -86,7 +86,7 @@ neal operations and diagnostics.
 | `.neal/runs/<run-id>/RUN_NARRATIVE.json` | Internal state | Narrative source data that neal may read to update the human narrative. It is not a public trace artifact. |
 | `.neal/runs/<run-id>/REVIEW.md` | User-facing human artifact | Scope or plan review history and findings. |
 | `.neal/runs/<run-id>/REVIEW-<commit>.md` | User-facing human artifact | Archived review history for an accepted scope commit. |
-| `.neal/runs/<run-id>/REVIEWER_CONTEXT.md` | Support/debug artifact | Bounded reviewer-continuity packet rendered for inspection. |
+| `.neal/runs/<run-id>/REVIEWER_CONTEXT.md` | Support/debug artifact | Bounded reviewer-continuity packet rendered for inspection: completed scopes with their changed files, findings, inherited plan-review debt, and citations. |
 | `.neal/runs/<run-id>/REVIEWER_CONTEXT.json` | Support/debug artifact | Machine-readable reviewer-continuity packet without the rendered prompt markdown. |
 | `.neal/runs/<run-id>/RECOVERY.md` | User-facing human artifact | Interactive blocked-recovery transcript/history for a run. |
 | `.neal/runs/<run-id>/FINAL_COMPLETION_REVIEW.md` | User-facing human artifact | Whole-plan final completion review. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navels/neal",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "A source-first multi-agent CLI for planning, executing, reviewing, and resuming scoped code changes.",
   "license": "MIT",
   "publishConfig": {
@@ -8,7 +8,7 @@
   },
   "author": "Lee Nave",
   "type": "module",
-  "packageManager": "pnpm@11.20.0",
+  "packageManager": "pnpm@11.21.0",
   "homepage": "https://github.com/navels/neal#readme",
   "repository": {
     "type": "git",
@@ -41,7 +41,7 @@
   ],
   "engines": {
     "node": ">=24.19.0",
-    "pnpm": ">=11.20.0"
+    "pnpm": ">=11.21.0"
   },
   "scripts": {
     "build": "rm -rf dist && node node_modules/typescript-7/bin/tsc -p tsconfig.json && chmod +x dist/neal/index.js",
@@ -55,10 +55,10 @@
     "typecheck": "node node_modules/typescript-7/bin/tsc --noEmit -p tsconfig.json && node node_modules/typescript-7/bin/tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@ai-sdk/openai-compatible": "3.0.27",
-    "@anthropic-ai/claude-agent-sdk": "0.3.227",
+    "@ai-sdk/openai-compatible": "3.0.30",
+    "@anthropic-ai/claude-agent-sdk": "0.3.234",
     "@openai/codex-sdk": "0.147.0",
-    "ai": "7.0.58",
+    "ai": "7.0.65",
     "dotenv": "^17.4.2",
     "yaml": "^2.9.0",
     "zod": "4.4.3"
@@ -67,9 +67,9 @@
     "@eslint/js": "^10.0.1",
     "@types/node": "^24.13.3",
     "eslint": "^10.8.1",
-    "tsx": "^4.23.11",
+    "tsx": "^4.23.12",
     "typescript": "^6.0.3",
     "typescript-7": "npm:typescript@^7.0.2",
-    "typescript-eslint": "^8.66.0"
+    "typescript-eslint": "^8.67.0"
   }
 }