@linimin/pi-letscook 0.1.56 → 0.1.58

package/scripts/context-proposal-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
+}
+
 mark_done() {
   python3 - <<'PY'
 import json
@@ -1358,7 +1401,446 @@ assert 'Discuss changes in the main chat and rerun /cook.' in output, 'cancel co
 assert not Path('.agent').exists(), 'cancel action should not write canonical workflow state'
 PY
 
+# Explicit primary-agent handoff: /cook should prefer the structured handoff capsule over broad context re-inference.
+HANDOFF_ROOT_START="$TMPDIR/handoff-root-start"
+mkdir -p "$HANDOFF_ROOT_START"
+cd "$HANDOFF_ROOT_START"
+git init -q
+
+HANDOFF_SESSION_START="$TMPDIR/handoff-session-start.jsonl"
+HANDOFF_SNAPSHOT_START="$TMPDIR/handoff-proposal-start.json"
+HANDOFF_MESSAGES_START="$(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": [
+        "Stale auth discussion could broaden the startup brief if the handoff is ignored."
+    ],
+    "notes": [
+        "Keep the startup brief aligned with the explicit primary-agent plan."
+    ],
+    "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. 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
+)"
+write_session_messages "$HANDOFF_SESSION_START" "$HANDOFF_ROOT_START" "$HANDOFF_MESSAGES_START"
+
+PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
+PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$HANDOFF_SNAPSHOT_START" \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$HANDOFF_SESSION_START" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-start.out" 2>"$TMPDIR/pi-completion-handoff-start.err"
+
+python3 - "$HANDOFF_SNAPSHOT_START" <<'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', 'explicit handoff startup should snapshot the handoff capsule as the proposal source'
+assert snapshot['mission'] == 'Fix login redirect callback behavior.', 'explicit handoff startup should preserve the primary-agent mission'
+assert state['mission_anchor'] == 'Fix login redirect callback behavior.', 'explicit handoff startup should use the handoff mission as canonical mission_anchor'
+assert state['advisory_startup_brief']['source'] == 'primary_agent_handoff', 'explicit handoff startup should preserve the advisory intake source'
+assert state['advisory_startup_brief']['risks'] == ['Stale auth discussion could broaden the startup brief if the handoff is ignored.'], 'explicit handoff startup should preserve handoff risks'
+assert 'First slice goal: Land the redirect callback fix and its regression coverage.' in state['advisory_startup_brief']['notes'], 'explicit handoff startup should preserve first_slice_goal in advisory notes'
+assert 'First slice non-goals: Do not refactor the broader auth flow.' in state['advisory_startup_brief']['notes'], 'explicit handoff startup should preserve first_slice_non_goals in advisory notes'
+assert 'Implementation surfaces: src/auth/redirect.ts | tests/auth/redirect.spec.ts' in state['advisory_startup_brief']['notes'], 'explicit handoff startup should preserve implementation_surfaces in advisory notes'
+assert 'Verification commands: npm test -- redirect.spec.ts' in state['advisory_startup_brief']['notes'], 'explicit handoff startup should preserve verification_commands in advisory notes'
+assert 'Why this slice first: The redirect callback bug is already bounded enough to start implementation safely.' in state['advisory_startup_brief']['notes'], 'explicit handoff startup should preserve why_this_slice_first in advisory notes'
+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 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"
+mkdir -p "$HANDOFF_ROOT_VAGUE"
+cd "$HANDOFF_ROOT_VAGUE"
+git init -q
+
+HANDOFF_SESSION_VAGUE="$TMPDIR/handoff-session-vague.jsonl"
+HANDOFF_SNAPSHOT_VAGUE="$TMPDIR/handoff-proposal-vague.json"
+HANDOFF_MESSAGES_VAGUE="$(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."
+    ],
+    "constraints": [
+        "Do not refactor the broader auth flow."
+    ],
+    "acceptance": [
+        "Confirm the final implementation breakdown before coding."
+    ],
+    "risks": [
+        "Broad recent context could be reused if the vague explicit handoff is ignored."
+    ],
+    "notes": [
+        "This handoff is still too vague to start implementation directly."
+    ],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Patch the callback redirect decision logic.",
+    "first_slice_non_goals": [
+        "Do not refactor the broader auth flow."
+    ],
+    "implementation_surfaces": [],
+    "verification_commands": [],
+    "why_this_slice_first": "The callback redirect path is the likely first slice, but the handoff still lacks execution detail.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "The task is workflow-worthy, but the implementation slice is not concrete enough yet."
+}
+recent_discussion = "Mission: Fix login redirect callback behavior.\nScope:\n- Update the callback redirect decision logic.\nConstraints:\n- Do not refactor the broader auth flow.\nAcceptance:\n- Add a regression test for returning to the requested page."
+messages = [
+    {"role": "user", "content": recent_discussion},
+    {"role": "assistant", "content": "This follow-up might soon be 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 "$HANDOFF_SESSION_VAGUE" "$HANDOFF_ROOT_VAGUE" "$HANDOFF_MESSAGES_VAGUE"
+
+PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$HANDOFF_SNAPSHOT_VAGUE" \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$HANDOFF_SESSION_VAGUE" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-vague.out" 2>"$TMPDIR/pi-completion-handoff-vague.err"
+
+python3 - "$HANDOFF_SNAPSHOT_VAGUE" "$TMPDIR/pi-completion-handoff-vague.out" "$TMPDIR/pi-completion-handoff-vague.err" <<'PY'
+import sys
+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(), 'fresh non-startable handoff should not emit a startup proposal snapshot'
+assert not Path('.agent').exists(), 'fresh non-startable handoff should fail closed without writing canonical state'
+assert 'fresh explicit primary-agent handoff exists' in output, 'fresh non-startable handoff should explain that the explicit capsule blocked startup'
+assert 'acceptance is not anchored to concrete repo changes or verification' in output, 'fresh non-startable handoff should explain the workflow-only acceptance failure'
+assert 'implementation_surfaces is empty' in output, 'fresh non-startable handoff should explain the missing implementation_surfaces requirement'
+assert 'verification_commands is empty' in output, 'fresh non-startable handoff should explain the missing verification_commands requirement'
+PY
+
+# Fresh explicit handoff with complete first-slice fields but vague acceptance: /cook should still fail closed
+# with the dedicated explicit-handoff message instead of bootstrapping canonical state.
+HANDOFF_ROOT_VAGUE_ACCEPTANCE="$TMPDIR/handoff-root-vague-acceptance"
+mkdir -p "$HANDOFF_ROOT_VAGUE_ACCEPTANCE"
+cd "$HANDOFF_ROOT_VAGUE_ACCEPTANCE"
+git init -q
+
+HANDOFF_SESSION_VAGUE_ACCEPTANCE="$TMPDIR/handoff-session-vague-acceptance.jsonl"
+HANDOFF_SNAPSHOT_VAGUE_ACCEPTANCE="$TMPDIR/handoff-proposal-vague-acceptance.json"
+HANDOFF_MESSAGES_VAGUE_ACCEPTANCE="$(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": [
+        "Current behavior stays understandable."
+    ],
+    "risks": [
+        "Broad recent context could be reused if the vague explicit handoff is ignored."
+    ],
+    "notes": [
+        "This handoff includes first-slice fields but still lacks concrete acceptance."
+    ],
+    "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 once acceptance is concrete.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "The task is workflow-worthy, but the acceptance still needs concrete repo-change detail."
+}
+recent_discussion = "Mission: Fix login redirect callback behavior.\nScope:\n- Update the callback redirect decision logic.\nConstraints:\n- Do not refactor the broader auth flow.\nAcceptance:\n- Add a regression test for returning to the requested page."
+messages = [
+    {"role": "user", "content": recent_discussion},
+    {"role": "assistant", "content": "This follow-up might soon be 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 "$HANDOFF_SESSION_VAGUE_ACCEPTANCE" "$HANDOFF_ROOT_VAGUE_ACCEPTANCE" "$HANDOFF_MESSAGES_VAGUE_ACCEPTANCE"
+
+PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$HANDOFF_SNAPSHOT_VAGUE_ACCEPTANCE" \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$HANDOFF_SESSION_VAGUE_ACCEPTANCE" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-vague-acceptance.out" 2>"$TMPDIR/pi-completion-handoff-vague-acceptance.err"
+
+python3 - "$HANDOFF_SNAPSHOT_VAGUE_ACCEPTANCE" "$TMPDIR/pi-completion-handoff-vague-acceptance.out" "$TMPDIR/pi-completion-handoff-vague-acceptance.err" <<'PY'
+import sys
+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(), 'fresh explicit handoff with vague acceptance should not emit a startup proposal snapshot'
+assert not Path('.agent').exists(), 'fresh explicit handoff with vague acceptance should fail closed without writing canonical state'
+assert 'fresh explicit primary-agent handoff exists' in output, 'fresh explicit handoff with vague acceptance should use the dedicated explicit-handoff fail-closed message'
+assert 'acceptance is not anchored to concrete repo changes or verification' in output, 'fresh explicit handoff with vague acceptance should explain the vague acceptance failure'
+PY
+
+# Done workflow + fresh handoff: the fresh explicit handoff should override done-state suppression and start the new round.
+HANDOFF_ROOT_DONE="$TMPDIR/handoff-root-done"
+mkdir -p "$HANDOFF_ROOT_DONE"
+cd "$HANDOFF_ROOT_DONE"
+git init -q
+
+DONE_SEED_SESSION="$TMPDIR/handoff-done-seed-session.jsonl"
+DONE_SEED_DISCUSSION=$'Mission: Seed a finished workflow before testing fresh handoff priority.\nScope:\n- Create canonical workflow state.\nConstraints:\n- Keep the seed minimal.\nAcceptance:\n- Mark the workflow done before the next test step.'
+write_session "$DONE_SEED_SESSION" "$HANDOFF_ROOT_DONE" "$DONE_SEED_DISCUSSION"
+PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
+PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$DONE_SEED_SESSION" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-done-seed.out" 2>"$TMPDIR/pi-completion-handoff-done-seed.err"
+mark_done
+
+HANDOFF_SESSION_DONE="$TMPDIR/handoff-session-done.jsonl"
+HANDOFF_SNAPSHOT_DONE="$TMPDIR/handoff-proposal-done.json"
+HANDOFF_MESSAGES_DONE="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Reopen the login redirect work for the callback edge case.",
+    "scope": [
+        "Handle the callback edge case in the redirect logic.",
+        "Keep the finished workflow as historical context only."
+    ],
+    "constraints": [
+        "Do not turn done-state suppression into the startup mission."
+    ],
+    "acceptance": [
+        "Add a regression test for the callback edge case."
+    ],
+    "risks": [
+        "Done-state context could override the new mission if the handoff is ignored."
+    ],
+    "notes": [
+        "This is a fresh implementation round, not a summary of the finished workflow."
+    ],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Patch the callback edge case and cover it with a focused regression test.",
+    "first_slice_non_goals": [
+        "Do not turn done-state suppression into the startup mission."
+    ],
+    "implementation_surfaces": [
+        "src/auth/redirect.ts",
+        "tests/auth/redirect-edge.spec.ts"
+    ],
+    "verification_commands": [
+        "npm test -- redirect-edge.spec.ts"
+    ],
+    "why_this_slice_first": "The new callback edge case is the smallest fresh implementation slice after the prior round closed.",
+    "task_type": "completion-workflow",
+    "evaluation_profile": "completion-rubric-v1",
+    "why_cook_now": "A new implementation-ready edge case was identified after the previous round closed."
+}
+messages = [
+    {"role": "user", "content": "The previous round is done, but there is a fresh callback edge case to implement."},
+    {"role": "assistant", "content": "The next round is ready for /cook. Run /cook to confirm this fresh implementation mission.\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 "$HANDOFF_SESSION_DONE" "$HANDOFF_ROOT_DONE" "$HANDOFF_MESSAGES_DONE"
+
+PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
+PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$HANDOFF_SNAPSHOT_DONE" \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$HANDOFF_SESSION_DONE" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-done.out" 2>"$TMPDIR/pi-completion-handoff-done.err"
+
+python3 - "$HANDOFF_SNAPSHOT_DONE" <<'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', 'done-workflow handoff should still use the explicit handoff capsule'
+assert snapshot['mission'] == 'Reopen the login redirect work for the callback edge case.', 'done-workflow handoff should preserve the fresh mission'
+assert state['mission_anchor'] == 'Reopen the login redirect work for the callback edge case.', 'done-workflow handoff should override done-state suppression with the fresh mission'
+assert state['continuation_policy'] == 'continue', 'done-workflow handoff should reopen canonical workflow state for the new round'
+assert state['advisory_startup_brief']['source'] == 'primary_agent_handoff', 'done-workflow handoff should preserve the handoff advisory source'
+assert 'First slice goal: Patch the callback edge case and cover it with a focused regression test.' in state['advisory_startup_brief']['notes'], 'done-workflow handoff should preserve first_slice_goal in advisory notes'
+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: later discussion should invalidate the older handoff capsule and fall back to the newer discussion mission.
+HANDOFF_ROOT_STALE="$TMPDIR/handoff-root-stale"
+mkdir -p "$HANDOFF_ROOT_STALE"
+cd "$HANDOFF_ROOT_STALE"
+git init -q
+
+HANDOFF_SESSION_STALE="$TMPDIR/handoff-session-stale.jsonl"
+HANDOFF_SNAPSHOT_STALE="$TMPDIR/handoff-proposal-stale.json"
+HANDOFF_MESSAGES_STALE="$(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 the original login redirect callback behavior.",
+    "scope": ["Update the original callback redirect logic."],
+    "constraints": ["Do not refactor the auth stack."],
+    "acceptance": ["Add the original callback regression test."],
+    "risks": [],
+    "notes": [],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Ship the original login callback follow-up.",
+    "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 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 = [
+    {"role": "user", "content": "Please plan the login redirect follow-up."},
+    {"role": "assistant", "content": "Run /cook if you want to start the original follow-up.\n\n```cook_handoff\n" + json.dumps(capsule, ensure_ascii=False, indent=2) + "\n```"},
+    {"role": "user", "content": newer_discussion},
+]
+print(json.dumps(messages, ensure_ascii=False))
+PY
+)"
+write_session_messages "$HANDOFF_SESSION_STALE" "$HANDOFF_ROOT_STALE" "$HANDOFF_MESSAGES_STALE"
+
+PI_COMPLETION_CONTEXT_PROPOSAL_ACTION=accept \
+PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$HANDOFF_SNAPSHOT_STALE" \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$HANDOFF_SESSION_STALE" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-stale.out" 2>"$TMPDIR/pi-completion-handoff-stale.err"
+
+python3 - "$HANDOFF_SNAPSHOT_STALE" <<'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'] == 'session', 'stale handoff should fall back to the newer user discussion proposal'
+assert snapshot['mission'] == 'Ship logout redirect consistency instead.', 'stale handoff fallback should prefer the newer discussion mission'
+assert state['mission_anchor'] == 'Ship logout redirect consistency instead.', 'stale handoff fallback should not keep the older handoff mission'
+assert state['advisory_startup_brief']['source'] == 'recent_discussion', 'stale handoff fallback should preserve that the accepted startup came from discussion'
+PY
+
+# Negative handoff rationale: a non-startable capsule must not become the startup mission.
+HANDOFF_ROOT_NEGATIVE="$TMPDIR/handoff-root-negative"
+mkdir -p "$HANDOFF_ROOT_NEGATIVE"
+cd "$HANDOFF_ROOT_NEGATIVE"
+git init -q
+
+HANDOFF_SESSION_NEGATIVE="$TMPDIR/handoff-session-negative.jsonl"
+HANDOFF_SNAPSHOT_NEGATIVE="$TMPDIR/handoff-proposal-negative.json"
+HANDOFF_MESSAGES_NEGATIVE="$(python3 - <<'PY'
+import json
+capsule = {
+    "kind": "cook_handoff",
+    "source": "primary_agent",
+    "captured_at": "2026-01-01T00:00:02.000Z",
+    "source_turn_id": "m0002",
+    "mission": "Do not reopen implementation for the finished workflow.",
+    "scope": ["Keep the old workflow closed."],
+    "constraints": ["Do not start repo changes."],
+    "acceptance": ["Explain that the finished workflow should stay closed."],
+    "risks": [],
+    "notes": [],
+    "handoff_kind": "implementation_workflow_handoff",
+    "first_slice_goal": "Keep the finished workflow closed.",
+    "first_slice_non_goals": ["Do not start repo changes."],
+    "implementation_surfaces": ["docs/workflow-status.md"],
+    "verification_commands": ["npm test -- workflow-status"],
+    "why_this_slice_first": "This is the only bounded next step being proposed, even though the mission itself is invalid."
+}
+messages = [
+    {"role": "user", "content": "Should we reopen the finished workflow?"},
+    {"role": "assistant", "content": "Do not reopen it directly.\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 "$HANDOFF_SESSION_NEGATIVE" "$HANDOFF_ROOT_NEGATIVE" "$HANDOFF_MESSAGES_NEGATIVE"
+
+PI_COMPLETION_DISABLE_CONTEXT_PROPOSAL_ANALYST=1 \
+PI_COMPLETION_TEST_CONTEXT_PROPOSAL_PATH="$HANDOFF_SNAPSHOT_NEGATIVE" \
+PI_COMPLETION_SKIP_DRIVER_KICKOFF=1 \
+pi --session "$HANDOFF_SESSION_NEGATIVE" -e "$PKG_ROOT" -p "/cook" >"$TMPDIR/pi-completion-handoff-negative.out" 2>"$TMPDIR/pi-completion-handoff-negative.err"
+
+python3 - "$HANDOFF_SNAPSHOT_NEGATIVE" "$TMPDIR/pi-completion-handoff-negative.out" "$TMPDIR/pi-completion-handoff-negative.err" <<'PY'
+import sys
+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(), 'negative handoff rationale should not emit a startup proposal snapshot'
+assert not Path('.agent').exists(), 'negative handoff rationale should fail closed without writing canonical state'
+assert '/cook failed closed' in output, 'negative handoff rationale should fail closed instead of becoming the startup mission'
+PY
+
 grep -q 'export async function deriveCookContextProposalFromRecentDiscussion' "$PKG_ROOT/extensions/completion/proposal.ts"
+grep -q 'export function extractLatestCookHandoffProposal' "$PKG_ROOT/extensions/completion/proposal.ts"
 grep -q 'export function parseContextProposalAnalystOutput' "$PKG_ROOT/extensions/completion/proposal.ts"
 grep -q 'export function buildContextProposalConfirmationLayout' "$PKG_ROOT/extensions/completion/prompt-surfaces.ts"
 grep -q 'export function buildEvaluationRoleContextLines' "$PKG_ROOT/extensions/completion/prompt-surfaces.ts"

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
@@ -18,19 +19,26 @@ checks = {
         "`/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.",
-        "`/cook` is the canonical workflow boundary and manual entry point",
-        "Discuss the concrete repo change in the main chat, then run `/cook`",
-        "The confirmed startup brief is also preserved there as advisory intake for later re-grounding.",
+        "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.",
+        "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`",
+        "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.",
+        "`/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.",
+        "The pre-`/cook` handoff capsule itself is not canonical workflow state. It is only startup intake for `/cook`.",
     ],
     "CHANGELOG.md": [
-        "made `/cook` derive a confirmable startup brief from recent discussion before any canonical workflow rewrite, then preserve the confirmed brief in canonical state as advisory intake for later re-grounding",
-        "removed inline `/cook` arguments from the shipped entry path again so explicit bare `/cook` is the only public command, and fail closed when recent discussion is insufficient or unreliable",
-        "added a pre-`/cook` ordinary-chat handoff boundary so the primary agent is instructed to stop at `/cook` once a task has matured into completion-workflow scope instead of starting long-running implementation directly in ordinary chat",
+        "made explicit primary-agent `/cook` handoff the preferred startup-intake path by teaching ordinary-chat handoff turns to emit a structured `cook_handoff` capsule and letting `/cook` prefer that capsule over broad context re-inference when it is fresh, valid, and implementation-startable",
+        "tightened implementation-ready explicit handoffs so the structured capsule must already carry a bounded `first_slice_goal`, repo-change-oriented acceptance, `implementation_surfaces`, `verification_commands`, and `why_this_slice_first` before `/cook` will start workflow from it",
+        "kept the pre-`/cook` handoff capsule as advisory startup intake only, not canonical `.agent/**` workflow state, while still using context-derived startup as the fallback only when no fresh explicit handoff is blocking startup",
+        "kept context-derived startup as a fallback only when there is no fresh explicit handoff blocking startup, so stale or invalidated capsules can still fall back to recent discussion while fresh non-startable handoffs fail closed instead of silently rewriting canonical state",
+        "made finished-workflow suppression stay a safety layer instead of a replacement mission when a fresh explicit `/cook` handoff exists, and blocked negative rejection/suppression text from becoming a Startable startup mission",
     ],
     "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',
-        '"If the task is still ordinary Q&A, lightweight brainstorming, or a tiny one-off fix, continue normally without forcing /cook."',
+        '"Distinguish a workflow-worthy handoff from an implementation-ready handoff: only emit the implementation-ready capsule when the first bounded implementation slice is concrete enough to start immediately."',
+        '"Otherwise append one exact fenced block in the same assistant reply using ```cook_handoff ... ``` JSON with kind/source/handoff_kind plus mission, scope, constraints or non_goals, acceptance, risks, notes, captured_at, source_turn_id, first_slice_goal, first_slice_non_goals, implementation_surfaces, verification_commands, why_this_slice_first, and optional task_type/evaluation_profile/why_cook_now."',
+        '"The capsule is startup intake for /cook only: do not present it as canonical .agent state',
     ],
 }
 

package/scripts/smoke-test.sh

@@ -170,6 +170,10 @@ assert handoff.exists(), 'ordinary non-/cook turn should inject the /cook handof
 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 '```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 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

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

@@ -35,11 +35,49 @@ When the task is judged ready for completion workflow, the primary agent must:
 - stop before long-running implementation
 - not edit tracked product files in ordinary chat for that workflow-level task
 - tell the user to run `/cook`
-- explain that `/cook` will derive a startup brief from recent discussion and ask for confirmation before workflow start
+- explain that `/cook` will first look for a fresh explicit primary-agent handoff and otherwise fall back to recent discussion before asking for confirmation
+- 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
+
+Required capsule format:
+
+````text
+```cook_handoff
+{
+  "kind": "cook_handoff",
+  "source": "primary_agent",
+  "captured_at": "<ISO-8601 timestamp>",
+  "source_turn_id": "<current assistant turn id>",
+  "mission": "<startable implementation mission>",
+  "scope": ["..."],
+  "constraints": ["..."],
+  "non_goals": ["..."],
+  "acceptance": ["..."],
+  "risks": ["..."],
+  "notes": ["..."],
+  "handoff_kind": "implementation_workflow_handoff",
+  "first_slice_goal": "<bounded first slice goal>",
+  "first_slice_non_goals": ["..."],
+  "implementation_surfaces": ["path/or/surface"],
+  "verification_commands": ["npm test -- example"],
+  "why_this_slice_first": "<why this first slice should start the workflow>",
+  "task_type": "completion-workflow",
+  "evaluation_profile": "completion-rubric-v1",
+  "why_cook_now": "<why the task is ready for /cook now>"
+}
+```
+````
+
+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, tell the user to run `/cook` without emitting this implementation-ready capsule.
+- 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.
 
 Suggested wording:
 
-> This task is now mature enough for the `/cook` workflow. If you want me to start implementation, run `/cook`. I’ll use our recent discussion to generate a startup brief for confirmation before the workflow begins.
+> This task is now mature enough for the `/cook` workflow. If you want me to start implementation, run `/cook`. I’ve also attached an explicit `/cook` handoff capsule so `/cook` can confirm this plan directly before the workflow begins.
 
 A short recap may include mission, scope, or acceptance, but that recap must not be presented as canonical plan state.