@navels/neal 0.1.0

package/dist/neal/context/reviewer-context.js

@@ -0,0 +1,166 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { getFinalCompletionView } from '../state-views.js';
+export const REVIEWER_CONTEXT_JSON = 'REVIEWER_CONTEXT.json';
+export const REVIEWER_CONTEXT_MARKDOWN = 'REVIEWER_CONTEXT.md';
+const COMPLETED_SCOPE_LIMIT = 12;
+const FINDING_LIMIT = 24;
+export async function buildAndPersistReviewerContextPacket(args) {
+    const packet = buildReviewerContextPacket(args);
+    await mkdir(args.state.runDir, { recursive: true });
+    await writeFile(join(args.state.runDir, REVIEWER_CONTEXT_JSON), JSON.stringify(withoutPromptMarkdown(packet), null, 2) + '\n');
+    await writeFile(join(args.state.runDir, REVIEWER_CONTEXT_MARKDOWN), packet.promptMarkdown + '\n');
+    return packet;
+}
+export function buildReviewerContextPacket(args) {
+    const { state } = args;
+    const createdAt = (args.now ?? new Date()).toISOString();
+    const completedScopeCount = state.completedScopes.length;
+    const findingCount = state.findings.length;
+    const completedScopes = state.completedScopes.slice(-COMPLETED_SCOPE_LIMIT).map((scope) => ({
+        number: scope.number,
+        result: scope.result,
+        marker: scope.marker,
+        finalCommit: scope.finalCommit,
+        summary: scope.summary ?? null,
+        reviewRounds: scope.reviewRounds,
+        findings: scope.findings,
+        residualReviewDebt: scope.residualReviewDebt?.length ?? 0,
+    }));
+    const findings = state.findings.slice(-FINDING_LIMIT).map((finding) => ({
+        canonicalId: finding.canonicalId,
+        id: finding.id,
+        severity: finding.severity,
+        status: finding.status,
+        source: finding.source,
+        files: finding.files,
+        claim: finding.claim,
+        requiredAction: finding.requiredAction,
+    }));
+    const finalCompletion = summarizeFinalCompletion(state);
+    const packetWithoutMarkdown = {
+        version: 1,
+        createdAt,
+        purpose: 'reviewer_continuity',
+        run: {
+            id: runIdFromDir(state.runDir),
+            cwd: state.cwd,
+            runDir: toDisplayPath(state.cwd, state.runDir),
+            planDoc: state.planDoc,
+            topLevelMode: state.topLevelMode,
+            executionShape: state.executionShape,
+            phase: state.phase,
+            status: state.status,
+            currentScopeNumber: state.currentScopeNumber,
+        },
+        completedScopes,
+        findings,
+        finalCompletion,
+        citations: buildReviewerContextCitations(state),
+        limits: {
+            completedScopeLimit: COMPLETED_SCOPE_LIMIT,
+            completedScopeCount,
+            findingLimit: FINDING_LIMIT,
+            findingCount,
+            truncatedCompletedScopes: completedScopeCount > completedScopes.length,
+            truncatedFindings: findingCount > findings.length,
+        },
+    };
+    return {
+        ...packetWithoutMarkdown,
+        promptMarkdown: renderReviewerContextMarkdown(packetWithoutMarkdown),
+    };
+}
+function withoutPromptMarkdown(packet) {
+    const { promptMarkdown: _promptMarkdown, ...json } = packet;
+    return json;
+}
+function summarizeFinalCompletion(state) {
+    const view = getFinalCompletionView(state);
+    if (!view) {
+        return null;
+    }
+    return {
+        state: view.state,
+        effectiveAction: view.effectiveAction,
+        hasSummary: view.hasSummary,
+        hasReviewVerdict: view.hasReviewVerdict,
+        continueExecutionCount: view.continueExecutionCount,
+        continueExecutionCapReached: view.continueExecutionCapReached,
+    };
+}
+function buildReviewerContextCitations(state) {
+    return [
+        { label: 'RUN_STATE.json', path: toDisplayPath(state.cwd, join(state.runDir, 'RUN_STATE.json')) },
+        { label: 'PLAN_PROGRESS.md', path: toDisplayPath(state.cwd, state.progressMarkdownPath) },
+        { label: 'plan-progress.json', path: toDisplayPath(state.cwd, state.progressJsonPath) },
+        { label: 'REVIEW.md', path: toDisplayPath(state.cwd, state.reviewMarkdownPath) },
+        { label: 'RECOVERY.md', path: toDisplayPath(state.cwd, state.recoveryMarkdownPath) },
+        { label: REVIEWER_CONTEXT_JSON, path: toDisplayPath(state.cwd, join(state.runDir, REVIEWER_CONTEXT_JSON)) },
+        { label: REVIEWER_CONTEXT_MARKDOWN, path: toDisplayPath(state.cwd, join(state.runDir, REVIEWER_CONTEXT_MARKDOWN)) },
+    ];
+}
+export function renderReviewerContextMarkdown(packet, options = {}) {
+    const mode = options.mode ?? 'tool-access';
+    const scopeLines = packet.completedScopes.length
+        ? packet.completedScopes.map((scope) => `- Scope ${scope.number}: ${scope.result}; marker=${scope.marker}; finalCommit=${scope.finalCommit ?? 'none'}; reviewRounds=${scope.reviewRounds}; findings=${scope.findings}; residualDebt=${scope.residualReviewDebt}; summary=${scope.summary ?? 'none'}`)
+        : ['- none'];
+    const findingLines = packet.findings.length
+        ? packet.findings.map((finding) => `- ${finding.canonicalId} (${finding.id}): ${finding.severity}/${finding.status}; source=${finding.source}; files=${finding.files.join(', ') || 'none'}; claim=${finding.claim}; requiredAction=${finding.requiredAction}`)
+        : ['- none'];
+    const finalCompletion = packet.finalCompletion;
+    return [
+        '# Reviewer Continuity Context',
+        '',
+        mode === 'inline'
+            ? 'Use this bounded Neal-owned context for continuity only. All required review context is inlined into this prompt; you have no access to the cited run artifacts or the checkout.'
+            : 'Use this bounded Neal-owned context for continuity only. Inspect cited artifacts or repository state directly before making findings.',
+        '',
+        '## Run',
+        `- id: ${packet.run.id}`,
+        `- plan: ${packet.run.planDoc}`,
+        `- mode: ${packet.run.topLevelMode}`,
+        `- executionShape: ${packet.run.executionShape ?? 'pending'}`,
+        `- phase: ${packet.run.phase}`,
+        `- status: ${packet.run.status}`,
+        `- currentScope: ${packet.run.currentScopeNumber}`,
+        '',
+        '## Completed Scopes',
+        ...scopeLines,
+        packet.limits.truncatedCompletedScopes
+            ? `- truncated: showing latest ${packet.completedScopes.length} of ${packet.limits.completedScopeCount}`
+            : '- truncated: no',
+        '',
+        '## Findings',
+        ...findingLines,
+        packet.limits.truncatedFindings
+            ? `- truncated: showing latest ${packet.findings.length} of ${packet.limits.findingCount}`
+            : '- truncated: no',
+        '',
+        '## Final Completion',
+        finalCompletion
+            ? `- state=${finalCompletion.state}; effectiveAction=${finalCompletion.effectiveAction ?? 'none'}; hasSummary=${finalCompletion.hasSummary}; hasReviewVerdict=${finalCompletion.hasReviewVerdict}; continueExecutionCount=${finalCompletion.continueExecutionCount}; capReached=${finalCompletion.continueExecutionCapReached}`
+            : '- not applicable',
+        // Citation paths are reading instructions; a no-read reviewer cannot
+        // follow them, so the inline rendering omits the section entirely.
+        ...(mode === 'inline'
+            ? []
+            : [
+                '',
+                '## Citations',
+                ...packet.citations.map((citation) => `- ${citation.label}: ${citation.path}`),
+            ]),
+    ].join('\n');
+}
+function runIdFromDir(runDir) {
+    const normalized = runDir.replace(/\/+$/, '');
+    return normalized.slice(normalized.lastIndexOf('/') + 1);
+}
+function toDisplayPath(cwd, path) {
+    const absolutePath = resolve(path);
+    const relativePath = relative(cwd, absolutePath);
+    if (!relativePath.startsWith('..') && !isAbsolute(relativePath)) {
+        return relativePath || '.';
+    }
+    return absolutePath;
+}

