@linimin/pi-letscook 0.1.57 → 0.1.58

package/CHANGELOG.md

@@ -2,12 +2,22 @@
 
 ## Unreleased
 
+## 0.1.58
+
+### Changed
+
+- tightened implementation-ready explicit `/cook` handoffs so fresh capsules must already carry a bounded first slice, repo-change-oriented acceptance, implementation surfaces, verification commands, and why-that-slice-first structure before workflow startup
+- made fresh explicit but non-startable `/cook` handoffs fail closed with a dedicated operator message instead of falling back to broader recent discussion or silently drifting into planning
+- expanded regressions and public parity so valid, vague, stale, done-workflow, and negative explicit-handoff cases stay truthful across runtime behavior, docs, and `npm run release-check`
+
 ## 0.1.57
 
 ### Changed
 
-- made explicit primary-agent `/cook` handoff the preferred startup-intake path by teaching ordinary-chat handoff turns to emit a structured `cook_handoff` capsule and letting `/cook` prefer that capsule over broad context re-inference when it is fresh and valid
-- kept context-derived startup as a fallback only, so stale, drifted, or non-startable handoff capsules still fail closed or fall back to recent discussion instead of silently rewriting canonical state
+- made explicit primary-agent `/cook` handoff the preferred startup-intake path by teaching ordinary-chat handoff turns to emit a structured `cook_handoff` capsule and letting `/cook` prefer that capsule over broad context re-inference when it is fresh, valid, and implementation-startable
+- tightened implementation-ready explicit handoffs so the structured capsule must already carry a bounded `first_slice_goal`, repo-change-oriented acceptance, `implementation_surfaces`, `verification_commands`, and `why_this_slice_first` before `/cook` will start workflow from it
+- kept the pre-`/cook` handoff capsule as advisory startup intake only, not canonical `.agent/**` workflow state, while still using context-derived startup as the fallback only when no fresh explicit handoff is blocking startup
+- kept context-derived startup as a fallback only when there is no fresh explicit handoff blocking startup, so stale or invalidated capsules can still fall back to recent discussion while fresh non-startable handoffs fail closed instead of silently rewriting canonical state
 - made finished-workflow suppression stay a safety layer instead of a replacement mission when a fresh explicit `/cook` handoff exists, and blocked negative rejection/suppression text from becoming a Startable startup mission
 - removed inline `/cook` arguments from the shipped entry path again so explicit bare `/cook` is the only public command, and fail closed when recent discussion is insufficient or unreliable
 - added a pre-`/cook` ordinary-chat handoff boundary so the primary agent is instructed to stop at `/cook` once a task has matured into completion-workflow scope instead of starting long-running implementation directly in ordinary chat

package/README.md

@@ -50,13 +50,16 @@ Then run `/reload` in Pi.
 ## What `/cook` expects
 
 - preferably a fresh explicit primary-agent `/cook` handoff capsule from the immediately preceding ordinary-chat turn
-- otherwise recent main-chat discussion about concrete repo changes
+- for that handoff capsule to start workflow immediately, it must already be implementation-startable: a bounded `first_slice_goal`, repo-change-oriented acceptance, `implementation_surfaces`, `verification_commands`, and `why_this_slice_first`
+- otherwise, when no fresh explicit handoff is blocking startup, recent main-chat discussion about concrete repo changes
 - enough detail to derive a startup brief with mission, scope, constraints or non-goals, acceptance, and notes or risks
 - README/CHANGELOG updates still count as concrete repo changes
 - assistant-produced summaries and plan/spec/design-doc/proposal-only artifacts still do not count unless they include the explicit structured `/cook` handoff capsule
 
 If no fresh valid handoff exists and recent discussion is missing, weak, ambiguous, assistant-produced, or only describes planning artifacts instead of concrete repo changes, `/cook` fails closed, leaves canonical `.agent/**` state unchanged, and tells you to clarify the mission in the main chat before rerunning `/cook`.
 
+If 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.
+
 If you pass inline arguments to `/cook`, it also fails closed and tells you to move that intent into the main chat before rerunning bare `/cook`.
 
 ## Workflow entry
@@ -67,6 +70,8 @@ If a task has clearly matured into completion-workflow scope, the primary agent
 
 That handoff should include an explicit structured `/cook` capsule in the assistant reply so `/cook` can confirm the already-formed mission instead of re-deriving it from broad ambient context.
 
+The preferred capsule is still advisory startup intake, not canonical workflow state, and it only counts as implementation-ready when it already names the first bounded slice, repo-change-oriented acceptance, implementation surfaces, and verification commands.
+
 Important behavior:
 - `/cook` is the canonical workflow boundary and manual entry point
 - startup, refocus, and next-round routing stay confirm-first; nothing silently starts a workflow
@@ -84,13 +89,13 @@ I want to add login redirect handling and tests.
 
 ## What happens when you run `/cook`
 
-`/cook` first looks for a fresh explicit primary-agent handoff capsule. If one is valid, `/cook` builds the startup brief from that handoff and only uses recent discussion as validation or supplemental notes. If no valid handoff exists, `/cook` falls back to deriving a startup brief from recent discussion before showing the existing approval-only Start/Cancel gate.
+`/cook` first looks for a fresh explicit primary-agent handoff capsule. If one is valid and implementation-startable, `/cook` builds the startup brief from that handoff and only uses recent discussion as validation or supplemental notes. `/cook` falls back to deriving a startup brief from recent discussion only when no fresh explicit handoff is blocking startup—for example, when there is no fresh capsule or only stale or invalidated capsules—before showing the existing approval-only Start/Cancel gate.
 
 | Repo state | What you'll see |
 |---|---|
-| No workflow yet | If a fresh explicit handoff capsule exists, a startup brief built from that handoff. Otherwise a startup brief built from recent main-chat discussion. You choose **Start** or **Cancel**. Weak, unreliable, stale, or planning-only intake fails closed. |
+| No workflow yet | If a fresh explicit handoff capsule exists and is implementation-startable, a startup brief built from that handoff. Otherwise, when no fresh explicit handoff is blocking startup, a startup brief built from recent main-chat discussion. You choose **Start** or **Cancel**. Weak, unreliable, stale, planning-only, or non-startable explicit-handoff intake fails closed. |
 | Active workflow exists | Usually a resume of the current workflow. If a fresh explicit handoff capsule or recent discussion clearly points to a different concrete repo change, `/cook` shows a chooser first and only rewrites canonical state after you confirm the new startup brief. Ambiguous intake stays conservative. |
-| Previous workflow is `done` | A fresh explicit handoff capsule can still start the next implementation round behind **Start** or **Cancel**. Without that, `/cook` falls back to recent discussion. Discussion that only restates already-finished work still fails closed. |
+| Previous workflow is `done` | A fresh explicit handoff capsule can still start the next implementation round behind **Start** or **Cancel**. Without a fresh explicit handoff blocking startup, `/cook` can fall back to recent discussion. Discussion that only restates already-finished work still fails closed. |
 
 ## Confirmation and fail-closed behavior
 

package/extensions/completion/driver.ts

