@linimin/pi-letscook 0.1.51 → 0.1.53

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 0.1.53
+
+### Changed
+
+- removed assist mode from public routing behavior so natural-language entry is now either off or router, and made router the default trigger mode while keeping `/cook` as the canonical workflow boundary
+- removed obsolete cook planning docs that no longer match the shipped router-only workflow entry behavior
+
+## 0.1.52
+
+### Changed
+
+- updated README/help/release parity copy to describe the shipped `off` / `assist` / `router` natural-language routing behavior truthfully while keeping `/cook` as the canonical confirm-first workflow boundary and manual fallback
+- documented the explicit router-mode **Send as normal chat** recovery path as a user choice, not as a silent downgrade, and kept public copy scoped to currently shipped router behavior rather than future auto-mode plans
+- made `npm run release-check` fail closed on the shipped workflow-aware router docs/help contract while continuing to rerun `bash ./scripts/cook-trigger-routing-test.sh` alongside the existing `/cook` smoke/refocus/context regressions
+
 ## 0.1.51
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 `/cook` turns main-chat discussion about concrete repo changes into a resumable repo workflow stored in repo-local `.agent/**` state.
 
-Assist-mode natural-language handoff can also offer to enter that same `/cook` flow before the primary agent starts implementation work, but `/cook` remains the canonical workflow boundary.
+Natural-language routing is optional and shipped in two modes: `off` disables it, and `router` reviews each non-bypass user turn before implementation starts while leaving ordinary questions in the main chat. In every mode, `/cook` remains the canonical workflow boundary and manual fallback.
 
 ## Use it when
 
@@ -46,9 +46,10 @@ Then run `/reload` in Pi.
 |---|---|
 | 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>` |
-| Hand off from discussion into the same `/cook` flow | Say `開始做`, `開始實作`, or `go ahead`, then accept the confirmation |
+| Change natural-language routing behavior | Set `PI_COMPLETION_TRIGGER_MODE=off` or `router` before starting Pi |
+| Hand off from discussion into the same `/cook` flow | In `router`, say `開始做`, `開始實作`, or `go ahead`, then accept the confirmation |
 | Continue the current workflow | Run `/cook` |
-| Use the canonical fallback when the natural-language trigger does not fire | Run `/cook` explicitly |
+| Use the canonical fallback when natural-language routing does not fire or you want to bypass it | Run `/cook` explicitly |
 
 ## What `/cook` expects
 
@@ -60,15 +61,19 @@ Then run `/reload` in Pi.
 
 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`.
 
-## Natural-language handoff (assist mode)
+## Natural-language routing modes
 
-After you have discussed a concrete repo change in the main chat, short execution handoff phrases such as `開始做`, `開始實作`, or `go ahead` can offer to enter the same `/cook` flow before the primary agent starts implementation work.
+Set `PI_COMPLETION_TRIGGER_MODE` before starting Pi if you want to change how natural-language routing behaves:
+
+- `off` — natural-language routing is disabled. Only explicit `/cook` or `/cook <hint>` can enter the workflow.
+- `router` *(default)* — the workflow-aware router reviews each non-bypass normal user turn before implementation starts. Ordinary questions stay in the main chat, while direct start/resume/refocus/next-round prompts can offer the shared `/cook` flow with confirmation or clarification. Short execution handoff phrases such as `開始做`, `開始實作`, or `go ahead` are covered by the same router path.
 
 Important behavior:
-- the handoff is only a shortcut into `/cook`; `/cook` is still the canonical workflow boundary
-- it asks for confirmation before `/cook` takes over
-- if the trigger is unclear or unavailable, nothing is auto-started and you can run `/cook` explicitly
-- ordinary questions and explicit slash commands continue normally
+- natural-language routing is only a shortcut into `/cook`; `/cook` is still the canonical workflow boundary and manual fallback
+- startup, refocus, and next-round routing stay confirm-first; nothing silently starts a workflow
+- unclear router offers and classifier recovery stay fail-closed
+- in router mode, the original message only reaches the normal chat path if you explicitly choose **Send as normal chat**
+- explicit slash commands and ordinary main-chat questions continue normally unless you choose the workflow boundary
 
 ## Typical examples
 
@@ -94,7 +99,7 @@ We should implement the natural-language routing path next.
 
 ## What happens when you run `/cook`
 
-`/cook` supports both bare discussion-driven startup and optional inline intent hints. Assist-mode natural-language handoff is optional; explicit `/cook` is always the canonical fallback.
+`/cook` supports both bare discussion-driven startup and optional inline intent hints. Explicit `/cook` is always the canonical fallback, even when natural-language routing is enabled in `router` mode.
 
 | Repo state | What you'll see |
 |---|---|
@@ -110,6 +115,7 @@ We should implement the natural-language routing path next.
 - actions are **Start** and **Cancel**
 - **Cancel** is side-effect free: discuss changes in the main chat and rerun `/cook`
 - weak, ambiguous, assistant-produced, or planning-only discussion does not start a workflow
+- router-mode false positives and classifier failures stay fail-closed unless you explicitly choose **Send as normal chat**
 - when recent discussion suggests a different workflow, `/cook` shows a chooser before any canonical state rewrite
 
 When you accept startup or refocus, `/cook` persists the chosen workflow state in canonical `.agent/**` files before the re-ground round begins.
@@ -260,7 +266,7 @@ npm run rubric-contract-test
 npm run release-check
 ```
 
-`npm run release-check` is the broad packaged-release verifier. It begins with `bash .agent/verify_completion_control_plane.sh`, so missing or stale `.agent/verification-evidence.json` parity fails closed before the broader suite runs, then asserts the shipped single-command `/cook` public parity surfaces in `README.md`, `CHANGELOG.md`, and the `/cook` help/fail-closed copy in `extensions/completion/index.ts`, reruns `bash ./scripts/cook-trigger-routing-test.sh` for the assist-mode natural-language handoff path, reruns the startup/refocus/context checks — including the critique-aware `/cook` confirmation regression and the smoke auto-resume prompt path — includes deterministic canonical evidence artifact coverage and includes deterministic active-slice contract coverage plus observability coverage, evaluator calibration, and the rubric-contract regression, and finishes with `npm pack --dry-run`.
+`npm run release-check` is the broad packaged-release verifier. It begins with `bash .agent/verify_completion_control_plane.sh`, so missing or stale `.agent/verification-evidence.json` parity fails closed before the broader suite runs, then asserts the shipped `/cook` public parity surfaces in `README.md`, `CHANGELOG.md`, and the `/cook` help/fail-closed copy in `extensions/completion/index.ts`, reruns `bash ./scripts/cook-trigger-routing-test.sh` for workflow-aware router coverage including explicit **Send as normal chat** recovery, reruns the startup/refocus/context checks — including the critique-aware `/cook` confirmation regression and the smoke auto-resume prompt path — includes deterministic canonical evidence artifact coverage and includes deterministic active-slice contract coverage plus observability coverage, evaluator calibration, and the rubric-contract regression, and finishes with `npm pack --dry-run`.
 
 The direct package-root verifier commands above intentionally self-isolate the repo-local extension when they shell back into `pi`, so you should not need to wrap them with `pi --no-extensions` even if `@linimin/pi-letscook` is also installed globally on the same machine.
 

package/extensions/completion/driver.ts

@@ -12,7 +12,7 @@ import {
 	loadCompletionSnapshot,
 	writeJsonFile,
 } from "./state-store";
-import type { CompletionStateSnapshot } from "./types";
+import type { CompletionStateSnapshot, CookNaturalLanguageHandoff, CookTriggerWorkflowBias } from "./types";
 
 type ContextProposalAnalysis = {
 	taskType?: string;
@@ -104,8 +104,13 @@ export type CompletionDriverDeps = {
 		evaluationProfile: string,
 		intent?: "auto" | "continue" | "refocus",
 		missionAnchor?: string,
+		naturalLanguageHandoff?: CookNaturalLanguageHandoff,
+	) => string;
+	completionResumePrompt: (
+		taskType: string,
+		evaluationProfile: string,
+		naturalLanguageHandoff?: CookNaturalLanguageHandoff,
 	) => string;
-	completionResumePrompt: (taskType: string, evaluationProfile: string) => string;
 	deriveCookContextProposal: (ctx: DriverContext, projectName: string, hintText?: string) => Promise<ContextProposal | undefined>;
 	confirmContextProposal: (
 		ctx: { hasUI: boolean; ui: any },
@@ -374,10 +379,15 @@ 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)");
+	const resumePrompt = deps.completionResumePrompt(
+		currentTaskType(snapshot) ?? "(missing)",
+		currentEvaluationProfile(snapshot) ?? "(missing)",
+		naturalLanguageHandoff,
+	);
 	const rootKey = deps.completionRootKey(snapshot, deps.getCtxCwd(ctx));
 	const fingerprint = completionContinuationFingerprint(snapshot) ?? JSON.stringify({
 		kind: "resume",
@@ -536,15 +546,49 @@ 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 explicitHint = options.hintText?.trim() ? options.hintText.trim() : undefined;
+	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);
@@ -616,7 +660,7 @@ export async function runCookEntry(
 		} else {
 			const assessment = await assessActiveWorkflowProposalRouting(ctx, snapshot, deps, explicitHint);
 			if (!assessment.proposal || assessment.action === "continue") {
-				await resumeActiveWorkflowFromCanonicalState(pi, ctx, snapshot, deps);
+				await resumeActiveWorkflowFromCanonicalState(pi, ctx, snapshot, deps, naturalLanguageHandoff);
 				return;
 			}
 			const decision = await confirmExistingWorkflowProposal(ctx, snapshot, assessment.proposal, deps, {
@@ -634,7 +678,7 @@ export async function runCookEntry(
 				return;
 			}
 			if (decision.action === "continue") {
-				await resumeActiveWorkflowFromCanonicalState(pi, ctx, snapshot, deps);
+				await resumeActiveWorkflowFromCanonicalState(pi, ctx, snapshot, deps, naturalLanguageHandoff);
 				return;
 			}
 			const selectedProposal = decision.proposal;
@@ -665,6 +709,7 @@ export async function runCookEntry(
 		currentEvaluationProfile(snapshot) ?? "(missing)",
 		kickoffIntent,
 		kickoffMissionAnchor,
+		naturalLanguageHandoff,
 	);
 	const rootKey = deps.completionRootKey(snapshot, deps.getCtxCwd(ctx));
 	const fingerprint = completionContinuationFingerprint(snapshot) ?? JSON.stringify({

package/extensions/completion/index.ts

@@ -42,6 +42,7 @@ import {
 	buildContextProposalContinuationReason as buildExtractedContextProposalContinuationReason,
 	buildEvaluationRoleContextLines as buildExtractedEvaluationRoleContextLines,
 	buildEvaluationRoleReminderText as buildExtractedEvaluationRoleReminderText,
+	buildNaturalLanguageHandoffMetadataLines,
 	buildResumeCapsule as buildExtractedResumeCapsule,
 	buildSystemReminder as buildExtractedSystemReminder,
 	maybeWriteContextProposalConfirmationSnapshot,
@@ -78,7 +79,7 @@ import {
 } from "./state-store";
 import { parseFirstNumber, parseYesNo } from "./transcription";
 import type { TranscriptionResult } from "./transcription";
-import type { CompletionStateSnapshot, CompletionRole, JsonRecord, LiveRoleActivity } from "./types";
+import type { CompletionStateSnapshot, CompletionRole, CookNaturalLanguageHandoff, JsonRecord, LiveRoleActivity } from "./types";
 
 const PROTOCOL_ID = "completion";
 const ROLE_NAMES = [
@@ -208,9 +209,9 @@ 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 remains the canonical workflow boundary. Assist-mode natural-language handoff can offer to enter the same /cook flow before implementation starts, while mission selection still comes from recent discussion, repo truth, and the approval-only confirmation flow.";
+	"/cook remains the canonical workflow boundary. Natural-language routing can stay off or run in router mode to review each non-bypass user turn before implementation starts, but the shared /cook flow still owns mission selection and confirmation.";
 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. Natural-language handoff only offers to enter the same /cook flow, so 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 Mission/Scope/Constraints/Acceptance proposal for concrete repo changes. Router mode only offers the same /cook flow, and router recovery only replays to normal chat when you explicitly choose Send as normal chat, so clarify the concrete repo changes in the main chat and rerun /cook.";
 
 function buildCookCancellationMessage(prefix: string): string {
 	return `${prefix}. ${COOK_MAIN_CHAT_RERUN_GUIDANCE}`;
@@ -895,18 +896,25 @@ function completionKickoff(
 	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${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${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.`;
 }
 
-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.`;
+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.`;
 }
 
 export default function completionExtension(pi: ExtensionAPI) {
@@ -923,7 +931,7 @@ export default function completionExtension(pi: ExtensionAPI) {
 		structuredDiscussionFailureDetail: COOK_STRUCTURED_DISCUSSION_FAILURE_DETAIL,
 		mainChatRerunGuidance: COOK_MAIN_CHAT_RERUN_GUIDANCE,
 		cookCommandSpec: {
-			description: "/cook workflow: start, continue, refocus, or start the next round; assist-mode natural-language handoff can offer the same /cook boundary",
+			description: "/cook workflow: start, continue, refocus, or start the next round; /cook stays canonical while natural-language routing can be off or router",
 		},
 		buildContextProposalContinuationReason,
 		completionKickoff,