@navels/neal 0.1.0 → 0.2.0

package/dist/neal/orchestrator/transitions.js

@@ -2,6 +2,31 @@ 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: [],
+        reviewStuckArbiterCount: 0,
+        findings: [],
+        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 +82,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 +108,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 +121,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 +135,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 +154,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 +197,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 +213,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/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/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

@@ -54,6 +54,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.',
@@ -257,8 +258,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.',

package/dist/neal/prompts/specialized.js

@@ -1,3 +1,4 @@
+import { guardStructuredJsonOutputFormatLines } from '../agents/structured-json.js';
 import { assertNoReadPromptInstructionText, renderInlineReviewerContext, renderInlinedRangeDiffSection, } from '../context/inline-review-context.js';
 import { renderReviewerContextMarkdown } from '../context/reviewer-context.js';
 import { assertPromptBuilder } from './assert-builder.js';
@@ -5,6 +6,24 @@ import { getUserGuidanceLines } from './guidance.js';
 import { getUnattendedAutonomyLines } from './shared.js';
 import { getAdversarialReviewDoctrineLines, getCodeReviewFalsificationLines, getFindingQualityLines, getPreexistingFailureContractLines, getRegressionPreservationLines, getVerificationSkepticismLines, resolveReviewerPromptAccessMode, } 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
