@linimin/pi-letscook 0.1.57 → 0.1.59

package/scripts/refocus-test.sh

@@ -47,15 +47,99 @@ with session_path.open('w', encoding='utf-8') as fh:
 PY
 }
 
+write_session_messages() {
+  local session_path="$1"
+  local cwd="$2"
+  local messages_json="$3"
+  python3 - "$session_path" "$cwd" "$messages_json" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+session_path = Path(sys.argv[1])
+cwd = sys.argv[2]
+messages = json.loads(sys.argv[3])
+session_path.parent.mkdir(parents=True, exist_ok=True)
+entries = [
+    {
+        "type": "session",
+        "version": 3,
+        "id": "11111111-1111-4111-8111-111111111111",
+        "timestamp": "2026-01-01T00:00:00.000Z",
+        "cwd": cwd,
+    },
+]
+parent_id = None
+for index, message in enumerate(messages, start=1):
+    entry_id = f"m{index:04d}"
+    entries.append({
+        "type": "message",
+        "id": entry_id,
+        "parentId": parent_id,
+        "timestamp": f"2026-01-01T00:00:{index:02d}.000Z",
+        "message": {
+            "role": message["role"],
+            "content": message["content"],
+            "timestamp": 1767225600000 + index * 1000,
+        },
+    })
+    parent_id = entry_id
+with session_path.open('w', encoding='utf-8') as fh:
+    for entry in entries:
+        fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+PY
+}
+
 cd "$TMPDIR"
 git init -q
 
 BOOTSTRAP_SESSION="$TMPDIR/session-bootstrap.jsonl"
-BOOTSTRAP_DISCUSSION=$'Mission: Smoke-test mission.\nScope:\n- Bootstrap a completion workflow for the refocus regression fixture.\nConstraints:\n- Use supported bare /cook discussion flow only.\nAcceptance:\n- Materialize canonical state for active-workflow refocus tests.'
-write_session "$BOOTSTRAP_SESSION" "$TMPDIR" "$BOOTSTRAP_DISCUSSION"
+BOOTSTRAP_MESSAGES="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Smoke-test mission.",
+    "scope": [
+        "Bootstrap a completion workflow for the refocus regression fixture."
+    ],
+    "constraints": [
+        "Keep active-workflow refocus behavior under the explicit-handoff startup contract."
+    ],
+    "acceptance": [
+        "Bootstrap canonical refocus-fixture state for the active-workflow regression.",
+        "Verify the refocus regression with npm run refocus-test."
+    ],
+    "risks": [],
+    "notes": [
+        "Use explicit primary-agent handoff startup for the refocus regression fixture."
+    ],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Bootstrap the refocus regression fixture from a fresh explicit handoff.",
+    "first_slice_non_goals": [],
+    "implementation_surfaces": [
+        "scripts/refocus-test.sh"
+    ],
+    "verification_commands": [
+        "npm run refocus-test"
+    ],
+    "why_this_slice_first": "The refocus regression fixture needs canonical state before active-workflow routing can be exercised.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "The active-workflow refocus regression needs a fresh explicit startup boundary."
+}
+messages = [
+    {"role": "user", "content": "Prepare the refocus regression fixture and tell me when it is ready for /cook."},
+    {"role": "assistant", "content": "The refocus regression fixture is ready for /cook.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
+]
+print(json.dumps(messages, ensure_ascii=False))
+PY
+)"
+write_session_messages "$BOOTSTRAP_SESSION" "$TMPDIR" "$BOOTSTRAP_MESSAGES"
 
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
-PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
 pi --session "$BOOTSTRAP_SESSION" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-refocus-bootstrap.out" 2>"$TMPDIR/pi-completion-refocus-bootstrap.err" &
 PI_PID=$!
 for _ in $(seq 1 60); do
@@ -139,11 +223,51 @@ assert before == after, 'active /cook inline-args rejection should leave canonic
 PY
 
 SESSION_INITIAL_REFOCUS="$TMPDIR/session-initial-bare-refocus.jsonl"
-INITIAL_REFOCUS_DISCUSSION=$'Mission: Remove completion status line, keep widget.\nScope:\n- Replace the initial smoke-test workflow with the widget mission.\nConstraints:\n- Keep the approval-only Start/Cancel refocus gate.\nAcceptance:\n- Rewrite canonical state only after the replacement mission is approved.'
 INITIAL_REFOCUS_ROUTING="$TMPDIR/initial-bare-refocus-routing.json"
-write_session "$SESSION_INITIAL_REFOCUS" "$TMPDIR" "$INITIAL_REFOCUS_DISCUSSION"
+INITIAL_REFOCUS_MESSAGES="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Remove completion status line, keep widget.",
+    "scope": [
+        "Replace the initial smoke-test workflow with the widget mission."
+    ],
+    "constraints": [
+        "Keep the approval-only Start/Cancel refocus gate."
+    ],
+    "acceptance": [
+        "Rewrite canonical state only after the replacement mission is approved."
+    ],
+    "risks": [],
+    "notes": [
+        "Use a fresh explicit primary-agent handoff for the active-workflow replacement."
+    ],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Replace the initial smoke-test workflow with the widget mission.",
+    "first_slice_non_goals": [],
+    "implementation_surfaces": [
+        "scripts/refocus-test.sh"
+    ],
+    "verification_commands": [
+        "npm run refocus-test"
+    ],
+    "why_this_slice_first": "The fresh explicit handoff is the only supported replacement entry while a workflow is active.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "A different active workflow is ready and explicitly handed off by the primary agent."
+}
+messages = [
+    {"role": "user", "content": "The smoke-test workflow is active, but a different replacement workflow may now be ready."},
+    {"role": "assistant", "content": "Use this fresh explicit handoff if you want /cook to replace the active workflow.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
+]
+print(json.dumps(messages, ensure_ascii=False))
+PY
+)"
+write_session_messages "$SESSION_INITIAL_REFOCUS" "$TMPDIR" "$INITIAL_REFOCUS_MESSAGES"
 
-PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
 PI_COMPLETION_EXISTING_WORKFLOW_ACTION=refocus \
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
 PI_COMPLETION_TEST_ACTIVE_WORKFLOW_ROUTING_PATH="$INITIAL_REFOCUS_ROUTING" \
@@ -188,9 +312,10 @@ assert active['status'] == 'idle', 'active-slice.json status should reset to idl
 assert routing['mode'] == 'bare', 'supported refocus should use bare active-workflow routing mode'
 assert 'explicitGoal' not in routing, 'supported bare refocus should not expose removed explicit-goal shim fields'
 assert 'explicitGoalProvided' not in routing, 'supported bare refocus should not expose removed explicit-goal shim fields'
-assert routing['action'] == 'refocus', 'supported bare /cook should classify as refocus when the mission changes'
-assert routing['reason'] == 'clear_refocus', 'supported bare /cook should record the clear-refocus routing reason'
-assert routing['proposedMissionAnchor'] == new_anchor, 'bare refocus routing snapshot should expose the replacement mission anchor'
+assert routing['action'] == 'refocus', 'supported bare /cook should classify as refocus when a fresh explicit handoff proposes a different mission'
+assert routing['reason'] == 'fresh_explicit_handoff', 'supported bare /cook should record the explicit-handoff replacement reason'
+assert routing['proposedMissionAnchor'] == new_anchor, 'explicit handoff routing snapshot should expose the replacement mission anchor'
+assert routing['proposalSource'] == 'handoff_capsule', 'explicit handoff routing snapshot should preserve the handoff source'
 PY
 
 UPDATED_MISSION="$(python3 - <<'PY'
@@ -206,16 +331,58 @@ if [[ "$INITIAL_MISSION" == "$UPDATED_MISSION" ]]; then
   exit 1
 fi
 
-# Negated replacement missions that contain the current anchor must still reach the conservative chooser and final Start/Cancel gate.
-BARE_REFOCUS_MISSION='Do not remove completion status line, keep widget.'
-BARE_REFOCUS_DISCUSSION=$'Mission: Do not remove completion status line, keep widget.\nScope:\n- Treat the active bare /cook discussion as a replacement workflow rather than a resume.\n- Keep the replacement behind the existing approval-only Start/Cancel gate.\nConstraints:\n- Do not rewrite canonical state before the final Start confirmation.\nAcceptance:\n- Add deterministic coverage proving the chooser and final approval path for this negated replacement mission.'
+# Fresh explicit handoff replacements must still reach the chooser and final Start/Cancel gate while the
+# workflow is active.
+BARE_REFOCUS_MISSION='Exercise explicit active-workflow replacement coverage.'
+BARE_REFOCUS_MESSAGES="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Exercise explicit active-workflow replacement coverage.",
+    "scope": [
+        "Treat the active bare /cook request as an explicit replacement workflow.",
+        "Keep the replacement behind the existing approval-only Start/Cancel gate."
+    ],
+    "constraints": [
+        "Do not rewrite canonical state before the final Start confirmation."
+    ],
+    "acceptance": [
+        "Add deterministic coverage proving the chooser and final approval path for this explicit replacement mission."
+    ],
+    "risks": [],
+    "notes": [
+        "This replacement should come only from the fresh explicit handoff, not recent discussion inference."
+    ],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Exercise the active-workflow explicit-handoff replacement path.",
+    "first_slice_non_goals": [],
+    "implementation_surfaces": [
+        "scripts/refocus-test.sh"
+    ],
+    "verification_commands": [
+        "npm run refocus-test"
+    ],
+    "why_this_slice_first": "The active workflow should only replace from a fresh explicit handoff.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "The primary agent explicitly handed off a replacement workflow while the current one is active."
+}
+messages = [
+    {"role": "user", "content": "The current workflow is active, but there is a fresh explicit replacement handoff ready."},
+    {"role": "assistant", "content": "Use this fresh explicit handoff if you want /cook to replace the active workflow.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
+]
+print(json.dumps(messages, ensure_ascii=False))
+PY
+)"
 
 SESSION_BARE_CHOOSER_CANCEL="$TMPDIR/session-bare-chooser-cancel.jsonl"
 BARE_CHOOSER_SNAPSHOT="$TMPDIR/bare-existing-workflow-chooser.json"
 BARE_ROUTING_CHOOSER_CANCEL="$TMPDIR/bare-routing-chooser-cancel.json"
-write_session "$SESSION_BARE_CHOOSER_CANCEL" "$TMPDIR" "$BARE_REFOCUS_DISCUSSION"
+write_session_messages "$SESSION_BARE_CHOOSER_CANCEL" "$TMPDIR" "$BARE_REFOCUS_MESSAGES"
 
-PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
 PI_COMPLETION_EXISTING_WORKFLOW_ACTION=cancel \
 PI_COMPLETION_TEST_EXISTING_WORKFLOW_CHOOSER_PATH="$BARE_CHOOSER_SNAPSHOT" \
 PI_COMPLETION_TEST_ACTIVE_WORKFLOW_ROUTING_PATH="$BARE_ROUTING_CHOOSER_CANCEL" \
@@ -243,13 +410,14 @@ assert active['mission_anchor'] == updated_mission, 'chooser cancel should keep
 assert routing['mode'] == 'bare', 'bare /cook should snapshot bare active-workflow routing mode'
 assert 'explicitGoal' not in routing, 'bare chooser routing should not expose removed explicit-goal shim fields'
 assert 'explicitGoalProvided' not in routing, 'bare chooser routing should not expose removed explicit-goal shim fields'
-assert routing['action'] == 'refocus', 'clear structured discussion should classify active bare /cook as refocus'
-assert routing['reason'] == 'clear_refocus', 'clear structured discussion should record the clear-refocus routing reason'
-assert routing['currentMissionAnchor'] == updated_mission, 'clear-refocus routing should keep the current mission anchor until the user approves replacement'
-assert routing['proposedMissionAnchor'] == replacement_mission, 'clear-refocus routing should expose the proposed replacement mission'
+assert routing['action'] == 'refocus', 'fresh explicit replacement handoff should classify active bare /cook as refocus'
+assert routing['reason'] == 'fresh_explicit_handoff', 'fresh explicit replacement handoff should record the explicit-handoff reason'
+assert routing['currentMissionAnchor'] == updated_mission, 'explicit-handoff routing should keep the current mission anchor until the user approves replacement'
+assert routing['proposedMissionAnchor'] == replacement_mission, 'explicit-handoff routing should expose the proposed replacement mission'
+assert routing['proposalSource'] == 'handoff_capsule', 'explicit-handoff routing should preserve the handoff source'
 assert chooser['title'].startswith('Existing completion workflow found'), 'bare chooser snapshot should describe the existing-workflow prompt'
 assert chooser['choices'][0].startswith('Continue current workflow'), 'bare chooser should keep the continue option'
-assert chooser['choices'][1].startswith('Start new workflow from recent discussion'), 'bare chooser should offer the recent-discussion refocus option'
+assert chooser['choices'][1].startswith('Start new workflow from explicit primary-agent handoff'), 'bare chooser should offer the explicit-handoff replacement option'
 assert 'Start/Cancel confirmation' in chooser['choices'][1], 'bare chooser should mention the approval-only replacement confirmation'
 assert chooser['choices'][2].startswith('Cancel'), 'bare chooser should keep the cancel option'
 assert 'Discuss changes in the main chat and rerun /cook.' in output, 'bare chooser cancel should redirect users back to the main chat and rerun /cook'
@@ -258,9 +426,8 @@ PY
 SESSION_BARE_FINAL_CANCEL="$TMPDIR/session-bare-final-cancel.jsonl"
 BARE_ROUTING_FINAL_CANCEL="$TMPDIR/bare-routing-final-cancel.json"
 BARE_PROPOSAL_CANCEL="$TMPDIR/bare-replacement-proposal-cancel.json"
-write_session "$SESSION_BARE_FINAL_CANCEL" "$TMPDIR" "$BARE_REFOCUS_DISCUSSION"
+write_session_messages "$SESSION_BARE_FINAL_CANCEL" "$TMPDIR" "$BARE_REFOCUS_MESSAGES"
 
-PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
 PI_COMPLETION_EXISTING_WORKFLOW_ACTION=refocus \
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=cancel \
 PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$BARE_PROPOSAL_CANCEL" \
@@ -286,19 +453,19 @@ active = json.loads(Path('.agent/active-slice.json').read_text())
 assert state['mission_anchor'] == updated_mission, 'final Start/Cancel cancel should keep the current mission anchor'
 assert plan['mission_anchor'] == updated_mission, 'final Start/Cancel cancel should keep plan.json unchanged'
 assert active['mission_anchor'] == updated_mission, 'final Start/Cancel cancel should keep active-slice.json unchanged'
-assert routing['action'] == 'refocus', 'final Start/Cancel cancel should still come from a clear-refocus classification'
-assert routing['reason'] == 'clear_refocus', 'final Start/Cancel cancel should preserve the clear-refocus reason'
+assert routing['action'] == 'refocus', 'final Start/Cancel cancel should still come from an explicit-handoff refocus classification'
+assert routing['reason'] == 'fresh_explicit_handoff', 'final Start/Cancel cancel should preserve the explicit-handoff reason'
 assert routing['currentMissionAnchor'] == updated_mission, 'final Start/Cancel cancel should keep the current mission anchor until the user approves replacement'
 assert proposal['mission'] == replacement_mission, 'final Start/Cancel cancel should still prepare the replacement proposal before rewriting state'
+assert proposal['source'] == 'handoff_capsule', 'final Start/Cancel cancel should preserve the explicit-handoff proposal source'
 assert 'Discuss changes in the main chat and rerun /cook.' in output, 'final Start/Cancel cancel should redirect users back to the main chat and rerun /cook'
 PY
 
 SESSION_BARE_ACCEPT="$TMPDIR/session-bare-accept.jsonl"
 BARE_ROUTING_ACCEPT="$TMPDIR/bare-routing-accept.json"
 BARE_PROPOSAL_ACCEPT="$TMPDIR/bare-replacement-proposal-accept.json"
-write_session "$SESSION_BARE_ACCEPT" "$TMPDIR" "$BARE_REFOCUS_DISCUSSION"
+write_session_messages "$SESSION_BARE_ACCEPT" "$TMPDIR" "$BARE_REFOCUS_MESSAGES"
 
-PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
 PI_COMPLETION_EXISTING_WORKFLOW_ACTION=refocus \
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
 PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$BARE_PROPOSAL_ACCEPT" \
@@ -312,7 +479,7 @@ import json
 import sys
 from pathlib import Path
 
-new_anchor = 'Do not remove completion status line, keep widget.'
+new_anchor = 'Exercise explicit active-workflow replacement coverage.'
 expected_task_type = 'completion-workflow'
 expected_eval_profile = 'completion-rubric-v1'
 proposal = json.loads(Path(sys.argv[1]).read_text())
@@ -327,9 +494,10 @@ assert proposal['mission'] == new_anchor, 'accepted bare refocus should preserve
 assert routing['mode'] == 'bare', 'accepted bare refocus should keep bare routing mode'
 assert 'explicitGoal' not in routing, 'accepted bare refocus should not expose removed explicit-goal shim fields'
 assert 'explicitGoalProvided' not in routing, 'accepted bare refocus should not expose removed explicit-goal shim fields'
-assert routing['action'] == 'refocus', 'accepted bare refocus should keep the clear-refocus classification'
-assert routing['reason'] == 'clear_refocus', 'accepted bare refocus should keep the clear-refocus reason'
+assert routing['action'] == 'refocus', 'accepted bare refocus should keep the explicit-handoff refocus classification'
+assert routing['reason'] == 'fresh_explicit_handoff', 'accepted bare refocus should keep the explicit-handoff reason'
 assert routing['currentMissionAnchor'] == 'Remove completion status line, keep widget.', 'accepted bare refocus should expose the original mission until Start is accepted'
+assert routing['proposalSource'] == 'handoff_capsule', 'accepted bare refocus should preserve the explicit-handoff source'
 assert new_anchor in mission_text, '.agent/mission.md did not update to the bare refocus mission anchor'
 assert profile['task_type'] == expected_task_type, 'profile.json task_type mismatch after bare refocus'
 assert profile['evaluation_profile'] == expected_eval_profile, 'profile.json evaluation_profile mismatch after bare refocus'

package/scripts/release-check.sh

@@ -3,6 +3,7 @@ set -euo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$ROOT"
+export PI_COMPLETION_RUNNING_RELEASE_CHECK=1
 
 echo "[release-check] running control-plane validation, tracked .agent contract coverage, slice-surface parity, explicit-/cook parity, startup/refocus/context regressions, canonical evidence artifact, active-slice contract, observability, legacy cleanup, evaluator calibration, and rubric contract coverage"
 bash .agent/verify_completion_control_plane.sh
@@ -10,45 +11,51 @@ git ls-files --error-unmatch .agent/README.md .agent/mission.md .agent/profile.j
 
 echo "[release-check] verifying public /cook parity and explicit-entry docs/help"
 python3 - <<'PY'
-import re
 from pathlib import Path
 
 checks = {
     "README.md": [
         "`/cook` is the explicit workflow boundary for starting, continuing, refocusing, or beginning the next round of long-running repo work.",
         "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.",
-        "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.",
-        "`/cook` first looks for a fresh explicit primary-agent handoff capsule.",
-        "The pre-`/cook` handoff capsule itself is not canonical workflow state. It is only startup intake for `/cook`.",
+        "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.",
+        "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.",
+        "- 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",
+        "`/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.",
+        "Without one, `/cook` fails closed instead of deriving the next round from recent discussion.",
+        "when a fresh explicit handoff suggests replacing an active workflow, `/cook` shows a chooser before any canonical state rewrite",
     ],
     "CHANGELOG.md": [
-        "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 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",
+        "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",
+        "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",
     ],
     "extensions/completion/prompt-surfaces.ts": [
         '"/cook is the only explicit entrypoint into long-running completion workflow."',
-        '"When you judge that the task has matured into completion-workflow scope',
-        '"Also append one exact fenced block in the same assistant reply using ```cook_handoff ... ``` JSON',
+        '"If the user keeps asking follow-up questions or refining requirements before /cook, continue that ordinary-chat discussion normally instead of switching into a handoff-only refusal mode, but do not act as though /cook had already been invoked."',
+        '"When handing off, explain that /cook can start a new workflow or next round only from a fresh valid explicit primary-agent handoff capsule from recent ordinary-chat discussion; otherwise it fails closed, while already-active workflows resume from canonical .agent state unless a fresh valid explicit handoff proposes replacement."',
         '"The capsule is startup intake for /cook only: do not present it as canonical .agent state',
     ],
+    "extensions/completion/index.ts": [
+        '"/cook failed closed because new-workflow startup now requires a fresh valid explicit primary-agent handoff from recent ordinary-chat discussion; recent discussion alone no longer starts a workflow. Ask the primary agent to hand off explicitly in the main chat, then rerun /cook."',
+        'description: "/cook workflow: start a new workflow or next round only from a fresh recent explicit primary-agent handoff, resume the current workflow from canonical state, or confirm an explicit replacement from the explicit /cook command"',
+    ],
 }
 
 forbidden = {
     "README.md": [
-        "`/cook <hint>`",
-        "Natural-language routing is optional and shipped in two modes",
-        "PI_COMPLETION_TRIGGER_MODE",
-        "workflow-aware router",
-        "Send as normal chat",
-        "bash ./scripts/cook-trigger-routing-test.sh",
+        "Start a new workflow from recent discussion:",
+        "`/cook` falls back to deriving a startup brief from recent discussion only when no fresh explicit handoff is blocking startup",
+        "Without a fresh explicit handoff blocking startup, `/cook` can fall back to recent discussion.",
+    ],
+    "extensions/completion/prompt-surfaces.ts": [
+        '"When handing off, explain that /cook will first look for a fresh explicit primary-agent handoff capsule and otherwise fall back to recent discussion."',
     ],
-    "CHANGELOG.md": ["compatibility" + " shim"],
     "extensions/completion/index.ts": [
-        'description: "/cook workflow: start, continue, refocus, or start the next round from an explicit /cook command"',
-        '"/cook failed closed because recent discussion did not produce a clear execution-ready Mission/Scope/Constraints/Acceptance proposal for concrete repo changes. Clarify the concrete repo changes in the main chat and rerun /cook."',
-        'handleCookNaturalLanguageTrigger',
+        'description: "/cook workflow: derive a startup brief from recent discussion, then start, continue, refocus, or start the next round from the explicit /cook command"',
+        '"/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."',
     ],
 }
 
@@ -62,7 +69,7 @@ for path, needles in forbidden.items():
     text = Path(path).read_text()
     for needle in needles:
         if needle in text:
-            raise SystemExit(f"[release-check] found stale compatibility wording in {path}: {needle}")
+            raise SystemExit(f"[release-check] found stale /cook parity text in {path}: {needle}")
 PY
 
 npm run smoke-test
@@ -75,6 +82,28 @@ npm run observability-status-test
 bash ./scripts/legacy-cleanup-test.sh
 npm run evaluator-calibration-test
 npm run rubric-contract-test
-npm pack --dry-run >/dev/null
+
+echo "[release-check] verifying packaged .agent contract files in npm pack output"
+PACK_JSON="$(npm pack --dry-run --json)"
+python3 - "$PACK_JSON" <<'PY'
+import json
+import sys
+
+required = {
+    '.agent/README.md',
+    '.agent/mission.md',
+    '.agent/profile.json',
+    '.agent/verify_completion_stop.sh',
+    '.agent/verify_completion_control_plane.sh',
+}
+
+payload = json.loads(sys.argv[1])
+if not isinstance(payload, list) or not payload:
+    raise SystemExit('[release-check] npm pack --dry-run --json returned no package payload')
+files = {item.get('path') for item in payload[0].get('files', []) if isinstance(item, dict)}
+missing = sorted(required - files)
+if missing:
+    raise SystemExit(f"[release-check] npm pack --dry-run is missing tracked .agent contract files: {', '.join(missing)}")
+PY
 
 echo "release check passed"

package/scripts/smoke-test.sh

@@ -47,6 +47,49 @@ with session_path.open('w', encoding='utf-8') as fh:
 PY
 }
 
+write_session_messages() {
+  local session_path="$1"
+  local cwd="$2"
+  local messages_json="$3"
+  python3 - "$session_path" "$cwd" "$messages_json" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+session_path = Path(sys.argv[1])
+cwd = sys.argv[2]
+messages = json.loads(sys.argv[3])
+session_path.parent.mkdir(parents=True, exist_ok=True)
+entries = [
+    {
+        "type": "session",
+        "version": 3,
+        "id": "11111111-1111-4111-8111-111111111111",
+        "timestamp": "2026-01-01T00:00:00.000Z",
+        "cwd": cwd,
+    },
+]
+parent_id = None
+for index, message in enumerate(messages, start=1):
+    entry_id = f"m{index:04d}"
+    entries.append({
+        "type": "message",
+        "id": entry_id,
+        "parentId": parent_id,
+        "timestamp": f"2026-01-01T00:00:{index:02d}.000Z",
+        "message": {
+            "role": message["role"],
+            "content": message["content"],
+            "timestamp": 1767225600000 + index * 1000,
+        },
+    })
+    parent_id = entry_id
+with session_path.open('w', encoding='utf-8') as fh:
+    for entry in entries:
+        fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+PY
+}
+
 ROOT="$TMPDIR/repo"
 KICKOFF_PROMPT="$TMPDIR/kickoff-prompt.txt"
 RESUME_PROMPT="$TMPDIR/resume-prompt.txt"
@@ -60,7 +103,55 @@ INLINE_REJECTION_ROUTING_SNAPSHOT="$TMPDIR/inline-arg-routing.json"
 INLINE_REJECTION_PROPOSAL_SNAPSHOT="$TMPDIR/inline-arg-proposal.json"
 INLINE_REJECTION_CHOOSER_SNAPSHOT="$TMPDIR/inline-arg-chooser.json"
 BOOTSTRAP_SESSION="$TMPDIR/session-smoke-bootstrap.jsonl"
-BOOTSTRAP_DISCUSSION=$'Mission: Exercise smoke-test bootstrap.\nScope:\n- Materialize the canonical completion control-plane files.\n- Keep the smoke test on supported /cook startup behavior.\nConstraints:\n- Keep startup proposal confirmation approval-only.\nAcceptance:\n- Scaffold canonical files and kickoff prompts for the smoke fixture.'
+BOOTSTRAP_MESSAGES="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Exercise smoke-test bootstrap.",
+    "scope": [
+        "Materialize the canonical completion control-plane files.",
+        "Keep the smoke test on supported /cook startup behavior."
+    ],
+    "constraints": [
+        "Keep startup proposal confirmation approval-only."
+    ],
+    "acceptance": [
+        "Scaffold .agent/profile.json, .agent/state.json, .agent/plan.json, .agent/active-slice.json, and .agent/verification-evidence.json for the smoke fixture.",
+        "Keep scripts/smoke-test.sh and kickoff-prompt coverage truthful for packaged bootstrap."
+    ],
+    "risks": [
+        "Smoke-test bootstrap should stay anchored to the fresh explicit handoff."
+    ],
+    "notes": [
+        "Keep the smoke fixture aligned with the shipped explicit-handoff-only startup contract."
+    ],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Scaffold canonical completion files and verify the packaged startup contract.",
+    "first_slice_non_goals": [
+        "Do not broaden the smoke fixture beyond the packaged startup surfaces."
+    ],
+    "implementation_surfaces": [
+        ".agent/README.md",
+        "scripts/smoke-test.sh"
+    ],
+    "verification_commands": [
+        "npm run smoke-test"
+    ],
+    "why_this_slice_first": "The packaged explicit-handoff startup path must work before later workflow verification can run.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "The startup handoff is concrete enough to bootstrap canonical workflow files."
+}
+messages = [
+    {"role": "user", "content": "Please prepare the packaged smoke-test bootstrap path and tell me when it is ready for /cook."},
+    {"role": "assistant", "content": "This bootstrap path is ready for /cook. Run /cook to confirm the startup brief.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
+]
+print(json.dumps(messages, ensure_ascii=False))
+PY
+)"
 
 mkdir -p "$ROOT"
 cd "$ROOT"
@@ -89,7 +180,7 @@ assert not chooser.exists(), 'startup /cook inline-args rejection should not ope
 assert '/cook no longer accepts inline arguments.' in output, 'startup /cook inline-args rejection should explain the bare-only entry contract'
 PY
 
-write_session "$BOOTSTRAP_SESSION" "$ROOT" "$BOOTSTRAP_DISCUSSION"
+write_session_messages "$BOOTSTRAP_SESSION" "$ROOT" "$BOOTSTRAP_MESSAGES"
 
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
 PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
@@ -133,11 +224,17 @@ assert active['implementation_surfaces'] == [], 'active-slice.json should scaffo
 assert active['verification_commands'] == [], 'active-slice.json should scaffold empty verification_commands'
 brief = state['advisory_startup_brief']
 assert brief['kind'] == 'startup_brief', 'state.json should preserve the confirmed startup brief as advisory intake'
+assert brief['source'] == 'primary_agent_handoff', 'smoke bootstrap should record the explicit handoff source in advisory intake'
 assert brief['mission'] == state['mission_anchor'], 'advisory startup brief mission should match the canonical mission anchor after bootstrap'
 assert brief['scope'] == ['Materialize the canonical completion control-plane files.', 'Keep the smoke test on supported /cook startup behavior.'], 'advisory startup brief should preserve scope items'
 assert brief['constraints'] == ['Keep startup proposal confirmation approval-only.'], 'advisory startup brief should preserve constraints'
-assert brief['acceptance'] == ['Scaffold canonical files and kickoff prompts for the smoke fixture.'], 'advisory startup brief should preserve acceptance'
-assert brief['notes'] == ['No additional operator notes were derived from recent discussion.'], 'advisory startup brief should still preserve operator-note structure when no explicit notes exist'
+assert brief['acceptance'] == [
+    'Scaffold .agent/profile.json, .agent/state.json, .agent/plan.json, .agent/active-slice.json, and .agent/verification-evidence.json for the smoke fixture.',
+    'Keep scripts/smoke-test.sh and kickoff-prompt coverage truthful for packaged bootstrap.'
+], 'advisory startup brief should preserve acceptance'
+assert brief['risks'] == ['Smoke-test bootstrap should stay anchored to the fresh explicit handoff.'], 'advisory startup brief should preserve handoff risks'
+assert 'First slice goal: Scaffold canonical completion files and verify the packaged startup contract.' in brief['notes'], 'advisory startup brief should preserve the first_slice_goal in notes'
+assert 'Verification commands: npm run smoke-test' in brief['notes'], 'advisory startup brief should preserve verification_commands in notes'
 assert evidence['artifact_type'] == 'completion-verification-evidence', 'verification-evidence.json artifact_type mismatch after bootstrap'
 assert evidence['subject_type'] == 'none', 'verification-evidence.json should scaffold idle subject_type'
 assert evidence['verification_commands'] == [], 'verification-evidence.json should scaffold empty verification_commands'
@@ -169,9 +266,17 @@ assert not reminder.exists(), 'ordinary non-/cook turn should not inject complet
 assert handoff.exists(), 'ordinary non-/cook turn should inject the /cook handoff boundary reminder'
 handoff_text = handoff.read_text()
 assert '/cook is the only explicit entrypoint into long-running completion workflow.' in handoff_text, 'ordinary handoff reminder should preserve the explicit /cook workflow boundary'
-assert 'stop short of long-running implementation and tell the user to run /cook.' in handoff_text, 'ordinary handoff reminder should require primary-agent handoff before implementation'
+assert 'do not begin long-running product implementation in ordinary chat' in handoff_text, 'ordinary handoff reminder should block workflow-level implementation before /cook'
+assert 'recommend /cook as the workflow boundary while keeping the conversation in ordinary chat until the user explicitly runs /cook.' in handoff_text, 'ordinary handoff reminder should keep pre-/cook discussion advisory-first'
+assert 'continue that ordinary-chat discussion normally instead of switching into a handoff-only refusal mode' in handoff_text, 'ordinary handoff reminder should avoid hard refusal mode before explicit /cook'
 assert '```cook_handoff ... ``` JSON' in handoff_text, 'ordinary handoff reminder should require the explicit structured /cook handoff capsule'
+assert 'implementation_workflow_handoff' in handoff_text, 'ordinary handoff reminder should require the implementation-ready handoff kind'
+assert 'first_slice_goal, first_slice_non_goals, implementation_surfaces, verification_commands, why_this_slice_first' in handoff_text, 'ordinary handoff reminder should require first-slice startability fields'
 assert 'The capsule is startup intake for /cook only' in handoff_text, 'ordinary handoff reminder should keep the capsule non-canonical'
+assert 'fresh valid explicit primary-agent handoff capsule from recent ordinary-chat discussion' in handoff_text, 'ordinary handoff reminder should describe recent explicit-handoff startup truthfully'
+assert 'fails closed' in handoff_text, 'ordinary handoff reminder should describe fail-closed startup when no fresh valid handoff exists'
+assert 'resume from canonical .agent state' in handoff_text, 'ordinary handoff reminder should preserve active-workflow canonical resume wording'
+assert 'fall back to recent discussion' not in handoff_text, 'ordinary handoff reminder should no longer promise recent-discussion startup fallback'
 assert not auto_resume.exists(), 'ordinary non-/cook turn should not queue auto-resume before /cook activation'
 assert 'Skipped completion workflow auto-resume prompt (test mode)' not in output, 'ordinary non-/cook turn should not attempt auto-resume'
 PY
@@ -199,11 +304,11 @@ assert 'Canonical routing profile:' in resume, 'resume prompt should expose cano
 assert f'- task_type: {expected_task_type}' in resume, 'resume prompt missing canonical task_type'
 assert f'- evaluation_profile: {expected_eval_profile}' in resume, 'resume prompt missing canonical evaluation_profile'
 assert routing['mode'] == 'bare', 'active bare /cook should snapshot bare routing mode'
-assert routing['action'] == 'unclear', 'no-discussion active bare /cook should classify as unclear'
-assert routing['reason'] == 'missing_proposal', 'no-discussion active bare /cook should fail closed because no replacement proposal was derived'
-assert routing['currentMissionAnchor'] == state['mission_anchor'], 'unclear routing snapshot should keep the current mission anchor'
-assert routing['proposedMissionAnchor'] is None, 'unclear no-discussion routing should not propose a replacement mission'
-assert not chooser_path.exists(), 'unclear active bare /cook should fall back to resume without opening the chooser'
+assert routing['action'] == 'continue', 'no-discussion active bare /cook should resume from canonical state without a fresh explicit handoff'
+assert routing['reason'] == 'missing_explicit_handoff', 'no-discussion active bare /cook should explain that resume happened because no fresh explicit handoff existed'
+assert routing['currentMissionAnchor'] == state['mission_anchor'], 'resume routing snapshot should keep the current mission anchor'
+assert routing['proposedMissionAnchor'] is None, 'no-discussion active bare /cook should not propose a replacement mission'
+assert not chooser_path.exists(), 'active bare /cook resume should not open the chooser without a fresh explicit handoff'
 PY
 
 PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \