@navels/neal 0.5.1 → 0.6.1

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

@@ -5,6 +5,7 @@ import { isOpenBlockingFinding, isOpenNonBlockingFinding, mapDecisionToStatus, }
 import { getDerivedPlanBlockedReason, isDerivedPlanReviewState, plannerProviderStartsFreshSessions, resolvePlanningAdjudicationContext, runPlanningResponseAdjudication, runPlanningReviewerAdjudication, synthesizePlanReviewRound, } from '../../adjudicator/planning.js';
 import { assertAdjudicationTransitionSignal } from '../../adjudicator/specs.js';
 import { getPlanReviewDebtRoundThreshold, getReviewStuckWindow } from '../../config.js';
+import { OPEN_FINDINGS_PROMPT_ITEM_LIMIT } from '../../context/inline-review-context.js';
 import { toPlanReviewDebt } from '../../review-debt.js';
 import { writeDiagnostic } from '../../diagnostic.js';
 import { getWorktreeStatus } from '../../git.js';
@@ -402,7 +403,14 @@ export async function runPlanningResponsePhase(state, statePath, phase, logger)
     if (isPlanRefinementState(state)) {
         writeDiagnostic(`${formatPlanRefinementRoundLine({ round: state.rounds.length + 1, maxRounds: state.maxRounds })}\n`, logger);
     }
-    const openFindings = state.findings.filter(mode === 'optional' ? isOpenNonBlockingFinding : isOpenBlockingFinding);
+    // The bounded finding set for this response round: the prompt and the
+    // disposition eligibility below consume this same selection. Findings
+    // beyond the per-round limit stay open; when the presented set is fully
+    // dispositioned, this phase stays active and presents the next batch (see
+    // hasNextResponseBatch below), so the cap never strands a finding.
+    const openFindings = state.findings
+        .filter(mode === 'optional' ? isOpenNonBlockingFinding : isOpenBlockingFinding)
+        .slice(0, OPEN_FINDINGS_PROMPT_ITEM_LIMIT);
     // Recorded operator guidance must reach the planner. If a prior blocked response
     // closed every finding, the guidance would otherwise be silently discarded here
     // (finalizePlanReviewResponseWithoutOpenFindings clears pendingPlanReviewGuidance
@@ -459,6 +467,31 @@ export async function runPlanningResponsePhase(state, statePath, phase, logger)
     // hardening finding cannot be silently un-banked by an out-of-band disposition)
     // and matches the replay harness's open-blocking eligibility guard.
     const openFindingIds = new Set(openFindings.map((finding) => finding.id));
+    // Optional responses must disposition every presented finding exactly once,
+    // matching execute optional response coverage: a partial optional response
+    // would otherwise land acceptance below while presented findings — and every
+    // overflow batch beyond the per-round presentation limit — were never
+    // resolved. Out-of-set ids keep their documented no-op tolerance.
+    if (mode === 'optional' && codex.payload.outcome === 'responded') {
+        const seenPresentedIds = new Set();
+        const duplicateIds = new Set();
+        for (const response of codex.payload.responses) {
+            if (!openFindingIds.has(response.id)) {
+                continue;
+            }
+            if (seenPresentedIds.has(response.id)) {
+                duplicateIds.add(response.id);
+            }
+            seenPresentedIds.add(response.id);
+        }
+        if (duplicateIds.size > 0) {
+            throw new Error(`Planner optional response returned duplicate finding dispositions: ${[...duplicateIds].join(', ')}`);
+        }
+        const missingIds = openFindings.map((finding) => finding.id).filter((id) => !seenPresentedIds.has(id));
+        if (missingIds.length > 0) {
+            throw new Error(`Planner optional response did not disposition every presented finding: ${missingIds.join(', ')}`);
+        }
+    }
     const findings = state.findings.map((finding) => {
         if (!openFindingIds.has(finding.id)) {
             return finding;
@@ -474,6 +507,16 @@ export async function runPlanningResponsePhase(state, statePath, phase, logger)
             coderCommit: null,
         };
     });
+    // Response rounds batch: when the presented set was fully dispositioned but
+    // open findings of this round's kind remain (they were beyond the per-round
+    // presentation limit), stay in this response phase so the next batch is
+    // presented immediately instead of spending a plan-review round per batch.
+    // The full-disposition requirement guarantees the backlog strictly shrinks;
+    // a partially-skipped presented set falls through to the reviewer so the
+    // existing convergence machinery judges it.
+    const openSelector = mode === 'optional' ? isOpenNonBlockingFinding : isOpenBlockingFinding;
+    const presentedStillOpen = findings.some((finding) => openFindingIds.has(finding.id) && openSelector(finding));
+    const hasNextResponseBatch = !presentedStillOpen && findings.some(openSelector);
     const nextState = await saveState(statePath, {
         ...state,
         plannerSessionHandle: codex.sessionHandle,
@@ -485,17 +528,19 @@ export async function runPlanningResponsePhase(state, statePath, phase, logger)
         planReviewDebt: toPlanReviewDebt(findings),
         phase: dirtyWorktreeBlocker || codex.payload.outcome === 'blocked'
             ? 'blocked'
-            : mode === 'optional'
-                ? derivedPlanReview
-                    ? 'awaiting_derived_plan_execution'
-                    : 'done'
-                : 'reviewer_plan',
+            : hasNextResponseBatch
+                ? phase
+                : mode === 'optional'
+                    ? derivedPlanReview
+                        ? 'awaiting_derived_plan_execution'
+                        : 'done'
+                    : 'reviewer_plan',
         status: dirtyWorktreeBlocker || codex.payload.outcome === 'blocked'
             ? 'blocked'
-            : mode === 'optional' && !derivedPlanReview
+            : mode === 'optional' && !derivedPlanReview && !hasNextResponseBatch
                 ? 'done'
                 : 'running',
-        derivedPlanStatus: mode === 'optional' && codex.payload.outcome !== 'blocked' && derivedPlanReview
+        derivedPlanStatus: mode === 'optional' && codex.payload.outcome !== 'blocked' && derivedPlanReview && !hasNextResponseBatch
             ? 'accepted'
             : state.derivedPlanStatus,
         blockedFromPhase: dirtyWorktreeBlocker || codex.payload.outcome === 'blocked' ? phase : null,

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

@@ -1,11 +1,14 @@
+import { readFile, writeFile } from 'node:fs/promises';
 import { CoderRoundError, runBlockedRecoveryCoderRound, } from '../../agents.js';
 import { CONSULTANT_ELIGIBLE_SOURCE_PHASES, buildRecentBlockCandidate, isReviewerConsultantPhase, runConsultant, upsertRecentBlock, } from '../../adjudicator/consultant.js';
 import { getInteractiveBlockedRecoveryMaxTurns, getConsultantMaxAttempts } from '../../config.js';
 import { EXECUTE_FINALIZATION_PHASE } from '../../execute-finalization.js';
+import { getLaterScopeRevisionEligibility, reviseLaterScope } from '../../plan-scope-revision.js';
 import { hasPendingOperatorGuidance } from '../../run-status.js';
 import { getExecutionPlanPath } from '../../scopes.js';
 import { loadState, saveState } from '../../state.js';
 import { getInteractiveRecoveryView, isActivePendingDerivedPlanReview } from '../../state-views.js';
+import { getCoderBlockedRecoveryLaterScopeErrors } from '../../agents/schemas.js';
 import { writeExecutionArtifacts } from '../artifacts.js';
 import { isCoderTimeoutError, shouldNotifyFailure } from '../failures.js';
 import { flushDerivedPlanNotifications, notifyBlocked } from '../notifications.js';
@@ -144,8 +147,8 @@ async function buildConsultantAdvice(state, reason, sourcePhase, logger) {
 }
 // Applies a recoverable consultant verdict. Enters interactive recovery and
 // injects the consultant's in-scope directive as the pending turn, exactly like
-// a human-supplied `neal resume --message`, so the coder consumes it and the
-// run continues. Consumes one unit of the per-scope consultant budget
+// a human-supplied `neal resume --message` except that the turn's `origin` is
+// `consultant`, so the coder consumes it and the run continues. Consumes one unit of the per-scope consultant budget
 // (`consultantAttemptCount`) and persists the anti-thrash `recentBlocks`. The
 // caller has already emitted the `consultant.verdict` audit event for this
 // verdict.
@@ -170,7 +173,7 @@ async function applyRecoverableConsultantDirective(args) {
         sourcePhase: enteredState.interactiveBlockedRecovery?.sourcePhase,
         blockedReason: reason,
     });
-    const resolvedState = await recordInteractiveBlockedRecoveryGuidance(statePath, resolutionDirective, logger);
+    const resolvedState = await recordInteractiveBlockedRecoveryTurn(statePath, resolutionDirective, 'consultant', logger);
     await logger?.event('consultant.resolved', {
         scopeNumber: resolvedState.currentScopeNumber,
         sourcePhase,
@@ -253,6 +256,11 @@ export function shouldNotifyInteractiveBlockedRecoveryEntry(state) {
     return getInteractiveRecoveryView(state)?.waitingForOperatorGuidance ?? false;
 }
 export async function recordInteractiveBlockedRecoveryGuidance(statePath, operatorGuidance, logger) {
+    return recordInteractiveBlockedRecoveryTurn(statePath, operatorGuidance, 'operator', logger);
+}
+// Shared by operator guidance (`neal resume --message`) and the consultant
+// injection path; `origin` marks the turn with whichever created it.
+async function recordInteractiveBlockedRecoveryTurn(statePath, operatorGuidance, origin, logger) {
     const trimmedGuidance = operatorGuidance.trim();
     if (!trimmedGuidance) {
         throw new Error('Recovery guidance must not be empty');
@@ -278,6 +286,7 @@ export async function recordInteractiveBlockedRecoveryGuidance(statePath, operat
                     recordedAt: new Date().toISOString(),
                     operatorGuidance: trimmedGuidance,
                     terminalOnly: true,
+                    origin,
                 },
             },
         });
@@ -299,6 +308,7 @@ export async function recordInteractiveBlockedRecoveryGuidance(statePath, operat
                     number: turns.length + 1,
                     recordedAt: new Date().toISOString(),
                     operatorGuidance: trimmedGuidance,
+                    origin,
                     disposition: null,
                 },
             ],
@@ -339,6 +349,7 @@ function withRecordedInteractiveBlockedRecoveryDisposition(state, disposition, s
                         number: state.interactiveBlockedRecovery.turns.length + 1,
                         recordedAt: state.interactiveBlockedRecovery.pendingDirective.recordedAt,
                         operatorGuidance: state.interactiveBlockedRecovery.pendingDirective.operatorGuidance,
+                        origin: state.interactiveBlockedRecovery.pendingDirective.origin,
                         disposition: {
                             recordedAt: new Date().toISOString(),
                             sessionHandle,
@@ -347,6 +358,8 @@ function withRecordedInteractiveBlockedRecoveryDisposition(state, disposition, s
                             rationale: disposition.rationale,
                             blocker: disposition.blocker.trim(),
                             replacementPlan: disposition.replacementPlan.trim(),
+                            laterScopeNumber: disposition.laterScopeNumber,
+                            laterScopeBody: disposition.laterScopeBody,
                             resultingPhase,
                         },
                     },
@@ -373,6 +386,8 @@ function withRecordedInteractiveBlockedRecoveryDisposition(state, disposition, s
                         rationale: disposition.rationale,
                         blocker: disposition.blocker.trim(),
                         replacementPlan: disposition.replacementPlan.trim(),
+                        laterScopeNumber: disposition.laterScopeNumber,
+                        laterScopeBody: disposition.laterScopeBody,
                         resultingPhase,
                     },
                 }
@@ -422,6 +437,78 @@ function getInteractiveBlockedRecoveryResumePhase(sourcePhase) {
             return sourcePhase;
     }
 }