+// transport-deferring line (replacing the old fence-prohibition that
+// contradicted the neal-json transport), and routes the assembled lines through
+// guardStructuredJsonOutputFormatLines so a reintroduced conflicting phrasing
+// throws at render. Both completion builders emit their output-format
+// instructions exclusively through this helper. The transport-deferring line is
+// provider-neutral: the neal-json protocol block is appended below the base
+// prompt only on the wrapper path (anthropic-claude and the repair loop), while
+// other transports (e.g. generic-agentic) send the base prompt with no protocol
+// below it, so the line must not claim instructions appear "below".
+export function completionJsonOutputFormatLines(label) {
+    return guardStructuredJsonOutputFormatLines([
+        'Return only JSON that matches the required schema.',
+        'Return the final answer only as the required structured output object, not as prose or markdown.',
+        'Defer exact output framing to the active structured-output transport; do not add your own output-format constraints.',
+    ], label);
+}
 export function buildFinalCompletionSummaryPrompt(args) {
     const spec = assertPromptBuilder('completion_coder', 'buildFinalCompletionSummaryPrompt', PROMPT_MODULE_PATH);
     const finalCompletionVariant = spec.variants.find((variant) => variant.kind === 'final_completion');
@@ -18,12 +37,12 @@ export function buildFinalCompletionSummaryPrompt(args) {
         `Summarize whether the execute-mode plan at ${args.planDoc} is complete as a whole.`,
         '',
         'Before writing the summary, review the current repository state, the plan document, and the completion packet below.',
-        'Return only JSON that matches the required schema.',
-        'Return the final answer only as the required structured output object, not as prose or markdown.',
+        ...completionJsonOutputFormatLines('buildFinalCompletionSummaryPrompt'),
         'Keep the response compact and auditable rather than essay-style.',
         'Use `planGoalSatisfied` to state whether the plan goal is satisfied overall.',
         'Use `whatChangedOverall` to summarize the completed work across the whole plan, not just the last scope.',
         'Use `verificationSummary` to summarize the completion evidence that actually ran.',
+        'Before claiming a step is done or a verification passed, confirm the claim against an actual tool or command result from this session, and do not claim verification that did not actually run.',
         'Use `remainingKnownGaps` for any known missing work, regressions, quality concerns, testing gaps, risks, or omissions that would make the plan not fully complete.',
         'Do not contradict yourself:',
         '- if `planGoalSatisfied` is `true`, `remainingKnownGaps` must be empty',
@@ -49,7 +68,6 @@ export function buildFinalCompletionSummaryPrompt(args) {
         }, null, 2),
         '',
         'If the completion is verification-only, say so directly in `whatChangedOverall` or `remainingKnownGaps` instead of pretending there was a terminal implementation diff.',
-        'Do not include markdown fences or prose outside the JSON object.',
         ...getUserGuidanceLines('coder'),
         '',
         'Last non-empty implementation scope reference:',
@@ -141,8 +159,7 @@ export function buildFinalCompletionReviewerPrompt(args) {
         '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, noRead ? 'inline' : 'tool-access'),
         'Do not treat prior per-scope acceptance as sufficient evidence that the whole plan is complete or that the aggregate code quality is acceptable.',
-        'Return only JSON that matches the required schema.',
-        'Return the final answer only as the required structured output object, not as prose or markdown.',
+        ...completionJsonOutputFormatLines('buildFinalCompletionReviewerPrompt'),
         'Use `accept_complete` only when the full plan objectives are satisfied and the aggregate implementation is acceptable under ordinary code review standards.',
         'Use `continue_execution` only when the remaining work is concrete, bounded, and suitable for one explicit follow-on scope.',
         'Use `block_for_operator` when the remaining gap is ambiguous, externally constrained, or needs human direction.',
@@ -183,7 +200,6 @@ export function buildFinalCompletionReviewerPrompt(args) {
         }, null, 2),
         '',
         'If this was a verification-only terminal scope, judge the whole-plan result directly instead of pretending there was a final implementation diff.',
-        'Do not include markdown fences or prose outside the JSON object.',
         ...getUserGuidanceLines('reviewer'),
         '',
         'Last non-empty implementation scope reference:',

package/dist/neal/prompts/specs.js

@@ -82,6 +82,10 @@ const COMPLETION_REVIEWER_CONTEXT = context('CompletionReviewerPromptContext', [
     field('inlineContext', 'repository_state', false, "Neal-inlined aggregate diff (or evidence-gap statement) and plan-document sections for reviewers without repository read access; only valid with the 'no-read' access mode."),
     field('accessMode', 'orchestrator_state', false, "Three-way reviewer doctrine access mode derived from the reviewer provider's structured-advisor tool access: 'tool-access' (inspect and execute), 'read-only' (read tools only; no command execution, test runs, or scratch work), or 'no-read' (judge entirely from Neal-inlined context). When absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
 ]);
+const BLOCKED_ADJUDICATOR_CONTEXT = context('BlockedAdjudicatorPromptContext', [
+    field('blockedReason', 'prompt_argument', true, 'Blocked reason reported by the stalled coder or reviewer turn.'),
+    field('inlineContext', 'repository_state', true, 'Neal-inlined adjudication context (plan content, open blocking findings, reviewer-round snapshots, or coder blocker plus changed files) the adjudicator judges entirely from.'),
+]);
 export const PROMPT_SPECS = [
     {
         id: 'plan_author',
@@ -542,6 +546,60 @@ export const PROMPT_SPECS = [
             },
         ],
     },
+    {
+        id: 'blocked_adjudicator',
+        role: 'reviewer',
+        purpose: 'Triage a blocked Neal run entirely from Neal-inlined context and decide whether the block is an in-scope recoverable misunderstanding or a genuine wall that must escalate to a human.',
+        requiredContext: BLOCKED_ADJUDICATOR_CONTEXT,
+        schemaTarget: {
+            kind: 'structured_json',
+            schemaBuilder: 'buildBlockedAdjudicatorSchema',
+            parser: 'validateBlockedAdjudicatorVerdictPayload',
+            providerSurface: 'neal_json_block_protocol',
+        },
+        baseInstructions: {
+            kind: 'builder',
+            modulePath: 'src/neal/agents/prompts.ts',
+            exportName: 'buildBlockedAdjudicatorPrompt',
+            inputShape: context('BuildBlockedAdjudicatorPromptArgs', [
+                field('blockedReason', 'prompt_argument', true, 'Blocked reason string.'),
+                field('inlineContext', 'repository_state', true, 'Neal-inlined adjudication context.'),
+            ]),
+        },
+        providerVariants: SHARED_PROVIDER_VARIANTS,
+        evaluationNotes: [
+            'Render tests should assert the adjudicator judges entirely from inlined context and its static instructions carry no repository-access phrasing.',
+            'A golden render test pins the exact prompt bytes, including the ALL-CAPS emphasis lines.',
+        ],
+        firstMigrationPriority: 3,
+        currentHome: 'mixed',
+        ownershipNotes: [
+            'Prompt spec owns the adjudicator instructions and required context only; anti-thrash guarding, recovery routing, and verdict persistence stay in src/neal/adjudicator/ outside the prompt-spec library.',
+        ],
+        variants: [
+            {
+                kind: 'primary',
+                status: 'adjacent',
+                description: 'Read-only blocked-run adjudication round.',
+                currentRoundEntrypoints: ['runBlockedAdjudicatorRound'],
+                baseInstructions: {
+                    kind: 'builder',
+                    modulePath: 'src/neal/agents/prompts.ts',
+                    exportName: 'buildBlockedAdjudicatorPrompt',
+                    inputShape: context('BuildBlockedAdjudicatorPromptArgs', [
+                        field('blockedReason', 'prompt_argument', true, 'Blocked reason string.'),
+                        field('inlineContext', 'repository_state', true, 'Neal-inlined adjudication context.'),
+                    ]),
+                },
+                schemaTarget: {
+                    kind: 'structured_json',
+                    schemaBuilder: 'buildBlockedAdjudicatorSchema',
+                    parser: 'validateBlockedAdjudicatorVerdictPayload',
+                    providerSurface: 'neal_json_block_protocol',
+                },
+            },
+        ],
+    },
 ];
 function getContractFieldKeys(contract) {
     return new Set(contract.fields.map((field) => field.key));