@@ -38,7 +38,7 @@ type ContextProposalAlternate = {
 	analysis: ContextProposalAnalysis;
 	goalText: string;
 	basisPreview: string;
-	source: "session" | "analyst";
+	source: "session" | "analyst" | "handoff_capsule";
 };
 
 type ContextProposal = ContextProposalAlternate & {
@@ -55,11 +55,22 @@ type ExistingWorkflowDecision =
 	| { action: "continue"; currentMissionAnchor: string }
 	| { action: "refocus"; currentMissionAnchor: string; missionAnchor: string; proposal: ContextProposal };
 
+type CookContextProposalResult = {
+	proposal?: ContextProposal;
+	blockedFailureMessage?: string;
+};
+
 type ActiveWorkflowProposalAssessment = {
-	action: "continue" | "refocus" | "unclear";
+	action: "continue" | "refocus" | "unclear" | "blocked";
 	currentMissionAnchor: string;
 	proposal?: ContextProposal;
-	reason: "matching_mission" | "clear_refocus" | "missing_proposal" | "ambiguous_discussion";
+	blockedFailureMessage?: string;
+	reason:
+		| "matching_mission"
+		| "clear_refocus"
+		| "missing_proposal"
+		| "ambiguous_discussion"
+		| "fresh_explicit_handoff_not_startable";
 };
 
 type ExistingWorkflowChooserOptions = {
@@ -110,7 +121,7 @@ export type CompletionDriverDeps = {
 		missionAnchor?: string,
 	) => string;
 	completionResumePrompt: (taskType: string, evaluationProfile: string) => string;
-	deriveCookContextProposal: (ctx: DriverContext, projectName: string) => Promise<ContextProposal | undefined>;
+	deriveCookContextProposal: (ctx: DriverContext, projectName: string) => Promise<CookContextProposalResult>;
 	confirmContextProposal: (
 		ctx: { hasUI: boolean; ui: any },
 		proposal: ContextProposal,
@@ -305,7 +316,18 @@ async function assessActiveWorkflowProposalRouting(
 ): Promise<ActiveWorkflowProposalAssessment> {
 	const currentMission = currentMissionAnchor(snapshot);
 	const projectName = path.basename(snapshot.files.root);
-	const proposal = await deps.deriveCookContextProposal(ctx, projectName);
+	const derived = await deps.deriveCookContextProposal(ctx, projectName);
+	if (derived.blockedFailureMessage) {
+		const assessment: ActiveWorkflowProposalAssessment = {
+			action: "blocked",
+			currentMissionAnchor: currentMission,
+			blockedFailureMessage: derived.blockedFailureMessage,
+			reason: "fresh_explicit_handoff_not_startable",
+		};
+		deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
+		return assessment;
+	}
+	const proposal = derived.proposal;
 	if (!proposal) {
 		const assessment: ActiveWorkflowProposalAssessment = {
 			action: "unclear",
@@ -519,7 +541,12 @@ export async function runCookEntry(
 	if (!snapshot) {
 		const root = findRepoRoot(cwd) ?? cwd;
 		const projectName = path.basename(root);
-		const proposal = await deps.deriveCookContextProposal(ctx, projectName);
+		const derived = await deps.deriveCookContextProposal(ctx, projectName);
+		if (derived.blockedFailureMessage) {
+			deps.emitCommandText(ctx, derived.blockedFailureMessage, "info");
+			return;
+		}
+		const proposal = derived.proposal;
 		if (!proposal) {
 			deps.emitCommandText(ctx, buildCookStructuredDiscussionFailureMessage(deps), "info");
 			return;
@@ -559,7 +586,12 @@ export async function runCookEntry(
 	if (!goal) {
 		if (workflowDone) {
 			const projectName = path.basename(snapshot.files.root);
-			const proposal = await deps.deriveCookContextProposal(ctx, projectName);
+			const derived = await deps.deriveCookContextProposal(ctx, projectName);
+			if (derived.blockedFailureMessage) {
+				deps.emitCommandText(ctx, derived.blockedFailureMessage, "info");
+				return;
+			}
+			const proposal = derived.proposal;
 			if (!proposal) {
 				deps.emitCommandText(ctx, buildCookStructuredDiscussionFailureMessage(deps, "The previous completion workflow is already done."), "info");
 				return;
@@ -586,6 +618,10 @@ export async function runCookEntry(
 			deps.emitCommandText(ctx, `Started a new completion workflow round from recent discussion: ${decision.missionAnchor}`, "info");
 		} else {
 			const assessment = await assessActiveWorkflowProposalRouting(ctx, snapshot, deps);
+			if (assessment.action === "blocked") {
+				deps.emitCommandText(ctx, assessment.blockedFailureMessage ?? buildCookStructuredDiscussionFailureMessage(deps), "info");
+				return;
+			}
 			if (!assessment.proposal || assessment.action === "continue") {
 				await resumeActiveWorkflowFromCanonicalState(pi, ctx, snapshot, deps);
 				return;

package/extensions/completion/index.ts

@@ -18,7 +18,7 @@ import {
 	collectRecentDiscussionEntries,
 	collectRecentSessionMessages,
 	deriveCookContextProposalFromRecentDiscussion,
-	extractLatestCookHandoffProposal,
+	assessLatestCookHandoffProposal,
 	finalizeContextProposalAnalysis,
 	isWeakMissionAnchor,
 	missionAnchorsLikelyEquivalent,
@@ -122,11 +122,22 @@ 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" | "unclear" | "blocked";
 	currentMissionAnchor: string;
 	proposal?: ContextProposal;
-	reason: "matching_mission" | "clear_refocus" | "missing_proposal" | "ambiguous_discussion";
+	blockedFailureMessage?: string;
+	reason:
+		| "matching_mission"
+		| "clear_refocus"
+		| "missing_proposal"
+		| "ambiguous_discussion"
+		| "fresh_explicit_handoff_not_startable";
 };
 
 function completionTestWorkflowActionOverride(): "continue" | "refocus" | "cancel" | undefined {
@@ -271,6 +282,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 ?? [],
@@ -365,7 +377,7 @@ async function promptContextProposalConfirmationAction(
 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,7 +396,7 @@ async function deriveCookContextProposal(
 			`verification summary: ${asString(snapshot.verificationEvidence?.summary) ?? "(none)"}`,
 		]
 		: [];
-	const explicitHandoff = extractLatestCookHandoffProposal(recentMessages, projectName, {
+	const explicitHandoff = assessLatestCookHandoffProposal(recentMessages, projectName, {
 		asString,
 		asStringArray,
 		assessMissionAnchor,
@@ -393,42 +405,47 @@ async function deriveCookContextProposal(
 		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,
-	});
+	if (explicitHandoff.status === "startable") return { proposal: explicitHandoff.proposal };
+	if (explicitHandoff.status === "fresh_but_not_startable") {
+		return { blockedFailureMessage: explicitHandoff.message };
+	}
+	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(

package/extensions/completion/prompt-surfaces.ts

@@ -31,8 +31,11 @@ export function buildCookHandoffBoundaryReminder(): string {
 		"/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.",
+		"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.",
 		"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.",
+		"If the task is workflow-worthy but that first slice is still vague, tell the user to run /cook without emitting an implementation-ready capsule yet.",
+		"Otherwise 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.",
 		"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;
@@ -1231,6 +1249,12 @@ 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 +1275,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 +1304,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,20 +1319,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 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">,
+): string[] {
+	const failures: string[] = [];
+	const mission = deps.normalizeMissionAnchorText(capsule.mission);
+	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 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 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;
+	return cookHandoffStartabilityFailures(capsule, deps).length === 0;
 }
 
 function laterMessagesInvalidateCookHandoff(
@@ -1347,6 +1435,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 +1448,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 +1470,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;
@@ -1380,11 +1485,27 @@ export function extractLatestCookHandoffProposal(
 			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.58",
   "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

@@ -1433,7 +1433,19 @@ capsule = {
     "notes": [
         "Keep the startup brief aligned with the explicit primary-agent plan."
     ],
-    "handoff_kind": "implementation_workflow_ready",
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Land the redirect callback fix and its regression coverage.",
+    "first_slice_non_goals": [
+        "Do not refactor the broader auth flow."
+    ],
+    "implementation_surfaces": [
+        "src/auth/redirect.ts",
+        "tests/auth/redirect.spec.ts"
+    ],
+    "verification_commands": [
+        "npm test -- redirect.spec.ts"
+    ],
+    "why_this_slice_first": "The redirect callback bug is already bounded enough to start implementation safely.",
     "task_type": "completion-workflow",
     "evaluation_profile": "completion-rubric-v1",
     "why_cook_now": "The implementation plan is concrete and ready for repo changes."
@@ -1465,9 +1477,166 @@ assert snapshot['mission'] == 'Fix login redirect callback behavior.', 'explicit
 assert state['mission_anchor'] == 'Fix login redirect callback behavior.', 'explicit handoff startup should use the handoff mission as canonical mission_anchor'
 assert state['advisory_startup_brief']['source'] == 'primary_agent_handoff', 'explicit handoff startup should preserve the advisory intake source'
 assert state['advisory_startup_brief']['risks'] == ['Stale auth discussion could broaden the startup brief if the handoff is ignored.'], 'explicit handoff startup should preserve handoff risks'
+assert 'First slice goal: Land the redirect callback fix and its regression coverage.' in state['advisory_startup_brief']['notes'], 'explicit handoff startup should preserve first_slice_goal in advisory notes'
+assert 'First slice non-goals: Do not refactor the broader auth flow.' in state['advisory_startup_brief']['notes'], 'explicit handoff startup should preserve first_slice_non_goals in advisory notes'
+assert 'Implementation surfaces: src/auth/redirect.ts | tests/auth/redirect.spec.ts' in state['advisory_startup_brief']['notes'], 'explicit handoff startup should preserve implementation_surfaces in advisory notes'
+assert 'Verification commands: npm test -- redirect.spec.ts' in state['advisory_startup_brief']['notes'], 'explicit handoff startup should preserve verification_commands in advisory notes'
+assert 'Why this slice first: The redirect callback bug is already bounded enough to start implementation safely.' in state['advisory_startup_brief']['notes'], 'explicit handoff startup should preserve why_this_slice_first in advisory notes'
 assert 'Primary-agent /cook handoff rationale: The implementation plan is concrete and ready for repo changes.' in state['advisory_startup_brief']['notes'], 'explicit handoff startup should preserve why_cook_now as notes'
 PY
 
+# Fresh but non-startable explicit handoff: /cook should fail closed instead of falling back
+# to a broad recent-discussion startup brief when the explicit capsule is still too vague.
+HANDOFF_ROOT_VAGUE="$TMPDIR/handoff-root-vague"
+mkdir -p "$HANDOFF_ROOT_VAGUE"
+cd "$HANDOFF_ROOT_VAGUE"
+git init -q
+
+HANDOFF_SESSION_VAGUE="$TMPDIR/handoff-session-vague.jsonl"
+HANDOFF_SNAPSHOT_VAGUE="$TMPDIR/handoff-proposal-vague.json"
+HANDOFF_MESSAGES_VAGUE="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Fix login redirect callback behavior.",
+    "scope": [
+        "Update the callback redirect decision logic."
+    ],
+    "constraints": [
+        "Do not refactor the broader auth flow."
+    ],
+    "acceptance": [
+        "Confirm the final implementation breakdown before coding."
+    ],
+    "risks": [
+        "Broad recent context could be reused if the vague explicit handoff is ignored."
+    ],
+    "notes": [
+        "This handoff is still too vague to start implementation directly."
+    ],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Patch the callback redirect decision logic.",
+    "first_slice_non_goals": [
+        "Do not refactor the broader auth flow."
+    ],
+    "implementation_surfaces": [],
+    "verification_commands": [],
+    "why_this_slice_first": "The callback redirect path is the likely first slice, but the handoff still lacks execution detail.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "The task is workflow-worthy, but the implementation slice is not concrete enough yet."
+}
+recent_discussion = "Mission: Fix login redirect callback behavior.\nScope:\n- Update the callback redirect decision logic.\nConstraints:\n- Do not refactor the broader auth flow.\nAcceptance:\n- Add a regression test for returning to the requested page."
+messages = [
+    {"role": "user", "content": recent_discussion},
+    {"role": "assistant", "content": "This follow-up might soon be ready for /cook.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
+]
+print(json.dumps(messages, ensure_ascii=False))
+PY
+)"
+write_session_messages "$HANDOFF_SESSION_VAGUE" "$HANDOFF_ROOT_VAGUE" "$HANDOFF_MESSAGES_VAGUE"
+
+PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$HANDOFF_SNAPSHOT_VAGUE" \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$HANDOFF_SESSION_VAGUE" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-vague.out" 2>"$TMPDIR/pi-completion-handoff-vague.err"
+
+python3 - "$HANDOFF_SNAPSHOT_VAGUE" "$TMPDIR/pi-completion-handoff-vague.out" "$TMPDIR/pi-completion-handoff-vague.err" <<'PY'
+import sys
+from pathlib import Path
+
+snapshot = Path(sys.argv[1])
+output = Path(sys.argv[2]).read_text() + Path(sys.argv[3]).read_text()
+
+assert not snapshot.exists(), 'fresh non-startable handoff should not emit a startup proposal snapshot'
+assert not Path('.agent').exists(), 'fresh non-startable handoff should fail closed without writing canonical state'
+assert 'fresh explicit primary-agent handoff exists' in output, 'fresh non-startable handoff should explain that the explicit capsule blocked startup'
+assert 'acceptance is not anchored to concrete repo changes or verification' in output, 'fresh non-startable handoff should explain the workflow-only acceptance failure'
+assert 'implementation_surfaces is empty' in output, 'fresh non-startable handoff should explain the missing implementation_surfaces requirement'
+assert 'verification_commands is empty' in output, 'fresh non-startable handoff should explain the missing verification_commands requirement'
+PY
+
+# Fresh explicit handoff with complete first-slice fields but vague acceptance: /cook should still fail closed
+# with the dedicated explicit-handoff message instead of bootstrapping canonical state.
+HANDOFF_ROOT_VAGUE_ACCEPTANCE="$TMPDIR/handoff-root-vague-acceptance"
+mkdir -p "$HANDOFF_ROOT_VAGUE_ACCEPTANCE"
+cd "$HANDOFF_ROOT_VAGUE_ACCEPTANCE"
+git init -q
+
+HANDOFF_SESSION_VAGUE_ACCEPTANCE="$TMPDIR/handoff-session-vague-acceptance.jsonl"
+HANDOFF_SNAPSHOT_VAGUE_ACCEPTANCE="$TMPDIR/handoff-proposal-vague-acceptance.json"
+HANDOFF_MESSAGES_VAGUE_ACCEPTANCE="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Fix login redirect callback behavior.",
+    "scope": [
+        "Update the callback redirect decision logic.",
+        "Preserve the broader auth flow."
+    ],
+    "constraints": [
+        "Do not refactor the broader auth flow."
+    ],
+    "acceptance": [
+        "Current behavior stays understandable."
+    ],
+    "risks": [
+        "Broad recent context could be reused if the vague explicit handoff is ignored."
+    ],
+    "notes": [
+        "This handoff includes first-slice fields but still lacks concrete acceptance."
+    ],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Land the redirect callback fix and its regression coverage.",
+    "first_slice_non_goals": [
+        "Do not refactor the broader auth flow."
+    ],
+    "implementation_surfaces": [
+        "src/auth/redirect.ts",
+        "tests/auth/redirect.spec.ts"
+    ],
+    "verification_commands": [
+        "npm test -- redirect.spec.ts"
+    ],
+    "why_this_slice_first": "The redirect callback bug is already bounded enough to start implementation safely once acceptance is concrete.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "The task is workflow-worthy, but the acceptance still needs concrete repo-change detail."
+}
+recent_discussion = "Mission: Fix login redirect callback behavior.\nScope:\n- Update the callback redirect decision logic.\nConstraints:\n- Do not refactor the broader auth flow.\nAcceptance:\n- Add a regression test for returning to the requested page."
+messages = [
+    {"role": "user", "content": recent_discussion},
+    {"role": "assistant", "content": "This follow-up might soon be ready for /cook.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
+]
+print(json.dumps(messages, ensure_ascii=False))
+PY
+)"
+write_session_messages "$HANDOFF_SESSION_VAGUE_ACCEPTANCE" "$HANDOFF_ROOT_VAGUE_ACCEPTANCE" "$HANDOFF_MESSAGES_VAGUE_ACCEPTANCE"
+
+PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$HANDOFF_SNAPSHOT_VAGUE_ACCEPTANCE" \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$HANDOFF_SESSION_VAGUE_ACCEPTANCE" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-vague-acceptance.out" 2>"$TMPDIR/pi-completion-handoff-vague-acceptance.err"
+
+python3 - "$HANDOFF_SNAPSHOT_VAGUE_ACCEPTANCE" "$TMPDIR/pi-completion-handoff-vague-acceptance.out" "$TMPDIR/pi-completion-handoff-vague-acceptance.err" <<'PY'
+import sys
+from pathlib import Path
+
+snapshot = Path(sys.argv[1])
+output = Path(sys.argv[2]).read_text() + Path(sys.argv[3]).read_text()
+
+assert not snapshot.exists(), 'fresh explicit handoff with vague acceptance should not emit a startup proposal snapshot'
+assert not Path('.agent').exists(), 'fresh explicit handoff with vague acceptance should fail closed without writing canonical state'
+assert 'fresh explicit primary-agent handoff exists' in output, 'fresh explicit handoff with vague acceptance should use the dedicated explicit-handoff fail-closed message'
+assert 'acceptance is not anchored to concrete repo changes or verification' in output, 'fresh explicit handoff with vague acceptance should explain the vague acceptance failure'
+PY
+
 # Done workflow + fresh handoff: the fresh explicit handoff should override done-state suppression and start the new round.
 HANDOFF_ROOT_DONE="$TMPDIR/handoff-root-done"
 mkdir -p "$HANDOFF_ROOT_DONE"
@@ -1509,7 +1678,19 @@ capsule = {
     "notes": [
         "This is a fresh implementation round, not a summary of the finished workflow."
     ],
-    "handoff_kind": "implementation_workflow_ready",
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Patch the callback edge case and cover it with a focused regression test.",
+    "first_slice_non_goals": [
+        "Do not turn done-state suppression into the startup mission."
+    ],
+    "implementation_surfaces": [
+        "src/auth/redirect.ts",
+        "tests/auth/redirect-edge.spec.ts"
+    ],
+    "verification_commands": [
+        "npm test -- redirect-edge.spec.ts"
+    ],
+    "why_this_slice_first": "The new callback edge case is the smallest fresh implementation slice after the prior round closed.",
     "task_type": "completion-workflow",
     "evaluation_profile": "completion-rubric-v1",
     "why_cook_now": "A new implementation-ready edge case was identified after the previous round closed."
@@ -1541,6 +1722,8 @@ assert snapshot['mission'] == 'Reopen the login redirect work for the callback e
 assert state['mission_anchor'] == 'Reopen the login redirect work for the callback edge case.', 'done-workflow handoff should override done-state suppression with the fresh mission'
 assert state['continuation_policy'] == 'continue', 'done-workflow handoff should reopen canonical workflow state for the new round'
 assert state['advisory_startup_brief']['source'] == 'primary_agent_handoff', 'done-workflow handoff should preserve the handoff advisory source'
+assert 'First slice goal: Patch the callback edge case and cover it with a focused regression test.' in state['advisory_startup_brief']['notes'], 'done-workflow handoff should preserve first_slice_goal in advisory notes'
+assert 'Verification commands: npm test -- redirect-edge.spec.ts' in state['advisory_startup_brief']['notes'], 'done-workflow handoff should preserve verification_commands in advisory notes'
 PY
 
 # Stale handoff: later discussion should invalidate the older handoff capsule and fall back to the newer discussion mission.
@@ -1564,7 +1747,12 @@ capsule = {
     "acceptance": ["Add the original callback regression test."],
     "risks": [],
     "notes": [],
-    "handoff_kind": "implementation_workflow_ready"
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Ship the original login callback follow-up.",
+    "first_slice_non_goals": ["Do not refactor the auth stack."],
+    "implementation_surfaces": ["src/auth/login-redirect.ts"],
+    "verification_commands": ["npm test -- login-redirect.spec.ts"],
+    "why_this_slice_first": "The original callback follow-up was the first bounded implementation slice before later discussion replaced it."
 }
 newer_discussion = "Mission: Ship logout redirect consistency instead.\nScope:\n- Update the logout redirect path.\nConstraints:\n- Leave the login callback flow unchanged.\nAcceptance:\n- Add a logout redirect regression test."
 messages = [
@@ -1618,7 +1806,12 @@ capsule = {
     "acceptance": ["Explain that the finished workflow should stay closed."],
     "risks": [],
     "notes": [],
-    "handoff_kind": "implementation_workflow_ready"
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Keep the finished workflow closed.",
+    "first_slice_non_goals": ["Do not start repo changes."],
+    "implementation_surfaces": ["docs/workflow-status.md"],
+    "verification_commands": ["npm test -- workflow-status"],
+    "why_this_slice_first": "This is the only bounded next step being proposed, even though the mission itself is invalid."
 }
 messages = [
     {"role": "user", "content": "Should we reopen the finished workflow?"},

package/scripts/release-check.sh

@@ -3,6 +3,7 @@ set -euo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$ROOT"
+export PI_COMPLETION_RUNNING_RELEASE_CHECK=1
 
 echo "[release-check] running control-plane validation, tracked .agent contract coverage, slice-surface parity, explicit-/cook parity, startup/refocus/context regressions, canonical evidence artifact, active-slice contract, observability, legacy cleanup, evaluator calibration, and rubric contract coverage"
 bash .agent/verify_completion_control_plane.sh
@@ -19,18 +20,24 @@ checks = {
         "Only explicit `/cook` enters the workflow. Ordinary prompts stay in the main chat and go straight to the primary agent.",
         "If a task has clearly matured into completion-workflow scope, the primary agent should hand you off to `/cook` instead of starting long-running implementation directly in ordinary chat.",
         "That handoff should include an explicit structured `/cook` capsule in the assistant reply so `/cook` can confirm the already-formed mission instead of re-deriving it from broad ambient context.",
-        "`/cook` first looks for a fresh explicit primary-agent handoff capsule.",
+        "for that handoff capsule to start workflow immediately, it must already be implementation-startable: a bounded `first_slice_goal`, repo-change-oriented acceptance, `implementation_surfaces`, `verification_commands`, and `why_this_slice_first`",
+        "The preferred capsule is still advisory startup intake, not canonical workflow state, and it only counts as implementation-ready when it already names the first bounded slice, repo-change-oriented acceptance, implementation surfaces, and verification commands.",
+        "`/cook` first looks for a fresh explicit primary-agent handoff capsule. If one is valid and implementation-startable, `/cook` builds the startup brief from that handoff and only uses recent discussion as validation or supplemental notes.",
+        "`/cook` falls back to deriving a startup brief from recent discussion only when no fresh explicit handoff is blocking startup—for example, when there is no fresh capsule or only stale or invalidated capsules—before showing the existing approval-only Start/Cancel gate.",
         "The pre-`/cook` handoff capsule itself is not canonical workflow state. It is only startup intake for `/cook`.",
     ],
     "CHANGELOG.md": [
-        "made explicit primary-agent `/cook` handoff the preferred startup-intake path by teaching ordinary-chat handoff turns to emit a structured `cook_handoff` capsule and letting `/cook` prefer that capsule over broad context re-inference when it is fresh and valid",
-        "kept context-derived startup as a fallback only, so stale, drifted, or non-startable handoff capsules still fail closed or fall back to recent discussion instead of silently rewriting canonical state",
+        "made explicit primary-agent `/cook` handoff the preferred startup-intake path by teaching ordinary-chat handoff turns to emit a structured `cook_handoff` capsule and letting `/cook` prefer that capsule over broad context re-inference when it is fresh, valid, and implementation-startable",
+        "tightened implementation-ready explicit handoffs so the structured capsule must already carry a bounded `first_slice_goal`, repo-change-oriented acceptance, `implementation_surfaces`, `verification_commands`, and `why_this_slice_first` before `/cook` will start workflow from it",
+        "kept the pre-`/cook` handoff capsule as advisory startup intake only, not canonical `.agent/**` workflow state, while still using context-derived startup as the fallback only when no fresh explicit handoff is blocking startup",
+        "kept context-derived startup as a fallback only when there is no fresh explicit handoff blocking startup, so stale or invalidated capsules can still fall back to recent discussion while fresh non-startable handoffs fail closed instead of silently rewriting canonical state",
         "made finished-workflow suppression stay a safety layer instead of a replacement mission when a fresh explicit `/cook` handoff exists, and blocked negative rejection/suppression text from becoming a Startable startup mission",
     ],
     "extensions/completion/prompt-surfaces.ts": [
         '"/cook is the only explicit entrypoint into long-running completion workflow."',
         '"When you judge that the task has matured into completion-workflow scope',
-        '"Also append one exact fenced block in the same assistant reply using ```cook_handoff ... ``` JSON',
+        '"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."',
+        '"Otherwise 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."',
         '"The capsule is startup intake for /cook only: do not present it as canonical .agent state',
     ],
 }

package/scripts/smoke-test.sh

@@ -171,6 +171,8 @@ handoff_text = handoff.read_text()
 assert '/cook is the only explicit entrypoint into long-running completion workflow.' in handoff_text, 'ordinary handoff reminder should preserve the explicit /cook workflow boundary'
 assert 'stop short of long-running implementation and tell the user to run /cook.' in handoff_text, 'ordinary handoff reminder should require primary-agent handoff before implementation'
 assert '```cook_handoff ... ``` JSON' in handoff_text, 'ordinary handoff reminder should require the explicit structured /cook handoff capsule'
+assert 'implementation_workflow_handoff' in handoff_text, 'ordinary handoff reminder should require the implementation-ready handoff kind'
+assert 'first_slice_goal, first_slice_non_goals, implementation_surfaces, verification_commands, why_this_slice_first' in handoff_text, 'ordinary handoff reminder should require first-slice startability fields'
 assert 'The capsule is startup intake for /cook only' in handoff_text, 'ordinary handoff reminder should keep the capsule non-canonical'
 assert not auto_resume.exists(), 'ordinary non-/cook turn should not queue auto-resume before /cook activation'
 assert 'Skipped completion workflow auto-resume prompt (test mode)' not in output, 'ordinary non-/cook turn should not attempt auto-resume'

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

@@ -36,7 +36,8 @@ When the task is judged ready for completion workflow, the primary agent must:
 - not edit tracked product files in ordinary chat for that workflow-level task
 - tell the user to run `/cook`
 - explain that `/cook` will first look for a fresh explicit primary-agent handoff and otherwise fall back to recent discussion before asking for confirmation
-- append one exact structured `/cook` handoff capsule in the same assistant reply
+- distinguish a workflow-worthy handoff from an implementation-ready handoff
+- only append an implementation-ready `/cook` handoff capsule when the first bounded implementation slice is concrete enough to start immediately
 
 Required capsule format:
 
@@ -50,10 +51,16 @@ Required capsule format:
   "mission": "<startable implementation mission>",
   "scope": ["..."],
   "constraints": ["..."],
+  "non_goals": ["..."],
   "acceptance": ["..."],
   "risks": ["..."],
   "notes": ["..."],
-  "handoff_kind": "implementation_workflow_ready",
+  "handoff_kind": "implementation_workflow_handoff",
+  "first_slice_goal": "<bounded first slice goal>",
+  "first_slice_non_goals": ["..."],
+  "implementation_surfaces": ["path/or/surface"],
+  "verification_commands": ["npm test -- example"],
+  "why_this_slice_first": "<why this first slice should start the workflow>",
   "task_type": "completion-workflow",
   "evaluation_profile": "completion-rubric-v1",
   "why_cook_now": "<why the task is ready for /cook now>"
@@ -64,6 +71,7 @@ Required capsule format:
 Notes:
 
 - `constraints` may be replaced or supplemented by `non_goals` when clearer.
+- `first_slice_goal`, `first_slice_non_goals`, `implementation_surfaces`, `verification_commands`, and `why_this_slice_first` are required only for implementation-ready handoffs; if the work is workflow-worthy but that first slice is still vague, tell the user to run `/cook` without emitting this implementation-ready capsule.
 - The mission must be positively startable implementation work; do not use rejection or suppression text as the mission.
 - The capsule is startup intake for `/cook` only. It is not canonical `.agent/**` state, not active-slice state, and not a second repo contract source.