@linimin/pi-letscook 0.1.54 → 0.1.56

package/CHANGELOG.md

@@ -4,8 +4,9 @@
 
 ### 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
+- added a pre-`/cook` ordinary-chat handoff boundary so the primary agent is instructed to stop at `/cook` once a task has matured into completion-workflow scope instead of starting long-running implementation directly in ordinary chat
 
 ## 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,28 +44,31 @@ 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.
+
+If a task has clearly matured into completion-workflow scope, the primary agent should hand you off to `/cook` instead of starting long-running implementation directly in ordinary chat.
 
 Important behavior:
 - `/cook` is the canonical workflow boundary and manual entry point
 - startup, refocus, and next-round routing stay confirm-first; nothing silently starts a workflow
 - explicit slash commands other than `/cook` continue normally in the main chat
+- ordinary main-chat discussion may clarify or propose, but mature long-running implementation should be handed off to `/cook`
 
 ## Typical examples
 
@@ -77,21 +79,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 +101,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);
 		},
 	});
 }