@linimin/pi-letscook 0.1.55 → 0.1.57

package/CHANGELOG.md

@@ -2,10 +2,15 @@
 
 ## Unreleased
 
+## 0.1.57
+
 ### Changed
 
-- made `/cook` derive a confirmable startup brief from recent discussion before any canonical workflow rewrite, then preserve the confirmed brief in canonical state as advisory intake for later re-grounding
+- made explicit primary-agent `/cook` handoff the preferred startup-intake path by teaching ordinary-chat handoff turns to emit a structured `cook_handoff` capsule and letting `/cook` prefer that capsule over broad context re-inference when it is fresh and valid
+- kept context-derived startup as a fallback only, so stale, drifted, or non-startable handoff capsules still fail closed or fall back to recent discussion instead of silently rewriting canonical state
+- made finished-workflow suppression stay a safety layer instead of a replacement mission when a fresh explicit `/cook` handoff exists, and blocked negative rejection/suppression text from becoming a Startable startup mission
 - removed inline `/cook` arguments from the shipped entry path again so explicit bare `/cook` is the only public command, and fail closed when recent discussion is insufficient or unreliable
+- added a pre-`/cook` ordinary-chat handoff boundary so the primary agent is instructed to stop at `/cook` once a task has matured into completion-workflow scope instead of starting long-running implementation directly in ordinary chat
 
 ## 0.1.54
 

package/README.md

@@ -49,12 +49,13 @@ Then run `/reload` in Pi.
 
 ## What `/cook` expects
 
-- recent main-chat discussion about concrete repo changes
+- preferably a fresh explicit primary-agent `/cook` handoff capsule from the immediately preceding ordinary-chat turn
+- otherwise recent main-chat discussion about concrete repo changes
 - enough detail to derive a startup brief with mission, scope, constraints or non-goals, acceptance, and notes or risks
 - README/CHANGELOG updates still count as concrete repo changes
-- assistant-produced summaries and plan/spec/design-doc/proposal-only artifacts do not
+- assistant-produced summaries and plan/spec/design-doc/proposal-only artifacts still do not count unless they include the explicit structured `/cook` handoff capsule
 
-If recent discussion is missing, weak, ambiguous, assistant-produced, or only describes planning artifacts instead of concrete repo changes, `/cook` fails closed, leaves canonical `.agent/**` state unchanged, and tells you to clarify the mission in the main chat before rerunning `/cook`.
+If no fresh valid handoff exists and recent discussion is missing, weak, ambiguous, assistant-produced, or only describes planning artifacts instead of concrete repo changes, `/cook` fails closed, leaves canonical `.agent/**` state unchanged, and tells you to clarify the mission in the main chat before rerunning `/cook`.
 
 If you pass inline arguments to `/cook`, it also fails closed and tells you to move that intent into the main chat before rerunning bare `/cook`.
 
@@ -62,10 +63,15 @@ If you pass inline arguments to `/cook`, it also fails closed and tells you to m
 
 Only explicit `/cook` enters the workflow. Ordinary prompts stay in the main chat and go straight to the primary agent.
 
+If a task has clearly matured into completion-workflow scope, the primary agent should hand you off to `/cook` instead of starting long-running implementation directly in ordinary chat.
+
+That handoff should include an explicit structured `/cook` capsule in the assistant reply so `/cook` can confirm the already-formed mission instead of re-deriving it from broad ambient context.
+
 Important behavior:
 - `/cook` is the canonical workflow boundary and manual entry point
 - startup, refocus, and next-round routing stay confirm-first; nothing silently starts a workflow
 - explicit slash commands other than `/cook` continue normally in the main chat
+- ordinary main-chat discussion may clarify or propose, but mature long-running implementation should be handed off to `/cook`
 
 ## Typical examples
 
@@ -78,13 +84,13 @@ I want to add login redirect handling and tests.
 
 ## What happens when you run `/cook`
 
-`/cook` first derives a startup brief from recent discussion, then shows the existing approval-only Start/Cancel gate.
+`/cook` first looks for a fresh explicit primary-agent handoff capsule. If one is valid, `/cook` builds the startup brief from that handoff and only uses recent discussion as validation or supplemental notes. If no valid handoff exists, `/cook` falls back to deriving a startup brief from recent discussion before showing the existing approval-only Start/Cancel gate.
 
 | Repo state | What you'll see |
 |---|---|
-| No workflow yet | A startup brief built from recent main-chat discussion. You choose **Start** or **Cancel**. Weak, unreliable, or planning-only discussion fails closed. |
-| Active workflow exists | Usually a resume of the current workflow. If recent discussion clearly points to a different concrete repo change, `/cook` shows a chooser first and only rewrites canonical state after you confirm the new startup brief. Ambiguous discussion stays conservative. |
-| Previous workflow is `done` | A next-round startup brief from recent main-chat discussion, again behind **Start** or **Cancel**. Discussion that only restates already-finished work fails closed. |
+| No workflow yet | If a fresh explicit handoff capsule exists, a startup brief built from that handoff. Otherwise a startup brief built from recent main-chat discussion. You choose **Start** or **Cancel**. Weak, unreliable, stale, or planning-only intake fails closed. |
+| Active workflow exists | Usually a resume of the current workflow. If a fresh explicit handoff capsule or recent discussion clearly points to a different concrete repo change, `/cook` shows a chooser first and only rewrites canonical state after you confirm the new startup brief. Ambiguous intake stays conservative. |
+| Previous workflow is `done` | A fresh explicit handoff capsule can still start the next implementation round behind **Start** or **Cancel**. Without that, `/cook` falls back to recent discussion. Discussion that only restates already-finished work still fails closed. |
 
 ## Confirmation and fail-closed behavior
 
@@ -93,13 +99,15 @@ I want to add login redirect handling and tests.
 - startup, next-round, and refocus proposals are approval-only
 - actions are **Start** and **Cancel**
 - **Cancel** is side-effect free: discuss changes in the main chat and rerun `/cook`
-- weak, ambiguous, assistant-produced, or planning-only discussion does not start a workflow
+- weak, ambiguous, stale, invalid, assistant-produced, or planning-only intake does not start a workflow
 - when recent discussion suggests a different workflow, `/cook` shows a chooser before any canonical state rewrite
 
 When you accept startup or refocus, `/cook` persists the chosen workflow state in canonical `.agent/**` files before the re-ground round begins.
 
 The confirmed startup brief is also preserved there as advisory intake for later re-grounding. It does not replace `.agent/plan.json` or `.agent/active-slice.json`, which remain under regrounder authority.
 
+The pre-`/cook` handoff capsule itself is not canonical workflow state. It is only startup intake for `/cook`.
+
 ## Observability
 
 When canonical `.agent/**` state exists and no role is actively running, the extension shows a completion widget sourced from that state. The widget summarizes:

package/extensions/completion/index.ts

@@ -16,7 +16,9 @@ import {
 import {
 	assessMissionAnchor,
 	collectRecentDiscussionEntries,
+	collectRecentSessionMessages,
 	deriveCookContextProposalFromRecentDiscussion,
+	extractLatestCookHandoffProposal,
 	finalizeContextProposalAnalysis,
 	isWeakMissionAnchor,
 	missionAnchorsLikelyEquivalent,
@@ -38,6 +40,7 @@ import {
 	buildContextProposalConfirmationLayout as buildExtractedContextProposalConfirmationLayout,
 	buildContextProposalConfirmationSelectItems,
 	buildContextProposalContinuationReason as buildExtractedContextProposalContinuationReason,
+	buildCookHandoffBoundaryReminder as buildExtractedCookHandoffBoundaryReminder,
 	buildEvaluationRoleContextLines as buildExtractedEvaluationRoleContextLines,
 	buildEvaluationRoleReminderText as buildExtractedEvaluationRoleReminderText,
 	buildResumeCapsule as buildExtractedResumeCapsule,
@@ -181,6 +184,10 @@ function completionTestSystemReminderPath(): string | undefined {
 	return asString(process.env.PI_COMPLETION_TEST_SYSTEM_REMINDER_PATH);
 }
 
+function completionTestCookHandoffReminderPath(): string | undefined {
+	return asString(process.env.PI_COMPLETION_TEST_COOK_HANDOFF_REMINDER_PATH);
+}
+
 function maybeWriteTestSnapshot(targetPath: string | undefined, content: string): void {
 	if (!targetPath) return;
 	try {
@@ -225,6 +232,19 @@ function shouldInjectCompletionWorkflowContext(snapshot: CompletionStateSnapshot
 	return hasCompletionRoutingActivation(snapshot) && isCompletionDriverPromptTurn(ctx);
 }
 
+function shouldInjectCookHandoffBoundary(event: { prompt?: string }, ctx: { sessionManager?: any }): boolean {
+	if (roleFromEnv()) return false;
+	if (isCompletionDriverPromptTurn(ctx)) return false;
+	const prompt = typeof event.prompt === "string" ? event.prompt.trim() : "";
+	if (!prompt) return false;
+	if (prompt.startsWith("/")) return false;
+	return true;
+}
+
+function buildCookHandoffBoundaryReminder(): string {
+	return buildExtractedCookHandoffBoundaryReminder();
+}
+
 function buildDoneWorkflowBoundaryReminder(snapshot: CompletionStateSnapshot): string {
 	const missionAnchor = asString(snapshot.state?.mission_anchor) ?? asString(snapshot.plan?.mission_anchor) ?? "(unknown)";
 	const continuationReason = asString(snapshot.state?.continuation_reason) ?? "(unknown)";
@@ -346,7 +366,11 @@ async function deriveCookContextProposal(
 	ctx: { cwd: string; hasUI: boolean; ui: any; sessionManager: any; model?: any; modelRegistry?: any },
 	projectName: string,
 ): Promise<ContextProposal | undefined> {
-	const recentEntries = collectRecentDiscussionEntries(ctx, { isRecord, asString, isStaleContextError });
+	const recentMessages = collectRecentSessionMessages(ctx, { isRecord, asString, asNumber, isStaleContextError });
+	const recentEntries = recentMessages
+		.filter((entry) => (entry.role === "user" || entry.role === "custom") && !entry.isCommand)
+		.slice(0, 8)
+		.map((entry) => ({ role: entry.role, text: entry.text }));
 	const snapshot = await loadCompletionSnapshot(getCtxCwd(ctx));
 	const workflowContextLines = snapshot
 		? [
@@ -360,6 +384,16 @@ async function deriveCookContextProposal(
 			`verification summary: ${asString(snapshot.verificationEvidence?.summary) ?? "(none)"}`,
 		]
 		: [];
+	const explicitHandoff = extractLatestCookHandoffProposal(recentMessages, projectName, {
+		asString,
+		asStringArray,
+		assessMissionAnchor,
+		normalizeMissionAnchorText,
+		isWeakMissionAnchor,
+		missionAnchorsStrictlyEquivalent,
+		stripCodeBlocks,
+	});
+	if (explicitHandoff) return explicitHandoff;
 	return await deriveCookContextProposalFromRecentDiscussion(projectName, recentEntries, {
 		asString,
 		asStringArray,
@@ -926,7 +960,7 @@ export default function completionExtension(pi: ExtensionAPI) {
 		}
 	});
 
-	pi.on("before_agent_start", async (_event, ctx) => {
+	pi.on("before_agent_start", async (event, ctx) => {
 		const loaded = await loadCompletionDataForReminder(getCtxCwd(ctx));
 		const driverPromptTurn = isCompletionDriverPromptTurn(ctx);
 		if (loaded && driverPromptTurn) {
@@ -934,28 +968,35 @@ export default function completionExtension(pi: ExtensionAPI) {
 			const fingerprint = completionContinuationFingerprint(loaded.snapshot);
 			if (fingerprint) markQueuedDriverPromptInFlight(rootKey, fingerprint);
 		}
-		if (!loaded || !shouldInjectCompletionWorkflowContext(loaded.snapshot, ctx)) return;
-		const additions = isWorkflowDone(loaded.snapshot)
-			? [buildDoneWorkflowBoundaryReminder(loaded.snapshot)]
-			: [composeSystemReminder(loaded.snapshot, loaded.sliceHistory, loaded.stopHistory)];
-		if (!isWorkflowDone(loaded.snapshot)) {
-			const markerText = await readText(loaded.snapshot.files.compactionMarkerPath);
-			let marker: JsonRecord | undefined;
-			if (markerText) {
-				try {
-					const parsed = JSON.parse(markerText);
-					marker = isRecord(parsed) ? parsed : undefined;
-				} catch {
-					marker = undefined;
+		const systemPrompt = getSystemPromptSafe(ctx);
+		if (!systemPrompt) return;
+		if (loaded && shouldInjectCompletionWorkflowContext(loaded.snapshot, ctx)) {
+			const additions = isWorkflowDone(loaded.snapshot)
+				? [buildDoneWorkflowBoundaryReminder(loaded.snapshot)]
+				: [composeSystemReminder(loaded.snapshot, loaded.sliceHistory, loaded.stopHistory)];
+			if (!isWorkflowDone(loaded.snapshot)) {
+				const markerText = await readText(loaded.snapshot.files.compactionMarkerPath);
+				let marker: JsonRecord | undefined;
+				if (markerText) {
+					try {
+						const parsed = JSON.parse(markerText);
+						marker = isRecord(parsed) ? parsed : undefined;
+					} catch {
+						marker = undefined;
+					}
 				}
+				if (marker) additions.push(buildPostCompactionDriverInstructions(loaded.snapshot, marker));
 			}
-			if (marker) additions.push(buildPostCompactionDriverInstructions(loaded.snapshot, marker));
+			maybeWriteTestSnapshot(completionTestSystemReminderPath(), additions.join("\n\n"));
+			return {
+				systemPrompt: `${systemPrompt}\n\n${additions.join("\n\n")}`,
+			};
 		}
-		maybeWriteTestSnapshot(completionTestSystemReminderPath(), additions.join("\n\n"));
-		const systemPrompt = getSystemPromptSafe(ctx);
-		if (!systemPrompt) return;
+		if (!shouldInjectCookHandoffBoundary(event, ctx)) return;
+		const handoffReminder = buildCookHandoffBoundaryReminder();
+		maybeWriteTestSnapshot(completionTestCookHandoffReminderPath(), handoffReminder);
 		return {
-			systemPrompt: `${systemPrompt}\n\n${additions.join("\n\n")}`,
+			systemPrompt: `${systemPrompt}\n\n${handoffReminder}`,
 		};
 	});
 

package/extensions/completion/prompt-surfaces.ts

@@ -10,7 +10,7 @@ import type {
 
 export type AdvisoryStartupBrief = {
 	kind: "startup_brief";
-	source: "recent_discussion";
+	source: "recent_discussion" | "primary_agent_handoff";
 	confirmed: true;
 	captured_at: string;
 	goal_text: string;
@@ -24,6 +24,20 @@ export type AdvisoryStartupBrief = {
 	evaluation_profile?: string;
 };
 
+export function buildCookHandoffBoundaryReminder(): string {
+	return [
+		"You are still in ordinary main chat before any explicit /cook workflow entry.",
+		"Use ordinary chat to clarify requirements, discuss tradeoffs, and propose implementation approaches.",
+		"/cook is the only explicit entrypoint into long-running completion workflow.",
+		"When you judge that the task has matured into completion-workflow scope — for example the user has clearly shifted from exploration into implementation intent, you have just produced a concrete plan or proposal whose next step would naturally be implementation, or the task spans multiple files, steps, or verification surfaces — stop short of long-running implementation and tell the user to run /cook.",
+		"At that handoff point, do not begin long-running product implementation in ordinary chat, do not edit tracked product files for that workflow-level task, and do not act as though /cook had already been invoked.",
+		"When handing off, explain that /cook will first look for a fresh explicit primary-agent handoff capsule and otherwise fall back to recent discussion.",
+		"Also append one exact fenced block in the same assistant reply using ```cook_handoff ... ``` JSON with kind/source/handoff_kind plus mission, scope, constraints or non_goals, acceptance, risks, notes, captured_at, source_turn_id, and optional task_type/evaluation_profile/why_cook_now.",
+		"The 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 task is still ordinary Q&A, lightweight brainstorming, or a tiny one-off fix, continue normally without forcing /cook.",
+	].join(" ");
+}
+
 export function buildContextProposalGoalText(proposal: {
 	mission: string;
 	scope: string[];
@@ -72,13 +86,13 @@ function buildAdvisoryStartupBriefNotes(analysis: ContextProposalAnalysis): stri
 }
 
 export function buildAdvisoryStartupBrief(args: {
-	proposal: Pick<ContextProposal, "goalText" | "mission" | "scope" | "constraints" | "acceptance">;
+	proposal: Pick<ContextProposal, "goalText" | "mission" | "scope" | "constraints" | "acceptance" | "source">;
 	analysis: ContextProposalAnalysis;
 	capturedAt?: string;
 }): AdvisoryStartupBrief {
 	return {
 		kind: "startup_brief",
-		source: "recent_discussion",
+		source: args.proposal.source === "handoff_capsule" ? "primary_agent_handoff" : "recent_discussion",
 		confirmed: true,
 		captured_at: args.capturedAt ?? new Date().toISOString(),
 		goal_text: args.proposal.goalText,

package/extensions/completion/proposal.ts

@@ -27,7 +27,7 @@ export type ContextProposalAlternate = {
 	analysis: ContextProposalAnalysis;
 	goalText: string;
 	basisPreview: string;
-	source: "session" | "analyst";
+	source: "session" | "analyst" | "handoff_capsule";
 };
 
 export type ContextProposal = ContextProposalAlternate & {
@@ -41,6 +41,30 @@ export type RecentDiscussionEntry = {
 	text: string;
 };
 
+export type RecentSessionMessage = RecentDiscussionEntry & {
+	messageId?: string;
+	timestampMs?: number;
+	isCommand: boolean;
+};
+
+export type CookHandoffCapsule = {
+	kind: "cook_handoff";
+	source: "primary_agent";
+	captured_at: string;
+	source_turn_id: string;
+	mission: string;
+	scope: string[];
+	constraints: string[];
+	non_goals: string[];
+	acceptance: string[];
+	risks: string[];
+	notes: string[];
+	handoff_kind: "implementation_workflow_ready";
+	task_type?: string;
+	evaluation_profile?: string;
+	why_cook_now?: string;
+};
+
 export type ContextProposalDecision = {
 	missionAnchor: string;
 	goalText: string;
@@ -113,6 +137,10 @@ function localAsStringArray(value: unknown): string[] {
 		: [];
 }
 
+function localAsNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
 function localIsRecord(value: unknown): value is JsonRecord {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -300,11 +328,12 @@ export function missionAnchorsLikelyEquivalent(left: string, right: string): boo
 	return missionAnchorBigramOverlapRatio(leftTokens, rightTokens) >= 0.5;
 }
 
-export function collectRecentDiscussionEntries(ctx: { sessionManager: any }, deps: {
+export function collectRecentSessionMessages(ctx: { sessionManager: any }, deps: {
 	isRecord: (value: unknown) => boolean;
 	asString?: (value: unknown) => string | undefined;
+	asNumber?: (value: unknown) => number | undefined;
 	isStaleContextError?: (error: unknown) => boolean;
-}, limit = 8): RecentDiscussionEntry[] {
+}, limit = 24): RecentSessionMessage[] {
 	let branch: any[] = [];
 	try {
 		branch = ctx.sessionManager?.getBranch?.() ?? [];
@@ -313,27 +342,42 @@ export function collectRecentDiscussionEntries(ctx: { sessionManager: any }, dep
 		throw error;
 	}
 	const asStringValue = deps.asString ?? localAsString;
-	const entries: RecentDiscussionEntry[] = [];
+	const asNumberValue = deps.asNumber ?? localAsNumber;
+	const entries: RecentSessionMessage[] = [];
 	for (let index = branch.length - 1; index >= 0; index -= 1) {
 		const entry = branch[index];
 		if (!deps.isRecord(entry) || entry.type !== "message" || !deps.isRecord(entry.message)) continue;
 		const message = entry.message as JsonRecord;
-		let text = "";
-		let role: RecentDiscussionEntry["role"] | undefined;
 		const messageRole = asStringValue(message.role);
-		if (messageRole === "user" || messageRole === "custom") {
-			text = extractTextFromMessageContent(message.content);
-			role = messageRole;
-		}
-		if (!text || !role) continue;
+		if (messageRole !== "user" && messageRole !== "assistant" && messageRole !== "custom" && messageRole !== "summary") continue;
+		const text = extractTextFromMessageContent(message.content);
+		if (!text) continue;
 		const trimmed = text.trim();
-		if (!trimmed || /^\/(?:cook|complete)\b/i.test(trimmed)) continue;
-		entries.push({ role, text: trimmed });
+		if (!trimmed) continue;
+		entries.push({
+			role: messageRole as RecentDiscussionEntry["role"],
+			text: trimmed,
+			messageId: asStringValue((entry as JsonRecord).id),
+			timestampMs: asNumberValue(message.timestamp),
+			isCommand: /^\//.test(trimmed),
+		});
 		if (entries.length >= limit) break;
 	}
 	return entries;
 }
 
+export function collectRecentDiscussionEntries(ctx: { sessionManager: any }, deps: {
+	isRecord: (value: unknown) => boolean;
+	asString?: (value: unknown) => string | undefined;
+	asNumber?: (value: unknown) => number | undefined;
+	isStaleContextError?: (error: unknown) => boolean;
+}, limit = 8): RecentDiscussionEntry[] {
+	return collectRecentSessionMessages(ctx, deps, Math.max(limit * 3, limit))
+		.filter((entry) => (entry.role === "user" || entry.role === "custom") && !entry.isCommand)
+		.slice(0, limit)
+		.map((entry) => ({ role: entry.role, text: entry.text }));
+}
+
 export function serializeRecentDiscussionEntries(entries: RecentDiscussionEntry[]): string {
 	return entries
 		.slice()
@@ -1182,6 +1226,167 @@ export function extractContextProposalFromStructuredSession(
 	return parseStrictStructuredSessionProposal(structuredTexts.join("\n\n"), projectName, deps);
 }
 
+const COOK_HANDOFF_BLOCK_REGEX = /```cook_handoff\s*([\s\S]*?)```/giu;
+const COOK_HANDOFF_MAX_AGE_MS = 45 * 60 * 1000;
+const COOK_HANDOFF_MAX_LATER_NON_COMMAND_MESSAGES = 2;
+const COOK_HANDOFF_NEGATIVE_MISSION_REGEX =
+	/(?:\b(?:do not|don't|dont|not|never|avoid|skip|refuse|recognize that|suppress|ignore|block|prevent)\b|(?:不要|別|别|勿|禁止|避免|忽略|阻止))/iu;
+
+function parseCookHandoffCapsulesFromText(
+	text: string,
+	messageId: string | undefined,
+	timestampMs: number | undefined,
+	deps: Pick<ProposalParseDeps, "asString" | "asStringArray">,
+): CookHandoffCapsule[] {
+	const capsules: CookHandoffCapsule[] = [];
+	for (const match of text.matchAll(COOK_HANDOFF_BLOCK_REGEX)) {
+		const rawJson = deps.asString(match[1]);
+		if (!rawJson) continue;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(rawJson);
+		} catch {
+			continue;
+		}
+		if (!localIsRecord(parsed)) continue;
+		if (deps.asString(parsed.kind) !== "cook_handoff") continue;
+		if (deps.asString(parsed.source) !== "primary_agent") continue;
+		if (deps.asString(parsed.handoff_kind) !== "implementation_workflow_ready") continue;
+		const mission = deps.asString(parsed.mission);
+		if (!mission) continue;
+		const scope = deps.asStringArray(parsed.scope);
+		const constraints = deps.asStringArray(parsed.constraints);
+		const nonGoals = deps.asStringArray(parsed.non_goals ?? parsed.nonGoals);
+		const acceptance = deps.asStringArray(parsed.acceptance);
+		const risks = deps.asStringArray(parsed.risks);
+		const notes = deps.asStringArray(parsed.notes);
+		const capturedAt = deps.asString(parsed.captured_at) ?? (timestampMs ? new Date(timestampMs).toISOString() : undefined);
+		const sourceTurnId = deps.asString(parsed.source_turn_id) ?? messageId;
+		if (!capturedAt || !sourceTurnId) continue;
+		capsules.push({
+			kind: "cook_handoff",
+			source: "primary_agent",
+			captured_at: capturedAt,
+			source_turn_id: sourceTurnId,
+			mission,
+			scope,
+			constraints,
+			non_goals: nonGoals,
+			acceptance,
+			risks,
+			notes,
+			handoff_kind: "implementation_workflow_ready",
+			task_type: deps.asString(parsed.task_type),
+			evaluation_profile: deps.asString(parsed.evaluation_profile),
+			why_cook_now: deps.asString(parsed.why_cook_now),
+		});
+	}
+	return capsules;
+}
+
+function buildCookHandoffBasisPreview(capsule: CookHandoffCapsule): string {
+	const parts = [capsule.mission, ...capsule.scope, ...capsule.constraints, ...capsule.non_goals, ...capsule.acceptance];
+	if (capsule.why_cook_now) parts.push(`why_cook_now: ${capsule.why_cook_now}`);
+	return parts.join("\n").trim();
+}
+
+function isStartableCookHandoffCapsule(
+	capsule: CookHandoffCapsule,
+	deps: Pick<ProposalParseDeps, "normalizeMissionAnchorText" | "isWeakMissionAnchor">,
+): boolean {
+	const mission = deps.normalizeMissionAnchorText(capsule.mission);
+	if (!mission || deps.isWeakMissionAnchor(mission)) return false;
+	if (COOK_HANDOFF_NEGATIVE_MISSION_REGEX.test(mission)) return false;
+	if (capsule.scope.length === 0 || capsule.acceptance.length === 0) return false;
+	return true;
+}
+
+function laterMessagesInvalidateCookHandoff(
+	laterMessages: RecentSessionMessage[],
+	deps: Pick<ProposalParseDeps, "stripCodeBlocks">,
+): boolean {
+	const laterNonCommandMessages = laterMessages.filter((entry) => !entry.isCommand);
+	if (laterNonCommandMessages.length > COOK_HANDOFF_MAX_LATER_NON_COMMAND_MESSAGES) return true;
+	return laterNonCommandMessages.some((entry) => {
+		if (entry.role === "summary") return false;
+		if (!hasRecentDiscussionImplementationIntent(entry.text, deps.stripCodeBlocks)) return false;
+		return true;
+	});
+}
+
+function cookHandoffIsFreshEnough(capsule: CookHandoffCapsule, laterMessages: RecentSessionMessage[]): boolean {
+	const capturedAtMs = Date.parse(capsule.captured_at);
+	if (!Number.isFinite(capturedAtMs)) return false;
+	const laterTimestamps = laterMessages.map((entry) => entry.timestampMs).filter((value): value is number => value !== undefined);
+	if (laterTimestamps.length === 0) return true;
+	return Math.max(...laterTimestamps) - capturedAtMs <= COOK_HANDOFF_MAX_AGE_MS;
+}
+
+function buildContextProposalFromCookHandoffCapsule(
+	capsule: CookHandoffCapsule,
+	projectName: string,
+	deps: ProposalParseDeps,
+): ContextProposal | undefined {
+	if (!isStartableCookHandoffCapsule(capsule, deps)) return undefined;
+	const constraints = uniqueProposalItems([...capsule.constraints, ...capsule.non_goals]);
+	const mission = deps.assessMissionAnchor(capsule.mission, projectName).derived;
+	const goalText = buildContextProposalGoalText({
+		mission,
+		scope: capsule.scope,
+		constraints,
+		acceptance: capsule.acceptance,
+	});
+	const proposal: ContextProposal = {
+		mission,
+		scope: [...capsule.scope],
+		constraints,
+		acceptance: [...capsule.acceptance],
+		analysis: finalizeContextProposalAnalysis(
+			{
+				taskType: capsule.task_type,
+				evaluationProfile: capsule.evaluation_profile,
+				critique: [
+					...capsule.notes,
+					...(capsule.why_cook_now ? [`Primary-agent /cook handoff rationale: ${capsule.why_cook_now}`] : []),
+				],
+				risks: capsule.risks,
+				possibleNoise: [],
+				alternateMissions: [],
+				suppressedCompletedTopics: [],
+				suppressedNegatedTopics: [],
+			},
+			[mission, goalText, capsule.mission, ...capsule.scope, ...constraints, ...capsule.acceptance],
+		),
+		goalText,
+		basisPreview: buildCookHandoffBasisPreview(capsule),
+		source: "handoff_capsule",
+		alternateProposals: [],
+	};
+	return finalizeContextProposal(proposal, projectName, deps);
+}
+
+export function extractLatestCookHandoffProposal(
+	recentMessages: RecentSessionMessage[],
+	projectName: string,
+	deps: ProposalParseDeps,
+): ContextProposal | undefined {
+	for (let index = 0; index < recentMessages.length; index += 1) {
+		const entry = recentMessages[index];
+		if (entry.role !== "assistant" || entry.isCommand) continue;
+		const capsules = parseCookHandoffCapsulesFromText(entry.text, entry.messageId, entry.timestampMs, deps);
+		if (capsules.length === 0) continue;
+		for (let capsuleIndex = capsules.length - 1; capsuleIndex >= 0; capsuleIndex -= 1) {
+			const capsule = capsules[capsuleIndex];
+			const laterMessages = recentMessages.slice(0, index);
+			if (!cookHandoffIsFreshEnough(capsule, laterMessages)) continue;
+			if (laterMessagesInvalidateCookHandoff(laterMessages, deps)) continue;
+			const proposal = buildContextProposalFromCookHandoffCapsule(capsule, projectName, deps);
+			if (proposal) return proposal;
+		}
+	}
+	return undefined;
+}
+
 export async function deriveCookContextProposalFromRecentDiscussion(
 	projectName: string,
 	recentEntries: RecentDiscussionEntry[],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linimin/pi-letscook",
-  "version": "0.1.55",
+  "version": "0.1.57",
   "description": "Pi package for long-running completion workflows with canonical .agent state, role-based subagents, continuity, and verification helpers.",
   "license": "MIT",
   "private": false,

package/scripts/context-proposal-test.sh

@@ -47,6 +47,49 @@ with session_path.open('w', encoding='utf-8') as fh:
 PY
 }
 
+write_session_messages() {
+  local session_path="$1"
+  local cwd="$2"
+  local messages_json="$3"
+  python3 - "$session_path" "$cwd" "$messages_json" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+session_path = Path(sys.argv[1])
+cwd = sys.argv[2]
+messages = json.loads(sys.argv[3])
+session_path.parent.mkdir(parents=True, exist_ok=True)
+entries = [
+    {
+        "type": "session",
+        "version": 3,
+        "id": "11111111-1111-4111-8111-111111111111",
+        "timestamp": "2026-01-01T00:00:00.000Z",
+        "cwd": cwd,
+    },
+]
+parent_id = None
+for index, message in enumerate(messages, start=1):
+    entry_id = f"m{index:04d}"
+    entries.append({
+        "type": "message",
+        "id": entry_id,
+        "parentId": parent_id,
+        "timestamp": f"2026-01-01T00:00:{index:02d}.000Z",
+        "message": {
+            "role": message["role"],
+            "content": message["content"],
+            "timestamp": 1767225600000 + index * 1000,
+        },
+    })
+    parent_id = entry_id
+with session_path.open('w', encoding='utf-8') as fh:
+    for entry in entries:
+        fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+PY
+}
+
 mark_done() {
   python3 - <<'PY'
 import json
@@ -1358,7 +1401,253 @@ assert 'Discuss changes in the main chat and rerun /cook.' in output, 'cancel co
 assert not Path('.agent').exists(), 'cancel action should not write canonical workflow state'
 PY
 
+# Explicit primary-agent handoff: /cook should prefer the structured handoff capsule over broad context re-inference.
+HANDOFF_ROOT_START="$TMPDIR/handoff-root-start"
+mkdir -p "$HANDOFF_ROOT_START"
+cd "$HANDOFF_ROOT_START"
+git init -q
+
+HANDOFF_SESSION_START="$TMPDIR/handoff-session-start.jsonl"
+HANDOFF_SNAPSHOT_START="$TMPDIR/handoff-proposal-start.json"
+HANDOFF_MESSAGES_START="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Fix login redirect callback behavior.",
+    "scope": [
+        "Update the callback redirect decision logic.",
+        "Preserve the broader auth flow."
+    ],
+    "constraints": [
+        "Do not refactor the broader auth flow."
+    ],
+    "acceptance": [
+        "Add a regression test for returning to the requested page."
+    ],
+    "risks": [
+        "Stale auth discussion could broaden the startup brief if the handoff is ignored."
+    ],
+    "notes": [
+        "Keep the startup brief aligned with the explicit primary-agent plan."
+    ],
+    "handoff_kind": "implementation_workflow_ready",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "The implementation plan is concrete and ready for repo changes."
+}
+messages = [
+    {"role": "user", "content": "Please think through the login redirect fix and tell me when it is ready for /cook."},
+    {"role": "assistant", "content": "This task is now ready for /cook. Run /cook to confirm the startup brief.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
+]
+print(json.dumps(messages, ensure_ascii=False))
+PY
+)"
+write_session_messages "$HANDOFF_SESSION_START" "$HANDOFF_ROOT_START" "$HANDOFF_MESSAGES_START"
+
+PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
+PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$HANDOFF_SNAPSHOT_START" \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$HANDOFF_SESSION_START" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-start.out" 2>"$TMPDIR/pi-completion-handoff-start.err"
+
+python3 - "$HANDOFF_SNAPSHOT_START" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+snapshot = json.loads(Path(sys.argv[1]).read_text())
+state = json.loads(Path('.agent/state.json').read_text())
+
+assert snapshot['source'] == 'handoff_capsule', 'explicit handoff startup should snapshot the handoff capsule as the proposal source'
+assert snapshot['mission'] == 'Fix login redirect callback behavior.', 'explicit handoff startup should preserve the primary-agent mission'
+assert state['mission_anchor'] == 'Fix login redirect callback behavior.', 'explicit handoff startup should use the handoff mission as canonical mission_anchor'
+assert state['advisory_startup_brief']['source'] == 'primary_agent_handoff', 'explicit handoff startup should preserve the advisory intake source'
+assert state['advisory_startup_brief']['risks'] == ['Stale auth discussion could broaden the startup brief if the handoff is ignored.'], 'explicit handoff startup should preserve handoff risks'
+assert 'Primary-agent /cook handoff rationale: The implementation plan is concrete and ready for repo changes.' in state['advisory_startup_brief']['notes'], 'explicit handoff startup should preserve why_cook_now as notes'
+PY
+
+# Done workflow + fresh handoff: the fresh explicit handoff should override done-state suppression and start the new round.
+HANDOFF_ROOT_DONE="$TMPDIR/handoff-root-done"
+mkdir -p "$HANDOFF_ROOT_DONE"
+cd "$HANDOFF_ROOT_DONE"
+git init -q
+
+DONE_SEED_SESSION="$TMPDIR/handoff-done-seed-session.jsonl"
+DONE_SEED_DISCUSSION=$'Mission: Seed a finished workflow before testing fresh handoff priority.\nScope:\n- Create canonical workflow state.\nConstraints:\n- Keep the seed minimal.\nAcceptance:\n- Mark the workflow done before the next test step.'
+write_session "$DONE_SEED_SESSION" "$HANDOFF_ROOT_DONE" "$DONE_SEED_DISCUSSION"
+PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
+PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$DONE_SEED_SESSION" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-done-seed.out" 2>"$TMPDIR/pi-completion-handoff-done-seed.err"
+mark_done
+
+HANDOFF_SESSION_DONE="$TMPDIR/handoff-session-done.jsonl"
+HANDOFF_SNAPSHOT_DONE="$TMPDIR/handoff-proposal-done.json"
+HANDOFF_MESSAGES_DONE="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Reopen the login redirect work for the callback edge case.",
+    "scope": [
+        "Handle the callback edge case in the redirect logic.",
+        "Keep the finished workflow as historical context only."
+    ],
+    "constraints": [
+        "Do not turn done-state suppression into the startup mission."
+    ],
+    "acceptance": [
+        "Add a regression test for the callback edge case."
+    ],
+    "risks": [
+        "Done-state context could override the new mission if the handoff is ignored."
+    ],
+    "notes": [
+        "This is a fresh implementation round, not a summary of the finished workflow."
+    ],
+    "handoff_kind": "implementation_workflow_ready",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "A new implementation-ready edge case was identified after the previous round closed."
+}
+messages = [
+    {"role": "user", "content": "The previous round is done, but there is a fresh callback edge case to implement."},
+    {"role": "assistant", "content": "The next round is ready for /cook. Run /cook to confirm this fresh implementation mission.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
+]
+print(json.dumps(messages, ensure_ascii=False))
+PY
+)"
+write_session_messages "$HANDOFF_SESSION_DONE" "$HANDOFF_ROOT_DONE" "$HANDOFF_MESSAGES_DONE"
+
+PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
+PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$HANDOFF_SNAPSHOT_DONE" \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$HANDOFF_SESSION_DONE" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-done.out" 2>"$TMPDIR/pi-completion-handoff-done.err"
+
+python3 - "$HANDOFF_SNAPSHOT_DONE" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+snapshot = json.loads(Path(sys.argv[1]).read_text())
+state = json.loads(Path('.agent/state.json').read_text())
+
+assert snapshot['source'] == 'handoff_capsule', 'done-workflow handoff should still use the explicit handoff capsule'
+assert snapshot['mission'] == 'Reopen the login redirect work for the callback edge case.', 'done-workflow handoff should preserve the fresh mission'
+assert state['mission_anchor'] == 'Reopen the login redirect work for the callback edge case.', 'done-workflow handoff should override done-state suppression with the fresh mission'
+assert state['continuation_policy'] == 'continue', 'done-workflow handoff should reopen canonical workflow state for the new round'
+assert state['advisory_startup_brief']['source'] == 'primary_agent_handoff', 'done-workflow handoff should preserve the handoff advisory source'
+PY
+
+# Stale handoff: later discussion should invalidate the older handoff capsule and fall back to the newer discussion mission.
+HANDOFF_ROOT_STALE="$TMPDIR/handoff-root-stale"
+mkdir -p "$HANDOFF_ROOT_STALE"
+cd "$HANDOFF_ROOT_STALE"
+git init -q
+
+HANDOFF_SESSION_STALE="$TMPDIR/handoff-session-stale.jsonl"
+HANDOFF_SNAPSHOT_STALE="$TMPDIR/handoff-proposal-stale.json"
+HANDOFF_MESSAGES_STALE="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Fix the original login redirect callback behavior.",
+    "scope": ["Update the original callback redirect logic."],
+    "constraints": ["Do not refactor the auth stack."],
+    "acceptance": ["Add the original callback regression test."],
+    "risks": [],
+    "notes": [],
+    "handoff_kind": "implementation_workflow_ready"
+}
+newer_discussion = "Mission: Ship logout redirect consistency instead.\nScope:\n- Update the logout redirect path.\nConstraints:\n- Leave the login callback flow unchanged.\nAcceptance:\n- Add a logout redirect regression test."
+messages = [
+    {"role": "user", "content": "Please plan the login redirect follow-up."},
+    {"role": "assistant", "content": "Run /cook if you want to start the original follow-up.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
+    {"role": "user", "content": newer_discussion},
+]
+print(json.dumps(messages, ensure_ascii=False))
+PY
+)"
+write_session_messages "$HANDOFF_SESSION_STALE" "$HANDOFF_ROOT_STALE" "$HANDOFF_MESSAGES_STALE"
+
+PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
+PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$HANDOFF_SNAPSHOT_STALE" \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$HANDOFF_SESSION_STALE" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-stale.out" 2>"$TMPDIR/pi-completion-handoff-stale.err"
+
+python3 - "$HANDOFF_SNAPSHOT_STALE" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+snapshot = json.loads(Path(sys.argv[1]).read_text())
+state = json.loads(Path('.agent/state.json').read_text())
+
+assert snapshot['source'] == 'session', 'stale handoff should fall back to the newer user discussion proposal'
+assert snapshot['mission'] == 'Ship logout redirect consistency instead.', 'stale handoff fallback should prefer the newer discussion mission'
+assert state['mission_anchor'] == 'Ship logout redirect consistency instead.', 'stale handoff fallback should not keep the older handoff mission'
+assert state['advisory_startup_brief']['source'] == 'recent_discussion', 'stale handoff fallback should preserve that the accepted startup came from discussion'
+PY
+
+# Negative handoff rationale: a non-startable capsule must not become the startup mission.
+HANDOFF_ROOT_NEGATIVE="$TMPDIR/handoff-root-negative"
+mkdir -p "$HANDOFF_ROOT_NEGATIVE"
+cd "$HANDOFF_ROOT_NEGATIVE"
+git init -q
+
+HANDOFF_SESSION_NEGATIVE="$TMPDIR/handoff-session-negative.jsonl"
+HANDOFF_SNAPSHOT_NEGATIVE="$TMPDIR/handoff-proposal-negative.json"
+HANDOFF_MESSAGES_NEGATIVE="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Do not reopen implementation for the finished workflow.",
+    "scope": ["Keep the old workflow closed."],
+    "constraints": ["Do not start repo changes."],
+    "acceptance": ["Explain that the finished workflow should stay closed."],
+    "risks": [],
+    "notes": [],
+    "handoff_kind": "implementation_workflow_ready"
+}
+messages = [
+    {"role": "user", "content": "Should we reopen the finished workflow?"},
+    {"role": "assistant", "content": "Do not reopen it directly.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
+]
+print(json.dumps(messages, ensure_ascii=False))
+PY
+)"
+write_session_messages "$HANDOFF_SESSION_NEGATIVE" "$HANDOFF_ROOT_NEGATIVE" "$HANDOFF_MESSAGES_NEGATIVE"
+
+PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$HANDOFF_SNAPSHOT_NEGATIVE" \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$HANDOFF_SESSION_NEGATIVE" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-negative.out" 2>"$TMPDIR/pi-completion-handoff-negative.err"
+
+python3 - "$HANDOFF_SNAPSHOT_NEGATIVE" "$TMPDIR/pi-completion-handoff-negative.out" "$TMPDIR/pi-completion-handoff-negative.err" <<'PY'
+import sys
+from pathlib import Path
+
+snapshot = Path(sys.argv[1])
+output = Path(sys.argv[2]).read_text() + Path(sys.argv[3]).read_text()
+
+assert not snapshot.exists(), 'negative handoff rationale should not emit a startup proposal snapshot'
+assert not Path('.agent').exists(), 'negative handoff rationale should fail closed without writing canonical state'
+assert '/cook failed closed' in output, 'negative handoff rationale should fail closed instead of becoming the startup mission'
+PY
+
 grep -q 'export async function deriveCookContextProposalFromRecentDiscussion' "$PKG_ROOT/extensions/completion/proposal.ts"
+grep -q 'export function extractLatestCookHandoffProposal' "$PKG_ROOT/extensions/completion/proposal.ts"
 grep -q 'export function parseContextProposalAnalystOutput' "$PKG_ROOT/extensions/completion/proposal.ts"
 grep -q 'export function buildContextProposalConfirmationLayout' "$PKG_ROOT/extensions/completion/prompt-surfaces.ts"
 grep -q 'export function buildEvaluationRoleContextLines' "$PKG_ROOT/extensions/completion/prompt-surfaces.ts"

package/scripts/release-check.sh

@@ -17,17 +17,21 @@ checks = {
     "README.md": [
         "`/cook` is the explicit workflow boundary for starting, continuing, refocusing, or beginning the next round of long-running repo work.",
         "Only explicit `/cook` enters the workflow. Ordinary prompts stay in the main chat and go straight to the primary agent.",
-        "`/cook` is the canonical workflow boundary and manual entry point",
-        "Discuss the concrete repo change in the main chat, then run `/cook`",
-        "The confirmed startup brief is also preserved there as advisory intake for later re-grounding.",
+        "If a task has clearly matured into completion-workflow scope, the primary agent should hand you off to `/cook` instead of starting long-running implementation directly in ordinary chat.",
+        "That handoff should include an explicit structured `/cook` capsule in the assistant reply so `/cook` can confirm the already-formed mission instead of re-deriving it from broad ambient context.",
+        "`/cook` first looks for a fresh explicit primary-agent handoff capsule.",
+        "The pre-`/cook` handoff capsule itself is not canonical workflow state. It is only startup intake for `/cook`.",
     ],
     "CHANGELOG.md": [
-        "made `/cook` derive a confirmable startup brief from recent discussion before any canonical workflow rewrite, then preserve the confirmed brief in canonical state as advisory intake for later re-grounding",
-        "removed inline `/cook` arguments from the shipped entry path again so explicit bare `/cook` is the only public command, and fail closed when recent discussion is insufficient or unreliable",
+        "made explicit primary-agent `/cook` handoff the preferred startup-intake path by teaching ordinary-chat handoff turns to emit a structured `cook_handoff` capsule and letting `/cook` prefer that capsule over broad context re-inference when it is fresh and valid",
+        "kept context-derived startup as a fallback only, so stale, drifted, or non-startable handoff capsules still fail closed or fall back to recent discussion instead of silently rewriting canonical state",
+        "made finished-workflow suppression stay a safety layer instead of a replacement mission when a fresh explicit `/cook` handoff exists, and blocked negative rejection/suppression text from becoming a Startable startup mission",
     ],
-    "extensions/completion/index.ts": [
-        'description: "/cook workflow: derive a startup brief from recent discussion, then start, continue, refocus, or start the next round from the explicit /cook command"',
-        '"/cook failed closed because recent discussion did not produce a clear execution-ready startup brief with Mission/Scope/Constraints/Acceptance for concrete repo changes. Clarify the concrete repo changes in the main chat and rerun /cook."',
+    "extensions/completion/prompt-surfaces.ts": [
+        '"/cook is the only explicit entrypoint into long-running completion workflow."',
+        '"When you judge that the task has matured into completion-workflow scope',
+        '"Also append one exact fenced block in the same assistant reply using ```cook_handoff ... ``` JSON',
+        '"The capsule is startup intake for /cook only: do not present it as canonical .agent state',
     ],
 }
 

package/scripts/smoke-test.sh

@@ -51,6 +51,7 @@ ROOT="$TMPDIR/repo"
 KICKOFF_PROMPT="$TMPDIR/kickoff-prompt.txt"
 RESUME_PROMPT="$TMPDIR/resume-prompt.txt"
 ORDINARY_SYSTEM_REMINDER="$TMPDIR/ordinary-system-reminder.txt"
+ORDINARY_HANDOFF_REMINDER="$TMPDIR/ordinary-handoff-reminder.txt"
 UNCLEAR_ROUTING_SNAPSHOT="$TMPDIR/active-unclear-routing.json"
 UNCLEAR_CHOOSER_SNAPSHOT="$TMPDIR/unexpected-existing-workflow-chooser.json"
 ORDINARY_AUTO_RESUME_PROMPT="$TMPDIR/ordinary-auto-resume-prompt.txt"
@@ -146,23 +147,31 @@ assert f'- task_type: {expected_task_type}' in kickoff, 'kickoff prompt missing
 assert f'- evaluation_profile: {expected_eval_profile}' in kickoff, 'kickoff prompt missing canonical evaluation_profile'
 PY
 
-rm -f "$ORDINARY_SYSTEM_REMINDER" "$ORDINARY_AUTO_RESUME_PROMPT"
+rm -f "$ORDINARY_SYSTEM_REMINDER" "$ORDINARY_HANDOFF_REMINDER" "$ORDINARY_AUTO_RESUME_PROMPT"
 PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
 PI_COMPLETION_TEST_SYSTEM_REMINDER_PATH="$ORDINARY_SYSTEM_REMINDER" \
+PI_COMPLETION_TEST_COOK_HANDOFF_REMINDER_PATH="$ORDINARY_HANDOFF_REMINDER" \
 PI_COMPLETION_TEST_AUTO_CONTINUE_ON_SESSION_START=1 \
 PI_COMPLETION_TEST_AUTO_CONTINUE_PROMPT_PATH="$ORDINARY_AUTO_RESUME_PROMPT" \
 pi -e "$PKG_ROOT" -p "Summarize the repo briefly." \
   >"$TMPDIR/pi-completion-smoke-ordinary.out" 2>"$TMPDIR/pi-completion-smoke-ordinary.err"
 
-python3 - "$TMPDIR/pi-completion-smoke-ordinary.out" "$TMPDIR/pi-completion-smoke-ordinary.err" "$ORDINARY_SYSTEM_REMINDER" "$ORDINARY_AUTO_RESUME_PROMPT" <<'PY'
+python3 - "$TMPDIR/pi-completion-smoke-ordinary.out" "$TMPDIR/pi-completion-smoke-ordinary.err" "$ORDINARY_SYSTEM_REMINDER" "$ORDINARY_HANDOFF_REMINDER" "$ORDINARY_AUTO_RESUME_PROMPT" <<'PY'
 import sys
 from pathlib import Path
 
 output = Path(sys.argv[1]).read_text() + Path(sys.argv[2]).read_text()
 reminder = Path(sys.argv[3])
-auto_resume = Path(sys.argv[4])
+handoff = Path(sys.argv[4])
+auto_resume = Path(sys.argv[5])
 
 assert not reminder.exists(), 'ordinary non-/cook turn should not inject completion reminder solely from canonical state'
+assert handoff.exists(), 'ordinary non-/cook turn should inject the /cook handoff boundary reminder'
+handoff_text = handoff.read_text()
+assert '/cook is the only explicit entrypoint into long-running completion workflow.' in handoff_text, 'ordinary handoff reminder should preserve the explicit /cook workflow boundary'
+assert 'stop short of long-running implementation and tell the user to run /cook.' in handoff_text, 'ordinary handoff reminder should require primary-agent handoff before implementation'
+assert '```cook_handoff ... ``` JSON' in handoff_text, 'ordinary handoff reminder should require the explicit structured /cook handoff capsule'
+assert 'The capsule is startup intake for /cook only' in handoff_text, 'ordinary handoff reminder should keep the capsule non-canonical'
 assert not auto_resume.exists(), 'ordinary non-/cook turn should not queue auto-resume before /cook activation'
 assert 'Skipped completion workflow auto-resume prompt (test mode)' not in output, 'ordinary non-/cook turn should not attempt auto-resume'
 PY

package/skills/cook-handoff-boundary/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: cook-handoff-boundary
+description: Ordinary-chat boundary contract for deciding when a task has matured enough that the primary agent must stop short of long-running implementation and hand the user off to `/cook`.
+---
+
+# /cook Handoff Boundary
+
+Load or summarize this contract when the primary agent is operating in ordinary main chat before the user has explicitly entered `/cook`.
+
+This skill governs the boundary between:
+
+- ordinary main-chat discussion, clarification, and proposal work
+- explicit transition into long-running completion workflow through `/cook`
+
+## Core Contract
+
+- Ordinary chat may be used to clarify requirements, discuss tradeoffs, and propose implementation approaches.
+- `/cook` is the only explicit entrypoint into long-running completion workflow.
+- When the primary agent judges that a task has matured into completion-workflow scope, it must stop short of implementation and direct the user to `/cook`.
+
+## When To Hand Off To `/cook`
+
+The primary agent should consider `/cook` handoff appropriate when one or more of the following are true:
+
+- the user has clearly shifted from exploration into implementation intent
+- the agent has just produced a concrete plan or proposal whose natural next step would be implementation
+- the task spans multiple files, steps, or verification surfaces
+- the task needs resumability, review, audit, or canonical workflow state
+- the task is better treated as a long-running repo mission than a one-off answer or tiny fix
+
+## Required Handoff Behavior
+
+When the task is judged ready for completion workflow, the primary agent must:
+
+- stop before long-running implementation
+- not edit tracked product files in ordinary chat for that workflow-level task
+- tell the user to run `/cook`
+- explain that `/cook` will first look for a fresh explicit primary-agent handoff and otherwise fall back to recent discussion before asking for confirmation
+- append one exact structured `/cook` handoff capsule in the same assistant reply
+
+Required capsule format:
+
+````text
+```cook_handoff
+{
+  "kind": "cook_handoff",
+  "source": "primary_agent",
+  "captured_at": "<ISO-8601 timestamp>",
+  "source_turn_id": "<current assistant turn id>",
+  "mission": "<startable implementation mission>",
+  "scope": ["..."],
+  "constraints": ["..."],
+  "acceptance": ["..."],
+  "risks": ["..."],
+  "notes": ["..."],
+  "handoff_kind": "implementation_workflow_ready",
+  "task_type": "completion-workflow",
+  "evaluation_profile": "completion-rubric-v1",
+  "why_cook_now": "<why the task is ready for /cook now>"
+}
+```
+````
+
+Notes:
+
+- `constraints` may be replaced or supplemented by `non_goals` when clearer.
+- The mission must be positively startable implementation work; do not use rejection or suppression text as the mission.
+- The capsule is startup intake for `/cook` only. It is not canonical `.agent/**` state, not active-slice state, and not a second repo contract source.
+
+Suggested wording:
+
+> This task is now mature enough for the `/cook` workflow. If you want me to start implementation, run `/cook`. I’ve also attached an explicit `/cook` handoff capsule so `/cook` can confirm this plan directly before the workflow begins.
+
+A short recap may include mission, scope, or acceptance, but that recap must not be presented as canonical plan state.
+
+## Forbidden Behaviors
+
+Once the task is judged ready for completion workflow, the primary agent must not:
+
+- directly begin long-running implementation in ordinary chat
+- modify tracked product files as part of that workflow-level task
+- act as though `/cook` had already been invoked
+- silently rewrite ordinary-chat discussion into active workflow state
+
+## Relationship To `completion-protocol`
+
+This skill is only about pre-`/cook` ordinary-chat handoff behavior.
+
+After the user explicitly enters `/cook`, the separate `completion-protocol` skill governs:
+
+- canonical `.agent/**` workflow state
+- workflow-driver behavior
+- mandatory completion-role dispatch
+- review, audit, and stop-wave rules