@navels/neal 0.6.0 → 0.6.2

package/README.md

@@ -453,6 +453,54 @@ agent:
     effort: xhigh
 ```
 
+### Review level
+
+`neal.review_level` sets how strict the scope reviewer and the final-completion
+reviewer are about what rises to a blocking finding. It takes one of three
+values and defaults to `moderate`:
+
+- `strict`: assume adversarial trust boundaries. Block on any failure reachable
+  under the worst case, including hardening gaps and missing defenses against
+  local or adversarial actors.
+- `moderate`: ordinary trust boundaries. Internal run artifacts aren't security
+  boundaries. Block on correctness bugs and failures reachable under normal use;
+  don't require defenses against an actor who could already subvert the system.
+- `lenient`: correctness and real, reachable bugs only. Minimal robustness,
+  style, or hardening demands.
+
+```yaml
+neal:
+  review_level: moderate
+```
+
+Set it in the repo's `neal.yml` or in `~/.neal/config.yml`; the repo value wins.
+A blank or null value means unset and falls back to `moderate`. Any other
+nonblank value (a typo, say) is rejected before any agent work: `neal check`
+fails, every fresh writer command fails at config load, and a `neal resume`
+that has selected a run and is about to resume writer work (plain, manual
+gate, or `--message`) fails before it takes the writer lock, rewrites run
+state, or starts an agent turn. Resume outcomes that never execute writer work
+(already done, already running, waiting for operator guidance) are decided
+first and don't validate the level.
+
+Under every level a blocking finding has to describe a failure that's actually
+reachable under the assumed trust boundaries, and the reviewer still treats the
+change as hostile input and tries to falsify it before crediting it. A level
+narrows what counts as blocking; it never means trust the coder or skip
+inspection. The plan reviewer, the consultant, and `neal review` don't use the
+level.
+
+`~/.neal/guidance/reviewer.md` refines the level rather than replacing it. It
+can widen or narrow the assumed trust boundaries ("we do defend the run
+directory against local processes" makes a local-process attack on the run
+directory blockable even at `moderate`) and it can demote or promote finding
+categories ("ignore performance, correctness only" makes a performance
+regression non-blocking at any level). It can't turn off the reachability
+filter, the adversarial stance, or blocking on reachable correctness failures,
+including correctness regressions. Guidance that conflicts with that floor is
+ignored on that point. See [Custom guidance](#custom-guidance) for where the
+file lives.
+
 ### Custom guidance
 
 neal supports additive guidance files for local preferences alongside the built-in protocol prompts:
@@ -463,6 +511,11 @@ neal supports additive guidance files for local preferences alongside the built-
 
 Set `NEAL_GUIDANCE_DIR=/path/to/guidance` to load those same `coder.md`, `reviewer.md`, and `planner.md` files from another directory. neal records applied guidance roles, selected paths, and byte counts in run artifacts. Guidance contents stay out of terminal output.
 
+For the two code reviewers, `reviewer.md` layers on top of `neal.review_level`
+(see [Review level](#review-level)): it can adjust trust boundaries and finding
+categories, but it can't switch off the reachability filter or blocking on
+reachable correctness failures.
+
 ## Artifacts and storage
 
 Writer run artifacts live under `.neal/runs/<run-id>/`, including the original-plan backup at `.neal/runs/<run-id>/PLAN_ORIGINAL.md` and reviewer scratch space under `.neal/runs/<run-id>/scratch/`. Queue artifacts live under `.neal/queues/<queue-id>/`. Review findings artifacts live under `.neal/reviews/<review-id>/`.

package/dist/neal/agents/prompts.js

@@ -50,6 +50,7 @@ export function buildConsultantPrompt(args) {
 }
 export function buildBlockedRecoveryCoderPrompt(args) {
     const allowReplacement = args.allowReplacement ?? true;
+    const laterScopeRevision = args.terminalOnly ? null : args.laterScopeRevision ?? null;
     const actionLines = [
         '- `resume_current_scope`',
         ...(allowReplacement ? ['- `replace_current_scope`'] : []),
@@ -87,6 +88,14 @@ export function buildBlockedRecoveryCoderPrompt(args) {
         allowReplacement
             ? 'Always include a `replacementPlan` string. Use an empty string unless action=`replace_current_scope`.'
             : 'Always include an empty `replacementPlan` string.',
+        ...(laterScopeRevision
+            ? [
+                'Always include an integer `laterScopeNumber` and a `laterScopeBody` string. Use `0` and an empty string unless the operator guidance directs a change to a later top-level scope.',
+                `The operator guidance may direct a change to one later scope of the top-level plan at ${laterScopeRevision.topLevelPlanDoc}. The current top-level scope is ${laterScopeRevision.currentScopeNumber}; eligible target scopes are ${laterScopeRevision.currentScopeNumber + 1} through ${laterScopeRevision.scopeCount}.`,
+                'To revise a later scope, set `laterScopeNumber` to the target scope number and `laterScopeBody` to the complete replacement text of that one `### Scope N:` entry. The body must start with the line `### Scope N:` for the same N (the title after the colon may change), must contain no other `### ` or `## ` heading, and must keep the `- Goal:`, `- Verification:`, and `- Success Condition:` bullets.',
+                'A later-scope revision may accompany action=`resume_current_scope` or action=`stay_blocked` only. Set both fields or neither. Do not revise the current scope, an earlier scope, or a derived plan this way, and do not edit the plan file yourself: Neal validates the revised plan and writes it. Put the reasoning for the revision in `rationale`.',
+            ]
+            : ['Always include `laterScopeNumber` as `0` and `laterScopeBody` as an empty string.']),
         ...(allowReplacement
             ? [
                 'When action=`replace_current_scope`, `replacementPlan` must use the same Neal-executable contract as a top-level plan.',

package/dist/neal/agents/rounds.js

@@ -1,5 +1,6 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { getAgentTurnRetryLimit, getAgentTurnStartupTimeoutMs, getApiRetryLimit, getInactivityTimeoutMs, } from '../config.js';
+import { getReviewLevel } from '../config.js';
 import { runWithAgentTurnLiveness } from '../providers/liveness.js';
 import { normalizeExecutionShapeDeclaration } from '../plan-validation.js';
 import { getCoderAdapter, getProviderDefinition, getStructuredAdvisorAdapter } from '../providers/registry.js';
@@ -176,7 +177,13 @@ export async function runReviewerRound(args) {
         cwd: args.cwd,
         // The doctrine access mode comes from the reviewer provider's declared
         // structured-advisor tool access, not from inline-context presence alone.
-        prompt: buildReviewerPrompt({ ...args, accessMode: getReviewerDoctrineAccessMode(args.reviewer) }),
+        // The review level comes from current config (`neal.review_level`), not
+        // persisted run state; the builder itself never reads config.
+        prompt: buildReviewerPrompt({
+            ...args,
+            accessMode: getReviewerDoctrineAccessMode(args.reviewer),
+            reviewLevel: getReviewLevel(args.cwd),
+        }),
         schema,
         structuredJsonProtocol: buildStructuredJsonProtocolSpec({
             schemaLabel: 'reviewer_payload',
@@ -334,7 +341,13 @@ export async function runReviewerFinalCompletionRound(args) {
         cwd: args.cwd,
         // The doctrine access mode comes from the reviewer provider's declared
         // structured-advisor tool access, not from inline-context presence alone.
-        prompt: buildFinalCompletionReviewerPrompt({ ...args, accessMode: getReviewerDoctrineAccessMode(args.reviewer) }),
+        // The review level comes from current config (`neal.review_level`), not
+        // persisted run state; the builder itself never reads config.
+        prompt: buildFinalCompletionReviewerPrompt({
+            ...args,
+            accessMode: getReviewerDoctrineAccessMode(args.reviewer),
+            reviewLevel: getReviewLevel(args.cwd),
+        }),
         schema,
         structuredJsonProtocol: buildStructuredJsonProtocolSpec({
             schemaLabel: 'final_completion_reviewer_payload',
@@ -629,6 +642,15 @@ export async function runCoderResponseRound(args) {
 export async function runBlockedRecoveryCoderRound(args) {
     const progressText = await safeReadText(args.progressMarkdownPath);
     const schema = buildCoderBlockedRecoveryDispositionSchema();
+    const laterScopeRevision = args.terminalOnly ? null : args.laterScopeRevision ?? null;
+    const laterScopeContext = laterScopeRevision
+        ? {
+            allowLaterScopeRevision: true,
+            currentScopeNumber: laterScopeRevision.currentScopeNumber,
+            planDocument: laterScopeRevision.planDocument,
+        }
+        : null;
+    const validator = (rawPayload) => validateCoderBlockedRecoveryDispositionPayload(rawPayload, laterScopeContext);
     const { sessionHandle, structured } = await runCoderStructuredPrompt({
         coder: args.coder,
         cwd: args.cwd,
@@ -642,20 +664,27 @@ export async function runBlockedRecoveryCoderRound(args) {
             turnsTaken: args.turnsTaken,
             terminalOnly: args.terminalOnly,
             allowReplacement: args.allowReplacement,
+            laterScopeRevision: laterScopeRevision
+                ? {
+                    topLevelPlanDoc: laterScopeRevision.topLevelPlanDoc,
+                    currentScopeNumber: laterScopeRevision.currentScopeNumber,
+                    scopeCount: laterScopeRevision.scopeCount,
+                }
+                : null,
         }),
         schema,
         label: 'Coder blocked-recovery round',
         structuredJsonProtocol: buildStructuredJsonProtocolSpec({
             schemaLabel: 'coder_blocked_recovery_disposition_payload',
             schema,
-            validator: validateCoderBlockedRecoveryDispositionPayload,
+            validator,
         }),
         resumeHandle: args.sessionHandle,
         logger: args.logger,
     });
     return {
         sessionHandle,
-        payload: validateCoderBlockedRecoveryDispositionPayload(structured),
+        payload: validator(structured),
     };
 }
 export async function runCoderPlanResponseRound(args) {

package/dist/neal/agents/schemas.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { reviseLaterScope } from '../plan-scope-revision.js';
 import { normalizeExecutionShapeDeclaration, validatePlanDocument } from '../plan-validation.js';
 import { repairReviewerSquashMessageDraft, validateReviewerSquashMessageDraft } from '../squash-message.js';
 export const EXECUTE_SCOPE_PROGRESS_PAYLOAD_START = 'NEAL_PROGRESS_JUSTIFICATION_JSON_START';
@@ -101,6 +102,8 @@ const coderBlockedRecoveryDispositionPayloadSchema = z.object({
     rationale: z.string(),
     blocker: z.string(),
     replacementPlan: z.string(),
+    laterScopeNumber: z.number(),
+    laterScopeBody: z.string(),
 });
 const coderPlanResponsePayloadSchema = z.object({
     outcome: z.enum(CODER_PLAN_RESPONSE_OUTCOMES),
@@ -823,7 +826,33 @@ function validateManualGateResumeChecks(value) {
         };
     });
 }
-export function validateCoderBlockedRecoveryDispositionPayload(rawPayload) {
+export function getCoderBlockedRecoveryLaterScopeErrors(payload, context) {
+    const hasNumber = payload.laterScopeNumber !== 0;
+    const hasBody = payload.laterScopeBody.trim().length > 0;
+    if (!hasNumber && !hasBody) {
+        return [];
+    }
+    if (!Number.isInteger(payload.laterScopeNumber) || payload.laterScopeNumber < 0) {
+        return [`laterScopeNumber must be a non-negative integer, received ${String(payload.laterScopeNumber)}.`];
+    }
+    if (hasNumber !== hasBody) {
+        return ['laterScopeNumber and laterScopeBody must be set together: both for a later-scope revision, or 0 and an empty string.'];
+    }
+    if (context === null || !context.allowLaterScopeRevision) {
+        return ['A later-scope revision is not available for this round; return laterScopeNumber=0 and an empty laterScopeBody.'];
+    }
+    if (payload.action !== 'resume_current_scope' && payload.action !== 'stay_blocked') {
+        return [`A later-scope revision may accompany only action=resume_current_scope or action=stay_blocked, not action=${payload.action}.`];
+    }
+    const result = reviseLaterScope({
+        planDocument: context.planDocument,
+        currentScopeNumber: context.currentScopeNumber,
+        targetScopeNumber: payload.laterScopeNumber,
+        replacementBody: payload.laterScopeBody,
+    });
+    return result.ok ? [] : result.errors;
+}
+export function validateCoderBlockedRecoveryDispositionPayload(rawPayload, laterScopeContext = null) {
     const payload = parsePayload(coderBlockedRecoveryDispositionPayloadSchema, rawPayload, 'Coder blocked-recovery payload');
     const blocker = payload.blocker.trim();
     const replacementPlan = payload.replacementPlan.trim();
@@ -836,6 +865,10 @@ export function validateCoderBlockedRecoveryDispositionPayload(rawPayload) {
     if ((payload.action === 'stay_blocked' || payload.action === 'terminal_block') && !blocker) {
         throw new Error(`Coder blocked-recovery round returned action=${payload.action} without a blocker payload.`);
     }
+    const laterScopeErrors = getCoderBlockedRecoveryLaterScopeErrors(payload, laterScopeContext);
+    if (laterScopeErrors.length > 0) {
+        throw new Error(`Coder blocked-recovery round returned an invalid later-scope revision: ${laterScopeErrors.join(' ')}`);
+    }
     return payload;
 }
 export function parseFinalCompletionSummaryPayload(rawPayload) {

package/dist/neal/commands/check.js

@@ -2,7 +2,7 @@ import { createInterface } from 'node:readline/promises';
 import process from 'node:process';
 import { verifyNotification } from '../../notifier.js';
 import { parseCheckArgs } from '../cli.js';
-import { assertWriterProvidersConfigured, getAgentTurnRetryLimit, getAgentTurnStartupTimeoutMs, getApiRetryLimit, getFinalCompletionContinueExecutionMax, getInactivityTimeoutMs, getInteractiveBlockedRecoveryMaxTurns, getMaxReviewRounds, getNotifyBin, getPhaseHeartbeatMs, getReviewStuckWindow, } from '../config.js';
+import { assertWriterProvidersConfigured, getAgentTurnRetryLimit, getAgentTurnStartupTimeoutMs, getApiRetryLimit, getFinalCompletionContinueExecutionMax, getInactivityTimeoutMs, getInteractiveBlockedRecoveryMaxTurns, getMaxReviewRounds, getNotifyBin, getPhaseHeartbeatMs, getReviewLevel, getReviewStuckWindow, } from '../config.js';
 import { getNealDirGitIgnoreStatus } from '../git.js';
 import { collectGuidanceDiagnostics, USER_GUIDANCE_MAX_CHARS } from '../prompts/guidance.js';
 import { runWithAgentTurnLiveness } from '../providers/liveness.js';
@@ -65,6 +65,7 @@ function validateConfig(cwd) {
     getInteractiveBlockedRecoveryMaxTurns(cwd);
     getFinalCompletionContinueExecutionMax(cwd);
     getNotifyBin(cwd);
+    getReviewLevel(cwd);
     return agentConfig;
 }
 async function promptForProviderVerification(stdin, stdout) {

package/dist/neal/commands/resume-run.js

@@ -2,7 +2,7 @@ import process from 'node:process';
 import { readdir, stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { parseResumeArgs } from '../cli.js';
-import { assertWriterProvidersConfigured } from '../config.js';
+import { assertWriterProvidersConfigured, getReviewLevel } from '../config.js';
 import { writeDiagnostic } from '../diagnostic.js';
 import { assertGitRepositoryWithCommit } from '../git.js';
 import { loadOrInitialize } from '../orchestrator.js';
@@ -261,6 +261,12 @@ function emitAlreadyRunningOutcome(selection) {
     return { kind: 'already_running' };
 }
 async function withResumeWriterLock(selection, evidence, action) {
+    // Every path that resumes writer work (plain, manual gate, --message) goes
+    // through this seam. The review level is read from current config, not
+    // persisted run state, so it is validated here before the lock is taken or
+    // any run state is rewritten. No-op and rejection outcomes (done, already
+    // running, waiting for guidance) are decided earlier and never reach it.
+    getReviewLevel(selection.state.cwd);
     let lock;
     try {
         lock = await acquireResumeWriterLock(selection, evidence);

package/dist/neal/config.js

@@ -3,6 +3,7 @@ import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import YAML from 'yaml';
 import { assertAgentConfigSupportsWriterRun, parseProviderId, } from './providers/registry.js';
+const REVIEW_LEVELS = ['strict', 'moderate', 'lenient'];
 const OPENAI_COMPATIBLE_DEFAULT_API_KEY_ENV = 'OPENAI_COMPATIBLE_API_KEY';
 const WRITER_PROVIDER_CONFIG_KEYS = {
     coder: 'agent.coder.provider',
@@ -22,6 +23,7 @@ const DEFAULT_CONFIG = {
         final_completion_continue_execution_max: 3,
         consultant_max_attempts: 1,
         notify_bin: null,
+        review_level: 'moderate',
     },
     agent: {
         planner: {
@@ -101,6 +103,22 @@ function parseNumberValue(value) {
 function parseStringValue(value) {
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }
+function isReviewLevel(value) {
+    return REVIEW_LEVELS.includes(value);
+}
+function parseReviewLevelValue(value, fieldPath) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === 'string' && !value.trim()) {
+        return undefined;
+    }
+    const level = typeof value === 'string' ? value.trim() : value;
+    if (typeof level !== 'string' || !isReviewLevel(level)) {
+        throw new Error(`Invalid review level for ${fieldPath}: ${JSON.stringify(level)}. Valid values: ${REVIEW_LEVELS.join(', ')}`);
+    }
+    return level;
+}
 function parseConfigProviderValue(value, fieldPath) {
     if (value === undefined || value === null) {
         return undefined;
@@ -255,8 +273,13 @@ export function assertWriterProvidersConfigured(cwd = process.cwd(), options = {
         throw new WriterProvidersNotConfiguredError(options.guidance ?? 'writer-run', missingProviderKeys);
     }
     assertAgentConfigSupportsWriterRun(agentConfig, { context: options.context });
+    getReviewLevel(cwd);
     return agentConfig;
 }
+export function getReviewLevel(cwd = process.cwd()) {
+    const config = loadConfigFile(cwd);
+    return parseReviewLevelValue(config.neal?.review_level, 'neal.review_level') ?? DEFAULT_CONFIG.neal.review_level;
+}
 export function getInactivityTimeoutMs(cwd = process.cwd()) {
     const config = loadConfigFile(cwd);
     return (parseNumberValue(config.neal?.inactivity_timeout_ms) ??

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

@@ -2,7 +2,7 @@ import { AGENT_FREE_TEXT_SECTION_MAX_CHARS, boundChangedFileList, boundCommitSub
 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 = [
@@ -136,6 +136,7 @@ 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
@@ -183,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,

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

@@ -1,3 +1,4 @@
+const DEFAULT_REVIEW_LEVEL = 'moderate';
 export function getAdversarialReviewDoctrineLines(context) {
     const falsificationTarget = context.falsificationTarget ?? 'the implementation';
     const creditPhrase = context.creditPhrase ?? 'give it credit for working';
@@ -83,11 +84,46 @@ export function getPreexistingFailureContractLines(context = {}) {
         'Conversely, treat a fix for a pre-existing issue that fails the acceptance-surface test as scope drift rather than extra credit: flag it so the change stays bounded to the plan.',
     ];
 }
+function getReviewLevelTrustBoundaryLine(level) {
+    switch (level) {
+        case 'strict':
+            return 'Review level: strict. Assume adversarial trust boundaries: treat every input, file, and process the change can be reached from, including local processes and internal run artifacts, as a potential attacker. A hardening gap or a missing defense against a local or adversarial actor is a reachable failure under these boundaries and blocks.';
+        case 'lenient':
+            return 'Review level: lenient. Assume ordinary trust boundaries and block only on correctness failures and real, reachable bugs. Do not demand additional robustness, hardening, performance, or style work as a condition of acceptance.';
+        case 'moderate':
+            return 'Review level: moderate. Assume ordinary trust boundaries: internal run artifacts and other files this system writes for itself are not security boundaries. Block on correctness bugs and on failures reachable under normal use. Do not require defenses against an actor who could already subvert the system directly, for example by editing its files; a failure that needs such an actor is not reachable.';
+    }
+}
+function getDemotedCategoryMeaning(outputContract) {
+    return outputContract === 'completion_verdict'
+        ? 'In this review a demoted or ignored category is not missing work: it must not produce `continue_execution` or `block_for_operator`, and when the plan objectives are otherwise satisfied you return `accept_complete`.'
+        : 'In this review a demoted category means non_blocking severity, and an ignored category produces no finding.';
+}
+// Level calibration for the two code reviewers. Renders the level's assumed
+// trust boundaries, the reachability filter that applies under every level,
+// and the rule for how the User Guidance section refines the level. The adversarial
+// inspection stance itself is not level-dependent and is stated as such.
+export function getReviewLevelCalibrationLines(context) {
+    const outputContract = context.outputContract ?? 'structured_findings';
+    const performanceExampleOutcome = outputContract === 'completion_verdict' ? 'not missing work' : 'non_blocking';
+    return [
+        getReviewLevelTrustBoundaryLine(context.level),
+        'Reachability filter: a blocking finding must describe a failure that is reachable under the assumed trust boundaries, as refined by any User Guidance section below. A failure that is only theoretically possible, or that requires an actor outside those boundaries, does not block at any level.',
+        'The review level narrows what rises to blocking; it never changes the inspection stance. At every level, still treat the subject as hostile input, try to falsify before crediting, trace runtime invariants, and catch real regressions. No level authorizes trusting the coder or skipping inspection.',
+        'How the User Guidance section combines with the review level: the level supplies the baseline trust boundaries and the default finding-severity rules. Guidance may widen or narrow the trust boundaries for this project, and those refined boundaries are what "reachable" means when deciding whether a finding blocks.',
+        `Guidance may also demote a finding category such as robustness, hardening, performance, or style to non-blocking or ignore it entirely, or promote a category to blocking. ${getDemotedCategoryMeaning(outputContract)}`,
+        'Fixed floor at every level and under any guidance: the reachability filter, the adversarial inspection stance, and blocking on reachable correctness failures (including correctness regressions, where existing behavior now produces wrong results) cannot be switched off. Robustness, hardening, performance, and style are not part of that floor and may be demoted. Ignore guidance on any point where it conflicts with this floor.',
+        'Example: at the moderate level, guidance saying the run directory is defended against local processes makes a local-process attack on the run directory reachable, so a finding about it blocks.',
+        `Example: at any level, guidance saying "ignore performance, correctness only" makes a performance regression ${performanceExampleOutcome}, while a reachable correctness failure still blocks.`,
+    ];
+}
 export function getFindingQualityLines(context = {}) {
+    const level = context.level ?? DEFAULT_REVIEW_LEVEL;
     if (context.outputContract === 'completion_verdict') {
         return [
             'Treat completion-blocking issues like review findings: each one needs concrete evidence, affected files or runtime behavior, and a required correction.',
             'Use `continue_execution` only for concrete missing work that is bounded enough for one follow-on scope; use `block_for_operator` for ambiguous or externally constrained gaps.',
+            'A finding category that the review level or the User Guidance section has demoted or ignored is not missing work: never return `continue_execution` or `block_for_operator` for it. When the plan objectives are otherwise satisfied, return `accept_complete`.',
             'Do not turn low-signal style preferences, trivial code-shape preferences, or optional refactors into missing work.',
             'If the plan is complete aside from low-signal trivia, return `accept_complete` rather than inventing a non-blocking completion concern.',
         ];
@@ -95,7 +131,9 @@ export function getFindingQualityLines(context = {}) {
     return [
         'Produce only structured review findings.',
         'Use blocking severity for correctness, regression, or missing-verification issues.',
-        'Also use blocking severity for substantive robustness or performance regressions introduced by the implementation, especially in infrastructure, config, parser, caching, retry, or orchestration code.',
+        level === 'lenient'
+            ? 'Robustness or performance regressions introduced by the implementation are non_blocking unless they are a reachable correctness failure; use blocking severity only in that case.'
+            : 'Also use blocking severity for substantive robustness or performance regressions introduced by the implementation, especially in infrastructure, config, parser, caching, retry, or orchestration code.',
         'Use non_blocking severity for suggestions that do not block acceptance.',
         'Only emit non_blocking findings when they identify a concrete maintenance, observability, or testability issue that is genuinely worth a later follow-up turn.',
         'Do not emit non_blocking findings for formatting, whitespace, naming preferences, trivial code-shape preferences, or optional refactors.',

package/dist/neal/prompts/specialized.js

@@ -2,7 +2,7 @@ import { guardStructuredJsonOutputFormatLines } from '../agents/structured-json.
 import { AGENT_FREE_TEXT_SECTION_MAX_CHARS, boundChangedFileList, boundCommitSubjectList, boundFreeTextValues, GIT_SUMMARY_SECTION_MAX_CHARS, renderInlinedRangeDiffSection, truncateInlineSectionBody, } from '../context/inline-review-context.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/specialized.ts';
 // Guarded output-format instruction block shared by the two structured-JSON
 // completion base prompts. It emits only JSON-only framing and a
@@ -143,6 +143,7 @@ export function buildFinalCompletionReviewerPrompt(args) {
         throw new Error('Prompt spec completion_reviewer is missing a final_completion variant');
     }
     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
@@ -201,6 +202,7 @@ export function buildFinalCompletionReviewerPrompt(args) {
             judgmentTarget: 'whole-plan completion',
             proofTarget: 'the aggregate implementation satisfies the plan',
         }),
+        ...getReviewLevelCalibrationLines({ level: reviewLevel, outputContract: 'completion_verdict' }),
         ...falsificationLines,
         ...scratchLines,
         'Falsify cross-scope runtime invariants and integration behavior before accepting completion, especially paths that individual scope reviews could not see together.',
@@ -208,7 +210,7 @@ export function buildFinalCompletionReviewerPrompt(args) {
         ...skepticismLines,
         ...regressionLines,
         ...preexistingLines,
-        ...getFindingQualityLines({ outputContract: 'completion_verdict' }),
+        ...getFindingQualityLines({ outputContract: 'completion_verdict', level: reviewLevel }),
         'Review the whole-plan result for correctness and completeness against the plan objectives, regressions or missing behavior, cross-scope integration issues that may not have been visible in individual scope reviews, code quality, maintainability, and consistency of the final implementation, and adequacy of test coverage and verification for the total change.',
         ...getReviewerContextLines(args.reviewerContext),
         'Do not treat prior per-scope acceptance as sufficient evidence that the whole plan is complete or that the aggregate code quality is acceptable.',

package/dist/neal/prompts/specs.js

@@ -67,6 +67,7 @@ const SCOPE_REVIEWER_CONTEXT = context('ScopeReviewerPromptContext', [
     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."),
+    field('reviewLevel', 'orchestrator_state', false, "Reviewer strictness ('strict', 'moderate', or 'lenient') from the `neal.review_level` config key, resolved by rounds.ts via getReviewLevel(cwd). Defaults to 'moderate' when absent."),
 ]);
 const COMPLETION_CODER_CONTEXT = context('CompletionCoderPromptContext', [
     field('planDoc', 'prompt_argument', true, 'Path to the execute-mode plan being evaluated for final completion.'),
@@ -80,6 +81,7 @@ const COMPLETION_REVIEWER_CONTEXT = context('CompletionReviewerPromptContext', [
     field('scratchDir', 'run_artifact', true, 'Run-local final-completion reviewer scratch directory for temporary verification artifacts.'),
     field('repositoryState', 'repository_state', true, 'Current repository state used to judge whole-plan completion.'),
     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."),
+    field('reviewLevel', 'orchestrator_state', false, "Reviewer strictness ('strict', 'moderate', or 'lenient') from the `neal.review_level` config key, resolved by rounds.ts via getReviewLevel(cwd). Defaults to 'moderate' when absent."),
 ]);
 const CONSULTANT_CONTEXT = context('ConsultantPromptContext', [
     field('blockedReason', 'prompt_argument', true, 'Blocked reason reported by the stalled coder or reviewer turn.'),
@@ -287,7 +289,7 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'scope_coder',
-        version: 2,
+        version: 3,
         changelog: [
             {
                 version: 1,
@@ -297,6 +299,10 @@ export const PROMPT_SPECS = [
                 version: 2,
                 renderSha: '0ce921ee7d0acc4042bacf31e1509968f7e76df8db8417eb4b724ce7842794ac',
             },
+            {
+                version: 3,
+                renderSha: '8fb94430bf9d9abcb11f905106a3a04fc1b81bd101104c88f84a8693f705c5ea',
+            },
         ],
         role: 'coder',
         purpose: 'Execute exactly one bounded implementation scope and respond to in-scope review feedback without starting new scopes.',
@@ -400,7 +406,7 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'scope_reviewer',
-        version: 4,
+        version: 5,
         changelog: [
             {
                 version: 1,
@@ -418,6 +424,10 @@ export const PROMPT_SPECS = [
                 version: 4,
                 renderSha: 'da87b19f2401ffdca21e3cefec1037c6470b3e74810b6152d07c55fa4924047f',
             },
+            {
+                version: 5,
+                renderSha: 'e8dcb976d0ea22e9026e09a87d7dde93c8513334f62ad89472ebefe91771754b',
+            },
         ],
         role: 'reviewer',
         purpose: 'Review execute-scope results for correctness, verification coverage, and meaningful progress toward the active parent objective.',
@@ -475,6 +485,7 @@ export const PROMPT_SPECS = [
                         field('parentScopeLabel', 'orchestrator_state', true, 'Active parent objective label.'),
                         field('scratchDir', 'run_artifact', true, 'Run-local scratch directory for reviewer verification artifacts.'),
                         field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access' or 'read-only'); defaults to 'tool-access' when absent."),
+                        field('reviewLevel', 'orchestrator_state', false, "Optional reviewer strictness ('strict', 'moderate', or 'lenient') from `neal.review_level`, resolved by rounds.ts via getReviewLevel(cwd); defaults to 'moderate' when absent."),
                     ]),
                 },
                 schemaTarget: {
@@ -573,7 +584,7 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'completion_reviewer',
-        version: 4,
+        version: 5,
         changelog: [
             {
                 version: 1,
@@ -591,6 +602,10 @@ export const PROMPT_SPECS = [
                 version: 4,
                 renderSha: 'c47009016178fc29c34440e06636ba7b21c6beb59202dd3fe63e365cb32a75cf',
             },
+            {
+                version: 5,
+                renderSha: '7930cec95560ad880bba94a7ae48e68c621805787261e295c4c405d09235c87b',
+            },
         ],
         role: 'reviewer',
         purpose: 'Judge whole-plan completion and decide whether Neal should accept completion, continue execution, or block for operator input.',
@@ -637,6 +652,7 @@ export const PROMPT_SPECS = [
                         field('summary', 'review_history', true, 'Coder-authored completion summary.'),
                         field('scratchDir', 'run_artifact', true, 'Run-local scratch directory for final-completion reviewer artifacts.'),
                         field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access' or 'read-only'); defaults to 'tool-access' when absent."),
+                        field('reviewLevel', 'orchestrator_state', false, "Optional reviewer strictness ('strict', 'moderate', or 'lenient') from `neal.review_level`, resolved by rounds.ts via getReviewLevel(cwd); defaults to 'moderate' when absent."),
                     ]),
                 },
                 schemaTarget: {

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

@@ -344,7 +344,7 @@ async function readRunStates(cwd) {
     const runsDir = getRunsDir(cwd);
     let entries;
     try {
-        entries = await readdir(runsDir);
+        entries = await readdir(runsDir, { withFileTypes: true });
     }
     catch (error) {
         if (isMissingFileError(error)) {
@@ -353,7 +353,14 @@ async function readRunStates(cwd) {
         throw error;
     }
     const states = {};
-    for (const entry of entries.sort()) {
+    // Only directories are runs. The runs root also collects stray files such as
+    // macOS `.DS_Store`, and joining a run-state path onto one of those reads
+    // through a non-directory.
+    const runDirNames = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+    for (const entry of runDirNames) {
         const statePath = getRunStatePath(join(runsDir, entry));
         const content = await readOptionalText(statePath);
         if (content !== null) {
@@ -374,6 +381,13 @@ function assertSameStringMap(before, after, label) {
         }
     }
 }
+// A run-state path can be unreadable because nothing is there (`ENOENT`) or
+// because a path segment is not a directory (`ENOTDIR`, e.g. a stray file in the
+// runs root). Both mean "no run state here", never a review failure.
 function isMissingFileError(error) {
-    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+    if (typeof error !== 'object' || error === null || !('code' in error)) {
+        return false;
+    }
+    const code = error.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
 }

package/dist/neal/state-invariants.js

@@ -169,8 +169,14 @@ function assertValidInteractiveBlockedRecoveryState(args) {
     if (recovery.lastHandledTurn > recovery.turns.length) {
         throwStateInvariant(context, `${fieldPath}.lastHandledTurn`, `must not exceed recorded turn count ${recovery.turns.length}`);
     }
-    if (recovery.turns.length > recovery.maxTurns) {
-        throwStateInvariant(context, `${fieldPath}.turns`, `recorded turn count ${recovery.turns.length} exceeds maxTurns ${recovery.maxTurns}`);
+    // A recovery that reaches the turn cap and is then resolved by a turn-cap
+    // terminal directive records one terminal-resolution turn beyond `maxTurns`,
+    // so the recorded count may be `maxTurns + 1`. That extra turn is only ever
+    // the terminal resolution: past the cap, new guidance becomes a
+    // `pendingDirective` rather than an appended turn, so nothing else can push
+    // the count higher.
+    if (recovery.turns.length > recovery.maxTurns + 1) {
+        throwStateInvariant(context, `${fieldPath}.turns`, `recorded turn count ${recovery.turns.length} exceeds maxTurns ${recovery.maxTurns} by more than the one terminal-resolution turn`);
     }
     if (recovery.pendingDirective) {
         assertNonEmptyString(recovery.pendingDirective.recordedAt, `${fieldPath}.pendingDirective.recordedAt`, context);

package/dist/neal/state.js

@@ -11,6 +11,7 @@ import { refreshActiveRunLock } from './run-lock.js';
 import { validateReviewerSquashMessageDraft } from './squash-message.js';
 import { assertOrchestrationPhase, assertOrchestrationStatus, assertValidOrchestrationState, } from './state-invariants.js';
 const TOP_LEVEL_MODES = new Set(['plan', 'execute']);
+const INTERACTIVE_BLOCKED_RECOVERY_TURN_ORIGINS = ['operator', 'consultant'];
 const INTERACTIVE_BLOCKED_RECOVERY_SOURCE_PHASES = new Set([
     'coder_plan',
     'reviewer_plan',
@@ -257,6 +258,16 @@ function readNullableString(record, key, fieldPath = key) {
     }
     throwInvalidState(fieldPath, `expected string or null, received ${formatStateValue(value)}`);
 }
+function readOptionalString(record, key, fieldPath = key) {
+    if (!hasOwn(record, key)) {
+        return undefined;
+    }
+    const value = record[key];
+    if (typeof value === 'string') {
+        return value;
+    }
+    throwInvalidState(fieldPath, `expected string, received ${formatStateValue(value)}`);
+}
 function readOptionalBoolean(record, key, fieldPath = key) {
     if (!hasOwn(record, key)) {
         return undefined;
@@ -646,6 +657,8 @@ function hydrateInteractiveBlockedRecoveryTurnDisposition(value, fieldPath) {
         rationale: readString(disposition, 'rationale', `${fieldPath}.rationale`),
         blocker: readString(disposition, 'blocker', `${fieldPath}.blocker`),
         replacementPlan: readString(disposition, 'replacementPlan', `${fieldPath}.replacementPlan`),
+        laterScopeNumber: readOptionalSafeInteger(disposition, 'laterScopeNumber', `${fieldPath}.laterScopeNumber`) ?? 0,
+        laterScopeBody: readOptionalString(disposition, 'laterScopeBody', `${fieldPath}.laterScopeBody`) ?? '',
         resultingPhase: readOrchestrationPhase(disposition, 'resultingPhase', `${fieldPath}.resultingPhase`),
     };
 }
@@ -655,6 +668,7 @@ function hydrateInteractiveBlockedRecoveryTurn(value, fieldPath) {
         number: readSafeInteger(turn, 'number', `${fieldPath}.number`),
         recordedAt: readString(turn, 'recordedAt', `${fieldPath}.recordedAt`),
         operatorGuidance: readString(turn, 'operatorGuidance', `${fieldPath}.operatorGuidance`),
+        origin: readOptionalNullableEnum(turn, 'origin', INTERACTIVE_BLOCKED_RECOVERY_TURN_ORIGINS, `${fieldPath}.origin`) ?? null,
         disposition: hydrateInteractiveBlockedRecoveryTurnDisposition(readRequired(turn, 'disposition', `${fieldPath}.disposition`), `${fieldPath}.disposition`),
     };
 }
@@ -667,6 +681,7 @@ function hydrateInteractiveBlockedRecoveryDirective(value, fieldPath) {
         recordedAt: readString(directive, 'recordedAt', `${fieldPath}.recordedAt`),
         operatorGuidance: readString(directive, 'operatorGuidance', `${fieldPath}.operatorGuidance`),
         terminalOnly: readBoolean(directive, 'terminalOnly', `${fieldPath}.terminalOnly`),
+        origin: readOptionalNullableEnum(directive, 'origin', INTERACTIVE_BLOCKED_RECOVERY_TURN_ORIGINS, `${fieldPath}.origin`) ?? null,
     };
 }
 const CONSULTANT_TRIAGE_CATEGORIES = [

package/dist/neal/support.js

@@ -17,9 +17,13 @@ function appendInteractiveBlockedRecoverySection(lines, title, recovery, options
         return;
     }
     for (const turn of recovery.turns) {
-        lines.push(`- Recovery turn ${turn.number} at ${turn.recordedAt}: ${turn.operatorGuidance}`);
+        lines.push(`- Recovery turn ${turn.number} at ${turn.recordedAt} (${turn.origin ?? 'unrecorded'} origin): ${turn.operatorGuidance}`);
         if (turn.disposition) {
-            lines.push(`- Recovery turn ${turn.number} coder action: ${turn.disposition.action}`, `- Recovery turn ${turn.number} coder summary: ${turn.disposition.summary}`, `- Recovery turn ${turn.number} coder blocker: ${turn.disposition.blocker || 'n/a'}`, `- Recovery turn ${turn.number} coder rationale: ${turn.disposition.rationale}`, `- Recovery turn ${turn.number} resulting step: ${formatPublicPhase(turn.disposition.resultingPhase)}`);
+            lines.push(`- Recovery turn ${turn.number} coder action: ${turn.disposition.action}`, `- Recovery turn ${turn.number} coder summary: ${turn.disposition.summary}`, `- Recovery turn ${turn.number} coder blocker: ${turn.disposition.blocker || 'n/a'}`, `- Recovery turn ${turn.number} coder rationale: ${turn.disposition.rationale}`);
+            if (turn.disposition.laterScopeNumber > 0) {
+                lines.push(`- Recovery turn ${turn.number} revised later scope: ${turn.disposition.laterScopeNumber}`, `- Recovery turn ${turn.number} revised scope text:`, ...turn.disposition.laterScopeBody.split('\n').map((line) => `  ${line}`));
+            }
+            lines.push(`- Recovery turn ${turn.number} resulting step: ${formatPublicPhase(turn.disposition.resultingPhase)}`);
         }
         else {
             lines.push(`- Recovery turn ${turn.number} coder response: pending`);

package/docs/plan-format.md

@@ -74,6 +74,16 @@ declares and owns its own execution shape. Plans authored `multi_scope` or
 `multi_scope_unknown` are unaffected. Refinement may adjust their scope
 content as usual.
 
+### Revising a later scope mid-run
+
+Operator guidance during a block can revise a later scope. When a
+`neal resume --message` directive calls for changing a scope after the current
+one, the coder returns replacement text for that one scope, and neal splices it
+into the plan, checks it still parses, and writes it. neal reads the plan fresh
+from disk each turn, so the next scope runs against the revised text. The coder
+can only revise a scope after the one it's working on, never the current or an
+earlier scope, and a consultant-injected directive can't trigger it.
+
 ## Multi-scope format
 
 `executionShape: multi_scope` must include a literal `## Execution Queue`

package/docs/prompt-specs.md

@@ -361,6 +361,8 @@ testing or profile experiments. That override wins over the default directory.
 
 When present, the file contents are appended under a fixed `## User Guidance` section inside the built-in prompt. Structured output contracts, completion markers, and the canonical plan contract survive injection.
 
+In the scope reviewer and final-completion reviewer prompts, `## User Guidance` renders after the `neal.review_level` calibration lines (`getReviewLevelCalibrationLines` in [src/neal/prompts/review-doctrine.ts](../src/neal/prompts/review-doctrine.ts)). The level supplies the baseline trust boundaries and the default finding-severity rules; guidance may widen or narrow those boundaries and demote or promote finding categories, and the refined boundaries are what "reachable" means when the reviewer decides whether a finding blocks. Guidance can't remove the floor: the reachability filter, the adversarial stance, and blocking on reachable correctness failures (including correctness regressions) stay on at every level. The calibration text itself states this merge rule, so the precedence is rendered in the prompt rather than implied by section order.
+
 Diagnostics: when a neal writer run initializes or resumes, it logs which roles have guidance applied and the byte count to the run's `stderr.log` and as a `run.user_guidance_applied` / `run.user_guidance_scanned` event. That is enough to confirm a guidance file was picked up without dumping contents.
 
 Non-goals: no repo-local `.neal/guidance/` override, no full-prompt replacement, no per-scope guidance variants, and no substitution of built-in sections.

package/docs/state-machine.md

@@ -79,6 +79,12 @@ Site A below). The consultant is read-only: it never grants authorization, expan
 scope, or waives verification gates. A recoverable verdict acts automatically. A
 non-recoverable verdict yields to the operator, carrying the verdict as advice.
 
+Each recovery turn records its `origin` — `operator` for a `neal resume --message`
+directive, `consultant` for a consultant injection — and the same marker rides the
+turn-cap `pendingDirective`. A later-scope revision is offered only on an
+operator-origin turn, so a consultant directive can direct the current scope but
+never rewrites a later scope on its own.
+
 Public resume eligibility is classified by `src/neal/resume-decision.ts` before
 any recovery mutation. That read-only decision layer combines loaded child-run
 state with lock, queue, and retrospective evidence, then returns the shared

package/neal.yml

@@ -42,6 +42,15 @@
 #   # for more work before neal stops reopening the plan.
 #   final_completion_continue_execution_max: 3
 #
+#   # How strict the scope and final-completion reviewers are about what
+#   # rises to a blocking finding. Under every level a blocking finding must
+#   # describe a failure reachable under the assumed trust boundaries.
+#   #   strict:   assume adversarial trust boundaries; block on hardening gaps
+#   #   moderate: ordinary trust boundaries; internal run artifacts are not
+#   #             security boundaries; block on correctness and normal-use bugs
+#   #   lenient:  correctness and real, reachable bugs only
+#   review_level: moderate
+#
 #   # Optional local notification command. Leave commented to keep
 #   # notifications disabled.
 #   # notify_bin: /absolute/path/to/notify

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navels/neal",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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.22.0",
+  "packageManager": "pnpm@11.24.0",
   "homepage": "https://github.com/navels/neal#readme",
   "repository": {
     "type": "git",
@@ -40,8 +40,8 @@
     "examples"
   ],
   "engines": {
-    "node": ">=24.19.0",
-    "pnpm": ">=11.22.0"
+    "node": ">=24.20.0",
+    "pnpm": ">=11.24.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.34",
-    "@anthropic-ai/claude-agent-sdk": "0.3.240",
-    "@openai/codex-sdk": "0.149.0",
-    "ai": "7.0.74",
+    "@ai-sdk/openai-compatible": "3.0.39",
+    "@anthropic-ai/claude-agent-sdk": "0.3.251",
+    "@openai/codex-sdk": "0.151.0",
+    "ai": "7.0.83",
     "dotenv": "^17.4.2",
     "yaml": "^2.9.0",
     "zod": "4.4.3"
@@ -66,10 +66,10 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^24.13.3",
-    "eslint": "^10.9.0",
+    "eslint": "^10.9.1",
     "tsx": "^4.23.12",
     "typescript": "^6.0.3",
     "typescript-7": "npm:typescript@^7.0.2",
-    "typescript-eslint": "^8.67.0"
+    "typescript-eslint": "^8.68.0"
   }
 }