@navels/neal 0.1.0

package/dist/neal/prompts/planning.js

@@ -0,0 +1,313 @@
+import { assertNoReadPromptInstructionText, renderInlineReviewerContext, } from '../context/inline-review-context.js';
+import { renderReviewerContextMarkdown } from '../context/reviewer-context.js';
+import { AUTONOMY_BLOCKED, AUTONOMY_DONE, getCanonicalPlanContractLines, getDerivedPlanSectionContractLines, getProtocolMarkerArtifactProhibitionLines, getTerminalMarkerArtifactBoundaryLines, getUnattendedAutonomyLines, } from './shared.js';
+import { assertPromptBuilder } from './assert-builder.js';
+import { getUserGuidanceLines } from './guidance.js';
+import { getAdversarialReviewDoctrineLines, getPlanReviewFalsificationLines, getVerificationSkepticismLines, resolveReviewerPromptAccessMode, } from './review-doctrine.js';
+const PROMPT_MODULE_PATH = 'src/neal/prompts/planning.ts';
+function getPlanningPromptBaseLines(planDoc) {
+    return [
+        `Refine the existing plan document at ${planDoc} into a stronger future execution plan for neal.`,
+        '',
+        'Before doing anything else:',
+        `1. Read ${planDoc} when it is accessible. If that path is outside your file-tool jail, use the inlined current plan content below as the authoritative plan text.`,
+        '2. Read any companion docs explicitly referenced by that plan.',
+        '3. Reset your instructions for this turn from the current contents of the plan and referenced context.',
+        '',
+        'Then identify weaknesses in the current plan and improve it. Look specifically for:',
+        '- Underdeveloped scopes that need more implementation detail.',
+        '- Vague or missing acceptance criteria / completion criteria.',
+        '- Ambiguous scope boundaries or hidden assumptions about the repository.',
+        '- Poor or unclear sequencing between scopes.',
+        '- Verification that is not executable or not concrete.',
+        '- Planning-task scaffolding left over from an earlier draft.',
+        'Produce a substantively improved revision in the same file.',
+        'If the current plan is already strong, do not invent new weaknesses; revise only what actually improves it.',
+        "Refine for executability without expanding the author's scope. Include refactoring only when the plan calls for it, the objective genuinely requires it, or implementing the change would otherwise increase complexity such that a refactor is a natural outgrowth — not opportunistically.",
+        '',
+        'Revise only plan-related artifacts.',
+        'Do not edit runtime source code outside the plan itself and adjacent planning notes.',
+        'Do not make git commits.',
+        'Your output must be a pure future execution plan, not a planning-task checklist.',
+        'Replace the plan in place so the resulting file is meant to be run later with `neal execute`, not `neal plan`.',
+        'Do not leave planning-only scaffolding in the final file. Remove or replace sections such as planning mode instructions, Required Inputs for the planner, Verification For This Planning Task, and Completion Criteria For This Planning Task.',
+        'Ground the plan in the actual current repository state. Inspect the real target files and write steps against the symbols, exports, and file structure that actually exist.',
+        'Do not leave avoidable ambiguity in the plan when the repository already answers the question. Name concrete target functions, files, and exports when they are knowable from the repo.',
+        'Do not ask the future executor to perform redundant edits. If an export already propagates through an existing barrel file, say to verify that behavior instead of adding a fake extra edit step.',
+        'Make the final plan explicit about scope boundaries, allowed scope, forbidden paths, implementation steps, verification, completion criteria, blocker handling, and any repeated-scope selection rules.',
+        'Choose `multi_scope` when the work changes orchestration or state-machine behavior, resume semantics, persistence or schema shape, multiple independent subsystems, or otherwise naturally falls into staged rollout checkpoints.',
+        'Choose `multi_scope_unknown` when the work repeats one bounded recurring slice at a time and the total number of scopes is intentionally unknown until an explicit completion condition is satisfied.',
+        'Choose `one_shot` only when the work can realistically be executed, reviewed, and verified as one bounded scope without hidden staging assumptions.',
+    ];
+}
+function getInlineCurrentPlanLines(planDocument) {
+    if (!planDocument) {
+        return [];
+    }
+    return [
+        '',
+        'Current plan document content:',
+        '```markdown',
+        planDocument,
+        '```',
+        'Use the inlined plan content above as the source of truth if the plan path itself cannot be read by your tools.',
+    ];
+}
+function getPlanReviewerModeLines(args) {
+    const { mode } = args;
+    const derivedPlanContractRule = [
+        'The derived plan should preserve the same target while replacing only the invalid scope shape, and it must use the same canonical Neal-executable shape contract as a top-level plan.',
+        ...getDerivedPlanSectionContractLines(),
+        'Reviewers must require the exact section set for the declared shape: `multi_scope` uses `## Execution Queue` and forbids `## Execution Loop` and `## Completion Condition`; `multi_scope_unknown` uses `## Execution Loop` plus `## Completion Condition` and forbids `## Execution Queue`; `one_shot` forbids all three orchestration sections.',
+    ].join(' ');
+    return {
+        heading: mode === 'derived-plan'
+            ? `Review the derived implementation plan at ${args.planDoc} for scope ${args.derivedFromScopeNumber ?? 'unknown'} in parent plan ${args.parentPlanDoc ?? args.planDoc}.`
+            : `Review the plan document at ${args.planDoc}.`,
+        blockingRule: mode === 'derived-plan'
+            ? 'Use blocking severity when the derived plan does not safely replace the abandoned scope shape, lacks concrete ordered scopes, leaves blast radius too broad, or does not define adequate verification.'
+            : 'Use blocking severity for missing information or plan structure that would prevent neal from executing safely.',
+        scaffoldingRule: mode === 'derived-plan'
+            ? 'Reject vague replans such as "break it into smaller chunks" when they do not define the actual replacement sequence in the canonical Neal-executable plan shape.'
+            : 'Treat leftover planning-task scaffolding as blocking. A final plan must not still describe how to revise itself, how to run `neal plan`, or how to validate the planning task.',
+        wideningRule: mode === 'derived-plan'
+            ? 'Also use blocking severity if the proposal appears to be a real blocker disguised as replanning rather than a safer in-repo execution shape.'
+            : 'Examples of blocking leftover scaffolding include planning-mode execution headers, planner-only required-input sections, "Verification For This Planning Task", and "Completion Criteria For This Planning Task".',
+        focusRule: mode === 'derived-plan'
+            ? 'Focus on whether the derived plan actually addresses the failure mode, is concrete enough to execute, reduces blast radius, and is truly not a blocker.'
+            : 'Focus on plan quality for refinement: scopes that need more detail, acceptance criteria that are vague or missing, ambiguous boundaries, hidden assumptions about the repository, weak sequencing, and non-executable verification. Call out plan steps that are avoidably ambiguous or redundant when the current repository already provides a more specific answer, such as existing function names, current exports, or barrel re-export behavior.',
+        contractRule: mode === 'derived-plan'
+            ? derivedPlanContractRule
+            : 'Focus on whether the plan is now a clean future execution plan, explicit about single-scope vs repeated-scope behavior, and clear about verification and completion.',
+    };
+}
+function getAuthoredOneShotPlanningLines(authoredOneShot) {
+    if (!authoredOneShot) {
+        return [];
+    }
+    return [
+        'This plan was authored as a single-scope (`one_shot`) plan; keep it one scope, make the smallest complete change, and do not restructure it into multiple scopes.',
+    ];
+}
+function getAuthoredOneShotReviewerLines(authoredOneShot) {
+    if (!authoredOneShot) {
+        return [];
+    }
+    return [
+        'This plan was authored `one_shot`; raise a blocking finding if the document declares any other execution shape or adds orchestration sections.',
+    ];
+}
+export function buildPlanningPrompt(planDoc, planDocument, options) {
+    const spec = assertPromptBuilder('plan_author', 'buildPlanningPrompt', PROMPT_MODULE_PATH);
+    const primaryVariant = spec.variants.find((variant) => variant.kind === 'primary');
+    if (!primaryVariant) {
+        throw new Error('Prompt spec plan_author is missing a primary variant');
+    }
+    return [
+        ...getPlanningPromptBaseLines(planDoc),
+        ...getInlineCurrentPlanLines(planDocument),
+        ...getAuthoredOneShotPlanningLines(options?.authoredOneShot),
+        ...getUnattendedAutonomyLines(options?.unattended),
+        ...getProtocolMarkerArtifactProhibitionLines(),
+        ...getCanonicalPlanContractLines(),
+        'If critical information is missing, do not invent it. Surface the concrete missing questions in your final response.',
+        'Return only a structured planning envelope with these fields:',
+        '- `action`: `ready_for_review` after the plan file has been revised and is ready for review, or `blocked` when critical information is missing.',
+        '- `message`: concise human-readable summary of what changed or why you are blocked.',
+        '- `executionShape`: exactly the chosen shape for the final plan: `one_shot`, `multi_scope`, or `multi_scope_unknown`.',
+        '- `planBody`: the complete final contents of the plan file when `action` is `ready_for_review`; otherwise an empty string.',
+        '- `blockedReason`: concrete missing information when `action` is `blocked`; otherwise an empty string.',
+        'Do not use terminal marker lines for this primary planning response.',
+        ...getUserGuidanceLines('planner'),
+    ].join('\n');
+}
+export function buildLegacyPlanningPrompt(planDoc, planDocument) {
+    return [
+        ...getPlanningPromptBaseLines(planDoc),
+        ...getInlineCurrentPlanLines(planDocument),
+        ...getTerminalMarkerArtifactBoundaryLines(),
+        ...getCanonicalPlanContractLines(),
+        'If critical information is missing, do not invent it. Surface the concrete missing questions in your final response.',
+        ...getUserGuidanceLines('planner'),
+        '',
+        'Final line must be exactly one of:',
+        `- ${AUTONOMY_DONE}`,
+        `- ${AUTONOMY_BLOCKED}`,
+    ].join('\n');
+}
+export function buildPlanReviewerPrompt(args) {
+    const mode = args.mode ?? 'plan';
+    const spec = assertPromptBuilder('plan_reviewer', 'buildPlanReviewerPrompt', PROMPT_MODULE_PATH);
+    const expectedVariant = mode === 'derived-plan' ? 'derived_plan' : 'primary';
+    if (!spec.variants.some((variant) => variant.kind === expectedVariant)) {
+        throw new Error(`Prompt spec ${spec.id} is missing variant ${expectedVariant}`);
+    }
+    const accessMode = resolveReviewerPromptAccessMode({
+        builder: 'buildPlanReviewerPrompt',
+        accessMode: args.accessMode,
+        inlineContextSupplied: Boolean(args.inlineContext),
+    });
+    const noRead = accessMode === 'no-read';
+    const modeLines = getPlanReviewerModeLines({
+        mode,
+        planDoc: args.planDoc,
+        parentPlanDoc: args.parentPlanDoc,
+        derivedFromScopeNumber: args.derivedFromScopeNumber,
+    });
+    const skepticismLines = getVerificationSkepticismLines({
+        reviewTarget: 'planned behavior',
+        coverageTarget: 'planned behavior',
+        coverageGapDescription: 'the plan lacks, weakens, or fails to require meaningful coverage for the riskiest planned behavior',
+        insufficientCoverageTarget: 'planned behavior',
+        mode: accessMode,
+    });
+    const reviewHistoryLine = noRead
+        ? 'Prior review history and coder responses are inlined below; consider them before finalizing findings.'
+        : `Read ${args.reviewMarkdownPath} before finalizing findings so you can inspect prior review history and coder responses.`;
+    const planInspectionLine = noRead
+        ? 'The reviewed plan content (and any parent plan content) is inlined below; finalize findings entirely from the inlined context in this prompt.'
+        : accessMode === 'read-only'
+            ? 'The reviewed plan content is inlined below; use your read-only file tools to inspect directly referenced companion docs and repository source files before finalizing findings.'
+            : 'The reviewed plan content is inlined below; use repository tools to inspect directly referenced companion docs and repository source files before finalizing findings.';
+    if (noRead) {
+        assertNoReadPromptInstructionText([...skepticismLines, reviewHistoryLine, planInspectionLine].join('\n'), 'buildPlanReviewerPrompt');
+    }
+    return [
+        modeLines.heading,
+        `Review round: ${args.round}.`,
+        '',
+        ...getAdversarialReviewDoctrineLines({
+            reviewSubject: 'the plan-readiness claim',
+            falsificationTarget: 'whether the plan is actually Neal-executable',
+            creditPhrase: 'accept it as ready',
+            claimSources: 'the plan narrative, prior review history, or operator framing',
+            judgmentTarget: 'plan readiness',
+            proofTarget: 'the plan will guide safe execution',
+        }),
+        ...skepticismLines,
+        '',
+        'Produce only structured review findings.',
+        'This is a read-only plan review. Do not edit files, create scratch artifacts, stage changes, commit, or otherwise mutate the repository.',
+        'The coder owns the plan document and must declare exactly one execution shape inside it: `one_shot`, `multi_scope`, or `multi_scope_unknown`.',
+        'You must confirm the declared execution shape and echo it in the required `executionShape` field of your structured output.',
+        'Raise a blocking finding when the declared shape is missing, internally inconsistent, or not safe for neal execution.',
+        'Assess execution readiness explicitly across these dimensions: scope granularity, verification concreteness, and resume safety.',
+        ...getPlanReviewFalsificationLines(),
+        'When you raise a blocking finding about execution readiness, name the failing dimension directly in the claim or required action.',
+        'Every finding must rest on concrete evidence, not assumption. Any claim about the repository’s current state — whether a file, symbol, export, or test node id exists, or whether a verification command collects or passes — must be verified by direct inspection (read the file, search the tree, collect the tests) and cite what you found; any claim about the plan must quote the exact plan text it rests on. If you cannot verify a claim, state the uncertainty instead of raising it as blocking.',
+        'Never infer the repository’s current state from what the plan proposes to change. A plan proposing to add a file, class, or test is not evidence that it already exists; a plan introducing a new abstraction is not evidence that existing code or tests are already organized around it. Confirm presence or absence against the actual tree before asserting it.',
+        'Scope granularity means boundaries stay narrow, auditable, and avoid accidental widening.',
+        'Verification concreteness means the plan uses executable verification commands or deterministic repo-derived checks rather than vague instructions.',
+        'Resume safety means scopes have clean stopping points, understandable ordering, and no hidden staging assumptions.',
+        'A plan should generally be forced to `multi_scope` when it changes orchestration behavior, resume semantics, persistence/schema shape, multiple independent subsystems, or naturally staged rollout checkpoints.',
+        'A plan should generally be forced to `multi_scope_unknown` when the work is an intentionally open-ended recurring loop that still executes one bounded scope per cycle and ends only when a stated completion condition becomes true.',
+        modeLines.blockingRule,
+        modeLines.scaffoldingRule,
+        modeLines.wideningRule,
+        'Use non_blocking severity for clarity improvements that do not block execution.',
+        modeLines.focusRule,
+        modeLines.contractRule,
+        'If the plan is already Neal-executable, confirm that quickly and return no manufactured findings.',
+        reviewHistoryLine,
+        ...getAuthoredOneShotReviewerLines(args.authoredOneShot),
+        ...getReviewerContextLines(args.reviewerContext, noRead ? 'inline' : 'tool-access'),
+        ...getUnattendedAutonomyLines(args.unattended),
+        ...getUserGuidanceLines('reviewer'),
+        '',
+        planInspectionLine,
+        ...getReviewedPlanContentLines({
+            noRead,
+            planDoc: args.planDoc,
+            reviewedPlanContent: args.reviewedPlanContent,
+            parentPlanDoc: args.parentPlanDoc,
+            parentPlanContent: args.parentPlanContent,
+        }),
+        ...(args.inlineContext ? ['', renderInlineReviewerContext(args.inlineContext)] : []),
+    ].join('\n');
+}
+function getReviewedPlanContentLines(args) {
+    if (args.noRead || !args.reviewedPlanContent) {
+        return [];
+    }
+    return [
+        '',
+        `Reviewed plan content from Neal (${args.planDoc}):`,
+        '```markdown',
+        args.reviewedPlanContent,
+        '```',
+        ...(args.parentPlanDoc && args.parentPlanContent
+            ? [
+                '',
+                `Parent plan content from Neal (${args.parentPlanDoc}):`,
+                '```markdown',
+                args.parentPlanContent,
+                '```',
+            ]
+            : []),
+        'Use the inlined plan content above as the authoritative plan text for plan-readiness review. Repository inspection should focus on validating referenced files, symbols, assumptions, and companion docs.',
+    ];
+}
+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 buildCoderPlanResponsePrompt(args) {
+    const mode = args.mode ?? 'blocking';
+    const reviewMode = args.reviewMode ?? 'plan';
+    const spec = assertPromptBuilder('plan_author', 'buildCoderPlanResponsePrompt', PROMPT_MODULE_PATH);
+    if (!spec.variants.some((variant) => variant.kind === 'response')) {
+        throw new Error(`Prompt spec ${spec.id} is missing a response variant`);
+    }
+    return [
+        reviewMode === 'derived-plan'
+            ? `Continue refining the derived implementation plan at ${args.planDoc} for scope ${args.derivedFromScopeNumber ?? 'unknown'} in parent plan ${args.parentPlanDoc ?? args.planDoc}.`
+            : `Continue refining the plan document at ${args.planDoc} into a stronger future execution plan.`,
+        '',
+        mode === 'blocking'
+            ? 'Address the currently open review findings provided below.'
+            : 'The currently open review findings below are non-blocking. Decide whether to address each one now or explicitly reject/defer it with rationale.',
+        reviewMode === 'derived-plan'
+            ? 'Edit only the derived plan artifact and directly related planning notes for that derived plan.'
+            : 'Edit only the plan document and directly related planning artifacts.',
+        'Do not edit runtime source code.',
+        'Do not make git commits.',
+        reviewMode === 'derived-plan'
+            ? 'Keep the same target, but make the derived plan concrete enough to replace the abandoned scope safely.'
+            : 'The final file must be a pure future execution plan for `neal execute`.',
+        reviewMode === 'derived-plan'
+            ? 'Do not silently widen the target or convert a real blocker into a vague replan.'
+            : 'Do not leave planning-task scaffolding behind after you respond to the findings.',
+        reviewMode === 'derived-plan'
+            ? 'Revise the derived plan so it uses the same Neal-executable contract as a top-level plan. Any derived-plan-specific rationale sections are optional additive context only; they must not replace the canonical machine-consumed sections.'
+            : 'Where the current repository already answers an implementation detail, revise the plan to use the concrete existing symbol names and exports instead of leaving generic or redundant instructions.',
+        ...(reviewMode === 'derived-plan' ? getDerivedPlanSectionContractLines() : []),
+        ...getProtocolMarkerArtifactProhibitionLines(),
+        ...(reviewMode === 'derived-plan' ? getCanonicalPlanContractLines() : []),
+        'Use `fixed` only when you actually revised the plan to resolve the finding.',
+        'Use `rejected` only when the finding is incorrect and your summary explains why.',
+        'Use `deferred` only when the finding is real but not safe to resolve without user input.',
+        'Always include a `blocker` string. Use an empty string when outcome=`responded`.',
+        mode === 'blocking'
+            ? 'If required information is missing, return outcome=`blocked` and explain the concrete questions in `blocker`.'
+            : 'Return outcome=`blocked` only if you are genuinely unable to make or explain a decision on these findings.',
+        ...getUserGuidanceLines('planner'),
+        '',
+        ...(args.planReviewGuidance
+            ? [
+                'Operator guidance for this blocked plan-review recovery:',
+                args.planReviewGuidance.message,
+                '',
+                'This guidance supplements the open reviewer findings. It does not waive plan-contract requirements, verification requirements, or the need to address blocking findings.',
+                '',
+            ]
+            : []),
+        'Open findings:',
+        JSON.stringify(args.openFindings, null, 2),
+    ].join('\n');
+}

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

@@ -0,0 +1,142 @@
+// Resolve the effective doctrine access mode for a reviewer prompt builder.
+// Precedence: an explicit accessMode wins; when absent, derive exactly the
+// legacy two-way behavior (inline context present -> 'no-read', else
+// 'tool-access') so existing callers render byte-identically. Inline context
+// combined with an explicit mode other than 'no-read' is mismatched wiring
+// (the call site inlined context for a reviewer the capability registry says
+// can read), which is a bug rather than a render choice.
+export function resolveReviewerPromptAccessMode(args) {
+    if (args.inlineContextSupplied && args.accessMode !== undefined && args.accessMode !== 'no-read') {
+        throw new Error(`${args.builder} received Neal-inlined reviewer context with explicit access mode ${JSON.stringify(args.accessMode)}; ` +
+            "inline context is only valid with the 'no-read' access mode");
+    }
+    if (args.accessMode !== undefined) {
+        return args.accessMode;
+    }
+    return args.inlineContextSupplied ? 'no-read' : 'tool-access';
+}
+export function getAdversarialReviewDoctrineLines(context) {
+    const falsificationTarget = context.falsificationTarget ?? 'the implementation';
+    const creditPhrase = context.creditPhrase ?? 'give it credit for working';
+    const claimSources = context.claimSources ?? 'the coder narrative, progress justification, or prior acceptance history';
+    const judgmentTarget = context.judgmentTarget ?? 'correctness';
+    const proofTarget = context.proofTarget ?? 'the code is sound';
+    return [
+        `Treat ${context.reviewSubject} as hostile input. Try to falsify ${falsificationTarget} before you ${creditPhrase}.`,
+        `Do not anchor on ${claimSources} when judging ${judgmentTarget}. Those are convergence signals, not proof that ${proofTarget}.`,
+    ];
+}
+export function getCodeReviewFalsificationLines(context) {
+    const mode = context.mode ?? 'tool-access';
+    const reviewTarget = context.reviewTarget ?? 'changed behavior';
+    const rangeDiffInlined = mode === 'read-only' && context.rangeDiffInlined === true;
+    const lines = [];
+    if (context.rangeLabel) {
+        lines.push(mode === 'no-read'
+            ? `The diff inlined below is the source of truth for this review of that ${context.rangeLabel}. You have no repository access; judge entirely from the inlined context in this prompt.`
+            : mode === 'read-only'
+                ? rangeDiffInlined
+                    ? `The commit-range diff for that ${context.rangeLabel} is inlined below and is the source of truth for exactly what the ${context.rangeLabel} changed (including deletions and renames). Use your read tools to verify the surrounding code; you have no commit-range diff tool, so rely on the inlined diff for what changed.`
+                    : `Review that ${context.rangeLabel} directly with your read-only repository tools: use the git_diff tool to see exactly what the ${context.rangeLabel} changed (including deletions and renames), and your read tools to verify the surrounding code. The ${context.rangeLabel} is the source of truth for this review.`
+                : `Review that ${context.rangeLabel} directly with repository tools. The ${context.rangeLabel} is the source of truth for this review.`);
+    }
+    if (mode === 'no-read') {
+        lines.push('A diff shows only changed hunks; declarations such as imports, struct fields, or helpers may exist in unchanged parts of the file. Never raise a missing-import or missing-declaration finding from absence in the diff alone — only claim one when the diff itself removes the declaration or adds a new file that lacks it. If you cannot verify such a claim from the inlined context, state the uncertainty instead of asserting a defect.');
+    }
+    if (mode === 'read-only') {
+        lines.push('A diff shows only changed hunks; declarations such as imports, struct fields, or helpers may exist in unchanged parts of the file. Absence from the diff is not evidence of absence from the repository — open the affected file with your read tools and verify before claiming a missing import or missing declaration.');
+    }
+    if (context.gitInspectionExamples) {
+        if (mode === 'tool-access') {
+            lines.push(context.gitInspectionExamples);
+        }
+        else if (mode === 'read-only') {
+            lines.push(rangeDiffInlined
+                ? 'Inspect the change using the inlined commit-range diff below for what changed (including deletions and renames), then read the changed files in full with your read tools and search the tree for affected symbols and callers to verify claims.'
+                : 'Inspect the change with your read-only tools: call git_diff with the base and head commits named in this prompt (stat:true first for the changed-file overview, then per-path diffs), read the changed files in full, and search the tree for affected symbols and callers to verify claims.');
+        }
+    }
+    lines.push(`Trace the changed runtime path far enough to prove the happy path is reachable and that runtime invariants, data-shape transitions, persistence, and error paths line up with the implementation claims.`, mode === 'no-read'
+        ? `Compare claimed behavior against the actual code and data transitions in the ${reviewTarget}; do not accept summaries when the inlined diff gives a more direct answer.`
+        : `Compare claimed behavior against the actual code and data transitions in the ${reviewTarget}; do not accept summaries when repository inspection gives a more direct answer.`, 'For refactors and config/runtime plumbing changes, actively look for implementation-quality regressions, not just behavioral correctness. Examples include replacing a robust library with a weaker hand-rolled parser, introducing repeated disk reads or reparsing in hot paths, silently weakening error handling, or otherwise making the implementation materially less robust than the prior version.');
+    lines.push('When the requirements enumerate multiple discrete items to change — a list of identifiers, fields, files, endpoints, or call sites — enumerate them yourself and confirm each maps to a concrete change before accepting; do not accept based only on the subset the implementation happened to touch.', 'Treat an unrequested change to a public or exported symbol — a renamed or removed exported function, type, field, constant, or signature that the requirements did not call for — as scope drift and a blocking finding unless the requirements require it: an unrequested public-symbol change widens the blast radius and can break callers the diff does not show.');
+    if (context.includeExecuteFailureClasses) {
+        lines.push('Bias your search toward execute-mode failure classes in this repository: persistence or state-shape mismatches, resume or recovery transition regressions, split-plan or execution-shape contract violations, artifact or reporting mismatches, and verification that does not actually cover the changed behavior.');
+    }
+    return lines;
+}
+export function getVerificationSkepticismLines(context = {}) {
+    const mode = context.mode ?? 'tool-access';
+    const reviewTarget = context.reviewTarget ?? 'changed behavior';
+    const coverageTarget = context.coverageTarget;
+    const coverageLine = coverageTarget
+        ? [
+            `Check whether test coverage for the ${coverageTarget} is missing or degraded.`,
+            `If ${context.coverageGapDescription ?? `the review lacks, weakens, or fails to preserve meaningful test coverage for the ${coverageTarget}`}, treat that as a review finding.`,
+            `Use blocking severity when the missing or degraded coverage leaves the ${context.insufficientCoverageTarget ?? coverageTarget} insufficiently protected.`,
+        ].join(' ')
+        : 'Check whether test coverage for the changed behavior degraded. If the change removes, weakens, or fails to preserve meaningful test coverage for the affected behavior, treat that as a review finding. Use blocking severity when the missing or degraded coverage leaves the changed behavior insufficiently protected.';
+    return [
+        mode === 'no-read'
+            ? 'Do not infer that verification was skipped merely because this prompt does not embed full terminal output. Treat missing verification as a finding only when the inlined context, plan requirements, or review history give concrete evidence that required verification was not run or was insufficient.'
+            : 'Do not infer that verification was skipped merely because this prompt does not embed full terminal output. Treat missing verification as a finding only when the repository state, plan requirements, or review history give concrete evidence that required verification was not run or was insufficient.',
+        `Look for verification that cannot catch the failure mode, including tests that mock away the risky runtime path or only assert mocked adapters instead of the ${reviewTarget}.`,
+        coverageLine,
+    ];
+}
+export function getRegressionPreservationLines(context = {}) {
+    const mode = context.mode ?? 'tool-access';
+    const reviewTarget = context.reviewTarget ?? 'changed behavior';
+    return [
+        `Identify the shared subsystems the ${reviewTarget} touches: state machines, event loops, parsers or byte framing, command dispatch, storage or shared-state abstractions, startup/load paths, and long-lived session or connection state.`,
+        'Existing behavior that depends on those subsystems remains part of the contract unless the plan explicitly changes it. Do not accept solely because the newly requested behavior appears implemented; also confirm that adjacent behavior sharing those paths still holds.',
+        mode === 'no-read'
+            ? 'Before accepting, either cite existing tests in the inlined context that cover the plausible regression surfaces or reason through representative existing flows in the inlined diff at the level of state transitions and data ownership.'
+            : mode === 'read-only'
+                ? 'Before accepting, either cite existing tests that cover the plausible regression surfaces — reading them with your read tools — or reason through representative existing flows at the level of state transitions and data ownership.'
+                : 'Before accepting, either cite existing tests that cover the plausible regression surfaces — running them when available — or reason through representative existing flows at the level of state transitions and data ownership.',
+        `Expand this regression check only along paths the ${reviewTarget} actually touches or depends on; you do not need to re-audit unrelated parts of the project.`,
+    ];
+}
+export function getPreexistingFailureContractLines(context = {}) {
+    const mode = context.mode ?? 'tool-access';
+    const reviewTarget = context.reviewTarget ?? 'changed behavior';
+    return [
+        `When the plan requires existing behavior to keep working, this review is not limited to newly changed lines. Apply an acceptance-surface test to any pre-existing crash, failure, flaky behavior, or anomaly reported in the coder narrative, progress justification, or review history instead of discounting it because it predates the ${reviewTarget}.`,
+        "A pre-existing failure is inside the required acceptance surface when the plan explicitly requires the affected existing behavior to keep working, when the plan's stated verification fails because of it, or when the behavior the plan delivers cannot be exercised end-to-end without the failing path. Otherwise it is outside the surface.",
+        mode === 'no-read'
+            ? "For a reported pre-existing failure inside the required surface, reason through the affected existing flows using the inlined context at the level of state transitions and data ownership rather than relying on the coder's dismissal."
+            : mode === 'read-only'
+                ? "For a reported pre-existing failure inside the required surface, read the most relevant existing tests and affected code with your read tools and reason through the affected existing flows directly rather than relying on the coder's dismissal."
+                : "For a reported pre-existing failure inside the required surface, exercise or reason through the affected existing flows directly — run the most relevant existing tests or reproduce the reported behavior when practical — rather than relying on the coder's dismissal.",
+        'An in-surface pre-existing failure that was neither fixed nor surfaced as a blocking concern is a blocking finding, and a dismissal without a concrete out-of-surface reason is a finding.',
+        '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.',
+    ];
+}
+export function getPlanReviewFalsificationLines() {
+    return [
+        'Try to falsify whether the plan would actually guide safe execution before accepting it as ready.',
+        'Check whether the proposed scopes, sequencing, and verification would catch the riskiest failure modes instead of merely describing plausible work.',
+        'Treat vague verification, hidden state assumptions, broad blast radius, and missing resume boundaries as evidence against plan readiness.',
+    ];
+}
+export function getFindingQualityLines(context = {}) {
+    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.',
+            '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.',
+        ];
+    }
+    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.',
+        '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.',
+        'If the scope is acceptable aside from low-signal trivia, return no finding rather than a non_blocking note.',
+        'Every finding must name the concrete issue, identify the affected files, explain the evidence or failure scenario that makes the issue credible, and state the required correction.',
+    ];
+}

package/dist/neal/prompts/shared.js

@@ -0,0 +1,101 @@
+import { EXECUTE_SCOPE_PROGRESS_PAYLOAD_END, EXECUTE_SCOPE_PROGRESS_PAYLOAD_START, } from '../agents/schemas.js';
+export const AUTONOMY_SCOPE_DONE = 'AUTONOMY_SCOPE_DONE';
+export const AUTONOMY_CHUNK_DONE = 'AUTONOMY_CHUNK_DONE';
+export const AUTONOMY_DONE = 'AUTONOMY_DONE';
+export const AUTONOMY_BLOCKED = 'AUTONOMY_BLOCKED';
+export const AUTONOMY_SPLIT_PLAN = 'AUTONOMY_SPLIT_PLAN';
+// Single autonomy line rendered into agent prompts when the run is unattended.
+// It tells the agent no operator can answer while keeping every verification
+// requirement intact (unattended means "no human to ask", not "skip checks").
+export const UNATTENDED_AUTONOMY_PROMPT_LINE = 'No operator is available to answer. Resolve this autonomously: do not escalate for operator guidance; make your best judgment and keep all verification requirements intact.';
+export function getUnattendedAutonomyLines(unattended) {
+    return unattended ? [UNATTENDED_AUTONOMY_PROMPT_LINE] : [];
+}
+export function getCanonicalPlanContractLines() {
+    return [
+        'Choose exactly one execution shape: `one_shot`, `multi_scope`, or `multi_scope_unknown`.',
+        'Declare that choice in the plan document with a literal `## Execution Shape` section followed by exactly one line: `executionShape: one_shot`, `executionShape: multi_scope`, or `executionShape: multi_scope_unknown`.',
+        'If the plan should complete in one scope, declare `executionShape: one_shot` and keep the plan single-scope.',
+        'If the plan requires multiple scopes, declare `executionShape: multi_scope` and make scope selection and completion rules explicit.',
+        'If the plan requires one bounded recurring scope at a time but the total number of scopes is intentionally unknown at authoring time, declare `executionShape: multi_scope_unknown` and use one recurring scope template plus an explicit completion condition.',
+        'Shape-specific section rules are mandatory:',
+        '`executionShape: one_shot` must not include a literal `## Execution Queue` section, literal `## Execution Loop` section, or standalone `## Completion Condition` section.',
+        '`executionShape: multi_scope` must include a literal `## Execution Queue` section and must not include a literal `## Execution Loop` section or standalone `## Completion Condition` section.',
+        '`executionShape: multi_scope_unknown` must include a literal `## Execution Loop` section and standalone `## Completion Condition` section and must not include a literal `## Execution Queue` section.',
+        'For `multi_scope` plans, include a literal `## Execution Queue` section.',
+        'Inside `## Execution Queue`, use literal `### Scope N:` headings with contiguous numbering starting at 1.',
+        'Each `### Scope N:` entry must include these labeled bullets: `- Goal:`, `- Verification:`, and `- Success Condition:`.',
+        'For `multi_scope_unknown` plans, include a literal `## Execution Loop` section containing exactly one literal `### Recurring Scope` entry with `- Goal:`, `- Verification:`, and `- Success Condition:` bullets, followed by a literal `## Completion Condition` section.',
+        'Minimal accepted multi-scope shape:',
+        '```md',
+        '## Execution Shape',
+        '',
+        'executionShape: multi_scope',
+        '',
+        '## Execution Queue',
+        '',
+        '### Scope 1: Example scope',
+        '- Goal: Implement one bounded slice.',
+        '- Verification: `pnpm typecheck`',
+        '- Success Condition: The bounded slice is complete and verified.',
+        '```',
+        'Minimal accepted multi-scope-unknown recurring shape:',
+        '```md',
+        '## Execution Shape',
+        '',
+        'executionShape: multi_scope_unknown',
+        '',
+        '## Execution Loop',
+        '',
+        '### Recurring Scope',
+        '- Goal: Implement one bounded recurring slice.',
+        '- Verification: `pnpm typecheck`',
+        '- Success Condition: The recurring slice is complete and reviewable.',
+        '',
+        '## Completion Condition',
+        '',
+        'Stop when the explicit plan-completion condition is satisfied.',
+        '```',
+    ];
+}
+export function getDerivedPlanSectionContractLines() {
+    return [
+        'For a derived plan, choose the declared execution shape first, then include only the orchestration sections valid for that shape.',
+        'A `multi_scope` derived plan must not include a standalone `## Completion Condition` section; that section is valid only for `multi_scope_unknown` derived plans.',
+    ];
+}
+export function getTerminalMarkerArtifactBoundaryLines() {
+    return [
+        'Protocol markers are terminal-response control signals, not artifact content.',
+        `Never write ${AUTONOMY_DONE}, ${AUTONOMY_BLOCKED}, ${AUTONOMY_SCOPE_DONE}, or ${AUTONOMY_SPLIT_PLAN} into any authored markdown or JSON artifact unless the file is explicitly about Neal protocol markers.`,
+        'Finish writing the artifact body first, stop editing files, and then emit exactly one terminal marker only in your final terminal response.',
+        'Bad example: appending a marker line to the plan or recovery artifact itself.',
+        'Good example: leave the file content marker-free, then output the marker as the final line of your terminal response.',
+    ];
+}
+export function getProtocolMarkerArtifactProhibitionLines() {
+    return [
+        'Protocol markers are terminal-response control signals, not artifact content.',
+        `Never write ${AUTONOMY_DONE}, ${AUTONOMY_BLOCKED}, ${AUTONOMY_SCOPE_DONE}, or ${AUTONOMY_SPLIT_PLAN} into any authored markdown or JSON artifact unless the file is explicitly about Neal protocol markers.`,
+        'Bad example: appending a marker line to the plan or recovery artifact itself.',
+        'Good example: leave the file content marker-free.',
+    ];
+}
+export function getStandalonePlanPayloadSourceOfTruthLines(args) {
+    return [
+        `The ${args.payloadLabel} is the source of truth for derived-plan review and must contain a complete standalone ${args.planLabel} body.`,
+        `Do not commit the ${args.planLabel} to the target repository as the source of truth; repo-local notes may help while drafting, but the returned ${args.payloadLabel} must carry the full plan.`,
+        'Do not return only a file path, commit SHA, branch name, reflog entry, PR link, external artifact, or a statement that another file was committed.',
+        `${args.resetWorkLabel} may be reset before derived-plan review begins, so anything needed to execute the replacement plan must be inside the returned ${args.payloadLabel}.`,
+    ];
+}
+export function buildProgressSection(progressText) {
+    return progressText.trim() || '(no current progress summary available)';
+}
+export function getExecuteScopeProgressPayloadContractLines() {
+    return [
+        `Include exactly one progress-justification JSON payload between ${EXECUTE_SCOPE_PROGRESS_PAYLOAD_START} and ${EXECUTE_SCOPE_PROGRESS_PAYLOAD_END}.`,
+        'That JSON payload must contain non-empty string fields for `milestoneTargeted`, `newEvidence`, `whyNotRedundant`, and `nextStepUnlocked`.',
+        'Keep any prose explanation or derived plan body outside that payload block.',
+    ];
+}