@linimin/pi-letscook 0.1.66 → 0.1.68

package/extensions/completion/index.ts

@@ -14,16 +14,17 @@ import {
 	registerCookCommand,
 } from "./driver";
 import {
+	assessCookHandoffText,
 	assessMissionAnchor,
 	collectRecentDiscussionEntries,
 	collectRecentSessionMessages,
-	assessLatestCookHandoffProposal,
 	finalizeContextProposalAnalysis,
 	isWeakMissionAnchor,
 	missionAnchorsLikelyEquivalent,
 	missionAnchorsStrictlyEquivalent,
 	normalizeMissionAnchorText,
 	resolveContextProposalConfirmationAction,
+	retagContextProposalSource,
 	stripCodeBlocks,
 } from "./proposal";
 import type {
@@ -47,7 +48,8 @@ import {
 	maybeWriteContextProposalSnapshot,
 } from "./prompt-surfaces";
 import { toolCallBlockReason } from "./policy-guards";
-import { analyzeContextProposalWithAgent, generateCookHandoffWithAgent, runCompletionRole } from "./role-runner";
+import { runCompletionRole } from "./role-runner";
+import { generateCookHandoffWithAgent } from "./role-runner";
 import {
 	applyLiveRoleEvent,
 	buildInlineRunningLines,
@@ -132,10 +134,10 @@ type ActiveWorkflowProposalAssessment = {
 	proposal?: ContextProposal;
 	blockedFailureMessage?: string;
 	reason:
-		| "matching_mission"
-		| "missing_explicit_handoff"
-		| "fresh_explicit_handoff"
-		| "fresh_explicit_handoff_not_startable";
+		| "matching_generated_startup_plan"
+		| "no_generated_startup_plan"
+		| "generated_replacement_startup_plan"
+		| "generated_startup_plan_not_startable";
 };
 
 function completionTestWorkflowActionOverride(): "continue" | "refocus" | "cancel" | undefined {
@@ -209,7 +211,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";
@@ -376,36 +378,13 @@ function stripCookHandoffBlocks(text: string): string {
 	return text.replace(COOK_HANDOFF_BLOCK_REGEX, " ").replace(/\s+/g, " ").trim();
 }
 
-async function deriveCookStartupProposal(
-	ctx: { cwd: string; hasUI: boolean; ui: any; sessionManager: any; model?: any; modelRegistry?: any },
-	projectName: string,
-): Promise<CookContextProposalResult> {
-	const recentMessages = collectRecentSessionMessages(ctx, { isRecord, asString, asNumber, isStaleContextError });
-	const explicitHandoff = assessLatestCookHandoffProposal(recentMessages, projectName, {
-		asString,
-		asStringArray,
-		assessMissionAnchor,
-		normalizeMissionAnchorText,
-		isWeakMissionAnchor,
-		missionAnchorsStrictlyEquivalent,
-		stripCodeBlocks,
-	});
-	if (explicitHandoff.status === "startable") return { proposal: explicitHandoff.proposal };
-	if (explicitHandoff.status === "fresh_but_not_startable") {
-		return { blockedFailureMessage: explicitHandoff.message };
-	}
-	return {};
-}
-
 async function deriveCookContextProposal(
 	ctx: { cwd: string; hasUI: boolean; ui: any; sessionManager: any; model?: any; modelRegistry?: any },
 	projectName: string,
 ): Promise<CookContextProposalResult> {
-	const explicit = await deriveCookStartupProposal(ctx, projectName);
-	if (explicit.proposal || explicit.blockedFailureMessage) return explicit;
 	const recentMessages = collectRecentSessionMessages(ctx, { isRecord, asString, asNumber, isStaleContextError });
 	const recentEntries = recentMessages
-		.filter((entry) => !entry.isCommand && (entry.role === "user" || entry.role === "assistant" || entry.role === "custom" || entry.role === "summary"))
+		.filter((entry) => !entry.isCommand && (entry.role === "user" || entry.role === "custom" || entry.role === "summary"))
 		.slice(0, 12)
 		.map((entry) => ({ role: entry.role, text: stripCookHandoffBlocks(entry.text) }))
 		.filter((entry) => entry.text.length > 0);
@@ -418,6 +397,7 @@ 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)"}`,
 		]
@@ -435,9 +415,7 @@ async function deriveCookContextProposal(
 		getCtxUi,
 	});
 	if (!raw) return {};
-	const generated = assessLatestCookHandoffProposal([
-		{ role: "assistant", text: raw, messageId: "generated-primary-agent-handoff", timestampMs: Date.now(), isCommand: false },
-	], projectName, {
+	const generated = assessCookHandoffText(raw, projectName, {
 		asString,
 		asStringArray,
 		assessMissionAnchor,
@@ -445,8 +423,14 @@ async function deriveCookContextProposal(
 		isWeakMissionAnchor,
 		missionAnchorsStrictlyEquivalent,
 		stripCodeBlocks,
+	}, {
+		messageId: "generated-primary-agent-handoff",
+		timestampMs: Date.now(),
+		context: "same_entry_synthesis",
 	});
-	if (generated.status === "startable") return { proposal: generated.proposal };
+	if (generated.status === "startable") {
+		return { proposal: retagContextProposalSource(generated.proposal, "deferred_primary_agent_handoff") };
+	}
 	if (generated.status === "fresh_but_not_startable") return { blockedFailureMessage: generated.message };
 	return {};
 }
@@ -485,13 +469,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 +644,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 +688,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 +718,7 @@ function composeSystemReminder(snapshot: CompletionStateSnapshot, sliceHistory:
 		implementationSurfacesLine,
 		verificationCommandsLine,
 		evidence,
+		startupPlan,
 		evaluationRoleReminderText: isRubricEvaluationRole(nextRole) ? buildEvaluationRoleReminderText(snapshot, nextRole) : undefined,
 	});
 }
@@ -732,17 +738,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 +765,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 +859,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 +880,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 +918,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 +938,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,
@@ -937,7 +951,6 @@ export default function completionExtension(pi: ExtensionAPI) {
 		completionTestWorkflowMissionOverride,
 		confirmContextProposal,
 		deriveCookContextProposal,
-		deriveCookStartupProposal,
 		emitCommandText,
 		finalizeContextProposalAnalysis,
 		getCtxCwd,

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.",
-		"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.",
+		"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, and do not expect /cook to directly reuse an old preview capsule; /cook should always synthesize the startup plan fresh in the same entry from current task context.",
+		"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 advisory only until /cook reruns same-entry primary-agent startup-plan synthesis: 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(" ");
 }
@@ -85,7 +106,28 @@ function buildAdvisoryStartupBriefNotes(analysis: ContextProposalAnalysis): stri
 		...analysis.critique,
 		...analysis.possibleNoise.map((item) => `Possible noise: ${item}`),
 	];
-	return notes.length > 0 ? notes : ["No additional operator notes were derived from recent discussion."];
+	return notes.length > 0 ? notes : ["No additional operator notes were captured for the approved startup plan."];
+}
+
+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: {
@@ -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.",