codebyplan 1.13.49 → 1.13.51

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

@@ -527,6 +527,150 @@ fi
 
 echo ""
 
+# ===== HOOK SMOKE TESTS — cbp-skill-context-guard =====
+echo "## Hook Smoke Tests — cbp-skill-context-guard (CHK-217)"
+
+GUARD_HOOK="$HOOKS_DIR/cbp-skill-context-guard.sh"
+FIXTURES_GUARD="$HOOKS_DIR/__test-fixtures__/cbp-context-window-notify"
+
+if [ ! -f "$GUARD_HOOK" ]; then
+  test_result "cbp-skill-context-guard.sh present" "passed" "missing"
+else
+
+  # Case 1: over-threshold + cbp-round-execute (heavy) → permissionDecision=deny
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD/over-threshold.jsonl" \
+    --arg s "cbp-round-execute" \
+    '{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 over-threshold + cbp-round-execute → deny" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh over-threshold + cbp-round-execute → deny" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+  fi
+
+  # Case 2: over-threshold + cbp-clear-prep (exempt) → empty stdout, exit 0
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD/over-threshold.jsonl" \
+    --arg s "cbp-clear-prep" \
+    '{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" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-skill-context-guard.sh over-threshold + cbp-clear-prep (exempt) → empty stdout" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh over-threshold + cbp-clear-prep (exempt) → empty stdout" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+
+  # Case 3: over-threshold + cbp-clear-continue (exempt) → empty stdout, exit 0
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD/over-threshold.jsonl" \
+    --arg s "cbp-clear-continue" \
+    '{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" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-skill-context-guard.sh over-threshold + cbp-clear-continue (exempt) → empty stdout" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh over-threshold + cbp-clear-continue (exempt) → empty stdout" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+
+  # Case 4: under-threshold + cbp-round-execute → empty stdout, exit 0
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD/under-threshold.jsonl" \
+    --arg s "cbp-round-execute" \
+    '{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" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-skill-context-guard.sh under-threshold + cbp-round-execute → empty stdout" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh under-threshold + cbp-round-execute → empty stdout" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+
+  # Case 5: empty skill_name → empty stdout, exit 0
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD/over-threshold.jsonl" \
+    '{transcript_path:$t,tool_input:{}}')
+  OUTPUT=$(echo "$STDIN" | CBP_CONTEXT_WARN_TOKENS=200000 bash "$GUARD_HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-skill-context-guard.sh empty skill_name → empty stdout" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh empty skill_name → empty stdout" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+
+  # Case 6: missing transcript_path → empty stdout, exit 0 (fast-path)
+  STDIN=$(jq -n --arg s "cbp-round-execute" '{tool_input:{skill:$s}}')
+  OUTPUT=$(echo "$STDIN" | CBP_CONTEXT_WARN_TOKENS=200000 bash "$GUARD_HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-skill-context-guard.sh missing transcript_path → empty stdout" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh missing transcript_path → empty stdout" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+
+fi
+
+# ===== STRUCTURAL ASSERTIONS — cbp-clear-* skills (CHK-217) =====
+echo ""
+echo "## Structural Assertions — cbp-clear-* skills (CHK-217)"
+
+# cbp-clear-prep/SKILL.md: scope: org-shared + references handoff.md
+CLEAR_PREP_SKILL="$(dirname "$HOOKS_DIR")/skills/cbp-clear-prep/SKILL.md"
+if [ -f "$CLEAR_PREP_SKILL" ]; then
+  if grep -q 'scope: org-shared' "$CLEAR_PREP_SKILL"; then
+    test_result "cbp-clear-prep/SKILL.md has scope: org-shared" "passed" "passed"
+  else
+    test_result "cbp-clear-prep/SKILL.md has scope: org-shared" "passed" "missing"
+  fi
+  if grep -q 'handoff\.md' "$CLEAR_PREP_SKILL"; then
+    test_result "cbp-clear-prep/SKILL.md references handoff.md" "passed" "passed"
+  else
+    test_result "cbp-clear-prep/SKILL.md references handoff.md" "passed" "missing"
+  fi
+else
+  test_result "cbp-clear-prep/SKILL.md structural checks (file absent — skipped)" "passed" "passed"
+fi
+
+# cbp-clear-continue/SKILL.md: scope: org-shared + references handoff.md + has rm of handoff
+CLEAR_CONTINUE_SKILL="$(dirname "$HOOKS_DIR")/skills/cbp-clear-continue/SKILL.md"
+if [ -f "$CLEAR_CONTINUE_SKILL" ]; then
+  if grep -q 'scope: org-shared' "$CLEAR_CONTINUE_SKILL"; then
+    test_result "cbp-clear-continue/SKILL.md has scope: org-shared" "passed" "passed"
+  else
+    test_result "cbp-clear-continue/SKILL.md has scope: org-shared" "passed" "missing"
+  fi
+  if grep -q 'handoff\.md' "$CLEAR_CONTINUE_SKILL"; then
+    test_result "cbp-clear-continue/SKILL.md references handoff.md" "passed" "passed"
+  else
+    test_result "cbp-clear-continue/SKILL.md references handoff.md" "passed" "missing"
+  fi
+  if grep -Eq 'rm -f.*handoff' "$CLEAR_CONTINUE_SKILL"; then
+    test_result "cbp-clear-continue/SKILL.md has rm -f of handoff.md" "passed" "passed"
+  else
+    test_result "cbp-clear-continue/SKILL.md has rm -f of handoff.md" "passed" "missing"
+  fi
+else
+  test_result "cbp-clear-continue/SKILL.md structural checks (file absent — skipped)" "passed" "passed"
+fi
+
+# .gitignore contains .codebyplan/clear/
+REPO_GITIGNORE="${CLAUDE_PROJECT_DIR:-}/.gitignore"
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -f "$REPO_GITIGNORE" ]; then
+  if grep -q '\.codebyplan/clear/' "$REPO_GITIGNORE"; then
+    test_result ".gitignore contains .codebyplan/clear/" "passed" "passed"
+  else
+    test_result ".gitignore contains .codebyplan/clear/" "passed" "missing"
+  fi
+else
+  test_result ".gitignore check skipped (CLAUDE_PROJECT_DIR unset or no .gitignore)" "passed" "passed"
+fi
+
+echo ""
+
 # ===== SUMMARY =====
 echo "=== TEST SUMMARY ==="
 echo -e "Passed: ${GREEN}$PASSED${NC}"

package/templates/hooks/hooks.json

@@ -52,6 +52,15 @@
           }
         ]
       },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-skill-context-guard.sh"
+          }
+        ]
+      },
       {
         "matcher": "mcp__codebyplan__(update_task|complete_task|update_checkpoint|create_checkpoint|create_task)",
         "hooks": [

package/templates/rules/model-invocation-convention.md

@@ -0,0 +1,40 @@
+# Model Invocation Convention
+
+CBP skills are **model-invocable by default**. Authors must omit `disable-model-invocation` unless
+a skill is strictly user-only (i.e. it must never auto-trigger from another skill).
+
+## Default: omit `disable-model-invocation`
+
+The absence of `disable-model-invocation` (or `disable-model-invocation: false`) is the normal
+state. It allows the skill to be auto-triggered via the Skill tool from within other skills —
+which is how the auto-trigger close-out flow works (e.g. `cbp-task-check` → `cbp-task-testing`,
+`cbp-task-testing` → `cbp-task-complete`).
+
+## The sole exception: `cbp-round-complete`
+
+`cbp-round-complete` sets `disable-model-invocation: true`. It is the permission-gated round
+finalizer: the user must explicitly run it after their own `git add` selections, so it must
+never auto-fire from within another skill. The `ask`-tier permission prompt on
+`Skill(cbp-round-complete)` is a secondary gate on top of this; the frontmatter flag is the
+primary model-invocation block.
+
+No other skill in the CBP framework sets this flag. Do NOT add it to new skills without a
+clear "user-only" rationale.
+
+## Human gates for auto-triggering skills
+
+For auto-trigger skills, the human checkpoint is expressed via two complementary mechanisms —
+not via `disable-model-invocation`:
+
+1. **`ask`-tier permission entry** in `settings.json` — the harness permission prompt is the
+   lightweight confirm gate. Skills in `ask` auto-fire silently ONLY after the user confirms.
+2. **Routing prose** inside the triggering skill — states explicitly which skill fires next and
+   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.
+
+## Related
+
+- `rules/scope-vocabulary.md` — scope marker conventions for managed vs user-created files
+- `cbp-build-cc-settings/reference/cbp-permission-policy.md` — allow/ask tiers

package/templates/rules/parallel-waves.md

@@ -33,7 +33,7 @@ Each entry in `plan.waves[]` carries these fields (source: `.claude/agents/cbp-t
   - Above 15: apply the proximity-split algorithm below.
   - Sole exception — trivially small plans are exempt from the lower bound: a plan with fewer than 3 total files uses one single wave, and a single-app plan with ≤5 total files MAY skip decomposition entirely (one wave, or `waves[]` omitted — see `cbp-task-planner` Phase 5.6). Zero waves (omitted `waves[]`) trivially satisfies this invariant.
 
-**(IV) UI skill preloads** — for each wave whose `files[]` contains UI-bearing paths (`*.tsx`, `*.jsx`, `*.scss`, etc.), add `"frontend-design"` and `"frontend-a11y"` to `skill_preloads[]` in that order (source: `.claude/agents/cbp-task-planner.md` Phase 5.6 step "Populate `skill_preloads[]`").
+**(IV) UI skill preloads** — for each wave whose `files[]` contains UI-bearing paths (`*.tsx`, `*.jsx`, `*.scss`, etc.), add `"frontend-design"` to `skill_preloads[]` (source: `.claude/agents/cbp-task-planner.md` Phase 5.6 step "Populate `skill_preloads[]`").
 
 ## Proximity-Split Algorithm
 

package/templates/rules/supabase-branch-lifecycle.md

@@ -7,7 +7,6 @@ paths:
   - ".claude/skills/cbp-supabase-migrate/**"
   - ".claude/skills/cbp-supabase-branch-check/**"
   - ".claude/skills/cbp-checkpoint-end/**"
-  - ".claude/skills/cbp-git-worktree-remove/**"
   - ".claude/skills/cbp-ship-main/**"
   - ".claude/skills/cbp-standalone-task-complete/**"
 ---
@@ -48,7 +47,7 @@ The Supabase branch is removed wherever the git branch is deleted:
 | Skill | Trigger |
 |---|---|
 | `cbp-checkpoint-end` | stale-branch cleanup + current feat-branch delete on ship |
-| `cbp-git-worktree-remove` | worktree teardown removes the coupled Supabase branch |
+| `codebyplan worktree remove CHK-NNN` | worktree teardown removes the coupled Supabase branch |
 | `cbp-ship-main` | `branch_deleted` event after PR merge |
 | `cbp-standalone-task-complete` | `branch_deleted` event after standalone PR merge (Step 7.3) |
 
@@ -94,7 +93,7 @@ or auto-created by the GitHub integration — both paths use the same branch nam
 | Role | Skill |
 |---|---|
 | Create (lazy) | `cbp-supabase-migrate` (Step 2.3) |
-| Delete | `cbp-checkpoint-end`, `cbp-standalone-task-complete`, `cbp-git-worktree-remove`, `cbp-ship-main` |
+| Delete | `cbp-checkpoint-end`, `cbp-standalone-task-complete`, `codebyplan worktree remove`, `cbp-ship-main` |
 | PR gate | `cbp-supabase-branch-check` |
 
 Each skill in the Skill Map above carries an inline back-reference to this rule at its create or teardown step.

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 → `Next: /clear, then /cbp-checkpoint-check`
+- Last task in checkpoint → auto-triggers `cbp-checkpoint-check` (ask-tier permission prompt is the human gate; the 200K context guard handles oversized contexts)
 
 **Standalone task complete:**
 - Always → `Next: /cbp-session-end` (or `/cbp-standalone-task-create` for new work)

package/templates/settings.project.base.json

@@ -116,14 +116,13 @@
       "Skill(cbp-build-cc-skill)",
       "Skill(cbp-checkpoint-plan)",
       "Skill(cbp-checkpoint-update)",
-      "Skill(cbp-frontend-a11y)",
+      "Skill(cbp-clear-continue)",
+      "Skill(cbp-clear-prep)",
       "Skill(cbp-frontend-design)",
       "Skill(cbp-frontend-ui)",
       "Skill(cbp-frontend-ux)",
       "Skill(cbp-git-branch-feat-create)",
       "Skill(cbp-git-commit)",
-      "Skill(cbp-git-worktree-create)",
-      "Skill(cbp-git-worktree-remove)",
       "Skill(cbp-map-architecture)",
       "Skill(cbp-merge-main)",
       "Skill(cbp-refresh-arch-map)",

package/templates/skills/cbp-build-cc-mode/SKILL.md

@@ -32,7 +32,7 @@ Omit `model:` entirely (inherit the session model). Set `effort:` per the skill'
 | `xhigh`  | deep authoring / planning / orchestration (most skills) | build-cc-*, checkpoint-check/end/plan, round-start/input/execute, task-create/start/complete/testing, standalone-task-*, frontend-*, ship, ship-configure, supabase-*, setup-e2e/eslint, session-end |
 | `high`   | summary / orchestration, lighter than xhigh            | checkpoint-create, checkpoint-start, checkpoint-update, round-end, task-check, standalone-task-check, ship-main, merge-main                                           |
 | `medium` | moderate, scoped sync work                             | refresh-infra                                                                                                                                                        |
-| `low`    | pure mechanical / dispatch / templated work            | checkpoint-complete, round-check, round-complete, round-update, todo, session-start, git-commit, git-branch-feat-create, git-worktree-create, git-worktree-remove    |
+| `low`    | pure mechanical / dispatch / templated work            | checkpoint-complete, round-check, round-complete, round-update, todo, session-start, git-commit, git-branch-feat-create    |
 
 A skill that carries a `model:` line is a **gap** — remove it unless a deliberate, documented exception is recorded here (currently none).
 

package/templates/skills/cbp-build-cc-settings/reference/cbp-permission-policy.md

@@ -45,6 +45,48 @@ The pre-existing dangerous-`rm -rf` blocks. This policy does not alter `deny` se
 
 When you add a skill / MCP tool / CLI subcommand, add its matching rule (`Skill(<name>)`, `mcp__codebyplan__<name>`, or `Bash(codebyplan <sub>:*)` + `Bash(npx codebyplan <sub>:*)`) to `allow` or `ask` in `templates/settings.project.base.json` — and mirror it into any dogfooding `.claude/settings.json`.
 
+## Auto-trigger + allow/ask gating model
+
+The CBP close-out flow uses **auto-triggers** instead of manual "Next: /cbp-X" directives.
+A skill invokes the next skill via the Skill tool at the appropriate routing branch.
+
+### How the human gate works
+
+- **`allow`-tier** skill: the harness auto-fires it silently when the triggering skill invokes it.
+  No permission prompt. Use for safe, routine-flow skills (e.g. `cbp-task-testing`,
+  `cbp-round-input`) where the trigger condition already encodes the human intent.
+- **`ask`-tier** skill: the harness pauses and shows a permission prompt before the skill runs.
+  **That prompt IS the human gate** — it replaces the old "Next: /cbp-X, run it yourself"
+  manual directive. Use for lifecycle/state-transition skills (e.g. `cbp-task-complete`,
+  `cbp-checkpoint-check`) where a deliberate confirmation is still desirable.
+
+This means:
+- A skill in `allow` that is auto-triggered fires silently — do NOT claim "the ask-tier prompt
+  is the gate" for it in routing prose.
+- A skill in `ask` that is auto-triggered shows a permission prompt — that prompt is the gate;
+  say so in the routing prose.
+
+### The 200K context guard
+
+The `cbp-skill-context-guard.sh` PreToolUse hook denies heavy close-out skills when the
+context window exceeds `CBP_CONTEXT_WARN_TOKENS` (default 200 000 tokens). The heavy allowlist
+is: `cbp-round-execute`, `cbp-task-testing`, `cbp-standalone-task-testing`,
+`cbp-checkpoint-check`, `cbp-checkpoint-end`.
+
+When the guard fires, it directs the model to run `/cbp-clear-prep` instead. The flow is:
+`cbp-clear-prep` (captures a handoff) → `/clear` (user command) → `cbp-clear-continue`
+(re-invokes the blocked skill in the fresh context).
+
+`cbp-clear-prep` and `cbp-clear-continue` are **excluded** from the guard's allowlist so they
+always run regardless of context size.
+
+Routing prose in triggering skills should NOT mandate an unconditional `/clear` before a heavy
+skill — the guard handles oversized contexts automatically. Drop "Run /clear first" directives
+from auto-trigger paths; only note the guard mechanism so the author understands when it fires.
+
+See `rules/model-invocation-convention.md` for the `disable-model-invocation` convention —
+authors must omit it on all skills except `cbp-round-complete`.
+
 ## Scope
 
 `scope: org-shared` — CBP-framework infrastructure that lands identically in every consuming repo via the `codebyplan` package.

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

@@ -113,6 +113,7 @@ Persist the branch via `codebyplan checkpoint update --id <checkpoint-id> --bran
 
 **CHK-NNN**: [title]  •  **Deadline**: [date]  •  **Branch**: feat/CHK-NNN-slug
 **Claim**: [claimed by this worktree / left open]
+**Worktree**: `npx codebyplan worktree add CHK-{NNN}`
 
 Now planning CHK-NNN… handing off to /cbp-checkpoint-plan.
 ```

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

@@ -72,6 +72,7 @@ Show a one-line confirmation before routing:
 
 **CHK-NNN**: [title]  •  **Status**: active  •  **Claimed by**: [worktree or "open"]
 **Next task**: TASK-[N] — [title]
+**Worktree**: `npx codebyplan worktree add CHK-{NNN}`
 ```
 
 ## Integration

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

@@ -0,0 +1,86 @@
+---
+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.
+effort: xhigh
+---
+
+# cbp-clear-continue
+
+Resume a blocked heavy skill after a `/clear`. Reads `.codebyplan/clear/handoff.md`, restores
+task/round context into this fresh session, re-invokes the blocked skill, then deletes the
+handoff file so a stale snapshot never misleads a future session.
+
+## When Used
+
+- After running `/clear` following a `/cbp-clear-prep` capture
+- The user is ready to re-run the heavy skill (cbp-round-execute, cbp-task-testing,
+  cbp-standalone-task-testing, cbp-checkpoint-check, cbp-checkpoint-end) that was denied
+
+## Instructions
+
+### Step 1 — Read the handoff
+
+Read `.codebyplan/clear/handoff.md`.
+
+If the file is absent: output the following and STOP — do not attempt to infer state.
+
+```
+No handoff found at .codebyplan/clear/handoff.md — nothing to continue.
+Use /cbp-todo to find the next action.
+```
+
+### Step 2 — Restore context
+
+Parse the handoff fields:
+- `checkpoint_number`, `task_number`, `round_number`
+- `blocked_skill` — the skill that was denied
+- `next_action` — the exact skill invocation to re-run (with args)
+- `in_flight_notes` — any in-progress state worth restoring
+
+Output a brief context summary to orient the fresh session:
+
+```
+Resuming from handoff:
+  CHK-<N> TASK-<N> R<N>
+  Blocked skill:  /<blocked-skill>
+  Next action:    /<next-action>
+```
+
+### Step 3 — Delete the handoff BEFORE re-invoking
+
+Delete `.codebyplan/clear/handoff.md` once its contents have been read and displayed:
+
+```bash
+rm -f .codebyplan/clear/handoff.md
+```
+
+A stale handoff must not mislead a later session. Delete it here, before the skill runs,
+so even if the skill fails the handoff is gone and the user starts fresh next time.
+
+### Step 4 — Re-invoke the blocked skill
+
+Invoke the skill from `next_action` via the Skill tool, passing any recorded arguments.
+
+Example: if `next_action` is `/cbp-round-execute 217-2-1`, invoke `Skill(cbp-round-execute)`
+with args `217-2-1`.
+
+If the context window is STILL above threshold after `/clear` (unusual — compact may help),
+the guard will deny again. Follow the same cycle: `/cbp-clear-prep` → `/clear` →
+`/cbp-clear-continue`.
+
+## Key Rules
+
+- Delete `.codebyplan/clear/handoff.md` in Step 3 BEFORE invoking the next skill
+- If the handoff is absent, surface the friendly error and stop — never infer state from scratch
+- Re-invoke the EXACT skill and arguments from `next_action` — do not substitute or guess
+- `.codebyplan/clear/` is gitignored — never commit handoff.md
+
+## Integration
+
+- **Invoked by**: user after `/clear` following `/cbp-clear-prep`
+- **Reads**: `.codebyplan/clear/handoff.md`
+- **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
+- **Guard hook**: `.claude/hooks/cbp-skill-context-guard.sh`

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

@@ -0,0 +1,121 @@
+---
+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]"
+effort: xhigh
+---
+
+# cbp-clear-prep
+
+Capture a handoff snapshot before clearing context. Invoked when the `cbp-skill-context-guard`
+PreToolUse hook denies a heavy skill (cbp-round-execute, cbp-task-testing,
+cbp-standalone-task-testing, cbp-checkpoint-check, cbp-checkpoint-end) because the context
+window exceeds the configured threshold.
+
+## When Used
+
+- The hook deny message says "Run /cbp-clear-prep now to capture a handoff"
+- A heavy skill was just blocked by the context guard
+- The user wants to preserve current task/round state before running `/clear`
+
+## Instructions
+
+### Step 1 — Identify the blocked skill
+
+Check `$ARGUMENTS` first. If empty, identify the blocked skill from the recent guard deny message
+in context — it will be one of: `cbp-round-execute`, `cbp-task-testing`,
+`cbp-standalone-task-testing`, `cbp-checkpoint-check`, `cbp-checkpoint-end`.
+
+### Step 2 — Resolve active task and round (local-first)
+
+1. Read `.codebyplan/state/session/current.json` to find the active task_id and checkpoint_id.
+2. Read `.codebyplan/state/checkpoints/<checkpoint_id>/tasks/<task_id>.json` for task details.
+3. Read the latest round file in `.codebyplan/state/checkpoints/<checkpoint_id>/tasks/<task_id>/rounds/`.
+4. On miss: run `npx codebyplan sync` once and re-read.
+5. Break-glass if state dir is absent: call `mcp__codebyplan__get_current_task` and
+   `mcp__codebyplan__get_rounds`.
+
+Capture: `checkpoint_id`, `checkpoint_number`, `task_id`, `task_number`, `round_id`,
+`round_number`. If no active task is found, set all to `unknown` and note the gap.
+
+### Step 3 — Identify the next action to resume
+
+From context, determine:
+- The exact skill the user was trying to invoke (blocked skill from Step 1)
+- Any arguments it was called with (e.g. `cbp-round-execute` args: `217-2-1`)
+- Any relevant in-flight state (round goal, step in progress, pending decisions)
+
+### Step 4 — Write the handoff file
+
+Create the directory and write `.codebyplan/clear/handoff.md`:
+
+```bash
+mkdir -p .codebyplan/clear
+```
+
+File content format:
+
+```
+# CBP Clear Handoff
+
+## Active Context
+
+checkpoint_id: <id or unknown>
+checkpoint_number: CHK-<N or unknown>
+task_id: <id or unknown>
+task_number: TASK-<N or unknown>
+round_id: <id or unknown>
+round_number: R<N or unknown>
+
+## Blocked Skill
+
+blocked_skill: <skill-name>
+
+## Next Action
+
+next_action: /<skill-name> <args if any>
+
+## In-Flight Notes
+
+<any relevant state — round goal, current step, pending decisions, uncommitted work>
+
+## Resume Instructions
+
+After /clear, run: /cbp-clear-continue
+```
+
+### Step 5 — Instruct the user
+
+Output exactly this summary (fill in the real values):
+
+```
+Handoff captured at .codebyplan/clear/handoff.md
+
+Active context:  CHK-<N> TASK-<N> R<N>
+Blocked skill:   /<blocked-skill>
+Resumes with:    /<next-action>
+
+Next steps:
+1. Run /clear to free context
+2. Run /cbp-clear-continue to resume
+```
+
+Do NOT auto-invoke `/clear` or `/cbp-clear-continue`. This is a directive-only stop.
+The user must run both commands manually.
+
+## Key Rules
+
+- Always write `.codebyplan/clear/handoff.md` BEFORE instructing `/clear`
+- Never auto-invoke the blocked skill — the guard denied it to protect context quality
+- If no active task resolves, still write the handoff with available context and note the gap
+- `.codebyplan/clear/` is gitignored — never commit handoff.md
+- Overwrite any existing handoff.md (each prep captures the freshest context)
+
+## Integration
+
+- **Invoked when**: `cbp-skill-context-guard` PreToolUse hook emits `permissionDecision: deny`
+- **Writes**: `.codebyplan/clear/handoff.md`
+- **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 > CBP_CONTEXT_WARN_TOKENS (default 200000)

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

@@ -216,7 +216,7 @@ Present the plan to user:
 ### Execution Waves
 | Wave | Agent type | Files | Depends on | Skill preloads |
 |------|-----------|-------|-----------|----------------|
-| web-ui | cbp-round-executor | 7 | — | cbp-frontend-design, cbp-frontend-a11y |
+| web-ui | cbp-round-executor | 7 | — | cbp-frontend-design |
 | backend-api | cbp-round-executor | 4 | — | — |
 ```
 

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

@@ -74,23 +74,9 @@ Same rule as `/cbp-session-start` Step 5.7 — only commit files that are **not*
 
 Non-blocking — session end proceeds either way.
 
-### Step 1.6: Home-Branch Fast-Forward
-
-Keep this worktree's **home branch** rooted at the freshest production tip — no prompt, fully non-blocking. Home branches are the folder-named placeholder branches each worktree rests on (e.g. `codebyplan-web`); `feat/*` branches are deliberately skipped — they integrate via `/cbp-merge-main` with QA, never an auto fast-forward.
-
-Runs after Step 1.5 so any infra commits land first, and before Step 1.7 so the freshness gate's asset update operates on the freshest tree.
-
-Run `codebyplan session home-ff` and parse the JSON output (`{ result: 'skipped'|'warn'|'fast_forwarded', reason?, warn? }`):
-
-- **`result === 'skipped'`** (non-home branch or production mismatch): proceed silently.
-- **`result === 'warn'`** (fast-forward attempt failed): surface the `warn` field as one line, then proceed silently.
-- **`result === 'fast_forwarded'`** (home branch updated): proceed silently.
-
-Never rebase, reset, force-push, or stash. A non-fast-forwardable home branch is a signal to reconcile manually, not to overwrite.
-
 ### Step 1.7: Package Freshness Gate
 
-Check whether a newer `codebyplan` is published and safe to auto-install on this worktree's current branch, then run the local install + asset update. Runs after the Step 1.6 home-branch fast-forward (so any update lands on the freshest tree) and before Step 2. Fully non-blocking — the guard and skip branches proceed silently; any failure in the install/update commands warns once and continues to Step 2. session-end never halts.
+Check whether a newer `codebyplan` is published and safe to auto-install on this worktree's current branch, then run the local install + asset update. Runs after the Step 1.5 non-task-file commit and before Step 2. Fully non-blocking — the guard and skip branches proceed silently; any failure in the install/update commands warns once and continues to Step 2. session-end never halts.
 
 Run `codebyplan session freshness-gate` (WITHOUT `--halt-on-update`; session-end is continue-only) and parse the JSON output (`{ result: 'skipped'|'guarded'|'up_to_date'|'updated'|'error', ... }`):
 
@@ -110,8 +96,6 @@ Run `codebyplan session freshness-gate` (WITHOUT `--halt-on-update`; session-end
     On `yes`: `git add` the listed paths only (not the whole directories), then trigger `/cbp-git-commit`. On `no`: skip. On `select`: ask which subset.
   - Continue to Step 2 — session-end does NOT halt. The update lands in the current worktree on its current branch; main/protected branches and the canonical source repo are already excluded by the `result !== 'guarded'` check above.
 
-**Home branches are intentionally not guarded.** A worktree's folder-named home branch (e.g. `codebyplan-web`) is neither protected/main nor the canonical source, so the freshness gate returns `result !== 'guarded'` there and this gate runs the update exactly as on a feat branch — landing it on whichever branch the worktree currently rests on (the deliberate "update the branch they're on, except main/canonical" behavior).
-
 Non-blocking — session end proceeds regardless of outcome.
 
 ### Step 2: Auto-Stop Servers
@@ -149,7 +133,7 @@ You can close this window.
 ## Integration
 
 - **Triggered by**: user invocation (prompted by `/cbp-todo` when no work remains)
-- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.6 home-branch fast-forward); 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 handoff snapshot + Step 1.5 active-task lookup), `.codebyplan/state/checkpoints/<id>/tasks/<id>/rounds/` (Step 1.5 task-file resolution); `codebyplan session home-ff` (Step 1.6 home-branch fast-forward); `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)
+- **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 handoff snapshot + 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> ...` (Step 1 finalize — CLI write-through to `.codebyplan/state/session/current.json`; break-glass: MCP `update_session_log`), `codebyplan session create-log` (Step 1 fallback when no log exists; break-glass: MCP `create_session_log`), `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).