@linimin/pi-letscook 0.1.58 → 0.1.60

package/extensions/completion/index.ts

@@ -25,7 +25,6 @@ import {
 	missionAnchorsStrictlyEquivalent,
 	normalizeMissionAnchorText,
 	resolveContextProposalConfirmationAction,
-	shouldTreatBareActiveWorkflowProposalAsClearRefocus,
 	stripCodeBlocks,
 } from "./proposal";
 import type {
@@ -128,15 +127,14 @@ type CookContextProposalResult = {
 };
 
 type ActiveWorkflowProposalAssessment = {
-	action: "continue" | "refocus" | "unclear" | "blocked";
+	action: "continue" | "refocus" | "blocked";
 	currentMissionAnchor: string;
 	proposal?: ContextProposal;
 	blockedFailureMessage?: string;
 	reason:
 		| "matching_mission"
-		| "clear_refocus"
-		| "missing_proposal"
-		| "ambiguous_discussion"
+		| "missing_explicit_handoff"
+		| "fresh_explicit_handoff"
 		| "fresh_explicit_handoff_not_startable";
 };
 
@@ -211,7 +209,7 @@ function maybeWriteTestSnapshot(targetPath: string | undefined, content: string)
 
 const COOK_MAIN_CHAT_RERUN_GUIDANCE = "Discuss changes in the main chat and rerun /cook.";
 const COOK_STRUCTURED_DISCUSSION_FAILURE_DETAIL =
-	"/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.";
+	"/cook failed closed because recent discussion did not produce a clear execution-ready startup brief for bare /cook with Mission/Scope/Constraints/Acceptance for concrete repo changes. Clarify the concrete repo changes in the main chat and rerun /cook; canonical workflow state is still only written after Start.";
 
 function isWorkflowDone(snapshot: CompletionStateSnapshot | undefined): boolean {
 	return asString(snapshot?.state?.continuation_policy) === "done";
@@ -374,6 +372,27 @@ async function promptContextProposalConfirmationAction(
 	});
 }
 
+async function deriveCookStartupProposal(
+	ctx: { cwd: string; hasUI: boolean; ui: any; sessionManager: any; model?: any; modelRegistry?: any },
+	projectName: string,
+): Promise<CookContextProposalResult> {
+	const recentMessages = collectRecentSessionMessages(ctx, { isRecord, asString, asNumber, isStaleContextError });
+	const explicitHandoff = assessLatestCookHandoffProposal(recentMessages, projectName, {
+		asString,
+		asStringArray,
+		assessMissionAnchor,
+		normalizeMissionAnchorText,
+		isWeakMissionAnchor,
+		missionAnchorsStrictlyEquivalent,
+		stripCodeBlocks,
+	});
+	if (explicitHandoff.status === "startable") return { proposal: explicitHandoff.proposal };
+	if (explicitHandoff.status === "fresh_but_not_startable") {
+		return { blockedFailureMessage: explicitHandoff.message };
+	}
+	return {};
+}
+
 async function deriveCookContextProposal(
 	ctx: { cwd: string; hasUI: boolean; ui: any; sessionManager: any; model?: any; modelRegistry?: any },
 	projectName: string,
@@ -396,19 +415,8 @@ async function deriveCookContextProposal(
 			`verification summary: ${asString(snapshot.verificationEvidence?.summary) ?? "(none)"}`,
 		]
 		: [];
-	const explicitHandoff = assessLatestCookHandoffProposal(recentMessages, projectName, {
-		asString,
-		asStringArray,
-		assessMissionAnchor,
-		normalizeMissionAnchorText,
-		isWeakMissionAnchor,
-		missionAnchorsStrictlyEquivalent,
-		stripCodeBlocks,
-	});
-	if (explicitHandoff.status === "startable") return { proposal: explicitHandoff.proposal };
-	if (explicitHandoff.status === "fresh_but_not_startable") {
-		return { blockedFailureMessage: explicitHandoff.message };
-	}
+	const explicitHandoff = await deriveCookStartupProposal(ctx, projectName);
+	if (explicitHandoff.proposal || explicitHandoff.blockedFailureMessage) return explicitHandoff;
 	return {
 		proposal: await deriveCookContextProposalFromRecentDiscussion(projectName, recentEntries, {
 			asString,
@@ -921,7 +929,7 @@ export default function completionExtension(pi: ExtensionAPI) {
 		structuredDiscussionFailureDetail: COOK_STRUCTURED_DISCUSSION_FAILURE_DETAIL,
 		mainChatRerunGuidance: COOK_MAIN_CHAT_RERUN_GUIDANCE,
 		cookCommandSpec: {
-			description: "/cook workflow: derive a startup brief from recent discussion, then start, continue, refocus, or start the next round from the explicit /cook command",
+			description: "/cook workflow: synthesize an approval-gated startup brief from recent discussion for new-workflow or next-round entry, resume the current workflow from canonical state, or confirm an explicit active-workflow replacement",
 		},
 		buildContextProposalContinuationReason,
 		completionKickoff,
@@ -934,6 +942,7 @@ export default function completionExtension(pi: ExtensionAPI) {
 		completionTestWorkflowMissionOverride,
 		confirmContextProposal,
 		deriveCookContextProposal,
+		deriveCookStartupProposal,
 		emitCommandText,
 		finalizeContextProposalAnalysis,
 		getCtxCwd,
@@ -948,7 +957,6 @@ export default function completionExtension(pi: ExtensionAPI) {
 		scaffoldCompletionFiles,
 		shouldSkipDriverKickoffForTests,
 		shouldTestAutoContinueOnSessionStart,
-		shouldTreatBareActiveWorkflowProposalAsClearRefocus,
 	};
 
 

package/extensions/completion/prompt-surfaces.ts

@@ -27,17 +27,19 @@ export type AdvisoryStartupBrief = {
 export function buildCookHandoffBoundaryReminder(): string {
 	return [
 		"You are still in ordinary main chat before any explicit /cook workflow entry.",
-		"Use ordinary chat to clarify requirements, discuss tradeoffs, and propose implementation approaches.",
+		"Use ordinary chat to clarify requirements, discuss tradeoffs, propose implementation approaches, and refine scope with the user.",
 		"/cook is the only explicit entrypoint into long-running completion workflow.",
-		"When you judge that the task has matured into completion-workflow scope — for example the user has clearly shifted from exploration into implementation intent, you have just produced a concrete plan or proposal whose next step would naturally be implementation, or the task spans multiple files, steps, or verification surfaces — stop short of long-running implementation and tell the user to run /cook.",
-		"At that handoff point, do not begin long-running product implementation in ordinary chat, do not edit tracked product files for that workflow-level task, and do not act as though /cook had already been invoked.",
-		"Distinguish a workflow-worthy handoff from an implementation-ready handoff: only emit the implementation-ready capsule when the first bounded implementation slice is concrete enough to start immediately.",
-		"When handing off, explain that /cook will first look for a fresh explicit primary-agent handoff capsule and otherwise fall back to recent discussion.",
-		"If the task is workflow-worthy but that first slice is still vague, tell the user to run /cook without emitting an implementation-ready capsule yet.",
-		"Otherwise append one exact fenced block in the same assistant reply using ```cook_handoff ... ``` JSON with kind/source/handoff_kind plus mission, scope, constraints or non_goals, acceptance, risks, notes, captured_at, source_turn_id, first_slice_goal, first_slice_non_goals, implementation_surfaces, verification_commands, why_this_slice_first, and optional task_type/evaluation_profile/why_cook_now.",
-		"Use handoff_kind implementation_workflow_handoff for that implementation-ready capsule.",
-		"The capsule is startup intake for /cook only: do not present it as canonical .agent state, an active slice, or a persistent repo contract.",
-		"If the task is still ordinary Q&A, lightweight brainstorming, or a tiny one-off fix, continue normally without forcing /cook.",
+		"When you judge that the task has matured into completion-workflow scope — for example the user has clearly shifted from exploration into implementation intent, you have just produced a concrete plan or proposal whose next step would naturally be implementation, or the task spans multiple files, steps, or verification surfaces — do not begin long-running product implementation in ordinary chat and do not edit tracked product files for that workflow-level task.",
+		"Instead, recommend /cook as the workflow boundary while keeping the conversation in ordinary chat until the user explicitly runs /cook.",
+		"If the user keeps asking follow-up questions or refining requirements before /cook, continue that ordinary-chat discussion normally instead of switching into a handoff-only refusal mode, but do not act as though /cook had already been invoked.",
+		"Distinguish a workflow-worthy handoff from an opt-in preview request: by default, do not emit a structured preview or cook_handoff capsule in ordinary chat once the task is concrete enough; recommend bare /cook instead.",
+		"If the task is workflow-worthy but the user still wants to refine scope before /cook, keep refining in ordinary chat without acting as though workflow already started.",
+		"When handing off, explain that bare /cook will synthesize a startup brief from recent ordinary-chat discussion for a new workflow or next round, while already-active workflows resume from canonical .agent state unless the user explicitly chooses a replacement path backed by a fresh valid explicit handoff.",
+		"If the user explicitly asks for a /cook preview or capsule before running /cook, you may append one exact fenced block in the same assistant reply using ```cook_handoff ... ``` JSON with kind/source/handoff_kind plus mission, scope, constraints or non_goals, acceptance, risks, notes, captured_at, source_turn_id, first_slice_goal, first_slice_non_goals, implementation_surfaces, verification_commands, why_this_slice_first, and optional task_type/evaluation_profile/why_cook_now.",
+		"Use handoff_kind implementation_workflow_handoff for that opt-in preview capsule.",
+		"If later ordinary-chat discussion materially changes the startup brief before /cook runs, update or replace the preview capsule in a later assistant reply instead of pretending the workflow already started.",
+		"Any preview capsule is startup intake for /cook only: do not present it as canonical .agent state, an active slice, or a persistent repo contract.",
+		"If the task is still ordinary Q&A, lightweight brainstorming, or a tiny one-off fix, continue normally without forcing /cook or emitting an unsolicited preview capsule.",
 	].join(" ");
 }
 

package/extensions/completion/proposal.ts

@@ -1246,7 +1246,6 @@ export function extractContextProposalFromStructuredSession(
 
 const COOK_HANDOFF_BLOCK_REGEX = /```cook_handoff\s*([\s\S]*?)```/giu;
 const COOK_HANDOFF_MAX_AGE_MS = 45 * 60 * 1000;
-const COOK_HANDOFF_MAX_LATER_NON_COMMAND_MESSAGES = 2;
 const COOK_HANDOFF_NEGATIVE_MISSION_REGEX =
 	/(?:\b(?:do not|don't|dont|not|never|avoid|skip|refuse|recognize that|suppress|ignore|block|prevent)\b|(?:不要|別|别|勿|禁止|避免|忽略|阻止))/iu;
 const COOK_HANDOFF_WORKFLOW_ONLY_ACCEPTANCE_REGEX =
@@ -1389,19 +1388,6 @@ function isStartableCookHandoffCapsule(
 	return cookHandoffStartabilityFailures(capsule, deps).length === 0;
 }
 
-function laterMessagesInvalidateCookHandoff(
-	laterMessages: RecentSessionMessage[],
-	deps: Pick<ProposalParseDeps, "stripCodeBlocks">,
-): boolean {
-	const laterNonCommandMessages = laterMessages.filter((entry) => !entry.isCommand);
-	if (laterNonCommandMessages.length > COOK_HANDOFF_MAX_LATER_NON_COMMAND_MESSAGES) return true;
-	return laterNonCommandMessages.some((entry) => {
-		if (entry.role === "summary") return false;
-		if (!hasRecentDiscussionImplementationIntent(entry.text, deps.stripCodeBlocks)) return false;
-		return true;
-	});
-}
-
 function cookHandoffIsFreshEnough(capsule: CookHandoffCapsule, laterMessages: RecentSessionMessage[]): boolean {
 	const capturedAtMs = Date.parse(capsule.captured_at);
 	if (!Number.isFinite(capturedAtMs)) return false;
@@ -1484,7 +1470,6 @@ export function assessLatestCookHandoffProposal(
 			const capsule = capsules[capsuleIndex];
 			const laterMessages = recentMessages.slice(0, index);
 			if (!cookHandoffIsFreshEnough(capsule, laterMessages)) continue;
-			if (laterMessagesInvalidateCookHandoff(laterMessages, deps)) continue;
 			const failures = cookHandoffStartabilityFailures(capsule, deps);
 			if (failures.length > 0) {
 				return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linimin/pi-letscook",
-  "version": "0.1.58",
+  "version": "0.1.60",
   "description": "Pi package for long-running completion workflows with canonical .agent state, role-based subagents, continuity, and verification helpers.",
   "license": "MIT",
   "private": false,
@@ -22,6 +22,11 @@
     "subagent"
   ],
   "files": [
+    ".agent/README.md",
+    ".agent/mission.md",
+    ".agent/profile.json",
+    ".agent/verify_completion_stop.sh",
+    ".agent/verify_completion_control_plane.sh",
     "extensions",
     "skills",
     "agents",

package/scripts/active-slice-contract-test.sh

@@ -47,6 +47,49 @@ with session_path.open('w', encoding='utf-8') as fh:
 PY
 }
 
+write_session_messages() {
+  local session_path="$1"
+  local cwd="$2"
+  local messages_json="$3"
+  python3 - "$session_path" "$cwd" "$messages_json" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+session_path = Path(sys.argv[1])
+cwd = sys.argv[2]
+messages = json.loads(sys.argv[3])
+session_path.parent.mkdir(parents=True, exist_ok=True)
+entries = [
+    {
+        "type": "session",
+        "version": 3,
+        "id": "11111111-1111-4111-8111-111111111111",
+        "timestamp": "2026-01-01T00:00:00.000Z",
+        "cwd": cwd,
+    },
+]
+parent_id = None
+for index, message in enumerate(messages, start=1):
+    entry_id = f"m{index:04d}"
+    entries.append({
+        "type": "message",
+        "id": entry_id,
+        "parentId": parent_id,
+        "timestamp": f"2026-01-01T00:00:{index:02d}.000Z",
+        "message": {
+            "role": message["role"],
+            "content": message["content"],
+            "timestamp": 1767225600000 + index * 1000,
+        },
+    })
+    parent_id = entry_id
+with session_path.open('w', encoding='utf-8') as fh:
+    for entry in entries:
+        fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+PY
+}
+
 cd "$PKG_ROOT"
 
 node <<'NODE'
@@ -94,11 +137,59 @@ NODE
 ROOT="$TMPDIR/repo"
 PROMPT="$TMPDIR/resume-prompt.txt"
 BOOTSTRAP_SESSION="$TMPDIR/session-active-slice-bootstrap.jsonl"
-BOOTSTRAP_DISCUSSION=$'Mission: Exercise active-slice contract parity.\nScope:\n- Bootstrap canonical completion files for the active-slice contract fixture.\nConstraints:\n- Use supported bare /cook startup only.\nAcceptance:\n- Materialize canonical files before the fixture rewrites them.'
+BOOTSTRAP_MESSAGES="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Exercise active-slice contract parity.",
+    "scope": [
+        "Bootstrap canonical completion files for the active-slice contract fixture.",
+        "Keep the fixture on the shipped explicit-handoff startup path."
+    ],
+    "constraints": [
+        "Use supported bare /cook startup only."
+    ],
+    "acceptance": [
+        "Materialize .agent/profile.json, .agent/state.json, .agent/plan.json, .agent/active-slice.json, and .agent/verification-evidence.json before the fixture rewrites them.",
+        "Keep scripts/active-slice-contract-test.sh aligned with the packaged startup contract."
+    ],
+    "risks": [
+        "Active-slice fixture bootstrap must stay anchored to the fresh explicit handoff."
+    ],
+    "notes": [
+        "This handoff exists only to scaffold canonical files before the fixture rewrites them for contract parity coverage."
+    ],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Scaffold active-slice contract fixture files before rewriting them for parity verification.",
+    "first_slice_non_goals": [
+        "Do not broaden the fixture beyond active-slice contract surfaces."
+    ],
+    "implementation_surfaces": [
+        ".agent/active-slice.json",
+        "scripts/active-slice-contract-test.sh"
+    ],
+    "verification_commands": [
+        "bash scripts/active-slice-contract-test.sh"
+    ],
+    "why_this_slice_first": "The active-slice fixture cannot validate parity until canonical files exist.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "The fixture bootstrap is concrete enough to scaffold canonical control-plane files."
+}
+messages = [
+    {"role": "user", "content": "Prepare the active-slice contract bootstrap fixture and tell me when it is ready for /cook."},
+    {"role": "assistant", "content": "The active-slice contract bootstrap fixture is ready for /cook. Run /cook to confirm it.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
+]
+print(json.dumps(messages, ensure_ascii=False))
+PY
+)"
 mkdir -p "$ROOT"
 cd "$ROOT"
 git init -q
-write_session "$BOOTSTRAP_SESSION" "$ROOT" "$BOOTSTRAP_DISCUSSION"
+write_session_messages "$BOOTSTRAP_SESSION" "$ROOT" "$BOOTSTRAP_MESSAGES"
 
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
 PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \

package/scripts/canonical-evidence-artifact-test.sh

@@ -47,6 +47,49 @@ with session_path.open('w', encoding='utf-8') as fh:
 PY
 }
 
+write_session_messages() {
+  local session_path="$1"
+  local cwd="$2"
+  local messages_json="$3"
+  python3 - "$session_path" "$cwd" "$messages_json" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+session_path = Path(sys.argv[1])
+cwd = sys.argv[2]
+messages = json.loads(sys.argv[3])
+session_path.parent.mkdir(parents=True, exist_ok=True)
+entries = [
+    {
+        "type": "session",
+        "version": 3,
+        "id": "11111111-1111-4111-8111-111111111111",
+        "timestamp": "2026-01-01T00:00:00.000Z",
+        "cwd": cwd,
+    },
+]
+parent_id = None
+for index, message in enumerate(messages, start=1):
+    entry_id = f"m{index:04d}"
+    entries.append({
+        "type": "message",
+        "id": entry_id,
+        "parentId": parent_id,
+        "timestamp": f"2026-01-01T00:00:{index:02d}.000Z",
+        "message": {
+            "role": message["role"],
+            "content": message["content"],
+            "timestamp": 1767225600000 + index * 1000,
+        },
+    })
+    parent_id = entry_id
+with session_path.open('w', encoding='utf-8') as fh:
+    for entry in entries:
+        fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+PY
+}
+
 cleanup() {
   if [[ -n "$CURRENT_EVIDENCE_BACKUP" && -f "$CURRENT_EVIDENCE_BACKUP" ]]; then
     cp "$CURRENT_EVIDENCE_BACKUP" "$PKG_ROOT/.agent/verification-evidence.json"
@@ -139,11 +182,59 @@ bash .agent/verify_completion_control_plane.sh >/dev/null
 ROOT="$TMPDIR/repo"
 SYSTEM_REMINDER="$TMPDIR/system-reminder.txt"
 BOOTSTRAP_SESSION="$TMPDIR/session-canonical-evidence-bootstrap.jsonl"
-BOOTSTRAP_DISCUSSION=$'Mission: Exercise canonical evidence fixture bootstrap.\nScope:\n- Materialize canonical completion files for the evidence artifact fixture.\nConstraints:\n- Use supported bare /cook startup only.\nAcceptance:\n- Scaffold canonical files before the fixture rewrites them.'
+BOOTSTRAP_MESSAGES="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Exercise canonical evidence fixture bootstrap.",
+    "scope": [
+        "Materialize canonical completion files for the evidence artifact fixture.",
+        "Keep the verification-evidence bootstrap on the supported explicit-handoff startup path."
+    ],
+    "constraints": [
+        "Use supported bare /cook startup only."
+    ],
+    "acceptance": [
+        "Scaffold .agent/profile.json, .agent/state.json, .agent/plan.json, .agent/active-slice.json, and .agent/verification-evidence.json before the fixture rewrites them.",
+        "Keep scripts/canonical-evidence-artifact-test.sh aligned with packaged bootstrap behavior."
+    ],
+    "risks": [
+        "Evidence-artifact bootstrap must stay anchored to the fresh explicit handoff."
+    ],
+    "notes": [
+        "This fixture exists only to scaffold canonical files before rewriting them for evidence parity coverage."
+    ],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Scaffold canonical evidence-artifact fixture files before rewriting them for parity checks.",
+    "first_slice_non_goals": [
+        "Do not broaden the bootstrap fixture beyond the evidence-artifact surfaces."
+    ],
+    "implementation_surfaces": [
+        ".agent/verification-evidence.json",
+        "scripts/canonical-evidence-artifact-test.sh"
+    ],
+    "verification_commands": [
+        "bash ./scripts/canonical-evidence-artifact-test.sh"
+    ],
+    "why_this_slice_first": "The evidence-artifact fixture cannot validate fail-closed parity until canonical files exist.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "The fixture bootstrap is concrete enough to create canonical control-plane files."
+}
+messages = [
+    {"role": "user", "content": "Prepare the canonical evidence bootstrap fixture and tell me when it is ready for /cook."},
+    {"role": "assistant", "content": "The canonical evidence bootstrap fixture is ready for /cook. Run /cook to confirm it.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
+]
+print(json.dumps(messages, ensure_ascii=False))
+PY
+)"
 mkdir -p "$ROOT"
 cd "$ROOT"
 git init -q
-write_session "$BOOTSTRAP_SESSION" "$ROOT" "$BOOTSTRAP_DISCUSSION"
+write_session_messages "$BOOTSTRAP_SESSION" "$ROOT" "$BOOTSTRAP_MESSAGES"
 
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
 PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \