codebyplan 1.13.49 → 1.13.50

package/dist/cli.js

@@ -39,7 +39,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.13.49";
+    VERSION = "1.13.50";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -639,6 +639,7 @@ var init_gitignore_block = __esm({
       ".codebyplan/statusline.local.json",
       ".codebyplan/worktree.local.json",
       ".codebyplan/state/",
+      ".codebyplan/clear/",
       ".codebyplan/todo/",
       ".codebyplan/claude-status.local.json",
       ".codebyplan.local.json"

package/package.json

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

package/templates/agents/cbp-round-executor.md

@@ -239,18 +239,13 @@ When the executor received a `wave` input with a non-empty `wave.skill_preloads[
 For each entry in `wave.skill_preloads[]`, invoke the named skill via the Skill tool BEFORE Step 3 (Execute). Invoke in order:
 
 1. `cbp-frontend-design` — if present, invoke FIRST (aesthetic direction before code)
-2. `cbp-frontend-a11y` — if present, invoke AFTER `cbp-frontend-design` (accessibility obligations)
-3. Any other skill preload — invoke in list order
+2. Any other skill preload — invoke in list order
 
 Record completion:
 ```yaml
 round.context.frontend_design_loaded: true   # if cbp-frontend-design was preloaded
-round.context.frontend_a11y_loaded: true     # if cbp-frontend-a11y was preloaded
-round.context.frontend_a11y_checklist: [items from cbp-frontend-a11y/SKILL.md Phase 6 output]  # only when cbp-frontend-a11y was preloaded for this wave
 ```
 
-When cbp-frontend-a11y is preloaded, capture its Phase 6 per-component checklist output verbatim into `round.context.frontend_a11y_checklist`. Step 3 reads this for accessibility enforcement during code emission.
-
 If `wave` is absent or `wave.skill_preloads[]` is empty, skip this step — Step 2.7 handles the non-wave UI pre-read path.
 
 **Why step 2.6 and 2.7 coexist**: Step 2.7 fires for non-wave rounds when the executor detects UI files directly. Step 2.6 fires for wave rounds where the planner already determined the preloads. They cover the same skill but via different trigger paths; the round.context recording is identical so downstream steps behave uniformly.

package/templates/agents/cbp-task-planner.md

@@ -533,7 +533,7 @@ After Phase 5 (solution design) and before Phase 6 (context summary), decompose
 1. **Identify natural cut points**: look for cross-app boundaries (files in `apps/web/` vs `apps/backend/` vs `apps/desktop/`), packages with no shared state, or dependency ordering (DB migration must precede app code using the new schema).
 2. **Check disjoint-files invariant**: no file may appear in two waves. If a shared file is needed by two waves, assign it to the earlier wave and make the later wave `depends_on` the earlier.
 3. **Check DAG invariant**: `depends_on[]` must be acyclic. Any cycle is a plan error — resolve by merging the cyclic waves.
-4. **Populate `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).
+4. **Populate `skill_preloads[]`**: for each wave whose `files[]` contains UI-bearing paths (`*.tsx`, `*.jsx`, `*.scss`, etc.), add `"frontend-design"` to `skill_preloads[]`.
 5. **Single-wave default**: if no independence is found, produce ONE wave covering all files. Parallel waves add orchestration overhead — only decompose when the benefit is clear.
 6. **15-file cap**: after decomposition (including the single-wave default), count files in each wave. If any wave would exceed 15 files, auto-split it using the proximity-split algorithm in priority order: (a) **shared directory subtree** — split at the deepest common ancestor that produces two groups each ≥3 files; (b) **shared module** — split at the next directory level below the common ancestor; (c) **arbitrary boundary** — split at the 15-file boundary and add a one-line `note` on the continuation wave explaining the boundary. Split siblings are **independent**: do NOT add `depends_on` between them unless a real shared-file or data dependency requires ordering. **Tail rule**: choose boundaries so every resulting wave holds 3–15 files. A split must never leave a wave with <3 files; rebalance the boundary rather than absorbing a tail into a sibling in a way that pushes it above 15. The 3–15 range is a hard invariant — there is no exception above 15. **Apply the cap iteratively**: after a split, re-check each resulting wave and split again any that still exceeds 15 — a 40-file single-concern plan therefore yields ≥3 waves. When no natural boundary yields groups each ≥3 files, take the smallest ≥3-file prefix as one wave and apply the same procedure to the remainder. The single-wave default is itself subject to this cap. See `rules/parallel-waves.md` for the full algorithm and invariants.
 
@@ -559,7 +559,7 @@ printf '%s' "$PLAN_JSON" | codebyplan validate-waves --json
 
 (`$PLAN_JSON` is the `{ "waves": [...] }` structure; pass a file path as the first argument instead of stdin if preferred.) Exit 0 = invariants I–III satisfied. Exit non-zero = one or more violations — the `--json` `violations[]` array names the failing invariant (`I`/`II`/`III`) and offending wave/file; fix the decomposition and re-run before emitting the plan. The validator does NOT check invariant IV (UI skill preloads) — that remains a manual step:
 
-- [ ] UI-bearing waves have `frontend-design` + `frontend-a11y` in `skill_preloads[]` (invariant IV — not covered by `validate-waves`)
+- [ ] UI-bearing waves have `frontend-design` in `skill_preloads[]` (invariant IV — not covered by `validate-waves`)
 
 ### Phase 6: Build Context Summary
 

package/templates/hooks/cbp-skill-context-guard.sh

@@ -0,0 +1,52 @@
+#!/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.
+
+set -euo pipefail
+
+INPUT=$(cat)
+SKILL_NAME=$(echo "$INPUT" | jq -r '.tool_input.skill // .tool_input.skill_name // ""' 2>/dev/null) || SKILL_NAME=""
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null) || TRANSCRIPT=""
+
+# Fast-path: no transcript → pass through
+[ -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-execute cbp-task-testing cbp-standalone-task-testing cbp-checkpoint-check cbp-checkpoint-end"
+
+# Cheap allowlist check before summing tokens
+IS_HEAVY=false
+for heavy in $HEAVY_SKILLS; do
+  if [ "$SKILL_NAME" = "$heavy" ]; then
+    IS_HEAVY=true
+    break
+  fi
+done
+[ "$IS_HEAVY" = "false" ] && exit 0
+
+# Token sum — same logic as cbp-context-window-notify.sh
+TOTAL=$(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
+TOTAL="${TOTAL:-0}"
+
+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.")}}'
+fi
+
+exit 0

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/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,7 +116,8 @@
       "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)",

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-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 | — | — |
 ```