@linimin/pi-letscook 0.1.54 → 0.1.56

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";
@@ -39,9 +38,9 @@ import {
 	buildContextProposalConfirmationLayout as buildExtractedContextProposalConfirmationLayout,
 	buildContextProposalConfirmationSelectItems,
 	buildContextProposalContinuationReason as buildExtractedContextProposalContinuationReason,
+	buildCookHandoffBoundaryReminder as buildExtractedCookHandoffBoundaryReminder,
 	buildEvaluationRoleContextLines as buildExtractedEvaluationRoleContextLines,
 	buildEvaluationRoleReminderText as buildExtractedEvaluationRoleReminderText,
-	buildNaturalLanguageHandoffMetadataLines,
 	buildResumeCapsule as buildExtractedResumeCapsule,
 	buildSystemReminder as buildExtractedSystemReminder,
 	maybeWriteContextProposalConfirmationSnapshot,
@@ -76,11 +75,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 +120,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 +127,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;
@@ -196,6 +182,10 @@ function completionTestSystemReminderPath(): string | undefined {
 	return asString(process.env.PI_COMPLETION_TEST_SYSTEM_REMINDER_PATH);
 }
 
+function completionTestCookHandoffReminderPath(): string | undefined {
+	return asString(process.env.PI_COMPLETION_TEST_COOK_HANDOFF_REMINDER_PATH);
+}
+
 function maybeWriteTestSnapshot(targetPath: string | undefined, content: string): void {
 	if (!targetPath) return;
 	try {
@@ -207,26 +197,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";
@@ -258,6 +230,19 @@ function shouldInjectCompletionWorkflowContext(snapshot: CompletionStateSnapshot
 	return hasCompletionRoutingActivation(snapshot) && isCompletionDriverPromptTurn(ctx);
 }
 
+function shouldInjectCookHandoffBoundary(event: { prompt?: string }, ctx: { sessionManager?: any }): boolean {
+	if (roleFromEnv()) return false;
+	if (isCompletionDriverPromptTurn(ctx)) return false;
+	const prompt = typeof event.prompt === "string" ? event.prompt.trim() : "";
+	if (!prompt) return false;
+	if (prompt.startsWith("/")) return false;
+	return true;
+}
+
+function buildCookHandoffBoundaryReminder(): string {
+	return buildExtractedCookHandoffBoundaryReminder();
+}
+
 function buildDoneWorkflowBoundaryReminder(snapshot: CompletionStateSnapshot): string {
 	const missionAnchor = asString(snapshot.state?.mission_anchor) ?? asString(snapshot.plan?.mission_anchor) ?? "(unknown)";
 	const continuationReason = asString(snapshot.state?.continuation_reason) ?? "(unknown)";
@@ -378,7 +363,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 +378,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 +394,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 +449,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 +855,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 +885,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,
@@ -986,7 +944,7 @@ export default function completionExtension(pi: ExtensionAPI) {
 		}
 	});
 
-	pi.on("before_agent_start", async (_event, ctx) => {
+	pi.on("before_agent_start", async (event, ctx) => {
 		const loaded = await loadCompletionDataForReminder(getCtxCwd(ctx));
 		const driverPromptTurn = isCompletionDriverPromptTurn(ctx);
 		if (loaded && driverPromptTurn) {
@@ -994,28 +952,35 @@ export default function completionExtension(pi: ExtensionAPI) {
 			const fingerprint = completionContinuationFingerprint(loaded.snapshot);
 			if (fingerprint) markQueuedDriverPromptInFlight(rootKey, fingerprint);
 		}
-		if (!loaded || !shouldInjectCompletionWorkflowContext(loaded.snapshot, ctx)) return;
-		const additions = isWorkflowDone(loaded.snapshot)
-			? [buildDoneWorkflowBoundaryReminder(loaded.snapshot)]
-			: [composeSystemReminder(loaded.snapshot, loaded.sliceHistory, loaded.stopHistory)];
-		if (!isWorkflowDone(loaded.snapshot)) {
-			const markerText = await readText(loaded.snapshot.files.compactionMarkerPath);
-			let marker: JsonRecord | undefined;
-			if (markerText) {
-				try {
-					const parsed = JSON.parse(markerText);
-					marker = isRecord(parsed) ? parsed : undefined;
-				} catch {
-					marker = undefined;
+		const systemPrompt = getSystemPromptSafe(ctx);
+		if (!systemPrompt) return;
+		if (loaded && shouldInjectCompletionWorkflowContext(loaded.snapshot, ctx)) {
+			const additions = isWorkflowDone(loaded.snapshot)
+				? [buildDoneWorkflowBoundaryReminder(loaded.snapshot)]
+				: [composeSystemReminder(loaded.snapshot, loaded.sliceHistory, loaded.stopHistory)];
+			if (!isWorkflowDone(loaded.snapshot)) {
+				const markerText = await readText(loaded.snapshot.files.compactionMarkerPath);
+				let marker: JsonRecord | undefined;
+				if (markerText) {
+					try {
+						const parsed = JSON.parse(markerText);
+						marker = isRecord(parsed) ? parsed : undefined;
+					} catch {
+						marker = undefined;
+					}
 				}
+				if (marker) additions.push(buildPostCompactionDriverInstructions(loaded.snapshot, marker));
 			}
-			if (marker) additions.push(buildPostCompactionDriverInstructions(loaded.snapshot, marker));
+			maybeWriteTestSnapshot(completionTestSystemReminderPath(), additions.join("\n\n"));
+			return {
+				systemPrompt: `${systemPrompt}\n\n${additions.join("\n\n")}`,
+			};
 		}
-		maybeWriteTestSnapshot(completionTestSystemReminderPath(), additions.join("\n\n"));
-		const systemPrompt = getSystemPromptSafe(ctx);
-		if (!systemPrompt) return;
+		if (!shouldInjectCookHandoffBoundary(event, ctx)) return;
+		const handoffReminder = buildCookHandoffBoundaryReminder();
+		maybeWriteTestSnapshot(completionTestCookHandoffReminderPath(), handoffReminder);
 		return {
-			systemPrompt: `${systemPrompt}\n\n${additions.join("\n\n")}`,
+			systemPrompt: `${systemPrompt}\n\n${handoffReminder}`,
 		};
 	});