@linimin/pi-letscook 0.1.59 → 0.1.61

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linimin/pi-letscook",
-  "version": "0.1.59",
+  "version": "0.1.61",
   "description": "Pi package for long-running completion workflows with canonical .agent state, role-based subagents, continuity, and verification helpers.",
   "license": "MIT",
   "private": false,

package/scripts/context-proposal-test.sh

@@ -147,30 +147,36 @@ mkdir -p "$ROOT"
 cd "$ROOT"
 git init -q
 
-# No workflow yet: bare /cook should fail closed without a fresh valid explicit primary-agent handoff,
-# even when recent discussion is fully structured.
+# No workflow yet: bare /cook should synthesize a deferred startup brief from recent discussion,
+# even when no explicit ordinary-chat handoff capsule exists.
 SESSION_ZERO="$TMPDIR/session-zero.jsonl"
 DISCUSSION_ZERO=$'Mission: Remove the completion status line while keeping the completion widget.\nScope:\n- Keep the non-running completion widget.\n- Suppress the widget while a completion role is active.\nConstraints:\n- Do not reintroduce any other completion status surface.\nAcceptance:\n- Update README to match the shipped behavior.\n- Keep observability regression coverage truthful.'
 DISCUSSION_SNAPSHOT_ZERO="$TMPDIR/context-proposal-structured-fallback.json"
 write_session "$SESSION_ZERO" "$ROOT" "$DISCUSSION_ZERO"
 
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
-PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
 PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$DISCUSSION_SNAPSHOT_ZERO" \
 PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
 pi --session "$SESSION_ZERO" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-context-proposal-structured-fallback.out" 2>"$TMPDIR/pi-completion-context-proposal-structured-fallback.err"
 
 python3 - "$TMPDIR/pi-completion-context-proposal-structured-fallback.out" "$TMPDIR/pi-completion-context-proposal-structured-fallback.err" "$DISCUSSION_SNAPSHOT_ZERO" <<'PY'
+import json
 import sys
 from pathlib import Path
 
 output = Path(sys.argv[1]).read_text() + Path(sys.argv[2]).read_text()
 snapshot = Path(sys.argv[3])
-assert not Path('.agent').exists(), 'missing explicit handoff should fail closed without writing canonical state'
-assert not snapshot.exists(), 'missing explicit handoff should not emit a startup proposal snapshot'
-assert 'fresh valid explicit primary-agent handoff' in output, 'missing explicit handoff should explain the explicit-handoff-only startup contract'
+assert Path('.agent').exists(), 'bare /cook should scaffold canonical state from structured recent discussion'
+assert snapshot.exists(), 'bare /cook should emit a startup proposal snapshot when recent discussion is concrete enough'
+proposal = json.loads(snapshot.read_text())
+brief = json.loads(Path('.agent/state.json').read_text())['advisory_startup_brief']
+assert proposal['source'] == 'deferred_primary_agent_handoff', 'structured startup should snapshot the deferred primary-agent handoff source'
+assert brief['source'] == 'deferred_primary_agent_handoff', 'structured startup should record the deferred primary-agent handoff source in advisory intake'
+assert 'Initialized completion control plane' in output, 'structured startup should initialize canonical workflow state'
 PY
 
+rm -rf .agent
+
 # No workflow yet: user-authored faux handoffs must not bootstrap canonical workflow state.
 SESSION_ZERO_USER_AUTHORED="$TMPDIR/session-zero-user-authored.jsonl"
 USER_AUTHORED_SNAPSHOT_ZERO="$TMPDIR/context-proposal-user-authored-handoff.json"
@@ -212,9 +218,9 @@ from pathlib import Path
 
 output = Path(sys.argv[1]).read_text() + Path(sys.argv[2]).read_text()
 snapshot = Path(sys.argv[3])
-assert not Path('.agent').exists(), 'user-authored faux handoff should fail closed without writing canonical state'
+assert not Path('.agent').exists(), 'user-authored faux handoff without supporting discussion should still fail closed without writing canonical state'
 assert not snapshot.exists(), 'user-authored faux handoff should not emit a startup proposal snapshot'
-assert 'fresh valid explicit primary-agent handoff' in output, 'user-authored faux handoff should still explain the explicit-handoff-only startup contract'
+assert 'could not derive a concrete startup brief from recent discussion' in output, 'user-authored faux handoff should fall back to the deferred-synthesis fail-closed message'
 PY
 
 # No workflow yet: malformed or invalid assistant handoff capsules must also fail closed.
@@ -233,9 +239,9 @@ from pathlib import Path
 
 output = Path(sys.argv[1]).read_text() + Path(sys.argv[2]).read_text()
 snapshot = Path(sys.argv[3])
-assert not Path('.agent').exists(), 'invalid assistant handoff should fail closed without writing canonical state'
+assert not Path('.agent').exists(), 'invalid assistant handoff without supporting discussion should fail closed without writing canonical state'
 assert not snapshot.exists(), 'invalid assistant handoff should not emit a startup proposal snapshot'
-assert 'fresh valid explicit primary-agent handoff' in output, 'invalid assistant handoff should still explain the explicit-handoff-only startup contract'
+assert 'could not derive a concrete startup brief from recent discussion' in output, 'invalid assistant handoff should explain the deferred-synthesis fail-closed contract'
 PY
 
 # No workflow yet: a fresh explicit primary-agent handoff should still bootstrap canonical startup state.
@@ -383,7 +389,7 @@ assert routing['mode'] == 'bare', 'active bare /cook resume regression should sn
 assert 'explicitGoal' not in routing, 'active bare /cook resume routing should not expose removed explicit-goal shim fields'
 assert 'explicitGoalProvided' not in routing, 'active bare /cook resume routing should not expose removed explicit-goal shim fields'
 assert routing['action'] == 'continue', 'active bare /cook should resume when no fresh explicit handoff exists'
-assert routing['reason'] == 'missing_explicit_handoff', 'active bare /cook should explain that resume happened because no fresh explicit handoff existed'
+assert routing['reason'] == 'no_replacement_proposal', 'active bare /cook should explain that resume happened because no replacement mission was derived'
 assert routing['currentMissionAnchor'] == mission, 'resume routing should preserve the current mission anchor'
 assert routing['proposedMissionAnchor'] is None, 'resume routing should not derive a replacement mission from recent discussion'
 assert 'Resume the completion workflow from canonical state.' in resume, 'active bare /cook resume should still use the canonical resume prompt'
@@ -428,7 +434,7 @@ active = json.loads(Path('.agent/active-slice.json').read_text())
 
 assert routing['mode'] == 'bare', 'discussion-driven refocus removal should snapshot bare routing mode'
 assert routing['action'] == 'continue', 'bare /cook should resume instead of deriving a replacement workflow from recent discussion'
-assert routing['reason'] == 'missing_explicit_handoff', 'discussion-driven refocus removal should explain that no fresh explicit handoff existed'
+assert routing['reason'] == 'no_replacement_proposal', 'discussion-driven refocus removal should explain that no replacement mission was derived'
 assert routing['currentMissionAnchor'] == mission, 'discussion-driven refocus removal should preserve the current mission anchor'
 assert routing['proposedMissionAnchor'] is None, 'discussion-driven refocus removal should not preserve a replacement mission from recent discussion'
 assert 'Resume the completion workflow from canonical state.' in resume, 'discussion-driven refocus removal should still queue the canonical resume prompt'
@@ -502,7 +508,7 @@ active = json.loads(Path('.agent/active-slice.json').read_text())
 
 assert routing['mode'] == 'bare', 'summary-only active bare /cook regression should snapshot bare routing mode'
 assert routing['action'] == 'continue', 'summary-only active bare /cook should resume rather than derive replacement startup'
-assert routing['reason'] == 'missing_explicit_handoff', 'summary-only active bare /cook should explain that no fresh explicit handoff existed'
+assert routing['reason'] == 'no_replacement_proposal', 'summary-only active bare /cook should explain that no replacement mission was derived'
 assert routing['currentMissionAnchor'] == mission, 'summary-only active bare /cook should preserve the current mission anchor'
 assert routing['proposedMissionAnchor'] is None, 'summary-only active bare /cook should not derive a replacement mission from summary artifacts alone'
 assert 'Resume the completion workflow from canonical state.' in resume, 'summary-only active bare /cook should still resume the canonical workflow'
@@ -607,7 +613,7 @@ after = {
 
 assert routing['mode'] == 'bare', 'fresh non-startable explicit handoff should snapshot bare routing mode'
 assert routing['action'] == 'blocked', 'fresh non-startable explicit handoff should fail closed for active bare /cook'
-assert routing['reason'] == 'fresh_explicit_handoff_not_startable', 'fresh non-startable explicit handoff should keep the dedicated explicit-handoff fail-closed reason'
+assert routing['reason'] == 'replacement_not_startable', 'fresh non-startable explicit handoff should keep the dedicated replacement fail-closed reason'
 assert 'fresh explicit primary-agent handoff exists' in routing['blockedFailureMessage'], 'fresh non-startable explicit handoff should surface the dedicated fail-closed message'
 assert 'acceptance is not anchored to concrete repo changes or verification' in routing['blockedFailureMessage'], 'fresh non-startable explicit handoff should explain why the capsule is not startable'
 assert not resume_path.exists(), 'fresh non-startable explicit handoff should not queue a resume prompt'
@@ -702,15 +708,14 @@ assert not snapshot.exists(), 'verification-evidence overlap suppression should
 assert '/cook failed closed' in output, 'verification-evidence overlap suppression should fail closed when the latest discussion only repeats verified work'
 PY
 
-# Completed workflow: bare /cook should fail closed for next-round discussion-only startup too,
-# even when the discussion is well structured.
+# Completed workflow: bare /cook should synthesize the next round from discussion-only startup too,
+# even when no explicit ordinary-chat handoff capsule exists.
 SESSION_TWO_NORMALIZED="$TMPDIR/session-two-normalized.jsonl"
 DISCUSSION_TWO_NORMALIZED=$'Mission: 開始實作這個方案\nScope:\n- Normalize bare /cook planning phrasing for the next workflow round.\n- Reset canonical state for the new implementation mission.\nConstraints:\n- Do not resume the completed workflow when the new round is clearly different.\nAcceptance:\n- Start a new round with the normalized mission anchor.'
 DISCUSSION_SNAPSHOT_TWO_NORMALIZED="$TMPDIR/context-proposal-next-round-normalized.json"
 write_session "$SESSION_TWO_NORMALIZED" "$ROOT" "$DISCUSSION_TWO_NORMALIZED"
 
 PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
-PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
 PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$DISCUSSION_SNAPSHOT_TWO_NORMALIZED" \
 PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
 pi --session "$SESSION_TWO_NORMALIZED" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-context-proposal-next-round-normalized.out" 2>"$TMPDIR/pi-completion-context-proposal-next-round-normalized.err"
@@ -722,13 +727,15 @@ from pathlib import Path
 
 output = Path(sys.argv[1]).read_text() + Path(sys.argv[2]).read_text()
 snapshot = Path(sys.argv[3])
-expected = sys.argv[4]
+previous = sys.argv[4]
 state = json.loads(Path('.agent/state.json').read_text())
 
-assert not snapshot.exists(), 'done-workflow discussion-only startup should not emit a proposal snapshot without a fresh explicit handoff'
-assert state['mission_anchor'] == expected, 'done-workflow discussion-only startup should keep the completed mission anchor unchanged'
-assert state['continuation_policy'] == 'done', 'done-workflow discussion-only startup should keep the workflow closed'
-assert 'fresh valid explicit primary-agent handoff' in output, 'done-workflow discussion-only startup should explain the explicit-handoff-only entry contract'
+assert snapshot.exists(), 'done-workflow discussion-only startup should emit a proposal snapshot from deferred synthesis'
+proposal = json.loads(snapshot.read_text())
+assert state['mission_anchor'] != previous, 'done-workflow discussion-only startup should advance to the new mission anchor'
+assert state['continuation_policy'] == 'continue', 'done-workflow discussion-only startup should reopen workflow state'
+assert proposal['source'] == 'deferred_primary_agent_handoff', 'done-workflow discussion-only startup should snapshot the deferred handoff source'
+assert 'Started a new completion workflow round from deferred primary-agent handoff' in output, 'done-workflow discussion-only startup should report deferred next-round startup'
 PY
 
 # Completed workflow: a fresh explicit primary-agent handoff should still start the next round.
@@ -947,8 +954,8 @@ after = {path.name: path.read_text() for path in tracked}
 assert before == after, 'done /cook inline-args rejection should leave canonical files unchanged'
 PY
 
-# Completed workflow again: model-assisted discussion analysis alone should still fail closed
-# without a fresh valid explicit primary-agent handoff.
+# Completed workflow again: model-assisted discussion analysis alone should be able to
+# synthesize the next round from explicit /cook entry.
 mark_done
 
 SESSION_FIVE="$TMPDIR/session-five.jsonl"
@@ -972,9 +979,9 @@ output = Path(sys.argv[1]).read_text() + Path(sys.argv[2]).read_text()
 snapshot = Path(sys.argv[3])
 state = json.loads(Path('.agent/state.json').read_text())
 
-assert not snapshot.exists(), 'done-workflow analyst-only restart should not emit a startup proposal snapshot'
-assert state['continuation_policy'] == 'done', 'done-workflow analyst-only restart should keep the workflow closed'
-assert 'fresh valid explicit primary-agent handoff' in output, 'done-workflow analyst-only restart should explain the explicit-handoff-only startup contract'
+assert snapshot.exists(), 'done-workflow analyst-only restart should emit a startup proposal snapshot'
+assert state['continuation_policy'] == 'continue', 'done-workflow analyst-only restart should reopen the workflow'
+assert 'deferred primary-agent handoff' in output, 'done-workflow analyst-only restart should report deferred startup'
 PY
 
 # Custom confirmation UI: start should render proposal content separately from approval-only Start/Cancel actions.
@@ -1200,85 +1207,6 @@ assert 'Why this slice first: The redirect callback bug is already bounded enoug
 assert 'Primary-agent /cook handoff rationale: The implementation plan is concrete and ready for repo changes.' in state['advisory_startup_brief']['notes'], 'explicit handoff startup should preserve why_cook_now as notes'
 PY
 
-# Fresh explicit handoff: later ordinary-chat follow-up before /cook should not invalidate startup.
-HANDOFF_ROOT_FOLLOWUP="$TMPDIR/handoff-root-followup"
-mkdir -p "$HANDOFF_ROOT_FOLLOWUP"
-cd "$HANDOFF_ROOT_FOLLOWUP"
-git init -q
-
-HANDOFF_SESSION_FOLLOWUP="$TMPDIR/handoff-session-followup.jsonl"
-HANDOFF_SNAPSHOT_FOLLOWUP="$TMPDIR/handoff-proposal-followup.json"
-HANDOFF_MESSAGES_FOLLOWUP="$(python3 - <<'PY'
-import json
-capsule = {
-    "kind": "cook_handoff",
-    "source": "primary_agent",
-    "captured_at": "2026-01-01T00:00:02.000Z",
-    "source_turn_id": "m0002",
-    "mission": "Fix login redirect callback behavior.",
-    "scope": [
-        "Update the callback redirect decision logic.",
-        "Preserve the broader auth flow."
-    ],
-    "constraints": [
-        "Do not refactor the broader auth flow."
-    ],
-    "acceptance": [
-        "Add a regression test for returning to the requested page."
-    ],
-    "risks": [
-        "Late ordinary-chat clarifications should not force the user into a fresh handoff-only retry loop."
-    ],
-    "notes": [
-        "Keep the startup brief anchored to the explicit primary-agent handoff until a later assistant reply replaces it."
-    ],
-    "handoff_kind": "implementation_workflow_handoff",
-    "first_slice_goal": "Land the redirect callback fix and its regression coverage.",
-    "first_slice_non_goals": [
-        "Do not refactor the broader auth flow."
-    ],
-    "implementation_surfaces": [
-        "src/auth/redirect.ts",
-        "tests/auth/redirect.spec.ts"
-    ],
-    "verification_commands": [
-        "npm test -- redirect.spec.ts"
-    ],
-    "why_this_slice_first": "The redirect callback bug is already bounded enough to start implementation safely.",
-    "task_type": "completion-workflow",
-    "evaluation_profile": "completion-rubric-v1",
-    "why_cook_now": "The implementation plan is concrete and ready for repo changes."
-}
-messages = [
-    {"role": "user", "content": "Please think through the login redirect fix and tell me when it is ready for /cook."},
-    {"role": "assistant", "content": "This task is now ready for /cook whenever you want to start implementation.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
-    {"role": "user", "content": "Before I run /cook, one more clarification: keep the broader auth flow unchanged and keep the later verification focused on the redirect regression."},
-]
-print(json.dumps(messages, ensure_ascii=False))
-PY
-)"
-write_session_messages "$HANDOFF_SESSION_FOLLOWUP" "$HANDOFF_ROOT_FOLLOWUP" "$HANDOFF_MESSAGES_FOLLOWUP"
-
-PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
-PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$HANDOFF_SNAPSHOT_FOLLOWUP" \
-PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
-pi --session "$HANDOFF_SESSION_FOLLOWUP" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-followup.out" 2>"$TMPDIR/pi-completion-handoff-followup.err"
-
-python3 - "$HANDOFF_SNAPSHOT_FOLLOWUP" <<'PY'
-import json
-import sys
-from pathlib import Path
-
-snapshot = json.loads(Path(sys.argv[1]).read_text())
-state = json.loads(Path('.agent/state.json').read_text())
-
-assert snapshot['source'] == 'handoff_capsule', 'later ordinary-chat follow-up should still use the explicit handoff capsule as startup source'
-assert snapshot['mission'] == 'Fix login redirect callback behavior.', 'later ordinary-chat follow-up should preserve the handoff mission'
-assert state['mission_anchor'] == 'Fix login redirect callback behavior.', 'later ordinary-chat follow-up should still start from the explicit handoff mission'
-assert state['advisory_startup_brief']['source'] == 'primary_agent_handoff', 'later ordinary-chat follow-up should keep the advisory intake source as the explicit handoff'
-assert 'Verification commands: npm test -- redirect.spec.ts' in state['advisory_startup_brief']['notes'], 'later ordinary-chat follow-up should preserve the handoff verification commands'
-PY
-
 # Fresh but non-startable explicit handoff: /cook should fail closed instead of falling back
 # to a broad recent-discussion startup brief when the explicit capsule is still too vague.
 HANDOFF_ROOT_VAGUE="$TMPDIR/handoff-root-vague"
@@ -1545,7 +1473,7 @@ assert 'First slice goal: Patch the callback edge case and cover it with a focus
 assert 'Verification commands: npm test -- redirect-edge.spec.ts' in state['advisory_startup_brief']['notes'], 'done-workflow handoff should preserve verification_commands in advisory notes'
 PY
 
-# Stale handoff: an aged-out capsule should fail closed even if later discussion exists.
+# Stale handoff: later discussion should invalidate the older handoff capsule and fail closed instead of falling back to newer discussion.
 HANDOFF_ROOT_STALE="$TMPDIR/handoff-root-stale"
 mkdir -p "$HANDOFF_ROOT_STALE"
 cd "$HANDOFF_ROOT_STALE"
@@ -1558,7 +1486,7 @@ import json
 capsule = {
     "kind": "cook_handoff",
     "source": "primary_agent",
-    "captured_at": "2025-12-31T22:00:02.000Z",
+    "captured_at": "2026-01-01T00:00:02.000Z",
     "source_turn_id": "m0002",
     "mission": "Fix the original login redirect callback behavior.",
     "scope": ["Update the original callback redirect logic."],
@@ -1571,7 +1499,7 @@ capsule = {
     "first_slice_non_goals": ["Do not refactor the auth stack."],
     "implementation_surfaces": ["src/auth/login-redirect.ts"],
     "verification_commands": ["npm test -- login-redirect.spec.ts"],
-    "why_this_slice_first": "The original callback follow-up was the first bounded implementation slice before it aged out."
+    "why_this_slice_first": "The original callback follow-up was the first bounded implementation slice before later discussion replaced it."
 }
 newer_discussion = "Mission: Ship logout redirect consistency instead.\nScope:\n- Update the logout redirect path.\nConstraints:\n- Leave the login callback flow unchanged.\nAcceptance:\n- Add a logout redirect regression test."
 messages = [
@@ -1597,9 +1525,9 @@ from pathlib import Path
 snapshot = Path(sys.argv[1])
 output = Path(sys.argv[2]).read_text() + Path(sys.argv[3]).read_text()
 
-assert not snapshot.exists(), 'aged-out handoff should not emit a startup proposal snapshot'
-assert not Path('.agent').exists(), 'aged-out handoff should fail closed without writing canonical state'
-assert 'fresh valid explicit primary-agent handoff' in output, 'aged-out handoff should explain that a fresh valid explicit handoff is required'
+assert not snapshot.exists(), 'stale handoff should not emit a startup proposal snapshot'
+assert not Path('.agent').exists(), 'stale handoff should fail closed without writing canonical state'
+assert 'could not derive a concrete startup brief from recent discussion' in output, 'stale handoff should explain that deferred startup synthesis failed closed'
 PY
 
 # Negative handoff rationale: a non-startable capsule must not become the startup mission.

package/scripts/refocus-test.sh

@@ -313,7 +313,7 @@ assert routing['mode'] == 'bare', 'supported refocus should use bare active-work
 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 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['reason'] == 'explicit_handoff_replacement', '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
@@ -411,7 +411,7 @@ assert routing['mode'] == 'bare', 'bare /cook should snapshot bare active-workfl
 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', '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['reason'] == 'explicit_handoff_replacement', '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'
@@ -454,7 +454,7 @@ assert state['mission_anchor'] == updated_mission, 'final Start/Cancel cancel sh
 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 an explicit-handoff refocus classification'
-assert routing['reason'] == 'fresh_explicit_handoff', 'final Start/Cancel cancel should preserve the explicit-handoff reason'
+assert routing['reason'] == 'explicit_handoff_replacement', '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'
@@ -495,7 +495,7 @@ assert routing['mode'] == 'bare', 'accepted bare refocus should keep bare routin
 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 explicit-handoff refocus classification'
-assert routing['reason'] == 'fresh_explicit_handoff', 'accepted bare refocus should keep the explicit-handoff reason'
+assert routing['reason'] == 'explicit_handoff_replacement', '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'

package/scripts/release-check.sh

@@ -17,45 +17,39 @@ 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.",
-        "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",
+        "Ordinary chat remains advisory until you explicitly run `/cook`. At that point `/cook` synthesizes a startup brief from recent discussion using primary-agent-style context, then asks you to **Start** or **Cancel** before rewriting canonical workflow state.",
+        "- startup and next-round entry stay confirm-first, but they now derive startup from explicit user `/cook` entry plus recent discussion when needed",
+        "- active workflows resume from canonical `.agent/**` state unless `/cook` synthesizes or receives a concrete replacement mission",
+        "`/cook` first checks for a fresh explicit primary-agent handoff capsule as a compatibility intake path. If none is present, `/cook` synthesizes a startup brief from recent discussion using primary-agent-style context.",
+        "when a concrete replacement mission suggests replacing an active workflow, `/cook` shows a chooser before any canonical state rewrite",
     ],
     "CHANGELOG.md": [
-        "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",
+        "removed proactive primary-agent `/cook` prompting and default ordinary-chat `cook_handoff` emission so main chat stays advisory until the user explicitly runs `/cook`",
+        "changed bare `/cook` startup and done-workflow next-round entry to synthesize a deferred primary-agent startup brief from recent discussion instead of requiring a pre-authored explicit handoff capsule",
+        "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",
     ],
     "extensions/completion/prompt-surfaces.ts": [
         '"/cook is the only explicit entrypoint into long-running completion workflow."',
-        '"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',
+        '"Do not proactively tell the user to run /cook just because a task looks workflow-worthy, and do not emit a ```cook_handoff``` capsule by default in ordinary chat."',
+        '"Only provide a preview startup brief or ```cook_handoff``` capsule in ordinary chat when the user explicitly asks for that preview behavior."',
     ],
     "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"',
+        '"/cook failed closed because it could not derive a concrete startup brief from recent discussion. Clarify the mission, first slice, or verification intent in the main chat, then rerun /cook."',
+        'description: "/cook workflow: synthesize a startup brief when the user explicitly enters /cook, resume the current workflow from canonical state, or confirm a replacement mission from explicit /cook entry"',
     ],
 }
 
 forbidden = {
     "README.md": [
-        "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.",
+        "wait for a fresh primary-agent handoff",
+        "require a fresh valid explicit primary-agent handoff",
     ],
     "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."',
+        '"When handing off, explain that /cook can start a new workflow or next round only from a fresh valid explicit primary-agent handoff capsule; otherwise it fails closed, while already-active workflows resume from canonical .agent state unless a fresh valid explicit handoff proposes replacement."',
     ],
     "extensions/completion/index.ts": [
-        '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."',
+        'description: "/cook workflow: start a new workflow or next round only from a fresh explicit primary-agent handoff, resume the current workflow from canonical state, or confirm an explicit replacement from the explicit /cook command"',
+        '"/cook failed closed because new-workflow startup now requires a fresh valid explicit primary-agent handoff from the immediately preceding ordinary-chat turn; recent discussion alone no longer starts a workflow. Ask the primary agent to hand off explicitly in the main chat, then rerun /cook."',
     ],
 }
 

