@linimin/pi-letscook 0.1.54 → 0.1.55

package/CHANGELOG.md

@@ -4,8 +4,8 @@
 
 ### Changed
 
-- removed workflow-aware prompt interception so only explicit `/cook` or `/cook <hint>` enters the workflow; ordinary prompts now always stay on the main chat path
-- updated docs and release checks to describe explicit `/cook` entry instead of router-managed natural-language takeover
+- 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
+- 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
 
 ## 0.1.54
 

package/README.md

@@ -31,13 +31,12 @@ Then run `/reload` in Pi.
    `pi install npm:@linimin/pi-letscook`
 2. Run `/reload` in Pi.
 3. In the main chat, describe the concrete repo change you want.
-4. Run `/cook` or `/cook <hint>`.
-5. Review the proposal and choose **Start** or **Cancel**.
+4. Run `/cook`.
+5. Review the startup brief and choose **Start** or **Cancel**.
 6. Later, run `/cook` again to continue, refocus, or start the next round.
 
 ```text
 /cook
-/cook login redirect
 ```
 
 ## Common actions
@@ -45,23 +44,23 @@ Then run `/reload` in Pi.
 | If you want to... | Do this |
 |---|---|
 | Start a long-running task | Discuss the concrete repo change in the main chat, then run `/cook` |
-| Bias mission detection toward one intent | Run `/cook <hint>` |
 | Continue the current workflow | Run `/cook` |
 | Refocus or start the next round | Discuss the new concrete repo change in the main chat, then run `/cook` |
 
 ## What `/cook` expects
 
 - 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
 
-`/cook <hint>` acts as a high-priority intent hint for interpreting recent discussion, but it does not bypass fail-closed behavior or the approval-only Start/Cancel confirmation flow.
-
 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 you pass inline arguments to `/cook`, it also fails closed and tells you to move that intent into the main chat before rerunning bare `/cook`.
+
 ## Workflow entry
 
-Only explicit `/cook` or `/cook <hint>` enters the workflow. Ordinary prompts stay in the main chat and go straight to the primary agent.
+Only explicit `/cook` enters the workflow. Ordinary prompts stay in the main chat and go straight to the primary agent.
 
 Important behavior:
 - `/cook` is the canonical workflow boundary and manual entry point
@@ -77,21 +76,15 @@ I want to add login redirect handling and tests.
 /cook
 ```
 
-Bias proposal derivation toward a specific intent:
-
-```text
-/cook login redirect
-```
-
 ## What happens when you run `/cook`
 
-`/cook` supports both bare discussion-driven startup and optional inline intent hints.
+`/cook` first derives a startup brief from recent discussion, then shows the existing approval-only Start/Cancel gate.
 
 | Repo state | What you'll see |
 |---|---|
-| No workflow yet | A startup proposal built from recent main-chat discussion. You choose **Start** or **Cancel**. Weak 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 confirmation. Ambiguous discussion stays conservative. |
-| Previous workflow is `done` | A next-round proposal from recent main-chat discussion, again behind **Start** or **Cancel**. Discussion that only restates already-finished work fails closed. |
+| 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. |
 
 ## Confirmation and fail-closed behavior
 
@@ -105,6 +98,8 @@ Bias proposal derivation toward a specific intent:
 
 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.
+
 ## 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

@@ -2,7 +2,11 @@ import { promises as fsp } from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import {
+	buildMission,
 	buildProfileRecord,
+	currentEvaluationProfile,
+	currentMissionAnchor,
+	currentTaskType,
 	defaultActiveSlice,
 	defaultPlan,
 	defaultState,
@@ -12,7 +16,8 @@ import {
 	loadCompletionSnapshot,
 	writeJsonFile,
 } from "./state-store";
-import type { CompletionStateSnapshot, CookNaturalLanguageHandoff, CookTriggerWorkflowBias } from "./types";
+import { buildAdvisoryStartupBrief } from "./prompt-surfaces";
+import type { CompletionStateSnapshot } from "./types";
 
 type ContextProposalAnalysis = {
 	taskType?: string;
@@ -82,7 +87,6 @@ type DriverContinuationTracker = {
 };
 
 export type CompletionDriverDeps = {
-	bareOnlyGuidance: string;
 	structuredDiscussionFailureDetail: string;
 	mainChatRerunGuidance: string;
 	cookCommandSpec: {
@@ -104,14 +108,9 @@ export type CompletionDriverDeps = {
 		evaluationProfile: string,
 		intent?: "auto" | "continue" | "refocus",
 		missionAnchor?: string,
-		naturalLanguageHandoff?: CookNaturalLanguageHandoff,
 	) => string;
-	completionResumePrompt: (
-		taskType: string,
-		evaluationProfile: string,
-		naturalLanguageHandoff?: CookNaturalLanguageHandoff,
-	) => string;
-	deriveCookContextProposal: (ctx: DriverContext, projectName: string, hintText?: string) => Promise<ContextProposal | undefined>;
+	completionResumePrompt: (taskType: string, evaluationProfile: string) => string;
+	deriveCookContextProposal: (ctx: DriverContext, projectName: string) => Promise<ContextProposal | undefined>;
 	confirmContextProposal: (
 		ctx: { hasUI: boolean; ui: any },
 		proposal: ContextProposal,
@@ -122,7 +121,7 @@ export type CompletionDriverDeps = {
 	scaffoldCompletionFiles: (
 		root: string,
 		missionAnchor: string,
-		options?: { analysis?: ContextProposalAnalysis; continuationReason?: string },
+		options?: { analysis?: ContextProposalAnalysis; continuationReason?: string; advisoryStartupBrief?: Record<string, unknown> },
 	) => Promise<{ root: string; created: string[] }>;
 	maybeWriteActiveWorkflowRoutingSnapshot: (assessment: ActiveWorkflowProposalAssessment) => void;
 	missionAnchorsLikelyEquivalent: (left: string, right: string) => boolean;
@@ -168,33 +167,6 @@ function buildCookStructuredDiscussionFailureMessage(deps: CompletionDriverDeps,
 	return prefix ? `${prefix} ${deps.structuredDiscussionFailureDetail}` : deps.structuredDiscussionFailureDetail;
 }
 
-function currentMissionAnchor(snapshot: CompletionStateSnapshot): string {
-	return (
-		asString(snapshot.state?.mission_anchor) ??
-		asString(snapshot.plan?.mission_anchor) ??
-		asString(snapshot.active?.mission_anchor) ??
-		path.basename(snapshot.files.root)
-	);
-}
-
-function currentTaskType(snapshot: CompletionStateSnapshot): string | undefined {
-	return (
-		asString(snapshot.active?.task_type) ??
-		asString(snapshot.state?.task_type) ??
-		asString(snapshot.plan?.task_type) ??
-		asString(snapshot.profile?.task_type)
-	);
-}
-
-function currentEvaluationProfile(snapshot: CompletionStateSnapshot): string | undefined {
-	return (
-		asString(snapshot.active?.evaluation_profile) ??
-		asString(snapshot.state?.evaluation_profile) ??
-		asString(snapshot.plan?.evaluation_profile) ??
-		asString(snapshot.profile?.evaluation_profile)
-	);
-}
-
 export function completionContinuationFingerprint(snapshot: CompletionStateSnapshot): string | undefined {
 	if (asString(snapshot.state?.continuation_policy) !== "continue") return undefined;
 	const nextMandatoryRole = asString(snapshot.state?.next_mandatory_role);
@@ -330,11 +302,10 @@ async function assessActiveWorkflowProposalRouting(
 	ctx: DriverContext,
 	snapshot: CompletionStateSnapshot,
 	deps: CompletionDriverDeps,
-	hintText?: string,
 ): Promise<ActiveWorkflowProposalAssessment> {
 	const currentMission = currentMissionAnchor(snapshot);
 	const projectName = path.basename(snapshot.files.root);
-	const proposal = await deps.deriveCookContextProposal(ctx, projectName, hintText);
+	const proposal = await deps.deriveCookContextProposal(ctx, projectName);
 	if (!proposal) {
 		const assessment: ActiveWorkflowProposalAssessment = {
 			action: "unclear",
@@ -379,15 +350,10 @@ async function resumeActiveWorkflowFromCanonicalState(
 	ctx: { cwd: string; hasUI: boolean; ui: any },
 	snapshot: CompletionStateSnapshot,
 	deps: CompletionDriverDeps,
-	naturalLanguageHandoff?: CookNaturalLanguageHandoff,
 ): Promise<void> {
 	const mission = currentMissionAnchor(snapshot);
 	pi.setSessionName(`completion: ${mission.slice(0, 60)}`);
-	const resumePrompt = deps.completionResumePrompt(
-		currentTaskType(snapshot) ?? "(missing)",
-		currentEvaluationProfile(snapshot) ?? "(missing)",
-		naturalLanguageHandoff,
-	);
+	const resumePrompt = deps.completionResumePrompt(currentTaskType(snapshot) ?? "(missing)", currentEvaluationProfile(snapshot) ?? "(missing)");
 	const rootKey = deps.completionRootKey(snapshot, deps.getCtxCwd(ctx));
 	const fingerprint = completionContinuationFingerprint(snapshot) ?? JSON.stringify({
 		kind: "resume",
@@ -495,6 +461,7 @@ async function refocusCompletionMission(
 	rawGoal: string,
 	analysis: ContextProposalAnalysis | undefined,
 	deps: CompletionDriverDeps,
+	advisoryStartupBrief?: Record<string, unknown>,
 ): Promise<void> {
 	const requiredStopJudges = asNumber(snapshot.profile?.required_stop_judges) ?? 3;
 	const root = snapshot.files.root;
@@ -513,7 +480,7 @@ async function refocusCompletionMission(
 			taskType: routing.taskType,
 			evaluationProfile: routing.evaluationProfile,
 			continuationReason: deps.buildContextProposalContinuationReason("User refocused workflow via /cook:", rawGoal, routing),
-		}),
+		}, advisoryStartupBrief),
 		remaining_stop_judges: requiredStopJudges,
 		next_mandatory_action: "Reconcile canonical state from current repo truth for the refocused mission",
 	};
@@ -536,59 +503,11 @@ function isWorkflowDone(snapshot: CompletionStateSnapshot | undefined): boolean
 	return asString(snapshot?.state?.continuation_policy) === "done";
 }
 
-function buildMission(projectName: string, missionAnchor: string): string {
-	return `# Mission\n\nProject: ${projectName}\n\nMission anchor:\n${missionAnchor}\n\nThis file is a tracked human-readable statement of the repo's completion mission. Re-grounders may refine this file when repo truth becomes clearer, but it must stay truthful to shipped behavior and the active completion objective.\n`;
-}
-
-export type CookInvocationOrigin = "command" | "natural-language-trigger";
-
-export type RunCookEntryOptions = {
-	origin: CookInvocationOrigin;
-	hintText?: string;
-	originalInput?: string;
-	triggerText?: string;
-	preferredRoutingBias?: CookTriggerWorkflowBias;
-	clarificationCapsule?: CookNaturalLanguageHandoff["clarificationCapsule"];
-	adoptedArtifact?: CookNaturalLanguageHandoff["adoptedArtifact"];
-};
-
-function buildNaturalLanguageDerivationHint(handoff: CookNaturalLanguageHandoff | undefined): string | undefined {
-	if (!handoff) return undefined;
-	const lines: string[] = [];
-	if (handoff.hintText) lines.push(`Focus hint: ${handoff.hintText}`);
-	if (handoff.clarificationCapsule?.goal) lines.push(`Clarified goal: ${handoff.clarificationCapsule.goal}`);
-	if (handoff.clarificationCapsule?.scope?.length) lines.push(`Clarified scope: ${handoff.clarificationCapsule.scope.join(" | ")}`);
-	if (handoff.clarificationCapsule?.nonGoal?.length) lines.push(`Clarified non-goal: ${handoff.clarificationCapsule.nonGoal.join(" | ")}`);
-	if (handoff.clarificationCapsule?.doneWhen?.length) lines.push(`Clarified done-when: ${handoff.clarificationCapsule.doneWhen.join(" | ")}`);
-	if (handoff.clarificationCapsule?.selectedWorkflowBias) {
-		lines.push(`Clarified routing bias: ${handoff.clarificationCapsule.selectedWorkflowBias}`);
-	}
-	if (handoff.adoptedArtifact) {
-		lines.push(`User explicitly adopted artifact: ${handoff.adoptedArtifact.title}`);
-		if (handoff.adoptedArtifact.path) lines.push(`Adopted artifact path: ${handoff.adoptedArtifact.path}`);
-		if (handoff.adoptedArtifact.preview) lines.push(`Adopted artifact preview: ${handoff.adoptedArtifact.preview}`);
-	}
-	return lines.length > 0 ? lines.join("\n") : undefined;
-}
-
 export async function runCookEntry(
 	pi: ExtensionAPI,
 	ctx: DriverContext,
 	deps: CompletionDriverDeps,
-	options: RunCookEntryOptions,
 ): Promise<void> {
-	const naturalLanguageHandoff =
-		options.origin === "natural-language-trigger"
-			? {
-				preferredRoutingBias: options.preferredRoutingBias,
-				triggerText: options.triggerText?.trim() ? options.triggerText.trim() : options.originalInput?.trim() ? options.originalInput.trim() : undefined,
-				hintText: options.hintText?.trim() ? options.hintText.trim() : undefined,
-				clarificationCapsule: options.clarificationCapsule,
-				adoptedArtifact: options.adoptedArtifact,
-			}
-			: undefined;
-	const derivationHint = buildNaturalLanguageDerivationHint(naturalLanguageHandoff);
-	const explicitHint = [options.hintText?.trim(), derivationHint].filter((value): value is string => Boolean(value)).join("\n\n") || undefined;
 	let goal: string | undefined;
 	const cwd = deps.getCtxCwd(ctx);
 	let snapshot = await loadCompletionSnapshot(cwd);
@@ -600,13 +519,13 @@ export async function runCookEntry(
 	if (!snapshot) {
 		const root = findRepoRoot(cwd) ?? cwd;
 		const projectName = path.basename(root);
-		const proposal = await deps.deriveCookContextProposal(ctx, projectName, explicitHint);
+		const proposal = await deps.deriveCookContextProposal(ctx, projectName);
 		if (!proposal) {
 			deps.emitCommandText(ctx, buildCookStructuredDiscussionFailureMessage(deps), "info");
 			return;
 		}
 		const decision = await deps.confirmContextProposal(ctx, proposal, {
-			title: "Start a completion workflow from the recent discussion?",
+			title: "Start a completion workflow from this startup brief?",
 		});
 		if (!decision) {
 			deps.emitCommandText(ctx, buildCookCancellationMessage("Cancelled recent-discussion workflow proposal", deps), "info");
@@ -623,6 +542,7 @@ export async function runCookEntry(
 				goal ?? kickoffMissionAnchor ?? projectName,
 				startupRouting,
 			),
+			advisoryStartupBrief: buildAdvisoryStartupBrief({ proposal, analysis: decision.analysis }),
 		});
 		deps.emitCommandText(
 			ctx,
@@ -639,13 +559,13 @@ export async function runCookEntry(
 	if (!goal) {
 		if (workflowDone) {
 			const projectName = path.basename(snapshot.files.root);
-			const proposal = await deps.deriveCookContextProposal(ctx, projectName, explicitHint);
+			const proposal = await deps.deriveCookContextProposal(ctx, projectName);
 			if (!proposal) {
 				deps.emitCommandText(ctx, buildCookStructuredDiscussionFailureMessage(deps, "The previous completion workflow is already done."), "info");
 				return;
 			}
 			const decision = await deps.confirmContextProposal(ctx, proposal, {
-				title: "The previous completion workflow is done. Start the next workflow round from the recent discussion?",
+				title: "The previous completion workflow is done. Start the next workflow round from this startup brief?",
 			});
 			if (!decision) {
 				deps.emitCommandText(ctx, buildCookCancellationMessage("Cancelled next workflow round proposal", deps), "info");
@@ -654,13 +574,20 @@ export async function runCookEntry(
 			goal = decision.goalText;
 			kickoffIntent = "refocus";
 			kickoffMissionAnchor = decision.missionAnchor;
-			await refocusCompletionMission(snapshot, decision.missionAnchor, decision.goalText, decision.analysis, deps);
+			await refocusCompletionMission(
+				snapshot,
+				decision.missionAnchor,
+				decision.goalText,
+				decision.analysis,
+				deps,
+				buildAdvisoryStartupBrief({ proposal, analysis: decision.analysis }),
+			);
 			snapshot = (await loadCompletionSnapshot(snapshot.files.root)) ?? snapshot;
 			deps.emitCommandText(ctx, `Started a new completion workflow round from recent discussion: ${decision.missionAnchor}`, "info");
 		} else {
-			const assessment = await assessActiveWorkflowProposalRouting(ctx, snapshot, deps, explicitHint);
+			const assessment = await assessActiveWorkflowProposalRouting(ctx, snapshot, deps);
 			if (!assessment.proposal || assessment.action === "continue") {
-				await resumeActiveWorkflowFromCanonicalState(pi, ctx, snapshot, deps, naturalLanguageHandoff);
+				await resumeActiveWorkflowFromCanonicalState(pi, ctx, snapshot, deps);
 				return;
 			}
 			const decision = await confirmExistingWorkflowProposal(ctx, snapshot, assessment.proposal, deps, {
@@ -678,15 +605,15 @@ export async function runCookEntry(
 				return;
 			}
 			if (decision.action === "continue") {
-				await resumeActiveWorkflowFromCanonicalState(pi, ctx, snapshot, deps, naturalLanguageHandoff);
+				await resumeActiveWorkflowFromCanonicalState(pi, ctx, snapshot, deps);
 				return;
 			}
 			const selectedProposal = decision.proposal;
 			const proposalDecision = await deps.confirmContextProposal(ctx, selectedProposal, {
 				title:
 					assessment.action === "refocus"
-						? "Start the replacement workflow from recent discussion?"
-						: "Start the latest inferred workflow from recent discussion?",
+						? "Start the replacement workflow from this startup brief?"
+						: "Start the latest inferred workflow from this startup brief?",
 			});
 			if (!proposalDecision) {
 				deps.emitCommandText(ctx, buildCookCancellationMessage("Cancelled replacement workflow proposal", deps), "info");
@@ -695,7 +622,14 @@ export async function runCookEntry(
 			goal = proposalDecision.goalText;
 			kickoffIntent = "refocus";
 			kickoffMissionAnchor = proposalDecision.missionAnchor;
-			await refocusCompletionMission(snapshot, proposalDecision.missionAnchor, proposalDecision.goalText, proposalDecision.analysis, deps);
+			await refocusCompletionMission(
+				snapshot,
+				proposalDecision.missionAnchor,
+				proposalDecision.goalText,
+				proposalDecision.analysis,
+				deps,
+				buildAdvisoryStartupBrief({ proposal: selectedProposal, analysis: proposalDecision.analysis }),
+			);
 			snapshot = (await loadCompletionSnapshot(snapshot.files.root)) ?? snapshot;
 			deps.emitCommandText(ctx, `Refocused completion mission from recent discussion to: ${proposalDecision.missionAnchor}`, "info");
 		}
@@ -709,7 +643,6 @@ export async function runCookEntry(
 		currentEvaluationProfile(snapshot) ?? "(missing)",
 		kickoffIntent,
 		kickoffMissionAnchor,
-		naturalLanguageHandoff,
 	);
 	const rootKey = deps.completionRootKey(snapshot, deps.getCtxCwd(ctx));
 	const fingerprint = completionContinuationFingerprint(snapshot) ?? JSON.stringify({
@@ -727,10 +660,11 @@ export function registerCookCommand(pi: ExtensionAPI, deps: CompletionDriverDeps
 	pi.registerCommand("cook", {
 		description: deps.cookCommandSpec.description,
 		handler: async (args, ctx) => {
-			await runCookEntry(pi, ctx, deps, {
-				origin: "command",
-				hintText: args,
-			});
+			if (args.trim().length > 0) {
+				deps.emitCommandText(ctx, "/cook no longer accepts inline arguments. Discuss the concrete repo change in the main chat and rerun /cook.", "info");
+				return;
+			}
+			await runCookEntry(pi, ctx, deps);
 		},
 	});
 }

package/extensions/completion/index.ts

@@ -1,4 +1,3 @@
-import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import { promises as fsp } from "node:fs";
 import * as os from "node:os";
@@ -41,7 +40,6 @@ import {
 	buildContextProposalContinuationReason as buildExtractedContextProposalContinuationReason,
 	buildEvaluationRoleContextLines as buildExtractedEvaluationRoleContextLines,
 	buildEvaluationRoleReminderText as buildExtractedEvaluationRoleReminderText,
-	buildNaturalLanguageHandoffMetadataLines,
 	buildResumeCapsule as buildExtractedResumeCapsule,
 	buildSystemReminder as buildExtractedSystemReminder,
 	maybeWriteContextProposalConfirmationSnapshot,
@@ -76,11 +74,9 @@ import {
 	readText,
 	scaffoldCompletionFiles as scaffoldCompletionFilesOnDisk,
 } from "./state-store";
-import { parseFirstNumber, parseYesNo } from "./transcription";
 import type { TranscriptionResult } from "./transcription";
-import type { CompletionStateSnapshot, CompletionRole, CookNaturalLanguageHandoff, JsonRecord, LiveRoleActivity } from "./types";
+import type { CompletionStateSnapshot, CompletionRole, JsonRecord, LiveRoleActivity } from "./types";
 
-const PROTOCOL_ID = "completion";
 const ROLE_NAMES = [
 	"completion-bootstrapper",
 	"completion-regrounder",
@@ -123,10 +119,6 @@ function candidateSlices(plan: JsonRecord | undefined): JsonRecord[] {
 	return Array.isArray(slices) ? slices.filter(isRecord) : [];
 }
 
-type ExistingWorkflowDecision =
-	| { action: "continue"; currentMissionAnchor: string }
-	| { action: "refocus"; currentMissionAnchor: string; missionAnchor: string };
-
 type ActiveWorkflowProposalAssessment = {
 	action: "continue" | "refocus" | "unclear";
 	currentMissionAnchor: string;
@@ -134,13 +126,6 @@ type ActiveWorkflowProposalAssessment = {
 	reason: "matching_mission" | "clear_refocus" | "missing_proposal" | "ambiguous_discussion";
 };
 
-type ExistingWorkflowChooserOptions = {
-	intro?: string;
-	proposedMissionLabel?: string;
-	refocusChoiceLabel?: string;
-	comparison?: "semantic" | "strict";
-};
-
 function completionTestWorkflowActionOverride(): "continue" | "refocus" | "cancel" | undefined {
 	const raw = process.env.PI_COMPLETION_EXISTING_WORKFLOW_ACTION?.trim().toLowerCase();
 	return raw === "continue" || raw === "refocus" || raw === "cancel" ? raw : undefined;
@@ -207,26 +192,8 @@ function maybeWriteTestSnapshot(targetPath: string | undefined, content: string)
 }
 
 const COOK_MAIN_CHAT_RERUN_GUIDANCE = "Discuss changes in the main chat and rerun /cook.";
-const COOK_BARE_ONLY_GUIDANCE =
-	"/cook is the canonical workflow boundary. Discuss the concrete repo changes in the main chat, then run /cook when you want to start, continue, refocus, or begin the next workflow round.";
 const COOK_STRUCTURED_DISCUSSION_FAILURE_DETAIL =
-	"/cook failed closed because recent discussion did not produce a clear execution-ready Mission/Scope/Constraints/Acceptance proposal for concrete repo changes. Clarify the concrete repo changes in the main chat and rerun /cook.";
-
-function buildCookCancellationMessage(prefix: string): string {
-	return `${prefix}. ${COOK_MAIN_CHAT_RERUN_GUIDANCE}`;
-}
-
-function buildCookStructuredDiscussionFailureMessage(prefix?: string): string {
-	return prefix ? `${prefix} ${COOK_STRUCTURED_DISCUSSION_FAILURE_DETAIL}` : COOK_STRUCTURED_DISCUSSION_FAILURE_DETAIL;
-}
-
-function shouldDisableContextProposalAnalyst(): boolean {
-	return process.env.PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST === "1";
-}
-
-function completionTestContextProposalAnalystOutput(): string | undefined {
-	return asString(process.env.PI_COMPLETION_CONTEXT_PROPOSAL_ANALYST_OUTPUT);
-}
+	"/cook failed closed because recent discussion did not produce a clear execution-ready startup brief with Mission/Scope/Constraints/Acceptance for concrete repo changes. Clarify the concrete repo changes in the main chat and rerun /cook.";
 
 function isWorkflowDone(snapshot: CompletionStateSnapshot | undefined): boolean {
 	return asString(snapshot?.state?.continuation_policy) === "done";
@@ -378,7 +345,6 @@ async function promptContextProposalConfirmationAction(
 async function deriveCookContextProposal(
 	ctx: { cwd: string; hasUI: boolean; ui: any; sessionManager: any; model?: any; modelRegistry?: any },
 	projectName: string,
-	hintText?: string,
 ): Promise<ContextProposal | undefined> {
 	const recentEntries = collectRecentDiscussionEntries(ctx, { isRecord, asString, isStaleContextError });
 	const snapshot = await loadCompletionSnapshot(getCtxCwd(ctx));
@@ -394,11 +360,9 @@ async function deriveCookContextProposal(
 			`verification summary: ${asString(snapshot.verificationEvidence?.summary) ?? "(none)"}`,
 		]
 		: [];
-	if (hintText) workflowContextLines.push(`cook hint: ${hintText}`);
 	return await deriveCookContextProposalFromRecentDiscussion(projectName, recentEntries, {
 		asString,
 		asStringArray,
-		hintText,
 		workflowContext: snapshot
 			? {
 				currentMissionAnchor:
@@ -412,15 +376,12 @@ async function deriveCookContextProposal(
 				continuationPolicy: asString(snapshot.state?.continuation_policy),
 			}
 			: undefined,
-		analyzeContextProposal: async (entries, derivedHintText) =>
+		analyzeContextProposal: async (entries) =>
 			await analyzeContextProposalWithAgent({
 				ctx,
 				projectName,
 				recentEntries: entries,
-				workflowContextLines:
-					derivedHintText && !workflowContextLines.includes(`cook hint: ${derivedHintText}`)
-						? [...workflowContextLines, `cook hint: ${derivedHintText}`]
-						: workflowContextLines,
+				workflowContextLines,
 				liveRoleActivityByRoot,
 				completionStatusKey: COMPLETION_STATUS_KEY,
 				safeUiCall,
@@ -470,12 +431,13 @@ async function confirmContextProposal(
 async function scaffoldCompletionFiles(
 	root: string,
 	missionAnchor: string,
-	options?: { analysis?: ContextProposalAnalysis; continuationReason?: string },
+	options?: { analysis?: ContextProposalAnalysis; continuationReason?: string; advisoryStartupBrief?: JsonRecord },
 ) {
 	const routing = finalizeContextProposalAnalysis(options?.analysis, [missionAnchor]);
 	return await scaffoldCompletionFilesOnDisk(root, missionAnchor, {
 		analysis: { taskType: routing.taskType, evaluationProfile: routing.evaluationProfile },
 		continuationReason: options?.continuationReason,
+		advisoryStartupBrief: options?.advisoryStartupBrief,
 	});
 }
 
@@ -875,45 +837,24 @@ function composeResumeCapsule(snapshot: CompletionStateSnapshot, sliceHistory: J
 	});
 }
 
-async function gitHeadSha(cwd: string): Promise<string | undefined> {
-	return await new Promise((resolve) => {
-		const proc = spawn("git", ["rev-parse", "HEAD"], { cwd, stdio: ["ignore", "pipe", "ignore"] });
-		let stdout = "";
-		proc.stdout.on("data", (chunk) => {
-			stdout += chunk.toString();
-		});
-		proc.on("close", (code) => {
-			resolve(code === 0 ? asString(stdout) : undefined);
-		});
-		proc.on("error", () => resolve(undefined));
-	});
-}
-
 function completionKickoff(
 	goal: string,
 	taskType: string,
 	evaluationProfile: string,
 	intent: "auto" | "continue" | "refocus" = "auto",
 	missionAnchor?: string,
-	naturalLanguageHandoff?: CookNaturalLanguageHandoff,
 ): string {
-	const naturalLanguageHandoffBlock = buildNaturalLanguageHandoffMetadataLines(naturalLanguageHandoff).join("\n");
 	const intentBlock =
 		intent === "continue" && missionAnchor
 			? `Existing canonical mission anchor:\n${missionAnchor}\n\nWorkflow intent:\n- Continue the existing workflow.\n- Treat the new user text as supplemental direction unless canonical reconciliation proves the mission itself must change.\n\n`
 			: intent === "refocus" && missionAnchor
 				? `Updated canonical mission anchor:\n${missionAnchor}\n\nWorkflow intent:\n- The user explicitly refocused the workflow before this kickoff.\n- Re-read canonical .agent/** state and continue from the refocused mission.\n\n`
 				: "";
-	return `/skill:completion-protocol Start or continue the completion workflow for this repo.\n\nBefore acting, read:\n- ${SKILL_PATH}\n- ${REFERENCE_PATH}\n\nCanonical routing profile:\n- task_type: ${taskType}\n- evaluation_profile: ${evaluationProfile}\n\nUser goal:\n${goal}\n\n${naturalLanguageHandoffBlock}${intentBlock}Driver instructions:\n- Canonical truth is in .agent/**. Re-read .agent/state.json, .agent/plan.json, .agent/active-slice.json, and .agent/verification-evidence.json before acting when they exist.\n- If tracked completion contract files are missing or onboarding is required, invoke completion_role with role completion-bootstrapper.\n- Otherwise follow the mandatory dispatch rules from completion-protocol.\n- For selected, in-progress, committed, or done slices, treat .agent/active-slice.json as the canonical implementation contract and route to completion-regrounder if it drifts from the selected plan slice or the exact handoff is unclear.\n- Consume .agent/verification-evidence.json instead of temp-only verification summaries when it is populated.\n- Use completion_role for all completion-* role work. Do not directly implement tracked product changes yourself.\n- Continue dispatching mandatory roles while continuation_policy == continue.\n- Only stop for the user when continuation_policy is await_user_input, blocked, paused, or done.`;
+	return `/skill:completion-protocol Start or continue the completion workflow for this repo.\n\nBefore acting, read:\n- ${SKILL_PATH}\n- ${REFERENCE_PATH}\n\nCanonical routing profile:\n- task_type: ${taskType}\n- evaluation_profile: ${evaluationProfile}\n\nUser goal:\n${goal}\n\n${intentBlock}Driver instructions:\n- Canonical truth is in .agent/**. Re-read .agent/state.json, .agent/plan.json, .agent/active-slice.json, and .agent/verification-evidence.json before acting when they exist.\n- If tracked completion contract files are missing or onboarding is required, invoke completion_role with role completion-bootstrapper.\n- Otherwise follow the mandatory dispatch rules from completion-protocol.\n- For selected, in-progress, committed, or done slices, treat .agent/active-slice.json as the canonical implementation contract and route to completion-regrounder if it drifts from the selected plan slice or the exact handoff is unclear.\n- Consume .agent/verification-evidence.json instead of temp-only verification summaries when it is populated.\n- Use completion_role for all completion-* role work. Do not directly implement tracked product changes yourself.\n- Continue dispatching mandatory roles while continuation_policy == continue.\n- Only stop for the user when continuation_policy is await_user_input, blocked, paused, or done.`;
 }
 
-function completionResumePrompt(
-	taskType: string,
-	evaluationProfile: string,
-	naturalLanguageHandoff?: CookNaturalLanguageHandoff,
-): string {
-	const naturalLanguageHandoffBlock = buildNaturalLanguageHandoffMetadataLines(naturalLanguageHandoff).join("\n");
-	return `/skill:completion-protocol Resume the completion workflow from canonical state.\n\nBefore acting, read:\n- ${SKILL_PATH}\n- ${REFERENCE_PATH}\n\nCanonical routing profile:\n- task_type: ${taskType}\n- evaluation_profile: ${evaluationProfile}\n\n${naturalLanguageHandoffBlock}Resume instructions:\n- Re-read .agent/state.json, .agent/plan.json, .agent/active-slice.json, and .agent/verification-evidence.json before acting.\n- If canonical state is missing, invalid, contradictory, stale, or ambiguous, route to completion-regrounder first.\n- For selected, in-progress, committed, or done slices, treat .agent/active-slice.json as the canonical implementation contract and route to completion-regrounder if it drifts from the selected plan slice or the exact handoff is unclear.\n- Consume .agent/verification-evidence.json instead of temp-only verification summaries when it is populated.\n- Continue from next_mandatory_role and next_mandatory_action.\n- Use completion_role for all completion-* role work.\n- Continue dispatching mandatory roles while continuation_policy == continue.\n- Only stop for the user when continuation_policy is await_user_input, blocked, paused, or done.`;
+function completionResumePrompt(taskType: string, evaluationProfile: string): string {
+	return `/skill:completion-protocol Resume the completion workflow from canonical state.\n\nBefore acting, read:\n- ${SKILL_PATH}\n- ${REFERENCE_PATH}\n\nCanonical routing profile:\n- task_type: ${taskType}\n- evaluation_profile: ${evaluationProfile}\n\nResume instructions:\n- Re-read .agent/state.json, .agent/plan.json, .agent/active-slice.json, and .agent/verification-evidence.json before acting.\n- If canonical state is missing, invalid, contradictory, stale, or ambiguous, route to completion-regrounder first.\n- For selected, in-progress, committed, or done slices, treat .agent/active-slice.json as the canonical implementation contract and route to completion-regrounder if it drifts from the selected plan slice or the exact handoff is unclear.\n- Consume .agent/verification-evidence.json instead of temp-only verification summaries when it is populated.\n- Continue from next_mandatory_role and next_mandatory_action.\n- Use completion_role for all completion-* role work.\n- Continue dispatching mandatory roles while continuation_policy == continue.\n- Only stop for the user when continuation_policy is await_user_input, blocked, paused, or done.`;
 }
 
 export default function completionExtension(pi: ExtensionAPI) {
@@ -926,11 +867,10 @@ export default function completionExtension(pi: ExtensionAPI) {
 		getCtxUi,
 	};
 	const driverDeps = {
-		bareOnlyGuidance: COOK_BARE_ONLY_GUIDANCE,
 		structuredDiscussionFailureDetail: COOK_STRUCTURED_DISCUSSION_FAILURE_DETAIL,
 		mainChatRerunGuidance: COOK_MAIN_CHAT_RERUN_GUIDANCE,
 		cookCommandSpec: {
-			description: "/cook workflow: start, continue, refocus, or start the next round from an explicit /cook command",
+			description: "/cook workflow: derive a startup brief from recent discussion, then start, continue, refocus, or start the next round from the explicit /cook command",
 		},
 		buildContextProposalContinuationReason,
 		completionKickoff,