@navels/neal 0.1.0

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

@@ -0,0 +1,172 @@
+const DIFF_PREVIEW_LIMIT = 12000;
+export const REVIEW_FINDINGS_READ_ONLY_RULES = [
+    'Do not mutate the repository.',
+    'Do not make commits, amend commits, rebase, reset, squash, or rewrite history.',
+    'Do not edit source files, Neal writer-run state, queue files, current-run pointers, or run-local RUN_STATE.json files.',
+    'Do not run shell write commands or claim that fixes were applied.',
+    'Review only the frozen selected commit range and the supplied instruction.',
+    'The checkout may advance while this review is running; do not treat current HEAD or dirty worktree files as part of the review target unless they are in the supplied resolved range.',
+    'Produce findings only; do not perform repair work.',
+];
+/**
+ * Read-only range-inspection section appended to the adjudication prompt for
+ * reviewers with read tool access but no shell (the 'read-only' doctrine
+ * access mode). The base adjudication prompt previews at most
+ * DIFF_PREVIEW_LIMIT characters of the resolved-range diff; a read-only
+ * reviewer cannot run git commands, so the read-only git_diff tool is its
+ * only source of truth for what the range actually changed (deletions and
+ * renames included). The section names the exact resolved revisions so the
+ * reviewer does not have to parse them back out of the context summary, and
+ * only claims the preview is truncated when it actually is.
+ */
+export function buildReviewFindingsReadOnlyInspectionSection(context) {
+    const previewTruncated = context.diff.trim() !== '' && context.diff.length > DIFF_PREVIEW_LIMIT;
+    const sourceOfTruthLine = previewTruncated
+        ? 'You have read-only repository tools: read_file, list_dir, grep, and git_diff. The diff preview above is truncated; the git_diff tool is the source of truth for what the resolved range actually changed, including deletions and renames that head-state file reads cannot reveal.'
+        : 'You have read-only repository tools: read_file, list_dir, grep, and git_diff. The git_diff tool is the source of truth for what the resolved range actually changed, including deletions and renames that head-state file reads cannot reveal.';
+    return [
+        '## Read-Only Range Inspection',
+        '',
+        sourceOfTruthLine,
+        `Before returning a verdict, inspect the resolved range with git_diff: first call git_diff with base ${context.externalBaseCommit}, head ${context.externalHeadCommit}, and stat:true for the changed-file overview, then request per-path diffs for the files the draft findings cite.`,
+        'Verify draft claims against the surrounding code with read_file and grep; absence from a diff hunk is not evidence of absence from the repository.',
+    ].join('\n');
+}
+/**
+ * Inlined-diff section appended to the adjudication prompt for a read-only
+ * reviewer that has read tools but no commit-range diff tool (native
+ * Claude/Codex). The base adjudication prompt only previews at most
+ * DIFF_PREVIEW_LIMIT characters of the resolved-range diff and such a reviewer
+ * can neither run git commands nor call a git_diff tool, so Neal inlines the
+ * full selected-range diff here as the source of truth and instructs only the
+ * read tools the provider actually has. Reviewers that expose a commit-range
+ * diff tool get buildReviewFindingsReadOnlyInspectionSection instead.
+ */
+export function buildReviewFindingsInlinedDiffSection(context) {
+    return [
+        '## Inlined Selected-Range Diff',
+        '',
+        'You have read-only repository tools (read and search, no shell) but no commit-range diff tool, so the full selected-range diff is inlined below.',
+        'This inlined diff is the source of truth for what the resolved range actually changed, including deletions and renames that head-state file reads cannot reveal.',
+        `Resolved range: ${context.externalBaseCommit}..${context.externalHeadCommit}.`,
+        'Verify draft claims against the surrounding code with your read tools; absence from a diff hunk is not evidence of absence from the repository.',
+        '',
+        context.diff.trim() === '' ? '(empty diff)' : context.diff,
+    ].join('\n');
+}
+export function buildReviewFindingsDraftPrompt(context, draftContext = {}) {
+    const round = draftContext.round ?? 1;
+    const reviewFindings = draftContext.reviewFindings ?? [];
+    return [
+        '# Neal Review Findings Draft',
+        '',
+        `You are drafting round ${round}${draftContext.maxRounds ? `/${draftContext.maxRounds}` : ''} of a read-only \`neal review\` findings artifact.`,
+        '',
+        '## Read-Only Rules',
+        '',
+        ...REVIEW_FINDINGS_READ_ONLY_RULES.map((rule) => `- ${rule}`),
+        ...(reviewFindings.length > 0
+            ? [
+                '',
+                '## Required Revision Findings',
+                '',
+                ...reviewFindings.map((finding) => `- ${finding}`),
+                '',
+                '## Previous Draft',
+                '',
+                renderDraftSummary(draftContext.previousDraft),
+            ]
+            : []),
+        '',
+        '## Review Instruction',
+        '',
+        context.instruction,
+        '',
+        '## Review Target',
+        '',
+        renderContextSummary(context),
+        '',
+        'Return a summary, concrete findings, and warnings only. Each finding needs severity, files, claim, evidence, and requiredAction. Do not suggest that Neal applied fixes.',
+    ].join('\n');
+}
+export function buildReviewFindingsReviewPrompt(context, draft, round = 1) {
+    return [
+        '# Neal Review Findings Review',
+        '',
+        `Review findings draft round ${round} for missing important findings, weak evidence, false positives, wrong severity, unclear required actions, and insufficient test or integration analysis.`,
+        '',
+        '## Read-Only Rules',
+        '',
+        ...REVIEW_FINDINGS_READ_ONLY_RULES.map((rule) => `- ${rule}`),
+        '',
+        '## Review Instruction',
+        '',
+        context.instruction,
+        '',
+        '## Review Target',
+        '',
+        renderContextSummary(context),
+        '',
+        '## Draft Findings',
+        '',
+        renderDraftSummary(draft),
+        '',
+        'Return verdict=`accepted` only when the final findings artifact is ready. Return verdict=`revise` with concrete findings when another draft is required. Return verdict=`blocked` only when a safe read-only review cannot be produced. Keep accepted finalMarkdown read-only and artifact-ready. Return empty strings for finalMarkdown or blockedReason when they do not apply.',
+    ].join('\n');
+}
+function renderContextSummary(context) {
+    return [
+        `Selector: ${formatSelector(context.selector)}`,
+        `Resolved range: ${context.externalBaseCommit}..${context.externalHeadCommit}`,
+        'Range stability: frozen at review startup; current HEAD/worktree may move independently.',
+        `Commit count: ${context.externalCommits.length}`,
+        '',
+        'Commits:',
+        ...renderList(context.externalCommitSubjects),
+        '',
+        'Changed files:',
+        ...renderList(context.externalChangedFiles),
+        '',
+        'Diff stat:',
+        context.diffStat.trim() || '(none)',
+        '',
+        'Diff preview:',
+        renderDiffPreview(context.diff),
+    ].join('\n');
+}
+function formatSelector(selector) {
+    switch (selector.kind) {
+        case 'last':
+            return `--last ${selector.count}`;
+        case 'since':
+            return `--since ${selector.baseRef}`;
+    }
+}
+function renderDraftSummary(draft) {
+    if (!draft) {
+        return '(none)';
+    }
+    return [
+        `Summary: ${draft.summary}`,
+        '',
+        'Findings:',
+        ...(draft.findings.length === 0
+            ? ['- (none)']
+            : draft.findings.map((finding, index) => `- F${index + 1} [${finding.severity}] ${finding.claim} Files: ${finding.files.join(', ') || '(none)'} Evidence: ${finding.evidence} Required action: ${finding.requiredAction}`)),
+        '',
+        'Warnings:',
+        ...renderList(draft.warnings ?? []),
+    ].join('\n');
+}
+function renderList(items) {
+    return items.length > 0 ? items.map((item) => `- ${item}`) : ['- (none)'];
+}
+function renderDiffPreview(diff) {
+    if (!diff.trim()) {
+        return '(none)';
+    }
+    if (diff.length <= DIFF_PREVIEW_LIMIT) {
+        return diff;
+    }
+    return `${diff.slice(0, DIFF_PREVIEW_LIMIT).trimEnd()}\n\n[diff truncated to ${DIFF_PREVIEW_LIMIT} characters for review prompt]`;
+}

