projscan 4.1.0 → 4.2.0

package/dist/core/start.js

@@ -45,6 +45,7 @@ export async function computeStartReport(rootPath, options = {}) {
         fixFirst,
         adoptionGaps,
         coordinationHints,
+        riskSources,
     });
     const nextActions = dedupeActions([
         missionControl.primaryAction,
@@ -267,12 +268,50 @@ function buildMissionControl(input) {
     const proofCommands = missionProofCommands(input.mode, input.workplan, guardrails, actionPlan);
     const successCriteria = missionSuccessCriteria(input.mode, routed, actionPlan, input.workplan);
     const unresolvedInputs = missionUnresolvedInputs(actionPlan);
+    const executionPlan = buildMissionExecutionPlan({
+        primaryAction,
+        actionPlan,
+        readyActions,
+        unresolvedInputs,
+        successCriteria,
+        proofCommands,
+    });
+    const resume = missionResume(executionPlan);
+    const reviewProof = buildMissionReviewProof(resume, proofCommands);
     const whyNow = routed
         ? routedWhyNow(routed, actionPlan)
         : input.fixFirst
             ? `Top evidence points to "${input.fixFirst.title}" as the first useful move.`
             : `The ${input.mode} workflow is the shortest path from orientation to verified action.`;
-    const commandText = primaryAction.command ?? primaryAction.tool ?? 'projscan start --format json';
+    const reviewGate = buildMissionReviewGate({
+        status,
+        doneWhen: successCriteria,
+        proof: reviewProof,
+        currentWorktree: input.riskSources.currentWorktree,
+    });
+    const handoffPrompt = missionHandoffPrompt(resume, successCriteria, whyNow, unresolvedInputs, proofCommands, reviewGate);
+    const runbook = buildMissionRunbook({
+        intent: input.intent,
+        status,
+        primaryAction,
+        readyActions,
+        unresolvedInputs,
+        successCriteria,
+        proofCommands,
+        executionPlan,
+        resume,
+        handoffPrompt,
+        reviewGate,
+    });
+    const taskCard = buildMissionTaskCard({
+        intent: input.intent,
+        status,
+        currentStep: executionPlan.cursor,
+        resume,
+        successCriteria,
+        handoffPrompt,
+        reviewGate,
+    });
     return {
         ...(input.intent ? { intent: input.intent } : {}),
         status,
@@ -288,27 +327,1021 @@ function buildMissionControl(input) {
         successCriteria,
         proofSummary: READY_PROOF_SUMMARY,
         proofCommands,
-        handoff: missionHandoff(primaryAction, readyActions, unresolvedInputs, successCriteria, proofCommands),
-        handoffPrompt: missionHandoffPrompt(commandText, successCriteria, whyNow, unresolvedInputs, proofCommands),
+        resume,
+        handoff: missionHandoff(executionPlan.cursor, resume, primaryAction, readyActions, unresolvedInputs, successCriteria, proofCommands, reviewGate),
+        executionPlan,
+        runbook,
+        reviewGate,
+        taskCard,
+        handoffPrompt,
+    };
+}
+function buildMissionReviewGate(input) {
+    const checklist = [
+        'Complete this task card and remaining proof.',
+        'Capture `git status --short`.',
+        'Capture `git diff --stat`.',
+        'Stop and ask for approval before starting another slice, release, publish, or deploy.',
+    ];
+    const commands = ['git status --short', 'git diff --stat'];
+    const doneWhen = input.doneWhen.slice();
+    const policy = buildMissionReviewPolicy();
+    const decisions = buildMissionReviewDecisions();
+    const worktree = buildMissionReviewWorktree(input.currentWorktree);
+    const stopCondition = 'Stop after the current Mission Control checklist and proof are complete.';
+    const reviewPrompt = `Review the completed mission, proof output, and working-tree summary before approving another slice, release, publish, or deploy. ${input.proof.summary}`;
+    return {
+        title: 'Mission Review Gate',
+        required: true,
+        status: input.status,
+        stopCondition,
+        reviewPrompt,
+        checklist,
+        doneWhen,
+        policy,
+        decisions,
+        commands,
+        worktree,
+        proof: input.proof,
+        markdown: renderMissionReviewGateMarkdown({
+            status: input.status,
+            stopCondition,
+            reviewPrompt,
+            checklist,
+            doneWhen,
+            policy,
+            decisions,
+            commands,
+            worktree,
+            proof: input.proof,
+        }),
     };
 }
-function missionHandoff(nextAction, readyActions, needsInput, doneWhen, proofCommands) {
+function buildMissionReviewPolicy() {
     return {
+        approvalRequired: true,
+        blockedActions: ['next_slice', 'release', 'publish', 'deploy', 'push', 'merge', 'version_bump'],
+        summary: 'Explicit reviewer approval is required before another slice, release, publish, deploy, push, merge, or version bump.',
+    };
+}
+function buildMissionReviewDecisions() {
+    return [
+        {
+            id: 'approve_next_slice',
+            label: 'Approve next slice',
+            description: 'The agent may start another bounded implementation slice.',
+            consequence: 'No release, publish, deploy, or version bump is allowed unless the reviewer asks for it.',
+            reply: 'Approved: start one more bounded implementation slice. Do not release, publish, deploy, push, merge, or bump the version.',
+        },
+        {
+            id: 'request_changes',
+            label: 'Request changes',
+            description: 'The agent must address review feedback before starting more scope.',
+            consequence: 'The current mission stays open until feedback and proof are updated.',
+            reply: 'Changes requested: address the review feedback first, update proof, then stop for another review.',
+        },
+        {
+            id: 'review_version_candidate',
+            label: 'Review version candidate',
+            description: 'The agent may prepare release notes, version rationale, and remaining gates for review.',
+            consequence: 'Publishing still requires a separate explicit approval.',
+            reply: 'Prepare a version-candidate review only. Do not publish, deploy, push, merge, or bump the version.',
+        },
+    ];
+}
+function buildMissionReviewProof(resume, proofCommands) {
+    const commands = resume.remainingProofCommands ?? proofCommands;
+    const toolCalls = resume.remainingProofToolCalls ?? [];
+    const items = resume.remainingProofItems ?? [];
+    return {
+        summary: READY_PROOF_SUMMARY,
+        commands,
+        ...(toolCalls.length > 0 ? { toolCalls } : {}),
+        ...(items.length > 0 ? { items } : {}),
+    };
+}
+function buildMissionReviewWorktree(currentWorktree) {
+    if (!currentWorktree.available) {
+        const reason = currentWorktree.reason ?? 'unknown';
+        return {
+            available: false,
+            clean: false,
+            changedFileCount: 0,
+            files: [],
+            baseRef: currentWorktree.baseRef,
+            summary: `Current worktree evidence is unavailable: ${reason}.`,
+            reason,
+        };
+    }
+    const changedFileCount = currentWorktree.count;
+    const baseRef = currentWorktree.baseRef;
+    return {
+        available: true,
+        clean: changedFileCount === 0,
+        changedFileCount,
+        files: currentWorktree.files,
+        baseRef,
+        summary: changedFileCount === 0
+            ? 'Current worktree evidence sees no changed files.'
+            : `Current worktree evidence sees ${changedFileCount} changed file(s)${baseRef ? ` against ${baseRef}` : ''}.`,
+    };
+}
+function renderMissionReviewGateMarkdown(input) {
+    const lines = [
+        '# Mission Review Gate',
+        '',
+        `Status: ${input.status}`,
+        `Stop condition: ${input.stopCondition}`,
+        '',
+        '## Checklist',
+        ...input.checklist.map((item) => `- [ ] ${item}`),
+        '',
+        '## Review Policy',
+        `Approval required: ${input.policy.approvalRequired ? 'yes' : 'no'}`,
+        input.policy.summary,
+        'Blocked until approval:',
+        ...input.policy.blockedActions.map(formatMissionReviewBlockedAction),
+        '',
+        '## Done When',
+        ...(input.doneWhen.length > 0
+            ? input.doneWhen.map((criterion) => `- [ ] ${criterion}`)
+            : ['- [ ] The current mission is complete and verified.']),
+        '',
+        '## Reviewer Decision',
+        ...input.decisions.map(formatMissionReviewDecision),
+        '',
+        ...renderMissionReviewProofLines(input.proof),
+        '## Evidence Commands',
+        ...input.commands.map((command) => `- \`${command}\``),
+        '',
+        '## Worktree Evidence',
+        input.worktree.summary,
+        ...input.worktree.files.slice(0, 8).map((file) => `- \`${file}\``),
+        '',
+        '## Review Prompt',
+        input.reviewPrompt,
+    ];
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+function formatMissionReviewDecision(decision) {
+    return `- [ ] ${decision.label}: ${decision.description} Consequence: ${decision.consequence} Reply: "${decision.reply}"`;
+}
+function formatMissionReviewBlockedAction(action) {
+    const labels = {
+        next_slice: 'Start another implementation slice',
+        release: 'Release',
+        publish: 'Publish',
+        deploy: 'Deploy',
+        push: 'Push',
+        merge: 'Merge',
+        version_bump: 'Version bump',
+    };
+    return `- ${labels[action]} (\`${action}\`)`;
+}
+function renderMissionReviewProofLines(proof) {
+    const lines = ['## Proof Queue', proof.summary];
+    if (proof.items && proof.items.length > 0) {
+        return [...lines, ...proof.items.map(formatMissionReviewProofItem), ''];
+    }
+    if (proof.commands.length > 0) {
+        return [...lines, ...proof.commands.map((command) => `- \`${command}\``), ''];
+    }
+    return [...lines, 'No proof commands are ready yet.', ''];
+}
+function formatMissionReviewProofItem(item) {
+    const annotation = item.toolCall
+        ? ` (MCP: ${formatMissionReviewToolCall(item.toolCall)})`
+        : ' (CLI only)';
+    return `- \`${item.command}\`${annotation}`;
+}
+function formatMissionReviewToolCall(toolCall) {
+    return typeof toolCall.args !== 'undefined'
+        ? `${toolCall.tool} ${JSON.stringify(toolCall.args)}`
+        : toolCall.tool;
+}
+function buildMissionRunbook(input) {
+    const readyCommands = uniqueStrings(input.readyActions
+        .map((action) => action.command ?? '')
+        .filter(isRunnableCommand));
+    const readyCommandBlock = readyCommands.join('\n');
+    const blockedInputSummary = input.unresolvedInputs.length > 0
+        ? `Needs input: ${input.unresolvedInputs.map((item) => `${item.name}=${item.placeholder}`).join(', ')}.`
+        : undefined;
+    return {
+        title: `Runbook: ${input.primaryAction.label}`,
+        status: input.status,
+        currentPhase: input.executionPlan.currentPhase,
+        currentStep: input.executionPlan.cursor,
+        resume: input.resume,
+        readyCommandBlock,
+        ...(blockedInputSummary ? { blockedInputSummary } : {}),
+        markdown: renderMissionRunbookMarkdown({
+            intent: input.intent,
+            status: input.status,
+            currentPhase: input.executionPlan.currentPhase,
+            currentStep: input.executionPlan.cursor,
+            resume: input.resume,
+            primaryAction: input.primaryAction,
+            readyCommands,
+            unresolvedInputs: input.unresolvedInputs,
+            proofCommands: input.proofCommands,
+            successCriteria: input.successCriteria,
+            handoffPrompt: input.handoffPrompt,
+            reviewGate: input.reviewGate,
+        }),
+    };
+}
+function renderMissionRunbookMarkdown(input) {
+    const lines = [
+        '# Mission Runbook',
+        '',
+        ...(input.intent ? [`Intent: ${input.intent}`] : []),
+        `Status: ${input.status}`,
+        `Current phase: ${input.currentPhase}`,
+        `Next action: ${input.primaryAction.command ? `\`${input.primaryAction.command}\`` : input.primaryAction.label}`,
+        '',
+        ...renderRunbookCursorLines(input.currentStep),
+        '',
+        ...renderRunbookResumeLines(input.resume),
+        '',
+        '## Handoff Prompt',
+        input.handoffPrompt,
+        '',
+        '## Review Gate',
+        ...input.reviewGate.checklist.map((item) => `- [ ] ${item}`),
+        '',
+        '## Reviewer Decision',
+        ...input.reviewGate.decisions.map(formatMissionReviewDecision),
+        '',
+        input.reviewGate.reviewPrompt,
+        '',
+        '## Ready Commands',
+        ...(input.readyCommands.length > 0 ? input.readyCommands.map((command) => `- \`${command}\``) : ['- None yet. Resolve blocked inputs first.']),
+        '',
+        ...(input.unresolvedInputs.length > 0
+            ? [
+                '## Blocked Inputs',
+                ...input.unresolvedInputs.map((item) => `- ${item.name}: ${item.instruction}`),
+                '',
+            ]
+            : []),
+        '## Proof Commands',
+        ...(input.proofCommands.length > 0 ? input.proofCommands.map((command) => `- \`${command}\``) : ['- No proof commands available yet.']),
+        '',
+        '## Done When',
+        ...(input.successCriteria.length > 0 ? input.successCriteria.map((criterion) => `- ${criterion}`) : ['- The next action is complete and verified.']),
+    ];
+    return `${lines.join('\n')}\n`;
+}
+function buildMissionTaskCard(input) {
+    return {
+        title: 'Mission Task Card',
+        status: input.status,
+        currentPhase: input.currentStep.phaseId,
+        currentStep: input.currentStep,
+        markdown: renderMissionTaskCardMarkdown(input),
+    };
+}
+function renderMissionTaskCardMarkdown(input) {
+    const lines = [
+        '# Mission Task Card',
+        '',
+        ...(input.intent ? [`Intent: ${input.intent}`] : []),
+        `Status: ${input.status}`,
+        `Current step: ${input.currentStep.stepId} in ${input.currentStep.phaseId}`,
+        '',
+        '## Do Next',
+        ...missionTaskCardActionLines(input.resume),
+        '',
+        '## Proof',
+        ...missionTaskCardProofLines(input.resume),
+        '',
+        '## Done When',
+        ...(input.successCriteria.length > 0
+            ? input.successCriteria.map((criterion) => `- [ ] ${criterion}`)
+            : ['- [ ] The next action is complete and verified.']),
+        '',
+        '## Review Gate',
+        ...input.reviewGate.checklist.map((item) => `- [ ] ${item}`),
+        '',
+        '## Reviewer Decision',
+        ...input.reviewGate.decisions.map(formatMissionReviewDecision),
+        '',
+        '## Handoff Prompt',
+        input.handoffPrompt,
+    ];
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+function missionTaskCardActionLines(resume) {
+    const checklist = resume.checklist ?? [];
+    const actionLines = checklist
+        .filter((item) => item.kind !== 'run_proof' && item.kind !== 'confirm_done')
+        .map(formatTaskCardChecklistItem);
+    return actionLines.length > 0 ? actionLines : ['- [ ] Continue from the current Mission Control cursor.'];
+}
+function missionTaskCardProofLines(resume) {
+    const proofItems = resume.remainingProofItems ?? [];
+    const proofLines = proofItems.map(formatTaskCardProofItem);
+    if (proofLines.length > 0)
+        return proofLines;
+    const commands = resume.remainingProofCommands ?? [];
+    return commands.length > 0
+        ? commands.map((command) => `- [ ] \`${command}\``)
+        : ['- [ ] No proof commands are ready yet.'];
+}
+function formatTaskCardChecklistItem(item) {
+    if (item.kind === 'resolve_input') {
+        const label = item.label ? ` (\`${item.label}\`)` : '';
+        const instruction = item.instruction ?? item.label;
+        return `- [ ] Resolve \`${item.stepId}\`${label}: ${instruction}`;
+    }
+    if (item.kind === 'run_follow_up' && item.command) {
+        const prefix = item.status === 'blocked' ? 'After inputs, run' : 'Then run';
+        return `- [ ] ${prefix} \`${item.command}\`${formatTaskCardChecklistAnnotation(item)}`;
+    }
+    if (item.command) {
+        return `- [ ] Run \`${item.command}\`${formatTaskCardChecklistAnnotation(item)}`;
+    }
+    return `- [ ] ${item.instruction ?? item.label}`;
+}
+function formatTaskCardChecklistAnnotation(item) {
+    if (!item.tool)
+        return '';
+    return ` (MCP: ${formatTaskCardToolCall({ tool: item.tool, ...(typeof item.args !== 'undefined' ? { args: item.args } : {}) })})`;
+}
+function formatTaskCardProofItem(item) {
+    const annotation = item.toolCall
+        ? ` (MCP: ${formatTaskCardToolCall(item.toolCall)})`
+        : ' (CLI only)';
+    return `- [ ] \`${item.command}\`${annotation}`;
+}
+function formatTaskCardToolCall(toolCall) {
+    return typeof toolCall.args !== 'undefined'
+        ? `${toolCall.tool} ${JSON.stringify(toolCall.args)}`
+        : toolCall.tool;
+}
+function missionResume(plan) {
+    const cursor = plan.cursor;
+    const commandBlock = cursor.command && isRunnableCommand(cursor.command) ? cursor.command : undefined;
+    const toolCall = resumeToolCall(plan, cursor);
+    const followUps = resumeFollowUps(plan, cursor);
+    const inputBindings = resumeInputBindings(plan, cursor);
+    const checklist = resumeChecklist(plan, cursor, inputBindings, followUps);
+    const remainingProofItems = resumeRemainingProofItems(checklist);
+    const remainingProofCommands = resumeRemainingProofCommands(checklist);
+    const remainingProofToolCalls = resumeRemainingProofToolCalls(checklist);
+    const unlocks = resolveResumeReferences(plan, cursor.unlocks);
+    const blockedBy = resolveResumeReferences(plan, cursor.blockedBy);
+    const instruction = commandBlock
+        ? `Run ${commandBlock}.`
+        : cursor.instruction
+            ? `Resolve ${cursor.label}: ${cursor.instruction}`
+            : `Continue with ${cursor.label}.`;
+    const prompt = commandBlock
+        ? `Resume at ${cursor.stepId} in ${cursor.phaseId}: run \`${commandBlock}\`.${resumeUnlocksSentence(unlocks, cursor.unlocks)}`
+        : `Resume at ${cursor.stepId} in ${cursor.phaseId}: ${instruction}${resumeBlockersSentence(blockedBy, cursor.blockedBy)}`;
+    return {
+        currentStep: cursor,
+        status: cursor.status,
+        instruction,
+        prompt,
+        ...(commandBlock ? { commandBlock } : {}),
+        ...(toolCall ? { toolCall } : {}),
+        ...(followUps.length > 0 ? { followUps } : {}),
+        ...(inputBindings.length > 0 ? { inputBindings } : {}),
+        ...(checklist.length > 0 ? { checklist } : {}),
+        ...(remainingProofItems.length > 0 ? { remainingProofItems } : {}),
+        ...(remainingProofCommands.length > 0 ? { remainingProofCommands } : {}),
+        ...(remainingProofToolCalls.length > 0 ? { remainingProofToolCalls } : {}),
+        ...(unlocks.length > 0 ? { unlocks } : {}),
+        ...(blockedBy.length > 0 ? { blockedBy } : {}),
+    };
+}
+function resumeRemainingProofCommands(checklist) {
+    return checklist
+        .filter((item) => item.kind === 'run_proof' && typeof item.command === 'string')
+        .map((item) => item.command);
+}
+function resumeRemainingProofItems(checklist) {
+    return checklist.flatMap((item) => {
+        if (item.kind !== 'run_proof' || typeof item.command !== 'string')
+            return [];
+        const toolCall = proofChecklistToolCall(item);
+        return [{
+                stepId: item.stepId,
+                status: item.status,
+                label: item.label,
+                command: item.command,
+                ...(toolCall ? { toolCall } : {}),
+            }];
+    });
+}
+function resumeRemainingProofToolCalls(checklist) {
+    return checklist.flatMap((item) => {
+        if (item.kind !== 'run_proof' || typeof item.command !== 'string')
+            return [];
+        const toolCall = proofChecklistToolCall(item);
+        return toolCall ? [{ stepId: item.stepId, command: item.command, ...toolCall }] : [];
+    });
+}
+function proofChecklistToolCall(item) {
+    if (item.tool) {
+        return {
+            tool: item.tool,
+            ...(typeof item.args !== 'undefined' ? { args: item.args } : {}),
+        };
+    }
+    return typeof item.command === 'string' ? proofCommandToolCall(item.command) : undefined;
+}
+function proofCommandToolCall(command) {
+    const preflightMatch = /^projscan preflight(?: --mode ([a-z_]+))? --format json$/.exec(command);
+    if (preflightMatch) {
+        return {
+            tool: 'projscan_preflight',
+            args: preflightMatch[1] ? { mode: preflightMatch[1] } : {},
+        };
+    }
+    const understandMatch = /^projscan understand --view ([a-z_]+)(?: --intent "((?:\\.|[^"\\])*)")? --format json$/.exec(command);
+    if (understandMatch) {
+        return {
+            tool: 'projscan_understand',
+            args: {
+                view: understandMatch[1],
+                ...(understandMatch[2] ? { intent: unescapeDoubleQuoted(understandMatch[2]) } : {}),
+            },
+        };
+    }
+    if (command === 'projscan session touched --format json') {
+        return {
+            tool: 'projscan_session',
+            args: { action: 'touched' },
+        };
+    }
+    return undefined;
+}
+function unescapeDoubleQuoted(value) {
+    return value.replace(/\\(["\\$`])/g, '$1');
+}
+function resumeChecklist(plan, cursor, inputBindings, followUps) {
+    const current = findStepInPlan(plan, cursor.stepId);
+    const currentItem = current
+        ? resumeChecklistItemFromStep(current.phase, current.step, currentChecklistKind(current.step), cursor.stepId)
+        : undefined;
+    const includedStepIds = new Set(currentItem ? [currentItem.stepId] : []);
+    const inputItems = inputBindings.flatMap((binding) => {
+        if (includedStepIds.has(binding.inputId))
+            return [];
+        const found = findStepInPlan(plan, binding.inputId);
+        if (!found)
+            return [];
+        includedStepIds.add(found.step.id);
+        return [{
+                id: `resume-${found.step.id}`,
+                kind: 'resolve_input',
+                phaseId: found.phase.id,
+                stepId: found.step.id,
+                status: found.step.status,
+                label: binding.label,
+                placeholder: binding.placeholder,
+                instruction: binding.instruction,
+                followUpIds: binding.followUpIds,
+                ...(found.step.dependsOn && found.step.dependsOn.length > 0 ? { dependsOn: found.step.dependsOn } : {}),
+                ...(found.step.unlocks && found.step.unlocks.length > 0 ? { unlocks: found.step.unlocks } : {}),
+            }];
+    });
+    const followUpItems = followUps.flatMap((followUp) => {
+        if (includedStepIds.has(followUp.id))
+            return [];
+        includedStepIds.add(followUp.id);
+        return [{
+                id: `resume-${followUp.id}`,
+                kind: 'run_follow_up',
+                phaseId: followUp.phaseId,
+                stepId: followUp.id,
+                status: followUp.status,
+                label: followUp.label,
+                ...(followUp.command ? { command: followUp.command } : {}),
+                ...(followUp.tool ? { tool: followUp.tool } : {}),
+                ...(followUp.args ? { args: followUp.args } : {}),
+                ...(followUp.blockedBy && followUp.blockedBy.length > 0 ? { blockedBy: followUp.blockedBy } : {}),
+                ...(followUp.dependsOn && followUp.dependsOn.length > 0 ? { dependsOn: followUp.dependsOn } : {}),
+            }];
+    });
+    const currentCommand = current?.step.command;
+    const proofItems = stepsForPhase(plan, 'proof')
+        .filter(({ step }) => step.command && step.command !== currentCommand)
+        .map(({ phase, step }) => resumeChecklistItemFromStep(phase, step, 'run_proof', step.id));
+    const doneItems = stepsForPhase(plan, 'done_when')
+        .map(({ phase, step }) => resumeChecklistItemFromStep(phase, step, 'confirm_done', step.id));
+    return [
+        ...(currentItem ? [currentItem] : []),
+        ...inputItems,
+        ...followUpItems,
+        ...proofItems,
+        ...doneItems,
+    ];
+}
+function resumeChecklistItemFromStep(phase, step, kind, stepId) {
+    return {
+        id: `resume-${stepId}`,
+        kind,
+        phaseId: phase.id,
+        stepId,
+        status: step.status,
+        label: step.label,
+        ...(step.command ? { command: step.command } : {}),
+        ...(step.tool ? { tool: step.tool } : {}),
+        ...(step.args ? { args: step.args } : {}),
+        ...(step.placeholder ? { placeholder: step.placeholder } : {}),
+        ...(step.instruction ? { instruction: step.instruction } : {}),
+        ...(step.blockedBy && step.blockedBy.length > 0 ? { blockedBy: step.blockedBy } : {}),
+        ...(step.dependsOn && step.dependsOn.length > 0 ? { dependsOn: step.dependsOn } : {}),
+        ...(step.unlocks && step.unlocks.length > 0 ? { unlocks: step.unlocks } : {}),
+    };
+}
+function currentChecklistKind(step) {
+    if (step.kind === 'input')
+        return 'resolve_input';
+    if (step.kind === 'proof')
+        return 'run_proof';
+    if (step.kind === 'criterion')
+        return 'confirm_done';
+    return 'run_current';
+}
+function resumeInputBindings(plan, cursor) {
+    const ids = uniqueStrings([
+        ...(cursor.kind === 'input' ? [cursor.stepId] : []),
+        ...(cursor.unlocks ?? []),
+    ]);
+    return ids.flatMap((id) => {
+        const found = findStepInPlan(plan, id);
+        if (!found || found.step.kind !== 'input' || !found.step.placeholder || !found.step.instruction)
+            return [];
+        const followUpIds = (found.step.unlocks ?? []).filter((unlockedId) => findStepInPlan(plan, unlockedId)?.phase.id === 'follow_up');
+        return [{
+                inputId: found.step.id,
+                label: found.step.label,
+                placeholder: found.step.placeholder,
+                instruction: found.step.instruction,
+                followUpIds,
+            }];
+    });
+}
+function resumeFollowUps(plan, cursor) {
+    const followUpIds = new Set();
+    for (const id of cursor.unlocks ?? []) {
+        const found = findStepInPlan(plan, id);
+        if (!found)
+            continue;
+        if (found.phase.id === 'follow_up')
+            followUpIds.add(found.step.id);
+        for (const unlockedId of found.step.unlocks ?? []) {
+            const unlocked = findStepInPlan(plan, unlockedId);
+            if (unlocked?.phase.id === 'follow_up')
+                followUpIds.add(unlocked.step.id);
+        }
+    }
+    return Array.from(followUpIds).flatMap((id) => {
+        const found = findStepInPlan(plan, id);
+        if (!found)
+            return [];
+        return [{
+                id: found.step.id,
+                phaseId: found.phase.id,
+                kind: found.step.kind,
+                status: found.step.status,
+                label: found.step.label,
+                ...(found.step.command ? { command: found.step.command } : {}),
+                ...(found.step.tool ? { tool: found.step.tool } : {}),
+                ...(found.step.args ? { args: found.step.args } : {}),
+                ...(found.step.blockedBy && found.step.blockedBy.length > 0 ? { blockedBy: found.step.blockedBy } : {}),
+                ...(found.step.dependsOn && found.step.dependsOn.length > 0 ? { dependsOn: found.step.dependsOn } : {}),
+            }];
+    });
+}
+function resumeToolCall(plan, cursor) {
+    const found = findStepInPlan(plan, cursor.stepId);
+    if (!found?.step.tool || !argsAreReady(found.step.args))
+        return undefined;
+    return {
+        tool: found.step.tool,
+        ...(typeof found.step.args !== 'undefined' ? { args: found.step.args } : {}),
+    };
+}
+function resolveResumeReferences(plan, ids) {
+    if (!ids || ids.length === 0)
+        return [];
+    const references = [];
+    for (const id of ids) {
+        const found = findStepInPlan(plan, id);
+        if (!found)
+            continue;
+        references.push({
+            id: found.step.id,
+            phaseId: found.phase.id,
+            kind: found.step.kind,
+            status: found.step.status,
+            label: found.step.label,
+            ...(found.step.instruction ? { instruction: found.step.instruction } : {}),
+            ...(found.step.command ? { command: found.step.command } : {}),
+            ...(found.step.placeholder ? { placeholder: found.step.placeholder } : {}),
+        });
+    }
+    return references;
+}
+function findStepInPlan(plan, id) {
+    for (const phase of plan.phases) {
+        for (const step of phase.steps) {
+            if (step.id === id)
+                return { phase, step };
+        }
+    }
+    return undefined;
+}
+function stepsForPhase(plan, phaseId) {
+    const phase = plan.phases.find((item) => item.id === phaseId);
+    return phase ? phase.steps.map((step) => ({ phase, step })) : [];
+}
+function resumeUnlocksSentence(unlocks, rawIds) {
+    if (unlocks.length > 0)
+        return ` This can unlock ${unlocks.map(formatResumeReferenceLabel).join(', ')}.`;
+    return rawIds && rawIds.length > 0 ? ` This can unlock ${rawIds.join(', ')}.` : '';
+}
+function resumeBlockersSentence(blockedBy, rawIds) {
+    if (blockedBy.length > 0)
+        return ` Blocked by ${blockedBy.map(formatResumeReferenceLabel).join(', ')}.`;
+    return rawIds && rawIds.length > 0 ? ` Blocked by ${rawIds.join(', ')}.` : '';
+}
+function formatResumeReferenceLabel(reference) {
+    return `${reference.id} (${reference.label})`;
+}
+function renderRunbookResumeLines(resume) {
+    const lines = ['## Resume'];
+    if (resume.commandBlock) {
+        lines.push('Run now:', '```sh', resume.commandBlock, '```');
+    }
+    else {
+        lines.push(`Do now: ${resume.instruction}`);
+    }
+    if (resume.toolCall) {
+        lines.push(`MCP call: ${formatRunbookToolCall(resume.toolCall)}`);
+    }
+    if (resume.unlocks && resume.unlocks.length > 0) {
+        lines.push('After running, resolve:', ...resume.unlocks.map((reference) => `- ${formatRunbookResumeReference(reference)}`));
+    }
+    if (resume.inputBindings && resume.inputBindings.length > 0) {
+        lines.push('Template inputs:', ...resume.inputBindings.map((binding) => `- ${formatRunbookInputBinding(binding)}`));
+    }
+    if (resume.checklist && resume.checklist.length > 0) {
+        lines.push('Resume checklist:', ...resume.checklist.map((item) => `- ${formatRunbookChecklistItem(item)}`));
+    }
+    if (resume.remainingProofItems && resume.remainingProofItems.length > 0) {
+        lines.push('Proof queue:', ...resume.remainingProofItems.map((item) => `- ${formatRunbookProofItem(item)}`));
+    }
+    if (resume.remainingProofCommands && resume.remainingProofCommands.length > 0) {
+        lines.push('Remaining proof:', ...resume.remainingProofCommands.map((command) => `- \`${command}\``));
+    }
+    if (resume.remainingProofToolCalls && resume.remainingProofToolCalls.length > 0) {
+        lines.push('MCP proof calls:', ...resume.remainingProofToolCalls.map((toolCall) => `- ${formatRunbookProofToolCall(toolCall)}`));
+    }
+    if (resume.followUps && resume.followUps.length > 0) {
+        lines.push('Then use:', ...resume.followUps.map((followUp) => `- ${formatRunbookFollowUp(followUp)}`));
+    }
+    if (resume.blockedBy && resume.blockedBy.length > 0) {
+        lines.push('Blocked by:', ...resume.blockedBy.map((reference) => `- ${formatRunbookResumeReference(reference)}`));
+    }
+    lines.push(`Prompt: ${resume.prompt}`);
+    return lines;
+}
+function formatRunbookResumeReference(reference) {
+    const detail = reference.instruction ?? reference.command ?? reference.label;
+    return `${reference.id} (${reference.label}): ${detail}`;
+}
+function formatRunbookInputBinding(binding) {
+    return `${binding.placeholder} -> ${binding.inputId} (${binding.label}): ${binding.instruction}`;
+}
+function formatRunbookChecklistItem(item) {
+    const action = item.command
+        ?? (item.placeholder && item.instruction ? `${item.placeholder} -> ${item.instruction}` : undefined)
+        ?? item.instruction
+        ?? item.label;
+    return `[${item.status}] ${item.kind} ${item.stepId}: ${action}${formatRunbookChecklistAnnotation(item)}`;
+}
+function formatRunbookChecklistAnnotation(item) {
+    if (item.tool) {
+        return ` (MCP: ${formatRunbookToolCall({ tool: item.tool, ...(typeof item.args !== 'undefined' ? { args: item.args } : {}) })})`;
+    }
+    if (item.kind === 'run_proof' && item.command)
+        return ' (CLI only)';
+    return '';
+}
+function formatRunbookToolCall(toolCall) {
+    return typeof toolCall.args !== 'undefined'
+        ? `${toolCall.tool} ${JSON.stringify(toolCall.args)}`
+        : toolCall.tool;
+}
+function formatRunbookProofToolCall(toolCall) {
+    return `${toolCall.stepId}: ${formatRunbookToolCall(toolCall)}`;
+}
+function formatRunbookProofItem(item) {
+    const proofAction = item.toolCall ? `MCP: ${formatRunbookToolCall(item.toolCall)}` : 'CLI only';
+    return `${item.stepId}: \`${item.command}\` (${proofAction})`;
+}
+function formatRunbookFollowUp(followUp) {
+    const action = followUp.command
+        ?? (followUp.tool ? formatRunbookToolCall({ tool: followUp.tool, ...(typeof followUp.args !== 'undefined' ? { args: followUp.args } : {}) }) : followUp.label);
+    return `${followUp.id} (${followUp.label}): ${action}`;
+}
+function renderRunbookCursorLines(cursor) {
+    const lines = [
+        '## Current Cursor',
+        `- Step: ${cursor.stepId} in ${cursor.phaseId}`,
+    ];
+    if (cursor.command) {
+        lines.push(`- Command: \`${cursor.command}\``);
+    }
+    else if (cursor.instruction) {
+        lines.push(`- Input: ${cursor.instruction}`);
+    }
+    else {
+        lines.push(`- Label: ${cursor.label}`);
+    }
+    if (cursor.tool) {
+        lines.push(`- MCP call: ${formatRunbookToolCall({ tool: cursor.tool, ...(typeof cursor.args !== 'undefined' ? { args: cursor.args } : {}) })}`);
+    }
+    if (cursor.blockedBy && cursor.blockedBy.length > 0) {
+        lines.push(`- Blocked by: ${cursor.blockedBy.join(', ')}`);
+    }
+    if (cursor.unlocks && cursor.unlocks.length > 0) {
+        lines.push(`- Unlocks: ${cursor.unlocks.join(', ')}`);
+    }
+    lines.push(`- Why: ${cursor.reason}`);
+    return lines;
+}
+function buildMissionExecutionPlan(input) {
+    const phases = [];
+    const readyStepIds = input.readyActions.map((_, index) => `ready-${index + 1}`);
+    const inputStepIdsByPlaceholder = new Map(input.unresolvedInputs.map((item, index) => [item.placeholder, `input-${index + 1}`]));
+    const nextActionStep = actionToExecutionStep('next-action-1', input.primaryAction);
+    phases.push({
+        id: 'next_action',
+        title: 'Next Action',
+        status: nextActionStep.status,
+        steps: [nextActionStep],
+    });
+    if (input.readyActions.length > 0) {
+        phases.push({
+            id: 'ready_now',
+            title: 'Ready Commands',
+            status: 'ready',
+            steps: input.readyActions.map((action, index) => {
+                const step = actionToExecutionStep(`ready-${index + 1}`, action);
+                const unlockedInputs = Array.from(inputStepIdsByPlaceholder.values());
+                if (index === 0 && unlockedInputs.length > 0)
+                    step.unlocks = unlockedInputs;
+                return step;
+            }),
+        });
+    }
+    if (input.unresolvedInputs.length > 0) {
+        phases.push({
+            id: 'resolve_inputs',
+            title: 'Resolve Inputs',
+            status: 'blocked',
+            steps: input.unresolvedInputs.map((item, index) => {
+                const id = `input-${index + 1}`;
+                const followUps = followUpIdsForPlaceholder(input.actionPlan, item.placeholder);
+                return {
+                    id,
+                    kind: 'input',
+                    status: 'blocked',
+                    label: item.name,
+                    ...(readyStepIds[0] ? { dependsOn: [readyStepIds[0]] } : {}),
+                    ...(followUps.length > 0 ? { unlocks: followUps } : {}),
+                    placeholder: item.placeholder,
+                    instruction: item.instruction,
+                };
+            }),
+        });
+    }
+    const pendingActions = input.actionPlan.filter((action) => !isReadyAction(action));
+    if (pendingActions.length > 0) {
+        phases.push({
+            id: 'follow_up',
+            title: 'Follow Up',
+            status: 'pending',
+            steps: pendingActions.map((action, index) => {
+                const step = actionToExecutionStep(`follow-up-${index + 1}`, action);
+                const blockedBy = placeholdersInAction(action)
+                    .map((placeholder) => inputStepIdsByPlaceholder.get(placeholder))
+                    .filter((id) => typeof id === 'string');
+                if (blockedBy.length > 0) {
+                    step.blockedBy = blockedBy;
+                    step.dependsOn = uniqueStrings([readyStepIds[0] ?? '', ...blockedBy].filter(Boolean));
+                }
+                return step;
+            }),
+        });
+    }
+    if (input.proofCommands.length > 0) {
+        phases.push({
+            id: 'proof',
+            title: 'Proof',
+            status: 'ready',
+            steps: input.proofCommands.map((command, index) => {
+                const toolCall = proofCommandToolCall(command);
+                return {
+                    id: `proof-${index + 1}`,
+                    kind: 'proof',
+                    status: 'ready',
+                    label: command,
+                    command,
+                    ...(toolCall ? {
+                        tool: toolCall.tool,
+                        ...(typeof toolCall.args !== 'undefined' ? { args: toolCall.args } : {}),
+                    } : {}),
+                };
+            }),
+        });
+    }
+    phases.push({
+        id: 'done_when',
+        title: 'Done When',
+        status: 'pending',
+        steps: input.successCriteria.map((criterion, index) => ({
+            id: `criterion-${index + 1}`,
+            kind: 'criterion',
+            status: 'pending',
+            label: criterion,
+        })),
+    });
+    const cursor = executionCursor(phases);
+    return {
+        summary: executionPlanSummary(input.readyActions.length, input.unresolvedInputs.length, input.proofCommands.length),
+        currentPhase: cursor.phaseId,
+        cursor,
+        phases,
+    };
+}
+function actionToExecutionStep(id, action) {
+    const step = {
+        id,
+        kind: 'tool',
+        status: executionStatusForAction(action),
+        label: action.label,
+    };
+    if (typeof action.command === 'string')
+        step.command = action.command;
+    if (typeof action.tool === 'string')
+        step.tool = action.tool;
+    if (action.args)
+        step.args = action.args;
+    return step;
+}
+function followUpIdsForPlaceholder(actionPlan, placeholder) {
+    return actionPlan
+        .filter((action) => !isReadyAction(action))
+        .map((action, index) => ({ action, id: `follow-up-${index + 1}` }))
+        .filter(({ action }) => placeholdersInAction(action).includes(placeholder))
+        .map(({ id }) => id);
+}
+function placeholdersInAction(action) {
+    const placeholders = new Set();
+    if (typeof action.command === 'string') {
+        for (const match of action.command.matchAll(/<[^<>]+>/g))
+            placeholders.add(match[0]);
+    }
+    collectPlaceholdersFromValue(action.args, placeholders);
+    return Array.from(placeholders);
+}
+function collectPlaceholdersFromValue(value, placeholders) {
+    if (typeof value === 'string') {
+        if (isPlaceholder(value))
+            placeholders.add(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectPlaceholdersFromValue(item, placeholders);
+        return;
+    }
+    if (value && typeof value === 'object') {
+        for (const item of Object.values(value))
+            collectPlaceholdersFromValue(item, placeholders);
+    }
+}
+function executionStatusForAction(action) {
+    if (isReadyAction(action))
+        return 'ready';
+    if ((typeof action.command === 'string' && !isRunnableCommand(action.command)) || !argsAreReady(action.args)) {
+        return 'blocked';
+    }
+    return 'pending';
+}
+function executionCursor(phases) {
+    const selected = findExecutionStep(phases, (phase, step) => phase.id === 'ready_now' && step.status === 'ready' && typeof step.command === 'string')
+        ?? findExecutionStep(phases, (phase, step) => phase.id === 'resolve_inputs' && step.status === 'blocked')
+        ?? findExecutionStep(phases, (phase, step) => phase.id === 'proof' && step.status === 'ready')
+        ?? findExecutionStep(phases, (phase) => phase.id === 'done_when')
+        ?? findExecutionStep(phases, (phase) => phase.id === 'next_action');
+    if (!selected) {
+        return {
+            phaseId: 'done_when',
+            stepId: 'criterion-1',
+            status: 'pending',
+            kind: 'criterion',
+            label: 'The next action is complete and verified.',
+            reason: 'Use this criterion to decide when the task is complete.',
+        };
+    }
+    return {
+        phaseId: selected.phase.id,
+        stepId: selected.step.id,
+        status: selected.step.status,
+        kind: selected.step.kind,
+        label: selected.step.label,
+        ...(selected.step.command ? { command: selected.step.command } : {}),
+        ...(selected.step.tool ? { tool: selected.step.tool } : {}),
+        ...(typeof selected.step.args !== 'undefined' ? { args: selected.step.args } : {}),
+        ...(selected.step.instruction ? { instruction: selected.step.instruction } : {}),
+        ...(selected.step.placeholder ? { placeholder: selected.step.placeholder } : {}),
+        ...(selected.step.blockedBy && selected.step.blockedBy.length > 0 ? { blockedBy: selected.step.blockedBy } : {}),
+        ...(selected.step.unlocks && selected.step.unlocks.length > 0 ? { unlocks: selected.step.unlocks } : {}),
+        reason: executionCursorReason(selected.step),
+    };
+}
+function findExecutionStep(phases, predicate) {
+    for (const phase of phases) {
+        for (const step of phase.steps) {
+            if (predicate(phase, step))
+                return { phase, step };
+        }
+    }
+    return undefined;
+}
+function executionCursorReason(step) {
+    if (step.status === 'ready' && step.kind === 'tool') {
+        return step.unlocks && step.unlocks.length > 0
+            ? 'Run this ready command next; it can unlock later inputs or follow-up steps.'
+            : 'Run this ready command next.';
+    }
+    if (step.status === 'blocked' && step.kind === 'input') {
+        return 'Resolve this blocked input before running dependent follow-up steps.';
+    }
+    if (step.status === 'ready' && step.kind === 'proof') {
+        return 'Run this proof command when action steps are complete.';
+    }
+    if (step.kind === 'criterion') {
+        return 'Use this criterion to decide when the task is complete.';
+    }
+    return 'Use this step as the current execution pointer.';
+}
+function executionPlanSummary(readyCount, inputCount, proofCount) {
+    const pieces = [`Run ${readyCount} ready ${pluralize(readyCount, 'step')}`];
+    if (inputCount > 0)
+        pieces.push(`resolve ${inputCount} input(s)`);
+    if (proofCount > 0)
+        pieces.push(`then gather ${proofCount} proof command(s)`);
+    return `${pieces.join(', ')}.`;
+}
+function pluralize(count, singular) {
+    return count === 1 ? singular : `${singular}s`;
+}
+function missionHandoff(currentStep, resume, nextAction, readyActions, needsInput, doneWhen, proofCommands, reviewGate) {
+    const readyProofCommands = resume.remainingProofCommands ?? proofCommands;
+    const readyProofToolCalls = resume.remainingProofToolCalls;
+    const readyProofItems = resume.remainingProofItems;
+    return {
+        currentStep,
+        resume,
+        reviewGate,
         nextAction,
         readyActions,
         needsInput,
         doneWhen,
         readyProof: {
             summary: READY_PROOF_SUMMARY,
-            commands: proofCommands,
+            commands: readyProofCommands,
+            ...(readyProofToolCalls && readyProofToolCalls.length > 0 ? { toolCalls: readyProofToolCalls } : {}),
+            ...(readyProofItems && readyProofItems.length > 0 ? { items: readyProofItems } : {}),
         },
     };
 }
-function missionHandoffPrompt(commandText, successCriteria, whyNow, unresolvedInputs, proofCommands) {
+function missionHandoffPrompt(resume, successCriteria, whyNow, unresolvedInputs, proofCommands, reviewGate) {
     const needsInput = unresolvedInputs.length > 0
         ? ` Needs input: ${unresolvedInputs.map((input) => `${input.name}=${input.placeholder}`).join(', ')}.`
         : '';
-    return `Next: ${commandText}. Done when: ${trimTrailingPunctuation(successCriteria[0] ?? 'The proof commands pass')}.${needsInput} Why: ${whyNow} Ready proof: ${READY_PROOF_SUMMARY} ${proofCommands.slice(0, 3).join(' && ')}.`;
+    const proofCommandText = (resume.remainingProofCommands ?? proofCommands).slice(0, 3).join(' && ');
+    const readyProof = proofCommandText.length > 0
+        ? ` Ready proof: ${READY_PROOF_SUMMARY} ${proofCommandText}.`
+        : ` Ready proof: ${READY_PROOF_SUMMARY}.`;
+    return `Resume: ${trimTrailingPunctuation(resume.prompt)}. Done when: ${trimTrailingPunctuation(successCriteria[0] ?? 'The proof commands pass')}.${needsInput} Why: ${whyNow}${readyProof}${handoffReviewGatePrompt(reviewGate)}`;
+}
+function handoffReviewGatePrompt(reviewGate) {
+    const decisions = reviewGate.decisions
+        .map((decision) => `${decision.label} => ${decision.reply}`)
+        .join('; ');
+    return ` Review gate: ${trimTrailingPunctuation(reviewGate.stopCondition)}. Reviewer replies: ${decisions}`;
 }
 function trimTrailingPunctuation(value) {
     return value.replace(/[.!?]+$/g, '');
@@ -1816,7 +2849,11 @@ function normalizePackageName(target) {
     return target.toLowerCase();
 }
 function escapeDoubleQuoted(value) {
-    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\$/g, '\\$')
+        .replace(/`/g, '\\`');
 }
 function quoteShellArg(value) {
     return /^[A-Za-z0-9_./:@-]+$/.test(value) ? value : `"${escapeDoubleQuoted(value)}"`;