@linimin/pi-letscook 0.1.58 → 0.1.60

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:
+Refactor the /cook startup boundary into the agreed mixed model: ordinary chat stays advisory-first by default with no default pre-/cook handoff capsule formation, while explicit /cook performs structured startup synthesis from recent discussion and preserves the approval-only Start/Cancel gate.
+
+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,18 @@
 
 ## Unreleased
 
+## 0.1.60
+
+## 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 moving default startup and done-workflow next-round synthesis to bare `/cook` from recent ordinary-chat discussion behind the existing **Start** / **Cancel** approval gate
+- kept pre-`/cook` previews or `cook_handoff` capsules opt-in only, non-canonical, and advisory until the user explicitly runs `/cook`; bare `/cook` no longer depends on a default prebuilt capsule for new-workflow startup
+- kept active workflows resuming from canonical `.agent/**` state unless a fresh explicit handoff proposes a replacement, so discussion-only context does not silently rewrite an in-progress workflow
+- updated public parity and packaged release verification so README/help/changelog/release-check all describe and gate the shipped mixed model truthfully, while still packaging the tracked `.agent` contract files
+
 ## 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,22 +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, then run `/cook` once the recent discussion is specific enough for a startup brief. If you explicitly want a pre-`/cook` preview or capsule first, ask for one. |
 | 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, then run `/cook` to synthesize the next startup brief. Active-workflow replacement still stays explicit and confirm-first. |
 
 ## What `/cook` expects
 
-- preferably a fresh explicit primary-agent `/cook` handoff capsule from the immediately preceding ordinary-chat turn
-- 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
+- recent ordinary-chat discussion concrete enough for bare `/cook` to synthesize a startup brief for a new workflow or the next round after a completed workflow
+- enough repo-change detail for that startup brief to stay implementation-oriented once you review it behind **Start** or **Cancel**
 - 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
+- assistant-produced summaries and plan/spec/design-doc/proposal-only artifacts still do not become canonical workflow state by themselves
+- any pre-`/cook` preview or `cook_handoff` capsule only when you explicitly ask for it; that preview stays advisory startup intake, not canonical `.agent/**` state
+- active-workflow replacement still stays conservative: `/cook` resumes from canonical state unless a fresh explicit handoff proposes a different concrete repo change and you confirm that replacement
 
-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 recent discussion is too weak, ambiguous, stale, or planning-only for new-workflow or next-round entry, `/cook` fails closed, leaves canonical `.agent/**` state unchanged, and tells you to clarify the concrete repo change 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 explicitly asked for a preview capsule and it is still workflow-worthy rather than implementation-startable, `/cook` also fails closed instead of silently treating that preview 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`.
 
@@ -66,15 +66,19 @@ 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.
+If you explicitly ask for a pre-`/cook` preview or capsule, the primary agent may provide one, but that preview is opt-in only and stays non-canonical until you later run `/cook` and choose **Start**.
+
+Bare `/cook` is still the canonical workflow boundary: it synthesizes the startup brief from recent ordinary-chat discussion at `/cook` time, then waits for **Start** or **Cancel** before any canonical `.agent/**` write.
 
 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: bare `/cook` synthesizes the startup brief from recent discussion, then waits for **Start** or **Cancel**
+- active workflows resume from canonical `.agent/**` state unless a fresh valid explicit handoff proposes a replacement
+- any pre-`/cook` preview or capsule is explicit-request-only and non-canonical
 - 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`
 
@@ -84,18 +88,19 @@ Start a new workflow from recent discussion:
 
 ```text
 I want to add login redirect handling and tests.
+# discuss scope until the startup brief is clear enough
 /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.
+When no workflow is active, bare `/cook` synthesizes a startup brief from recent ordinary-chat discussion and then waits for **Start** or **Cancel**. If recent discussion is too weak, ambiguous, stale, or planning-only, `/cook` fails closed instead of guessing. If you explicitly asked for a preview capsule first and that preview is fresh but still non-startable, `/cook` also fails closed instead of silently treating it as canonical state. When a workflow is already active and no fresh valid explicit replacement 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 | `/cook` synthesizes a startup brief from recent discussion and shows **Start** / **Cancel**. If recent discussion is too weak, ambiguous, stale, or planning-only, `/cook` fails closed and leaves canonical state unchanged. An explicit-request preview capsule can inform that startup brief, but it is still non-canonical until you choose **Start**. |
+| 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` | `/cook` synthesizes the next implementation round from recent discussion behind **Start** / **Cancel**. If that recent discussion is too weak or ambiguous, `/cook` fails closed and leaves the finished workflow state unchanged. |
 
 ## Confirmation and fail-closed behavior
 
@@ -103,9 +108,10 @@ 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
+- any pre-`/cook` preview or capsule is advisory only and never writes canonical workflow state by itself
+- 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.
 
@@ -258,7 +264,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 `/cook` public parity surfaces in `README.md`, `CHANGELOG.md`, and the `/cook` help/fail-closed copy in `extensions/completion/index.ts`, 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 mixed-model `/cook` public parity surfaces in `README.md`, `CHANGELOG.md`, and the `/cook` help/fail-closed copy in `extensions/completion/index.ts`, 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

@@ -60,16 +60,21 @@ type CookContextProposalResult = {
 	blockedFailureMessage?: string;
 };
 
+function buildCookStartupBriefRequiredMessage(deps: CompletionDriverDeps, prefix?: string): string {
+	const requirement =
+		"/cook failed closed because recent discussion did not produce a clear execution-ready startup brief with Mission/Scope/Constraints/Acceptance for concrete repo changes. Clarify the concrete repo changes in the main chat and rerun /cook.";
+	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;
@@ -548,7 +543,7 @@ export async function runCookEntry(
 		}
 		const proposal = derived.proposal;
 		if (!proposal) {
-			deps.emitCommandText(ctx, buildCookStructuredDiscussionFailureMessage(deps), "info");
+			deps.emitCommandText(ctx, buildCookStartupBriefRequiredMessage(deps), "info");
 			return;
 		}
 		const decision = await deps.confirmContextProposal(ctx, proposal, {
@@ -593,7 +588,7 @@ export async function runCookEntry(
 			}
 			const proposal = derived.proposal;
 			if (!proposal) {
-				deps.emitCommandText(ctx, buildCookStructuredDiscussionFailureMessage(deps, "The previous completion workflow is already done."), "info");
+				deps.emitCommandText(ctx, buildCookStartupBriefRequiredMessage(deps, "The previous completion workflow is already done."), "info");
 				return;
 			}
 			const decision = await deps.confirmContextProposal(ctx, proposal, {
@@ -615,7 +610,13 @@ 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,
+				proposal.source === "handoff_capsule"
+					? `Started a new completion workflow round from explicit primary-agent handoff: ${decision.missionAnchor}`
+					: `Started a new completion workflow round from recent discussion: ${decision.missionAnchor}`,
+				"info",
+			);
 		} else {
 			const assessment = await assessActiveWorkflowProposalRouting(ctx, snapshot, deps);
 			if (assessment.action === "blocked") {
@@ -626,15 +627,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 +653,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 +673,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);