codebyplan 1.13.64 → 1.13.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.64",
+  "version": "1.13.66",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {
@@ -52,18 +52,17 @@
     "registry": "https://registry.npmjs.org/"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "dependencies": {
     "@napi-rs/keyring": "^1.1.6",
-    "@supabase/supabase-js": "^2.106.0",
-    "ws": ">=8.20.1"
+    "@supabase/supabase-js": "^2.106.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",
-    "@types/node": "^20",
+    "@types/node": "^22",
     "@vitest/eslint-plugin": "^1.1.44",
-    "esbuild": ">=0.28.1",
+    "esbuild": "^0.28.1",
     "eslint": "^9.18.0",
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-no-secrets": "^2.2.1",

package/templates/agents/cbp-security-agent.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-security-agent
 description: Security review specialist. Checks for OWASP top 10 vulnerabilities, hardcoded secrets, SQL injection, XSS, CSRF, and dependency vulnerabilities.
 tools: Read, Glob, Grep, Bash

package/templates/agents/cbp-stripe-agent.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-stripe-agent
 description: Stripe integration specialist. Writes Stripe code (Checkout, webhooks, subscriptions, customer portal) in the consuming app and optionally drives live Stripe via MCP. Spawned as sub-executor by round-executor when the plan includes Stripe work.
 tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion

package/templates/agents/cbp-testing-qa-agent.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-testing-qa-agent
 description: Combined testing, QA generation, and default checklists. Runs build/lint/types/unit-tests/audit, generates auto QA items, applies default production checklists. Does NOT consume e2e screenshots or frontend-ui findings.
 tools: Read, Glob, Grep, Bash, AskUserQuestion

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-skill-context-guard.sh

@@ -1,5 +1,4 @@
 #!/bin/bash
-# @scope: org-shared
 # Hook: PreToolUse (Skill)
 # Purpose: Deny heavy close-out skills when context window exceeds the model-aware threshold:
 #          200K tokens for standard models (CBP_CONTEXT_WARN_TOKENS, default 200000);

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/hooks/validate-structure-lib.sh

@@ -103,17 +103,44 @@ has_scope_comment() {
 }
 
 # has_template_twin <rel_path_under_claude>
-# Returns 0 when the codebyplan package ships a template twin for this .claude file
-# (i.e. the file is package-MANAGED — org-shared is its implicit default and a
-# scope marker is NOT required). <rel_path_under_claude> is the path beneath
-# .claude/ (e.g. "rules/foo.md", "skills/x/SKILL.md").
-#   Monorepo: $REPO_ROOT/packages/codebyplan-package/templates/<rel>
-#   Consumer: $REPO_ROOT/node_modules/codebyplan/templates/<rel>
-# Returns non-zero when no twin is found — including when no templates dir is
-# resolvable at all. Callers treat a non-zero result as "user-created", which is
-# the conservative fallback: a scope marker is then required (legacy behavior).
+# Returns 0 when the file is package-MANAGED (a template twin exists) — org-shared
+# is its implicit default and a scope marker is NOT required. <rel_path_under_claude>
+# is the path beneath .claude/ (e.g. "rules/foo.md", "skills/x/SKILL.md").
+#
+# Resolution order:
+#   1. The install manifest (.claude/.cbp.manifest.json, with mid/legacy filename
+#      fallback). Its files[].dest entries are the authoritative record of what
+#      codebyplan installed INTO THIS repo — independent of where the package
+#      lives on disk (pnpm symlinks, hoisting, monorepo sub-packages). Requires jq.
+#   2. Filesystem probe of the package's templates dir — fallback when there is no
+#      manifest/jq, and a backstop so a stale manifest never hides a genuine twin:
+#        Monorepo: $REPO_ROOT/packages/codebyplan-package/templates/<rel>
+#        Consumer: $REPO_ROOT/node_modules/codebyplan/templates/<rel>
+# Returns non-zero when no twin is found by either path. Callers treat non-zero as
+# "user-created": a scope marker is then required (the conservative fallback).
 has_template_twin() {
   local rel="$1"
+
+  # 1. Authoritative: the install manifest lists every managed file by dest path.
+  if command -v jq >/dev/null 2>&1; then
+    local manifest
+    for manifest in \
+      "$REPO_ROOT/.claude/.cbp.manifest.json" \
+      "$REPO_ROOT/.claude/.cbp-claude.manifest.json" \
+      "$REPO_ROOT/.claude/.codebyplan-claude.manifest.json"; do
+      if [ -f "$manifest" ]; then
+        if jq -e --arg rel "$rel" 'any(.files[]?; .dest == $rel)' "$manifest" >/dev/null 2>&1; then
+          return 0
+        fi
+        # Manifest found but does not list this file — stop scanning older
+        # manifest names and fall through to the filesystem probe (a stale
+        # manifest must not hide a genuine template twin).
+        break
+      fi
+    done
+  fi
+
+  # 2. Fallback / backstop: probe the package's templates dir directly.
   [ -f "$REPO_ROOT/packages/codebyplan-package/templates/$rel" ] && return 0
   [ -f "$REPO_ROOT/node_modules/codebyplan/templates/$rel" ] && return 0
   return 1

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-check/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-check
 description: Full re-evaluation of a checkpoint with before/after comparison
 argument-hint: [CHK-NNN]

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

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-clear-continue
 description: Resume work after /clear by reading .codebyplan/clear/handoff.md and re-invoking the previously-blocked heavy skill. Reports a friendly error if no handoff file exists.
 model: inherit
@@ -48,6 +47,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 +101,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

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-clear-prep
 description: Capture a clear-context handoff when the context window is too large to run a heavy skill. Reads active task/round state, writes .codebyplan/clear/handoff.md, then instructs the user to run /clear and /cbp-clear-continue to resume.
 argument-hint: "[blocked-skill]"
@@ -86,6 +85,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 +136,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`: