codebyplan 1.13.63 → 1.13.65

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.63",
+  "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-skill-context-guard.sh

@@ -1,11 +1,16 @@
 #!/bin/bash
 # @scope: org-shared
 # Hook: PreToolUse (Skill)
-# Purpose: Deny heavy close-out skills when context window > CBP_CONTEXT_WARN_TOKENS (default 200000).
-#          Reads transcript_path from stdin, sums the latest assistant message.usage — same logic
-#          as cbp-context-window-notify.sh. If total exceeds threshold AND the skill is in the
-#          heavy close-out allowlist, emits hookSpecificOutput.permissionDecision=deny directing
-#          Claude to run /cbp-clear-prep. Always exits 0 — fail-open.
+# 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);
+#          800K tokens for 1M-context models whose id contains "[1m]"
+#          (CBP_CONTEXT_WARN_TOKENS_1M, default 800000).
+#          Reads transcript_path from stdin, extracts the latest assistant message.usage
+#          AND model id in one pass — same logic as cbp-context-window-notify.sh.
+#          If total exceeds the tier threshold AND the skill is in the heavy close-out
+#          allowlist, emits hookSpecificOutput.permissionDecision=deny directing Claude
+#          to run /cbp-clear-prep. Always exits 0 — fail-open.
+#          No model id found → standard tier (fail-conservative).
 
 set -euo pipefail
 
@@ -17,8 +22,6 @@ TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null) || TRAN
 [ -z "$TRANSCRIPT" ] && exit 0
 [ ! -f "$TRANSCRIPT" ] && exit 0
 
-THRESHOLD="${CBP_CONTEXT_WARN_TOKENS:-200000}"
-
 # Heavy close-out allowlist (cbp-clear-prep + cbp-clear-continue deliberately excluded so
 # they always run even when context > threshold).
 HEAVY_SKILLS="cbp-round-build cbp-verify cbp-standalone-task-testing cbp-checkpoint-check cbp-checkpoint-end"
@@ -33,20 +36,37 @@ for heavy in $HEAVY_SKILLS; do
 done
 [ "$IS_HEAVY" = "false" ] && exit 0
 
-# Token sum — same logic as cbp-context-window-notify.sh
-TOTAL=$(tail -n 400 "$TRANSCRIPT" \
+# Extract model id AND token sum from the latest assistant message with usage, in one pass.
+# Outputs two tab-separated fields: MODEL_ID <tab> TOTAL.
+# Use cut -f1/f2 (not read -r A B) to correctly handle an empty first field (no .message.model).
+_TSV=$(tail -n 400 "$TRANSCRIPT" \
   | jq -rR 'fromjson? | select(.message.usage != null)
-      | (.message.usage
-         | ((.input_tokens // 0) + (.cache_creation_input_tokens // 0) + (.cache_read_input_tokens // 0)))' \
-  2>/dev/null | tail -1) || TOTAL=0
+      | [ (.message.model // ""),
+          ((.message.usage.input_tokens // 0)
+           + (.message.usage.cache_creation_input_tokens // 0)
+           + (.message.usage.cache_read_input_tokens // 0)) ]
+      | @tsv' 2>/dev/null | tail -1) || _TSV=""
+MODEL_ID=$(printf '%s' "${_TSV:-}" | cut -f1)
+TOTAL=$(printf '%s' "${_TSV:-}" | cut -f2)
+MODEL_ID="${MODEL_ID:-}"
 TOTAL="${TOTAL:-0}"
 
+# Tier selection: [1m] in model id → 1M tier; otherwise standard (fail-conservative)
+if printf '%s' "$MODEL_ID" | grep -qF '[1m]'; then
+  THRESHOLD="${CBP_CONTEXT_WARN_TOKENS_1M:-800000}"
+  TIER="1M"
+else
+  THRESHOLD="${CBP_CONTEXT_WARN_TOKENS:-200000}"
+  TIER="standard"
+fi
+
 if [ "$TOTAL" -ge "$THRESHOLD" ] 2>/dev/null; then
   jq -n \
     --argjson tokens "$TOTAL" \
     --argjson threshold "$THRESHOLD" \
     --arg skill "$SKILL_NAME" \
-    '{hookSpecificOutput:{permissionDecision:"deny",permissionDecisionReason:("Context window at \($tokens) tokens (threshold \($threshold)) is too large to safely run /\($skill). Run /cbp-clear-prep now to capture a handoff, then /clear, then /cbp-clear-continue to resume.")}}'
+    --arg tier "$TIER" \
+    '{hookSpecificOutput:{permissionDecision:"deny",permissionDecisionReason:("Context window at \($tokens) tokens (\($tier) tier, threshold \($threshold)) is too large to safely run /\($skill). Run /cbp-clear-prep now to capture a handoff, then /clear, then /cbp-clear-continue to resume.")}}'
 fi
 
 exit 0

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

@@ -374,6 +374,87 @@ fi
 
 echo ""
 
+# ===== HOOK SMOKE TESTS — cbp-mcp-caller-worktree-inject =====
+echo "## Hook Smoke Tests — cbp-mcp-caller-worktree-inject (CHK-198)"
+
+INJECT_HOOK="$HOOKS_DIR/cbp-mcp-caller-worktree-inject.sh"
+# Absolute path — the fail-open test runs the hook from a temp cwd (to isolate it
+# from this repo's git context), where the relative "$HOOKS_DIR" no longer resolves.
+INJECT_HOOK_ABS="$(cd "$HOOKS_DIR" 2>/dev/null && pwd)/cbp-mcp-caller-worktree-inject.sh"
+
+if [ ! -f "$INJECT_HOOK" ]; then
+  test_result "cbp-mcp-caller-worktree-inject.sh present" "passed" "missing"
+else
+  test_result "cbp-mcp-caller-worktree-inject.sh present" "passed" "passed"
+
+  FIRST_LINE=$(head -1 "$INJECT_HOOK")
+  if echo "$FIRST_LINE" | grep -q '^#!/'; then
+    test_result "cbp-mcp-caller-worktree-inject.sh has shebang" "passed" "passed"
+  else
+    test_result "cbp-mcp-caller-worktree-inject.sh has shebang" "passed" "missing"
+  fi
+
+  if grep -q '@scope: org-shared' "$INJECT_HOOK"; then
+    test_result "cbp-mcp-caller-worktree-inject.sh has @scope: org-shared" "passed" "passed"
+  else
+    test_result "cbp-mcp-caller-worktree-inject.sh has @scope: org-shared" "passed" "missing"
+  fi
+
+  # Fail-open: run from a non-repo temp dir with no worktree cache and no
+  # CLAUDE_PROJECT_DIR — neither the cache nor the CLI fallback can resolve a
+  # worktree, so the hook must exit 0 with empty stdout (no updatedInput).
+  ISO=$(mktemp -d)
+  OUTPUT=$( (cd "$ISO" && env -u CLAUDE_PROJECT_DIR bash "$INJECT_HOOK_ABS" <<< '{"tool_input":{"task_id":"x"}}') 2>/dev/null )
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-mcp-caller-worktree-inject.sh fail-open (unresolvable) exits 0 + empty stdout" "passed" "passed"
+  else
+    test_result "cbp-mcp-caller-worktree-inject.sh fail-open (unresolvable) exits 0 + empty stdout" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+  rm -rf "$ISO"
+
+  # C6 — input already carries a non-empty caller_worktree_id → never overwrite;
+  # early-return with exit 0 and empty stdout (no resolution attempted).
+  OUTPUT=$(echo '{"tool_input":{"caller_worktree_id":"11111111-1111-1111-1111-111111111111"}}' | bash "$INJECT_HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-mcp-caller-worktree-inject.sh C6 keeps existing caller_worktree_id (exit 0 + empty stdout)" "passed" "passed"
+  else
+    test_result "cbp-mcp-caller-worktree-inject.sh C6 keeps existing caller_worktree_id (exit 0 + empty stdout)" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+
+  # Injection — a worktree.local.json whose .branch matches the current git branch
+  # makes the cache fast-path resolve. Use a synthetic UUID so the assertion proves
+  # the cache value (not the live CLI) was injected. Skipped when no concrete git
+  # branch resolves (detached HEAD / non-git checkout) or jq is unavailable.
+  CUR_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+  if [ -n "$CUR_BRANCH" ] && [ "$CUR_BRANCH" != "HEAD" ] && command -v jq >/dev/null 2>&1; then
+    ISO=$(mktemp -d)
+    mkdir -p "$ISO/.codebyplan"
+    FAKE_WT="abcdef01-2345-6789-abcd-ef0123456789"
+    jq -n --arg b "$CUR_BRANCH" --arg w "$FAKE_WT" \
+      '{worktree_id:$w, branch:$b}' > "$ISO/.codebyplan/worktree.local.json"
+    OUTPUT=$(CLAUDE_PROJECT_DIR="$ISO" bash "$INJECT_HOOK" <<< '{"tool_input":{"task_id":"x"}}' 2>/dev/null)
+    EXIT_CODE=$?
+    INJECTED=$(echo "$OUTPUT" | jq -r '.hookSpecificOutput.updatedInput.caller_worktree_id // empty' 2>/dev/null)
+    # Sibling-key survival — CC's updatedInput REPLACES tool_input wholesale (it is
+    # not a partial merge), so the hook must echo back every original field merged
+    # with caller_worktree_id. Assert the non-target sibling key (task_id) survives;
+    # this is the assertion gap that let the replace-vs-merge bug ship in round 2.
+    PRESERVED=$(echo "$OUTPUT" | jq -r '.hookSpecificOutput.updatedInput.task_id // empty' 2>/dev/null)
+    if [ "$EXIT_CODE" = "0" ] && [ "$INJECTED" = "$FAKE_WT" ] && [ "$PRESERVED" = "x" ]; then
+      test_result "cbp-mcp-caller-worktree-inject.sh injects caller_worktree_id AND preserves sibling keys" "passed" "passed"
+    else
+      test_result "cbp-mcp-caller-worktree-inject.sh injects caller_worktree_id AND preserves sibling keys" "passed" "failed (exit=$EXIT_CODE injected=$INJECTED preserved=$PRESERVED)"
+    fi
+    rm -rf "$ISO"
+  else
+    test_result "cbp-mcp-caller-worktree-inject.sh injection test (no branch resolvable — skipped)" "passed" "passed"
+  fi
+fi
+
+echo ""
+
 # ===== HOOK SMOKE TESTS — cbp-session-start-hook =====
 echo "## Hook Smoke Tests — cbp-session-start-hook (CHK-178)"
 
@@ -533,6 +614,196 @@ 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) =====
+echo "## Hook Smoke Tests — cbp-skill-context-guard model-aware tier (CHK-224)"
+
+FIXTURES_GUARD_MODEL="$HOOKS_DIR/__test-fixtures__/cbp-skill-context-guard"
+
+# Case M1: standard model @201K → deny (standard tier, 200K threshold)
+if [ -f "$FIXTURES_GUARD_MODEL/over-threshold-standard.jsonl" ]; then
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD_MODEL/over-threshold-standard.jsonl" \
+    --arg s "cbp-round-build" \
+    '{transcript_path:$t,tool_input:{skill:$s}}')
+  OUTPUT=$(echo "$STDIN" | CBP_CONTEXT_WARN_TOKENS=200000 bash "$GUARD_HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] \
+     && echo "$OUTPUT" | jq -e '.hookSpecificOutput.permissionDecision == "deny"' >/dev/null 2>&1; then
+    test_result "cbp-skill-context-guard.sh standard model @201K → deny (standard tier)" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh standard model @201K → deny (standard tier)" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+  fi
+fi
+
+# Case M2: [1m] model @201K → empty stdout (allowed; 201K is below 800K 1M-tier threshold)
+if [ -f "$FIXTURES_GUARD_MODEL/over-threshold-1m.jsonl" ]; then
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD_MODEL/over-threshold-1m.jsonl" \
+    --arg s "cbp-round-build" \
+    '{transcript_path:$t,tool_input:{skill:$s}}')
+  OUTPUT=$(echo "$STDIN" | CBP_CONTEXT_WARN_TOKENS_1M=800000 bash "$GUARD_HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-skill-context-guard.sh [1m] model @201K → empty stdout (under 800K 1M tier)" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh [1m] model @201K → empty stdout (under 800K 1M tier)" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+  fi
+fi
+
+# Case M3: [1m] model @850K → deny (1M tier, 800K threshold)
+if [ -f "$FIXTURES_GUARD_MODEL/over-threshold-1m-denied.jsonl" ]; then
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD_MODEL/over-threshold-1m-denied.jsonl" \
+    --arg s "cbp-round-build" \
+    '{transcript_path:$t,tool_input:{skill:$s}}')
+  OUTPUT=$(echo "$STDIN" | CBP_CONTEXT_WARN_TOKENS_1M=800000 bash "$GUARD_HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] \
+     && echo "$OUTPUT" | jq -e '.hookSpecificOutput.permissionDecision == "deny"' >/dev/null 2>&1; then
+    test_result "cbp-skill-context-guard.sh [1m] model @850K → deny (1M tier)" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh [1m] model @850K → deny (1M tier)" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+  fi
+fi
+
+# Case M4: env override CBP_CONTEXT_WARN_TOKENS=150000 + standard model @201K → deny
+if [ -f "$FIXTURES_GUARD_MODEL/over-threshold-standard.jsonl" ]; then
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD_MODEL/over-threshold-standard.jsonl" \
+    --arg s "cbp-round-build" \
+    '{transcript_path:$t,tool_input:{skill:$s}}')
+  OUTPUT=$(echo "$STDIN" | CBP_CONTEXT_WARN_TOKENS=150000 bash "$GUARD_HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] \
+     && echo "$OUTPUT" | jq -e '.hookSpecificOutput.permissionDecision == "deny"' >/dev/null 2>&1; then
+    test_result "cbp-skill-context-guard.sh env CBP_CONTEXT_WARN_TOKENS=150000 + standard @201K → deny" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh env CBP_CONTEXT_WARN_TOKENS=150000 + standard @201K → deny" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+  fi
+fi
+
+# Case M5: env override CBP_CONTEXT_WARN_TOKENS_1M=900000 + [1m] model @850K → empty stdout (allowed)
+if [ -f "$FIXTURES_GUARD_MODEL/over-threshold-1m-denied.jsonl" ]; then
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD_MODEL/over-threshold-1m-denied.jsonl" \
+    --arg s "cbp-round-build" \
+    '{transcript_path:$t,tool_input:{skill:$s}}')
+  OUTPUT=$(echo "$STDIN" | CBP_CONTEXT_WARN_TOKENS_1M=900000 bash "$GUARD_HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-skill-context-guard.sh env CBP_CONTEXT_WARN_TOKENS_1M=900000 + [1m] @850K → empty stdout (override keeps allowed)" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh env CBP_CONTEXT_WARN_TOKENS_1M=900000 + [1m] @850K → empty stdout (override keeps allowed)" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+  fi
+fi
+
 # ===== STRUCTURAL ASSERTIONS — cbp-clear-* skills (CHK-217) =====
 echo ""
 echo "## Structural Assertions — cbp-clear-* skills (CHK-217)"

package/templates/rules/architecture-map.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - "apps/**"
+  - "packages/**"
+---
+
 # Architecture Map
 
 When `.claude/architecture/` exists in this repo, per-module map files may be present.

package/templates/rules/cbp-operating-gotchas.md

@@ -25,13 +25,11 @@ SHARED tooling behavior only — repo-specific gotchas belong in that repo's own
   clobbers existing `decisions` / `discoveries` / `check_results`. Always read the current row,
   merge your change into the full object/array, then write the whole thing back.
 
-- **User-level locks are invisible until a mutation they block.** `get_checkpoints` /
-  `get_tasks` succeed even when another user holds the assignment; the 403 fires only on
-  `update_*` / `complete_*`. The lock keys on the JWT user (`ctx.userId`) vs the row's
-  `assigned_user_id` (null = open). `caller_worktree_id` / `worktree_id` params are
-  accepted-and-ignored — do not thread them. Verify `assigned_user_id` matches
-  `npx codebyplan whoami` before mutating; recover a stale assignment with
-  `release_assignment` (maintainer).
+- **`resolve-worktree` empty output = a NULL `(device, path, branch)` tuple, not a broken
+  resolver.** When identity is unresolved the server can collapse the caller to the repo's main
+  worktree, so feat-locked writes get rejected. Pass `caller_worktree_id` on every MCP mutation,
+  and confirm ownership by matching the row's repo path + branch to the current directory before
+  mutating.
 
 - **Full-repo lint/type baselines are often pre-existing red.** A round must gate on the files
   it changed, not the whole-repo baseline — scope lint/tsc checks to the round's changed set so a
@@ -40,14 +38,30 @@ SHARED tooling behavior only — repo-specific gotchas belong in that repo's own
 - **`complete_task` checks file approval on the round's `files_changed`, not the task's.**
   Reconcile approvals via `update_round` (set each entry `user_approved: true`), not
   `update_task` alone — updating only the task leaves the round entries unapproved and
-  `complete_task` rejects with "files are not approved".
+  `complete_task` rejects with "files are not approved". After a merge-main pulls in foreign
+  files or carried directory-slash round artifacts, `complete_task` can hard-fail "N files not
+  approved"; fix by re-writing each affected round's `files_changed` via `update_round`.
 
-- **CLI transport uses REST (reads) and OAuth+MCP (writes) — a 502 from `codebyplan round sync-approvals` is transient MCP churn, not an outage.** The CLI exits 0 with a warning and MCP tools still work. A missing `CODEBYPLAN_API_KEY` surfaces as an `ApiError`, not a 502. `sync-approvals` can also drag untracked per-device dirs into `files_changed` — run it from the repo root.
+- **CLI transport uses REST (reads) and OAuth+MCP (writes) — a 502 from `codebyplan round sync-approvals` is transient MCP churn, not an outage.** The CLI exits 0 with a warning and MCP tools still work. A missing `CODEBYPLAN_API_KEY` surfaces as an `ApiError`, not a 502. `sync-approvals` can also drag untracked per-device dirs into `files_changed` — run it from the repo root or pass `--caller-worktree-id`.
 
 - **`codebyplan claude update` requires a TTY.** On non-TTY stdin (CI, piped) it half-applies then errors. Re-run with `--yes` to accept defaults non-interactively.
 
+- **Checkpoint locks are invisible until a mutation they block.** `get_checkpoints` / `get_tasks` succeed even when another worktree holds the lock; the 403 fires only on `update_*` / `complete_*`. Verify the row's `worktree_id` matches the caller before mutating. A null-`worktree_id` checkpoint can still be actively shipped by whichever worktree physically holds its feat branch — check `git worktree list` first.
+
+- **`update_task` accepts `caller_worktree_id` for lock-verify only — it does NOT assign ownership.** Ownership assignment goes through the web UI or the dedicated assignment path. Don't conflate `caller_worktree_id` with `assigned_worktree_id`.
+
 - **Re-run config-driven gates after merging main into a feat branch.** A merge can add or change `.codebyplan/shipment.json`, ports, branch config, `e2e.json`, and `eslint.json` — treat the post-merge state as a fresh baseline before continuing.
 
+- **MCP write calls can return 403 via Cloudflare WAF when the JSONB payload contains DDL
+  keywords (table-drop statements, function-drop statements, or raw query clauses).** Paraphrase
+  or base64-encode any user-provided SQL content before embedding it in a JSONB field — never
+  pass raw DDL verbatim in MCP context payloads.
+
+- **A "Merge origin/main" commit can integrate ZERO commits if it merged a stale local ref.**
+  Always `git fetch` and re-check the behind-count before treating a merge as complete — a
+  clean merge with no new commits is a sign the local ref was stale, not that the branch was
+  already up to date.
+
 ## Behavioral Preferences
 
 - **Never `git stash`** — for any reason. To inspect or compare other state use

package/templates/rules/e2e-mandatory.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - "apps/**"
+---
+
 # E2E Mandatory Run Contract
 
 E2E is **opt-out, not opt-in**. Whenever a framework configured in `.codebyplan/e2e.json`

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/rules/model-invocation-convention.md

@@ -32,7 +32,7 @@ not via `disable-model-invocation`:
    under what condition, so the intent is auditable and overridable.
 
 See `.claude/skills/cbp-build-cc-settings/reference/cbp-permission-policy.md` for the full
-`allow` vs `ask` split and the auto-trigger + 200K context-guard model.
+`allow` vs `ask` split and the auto-trigger + model-aware context-guard (200K standard / 800K on `[1m]` sessions).
 
 ## Related
 

package/templates/rules/scope-vocabulary.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - ".claude/**"
+---
+
 # Scope Vocabulary
 
 Canonical scope-marker enum for `.claude/` files. The marker classifies a structural file's distribution scope — but it is **required only on user-created files**, not on the assets the `codebyplan` package distributes.

package/templates/rules/task-routing-recommendation.md

@@ -45,7 +45,7 @@ After task completion, routes use single-directive form (never A/B/C menus):
 
 **Checkpoint-bound task complete:**
 - More tasks in checkpoint → auto-triggers next task (same context)
-- Last task in checkpoint → auto-triggers `cbp-checkpoint-check` (ask-tier permission prompt is the human gate; the 200K context guard handles oversized contexts)
+- Last task in checkpoint → auto-triggers `cbp-checkpoint-check` (ask-tier permission prompt is the human gate; the model-aware context guard handles oversized contexts — 200K standard, 800K on `[1m]` sessions)
 
 **Standalone task complete:**
 - Always → `Next: /cbp-session-end` (or `/cbp-standalone-task-create` for new work)