@linimin/pi-letscook 0.1.56 → 0.1.58

package/CHANGELOG.md

@@ -2,9 +2,23 @@
 
 ## 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 `/cook` derive a confirmable startup brief from recent discussion before any canonical workflow rewrite, then preserve the confirmed brief in canonical state as advisory intake for later re-grounding
+- made explicit primary-agent `/cook` handoff the preferred startup-intake path by teaching ordinary-chat handoff turns to emit a structured `cook_handoff` capsule and letting `/cook` prefer that capsule over broad context re-inference when it is fresh, 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

@@ -49,12 +49,16 @@ Then run `/reload` in Pi.
 
 ## What `/cook` expects
 
-- recent main-chat discussion about concrete repo changes
+- preferably a fresh explicit primary-agent `/cook` handoff capsule from the immediately preceding ordinary-chat turn
+- 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 do not
+- assistant-produced summaries and plan/spec/design-doc/proposal-only artifacts still do not count unless they include the explicit structured `/cook` handoff capsule
 
-If recent discussion is missing, weak, ambiguous, assistant-produced, or only describes planning artifacts instead of concrete repo changes, `/cook` fails closed, leaves canonical `.agent/**` state unchanged, and tells you to clarify the mission in the main chat before rerunning `/cook`.
+If no fresh valid handoff exists and recent discussion is missing, weak, ambiguous, assistant-produced, or only describes planning artifacts instead of concrete repo changes, `/cook` fails closed, leaves canonical `.agent/**` state unchanged, and tells you to clarify the mission in the main chat before rerunning `/cook`.
+
+If 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`.
 
@@ -64,6 +68,10 @@ Only explicit `/cook` enters the workflow. Ordinary prompts stay in the main cha
 
 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.
+
+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
@@ -81,13 +89,13 @@ I want to add login redirect handling and tests.
 
 ## What happens when you run `/cook`
 
-`/cook` first derives a startup brief from recent discussion, then shows the existing approval-only Start/Cancel gate.
+`/cook` first looks for a fresh explicit primary-agent handoff capsule. If one is valid 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 | A startup brief built from recent main-chat discussion. You choose **Start** or **Cancel**. Weak, unreliable, or planning-only discussion fails closed. |
-| Active workflow exists | Usually a resume of the current workflow. If recent discussion clearly points to a different concrete repo change, `/cook` shows a chooser first and only rewrites canonical state after you confirm the new startup brief. Ambiguous discussion stays conservative. |
-| Previous workflow is `done` | A next-round startup brief from recent main-chat discussion, again behind **Start** or **Cancel**. Discussion that only restates already-finished work fails closed. |
+| No workflow yet | If a fresh explicit handoff capsule exists 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 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
 
@@ -96,13 +104,15 @@ I want to add login redirect handling and tests.
 - startup, next-round, and refocus proposals are approval-only
 - actions are **Start** and **Cancel**
 - **Cancel** is side-effect free: discuss changes in the main chat and rerun `/cook`
-- weak, ambiguous, assistant-produced, or planning-only discussion does not start a workflow
+- weak, ambiguous, stale, invalid, assistant-produced, or planning-only intake does not start a workflow
 - when recent discussion suggests a different workflow, `/cook` shows a chooser before any canonical state rewrite
 
 When you accept startup or refocus, `/cook` persists the chosen workflow state in canonical `.agent/**` files before the re-ground round begins.
 
 The confirmed startup brief is also preserved there as advisory intake for later re-grounding. It does not replace `.agent/plan.json` or `.agent/active-slice.json`, which remain under regrounder authority.
 
+The pre-`/cook` handoff capsule itself is not canonical workflow state. It is only startup intake for `/cook`.
+
 ## Observability
 
 When canonical `.agent/**` state exists and no role is actively running, the extension shows a completion widget sourced from that state. The widget summarizes:

package/extensions/completion/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

@@ -16,7 +16,9 @@ import {
 import {
 	assessMissionAnchor,
 	collectRecentDiscussionEntries,
+	collectRecentSessionMessages,
 	deriveCookContextProposalFromRecentDiscussion,
+	assessLatestCookHandoffProposal,
 	finalizeContextProposalAnalysis,
 	isWeakMissionAnchor,
 	missionAnchorsLikelyEquivalent,
@@ -120,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 {
@@ -269,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 ?? [],
@@ -363,8 +377,12 @@ async function promptContextProposalConfirmationAction(
 async function deriveCookContextProposal(
 	ctx: { cwd: string; hasUI: boolean; ui: any; sessionManager: any; model?: any; modelRegistry?: any },
 	projectName: string,
-): Promise<ContextProposal | undefined> {
-	const recentEntries = collectRecentDiscussionEntries(ctx, { isRecord, asString, isStaleContextError });
+): Promise<CookContextProposalResult> {
+	const recentMessages = collectRecentSessionMessages(ctx, { isRecord, asString, asNumber, isStaleContextError });
+	const recentEntries = recentMessages
+		.filter((entry) => (entry.role === "user" || entry.role === "custom") && !entry.isCommand)
+		.slice(0, 8)
+		.map((entry) => ({ role: entry.role, text: entry.text }));
 	const snapshot = await loadCompletionSnapshot(getCtxCwd(ctx));
 	const workflowContextLines = snapshot
 		? [
@@ -378,41 +396,56 @@ async function deriveCookContextProposal(
 			`verification summary: ${asString(snapshot.verificationEvidence?.summary) ?? "(none)"}`,
 		]
 		: [];
-	return await deriveCookContextProposalFromRecentDiscussion(projectName, recentEntries, {
+	const explicitHandoff = assessLatestCookHandoffProposal(recentMessages, projectName, {
 		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,
+		normalizeMissionAnchorText,
 		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

@@ -10,7 +10,7 @@ import type {
 
 export type AdvisoryStartupBrief = {
 	kind: "startup_brief";
-	source: "recent_discussion";
+	source: "recent_discussion" | "primary_agent_handoff";
 	confirmed: true;
 	captured_at: string;
 	goal_text: string;
@@ -31,7 +31,12 @@ 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.",
-		"When handing off, explain that /cook will derive a startup brief from recent discussion and ask for confirmation before workflow start.",
+		"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.",
+		"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(" ");
 }
@@ -84,13 +89,13 @@ function buildAdvisoryStartupBriefNotes(analysis: ContextProposalAnalysis): stri
 }
 
 export function buildAdvisoryStartupBrief(args: {
-	proposal: Pick<ContextProposal, "goalText" | "mission" | "scope" | "constraints" | "acceptance">;
+	proposal: Pick<ContextProposal, "goalText" | "mission" | "scope" | "constraints" | "acceptance" | "source">;
 	analysis: ContextProposalAnalysis;
 	capturedAt?: string;
 }): AdvisoryStartupBrief {
 	return {
 		kind: "startup_brief",
-		source: "recent_discussion",
+		source: args.proposal.source === "handoff_capsule" ? "primary_agent_handoff" : "recent_discussion",
 		confirmed: true,
 		captured_at: args.capturedAt ?? new Date().toISOString(),
 		goal_text: args.proposal.goalText,