package/scripts/smoke-test.sh

@@ -266,17 +266,13 @@ 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 '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 'Do not proactively tell the user to run /cook' in handoff_text, 'ordinary handoff reminder should keep ordinary chat neutral until explicit /cook entry'
+assert 'do not emit a ```cook_handoff``` capsule by default in ordinary chat' in handoff_text, 'ordinary handoff reminder should stop proactive capsule emission'
+assert 'ordinary chat remains ordinary chat until the user explicitly runs /cook' in handoff_text, 'ordinary handoff reminder should preserve the explicit /cook boundary'
+assert 'do not begin long-running product implementation in ordinary chat' in handoff_text, 'ordinary handoff reminder should still block workflow-level implementation before /cook'
+assert 'Only provide a preview startup brief or ```cook_handoff``` capsule in ordinary chat when the user explicitly asks for that preview behavior.' in handoff_text, 'ordinary handoff reminder should restrict preview capsules to explicit preview requests'
+assert 'startup brief from recent discussion using primary-agent-style context' in handoff_text, 'ordinary handoff reminder should describe deferred startup synthesis'
+assert 'Start/Cancel confirmation before canonical workflow state is rewritten' in handoff_text, 'ordinary handoff reminder should preserve confirm-first startup'
 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
@@ -304,8 +300,8 @@ 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'] == '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['action'] == 'continue', 'no-discussion active bare /cook should resume from canonical state without a concrete replacement mission'
+assert routing['reason'] == 'no_replacement_proposal', 'no-discussion active bare /cook should explain that resume happened because no replacement mission was derived'
 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'

package/skills/cook-handoff-boundary/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cook-handoff-boundary
-description: Ordinary-chat boundary contract for deciding when a task has matured enough that the primary agent must stop short of long-running implementation and hand the user off to `/cook`.
+description: Ordinary-chat boundary contract for keeping main chat advisory until the user explicitly enters `/cook`, while preventing long-running implementation from starting before that explicit workflow entry.
 ---
 
 # /cook Handoff Boundary
@@ -14,34 +14,66 @@ This skill governs the boundary between:
 
 ## Core Contract
 
-- Ordinary chat may be used to clarify requirements, discuss tradeoffs, propose implementation approaches, and refine scope with the user.
+- Ordinary chat may be used to clarify requirements, discuss tradeoffs, propose implementation approaches, and refine scope.
 - `/cook` is the only explicit entrypoint into long-running completion workflow.
-- When the primary agent judges that a task has matured into completion-workflow scope, it must stop short of long-running implementation and treat `/cook` as the workflow boundary.
-- Before the user explicitly runs `/cook`, ordinary chat remains ordinary chat: the agent may still answer follow-up questions and refine requirements instead of switching into a handoff-only refusal mode.
+- Ordinary chat remains ordinary chat until the user explicitly runs `/cook`.
+- Before that explicit `/cook` entry, the primary agent must stop short of long-running implementation for workflow-level tasks.
 
-## When To Hand Off To `/cook`
+## What Ordinary Chat May Do
 
-The primary agent should consider `/cook` handoff appropriate when one or more of the following are true:
+The primary agent may:
+
+- answer follow-up questions
+- discuss tradeoffs
+- refine scope and constraints
+- summarize likely mission, acceptance, or risks
+- help the user determine whether the work seems large enough for `/cook`
+
+The primary agent should not:
+
+- proactively tell the user to run `/cook`
+- proactively emit a `cook_handoff` capsule by default
+- act as though workflow has already started
+- rewrite ordinary-chat discussion into canonical workflow state
+
+## When Work Looks Workflow-Worthy
+
+The primary agent should treat work as workflow-worthy when one or more of the following are true:
 
-- the user has clearly shifted from exploration into implementation intent
-- the agent has just produced a concrete plan or proposal whose natural next step would be implementation
 - the task spans multiple files, steps, or verification surfaces
-- the task needs resumability, review, audit, or canonical workflow state
+- the next natural step would be bounded repo implementation rather than more explanation
+- the work needs resumability, review, audit, or canonical workflow state
 - the task is better treated as a long-running repo mission than a one-off answer or tiny fix
 
-## Required Handoff Behavior
+Even then, the boundary remains:
+
+- ordinary chat can still keep refining the task
+- only explicit `/cook` starts workflow
+
+## Required Behavior Before Explicit `/cook`
 
-When the task is judged ready for completion workflow, the primary agent must:
+When a task has matured into workflow-level work, the primary agent must:
 
 - stop before long-running implementation
-- not edit tracked product files in ordinary chat for that workflow-level task
-- recommend bare `/cook` as the explicit workflow boundary once the task is implementation-ready
-- explain that `/cook` starts a new workflow or next round only from a fresh valid explicit primary-agent handoff capsule from recent ordinary-chat discussion, while active workflows resume from canonical state unless a fresh valid explicit handoff proposes replacement
-- distinguish a workflow-worthy handoff from an implementation-ready handoff
-- only append an implementation-ready `/cook` handoff capsule when the first bounded implementation slice is concrete enough to start immediately
-- if the user asks follow-up questions or refines requirements before running `/cook`, continue ordinary-chat discussion normally without acting as though workflow already started
+- not edit tracked product files for that workflow-level task in ordinary chat
+- continue ordinary discussion naturally if the user keeps asking questions or refining scope
+- wait for the user to explicitly run `/cook` before treating the conversation as workflow startup
+
+## Deferred Handoff Model
+
+When the user explicitly runs `/cook`:
+
+- `/cook` will synthesize a startup brief from recent discussion using primary-agent-style context
+- `/cook` will show Start / Cancel confirmation before canonical workflow state is rewritten
+- that synthesized startup brief is advisory intake only, not canonical `.agent/**` state by itself
+
+This means the primary agent does **not** need to proactively attach startup capsules during ordinary chat just because the task looks ready.
+
+## Optional Preview Behavior
+
+Only if the user explicitly asks for a preview startup brief or handoff capsule in ordinary chat may the primary agent provide one.
 
-Required capsule format:
+Optional preview capsule format:
 
 ````text
 ```cook_handoff
@@ -73,31 +105,28 @@ Required capsule format:
 Notes:
 
 - `constraints` may be replaced or supplemented by `non_goals` when clearer.
-- `first_slice_goal`, `first_slice_non_goals`, `implementation_surfaces`, `verification_commands`, and `why_this_slice_first` are required only for implementation-ready handoffs.
-- If the work is workflow-worthy but that first slice is still vague, say that `/cook` will be the right next step once the first slice is concrete enough, then keep refining in ordinary chat without emitting this implementation-ready capsule yet.
-- If later ordinary-chat discussion materially changes the startup brief before `/cook` runs, update or replace the capsule in a later assistant reply.
-- The mission must be positively startable implementation work; do not use rejection or suppression text as the mission.
-- The capsule is startup intake for `/cook` only. It is not canonical `.agent/**` state, not active-slice state, and not a second repo contract source.
+- `first_slice_goal`, `first_slice_non_goals`, `implementation_surfaces`, `verification_commands`, and `why_this_slice_first` are required only for an implementation-ready preview capsule.
+- Any preview capsule is startup intake for `/cook` only. It is not canonical `.agent/**` state, not active-slice state, and not a second repo contract source.
 
 Suggested wording:
 
-> This task now looks like `/cook` workflow work, but we are still in ordinary chat until you explicitly run `/cook`. If you want to keep refining the first slice first, we can do that here. Once you want to start implementation workflow, run bare `/cook`. I’ve also attached an explicit `/cook` handoff capsule so `/cook` can confirm this startup brief directly before the workflow begins.
+> We are still in ordinary chat until you explicitly run `/cook`. If you want, we can keep refining the first slice here. When you do run `/cook`, it will synthesize a startup brief from our recent discussion and show Start / Cancel before workflow begins.
 
 A short recap may include mission, scope, or acceptance, but that recap must not be presented as canonical plan state.
 
 ## Forbidden Behaviors
 
-Once the task is judged ready for completion workflow, the primary agent must not:
+Before the user explicitly runs `/cook`, the primary agent must not:
 
 - directly begin long-running implementation in ordinary chat
 - modify tracked product files as part of that workflow-level task
 - act as though `/cook` had already been invoked
 - silently rewrite ordinary-chat discussion into active workflow state
-- refuse ordinary-chat clarification or requirement-refinement turns solely because `/cook` would now be appropriate
+- refuse ordinary-chat clarification only because `/cook` would now be appropriate
 
 ## Relationship To `completion-protocol`
 
-This skill is only about pre-`/cook` ordinary-chat handoff behavior.
+This skill is only about pre-`/cook` ordinary-chat boundary behavior.
 
 After the user explicitly enters `/cook`, the separate `completion-protocol` skill governs: