@linimin/pi-letscook 0.1.66 → 0.1.67

package/extensions/completion/index.ts

@@ -18,7 +18,9 @@ import {
 	collectRecentDiscussionEntries,
 	collectRecentSessionMessages,
 	assessLatestCookHandoffProposal,
+	deriveCookContextProposalFromRecentDiscussion,
 	finalizeContextProposalAnalysis,
+	hasStructuredContextProposalSignal,
 	isWeakMissionAnchor,
 	missionAnchorsLikelyEquivalent,
 	missionAnchorsStrictlyEquivalent,
@@ -47,7 +49,8 @@ import {
 	maybeWriteContextProposalSnapshot,
 } from "./prompt-surfaces";
 import { toolCallBlockReason } from "./policy-guards";
-import { analyzeContextProposalWithAgent, generateCookHandoffWithAgent, runCompletionRole } from "./role-runner";
+import { analyzeContextProposalWithAgent, runCompletionRole } from "./role-runner";
+import { generateCookHandoffWithAgent } from "./role-runner";
 import {
 	applyLiveRoleEvent,
 	buildInlineRunningLines,
@@ -209,7 +212,7 @@ function maybeWriteTestSnapshot(targetPath: string | undefined, content: string)
 
 const COOK_MAIN_CHAT_RERUN_GUIDANCE = "Discuss changes in the main chat and rerun /cook.";
 const COOK_STRUCTURED_DISCUSSION_FAILURE_DETAIL =
-	"/cook failed closed because the primary-agent handoff step could not prepare a concrete startup handoff from the current task context. Clarify the mission, first slice, or verification intent in the main chat, then rerun /cook.";
+	"/cook failed closed because the startup-plan step could not prepare a concrete workflow startup plan from the current task context. Clarify the mission, scope, acceptance, or verification intent in the main chat, then rerun /cook.";
 
 function isWorkflowDone(snapshot: CompletionStateSnapshot | undefined): boolean {
 	return asString(snapshot?.state?.continuation_policy) === "done";
@@ -418,10 +421,23 @@ async function deriveCookContextProposal(
 			`latest verified slice: ${asString(snapshot.state?.latest_verified_slice) ?? "(none)"}`,
 			`active slice goal: ${asString(snapshot.active?.goal) ?? "(none)"}`,
 			`active slice why_now: ${asString(snapshot.active?.why_now) ?? "(none)"}`,
+			`approved startup plan summary: ${asString(snapshot.startupPlan?.goal_text) ?? "(none)"}`,
 			`verification goal: ${asString(snapshot.verificationEvidence?.goal) ?? "(none)"}`,
 			`verification summary: ${asString(snapshot.verificationEvidence?.summary) ?? "(none)"}`,
 		]
 		: [];
+	const workflowContext = snapshot
+		? {
+			currentMissionAnchor: asString(snapshot.state?.mission_anchor) ?? asString(snapshot.plan?.mission_anchor) ?? asString(snapshot.active?.mission_anchor),
+			latestCompletedSlice: asString(snapshot.state?.latest_completed_slice),
+			latestVerifiedSlice: asString(snapshot.state?.latest_verified_slice),
+			activeSliceGoal: asString(snapshot.active?.goal),
+			activeSliceWhyNow: asString(snapshot.active?.why_now),
+			verificationGoal: asString(snapshot.verificationEvidence?.goal),
+			verificationSummary: asString(snapshot.verificationEvidence?.summary),
+			continuationPolicy: asString(snapshot.state?.continuation_policy),
+		}
+		: undefined;
 	const raw = await generateCookHandoffWithAgent({
 		ctx,
 		projectName,
@@ -434,20 +450,49 @@ async function deriveCookContextProposal(
 		getCtxHasUI,
 		getCtxUi,
 	});
-	if (!raw) return {};
-	const generated = assessLatestCookHandoffProposal([
-		{ role: "assistant", text: raw, messageId: "generated-primary-agent-handoff", timestampMs: Date.now(), isCommand: false },
-	], projectName, {
-		asString,
-		asStringArray,
-		assessMissionAnchor,
-		normalizeMissionAnchorText,
-		isWeakMissionAnchor,
-		missionAnchorsStrictlyEquivalent,
-		stripCodeBlocks,
-	});
-	if (generated.status === "startable") return { proposal: generated.proposal };
-	if (generated.status === "fresh_but_not_startable") return { blockedFailureMessage: generated.message };
+	if (raw) {
+		const generated = assessLatestCookHandoffProposal([
+			{ role: "assistant", text: raw, messageId: "generated-primary-agent-handoff", timestampMs: Date.now(), isCommand: false },
+		], projectName, {
+			asString,
+			asStringArray,
+			assessMissionAnchor,
+			normalizeMissionAnchorText,
+			isWeakMissionAnchor,
+			missionAnchorsStrictlyEquivalent,
+			stripCodeBlocks,
+		});
+		if (generated.status === "startable") return { proposal: generated.proposal };
+		if (generated.status === "fresh_but_not_startable") return { blockedFailureMessage: generated.message };
+	}
+	const canFallbackToDiscussionProposal =
+		recentEntries.length >= 2 || recentEntries.some((entry) => hasStructuredContextProposalSignal(entry.text, stripCodeBlocks));
+	if (canFallbackToDiscussionProposal) {
+		const fromDiscussion = await deriveCookContextProposalFromRecentDiscussion(projectName, recentEntries, {
+			asString,
+			asStringArray,
+			assessMissionAnchor,
+			normalizeMissionAnchorText,
+			isWeakMissionAnchor,
+			missionAnchorsStrictlyEquivalent,
+			stripCodeBlocks,
+			analyzeContextProposal: async (candidateEntries) =>
+				await analyzeContextProposalWithAgent({
+					ctx,
+					projectName,
+					recentEntries: candidateEntries,
+					workflowContextLines,
+					liveRoleActivityByRoot,
+					completionStatusKey: COMPLETION_STATUS_KEY,
+					safeUiCall,
+					getCtxCwd,
+					getCtxHasUI,
+					getCtxUi,
+				}),
+			workflowContext,
+		});
+		if (fromDiscussion) return { proposal: fromDiscussion };
+	}
 	return {};
 }
 
@@ -485,13 +530,19 @@ async function confirmContextProposal(
 async function scaffoldCompletionFiles(
 	root: string,
 	missionAnchor: string,
-	options?: { analysis?: ContextProposalAnalysis; continuationReason?: string; advisoryStartupBrief?: JsonRecord },
+	options?: {
+		analysis?: ContextProposalAnalysis;
+		continuationReason?: string;
+		advisoryStartupBrief?: JsonRecord;
+		approvedStartupPlan?: JsonRecord;
+	},
 ) {
 	const routing = finalizeContextProposalAnalysis(options?.analysis, [missionAnchor]);
 	return await scaffoldCompletionFilesOnDisk(root, missionAnchor, {
 		analysis: { taskType: routing.taskType, evaluationProfile: routing.evaluationProfile },
 		continuationReason: options?.continuationReason,
 		advisoryStartupBrief: options?.advisoryStartupBrief,
+		approvedStartupPlan: options?.approvedStartupPlan,
 	});
 }
 
@@ -654,6 +705,20 @@ function verificationEvidenceContext(snapshot: CompletionStateSnapshot) {
 	};
 }
 
+function startupPlanContext(snapshot: CompletionStateSnapshot) {
+	const startupPlan = snapshot.startupPlan;
+	return {
+		path: path.relative(snapshot.files.root, snapshot.files.startupPlanPath) || ".agent/startup-plan.json",
+		status: startupPlan ? "present" : "missing",
+		source: asString(startupPlan?.source),
+		plannedSurfaces: asStringArray(startupPlan?.planned_surfaces),
+		verificationIntent: asStringArray(startupPlan?.verification_intent),
+		summary:
+			asString(startupPlan?.goal_text) ??
+			(startupPlan ? "Approved startup plan is present but its goal_text is missing." : "Approved startup plan is missing."),
+	};
+}
+
 function buildEvaluationRoleContextLines(snapshot: CompletionStateSnapshot, role: RubricEvaluationRole): string[] {
 	return buildExtractedEvaluationRoleContextLines(snapshot, role, {
 		asString,
@@ -684,6 +749,7 @@ function composeSystemReminder(snapshot: CompletionStateSnapshot, sliceHistory:
 	const exactActiveContract = activeCarriesExactHandoff(snapshot.active);
 	const activeContractDrift = activeSliceContractDriftSummary(snapshot);
 	const evidence = verificationEvidenceContext(snapshot);
+	const startupPlan = startupPlanContext(snapshot);
 	const activePriorityLine = activePriority !== undefined ? `Active slice priority: ${activePriority}` : undefined;
 	const activeWhyNowLine = activeWhyNow ? `Active slice why_now: ${activeWhyNow}` : undefined;
 	const implementationSurfacesLine =
@@ -713,6 +779,7 @@ function composeSystemReminder(snapshot: CompletionStateSnapshot, sliceHistory:
 		implementationSurfacesLine,
 		verificationCommandsLine,
 		evidence,
+		startupPlan,
 		evaluationRoleReminderText: isRubricEvaluationRole(nextRole) ? buildEvaluationRoleReminderText(snapshot, nextRole) : undefined,
 	});
 }
@@ -732,17 +799,19 @@ function buildPostCompactionDriverInstructions(snapshot: CompletionStateSnapshot
 	const exactActiveContract = activeCarriesExactHandoff(snapshot.active);
 	const activeContractDrift = activeSliceContractDriftSummary(snapshot);
 	const evidence = verificationEvidenceContext(snapshot);
+	const startupPlan = startupPlanContext(snapshot);
 	const lines = [
 		"POST-COMPACTION RECOVERY MODE is active.",
 		`Compaction marker time: ${markerAt}`,
 		"Treat the previous conversation as lossy continuity support only.",
-		"Before taking any substantive action, re-read .agent/state.json, .agent/plan.json, .agent/active-slice.json, .agent/slice-history.jsonl, .agent/stop-check-history.jsonl, and .agent/verification-evidence.json from disk.",
+		"Before taking any substantive action, re-read .agent/state.json, .agent/startup-plan.json, .agent/plan.json, .agent/active-slice.json, .agent/slice-history.jsonl, .agent/stop-check-history.jsonl, and .agent/verification-evidence.json from disk.",
 		`Canonical task_type is currently: ${taskType}`,
 		`Canonical evaluation_profile is currently: ${evaluationProfile}`,
 		`Canonical next mandatory role is currently: ${nextRole}`,
 		`Canonical next mandatory action is currently: ${nextAction}`,
 		`Canonical continuation policy is currently: ${continuation}`,
 		`Canonical active slice is currently: ${activeSliceId}`,
+		`Canonical approved startup plan is currently: ${startupPlan.path} (${startupPlan.status})`,
 		`Canonical verification evidence artifact is currently: ${evidence.path} (${evidence.status})`,
 		"Do not trust pre-compaction memory over canonical files.",
 		"If the canonical state is ambiguous, inconsistent, missing, or stale after re-reading it, your first mandatory action is to dispatch completion-regrounder rather than guessing.",
@@ -757,6 +826,10 @@ function buildPostCompactionDriverInstructions(snapshot: CompletionStateSnapshot
 	if (activeWhyNow) lines.push(`Canonical active-slice why_now is currently: ${activeWhyNow}`);
 	if (implementationSurfaces.length > 0) lines.push(`Canonical implementation surfaces are currently: ${implementationSurfaces.join(", ")}`);
 	if (verificationCommands.length > 0) lines.push(`Canonical verification commands are currently: ${verificationCommands.join(" | ")}`);
+	if (startupPlan.source) lines.push(`Canonical approved startup plan source is currently: ${startupPlan.source}`);
+	if (startupPlan.plannedSurfaces.length > 0) lines.push(`Canonical approved startup plan surfaces are currently: ${startupPlan.plannedSurfaces.join(" | ")}`);
+	if (startupPlan.verificationIntent.length > 0) lines.push(`Canonical approved startup plan verification intent is currently: ${startupPlan.verificationIntent.join(" | ")}`);
+	lines.push(`Canonical approved startup plan summary is currently: ${startupPlan.summary}`);
 	if (evidence.subjectType) lines.push(`Canonical verification evidence subject is currently: ${evidence.subjectType}`);
 	if (evidence.outcome) lines.push(`Canonical verification evidence outcome is currently: ${evidence.outcome}`);
 	if (evidence.recordedAt) lines.push(`Canonical verification evidence recorded_at is currently: ${evidence.recordedAt}`);
@@ -847,6 +920,7 @@ function composeResumeCapsule(snapshot: CompletionStateSnapshot, sliceHistory: J
 	const verificationCommands = asStringArray(snapshot.active?.verification_commands);
 	const remainingBefore = asStringArray(snapshot.active?.remaining_contract_ids_before);
 	const evidence = verificationEvidenceContext(snapshot);
+	const startupPlan = startupPlanContext(snapshot);
 	const implementationSurfacesLine =
 		implementationSurfaces.length > 0 ? `- implementation_surfaces: ${implementationSurfaces.join(" | ")}` : undefined;
 	const verificationCommandsLine =
@@ -867,6 +941,7 @@ function composeResumeCapsule(snapshot: CompletionStateSnapshot, sliceHistory: J
 		activeSliceMatchesPlan: activeSliceMatchesPlan(snapshot),
 		activeSliceContractDrift: activeSliceContractDriftSummary(snapshot),
 		implementerHandoffSnapshot: handoffSnapshotState(snapshot.active),
+		startupPlan,
 		evidence,
 		activeSlice: {
 			sliceId: asString(snapshot.active?.slice_id) ?? asString(snapshot.activeSlice?.slice_id),
@@ -904,11 +979,11 @@ function completionKickoff(
 			: intent === "refocus" && missionAnchor
 				? `Updated canonical mission anchor:\n${missionAnchor}\n\nWorkflow intent:\n- The user explicitly refocused the workflow before this kickoff.\n- Re-read canonical .agent/** state and continue from the refocused mission.\n\n`
 				: "";
-	return `/skill:completion-protocol Start or continue the completion workflow for this repo.\n\nBefore acting, read:\n- ${SKILL_PATH}\n- ${REFERENCE_PATH}\n\nCanonical routing profile:\n- task_type: ${taskType}\n- evaluation_profile: ${evaluationProfile}\n\nUser goal:\n${goal}\n\n${intentBlock}Driver instructions:\n- Canonical truth is in .agent/**. Re-read .agent/state.json, .agent/plan.json, .agent/active-slice.json, and .agent/verification-evidence.json before acting when they exist.\n- If tracked completion contract files are missing or onboarding is required, invoke completion_role with role completion-bootstrapper.\n- Otherwise follow the mandatory dispatch rules from completion-protocol.\n- For selected, in-progress, committed, or done slices, treat .agent/active-slice.json as the canonical implementation contract and route to completion-regrounder if it drifts from the selected plan slice or the exact handoff is unclear.\n- Consume .agent/verification-evidence.json instead of temp-only verification summaries when it is populated.\n- Use completion_role for all completion-* role work. Do not directly implement tracked product changes yourself.\n- Continue dispatching mandatory roles while continuation_policy == continue.\n- Only stop for the user when continuation_policy is await_user_input, blocked, paused, or done.`;
+	return `/skill:completion-protocol Start or continue the completion workflow for this repo.\n\nBefore acting, read:\n- ${SKILL_PATH}\n- ${REFERENCE_PATH}\n\nCanonical routing profile:\n- task_type: ${taskType}\n- evaluation_profile: ${evaluationProfile}\n\nUser goal:\n${goal}\n\n${intentBlock}Driver instructions:\n- Canonical truth is in .agent/**. Re-read .agent/state.json, .agent/startup-plan.json, .agent/plan.json, .agent/active-slice.json, and .agent/verification-evidence.json before acting when they exist.\n- Treat .agent/startup-plan.json as the approved startup plan captured at /cook. completion-regrounder should use it as planning input, then derive canonical slices from current repo truth.\n- If tracked completion contract files are missing or onboarding is required, invoke completion_role with role completion-bootstrapper.\n- Otherwise follow the mandatory dispatch rules from completion-protocol.\n- For selected, in-progress, committed, or done slices, treat .agent/active-slice.json as the canonical implementation contract and route to completion-regrounder if it drifts from the selected plan slice or the exact handoff is unclear.\n- Consume .agent/verification-evidence.json instead of temp-only verification summaries when it is populated.\n- Use completion_role for all completion-* role work. Do not directly implement tracked product changes yourself.\n- Continue dispatching mandatory roles while continuation_policy == continue.\n- Only stop for the user when continuation_policy is await_user_input, blocked, paused, or done.`;
 }
 
 function completionResumePrompt(taskType: string, evaluationProfile: string): string {
-	return `/skill:completion-protocol Resume the completion workflow from canonical state.\n\nBefore acting, read:\n- ${SKILL_PATH}\n- ${REFERENCE_PATH}\n\nCanonical routing profile:\n- task_type: ${taskType}\n- evaluation_profile: ${evaluationProfile}\n\nResume instructions:\n- Re-read .agent/state.json, .agent/plan.json, .agent/active-slice.json, and .agent/verification-evidence.json before acting.\n- If canonical state is missing, invalid, contradictory, stale, or ambiguous, route to completion-regrounder first.\n- For selected, in-progress, committed, or done slices, treat .agent/active-slice.json as the canonical implementation contract and route to completion-regrounder if it drifts from the selected plan slice or the exact handoff is unclear.\n- Consume .agent/verification-evidence.json instead of temp-only verification summaries when it is populated.\n- Continue from next_mandatory_role and next_mandatory_action.\n- Use completion_role for all completion-* role work.\n- Continue dispatching mandatory roles while continuation_policy == continue.\n- Only stop for the user when continuation_policy is await_user_input, blocked, paused, or done.`;
+	return `/skill:completion-protocol Resume the completion workflow from canonical state.\n\nBefore acting, read:\n- ${SKILL_PATH}\n- ${REFERENCE_PATH}\n\nCanonical routing profile:\n- task_type: ${taskType}\n- evaluation_profile: ${evaluationProfile}\n\nResume instructions:\n- Re-read .agent/state.json, .agent/startup-plan.json, .agent/plan.json, .agent/active-slice.json, and .agent/verification-evidence.json before acting.\n- Treat .agent/startup-plan.json as the approved workflow plan captured at /cook, then let completion-regrounder reconcile or rebuild canonical slices from repo truth when needed.\n- If canonical state is missing, invalid, contradictory, stale, or ambiguous, route to completion-regrounder first.\n- For selected, in-progress, committed, or done slices, treat .agent/active-slice.json as the canonical implementation contract and route to completion-regrounder if it drifts from the selected plan slice or the exact handoff is unclear.\n- Consume .agent/verification-evidence.json instead of temp-only verification summaries when it is populated.\n- Continue from next_mandatory_role and next_mandatory_action.\n- Use completion_role for all completion-* role work.\n- Continue dispatching mandatory roles while continuation_policy == continue.\n- Only stop for the user when continuation_policy is await_user_input, blocked, paused, or done.`;
 }
 
 export default function completionExtension(pi: ExtensionAPI) {
@@ -924,7 +999,7 @@ export default function completionExtension(pi: ExtensionAPI) {
 		structuredDiscussionFailureDetail: COOK_STRUCTURED_DISCUSSION_FAILURE_DETAIL,
 		mainChatRerunGuidance: COOK_MAIN_CHAT_RERUN_GUIDANCE,
 		cookCommandSpec: {
-			description: "/cook workflow: start or replace workflow only from an explicit primary-agent handoff, or resume the current workflow from canonical state",
+			description: "/cook workflow: capture the approved startup plan into .agent, let completion-regrounder split canonical slices, or resume the current workflow from canonical state",
 		},
 		buildContextProposalContinuationReason,
 		completionKickoff,

package/extensions/completion/prompt-surfaces.ts

@@ -24,6 +24,26 @@ export type AdvisoryStartupBrief = {
 	evaluation_profile?: string;
 };
 
+export type ApprovedStartupPlan = {
+	artifact_type: "completion-startup-plan";
+	schema_version: 1;
+	status: "approved";
+	source: AdvisoryStartupBrief["source"];
+	captured_at: string;
+	mission_anchor: string;
+	goal_text: string;
+	task_type?: string;
+	evaluation_profile?: string;
+	scope: string[];
+	constraints: string[];
+	acceptance: string[];
+	risks: string[];
+	notes: string[];
+	planned_surfaces: string[];
+	verification_intent: string[];
+	sequencing_hints: string[];
+};
+
 export function buildCookHandoffBoundaryReminder(): string {
 	return [
 		"You are in ordinary main chat unless the user explicitly runs /cook.",
@@ -33,10 +53,11 @@ export function buildCookHandoffBoundaryReminder(): string {
 		"In ordinary chat, do not load or follow completion-protocol, and do not call completion_role.",
 		"If the user wants direct implementation now, stay in ordinary chat and help directly instead of blocking on /cook.",
 		"If the user asks follow-up questions or wants to keep refining scope, continue helping naturally in ordinary chat.",
-		"If the user explicitly runs /cook, the extension should call a primary-agent handoff synthesis step from the current task context, then show Start/Cancel confirmation without making the user rerun /cook.",
-		"Do not expect /cook to infer or guess startup intent from recent discussion alone; /cook should use explicit primary-agent handoff data, whether it already exists or is synthesized in the same /cook entry.",
-		"Only provide a preview startup brief or ```cook_handoff``` capsule in ordinary chat when the user explicitly asks for that preview behavior.",
+		"If the user explicitly runs /cook, the extension should call a primary-agent startup-plan synthesis step from the current task context, show Start/Cancel confirmation in the same /cook entry, and only write the approved plan into .agent after Start.",
+		"Do not expect /cook to infer or guess startup intent from recent discussion alone; /cook should use primary-agent-authored startup-plan data, whether it already exists as preview intake or is synthesized in the same /cook entry.",
+		"Only provide a preview startup plan or ```cook_handoff``` capsule in ordinary chat when the user explicitly asks for that preview behavior.",
 		"Any preview capsule is startup intake for /cook only: do not present it as canonical .agent state, an active slice, or a persistent repo contract.",
+		"When /cook starts, the approved startup plan should be written into .agent and then handed to completion-regrounder so canonical slices can be derived from repo truth.",
 		"When you continue in ordinary chat, do not pretend /cook already started and do not silently rewrite discussion into canonical workflow state.",
 	].join(" ");
 }
@@ -88,6 +109,27 @@ function buildAdvisoryStartupBriefNotes(analysis: ContextProposalAnalysis): stri
 	return notes.length > 0 ? notes : ["No additional operator notes were derived from recent discussion."];
 }
 
+function startupPlanSourceForProposal(source: ContextProposal["source"]): AdvisoryStartupBrief["source"] {
+	return source === "handoff_capsule"
+		? "primary_agent_handoff"
+		: source === "deferred_primary_agent_handoff"
+			? "deferred_primary_agent_handoff"
+			: "recent_discussion";
+}
+
+function extractDelimitedNoteValues(notes: string[], prefix: string): string[] {
+	return notes.flatMap((note) => {
+		if (!note.startsWith(prefix)) return [];
+		return note.slice(prefix.length).split("|").map((item) => item.trim()).filter(Boolean);
+	});
+}
+
+function extractSequencingHints(notes: string[]): string[] {
+	return notes.filter((note) =>
+		note.startsWith("First slice goal:") || note.startsWith("First slice non-goals:") || note.startsWith("Why this slice first:"),
+	);
+}
+
 export function buildAdvisoryStartupBrief(args: {
 	proposal: Pick<ContextProposal, "goalText" | "mission" | "scope" | "constraints" | "acceptance" | "source">;
 	analysis: ContextProposalAnalysis;
@@ -95,12 +137,7 @@ export function buildAdvisoryStartupBrief(args: {
 }): AdvisoryStartupBrief {
 	return {
 		kind: "startup_brief",
-		source:
-			args.proposal.source === "handoff_capsule"
-				? "primary_agent_handoff"
-				: args.proposal.source === "deferred_primary_agent_handoff"
-					? "deferred_primary_agent_handoff"
-					: "recent_discussion",
+		source: startupPlanSourceForProposal(args.proposal.source),
 		confirmed: true,
 		captured_at: args.capturedAt ?? new Date().toISOString(),
 		goal_text: args.proposal.goalText,
@@ -115,6 +152,81 @@ export function buildAdvisoryStartupBrief(args: {
 	};
 }
 
+export function buildApprovedStartupPlan(args: {
+	proposal: Pick<ContextProposal, "goalText" | "mission" | "scope" | "constraints" | "acceptance" | "source">;
+	analysis: ContextProposalAnalysis;
+	missionAnchor?: string;
+	capturedAt?: string;
+}): ApprovedStartupPlan {
+	const capturedAt = args.capturedAt ?? new Date().toISOString();
+	const notes = buildAdvisoryStartupBriefNotes(args.analysis);
+	return {
+		artifact_type: "completion-startup-plan",
+		schema_version: 1,
+		status: "approved",
+		source: startupPlanSourceForProposal(args.proposal.source),
+		captured_at: capturedAt,
+		mission_anchor: args.missionAnchor ?? args.proposal.mission,
+		goal_text: args.proposal.goalText,
+		task_type: args.analysis.taskType,
+		evaluation_profile: args.analysis.evaluationProfile,
+		scope: [...args.proposal.scope],
+		constraints: [...args.proposal.constraints],
+		acceptance: [...args.proposal.acceptance],
+		risks: [...args.analysis.risks],
+		notes: [...notes],
+		planned_surfaces: extractDelimitedNoteValues(notes, "Implementation surfaces:"),
+		verification_intent: extractDelimitedNoteValues(notes, "Verification commands:"),
+		sequencing_hints: extractSequencingHints(notes),
+	};
+}
+
+export function buildApprovedStartupPlanMarkdown(plan: ApprovedStartupPlan): string {
+	const lines = [
+		"# Approved Startup Plan",
+		"",
+		`Mission anchor: ${plan.mission_anchor}`,
+		`Source: ${plan.source}`,
+		`Captured at: ${plan.captured_at}`,
+	];
+	if (plan.task_type) lines.push(`Task type: ${plan.task_type}`);
+	if (plan.evaluation_profile) lines.push(`Evaluation profile: ${plan.evaluation_profile}`);
+	lines.push("", "## Goal", "", plan.goal_text);
+	if (plan.scope.length > 0) {
+		lines.push("", "## Scope", "");
+		for (const item of plan.scope) lines.push(`- ${item}`);
+	}
+	if (plan.constraints.length > 0) {
+		lines.push("", "## Constraints", "");
+		for (const item of plan.constraints) lines.push(`- ${item}`);
+	}
+	if (plan.acceptance.length > 0) {
+		lines.push("", "## Acceptance", "");
+		for (const item of plan.acceptance) lines.push(`- ${item}`);
+	}
+	if (plan.risks.length > 0) {
+		lines.push("", "## Risks", "");
+		for (const item of plan.risks) lines.push(`- ${item}`);
+	}
+	if (plan.planned_surfaces.length > 0) {
+		lines.push("", "## Planned surfaces", "");
+		for (const item of plan.planned_surfaces) lines.push(`- ${item}`);
+	}
+	if (plan.verification_intent.length > 0) {
+		lines.push("", "## Verification intent", "");
+		for (const item of plan.verification_intent) lines.push(`- ${item}`);
+	}
+	if (plan.sequencing_hints.length > 0) {
+		lines.push("", "## Sequencing hints", "");
+		for (const item of plan.sequencing_hints) lines.push(`- ${item}`);
+	}
+	if (plan.notes.length > 0) {
+		lines.push("", "## Notes", "");
+		for (const item of plan.notes) lines.push(`- ${item}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
 export function buildContextProposalCritiqueText(analysis: ContextProposalAnalysis): string {
 	const lines: string[] = [];
 	if (analysis.critique.length > 0) {
@@ -147,7 +259,7 @@ export function buildContextProposalCritiqueText(analysis: ContextProposalAnalys
 		for (const item of analysis.suppressedNegatedTopics) lines.push(`- ${item}`);
 	}
 	if (lines.length === 0) {
-		return "No additional operator notes or risks were derived for this startup brief.";
+		return "No additional operator notes or risks were derived for this startup plan.";
 	}
 	return lines.join("\n");
 }
@@ -196,7 +308,7 @@ export function buildContextProposalConfirmationActions(mainChatRerunGuidance: s
 		{
 			id: "start",
 			label: "Start",
-			description: "Accept this startup brief and let /cook write or refocus canonical workflow state.",
+			description: "Accept this startup plan and let /cook write or refocus canonical workflow state.",
 		},
 		{
 			id: "cancel",
@@ -216,8 +328,8 @@ export function buildContextProposalConfirmationLayout(args: {
 }): ContextProposalConfirmationLayout {
 	return {
 		title: args.title,
-		intro: "Review the startup brief (mission, scope, constraints, acceptance, and notes/risks) plus the routing details before /cook writes canonical workflow state. This gate is approval-only: either Start it as-is or Cancel, discuss changes in the main chat, and rerun /cook.",
-		proposalHeading: "Startup brief",
+		intro: "Review the startup plan (mission, scope, constraints, acceptance, and notes/risks) plus the routing details before /cook writes canonical workflow state. This gate is approval-only: either Start it as-is or Cancel, discuss changes in the main chat, and rerun /cook.",
+		proposalHeading: "Startup plan",
 		proposalBody: buildContextProposalDisplayText(args.proposal),
 		critiqueHeading: "Notes and risks",
 		critiqueBody: buildContextProposalCritiqueText(args.analysis),
@@ -417,6 +529,15 @@ type CompletionVerificationEvidenceSummary = {
 	summary: string;
 };
 
+type CompletionStartupPlanSummary = {
+	path: string;
+	status: string;
+	source?: string;
+	plannedSurfaces: string[];
+	verificationIntent: string[];
+	summary: string;
+};
+
 export function buildSystemReminder(args: {
 	missionAnchor?: string;
 	taskType?: string;
@@ -440,11 +561,12 @@ export function buildSystemReminder(args: {
 	implementationSurfacesLine?: string;
 	verificationCommandsLine?: string;
 	evidence: CompletionVerificationEvidenceSummary;
+	startupPlan: CompletionStartupPlanSummary;
 	evaluationRoleReminderText?: string;
 }): string {
 	const lines = [
 		"Completion workflow detected.",
-		"Canonical truth lives in .agent/state.json, .agent/plan.json, .agent/active-slice.json, .agent/slice-history.jsonl, .agent/stop-check-history.jsonl, and .agent/verification-evidence.json.",
+		"Canonical truth lives in .agent/state.json, .agent/startup-plan.json, .agent/plan.json, .agent/active-slice.json, .agent/slice-history.jsonl, .agent/stop-check-history.jsonl, and .agent/verification-evidence.json.",
 		`Mission anchor: ${args.missionAnchor ?? "(unknown)"}`,
 		`Task type: ${args.taskType ?? "(missing)"}`,
 		`Evaluation profile: ${args.evaluationProfile ?? "(missing)"}`,
@@ -461,6 +583,7 @@ export function buildSystemReminder(args: {
 		"Only stop for the user when continuation_policy is await_user_input, blocked, paused, or done.",
 		"If canonical state is stale, invalid, ambiguous, or missing, route to completion-regrounder.",
 		"When recovering from compaction, prefer a deterministic restart from canonical files over conversational inference.",
+		`Approved startup plan: ${args.startupPlan.path} (${args.startupPlan.status})`,
 	];
 	if (args.exactActiveContract) {
 		lines.push("Selected/in-progress/committed/done .agent/active-slice.json is the canonical implementation contract.");
@@ -474,6 +597,14 @@ export function buildSystemReminder(args: {
 	else if (args.implementationSurfaces.length > 0) lines.push(`Active implementation surfaces: ${args.implementationSurfaces.join(", ")}`);
 	if (args.verificationCommandsLine) lines.push(args.verificationCommandsLine);
 	else if (args.verificationCommands.length > 0) lines.push(`Active verification commands: ${args.verificationCommands.join(" | ")}`);
+	if (args.startupPlan.source) lines.push(`Approved startup plan source: ${args.startupPlan.source}`);
+	if (args.startupPlan.plannedSurfaces.length > 0) {
+		lines.push(`Approved startup plan surfaces: ${args.startupPlan.plannedSurfaces.join(" | ")}`);
+	}
+	if (args.startupPlan.verificationIntent.length > 0) {
+		lines.push(`Approved startup plan verification intent: ${args.startupPlan.verificationIntent.join(" | ")}`);
+	}
+	lines.push(`Approved startup plan summary: ${args.startupPlan.summary}`);
 	lines.push(`Verification evidence artifact: ${args.evidence.path} (${args.evidence.status})`);
 	if (args.evidence.subjectType) lines.push(`Verification evidence subject: ${args.evidence.subjectType}`);
 	if (args.evidence.outcome) lines.push(`Verification evidence outcome: ${args.evidence.outcome}`);
@@ -502,6 +633,7 @@ export function buildResumeCapsule(args: {
 	activeSliceMatchesPlan: "yes" | "no" | "unknown";
 	activeSliceContractDrift: string;
 	implementerHandoffSnapshot: "present" | "missing_or_unclear";
+	startupPlan: CompletionStartupPlanSummary;
 	evidence: CompletionVerificationEvidenceSummary;
 	activeSlice: {
 		sliceId?: string;
@@ -544,6 +676,14 @@ export function buildResumeCapsule(args: {
 		`implementer_handoff_snapshot: ${args.implementerHandoffSnapshot}`,
 		`history_counts: reviewed=${args.history.reviewed}, audited=${args.history.audited}, accepted=${args.history.accepted}, reopened=${args.history.reopened}, judgments=${args.history.judgments}`,
 		"",
+		"startup_plan:",
+		`- path: ${args.startupPlan.path}`,
+		`- status: ${args.startupPlan.status}`,
+		`- source: ${args.startupPlan.source ?? "(missing)"}`,
+		`- planned_surfaces: ${args.startupPlan.plannedSurfaces.length > 0 ? args.startupPlan.plannedSurfaces.join(" | ") : "(none)"}`,
+		`- verification_intent: ${args.startupPlan.verificationIntent.length > 0 ? args.startupPlan.verificationIntent.join(" | ") : "(none)"}`,
+		`- summary: ${args.startupPlan.summary}`,
+		"",
 		"verification_evidence:",
 		`- path: ${args.evidence.path}`,
 		`- status: ${args.evidence.status}`,
@@ -591,8 +731,9 @@ export function buildResumeCapsule(args: {
 		"- Treat this block as continuity support derived from canonical .agent state.",
 		"- For selected/in-progress/committed/done slices, .agent/active-slice.json is the canonical implementation contract and the selected plan slice must mirror it exactly.",
 		"- Preserve exact slice_id, goal, contract_ids, acceptance criteria, blocked_on, priority, why_now, implementation surfaces, verification commands, locked notes, must-fix findings, basis_commit, and before-slice counters where still true.",
+		"- .agent/startup-plan.json is the approved workflow plan captured at /cook entry. completion-regrounder must treat it as planning input, then reconcile canonical slices against repo truth instead of copying it blindly into plan.json.",
 		"- When populated, .agent/verification-evidence.json is the durable canonical verification record for the selected slice or current HEAD and should be consumed instead of temp-only artifacts or conversational summaries.",
-		"- After compaction, re-read .agent/state.json, .agent/plan.json, .agent/active-slice.json, .agent/slice-history.jsonl, .agent/stop-check-history.jsonl, and .agent/verification-evidence.json before resuming long-running completion work.",
+		"- After compaction, re-read .agent/state.json, .agent/startup-plan.json, .agent/plan.json, .agent/active-slice.json, .agent/slice-history.jsonl, .agent/stop-check-history.jsonl, and .agent/verification-evidence.json before resuming long-running completion work.",
 		"- Invoke completion-regrounder before continuing when requires_reground is true or unknown.",
 		"- Invoke completion-regrounder before continuing when next_mandatory_role or next_mandatory_action is unknown or ambiguous.",
 		"- Invoke completion-regrounder before continuing when active_slice_matches_plan is no, active_slice_contract_drift_fields is not none, or implementer_handoff_snapshot is missing_or_unclear.",

package/extensions/completion/proposal.ts

@@ -60,11 +60,11 @@ export type CookHandoffCapsule = {
 	risks: string[];
 	notes: string[];
 	handoff_kind: "implementation_workflow_handoff";
-	first_slice_goal: string;
+	first_slice_goal?: string;
 	first_slice_non_goals: string[];
 	implementation_surfaces: string[];
 	verification_commands: string[];
-	why_this_slice_first: string;
+	why_this_slice_first?: string;
 	task_type?: string;
 	evaluation_profile?: string;
 	why_cook_now?: string;
@@ -1279,7 +1279,7 @@ function parseCookHandoffCapsulesFromText(
 		const mission = deps.asString(parsed.mission);
 		const firstSliceGoal = deps.asString(parsed.first_slice_goal ?? parsed.firstSliceGoal);
 		const whyThisSliceFirst = deps.asString(parsed.why_this_slice_first ?? parsed.whyThisSliceFirst);
-		if (!mission || !firstSliceGoal || !whyThisSliceFirst) continue;
+		if (!mission) continue;
 		const scope = deps.asStringArray(parsed.scope);
 		const constraints = deps.asStringArray(parsed.constraints);
 		const nonGoals = deps.asStringArray(parsed.non_goals ?? parsed.nonGoals);
@@ -1325,12 +1325,12 @@ function buildCookHandoffBasisPreview(capsule: CookHandoffCapsule): string {
 		...capsule.constraints,
 		...capsule.non_goals,
 		...capsule.acceptance,
-		`first_slice_goal: ${capsule.first_slice_goal}`,
-		...capsule.first_slice_non_goals.map((item) => `first_slice_non_goals: ${item}`),
-		...capsule.implementation_surfaces.map((item) => `implementation_surfaces: ${item}`),
-		...capsule.verification_commands.map((item) => `verification_commands: ${item}`),
-		`why_this_slice_first: ${capsule.why_this_slice_first}`,
 	];
+	if (capsule.first_slice_goal) parts.push(`first_slice_goal: ${capsule.first_slice_goal}`);
+	parts.push(...capsule.first_slice_non_goals.map((item) => `first_slice_non_goals: ${item}`));
+	parts.push(...capsule.implementation_surfaces.map((item) => `implementation_surfaces: ${item}`));
+	parts.push(...capsule.verification_commands.map((item) => `verification_commands: ${item}`));
+	if (capsule.why_this_slice_first) parts.push(`why_this_slice_first: ${capsule.why_this_slice_first}`);
 	if (capsule.why_cook_now) parts.push(`why_cook_now: ${capsule.why_cook_now}`);
 	return parts.join("\n").trim();
 }
@@ -1363,21 +1363,21 @@ function cookHandoffStartabilityFailures(
 	else if (!cookHandoffAcceptanceIsRepoChangeOriented(capsule)) {
 		failures.push("acceptance is not anchored to concrete repo changes or verification");
 	}
-	const firstSliceGoal = deps.normalizeMissionAnchorText(capsule.first_slice_goal);
-	if (!firstSliceGoal || deps.isWeakMissionAnchor(firstSliceGoal) || COOK_HANDOFF_NEGATIVE_MISSION_REGEX.test(firstSliceGoal)) {
-		failures.push("first_slice_goal is not a bounded implementation slice");
-	} else if (hasExplicitPlanningOnlyDeliverable([capsule.first_slice_goal]) || hasClearNoImplementationSignal([capsule.first_slice_goal])) {
-		failures.push("first_slice_goal is planning-only instead of a repo-change slice");
+	if (capsule.first_slice_goal) {
+		const firstSliceGoal = deps.normalizeMissionAnchorText(capsule.first_slice_goal);
+		if (!firstSliceGoal || deps.isWeakMissionAnchor(firstSliceGoal) || COOK_HANDOFF_NEGATIVE_MISSION_REGEX.test(firstSliceGoal)) {
+			failures.push("first_slice_goal is not a useful sequencing hint");
+		} else if (hasExplicitPlanningOnlyDeliverable([capsule.first_slice_goal]) || hasClearNoImplementationSignal([capsule.first_slice_goal])) {
+			failures.push("first_slice_goal is planning-only instead of a repo-change sequencing hint");
+		}
 	}
-	if (capsule.implementation_surfaces.length === 0) failures.push("implementation_surfaces is empty");
-	if (capsule.verification_commands.length === 0) failures.push("verification_commands is empty");
 	return failures;
 }
 
 function buildNonStartableCookHandoffMessage(failures: string[]): string {
 	return [
-		"/cook failed closed because a fresh explicit primary-agent handoff exists, but it is not concrete enough to start implementation workflow yet.",
-		"Tighten the handoff in the main chat so it names a bounded first implementation slice, repo-change-oriented acceptance, implementation_surfaces, and verification_commands, then rerun /cook.",
+		"/cook failed closed because a fresh explicit primary-agent startup plan exists, but it is not concrete enough to seed workflow planning yet.",
+		"Tighten the startup plan in the main chat so it captures a concrete mission, repo-change-oriented acceptance, and truthful verification intent, then rerun /cook.",
 		`Blocking details: ${failures.join("; ")}.`,
 	].join(" ");
 }
@@ -1435,11 +1435,11 @@ function buildContextProposalFromCookHandoffCapsule(
 				evaluationProfile: capsule.evaluation_profile,
 				critique: [
 					...capsule.notes,
-					`First slice goal: ${capsule.first_slice_goal}`,
+					...(capsule.first_slice_goal ? [`First slice goal: ${capsule.first_slice_goal}`] : []),
 					...(capsule.first_slice_non_goals.length > 0 ? [`First slice non-goals: ${capsule.first_slice_non_goals.join(" | ")}`] : []),
 					...(capsule.implementation_surfaces.length > 0 ? [`Implementation surfaces: ${capsule.implementation_surfaces.join(" | ")}`] : []),
 					...(capsule.verification_commands.length > 0 ? [`Verification commands: ${capsule.verification_commands.join(" | ")}`] : []),
-					`Why this slice first: ${capsule.why_this_slice_first}`,
+					...(capsule.why_this_slice_first ? [`Why this slice first: ${capsule.why_this_slice_first}`] : []),
 					...(capsule.why_cook_now ? [`Primary-agent /cook handoff rationale: ${capsule.why_cook_now}`] : []),
 				],
 				risks: capsule.risks,
@@ -1455,11 +1455,11 @@ function buildContextProposalFromCookHandoffCapsule(
 				...capsule.scope,
 				...constraints,
 				...capsule.acceptance,
-				capsule.first_slice_goal,
+				...(capsule.first_slice_goal ? [capsule.first_slice_goal] : []),
 				...capsule.first_slice_non_goals,
 				...capsule.implementation_surfaces,
 				...capsule.verification_commands,
-				capsule.why_this_slice_first,
+				...(capsule.why_this_slice_first ? [capsule.why_this_slice_first] : []),
 			],
 		),
 		goalText,