@navels/neal 0.1.0

package/dist/neal/orchestrator/split-plan.js

@@ -0,0 +1,235 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeTextAtomic } from '../atomic-write.js';
+import { cleanUntracked, getStagedDiff, getUnstagedDiff, getUntrackedFiles, getWorktreeStatus, resetHard, } from '../git.js';
+import { validatePlanDocument } from '../plan-validation.js';
+import { saveState } from '../state.js';
+import { getDerivedPlanCountersView } from '../state-views.js';
+import { filterWrapperOwnedWorktreeStatus, isWrapperOwnedPath, } from '../worktree-status.js';
+import { flushDerivedPlanNotifications, notifyBlocked } from './notifications.js';
+import { enterInteractiveBlockedRecovery, shouldNotifyInteractiveBlockedRecoveryEntry, } from './phases/recovery.js';
+const MAX_SPLIT_PLANS_PER_SCOPE = 10;
+function getSplitPlanArtifactPaths(state) {
+    return {
+        derivedPlanPath: join(state.runDir, `DERIVED_PLAN_SCOPE_${state.currentScopeNumber}.md`),
+        invalidDerivedPlanPath: join(state.runDir, `SCOPE_${state.currentScopeNumber}_INVALID_DERIVED_PLAN.md`),
+        discardedDiffPath: join(state.runDir, `SCOPE_${state.currentScopeNumber}_DISCARDED.diff`),
+    };
+}
+function validateSplitPlanPayload(derivedPlanMarkdown) {
+    const trimmedPayload = derivedPlanMarkdown.trim();
+    if (!trimmedPayload) {
+        return {
+            ok: false,
+            trimmedPayload,
+            errors: ['Replacement plan payload is empty.'],
+        };
+    }
+    const validation = validatePlanDocument(trimmedPayload);
+    if (!validation.ok) {
+        return {
+            ok: false,
+            trimmedPayload,
+            errors: validation.errors,
+        };
+    }
+    // Persist the normalized document so downstream derived-plan review sees the canonical Neal plan contract.
+    return {
+        ok: true,
+        persistedPlanBody: validation.normalization.applied ? validation.normalization.normalizedDocument.trim() : trimmedPayload,
+    };
+}
+function renderInvalidSplitPlanPayloadArtifact(payload, errors) {
+    return [
+        '# Invalid Derived Plan Payload',
+        '',
+        'This artifact is diagnostic only. It is not a reviewable derived plan.',
+        '',
+        '## Validation Errors',
+        '',
+        ...errors.map((error) => `- ${error}`),
+        '',
+        '## Returned Payload',
+        '',
+        '```markdown',
+        payload,
+        '```',
+        '',
+    ].join('\n');
+}
+function formatInvalidSplitPlanReason(errors) {
+    return `split-plan recovery rejected: replacement plan payload is not a valid Neal-executable plan: ${errors.join('; ')}`;
+}
+function isRecoverableInvalidSplitPlanSourcePhase(sourcePhase) {
+    return sourcePhase === 'coder_scope' || sourcePhase === 'coder_response';
+}
+async function captureDiscardedScopeArtifact(cwd, artifactPath) {
+    const [status, stagedDiff, unstagedDiff, untrackedFiles] = await Promise.all([
+        getWorktreeStatus(cwd),
+        getStagedDiff(cwd),
+        getUnstagedDiff(cwd),
+        getUntrackedFiles(cwd),
+    ]);
+    const visibleUntrackedFiles = untrackedFiles.filter((file) => !isWrapperOwnedPath(file));
+    const lines = [
+        '# Discarded Scope WIP',
+        '',
+        '## Git Status',
+        '```text',
+        status || '(clean)',
+        '```',
+        '',
+        '## Staged Diff',
+        '```diff',
+        stagedDiff || '',
+        '```',
+        '',
+        '## Unstaged Diff',
+        '```diff',
+        unstagedDiff || '',
+        '```',
+        '',
+        '## Untracked Files',
+        visibleUntrackedFiles.length > 0 ? visibleUntrackedFiles.map((file) => `- ${file}`).join('\n') : '(none)',
+    ];
+    for (const file of visibleUntrackedFiles) {
+        lines.push('', `### ${file}`);
+        try {
+            const content = await readFile(join(cwd, file), 'utf8');
+            lines.push('```text', content, '```');
+        }
+        catch {
+            lines.push('(binary or unreadable file omitted from inline snapshot)');
+        }
+    }
+    await writeTextAtomic(artifactPath, `${lines.join('\n')}\n`);
+}
+async function discardScopeWorktree(state) {
+    if (!state.baseCommit) {
+        throw new Error('Cannot discard scope worktree without a baseCommit');
+    }
+    await resetHard(state.cwd, state.baseCommit);
+    await cleanUntracked(state.cwd, ['.neal', '.forge']);
+    const remainingStatus = filterWrapperOwnedWorktreeStatus(await getWorktreeStatus(state.cwd));
+    if (remainingStatus) {
+        throw new Error(`Failed to restore worktree to scope base ${state.baseCommit}:\n${remainingStatus}`);
+    }
+}
+export async function persistSplitPlanRecovery(state, statePath, args, deps) {
+    const derivedPlanCounters = getDerivedPlanCountersView(state);
+    if (derivedPlanCounters.splitPlanCountForCurrentScope >= MAX_SPLIT_PLANS_PER_SCOPE) {
+        const reason = `split-plan recovery rejected: scope ${state.currentScopeNumber} reached the split-plan limit (${MAX_SPLIT_PLANS_PER_SCOPE})`;
+        const blockedState = await saveState(statePath, {
+            ...state,
+            lastScopeMarker: 'AUTONOMY_SPLIT_PLAN',
+            phase: 'blocked',
+            status: 'blocked',
+            blockedFromPhase: args.sourcePhase,
+            interactiveBlockedRecovery: null,
+        });
+        await deps.writeExecutionArtifacts(blockedState);
+        const persistedState = await deps.persistBlockedScope(blockedState, statePath, reason);
+        return flushDerivedPlanNotifications(persistedState, statePath, args.logger, reason);
+    }
+    if (derivedPlanCounters.derivedPlanDepth >= 1) {
+        const reason = `split-plan recovery rejected: derived plan depth limit reached for scope ${state.currentScopeNumber}`;
+        const blockedState = await saveState(statePath, {
+            ...state,
+            lastScopeMarker: 'AUTONOMY_SPLIT_PLAN',
+            phase: 'blocked',
+            status: 'blocked',
+            blockedFromPhase: args.sourcePhase,
+            interactiveBlockedRecovery: null,
+        });
+        await deps.writeExecutionArtifacts(blockedState);
+        const persistedState = await deps.persistBlockedScope(blockedState, statePath, reason);
+        return flushDerivedPlanNotifications(persistedState, statePath, args.logger, reason);
+    }
+    const { derivedPlanPath, invalidDerivedPlanPath, discardedDiffPath } = getSplitPlanArtifactPaths(state);
+    const validation = validateSplitPlanPayload(args.derivedPlanMarkdown);
+    if (!validation.ok) {
+        const reason = formatInvalidSplitPlanReason(validation.errors);
+        await writeTextAtomic(invalidDerivedPlanPath, renderInvalidSplitPlanPayloadArtifact(validation.trimmedPayload, validation.errors));
+        await args.logger?.event('split_plan.invalid_payload', {
+            scopeNumber: state.currentScopeNumber,
+            sourcePhase: args.sourcePhase,
+            validationErrors: validation.errors,
+            invalidPayloadPath: invalidDerivedPlanPath,
+            resetSkipped: true,
+            createdCommits: args.createdCommits,
+        });
+        const recoveryCandidateState = {
+            ...state,
+            lastScopeMarker: 'AUTONOMY_SPLIT_PLAN',
+            blockedFromPhase: args.sourcePhase,
+            interactiveBlockedRecovery: null,
+            splitPlanBlockedNotified: false,
+        };
+        if (isRecoverableInvalidSplitPlanSourcePhase(args.sourcePhase)) {
+            await args.logger?.event('split_plan.invalid_payload_recovery_started', {
+                scopeNumber: state.currentScopeNumber,
+                sourcePhase: args.sourcePhase,
+                invalidPayloadPath: invalidDerivedPlanPath,
+                validationErrors: validation.errors,
+                createdCommits: args.createdCommits,
+            });
+            const persistedState = await enterInteractiveBlockedRecovery({
+                ...recoveryCandidateState,
+                status: 'blocked',
+                currentScopeProgressJustification: null,
+                currentScopeMeaningfulProgressVerdict: null,
+            }, statePath, reason, args.logger);
+            if (shouldNotifyInteractiveBlockedRecoveryEntry(persistedState)) {
+                await notifyBlocked(persistedState, reason, args.logger);
+            }
+            return persistedState;
+        }
+        const blockedState = await saveState(statePath, {
+            ...recoveryCandidateState,
+            phase: 'blocked',
+            status: 'blocked',
+            currentScopeProgressJustification: null,
+            currentScopeMeaningfulProgressVerdict: null,
+        });
+        await deps.writeExecutionArtifacts(blockedState);
+        const persistedState = await deps.persistBlockedScope(blockedState, statePath, reason);
+        return flushDerivedPlanNotifications(persistedState, statePath, args.logger, reason);
+    }
+    await captureDiscardedScopeArtifact(state.cwd, discardedDiffPath);
+    await writeTextAtomic(derivedPlanPath, `${validation.persistedPlanBody}\n`);
+    await discardScopeWorktree(state);
+    const nextState = await saveState(statePath, {
+        ...state,
+        lastScopeMarker: 'AUTONOMY_SPLIT_PLAN',
+        phase: 'reviewer_plan',
+        status: 'running',
+        blockedFromPhase: null,
+        currentScopeProgressJustification: null,
+        currentScopeMeaningfulProgressVerdict: null,
+        interactiveBlockedRecovery: null,
+        derivedPlanPath,
+        derivedFromScopeNumber: state.currentScopeNumber,
+        derivedPlanStatus: 'pending_review',
+        splitPlanStartedNotified: false,
+        derivedPlanAcceptedNotified: false,
+        splitPlanBlockedNotified: false,
+        derivedScopeIndex: null,
+        splitPlanCountForCurrentScope: state.splitPlanCountForCurrentScope + 1,
+        rounds: [],
+        recentBlocks: [],
+        reviewStuckArbiterCount: 0,
+        findings: [],
+        createdCommits: [],
+        coderRetryCount: 0,
+        reviewerSessionHandle: null,
+    });
+    await deps.writeExecutionArtifacts(nextState);
+    await args.logger?.event('split_plan.persisted', {
+        scopeNumber: state.currentScopeNumber,
+        sourcePhase: args.sourcePhase,
+        derivedPlanPath,
+        discardedDiffPath,
+        createdCommits: args.createdCommits,
+    });
+    return flushDerivedPlanNotifications(nextState, statePath, args.logger);
+}

