@linimin/pi-letscook 0.1.69 → 0.1.71

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.71
+
+### Changed
+
+- clarified the packaged `completion-auditor` output contract so `Stale or conflicting canonical state` must begin with `yes` or `no`, matching the canonical transcription gate
+- added rubric-contract coverage to keep the stricter auditor yes/no guidance from drifting and to reduce avoidable transcription warnings during audit
+
+## 0.1.70
+
+### Changed
+
+- added a visible `/cook startup plan` overlay while same-entry primary-agent startup synthesis is running so users no longer wait on a silent UI before Start/Cancel appears
+- reused the same cancellable overlay/heartbeat pattern for `/cook` startup subprocesses so progress updates, elapsed time, and waiting state stay visible during startup-plan synthesis
+
 ## 0.1.69
 
 ### Changed

package/agents/completion-auditor.md

@@ -52,9 +52,11 @@ Answer only:
 - `Tracked and unignored worktree is clean: yes/no`
 - `Worktree blockers: ...`
 - `Next mandatory slice: ...`
-- `Stale or conflicting canonical state: ...`
+- `Stale or conflicting canonical state: yes/no - ...`
 - `Plan truthfully captures remaining slice backlog: yes/no - ...`
 
+For every yes/no audit field, start the value with exactly `yes` or `no`. Do not substitute `none`, `clear`, `fresh`, `unknown`, or other synonyms. For example: `Stale or conflicting canonical state: no - canonical state remains aligned with the active slice and backlog.`
+
 If the tracked and unignored worktree is dirty after the latest committed slice, report that as a blocker to next-slice progression, do not recommend a new next slice, and point the workflow back to reconciliation of the latest slice.
 
 If no remaining gap is evident, say so plainly instead of inventing one.

package/extensions/completion/prompt-surfaces.ts

@@ -277,14 +277,14 @@ export function buildContextProposalAnalystPrompt(projectName: string, discussio
 	return lines.join("\n");
 }
 
-export function contextProposalAnalystProgressLines(
+function buildCookStartupProgressLines(
 	activity: LiveRoleActivity,
 	buildInlineRunningLines: (details: {
 		role?: string;
 		startedAt?: number;
 		updatedAt?: number;
 		currentAction?: string;
-		toolActivity?: string[];
+		toolActivity?: string;
 		toolRecentActivity?: string[];
 		recentActivity?: string[];
 		assistantSummary?: string;
@@ -294,6 +294,7 @@ export function contextProposalAnalystProgressLines(
 		verifying?: string;
 		stateDeltas?: string[];
 	}) => string[],
+	footerLine: string,
 ): string[] {
 	return [
 		...buildInlineRunningLines({
@@ -312,10 +313,52 @@ export function contextProposalAnalystProgressLines(
 			stateDeltas: activity.stateDeltas,
 		}),
 		"",
-		"This step only prepares a proposal for confirmation.",
+		footerLine,
 	];
 }
 
+export function contextProposalAnalystProgressLines(
+	activity: LiveRoleActivity,
+	buildInlineRunningLines: (details: {
+		role?: string;
+		startedAt?: number;
+		updatedAt?: number;
+		currentAction?: string;
+		toolActivity?: string;
+		toolRecentActivity?: string[];
+		recentActivity?: string[];
+		assistantSummary?: string;
+		progress?: string;
+		rationale?: string;
+		nextStep?: string;
+		verifying?: string;
+		stateDeltas?: string[];
+	}) => string[],
+): string[] {
+	return buildCookStartupProgressLines(activity, buildInlineRunningLines, "This step only prepares a proposal for confirmation.");
+}
+
+export function primaryAgentHandoffProgressLines(
+	activity: LiveRoleActivity,
+	buildInlineRunningLines: (details: {
+		role?: string;
+		startedAt?: number;
+		updatedAt?: number;
+		currentAction?: string;
+		toolActivity?: string;
+		toolRecentActivity?: string[];
+		recentActivity?: string[];
+		assistantSummary?: string;
+		progress?: string;
+		rationale?: string;
+		nextStep?: string;
+		verifying?: string;
+		stateDeltas?: string[];
+	}) => string[],
+): string[] {
+	return buildCookStartupProgressLines(activity, buildInlineRunningLines, "This step only synthesizes the startup plan for Start/Cancel confirmation.");
+}
+
 export function buildEvaluationRoleContextLines(
 	snapshot: CompletionStateSnapshot,
 	role: string,

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,
@@ -108,7 +108,12 @@ const PRIMARY_AGENT_HANDOFF_SYSTEM_PROMPT = [
 ].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;
@@ -116,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);
@@ -136,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 {
@@ -192,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) => {
@@ -313,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;
@@ -353,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 handoff 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> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linimin/pi-letscook",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "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/legacy-cleanup-test.sh

@@ -48,7 +48,7 @@ assertIncludes('extensions/completion/proposal.ts', 'export function serializeRe
 assertIncludes('extensions/completion/proposal.ts', 'export function extractJsonObjectFromText(');
 
 assertIncludes('extensions/completion/role-runner.ts', 'export async function analyzeContextProposalWithAgent(');
-assertIncludes('extensions/completion/role-runner.ts', 'class StartupAnalystOverlay extends Container');
+assertIncludes('extensions/completion/role-runner.ts', 'class CookStartupOverlay extends Container');
 assertIncludes('extensions/completion/role-runner.ts', 'async function runContextProposalAnalystSubprocess(');
 
 assertIncludes('extensions/completion/prompt-surfaces.ts', 'export function buildSystemReminder(');

package/scripts/role-runner-contract-test.sh

@@ -30,6 +30,8 @@ assertIncludes('extensions/completion/role-runner.ts', 'const transcription = ex
 assertIncludes('extensions/completion/role-runner.ts', 'env: { ...process.env, PI_COMPLETION_ROLE: params.role },');
 assertIncludes('extensions/completion/role-runner.ts', 'async function runContextProposalAnalystSubprocess(');
 assertIncludes('extensions/completion/role-runner.ts', 'export async function analyzeContextProposalWithAgent(');
+assertIncludes('extensions/completion/role-runner.ts', 'class CookStartupOverlay extends Container');
+assertIncludes('extensions/completion/role-runner.ts', 'overlay = new CookStartupOverlay(theme, {');
 assertIncludes('extensions/completion/index.ts', 'import { analyzeContextProposalWithAgent, generateCookHandoffWithAgent, runCompletionRole } from "./role-runner";');
 assertIncludes('extensions/completion/index.ts', 'const result = await runCompletionRole({');
 assertIncludes('extensions/completion/index.ts', 'const raw = await generateCookHandoffWithAgent({');

package/scripts/rubric-contract-test.sh

@@ -90,6 +90,8 @@ assertIncludes('extensions/completion/role-reporting.js', 'Reviewer output canno
 assertIncludes('extensions/completion/role-reporting.js', 'Auditor output must answer \'Tracked and unignored worktree is clean\' with yes or no.');
 assertIncludes('extensions/completion/role-reporting.js', 'Auditor output must answer \'Stale or conflicting canonical state\' with yes or no.');
 assertIncludes('extensions/completion/role-reporting.js', 'Auditor output must answer \'Plan truthfully captures remaining slice backlog\' with yes or no.');
+assertIncludes('agents/completion-auditor.md', '`Stale or conflicting canonical state: yes/no - ...`');
+assertIncludes('agents/completion-auditor.md', 'For every yes/no audit field, start the value with exactly `yes` or `no`.');
 assertIncludes('extensions/completion/role-reporting.js', 'Stop-judge output cannot mark \'Can the project stop now: yes\' when any rubric line is fail.');
 assertIncludes('extensions/completion/role-reporting.js', 'Stop-judge output must answer \'Docs/config/runbooks match shipped behavior\' with yes or no.');
 assertIncludes('extensions/completion/role-reporting.js', 'Stop-judge output must answer \'Tracked and unignored worktree is clean\' with yes or no.');