@navels/neal 0.1.0

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

@@ -0,0 +1,373 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, normalize, resolve } from 'node:path';
+import { REVIEW_FINDINGS_ADJUDICATED_LOOP_CONTRACT, resolveReviewedDraftLoopStep, } from '../adjudicator/contracts.js';
+import { getMaxReviewRounds } from '../config.js';
+import { getDiffForRange, getDiffStatForRange, getWorktreeStatus } from '../git.js';
+import { createRunId, RunLogger } from '../logger.js';
+import { resolveReviewTarget } from '../review-mode.js';
+import { getCurrentPlanAndExecuteQueuePointerPath, getCurrentRunPointerPath, getRunsDir, getRunStatePath, } from '../storage-paths.js';
+import { formatDirtyWorktreeDiagnostic, parseWorktreeStatusLine } from '../worktree-status.js';
+import { formatReviewResumeStdoutLine, getReviewFindingsArtifactPaths, writeReviewFindingsContext, writeReviewFindingsDraft, writeReviewFindingsEvent, writeReviewFindingsFinal, writeReviewFindingsMeta, writeReviewFindingsRequest, writeReviewFindingsReview, writeReviewFindingsRounds, } from './artifacts.js';
+import { createAgentReviewFindingsProviderAdapter, renderReviewFindingsFinalMarkdown, validateReviewFindingsDraft, validateReviewFindingsReview, } from './provider.js';
+import { buildReviewFindingsDraftPrompt, buildReviewFindingsReviewPrompt } from './prompts.js';
+export async function runNealReviewCli(args) {
+    const cwd = resolve(args.cwd);
+    const createdAt = (args.now ?? new Date()).toISOString();
+    const reviewId = args.reviewId ?? createRunId();
+    const paths = getReviewFindingsArtifactPaths(cwd, reviewId);
+    const reviewLogger = args.provider ? undefined : new RunLogger(paths.reviewDir);
+    const provider = args.provider ?? createAgentReviewFindingsProviderAdapter({ cwd, logger: reviewLogger });
+    const maxRounds = Math.max(1, Math.floor(getMaxReviewRounds(cwd)));
+    await reportActivity(args, {
+        activity: 'resolving review target',
+        detailContext: { runId: reviewId, phase: 'review' },
+    });
+    const target = await resolveReviewTarget(cwd, args.parsed);
+    writeReviewStartupDiagnostics(args.stderr, target.externalCommits.length, target.externalBaseCommit, target.externalHeadCommit, args.parsed);
+    await reportActivity(args, {
+        activity: 'building review context',
+        detailContext: { runId: reviewId, phase: 'review' },
+    });
+    const beforeState = await captureProtectedStateSnapshot(cwd);
+    const beforeWorktreeStatus = await captureReviewReadOnlyWorktreeStatus(cwd, reviewId);
+    const context = await buildReviewFindingsContext(cwd, args.parsed, target);
+    let outcome = 'failed';
+    let finalMarkdown = null;
+    const rounds = [];
+    let previousDraft = null;
+    let reviewFindings = [];
+    const buildMeta = (nextOutcome) => ({
+        version: 1,
+        reviewId,
+        createdAt,
+        cwd,
+        instruction: args.parsed.instruction,
+        instructionSource: args.parsed.instructionSource,
+        selector: args.parsed.selector,
+        target,
+        reviewDir: paths.reviewDir,
+        maxRounds,
+        outcome: nextOutcome,
+    });
+    await writeReviewFindingsMeta(paths, buildMeta('failed'));
+    await writeReviewFindingsEvent(paths, 'review.started', {
+        selectorKind: args.parsed.selector.kind,
+        externalBaseCommit: target.externalBaseCommit,
+        externalHeadCommit: target.externalHeadCommit,
+        externalCommitCount: target.externalCommits.length,
+        loopKind: REVIEW_FINDINGS_ADJUDICATED_LOOP_CONTRACT.loopKind,
+        sideEffectPolicy: REVIEW_FINDINGS_ADJUDICATED_LOOP_CONTRACT.sideEffectPolicy,
+        roundCapSource: REVIEW_FINDINGS_ADJUDICATED_LOOP_CONTRACT.roundCap.source,
+        maxRounds,
+    });
+    await writeReviewFindingsContext(paths, context);
+    try {
+        for (let roundNumber = 1; roundNumber <= maxRounds; roundNumber += 1) {
+            await reportActivity(args, {
+                activity: `coder drafting review findings round ${roundNumber}/${maxRounds}`,
+                detailContext: { runId: reviewId, phase: 'review', scopeNumber: roundNumber },
+            });
+            const draftPrompt = buildReviewFindingsDraftPrompt(context, {
+                round: roundNumber,
+                previousDraft,
+                reviewFindings,
+                maxRounds,
+            });
+            let draftSessionHandle = null;
+            const draftResponse = await provider.draftFindings({
+                context,
+                round: roundNumber,
+                previousDraft,
+                reviewFindings,
+                prompt: draftPrompt,
+                onSessionHandle: (handle) => {
+                    draftSessionHandle = handle;
+                },
+            });
+            await assertReviewReadOnlyStateUnchanged(cwd, beforeState);
+            await assertReviewReadOnlyWorktreeUnchanged(cwd, reviewId, beforeWorktreeStatus);
+            const draft = validateReviewFindingsDraft(draftResponse);
+            await writeReviewFindingsEvent(paths, 'review.draft_completed', {
+                round: roundNumber,
+                findingCount: draft.findings.length,
+            });
+            await reportActivity(args, {
+                activity: `reviewer checking review findings round ${roundNumber}/${maxRounds}`,
+                detailContext: { runId: reviewId, phase: 'review', scopeNumber: roundNumber },
+            });
+            const reviewPrompt = buildReviewFindingsReviewPrompt(context, draft, roundNumber);
+            let reviewSessionHandle = null;
+            const reviewResponse = await provider.reviewDraft({
+                context,
+                round: roundNumber,
+                draft,
+                prompt: reviewPrompt,
+                onSessionHandle: (handle) => {
+                    reviewSessionHandle = handle;
+                },
+            });
+            await assertReviewReadOnlyStateUnchanged(cwd, beforeState);
+            await assertReviewReadOnlyWorktreeUnchanged(cwd, reviewId, beforeWorktreeStatus);
+            const review = validateReviewFindingsReview(reviewResponse);
+            const loopRound = {
+                round: roundNumber,
+                draftPrompt,
+                reviewPrompt,
+                draft,
+                review,
+                // Only record handles when captured, so artifacts stay byte-identical
+                // for non-SDK providers.
+                ...(draftSessionHandle ? { draftSessionHandle } : {}),
+                ...(reviewSessionHandle ? { reviewSessionHandle } : {}),
+            };
+            rounds.push(loopRound);
+            await writeReviewFindingsEvent(paths, 'review.review_completed', {
+                round: roundNumber,
+                verdict: review.verdict,
+                findingCount: review.findings.length,
+            });
+            const loopStep = resolveReviewedDraftLoopStep({
+                ownerId: 'review',
+                contract: REVIEW_FINDINGS_ADJUDICATED_LOOP_CONTRACT,
+                verdict: review.verdict,
+                round: roundNumber,
+                maxRounds,
+            });
+            if (loopStep.terminalOutcome === 'accepted') {
+                outcome = loopStep.terminalOutcome;
+                finalMarkdown = review.finalMarkdown ?? renderReviewFindingsFinalMarkdown(context, draft, review);
+                await reportActivity(args, {
+                    activity: 'review findings accepted',
+                    status: 'done',
+                    detailContext: { runId: reviewId, phase: 'review', scopeNumber: roundNumber },
+                });
+                break;
+            }
+            if (loopStep.terminalOutcome) {
+                outcome = loopStep.terminalOutcome;
+                await reportActivity(args, {
+                    activity: `review findings ${loopStep.terminalOutcome}`,
+                    status: loopStep.terminalOutcome === 'blocked' ? 'blocked' : 'failed',
+                    detailContext: { runId: reviewId, phase: 'review', scopeNumber: roundNumber },
+                });
+                break;
+            }
+            previousDraft = draft;
+            reviewFindings = review.findings;
+        }
+        await assertReviewReadOnlyStateUnchanged(cwd, beforeState);
+        await assertReviewReadOnlyWorktreeUnchanged(cwd, reviewId, beforeWorktreeStatus);
+    }
+    catch (error) {
+        outcome = 'failed';
+        await reportActivity(args, {
+            activity: 'review failed',
+            status: 'failed',
+            detailContext: { runId: reviewId, phase: 'review' },
+        });
+        await persistReviewFindingsLoopArtifacts(paths, buildMeta(outcome), {
+            version: 1,
+            outcome,
+            maxRounds,
+            rounds,
+        });
+        await writeReviewFindingsEvent(paths, 'review.failed', {
+            message: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
+    const meta = buildMeta(outcome);
+    const reviewArtifact = {
+        version: 1,
+        outcome,
+        maxRounds,
+        rounds,
+    };
+    await persistReviewFindingsLoopArtifacts(paths, meta, reviewArtifact);
+    if (outcome !== 'accepted' || !finalMarkdown) {
+        await writeReviewFindingsEvent(paths, outcome === 'cap_reached' ? 'review.cap_reached' : 'review.blocked', {
+            roundCount: rounds.length,
+            outcome,
+        });
+        throw new Error(formatUnacceptedReviewError(outcome, paths.reviewDir, rounds));
+    }
+    const acceptedRound = rounds[rounds.length - 1];
+    if (!acceptedRound) {
+        throw new Error(`Review ${reviewId} accepted without a recorded round`);
+    }
+    await writeReviewFindingsFinal(paths, finalMarkdown, acceptedRound, cwd);
+    await writeReviewFindingsEvent(paths, 'review.completed', {
+        finalBytes: Buffer.byteLength(finalMarkdown, 'utf8'),
+        findingCount: acceptedRound.draft.findings.length,
+        roundCount: rounds.length,
+    });
+    const resumeLine = formatReviewResumeStdoutLine(cwd, acceptedRound);
+    args.stdout.write(`${finalMarkdown.trimEnd()}\n\nReview findings accepted: ${paths.final}\n${resumeLine ? `${resumeLine}\n` : ''}`);
+    return {
+        reviewId,
+        paths,
+        meta,
+        context,
+        draft: acceptedRound.draft,
+        review: acceptedRound.review,
+        rounds,
+        outcome,
+        finalMarkdown,
+    };
+}
+async function reportActivity(args, update) {
+    await args.onActivity?.(update);
+}
+async function buildReviewFindingsContext(cwd, parsed, target) {
+    return {
+        version: 1,
+        instruction: parsed.instruction,
+        instructionSource: parsed.instructionSource,
+        selector: parsed.selector,
+        baseRef: target.baseRef,
+        headRef: target.headRef,
+        externalBaseCommit: target.externalBaseCommit,
+        externalHeadCommit: target.externalHeadCommit,
+        externalCommits: target.externalCommits,
+        externalCommitSubjects: target.externalCommitSubjects,
+        externalChangedFiles: target.externalChangedFiles,
+        diffStat: await getDiffStatForRange(cwd, target.externalBaseCommit, target.externalHeadCommit),
+        diff: await getDiffForRange(cwd, target.externalBaseCommit, target.externalHeadCommit),
+    };
+}
+async function persistReviewFindingsLoopArtifacts(paths, meta, reviewArtifact) {
+    await writeReviewFindingsMeta(paths, meta);
+    await writeReviewFindingsRequest(paths, meta, reviewArtifact.rounds);
+    await writeReviewFindingsDraft(paths, reviewArtifact.rounds);
+    await writeReviewFindingsReview(paths, reviewArtifact);
+    await writeReviewFindingsRounds(paths, reviewArtifact);
+}
+function formatUnacceptedReviewError(outcome, reviewDir, rounds) {
+    const latestRound = rounds[rounds.length - 1];
+    const latestReview = latestRound?.review;
+    const detail = latestReview?.blockedReason ??
+        latestReview?.findings.join('; ') ??
+        'The review loop did not produce accepted findings.';
+    if (outcome === 'cap_reached') {
+        return `neal review reached the review round cap without accepted findings. Latest finding: ${detail}. Artifacts: ${reviewDir}`;
+    }
+    if (outcome === 'blocked') {
+        return `neal review was blocked before producing accepted findings. Latest finding: ${detail}. Artifacts: ${reviewDir}`;
+    }
+    return `neal review failed before producing accepted findings. Artifacts: ${reviewDir}`;
+}
+function shortCommit(commit) {
+    return commit.slice(0, 7);
+}
+function formatCommitCount(count) {
+    return `${count} ${count === 1 ? 'commit' : 'commits'}`;
+}
+function writeReviewStartupDiagnostics(stderr, commitCount, baseCommit, headCommit, parsed) {
+    stderr.write(`[neal] review: analyzing ${formatCommitCount(commitCount)}\n`);
+    stderr.write(`[neal] review range: ${shortCommit(baseCommit)}..${shortCommit(headCommit)}\n`);
+    if (parsed.instructionSource === 'default') {
+        stderr.write('[neal] review posture: built-in findings review\n');
+    }
+    else {
+        stderr.write(`[neal] user review context: ${parsed.instruction}\n`);
+    }
+}
+async function captureProtectedStateSnapshot(cwd) {
+    return {
+        currentRunPointer: await readOptionalText(getCurrentRunPointerPath(cwd)),
+        currentQueuePointer: await readOptionalText(getCurrentPlanAndExecuteQueuePointerPath(cwd)),
+        runStates: await readRunStates(cwd),
+    };
+}
+async function assertReviewReadOnlyStateUnchanged(cwd, before) {
+    const after = await captureProtectedStateSnapshot(cwd);
+    if (after.currentRunPointer !== before.currentRunPointer) {
+        throw new Error('neal review is read-only but .neal/current.json changed');
+    }
+    if (after.currentQueuePointer !== before.currentQueuePointer) {
+        throw new Error('neal review is read-only but .neal/current-queue.json changed');
+    }
+    assertSameStringMap(before.runStates, after.runStates, 'run-local RUN_STATE.json files');
+}
+async function captureReviewReadOnlyWorktreeStatus(cwd, reviewId) {
+    return filterReviewArtifactWorktreeStatus(await getWorktreeStatus(cwd, { untrackedFiles: 'all' }), reviewId);
+}
+async function assertReviewReadOnlyWorktreeUnchanged(cwd, reviewId, beforeStatus) {
+    const afterStatus = await captureReviewReadOnlyWorktreeStatus(cwd, reviewId);
+    if (afterStatus === beforeStatus) {
+        return;
+    }
+    const scratchDiagnostic = formatDirtyWorktreeDiagnostic({ statusOutput: afterStatus });
+    throw new Error([
+        'neal review is read-only but the worktree changed outside its review artifacts:',
+        'Before:',
+        beforeStatus || '(clean)',
+        'After:',
+        afterStatus || '(clean)',
+        scratchDiagnostic,
+    ].filter(Boolean).join('\n'));
+}
+function filterReviewArtifactWorktreeStatus(statusOutput, reviewId) {
+    return statusOutput
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter(Boolean)
+        .filter((line) => {
+        const paths = parseWorktreeStatusLine(line)?.paths ?? [];
+        return paths.length === 0 || paths.some((path) => !isReviewArtifactPath(path, reviewId));
+    })
+        .join('\n');
+}
+function isReviewArtifactPath(path, reviewId) {
+    const normalized = normalize(path).replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+    const reviewPrefix = `.neal/reviews/${reviewId}`;
+    return normalized === reviewPrefix || normalized.startsWith(`${reviewPrefix}/`);
+}
+async function readOptionalText(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+async function readRunStates(cwd) {
+    const runsDir = getRunsDir(cwd);
+    let entries;
+    try {
+        entries = await readdir(runsDir);
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return {};
+        }
+        throw error;
+    }
+    const states = {};
+    for (const entry of entries.sort()) {
+        const statePath = getRunStatePath(join(runsDir, entry));
+        const content = await readOptionalText(statePath);
+        if (content !== null) {
+            states[entry] = content;
+        }
+    }
+    return states;
+}
+function assertSameStringMap(before, after, label) {
+    const beforeKeys = Object.keys(before).sort();
+    const afterKeys = Object.keys(after).sort();
+    if (beforeKeys.join('\n') !== afterKeys.join('\n')) {
+        throw new Error(`neal review is read-only but ${label} changed`);
+    }
+    for (const key of beforeKeys) {
+        if (before[key] !== after[key]) {
+            throw new Error(`neal review is read-only but ${label} changed for ${key}`);
+        }
+    }
+}
+function isMissingFileError(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/neal/review-mode.js

@@ -0,0 +1,67 @@
+import { getChangedFilesForRange, getCommitRange, getCommitSubjects, getHeadCommit, isAncestorCommit, resolveCommitRef, } from './git.js';
+function shortCommit(commit) {
+    return commit.slice(0, 7);
+}
+function getSelectorRefs(selector) {
+    switch (selector.kind) {
+        case 'last':
+            return {
+                baseRef: `HEAD~${selector.count}`,
+                headRef: 'HEAD',
+            };
+        case 'since':
+            return {
+                baseRef: selector.baseRef,
+                headRef: 'HEAD',
+            };
+    }
+}
+async function resolveReviewCommitRef(cwd, label, ref) {
+    try {
+        return await resolveCommitRef(cwd, ref);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Unable to resolve review ${label} ref "${ref}" to a commit: ${detail}`);
+    }
+}
+export async function assertReviewExternalCommitsReproducible(args) {
+    const actualCommits = await getCommitRange(args.cwd, args.externalBaseCommit, args.externalHeadCommit);
+    if (actualCommits.length !== args.externalCommits.length ||
+        actualCommits.some((commit, index) => commit !== args.externalCommits[index])) {
+        throw new Error('neal review external commit list no longer matches the resolved base..head range');
+    }
+}
+export async function resolveReviewTarget(cwd, parsed) {
+    const { baseRef, headRef } = getSelectorRefs(parsed.selector);
+    const externalBaseCommit = await resolveReviewCommitRef(cwd, 'base', baseRef);
+    const externalHeadCommit = await resolveReviewCommitRef(cwd, 'head', headRef);
+    const currentHeadCommit = await getHeadCommit(cwd);
+    if (externalHeadCommit !== currentHeadCommit) {
+        throw new Error(`neal review requires the selected head to be the current checkout HEAD in v1: selected ${shortCommit(externalHeadCommit)}, current ${shortCommit(currentHeadCommit)}`);
+    }
+    const baseIsAncestor = await isAncestorCommit(cwd, externalBaseCommit, externalHeadCommit);
+    if (!baseIsAncestor) {
+        throw new Error(`neal review requires the selected base to be an ancestor of the selected head: ${shortCommit(externalBaseCommit)} is not an ancestor of ${shortCommit(externalHeadCommit)}`);
+    }
+    const externalCommits = await getCommitRange(cwd, externalBaseCommit, externalHeadCommit);
+    if (externalCommits.length === 0) {
+        throw new Error('neal review requires at least one commit in the selected range');
+    }
+    await assertReviewExternalCommitsReproducible({
+        cwd,
+        externalBaseCommit,
+        externalHeadCommit,
+        externalCommits,
+    });
+    return {
+        selector: parsed.selector,
+        baseRef,
+        headRef,
+        externalBaseCommit,
+        externalHeadCommit,
+        externalCommits,
+        externalCommitSubjects: await getCommitSubjects(cwd, externalCommits),
+        externalChangedFiles: await getChangedFilesForRange(cwd, externalBaseCommit, externalHeadCommit),
+    };
+}

package/dist/neal/review.js

@@ -0,0 +1,137 @@
+import { join } from 'node:path';
+import { writeTextAtomic } from './atomic-write.js';
+import { renderAdjudicationContractLines } from './adjudicator/artifacts.js';
+import { formatPublicPhase } from './phase-display.js';
+import { getCurrentScopeLabel, getExecutionPlanPath, getExecutionPlanScopeCountForShape, getParentScopeLabel, renderRecentAcceptedScopesSummary, renderScopeProgressSummary, } from './scopes.js';
+import { getDerivedPlanView, getFinalCompletionView } from './state-views.js';
+function getDiscardedDiffPath(state) {
+    if (!getDerivedPlanView(state)) {
+        return null;
+    }
+    return join(state.runDir, `SCOPE_${state.currentScopeNumber}_DISCARDED.diff`);
+}
+function getReviewTarget(state) {
+    const derivedPlan = getDerivedPlanView(state);
+    if (derivedPlan) {
+        return {
+            path: derivedPlan.path,
+            label: 'derived plan',
+        };
+    }
+    return {
+        path: getExecutionPlanPath(state),
+        label: 'plan document',
+    };
+}
+export function renderReviewMarkdown(state) {
+    const reviewTarget = getReviewTarget(state);
+    const derivedPlan = getDerivedPlanView(state);
+    const finalCompletion = getFinalCompletionView(state);
+    const lastReviewedPlanPath = state.rounds.at(-1)?.reviewedPlanPath ?? null;
+    const parentScopeLabel = state.topLevelMode === 'execute' ? getParentScopeLabel(state) : null;
+    const lines = [
+        '# Review Session',
+        '',
+        '## Metadata',
+        `- Plan: ${state.planDoc}`,
+        `- Review target: ${reviewTarget.path}`,
+        `- Review target kind: ${reviewTarget.label}`,
+        `- Last reviewed artifact: ${lastReviewedPlanPath ?? 'pending'}`,
+        `- Scope: ${getCurrentScopeLabel(state)}`,
+        `- Scope progress: ${renderScopeProgressSummary(state, getExecutionPlanScopeCountForShape(state.executionShape))}`,
+        `- Current step: ${formatPublicPhase(state.phase)}`,
+        `- Execution shape: ${state.executionShape ?? 'pending'}`,
+        `- Coder session: ${state.coderSessionHandle ?? 'pending'}`,
+        `- Base commit: ${state.baseCommit ?? 'unknown'}`,
+        `- Final commit: ${state.finalCommit ?? 'pending'}`,
+        `- Last marker: ${state.lastScopeMarker ?? 'pending'}`,
+        `- Derived plan: ${derivedPlan?.path ?? 'none'}`,
+        `- Derived plan status: ${derivedPlan?.status ?? 'none'}`,
+        `- Derived from scope: ${derivedPlan?.parentScopeNumber ?? 'none'}`,
+        `- Discarded WIP artifact: ${getDiscardedDiffPath(state) ?? 'none'}`,
+    ];
+    if (state.topLevelMode === 'execute') {
+        lines.push('', '## Meaningful Progress', `- Active parent objective: ${parentScopeLabel ?? 'none'}`);
+        if (state.currentScopeProgressJustification) {
+            lines.push(`- Coder milestone: ${state.currentScopeProgressJustification.milestoneTargeted}`, `- New evidence: ${state.currentScopeProgressJustification.newEvidence}`, `- Why not redundant: ${state.currentScopeProgressJustification.whyNotRedundant}`, `- Next step unlocked: ${state.currentScopeProgressJustification.nextStepUnlocked}`);
+        }
+        else {
+            lines.push('- Coder justification: pending');
+        }
+        if (state.currentScopeMeaningfulProgressVerdict) {
+            lines.push(`- Reviewer action: ${state.currentScopeMeaningfulProgressVerdict.action}`, `- Reviewer rationale: ${state.currentScopeMeaningfulProgressVerdict.rationale}`);
+        }
+        else {
+            lines.push('- Reviewer action: pending', '- Reviewer rationale: pending');
+        }
+        lines.push('', '### Recent Accepted Scope History');
+        for (const line of renderRecentAcceptedScopesSummary(state, parentScopeLabel ?? String(state.currentScopeNumber)).split('\n')) {
+            lines.push(line);
+        }
+    }
+    const latestCompletedScope = state.completedScopes.at(-1) ?? null;
+    if (latestCompletedScope) {
+        lines.push('', '## Latest Completed Scope', `- Scope: ${latestCompletedScope.number}`, `- Result: ${latestCompletedScope.result}`, `- Summary: ${latestCompletedScope.summary ?? 'none'}`, `- Commit subject: ${latestCompletedScope.commitSubject ?? 'pending'}`, `- Replaced by derived plan: ${latestCompletedScope.replacedByDerivedPlanPath ?? 'none'}`);
+    }
+    const contractLines = renderAdjudicationContractLines(state);
+    if (contractLines.length > 0) {
+        lines.push('', ...contractLines);
+    }
+    if (finalCompletion?.summary) {
+        lines.push('', '## Final Completion Summary', `- Plan goal satisfied: ${finalCompletion.summary.planGoalSatisfied ? 'yes' : 'no'}`, `- What changed overall: ${finalCompletion.summary.whatChangedOverall}`, `- Verification summary: ${finalCompletion.summary.verificationSummary}`);
+        if (finalCompletion.summary.remainingKnownGaps.length > 0) {
+            lines.push('- Remaining known gaps:');
+            for (const gap of finalCompletion.summary.remainingKnownGaps) {
+                lines.push(`  - ${gap}`);
+            }
+        }
+        else {
+            lines.push('- Remaining known gaps: none');
+        }
+    }
+    if (finalCompletion?.reviewVerdict) {
+        lines.push('', '## Final Completion Review', `- Reviewer action: ${finalCompletion.reviewVerdict.action}`, `- Resulting action: ${finalCompletion.effectiveAction ?? finalCompletion.reviewVerdict.action}`, `- Reviewer summary: ${finalCompletion.reviewVerdict.summary}`, `- Reviewer rationale: ${finalCompletion.reviewVerdict.rationale}`, `- Continue-execution cycles used: ${finalCompletion.continueExecutionCount}`, `- Continue-execution cap reached: ${finalCompletion.continueExecutionCapReached ? 'yes' : 'no'}`);
+        if (finalCompletion.reviewVerdict.missingWork) {
+            lines.push(`- Missing work summary: ${finalCompletion.reviewVerdict.missingWork.summary}`, `- Missing work required outcome: ${finalCompletion.reviewVerdict.missingWork.requiredOutcome}`, `- Missing work verification: ${finalCompletion.reviewVerdict.missingWork.verification}`);
+        }
+        else {
+            lines.push('- Missing work: none');
+        }
+    }
+    lines.push('', '## Review Rounds');
+    if (state.rounds.length === 0) {
+        lines.push('', 'No review rounds yet.');
+    }
+    else {
+        for (const round of state.rounds) {
+            const normalizationStatus = round.normalizationApplied
+                ? round.normalizationOperations.length > 0
+                    ? round.normalizationOperations.join(' | ')
+                    : 'applied'
+                : 'none';
+            const scopeMappings = round.normalizationScopeLabelMappings.length > 0
+                ? round.normalizationScopeLabelMappings
+                    .map((mapping) => `${mapping.originalScopeLabel} -> ${mapping.normalizedScopeNumber}`)
+                    .join(', ')
+                : 'none';
+            lines.push('', `### Round ${round.round}`, `- Reviewed artifact: ${round.reviewedPlanPath ?? 'unknown'}`, `- Normalization: ${normalizationStatus}`, `- Scope label mappings: ${scopeMappings}`, `- Reviewer session: ${round.reviewerSessionHandle ?? 'pending'}`, `- Open blocking canonicals: ${round.openBlockingCanonicalCount}`, `- Findings: ${round.findings.join(', ') || 'none'}`);
+        }
+    }
+    lines.push('', '## Findings');
+    if (state.findings.length === 0) {
+        lines.push('', 'No findings yet.');
+    }
+    else {
+        const rounds = [...new Set(state.findings.map((finding) => finding.round))].sort((a, b) => a - b);
+        for (const round of rounds) {
+            lines.push('', `## Round ${round} Findings`);
+            for (const finding of state.findings.filter((item) => item.round === round)) {
+                lines.push('', `### ${finding.id}`, `- Canonical ID: ${finding.canonicalId}`, `- Source: ${finding.source}`, `- Severity: ${finding.severity}`, `- Status: ${finding.status}`, `- Files: ${finding.files.join(', ') || 'n/a'}`, `- Claim: ${finding.claim}`, `- Evidence: ${finding.evidence?.trim() || 'n/a'}`, `- Required action: ${finding.requiredAction}`, `- Round summary: ${finding.roundSummary}`, `- Coder disposition: ${finding.coderDisposition ?? 'pending'}`, `- Coder commit: ${finding.coderCommit ?? 'pending'}`);
+            }
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+export async function writeReviewMarkdown(path, state) {
+    await writeTextAtomic(path, renderReviewMarkdown(state));
+}