package/dist/neal/context/shared.js

@@ -0,0 +1,117 @@
+export const SUPPORTED_NEAL_ACTION_TYPES = [
+    'inspect_artifact',
+    'start_plan_refinement',
+    'start_execution',
+    'pause_after_scope',
+    'recover',
+    'resume',
+    'squash',
+];
+export function isSupportedNealActionType(value) {
+    return SUPPORTED_NEAL_ACTION_TYPES.includes(value);
+}
+const RUN_SCOPED_ACTION_TYPES = new Set([
+    'inspect_artifact',
+    'pause_after_scope',
+    'recover',
+    'resume',
+    'squash',
+]);
+const PLAN_SCOPED_ACTION_TYPES = new Set([
+    'start_plan_refinement',
+    'start_execution',
+]);
+const IMPLICIT_RUN_TARGETS = new Set(['latest', 'current']);
+const TARGET_STRING_FIELDS = ['runDirName', 'statePath', 'planPath', 'artifactLabel'];
+const ACTION_FIELDS = ['type', 'label', 'target', 'rationale'];
+export function validateSuggestedNealAction(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('suggestion must be an object');
+    }
+    if (containsForbiddenCommandKey(value)) {
+        throw new Error('forbidden command payload');
+    }
+    for (const key of Object.keys(value)) {
+        if (!ACTION_FIELDS.includes(key)) {
+            throw new Error(`unsupported action field "${key}"`);
+        }
+    }
+    const action = value;
+    if (typeof action.type !== 'string' ||
+        !isSupportedNealActionType(action.type) ||
+        typeof action.label !== 'string' ||
+        action.label.trim() === '' ||
+        !action.target ||
+        typeof action.target !== 'object') {
+        throw new Error('invalid action shape');
+    }
+    const target = validateNealActionTarget(action.type, action.target);
+    return {
+        type: action.type,
+        label: action.label.trim(),
+        target,
+        ...(typeof action.rationale === 'string' && action.rationale.trim() ? { rationale: action.rationale.trim() } : {}),
+    };
+}
+function validateNealActionTarget(type, value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('target must be an object');
+    }
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (!TARGET_STRING_FIELDS.includes(key)) {
+            throw new Error(`unsupported target field "${key}"`);
+        }
+    }
+    const target = {};
+    for (const key of TARGET_STRING_FIELDS) {
+        const rawValue = record[key];
+        if (rawValue === undefined) {
+            continue;
+        }
+        if (typeof rawValue !== 'string' || rawValue.trim() === '') {
+            throw new Error(`target.${key} must be a non-empty string`);
+        }
+        target[key] = rawValue.trim();
+    }
+    if (target.runDirName) {
+        validateRunDirName(target.runDirName);
+    }
+    if (target.statePath) {
+        validateStatePath(target.statePath);
+    }
+    if (RUN_SCOPED_ACTION_TYPES.has(type) && !target.runDirName && !target.statePath) {
+        throw new Error('run-scoped action target must include runDirName or exact statePath');
+    }
+    if (PLAN_SCOPED_ACTION_TYPES.has(type) && !target.planPath) {
+        throw new Error('plan-scoped action target must include planPath');
+    }
+    if (type === 'inspect_artifact' && !target.artifactLabel) {
+        throw new Error('inspect_artifact target must include artifactLabel');
+    }
+    return target;
+}
+function validateRunDirName(runDirName) {
+    const normalized = runDirName.trim().toLowerCase();
+    if (IMPLICIT_RUN_TARGETS.has(normalized) || runDirName.includes('/') || runDirName.includes('\\') || runDirName.includes('..')) {
+        throw new Error('runDirName must name an explicit run directory');
+    }
+}
+function validateStatePath(statePath) {
+    const normalized = statePath.trim().replace(/\\/g, '/').toLowerCase();
+    if (IMPLICIT_RUN_TARGETS.has(normalized)) {
+        throw new Error('statePath must not target an implicit run pointer');
+    }
+    if (!normalized.endsWith('/run_state.json') && normalized !== 'run_state.json') {
+        throw new Error('statePath must target an exact RUN_STATE.json');
+    }
+}
+function containsForbiddenCommandKey(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    if (Object.hasOwn(value, 'command')) {
+        return true;
+    }
+    return Object.values(value).some((child) => containsForbiddenCommandKey(child));
+}

package/dist/neal/context/types.js

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

package/dist/neal/diagnostic.js

@@ -0,0 +1,208 @@
+const DETAIL_BUFFER_ENTRY_LIMIT = 400;
+const DETAIL_BUFFER_BYTE_LIMIT = 128 * 1024;
+const NARRATIVE_BUFFER_ENTRY_LIMIT = 400;
+const NARRATIVE_BUFFER_BYTE_LIMIT = 128 * 1024;
+let statusFooter = null;
+let activeView = 'narrative';
+let activeDetailContext = {};
+let bufferedNarrativeEntries = [];
+let bufferedNarrativeBytes = 0;
+let droppedNarrativeEntries = 0;
+let droppedNarrativeBytes = 0;
+let bufferedDetailEntries = [];
+let bufferedDetailBytes = 0;
+let droppedDetailEntries = 0;
+let droppedDetailBytes = 0;
+export function configureDiagnosticFooter(footer) {
+    statusFooter?.dispose();
+    statusFooter = footer;
+}
+export function clearDiagnosticFooter() {
+    statusFooter?.dispose();
+    statusFooter = null;
+}
+export function setDiagnosticDetailContext(context) {
+    activeDetailContext = {
+        ...activeDetailContext,
+        ...context,
+    };
+}
+export function resetDiagnosticDetailState(context = {}) {
+    activeView = 'narrative';
+    activeDetailContext = { ...context };
+    bufferedNarrativeEntries = [];
+    bufferedNarrativeBytes = 0;
+    droppedNarrativeEntries = 0;
+    droppedNarrativeBytes = 0;
+    bufferedDetailEntries = [];
+    bufferedDetailBytes = 0;
+    droppedDetailEntries = 0;
+    droppedDetailBytes = 0;
+}
+export function setDiagnosticDetailVisibility(visible) {
+    activeView = visible ? 'detail' : 'narrative';
+}
+export function isDiagnosticDetailVisible() {
+    return activeView === 'detail';
+}
+export function getBufferedNarrativeSnapshot() {
+    return {
+        entries: [...bufferedNarrativeEntries],
+        droppedEntries: droppedNarrativeEntries,
+        droppedBytes: droppedNarrativeBytes,
+    };
+}
+export function getBufferedDetailSnapshot(filter = {}) {
+    return {
+        entries: bufferedDetailEntries.filter((entry) => matchesDetailFilter(entry.context, filter)),
+        droppedEntries: droppedDetailEntries,
+        droppedBytes: droppedDetailBytes,
+    };
+}
+export function writeBufferedDetail(filter = {}) {
+    const transcript = renderDetailTranscript(filter);
+    if (transcript !== '') {
+        writeTerminalDiagnostic(transcript);
+    }
+}
+export function showDiagnosticDetailView(filter = {}) {
+    activeView = 'detail';
+    const transcript = renderDetailTranscript(filter);
+    if (canReplaceManagedView()) {
+        statusFooter.replaceView(transcript);
+        return;
+    }
+    if (transcript !== '') {
+        writeTerminalDiagnostic(transcript);
+    }
+}
+export function showDiagnosticNarrativeView() {
+    activeView = 'narrative';
+    if (canReplaceManagedView()) {
+        statusFooter.replaceView(renderNarrativeTranscript());
+    }
+}
+export function writeNarrative(message, logger) {
+    bufferNarrative(message);
+    if (activeView === 'narrative' || !isManagedDiagnosticView()) {
+        writeTerminalDiagnostic(message);
+    }
+    void logger?.stderr(message);
+}
+export function writeDetail(message, logger, context = {}) {
+    bufferDetail(message, context);
+    if (activeView === 'detail') {
+        writeTerminalDiagnostic(message);
+    }
+    void logger?.stderr(message);
+}
+export function writeErrorDetail(message, logger, context = {}) {
+    writeDetail(message, logger, context);
+}
+export function writeDiagnostic(message, logger) {
+    writeNarrative(message, logger);
+}
+export function resetDiagnosticStateForTests() {
+    clearDiagnosticFooter();
+    resetDiagnosticDetailState();
+}
+function writeTerminalDiagnostic(message) {
+    if (statusFooter) {
+        statusFooter.write(message);
+    }
+    else {
+        process.stderr.write(message);
+    }
+}
+function isManagedDiagnosticView() {
+    return statusFooter?.isEnabled?.() === true;
+}
+function canReplaceManagedView() {
+    return isManagedDiagnosticView() && typeof statusFooter?.replaceView === 'function';
+}
+function renderNarrativeTranscript() {
+    const snapshot = getBufferedNarrativeSnapshot();
+    const transcript = [];
+    if (snapshot.droppedEntries > 0 || snapshot.droppedBytes > 0) {
+        transcript.push(`[neal] earlier narrative omitted from buffer (${snapshot.droppedEntries} entries, ${snapshot.droppedBytes} bytes)\n`);
+    }
+    for (const entry of snapshot.entries) {
+        transcript.push(entry.message);
+    }
+    return transcript.join('');
+}
+function renderDetailTranscript(filter) {
+    const snapshot = getBufferedDetailSnapshot(filter);
+    const transcript = [];
+    if (snapshot.droppedEntries > 0 || snapshot.droppedBytes > 0) {
+        transcript.push(`[neal:detail] earlier detail omitted from buffer (${snapshot.droppedEntries} entries, ${snapshot.droppedBytes} bytes)\n`);
+    }
+    for (const entry of snapshot.entries) {
+        transcript.push(entry.message);
+    }
+    return transcript.join('');
+}
+function bufferNarrative(message) {
+    const entry = {
+        message,
+        timestamp: new Date().toISOString(),
+        bytes: Buffer.byteLength(message, 'utf8'),
+    };
+    bufferedNarrativeEntries.push(entry);
+    bufferedNarrativeBytes += entry.bytes;
+    trimNarrativeBuffer();
+}
+function trimNarrativeBuffer() {
+    while (bufferedNarrativeEntries.length > NARRATIVE_BUFFER_ENTRY_LIMIT ||
+        bufferedNarrativeBytes > NARRATIVE_BUFFER_BYTE_LIMIT) {
+        const [dropped] = bufferedNarrativeEntries.splice(0, 1);
+        if (!dropped) {
+            return;
+        }
+        bufferedNarrativeBytes -= dropped.bytes;
+        droppedNarrativeEntries += 1;
+        droppedNarrativeBytes += dropped.bytes;
+    }
+}
+function bufferDetail(message, context) {
+    const entryContext = {
+        ...activeDetailContext,
+        ...context,
+        timestamp: context.timestamp ?? activeDetailContext.timestamp ?? new Date().toISOString(),
+    };
+    const entry = {
+        message,
+        context: entryContext,
+        bytes: Buffer.byteLength(message, 'utf8'),
+    };
+    bufferedDetailEntries.push(entry);
+    bufferedDetailBytes += entry.bytes;
+    trimDetailBuffer();
+}
+function trimDetailBuffer() {
+    while (bufferedDetailEntries.length > DETAIL_BUFFER_ENTRY_LIMIT ||
+        bufferedDetailBytes > DETAIL_BUFFER_BYTE_LIMIT) {
+        const [dropped] = bufferedDetailEntries.splice(0, 1);
+        if (!dropped) {
+            return;
+        }
+        bufferedDetailBytes -= dropped.bytes;
+        droppedDetailEntries += 1;
+        droppedDetailBytes += dropped.bytes;
+    }
+}
+function matchesDetailFilter(context, filter) {
+    if (filter.runId !== undefined && context.runId !== filter.runId) {
+        return false;
+    }
+    if (filter.phase !== undefined && context.phase !== filter.phase) {
+        return false;
+    }
+    if (filter.scopeLabel !== undefined && context.scopeLabel !== filter.scopeLabel) {
+        return false;
+    }
+    if (filter.scopeNumber !== undefined && String(context.scopeNumber) !== String(filter.scopeNumber)) {
+        return false;
+    }
+    return true;
+}

package/dist/neal/execute-finalization.js

@@ -0,0 +1,5 @@
+export const EXECUTE_FINALIZATION_PHASE = 'execute_finalization';
+export const EXECUTE_FINALIZATION_PUBLIC_LABEL = 'finalizing accepted scope';
+export function isExecuteFinalizationPhase(phase) {
+    return phase === EXECUTE_FINALIZATION_PHASE;
+}

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

@@ -0,0 +1,188 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeTextAtomic } from './atomic-write.js';
+import { renderAdjudicationContractLines } from './adjudicator/artifacts.js';
+import { formatPublicPhase } from './phase-display.js';
+import { renderInteractiveBlockedRecoveryHistoryLines } from './recovery-artifacts.js';
+import { buildScopeAccountingSummary, getCurrentScopeLabel, getExecutionPlanScopeCountForShape, renderScopeProgressSummary, } from './scopes.js';
+import { getFinalCompletionView } from './state-views.js';
+import { formatSquashMessage } from './squash-message.js';
+export function getFinalCompletionReviewArtifactPath(runDir) {
+    return join(runDir, 'FINAL_COMPLETION_REVIEW.md');
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+export async function readFinalCompletionUnstructuredOutput(args) {
+    let content;
+    try {
+        content = await readFile(join(args.runDir, 'events.ndjson'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const matchedTexts = [];
+    for (const line of content.split('\n')) {
+        if (!line.trim()) {
+            continue;
+        }
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const data = event.data ?? {};
+        if (event.type !== 'provider.assistant_text' ||
+            data.provider !== 'anthropic-claude' ||
+            data.role !== 'structured-advisor' ||
+            data.label !== 'final-completion') {
+            continue;
+        }
+        const eventSessionHandle = stringValue(data.sessionHandle);
+        if (args.sessionHandle && eventSessionHandle !== args.sessionHandle) {
+            continue;
+        }
+        const text = stringValue(data.text);
+        if (text) {
+            matchedTexts.push(text);
+        }
+    }
+    if (!matchedTexts.length) {
+        return null;
+    }
+    return {
+        source: args.source,
+        text: matchedTexts.join('\n'),
+        ambiguousMatch: !args.sessionHandle,
+    };
+}
+function collectResidualReviewDebt(scopes) {
+    return scopes.flatMap((scope) => (scope.residualReviewDebt ?? []).map((item) => ({
+        scope: scope.number,
+        ...item,
+    })));
+}
+export function renderFinalCompletionReviewMarkdown(state, options = {}) {
+    const finalCompletion = getFinalCompletionView(state);
+    const summary = finalCompletion?.summary ?? null;
+    const reviewVerdict = finalCompletion?.reviewVerdict ?? null;
+    const residualDebt = collectResidualReviewDebt(state.completedScopes.filter((scope) => scope.result === 'accepted'));
+    const scopeAccounting = buildScopeAccountingSummary(state.completedScopes);
+    const lines = [
+        '# Final Completion Review',
+        '',
+        '## Metadata',
+        `- Plan: ${state.planDoc}`,
+        `- Current step: ${formatPublicPhase(state.phase)}`,
+        `- Status: ${state.status}`,
+        `- Execution shape: ${state.executionShape ?? 'pending'}`,
+        `- Current scope: ${getCurrentScopeLabel(state)}`,
+        `- Scope progress: ${renderScopeProgressSummary(state, getExecutionPlanScopeCountForShape(state.executionShape))}`,
+        `- Final commit: ${state.finalCommit ?? 'pending'}`,
+        `- Last marker: ${state.lastScopeMarker ?? 'pending'}`,
+        `- Reviewer session: ${state.reviewerSessionHandle ?? 'pending'}`,
+        `- Continue-execution cycles used: ${finalCompletion?.continueExecutionCount ?? 0}`,
+        `- Continue-execution cap reached: ${finalCompletion?.continueExecutionCapReached ? 'yes' : 'no'}`,
+    ];
+    lines.push('', '## Coder Completion Summary');
+    if (!summary) {
+        lines.push('', 'Pending.');
+    }
+    else {
+        lines.push(`- Plan goal satisfied: ${summary.planGoalSatisfied ? 'yes' : 'no'}`, `- What changed overall: ${summary.whatChangedOverall}`, `- Verification summary: ${summary.verificationSummary}`);
+        if (summary.remainingKnownGaps.length > 0) {
+            lines.push('- Remaining known gaps:');
+            for (const gap of summary.remainingKnownGaps) {
+                lines.push(`  - ${gap}`);
+            }
+        }
+        else {
+            lines.push('- Remaining known gaps: none');
+        }
+    }
+    if (options.unstructuredOutput?.source === 'coder_summary') {
+        lines.push('', '## Unstructured Coder Summary Output', '', 'Claude returned this prose but failed to provide SDK structured output.');
+        if (options.unstructuredOutput.ambiguousMatch) {
+            lines.push('', 'This prose was selected without a failed-session handle, so the match may be ambiguous.');
+        }
+        lines.push('', options.unstructuredOutput.text);
+    }
+    const contractLines = renderAdjudicationContractLines(state);
+    if (contractLines.length > 0) {
+        lines.push('', ...contractLines);
+    }
+    lines.push(...renderInteractiveBlockedRecoveryHistoryLines(state.interactiveBlockedRecoveryHistory));
+    lines.push('', '## Scope Accounting', `- ${scopeAccounting.summary}`);
+    if (scopeAccounting.replacedParentScopes.length > 0) {
+        lines.push('- Derived parent replacements:');
+        for (const replacement of scopeAccounting.replacedParentScopes) {
+            lines.push(`  - Scope ${replacement.number}: ${replacement.derivedPlanPath}`);
+        }
+    }
+    else {
+        lines.push('- Derived parent replacements: none');
+    }
+    lines.push('', '## Residual Review Debt');
+    if (residualDebt.length === 0) {
+        lines.push('', 'No unresolved non-blocking review debt was recorded for accepted scopes.');
+    }
+    else {
+        lines.push('', 'The final reviewer should decide whether these accepted-scope leftovers are acceptable residual polish or evidence that execution exited too early.');
+        for (const item of residualDebt) {
+            const files = item.files.length > 0 ? item.files.join(', ') : 'n/a';
+            lines.push('', `### Scope ${item.scope} ${item.id}`, `- Status: ${item.status}`, `- Files: ${files}`, `- Claim: ${item.claim}`, `- Evidence: ${item.evidence?.trim() || 'n/a'}`, `- Required action: ${item.requiredAction}`, `- Coder disposition: ${item.coderDisposition ?? 'pending'}`, `- Coder commit: ${item.coderCommit ?? 'pending'}`);
+        }
+    }
+    lines.push('', '## Reviewer Verdict');
+    if (!reviewVerdict) {
+        lines.push('', 'Pending.');
+    }
+    else {
+        lines.push(`- Reviewer action: ${reviewVerdict.action}`, `- Resulting action: ${finalCompletion?.effectiveAction ?? reviewVerdict.action}`, `- Reviewer summary: ${reviewVerdict.summary}`, `- Reviewer rationale: ${reviewVerdict.rationale}`);
+        if (reviewVerdict.missingWork) {
+            lines.push(`- Missing work summary: ${reviewVerdict.missingWork.summary}`, `- Missing work required outcome: ${reviewVerdict.missingWork.requiredOutcome}`, `- Missing work verification: ${reviewVerdict.missingWork.verification}`);
+        }
+        else {
+            lines.push('- Missing work: none');
+        }
+    }
+    if (options.unstructuredOutput?.source === 'reviewer_verdict') {
+        lines.push('', '## Unstructured Reviewer Output', '', 'Claude returned this prose but failed to provide SDK structured output.');
+        if (options.unstructuredOutput.ambiguousMatch) {
+            lines.push('', 'This prose was selected without a failed-session handle, so the match may be ambiguous.');
+        }
+        lines.push('', options.unstructuredOutput.text);
+    }
+    lines.push('', '## Squash Commit Message Draft');
+    if (!reviewVerdict) {
+        lines.push('', 'Pending.');
+    }
+    else if (!reviewVerdict.squashCommitMessage && reviewVerdict.action === 'accept_complete') {
+        lines.push('', 'No reviewer-authored squash draft recorded. If squash is requested, Neal will derive the squash message from deterministic fallback generation.');
+    }
+    else if (!reviewVerdict.squashCommitMessage) {
+        lines.push('', 'None recorded.');
+    }
+    else {
+        lines.push('', '```text', formatSquashMessage(reviewVerdict.squashCommitMessage), '```');
+    }
+    lines.push('', '## Result');
+    if (!reviewVerdict) {
+        lines.push('', 'Final completion review has not settled yet.');
+    }
+    else if (finalCompletion?.acceptedComplete) {
+        lines.push('', 'Run completed cleanly.');
+    }
+    else if (finalCompletion?.continuesExecution) {
+        lines.push('', 'Execution reopened with one explicit follow-on scope.');
+    }
+    else {
+        lines.push('', 'Run blocked for operator guidance.');
+    }
+    return `${lines.join('\n')}\n`;
+}
+export async function writeFinalCompletionReviewMarkdown(path, state, options = {}) {
+    await writeTextAtomic(path, renderFinalCompletionReviewMarkdown(state, options));
+}