@linimin/pi-letscook 0.1.57 → 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,12 +2,32 @@
 
 ## 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
+
+- tightened implementation-ready explicit `/cook` handoffs so fresh capsules must already carry a bounded first slice, repo-change-oriented acceptance, implementation surfaces, verification commands, and why-that-slice-first structure before workflow startup
+- made fresh explicit but non-startable `/cook` handoffs fail closed with a dedicated operator message instead of falling back to broader recent discussion or silently drifting into planning
+- expanded regressions and public parity so valid, vague, stale, done-workflow, and negative explicit-handoff cases stay truthful across runtime behavior, docs, and `npm run release-check`
+
 ## 0.1.57
 
 ### Changed
 
-- made explicit primary-agent `/cook` handoff the preferred startup-intake path by teaching ordinary-chat handoff turns to emit a structured `cook_handoff` capsule and letting `/cook` prefer that capsule over broad context re-inference when it is fresh and valid
-- kept context-derived startup as a fallback only, so stale, drifted, or non-startable handoff capsules still fail closed or fall back to recent discussion instead of silently rewriting canonical state
+- made explicit primary-agent `/cook` handoff the preferred startup-intake path by teaching ordinary-chat handoff turns to emit a structured `cook_handoff` capsule and letting `/cook` prefer that capsule over broad context re-inference when it is fresh, valid, and implementation-startable
+- tightened implementation-ready explicit handoffs so the structured capsule must already carry a bounded `first_slice_goal`, repo-change-oriented acceptance, `implementation_surfaces`, `verification_commands`, and `why_this_slice_first` before `/cook` will start workflow from it
+- kept the pre-`/cook` handoff capsule as advisory startup intake only, not canonical `.agent/**` workflow state, while still using context-derived startup as the fallback only when no fresh explicit handoff is blocking startup
+- kept context-derived startup as a fallback only when there is no fresh explicit handoff blocking startup, so stale or invalidated capsules can still fall back to recent discussion while fresh non-startable handoffs fail closed instead of silently rewriting canonical state
 - made finished-workflow suppression stay a safety layer instead of a replacement mission when a fresh explicit `/cook` handoff exists, and blocked negative rejection/suppression text from becoming a Startable startup mission
 - 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

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,19 +43,22 @@ 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
-- otherwise 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
+- 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`
+- 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.
 
 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`.
 
@@ -63,34 +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.
+
+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.
+
+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.
 
-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.
+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, `/cook` builds the startup brief from that handoff and only uses recent discussion as validation or supplemental notes. If no valid handoff exists, `/cook` falls back to deriving a startup brief from recent discussion 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, a startup brief built from that handoff. Otherwise a startup brief built from recent main-chat discussion. You choose **Start** or **Cancel**. Weak, unreliable, stale, or planning-only 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 that, `/cook` falls 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
 
@@ -98,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

@@ -38,7 +38,7 @@ type ContextProposalAlternate = {
 	analysis: ContextProposalAnalysis;
 	goalText: string;
 	basisPreview: string;
-	source: "session" | "analyst";
+	source: "session" | "analyst" | "handoff_capsule";
 };
 
 type ContextProposal = ContextProposalAlternate & {
@@ -55,11 +55,27 @@ type ExistingWorkflowDecision =
 	| { action: "continue"; currentMissionAnchor: string }
 	| { action: "refocus"; currentMissionAnchor: string; missionAnchor: string; proposal: ContextProposal };
 
+type CookContextProposalResult = {
+	proposal?: ContextProposal;
+	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";
+	action: "continue" | "refocus" | "blocked";
 	currentMissionAnchor: string;
 	proposal?: ContextProposal;
-	reason: "matching_mission" | "clear_refocus" | "missing_proposal" | "ambiguous_discussion";
+	blockedFailureMessage?: string;
+	reason:
+		| "matching_mission"
+		| "missing_explicit_handoff"
+		| "fresh_explicit_handoff"
+		| "fresh_explicit_handoff_not_startable";
 };
 
 type ExistingWorkflowChooserOptions = {
@@ -110,7 +126,8 @@ export type CompletionDriverDeps = {
 		missionAnchor?: string,
 	) => string;
 	completionResumePrompt: (taskType: string, evaluationProfile: string) => string;
-	deriveCookContextProposal: (ctx: DriverContext, projectName: string) => Promise<ContextProposal | undefined>;
+	deriveCookContextProposal: (ctx: DriverContext, projectName: string) => Promise<CookContextProposalResult>;
+	deriveCookStartupProposal: (ctx: DriverContext, projectName: string) => Promise<CookContextProposalResult>;
 	confirmContextProposal: (
 		ctx: { hasUI: boolean; ui: any },
 		proposal: ContextProposal,
@@ -126,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;
@@ -305,41 +321,42 @@ async function assessActiveWorkflowProposalRouting(
 ): Promise<ActiveWorkflowProposalAssessment> {
 	const currentMission = currentMissionAnchor(snapshot);
 	const projectName = path.basename(snapshot.files.root);
-	const proposal = await deps.deriveCookContextProposal(ctx, projectName);
-	if (!proposal) {
+	const explicitHandoff = await deps.deriveCookStartupProposal(ctx, projectName);
+	if (explicitHandoff.blockedFailureMessage) {
 		const assessment: ActiveWorkflowProposalAssessment = {
-			action: "unclear",
+			action: "blocked",
 			currentMissionAnchor: currentMission,
-			reason: "missing_proposal",
+			blockedFailureMessage: explicitHandoff.blockedFailureMessage,
+			reason: "fresh_explicit_handoff_not_startable",
 		};
 		deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
 		return assessment;
 	}
-	if (deps.missionAnchorsLikelyEquivalent(currentMission, proposal.mission)) {
+	const proposal = explicitHandoff.proposal;
+	if (!proposal) {
 		const assessment: ActiveWorkflowProposalAssessment = {
 			action: "continue",
 			currentMissionAnchor: currentMission,
-			proposal,
-			reason: "matching_mission",
+			reason: "missing_explicit_handoff",
 		};
 		deps.maybeWriteActiveWorkflowRoutingSnapshot(assessment);
 		return assessment;
 	}
-	if (deps.shouldTreatBareActiveWorkflowProposalAsClearRefocus(proposal)) {
+	if (deps.missionAnchorsLikelyEquivalent(currentMission, proposal.mission)) {
 		const assessment: ActiveWorkflowProposalAssessment = {
-			action: "refocus",
+			action: "continue",
 			currentMissionAnchor: currentMission,
 			proposal,
-			reason: "clear_refocus",
+			reason: "matching_mission",
 		};
 		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;
@@ -519,9 +536,14 @@ export async function runCookEntry(
 	if (!snapshot) {
 		const root = findRepoRoot(cwd) ?? cwd;
 		const projectName = path.basename(root);
-		const proposal = 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, {
@@ -559,9 +581,14 @@ export async function runCookEntry(
 	if (!goal) {
 		if (workflowDone) {
 			const projectName = path.basename(snapshot.files.root);
-			const proposal = 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, {
@@ -583,22 +610,32 @@ 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") {
+				deps.emitCommandText(ctx, assessment.blockedFailureMessage ?? buildCookStructuredDiscussionFailureMessage(deps), "info");
+				return;
+			}
 			if (!assessment.proposal || assessment.action === "continue") {
 				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");
@@ -610,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");
@@ -631,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);