@navels/neal 0.1.0

package/dist/neal/adjudicator/specs.js

@@ -0,0 +1,453 @@
+import { getPromptSpec } from '../prompts/specs.js';
+import { validateAdjudicatedLoopContract } from './contracts.js';
+const FAMILY_RUNTIME_TRANSITION_SIGNALS = {
+    plan_review: ['accept_plan', 'accept_derived_plan', 'request_revision', 'optional_revision', 'block_for_operator'],
+    execute_review: ['accept_scope', 'request_revision', 'optional_revision', 'block_for_operator', 'replace_plan', 'advance_parent'],
+    final_completion: ['accept_complete', 'continue_execution', 'block_for_operator'],
+};
+const SPEC_RUNTIME_TRANSITION_SIGNALS = {
+    plan_review: ['accept_plan', 'request_revision', 'optional_revision', 'block_for_operator'],
+    derived_plan_review: ['accept_derived_plan', 'request_revision', 'optional_revision', 'block_for_operator'],
+    execute_review: ['accept_scope', 'request_revision', 'optional_revision', 'block_for_operator', 'replace_plan', 'advance_parent'],
+    final_completion_review: ['accept_complete', 'continue_execution', 'block_for_operator'],
+};
+export const ADJUDICATION_SPECS = [
+    {
+        id: 'plan_review',
+        family: 'plan_review',
+        status: 'in_scope_v1',
+        roundLabel: 'plan-review',
+        currentEntrypoints: ['runCoderPlanRound', 'runPlanReviewerRound', 'runCoderPlanResponseRound(reviewMode=plan)'],
+        artifactUnderReview: 'Top-level Neal-executable plan markdown.',
+        contextAssembly: {
+            owner: 'orchestrator',
+            inputs: ['planDoc', 'reviewMarkdownPath', 'openFindings', 'repositoryState'],
+            notes: 'Ordinary plan review keeps execution-shape validation and review history in the existing plan-review artifacts.',
+        },
+        coder: {
+            primary: {
+                prompt: {
+                    role: 'coder',
+                    promptSpecId: 'plan_author',
+                    variantKind: 'primary',
+                    exportName: 'buildPlanningPrompt',
+                },
+                output: {
+                    protocol: 'structured_json',
+                    schemaBuilder: 'buildCoderPlanSchema',
+                    parser: 'validateCoderPlanPayload',
+                    providerSurface: 'coder_structured_schema',
+                },
+            },
+            response: {
+                prompt: {
+                    role: 'coder',
+                    promptSpecId: 'plan_author',
+                    variantKind: 'response',
+                    exportName: 'buildCoderPlanResponsePrompt',
+                },
+                output: {
+                    protocol: 'structured_json',
+                    schemaBuilder: 'buildCoderPlanResponseSchema',
+                    parser: 'validateCoderPlanResponsePayload',
+                    providerSurface: 'coder_structured_schema',
+                },
+            },
+        },
+        reviewer: {
+            prompt: {
+                role: 'reviewer',
+                promptSpecId: 'plan_reviewer',
+                variantKind: 'primary',
+                exportName: 'buildPlanReviewerPrompt',
+            },
+            output: {
+                protocol: 'structured_json',
+                schemaBuilder: 'buildPlanReviewerSchema',
+                parser: 'PlanReviewerPayload',
+                providerSurface: 'structured_advisor_schema',
+            },
+        },
+        convergence: {
+            settledWhen: 'Reviewer returns no open findings and the plan remains structurally valid.',
+            reviseWhen: 'Open findings route back to a required or optional coder plan-response round.',
+            blockedWhen: 'Coder returns structured action=blocked instead of a revised plan; round code still renders compatibility markers for downstream state.',
+        },
+        transitionSignals: ['accept_plan', 'request_revision', 'optional_revision', 'block_for_operator'],
+        loopContract: {
+            loopKind: 'plan',
+            sideEffectPolicy: 'plan_doc_only',
+            allowedOutcomes: ['accepted', 'revise', 'blocked', 'failed', 'cap_reached'],
+            terminalOutcomes: ['accepted', 'blocked', 'failed', 'cap_reached'],
+            roundCap: {
+                source: 'state.maxRounds',
+                appliesTo: 'review_iterations',
+                outcomeWhenReached: 'cap_reached',
+                notes: 'Plan refinement stops at the configured review-round cap and routes to operator blocking instead of accepting an unreviewed plan.',
+            },
+            terminalArtifact: {
+                kind: 'plan_document',
+                storage: 'state.planDoc',
+                description: 'Accepted top-level Neal-executable plan markdown revised in place.',
+            },
+        },
+        successCondition: 'Ordinary plan-mode review can settle without bespoke loop wiring outside the adjudicator family.',
+    },
+    {
+        id: 'derived_plan_review',
+        family: 'plan_review',
+        status: 'in_scope_v1',
+        roundLabel: 'plan-review',
+        currentEntrypoints: ['runPlanReviewerRound(mode=derived-plan)', 'runCoderPlanResponseRound(reviewMode=derived-plan)'],
+        artifactUnderReview: 'Derived replacement plan that targets one stale execute scope.',
+        contextAssembly: {
+            owner: 'orchestrator',
+            inputs: ['derivedPlanPath', 'parentPlanDoc', 'derivedFromScopeNumber', 'reviewMarkdownPath'],
+            notes: 'The loop mechanics match ordinary plan review while adoption semantics remain in the transition layer.',
+        },
+        coder: {
+            primary: {
+                prompt: {
+                    role: 'coder',
+                    promptSpecId: 'plan_author',
+                    variantKind: 'response',
+                    exportName: 'buildCoderPlanResponsePrompt',
+                },
+                output: {
+                    protocol: 'structured_json',
+                    schemaBuilder: 'buildCoderPlanResponseSchema',
+                    parser: 'validateCoderPlanResponsePayload',
+                    providerSurface: 'coder_structured_schema',
+                },
+            },
+            response: null,
+        },
+        reviewer: {
+            prompt: {
+                role: 'reviewer',
+                promptSpecId: 'plan_reviewer',
+                variantKind: 'derived_plan',
+                exportName: 'buildPlanReviewerPrompt',
+            },
+            output: {
+                protocol: 'structured_json',
+                schemaBuilder: 'buildPlanReviewerSchema',
+                parser: 'PlanReviewerPayload',
+                providerSurface: 'structured_advisor_schema',
+            },
+        },
+        convergence: {
+            settledWhen: 'Reviewer returns no open findings and the derived plan is safe to adopt.',
+            reviseWhen: 'Derived-plan findings loop through the same plan-response path as ordinary plan review.',
+            blockedWhen: 'Coder blocks or the derived plan remains structurally invalid.',
+        },
+        transitionSignals: ['accept_derived_plan', 'request_revision', 'optional_revision', 'block_for_operator'],
+        loopContract: {
+            loopKind: 'plan',
+            sideEffectPolicy: 'plan_doc_only',
+            allowedOutcomes: ['accepted', 'revise', 'blocked', 'failed', 'cap_reached'],
+            terminalOutcomes: ['accepted', 'blocked', 'failed', 'cap_reached'],
+            roundCap: {
+                source: 'derivedPlan.counters.maxDerivedPlanReviewRounds',
+                appliesTo: 'review_iterations',
+                outcomeWhenReached: 'cap_reached',
+                notes: 'Derived-plan review uses the derived-plan review cap and blocks rather than adopting an unresolved replacement plan.',
+            },
+            terminalArtifact: {
+                kind: 'derived_plan_document',
+                storage: 'state.derivedPlanPath',
+                description: 'Accepted derived replacement plan for one stale execute scope.',
+            },
+        },
+        successCondition: 'Derived-plan review shares planning-side adjudication mechanics while keeping replacement/adoption explicit.',
+    },
+    {
+        id: 'execute_review',
+        family: 'execute_review',
+        status: 'in_scope_v1',
+        roundLabel: 'review',
+        currentEntrypoints: ['runCoderScopeRound', 'runReviewerRound', 'runCoderResponseRound'],
+        artifactUnderReview: 'Execute-mode scope diff plus persisted meaningful-progress history for the active parent objective.',
+        contextAssembly: {
+            owner: 'review_artifact',
+            inputs: ['planDoc', 'baseCommit', 'headCommit', 'changedFiles', 'reviewMarkdownPath', 'currentScopeProgressJustification', 'recentHistorySummary'],
+            notes: 'Execute review is the only in-scope adjudication spec with meaningful-progress capability layered onto the reviewer prompt surface.',
+        },
+        coder: {
+            primary: {
+                prompt: {
+                    role: 'coder',
+                    promptSpecId: 'scope_coder',
+                    variantKind: 'primary',
+                    exportName: 'buildScopePrompt',
+                },
+                output: {
+                    protocol: 'structured_json',
+                    schemaBuilder: 'buildCoderScopeSchema',
+                    parser: 'validateCoderScopePayload',
+                    providerSurface: 'coder_structured_schema',
+                },
+            },
+            response: {
+                prompt: {
+                    role: 'coder',
+                    promptSpecId: 'scope_coder',
+                    variantKind: 'response',
+                    exportName: 'buildCoderResponsePrompt',
+                },
+                output: {
+                    protocol: 'structured_json',
+                    schemaBuilder: 'buildCoderResponseSchema',
+                    parser: 'validateCoderResponsePayload',
+                    providerSurface: 'coder_structured_schema',
+                },
+            },
+        },
+        reviewer: {
+            prompt: {
+                role: 'reviewer',
+                promptSpecId: 'scope_reviewer',
+                variantKind: 'primary',
+                exportName: 'buildReviewerPrompt',
+            },
+            output: {
+                protocol: 'structured_json',
+                schemaBuilder: 'buildReviewerSchema',
+                parser: 'ReviewerPayload',
+                providerSurface: 'structured_advisor_schema',
+            },
+            capabilities: [
+                {
+                    role: 'reviewer',
+                    promptSpecId: 'scope_reviewer',
+                    variantKind: 'meaningful_progress',
+                    exportName: 'buildReviewerPrompt',
+                },
+            ],
+        },
+        convergence: {
+            settledWhen: 'Reviewer returns no blocking findings and meaningfulProgressAction === accept, including top-level scopes already satisfied by prior accepted work; advance_parent is a distinct empty-derived-scope parent-advancement signal.',
+            reviseWhen: 'Findings reopen coder_response or coder_optional_response without changing execute-scope transition semantics.',
+            blockedWhen: 'Reviewer returns block_for_operator, replace_plan, or an unsafe advance_parent, or coder returns structured action=blocked/split_plan; round code still renders compatibility markers for downstream state.',
+        },
+        transitionSignals: ['accept_scope', 'request_revision', 'optional_revision', 'block_for_operator', 'replace_plan', 'advance_parent'],
+        loopContract: {
+            loopKind: 'execute',
+            sideEffectPolicy: 'code_changes',
+            allowedOutcomes: ['accepted', 'revise', 'blocked', 'failed', 'cap_reached'],
+            terminalOutcomes: ['accepted', 'blocked', 'failed', 'cap_reached'],
+            roundCap: {
+                source: 'state.maxRounds',
+                appliesTo: 'review_iterations',
+                outcomeWhenReached: 'cap_reached',
+                notes: 'Execute review stops at the configured review-round cap when blocking findings remain and records a blocked writer run.',
+            },
+            terminalArtifact: {
+                kind: 'implementation_scope',
+                storage: 'state.createdCommits plus state.reviewMarkdownPath',
+                description: 'Accepted implementation scope commits and the corresponding scope-review artifact.',
+            },
+        },
+        successCondition: 'Ordinary execute review and meaningful-progress gating share one adjudication spec family rather than branching by phase.',
+    },
+    {
+        id: 'final_completion_review',
+        family: 'final_completion',
+        status: 'in_scope_v1',
+        roundLabel: 'final-completion',
+        currentEntrypoints: ['runCoderFinalCompletionSummaryRound', 'runReviewerFinalCompletionRound'],
+        artifactUnderReview: 'Whole-plan completion packet assembled after the terminal execute scope settles.',
+        contextAssembly: {
+            owner: 'final_completion_packet',
+            inputs: ['planDoc', 'FinalCompletionPacket', 'FinalCompletionSummary'],
+            notes: 'Final completion review is plan-review-adjacent, but its accept/continue/block transitions stay outside the adjudicator.',
+        },
+        coder: {
+            primary: {
+                prompt: {
+                    role: 'coder',
+                    promptSpecId: 'completion_coder',
+                    variantKind: 'final_completion',
+                    exportName: 'buildFinalCompletionSummaryPrompt',
+                },
+                output: {
+                    protocol: 'structured_json',
+                    schemaBuilder: 'buildFinalCompletionSummarySchema',
+                    parser: 'parseFinalCompletionSummaryPayload',
+                    providerSurface: 'structured_advisor_schema',
+                },
+            },
+            response: null,
+        },
+        reviewer: {
+            prompt: {
+                role: 'reviewer',
+                promptSpecId: 'completion_reviewer',
+                variantKind: 'final_completion',
+                exportName: 'buildFinalCompletionReviewerPrompt',
+            },
+            output: {
+                protocol: 'structured_json',
+                schemaBuilder: 'buildFinalCompletionReviewerSchema',
+                parser: 'parseFinalCompletionReviewerPayload',
+                providerSurface: 'structured_advisor_schema',
+            },
+        },
+        convergence: {
+            settledWhen: 'Reviewer returns accept_complete, continue_execution, or block_for_operator for the whole plan.',
+            reviseWhen: 'No coder-response loop exists in v1; continue_execution returns control to execute-mode transitions instead.',
+            blockedWhen: 'Transition-layer continue_execution cap or explicit block_for_operator escalates to operator guidance.',
+        },
+        transitionSignals: ['accept_complete', 'continue_execution', 'block_for_operator'],
+        loopContract: {
+            loopKind: 'final_completion',
+            sideEffectPolicy: 'code_changes',
+            allowedOutcomes: ['accepted', 'revise', 'blocked', 'failed', 'cap_reached'],
+            terminalOutcomes: ['accepted', 'blocked', 'failed', 'cap_reached'],
+            roundCap: {
+                source: 'state.finalCompletionContinueExecutionMax',
+                appliesTo: 'continued_execution',
+                outcomeWhenReached: 'cap_reached',
+                notes: 'Final completion can reopen execution only up to its continue-execution cap before routing to operator blocking.',
+            },
+            terminalArtifact: {
+                kind: 'final_completion_review',
+                storage: 'FINAL_COMPLETION_REVIEW.md and state.finalCompletionReviewVerdict',
+                description: 'Whole-plan final-completion review artifact and resolved reviewer verdict.',
+            },
+        },
+        successCondition: 'Whole-plan completion review uses the shared adjudication model without hiding execute-mode completion semantics.',
+    },
+];
+export const ADJUDICATION_ADJACENT_FLOWS = [
+    {
+        id: 'interactive_blocked_recovery',
+        status: 'adjacent_v1',
+        currentEntrypoints: ['runInteractiveBlockedRecoveryPhase'],
+        reason: 'Interactive blocked recovery mixes operator input, coder dispositions, and transition routing rather than a pure coder/reviewer adjudication loop.',
+        futureRelationship: 'Keep adjacent until Neal decides to formalize operator-in-the-loop adjudication as its own family.',
+    },
+];
+const STRUCTURED_SCHEMA_BUILDERS = new Set([
+    'buildReviewerSchema',
+    'buildPlanReviewerSchema',
+    'buildCoderPlanSchema',
+    'buildCoderScopeSchema',
+    'buildCoderResponseSchema',
+    'buildCoderPlanResponseSchema',
+    'buildFinalCompletionSummarySchema',
+    'buildFinalCompletionReviewerSchema',
+]);
+const PARSER_SURFACES = new Set([
+    'validateCoderPlanPayload',
+    'validateCoderPlanResponsePayload',
+    'validateCoderScopePayload',
+    'validateCoderResponsePayload',
+    'PlanReviewerPayload',
+    'ReviewerPayload',
+    'parseFinalCompletionSummaryPayload',
+    'parseFinalCompletionReviewerPayload',
+]);
+const PROVIDER_SURFACES = new Set(['coder_structured_schema', 'structured_advisor_schema']);
+function validatePromptSurfaceReference(specId, label, reference) {
+    const promptSpec = getPromptSpec(reference.promptSpecId);
+    if (promptSpec.role !== reference.role) {
+        throw new Error(`Adjudication spec ${specId} ${label} role mismatch: expected ${reference.role}, prompt spec ${reference.promptSpecId} is ${promptSpec.role}.`);
+    }
+    const variant = promptSpec.variants.find((candidate) => candidate.kind === reference.variantKind && candidate.baseInstructions.exportName === reference.exportName);
+    if (!variant) {
+        throw new Error(`Adjudication spec ${specId} ${label} references missing prompt surface ${reference.promptSpecId}.${reference.variantKind}/${reference.exportName}.`);
+    }
+}
+function validateOutputSurface(specId, label, surface) {
+    const protocol = surface.protocol;
+    if (protocol !== 'structured_json') {
+        throw new Error(`Adjudication spec ${specId} ${label} references unsupported output protocol ${String(protocol)}.`);
+    }
+    if (!STRUCTURED_SCHEMA_BUILDERS.has(surface.schemaBuilder)) {
+        throw new Error(`Adjudication spec ${specId} ${label} references unknown schema builder ${surface.schemaBuilder}.`);
+    }
+    if (!PARSER_SURFACES.has(surface.parser)) {
+        throw new Error(`Adjudication spec ${specId} ${label} references unknown parser ${surface.parser}.`);
+    }
+    if (!PROVIDER_SURFACES.has(surface.providerSurface)) {
+        throw new Error(`Adjudication spec ${specId} ${label} references unknown provider surface ${surface.providerSurface}.`);
+    }
+}
+function validateTransitionSignals(spec) {
+    const familySignals = new Set(FAMILY_RUNTIME_TRANSITION_SIGNALS[spec.family]);
+    const specSignals = new Set(spec.transitionSignals);
+    const requiredSignals = SPEC_RUNTIME_TRANSITION_SIGNALS[spec.id];
+    if (specSignals.size !== spec.transitionSignals.length) {
+        throw new Error(`Adjudication spec ${spec.id} family ${spec.family} declares duplicate transition signals.`);
+    }
+    for (const signal of spec.transitionSignals) {
+        if (!familySignals.has(signal)) {
+            throw new Error(`Adjudication spec ${spec.id} family ${spec.family} declares impossible transition signal ${signal}.`);
+        }
+    }
+    for (const signal of requiredSignals) {
+        if (!specSignals.has(signal)) {
+            throw new Error(`Adjudication spec ${spec.id} family ${spec.family} is missing runtime transition signal ${signal}.`);
+        }
+    }
+}
+function validateFamilyRuntimeCoverage(specs) {
+    const signalsByFamily = new Map();
+    for (const spec of specs) {
+        const signals = signalsByFamily.get(spec.family) ?? new Set();
+        for (const signal of SPEC_RUNTIME_TRANSITION_SIGNALS[spec.id]) {
+            signals.add(signal);
+        }
+        signalsByFamily.set(spec.family, signals);
+    }
+    for (const [family, allowedSignals] of Object.entries(FAMILY_RUNTIME_TRANSITION_SIGNALS)) {
+        const coveredSignals = signalsByFamily.get(family) ?? new Set();
+        for (const signal of allowedSignals) {
+            if (!coveredSignals.has(signal)) {
+                throw new Error(`Adjudication family ${family} is missing runtime transition coverage for signal ${signal}.`);
+            }
+        }
+    }
+}
+export function validateAdjudicationSpecContracts(specs) {
+    for (const spec of specs) {
+        validateAdjudicatedLoopContract(spec.id, spec.loopContract);
+        validatePromptSurfaceReference(spec.id, 'coder.primary.prompt', spec.coder.primary.prompt);
+        validateOutputSurface(spec.id, 'coder.primary.output', spec.coder.primary.output);
+        if (spec.coder.response) {
+            validatePromptSurfaceReference(spec.id, 'coder.response.prompt', spec.coder.response.prompt);
+            validateOutputSurface(spec.id, 'coder.response.output', spec.coder.response.output);
+        }
+        validatePromptSurfaceReference(spec.id, 'reviewer.prompt', spec.reviewer.prompt);
+        validateOutputSurface(spec.id, 'reviewer.output', spec.reviewer.output);
+        for (const capability of spec.reviewer.capabilities ?? []) {
+            validatePromptSurfaceReference(spec.id, 'reviewer.capability', capability);
+        }
+        validateTransitionSignals(spec);
+    }
+    validateFamilyRuntimeCoverage(specs);
+}
+validateAdjudicationSpecContracts(ADJUDICATION_SPECS);
+const ADJUDICATION_SPEC_MAP = new Map(ADJUDICATION_SPECS.map((spec) => [spec.id, spec]));
+export function getAdjudicationSpec(id) {
+    const spec = ADJUDICATION_SPEC_MAP.get(id);
+    if (!spec) {
+        throw new Error(`Unknown adjudication spec: ${id}`);
+    }
+    return spec;
+}
+export function assertAdjudicationTransitionSignal(spec, signal, callerLabel) {
+    if (spec.transitionSignals.includes(signal)) {
+        return;
+    }
+    throw new Error(`${callerLabel} resolved transition signal ${signal} for adjudication spec ${spec.id} ` +
+        `family ${spec.family}, but allowed signals are: ${spec.transitionSignals.join(', ')}.`);
+}
+export function getReviewerCapability(spec, variantKind) {
+    const capability = spec.reviewer.capabilities?.find((candidate) => candidate.variantKind === variantKind);
+    if (!capability) {
+        throw new Error(`Adjudication spec ${spec.id} reviewer is missing capability ${variantKind}.`);
+    }
+    return capability;
+}

package/dist/neal/agents/prompts.js

@@ -0,0 +1,120 @@
+import { assertNoReadPromptInstructionText, renderInlineReviewerContext, } from '../context/inline-review-context.js';
+import { renderReviewerContextMarkdown } from '../context/reviewer-context.js';
+import { AUTONOMY_BLOCKED as SHARED_AUTONOMY_BLOCKED, AUTONOMY_CHUNK_DONE as SHARED_AUTONOMY_CHUNK_DONE, AUTONOMY_DONE as SHARED_AUTONOMY_DONE, AUTONOMY_SCOPE_DONE as SHARED_AUTONOMY_SCOPE_DONE, AUTONOMY_SPLIT_PLAN as SHARED_AUTONOMY_SPLIT_PLAN, buildProgressSection, getCanonicalPlanContractLines, getProtocolMarkerArtifactProhibitionLines, getStandalonePlanPayloadSourceOfTruthLines, } from '../prompts/shared.js';
+import { getUserGuidanceLines } from '../prompts/guidance.js';
+export { buildCoderResponsePrompt, buildLegacyScopePrompt, buildReviewerPrompt, buildScopePrompt } from '../prompts/execute.js';
+export { buildCoderPlanResponsePrompt, buildLegacyPlanningPrompt, buildPlanReviewerPrompt, buildPlanningPrompt, } from '../prompts/planning.js';
+export { buildFinalCompletionReviewerPrompt, buildFinalCompletionSummaryPrompt, } from '../prompts/specialized.js';
+export const AUTONOMY_BLOCKED = SHARED_AUTONOMY_BLOCKED;
+export const AUTONOMY_CHUNK_DONE = SHARED_AUTONOMY_CHUNK_DONE;
+export const AUTONOMY_DONE = SHARED_AUTONOMY_DONE;
+export const AUTONOMY_SCOPE_DONE = SHARED_AUTONOMY_SCOPE_DONE;
+export const AUTONOMY_SPLIT_PLAN = SHARED_AUTONOMY_SPLIT_PLAN;
+// Single no-read-safe prompt variant for the read-only blocked-run adjudicator.
+// It generalizes across every triaged block class (a coder-blocked signal or a
+// reviewer `review_stuck` deadlock): it takes a NON-null InlineReviewerContext
+// (the round runner narrows before calling it) and judges entirely from whatever
+// sections that context supplies, making no assumptions about which sections are
+// present. The static Neal-authored instructions must never reference
+// repository/file/shell access, so they pass through the shared no-read guard.
+export function buildBlockedAdjudicatorPrompt(args) {
+    const staticInstructionLines = [
+        'You are a read-only adjudicator for a blocked neal run. The run has stopped because a coder or reviewer turn reported a blocker it could not resolve on its own.',
+        'Judge entirely from the inlined context sections below. You make no changes, run nothing, and look at nothing outside this prompt.',
+        'Decide whether the block is an autonomously recoverable misunderstanding that can be resolved WITHIN the existing scope, or a genuine wall that must escalate to a human.',
+        'Return `recoverable:true` with `triageCategory:"misunderstanding"` and a concrete, in-scope `resolutionDirective` ONLY when ALL of these hold:',
+        '- the block stems from a genuine misunderstanding (the blocked party means something different from, or missed something already present in, the plan or the inlined context),',
+        '- it can be resolved within the current scope as written, with no new authorization, credentials, network access, external services, external state, or scope expansion,',
+        '- the resolution does not require asking the operator a question (a bounded clarification that needs an operator answer is NOT in scope here; treat it as a genuine wall).',
+        'The `resolutionDirective` must be a concrete instruction the blocked party can act on immediately, naming the specific in-scope action that breaks the block.',
+        'Otherwise return `recoverable:false` with the matching genuine-wall category:',
+        '- `authorization`: the next useful step needs explicit new authorization, credentials, or permission.',
+        '- `external_precondition`: it needs network access, external services, or external state that cannot be created in-scope.',
+        '- `impossible_task`: the scope as written cannot be satisfied.',
+        'If the inlined context lists specific blocking findings, set `targetCanonicalIds` to the canonical ids your verdict addresses; otherwise leave it empty.',
+        'Always provide a non-empty `rationale` explaining the triage.',
+    ];
+    assertNoReadPromptInstructionText(staticInstructionLines.join('\n'), 'buildBlockedAdjudicatorPrompt');
+    return [
+        ...staticInstructionLines,
+        '',
+        'Blocked reason:',
+        args.blockedReason,
+        '',
+        renderInlineReviewerContext(args.inlineContext),
+    ].join('\n');
+}
+function getReviewerContextLines(reviewerContext, mode = 'tool-access') {
+    if (!reviewerContext) {
+        return [];
+    }
+    return [
+        '',
+        'Bounded current-run continuity context:',
+        mode === 'inline' ? renderReviewerContextMarkdown(reviewerContext, { mode: 'inline' }) : reviewerContext.promptMarkdown,
+    ];
+}
+export function buildBlockedRecoveryCoderPrompt(args) {
+    const allowReplacement = args.allowReplacement ?? true;
+    const actionLines = [
+        '- `resume_current_scope`',
+        ...(allowReplacement ? ['- `replace_current_scope`'] : []),
+        ...(args.terminalOnly && !allowReplacement ? [] : ['- `stay_blocked`']),
+        '- `terminal_block`',
+    ];
+    const terminalOnlyInstruction = args.terminalOnly && allowReplacement
+        ? 'The recovery turn cap has been reached. You must choose either `replace_current_scope` or `terminal_block`. Do not use `resume_current_scope` or `stay_blocked`.'
+        : args.terminalOnly
+            ? 'The recovery turn cap has been reached. You must choose `terminal_block`. Do not use `resume_current_scope` or `stay_blocked`.'
+            : 'Use `resume_current_scope` when the current scope is still correct and the operator guidance gives enough direction to continue normally.';
+    return [
+        `Continue blocked recovery for the current neal scope in ${args.planDoc}.`,
+        `Read ${args.recoveryMarkdownPath} before responding so you understand the blocked-recovery history.`,
+        'Blocked recovery is now in-band inside Neal. Do not tell the operator to leave Neal or resume the coder session separately.',
+        'Use the inlined progress state below to stay on the current scope.',
+        'You are still handling the same blocked scope. Do not start a new scope.',
+        ...getUserGuidanceLines('coder'),
+        'Choose exactly one recovery action in your structured response:',
+        ...actionLines,
+        terminalOnlyInstruction,
+        allowReplacement
+            ? 'Use `replace_current_scope` when the current scope shape is wrong and Neal should route the replacement through the existing split-plan / derived-plan machinery.'
+            : '`replace_current_scope` is not available for this run because replacing the scope would discard or rewrite externally authored commits.',
+        args.terminalOnly
+            ? 'Use `terminal_block` when no safe in-repo path remains and the run must finalize as truly blocked.'
+            : 'Use `stay_blocked` when more operator guidance is still required and the run should remain in interactive blocked recovery.',
+        args.terminalOnly
+            ? 'Do not ask for additional operator guidance in this turn.'
+            : 'Use `terminal_block` only when no safe in-repo path remains and the run should finalize as truly blocked.',
+        'Always include a `summary` and `rationale`.',
+        allowReplacement
+            ? 'Always include a `blocker` string. Use an empty string only when action=`resume_current_scope` or action=`replace_current_scope`.'
+            : 'Always include a `blocker` string. Use an empty string only when action=`resume_current_scope`.',
+        allowReplacement
+            ? 'Always include a `replacementPlan` string. Use an empty string unless action=`replace_current_scope`.'
+            : 'Always include an empty `replacementPlan` string.',
+        ...(allowReplacement
+            ? [
+                'When action=`replace_current_scope`, `replacementPlan` must use the same Neal-executable contract as a top-level plan.',
+                'Any replacement-specific rationale sections are optional additive context only; they must not replace or rename the canonical machine-consumed sections.',
+                ...getStandalonePlanPayloadSourceOfTruthLines({
+                    planLabel: 'replacement plan',
+                    payloadLabel: '`replacementPlan` field',
+                    resetWorkLabel: 'Abandoned scope work',
+                }),
+                ...getProtocolMarkerArtifactProhibitionLines(),
+                ...getCanonicalPlanContractLines(),
+            ]
+            : []),
+        'Do not invent a new recovery taxonomy or extra top-level actions.',
+        'Do not treat operator guidance as authorization to skip verification, waive policy, or reinterpret the target beyond the current scope.',
+        '',
+        'Blocked recovery context:',
+        `- Blocked reason: ${args.blockedReason}`,
+        `- Recovery turns used: ${args.turnsTaken} of ${args.maxTurns}`,
+        `- Latest operator guidance: ${args.operatorGuidance}`,
+        '',
+        'Current progress state:',
+        buildProgressSection(args.progressText),
+    ].join('\n');
+}