package/dist/neal/orchestrator/transitions.js

@@ -0,0 +1,309 @@
+import { aggregateChangedFilesForAcceptedDerivedScopes, getAcceptedDerivedScopesForParentObjective, getAcceptedParentScopeForObjective, getCurrentScopeLabel, getParentScopeLabel, isExecutingDerivedPlan, shouldAdvanceTopLevelScopeNumber, shouldContinueTopLevelExecutionAfterAcceptedScope, } from '../scopes.js';
+import { toResidualReviewDebt } from '../review-debt.js';
+import { getDerivedPlanView, getFinalCompletionView } from '../state-views.js';
+const ALREADY_SATISFIED_ACCEPTANCE_RATIONALE_PREFIX = 'Accepted top-level already-satisfied scope';
+export function appendCompletedScope(state, result, details) {
+    const scopeLabel = details.scopeLabel ?? getCurrentScopeLabel(state);
+    const marker = details.marker ?? (state.lastScopeMarker ?? 'AUTONOMY_BLOCKED');
+    return [
+        ...state.completedScopes.filter((scope) => scope.number !== scopeLabel),
+        {
+            number: scopeLabel,
+            marker,
+            result,
+            baseCommit: state.baseCommit,
+            finalCommit: details.finalCommit,
+            summary: details.summary ?? null,
+            commitSubject: details.commitSubject,
+            changedFiles: [...(details.changedFiles ?? [])],
+            reviewRounds: state.rounds.length,
+            findings: state.findings.length,
+            residualReviewDebt: result === 'accepted' ? toResidualReviewDebt(state.findings) : [],
+            archivedReviewPath: details.archivedReviewPath,
+            blocker: details.blocker,
+            derivedFromParentScope: details.derivedFromParentScope ?? null,
+            replacedByDerivedPlanPath: details.replacedByDerivedPlanPath ?? null,
+        },
+    ];
+}
+export function shouldNotifyDerivedPlanAcceptance(previousState, nextState) {
+    const previousDerivedPlan = getDerivedPlanView(previousState);
+    const nextDerivedPlan = getDerivedPlanView(nextState);
+    return (previousDerivedPlan?.status !== 'accepted' &&
+        nextDerivedPlan?.acceptedAwaitingExecution === true &&
+        nextState.phase === 'awaiting_derived_plan_execution');
+}
+export function transitionPlanReviewWithoutOpenFindings(state, reviewMode) {
+    return {
+        ...state,
+        phase: reviewMode === 'derived-plan' ? 'awaiting_derived_plan_execution' : 'done',
+        status: reviewMode === 'plan' ? 'done' : 'running',
+        derivedPlanStatus: reviewMode === 'derived-plan' ? 'accepted' : state.derivedPlanStatus,
+    };
+}
+export function adoptAcceptedDerivedPlan(state) {
+    const derivedPlan = getDerivedPlanView(state);
+    if (derivedPlan?.status !== 'accepted' || derivedPlan.parentScopeNumber === null) {
+        return state;
+    }
+    if (state.phase !== 'awaiting_derived_plan_execution') {
+        throw new Error(`Cannot adopt derived plan from phase ${state.phase}`);
+    }
+    if (state.createdCommits.length > 0) {
+        throw new Error('Cannot adopt derived plan after derived execution has already created commits');
+    }
+    if (derivedPlan.scopeIndex !== null) {
+        throw new Error('Cannot adopt derived plan after derived scope execution has already started');
+    }
+    return {
+        ...state,
+        phase: 'coder_scope',
+        status: 'running',
+        derivedScopeIndex: derivedPlan.scopeIndex ?? 1,
+        coderSessionHandle: null,
+        coderSessionProtocol: null,
+        coderRetryCount: 0,
+        currentScopeProgressJustification: null,
+        currentScopeMeaningfulProgressVerdict: null,
+        finalCompletionSummary: null,
+        finalCompletionReviewVerdict: null,
+        finalCompletionResolvedAction: null,
+        finalCompletionContinueExecutionCapReached: false,
+        rounds: [],
+        recentBlocks: [],
+        reviewStuckArbiterCount: 0,
+        findings: [],
+        createdCommits: [],
+        blockedFromPhase: null,
+    };
+}
+export function computeNextScopeStateAfterExecuteFinalization({ state, finalCommit, completedScopes, archivedReviewPath, }) {
+    const derivedExecution = isExecutingDerivedPlan(state);
+    const derivedPlan = getDerivedPlanView(state);
+    const finalCompletion = getFinalCompletionView(state);
+    const derivedPlanCompleted = derivedExecution && state.lastScopeMarker === 'AUTONOMY_DONE';
+    const continueScopes = derivedExecution ? true : shouldContinueTopLevelExecutionAfterAcceptedScope(state);
+    const nextTopLevelScopeNumber = shouldAdvanceTopLevelScopeNumber(state)
+        ? state.currentScopeNumber + 1
+        : state.currentScopeNumber;
+    if (derivedExecution && derivedPlanCompleted) {
+        return {
+            ...state,
+            baseCommit: finalCommit,
+            finalCommit: null,
+            coderSessionHandle: null,
+            coderSessionProtocol: null,
+            currentScopeNumber: nextTopLevelScopeNumber,
+            lastScopeMarker: null,
+            currentScopeProgressJustification: null,
+            currentScopeMeaningfulProgressVerdict: null,
+            finalCompletionSummary: null,
+            finalCompletionReviewVerdict: null,
+            finalCompletionResolvedAction: null,
+            finalCompletionContinueExecutionCapReached: false,
+            derivedPlanPath: null,
+            derivedFromScopeNumber: null,
+            derivedPlanStatus: null,
+            derivedScopeIndex: null,
+            splitPlanStartedNotified: false,
+            derivedPlanAcceptedNotified: false,
+            splitPlanBlockedNotified: false,
+            splitPlanCountForCurrentScope: 0,
+            rounds: [],
+            recentBlocks: [],
+            reviewStuckArbiterCount: 0,
+            findings: [],
+            createdCommits: [],
+            completedScopes,
+            archivedReviewPath: null,
+            phase: 'coder_scope',
+            status: 'running',
+        };
+    }
+    if (derivedExecution) {
+        return {
+            ...state,
+            baseCommit: finalCommit,
+            finalCommit: null,
+            coderSessionHandle: null,
+            coderSessionProtocol: null,
+            lastScopeMarker: null,
+            currentScopeProgressJustification: null,
+            currentScopeMeaningfulProgressVerdict: null,
+            finalCompletionSummary: null,
+            finalCompletionReviewVerdict: null,
+            finalCompletionResolvedAction: null,
+            finalCompletionContinueExecutionCapReached: false,
+            derivedScopeIndex: (derivedPlan?.scopeIndex ?? 1) + 1,
+            splitPlanStartedNotified: false,
+            derivedPlanAcceptedNotified: false,
+            splitPlanBlockedNotified: false,
+            rounds: [],
+            recentBlocks: [],
+            reviewStuckArbiterCount: 0,
+            findings: [],
+            createdCommits: [],
+            completedScopes,
+            archivedReviewPath: null,
+            phase: 'coder_scope',
+            status: 'running',
+        };
+    }
+    if (continueScopes) {
+        return {
+            ...state,
+            baseCommit: finalCommit,
+            finalCommit: null,
+            coderSessionHandle: null,
+            coderSessionProtocol: null,
+            currentScopeNumber: nextTopLevelScopeNumber,
+            lastScopeMarker: null,
+            currentScopeProgressJustification: null,
+            currentScopeMeaningfulProgressVerdict: null,
+            finalCompletionSummary: null,
+            finalCompletionReviewVerdict: null,
+            finalCompletionResolvedAction: null,
+            finalCompletionContinueExecutionCapReached: false,
+            derivedPlanPath: null,
+            derivedFromScopeNumber: null,
+            derivedPlanStatus: null,
+            derivedScopeIndex: null,
+            splitPlanStartedNotified: false,
+            derivedPlanAcceptedNotified: false,
+            splitPlanBlockedNotified: false,
+            splitPlanCountForCurrentScope: 0,
+            rounds: [],
+            recentBlocks: [],
+            reviewStuckArbiterCount: 0,
+            findings: [],
+            createdCommits: [],
+            completedScopes,
+            archivedReviewPath: null,
+            phase: 'coder_scope',
+            status: 'running',
+        };
+    }
+    return {
+        ...state,
+        finalCommit,
+        archivedReviewPath,
+        completedScopes,
+        currentScopeProgressJustification: null,
+        currentScopeMeaningfulProgressVerdict: null,
+        finalCompletionSummary: finalCompletion?.summary ?? null,
+        finalCompletionReviewVerdict: finalCompletion?.reviewVerdict ?? null,
+        finalCompletionResolvedAction: finalCompletion?.resolvedAction ?? null,
+        phase: 'final_completion_review',
+        status: 'running',
+    };
+}
+export function appendParentCompletionFromAcceptedDerivedScopes(args) {
+    const derivedPlan = getDerivedPlanView(args.state);
+    const parentScopeLabel = getParentScopeLabel(args.state);
+    if (getAcceptedParentScopeForObjective(args.state, parentScopeLabel)) {
+        throw new Error(`Cannot append parent completion for objective ${parentScopeLabel}: accepted parent record already exists`);
+    }
+    const derivedScopes = getAcceptedDerivedScopesForParentObjective(args.state, parentScopeLabel);
+    const parentScopeChangedFiles = aggregateChangedFilesForAcceptedDerivedScopes(derivedScopes);
+    return appendCompletedScope(args.state, 'accepted', {
+        scopeLabel: parentScopeLabel,
+        finalCommit: args.finalCommit,
+        summary: `advance_parent accepted parent scope ${parentScopeLabel} via prior derived work; the current empty derived sub-scope was not accepted.`,
+        commitSubject: `Parent scope ${parentScopeLabel} complete via derived plan`,
+        changedFiles: parentScopeChangedFiles,
+        archivedReviewPath: args.archivedReviewPath,
+        blocker: null,
+        marker: 'AUTONOMY_SCOPE_DONE',
+        replacedByDerivedPlanPath: derivedPlan?.path ?? null,
+    });
+}
+export function computeNextScopeStateAfterParentAdvance(args) {
+    const nextTopLevelScopeNumber = shouldAdvanceTopLevelScopeNumber(args.state)
+        ? args.state.currentScopeNumber + 1
+        : args.state.currentScopeNumber;
+    return {
+        ...args.state,
+        baseCommit: args.finalCommit,
+        finalCommit: null,
+        archivedReviewPath: null,
+        coderSessionHandle: null,
+        coderSessionProtocol: null,
+        reviewerSessionHandle: null,
+        coderRetryCount: 0,
+        currentScopeNumber: nextTopLevelScopeNumber,
+        lastScopeMarker: null,
+        currentScopeProgressJustification: null,
+        currentScopeMeaningfulProgressVerdict: null,
+        manualGate: null,
+        finalCompletionSummary: null,
+        finalCompletionReviewVerdict: null,
+        finalCompletionResolvedAction: null,
+        finalCompletionContinueExecutionCapReached: false,
+        derivedPlanPath: null,
+        derivedFromScopeNumber: null,
+        derivedPlanStatus: null,
+        derivedScopeIndex: null,
+        splitPlanStartedNotified: false,
+        derivedPlanAcceptedNotified: false,
+        splitPlanBlockedNotified: false,
+        splitPlanCountForCurrentScope: 0,
+        rounds: [],
+        recentBlocks: [],
+        reviewStuckArbiterCount: 0,
+        findings: [],
+        createdCommits: [],
+        completedScopes: args.completedScopes,
+        blockedFromPhase: null,
+        interactiveBlockedRecovery: null,
+        phase: 'coder_scope',
+        status: 'running',
+    };
+}
+function getAcceptedScopeSummary(state) {
+    const meaningfulProgressVerdict = state.currentScopeMeaningfulProgressVerdict;
+    if (!isExecutingDerivedPlan(state) &&
+        meaningfulProgressVerdict?.action === 'accept' &&
+        meaningfulProgressVerdict.rationale.startsWith(ALREADY_SATISFIED_ACCEPTANCE_RATIONALE_PREFIX)) {
+        return meaningfulProgressVerdict.rationale;
+    }
+    return state.currentScopeProgressJustification?.milestoneTargeted ?? null;
+}
+export function appendDerivedSubScopeAndParentCompletion(args) {
+    const derivedExecution = isExecutingDerivedPlan(args.state);
+    const derivedPlan = getDerivedPlanView(args.state);
+    const currentScopeLabel = getCurrentScopeLabel(args.state);
+    const subScopeCompletedScopes = appendCompletedScope(args.state, 'accepted', {
+        scopeLabel: currentScopeLabel,
+        finalCommit: args.finalCommit,
+        summary: getAcceptedScopeSummary(args.state),
+        commitSubject: args.finalSubject,
+        changedFiles: args.changedFiles,
+        archivedReviewPath: args.archivedReviewPath,
+        blocker: null,
+        derivedFromParentScope: derivedExecution ? getParentScopeLabel(args.state) : null,
+    });
+    const derivedPlanCompleted = derivedExecution && args.state.lastScopeMarker === 'AUTONOMY_DONE';
+    const parentScopeChangedFiles = derivedPlanCompleted
+        ? [
+            ...new Set(subScopeCompletedScopes
+                .filter((scope) => scope.result === 'accepted' && scope.derivedFromParentScope === getParentScopeLabel(args.state))
+                .flatMap((scope) => scope.changedFiles)),
+        ]
+        : args.changedFiles;
+    return derivedPlanCompleted
+        ? appendCompletedScope({
+            ...args.state,
+            completedScopes: subScopeCompletedScopes,
+        }, 'accepted', {
+            scopeLabel: getParentScopeLabel(args.state),
+            finalCommit: args.finalCommit,
+            summary: null,
+            commitSubject: args.finalSubject,
+            changedFiles: parentScopeChangedFiles,
+            archivedReviewPath: args.archivedReviewPath,
+            blocker: null,
+            marker: 'AUTONOMY_SCOPE_DONE',
+            replacedByDerivedPlanPath: derivedPlan?.path ?? null,
+        })
+        : subScopeCompletedScopes;
+}