+// Reads the top-level plan (always `state.planDoc`, even while a derived plan
+// is executing) at the time the disposition is applied, splices the revised
+// scope entry in, and writes the file. The plan is read fresh from disk on
+// every later turn, so nothing in state needs to change.
+async function applyLaterScopeRevision(state, disposition, logger) {
+    if (disposition.laterScopeNumber === 0 && disposition.laterScopeBody.trim() === '') {
+        return;
+    }
+    if (!isOperatorGuidedRecoveryTurn(state)) {
+        throw new Error('Interactive blocked recovery cannot apply the later-scope revision: only operator guidance may direct a later-scope revision, and the pending guidance is not an operator message.');
+    }
+    const planDocument = await readFile(state.planDoc, 'utf8');
+    const errors = getCoderBlockedRecoveryLaterScopeErrors(disposition, {
+        allowLaterScopeRevision: true,
+        currentScopeNumber: state.currentScopeNumber,
+        planDocument,
+    });
+    if (errors.length > 0) {
+        throw new Error(`Interactive blocked recovery cannot apply the later-scope revision: ${errors.join(' ')}`);
+    }
+    const result = reviseLaterScope({
+        planDocument,
+        currentScopeNumber: state.currentScopeNumber,
+        targetScopeNumber: disposition.laterScopeNumber,
+        replacementBody: disposition.laterScopeBody,
+    });
+    if (!result.ok) {
+        throw new Error(`Interactive blocked recovery cannot apply the later-scope revision: ${result.errors.join(' ')}`);
+    }
+    await writeFile(state.planDoc, result.document, 'utf8');
+    await logger?.event('interactive_blocked_recovery.later_scope_revised', {
+        scopeNumber: state.currentScopeNumber,
+        laterScopeNumber: disposition.laterScopeNumber,
+        planDoc: state.planDoc,
+    });
+}
+// Whether the pending guidance is an operator message. Only an operator message
+// may direct a later-scope revision. The turn's `origin` marker is set where the
+// turn is created: `operator` by `neal resume --message`, `consultant` by the
+// consultant-injection path. A turn persisted without the marker, and the
+// operator's turn-cap directive (which cannot choose an action that carries a
+// revision anyway), do not qualify.
+function isOperatorGuidedRecoveryTurn(state) {
+    const recovery = state.interactiveBlockedRecovery;
+    if (!recovery || recovery.pendingDirective) {
+        return false;
+    }
+    const latestTurn = recovery.turns.at(-1);
+    return latestTurn !== undefined && latestTurn.number > recovery.lastHandledTurn && latestTurn.origin === 'operator';
+}
+async function getLaterScopeRevisionOffer(state, terminalOnly) {
+    if (terminalOnly || !isOperatorGuidedRecoveryTurn(state)) {
+        return null;
+    }
+    let planDocument;
+    try {
+        planDocument = await readFile(state.planDoc, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const eligibility = getLaterScopeRevisionEligibility(planDocument, state.currentScopeNumber);
+    if (!eligibility.eligible) {
+        return null;
+    }
+    return {
+        topLevelPlanDoc: state.planDoc,
+        planDocument,
+        currentScopeNumber: state.currentScopeNumber,
+        scopeCount: eligibility.scopeCount,
+    };
+}
 export async function applyInteractiveBlockedRecoveryDisposition(state, statePath, disposition, sessionHandle, logger) {
     if (state.phase !== 'interactive_blocked_recovery' || !state.interactiveBlockedRecovery) {
         throw new Error(`Run is not in interactive blocked recovery: ${statePath}`);
@@ -430,11 +517,11 @@ export async function applyInteractiveBlockedRecoveryDisposition(state, statePat
         throw new Error('Interactive blocked recovery is only supported for execute-mode runs');
     }
     const latestTurn = state.interactiveBlockedRecovery.turns.at(-1);
-    const terminalDirective = state.interactiveBlockedRecovery.pendingDirective;
-    if (!latestTurn && !terminalDirective) {
+    const pendingDirective = state.interactiveBlockedRecovery.pendingDirective;
+    if (!latestTurn && !pendingDirective) {
         throw new Error('Interactive blocked recovery requires recorded operator guidance before a coder response can be applied.');
     }
-    if (terminalDirective &&
+    if (pendingDirective &&
         disposition.action !== 'replace_current_scope' &&
         disposition.action !== 'terminal_block') {
         throw new Error('Interactive blocked recovery reached its turn cap and now only allows replace_current_scope or terminal_block.');
@@ -448,6 +535,7 @@ export async function applyInteractiveBlockedRecoveryDisposition(state, statePat
         action: disposition.action,
         sessionHandle,
     });
+    await applyLaterScopeRevision(state, disposition, logger);
     if (disposition.action === 'replace_current_scope') {
         const persistedState = await persistSplitPlanRecovery({
             ...state,
@@ -541,12 +629,14 @@ export async function runInteractiveBlockedRecoveryPhase(state, statePath, logge
     if (!hasPendingTurn && !pendingDirective) {
         throw new Error('Interactive blocked recovery has no pending operator guidance to process.');
     }
+    const terminalOnly = Boolean(pendingDirective?.terminalOnly);
     await logger?.event('phase.start', {
         phase: 'interactive_blocked_recovery',
         recoveryTurn: pendingDirective ? state.interactiveBlockedRecovery.turns.length : latestTurn?.number,
         sourcePhase: state.interactiveBlockedRecovery.sourcePhase,
-        terminalOnly: Boolean(pendingDirective?.terminalOnly),
+        terminalOnly,
     });
+    const laterScopeRevision = await getLaterScopeRevisionOffer(state, terminalOnly);
     let codex;
     try {
         codex = await runBlockedRecoveryCoderRound({
@@ -559,8 +649,9 @@ export async function runInteractiveBlockedRecoveryPhase(state, statePath, logge
             operatorGuidance: pendingDirective?.operatorGuidance ?? latestTurn?.operatorGuidance ?? state.interactiveBlockedRecovery.blockedReason,
             maxTurns: state.interactiveBlockedRecovery.maxTurns,
             turnsTaken: pendingDirective ? state.interactiveBlockedRecovery.turns.length : latestTurn?.number ?? 0,
-            terminalOnly: Boolean(pendingDirective?.terminalOnly),
+            terminalOnly,
             allowReplacement: true,
+            laterScopeRevision,
             sessionHandle: state.coderSessionHandle,
             logger,
         });

package/dist/neal/plan-scope-revision.js

@@ -0,0 +1,129 @@
+import { validatePlanDocument } from './plan-validation.js';
+const EXECUTION_QUEUE_HEADER = '## Execution Queue';
+const SCOPE_HEADING_PATTERN = /^### Scope (\d+):/;
+const SECTION_HEADING_PATTERN = /^##(#)? /;
+/**
+ * Decides whether operator guidance may revise a later top-level scope in
+ * `planDocument`: the document validates, its shape is `multi_scope`, it is
+ * already in canonical `## Execution Queue` / `### Scope N:` form on disk, and
+ * it has at least one scope after `currentScopeNumber`.
+ */
+export function getLaterScopeRevisionEligibility(planDocument, currentScopeNumber) {
+    const reasons = collectCanonicalMultiScopeErrors(planDocument);
+    const scopeCount = reasons.length === 0 ? collectScopeEntries(planDocument.split('\n')).length : 0;
+    if (reasons.length === 0 && scopeCount <= currentScopeNumber) {
+        reasons.push(`The plan has ${scopeCount} scope(s) and the current scope is ${currentScopeNumber}, so there is no later scope to revise.`);
+    }
+    return { eligible: reasons.length === 0, scopeCount, reasons };
+}
+/**
+ * Replaces exactly one later `### Scope N:` entry in `planDocument` with
+ * `replacementBody`. The splice is bounded by the next `### `/`## ` heading
+ * (or end of file), so nothing outside the target entry changes. The revised
+ * document must still validate with the same scope count.
+ */
+export function reviseLaterScope(input) {
+    const { planDocument, currentScopeNumber, targetScopeNumber, replacementBody } = input;
+    const errors = collectCanonicalMultiScopeErrors(planDocument);
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    const lines = planDocument.split('\n');
+    const entries = collectScopeEntries(lines);
+    const scopeCount = entries.length;
+    if (!Number.isInteger(targetScopeNumber) || targetScopeNumber <= currentScopeNumber) {
+        errors.push(`Target scope ${targetScopeNumber} must be a later scope than the current scope ${currentScopeNumber}.`);
+    }
+    if (Number.isInteger(targetScopeNumber) && targetScopeNumber > scopeCount) {
+        errors.push(`Target scope ${targetScopeNumber} is past the plan's scope count of ${scopeCount}.`);
+    }
+    errors.push(...collectReplacementBodyErrors(replacementBody, targetScopeNumber));
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    const target = entries.find((entry) => entry.number === targetScopeNumber);
+    if (target === undefined) {
+        return { ok: false, errors: [`Target scope ${targetScopeNumber} has no \`### Scope ${targetScopeNumber}:\` heading in the plan.`] };
+    }
+    const bodyLines = trimTrailingBlankLines(replacementBody.split('\n'));
+    const contentEnd = target.start + trimTrailingBlankLines(lines.slice(target.start, target.end)).length;
+    const revisedLines = [...lines.slice(0, target.start), ...bodyLines, ...lines.slice(contentEnd)];
+    const document = revisedLines.join('\n');
+    const validation = validatePlanDocument(document);
+    if (!validation.ok) {
+        return { ok: false, errors: validation.errors.map((error) => `Revised plan does not validate: ${error}`) };
+    }
+    const revisedCount = collectScopeEntries(document.split('\n')).length;
+    if (revisedCount !== scopeCount) {
+        return {
+            ok: false,
+            errors: [`Revised plan has ${revisedCount} scope(s) but the original has ${scopeCount}; the scope count must not change.`],
+        };
+    }
+    return { ok: true, document };
+}
+function collectCanonicalMultiScopeErrors(planDocument) {
+    const validation = validatePlanDocument(planDocument);
+    if (!validation.ok) {
+        return validation.errors.map((error) => `Plan does not validate: ${error}`);
+    }
+    if (validation.executionShape !== 'multi_scope') {
+        return [`Plan shape is \`${validation.executionShape}\`; only \`multi_scope\` plans have later scopes to revise.`];
+    }
+    if (validation.normalization.applied) {
+        return [
+            'Plan uses an alias form that is normalized in memory; only plans already in canonical `## Execution Queue` / `### Scope N:` form can be revised.',
+        ];
+    }
+    return [];
+}
+function collectReplacementBodyErrors(replacementBody, targetScopeNumber) {
+    const errors = [];
+    const bodyLines = replacementBody.split('\n');
+    const firstLine = bodyLines[0] ?? '';
+    const headingMatch = SCOPE_HEADING_PATTERN.exec(firstLine.trim());
+    if (headingMatch === null || Number(headingMatch[1]) !== targetScopeNumber) {
+        errors.push(`Replacement body must start with the line \`### Scope ${targetScopeNumber}:\`.`);
+    }
+    const extraHeadings = bodyLines.slice(1).filter((line) => SECTION_HEADING_PATTERN.test(line.trim()));
+    if (extraHeadings.length > 0) {
+        errors.push(`Replacement body must contain exactly one scope entry; found additional heading(s): ${extraHeadings.map((line) => `\`${line.trim()}\``).join(', ')}.`);
+    }
+    return errors;
+}
+function collectScopeEntries(lines) {
+    const queueStart = lines.findIndex((line) => line.trim() === EXECUTION_QUEUE_HEADER);
+    if (queueStart === -1) {
+        return [];
+    }
+    let queueEnd = lines.length;
+    for (let index = queueStart + 1; index < lines.length; index += 1) {
+        if (/^## /.test(lines[index].trim())) {
+            queueEnd = index;
+            break;
+        }
+    }
+    const entries = [];
+    for (let index = queueStart + 1; index < queueEnd; index += 1) {
+        const match = SCOPE_HEADING_PATTERN.exec(lines[index].trim());
+        if (match === null) {
+            continue;
+        }
+        let end = queueEnd;
+        for (let cursor = index + 1; cursor < queueEnd; cursor += 1) {
+            if (SECTION_HEADING_PATTERN.test(lines[cursor].trim())) {
+                end = cursor;
+                break;
+            }
+        }
+        entries.push({ number: Number(match[1]), start: index, end });
+    }
+    return entries;
+}
+function trimTrailingBlankLines(lines) {
+    const trimmed = [...lines];
+    while (trimmed.length > 0 && trimmed.at(-1)?.trim() === '') {
+        trimmed.pop();
+    }
+    return trimmed;
+}

package/dist/neal/prompts/execute.js

@@ -1,8 +1,8 @@
-import { renderInlinedRangeDiffSection, truncateInlineSectionBody } from '../context/inline-review-context.js';
+import { AGENT_FREE_TEXT_SECTION_MAX_CHARS, boundChangedFileList, boundCommitSubjectList, boundFreeTextValues, boundOpenFindingsForPrompt, GIT_SUMMARY_SECTION_MAX_CHARS, 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, } from './shared.js';
 import { assertPromptBuilder } from './assert-builder.js';
 import { getUserGuidanceLines } from './guidance.js';
-import { getAdversarialReviewDoctrineLines, getCodeReviewFalsificationLines, getFindingQualityLines, getPreexistingFailureContractLines, getRegressionPreservationLines, getVerificationSkepticismLines, } from './review-doctrine.js';
+import { getAdversarialReviewDoctrineLines, getCodeReviewFalsificationLines, getFindingQualityLines, getPreexistingFailureContractLines, getRegressionPreservationLines, getReviewLevelCalibrationLines, getVerificationSkepticismLines, } from './review-doctrine.js';
 const PROMPT_MODULE_PATH = 'src/neal/prompts/execute.ts';
 export const CODER_REGRESSION_PRESERVATION_LINE = 'Treat existing behavior on the code paths you touch as part of the contract: identify the shared subsystems your change intersects (state, parsing, dispatch, lifecycle, storage, startup) and confirm that adjacent behavior on those paths still works — by running existing tests that exercise them when such tests exist, or by concrete reasoning through representative flows otherwise — before you finish.';
 export const CODER_PREEXISTING_FAILURE_LINES = [
@@ -107,6 +107,23 @@ export function buildLegacyScopePrompt(planDoc, progressText) {
     ].join('\n');
 }
 export const EARLIER_SCOPE_CHANGES_SECTION_HEADING = '## Earlier-scope changes to files in this diff';
+// Render-only view of the coder's progress justification: the four free-text
+// fields share the fixed aggregate free-text budget; the stored payload keeps
+// its full text.
+function boundProgressJustificationForPrompt(justification) {
+    const bounded = boundFreeTextValues([
+        justification.milestoneTargeted,
+        justification.newEvidence,
+        justification.whyNotRedundant,
+        justification.nextStepUnlocked,
+    ]);
+    return {
+        milestoneTargeted: bounded[0],
+        newEvidence: bounded[1],
+        whyNotRedundant: bounded[2],
+        nextStepUnlocked: bounded[3],
+    };
+}
 // 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.
@@ -119,13 +136,14 @@ export function buildReviewerPrompt(args) {
         throw new Error('Prompt spec scope_reviewer is missing primary or meaningful-progress coverage');
     }
     const accessMode = args.accessMode ?? 'tool-access';
+    const reviewLevel = args.reviewLevel ?? 'moderate';
     // A collected diff may legitimately be the empty string (a range with no
     // changes); distinguish "collected" (any string, including '') from "not
     // collected" (null/undefined) so an empty diff still rides the inlined channel
     // instead of falling back to git_diff-tool phrasing the reviewer cannot use.
     const rangeDiffInlined = accessMode === 'read-only' && args.inlinedRangeDiff !== null && args.inlinedRangeDiff !== undefined;
-    const changedFilesText = args.changedFiles.length > 0 ? args.changedFiles.join('\n') : '(no changed files)';
-    const commitsText = args.commits.length > 0 ? args.commits.join('\n') : '(no commits recorded)';
+    const changedFilesText = args.changedFiles.length > 0 ? boundChangedFileList(args.changedFiles).join('\n') : '(no changed files)';
+    const commitsText = args.commits.length > 0 ? boundCommitSubjectList(args.commits).join('\n') : '(no commits recorded)';
     const falsificationLines = getCodeReviewFalsificationLines({
         rangeLabel: 'commit range',
         gitInspectionExamples: `Use git commands against the repository, for example: git diff ${args.baseCommit}..${args.headCommit}, git show --stat ${args.headCommit}, and targeted path diffs or file reads for changed files.`,
@@ -166,8 +184,9 @@ export function buildReviewerPrompt(args) {
         ...getAdversarialReviewDoctrineLines({
             reviewSubject: 'the scope diff',
         }),
+        ...getReviewLevelCalibrationLines({ level: reviewLevel, outputContract: 'structured_findings' }),
         '',
-        ...getFindingQualityLines(),
+        ...getFindingQualityLines({ outputContract: 'structured_findings', level: reviewLevel }),
         ...skepticismLines,
         ...regressionLines,
         EARLIER_SCOPE_PRESERVATION_LINE,
@@ -181,7 +200,7 @@ export function buildReviewerPrompt(args) {
         commitsText,
         '',
         'Diff stat:',
-        args.diffStat || '(no diff stat)',
+        args.diffStat ? truncateInlineSectionBody(args.diffStat, GIT_SUMMARY_SECTION_MAX_CHARS) : '(no diff stat)',
         '',
         'Changed files:',
         changedFilesText,
@@ -200,10 +219,10 @@ export function buildReviewerPrompt(args) {
         'Use `meaningfulProgressRationale` to explain the convergence judgment against the parent objective and recent accepted-scope history. Do not use it to restate correctness findings.',
         '',
         'Coder progress justification for this scope:',
-        JSON.stringify(args.progressJustification, null, 2),
+        JSON.stringify(boundProgressJustificationForPrompt(args.progressJustification), null, 2),
         '',
         'Recent accepted scope history for this parent objective:',
-        args.recentHistorySummary,
+        truncateInlineSectionBody(args.recentHistorySummary, AGENT_FREE_TEXT_SECTION_MAX_CHARS),
         '',
         reviewHistoryLine,
         'If prior review history or continuity context describes a finding as fixed, rejected, or deferred, do not reopen the same claim from that history alone.',
@@ -302,7 +321,7 @@ export function buildCoderResponsePrompt(args) {
         ...getUserGuidanceLines('coder'),
         '',
         'Open findings:',
-        JSON.stringify(args.openFindings, null, 2),
+        JSON.stringify(boundOpenFindingsForPrompt(args.openFindings), null, 2),
         '',
         'Current progress state:',
         buildProgressSection(args.progressText),

package/dist/neal/prompts/guidance.js

@@ -1,6 +1,12 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { truncateInlineSectionBody } from '../context/inline-review-context.js';
+// Per-role character cap for operator guidance inlined into prompts. Guidance
+// beyond the cap is truncated at render time with an explicit marker; the
+// guidance file itself is never modified. `neal check` warns when a guidance
+// file exceeds this cap.
+export const USER_GUIDANCE_MAX_CHARS = 20_000;
 export const GUIDANCE_ROLES = ['coder', 'reviewer', 'planner'];
 export const GUIDANCE_SECTION_HEADER = '## User Guidance';
 const cache = new Map();
@@ -38,7 +44,7 @@ export function getUserGuidanceLines(role) {
     if (!content) {
         return [];
     }
-    return ['', GUIDANCE_SECTION_HEADER, '', content];
+    return ['', GUIDANCE_SECTION_HEADER, '', truncateInlineSectionBody(content, USER_GUIDANCE_MAX_CHARS)];
 }
 export function clearUserGuidanceCache() {
     cache.clear();
@@ -52,6 +58,7 @@ export function collectGuidanceDiagnostics() {
         entries.push({
             role,
             bytes: Buffer.byteLength(entry.content, 'utf8'),
+            chars: entry.content.length,
             path: entry.path,
         });
     }

package/dist/neal/prompts/planning.js

@@ -1,6 +1,7 @@
+import { boundOpenFindingsForPrompt, truncateInlineSectionBody } from '../context/inline-review-context.js';
 import { AUTONOMY_BLOCKED, AUTONOMY_DONE, getCanonicalPlanContractLines, getDerivedPlanSectionContractLines, getProtocolMarkerArtifactProhibitionLines, getTerminalMarkerArtifactBoundaryLines, } from './shared.js';
 import { assertPromptBuilder } from './assert-builder.js';
-import { getUserGuidanceLines } from './guidance.js';
+import { getUserGuidanceLines, USER_GUIDANCE_MAX_CHARS } from './guidance.js';
 const PROMPT_MODULE_PATH = 'src/neal/prompts/planning.ts';
 const PLAN_VERIFICATION_NECESSITY_RULE = 'A repository-wide invariant or global regression guarantee belongs in the plan only when it is necessary for the requested change to be correct.';
 function getPlanVerificationScopeLines(role) {
@@ -278,6 +279,9 @@ export function buildCoderPlanResponsePrompt(args) {
         mode === 'blocking'
             ? 'Address the currently open review findings provided below.'
             : 'The currently open review findings below are non-blocking. Decide whether to address each one now or explicitly reject/defer it with rationale.',
+        ...(mode === 'optional'
+            ? ['Return exactly one disposition for every finding listed below; a partial response is rejected.']
+            : []),
         reviewMode === 'derived-plan'
             ? 'Edit only the derived plan artifact and directly related planning notes for that derived plan.'
             : 'Edit only the plan document and directly related planning artifacts.',
@@ -308,13 +312,15 @@ export function buildCoderPlanResponsePrompt(args) {
         ...(args.planReviewGuidance
             ? [
                 'Operator guidance for this blocked plan-review recovery:',
-                args.planReviewGuidance.message,
+                // Same render-time cap as the operator guidance files; the persisted
+                // guidance record keeps its full message.
+                truncateInlineSectionBody(args.planReviewGuidance.message, USER_GUIDANCE_MAX_CHARS),
                 '',
                 'This guidance supplements the open reviewer findings. It does not waive plan-contract requirements, verification requirements, or the need to address blocking findings.',
                 '',
             ]
             : []),
         'Open findings:',
-        JSON.stringify(args.openFindings, null, 2),
+        JSON.stringify(boundOpenFindingsForPrompt(args.openFindings), null, 2),
     ].join('\n');
 }