@navels/neal 0.1.0 → 0.3.0

package/dist/neal/orchestrator/transitions.js

@@ -2,6 +2,37 @@ import { aggregateChangedFilesForAcceptedDerivedScopes, getAcceptedDerivedScopes
 import { toResidualReviewDebt } from '../review-debt.js';
 import { getDerivedPlanView, getFinalCompletionView } from '../state-views.js';
 const ALREADY_SATISFIED_ACCEPTANCE_RATIONALE_PREFIX = 'Accepted top-level already-satisfied scope';
+export function createScopeBoundaryReset() {
+    return {
+        currentScopeProgressJustification: null,
+        currentScopeMeaningfulProgressVerdict: null,
+        rounds: [],
+        recentBlocks: [],
+        consultantAttemptCount: 0,
+        findings: [],
+        // planReviewDebt is a projection of the current findings, so clearing
+        // findings must clear it too (toPlanReviewDebt([]) === []); otherwise a new
+        // derived-plan negotiation would carry stale current-negotiation debt. The
+        // durable inheritedPlanReviewDebt is intentionally NOT reset here — it is
+        // write-once and survives scope boundaries.
+        planReviewDebt: [],
+        createdCommits: [],
+    };
+}
+export function createNextScopeEntryReset(baseCommit) {
+    return {
+        ...createScopeBoundaryReset(),
+        baseCommit,
+        finalCommit: null,
+        archivedReviewPath: null,
+        coderSessionHandle: null,
+        coderSessionProtocol: null,
+        lastScopeMarker: null,
+        finalCompletionSummary: null,
+        phase: 'coder_scope',
+        status: 'running',
+    };
+}
 export function appendCompletedScope(state, result, details) {
     const scopeLabel = details.scopeLabel ?? getCurrentScopeLabel(state);
     const marker = details.marker ?? (state.lastScopeMarker ?? 'AUTONOMY_BLOCKED');
@@ -57,23 +88,17 @@ export function adoptAcceptedDerivedPlan(state) {
     }
     return {
         ...state,
+        ...createScopeBoundaryReset(),
         phase: 'coder_scope',
         status: 'running',
         derivedScopeIndex: derivedPlan.scopeIndex ?? 1,
         coderSessionHandle: null,
         coderSessionProtocol: null,
         coderRetryCount: 0,
-        currentScopeProgressJustification: null,
-        currentScopeMeaningfulProgressVerdict: null,
         finalCompletionSummary: null,
         finalCompletionReviewVerdict: null,
         finalCompletionResolvedAction: null,
         finalCompletionContinueExecutionCapReached: false,
-        rounds: [],
-        recentBlocks: [],
-        reviewStuckArbiterCount: 0,
-        findings: [],
-        createdCommits: [],
         blockedFromPhase: null,
     };
 }
@@ -89,15 +114,8 @@ export function computeNextScopeStateAfterExecuteFinalization({ state, finalComm
     if (derivedExecution && derivedPlanCompleted) {
         return {
             ...state,
-            baseCommit: finalCommit,
-            finalCommit: null,
-            coderSessionHandle: null,
-            coderSessionProtocol: null,
+            ...createNextScopeEntryReset(finalCommit),
             currentScopeNumber: nextTopLevelScopeNumber,
-            lastScopeMarker: null,
-            currentScopeProgressJustification: null,
-            currentScopeMeaningfulProgressVerdict: null,
-            finalCompletionSummary: null,
             finalCompletionReviewVerdict: null,
             finalCompletionResolvedAction: null,
             finalCompletionContinueExecutionCapReached: false,
@@ -109,28 +127,13 @@ export function computeNextScopeStateAfterExecuteFinalization({ state, finalComm
             derivedPlanAcceptedNotified: false,
             splitPlanBlockedNotified: false,
             splitPlanCountForCurrentScope: 0,
-            rounds: [],
-            recentBlocks: [],
-            reviewStuckArbiterCount: 0,
-            findings: [],
-            createdCommits: [],
             completedScopes,
-            archivedReviewPath: null,
-            phase: 'coder_scope',
-            status: 'running',
         };
     }
     if (derivedExecution) {
         return {
             ...state,
-            baseCommit: finalCommit,
-            finalCommit: null,
-            coderSessionHandle: null,
-            coderSessionProtocol: null,
-            lastScopeMarker: null,
-            currentScopeProgressJustification: null,
-            currentScopeMeaningfulProgressVerdict: null,
-            finalCompletionSummary: null,
+            ...createNextScopeEntryReset(finalCommit),
             finalCompletionReviewVerdict: null,
             finalCompletionResolvedAction: null,
             finalCompletionContinueExecutionCapReached: false,
@@ -138,29 +141,14 @@ export function computeNextScopeStateAfterExecuteFinalization({ state, finalComm
             splitPlanStartedNotified: false,
             derivedPlanAcceptedNotified: false,
             splitPlanBlockedNotified: false,
-            rounds: [],
-            recentBlocks: [],
-            reviewStuckArbiterCount: 0,
-            findings: [],
-            createdCommits: [],
             completedScopes,
-            archivedReviewPath: null,
-            phase: 'coder_scope',
-            status: 'running',
         };
     }
     if (continueScopes) {
         return {
             ...state,
-            baseCommit: finalCommit,
-            finalCommit: null,
-            coderSessionHandle: null,
-            coderSessionProtocol: null,
+            ...createNextScopeEntryReset(finalCommit),
             currentScopeNumber: nextTopLevelScopeNumber,
-            lastScopeMarker: null,
-            currentScopeProgressJustification: null,
-            currentScopeMeaningfulProgressVerdict: null,
-            finalCompletionSummary: null,
             finalCompletionReviewVerdict: null,
             finalCompletionResolvedAction: null,
             finalCompletionContinueExecutionCapReached: false,
@@ -172,15 +160,7 @@ export function computeNextScopeStateAfterExecuteFinalization({ state, finalComm
             derivedPlanAcceptedNotified: false,
             splitPlanBlockedNotified: false,
             splitPlanCountForCurrentScope: 0,
-            rounds: [],
-            recentBlocks: [],
-            reviewStuckArbiterCount: 0,
-            findings: [],
-            createdCommits: [],
             completedScopes,
-            archivedReviewPath: null,
-            phase: 'coder_scope',
-            status: 'running',
         };
     }
     return {
@@ -223,19 +203,11 @@ export function computeNextScopeStateAfterParentAdvance(args) {
         : args.state.currentScopeNumber;
     return {
         ...args.state,
-        baseCommit: args.finalCommit,
-        finalCommit: null,
-        archivedReviewPath: null,
-        coderSessionHandle: null,
-        coderSessionProtocol: null,
+        ...createNextScopeEntryReset(args.finalCommit),
         reviewerSessionHandle: null,
         coderRetryCount: 0,
         currentScopeNumber: nextTopLevelScopeNumber,
-        lastScopeMarker: null,
-        currentScopeProgressJustification: null,
-        currentScopeMeaningfulProgressVerdict: null,
         manualGate: null,
-        finalCompletionSummary: null,
         finalCompletionReviewVerdict: null,
         finalCompletionResolvedAction: null,
         finalCompletionContinueExecutionCapReached: false,
@@ -247,16 +219,9 @@ export function computeNextScopeStateAfterParentAdvance(args) {
         derivedPlanAcceptedNotified: false,
         splitPlanBlockedNotified: false,
         splitPlanCountForCurrentScope: 0,
-        rounds: [],
-        recentBlocks: [],
-        reviewStuckArbiterCount: 0,
-        findings: [],
-        createdCommits: [],
         completedScopes: args.completedScopes,
         blockedFromPhase: null,
         interactiveBlockedRecovery: null,
-        phase: 'coder_scope',
-        status: 'running',
     };
 }
 function getAcceptedScopeSummary(state) {

package/dist/neal/orchestrator.js

@@ -81,6 +81,9 @@ export async function initializeOrchestration(planDoc, cwd, agentConfig, topLeve
         reviewMarkdownPath: join(logger.runDir, 'REVIEW.md'),
         recoveryMarkdownPath: join(logger.runDir, 'RECOVERY.md'),
         maxRounds: getMaxReviewRounds(cwd),
+        // Only the `neal run` queue's execution stage supplies this; every other
+        // caller omits it and the durable inherited debt seeds to an empty array.
+        inheritedPlanReviewDebt: options?.inheritedPlanReviewDebt,
     };
     await mkdir(stateDir, { recursive: true });
     const baseCommit = await getHeadCommit(cwd);

package/dist/neal/plan-doc.js

@@ -1,6 +1,29 @@
-import { realpath, stat } from 'node:fs/promises';
+import { readFile, realpath, stat, writeFile } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
 import { getIgnoredPaths, getRepositoryRoot } from './git.js';
+/**
+ * Run a destructive worktree action (reset --hard / clean) while preserving
+ * the plan document's byte content across it. The plan doc is a wrapper-owned
+ * overlay by contract: it may be an uncommitted modification of a TRACKED file
+ * (reset --hard would silently restore the committed content — a different
+ * plan — mid-run) or an untracked file (clean would delete it). Either way the
+ * run's plan must survive worktree hygiene. Restores nothing if the plan doc
+ * did not exist before the action.
+ */
+export async function withPlanDocPreserved(planDoc, action) {
+    let content = null;
+    try {
+        content = await readFile(planDoc);
+    }
+    catch {
+        content = null;
+    }
+    const result = await action();
+    if (content !== null) {
+        await writeFile(planDoc, content);
+    }
+    return result;
+}
 export async function inspectPlanDocDisposition(cwd, planDoc, options = {}) {
     const repositoryRoot = await realpath(await getRepositoryRoot(cwd));
     const absolutePlanDoc = resolve(cwd, planDoc);

package/dist/neal/plan-queue.js

@@ -9,7 +9,7 @@ import { writeExecutionArtifacts } from './orchestrator/artifacts.js';
 import { assertAgentConfigSupportsResume, assertAgentConfigSupportsWriterRun } from './providers/registry.js';
 import { writeCurrentRunPointer } from './run-registry.js';
 import { formatPublicRunStatus, getRunDisplayStatus } from './run-status.js';
-import { getRunStatePath, loadState, saveState } from './state.js';
+import { getRunStatePath, hydrateResidualReviewDebtItem, loadState, saveState } from './state.js';
 import { QUEUE_LINK_FILE, QUEUE_STATE_FILE, QUEUE_SUMMARY_FILE, getCurrentPlanAndExecuteQueuePointerPath as getStorageCurrentPlanAndExecuteQueuePointerPath, getQueuesDir, } from './storage-paths.js';
 import { executeRun, withPreparedWriterRun, } from './commands/runtime.js';
 import { filterAllowedDirtyPathStatus, filterWrapperOwnedWorktreeStatus, parseWorktreeStatusLine, } from './worktree-status.js';
@@ -114,6 +114,7 @@ export async function createPlanAndExecuteQueue(args) {
             planningRunId: null,
             planningStatePath: null,
             acceptedPlanPath: null,
+            planReviewDebt: [],
             executionRunId: null,
             executionStatePath: null,
             activeStage: null,
@@ -496,6 +497,10 @@ async function runFreshPlanAndExecuteChild(args, onInitialized) {
             // initialized, the run state is the single source of truth for
             // this run — `neal resume` reads it back from there.
             autoSquashOnCompletion: args.squashOnCompletion,
+            // Only the execution child inherits the accepted plan's plan-review
+            // debt (into the durable inheritedPlanReviewDebt state field). The
+            // planning child recomputes its own planReviewDebt from scratch.
+            inheritedPlanReviewDebt: args.stage === 'execution' ? args.item.planReviewDebt : undefined,
         });
         markInitialized();
         assertAgentConfigSupportsWriterRun(loaded.state.agentConfig, { context: `${args.stage} queue child` });
@@ -581,6 +586,11 @@ async function completePlanningStage(state, itemIndex, finalState, deps) {
             ...item,
             status: 'planned',
             acceptedPlanPath,
+            // Carry the accepted plan's current-negotiation debt onto the queue item
+            // so the fresh execution child inherits it (both the in-process completion
+            // and the cross-process continuePlanAndExecuteQueueFromChildRun resume
+            // route through here).
+            planReviewDebt: finalState.planReviewDebt,
             activeStage: null,
             stopReason: null,
         }),
@@ -916,6 +926,10 @@ function parsePlanAndExecuteQueueItem(value, expectedIndex, cwd) {
         planningRunId: requireNullableString(item.planningRunId, 'Invalid queue state: malformed planningRunId'),
         planningStatePath,
         acceptedPlanPath,
+        // Legacy-tolerant: queue items persisted before this field existed default
+        // to an empty debt array. Present arrays are hydrated with the shared
+        // residual-debt validator so an older/newer field shape is caught.
+        planReviewDebt: parseQueueItemPlanReviewDebt(item.planReviewDebt),
         executionRunId: requireNullableString(item.executionRunId, 'Invalid queue state: malformed executionRunId'),
         executionStatePath,
         activeStage: requireNullableQueueChildStage(item.activeStage, 'Invalid queue state: malformed activeStage'),
@@ -924,6 +938,20 @@ function parsePlanAndExecuteQueueItem(value, expectedIndex, cwd) {
         stopReason: requireNullableString(item.stopReason, 'Invalid queue state: malformed item stopReason'),
     };
 }
+function parseQueueItemPlanReviewDebt(value) {
+    // Legacy-tolerant ONLY for a genuinely absent field: queue items persisted
+    // before this field existed omit it entirely (undefined), and those default to
+    // an empty debt array. A PRESENT null (or any other non-array) is corrupted
+    // state that would silently erase accepted plan-review debt, so it is rejected
+    // as malformed rather than defaulted away.
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error('Invalid queue state: malformed planReviewDebt');
+    }
+    return value.map((item, index) => hydrateResidualReviewDebtItem(item, `queue item planReviewDebt[${index}]`));
+}
 function parseCurrentPlanAndExecuteQueuePointer(value, cwd) {
     if (!value || typeof value !== 'object') {
         throw new Error('Invalid .neal/current-queue.json: expected object');

package/dist/neal/prompts/assert-builder.js

@@ -1,4 +1,4 @@
-import { getPromptSpec } from './specs.js';
+import { getPromptSpec, } from './specs.js';
 export function assertPromptBuilder(id, exportName, modulePath) {
     const spec = getPromptSpec(id);
     const allowedBuilders = [spec.baseInstructions, ...spec.variants.map((variant) => variant.baseInstructions)];
@@ -11,3 +11,10 @@ export function assertPromptBuilder(id, exportName, modulePath) {
     }
     return spec;
 }
+export function resolvePrimaryVariant(spec, specLabel) {
+    const primary = spec.variants.find((variant) => variant.kind === 'primary');
+    if (!primary) {
+        throw new Error(`Prompt spec ${specLabel} is missing a primary variant`);
+    }
+    return primary;
+}

package/dist/neal/prompts/execute.js

@@ -1,9 +1,8 @@
-import { assertNoReadPromptInstructionText, renderInlineReviewerContext, renderInlinedRangeDiffSection, } from '../context/inline-review-context.js';
-import { renderReviewerContextMarkdown } from '../context/reviewer-context.js';
+import { renderInlinedRangeDiffSection } from '../context/inline-review-context.js';
 import { AUTONOMY_BLOCKED, AUTONOMY_DONE, AUTONOMY_SCOPE_DONE, AUTONOMY_SPLIT_PLAN, buildProgressSection, getCanonicalPlanContractLines, getDerivedPlanSectionContractLines, getExecuteScopeProgressPayloadContractLines, getProtocolMarkerArtifactProhibitionLines, getStandalonePlanPayloadSourceOfTruthLines, getTerminalMarkerArtifactBoundaryLines, getUnattendedAutonomyLines, } from './shared.js';
 import { assertPromptBuilder } from './assert-builder.js';
 import { getUserGuidanceLines } from './guidance.js';
-import { getAdversarialReviewDoctrineLines, getCodeReviewFalsificationLines, getFindingQualityLines, getPreexistingFailureContractLines, getRegressionPreservationLines, getVerificationSkepticismLines, resolveReviewerPromptAccessMode, } from './review-doctrine.js';
+import { getAdversarialReviewDoctrineLines, getCodeReviewFalsificationLines, getFindingQualityLines, getPreexistingFailureContractLines, getRegressionPreservationLines, 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 = [
@@ -54,6 +53,7 @@ export function buildScopePrompt(planDoc, progressText, options) {
         CODER_REGRESSION_PRESERVATION_LINE,
         ...CODER_PREEXISTING_FAILURE_LINES,
         'Verify the relevant work before you finish.',
+        'Before claiming a step is done or a verification passed, confirm the claim against an actual tool or command result from this session, and state plainly when a step is not yet verified.',
         'Create real git commit(s) for completed work.',
         'Do not edit or stage wrapper-owned artifacts such as review files under .neal/runs/, PLAN_PROGRESS.md, plan-progress.json, or .neal/*.',
         'Treat action=`blocked` as a last resort, not an early exit.',
@@ -114,12 +114,7 @@ export function buildReviewerPrompt(args) {
     if (!primaryVariant || !meaningfulProgressVariant) {
         throw new Error('Prompt spec scope_reviewer is missing primary or meaningful-progress coverage');
     }
-    const accessMode = resolveReviewerPromptAccessMode({
-        builder: 'buildReviewerPrompt',
-        accessMode: args.accessMode,
-        inlineContextSupplied: Boolean(args.inlineContext),
-    });
-    const noRead = accessMode === 'no-read';
+    const accessMode = args.accessMode ?? 'tool-access';
     // 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
@@ -157,12 +152,7 @@ export function buildReviewerPrompt(args) {
         reviewTarget: 'scope diff',
         mode: accessMode,
     });
-    const reviewHistoryLine = noRead
-        ? 'Prior review history is inlined below if you need earlier reviewer findings or coder responses, but review the inlined diff for the current commit range directly.'
-        : `Prior review history is available at ${args.reviewMarkdownPath} if you need earlier reviewer findings or coder responses, but review the current commit range directly.`;
-    if (noRead) {
-        assertNoReadPromptInstructionText([...falsificationLines, ...skepticismLines, ...regressionLines, ...preexistingLines, reviewHistoryLine].join('\n'), 'buildReviewerPrompt');
-    }
+    const reviewHistoryLine = `Prior review history is available at ${args.reviewMarkdownPath} if you need earlier reviewer findings or coder responses, but review the current commit range directly.`;
     return [
         `Review the current scope for plan ${args.planDoc}.`,
         `Review round: ${args.round}.`,
@@ -191,7 +181,7 @@ export function buildReviewerPrompt(args) {
         'Changed files:',
         changedFilesText,
         '',
-        ...getReviewerContextLines(args.reviewerContext, noRead ? 'inline' : 'tool-access'),
+        ...getReviewerContextLines(args.reviewerContext),
         `The active parent objective for meaningful-progress evaluation is scope ${args.parentScopeLabel}.`,
         'You are the authority for meaningful-progress gating during this execute review pass, but perform that judgment after the adversarial correctness review above.',
         'Set `meaningfulProgressAction` to `accept` only when either this scope materially advances the active parent objective, or a top-level scope has no required new diff because prior accepted work already satisfies it and you find no issues with sufficient verification evidence.',
@@ -215,7 +205,6 @@ export function buildReviewerPrompt(args) {
         '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.',
         'Before emitting a finding that resembles a prior fixed/rejected/deferred finding, inspect the current code or current diff and cite fresh current evidence showing the defect still exists.',
         'If current evidence is ambiguous for an already-addressed claim, do not use a blocking finding to force another coder loop; use meaningfulProgressAction=`block_for_operator` only when operator judgment is genuinely required.',
-        ...(args.inlineContext ? ['', renderInlineReviewerContext(args.inlineContext)] : []),
         ...(rangeDiffInlined
             ? [
                 '',
@@ -227,13 +216,13 @@ export function buildReviewerPrompt(args) {
             : []),
     ].join('\n');
 }
-function getReviewerContextLines(reviewerContext, mode = 'tool-access') {
+function getReviewerContextLines(reviewerContext) {
     if (!reviewerContext) {
         return [];
     }
     return [
         'Bounded current-run continuity context:',
-        mode === 'inline' ? renderReviewerContextMarkdown(reviewerContext, { mode: 'inline' }) : reviewerContext.promptMarkdown,
+        reviewerContext.promptMarkdown,
         '',
     ];
 }
@@ -257,8 +246,11 @@ export function buildCoderResponsePrompt(args) {
         mode === 'blocking'
             ? 'Make code changes if needed, run the most relevant verification for the fixes you make, and create a real git commit if you changed code.'
             : 'Fix local, concrete, low-expansion non-blocking findings by default. Make the smallest justified code changes, run the most relevant verification for those changes, and create a real git commit if you changed code.',
+        // model-calibrated: caps post-commit tool use once the fix is committed and verified; tuned for a model that otherwise keeps issuing redundant shell commands after it already has enough evidence.
         'After you have made the necessary commit and run the relevant verification, stop using tools. Your next response must return the structured outcome with no additional shell commands such as git show, git status, or extra exploratory tests.',
+        // model-calibrated: stops repeated re-verification of an already-evidenced fix; tuned for a model that over-proves rather than summarizing the evidence it already gathered.
         'Do not keep proving the same fix after you have enough evidence to answer each finding. Summarize the evidence in the structured response instead.',
+        'Before claiming a step is done or a verification passed, confirm the claim against an actual tool or command result from this session, and state plainly when a finding is not yet verified.',
         CODER_REGRESSION_PRESERVATION_LINE,
         ...CODER_PREEXISTING_FAILURE_LINES,
         'Use `fixed` only when you actually changed the code or verification in a way that resolves the finding.',