@linimin/pi-letscook 0.1.65 → 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,
@@ -1055,11 +1130,13 @@ export default function completionExtension(pi: ExtensionAPI) {
 		const snapshot = await loadCompletionSnapshot(cwd);
 		const completionActive = Boolean(snapshot) && asString(snapshot?.state?.continuation_policy) !== "done";
 		const root = snapshot?.files.root ?? findRepoRoot(cwd) ?? cwd;
+		const completionRoleDispatchAllowed = Boolean(role) || (hasCompletionRoutingActivation(snapshot) && isCompletionDriverPromptTurn(ctx));
 		const reason = toolCallBlockReason({
 			toolName: event.toolName,
 			input: isRecord(event.input) ? event.input : undefined,
 			role,
 			completionActive,
+			completionRoleDispatchAllowed,
 			root,
 		});
 		if (reason) return { block: true, reason };
@@ -1074,6 +1151,7 @@ export default function completionExtension(pi: ExtensionAPI) {
 			"Use completion_role when driving the completion workflow and a mandatory completion role must act next.",
 			"Use completion_role only for completion-bootstrapper, completion-regrounder, completion-implementer, completion-reviewer, completion-auditor, or completion-stop-judge.",
 			"Do not use completion_role from inside a completion role; only the workflow driver may dispatch roles.",
+			"Do not call completion_role from ordinary chat; it is reserved for explicit /cook workflow driver turns.",
 		],
 		parameters: Type.Object({
 			role: StringEnum(ROLE_NAMES, { description: "The completion role to invoke." }),

package/extensions/completion/policy-guards.ts

@@ -62,14 +62,19 @@ export function toolCallBlockReason(args: {
 	input?: JsonRecord;
 	role?: string;
 	completionActive: boolean;
+	completionRoleDispatchAllowed: boolean;
 	root: string;
 }): string | undefined {
-	const { toolName, input, role, completionActive, root } = args;
+	const { toolName, input, role, completionActive, completionRoleDispatchAllowed, root } = args;
 
 	if (toolName === "completion_role" && role) {
 		return `Nested completion role dispatch is forbidden for ${role}.`;
 	}
 
+	if (toolName === "completion_role" && !completionRoleDispatchAllowed) {
+		return "completion_role may only be used from an explicit /cook workflow driver turn.";
+	}
+
 	if (toolName === "edit" || toolName === "write") {
 		const rawPath = asString(input?.path);
 		if (!rawPath) return undefined;

package/extensions/completion/prompt-surfaces.ts

@@ -24,18 +24,40 @@ 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.",
 		"Ordinary chat may clarify requirements, discuss tradeoffs, refine scope, and directly implement requested repo changes, including multi-file work, when that is the most helpful response.",
 		"Do not proactively tell the user to run /cook just because a task looks workflow-worthy, and do not emit a ```cook_handoff``` capsule by default in ordinary chat.",
 		"/cook is optional workflow mode for resumability, review, audit, canonical .agent state, or deliberate multi-session control; it is not required just to edit repo files in ordinary chat.",
+		"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(" ");
 }
@@ -87,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;
@@ -94,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,
@@ -114,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) {
@@ -146,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");
 }
@@ -195,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",
@@ -215,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),
@@ -416,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;
@@ -439,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)"}`,
@@ -460,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.");
@@ -473,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}`);
@@ -501,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;
@@ -543,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}`,
@@ -590,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.",