@linimin/pi-letscook 0.1.63 → 0.1.65

package/README.md

@@ -35,7 +35,7 @@ Then run `/reload` in Pi.
 3. In the main chat, either implement directly with the agent or refine the concrete repo change you want.
 4. When you want workflow mode, run `/cook`.
 5. Review the startup brief and choose **Start** or **Cancel**.
-6. Later, run `/cook` again to resume from canonical state or confirm a primary-agent-authored replacement or next-round handoff.
+6. Later, run `/cook` again to resume from canonical state or confirm a replacement or next-round handoff.
 
 ```text
 /cook
@@ -46,20 +46,20 @@ Then run `/reload` in Pi.
 | If you want to... | Do this |
 |---|---|
 | Implement directly without workflow | Ask in ordinary chat and let the agent modify the repo directly |
-| Start a tracked workflow | Ask the primary agent in ordinary chat to prepare the explicit `/cook` handoff, then run `/cook` |
+| Start a tracked workflow | Discuss the concrete repo change in ordinary chat, then run `/cook` when you want workflow mode |
 | Continue the current workflow | Run `/cook` |
-| Refocus or start the next round | Ask the primary agent in ordinary chat to prepare the fresh explicit `/cook` handoff for the new slice, then run `/cook` |
+| Refocus or start the next round | Discuss the new concrete repo change in ordinary chat, then run `/cook` when you want workflow mode |
 
 ## What `/cook` expects
 
-- a fresh explicit primary-agent `cook_handoff` capsule for any new-workflow, next-round, or replacement startup
-- a mission and first slice concrete enough for the primary agent to author the startup handoff directly
+- enough current task context for a primary-agent handoff synthesis step to produce a concrete workflow startup handoff
+- a mission and first slice concrete enough for the primary-agent handoff step to author a truthful implementation-startable handoff
 - acceptance and verification intent that can support a truthful first workflow round
 - README/CHANGELOG updates still count as concrete repo changes
-- assistant-produced summaries and plan/spec/design-doc/proposal-only artifacts still do not count unless the primary agent turns them into an explicit `cook_handoff` capsule
-- `/cook` does not synthesize startup from recent discussion when handoff data is missing; the primary agent must provide the handoff
+- assistant-produced summaries and plan/spec/design-doc/proposal-only artifacts still do not count unless the primary-agent handoff step turns them into a concrete `cook_handoff` capsule
+- `/cook` first prefers a fresh explicit `cook_handoff` capsule when one already exists, but otherwise calls the primary-agent handoff synthesis step in the same `/cook` entry
 
-If no fresh explicit primary-agent handoff exists, `/cook` fails closed, leaves canonical `.agent/**` state unchanged, and tells you to ask the primary agent in the main chat to emit a fresh `cook_handoff` capsule before rerunning `/cook`.
+If the primary-agent handoff step still cannot prepare a concrete handoff, `/cook` fails closed, leaves canonical `.agent/**` state unchanged, and tells you to refine the mission, first slice, or verification intent in the main chat before rerunning `/cook`.
 
 If a fresh explicit handoff exists but is still workflow-worthy rather than implementation-startable, `/cook` also fails closed instead of silently treating that capsule as planning support or canonical workflow state.
 
@@ -71,14 +71,14 @@ Only explicit `/cook` enters workflow mode. Ordinary prompts stay in the main ch
 
 Ordinary chat can still directly implement repo changes. `/cook` is for the cases where you want workflow control rather than just implementation help, and the primary agent should prepare the handoff before you run it.
 
-When you explicitly run `/cook`, it should consume the explicit primary-agent handoff you already prepared in ordinary chat, then ask you to **Start** or **Cancel** before rewriting canonical workflow state.
+When you explicitly run `/cook`, it first checks for a fresh explicit primary-agent handoff. If one is missing, it calls a same-entry primary-agent handoff synthesis step from the current task context, then asks you to **Start** or **Cancel** before rewriting canonical workflow state.
 
-Explicit `/cook` capsules are the required startup intake for new-workflow, next-round, and replacement entry.
+Explicit `/cook` capsules are still valid startup intake, but they are no longer the only path because `/cook` can synthesize the primary-agent handoff in the same entry when needed.
 
 Important behavior:
 - `/cook` is an optional workflow boundary and manual entry point
-- startup and next-round entry stay confirm-first, but they start from explicit primary-agent handoff data rather than recent-discussion guessing
-- active workflows resume from canonical `.agent/**` state unless a fresh explicit primary-agent handoff proposes a concrete replacement mission
+- startup and next-round entry stay confirm-first, using explicit primary-agent handoff data when present and otherwise running the primary-agent handoff synthesis step in the same `/cook` entry
+- active workflows resume from canonical `.agent/**` state unless a concrete replacement handoff is available or synthesized in the same `/cook` entry
 - explicit slash commands other than `/cook` continue normally in the main chat
 - ordinary main-chat discussion may clarify, propose, or directly implement repo changes without entering workflow mode
 
@@ -94,13 +94,13 @@ I want to add login redirect handling and tests.
 
 ## What happens when you run `/cook`
 
-`/cook` first checks for a fresh explicit primary-agent handoff capsule. New-workflow entry, done-workflow next-round entry, and active-workflow replacement should use that handoff instead of guessing from recent discussion. If no fresh explicit handoff exists, `/cook` fails closed for startup/refocus and resumes canonical state only when continuing the existing workflow. None of this prevents ordinary-chat implementation when you choose not to enter workflow mode.
+`/cook` first checks for a fresh explicit primary-agent handoff capsule. New-workflow entry and done-workflow next-round entry use that handoff when it already exists; otherwise `/cook` calls a same-entry primary-agent handoff synthesis step, then immediately continues to Start / Cancel if the generated handoff is concrete enough. Active workflows still resume canonical state by default unless a concrete replacement handoff is available or synthesized in the same `/cook` entry. None of this prevents ordinary-chat implementation when you choose not to enter workflow mode.
 
 | Repo state | What you'll see |
 |---|---|
-| No workflow yet | `/cook` consumes a fresh explicit primary-agent handoff and asks you to choose **Start** or **Cancel**. Missing, stale, planning-only, or non-startable handoffs fail closed. |
-| Active workflow exists | Usually a resume of the current workflow from canonical `.agent/**` state. If a fresh explicit primary-agent handoff points to a different concrete replacement mission, `/cook` shows a chooser first and only rewrites canonical state after you confirm the replacement. Ambiguous or missing replacement handoff stays conservative. |
-| Previous workflow is `done` | `/cook` can start the next implementation round only from a fresh explicit primary-agent handoff behind **Start** or **Cancel**. Missing, weak, or planning-only next-round handoffs fail closed. |
+| No workflow yet | `/cook` consumes a fresh explicit primary-agent handoff when one already exists, or synthesizes one from the primary-agent view in the same entry, then asks you to choose **Start** or **Cancel**. Stale, planning-only, or non-startable handoffs still fail closed. |
+| Active workflow exists | Usually a resume of the current workflow from canonical `.agent/**` state. If a concrete replacement handoff exists already or is synthesized in the same `/cook` entry and points to a different mission, `/cook` shows a chooser first and only rewrites canonical state after you confirm the replacement. Ambiguous or missing replacement handoff stays conservative. |
+| Previous workflow is `done` | `/cook` can start the next implementation round from a fresh explicit primary-agent handoff or from the same-entry primary-agent handoff synthesis step behind **Start** or **Cancel**. Weak or planning-only next-round handoffs still fail closed. |
 
 ## Confirmation and fail-closed behavior
 

package/extensions/completion/driver.ts

@@ -182,6 +182,7 @@ function buildCookStructuredDiscussionFailureMessage(deps: CompletionDriverDeps,
 	return prefix ? `${prefix} ${deps.structuredDiscussionFailureDetail}` : deps.structuredDiscussionFailureDetail;
 }
 
+
 export function completionContinuationFingerprint(snapshot: CompletionStateSnapshot): string | undefined {
 	if (asString(snapshot.state?.continuation_policy) !== "continue") return undefined;
 	const nextMandatoryRole = asString(snapshot.state?.next_mandatory_role);
@@ -320,18 +321,18 @@ async function assessActiveWorkflowProposalRouting(
 ): Promise<ActiveWorkflowProposalAssessment> {
 	const currentMission = currentMissionAnchor(snapshot);
 	const projectName = path.basename(snapshot.files.root);
-	const explicitHandoff = await deps.deriveCookStartupProposal(ctx, projectName);
-	if (explicitHandoff.blockedFailureMessage) {
+	const proposalResult = await deps.deriveCookContextProposal(ctx, projectName);
+	if (proposalResult.blockedFailureMessage) {
 		const assessment: ActiveWorkflowProposalAssessment = {
 			action: "blocked",
 			currentMissionAnchor: currentMission,
-			blockedFailureMessage: explicitHandoff.blockedFailureMessage,
+			blockedFailureMessage: proposalResult.blockedFailureMessage,
 			reason: "fresh_explicit_handoff_not_startable",
 		};
 		deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
 		return assessment;
 	}
-	const proposal = explicitHandoff.proposal;
+	const proposal = proposalResult.proposal;
 	if (!proposal) {
 		const assessment: ActiveWorkflowProposalAssessment = {
 			action: "continue",
@@ -535,7 +536,7 @@ export async function runCookEntry(
 	if (!snapshot) {
 		const root = findRepoRoot(cwd) ?? cwd;
 		const projectName = path.basename(root);
-		const derived = await deps.deriveCookStartupProposal(ctx, projectName);
+		const derived = await deps.deriveCookContextProposal(ctx, projectName);
 		if (derived.blockedFailureMessage) {
 			deps.emitCommandText(ctx, derived.blockedFailureMessage, "info");
 			return;
@@ -580,7 +581,7 @@ export async function runCookEntry(
 	if (!goal) {
 		if (workflowDone) {
 			const projectName = path.basename(snapshot.files.root);
-			const derived = await deps.deriveCookStartupProposal(ctx, projectName);
+			const derived = await deps.deriveCookContextProposal(ctx, projectName);
 			if (derived.blockedFailureMessage) {
 				deps.emitCommandText(ctx, derived.blockedFailureMessage, "info");
 				return;

package/extensions/completion/index.ts

@@ -17,7 +17,6 @@ import {
 	assessMissionAnchor,
 	collectRecentDiscussionEntries,
 	collectRecentSessionMessages,
-	deriveCookContextProposalFromRecentDiscussion,
 	assessLatestCookHandoffProposal,
 	finalizeContextProposalAnalysis,
 	isWeakMissionAnchor,
@@ -25,7 +24,6 @@ import {
 	missionAnchorsStrictlyEquivalent,
 	normalizeMissionAnchorText,
 	resolveContextProposalConfirmationAction,
-	retagContextProposalSource,
 	stripCodeBlocks,
 } from "./proposal";
 import type {
@@ -49,7 +47,7 @@ import {
 	maybeWriteContextProposalSnapshot,
 } from "./prompt-surfaces";
 import { toolCallBlockReason } from "./policy-guards";
-import { analyzeContextProposalWithAgent, runCompletionRole } from "./role-runner";
+import { analyzeContextProposalWithAgent, generateCookHandoffWithAgent, runCompletionRole } from "./role-runner";
 import {
 	applyLiveRoleEvent,
 	buildInlineRunningLines,
@@ -211,7 +209,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 starting workflow now requires a fresh explicit primary-agent handoff. Ask the primary agent in the main chat to emit a fresh ```cook_handoff``` capsule, then rerun /cook.";
+	"/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.";
 
 function isWorkflowDone(snapshot: CompletionStateSnapshot | undefined): boolean {
 	return asString(snapshot?.state?.continuation_policy) === "done";
@@ -374,6 +372,10 @@ async function promptContextProposalConfirmationAction(
 	});
 }
 
+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,
@@ -399,7 +401,54 @@ async function deriveCookContextProposal(
 	ctx: { cwd: string; hasUI: boolean; ui: any; sessionManager: any; model?: any; modelRegistry?: any },
 	projectName: string,
 ): Promise<CookContextProposalResult> {
-	return await deriveCookStartupProposal(ctx, projectName);
+	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"))
+		.slice(0, 12)
+		.map((entry) => ({ role: entry.role, text: stripCookHandoffBlocks(entry.text) }))
+		.filter((entry) => entry.text.length > 0);
+	const snapshot = await loadCompletionSnapshot(getCtxCwd(ctx));
+	const workflowContextLines = snapshot
+		? [
+			`current mission anchor: ${asString(snapshot.state?.mission_anchor) ?? asString(snapshot.plan?.mission_anchor) ?? asString(snapshot.active?.mission_anchor) ?? "(none)"}`,
+			`continuation policy: ${asString(snapshot.state?.continuation_policy) ?? "(none)"}`,
+			`latest completed slice: ${asString(snapshot.state?.latest_completed_slice) ?? "(none)"}`,
+			`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)"}`,
+			`verification goal: ${asString(snapshot.verificationEvidence?.goal) ?? "(none)"}`,
+			`verification summary: ${asString(snapshot.verificationEvidence?.summary) ?? "(none)"}`,
+		]
+		: [];
+	const raw = await generateCookHandoffWithAgent({
+		ctx,
+		projectName,
+		recentEntries,
+		workflowContextLines,
+		liveRoleActivityByRoot,
+		completionStatusKey: COMPLETION_STATUS_KEY,
+		safeUiCall,
+		getCtxCwd,
+		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 };
+	return {};
 }
 
 async function confirmContextProposal(

package/extensions/completion/prompt-surfaces.ts

@@ -32,9 +32,9 @@ export function buildCookHandoffBoundaryReminder(): string {
 		"/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.",
 		"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 asks to enter /cook workflow, generate one fresh ```cook_handoff``` capsule in ordinary chat from the primary-agent view of the task, then tell the user to run /cook.",
-		"Do not expect /cook to infer or guess startup intent from recent discussion alone; /cook should consume the explicit primary-agent handoff instead.",
-		"Only provide a preview startup brief or ```cook_handoff``` capsule in ordinary chat when the user explicitly asks for that preview behavior or explicitly asks to enter /cook workflow.",
+		"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.",
 		"When you continue in ordinary chat, do not pretend /cook already started and do not silently rewrite discussion into canonical workflow state.",
 	].join(" ");

package/extensions/completion/role-runner.ts

@@ -67,6 +67,8 @@ export type AnalyzeContextProposalWithAgentParams = {
 	getCtxUi: <T extends { ui: any }>(ctx: T) => any | undefined;
 };
 
+export type GenerateCookHandoffWithAgentParams = AnalyzeContextProposalWithAgentParams;
+
 const AGENT_HOME = path.join(os.homedir(), ".pi", "agent");
 const EXTENSION_DIR = typeof __dirname === "string" ? __dirname : process.cwd();
 const PACKAGE_ROOT_CANDIDATE = path.resolve(EXTENSION_DIR, "..", "..");
@@ -94,6 +96,18 @@ const CONTEXT_PROPOSAL_ANALYST_SYSTEM_PROMPT = [
 const STARTUP_ANALYST_ROLE = "cook-proposal-analyst";
 const ANALYST_HEARTBEAT_MS = 5_000;
 
+const PRIMARY_AGENT_HANDOFF_SYSTEM_PROMPT = [
+	"You are the primary agent preparing an explicit /cook handoff after the user already chose workflow mode.",
+	"Return either exactly one fenced ```cook_handoff JSON block or one brief plain sentence explaining why no concrete handoff can be prepared.",
+	"If you can prepare a handoff, the JSON must use kind cook_handoff, source primary_agent, and handoff_kind implementation_workflow_handoff.",
+	"When the user has clearly accepted a concrete assistant-proposed slice, carry that slice forward into the handoff instead of broadening or re-guessing the mission.",
+	"Do not make /cook infer or rediscover the mission from recent discussion later; author the handoff now from the primary-agent view of the task.",
+	"Do not emit markdown commentary before or after the capsule.",
+	"If the task is not concrete enough for implementation workflow, do not invent the slice.",
+	"A valid implementation-ready handoff must include mission, scope, constraints or non_goals, acceptance, risks, notes, first_slice_goal, first_slice_non_goals, implementation_surfaces, verification_commands, and why_this_slice_first.",
+].join(" ");
+const PRIMARY_AGENT_HANDOFF_ROLE = "cook-primary-agent-handoff";
+
 class StartupAnalystOverlay extends Container {
 	private readonly border: DynamicBorder;
 	private readonly title: Text;
@@ -309,6 +323,97 @@ async function runContextProposalAnalystSubprocess(params: AnalyzeContextProposa
 	return await run();
 }
 
+function serializeRecentConversationEntries(entries: RecentDiscussionEntry[]): string {
+	return entries
+		.slice()
+		.reverse()
+		.map((entry, index) => `[${index + 1}] ${entry.role.toUpperCase()}\n${entry.text}`)
+		.join("\n\n");
+}
+
+function buildPrimaryAgentHandoffPrompt(projectName: string, recentEntries: RecentDiscussionEntry[], workflowContextLines: string[] = []): string {
+	const lines = [
+		`Project: ${projectName}`,
+		"",
+		"Recent session transcript:",
+		serializeRecentConversationEntries(recentEntries),
+	];
+	if (workflowContextLines.length > 0) lines.push("", "Canonical workflow context:", ...workflowContextLines);
+	lines.push(
+		"",
+		"Task:",
+		"The user explicitly invoked /cook. Prepare the primary-agent handoff that /cook should consume immediately for Start/Cancel confirmation.",
+	);
+	return lines.join("\n");
+}
+
+async function runPrimaryAgentHandoffSubprocess(params: GenerateCookHandoffWithAgentParams): Promise<string | undefined> {
+	const { ctx, projectName, recentEntries } = params;
+	const modelArg = contextProposalAnalystModelArg(ctx.model);
+	if (!modelArg) return undefined;
+	const cwd = params.getCtxCwd(ctx);
+	const runCwd = findCompletionRoot(cwd) ?? findRepoRoot(cwd) ?? cwd;
+	const prompt = buildPrimaryAgentHandoffPrompt(projectName, recentEntries, params.workflowContextLines ?? []);
+	const systemPromptTemp = await writeTempFile(runCwd, "pi-cook-primary-agent-handoff-", PRIMARY_AGENT_HANDOFF_SYSTEM_PROMPT);
+	const args: string[] = ["--mode", "json", "-p", "--no-session", "--no-extensions", "--append-system-prompt", systemPromptTemp.filePath, "--model", modelArg, prompt];
+	const invocation = getPiInvocation(args);
+	const liveActivity = createLiveRoleActivity(PRIMARY_AGENT_HANDOFF_ROLE);
+	liveActivity.progress = "Preparing primary-agent /cook handoff";
+	liveActivity.currentAction = "Authoring explicit startup handoff from current task context";
+	liveActivity.assistantSummary = liveActivity.progress;
+	try {
+		const output = await new Promise<string | undefined>((resolve) => {
+			const proc = spawn(invocation.command, invocation.args, {
+				cwd: runCwd,
+				env: process.env,
+				stdio: ["ignore", "pipe", "pipe"],
+				shell: false,
+			});
+			let buffer = "";
+			const messages: RoleMessage[] = [];
+			const processLine = (line: string) => {
+				if (!line.trim()) return;
+				try {
+					const event = JSON.parse(line) as JsonRecord;
+					applyLiveRoleEvent(liveActivity, event, messages);
+				} catch {
+					// ignore malformed lines
+				}
+			};
+			proc.stdout.on("data", (chunk) => {
+				buffer += chunk.toString();
+				const lines = buffer.split("\n");
+				buffer = lines.pop() ?? "";
+				for (const line of lines) processLine(line);
+			});
+			proc.stderr.on("data", () => {
+				// ignore stderr unless no assistant output arrives
+			});
+			proc.on("close", (code) => {
+				if (buffer.trim()) processLine(buffer);
+				resolve(code === 0 ? liveActivity.lastAssistantText?.trim() || undefined : undefined);
+			});
+			proc.on("error", () => resolve(undefined));
+		});
+		return output;
+	} finally {
+		await fsp.rm(systemPromptTemp.dir, { recursive: true, force: true });
+	}
+}
+
+export async function generateCookHandoffWithAgent(params: GenerateCookHandoffWithAgentParams): Promise<string | undefined> {
+	if (process.env.PI_COMPLETION_DISABLE_PRIMARY_HANDOFF_SYNTHESIS === "1") return undefined;
+	const testOutput = asString(process.env.PI_COMPLETION_PRIMARY_HANDOFF_OUTPUT);
+	if (testOutput) return testOutput;
+	if (params.recentEntries.length === 0) return undefined;
+	try {
+		return await runPrimaryAgentHandoffSubprocess(params);
+	} catch (error) {
+		console.warn("[completion] primary-agent handoff generation failed", error);
+		return undefined;
+	}
+}
+
 export async function analyzeContextProposalWithAgent(params: AnalyzeContextProposalWithAgentParams): Promise<ContextProposal | undefined> {
 	if (process.env.PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST === "1") return undefined;
 	const testOutput = asString(process.env.PI_COMPLETION_CONTEXT_PROPOSAL_ANALYST_OUTPUT);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linimin/pi-letscook",
-  "version": "0.1.63",
+  "version": "0.1.65",
   "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

@@ -147,18 +147,54 @@ mkdir -p "$ROOT"
 cd "$ROOT"
 git init -q
 
-# No workflow yet: bare /cook should fail closed without a fresh explicit primary-agent handoff,
-# even when recent discussion is fully structured.
+# No workflow yet: bare /cook should be able to generate a primary-agent handoff in the same entry,
+# then continue directly to startup confirmation.
 SESSION_ZERO="$TMPDIR/session-zero.jsonl"
-DISCUSSION_ZERO=$'Mission: Remove the completion status line while keeping the completion widget.\nScope:\n- Keep the non-running completion widget.\n- Suppress the widget while a completion role is active.\nConstraints:\n- Do not reintroduce any other completion status surface.\nAcceptance:\n- Update README to match the shipped behavior.\n- Keep observability regression coverage truthful.'
+DISCUSSION_ZERO=$'Mission: Remove the completion status line while keeping the completion widget.
+Scope:
+- Keep the non-running completion widget.
+- Suppress the widget while a completion role is active.
+Constraints:
+- Do not reintroduce any other completion status surface.
+Acceptance:
+- Update README to match the shipped behavior.
+- Keep observability regression coverage truthful.'
 DISCUSSION_SNAPSHOT_ZERO="$TMPDIR/context-proposal-structured-fallback.json"
+GENERATED_HANDOFF_ZERO="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "mission": "Remove the completion status line while keeping the completion widget.",
+    "scope": [
+        "Keep the non-running completion widget.",
+        "Suppress the widget while a completion role is active."
+    ],
+    "constraints": [
+        "Do not reintroduce any other completion status surface."
+    ],
+    "acceptance": [
+        "Update README to match the shipped behavior.",
+        "Keep observability regression coverage truthful."
+    ],
+    "risks": [],
+    "notes": ["Generated by the primary-agent handoff step triggered from /cook."],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Remove the completion status line while preserving the widget behavior.",
+    "first_slice_non_goals": ["Do not reintroduce another status surface."],
+    "implementation_surfaces": ["extensions/completion/index.ts", "README.md"],
+    "verification_commands": ["npm run smoke-test"],
+    "why_this_slice_first": "This slice is already concrete and bounded enough to start workflow safely.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "The user explicitly chose workflow mode for this bounded implementation slice."
+}
+print("```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```")
+PY
+)"
 write_session "$SESSION_ZERO" "$ROOT" "$DISCUSSION_ZERO"
 
-PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
-PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
-PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$DISCUSSION_SNAPSHOT_ZERO" \
-PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
-pi --session "$SESSION_ZERO" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-context-proposal-structured-fallback.out" 2>"$TMPDIR/pi-completion-context-proposal-structured-fallback.err"
+PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept PI_COMPLETION_PRIMARY_HANDOFF_OUTPUT="$GENERATED_HANDOFF_ZERO" PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$DISCUSSION_SNAPSHOT_ZERO" PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 pi --session "$SESSION_ZERO" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-context-proposal-structured-fallback.out" 2>"$TMPDIR/pi-completion-context-proposal-structured-fallback.err"
 
 python3 - "$TMPDIR/pi-completion-context-proposal-structured-fallback.out" "$TMPDIR/pi-completion-context-proposal-structured-fallback.err" "$DISCUSSION_SNAPSHOT_ZERO" <<'PY'
 import json
@@ -167,9 +203,13 @@ from pathlib import Path
 
 output = Path(sys.argv[1]).read_text() + Path(sys.argv[2]).read_text()
 snapshot = Path(sys.argv[3])
-assert not Path('.agent').exists(), 'missing explicit handoff should fail closed without writing canonical state'
-assert not snapshot.exists(), 'missing explicit handoff should not emit a startup proposal snapshot'
-assert 'fresh explicit primary-agent handoff' in output, 'missing explicit handoff should explain the explicit-handoff-only startup contract'
+assert Path('.agent').exists(), 'primary-agent handoff generation should scaffold canonical state in the same /cook entry'
+assert snapshot.exists(), 'primary-agent handoff generation should emit a startup proposal snapshot'
+proposal = json.loads(snapshot.read_text())
+brief = json.loads(Path('.agent/state.json').read_text())['advisory_startup_brief']
+assert proposal['source'] == 'handoff_capsule', 'generated primary-agent handoff should be consumed as handoff capsule startup source'
+assert brief['source'] == 'primary_agent_handoff', 'generated primary-agent handoff should record primary_agent_handoff advisory intake'
+assert 'Initialized completion control plane' in output, 'same-entry primary-agent handoff generation should initialize canonical workflow state'
 PY
 
 rm -rf .agent
@@ -206,6 +246,7 @@ PY
 write_session_messages "$SESSION_ZERO_USER_AUTHORED" "$ROOT" "$USER_AUTHORED_MESSAGES_ZERO"
 
 PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$USER_AUTHORED_SNAPSHOT_ZERO" \
+PI_COMPLETION_DISABLE_PRIMARY_HANDOFF_SYNTHESIS=1 \
 PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
 pi --session "$SESSION_ZERO_USER_AUTHORED" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-context-proposal-user-authored.out" 2>"$TMPDIR/pi-completion-context-proposal-user-authored.err"
 
@@ -217,7 +258,7 @@ output = Path(sys.argv[1]).read_text() + Path(sys.argv[2]).read_text()
 snapshot = Path(sys.argv[3])
 assert not Path('.agent').exists(), 'user-authored faux handoff without supporting discussion should still fail closed without writing canonical state'
 assert not snapshot.exists(), 'user-authored faux handoff should not emit a startup proposal snapshot'
-assert 'fresh explicit primary-agent handoff' in output, 'user-authored faux handoff should still explain the explicit-handoff requirement'
+assert 'primary-agent handoff step could not prepare a concrete startup handoff' in output, 'user-authored faux handoff should fail closed when primary-agent handoff generation yields no handoff'
 PY
 
 # No workflow yet: malformed or invalid assistant handoff capsules must also fail closed.
@@ -227,6 +268,7 @@ INVALID_MESSAGES_ZERO='[{"role":"assistant","content":"This is not a valid start
 write_session_messages "$SESSION_ZERO_INVALID" "$ROOT" "$INVALID_MESSAGES_ZERO"
 
 PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$INVALID_SNAPSHOT_ZERO" \
+PI_COMPLETION_DISABLE_PRIMARY_HANDOFF_SYNTHESIS=1 \
 PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
 pi --session "$SESSION_ZERO_INVALID" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-context-proposal-invalid-handoff.out" 2>"$TMPDIR/pi-completion-context-proposal-invalid-handoff.err"
 
@@ -238,7 +280,7 @@ output = Path(sys.argv[1]).read_text() + Path(sys.argv[2]).read_text()
 snapshot = Path(sys.argv[3])
 assert not Path('.agent').exists(), 'invalid assistant handoff without supporting discussion should fail closed without writing canonical state'
 assert not snapshot.exists(), 'invalid assistant handoff should not emit a startup proposal snapshot'
-assert 'fresh explicit primary-agent handoff' in output, 'invalid assistant handoff should still explain the explicit-handoff requirement'
+assert 'primary-agent handoff step could not prepare a concrete startup handoff' in output, 'invalid assistant handoff should fail closed when no valid handoff can be prepared'
 PY
 
 # No workflow yet: a fresh explicit primary-agent handoff should still bootstrap canonical startup state.
@@ -361,6 +403,7 @@ CONTINUE_PROPOSAL_ONE="$TMPDIR/unexpected-active-continue-proposal.json"
 write_session "$SESSION_ONE_CONTINUE" "$ROOT" "$DISCUSSION_ONE_CONTINUE"
 
 PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_DISABLE_PRIMARY_HANDOFF_SYNTHESIS=1 \
 PI_COMPLETION_TEST_ACTIVE_WORKFLOW_ROUTING_PATH="$CONTINUE_ROUTING_ONE" \
 PI_COMPLETION_TEST_DRIVER_PROMPT_PATH="$CONTINUE_RESUME_PROMPT_ONE" \
 PI_COMPLETION_TEST_EXISTING_WORKFLOW_CHOOSER_PATH="$CONTINUE_CHOOSER_ONE" \
@@ -408,6 +451,7 @@ DISCUSSION_REFOCUS_PROPOSAL_ONE="$TMPDIR/unexpected-active-discussion-refocus-pr
 write_session "$SESSION_ONE_DISCUSSION_REFOCUS" "$ROOT" "$DISCUSSION_ONE_DISCUSSION_REFOCUS"
 
 PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_DISABLE_PRIMARY_HANDOFF_SYNTHESIS=1 \
 PI_COMPLETION_TEST_ACTIVE_WORKFLOW_ROUTING_PATH="$DISCUSSION_REFOCUS_ROUTING_ONE" \
 PI_COMPLETION_TEST_DRIVER_PROMPT_PATH="$DISCUSSION_REFOCUS_RESUME_ONE" \
 PI_COMPLETION_TEST_EXISTING_WORKFLOW_CHOOSER_PATH="$DISCUSSION_REFOCUS_CHOOSER_ONE" \
@@ -482,6 +526,7 @@ with session_path.open('w', encoding='utf-8') as fh:
 PY
 
 PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_DISABLE_PRIMARY_HANDOFF_SYNTHESIS=1 \
 PI_COMPLETION_TEST_ACTIVE_WORKFLOW_ROUTING_PATH="$SUMMARY_ROUTING_ONE" \
 PI_COMPLETION_TEST_DRIVER_PROMPT_PATH="$SUMMARY_RESUME_PROMPT_ONE" \
 PI_COMPLETION_TEST_EXISTING_WORKFLOW_CHOOSER_PATH="$SUMMARY_CHOOSER_ONE" \
@@ -643,6 +688,7 @@ write_session "$SESSION_TWO_COMPLETED_SUPPRESS" "$ROOT" "$DISCUSSION_TWO_COMPLET
 
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
 PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_DISABLE_PRIMARY_HANDOFF_SYNTHESIS=1 \
 PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$DISCUSSION_SNAPSHOT_TWO_COMPLETED_SUPPRESS" \
 PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
 pi --session "$SESSION_TWO_COMPLETED_SUPPRESS" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-context-proposal-next-round-completed-suppress.out" 2>"$TMPDIR/pi-completion-context-proposal-next-round-completed-suppress.err"
@@ -660,7 +706,7 @@ state = json.loads(Path('.agent/state.json').read_text())
 assert state['mission_anchor'] == expected, 'completed-topic suppression should keep the done workflow mission anchor unchanged'
 assert state['continuation_policy'] == 'done', 'completed-topic suppression should keep the workflow closed'
 assert not snapshot.exists(), 'completed-topic suppression should not emit a proposal snapshot when the latest discussion only repeats finished work'
-assert '/cook failed closed' in output, 'completed-topic suppression should fail closed instead of reopening the finished mission'
+assert 'primary-agent handoff step could not prepare a concrete startup handoff' in output, 'completed-topic suppression should fail closed when no concrete primary-agent handoff can be prepared'
 PY
 
 # Completed workflow: bare /cook should also suppress proposals that merely restate canonical
@@ -691,6 +737,7 @@ write_session "$SESSION_TWO_VERIFIED_SUPPRESS" "$ROOT" "$DISCUSSION_TWO_VERIFIED
 
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
 PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_DISABLE_PRIMARY_HANDOFF_SYNTHESIS=1 \
 PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$DISCUSSION_SNAPSHOT_TWO_VERIFIED_SUPPRESS" \
 PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
 pi --session "$SESSION_TWO_VERIFIED_SUPPRESS" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-context-proposal-next-round-verified-suppress.out" 2>"$TMPDIR/pi-completion-context-proposal-next-round-verified-suppress.err"
@@ -702,7 +749,7 @@ from pathlib import Path
 output = Path(sys.argv[1]).read_text() + Path(sys.argv[2]).read_text()
 snapshot = Path(sys.argv[3])
 assert not snapshot.exists(), 'verification-evidence overlap suppression should not emit a proposal snapshot for already verified work'
-assert '/cook failed closed' in output, 'verification-evidence overlap suppression should fail closed when the latest discussion only repeats verified work'
+assert 'primary-agent handoff step could not prepare a concrete startup handoff' in output, 'verification-evidence overlap suppression should fail closed when no concrete primary-agent handoff can be prepared'
 PY
 
 # Completed workflow: bare /cook should fail closed for next-round discussion-only startup too,
@@ -712,11 +759,38 @@ DISCUSSION_TWO_NORMALIZED=$'Mission: 開始實作這個方案\nScope:\n- Normali
 DISCUSSION_SNAPSHOT_TWO_NORMALIZED="$TMPDIR/context-proposal-next-round-normalized.json"
 write_session "$SESSION_TWO_NORMALIZED" "$ROOT" "$DISCUSSION_TWO_NORMALIZED"
 
-PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
-PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
-PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$DISCUSSION_SNAPSHOT_TWO_NORMALIZED" \
-PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
-pi --session "$SESSION_TWO_NORMALIZED" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-context-proposal-next-round-normalized.out" 2>"$TMPDIR/pi-completion-context-proposal-next-round-normalized.err"
+GENERATED_HANDOFF_TWO_NORMALIZED="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "mission": "Start the next workflow round with a normalized implementation mission.",
+    "scope": [
+        "Reset canonical state for the new implementation mission.",
+        "Keep the next round distinct from the completed workflow."
+    ],
+    "constraints": [
+        "Do not resume the completed workflow when the new round is clearly different."
+    ],
+    "acceptance": [
+        "Reset canonical state back to reground for the new mission.",
+        "Preserve the tracked completion control-plane files."
+    ],
+    "risks": [],
+    "notes": ["Generated by the primary-agent handoff step triggered from /cook."],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Bootstrap the next workflow round from the normalized implementation mission.",
+    "first_slice_non_goals": ["Do not reopen finished slices from the previous workflow."],
+    "implementation_surfaces": ["extensions/completion/driver.ts", "scripts/context-proposal-test.sh"],
+    "verification_commands": ["npm run context-proposal-test"],
+    "why_this_slice_first": "The user explicitly chose workflow mode for a bounded next-round restart.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1"
+}
+print("```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```")
+PY
+)"
+PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept PI_COMPLETION_PRIMARY_HANDOFF_OUTPUT="$GENERATED_HANDOFF_TWO_NORMALIZED" PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$DISCUSSION_SNAPSHOT_TWO_NORMALIZED" PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 pi --session "$SESSION_TWO_NORMALIZED" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-context-proposal-next-round-normalized.out" 2>"$TMPDIR/pi-completion-context-proposal-next-round-normalized.err"
 
 python3 - "$TMPDIR/pi-completion-context-proposal-next-round-normalized.out" "$TMPDIR/pi-completion-context-proposal-next-round-normalized.err" "$DISCUSSION_SNAPSHOT_TWO_NORMALIZED" "$CURRENT_DONE_MISSION" <<'PY'
 import json
@@ -727,11 +801,12 @@ output = Path(sys.argv[1]).read_text() + Path(sys.argv[2]).read_text()
 snapshot = Path(sys.argv[3])
 previous = sys.argv[4]
 state = json.loads(Path('.agent/state.json').read_text())
-
-assert not snapshot.exists(), 'done-workflow discussion-only startup should not emit a proposal snapshot without a fresh explicit handoff'
-assert state['mission_anchor'] == previous, 'done-workflow discussion-only startup should keep the completed mission anchor unchanged'
-assert state['continuation_policy'] == 'done', 'done-workflow discussion-only startup should keep the workflow closed'
-assert 'fresh explicit primary-agent handoff' in output, 'done-workflow discussion-only startup should explain the explicit-handoff-only entry contract'
+if snapshot.exists():
+    proposal = json.loads(snapshot.read_text())
+    assert proposal['source'] == 'handoff_capsule', 'done-workflow generated startup should snapshot the primary-agent handoff source'
+assert state['mission_anchor'] != previous, 'done-workflow discussion-only startup should advance to the new mission anchor'
+assert state['continuation_policy'] == 'continue', 'done-workflow discussion-only startup should reopen workflow state'
+assert 'Started a new completion workflow round from explicit primary-agent handoff' in output, 'done-workflow generated startup should report explicit primary-agent handoff startup'
 PY
 
 # Completed workflow: a fresh explicit primary-agent handoff should still start the next round.
@@ -960,11 +1035,37 @@ ANALYST_OUTPUT_FIVE='{"mission":"Use a proposal analyst to summarize natural dis
 DISCUSSION_SNAPSHOT_FIVE="$TMPDIR/context-proposal-analyst-restart-rejected.json"
 write_session "$SESSION_FIVE" "$ROOT" "$DISCUSSION_FIVE"
 
-PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
-PI_COMPLETION_CONTEXT_PROPOSAL_ANALYST_OUTPUT="$ANALYST_OUTPUT_FIVE" \
-PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$DISCUSSION_SNAPSHOT_FIVE" \
-PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
-pi --session "$SESSION_FIVE" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-context-proposal-analyst.out" 2>"$TMPDIR/pi-completion-context-proposal-analyst.err"
+GENERATED_HANDOFF_FIVE="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "mission": "Use the analyst-backed parser follow-up as the next workflow round.",
+    "scope": [
+        "Keep the discussion-derived mission anchored once it is clear.",
+        "Drop stale scope from earlier turns."
+    ],
+    "constraints": [
+        "Do not rewrite the parser."
+    ],
+    "acceptance": [
+        "Add a regression test."
+    ],
+    "risks": [],
+    "notes": ["Generated by the primary-agent handoff step triggered from /cook."],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Land the regression-test-backed parser follow-up without rewriting the parser.",
+    "first_slice_non_goals": ["Do not broaden the mission with stale scope."],
+    "implementation_surfaces": ["scripts/context-proposal-test.sh"],
+    "verification_commands": ["npm run context-proposal-test"],
+    "why_this_slice_first": "The user explicitly chose workflow mode and the primary agent can already bound the first slice.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1"
+}
+print("```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```")
+PY
+)"
+PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept PI_COMPLETION_CONTEXT_PROPOSAL_ANALYST_OUTPUT="$ANALYST_OUTPUT_FIVE" PI_COMPLETION_PRIMARY_HANDOFF_OUTPUT="$GENERATED_HANDOFF_FIVE" PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$DISCUSSION_SNAPSHOT_FIVE" PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 pi --session "$SESSION_FIVE" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-context-proposal-analyst.out" 2>"$TMPDIR/pi-completion-context-proposal-analyst.err"
 
 python3 - "$TMPDIR/pi-completion-context-proposal-analyst.out" "$TMPDIR/pi-completion-context-proposal-analyst.err" "$DISCUSSION_SNAPSHOT_FIVE" <<'PY'
 import json
@@ -975,9 +1076,10 @@ output = Path(sys.argv[1]).read_text() + Path(sys.argv[2]).read_text()
 snapshot = Path(sys.argv[3])
 state = json.loads(Path('.agent/state.json').read_text())
 
-assert not snapshot.exists(), 'done-workflow analyst-only restart should not emit a startup proposal snapshot'
-assert state['continuation_policy'] == 'done', 'done-workflow analyst-only restart should keep the workflow closed'
-assert 'fresh explicit primary-agent handoff' in output, 'done-workflow analyst-only restart should explain the explicit-handoff-only startup contract'
+if snapshot.exists():
+    pass
+assert state['continuation_policy'] == 'continue', 'done-workflow analyst-backed primary-agent handoff should reopen the workflow'
+assert 'Started a new completion workflow round from explicit primary-agent handoff' in output, 'done-workflow analyst-backed startup should report explicit primary-agent handoff startup'
 PY
 
 # Custom confirmation UI: start should render proposal content separately from approval-only Start/Cancel actions.
@@ -1511,6 +1613,7 @@ write_session_messages "$HANDOFF_SESSION_STALE" "$HANDOFF_ROOT_STALE" "$HANDOFF_
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
 PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
 PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$HANDOFF_SNAPSHOT_STALE" \
+PI_COMPLETION_DISABLE_PRIMARY_HANDOFF_SYNTHESIS=1 \
 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"
 
@@ -1523,7 +1626,7 @@ output = Path(sys.argv[2]).read_text() + Path(sys.argv[3]).read_text()
 
 assert not snapshot.exists(), 'stale handoff should not emit a startup proposal snapshot'
 assert not Path('.agent').exists(), 'stale handoff should fail closed without writing canonical state'
-assert 'fresh explicit primary-agent handoff' in output, 'stale handoff should explain that a fresh valid explicit handoff is required'
+assert 'primary-agent handoff step could not prepare a concrete startup handoff' in output, 'stale handoff should fail closed when the synthesized handoff step produces nothing'
 PY
 
 # Negative handoff rationale: a non-startable capsule must not become the startup mission.

package/scripts/refocus-test.sh

@@ -519,4 +519,81 @@ assert plan['plan_basis'] == 'user_refocus', 'plan.json plan_basis should be use
 assert active['status'] == 'idle', 'active-slice.json status should reset to idle after bare refocus'
 PY
 
+SYNTH_REPLACEMENT_SESSION="$TMPDIR/session-synthesized-active-replacement.jsonl"
+SYNTH_REPLACEMENT_ROUTING="$TMPDIR/synthesized-active-replacement-routing.json"
+SYNTH_REPLACEMENT_PROPOSAL="$TMPDIR/synthesized-active-replacement-proposal.json"
+write_session "$SYNTH_REPLACEMENT_SESSION" "$TMPDIR" "Please replace the current workflow with the synthesized replacement mission when I run /cook."
+
+SYNTH_REPLACEMENT_HANDOFF="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "generated-primary-agent-handoff",
+    "mission": "Exercise same-entry active-workflow replacement synthesis.",
+    "scope": [
+        "Generate the replacement handoff inside the same /cook entry.",
+        "Keep the chooser and final Start/Cancel confirmation truthful."
+    ],
+    "constraints": [
+        "Do not rewrite canonical state before the final Start confirmation."
+    ],
+    "acceptance": [
+        "Replace the active workflow using the synthesized primary-agent handoff.",
+        "Keep deterministic coverage for same-entry active replacement."
+    ],
+    "risks": [],
+    "notes": [
+        "This replacement is synthesized during /cook rather than pre-authored in the transcript."
+    ],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Exercise same-entry active-workflow replacement synthesis.",
+    "first_slice_non_goals": [],
+    "implementation_surfaces": [
+        "scripts/refocus-test.sh"
+    ],
+    "verification_commands": [
+        "npm run refocus-test"
+    ],
+    "why_this_slice_first": "Active replacement should work when the primary-agent handoff is synthesized in the same /cook entry.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "The user explicitly chose workflow mode and the replacement handoff can be synthesized immediately."
+}
+print("```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```")
+PY
+)"
+
+PI_COMPLETION_PRIMARY_HANDOFF_OUTPUT="$SYNTH_REPLACEMENT_HANDOFF" \
+PI_COMPLETION_EXISTING_WORKFLOW_ACTION=refocus \
+PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
+PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$SYNTH_REPLACEMENT_PROPOSAL" \
+PI_COMPLETION_TEST_ACTIVE_WORKFLOW_ROUTING_PATH="$SYNTH_REPLACEMENT_ROUTING" \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$SYNTH_REPLACEMENT_SESSION" -e "$PKG_ROOT" -p "/cook" \
+  >"$TMPDIR/pi-completion-synthesized-active-replacement.out" 2>"$TMPDIR/pi-completion-synthesized-active-replacement.err"
+
+python3 - "$SYNTH_REPLACEMENT_PROPOSAL" "$SYNTH_REPLACEMENT_ROUTING" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+new_anchor = 'Exercise same-entry active-workflow replacement synthesis.'
+proposal = json.loads(Path(sys.argv[1]).read_text())
+routing = json.loads(Path(sys.argv[2]).read_text())
+state = json.loads(Path('.agent/state.json').read_text())
+plan = json.loads(Path('.agent/plan.json').read_text())
+active = json.loads(Path('.agent/active-slice.json').read_text())
+
+assert proposal['mission'] == new_anchor, 'same-entry synthesized replacement should preserve the replacement proposal mission'
+assert routing['action'] == 'refocus', 'same-entry synthesized replacement should classify active bare /cook as refocus'
+assert routing['reason'] == 'fresh_explicit_handoff', 'same-entry synthesized replacement should reuse the explicit-handoff routing reason because /cook synthesized an explicit handoff'
+assert routing['proposalSource'] == 'handoff_capsule', 'same-entry synthesized replacement should surface the synthesized handoff as a handoff capsule source'
+assert state['mission_anchor'] == new_anchor, 'state.json mission_anchor mismatch after same-entry synthesized refocus'
+assert plan['mission_anchor'] == new_anchor, 'plan.json mission_anchor mismatch after same-entry synthesized refocus'
+assert active['mission_anchor'] == new_anchor, 'active-slice.json mission_anchor mismatch after same-entry synthesized refocus'
+assert state['continuation_reason'].startswith('User refocused workflow via /cook:'), 'same-entry synthesized replacement should record the /cook refocus continuation reason'
+PY
+
 echo "refocus test passed: $TMPDIR"

package/scripts/release-check.sh

@@ -9,43 +9,41 @@ echo "[release-check] running control-plane validation, tracked .agent contract
 bash .agent/verify_completion_control_plane.sh
 git ls-files --error-unmatch .agent/README.md .agent/mission.md .agent/profile.json .agent/verify_completion_stop.sh .agent/verify_completion_control_plane.sh >/dev/null
 
-echo "[release-check] verifying public /cook parity and explicit-handoff docs/help"
+echo "[release-check] verifying public /cook parity and primary-agent-handoff docs/help"
 python3 - <<'PY'
 from pathlib import Path
 
 checks = {
     "README.md": [
         "You can still implement directly in ordinary chat when you do not need workflow state.",
-        "When you explicitly run `/cook`, it should consume the explicit primary-agent handoff you already prepared in ordinary chat, then ask you to **Start** or **Cancel** before rewriting canonical workflow state.",
-        "Explicit `/cook` capsules are the required startup intake for new-workflow, next-round, and replacement entry.",
-        "`/cook` first checks for a fresh explicit primary-agent handoff capsule.",
-        "New-workflow entry, done-workflow next-round entry, and active-workflow replacement should use that handoff instead of guessing from recent discussion.",
+        "When you explicitly run `/cook`, it first checks for a fresh explicit primary-agent handoff.",
+        "If one is missing, it calls a same-entry primary-agent handoff synthesis step from the current task context, then asks you to **Start** or **Cancel** before rewriting canonical workflow state.",
+        "Explicit `/cook` capsules are still valid startup intake, but they are no longer the only path because `/cook` can synthesize the primary-agent handoff in the same entry when needed.",
     ],
     "CHANGELOG.md": [
-        "made `/cook` stop inferring startup handoffs from recent discussion so workflow startup and replacement now require fresh explicit primary-agent `cook_handoff` data",
-        "clarified that when a user explicitly chooses `/cook`, the primary agent must author the handoff in ordinary chat and `/cook` must consume that handoff instead of guessing",
+        "changed `/cook` entry again so it now calls a same-entry primary-agent handoff synthesis step when no fresh explicit handoff exists, then proceeds directly to Start / Cancel without requiring a second `/cook` run",
+        "kept `/cook` from guessing startup purely from recent discussion by requiring that same-entry synthesis step to produce explicit primary-agent handoff data before workflow state can start",
     ],
     "extensions/completion/prompt-surfaces.ts": [
-        '"If the user explicitly asks to enter /cook workflow, generate one fresh ```cook_handoff``` capsule in ordinary chat from the primary-agent view of the task, then tell the user to run /cook."',
-        '"Do not expect /cook to infer or guess startup intent from recent discussion alone; /cook should consume the explicit primary-agent handoff instead."',
+        '"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."',
     ],
     "extensions/completion/index.ts": [
-        '"/cook failed closed because starting workflow now requires a fresh explicit primary-agent handoff. Ask the primary agent in the main chat to emit a fresh ```cook_handoff``` capsule, then rerun /cook."',
+        '"/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."',
         'description: "/cook workflow: start or replace workflow only from an explicit primary-agent handoff, or resume the current workflow from canonical state"',
     ],
 }
 
 forbidden = {
     "README.md": [
-        "synthesizes a startup brief from recent discussion using primary-agent-style context",
-        "derive startup from explicit user `/cook` entry plus recent discussion when needed",
+        "asks the primary agent to prepare one in the main chat and leaves canonical state unchanged until you rerun /cook",
+        "Explicit `/cook` capsules are the required startup intake for new-workflow, next-round, and replacement entry.",
     ],
     "extensions/completion/prompt-surfaces.ts": [
-        '"If the user explicitly runs /cook, /cook will synthesize a startup brief from recent discussion using primary-agent-style context, then show Start/Cancel confirmation before canonical workflow state is rewritten."',
+        '"If the user explicitly asks to enter /cook workflow, generate one fresh ```cook_handoff``` capsule in ordinary chat from the primary-agent view of the task, then tell the user to run /cook."',
     ],
     "extensions/completion/index.ts": [
-        'description: "/cook workflow: optionally enter tracked workflow mode, synthesize a startup brief from explicit /cook entry, resume the current workflow from canonical state, or confirm a replacement mission"',
-        '"/cook failed closed because it could not derive a concrete startup brief from recent discussion. Clarify the mission, first slice, or verification intent in the main chat, then rerun /cook."',
+        '"/cook failed closed because starting workflow now requires a fresh explicit primary-agent handoff. Ask the primary agent in the main chat to emit a fresh ```cook_handoff``` capsule, then rerun /cook."',
     ],
 }
 

package/scripts/smoke-test.sh

@@ -270,7 +270,7 @@ assert 'directly implement requested repo changes, including multi-file work' in
 assert 'Do not proactively tell the user to run /cook' in handoff_text, 'ordinary handoff reminder should keep ordinary chat neutral until explicit /cook entry'
 assert '/cook is optional workflow mode' in handoff_text, 'ordinary handoff reminder should position /cook as optional workflow mode'
 assert 'If the user wants direct implementation now, stay in ordinary chat and help directly instead of blocking on /cook.' in handoff_text, 'ordinary handoff reminder should avoid blocking implementation on /cook'
-assert 'generate one fresh ```cook_handoff``` capsule in ordinary chat from the primary-agent view of the task' in handoff_text, 'ordinary handoff reminder should require primary-agent authored handoff when the user explicitly chooses /cook'
+assert 'the extension should call a primary-agent handoff synthesis step from the current task context' in handoff_text, 'ordinary handoff reminder should describe same-entry primary-agent handoff synthesis for /cook'
 assert 'Do not expect /cook to infer or guess startup intent from recent discussion alone' in handoff_text, 'ordinary handoff reminder should forbid /cook-side guessing'
 assert 'do not silently rewrite discussion into canonical workflow state' in handoff_text, 'ordinary handoff reminder should preserve non-canonical ordinary-chat behavior'
 assert not auto_resume.exists(), 'ordinary non-/cook turn should not queue auto-resume before /cook activation'

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

@@ -1,6 +1,6 @@
 ---
 name: cook-handoff-boundary
-description: Ordinary-chat contract for treating `/cook` as an optional workflow mode while still requiring primary-agent-authored handoff data whenever the user explicitly chooses workflow mode.
+description: Ordinary-chat contract for treating `/cook` as an optional workflow mode while requiring `/cook` to use primary-agent-authored handoff data instead of guessing from recent discussion.
 ---
 
 # /cook Handoff Boundary
@@ -54,20 +54,24 @@ But even in those cases:
 
 ## Required Behavior When The User Explicitly Chooses `/cook`
 
-If the user explicitly asks to enter `/cook` workflow mode, the primary agent must:
+If the user explicitly runs or clearly chooses `/cook` workflow mode, the system behavior should be:
 
-- generate the handoff information itself in ordinary chat
-- emit exactly one fresh `cook_handoff` capsule that captures the intended startup slice from the primary-agent view of the task
-- tell the user to run `/cook` only after that explicit handoff exists
-- not rely on `/cook` to infer, summarize, or guess the startup slice from recent discussion alone
+1. check for a fresh explicit primary-agent `cook_handoff`
+2. if none exists, call a primary-agent handoff synthesis step immediately from the current task context
+3. use that handoff to show Start / Cancel confirmation in the same `/cook` entry
+4. write canonical workflow state only after Start
 
-In other words:
+That means:
 
-- primary agent authors the handoff
-- `/cook` consumes and confirms that handoff
-- `/cook` must not invent the mission from transcript guessing
+- `/cook` must not infer or guess the startup slice from recent discussion alone
+- `/cook` should use primary-agent-authored handoff data
+- `/cook` should not require a manual rerun just to consume a handoff it can synthesize immediately from the primary-agent view
 
-## Required Capsule Format
+## Optional Preview Behavior
+
+Only if the user explicitly asks for a preview startup brief or handoff capsule in ordinary chat may the primary agent provide one.
+
+Optional preview capsule format:
 
 ````text
 ```cook_handoff
@@ -102,9 +106,9 @@ Notes:
 - `first_slice_goal`, `first_slice_non_goals`, `implementation_surfaces`, `verification_commands`, and `why_this_slice_first` are required for an implementation-ready handoff.
 - Any 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 when the user chooses workflow mode:
+Suggested wording:
 
-> Got it — since you want `/cook`, I’ll first prepare the explicit startup handoff here from the current task context. After that, run `/cook` and it should confirm this handoff rather than guessing from recent discussion.
+> We can continue directly in ordinary chat if you want. If you prefer workflow mode, run `/cook` and it should use a primary-agent handoff for Start / Cancel confirmation rather than guessing from recent discussion.
 
 ## Forbidden Behaviors
 
@@ -118,12 +122,12 @@ Before the user explicitly runs `/cook`, the primary agent must not:
 When the user does explicitly choose `/cook`, the system must not:
 
 - let `/cook` invent the startup mission from recent discussion alone
-- let `/cook` replace missing primary-agent handoff data with transcript guessing
-- let `/cook` reopen or refocus workflow from guessed intent when no fresh explicit primary-agent handoff exists
+- let `/cook` replace missing handoff data with generic transcript guessing
+- require a second `/cook` invocation when same-entry primary-agent handoff synthesis is possible
 
 ## Relationship To `completion-protocol`
 
-This skill is only about pre-`/cook` ordinary-chat behavior and explicit handoff preparation.
+This skill is only about pre-`/cook` ordinary-chat behavior and `/cook` handoff expectations.
 
 After the user explicitly enters `/cook`, the separate `completion-protocol` skill governs: