codebyplan 1.13.64 → 1.13.65

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.64",
+  "version": "1.13.65",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

package/templates/github-workflows/ci.yml

@@ -40,6 +40,8 @@ jobs:
   ci:
     name: Lint + typecheck + test + build
     runs-on: ubuntu-latest
+    # Cap the job so a hung step can't burn the 6h default and waste runner minutes.
+    timeout-minutes: 20
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -85,6 +87,9 @@ jobs:
   ci-strict:
     name: Strict whole-repo green{{STRICT_NAME_SUFFIX}}
     runs-on: ubuntu-latest{{STRICT_CONTINUE_ON_ERROR_LINE}}
+    # Whole-repo green is heavier than the soft tier; allow more headroom but
+    # still cap it so a hang can't run to the 6h default.
+    timeout-minutes: 30
     steps:
       - name: Checkout
         uses: actions/checkout@v4

package/templates/hooks/cbp-session-id-stamp.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# @scope: org-shared
+# Hook: SessionStart
+# Purpose: Stamp the Claude harness session UUID into
+#          .codebyplan/state/session/session-id.json so the CLI create-log path
+#          (and other session-aware tools) can correlate log entries with the
+#          running Claude session.
+#
+# Hook-safe: all errors are swallowed, always exits 0. Non-fatal / best-effort.
+# No-op when not inside a codebyplan repo or when the session UUID cannot be
+# derived from the hook payload.
+#
+# UUID derivation order:
+#   1. stdin JSON payload `.session_id` field
+#   2. basename (without extension) of `.transcript_path` field
+#   3. no-op — exit 0 without writing
+
+# C0 — require jq; if absent, exit 0 (fail-open).
+if ! command -v jq > /dev/null 2>&1; then
+  exit 0
+fi
+
+# Resolve the project dir: Claude Code sets CLAUDE_PROJECT_DIR; fall back to pwd.
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# No-op when not inside a codebyplan repo (sentinel file absent).
+if [ ! -f "$PROJECT_DIR/.codebyplan/repo.json" ]; then
+  exit 0
+fi
+
+# Read stdin once into a variable.
+INPUT=$(cat)
+
+# Derive the session UUID — try session_id field first.
+SESSION_UUID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+
+# Fall back to transcript_path basename (strip directory + extension).
+if [ -z "$SESSION_UUID" ]; then
+  TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+  if [ -n "$TRANSCRIPT" ]; then
+    BASENAME=$(basename "$TRANSCRIPT")
+    SESSION_UUID="${BASENAME%.*}"
+  fi
+fi
+
+# If still no UUID, nothing to write — exit gracefully.
+if [ -z "$SESSION_UUID" ]; then
+  exit 0
+fi
+
+# UUID guard — accept only a canonical UUID (8-4-4-4-12 hex) to avoid
+# stamping garbage values (e.g. a literal "null" or an arbitrary path stem).
+UUID_PATTERN='^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
+if ! printf '%s' "$SESSION_UUID" | grep -qE "$UUID_PATTERN"; then
+  exit 0
+fi
+
+# Ensure the target directory exists.
+SESSION_DIR="$PROJECT_DIR/.codebyplan/state/session"
+mkdir -p "$SESSION_DIR" 2>/dev/null || true
+
+# Stamp the session UUID with an ISO timestamp.
+STAMPED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null)
+printf '{"claude_session_id":"%s","stamped_at":"%s"}\n' "$SESSION_UUID" "$STAMPED_AT" \
+  > "$SESSION_DIR/session-id.json" 2>/dev/null || true
+
+exit 0

package/templates/hooks/cbp-test-hooks.sh

@@ -614,6 +614,111 @@ else
 
 fi
 
+# ===== HOOK SMOKE TESTS — cbp-session-id-stamp (CHK-231) =====
+echo "## Hook Smoke Tests — cbp-session-id-stamp (CHK-231)"
+
+STAMP_HOOK="$HOOKS_DIR/cbp-session-id-stamp.sh"
+
+if [ ! -f "$STAMP_HOOK" ]; then
+  test_result "cbp-session-id-stamp.sh present" "passed" "missing"
+else
+  test_result "cbp-session-id-stamp.sh present" "passed" "passed"
+
+  FIRST_LINE=$(head -1 "$STAMP_HOOK")
+  if echo "$FIRST_LINE" | grep -q '^#!/'; then
+    test_result "cbp-session-id-stamp.sh has shebang" "passed" "passed"
+  else
+    test_result "cbp-session-id-stamp.sh has shebang" "passed" "missing"
+  fi
+
+  if grep -q '@scope: org-shared' "$STAMP_HOOK"; then
+    test_result "cbp-session-id-stamp.sh has @scope: org-shared" "passed" "passed"
+  else
+    test_result "cbp-session-id-stamp.sh has @scope: org-shared" "passed" "missing"
+  fi
+
+  if bash -n "$STAMP_HOOK" 2>/dev/null; then
+    test_result "cbp-session-id-stamp.sh bash -n syntax ok" "passed" "passed"
+  else
+    test_result "cbp-session-id-stamp.sh bash -n syntax ok" "passed" "failed"
+  fi
+
+  # Case 1: session_id present in payload → session-id.json written with that UUID
+  ISO=$(mktemp -d)
+  mkdir -p "$ISO/.codebyplan"
+  printf '{}' > "$ISO/.codebyplan/repo.json"
+  FAKE_UUID="aaaabbbb-cccc-dddd-eeee-ffffffffffff"
+  PAYLOAD=$(jq -n --arg s "$FAKE_UUID" '{session_id:$s}')
+  EXIT_CODE=$(echo "$PAYLOAD" | CLAUDE_PROJECT_DIR="$ISO" bash "$STAMP_HOOK" >/dev/null 2>&1; echo $?)
+  STAMPED_ID=$(jq -r '.claude_session_id // empty' "$ISO/.codebyplan/state/session/session-id.json" 2>/dev/null)
+  if [ "$EXIT_CODE" = "0" ] && [ "$STAMPED_ID" = "$FAKE_UUID" ]; then
+    test_result "cbp-session-id-stamp.sh session_id present → session-id.json written with UUID" "passed" "passed"
+  else
+    test_result "cbp-session-id-stamp.sh session_id present → session-id.json written with UUID" "passed" "failed (exit=$EXIT_CODE stamped=$STAMPED_ID)"
+  fi
+  rm -rf "$ISO"
+
+  # Case 2: no session_id but transcript_path present (basename is a valid UUID) →
+  # UUID derived from transcript basename and written to session-id.json.
+  ISO=$(mktemp -d)
+  mkdir -p "$ISO/.codebyplan"
+  printf '{}' > "$ISO/.codebyplan/repo.json"
+  TRANSCRIPT_UUID="11112222-3333-4444-5555-666677778888"
+  PAYLOAD=$(jq -n --arg t "/tmp/sessions/${TRANSCRIPT_UUID}.jsonl" '{transcript_path:$t}')
+  EXIT_CODE=$(echo "$PAYLOAD" | CLAUDE_PROJECT_DIR="$ISO" bash "$STAMP_HOOK" >/dev/null 2>&1; echo $?)
+  STAMPED_ID=$(jq -r '.claude_session_id // empty' "$ISO/.codebyplan/state/session/session-id.json" 2>/dev/null)
+  if [ "$EXIT_CODE" = "0" ] && [ "$STAMPED_ID" = "$TRANSCRIPT_UUID" ]; then
+    test_result "cbp-session-id-stamp.sh transcript_path fallback → UUID derived from basename" "passed" "passed"
+  else
+    test_result "cbp-session-id-stamp.sh transcript_path fallback → UUID derived from basename" "passed" "failed (exit=$EXIT_CODE stamped=$STAMPED_ID)"
+  fi
+  rm -rf "$ISO"
+
+  # Case 3: neither session_id nor transcript_path → no-op (no file written), exit 0
+  ISO=$(mktemp -d)
+  mkdir -p "$ISO/.codebyplan"
+  printf '{}' > "$ISO/.codebyplan/repo.json"
+  PAYLOAD='{"tool_name":"some_tool"}'
+  EXIT_CODE=$(echo "$PAYLOAD" | CLAUDE_PROJECT_DIR="$ISO" bash "$STAMP_HOOK" >/dev/null 2>&1; echo $?)
+  STAMP_FILE="$ISO/.codebyplan/state/session/session-id.json"
+  if [ "$EXIT_CODE" = "0" ] && [ ! -f "$STAMP_FILE" ]; then
+    test_result "cbp-session-id-stamp.sh neither present → no-op, exit 0, no file written" "passed" "passed"
+  else
+    test_result "cbp-session-id-stamp.sh neither present → no-op, exit 0, no file written" "passed" "failed (exit=$EXIT_CODE file_exists=$([ -f "$STAMP_FILE" ] && echo yes || echo no))"
+  fi
+  rm -rf "$ISO"
+
+  # Case 4: outside a codebyplan repo (no .codebyplan/repo.json) → no-op, exit 0
+  ISO=$(mktemp -d)
+  FAKE_UUID="aaaabbbb-cccc-dddd-eeee-ffffffffffff"
+  PAYLOAD=$(jq -n --arg s "$FAKE_UUID" '{session_id:$s}')
+  EXIT_CODE=$(echo "$PAYLOAD" | CLAUDE_PROJECT_DIR="$ISO" bash "$STAMP_HOOK" >/dev/null 2>&1; echo $?)
+  STAMP_FILE="$ISO/.codebyplan/state/session/session-id.json"
+  if [ "$EXIT_CODE" = "0" ] && [ ! -f "$STAMP_FILE" ]; then
+    test_result "cbp-session-id-stamp.sh no repo.json → no-op, exit 0" "passed" "passed"
+  else
+    test_result "cbp-session-id-stamp.sh no repo.json → no-op, exit 0" "passed" "failed (exit=$EXIT_CODE file_exists=$([ -f "$STAMP_FILE" ] && echo yes || echo no))"
+  fi
+  rm -rf "$ISO"
+
+  # Case 5: session_id present but not a canonical UUID → guard rejects, no file written, exit 0
+  ISO=$(mktemp -d)
+  mkdir -p "$ISO/.codebyplan"
+  printf '{}' > "$ISO/.codebyplan/repo.json"
+  PAYLOAD=$(jq -n '{session_id:"not-a-valid-uuid"}')
+  EXIT_CODE=$(echo "$PAYLOAD" | CLAUDE_PROJECT_DIR="$ISO" bash "$STAMP_HOOK" >/dev/null 2>&1; echo $?)
+  STAMP_FILE="$ISO/.codebyplan/state/session/session-id.json"
+  if [ "$EXIT_CODE" = "0" ] && [ ! -f "$STAMP_FILE" ]; then
+    test_result "cbp-session-id-stamp.sh invalid UUID → guard rejects, no file written" "passed" "passed"
+  else
+    test_result "cbp-session-id-stamp.sh invalid UUID → guard rejects, no file written" "passed" "failed (exit=$EXIT_CODE file_exists=$([ -f "$STAMP_FILE" ] && echo yes || echo no))"
+  fi
+  rm -rf "$ISO"
+
+fi
+
+echo ""
+
 echo ""
 
 # ===== HOOK SMOKE TESTS — cbp-skill-context-guard model-aware tier (CHK-224) =====

package/templates/rules/handoff-file-convention.md

@@ -0,0 +1,65 @@
+# Handoff File Convention
+
+Per-level handoff notes for cross-session context. Files live under
+`.codebyplan/handoff/` and are committed (negation entry `!.codebyplan/handoff/`
+in the managed `.gitignore` block).
+
+## Layout
+
+| Level      | Path template                                    | Number format     |
+|------------|--------------------------------------------------|-------------------|
+| repo       | `.codebyplan/handoff/repo.md`                    | n/a (per-section) |
+| checkpoint | `.codebyplan/handoff/checkpoint/<NNN>.md`        | 3-digit zero-pad  |
+| task       | `.codebyplan/handoff/task/<NNN>-<T>.md`          | CHK zero-pad + T  |
+| standalone | `.codebyplan/handoff/standalone/<N>.md`          | bare number       |
+
+## repo.md — per-worktree sections
+
+`repo.md` uses `## <worktree-label>` sections so multiple worktrees can write
+to the same file without conflict. Label resolution order:
+
+1. Read `.codebyplan/state/worktrees.json`; find entry whose `branch` matches
+   the current git branch; use its `name`.
+2. Fallback: git branch name with `/` replaced by `-`.
+
+Each CLI verb (`write`, `append`, `clear`) operates on the current worktree's
+section only. Merge conflicts are structurally impossible: two worktrees write
+to different `##` sections of the same file.
+
+## Empty = absent / whitespace-only
+
+A handoff is considered **empty** when the file is absent OR its content is
+whitespace-only. The CLI deletes the file when it becomes empty:
+
+- Non-repo levels: `write --content ""` and `clear` both delete the file.
+- repo level: `write --content ""` and `clear` remove the current worktree's
+  `##` section; the file is deleted when no non-empty sections remain.
+
+All delete operations swallow ENOENT (idempotent).
+
+## CLI verbs
+
+```
+codebyplan handoff read    --level <l> [--number N] [--task T]
+codebyplan handoff write   --level <l> [--number N] [--task T] --content "..."
+codebyplan handoff append  --level <l> [--number N] [--task T] --content "..."
+codebyplan handoff clear   --level <l> [--number N] [--task T]
+codebyplan handoff status  [--json]
+```
+
+## status --json shape (stable contract)
+
+```json
+{
+  "nonEmpty": [{ "level": "checkpoint", "identifier": "005", "path": "/abs/path" }],
+  "empty":    []
+}
+```
+
+`status` is consumed by TASK-3 session-start/end gates to decide whether a
+handoff prompt is shown. TASK-4 web UI reads the same files via the API.
+
+## Content format
+
+Freeform markdown. No structured schema is enforced; the files are human-written
+notes surfaced to Claude at session boundaries.

package/templates/settings.project.base.json

@@ -252,13 +252,29 @@
       "Bash(codebyplan cd:*)",
       "Bash(npx codebyplan cd:*)",
       "Bash(codebyplan cleanup-plan-folders:*)",
-      "Bash(npx codebyplan cleanup-plan-folders:*)"
+      "Bash(npx codebyplan cleanup-plan-folders:*)",
+      "Bash(codebyplan handoff:*)",
+      "Bash(npx codebyplan handoff:*)"
     ]
   },
   "attribution": {
     "commit": "",
     "pr": ""
   },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "_owner": "codebyplan-claude",
+            "_hook_id": "cbp-session-id-stamp.sh",
+            "type": "command",
+            "command": "bash ./.claude/hooks/cbp-session-id-stamp.sh"
+          }
+        ]
+      }
+    ]
+  },
   "showClearContextOnPlanAccept": false,
   "syntaxHighlightingDisabled": false
 }

package/templates/skills/cbp-checkpoint-complete/SKILL.md

@@ -72,6 +72,38 @@ Complete remaining tasks first, then run `/cbp-checkpoint-complete`.
 ```
 Stop here.
 
+### Step 2.6: Verify Checkpoint Handoff Is Resolved
+
+Run `codebyplan handoff status --json` and parse the output.
+
+Check if `nonEmpty[]` contains an entry where `level === 'checkpoint'` AND `identifier === '{NNN}'`
+(the 3-digit zero-padded checkpoint number — e.g. `231`).
+
+If a matching entry is found, BLOCK with:
+
+```
+## Cannot Complete Checkpoint — Handoff Unresolved
+
+CHK-[NNN] has unresolved handoff content at `.codebyplan/handoff/checkpoint/[NNN].md`.
+
+The handoff file contains scope that has not been resolved. You must clear it before
+completing this checkpoint. Three options — pick exactly one:
+
+1. **Absorb** — address the pending scope now, then clear:
+   `codebyplan handoff clear --level checkpoint --number [NNN]`
+2. **Defer** — create a follow-up checkpoint or standalone task to cover the scope,
+   then clear: `codebyplan handoff clear --level checkpoint --number [NNN]`
+3. **Escalate** — move the content to the repo handoff:
+   `codebyplan handoff append --level repo --content "<content>"`
+   then clear: `codebyplan handoff clear --level checkpoint --number [NNN]`
+
+Never silently delete handoff content — it represents tracked scope.
+```
+
+(STOP)
+
+If no matching entry: continue to Step 3.
+
 ### Step 3: Aggregate QA
 
 Collect QA results from all tasks and rounds. Build checkpoint-level QA summary:

package/templates/skills/cbp-clear-continue/SKILL.md

@@ -48,6 +48,28 @@ Resuming from handoff:
   Next action:    /<next-action>
 ```
 
+### Step 2.5 — Surface committed handoffs
+
+Surface any committed handoff files before proceeding. Non-blocking.
+
+1. Run `codebyplan handoff status --json` → parse `nonEmpty[]`.
+2. If `nonEmpty` is empty → skip silently.
+3. For each entry in `nonEmpty`, read the content:
+   - `repo` → `codebyplan handoff read --level repo`
+   - `checkpoint` → `codebyplan handoff read --level checkpoint --number <identifier>`
+   - `task` → split identifier `"<NNN>-<T>"` → `codebyplan handoff read --level task --number <NNN> --task <T>`
+   - `standalone` → `codebyplan handoff read --level standalone --number <identifier>`
+4. Display:
+   ```
+   Handoff notes from previous session(s):
+
+   [<level>: <identifier>]
+   <content>
+
+   ---
+   ```
+5. Non-blocking — proceed to Step 3 regardless.
+
 ### Step 3 — Delete the handoff BEFORE re-invoking
 
 Delete `.codebyplan/clear/handoff.md` once its contents have been read and displayed:
@@ -80,7 +102,7 @@ the guard will deny again. Follow the same cycle: `/cbp-clear-prep` → `/clear`
 ## Integration
 
 - **Invoked by**: user after `/clear` following `/cbp-clear-prep`
-- **Reads**: `.codebyplan/clear/handoff.md`
+- **Reads**: `.codebyplan/clear/handoff.md` (Step 1); `codebyplan handoff status --json` + `codebyplan handoff read` (Step 2.5 — committed handoff surfacing)
 - **Deletes**: `.codebyplan/clear/handoff.md` (Step 3, before resuming)
 - **Then invokes**: the skill from `next_action` via Skill tool
 - **Companion**: `.claude/skills/cbp-clear-prep/SKILL.md` writes the handoff

package/templates/skills/cbp-clear-prep/SKILL.md

@@ -86,6 +86,27 @@ next_action: /<skill-name> <args if any>
 After /clear, run: /cbp-clear-continue
 ```
 
+### Step 4.5 — Flush carryover to committed handoff
+
+If `checkpoint_number` from Step 2 is `unknown` → skip silently (no reliable key).
+
+Otherwise:
+
+1. Compose a brief carryover note:
+   ```markdown
+   ## Context-clear carryover — CHK-<N>
+
+   Captured: <ISO now>
+   Blocked skill: <blocked_skill>
+   Next action: `<next_action>`
+
+   <in-flight notes from Step 3>
+   ```
+2. Run `codebyplan handoff write --level checkpoint --number <N> --content "<content>"`.
+3. Output: `Carryover handoff written to .codebyplan/handoff/checkpoint/<NNN>.md`.
+
+Non-blocking — Step 5 continues regardless.
+
 ### Step 5 — Instruct the user
 
 Output exactly this summary (fill in the real values):
@@ -116,7 +137,7 @@ The user must run both commands manually.
 ## Integration
 
 - **Invoked when**: `cbp-skill-context-guard` PreToolUse hook emits `permissionDecision: deny`
-- **Writes**: `.codebyplan/clear/handoff.md`
+- **Writes**: `.codebyplan/clear/handoff.md` (Step 4 — transient, gitignored); `codebyplan handoff write --level checkpoint --number <N>` (Step 4.5 — committed carryover flush; skipped when checkpoint_number unknown)
 - **Next**: user runs `/clear`, then `/cbp-clear-continue`
 - **Companion**: `.claude/skills/cbp-clear-continue/SKILL.md` reads `.codebyplan/clear/handoff.md`
 - **Guard hook**: `.claude/hooks/cbp-skill-context-guard.sh` — fires when context exceeds the model-aware threshold: `CBP_CONTEXT_WARN_TOKENS` (default 200000) for standard models; `CBP_CONTEXT_WARN_TOKENS_1M` (default 800000) for `[1m]`-context models. No model id found → standard tier (fail-conservative).

package/templates/skills/cbp-finalize/SKILL.md

@@ -85,6 +85,42 @@ Stop here.
 
 `task.context.verify_verdict` must exist and have `verdict: 'READY'` (written by `/cbp-verify` Phase 6 when it runs at task scope — whole-repo `codebyplan check --scope task`, holistic `cbp-verify-reviewer`, and the single batched human walkthrough all passed). If absent or not `READY`, surface "Run `/cbp-verify` first" and stop.
 
+### Step 2.6: Verify Task Handoff Is Resolved
+
+Run `codebyplan handoff status --json` and parse the output.
+
+Check if `nonEmpty[]` contains an entry where `level === 'task'` AND `identifier === '{NNN}-{T}'`
+(the 3-digit zero-padded checkpoint number, hyphen, task number — e.g. `231-3`).
+
+> Gate scope is intentional: only **task**-level handoffs block here. Checkpoint-level handoffs
+> (written by `/cbp-session-end` as resume-pointers) are deliberately scoped to
+> `/cbp-checkpoint-complete`, NOT task finalize — do not "fix" this to gate on checkpoint level.
+
+If a matching entry is found, BLOCK with:
+
+```
+## Cannot Complete Task — Handoff Unresolved
+
+TASK-[N] has unresolved handoff content at `.codebyplan/handoff/task/[NNN]-[T].md`.
+
+The handoff file contains scope that has not been resolved. You must clear it before
+completing this task. Three options — pick exactly one:
+
+1. **Absorb** — address the pending scope in current work, then clear:
+   `codebyplan handoff clear --level task --number [NNN] --task [T]`
+2. **Defer** — create a follow-up task or standalone task to cover the scope,
+   then clear: `codebyplan handoff clear --level task --number [NNN] --task [T]`
+3. **Escalate** — move the content to the repo handoff:
+   `codebyplan handoff append --level repo --content "<content>"`
+   then clear: `codebyplan handoff clear --level task --number [NNN] --task [T]`
+
+Never silently delete handoff content — it represents tracked scope.
+```
+
+(STOP)
+
+If no matching entry: continue to Step 3.
+
 ### Step 3: Verify QA and File Approval
 
 Load `task.qa` and `task.files_changed`:

package/templates/skills/cbp-session-end/SKILL.md

@@ -22,46 +22,44 @@ Always write a session log for this session — **even if empty**. `/cbp-session
 2. Pull facts from local state files rather than narrating from memory:
    - Rounds added/completed, tasks advanced/completed during this session (read from `.codebyplan/state/checkpoints/` subtree)
    - Decisions, blockers, or discoveries recorded in checkpoint/task context
-3. Run `codebyplan session update-log --id <log-id> --ended-at <now> --summary <text> --pending <text> --git-branch <current-branch>` (CLI write-through: updates `.codebyplan/state/session/current.json` + REST). Break-glass fallback: MCP `update_session_log` when the CLI is unavailable. Fields:
+3. Run `codebyplan session update-log --id <log-id> --ended-at <now> --git-branch <current-branch>` (CLI write-through: updates `.codebyplan/state/session/current.json` + REST). Break-glass fallback: MCP `update_session_log` when the CLI is unavailable. Fields:
    - `ended_at`: now (maps to the `closed_at` column per TASK-2 alias)
-   - `summary`: concise — may be empty if nothing happened
-   - `pending`: open items the next session should see first
    - `git_branch`: the current git branch (informational; `git rev-parse --abbrev-ref HEAD`)
-   - **Do NOT pass `--handoff` / `handoff` field.** The DB handoff field is no longer written here. Omit entirely — never pass `handoff:null` (it clobbers summary/pending content).
+   - Carryover notes now go to committed `.codebyplan/handoff/` files (Step 1.3) — not the session log.
 
 ### Step 1.3: Optional Handoff File (mid-work only)
 
 When an active in-progress task or round exists, offer to write a handoff file so the next session can auto-resume. Skip entirely when not mid-work.
 
-1. Read `.codebyplan/state/todos.json` (local-first) and check `rows[0]` (queue head, ordered by `sort_order`). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_todos({ repo_id })` when the state dir is absent and sync fails. The worker stamps `command`, `instructions`, `state`, and entity ids `checkpoint_id` / `task_id` / `round_id` on every row.
+1. Read `.codebyplan/state/todos.json` (local-first) and check `rows[0]` (queue head, ordered by `sort_order`). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_todos({ repo_id })` when the state dir is absent and sync fails.
 
 2. **If `rows[0]` exists and its `command` is non-empty** (active work in flight):
-   - Determine the handoff file path. The directory is keyed by the human-facing **number** (`<NNN>` checkpoint number / `<N>` standalone task number) — matching the committed `.codebyplan/checkpoint/<NNN>/` plan-artifact convention and the session-start resume probe (which globs by number). Resolve the number from local state (break-glass: MCP):
-     - Checkpoint work: read `.codebyplan/state/checkpoints/<rows[0].checkpoint_id>.json` → `number` (break-glass: MCP `get_checkpoints`). Path: `.codebyplan/checkpoint/<NNN>/handoff.md`.
-     - Standalone work: read the standalone task's `number` from local standalone state (break-glass: MCP `get_standalone_tasks`). Path: `.codebyplan/standalone/<N>/handoff.md`.
-   - Offer to write the file:
+   - Resolve the level and number (level is `checkpoint`/`standalone`, NOT `task` — a session-end
+     handoff is a checkpoint-scope resume-pointer; `task`-level handoffs are reserved for explicit
+     user-deferred scope and gate only `/cbp-finalize`):
+     - Checkpoint work: read `.codebyplan/state/checkpoints/<rows[0].checkpoint_id>.json` → `number` (break-glass: MCP `get_checkpoints`). Level: `checkpoint`, number: `<NNN>` (3-digit zero-pad).
+     - Standalone work: read the standalone task `number` from local standalone state (break-glass: MCP `get_standalone_tasks`). Level: `standalone`, number: `<N>`.
+   - Offer to write:
      ```
-     Write handoff file for next session?
-     <path>
+     Write handoff for next session?
+     .codebyplan/handoff/<level>/<identifier>.md
 
      Reply: yes | no
      ```
-   - On `yes`: write the file with this structure:
+   - On `yes`: run `codebyplan handoff write --level <level> --number <N> --content "<content>"` where content is:
      ```markdown
-     ---
-     command: <rows[0].command>
-     state: <rows[0].state>
-     captured_at: <ISO now>
-     checkpoint_id: <rows[0].checkpoint_id or null>
-     task_id: <rows[0].task_id or null>
-     round_id: <rows[0].round_id or null>
-     ---
-
-     <rows[0].instructions — human-readable trigger reason>
+     ## Session handoff — CHK-<N>
+
+     Captured: <ISO now>
+     Next action: `<rows[0].command>`
+
+     <rows[0].instructions>
      ```
-   - The file is committed with the session's final commit (Step 1.5) or the user can stage it manually.
+     (Standalone variant: `## Session handoff — TASK-<N>` heading.)
+   - On `no`: skip — do not create an empty file.
+   - The committed file is picked up by the Step 1.5 infra-commit offer automatically (it lives under the managed `.gitignore` negation `!.codebyplan/handoff/`).
 
-3. **If the queue is empty or `rows[0].command` is empty/idle**: skip — no handoff file is written.
+3. **If the queue is empty or `rows[0].command` is empty/idle**: skip.
 
 ### Step 1.5: Commit Non-Task Files
 
@@ -146,7 +144,7 @@ You can close this window.
 
 - **Triggered by**: user invocation (prompted by `/cbp-todo` when no work remains)
 - **Reads**: `.codebyplan/repo.json`; local-first reads (with `npx codebyplan sync` + MCP break-glass): `.codebyplan/state/session/current.json` (Step 1 resolve log), `.codebyplan/state/todos.json` (Step 1.3 mid-work detection + Step 1.5 active-task lookup), `.codebyplan/state/checkpoints/<id>/tasks/<id>/rounds/` (Step 1.5 task-file resolution); `codebyplan session freshness-gate` (Step 1.7 package-freshness gate, without --halt-on-update); `codebyplan session infra-files --json --task-files <csv>` (Step 1.5 infra-file set math)
-- **Writes**: `codebyplan session update-log --id <id> --git-branch <branch> ...` (Step 1 finalize — CLI write-through to `.codebyplan/state/session/current.json`; break-glass: MCP `update_session_log`; handoff field never passed), `codebyplan session create-log` (Step 1 fallback when no log exists; break-glass: MCP `create_session_log`), optional handoff file at `.codebyplan/checkpoint/<NNN>/handoff.md` or `.codebyplan/standalone/<N>/handoff.md` (Step 1.3, mid-work only), `codebyplan session update-state --action deactivate` (Step 3 — CLI write-through to `.codebyplan/state/session/state.json`; break-glass: MCP `update_session_state`)
+- **Writes**: `codebyplan session update-log --id <id> --ended-at <now> --git-branch <branch>` (Step 1 finalize — CLI write-through to `.codebyplan/state/session/current.json`; break-glass: MCP `update_session_log`; summary/pending/handoff fields never passed), `codebyplan session create-log` (Step 1 fallback when no log exists; break-glass: MCP `create_session_log`), `codebyplan handoff write --level <checkpoint|standalone> --number <N>` (Step 1.3, mid-work only, committed under `.codebyplan/handoff/`), `codebyplan session update-state --action deactivate` (Step 3 — CLI write-through to `.codebyplan/state/session/state.json`; break-glass: MCP `update_session_state`)
 - **Spawns**: none
 - **Triggers**: none at the skill-contract level. Step 1.5 may invoke `/cbp-git-commit` inline on user approval; Step 1.7 may invoke `/cbp-git-commit` on the `result === 'updated'` path (committing changed `.claude/` and `.codebyplan/` paths).
 - **Paired with**: `/cbp-session-start`

package/templates/skills/cbp-session-start/SKILL.md

@@ -78,7 +78,29 @@ The envelope shape:
 **Parse and branch**:
 
 - `status === 'update_halt'` → print `rendered_block` (the update-halt message) and **STOP**. No further writes, no `/cbp-todo` trigger.
-- Otherwise → print `rendered_block` (the Step 6 output block), then proceed to Step 5.7 and Step 7.
+- Otherwise → print `rendered_block` (the Step 6 output block), then proceed to Step 5.5, Step 5.7, and Step 7.
+
+### Step 5.5: Surface Committed Handoff Notes
+
+After printing the orchestrator output, surface any committed handoff files from previous sessions. Non-blocking.
+
+1. Run `codebyplan handoff status --json` → parse `nonEmpty[]`.
+2. If `nonEmpty` is empty → skip silently.
+3. For each entry in `nonEmpty`, read the content:
+   - `repo` → `codebyplan handoff read --level repo`
+   - `checkpoint` → `codebyplan handoff read --level checkpoint --number <identifier>`
+   - `task` → split identifier `"<NNN>-<T>"` → `codebyplan handoff read --level task --number <NNN> --task <T>`
+   - `standalone` → `codebyplan handoff read --level standalone --number <identifier>`
+4. Display:
+   ```
+   Handoff notes from previous session(s):
+
+   [<level>: <identifier>]
+   <content>
+
+   ---
+   ```
+5. Non-blocking — proceed to Step 5.7 regardless.
 
 ### Step 5.7: Commit Non-Task Files (Claude-side)
 
@@ -109,7 +131,7 @@ Route from `envelope.next_action`:
 ## Integration
 
 - **Triggered by**: user invocation, `/clear` recovery
-- **Reads**: MCP `health_check` (Step 0 hard gate — stays MCP unconditionally); `codebyplan session start --json` (Steps 1–5.8 — the orchestrator runs `codebyplan whoami --json` for caller identity and reads `.codebyplan/repo.json`, `.codebyplan/git.json`, `.codebyplan/state/session/current.json`, `.codebyplan/state/todos.json`, `.codebyplan/state/checkpoints/` entity files, `scripts/infra-drift.mjs`, `.codebyplan/architecture.json`, `.codebyplan/lsp.json`)
+- **Reads**: MCP `health_check` (Step 0 hard gate — stays MCP unconditionally); `codebyplan session start --json` (Steps 1–5.8 — the orchestrator runs `codebyplan whoami --json` for caller identity and reads `.codebyplan/repo.json`, `.codebyplan/git.json`, `.codebyplan/state/session/current.json`, `.codebyplan/state/todos.json`, `.codebyplan/state/checkpoints/` entity files, `scripts/infra-drift.mjs`, `.codebyplan/architecture.json`, `.codebyplan/lsp.json`); `codebyplan handoff status --json` + `codebyplan handoff read --level <l> ...` (Step 5.5 — committed handoff surfacing)
 - **Writes**: orchestrator calls `codebyplan session update-state --action activate` (Step 7) and `codebyplan session create-log` (Step 8 — user-level; no worktree_id in the body) — both SKIPPED on Step 0 hard-fail and on `status: update_halt`
 - **Spawns**: none
 - **Triggers**: `/cbp-git-commit` (conditional, on user approval at Step 5.7), `envelope.handoff.command` (on `next_action: resume_handoff`), `/cbp-todo` (on `next_action: trigger_todo` or `commit_then_todo`); STOPS with no trigger on `next_action: stop` or `mcp_update_halt`

package/templates/skills/cbp-standalone-task-complete/SKILL.md

@@ -80,6 +80,38 @@ Stop here.
 
 `task.context.task_testing_output` must exist with `all_passed: true`. If not, surface "Run `/cbp-standalone-task-testing` first" and stop.
 
+### Step 2.7: Verify Standalone Task Handoff Is Resolved
+
+Run `codebyplan handoff status --json` and parse the output.
+
+Check if `nonEmpty[]` contains an entry where `level === 'standalone'` AND `identifier === '{N}'`
+(the bare standalone task number — e.g. `45`).
+
+If a matching entry is found, BLOCK with:
+
+```
+## Cannot Complete Standalone Task — Handoff Unresolved
+
+Standalone TASK-[N] has unresolved handoff content at `.codebyplan/handoff/standalone/[N].md`.
+
+The handoff file contains scope that has not been resolved. You must clear it before
+completing this task. Three options — pick exactly one:
+
+1. **Absorb** — address the pending scope in current work, then clear:
+   `codebyplan handoff clear --level standalone --number [N]`
+2. **Defer** — create a new standalone task to cover the scope,
+   then clear: `codebyplan handoff clear --level standalone --number [N]`
+3. **Escalate** — move the content to the repo handoff:
+   `codebyplan handoff append --level repo --content "<content>"`
+   then clear: `codebyplan handoff clear --level standalone --number [N]`
+
+Never silently delete handoff content — it represents tracked scope.
+```
+
+(STOP)
+
+If no matching entry: continue to Step 3.
+
 ### Step 3: Verify QA and File Approval
 
 Load `task.qa` and `task.files_changed`: