@linimin/pi-letscook 0.1.58 → 0.1.59

package/.agent/README.md

@@ -0,0 +1,28 @@
+# Completion Control Plane
+
+This repository uses the `completion` workflow for long-running coding tasks.
+
+## Canonical tracked contract files
+
+- `.agent/README.md`
+- `.agent/mission.md`
+- `.agent/profile.json`
+- `.agent/verify_completion_stop.sh`
+- `.agent/verify_completion_control_plane.sh`
+
+## Ignored canonical execution state
+
+- `.agent/state.json`
+- `.agent/plan.json`
+- `.agent/active-slice.json`
+- `.agent/slice-history.jsonl`
+- `.agent/stop-check-history.jsonl`
+- `.agent/verification-evidence.json`
+- `.agent/*.log`
+- `.agent/tmp/`
+
+`.agent/verification-evidence.json` is the durable canonical record of deterministic verification for the selected slice or current HEAD. Recovery, review, audit, and stop-check reminder surfaces consume it instead of temp-only artifacts or conversational summaries when it is populated.
+
+The source of truth for long-running completion work is canonical `.agent/**` state plus current repo truth.
+
+Project: pi-letscook

package/.agent/mission.md

@@ -0,0 +1,8 @@
+# Mission
+
+Project: pi-letscook
+
+Mission anchor:
+Implement the primary-agent → /cook handoff pipeline refactor so /cook only starts implementation workflow from structurally startable handoffs, while preserving explicit handoff as the preferred startup-intake path.
+
+This 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.

package/.agent/profile.json

@@ -0,0 +1,13 @@
+{
+  "schema_version": 1,
+  "protocol_id": "completion",
+  "project_name": "pi-letscook",
+  "required_stop_judges": 3,
+  "priority_policy_id": "completion-default",
+  "task_type": "completion-workflow",
+  "evaluation_profile": "completion-rubric-v1",
+  "docs_surfaces": [
+    "README.md",
+    "CHANGELOG.md"
+  ]
+}

package/.agent/verify_completion_control_plane.sh

@@ -0,0 +1,203 @@
+#!/usr/bin/env bash
+':' //; exec node "$0" "$@"
+const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+
+const REQUIRED_TRACKED_CONTRACT_FILES = [
+  '.agent/README.md',
+  '.agent/mission.md',
+  '.agent/profile.json',
+  '.agent/verify_completion_stop.sh',
+  '.agent/verify_completion_control_plane.sh',
+];
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    fail('Failed to read ' + file + ': ' + error.message);
+  }
+}
+
+function asString(value) {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function asNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function asStringArray(value) {
+  return Array.isArray(value)
+    ? value.filter((item) => typeof item === 'string' && item.trim().length > 0)
+    : [];
+}
+
+function sameStringArrays(left, right) {
+  return left.length === right.length && left.every((item, index) => item === right[index]);
+}
+
+function runGit(args, options = {}) {
+  const result = spawnSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if (!options.allowFailure && result.status !== 0) {
+    const stderr = asString(result.stderr) ?? 'git command failed';
+    fail(`git ${args.join(' ')} failed: ${stderr}`);
+  }
+  return result;
+}
+
+function gitHeadSha() {
+  const result = runGit(['rev-parse', 'HEAD'], { allowFailure: true });
+  return result.status === 0 ? asString(result.stdout) : undefined;
+}
+
+function ensureTrackedContractFiles() {
+  for (const file of REQUIRED_TRACKED_CONTRACT_FILES) {
+    const result = runGit(['ls-files', '--error-unmatch', file], { allowFailure: true });
+    if (result.status !== 0) {
+      fail(`Required tracked completion contract file is missing from git index: ${file}`);
+    }
+  }
+}
+
+function ensureCommitExists(commitish, label) {
+  const result = runGit(['rev-parse', '--verify', `${commitish}^{commit}`], { allowFailure: true });
+  if (result.status !== 0) {
+    fail(`${label} must resolve to an existing commit: ${commitish}`);
+  }
+}
+
+function trackedDiffFiles(fromCommit, toCommit) {
+  const result = runGit(['diff', '--name-only', '--diff-filter=ACMR', `${fromCommit}..${toCommit}`]);
+  return result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+const profile = readJson('.agent/profile.json');
+const state = readJson('.agent/state.json');
+const plan = readJson('.agent/plan.json');
+const active = readJson('.agent/active-slice.json');
+const evidence = readJson('.agent/verification-evidence.json');
+
+ensureTrackedContractFiles();
+
+for (const [file, record] of [
+  ['.agent/profile.json', profile],
+  ['.agent/state.json', state],
+  ['.agent/plan.json', plan],
+  ['.agent/active-slice.json', active],
+]) {
+  if (!asString(record.task_type)) fail(file + ' is missing task_type');
+  if (!asString(record.evaluation_profile)) fail(file + ' is missing evaluation_profile');
+}
+
+const taskType = asString(profile.task_type);
+const evaluationProfile = asString(profile.evaluation_profile);
+if (asString(state.task_type) !== taskType) fail('.agent/state.json task_type must match .agent/profile.json task_type');
+if (asString(plan.task_type) !== taskType) fail('.agent/plan.json task_type must match .agent/profile.json task_type');
+if (asString(active.task_type) !== taskType) fail('.agent/active-slice.json task_type must match .agent/profile.json task_type');
+if (asString(state.evaluation_profile) !== evaluationProfile) fail('.agent/state.json evaluation_profile must match .agent/profile.json evaluation_profile');
+if (asString(plan.evaluation_profile) !== evaluationProfile) fail('.agent/plan.json evaluation_profile must match .agent/profile.json evaluation_profile');
+if (asString(active.evaluation_profile) !== evaluationProfile) fail('.agent/active-slice.json evaluation_profile must match .agent/profile.json evaluation_profile');
+
+if (asString(evidence.artifact_type) !== 'completion-verification-evidence') {
+  fail('.agent/verification-evidence.json artifact_type must be completion-verification-evidence');
+}
+
+const exactStatuses = new Set(['selected', 'in_progress', 'committed', 'done']);
+const activeStatus = asString(active.status);
+const exactHandoff = exactStatuses.has(activeStatus || '');
+const planSlices = Array.isArray(plan.candidate_slices) ? plan.candidate_slices : [];
+const activeSliceId = asString(active.slice_id);
+const planSlice = activeSliceId ? planSlices.find((slice) => asString(slice && slice.slice_id) === activeSliceId) : undefined;
+
+if (exactHandoff && !planSlice) {
+  fail('slice_id must match a slice in .agent/plan.json when status carries an exact handoff');
+}
+
+if (exactHandoff) {
+  const requiredStringFields = ['goal', 'why_now', 'basis_commit'];
+  for (const field of requiredStringFields) {
+    if (!asString(active[field])) fail('.agent/active-slice.json is missing ' + field + ' when status carries an exact handoff');
+  }
+  const requiredArrayFields = ['contract_ids', 'acceptance_criteria', 'blocked_on', 'locked_notes', 'must_fix_findings', 'implementation_surfaces', 'verification_commands', 'remaining_contract_ids_before'];
+  for (const field of requiredArrayFields) {
+    if (!Array.isArray(active[field])) fail('.agent/active-slice.json is missing ' + field + ' when status carries an exact handoff');
+  }
+  const requiredNumberFields = ['priority', 'release_blocker_count_before', 'high_value_gap_count_before'];
+  for (const field of requiredNumberFields) {
+    if (asNumber(active[field]) === undefined) fail('.agent/active-slice.json is missing ' + field + ' when status carries an exact handoff');
+  }
+
+  const mismatchFields = [];
+  if (asString(planSlice.slice_id) !== activeSliceId) mismatchFields.push('slice_id');
+  if (asString(planSlice.goal) !== asString(active.goal)) mismatchFields.push('goal');
+  if (!sameStringArrays(asStringArray(planSlice.contract_ids), asStringArray(active.contract_ids))) mismatchFields.push('contract_ids');
+  if (!sameStringArrays(asStringArray(planSlice.acceptance_criteria), asStringArray(active.acceptance_criteria))) mismatchFields.push('acceptance_criteria');
+  if (!sameStringArrays(asStringArray(planSlice.blocked_on), asStringArray(active.blocked_on))) mismatchFields.push('blocked_on');
+  if (asNumber(planSlice.priority) !== asNumber(active.priority)) mismatchFields.push('priority');
+  if (asString(planSlice.why_now) !== asString(active.why_now)) mismatchFields.push('why_now');
+  const planMirrorFields = ['locked_notes', 'must_fix_findings', 'implementation_surfaces', 'verification_commands', 'basis_commit', 'remaining_contract_ids_before', 'release_blocker_count_before', 'high_value_gap_count_before'];
+  for (const field of planMirrorFields) {
+    const planValue = planSlice[field];
+    const activeValue = active[field];
+    if (Array.isArray(planValue) || Array.isArray(activeValue)) {
+      if (!sameStringArrays(asStringArray(planValue), asStringArray(activeValue))) mismatchFields.push(field);
+      continue;
+    }
+    if (typeof planValue === 'number' || typeof activeValue === 'number') {
+      if (asNumber(planValue) !== asNumber(activeValue)) mismatchFields.push(field);
+      continue;
+    }
+    if (asString(planValue) !== asString(activeValue)) mismatchFields.push(field);
+  }
+  if (mismatchFields.length > 0) {
+    fail('.agent/active-slice.json must match the selected .agent/plan.json slice across: ' + mismatchFields.join(', '));
+  }
+
+  if (asString(evidence.subject_type) !== 'selected_slice') {
+    fail('subject_type must be selected_slice when active slice exact handoff requires verification evidence');
+  }
+  if (asString(evidence.slice_id) !== activeSliceId) fail('.agent/verification-evidence.json slice_id must match .agent/active-slice.json slice_id');
+  if (asString(evidence.goal) !== asString(active.goal)) fail('.agent/verification-evidence.json goal must match .agent/active-slice.json goal');
+  if (!sameStringArrays(asStringArray(evidence.contract_ids), asStringArray(active.contract_ids))) fail('.agent/verification-evidence.json contract_ids must match .agent/active-slice.json contract_ids');
+  if (asString(evidence.basis_commit) !== asString(active.basis_commit)) fail('.agent/verification-evidence.json basis_commit must match .agent/active-slice.json basis_commit');
+  if (!sameStringArrays(asStringArray(evidence.verification_commands), asStringArray(active.verification_commands))) {
+    fail('.agent/verification-evidence.json verification_commands must match .agent/active-slice.json verification_commands');
+  }
+  if (!asString(evidence.recorded_at)) fail('.agent/verification-evidence.json recorded_at must be present for selected-slice evidence');
+  if (asString(evidence.outcome) === 'not_recorded') fail('.agent/verification-evidence.json outcome must not be not_recorded for selected-slice evidence');
+  const headSha = gitHeadSha();
+  if (headSha && asString(evidence.head_sha) !== headSha) {
+    fail('.agent/verification-evidence.json head_sha must match current HEAD');
+  }
+
+  const basisCommit = asString(active.basis_commit);
+  if (basisCommit && headSha) {
+    ensureCommitExists(basisCommit, '.agent/active-slice.json basis_commit');
+    const ancestorCheck = runGit(['merge-base', '--is-ancestor', basisCommit, headSha], { allowFailure: true });
+    if (ancestorCheck.status !== 0) {
+      fail(`.agent/active-slice.json basis_commit must be an ancestor of current HEAD: ${basisCommit} -> ${headSha}`);
+    }
+    const changedFiles = trackedDiffFiles(basisCommit, headSha);
+    const implementationSurfaces = new Set(asStringArray(active.implementation_surfaces));
+    const missingSurfaces = changedFiles.filter((file) => !implementationSurfaces.has(file));
+    if (missingSurfaces.length > 0) {
+      fail('.agent/active-slice.json implementation_surfaces must cover every tracked file changed from basis_commit to current HEAD; missing: ' + missingSurfaces.join(', '));
+    }
+  }
+} else {
+  const subjectType = asString(evidence.subject_type);
+  if (subjectType === 'none') {
+    if (asString(evidence.outcome) && asString(evidence.outcome) !== 'not_recorded') {
+      fail('.agent/verification-evidence.json outcome must stay not_recorded when subject_type=none');
+    }
+  }
+}

package/.agent/verify_completion_stop.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+echo "[completion-stop] verifying control plane and .agent/verification-evidence.json parity"
+bash .agent/verify_completion_control_plane.sh
+
+if [[ "${PI_COMPLETION_RUNNING_RELEASE_CHECK:-0}" == "1" ]]; then
+  echo "[completion-stop] release-check is already in progress; skipping nested npm run release-check >/dev/null recursion"
+  npm run evaluator-calibration-test >/dev/null
+  echo "completion stop verification passed"
+  exit 0
+fi
+
+echo "[completion-stop] delegating to npm run release-check >/dev/null for broad packaged verification, evaluator calibration, and contract coverage"
+PI_COMPLETION_RUNNING_RELEASE_CHECK=1 npm run release-check >/dev/null
+
+echo "completion stop verification passed"

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.1.59
+
+### Changed
+
+- relaxed the pre-`/cook` ordinary-chat boundary so the primary agent can keep discussing and refining requirements before explicit `/cook` instead of switching into a hard handoff-only refusal mode as soon as workflow-worthiness is detected
+- kept `/cook` as the only explicit workflow boundary, while teaching the pre-`/cook` prompt surfaces to recommend `/cook` advisory-first and only emit implementation-ready capsules once the first bounded slice is concrete enough
+- made fresh explicit `/cook` handoffs reusable from recent ordinary-chat discussion instead of requiring the immediately preceding turn, so Cancel can return users cleanly to ordinary discussion before they rerun `/cook`
+- kept bare `/cook` startup and done-workflow next-round entry fail-closed on missing or non-startable explicit handoffs, while active workflows still resume from canonical `.agent/**` state unless a fresh explicit handoff proposes replacement
+- updated public parity and shipped package contents so the tracked `.agent` contract files are included in package tarballs and packaged smoke/release verification can scaffold canonical state truthfully
+
 ## 0.1.58
 
 ### Changed

package/README.md

@@ -30,10 +30,10 @@ Then run `/reload` in Pi.
 1. Install the package:
    `pi install npm:@linimin/pi-letscook`
 2. Run `/reload` in Pi.
-3. In the main chat, describe the concrete repo change you want.
+3. In the main chat, describe the concrete repo change you want and let the primary agent help refine it until the first slice is ready for `/cook`.
 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.
+6. Later, run `/cook` again to resume from canonical state or confirm an explicit replacement or next-round handoff.
 
 ```text
 /cook
@@ -43,20 +43,20 @@ 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` |
+| Start a long-running task | Discuss the concrete repo change in the main chat, wait for a fresh primary-agent handoff, then run `/cook` |
 | 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` |
+| Refocus or start the next round | Discuss the new concrete repo change in the main chat, wait for a fresh primary-agent handoff, then run `/cook` |
 
 ## What `/cook` expects
 
-- preferably a fresh explicit primary-agent `/cook` handoff capsule from the immediately preceding ordinary-chat turn
+- a fresh valid explicit primary-agent `/cook` handoff capsule from recent ordinary-chat discussion whenever `/cook` is starting a new workflow or the next round after a completed workflow
 - for that handoff capsule to start workflow immediately, it must already be implementation-startable: a bounded `first_slice_goal`, repo-change-oriented acceptance, `implementation_surfaces`, `verification_commands`, and `why_this_slice_first`
-- otherwise, when no fresh explicit handoff is blocking startup, 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
+- enough detail in the main chat for the primary agent to form that bounded handoff capsule before you run `/cook`
 - README/CHANGELOG updates still count as concrete repo changes
 - assistant-produced summaries and plan/spec/design-doc/proposal-only artifacts still do not count unless they include the explicit structured `/cook` handoff capsule
+- recent main-chat discussion can still validate or supplement an accepted explicit handoff, but it no longer starts a new workflow by itself
 
-If no fresh valid handoff exists and 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 no fresh valid handoff exists for new-workflow or next-round entry, `/cook` fails closed, leaves canonical `.agent/**` state unchanged, and tells you to get an explicit primary-agent handoff in the main chat before rerunning `/cook`.
 
 If a fresh explicit handoff exists but is still workflow-worthy rather than implementation-startable, `/cook` also fails closed instead of silently treating that capsule as planning support or canonical workflow state.
 
@@ -66,36 +66,40 @@ If you pass inline arguments to `/cook`, it also fails closed and tells you to m
 
 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.
+If a task has clearly matured into completion-workflow scope, the primary agent should recommend `/cook` instead of starting long-running implementation directly in ordinary chat.
 
-That handoff should include an explicit structured `/cook` capsule in the assistant reply so `/cook` can confirm the already-formed mission instead of re-deriving it from broad ambient context.
+Before you explicitly run `/cook`, the conversation can still stay in ordinary chat: the primary agent may keep answering follow-up questions and refining requirements rather than switching into a hard handoff-only refusal mode.
 
-The preferred capsule is still advisory startup intake, not canonical workflow state, and it only counts as implementation-ready when it already names the first bounded slice, repo-change-oriented acceptance, implementation surfaces, and verification commands.
+That handoff should include an explicit structured `/cook` capsule in the assistant reply once the first slice is implementation-ready, so `/cook` can confirm the already-formed mission instead of re-deriving it from broad ambient context.
+
+The capsule is still advisory startup intake, not canonical workflow state, and new-workflow or next-round entry only proceeds when it already names the first bounded slice, repo-change-oriented acceptance, implementation surfaces, and verification commands.
 
 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
+- startup and next-round entry stay confirm-first and require a fresh valid explicit primary-agent handoff
+- active workflows resume from canonical `.agent/**` state unless a fresh valid explicit handoff proposes a replacement
 - 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
 
-Start a new workflow from recent discussion:
+Start a new workflow after a fresh primary-agent handoff:
 
 ```text
 I want to add login redirect handling and tests.
+# let the primary agent hand you off to /cook
 /cook
 ```
 
 ## What happens when you run `/cook`
 
-`/cook` first looks for a fresh explicit primary-agent handoff capsule. If one is valid and implementation-startable, `/cook` builds the startup brief from that handoff and only uses recent discussion as validation or supplemental notes. `/cook` falls back to deriving a startup brief from recent discussion only when no fresh explicit handoff is blocking startup—for example, when there is no fresh capsule or only stale or invalidated capsules—before showing the existing approval-only Start/Cancel gate.
+`/cook` first looks for a fresh explicit primary-agent handoff capsule from recent ordinary-chat discussion. New-workflow entry and done-workflow next-round entry start only when that capsule is fresh, valid, and implementation-startable; otherwise `/cook` fails closed instead of deriving startup from recent discussion. When a workflow is already active and no fresh valid explicit handoff is present, `/cook` resumes from canonical `.agent/**` state instead of deriving replacement startup from recent discussion.
 
 | Repo state | What you'll see |
 |---|---|
-| No workflow yet | If a fresh explicit handoff capsule exists and is implementation-startable, a startup brief built from that handoff. Otherwise, when no fresh explicit handoff is blocking startup, a startup brief built from recent main-chat discussion. You choose **Start** or **Cancel**. Weak, unreliable, stale, planning-only, or non-startable explicit-handoff intake fails closed. |
-| Active workflow exists | Usually a resume of the current workflow. If a fresh explicit handoff capsule or 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 intake stays conservative. |
-| Previous workflow is `done` | A fresh explicit handoff capsule can still start the next implementation round behind **Start** or **Cancel**. Without a fresh explicit handoff blocking startup, `/cook` can fall back to recent discussion. Discussion that only restates already-finished work still fails closed. |
+| No workflow yet | If a fresh explicit handoff capsule exists and is implementation-startable, you get a startup brief built from that handoff and choose **Start** or **Cancel**. Otherwise `/cook` fails closed, leaves canonical state unchanged, and tells you to get a fresh explicit primary-agent handoff. Weak, unreliable, stale, planning-only, or non-startable explicit-handoff intake also fails closed. |
+| Active workflow exists | Usually a resume of the current workflow from canonical `.agent/**` state. If a fresh explicit handoff capsule points to a different concrete repo change, `/cook` shows a chooser first and only rewrites canonical state after you confirm the replacement. Ambiguous intake stays conservative. |
+| Previous workflow is `done` | A fresh explicit handoff capsule can still start the next implementation round behind **Start** or **Cancel**. Without one, `/cook` fails closed instead of deriving the next round from recent discussion. |
 
 ## Confirmation and fail-closed behavior
 
@@ -103,9 +107,9 @@ I want to add login redirect handling and tests.
 
 - startup, next-round, and refocus proposals are approval-only
 - actions are **Start** and **Cancel**
-- **Cancel** is side-effect free: discuss changes in the main chat and rerun `/cook`
+- **Cancel** is side-effect free: canonical workflow state stays unchanged, so you can discuss changes in the main chat and rerun `/cook`
 - weak, ambiguous, stale, invalid, assistant-produced, or planning-only intake does not start a workflow
-- when recent discussion suggests a different workflow, `/cook` shows a chooser before any canonical state rewrite
+- when a fresh explicit handoff suggests replacing an active 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.
 

package/extensions/completion/driver.ts

@@ -60,16 +60,21 @@ type CookContextProposalResult = {
 	blockedFailureMessage?: string;
 };
 
+function buildCookExplicitHandoffRequiredMessage(deps: CompletionDriverDeps, prefix?: string): string {
+	const requirement =
+		"/cook failed closed because starting a new completion workflow now requires a fresh valid explicit primary-agent handoff. Ask the primary agent to emit a fresh ```cook_handoff``` capsule in the main chat, then rerun /cook.";
+	return prefix ? `${prefix} ${requirement}` : requirement;
+}
+
 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";
 };
 
@@ -122,6 +127,7 @@ export type CompletionDriverDeps = {
 	) => string;
 	completionResumePrompt: (taskType: string, evaluationProfile: string) => string;
 	deriveCookContextProposal: (ctx: DriverContext, projectName: string) => Promise<CookContextProposalResult>;
+	deriveCookStartupProposal: (ctx: DriverContext, projectName: string) => Promise<CookContextProposalResult>;
 	confirmContextProposal: (
 		ctx: { hasUI: boolean; ui: any },
 		proposal: ContextProposal,
@@ -137,7 +143,6 @@ export type CompletionDriverDeps = {
 	maybeWriteActiveWorkflowRoutingSnapshot: (assessment: ActiveWorkflowProposalAssessment) => void;
 	missionAnchorsLikelyEquivalent: (left: string, right: string) => boolean;
 	missionAnchorsStrictlyEquivalent: (left: string, right: string) => boolean;
-	shouldTreatBareActiveWorkflowProposalAsClearRefocus: (proposal: ContextProposal) => boolean;
 	activateCompletionRoutingForRoot: (root: string | undefined) => void;
 	maybeWriteTestSnapshot: (targetPath: string | undefined, content: string) => void;
 	completionTestDriverPromptPath: () => string | undefined;
@@ -316,23 +321,23 @@ async function assessActiveWorkflowProposalRouting(
 ): Promise<ActiveWorkflowProposalAssessment> {
 	const currentMission = currentMissionAnchor(snapshot);
 	const projectName = path.basename(snapshot.files.root);
-	const derived = await deps.deriveCookContextProposal(ctx, projectName);
-	if (derived.blockedFailureMessage) {
+	const explicitHandoff = await deps.deriveCookStartupProposal(ctx, projectName);
+	if (explicitHandoff.blockedFailureMessage) {
 		const assessment: ActiveWorkflowProposalAssessment = {
 			action: "blocked",
 			currentMissionAnchor: currentMission,
-			blockedFailureMessage: derived.blockedFailureMessage,
+			blockedFailureMessage: explicitHandoff.blockedFailureMessage,
 			reason: "fresh_explicit_handoff_not_startable",
 		};
 		deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
 		return assessment;
 	}
-	const proposal = derived.proposal;
+	const proposal = explicitHandoff.proposal;
 	if (!proposal) {
 		const assessment: ActiveWorkflowProposalAssessment = {
-			action: "unclear",
+			action: "continue",
 			currentMissionAnchor: currentMission,
-			reason: "missing_proposal",
+			reason: "missing_explicit_handoff",
 		};
 		deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
 		return assessment;
@@ -347,21 +352,11 @@ async function assessActiveWorkflowProposalRouting(
 		deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
 		return assessment;
 	}
-	if (deps.shouldTreatBareActiveWorkflowProposalAsClearRefocus(proposal)) {
-		const assessment: ActiveWorkflowProposalAssessment = {
-			action: "refocus",
-			currentMissionAnchor: currentMission,
-			proposal,
-			reason: "clear_refocus",
-		};
-		deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
-		return assessment;
-	}
 	const assessment: ActiveWorkflowProposalAssessment = {
-		action: "unclear",
+		action: "refocus",
 		currentMissionAnchor: currentMission,
 		proposal,
-		reason: "ambiguous_discussion",
+		reason: "fresh_explicit_handoff",
 	};
 	deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
 	return assessment;
@@ -541,14 +536,14 @@ export async function runCookEntry(
 	if (!snapshot) {
 		const root = findRepoRoot(cwd) ?? cwd;
 		const projectName = path.basename(root);
-		const derived = await deps.deriveCookContextProposal(ctx, projectName);
+		const derived = await deps.deriveCookStartupProposal(ctx, projectName);
 		if (derived.blockedFailureMessage) {
 			deps.emitCommandText(ctx, derived.blockedFailureMessage, "info");
 			return;
 		}
 		const proposal = derived.proposal;
 		if (!proposal) {
-			deps.emitCommandText(ctx, buildCookStructuredDiscussionFailureMessage(deps), "info");
+			deps.emitCommandText(ctx, buildCookExplicitHandoffRequiredMessage(deps), "info");
 			return;
 		}
 		const decision = await deps.confirmContextProposal(ctx, proposal, {
@@ -586,14 +581,14 @@ export async function runCookEntry(
 	if (!goal) {
 		if (workflowDone) {
 			const projectName = path.basename(snapshot.files.root);
-			const derived = await deps.deriveCookContextProposal(ctx, projectName);
+			const derived = await deps.deriveCookStartupProposal(ctx, projectName);
 			if (derived.blockedFailureMessage) {
 				deps.emitCommandText(ctx, derived.blockedFailureMessage, "info");
 				return;
 			}
 			const proposal = derived.proposal;
 			if (!proposal) {
-				deps.emitCommandText(ctx, buildCookStructuredDiscussionFailureMessage(deps, "The previous completion workflow is already done."), "info");
+				deps.emitCommandText(ctx, buildCookExplicitHandoffRequiredMessage(deps, "The previous completion workflow is already done."), "info");
 				return;
 			}
 			const decision = await deps.confirmContextProposal(ctx, proposal, {
@@ -615,7 +610,7 @@ export async function runCookEntry(
 				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");
+			deps.emitCommandText(ctx, `Started a new completion workflow round from explicit primary-agent handoff: ${decision.missionAnchor}`, "info");
 		} else {
 			const assessment = await assessActiveWorkflowProposalRouting(ctx, snapshot, deps);
 			if (assessment.action === "blocked") {
@@ -626,15 +621,21 @@ export async function runCookEntry(
 				await resumeActiveWorkflowFromCanonicalState(pi, ctx, snapshot, deps);
 				return;
 			}
+			const explicitReplacement = assessment.reason === "fresh_explicit_handoff";
 			const decision = await confirmExistingWorkflowProposal(ctx, snapshot, assessment.proposal, deps, {
-				intro:
-					assessment.action === "refocus"
-						? "Recent non-command discussion suggests a different workflow. Choose how /cook should proceed:"
-						: "Recent discussion may point to a different implementation goal. Review the current mission and the latest inferred mission before deciding how /cook should proceed:",
-				proposedMissionLabel: "Proposed mission from recent discussion",
-				refocusChoiceLabel:
-					"Start new workflow from recent discussion\n\nReview the proposed replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state.",
-				comparison: assessment.action === "refocus" ? "semantic" : "strict",
+				intro: explicitReplacement
+					? "A fresh explicit primary-agent handoff proposes replacing the current workflow. Choose how /cook should proceed:"
+					: "A replacement workflow is ready. Choose how /cook should proceed:",
+				proposedMissionLabel: explicitReplacement
+					? "Proposed mission from explicit primary-agent handoff"
+					: "Proposed mission",
+				refocusChoiceLabel: explicitReplacement
+					? "Start new workflow from explicit primary-agent handoff\n\nReview the proposed replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state."
+					: "Start new workflow\n\nReview the proposed replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state.",
+				alternateChoiceLabel: explicitReplacement
+					? "Start alternate workflow from explicit primary-agent handoff\n\nReview this alternate replacement in a final Start/Cancel confirmation before /cook rewrites canonical workflow state."
+					: undefined,
+				comparison: "strict",
 			});
 			if (!decision) {
 				deps.emitCommandText(ctx, buildCookCancellationMessage("Cancelled existing workflow confirmation", deps), "info");
@@ -646,10 +647,9 @@ export async function runCookEntry(
 			}
 			const selectedProposal = decision.proposal;
 			const proposalDecision = await deps.confirmContextProposal(ctx, selectedProposal, {
-				title:
-					assessment.action === "refocus"
-						? "Start the replacement workflow from this startup brief?"
-						: "Start the latest inferred workflow from this startup brief?",
+				title: assessment.reason === "fresh_explicit_handoff"
+					? "Start the replacement workflow from this explicit startup brief?"
+					: "Start the replacement workflow from this startup brief?",
 			});
 			if (!proposalDecision) {
 				deps.emitCommandText(ctx, buildCookCancellationMessage("Cancelled replacement workflow proposal", deps), "info");
@@ -667,7 +667,13 @@ export async function runCookEntry(
 				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");
+			deps.emitCommandText(
+				ctx,
+				assessment.reason === "fresh_explicit_handoff"
+					? `Refocused completion mission from explicit primary-agent handoff to: ${proposalDecision.missionAnchor}`
+					: `Refocused completion mission to: ${proposalDecision.missionAnchor}`,
+				"info",
+			);
 		}
 	}
 	kickoffMissionAnchor = kickoffMissionAnchor ?? currentMissionAnchor(snapshot);