@navels/neal 0.1.0 → 0.3.0

package/dist/neal/prompts/planning.js

@@ -1,10 +1,45 @@
-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';
+const PLAN_VERIFICATION_NECESSITY_RULE = 'A repository-wide invariant or global regression guarantee belongs in the plan only when it is necessary for the requested change to be correct.';
+function getPlanVerificationScopeLines(role) {
+    return [
+        PLAN_VERIFICATION_NECESSITY_RULE,
+        role === 'planner'
+            ? 'Otherwise, do not introduce it. If the plan already contains an unnecessary broader guarantee, narrow or remove it instead of expanding the implementation or verification scope to satisfy it.'
+            : 'Otherwise, do not require additional implementation or verification to satisfy it. If an unnecessary broader guarantee makes the plan misleading, require the planner to narrow or remove the guarantee rather than expand its coverage.',
+    ];
+}
+function getPlanDetailLevelLines() {
+    return [
+        'Write for both neal and the operator. Prefer the smallest human-reviewable plan that communicates the approach, scope boundaries, and important decisions.',
+        'Use moderate-to-high-level implementation detail. Name major subsystems, important files, or key interfaces when they clarify the approach, but leave routine implementation discovery to the coder and reviewer working against the implementation.',
+        'Inspect the repository enough to confirm that the approach fits the existing architecture and to identify major dependencies, constraints, and affected subsystems. Do not try to complete the implementation or its full blast-radius analysis in the plan.',
+        'Leave routine file, symbol, caller, and test discovery to execution. Avoid line-by-line change lists, exhaustive inventories, exact assertions, pinned values, and fixture recipes unless they preserve a fixed decision or prevent a known failure.',
+        'Use allowed-path lists, forbidden-path lists, and detailed blocker handling only when the task has a real boundary or known hazard that needs to survive into execution.',
+        ...getPlanVerificationScopeLines('planner'),
+    ];
+}
+function getPlanResponseDetailLevelLines() {
+    return [
+        'Keep the revised plan concise, human-reviewable, and at moderate-to-high-level implementation detail.',
+        'Resolve material findings without expanding the plan into an exhaustive implementation inventory; leave routine discovery to execution.',
+        ...getPlanVerificationScopeLines('planner'),
+    ];
+}
+function getPlanReviewerReadinessLines() {
+    return [
+        'Review the plan independently and look for material problems before accepting it.',
+        'A ready plan preserves the requested objective, proposes a sound approach, accounts for major architectural constraints and dependencies, uses a valid execution shape with coherent scopes, and gives each scope meaningful verification and a reviewable success condition.',
+        'The plan is written for both neal and the operator. It should be concise enough for a person to review, specific enough to guide implementation, and open enough for the coder to make local choices after inspecting the code.',
+        'Raise a blocking finding only when an omission is likely to produce the wrong implementation, make a scope unsafe or impractical, hide a major dependency, leave sequencing materially unclear, or allow incorrect work to appear complete.',
+        'Missing routine implementation detail is not a finding. Do not require exhaustive file, symbol, caller, test, command, assertion, line-number, pinned-value, or fixture inventories.',
+        'More detail can make a plan worse by turning tentative implementation choices into acceptance requirements. Ask for low-level detail only when it records a fixed decision, preserves compatibility, or prevents a known failure.',
+        ...getPlanVerificationScopeLines('reviewer'),
+        'Inspect enough repository context to support material findings. Do not audit every implementation path before code has been written.',
+    ];
+}
 function getPlanningPromptBaseLines(planDoc) {
     return [
         `Refine the existing plan document at ${planDoc} into a stronger future execution plan for neal.`,
@@ -15,15 +50,17 @@ function getPlanningPromptBaseLines(planDoc) {
         '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.',
+        '- Underdeveloped scopes that need enough implementation detail to guide the coder.',
+        '- Missing major architectural constraints or dependencies.',
         '- 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.',
+        '- Verification that would not meaningfully establish the scope\'s success.',
         '- 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.",
+        ...getPlanDetailLevelLines(),
         '',
         'Revise only plan-related artifacts.',
         'Do not edit runtime source code outside the plan itself and adjacent planning notes.',
@@ -31,10 +68,8 @@ function getPlanningPromptBaseLines(planDoc) {
         '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.',
+        'Your refined plan will be reviewed for execution readiness on three dimensions; satisfy each before finalizing: scope granularity (the work is divided into coherent, bounded scopes without exhaustive path inventories), verification concreteness (each scope names meaningful checks without specifying every possible oracle), and resume safety (scopes have understandable ordering and clean stopping points).',
+        'Make the final plan explicit about its execution shape, scope goals and approach, sequencing, meaningful verification, and success conditions. Add constraints, non-goals, or blocker handling only where the task needs them.',
         '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.',
@@ -75,10 +110,10 @@ function getPlanReviewerModeLines(args) {
             : '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.',
+            : 'Focus on plan quality for refinement: a sound implementation approach, material architectural constraints, coherent scopes, clear sequencing, meaningful verification, and reviewable success conditions. Do not turn routine implementation discovery into plan findings.',
         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.',
+            : 'Focus on whether the plan is now a clean, human-reviewable future execution plan, explicit about single-scope vs repeated-scope behavior, and clear about verification and completion.',
     };
 }
 function getAuthoredOneShotPlanningLines(authoredOneShot) {
@@ -142,49 +177,22 @@ export function buildPlanReviewerPrompt(args) {
     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 accessMode = args.accessMode ?? 'tool-access';
     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');
-    }
+    const reviewHistoryLine = `Read ${args.reviewMarkdownPath} before finalizing findings so you can inspect prior review history and coder responses.`;
+    const planInspectionLine = 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.';
     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,
+        ...getPlanReviewerReadinessLines(),
         '',
         '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.',
@@ -192,41 +200,41 @@ export function buildPlanReviewerPrompt(args) {
         '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.',
+        'Scope granularity means the work is divided into coherent, bounded scopes. It does not require an exhaustive allowed-path inventory.',
+        'Verification concreteness means each scope names checks that can meaningfully establish success. It does not require every possible test, oracle, assertion, or shell command to be designed in advance.',
+        'Resume safety means scopes have understandable ordering and clean stopping points. It does not require the plan to prescribe routine Git mechanics.',
         '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.',
+        'Classify every finding with a `findingClass` of either `plan_correctness` or `verification_hardening`.',
+        'A `verification_hardening` finding asks for a material improvement to how already-specified behavior will be verified. It may block only when the planned checks could allow the requested change itself to be wrong while still appearing complete. Incomplete enforcement of an unnecessary broader guarantee introduced by the plan is non-blocking.',
+        'A `plan_correctness` finding means the plan would build the wrong thing, build an unverifiable thing, or contains an impossible or self-contradictory instruction. When you are unsure which class applies, use `plan_correctness`.',
         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'),
+        ...getReviewerContextLines(args.reviewerContext),
         ...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) {
+    if (!args.reviewedPlanContent) {
         return [];
     }
     return [
@@ -247,14 +255,14 @@ function getReviewedPlanContentLines(args) {
         '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') {
+function getReviewerContextLines(reviewerContext) {
     if (!reviewerContext) {
         return [];
     }
     return [
         '',
         'Bounded current-run continuity context:',
-        mode === 'inline' ? renderReviewerContextMarkdown(reviewerContext, { mode: 'inline' }) : reviewerContext.promptMarkdown,
+        reviewerContext.promptMarkdown,
     ];
 }
 export function buildCoderPlanResponsePrompt(args) {
@@ -277,6 +285,7 @@ export function buildCoderPlanResponsePrompt(args) {
             : 'Edit only the plan document and directly related planning artifacts.',
         'Do not edit runtime source code.',
         'Do not make git commits.',
+        ...getPlanResponseDetailLevelLines(),
         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`.',
@@ -285,7 +294,7 @@ export function buildCoderPlanResponsePrompt(args) {
             : '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.',
+            : 'Resolve the material finding without adding planning-task scaffolding.',
         ...(reviewMode === 'derived-plan' ? getDerivedPlanSectionContractLines() : []),
         ...getProtocolMarkerArtifactProhibitionLines(),
         ...(reviewMode === 'derived-plan' ? getCanonicalPlanContractLines() : []),

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

@@ -1,20 +1,3 @@
-// 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';
@@ -32,16 +15,11 @@ export function getCodeReviewFalsificationLines(context) {
     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.');
+        lines.push(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 === '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.');
@@ -56,9 +34,7 @@ export function getCodeReviewFalsificationLines(context) {
                 : '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(`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.`, `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.');
@@ -77,9 +53,7 @@ export function getVerificationSkepticismLines(context = {}) {
         ].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.',
+        '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,
     ];
@@ -90,11 +64,9 @@ export function getRegressionPreservationLines(context = {}) {
     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.',
+        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.`,
     ];
 }
@@ -104,22 +76,13 @@ export function getPreexistingFailureContractLines(context = {}) {
     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.",
+        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 [

package/dist/neal/prompts/specialized.js

@@ -1,10 +1,28 @@
-import { assertNoReadPromptInstructionText, renderInlineReviewerContext, renderInlinedRangeDiffSection, } from '../context/inline-review-context.js';
-import { renderReviewerContextMarkdown } from '../context/reviewer-context.js';
+import { guardStructuredJsonOutputFormatLines } from '../agents/structured-json.js';
+import { renderInlinedRangeDiffSection } from '../context/inline-review-context.js';
 import { assertPromptBuilder } from './assert-builder.js';
 import { getUserGuidanceLines } from './guidance.js';
 import { getUnattendedAutonomyLines } from './shared.js';
-import { getAdversarialReviewDoctrineLines, getCodeReviewFalsificationLines, getFindingQualityLines, getPreexistingFailureContractLines, getRegressionPreservationLines, getVerificationSkepticismLines, resolveReviewerPromptAccessMode, } from './review-doctrine.js';
+import { getAdversarialReviewDoctrineLines, getCodeReviewFalsificationLines, getFindingQualityLines, getPreexistingFailureContractLines, getRegressionPreservationLines, getVerificationSkepticismLines, } from './review-doctrine.js';
 const PROMPT_MODULE_PATH = 'src/neal/prompts/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. openai-compatible) 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 +36,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 +67,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:',
@@ -62,12 +79,7 @@ export function buildFinalCompletionReviewerPrompt(args) {
     if (!finalCompletionVariant) {
         throw new Error('Prompt spec completion_reviewer is missing a final_completion variant');
     }
-    const accessMode = resolveReviewerPromptAccessMode({
-        builder: 'buildFinalCompletionReviewerPrompt',
-        accessMode: args.accessMode,
-        inlineContextSupplied: Boolean(args.inlineContext),
-    });
-    const noRead = accessMode === 'no-read';
+    const accessMode = args.accessMode ?? 'tool-access';
     // A collected diff may legitimately be the empty string (a range with no
     // changes); distinguish "collected" (any string, including '') from "not
     // collected" (null/undefined) so an empty diff still rides the inlined channel
@@ -110,9 +122,6 @@ export function buildFinalCompletionReviewerPrompt(args) {
         reviewTarget: 'aggregate implementation',
         mode: accessMode,
     });
-    if (noRead) {
-        assertNoReadPromptInstructionText([...falsificationLines, ...skepticismLines, ...regressionLines, ...preexistingLines].join('\n'), 'buildFinalCompletionReviewerPrompt');
-    }
     return [
         `Review whether the execute-mode plan at ${args.planDoc} is complete as a whole.`,
         '',
@@ -139,10 +148,9 @@ export function buildFinalCompletionReviewerPrompt(args) {
         ...preexistingLines,
         ...getFindingQualityLines({ outputContract: 'completion_verdict' }),
         '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'),
+        ...getReviewerContextLines(args.reviewerContext),
         'Do not treat prior per-scope acceptance as sufficient evidence that the whole plan is complete or that the aggregate code quality is acceptable.',
-        '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,12 +191,10 @@ 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:',
         lastImplementationScope,
-        ...(args.inlineContext ? ['', renderInlineReviewerContext(args.inlineContext)] : []),
         ...(rangeDiffInlined
             ? [
                 '',
@@ -200,13 +206,13 @@ export function buildFinalCompletionReviewerPrompt(args) {
             : []),
     ].join('\n');
 }
-function getReviewerContextLines(reviewerContext, mode = 'tool-access') {
+function getReviewerContextLines(reviewerContext) {
     if (!reviewerContext) {
         return [];
     }
     return [
         '',
         'Bounded current-run continuity context:',
-        mode === 'inline' ? renderReviewerContextMarkdown(reviewerContext, { mode: 'inline' }) : reviewerContext.promptMarkdown,
+        reviewerContext.promptMarkdown,
     ];
 }