@linimin/pi-letscook 0.1.57 → 0.1.59

package/extensions/completion/index.ts

@@ -18,14 +18,13 @@ import {
 	collectRecentDiscussionEntries,
 	collectRecentSessionMessages,
 	deriveCookContextProposalFromRecentDiscussion,
-	extractLatestCookHandoffProposal,
+	assessLatestCookHandoffProposal,
 	finalizeContextProposalAnalysis,
 	isWeakMissionAnchor,
 	missionAnchorsLikelyEquivalent,
 	missionAnchorsStrictlyEquivalent,
 	normalizeMissionAnchorText,
 	resolveContextProposalConfirmationAction,
-	shouldTreatBareActiveWorkflowProposalAsClearRefocus,
 	stripCodeBlocks,
 } from "./proposal";
 import type {
@@ -122,11 +121,21 @@ function candidateSlices(plan: JsonRecord | undefined): JsonRecord[] {
 	return Array.isArray(slices) ? slices.filter(isRecord) : [];
 }
 
+type CookContextProposalResult = {
+	proposal?: ContextProposal;
+	blockedFailureMessage?: string;
+};
+
 type ActiveWorkflowProposalAssessment = {
-	action: "continue" | "refocus" | "unclear";
+	action: "continue" | "refocus" | "blocked";
 	currentMissionAnchor: string;
 	proposal?: ContextProposal;
-	reason: "matching_mission" | "clear_refocus" | "missing_proposal" | "ambiguous_discussion";
+	blockedFailureMessage?: string;
+	reason:
+		| "matching_mission"
+		| "missing_explicit_handoff"
+		| "fresh_explicit_handoff"
+		| "fresh_explicit_handoff_not_startable";
 };
 
 function completionTestWorkflowActionOverride(): "continue" | "refocus" | "cancel" | undefined {
@@ -200,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 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.";
+	"/cook failed closed because new-workflow startup now requires a fresh valid explicit primary-agent handoff from recent ordinary-chat discussion; recent discussion alone no longer starts a workflow. Ask the primary agent to hand off explicitly in the main chat, then rerun /cook.";
 
 function isWorkflowDone(snapshot: CompletionStateSnapshot | undefined): boolean {
 	return asString(snapshot?.state?.continuation_policy) === "done";
@@ -271,6 +280,7 @@ function maybeWriteActiveWorkflowRoutingSnapshot(assessment: ActiveWorkflowPropo
 				action: assessment.action,
 				reason: assessment.reason,
 				currentMissionAnchor: assessment.currentMissionAnchor,
+				blockedFailureMessage: assessment.blockedFailureMessage ?? null,
 				proposedMissionAnchor: assessment.proposal?.mission ?? null,
 				proposalSource: assessment.proposal?.source ?? null,
 				possibleNoise: assessment.proposal?.analysis.possibleNoise ?? [],
@@ -362,10 +372,31 @@ async function promptContextProposalConfirmationAction(
 	});
 }
 
+async function deriveCookStartupProposal(
+	ctx: { cwd: string; hasUI: boolean; ui: any; sessionManager: any; model?: any; modelRegistry?: any },
+	projectName: string,
+): Promise<CookContextProposalResult> {
+	const recentMessages = collectRecentSessionMessages(ctx, { isRecord, asString, asNumber, isStaleContextError });
+	const explicitHandoff = assessLatestCookHandoffProposal(recentMessages, projectName, {
+		asString,
+		asStringArray,
+		assessMissionAnchor,
+		normalizeMissionAnchorText,
+		isWeakMissionAnchor,
+		missionAnchorsStrictlyEquivalent,
+		stripCodeBlocks,
+	});
+	if (explicitHandoff.status === "startable") return { proposal: explicitHandoff.proposal };
+	if (explicitHandoff.status === "fresh_but_not_startable") {
+		return { blockedFailureMessage: explicitHandoff.message };
+	}
+	return {};
+}
+
 async function deriveCookContextProposal(
 	ctx: { cwd: string; hasUI: boolean; ui: any; sessionManager: any; model?: any; modelRegistry?: any },
 	projectName: string,
-): Promise<ContextProposal | undefined> {
+): Promise<CookContextProposalResult> {
 	const recentMessages = collectRecentSessionMessages(ctx, { isRecord, asString, asNumber, isStaleContextError });
 	const recentEntries = recentMessages
 		.filter((entry) => (entry.role === "user" || entry.role === "custom") && !entry.isCommand)
@@ -384,51 +415,45 @@ 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,
-		workflowContext: snapshot
-			? {
-				currentMissionAnchor:
-					asString(snapshot.state?.mission_anchor) ?? asString(snapshot.plan?.mission_anchor) ?? asString(snapshot.active?.mission_anchor),
-				latestCompletedSlice: asString(snapshot.state?.latest_completed_slice),
-				latestVerifiedSlice: asString(snapshot.state?.latest_verified_slice),
-				activeSliceGoal: asString(snapshot.active?.goal),
-				activeSliceWhyNow: asString(snapshot.active?.why_now),
-				verificationGoal: asString(snapshot.verificationEvidence?.goal),
-				verificationSummary: asString(snapshot.verificationEvidence?.summary),
-				continuationPolicy: asString(snapshot.state?.continuation_policy),
-			}
-			: undefined,
-		analyzeContextProposal: async (entries) =>
-			await analyzeContextProposalWithAgent({
-				ctx,
-				projectName,
-				recentEntries: entries,
-				workflowContextLines,
-				liveRoleActivityByRoot,
-				completionStatusKey: COMPLETION_STATUS_KEY,
-				safeUiCall,
-				getCtxCwd,
-				getCtxHasUI,
-				getCtxUi,
-			}),
-		assessMissionAnchor,
-		isWeakMissionAnchor,
-		missionAnchorsStrictlyEquivalent,
-		normalizeMissionAnchorText,
-		stripCodeBlocks,
-	});
+	const explicitHandoff = await deriveCookStartupProposal(ctx, projectName);
+	if (explicitHandoff.proposal || explicitHandoff.blockedFailureMessage) return explicitHandoff;
+	return {
+		proposal: await deriveCookContextProposalFromRecentDiscussion(projectName, recentEntries, {
+			asString,
+			asStringArray,
+			workflowContext: snapshot
+				? {
+					currentMissionAnchor:
+						asString(snapshot.state?.mission_anchor) ?? asString(snapshot.plan?.mission_anchor) ?? asString(snapshot.active?.mission_anchor),
+					latestCompletedSlice: asString(snapshot.state?.latest_completed_slice),
+					latestVerifiedSlice: asString(snapshot.state?.latest_verified_slice),
+					activeSliceGoal: asString(snapshot.active?.goal),
+					activeSliceWhyNow: asString(snapshot.active?.why_now),
+					verificationGoal: asString(snapshot.verificationEvidence?.goal),
+					verificationSummary: asString(snapshot.verificationEvidence?.summary),
+					continuationPolicy: asString(snapshot.state?.continuation_policy),
+				}
+				: undefined,
+			analyzeContextProposal: async (entries) =>
+				await analyzeContextProposalWithAgent({
+					ctx,
+					projectName,
+					recentEntries: entries,
+					workflowContextLines,
+					liveRoleActivityByRoot,
+					completionStatusKey: COMPLETION_STATUS_KEY,
+					safeUiCall,
+					getCtxCwd,
+					getCtxHasUI,
+					getCtxUi,
+				}),
+			assessMissionAnchor,
+			isWeakMissionAnchor,
+			missionAnchorsStrictlyEquivalent,
+			normalizeMissionAnchorText,
+			stripCodeBlocks,
+		}),
+	};
 }
 
 async function confirmContextProposal(
@@ -904,7 +929,7 @@ export default function completionExtension(pi: ExtensionAPI) {
 		structuredDiscussionFailureDetail: COOK_STRUCTURED_DISCUSSION_FAILURE_DETAIL,
 		mainChatRerunGuidance: COOK_MAIN_CHAT_RERUN_GUIDANCE,
 		cookCommandSpec: {
-			description: "/cook workflow: derive a startup brief from recent discussion, then start, continue, refocus, or start the next round from the explicit /cook command",
+			description: "/cook workflow: start a new workflow or next round only from a fresh recent explicit primary-agent handoff, resume the current workflow from canonical state, or confirm an explicit replacement from the explicit /cook command",
 		},
 		buildContextProposalContinuationReason,
 		completionKickoff,
@@ -917,6 +942,7 @@ export default function completionExtension(pi: ExtensionAPI) {
 		completionTestWorkflowMissionOverride,
 		confirmContextProposal,
 		deriveCookContextProposal,
+		deriveCookStartupProposal,
 		emitCommandText,
 		finalizeContextProposalAnalysis,
 		getCtxCwd,
@@ -931,7 +957,6 @@ export default function completionExtension(pi: ExtensionAPI) {
 		scaffoldCompletionFiles,
 		shouldSkipDriverKickoffForTests,
 		shouldTestAutoContinueOnSessionStart,
-		shouldTreatBareActiveWorkflowProposalAsClearRefocus,
 	};
 
 

package/extensions/completion/prompt-surfaces.ts

@@ -27,12 +27,17 @@ export type AdvisoryStartupBrief = {
 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.",
+		"Use ordinary chat to clarify requirements, discuss tradeoffs, propose implementation approaches, and refine scope with the user.",
 		"/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.",
+		"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 — do not begin long-running product implementation in ordinary chat and do not edit tracked product files for that workflow-level task.",
+		"Instead, recommend /cook as the workflow boundary while keeping the conversation in ordinary chat until the user explicitly runs /cook.",
+		"If the user keeps asking follow-up questions or refining requirements before /cook, continue that ordinary-chat discussion normally instead of switching into a handoff-only refusal mode, but do not act as though /cook had already been invoked.",
+		"Distinguish a workflow-worthy handoff from an implementation-ready handoff: only emit the implementation-ready capsule when the first bounded implementation slice is concrete enough to start immediately.",
+		"If the task is workflow-worthy but that first slice is still vague, say that /cook will be the right next step once the first bounded slice is concrete enough, then keep refining in ordinary chat without emitting an implementation-ready capsule yet.",
+		"When handing off, explain that /cook can start a new workflow or next round only from a fresh valid explicit primary-agent handoff capsule from recent ordinary-chat discussion; otherwise it fails closed, while already-active workflows resume from canonical .agent state unless a fresh valid explicit handoff proposes replacement.",
+		"Once the task is implementation-ready, 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, first_slice_goal, first_slice_non_goals, implementation_surfaces, verification_commands, why_this_slice_first, and optional task_type/evaluation_profile/why_cook_now.",
+		"Use handoff_kind implementation_workflow_handoff for that implementation-ready capsule.",
+		"If later ordinary-chat discussion materially changes the startup brief before /cook runs, update or replace the capsule in a later assistant reply instead of pretending the workflow already started.",
 		"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(" ");

package/extensions/completion/proposal.ts

@@ -59,12 +59,30 @@ export type CookHandoffCapsule = {
 	acceptance: string[];
 	risks: string[];
 	notes: string[];
-	handoff_kind: "implementation_workflow_ready";
+	handoff_kind: "implementation_workflow_handoff";
+	first_slice_goal: string;
+	first_slice_non_goals: string[];
+	implementation_surfaces: string[];
+	verification_commands: string[];
+	why_this_slice_first: string;
 	task_type?: string;
 	evaluation_profile?: string;
 	why_cook_now?: string;
 };
 
+export type CookHandoffProposalAssessment =
+	| {
+		status: "none";
+	  }
+	| {
+		status: "startable";
+		proposal: ContextProposal;
+	  }
+	| {
+		status: "fresh_but_not_startable";
+		message: string;
+	  };
+
 export type ContextProposalDecision = {
 	missionAnchor: string;
 	goalText: string;
@@ -1228,9 +1246,14 @@ export function extractContextProposalFromStructuredSession(
 
 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;
+const COOK_HANDOFF_WORKFLOW_ONLY_ACCEPTANCE_REGEX =
+	/(?:\b(?:confirm|discuss|clarify|decide|review|align(?: on)?|agree(?: on)?|explain|summari(?:s|z)e|describe|plan|proposal|spec(?:ification)?|design(?: doc(?:ument)?)?|next step|handoff|workflow|readiness)\b|(?:確認|确认|討論|讨论|釐清|厘清|決定|决定|審查|审查|對齊|对齐|同意|说明|說明|總結|总结|描述|規劃|规划|提案|方案|工作流|就緒|就绪))/iu;
+const COOK_HANDOFF_VERIFICATION_ACCEPTANCE_REGEX =
+	/(?:\b(?:test|tests|testing|verify|verification|validated?|regression|coverage|assert(?:ion)?s?|check|checks|smoke|snapshot(?:s)?)\b|(?:測試|测试|驗證|验证|回歸|回归|覆蓋|覆盖|斷言|断言|檢查|检查|快照))/iu;
+const COOK_HANDOFF_VERIFICATION_ACTION_REGEX =
+	/(?:\b(?:add|update|keep|run|rerun|cover|verify|validate|check|assert|exercise|prove)\b|(?:新增|更新|保持|執行|执行|重跑|覆蓋|覆盖|驗證|验证|檢查|检查|斷言|断言|證明|证明))/iu;
 
 function parseCookHandoffCapsulesFromText(
 	text: string,
@@ -1251,15 +1274,20 @@ function parseCookHandoffCapsulesFromText(
 		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;
+		if (deps.asString(parsed.handoff_kind) !== "implementation_workflow_handoff") continue;
 		const mission = deps.asString(parsed.mission);
-		if (!mission) continue;
+		const firstSliceGoal = deps.asString(parsed.first_slice_goal ?? parsed.firstSliceGoal);
+		const whyThisSliceFirst = deps.asString(parsed.why_this_slice_first ?? parsed.whyThisSliceFirst);
+		if (!mission || !firstSliceGoal || !whyThisSliceFirst) continue;
 		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 firstSliceNonGoals = deps.asStringArray(parsed.first_slice_non_goals ?? parsed.firstSliceNonGoals);
+		const implementationSurfaces = deps.asStringArray(parsed.implementation_surfaces ?? parsed.implementationSurfaces);
+		const verificationCommands = deps.asStringArray(parsed.verification_commands ?? parsed.verificationCommands);
 		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;
@@ -1275,7 +1303,12 @@ function parseCookHandoffCapsulesFromText(
 			acceptance,
 			risks,
 			notes,
-			handoff_kind: "implementation_workflow_ready",
+			handoff_kind: "implementation_workflow_handoff",
+			first_slice_goal: firstSliceGoal,
+			first_slice_non_goals: firstSliceNonGoals,
+			implementation_surfaces: implementationSurfaces,
+			verification_commands: verificationCommands,
+			why_this_slice_first: whyThisSliceFirst,
 			task_type: deps.asString(parsed.task_type),
 			evaluation_profile: deps.asString(parsed.evaluation_profile),
 			why_cook_now: deps.asString(parsed.why_cook_now),
@@ -1285,33 +1318,74 @@ function parseCookHandoffCapsulesFromText(
 }
 
 function buildCookHandoffBasisPreview(capsule: CookHandoffCapsule): string {
-	const parts = [capsule.mission, ...capsule.scope, ...capsule.constraints, ...capsule.non_goals, ...capsule.acceptance];
+	const parts = [
+		capsule.mission,
+		...capsule.scope,
+		...capsule.constraints,
+		...capsule.non_goals,
+		...capsule.acceptance,
+		`first_slice_goal: ${capsule.first_slice_goal}`,
+		...capsule.first_slice_non_goals.map((item) => `first_slice_non_goals: ${item}`),
+		...capsule.implementation_surfaces.map((item) => `implementation_surfaces: ${item}`),
+		...capsule.verification_commands.map((item) => `verification_commands: ${item}`),
+		`why_this_slice_first: ${capsule.why_this_slice_first}`,
+	];
 	if (capsule.why_cook_now) parts.push(`why_cook_now: ${capsule.why_cook_now}`);
 	return parts.join("\n").trim();
 }
 
-function isStartableCookHandoffCapsule(
+function cookHandoffAcceptanceItemIsRepoChangeOrVerificationOriented(item: string): boolean {
+	const normalized = normalizeProposalLine(item);
+	if (!normalized) return false;
+	if (hasExplicitPlanningOnlyDeliverable([normalized])) return false;
+	if (hasClearNoImplementationSignal([normalized])) return false;
+	if (implementationMissionSourceCandidateText(normalized)) return true;
+	if (COOK_HANDOFF_WORKFLOW_ONLY_ACCEPTANCE_REGEX.test(normalized)) return false;
+	return COOK_HANDOFF_VERIFICATION_ACCEPTANCE_REGEX.test(normalized) && COOK_HANDOFF_VERIFICATION_ACTION_REGEX.test(normalized);
+}
+
+function cookHandoffAcceptanceIsRepoChangeOriented(capsule: CookHandoffCapsule): boolean {
+	if (capsule.acceptance.length === 0) return false;
+	return capsule.acceptance.some((item) => cookHandoffAcceptanceItemIsRepoChangeOrVerificationOriented(item));
+}
+
+function cookHandoffStartabilityFailures(
 	capsule: CookHandoffCapsule,
 	deps: Pick<ProposalParseDeps, "normalizeMissionAnchorText" | "isWeakMissionAnchor">,
-): boolean {
+): string[] {
+	const failures: string[] = [];
 	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;
+	if (!mission || deps.isWeakMissionAnchor(mission)) failures.push("mission is missing a concrete implementation anchor");
+	else if (COOK_HANDOFF_NEGATIVE_MISSION_REGEX.test(mission)) failures.push("mission is negative or workflow-suppression-only");
+	if (capsule.scope.length === 0) failures.push("scope is empty");
+	if (capsule.acceptance.length === 0) failures.push("acceptance is empty");
+	else if (!cookHandoffAcceptanceIsRepoChangeOriented(capsule)) {
+		failures.push("acceptance is not anchored to concrete repo changes or verification");
+	}
+	const firstSliceGoal = deps.normalizeMissionAnchorText(capsule.first_slice_goal);
+	if (!firstSliceGoal || deps.isWeakMissionAnchor(firstSliceGoal) || COOK_HANDOFF_NEGATIVE_MISSION_REGEX.test(firstSliceGoal)) {
+		failures.push("first_slice_goal is not a bounded implementation slice");
+	} else if (hasExplicitPlanningOnlyDeliverable([capsule.first_slice_goal]) || hasClearNoImplementationSignal([capsule.first_slice_goal])) {
+		failures.push("first_slice_goal is planning-only instead of a repo-change slice");
+	}
+	if (capsule.implementation_surfaces.length === 0) failures.push("implementation_surfaces is empty");
+	if (capsule.verification_commands.length === 0) failures.push("verification_commands is empty");
+	return failures;
 }
 
-function laterMessagesInvalidateCookHandoff(
-	laterMessages: RecentSessionMessage[],
-	deps: Pick<ProposalParseDeps, "stripCodeBlocks">,
+function buildNonStartableCookHandoffMessage(failures: string[]): string {
+	return [
+		"/cook failed closed because a fresh explicit primary-agent handoff exists, but it is not concrete enough to start implementation workflow yet.",
+		"Tighten the handoff in the main chat so it names a bounded first implementation slice, repo-change-oriented acceptance, implementation_surfaces, and verification_commands, then rerun /cook.",
+		`Blocking details: ${failures.join("; ")}.`,
+	].join(" ");
+}
+
+function isStartableCookHandoffCapsule(
+	capsule: CookHandoffCapsule,
+	deps: Pick<ProposalParseDeps, "normalizeMissionAnchorText" | "isWeakMissionAnchor">,
 ): 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;
-	});
+	return cookHandoffStartabilityFailures(capsule, deps).length === 0;
 }
 
 function cookHandoffIsFreshEnough(capsule: CookHandoffCapsule, laterMessages: RecentSessionMessage[]): boolean {
@@ -1347,6 +1421,11 @@ function buildContextProposalFromCookHandoffCapsule(
 				evaluationProfile: capsule.evaluation_profile,
 				critique: [
 					...capsule.notes,
+					`First slice goal: ${capsule.first_slice_goal}`,
+					...(capsule.first_slice_non_goals.length > 0 ? [`First slice non-goals: ${capsule.first_slice_non_goals.join(" | ")}`] : []),
+					...(capsule.implementation_surfaces.length > 0 ? [`Implementation surfaces: ${capsule.implementation_surfaces.join(" | ")}`] : []),
+					...(capsule.verification_commands.length > 0 ? [`Verification commands: ${capsule.verification_commands.join(" | ")}`] : []),
+					`Why this slice first: ${capsule.why_this_slice_first}`,
 					...(capsule.why_cook_now ? [`Primary-agent /cook handoff rationale: ${capsule.why_cook_now}`] : []),
 				],
 				risks: capsule.risks,
@@ -1355,7 +1434,19 @@ function buildContextProposalFromCookHandoffCapsule(
 				suppressedCompletedTopics: [],
 				suppressedNegatedTopics: [],
 			},
-			[mission, goalText, capsule.mission, ...capsule.scope, ...constraints, ...capsule.acceptance],
+			[
+				mission,
+				goalText,
+				capsule.mission,
+				...capsule.scope,
+				...constraints,
+				...capsule.acceptance,
+				capsule.first_slice_goal,
+				...capsule.first_slice_non_goals,
+				...capsule.implementation_surfaces,
+				...capsule.verification_commands,
+				capsule.why_this_slice_first,
+			],
 		),
 		goalText,
 		basisPreview: buildCookHandoffBasisPreview(capsule),
@@ -1365,11 +1456,11 @@ function buildContextProposalFromCookHandoffCapsule(
 	return finalizeContextProposal(proposal, projectName, deps);
 }
 
-export function extractLatestCookHandoffProposal(
+export function assessLatestCookHandoffProposal(
 	recentMessages: RecentSessionMessage[],
 	projectName: string,
 	deps: ProposalParseDeps,
-): ContextProposal | undefined {
+): CookHandoffProposalAssessment {
 	for (let index = 0; index < recentMessages.length; index += 1) {
 		const entry = recentMessages[index];
 		if (entry.role !== "assistant" || entry.isCommand) continue;
@@ -1379,12 +1470,27 @@ export function extractLatestCookHandoffProposal(
 			const capsule = capsules[capsuleIndex];
 			const laterMessages = recentMessages.slice(0, index);
 			if (!cookHandoffIsFreshEnough(capsule, laterMessages)) continue;
-			if (laterMessagesInvalidateCookHandoff(laterMessages, deps)) continue;
+			const failures = cookHandoffStartabilityFailures(capsule, deps);
+			if (failures.length > 0) {
+				return {
+					status: "fresh_but_not_startable",
+					message: buildNonStartableCookHandoffMessage(failures),
+				};
+			}
 			const proposal = buildContextProposalFromCookHandoffCapsule(capsule, projectName, deps);
-			if (proposal) return proposal;
+			if (proposal) return { status: "startable", proposal };
 		}
 	}
-	return undefined;
+	return { status: "none" };
+}
+
+export function extractLatestCookHandoffProposal(
+	recentMessages: RecentSessionMessage[],
+	projectName: string,
+	deps: ProposalParseDeps,
+): ContextProposal | undefined {
+	const assessment = assessLatestCookHandoffProposal(recentMessages, projectName, deps);
+	return assessment.status === "startable" ? assessment.proposal : undefined;
 }
 
 export async function deriveCookContextProposalFromRecentDiscussion(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linimin/pi-letscook",
-  "version": "0.1.57",
+  "version": "0.1.59",
   "description": "Pi package for long-running completion workflows with canonical .agent state, role-based subagents, continuity, and verification helpers.",
   "license": "MIT",
   "private": false,
@@ -22,6 +22,11 @@
     "subagent"
   ],
   "files": [
+    ".agent/README.md",
+    ".agent/mission.md",
+    ".agent/profile.json",
+    ".agent/verify_completion_stop.sh",
+    ".agent/verify_completion_control_plane.sh",
     "extensions",
     "skills",
     "agents",

package/scripts/active-slice-contract-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
+}
+
 cd "$PKG_ROOT"
 
 node <<'NODE'
@@ -94,11 +137,59 @@ NODE
 ROOT="$TMPDIR/repo"
 PROMPT="$TMPDIR/resume-prompt.txt"
 BOOTSTRAP_SESSION="$TMPDIR/session-active-slice-bootstrap.jsonl"
-BOOTSTRAP_DISCUSSION=$'Mission: Exercise active-slice contract parity.\nScope:\n- Bootstrap canonical completion files for the active-slice contract fixture.\nConstraints:\n- Use supported bare /cook startup only.\nAcceptance:\n- Materialize canonical files before the fixture rewrites them.'
+BOOTSTRAP_MESSAGES="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Exercise active-slice contract parity.",
+    "scope": [
+        "Bootstrap canonical completion files for the active-slice contract fixture.",
+        "Keep the fixture on the shipped explicit-handoff startup path."
+    ],
+    "constraints": [
+        "Use supported bare /cook startup only."
+    ],
+    "acceptance": [
+        "Materialize .agent/profile.json, .agent/state.json, .agent/plan.json, .agent/active-slice.json, and .agent/verification-evidence.json before the fixture rewrites them.",
+        "Keep scripts/active-slice-contract-test.sh aligned with the packaged startup contract."
+    ],
+    "risks": [
+        "Active-slice fixture bootstrap must stay anchored to the fresh explicit handoff."
+    ],
+    "notes": [
+        "This handoff exists only to scaffold canonical files before the fixture rewrites them for contract parity coverage."
+    ],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Scaffold active-slice contract fixture files before rewriting them for parity verification.",
+    "first_slice_non_goals": [
+        "Do not broaden the fixture beyond active-slice contract surfaces."
+    ],
+    "implementation_surfaces": [
+        ".agent/active-slice.json",
+        "scripts/active-slice-contract-test.sh"
+    ],
+    "verification_commands": [
+        "bash scripts/active-slice-contract-test.sh"
+    ],
+    "why_this_slice_first": "The active-slice fixture cannot validate parity until canonical files exist.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "The fixture bootstrap is concrete enough to scaffold canonical control-plane files."
+}
+messages = [
+    {"role": "user", "content": "Prepare the active-slice contract bootstrap fixture and tell me when it is ready for /cook."},
+    {"role": "assistant", "content": "The active-slice contract bootstrap fixture is ready for /cook. Run /cook to confirm it.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
+]
+print(json.dumps(messages, ensure_ascii=False))
+PY
+)"
 mkdir -p "$ROOT"
 cd "$ROOT"
 git init -q
-write_session "$BOOTSTRAP_SESSION" "$ROOT" "$BOOTSTRAP_DISCUSSION"
+write_session_messages "$BOOTSTRAP_SESSION" "$ROOT" "$BOOTSTRAP_MESSAGES"
 
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
 PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \