@linimin/pi-letscook 0.1.68 → 0.1.70

package/extensions/completion/role-runner.ts

@@ -11,7 +11,7 @@ import {
 	type ContextProposal,
 	type RecentDiscussionEntry,
 } from "./proposal";
-import { contextProposalAnalystProgressLines } from "./prompt-surfaces";
+import { contextProposalAnalystProgressLines, primaryAgentHandoffProgressLines } from "./prompt-surfaces";
 import {
 	applyLiveRoleEvent,
 	buildInlineRunningLines,
@@ -97,22 +97,23 @@ 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 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.",
+	"You are the primary agent preparing an explicit /cook handoff after the user already chose workflow mode.",
+	"Return either exactly one fenced ```cook_handoff JSON block or one brief plain sentence explaining why no concrete handoff can be prepared.",
+	"If you can prepare a handoff, the JSON must use kind cook_handoff, source primary_agent, and handoff_kind implementation_workflow_handoff.",
+	"When the user has clearly accepted a concrete assistant-proposed slice, carry that slice forward into the handoff instead of broadening or re-guessing the mission.",
+	"Do not make /cook infer or rediscover the mission from recent discussion later; author the handoff now from the primary-agent view of the task.",
 	"Do not emit markdown commentary before or after the capsule.",
-	"If the task is not concrete enough for workflow startup, do not invent missing detail.",
+	"If the task is not concrete enough for implementation workflow, do not invent the slice.",
+	"A valid implementation-ready handoff must include mission, scope, constraints or non_goals, acceptance, risks, notes, first_slice_goal, first_slice_non_goals, implementation_surfaces, verification_commands, and why_this_slice_first.",
 ].join(" ");
 const PRIMARY_AGENT_HANDOFF_ROLE = "cook-primary-agent-handoff";
 
-class StartupAnalystOverlay extends Container {
+type CookStartupOverlayOptions = {
+	title: string;
+	footer: string;
+};
+
+class CookStartupOverlay extends Container {
 	private readonly border: DynamicBorder;
 	private readonly title: Text;
 	private readonly body: Text;
@@ -120,7 +121,10 @@ class StartupAnalystOverlay extends Container {
 	private lines: string[] = [];
 	onAbort?: () => void;
 
-	constructor(private readonly theme: any) {
+	constructor(
+		private readonly theme: any,
+		private readonly options: CookStartupOverlayOptions,
+	) {
 		super();
 		this.border = new DynamicBorder((s: string) => this.theme.fg("accent", s));
 		this.title = new Text("", 1, 0);
@@ -140,9 +144,9 @@ class StartupAnalystOverlay extends Container {
 	}
 
 	private updateDisplay(): void {
-		this.title.setText(this.theme.fg("accent", this.theme.bold("/cook proposal analyst")));
+		this.title.setText(this.theme.fg("accent", this.theme.bold(this.options.title)));
 		this.body.setText(formatInlineRunningText(this.theme, this.lines, { primaryAssistant: true }));
-		this.footer.setText(this.theme.fg("muted", "Esc/Ctrl+C cancel • This analysis runs before /cook writes canonical workflow state"));
+		this.footer.setText(this.theme.fg("muted", this.options.footer));
 	}
 
 	override handleInput(data: string): void {
@@ -196,12 +200,15 @@ async function runContextProposalAnalystSubprocess(params: AnalyzeContextProposa
 	const args: string[] = ["--mode", "json", "-p", "--no-session", "--no-extensions", "--append-system-prompt", systemPromptTemp.filePath, "--model", modelArg, prompt];
 	const invocation = getPiInvocation(args);
 	const liveActivity = createLiveRoleActivity(STARTUP_ANALYST_ROLE);
+	liveActivity.toolActivity = undefined;
+	liveActivity.toolRecentActivity = [];
+	liveActivity.recentActivity = [];
 	liveActivity.progress = "Analyzing recent discussion";
 	liveActivity.currentAction = "Reading recent discussion and preparing a startup proposal";
 	liveActivity.assistantSummary = liveActivity.progress;
 	liveActivity.recentActivity = pushRecentActivity(liveActivity.recentActivity, `assistant: ${liveActivity.progress}`);
 	const messages: RoleMessage[] = [];
-	let overlay: StartupAnalystOverlay | undefined;
+	let overlay: CookStartupOverlay | undefined;
 	let finishOverlay: ((value: string | undefined) => void) | undefined;
 	let overlaySettled = false;
 	const settleOverlay = (value: string | undefined) => {
@@ -317,7 +324,10 @@ async function runContextProposalAnalystSubprocess(params: AnalyzeContextProposa
 		if (ui) {
 			return await ui.custom<string | undefined>((_tui, theme, _kb, done) => {
 				finishOverlay = done;
-				overlay = new StartupAnalystOverlay(theme);
+				overlay = new CookStartupOverlay(theme, {
+					title: "/cook proposal analyst",
+					footer: "Esc/Ctrl+C cancel • This analysis runs before /cook writes canonical workflow state",
+				});
 				overlay.setLines(contextProposalAnalystProgressLines(liveActivity, buildInlineRunningLines));
 				run().then(settleOverlay).catch(() => settleOverlay(undefined));
 				return overlay;
@@ -346,8 +356,7 @@ function buildPrimaryAgentHandoffPrompt(projectName: string, recentEntries: Rece
 	lines.push(
 		"",
 		"Task:",
-		"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.",
+		"The user explicitly invoked /cook. Prepare the primary-agent handoff that /cook should consume immediately for Start/Cancel confirmation.",
 	);
 	return lines.join("\n");
 }
@@ -358,52 +367,147 @@ async function runPrimaryAgentHandoffSubprocess(params: GenerateCookHandoffWithA
 	if (!modelArg) return undefined;
 	const cwd = params.getCtxCwd(ctx);
 	const runCwd = findCompletionRoot(cwd) ?? findRepoRoot(cwd) ?? cwd;
+	const rootKey = completionRootKey(undefined, cwd);
 	const prompt = buildPrimaryAgentHandoffPrompt(projectName, recentEntries, params.workflowContextLines ?? []);
 	const systemPromptTemp = await writeTempFile(runCwd, "pi-cook-primary-agent-handoff-", PRIMARY_AGENT_HANDOFF_SYSTEM_PROMPT);
 	const args: string[] = ["--mode", "json", "-p", "--no-session", "--no-extensions", "--append-system-prompt", systemPromptTemp.filePath, "--model", modelArg, prompt];
 	const invocation = getPiInvocation(args);
 	const liveActivity = createLiveRoleActivity(PRIMARY_AGENT_HANDOFF_ROLE);
-	liveActivity.progress = "Preparing primary-agent /cook handoff";
-	liveActivity.currentAction = "Authoring explicit startup plan from current task context";
-	liveActivity.assistantSummary = liveActivity.progress;
-	try {
-		const output = await new Promise<string | undefined>((resolve) => {
-			const proc = spawn(invocation.command, invocation.args, {
-				cwd: runCwd,
-				env: process.env,
-				stdio: ["ignore", "pipe", "pipe"],
-				shell: false,
-			});
-			let buffer = "";
-			const messages: RoleMessage[] = [];
-			const processLine = (line: string) => {
-				if (!line.trim()) return;
-				try {
-					const event = JSON.parse(line) as JsonRecord;
-					applyLiveRoleEvent(liveActivity, event, messages);
-				} catch {
-					// ignore malformed lines
+	liveActivity.toolActivity = undefined;
+	liveActivity.toolRecentActivity = [];
+	liveActivity.recentActivity = [];
+	liveActivity.currentAction = "Reading current task context";
+	liveActivity.rationale = "Loading canonical workflow context";
+	liveActivity.nextStep = "Synthesizing startup plan";
+	liveActivity.verifying = "Waiting for model response...";
+	let overlay: CookStartupOverlay | undefined;
+	let finishOverlay: ((value: string | undefined) => void) | undefined;
+	let overlaySettled = false;
+	const settleOverlay = (value: string | undefined) => {
+		if (overlaySettled) return;
+		overlaySettled = true;
+		finishOverlay?.(value);
+	};
+	const updateActivity = (fresh = false) => {
+		if (fresh) liveActivity.updatedAt = nowMs();
+		params.liveRoleActivityByRoot.set(rootKey, cloneLiveRoleActivity(liveActivity, { status: "running" }));
+		void refreshCompletionStatus({
+			ctx,
+			liveRoleActivityByRoot: params.liveRoleActivityByRoot,
+			completionStatusKey: params.completionStatusKey,
+			safeUiCall: params.safeUiCall,
+			getCtxCwd: params.getCtxCwd,
+			getCtxHasUI: params.getCtxHasUI,
+			getCtxUi: params.getCtxUi,
+		});
+		overlay?.setLines(primaryAgentHandoffProgressLines(liveActivity, buildInlineRunningLines));
+	};
+	const heartbeat = setInterval(() => updateActivity(false), ANALYST_HEARTBEAT_MS);
+	const run = async (): Promise<string | undefined> => {
+		try {
+			updateActivity(true);
+			const output = await new Promise<string | undefined>((resolve) => {
+				const proc = spawn(invocation.command, invocation.args, {
+					cwd: runCwd,
+					env: process.env,
+					stdio: ["ignore", "pipe", "pipe"],
+					shell: false,
+				});
+				let settled = false;
+				const resolveOnce = (value: string | undefined) => {
+					if (settled) return;
+					settled = true;
+					resolve(value);
+				};
+				const abort = () => {
+					proc.kill("SIGTERM");
+					resolveOnce(undefined);
+				};
+				const handleSigint = () => abort();
+				let buffer = "";
+				const messages: RoleMessage[] = [];
+				const processLine = (line: string) => {
+					if (!line.trim()) return;
+					try {
+						const event = JSON.parse(line) as JsonRecord;
+						if (applyLiveRoleEvent(liveActivity, event, messages)) updateActivity(true);
+					} catch {
+						// ignore malformed lines
+					}
+				};
+				proc.stdout.on("data", (chunk) => {
+					buffer += chunk.toString();
+					const lines = buffer.split("\n");
+					buffer = lines.pop() ?? "";
+					for (const line of lines) processLine(line);
+				});
+				proc.stderr.on("data", (_chunk) => {
+					// ignore handoff stderr unless the subprocess exits without assistant output
+				});
+				proc.on("close", (code) => {
+					process.off("SIGINT", handleSigint);
+					if (buffer.trim()) processLine(buffer);
+					resolveOnce(code === 0 ? liveActivity.lastAssistantText?.trim() || undefined : undefined);
+				});
+				proc.on("error", () => {
+					process.off("SIGINT", handleSigint);
+					resolveOnce(undefined);
+				});
+				process.once("SIGINT", handleSigint);
+				if (overlay) {
+					overlay.onAbort = () => {
+						process.off("SIGINT", handleSigint);
+						abort();
+					};
 				}
-			};
-			proc.stdout.on("data", (chunk) => {
-				buffer += chunk.toString();
-				const lines = buffer.split("\n");
-				buffer = lines.pop() ?? "";
-				for (const line of lines) processLine(line);
 			});
-			proc.stderr.on("data", () => {
-				// ignore stderr unless no assistant output arrives
+			params.liveRoleActivityByRoot.set(rootKey, cloneLiveRoleActivity(liveActivity, { status: output ? "ok" : "error" }));
+			await refreshCompletionStatus({
+				ctx,
+				liveRoleActivityByRoot: params.liveRoleActivityByRoot,
+				completionStatusKey: params.completionStatusKey,
+				safeUiCall: params.safeUiCall,
+				getCtxCwd: params.getCtxCwd,
+				getCtxHasUI: params.getCtxHasUI,
+				getCtxUi: params.getCtxUi,
 			});
-			proc.on("close", (code) => {
-				if (buffer.trim()) processLine(buffer);
-				resolve(code === 0 ? liveActivity.lastAssistantText?.trim() || undefined : undefined);
+			return output;
+		} finally {
+			clearInterval(heartbeat);
+			setTimeout(() => {
+				const current = params.liveRoleActivityByRoot.get(rootKey);
+				if (current && current.role === PRIMARY_AGENT_HANDOFF_ROLE && current.status !== "running") {
+					params.liveRoleActivityByRoot.delete(rootKey);
+					void refreshCompletionStatus({
+						ctx,
+						liveRoleActivityByRoot: params.liveRoleActivityByRoot,
+						completionStatusKey: params.completionStatusKey,
+						safeUiCall: params.safeUiCall,
+						getCtxCwd: params.getCtxCwd,
+						getCtxHasUI: params.getCtxHasUI,
+						getCtxUi: params.getCtxUi,
+					});
+				}
+			}, 10_000);
+			await fsp.rm(systemPromptTemp.dir, { recursive: true, force: true });
+		}
+	};
+	if (params.getCtxHasUI(ctx)) {
+		const ui = params.getCtxUi(ctx);
+		if (ui) {
+			return await ui.custom<string | undefined>((_tui, theme, _kb, done) => {
+				finishOverlay = done;
+				overlay = new CookStartupOverlay(theme, {
+					title: "/cook startup plan",
+					footer: "Esc/Ctrl+C cancel • This startup-plan synthesis runs before /cook writes canonical workflow state",
+				});
+				overlay.setLines(primaryAgentHandoffProgressLines(liveActivity, buildInlineRunningLines));
+				run().then(settleOverlay).catch(() => settleOverlay(undefined));
+				return overlay;
 			});
-			proc.on("error", () => resolve(undefined));
-		});
-		return output;
-	} finally {
-		await fsp.rm(systemPromptTemp.dir, { recursive: true, force: true });
+		}
 	}
+	return await run();
 }
 
 export async function generateCookHandoffWithAgent(params: GenerateCookHandoffWithAgentParams): Promise<string | undefined> {
@@ -414,7 +518,7 @@ export async function generateCookHandoffWithAgent(params: GenerateCookHandoffWi
 	try {
 		return await runPrimaryAgentHandoffSubprocess(params);
 	} catch (error) {
-		console.warn("[completion] primary-agent startup-plan generation failed", error);
+		console.warn("[completion] primary-agent handoff generation failed", error);
 		return undefined;
 	}
 }

package/extensions/completion/state-store.ts

@@ -3,7 +3,6 @@ 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";
@@ -46,10 +45,9 @@ 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"),
+		startupBriefPath: path.join(agentDir, "startup-brief.json"),
 		verificationEvidencePath: path.join(agentDir, "verification-evidence.json"),
 		compactionMarkerPath: path.join(tmpDir, "post-compaction-recovery.json"),
 	};
@@ -144,7 +142,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 startupBrief = await readJson(files.startupBriefPath);
 	const verificationEvidence = await readJson(files.verificationEvidencePath);
 	return {
 		files,
@@ -152,7 +150,7 @@ export async function loadCompletionSnapshot(startCwd: string): Promise<Completi
 		state,
 		plan,
 		active,
-		startupPlan,
+		startupBrief,
 		verificationEvidence,
 		activeSlice: findActiveSlice(plan, active),
 	};
@@ -233,15 +231,25 @@ export function buildProfileRecord(args: {
 	};
 }
 
+function buildWorkflowSessionId(): string {
+	return `wf-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
 export function defaultState(
 	missionAnchor: string,
 	routing?: { taskType?: string; evaluationProfile?: string; continuationReason?: string },
 	advisoryStartupBrief?: JsonRecord,
 ): JsonRecord {
+	const confirmedAt = asString(advisoryStartupBrief?.captured_at) ?? new Date().toISOString();
 	return {
 		schema_version: 1,
 		mission_anchor: missionAnchor,
 		advisory_startup_brief: advisoryStartupBrief ?? null,
+		workflow_entry_status: "active",
+		workflow_entry_source: "/cook",
+		workflow_entry_confirmed_at: confirmedAt,
+		workflow_session_id: buildWorkflowSessionId(),
+		startup_brief_path: ".agent/startup-brief.json",
 		current_phase: "reground",
 		continuation_policy: "continue",
 		continuation_reason: routing?.continuationReason ?? "Fresh completion bootstrap requires canonical re-ground",
@@ -280,32 +288,6 @@ 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 },
@@ -334,6 +316,32 @@ export function defaultActiveSlice(
 	};
 }
 
+export function defaultStartupBrief(
+	missionAnchor: string,
+	routing?: { taskType?: string; evaluationProfile?: string },
+	advisoryStartupBrief?: JsonRecord,
+): JsonRecord {
+	return {
+		schema_version: 1,
+		artifact_type: "completion-startup-brief",
+		source: asString(advisoryStartupBrief?.source) ?? "primary_agent",
+		confirmed: true,
+		confirmed_at: asString(advisoryStartupBrief?.captured_at) ?? new Date().toISOString(),
+		mission: asString(advisoryStartupBrief?.mission) ?? missionAnchor,
+		goal_text: asString(advisoryStartupBrief?.goal_text) ?? `Mission: ${missionAnchor}`,
+		scope: asStringArray(advisoryStartupBrief?.scope),
+		constraints: asStringArray(advisoryStartupBrief?.constraints),
+		acceptance: asStringArray(advisoryStartupBrief?.acceptance),
+		risks: asStringArray(advisoryStartupBrief?.risks),
+		notes:
+			asStringArray(advisoryStartupBrief?.notes).length > 0
+				? asStringArray(advisoryStartupBrief?.notes)
+				: ["No additional startup notes were preserved for this workflow entry."],
+		task_type: asString(advisoryStartupBrief?.task_type) ?? routing?.taskType ?? DEFAULT_TASK_TYPE,
+		evaluation_profile: asString(advisoryStartupBrief?.evaluation_profile) ?? routing?.evaluationProfile ?? DEFAULT_EVALUATION_PROFILE,
+	};
+}
+
 export function defaultVerificationEvidence(): JsonRecord {
 	return {
 		schema_version: 1,
@@ -352,7 +360,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/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`;
+	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-brief.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/startup-brief.json\` preserves the confirmed \`/cook\` startup intent as canonical intake for re-grounding. It does not replace \`.agent/plan.json\` or \`.agent/active-slice.json\`, which remain under regrounder authority.\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 {
@@ -455,23 +463,15 @@ 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],
 ]) {
@@ -482,38 +482,12 @@ 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');
 }
@@ -660,12 +634,7 @@ export type ScaffoldResult = {
 export async function scaffoldCompletionFiles(
 	root: string,
 	missionAnchor: string,
-	options?: {
-		analysis?: { taskType?: string; evaluationProfile?: string };
-		continuationReason?: string;
-		advisoryStartupBrief?: JsonRecord;
-		approvedStartupPlan?: JsonRecord;
-	},
+	options?: { analysis?: { taskType?: string; evaluationProfile?: string }; continuationReason?: string; advisoryStartupBrief?: JsonRecord },
 ): Promise<ScaffoldResult> {
 	const files = resolveFiles(root);
 	const created: string[] = [];
@@ -675,10 +644,6 @@ 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) },
@@ -693,12 +658,8 @@ export async function scaffoldCompletionFiles(
 			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.startupBriefPath,
+			content: `${JSON.stringify(defaultStartupBrief(missionAnchor, { taskType: options?.analysis?.taskType, evaluationProfile: options?.analysis?.evaluationProfile }, options?.advisoryStartupBrief), null, 2)}\n`,
 		},
 		{ 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` },
@@ -721,7 +682,6 @@ 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)
 	);
@@ -731,7 +691,6 @@ 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)
 	);
@@ -740,7 +699,6 @@ 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,10 +18,9 @@ export type CompletionFiles = {
 	statePath: string;
 	planPath: string;
 	activePath: string;
-	startupPlanPath: string;
-	startupPlanMarkdownPath: string;
 	sliceHistoryPath: string;
 	stopHistoryPath: string;
+	startupBriefPath: string;
 	verificationEvidencePath: string;
 	compactionMarkerPath: string;
 };
@@ -32,7 +31,7 @@ export type CompletionStateSnapshot = {
 	state?: JsonRecord;
 	plan?: JsonRecord;
 	active?: JsonRecord;
-	startupPlan?: JsonRecord;
+	startupBrief?: JsonRecord;
 	verificationEvidence?: JsonRecord;
 	activeSlice?: JsonRecord;
 };

package/package.json

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

@@ -242,6 +242,11 @@ acceptance = [
 state = {
     'schema_version': 1,
     'mission_anchor': mission,
+    'workflow_entry_status': 'active',
+    'workflow_entry_source': '/cook',
+    'workflow_entry_confirmed_at': '2026-05-03T00:00:00Z',
+    'workflow_session_id': 'active-slice-fixture-session',
+    'startup_brief_path': '.agent/startup-brief.json',
     'current_phase': 'implement',
     'continuation_policy': 'continue',
     'continuation_reason': 'Fixture for active-slice contract regression coverage.',
@@ -316,6 +321,22 @@ active = {
 }
 
 Path('.agent/state.json').write_text(json.dumps(state, indent=2) + '\n')
+Path('.agent/startup-brief.json').write_text(json.dumps({
+    'schema_version': 1,
+    'artifact_type': 'completion-startup-brief',
+    'source': 'primary_agent',
+    'confirmed': True,
+    'confirmed_at': '2026-05-03T00:00:00Z',
+    'mission': mission,
+    'goal_text': f'Mission: {mission}',
+    'scope': ['Exercise active-slice contract parity.'],
+    'constraints': ['Keep the fixture scoped to active-slice contract coverage.'],
+    'acceptance': acceptance,
+    'risks': ['Fixture drift can hide active-slice contract regressions.'],
+    'notes': ['Fixture startup brief for active-slice contract regression coverage.'],
+    'task_type': task_type,
+    'evaluation_profile': evaluation_profile,
+}, indent=2) + '\n')
 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')
 Path('.agent/verification-evidence.json').write_text(json.dumps({