@navels/neal 0.1.0

package/dist/neal/adjudicator/final-completion.js

@@ -0,0 +1,104 @@
+import { mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { runCoderFinalCompletionSummaryRound, runReviewerFinalCompletionRound, } from '../agents.js';
+import { createInlineSection, readOnlyReviewerNeedsInlinedDiff, readTextForInlineSection, reviewerNeedsInlineContext, } from '../context/inline-review-context.js';
+import { buildAndPersistReviewerContextPacket } from '../context/reviewer-context.js';
+import { getDiffForRange } from '../git.js';
+import { getFinalCompletionView } from '../state-views.js';
+import { getFinalCompletionReviewerScratchDir } from '../storage-paths.js';
+import { getAdjudicationSpec } from './specs.js';
+export function resolveFinalCompletionAdjudicationContext(args) {
+    const spec = getAdjudicationSpec('final_completion_review');
+    if (spec.family !== 'final_completion') {
+        throw new Error(`Expected final completion adjudication spec, received ${spec.id}.`);
+    }
+    return {
+        spec,
+        packet: args.packet,
+        summary: getFinalCompletionView(args.state)?.summary ?? null,
+    };
+}
+export async function runFinalCompletionSummaryAdjudication(args) {
+    const context = resolveFinalCompletionAdjudicationContext({
+        state: args.state,
+        packet: args.packet,
+    });
+    const summary = await (args.runSummaryRound ?? runCoderFinalCompletionSummaryRound)({
+        coder: args.state.agentConfig.coder,
+        cwd: args.state.cwd,
+        planDoc: args.state.planDoc,
+        packet: context.packet,
+        logger: args.logger,
+    });
+    return {
+        context,
+        summary,
+    };
+}
+async function buildFinalCompletionReviewerInlineContext(args) {
+    const aggregate = args.packet.aggregateReviewContext;
+    const sections = [];
+    if (aggregate.unavailableReason !== null || !aggregate.baseCommit || !aggregate.headCommit) {
+        // Inline the evidence-gap statement instead of a diff so the no-read
+        // reviewer treats the missing aggregate range as a completion-review
+        // evidence gap rather than proof of correctness.
+        sections.push(createInlineSection('Aggregate review evidence gap', `The aggregate diff for this completion review is unavailable: ${aggregate.unavailableReason ?? 'no aggregate commit range was resolved'}. Treat this as a completion-review evidence gap rather than proof that the aggregate implementation is correct.`));
+    }
+    else {
+        const diff = await args.getDiffForRange(args.state.cwd, aggregate.baseCommit, aggregate.headCommit);
+        sections.push(createInlineSection(`Full aggregate diff for range ${aggregate.range ?? `${aggregate.baseCommit}..${aggregate.headCommit}`}`, diff || '(empty diff)'));
+    }
+    const planContent = await readTextForInlineSection(resolve(args.state.cwd, args.state.planDoc));
+    sections.push(createInlineSection(`Plan document content (${args.state.planDoc})`, planContent || '(plan document content unavailable)'));
+    return { sections };
+}
+export async function runFinalCompletionReviewerAdjudication(args) {
+    const finalCompletion = getFinalCompletionView(args.state);
+    if (!finalCompletion?.summary) {
+        throw new Error('Cannot run final completion reviewer adjudication without a final completion summary.');
+    }
+    const context = resolveFinalCompletionAdjudicationContext({
+        state: args.state,
+        packet: args.packet,
+    });
+    const scratchDir = getFinalCompletionReviewerScratchDir(args.state.runDir);
+    await mkdir(scratchDir, { recursive: true });
+    // The aggregate diff is collected only for reviewers without repository read
+    // access; read-capable reviewers inspect the aggregate range with their own
+    // tools.
+    const inlineContext = reviewerNeedsInlineContext(args.state.agentConfig.reviewer)
+        ? await buildFinalCompletionReviewerInlineContext({
+            state: args.state,
+            packet: context.packet,
+            getDiffForRange: args.getDiffForRange ?? getDiffForRange,
+        })
+        : null;
+    // Read-only reviewers with read tools but no commit-range diff tool (native
+    // Claude/Codex) get the aggregate commit-range diff inlined directly when the
+    // aggregate range is available; read-only reviewers that expose their own
+    // commit-range diff tool (generic-agentic) inspect the range with that tool.
+    const aggregate = context.packet.aggregateReviewContext;
+    const inlinedRangeDiff = readOnlyReviewerNeedsInlinedDiff(args.state.agentConfig.reviewer) &&
+        aggregate.unavailableReason === null &&
+        aggregate.baseCommit &&
+        aggregate.headCommit
+        ? await (args.getDiffForRange ?? getDiffForRange)(args.state.cwd, aggregate.baseCommit, aggregate.headCommit)
+        : null;
+    const reviewerResult = await (args.runReviewerRound ?? runReviewerFinalCompletionRound)({
+        reviewer: args.state.agentConfig.reviewer,
+        cwd: args.state.cwd,
+        planDoc: args.state.planDoc,
+        packet: context.packet,
+        summary: finalCompletion.summary,
+        scratchDir,
+        reviewerContext: await buildAndPersistReviewerContextPacket({ state: args.state }),
+        inlineContext,
+        inlinedRangeDiff,
+        unattended: args.state.unattended,
+        logger: args.logger,
+    });
+    return {
+        context,
+        reviewerResult,
+    };
+}

package/dist/neal/adjudicator/planning.js

@@ -0,0 +1,145 @@
+import { resolve } from 'node:path';
+import { runCoderPlanResponseRound, runPlanReviewerRound } from '../agents.js';
+import { createInlineSection, readTextForInlineSection, reviewerNeedsInlineContext, } from '../context/inline-review-context.js';
+import { buildAndPersistReviewerContextPacket } from '../context/reviewer-context.js';
+import { getProviderDefinition } from '../providers/registry.js';
+import { getDerivedPlanView } from '../state-views.js';
+import { getAdjudicationSpec } from './specs.js';
+export function isDerivedPlanReviewState(state) {
+    return getDerivedPlanView(state)?.reviewActive ?? false;
+}
+// The planner role runs through the coder adapter, so its session-resume capability comes from
+// the provider's coder capabilities. Providers that declare `supportsSessionResume: false`
+// (openai-compatible, generic-agentic) never persist a planner session handle — a null handle is
+// their expected steady state, so top-level plan-refinement responses must start a fresh planner
+// session for them instead of treating the missing handle as corrupted state. Resume-capable
+// planner providers keep the hard invariant: a missing handle there is a genuine violation.
+export function plannerProviderStartsFreshSessions(planner) {
+    return !getProviderDefinition(planner.provider).capabilities.coder.supportsSessionResume;
+}
+export function resolvePlanningAdjudicationContext(state) {
+    const derivedPlan = getDerivedPlanView(state);
+    const derivedPlanReview = derivedPlan?.reviewActive ?? false;
+    const reviewMode = derivedPlanReview ? 'derived-plan' : 'plan';
+    const spec = getAdjudicationSpec(reviewMode === 'derived-plan'
+        ? 'derived_plan_review'
+        : 'plan_review');
+    if (spec.family !== 'plan_review') {
+        throw new Error(`Expected planning adjudication spec, received ${spec.id}.`);
+    }
+    return {
+        spec,
+        reviewMode,
+        derivedPlanReview,
+        reviewTargetPath: derivedPlanReview && derivedPlan
+            ? derivedPlan.path
+            : state.planDoc,
+        roundLimit: derivedPlanReview && derivedPlan ? derivedPlan.counters.maxDerivedPlanReviewRounds : state.maxRounds,
+        parentPlanDoc: derivedPlanReview ? state.planDoc : undefined,
+        derivedFromScopeNumber: derivedPlanReview && derivedPlan ? derivedPlan.parentScopeNumber : null,
+    };
+}
+async function buildPlanReviewerInlineContext(args) {
+    const planContent = await readTextForInlineSection(resolve(args.state.cwd, args.reviewedPlanPath));
+    const sections = [
+        createInlineSection(`Reviewed plan document content (${args.reviewedPlanPath})`, planContent || '(plan document content unavailable)'),
+    ];
+    if (args.context.reviewMode === 'derived-plan' && args.context.parentPlanDoc) {
+        const parentPlanContent = await readTextForInlineSection(resolve(args.state.cwd, args.context.parentPlanDoc));
+        sections.push(createInlineSection(`Parent plan document content (${args.context.parentPlanDoc})`, parentPlanContent || '(parent plan document content unavailable)'));
+    }
+    const reviewHistory = await readTextForInlineSection(resolve(args.state.cwd, args.reviewMarkdownPath));
+    sections.push(createInlineSection('Prior review history (REVIEW.md content)', reviewHistory || '(no prior review history)'));
+    return { sections };
+}
+export async function runPlanningReviewerAdjudication(args) {
+    const context = resolvePlanningAdjudicationContext(args.state);
+    const preparedReview = await args.preparePlanReviewArtifact({
+        planPath: context.reviewTargetPath,
+        normalizedPlanPath: args.normalizedPlanPath,
+    });
+    // Plan and review-history contents are inlined only for reviewers without
+    // repository read access; read-capable reviewers inspect them directly.
+    const inlineContext = reviewerNeedsInlineContext(args.state.agentConfig.reviewer)
+        ? await buildPlanReviewerInlineContext({
+            state: args.state,
+            context,
+            reviewedPlanPath: preparedReview.reviewedPlanPath,
+            reviewMarkdownPath: args.reviewMarkdownPath,
+        })
+        : null;
+    const reviewedPlanContent = await readTextForInlineSection(resolve(args.state.cwd, preparedReview.reviewedPlanPath));
+    const parentPlanContent = context.reviewMode === 'derived-plan' && context.parentPlanDoc
+        ? await readTextForInlineSection(resolve(args.state.cwd, context.parentPlanDoc))
+        : null;
+    const reviewerResult = await (args.runReviewerRound ?? runPlanReviewerRound)({
+        reviewer: args.state.agentConfig.reviewer,
+        cwd: args.state.cwd,
+        planDoc: preparedReview.reviewedPlanPath,
+        round: args.round,
+        reviewMarkdownPath: args.reviewMarkdownPath,
+        mode: context.reviewMode,
+        parentPlanDoc: context.parentPlanDoc,
+        derivedFromScopeNumber: context.derivedFromScopeNumber,
+        reviewerContext: await buildAndPersistReviewerContextPacket({ state: args.state }),
+        reviewedPlanContent,
+        parentPlanContent,
+        inlineContext,
+        unattended: args.state.unattended,
+        // Reinforce an author-declared `one_shot` only for the top-level authored plan; derived
+        // plans declare and own their own shape and are never clamped.
+        authoredOneShot: !context.derivedPlanReview && args.state.authoredExecutionShape === 'one_shot',
+        logger: args.logger,
+    });
+    const synthesizedReview = await args.synthesizePlanReviewFindings({
+        planPath: context.reviewTargetPath,
+        round: args.round,
+        roundSummary: reviewerResult.summary,
+        findings: reviewerResult.findings.map((finding) => ({
+            ...finding,
+            source: finding.source,
+        })),
+        preparedReview,
+    });
+    return {
+        context,
+        preparedReview,
+        reviewerResult,
+        synthesizedReview,
+    };
+}
+export async function runPlanningResponseAdjudication(args) {
+    const context = resolvePlanningAdjudicationContext(args.state);
+    // Top-level `neal plan` refinement (reviewMode === 'plan') is normally authored by a persisted
+    // planner session, so a missing handle is a genuine invariant violation for resume-capable
+    // planner providers and must keep throwing. Two paths legitimately run without one:
+    // derived-plan revisions (reviewMode === 'derived-plan') are authored by the coder during
+    // coder_scope and never create a planner session, and no-resume planner providers
+    // (`supportsSessionResume: false`) never persist a handle at all. Both start a fresh planner
+    // session (resumeHandle: null).
+    if (context.reviewMode === 'plan' &&
+        !args.state.plannerSessionHandle &&
+        !plannerProviderStartsFreshSessions(args.state.agentConfig.planner)) {
+        throw new Error('Cannot run planning response adjudication without an existing planner session.');
+    }
+    const planReviewGuidance = args.state.topLevelMode === 'plan' && context.reviewMode === 'plan'
+        ? (args.state.pendingPlanReviewGuidance ?? undefined)
+        : undefined;
+    const response = await (args.runResponseRound ?? runCoderPlanResponseRound)({
+        coder: args.state.agentConfig.planner,
+        cwd: args.state.cwd,
+        planDoc: context.reviewTargetPath,
+        openFindings: args.openFindings,
+        mode: args.mode,
+        sessionHandle: args.state.plannerSessionHandle ?? null,
+        reviewMode: context.reviewMode,
+        parentPlanDoc: context.parentPlanDoc,
+        derivedFromScopeNumber: context.derivedFromScopeNumber,
+        planReviewGuidance,
+        logger: args.logger,
+    });
+    return {
+        context,
+        response,
+    };
+}