package/dist/neal/review-findings/provider.js

@@ -0,0 +1,330 @@
+import { getAgentTurnRetryLimit, getAgentTurnStartupTimeoutMs, getApiRetryLimit, getDefaultCoderModel, getDefaultCoderProvider, getDefaultReviewerModel, getDefaultReviewerProvider, getInactivityTimeoutMs, } from '../config.js';
+import { runCoderStructuredPrompt } from '../agents/structured-coder.js';
+import { createInlineSection, getReviewerDoctrineAccessMode, readOnlyReviewerNeedsInlinedDiff, renderInlineReviewerContext, reviewerNeedsInlineContext, } from '../context/inline-review-context.js';
+import { runWithAgentTurnLiveness } from '../providers/liveness.js';
+import { assertProviderSupportsCoder, assertProviderSupportsStructuredAdvisor, getStructuredAdvisorAdapter, } from '../providers/registry.js';
+import { createProviderTelemetrySink } from '../providers/telemetry.js';
+import { buildReviewFindingsInlinedDiffSection, buildReviewFindingsReadOnlyInspectionSection, } from './prompts.js';
+// An accepted (read-only) review must not claim the reviewer mutated code, nor
+// instruct mutating commands. Pattern #1 requires a first-person agency subject
+// ("I/we … applied/made/committed … a fix/change"), so it flags self-attribution
+// without rejecting benign passive descriptions of the coder's change under review
+// (e.g. "the fix was applied and tests pass" — a thing a read-only reviewer may say).
+// The earlier `(fix) (was|has|applied|…)` form false-positived on that passive
+// phrasing, failing otherwise-capable review models. #2-#5 catch explicit commit
+// claims and mutating git/neal command instructions regardless of subject.
+const FORBIDDEN_ACCEPTED_TEXT = [
+    /\b(?:i|we)\s+(?:\w+\s+){0,2}(?:applied|made|wrote|added|introduced|implemented|created|committed)\s+(?:\w+\s+){0,2}(?:fix|fixes|repair|repairs|change|changes|edit|edits|patch|patches|commit|correction)\b/i,
+    /\bcreated\s+(an?\s+)?(additive\s+)?fix\s+commit\b/i,
+    /\bcommitted\s+(the\s+)?fix\b/i,
+    /\b(run|execute|start|invoke|call|use)\s+`?git\s+(commit|reset|rebase|squash|checkout|switch|merge|push)\b/i,
+    /\b(run|execute|start|invoke|call|use)\s+`?neal\s+(execute|run|resume|squash)\b/i,
+];
+class AgentReviewFindingsProviderAdapter {
+    args;
+    constructor(args) {
+        this.args = args;
+        assertReviewAgentCapabilities(args.agentConfig);
+    }
+    async draftFindings(args) {
+        const schema = buildReviewFindingsDraftSchema();
+        const result = await runCoderStructuredPrompt({
+            coder: this.args.agentConfig.coder,
+            cwd: this.args.cwd,
+            prompt: args.prompt,
+            schema,
+            label: 'Review findings draft',
+            structuredJsonProtocol: buildReviewFindingsProtocolSpec({
+                schemaLabel: 'review_findings_draft_payload',
+                schema,
+                validator: validateReviewFindingsDraft,
+            }),
+            logger: this.args.logger,
+        });
+        args.onSessionHandle?.(result.sessionHandle ?? null);
+        return validateReviewFindingsDraft(result.structured);
+    }
+    async reviewDraft(args) {
+        const reviewer = getStructuredAdvisorAdapter(this.args.agentConfig.reviewer);
+        const schema = buildReviewFindingsReviewSchema();
+        // The base adjudication prompt only previews the diff. A reviewer without
+        // repository read access gets the full selected diff and the draft
+        // findings artifact inlined so it can adjudicate entirely from the
+        // prompt. A read-only reviewer (read tools, no shell) that exposes its own
+        // commit-range diff tool gets the read-only range-inspection section
+        // directing it to the git_diff tool with the exact resolved revisions; a
+        // read-only reviewer without a commit-range diff tool (native Claude/Codex)
+        // instead gets the full selected diff inlined and no git_diff-tool
+        // instruction, because it can neither run git commands, call a git_diff
+        // tool, nor rely on the truncated preview. Tool-access reviewers keep the
+        // built prompt byte-identical.
+        const accessMode = getReviewerDoctrineAccessMode(this.args.agentConfig.reviewer);
+        const prompt = reviewerNeedsInlineContext(this.args.agentConfig.reviewer)
+            ? `${args.prompt}\n\n${renderInlineReviewerContext(buildReviewFindingsReviewInlineContext(args))}`
+            : accessMode === 'read-only'
+                ? readOnlyReviewerNeedsInlinedDiff(this.args.agentConfig.reviewer)
+                    ? `${args.prompt}\n\n${buildReviewFindingsInlinedDiffSection(args.context)}`
+                    : `${args.prompt}\n\n${buildReviewFindingsReadOnlyInspectionSection(args.context)}`
+                : args.prompt;
+        const result = await runWithAgentTurnLiveness({
+            provider: this.args.agentConfig.reviewer.provider,
+            role: 'structured-advisor',
+            label: 'review-findings',
+            startupTimeoutMs: Math.min(getAgentTurnStartupTimeoutMs(this.args.cwd), getInactivityTimeoutMs(this.args.cwd)),
+            // Structured-advisor turns retry locally: they are non-writing by policy
+            // and do not resume sessions at this call site.
+            retryLimit: getAgentTurnRetryLimit(this.args.cwd),
+            logger: this.args.logger,
+            baseSink: createProviderTelemetrySink({
+                logger: this.args.logger,
+                provider: this.args.agentConfig.reviewer.provider,
+                role: 'structured-advisor',
+                label: 'review-findings',
+                cwd: this.args.cwd,
+            }),
+            run: (events, attempt) => reviewer.runStructuredRound({
+                label: 'review-findings',
+                cwd: this.args.cwd,
+                prompt,
+                schema,
+                structuredJsonProtocol: buildReviewFindingsProtocolSpec({
+                    schemaLabel: 'review_findings_review_payload',
+                    schema,
+                    validator: validateReviewFindingsReview,
+                }),
+                inactivityTimeoutMs: getInactivityTimeoutMs(this.args.cwd),
+                apiRetryLimit: getApiRetryLimit(this.args.cwd),
+                signal: attempt.signal,
+                events,
+            }),
+        });
+        args.onSessionHandle?.(result.sessionHandle ?? null);
+        return validateReviewFindingsReview(result.structured);
+    }
+}
+function buildReviewFindingsReviewInlineContext(args) {
+    return {
+        sections: [
+            createInlineSection(`Full selected diff for range ${args.context.externalBaseCommit}..${args.context.externalHeadCommit}`, args.context.diff || '(empty diff)'),
+            createInlineSection('Draft findings artifact under adjudication', JSON.stringify(args.draft, null, 2)),
+        ],
+    };
+}
+function buildReviewFindingsProtocolSpec(args) {
+    return {
+        protocol: 'neal-json-block-v1',
+        schemaLabel: args.schemaLabel,
+        schema: args.schema,
+        validator: args.validator,
+        repairAttemptLimit: 2,
+    };
+}
+export function getDefaultReviewAgentConfig(cwd) {
+    return {
+        planner: {
+            provider: getDefaultCoderProvider(cwd),
+            model: getDefaultCoderModel(cwd),
+        },
+        coder: {
+            provider: getDefaultCoderProvider(cwd),
+            model: getDefaultCoderModel(cwd),
+        },
+        reviewer: {
+            provider: getDefaultReviewerProvider(cwd),
+            model: getDefaultReviewerModel(cwd),
+        },
+    };
+}
+export function createAgentReviewFindingsProviderAdapter(args) {
+    return new AgentReviewFindingsProviderAdapter({
+        cwd: args.cwd,
+        agentConfig: args.agentConfig ?? getDefaultReviewAgentConfig(args.cwd),
+        logger: args.logger,
+    });
+}
+function assertReviewAgentCapabilities(agentConfig) {
+    assertProviderSupportsCoder(agentConfig.coder, {
+        role: 'coder',
+        context: 'neal review',
+        reason: 'neal review uses the configured coder provider to inspect the selected committed range and draft structured findings',
+        requireReadToolAccess: true,
+        requireStructuredOutput: true,
+        reasons: {
+            coder_adapter: 'the review findings draft starts through the configured coder adapter',
+            read_tool_access: 'the coder must inspect the selected diff and repository context without editing it',
+            structured_output: 'the review findings draft must be schema-validated before reviewer adjudication',
+            model_override: 'a non-null coder model override is configured for review drafting',
+        },
+    });
+    assertProviderSupportsStructuredAdvisor(agentConfig.reviewer, {
+        role: 'reviewer',
+        context: 'neal review',
+        reason: 'neal review uses the configured reviewer provider to adjudicate and accept or revise the findings artifact',
+        requireReadToolAccessOrInlineReviewerContext: true,
+        requireStructuredOutput: true,
+        reasons: {
+            structured_advisor_adapter: 'review findings adjudication runs through the configured structured-advisor adapter',
+            read_tool_access_or_inline_reviewer_context: 'the reviewer must either inspect the draft, selected diff, and repository context directly with read tools, or support structured output so Neal can inline the draft findings artifact and the full selected diff into the adjudication prompt',
+            structured_output: 'the reviewer verdict must be schema-validated before Neal accepts the findings artifact',
+            model_override: 'a non-null reviewer model override is configured for review adjudication',
+        },
+    });
+}
+function buildReviewFindingSchema() {
+    return {
+        type: 'object',
+        properties: {
+            severity: { type: 'string', enum: ['blocking', 'non_blocking'] },
+            files: { type: 'array', items: { type: 'string' } },
+            claim: { type: 'string' },
+            evidence: { type: 'string' },
+            requiredAction: { type: 'string' },
+        },
+        required: ['severity', 'files', 'claim', 'evidence', 'requiredAction'],
+        additionalProperties: false,
+    };
+}
+function buildReviewFindingsDraftSchema() {
+    return {
+        type: 'object',
+        properties: {
+            summary: { type: 'string' },
+            findings: {
+                type: 'array',
+                items: buildReviewFindingSchema(),
+            },
+            warnings: { type: 'array', items: { type: 'string' } },
+        },
+        required: ['summary', 'findings', 'warnings'],
+        additionalProperties: false,
+    };
+}
+function buildReviewFindingsReviewSchema() {
+    return {
+        type: 'object',
+        properties: {
+            verdict: { type: 'string', enum: ['accepted', 'revise', 'blocked'] },
+            findings: { type: 'array', items: { type: 'string' } },
+            finalMarkdown: { type: 'string' },
+            blockedReason: { type: 'string' },
+            warnings: { type: 'array', items: { type: 'string' } },
+        },
+        required: ['verdict', 'findings', 'finalMarkdown', 'blockedReason', 'warnings'],
+        additionalProperties: false,
+    };
+}
+export function validateReviewFindingsDraft(draft) {
+    if (!draft || typeof draft !== 'object') {
+        throw new Error('Review provider returned an invalid draft object');
+    }
+    const raw = draft;
+    if (typeof raw.summary !== 'string' || raw.summary.trim() === '') {
+        throw new Error('Review provider returned an empty draft summary');
+    }
+    return {
+        summary: raw.summary.trim(),
+        findings: validateFindingItems(raw.findings),
+        warnings: validateStringArray(raw.warnings),
+    };
+}
+export function validateReviewFindingsReview(review) {
+    if (!review || typeof review !== 'object') {
+        throw new Error('Review provider returned an invalid review object');
+    }
+    const raw = review;
+    if (raw.verdict !== 'accepted' && raw.verdict !== 'revise' && raw.verdict !== 'blocked') {
+        throw new Error('Review provider returned an invalid review verdict');
+    }
+    const findings = validateStringArray(raw.findings);
+    if (raw.verdict === 'revise' && findings.length === 0) {
+        throw new Error('Review provider requested review revision without findings');
+    }
+    if (raw.verdict === 'blocked' &&
+        findings.length === 0 &&
+        (typeof raw.blockedReason !== 'string' || raw.blockedReason.trim() === '')) {
+        throw new Error('Review provider blocked without findings or a blocked reason');
+    }
+    const finalMarkdown = typeof raw.finalMarkdown === 'string' && raw.finalMarkdown.trim() !== ''
+        ? raw.finalMarkdown.trim()
+        : undefined;
+    if (finalMarkdown && FORBIDDEN_ACCEPTED_TEXT.some((pattern) => pattern.test(finalMarkdown))) {
+        throw new Error('Review provider returned accepted final markdown with mutation or repair-commit wording');
+    }
+    return {
+        verdict: raw.verdict,
+        findings,
+        finalMarkdown,
+        blockedReason: typeof raw.blockedReason === 'string' && raw.blockedReason.trim() !== ''
+            ? raw.blockedReason.trim()
+            : undefined,
+        warnings: validateStringArray(raw.warnings),
+    };
+}
+export function renderReviewFindingsFinalMarkdown(context, draft, review) {
+    return [
+        '# Review Findings',
+        '',
+        '## Summary',
+        '',
+        draft.summary,
+        '',
+        '## Range',
+        '',
+        `- Base: ${context.externalBaseCommit}`,
+        `- Head: ${context.externalHeadCommit}`,
+        `- Commits: ${context.externalCommits.length}`,
+        '',
+        '## Findings',
+        '',
+        ...formatFindings(draft.findings),
+        '',
+        '## Review Acceptance',
+        '',
+        `- Verdict: ${review.verdict}`,
+        `- Revision findings: ${review.findings.length === 0 ? 'none' : review.findings.join('; ')}`,
+        `- Warnings: ${(review.warnings ?? []).length === 0 ? 'none' : (review.warnings ?? []).join('; ')}`,
+    ].join('\n') + '\n';
+}
+function validateFindingItems(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const findings = [];
+    for (const [index, item] of value.entries()) {
+        if (!item || typeof item !== 'object') {
+            throw new Error(`Review provider returned invalid finding at index ${index}`);
+        }
+        const raw = item;
+        if (raw.severity !== 'blocking' && raw.severity !== 'non_blocking') {
+            throw new Error(`Review provider returned invalid finding severity at index ${index}`);
+        }
+        findings.push({
+            severity: raw.severity,
+            files: validateStringArray(raw.files),
+            claim: typeof raw.claim === 'string' ? raw.claim.trim() : '',
+            evidence: typeof raw.evidence === 'string' ? raw.evidence.trim() : '',
+            requiredAction: typeof raw.requiredAction === 'string' ? raw.requiredAction.trim() : '',
+        });
+    }
+    return findings;
+}
+function validateStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === 'string' && item.trim() !== '').map((item) => item.trim());
+}
+function formatFindings(findings) {
+    if (findings.length === 0) {
+        return ['No findings were identified in the selected range.'];
+    }
+    return findings.flatMap((finding, index) => [
+        `### F${index + 1}: ${finding.claim}`,
+        '',
+        `- Severity: ${finding.severity}`,
+        `- Files: ${finding.files.length === 0 ? '(none)' : finding.files.join(', ')}`,
+        `- Evidence: ${finding.evidence}`,
+        `- Required action: ${finding.requiredAction}`,
+        '',
+    ]);
+}