@linimin/pi-letscook 0.1.66 → 0.1.68

package/extensions/completion/proposal.ts

@@ -60,11 +60,11 @@ export type CookHandoffCapsule = {
 	risks: string[];
 	notes: string[];
 	handoff_kind: "implementation_workflow_handoff";
-	first_slice_goal: string;
+	first_slice_goal?: string;
 	first_slice_non_goals: string[];
 	implementation_surfaces: string[];
 	verification_commands: string[];
-	why_this_slice_first: string;
+	why_this_slice_first?: string;
 	task_type?: string;
 	evaluation_profile?: string;
 	why_cook_now?: string;
@@ -1279,7 +1279,7 @@ function parseCookHandoffCapsulesFromText(
 		const mission = deps.asString(parsed.mission);
 		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;
+		if (!mission) continue;
 		const scope = deps.asStringArray(parsed.scope);
 		const constraints = deps.asStringArray(parsed.constraints);
 		const nonGoals = deps.asStringArray(parsed.non_goals ?? parsed.nonGoals);
@@ -1325,12 +1325,12 @@ function buildCookHandoffBasisPreview(capsule: CookHandoffCapsule): string {
 		...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.first_slice_goal) parts.push(`first_slice_goal: ${capsule.first_slice_goal}`);
+	parts.push(...capsule.first_slice_non_goals.map((item) => `first_slice_non_goals: ${item}`));
+	parts.push(...capsule.implementation_surfaces.map((item) => `implementation_surfaces: ${item}`));
+	parts.push(...capsule.verification_commands.map((item) => `verification_commands: ${item}`));
+	if (capsule.why_this_slice_first) parts.push(`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();
 }
@@ -1363,23 +1363,32 @@ function cookHandoffStartabilityFailures(
 	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.first_slice_goal) {
+		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 useful sequencing hint");
+		} 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 sequencing hint");
+		}
 	}
-	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 buildNonStartableCookHandoffMessage(
+	failures: string[],
+	context: "explicit_preview" | "same_entry_synthesis" = "explicit_preview",
+): string {
+	return context === "same_entry_synthesis"
+		? [
+			"/cook failed closed because the same-entry primary-agent startup-plan synthesis step returned a startup plan that is still not concrete enough to seed workflow planning yet.",
+			"Clarify the mission, scope, acceptance, or verification intent in the main chat, then rerun /cook so the primary agent can synthesize a tighter startup plan.",
+			`Blocking details: ${failures.join("; ")}.`,
+		].join(" ")
+		: [
+			"/cook failed closed because a fresh explicit primary-agent startup plan exists, but it is not concrete enough to seed workflow planning yet.",
+			"Tighten the startup plan in the main chat so it captures a concrete mission, repo-change-oriented acceptance, and truthful verification intent, then rerun /cook.",
+			`Blocking details: ${failures.join("; ")}.`,
+		].join(" ");
 }
 
 function isStartableCookHandoffCapsule(
@@ -1435,11 +1444,11 @@ function buildContextProposalFromCookHandoffCapsule(
 				evaluationProfile: capsule.evaluation_profile,
 				critique: [
 					...capsule.notes,
-					`First slice goal: ${capsule.first_slice_goal}`,
+					...(capsule.first_slice_goal ? [`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_this_slice_first ? [`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,
@@ -1455,11 +1464,11 @@ function buildContextProposalFromCookHandoffCapsule(
 				...capsule.scope,
 				...constraints,
 				...capsule.acceptance,
-				capsule.first_slice_goal,
+				...(capsule.first_slice_goal ? [capsule.first_slice_goal] : []),
 				...capsule.first_slice_non_goals,
 				...capsule.implementation_surfaces,
 				...capsule.verification_commands,
-				capsule.why_this_slice_first,
+				...(capsule.why_this_slice_first ? [capsule.why_this_slice_first] : []),
 			],
 		),
 		goalText,
@@ -1470,6 +1479,32 @@ function buildContextProposalFromCookHandoffCapsule(
 	return finalizeContextProposal(proposal, projectName, deps);
 }
 
+export function assessCookHandoffText(
+	text: string,
+	projectName: string,
+	deps: ProposalParseDeps,
+	options?: {
+		messageId?: string;
+		timestampMs?: number;
+		context?: "explicit_preview" | "same_entry_synthesis";
+	},
+): CookHandoffProposalAssessment {
+	const capsules = parseCookHandoffCapsulesFromText(text, options?.messageId, options?.timestampMs, deps);
+	for (let capsuleIndex = capsules.length - 1; capsuleIndex >= 0; capsuleIndex -= 1) {
+		const capsule = capsules[capsuleIndex];
+		const failures = cookHandoffStartabilityFailures(capsule, deps);
+		if (failures.length > 0) {
+			return {
+				status: "fresh_but_not_startable",
+				message: buildNonStartableCookHandoffMessage(failures, options?.context ?? "explicit_preview"),
+			};
+		}
+		const proposal = buildContextProposalFromCookHandoffCapsule(capsule, projectName, deps);
+		if (proposal) return { status: "startable", proposal };
+	}
+	return { status: "none" };
+}
+
 export function assessLatestCookHandoffProposal(
 	recentMessages: RecentSessionMessage[],
 	projectName: string,
@@ -1489,7 +1524,7 @@ export function assessLatestCookHandoffProposal(
 			if (failures.length > 0) {
 				return {
 					status: "fresh_but_not_startable",
-					message: buildNonStartableCookHandoffMessage(failures),
+					message: buildNonStartableCookHandoffMessage(failures, "explicit_preview"),
 				};
 			}
 			const proposal = buildContextProposalFromCookHandoffCapsule(capsule, projectName, deps);

package/extensions/completion/role-runner.ts

@@ -97,14 +97,18 @@ const STARTUP_ANALYST_ROLE = "cook-proposal-analyst";
 const ANALYST_HEARTBEAT_MS = 5_000;
 
 const PRIMARY_AGENT_HANDOFF_SYSTEM_PROMPT = [
-	"You are the primary agent preparing an explicit /cook handoff after the user already chose workflow mode.",
-	"Return either exactly one fenced ```cook_handoff JSON block or one brief plain sentence explaining why no concrete handoff can be prepared.",
-	"If you can prepare a handoff, the JSON must use kind cook_handoff, source primary_agent, and handoff_kind implementation_workflow_handoff.",
-	"When the user has clearly accepted a concrete assistant-proposed slice, carry that slice forward into the handoff instead of broadening or re-guessing the mission.",
-	"Do not make /cook infer or rediscover the mission from recent discussion later; author the handoff now from the primary-agent view of the task.",
+	"You are the primary agent preparing an explicit /cook startup plan after the user already chose workflow mode.",
+	"Return either exactly one fenced ```cook_handoff JSON block or one brief plain sentence explaining why no concrete startup plan can be prepared.",
+	"If you can prepare a plan, the JSON must use kind cook_handoff, source primary_agent, and handoff_kind implementation_workflow_handoff.",
+	"Author the approved workflow startup plan now from the primary-agent view of the task so /cook can persist it under .agent before completion-regrounder derives canonical slices.",
+	"Capture the agreed mission, scope, constraints or non_goals, acceptance, risks, notes, and any concrete planning hints that will help completion-regrounder split slices later.",
+	"If a bounded first slice, likely implementation surfaces, or likely verification commands are already obvious, include first_slice_goal, first_slice_non_goals, implementation_surfaces, verification_commands, and why_this_slice_first as optional hints only. They are not required when the overall startup plan is already concrete enough to begin workflow planning.",
+	"Prefer the latest user-authored task context plus canonical workflow context over older assistant-authored previews or stale planning text.",
+	"Do not directly reuse an old preview capsule as-is; either synthesize a fresh startup plan from the current task context or return a brief plain sentence saying no concrete startup plan should replace canonical state yet.",
+	"If canonical workflow context already exists and the latest discussion does not clearly ask to replace the mission or start the next round, return a brief plain sentence instead of inventing a replacement startup plan.",
+	"Do not make /cook infer or rediscover the mission later; author the startup plan now from the primary-agent view of the task.",
 	"Do not emit markdown commentary before or after the capsule.",
-	"If the task is not concrete enough for implementation workflow, do not invent the slice.",
-	"A valid implementation-ready handoff must include mission, scope, constraints or non_goals, acceptance, risks, notes, first_slice_goal, first_slice_non_goals, implementation_surfaces, verification_commands, and why_this_slice_first.",
+	"If the task is not concrete enough for workflow startup, do not invent missing detail.",
 ].join(" ");
 const PRIMARY_AGENT_HANDOFF_ROLE = "cook-primary-agent-handoff";
 
@@ -342,7 +346,8 @@ function buildPrimaryAgentHandoffPrompt(projectName: string, recentEntries: Rece
 	lines.push(
 		"",
 		"Task:",
-		"The user explicitly invoked /cook. Prepare the primary-agent handoff that /cook should consume immediately for Start/Cancel confirmation.",
+		"The user explicitly invoked /cook. Prepare the primary-agent startup plan that /cook should synthesize immediately for Start/Cancel confirmation, persistence under .agent, and later slice derivation by completion-regrounder.",
+		"If the latest discussion does not justify a concrete new startup plan, return a brief plain sentence instead of speculative JSON.",
 	);
 	return lines.join("\n");
 }
@@ -359,7 +364,7 @@ async function runPrimaryAgentHandoffSubprocess(params: GenerateCookHandoffWithA
 	const invocation = getPiInvocation(args);
 	const liveActivity = createLiveRoleActivity(PRIMARY_AGENT_HANDOFF_ROLE);
 	liveActivity.progress = "Preparing primary-agent /cook handoff";
-	liveActivity.currentAction = "Authoring explicit startup handoff from current task context";
+	liveActivity.currentAction = "Authoring explicit startup plan from current task context";
 	liveActivity.assistantSummary = liveActivity.progress;
 	try {
 		const output = await new Promise<string | undefined>((resolve) => {
@@ -409,7 +414,7 @@ export async function generateCookHandoffWithAgent(params: GenerateCookHandoffWi
 	try {
 		return await runPrimaryAgentHandoffSubprocess(params);
 	} catch (error) {
-		console.warn("[completion] primary-agent handoff generation failed", error);
+		console.warn("[completion] primary-agent startup-plan generation failed", error);
 		return undefined;
 	}
 }

package/extensions/completion/state-store.ts

@@ -3,6 +3,7 @@ import { spawnSync } from "node:child_process";
 import { promises as fsp } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { buildApprovedStartupPlanMarkdown } from "./prompt-surfaces";
 import type { CompletionStateSnapshot, JsonRecord } from "./types";
 
 const PROTOCOL_ID = "completion";
@@ -45,6 +46,8 @@ export function resolveFiles(root: string) {
 		statePath: path.join(agentDir, "state.json"),
 		planPath: path.join(agentDir, "plan.json"),
 		activePath: path.join(agentDir, "active-slice.json"),
+		startupPlanPath: path.join(agentDir, "startup-plan.json"),
+		startupPlanMarkdownPath: path.join(agentDir, "startup-plan.md"),
 		sliceHistoryPath: path.join(agentDir, "slice-history.jsonl"),
 		stopHistoryPath: path.join(agentDir, "stop-check-history.jsonl"),
 		verificationEvidencePath: path.join(agentDir, "verification-evidence.json"),
@@ -141,6 +144,7 @@ export async function loadCompletionSnapshot(startCwd: string): Promise<Completi
 	const state = await readJson(files.statePath);
 	const plan = await readJson(files.planPath);
 	const active = await readJson(files.activePath);
+	const startupPlan = await readJson(files.startupPlanPath);
 	const verificationEvidence = await readJson(files.verificationEvidencePath);
 	return {
 		files,
@@ -148,6 +152,7 @@ export async function loadCompletionSnapshot(startCwd: string): Promise<Completi
 		state,
 		plan,
 		active,
+		startupPlan,
 		verificationEvidence,
 		activeSlice: findActiveSlice(plan, active),
 	};
@@ -275,6 +280,32 @@ export function defaultPlan(
 	};
 }
 
+export function defaultStartupPlan(
+	missionAnchor: string,
+	routing?: { taskType?: string; evaluationProfile?: string },
+	approvedStartupPlan?: JsonRecord,
+): JsonRecord {
+	return approvedStartupPlan ?? {
+		schema_version: 1,
+		artifact_type: "completion-startup-plan",
+		status: "approved",
+		source: "recent_discussion",
+		captured_at: null,
+		mission_anchor: missionAnchor,
+		goal_text: `Mission: ${missionAnchor}`,
+		task_type: routing?.taskType ?? DEFAULT_TASK_TYPE,
+		evaluation_profile: routing?.evaluationProfile ?? DEFAULT_EVALUATION_PROFILE,
+		scope: [],
+		constraints: [],
+		acceptance: [],
+		risks: [],
+		notes: ["No approved startup plan has been recorded yet."],
+		planned_surfaces: [],
+		verification_intent: [],
+		sequencing_hints: [],
+	};
+}
+
 export function defaultActiveSlice(
 	missionAnchor: string,
 	routing?: { taskType?: string; evaluationProfile?: string },
@@ -321,7 +352,7 @@ export function defaultVerificationEvidence(): JsonRecord {
 }
 
 export function buildAgentReadme(projectName: string): string {
-	return `# Completion Control Plane\n\nThis repository uses the \`completion\` workflow for long-running coding tasks.\n\n## Canonical tracked contract files\n\n- \`.agent/README.md\`\n- \`.agent/mission.md\`\n- \`.agent/profile.json\`\n- \`.agent/verify_completion_stop.sh\`\n- \`.agent/verify_completion_control_plane.sh\`\n\n## Ignored canonical execution state\n\n- \`.agent/state.json\`\n- \`.agent/plan.json\`\n- \`.agent/active-slice.json\`\n- \`.agent/slice-history.jsonl\`\n- \`.agent/stop-check-history.jsonl\`\n- \`.agent/verification-evidence.json\`\n- \`.agent/*.log\`\n- \`.agent/tmp/\`\n\n\`.agent/verification-evidence.json\` is the durable canonical record of deterministic verification for the selected slice or current HEAD. Recovery, review, audit, and stop-check reminder surfaces consume it instead of temp-only artifacts or conversational summaries when it is populated.\n\nThe source of truth for long-running completion work is canonical \`.agent/**\` state plus current repo truth.\n\nProject: ${projectName}\n`;
+	return `# Completion Control Plane\n\nThis repository uses the \`completion\` workflow for long-running coding tasks.\n\n## Canonical tracked contract files\n\n- \`.agent/README.md\`\n- \`.agent/mission.md\`\n- \`.agent/profile.json\`\n- \`.agent/verify_completion_stop.sh\`\n- \`.agent/verify_completion_control_plane.sh\`\n\n## Ignored canonical execution state\n\n- \`.agent/state.json\`\n- \`.agent/startup-plan.json\`\n- \`.agent/startup-plan.md\`\n- \`.agent/plan.json\`\n- \`.agent/active-slice.json\`\n- \`.agent/slice-history.jsonl\`\n- \`.agent/stop-check-history.jsonl\`\n- \`.agent/verification-evidence.json\`\n- \`.agent/*.log\`\n- \`.agent/tmp/\`\n\n\`.agent/startup-plan.json\` plus \`.agent/startup-plan.md\` preserve the approved workflow startup plan captured at \`/cook\`. \`completion-regrounder\` consumes that plan as planning input, then derives canonical slices in \`.agent/plan.json\` from current repo truth.\n\n\`.agent/verification-evidence.json\` is the durable canonical record of deterministic verification for the selected slice or current HEAD. Recovery, review, audit, and stop-check reminder surfaces consume it instead of temp-only artifacts or conversational summaries when it is populated.\n\nThe source of truth for long-running completion work is canonical \`.agent/**\` state plus current repo truth.\n\nProject: ${projectName}\n`;
 }
 
 export function buildMission(projectName: string, missionAnchor: string): string {
@@ -424,15 +455,23 @@ function trackedDiffFiles(fromCommit, toCommit) {
 
 const profile = readJson('.agent/profile.json');
 const state = readJson('.agent/state.json');
+const startupPlan = readJson('.agent/startup-plan.json');
 const plan = readJson('.agent/plan.json');
 const active = readJson('.agent/active-slice.json');
 const evidence = readJson('.agent/verification-evidence.json');
+let startupPlanMarkdown = '';
+try {
+  startupPlanMarkdown = fs.readFileSync('.agent/startup-plan.md', 'utf8');
+} catch (error) {
+  fail('.agent/startup-plan.md must be present and readable: ' + error.message);
+}
 
 ensureTrackedContractFiles();
 
 for (const [file, record] of [
   ['.agent/profile.json', profile],
   ['.agent/state.json', state],
+  ['.agent/startup-plan.json', startupPlan],
   ['.agent/plan.json', plan],
   ['.agent/active-slice.json', active],
 ]) {
@@ -443,12 +482,38 @@ for (const [file, record] of [
 const taskType = asString(profile.task_type);
 const evaluationProfile = asString(profile.evaluation_profile);
 if (asString(state.task_type) !== taskType) fail('.agent/state.json task_type must match .agent/profile.json task_type');
+if (asString(startupPlan.task_type) !== taskType) fail('.agent/startup-plan.json task_type must match .agent/profile.json task_type');
 if (asString(plan.task_type) !== taskType) fail('.agent/plan.json task_type must match .agent/profile.json task_type');
 if (asString(active.task_type) !== taskType) fail('.agent/active-slice.json task_type must match .agent/profile.json task_type');
 if (asString(state.evaluation_profile) !== evaluationProfile) fail('.agent/state.json evaluation_profile must match .agent/profile.json evaluation_profile');
+if (asString(startupPlan.evaluation_profile) !== evaluationProfile) fail('.agent/startup-plan.json evaluation_profile must match .agent/profile.json evaluation_profile');
 if (asString(plan.evaluation_profile) !== evaluationProfile) fail('.agent/plan.json evaluation_profile must match .agent/profile.json evaluation_profile');
 if (asString(active.evaluation_profile) !== evaluationProfile) fail('.agent/active-slice.json evaluation_profile must match .agent/profile.json evaluation_profile');
 
+if (asString(startupPlan.artifact_type) !== 'completion-startup-plan') {
+  fail('.agent/startup-plan.json artifact_type must be completion-startup-plan');
+}
+if (asString(startupPlan.status) !== 'approved') {
+  fail('.agent/startup-plan.json status must be approved');
+}
+const startupPlanMissionAnchor = asString(startupPlan.mission_anchor);
+if (!startupPlanMissionAnchor) fail('.agent/startup-plan.json mission_anchor must be present');
+if (startupPlanMissionAnchor !== asString(state.mission_anchor)) fail('.agent/startup-plan.json mission_anchor must match .agent/state.json mission_anchor');
+if (startupPlanMissionAnchor !== asString(plan.mission_anchor)) fail('.agent/startup-plan.json mission_anchor must match .agent/plan.json mission_anchor');
+if (startupPlanMissionAnchor !== asString(active.mission_anchor)) fail('.agent/startup-plan.json mission_anchor must match .agent/active-slice.json mission_anchor');
+if (!asString(startupPlan.goal_text)) fail('.agent/startup-plan.json goal_text must be present');
+for (const field of ['scope', 'constraints', 'acceptance', 'risks', 'notes', 'planned_surfaces', 'verification_intent', 'sequencing_hints']) {
+  if (!Array.isArray(startupPlan[field])) fail('.agent/startup-plan.json is missing ' + field);
+}
+if (startupPlanMarkdown.trim().length === 0) fail('.agent/startup-plan.md must not be empty');
+if (startupPlanMissionAnchor && !startupPlanMarkdown.includes(startupPlanMissionAnchor)) {
+  fail('.agent/startup-plan.md must mention the startup-plan mission_anchor');
+}
+const startupPlanGoalText = asString(startupPlan.goal_text);
+if (startupPlanGoalText && !startupPlanMarkdown.includes(startupPlanGoalText)) {
+  fail('.agent/startup-plan.md must render the startup-plan goal_text');
+}
+
 if (asString(evidence.artifact_type) !== 'completion-verification-evidence') {
   fail('.agent/verification-evidence.json artifact_type must be completion-verification-evidence');
 }
@@ -595,7 +660,12 @@ export type ScaffoldResult = {
 export async function scaffoldCompletionFiles(
 	root: string,
 	missionAnchor: string,
-	options?: { analysis?: { taskType?: string; evaluationProfile?: string }; continuationReason?: string; advisoryStartupBrief?: JsonRecord },
+	options?: {
+		analysis?: { taskType?: string; evaluationProfile?: string };
+		continuationReason?: string;
+		advisoryStartupBrief?: JsonRecord;
+		approvedStartupPlan?: JsonRecord;
+	},
 ): Promise<ScaffoldResult> {
 	const files = resolveFiles(root);
 	const created: string[] = [];
@@ -605,6 +675,10 @@ export async function scaffoldCompletionFiles(
 	const projectName = path.basename(root);
 	const docsSurfaces = await detectDocsSurfaces(root);
 	const verifierCommand = await detectVerifierCommand(root);
+	const startupPlanRecord =
+		options?.approvedStartupPlan ??
+		(await readJson(files.startupPlanPath)) ??
+		defaultStartupPlan(missionAnchor, { taskType: options?.analysis?.taskType, evaluationProfile: options?.analysis?.evaluationProfile });
 	const trackedFiles: Array<{ path: string; content: string; executable?: boolean }> = [
 		{ path: path.join(files.agentDir, "README.md"), content: buildAgentReadme(projectName) },
 		{ path: path.join(files.agentDir, "mission.md"), content: buildMission(projectName, missionAnchor) },
@@ -618,6 +692,14 @@ export async function scaffoldCompletionFiles(
 			path: files.statePath,
 			content: `${JSON.stringify(defaultState(missionAnchor, { taskType: options?.analysis?.taskType, evaluationProfile: options?.analysis?.evaluationProfile, continuationReason: options?.continuationReason }, options?.advisoryStartupBrief), null, 2)}\n`,
 		},
+		{
+			path: files.startupPlanPath,
+			content: `${JSON.stringify(startupPlanRecord, null, 2)}\n`,
+		},
+		{
+			path: files.startupPlanMarkdownPath,
+			content: buildApprovedStartupPlanMarkdown(startupPlanRecord as any),
+		},
 		{ path: files.planPath, content: `${JSON.stringify(defaultPlan(missionAnchor, { taskType: options?.analysis?.taskType, evaluationProfile: options?.analysis?.evaluationProfile }), null, 2)}\n` },
 		{ path: files.activePath, content: `${JSON.stringify(defaultActiveSlice(missionAnchor, { taskType: options?.analysis?.taskType, evaluationProfile: options?.analysis?.evaluationProfile }), null, 2)}\n` },
 		{ path: files.verificationEvidencePath, content: `${JSON.stringify(defaultVerificationEvidence(), null, 2)}\n` },
@@ -639,6 +721,7 @@ export function currentTaskType(snapshot: CompletionStateSnapshot): string | und
 	return (
 		asString(snapshot.active?.task_type) ??
 		asString(snapshot.state?.task_type) ??
+		asString(snapshot.startupPlan?.task_type) ??
 		asString(snapshot.plan?.task_type) ??
 		asString(snapshot.profile?.task_type)
 	);
@@ -648,6 +731,7 @@ export function currentEvaluationProfile(snapshot: CompletionStateSnapshot): str
 	return (
 		asString(snapshot.active?.evaluation_profile) ??
 		asString(snapshot.state?.evaluation_profile) ??
+		asString(snapshot.startupPlan?.evaluation_profile) ??
 		asString(snapshot.plan?.evaluation_profile) ??
 		asString(snapshot.profile?.evaluation_profile)
 	);
@@ -656,6 +740,7 @@ export function currentEvaluationProfile(snapshot: CompletionStateSnapshot): str
 export function currentMissionAnchor(snapshot: CompletionStateSnapshot): string {
 	return (
 		asString(snapshot.state?.mission_anchor) ??
+		asString(snapshot.startupPlan?.mission_anchor) ??
 		asString(snapshot.plan?.mission_anchor) ??
 		asString(snapshot.active?.mission_anchor) ??
 		path.basename(snapshot.files.root)

package/extensions/completion/types.ts

@@ -18,6 +18,8 @@ export type CompletionFiles = {
 	statePath: string;
 	planPath: string;
 	activePath: string;
+	startupPlanPath: string;
+	startupPlanMarkdownPath: string;
 	sliceHistoryPath: string;
 	stopHistoryPath: string;
 	verificationEvidencePath: string;
@@ -30,6 +32,7 @@ export type CompletionStateSnapshot = {
 	state?: JsonRecord;
 	plan?: JsonRecord;
 	active?: JsonRecord;
+	startupPlan?: JsonRecord;
 	verificationEvidence?: JsonRecord;
 	activeSlice?: JsonRecord;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linimin/pi-letscook",
-  "version": "0.1.66",
+  "version": "0.1.68",
   "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/active-slice-contract-test.sh

@@ -137,17 +137,16 @@ NODE
 ROOT="$TMPDIR/repo"
 PROMPT="$TMPDIR/resume-prompt.txt"
 BOOTSTRAP_SESSION="$TMPDIR/session-active-slice-bootstrap.jsonl"
-BOOTSTRAP_MESSAGES="$(python3 - <<'PY'
+BOOTSTRAP_DISCUSSION=$'Prepare the active-slice contract bootstrap fixture and tell me when it is ready for /cook.'
+GENERATED_HANDOFF="$(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."
+        "Keep the fixture on the shipped same-entry synthesis startup path."
     ],
     "constraints": [
         "Use supported bare /cook startup only."
@@ -157,7 +156,7 @@ capsule = {
         "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."
+        "Active-slice fixture bootstrap must stay anchored to same-entry primary-agent startup-plan synthesis."
     ],
     "notes": [
         "This handoff exists only to scaffold canonical files before the fixture rewrites them for contract parity coverage."
@@ -179,20 +178,16 @@ capsule = {
     "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))
+print("```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```")
 PY
 )"
 mkdir -p "$ROOT"
 cd "$ROOT"
 git init -q
-write_session_messages "$BOOTSTRAP_SESSION" "$ROOT" "$BOOTSTRAP_MESSAGES"
+write_session "$BOOTSTRAP_SESSION" "$ROOT" "$BOOTSTRAP_DISCUSSION"
 
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
-PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_PRIMARY_HANDOFF_OUTPUT="$GENERATED_HANDOFF" \
 PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
 pi --session "$BOOTSTRAP_SESSION" -e "$PKG_ROOT" -p "/cook" \
   >"$TMPDIR/pi-active-slice-bootstrap.out" 2>"$TMPDIR/pi-active-slice-bootstrap.err"

package/scripts/canonical-evidence-artifact-test.sh

@@ -134,11 +134,11 @@ assertIncludes('.agent/README.md', 'durable canonical record of deterministic ve
 assertSectionIncludes('skills/completion-protocol/SKILL.md', '## Canonical Files', '- `.agent/verification-evidence.json`');
 assertSectionIncludes('skills/completion-protocol/SKILL.md', '## Canonical Inputs', '- `.agent/verification-evidence.json`');
 assertSectionIncludes('skills/completion-protocol/SKILL.md', '## Compaction And Recovery', '- `.agent/verification-evidence.json`');
-assertSectionIncludes('skills/completion-protocol/SKILL.md', '## Compaction And Recovery', '`completion-implementer` must also re-read canonical `.agent/state.json`, `.agent/plan.json`, `.agent/active-slice.json`, and `.agent/verification-evidence.json` before resuming work.');
+assertSectionIncludes('skills/completion-protocol/SKILL.md', '## Compaction And Recovery', '`completion-implementer` must also re-read canonical `.agent/state.json`, `.agent/startup-plan.json`, `.agent/plan.json`, `.agent/active-slice.json`, and `.agent/verification-evidence.json` before resuming work.');
 assertSectionIncludes('skills/completion-protocol/references/completion.md', '## Ignored Canonical Execution State', '- `.agent/verification-evidence.json`');
 assertSectionIncludes('skills/completion-protocol/references/completion.md', '## Canonical Inputs', '- `.agent/verification-evidence.json`');
 assertSectionIncludes('skills/completion-protocol/references/completion.md', '## Compaction And Recovery', '- `.agent/verification-evidence.json`');
-assertSectionIncludes('skills/completion-protocol/references/completion.md', '## Compaction And Recovery', '`completion-implementer` must also re-read canonical `.agent/state.json`, `.agent/plan.json`, `.agent/active-slice.json`, and `.agent/verification-evidence.json` before resuming work.');
+assertSectionIncludes('skills/completion-protocol/references/completion.md', '## Compaction And Recovery', '`completion-implementer` must also re-read canonical `.agent/state.json`, `.agent/startup-plan.json`, `.agent/plan.json`, `.agent/active-slice.json`, and `.agent/verification-evidence.json` before resuming work.');
 assertIncludes('extensions/completion/prompt-surfaces.ts', 'Verification evidence artifact: ${args.evidence.path} (${args.evidence.status})');
 assertIncludes('extensions/completion/prompt-surfaces.ts', 'Verification evidence summary: ${args.evidence.summary}');
 assertIncludes('extensions/completion/index.ts', 'Canonical verification evidence artifact is currently: ${evidence.path} (${evidence.status})');
@@ -182,17 +182,16 @@ bash .agent/verify_completion_control_plane.sh >/dev/null
 ROOT="$TMPDIR/repo"
 SYSTEM_REMINDER="$TMPDIR/system-reminder.txt"
 BOOTSTRAP_SESSION="$TMPDIR/session-canonical-evidence-bootstrap.jsonl"
-BOOTSTRAP_MESSAGES="$(python3 - <<'PY'
+BOOTSTRAP_DISCUSSION=$'Prepare the canonical evidence bootstrap fixture and tell me when it is ready for /cook.'
+GENERATED_HANDOFF="$(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 canonical evidence fixture bootstrap.",
     "scope": [
         "Materialize canonical completion files for the evidence artifact fixture.",
-        "Keep the verification-evidence bootstrap on the supported explicit-handoff startup path."
+        "Keep the verification-evidence bootstrap on the supported same-entry synthesis startup path."
     ],
     "constraints": [
         "Use supported bare /cook startup only."
@@ -202,7 +201,7 @@ capsule = {
         "Keep scripts/canonical-evidence-artifact-test.sh aligned with packaged bootstrap behavior."
     ],
     "risks": [
-        "Evidence-artifact bootstrap must stay anchored to the fresh explicit handoff."
+        "Evidence-artifact bootstrap must stay anchored to same-entry primary-agent startup-plan synthesis."
     ],
     "notes": [
         "This fixture exists only to scaffold canonical files before rewriting them for evidence parity coverage."
@@ -224,25 +223,21 @@ capsule = {
     "evaluation_profile": "completion-rubric-v1",
     "why_cook_now": "The fixture bootstrap is concrete enough to create canonical control-plane files."
 }
-messages = [
-    {"role": "user", "content": "Prepare the canonical evidence bootstrap fixture and tell me when it is ready for /cook."},
-    {"role": "assistant", "content": "The canonical evidence 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))
+print("```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```")
 PY
 )"
 mkdir -p "$ROOT"
 cd "$ROOT"
 git init -q
-write_session_messages "$BOOTSTRAP_SESSION" "$ROOT" "$BOOTSTRAP_MESSAGES"
+write_session "$BOOTSTRAP_SESSION" "$ROOT" "$BOOTSTRAP_DISCUSSION"
 
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
-PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_PRIMARY_HANDOFF_OUTPUT="$GENERATED_HANDOFF" \
 PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
 pi --session "$BOOTSTRAP_SESSION" -e "$PKG_ROOT" -p "/cook" \
   >"$TMPDIR/pi-canonical-evidence-bootstrap.out" 2>"$TMPDIR/pi-canonical-evidence-bootstrap.err"
 
-for file in .agent/profile.json .agent/state.json .agent/plan.json .agent/active-slice.json .agent/verification-evidence.json; do
+for file in .agent/profile.json .agent/state.json .agent/startup-plan.json .agent/startup-plan.md .agent/plan.json .agent/active-slice.json .agent/verification-evidence.json; do
   [[ -f "$file" ]] || { echo "missing canonical bootstrap file: $file" >&2; exit 1; }
 done
 
@@ -288,6 +283,36 @@ acceptance = [
     'Canonical verification evidence is recorded for the selected slice.',
     'Fail-closed verification rejects missing or stale evidence.',
 ]
+startup_plan = {
+    'schema_version': 1,
+    'artifact_type': 'completion-startup-plan',
+    'status': 'approved',
+    'source': 'deferred_primary_agent_handoff',
+    'captured_at': '2026-05-03T00:00:00Z',
+    'mission_anchor': mission,
+    'goal_text': 'Mission: Exercise canonical verification evidence parity.\n\nScope:\n- Persist canonical verification evidence for the selected slice.\n- Keep the verifier fail-closed on stale or missing evidence.\n\nAcceptance:\n- Canonical verification evidence is recorded for the selected slice.\n- Fail-closed verification rejects missing or stale evidence.',
+    'task_type': task_type,
+    'evaluation_profile': evaluation_profile,
+    'scope': [
+        'Persist canonical verification evidence for the selected slice.',
+        'Keep the verifier fail-closed on stale or missing evidence.',
+    ],
+    'constraints': [
+        'Keep the fixture scoped to canonical verification evidence parity.',
+    ],
+    'acceptance': acceptance,
+    'risks': [
+        'Stale startup-plan parity could mask canonical evidence regressions.',
+    ],
+    'notes': [
+        'Use startup-plan parity to prove the verifier reads the approved startup plan alongside other canonical state.',
+    ],
+    'planned_surfaces': implementation_surfaces,
+    'verification_intent': verification_commands,
+    'sequencing_hints': [
+        'First slice goal: Persist canonical verification evidence for the selected slice.',
+    ],
+}
 state = {
     'schema_version': 1,
     'mission_anchor': mission,
@@ -365,6 +390,21 @@ active = {
 }
 
 Path('.agent/state.json').write_text(json.dumps(state, indent=2) + '\n')
+Path('.agent/startup-plan.json').write_text(json.dumps(startup_plan, indent=2) + '\n')
+Path('.agent/startup-plan.md').write_text(
+    '# Approved Startup Plan\n\n'
+    f'Mission anchor: {mission}\n'
+    'Source: deferred_primary_agent_handoff\n'
+    'Captured at: 2026-05-03T00:00:00Z\n'
+    f'Task type: {task_type}\n'
+    f'Evaluation profile: {evaluation_profile}\n\n'
+    '## Goal\n\n'
+    f"{startup_plan['goal_text']}\n\n"
+    '## Planned surfaces\n\n'
+    + ''.join(f'- {item}\n' for item in startup_plan['planned_surfaces'])
+    + '\n## Verification intent\n\n'
+    + ''.join(f'- {item}\n' for item in startup_plan['verification_intent'])
+)
 Path('.agent/plan.json').write_text(json.dumps(plan, indent=2) + '\n')
 Path('.agent/active-slice.json').write_text(json.dumps(active, indent=2) + '\n')
 PY