codebyplan 1.13.63 → 1.13.65

package/templates/settings.project.base.json

@@ -147,22 +147,16 @@
       "mcp__codebyplan__get_checkpoints",
       "mcp__codebyplan__get_current_task",
       "mcp__codebyplan__get_eslint_presets",
-      "mcp__codebyplan__get_eslint_repo_config",
       "mcp__codebyplan__get_file_changes",
-      "mcp__codebyplan__get_library_doc_job",
       "mcp__codebyplan__get_repos",
       "mcp__codebyplan__get_rounds",
       "mcp__codebyplan__get_server_config",
       "mcp__codebyplan__get_session_log",
       "mcp__codebyplan__get_session_logs",
       "mcp__codebyplan__get_session_state",
-      "mcp__codebyplan__get_task_template",
-      "mcp__codebyplan__get_task_templates",
       "mcp__codebyplan__get_tasks",
       "mcp__codebyplan__get_todos",
-      "mcp__codebyplan__list_tech_stack_sync_sessions",
       "mcp__codebyplan__get_chunk",
-      "mcp__codebyplan__get_library_toc",
       "mcp__codebyplan__list_migrations",
       "mcp__codebyplan__lookup_symbol",
       "mcp__codebyplan__resolve_library_id",
@@ -184,7 +178,15 @@
       "mcp__codebyplan__flag_stale_chunk",
       "mcp__codebyplan__update_eslint_repo_config",
       "mcp__codebyplan__update_server_config",
-      "mcp__codebyplan__update_task_template",
+      "mcp__codebyplan__get_standalone_tasks",
+      "mcp__codebyplan__get_current_standalone_task",
+      "mcp__codebyplan__get_standalone_rounds",
+      "mcp__codebyplan__create_standalone_task",
+      "mcp__codebyplan__update_standalone_task",
+      "mcp__codebyplan__complete_standalone_task",
+      "mcp__codebyplan__add_standalone_round",
+      "mcp__codebyplan__update_standalone_round",
+      "mcp__codebyplan__complete_standalone_round",
       "Bash(codebyplan check:*)",
       "Bash(npx codebyplan check:*)",
       "Bash(codebyplan session:*)",
@@ -250,13 +252,29 @@
       "Bash(codebyplan cd:*)",
       "Bash(npx codebyplan cd:*)",
       "Bash(codebyplan cleanup-plan-folders:*)",
-      "Bash(npx codebyplan cleanup-plan-folders:*)"
+      "Bash(npx codebyplan cleanup-plan-folders:*)",
+      "Bash(codebyplan handoff:*)",
+      "Bash(npx codebyplan handoff:*)"
     ]
   },
   "attribution": {
     "commit": "",
     "pr": ""
   },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "_owner": "codebyplan-claude",
+            "_hook_id": "cbp-session-id-stamp.sh",
+            "type": "command",
+            "command": "bash ./.claude/hooks/cbp-session-id-stamp.sh"
+          }
+        ]
+      }
+    ]
+  },
   "showClearContextOnPlanAccept": false,
   "syntaxHighlightingDisabled": false
 }

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

@@ -77,6 +77,7 @@ Check each against the task and include only when they add value:
 | Background execution | `background: true`                                              | Agent should always run concurrently                   |
 | Bounded turns        | `maxTurns: N`                                                   | Cap runaway loops                                      |
 | Subagent spawning    | `tools: Agent(worker, researcher)`                              | Only if run as main thread via `--agent`               |
+| Memory store         | `memory: user \| project \| local`                              | Which memory store the agent reads/writes              |
 
 Cross-references for complex cases:
 
@@ -136,5 +137,7 @@ Report:
 - Subagents cannot spawn other subagents — the `Agent` tool only applies when the agent runs as the main thread
 - `bypassPermissions` and `acceptEdits` inherited from the parent cannot be weakened by the child
 - Preloaded skills inject _full content_ at startup — don't preload `disable-model-invocation: true` skills
+- `Task(` was renamed to `Agent(` in v2.1.63 — use `Agent(...)` in `tools:` allowlists; `Task()` is a stale alias that still works but should not appear in new agents
+- Plugin agents (`.claude/agents/`) ignore `hooks`, `mcpServers`, and `permissionMode` — these fields parse without error but have no runtime effect for plugin agents
 - Restart the session or use `/agents` to load a newly written agent file
 - Flat form `.claude/agents/{name}.md` is the default and matches all 12 existing CBP agents; folder form `{name}/AGENT.md` is optional and only for agents that bundle supporting files alongside them

package/templates/skills/cbp-build-cc-agent/reference/frontmatter-fields.md

@@ -18,6 +18,7 @@ Source: official Claude Code sub-agents spec. Only `name` and `description` are
 | `effort` | string | `low` \| `medium` \| `high` \| `xhigh` \| `max`. **Plugin agents authored in CBP MUST set this explicitly** (no commented-out placeholder); see [/cbp-build-cc-mode](../../build-cc-mode/SKILL.md) for the matrix |
 | `isolation` | string | `worktree` — gives the agent a temporary git worktree |
 | `color` | string | `red` \| `blue` \| `green` \| `yellow` \| `purple` \| `orange` \| `pink` \| `cyan` |
+| `memory` | string | Which memory store the agent reads/writes: `user` \| `project` \| `local` |
 | `initialPrompt` | string | Auto-submitted first user turn when the agent is the main session agent |
 
 ## Tool-allowlist special forms
@@ -34,3 +35,33 @@ Source: official Claude Code sub-agents spec. Only `name` and `description` are
 2. Per-invocation `model` parameter passed by Claude
 3. The `model` field in this file
 4. Main conversation's model
+
+## Task( → Agent( rename (v2.1.63)
+
+The `Agent` tool replaces the older `Task` tool. `Task()` still works as a stale alias but new agents should use `Agent(...)` in their `tools:` allowlists. Example: `tools: Agent(worker, researcher)` — not `Task(worker, researcher)`. The runtime accepts both forms; prefer `Agent`.
+
+## Plugin agent limitations
+
+Plugin agents (those defined in `.claude/agents/`) ignore the following fields — they are parsed without error but have **no runtime effect**:
+
+- `hooks` — lifecycle hooks are silently no-opped for plugin agents
+- `mcpServers` — scoped MCP server definitions are ignored
+- `permissionMode` — the parent session's permission mode applies unchanged; the child cannot set its own
+
+This is distinct from agents run as the main thread via `claude --agent`, where these fields take full effect.
+
+## Skills-preload constraint
+
+Skills listed in `skills:` are preloaded — their full content is injected into the agent's context at startup. Do NOT preload skills that carry `disable-model-invocation: true`. A preloaded skill with that flag is loaded at startup but can never be invoked at runtime, so its content wastes context and its intent cannot be fulfilled.
+
+## CBP-only fields (not read by Claude Code)
+
+`scope:` is **CBP framework metadata** — it is NOT part of the official Claude Code sub-agents spec and is not read by the Claude Code runtime. It declares the agent's distribution class:
+
+| Value | Meaning |
+|-------|---------|
+| `org-shared` | Ships identically to every consuming repo via the `codebyplan` package |
+| `project-shared` | Shared across repos in a single project family |
+| `repo-only:<name>` | Bound to one repo; `<name>` is the repo slug |
+
+Required only on user-created agents (no template twin). Package-managed agents are `org-shared` by default — no marker needed. See [rules/scope-vocabulary.md](../../../../rules/scope-vocabulary.md).

package/templates/skills/cbp-build-cc-agent/reference/permission-modes.md

@@ -16,3 +16,9 @@ Source: official Claude Code sub-agents and permission-modes specs.
 - If parent is `bypassPermissions` or `acceptEdits`, child cannot weaken it
 - If parent is `auto`, child inherits `auto` and its `permissionMode` is ignored
 - Otherwise the child's `permissionMode` takes effect as declared
+
+## Plugin agents
+
+Plugin agents (those defined in `.claude/agents/` and loaded by the runtime, not run via `claude --agent`) **ignore `permissionMode` entirely**. The field is valid YAML and parses without error, but has no runtime effect — the parent session's permission mode applies unchanged.
+
+Likewise, `hooks` and `mcpServers` are ignored for plugin agents regardless of the parent session's permission mode. These fields only take effect when the agent runs as the main thread via `claude --agent`.

package/templates/skills/cbp-build-cc-agent/templates/agent.md

@@ -6,6 +6,7 @@ tools: Read, Grep, Glob, Bash
 # disallowedTools: Write, Edit  # alternative to tools — inherits then removes
 # review with /cbp-build-cc-mode if defaults don't fit this agent's purpose
 model: sonnet
+# memory: user  # user | project | local — which memory store this agent reads/writes
 # permissionMode: default  # default | acceptEdits | auto | dontAsk | bypassPermissions | plan
 # maxTurns: 20
 effort: xhigh

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

@@ -24,8 +24,8 @@ Precedence is `deny > ask > allow`; arrays union across scopes (managed/user/pro
 
 - **Non-lifecycle, non-shipment `/cbp-*` skills** — authoring (`cbp-build-cc-*`), frontend (`cbp-frontend-*`), git (`cbp-git-*`, `cbp-merge-main`, `cbp-refresh-infra`), round work (`cbp-round-plan`, `cbp-verify` — `cbp-verify` is the autonomous verify stage that runs deterministic gates, proves execution, spawns the fresh-context reviewer, and routes to `cbp-round-complete` or `cbp-round-plan`, so it runs without a prompt), setup/configure (`cbp-setup-*`, `cbp-ship-configure`, `cbp-supabase-*`), task prep (`cbp-task-create`/`-start`, `cbp-standalone-task-check`/`-testing`), planning (`cbp-checkpoint-plan`/`-update`), plus `cbp-session-start` and `cbp-todo`. Invoking a skill is the intended mode of operation; the gated side effects happen inside via the Bash/MCP tools the skill calls, which carry their own tiering. The lifecycle/state-transition and plan-approval skills are the exception — they live in `ask` (next section).
 - **All `mcp__codebyplan__*` reads** (`get_*`, `list_*`, `search_*`, `health_check`, `lookup_symbol`, `resolve_library_id`, `get_chunk`).
-- **Routine workflow-write MCP tools** the pipeline calls many times per task: create/update/complete checkpoint, task, and round; session log + session-state writes; `create_worktree`, `add_library`, `flag_stale_chunk`, `update_server_config`, `update_eslint_repo_config`, `update_task_template`. Gating these with `ask` would make the autonomous workflow unusable.
-- **Read/safe CLI commands** (both `codebyplan X` and `npx codebyplan X`): `whoami`, `statusline`, `ports`, `tech-stack`, `eslint`, `round`, `help`, `--version`.
+- **Routine workflow-write MCP tools** the pipeline calls many times per task: create/update/complete checkpoint, task, and round; session log + session-state writes; `create_worktree`, `add_library`, `flag_stale_chunk`, `update_server_config`, `update_eslint_repo_config`. Gating these with `ask` would make the autonomous workflow unusable.
+- **Read/safe CLI commands** (both `codebyplan X` and `npx codebyplan X`): `whoami`, `resolve-worktree`, `statusline`, `ports`, `tech-stack`, `eslint`, `round`, `help`, `--version`.
 
 ### `ask` — the deliberate confirm-gate
 
@@ -66,11 +66,18 @@ This means:
 - 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 model-aware 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-build`, `cbp-verify`, `cbp-standalone-task-testing`,
+context window exceeds the model-aware threshold:
+
+- **Standard models**: `CBP_CONTEXT_WARN_TOKENS` (default 200 000 tokens)
+- **1M-context models** (model id contains `[1m]`): `CBP_CONTEXT_WARN_TOKENS_1M` (default 800 000 tokens)
+
+When no model id is found in the transcript the hook fails conservative to the standard 200K
+tier. Each env var overrides only its own tier — the other tier is unaffected.
+
+The heavy allowlist is: `cbp-round-build`, `cbp-verify`, `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:

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

@@ -97,6 +97,7 @@ Key fields by use case:
 | Manual-only workflow                                 | `disable-model-invocation: true`                                                                                                                                                                                                 |
 | Hide from `/` menu                                   | `user-invocable: false`                                                                                                                                                                                                          |
 | Pre-approve tools                                    | `allowed-tools: Bash(git add *) Bash(git commit *)`                                                                                                                                                                              |
+| Block specific tools                                 | `disallowed-tools: Write, Edit` (denylist applied before `allowed-tools`; blocks those tools for the duration of the skill)                                                                                                       |
 | Accept arguments                                     | `argument-hint: [file] [mode]`, optionally `arguments: [file mode]` for named `$file`/`$mode`                                                                                                                                    |
 | Set model + effort                                   | `model: inherit` (the standard value — explicitly signals session-model inheritance) and `effort: xhigh` (default for plugin skills; lower tiers `high`/`medium`/`low` per [/cbp-build-cc-mode](../build-cc-mode/SKILL.md)). A non-`inherit` model pin forces a model the user didn't choose and can carry the session's 1M `[1m]` tier onto the skill (→ "usage credits required for 1M context"), so pin only as a deliberate, documented exception |
 | Path-scoped auto-load                                | `paths: ["src/api/**/*.ts"]`                                                                                                                                                                                                     |

package/templates/skills/cbp-build-cc-skill/reference/frontmatter-fields.md

@@ -12,6 +12,7 @@ Source: official Claude Code skills spec. All fields are optional; `description`
 | `disable-model-invocation` | `true` → only user can invoke (via `/name`). Upstream skills that auto-trigger this skill MUST emit a `Next: /name` directive instead — model invocation is blocked by the runtime; see SKILL.md Step 4 "Convention: User-only / permission-gated finalizer" |
 | `user-invocable` | `false` → hidden from `/` menu, Claude-only |
 | `allowed-tools` | Pre-approve tools while the skill is active |
+| `disallowed-tools` | Denylist tools blocked while the skill is active — complement to `allowed-tools`. Applied before `allowed-tools`; e.g. `disallowed-tools: Write, Edit` prevents those tools even if the session allows them |
 | `model` | Model for this skill's turn. **CBP skills set `model: inherit`** (the standard value — explicitly signals session-model inheritance). A non-`inherit` pin (e.g. `sonnet`) forces that model and can carry the session's 1M `[1m]` context tier onto the skill, triggering "usage credits required for 1M context"; use only as a deliberate, documented exception — see [/cbp-build-cc-mode](../../build-cc-mode/SKILL.md) |
 | `effort` | Override effort level (`low`/`medium`/`high`/`xhigh`/`max`). **Plugin skills authored in CBP MUST set this explicitly** (no commented-out placeholder); defaults to `xhigh`. See [/cbp-build-cc-mode](../../build-cc-mode/SKILL.md) for the matrix |
 | `context` | `fork` → run in a subagent |
@@ -39,3 +40,16 @@ Total skill-description budget in context: 1% of the context window (fallback 8,
 | `user-invocable: false` | No | Yes | Description in context; body loads on auto-invoke |
 
 > **Upstream-directive rule**: a skill with `disable-model-invocation: true` cannot be invoked by another skill. Any upstream skill that auto-triggers it MUST emit a `Next: /skill-name` close-out directive and stop. See "Convention: User-only / permission-gated finalizer" in SKILL.md Step 4 for the full pattern and canonical example.
+
+## `context: fork` + `agent:` interplay
+
+`agent:` is **ignored by the runtime unless `context: fork` is also set**. When both are present, the skill body runs in the named agent's context (isolated subagent). Built-in agent types: `Explore`, `Plan`, `general-purpose`, or any custom agent name. Note that `Explore`/`Plan` subagents skip the project `CLAUDE.md` — they have no inherited session context. Use `general-purpose` (or a custom agent) when the forked skill needs CLAUDE.md to be in scope.
+
+## CBP-only fields (not read by Claude Code)
+
+Two fields in CBP `.claude/` structural files are **CBP framework metadata** — they are NOT part of the official Claude Code skills spec and are not read by the Claude Code runtime:
+
+| Field | Purpose |
+|-------|---------|
+| `scope:` | Distribution class — `org-shared` \| `project-shared` \| `repo-only:<repo-name>`. Required only on user-created skills (no template twin). Package-managed skills are `org-shared` by default and need no marker. See [rules/scope-vocabulary.md](../../../../rules/scope-vocabulary.md) |
+| `triggers:` | CBP pipeline routing documentation only — describes when the skill auto-fires in the CBP pipeline. Has no runtime effect; Claude Code does not read it |

package/templates/skills/cbp-build-cc-skill/templates/skill.md

@@ -8,6 +8,7 @@ description: What this skill does and when to use it. Front-load the key use cas
 # disable-model-invocation: false  # true = only user can invoke via /name
 # user-invocable: true  # false = only Claude can invoke (hidden from / menu)
 # allowed-tools: Read, Grep, Glob, Bash(git status *)
+# disallowed-tools: Write, Edit  # tools blocked while the skill is active (complement to allowed-tools)
 # model:  # OMIT to inherit the session model (recommended). A pinned model can carry the session's 1M [1m] tier and require usage credits — pin only as a documented exception (see /cbp-build-cc-mode)
 # review effort with /cbp-build-cc-mode if the default doesn't fit this skill's purpose
 effort: xhigh

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

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

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

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

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

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

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

@@ -85,6 +85,42 @@ Stop here.
 
 `task.context.verify_verdict` must exist and have `verdict: 'READY'` (written by `/cbp-verify` Phase 6 when it runs at task scope — whole-repo `codebyplan check --scope task`, holistic `cbp-verify-reviewer`, and the single batched human walkthrough all passed). If absent or not `READY`, surface "Run `/cbp-verify` first" and stop.
 
+### Step 2.6: Verify Task Handoff Is Resolved
+
+Run `codebyplan handoff status --json` and parse the output.
+
+Check if `nonEmpty[]` contains an entry where `level === 'task'` AND `identifier === '{NNN}-{T}'`
+(the 3-digit zero-padded checkpoint number, hyphen, task number — e.g. `231-3`).
+
+> Gate scope is intentional: only **task**-level handoffs block here. Checkpoint-level handoffs
+> (written by `/cbp-session-end` as resume-pointers) are deliberately scoped to
+> `/cbp-checkpoint-complete`, NOT task finalize — do not "fix" this to gate on checkpoint level.
+
+If a matching entry is found, BLOCK with:
+
+```
+## Cannot Complete Task — Handoff Unresolved
+
+TASK-[N] has unresolved handoff content at `.codebyplan/handoff/task/[NNN]-[T].md`.
+
+The handoff file contains scope that has not been resolved. You must clear it before
+completing this task. Three options — pick exactly one:
+
+1. **Absorb** — address the pending scope in current work, then clear:
+   `codebyplan handoff clear --level task --number [NNN] --task [T]`
+2. **Defer** — create a follow-up task or standalone task to cover the scope,
+   then clear: `codebyplan handoff clear --level task --number [NNN] --task [T]`
+3. **Escalate** — move the content to the repo handoff:
+   `codebyplan handoff append --level repo --content "<content>"`
+   then clear: `codebyplan handoff clear --level task --number [NNN] --task [T]`
+
+Never silently delete handoff content — it represents tracked scope.
+```
+
+(STOP)
+
+If no matching entry: continue to Step 3.
+
 ### Step 3: Verify QA and File Approval
 
 Load `task.qa` and `task.files_changed`:
@@ -133,7 +169,7 @@ Skip the push only when nothing was committed in Step 5 AND `/cbp-merge-main` re
 
 ### Step 7: Complete Task
 
-MCP `complete_task(task_id)`. The server keys on the JWT user (`ctx.userId`) — no worktree param is needed. The server auto-clears `assigned_user_id` on the task; if this was the last sibling task, it also clears the parent checkpoint's assignment.
+MCP `complete_task(task_id)` — kept on MCP because the CLI `codebyplan task complete` sends an empty POST body and cannot forward `caller_worktree_id`, which the server uses to enforce the mutate-lock. `caller_worktree_id` is auto-injected by the `cbp-mcp-caller-worktree-inject.sh` PreToolUse hook (CHK-198 TASK-2); the server falls back to the repo `main` worktree only when it is absent, then enforces the mutate-lock. The server auto-clears `assigned_user_id` + `assigned_worktree_id` on the task; if this was the last sibling task, it also clears the parent checkpoint's assignment. (Per CHK-104 hard-lock.)
 
 ### Step 8: Run Cleanup + Migration (inline)
 
@@ -153,7 +189,7 @@ Show the completion summary:
 **Warnings**: [any QA / file-approval warnings from Step 3, or "none"]
 ```
 
-Then route. Same-context transitions (next task in this checkpoint) auto-trigger `cbp-task-start` via the Skill tool. Checkpoint-done (last task) also auto-triggers `cbp-checkpoint-check` via the Skill tool (`ask`-tier — the permission prompt is the human gate; the 200K context guard handles oversized contexts via the cbp-clear-prep flow). Only the no-task-anywhere session-end fallback surfaces as a single directive (`Next: Run /clear, then /cbp-session-end`) for the user to invoke.
+Then route. Same-context transitions (next task in this checkpoint) auto-trigger `cbp-task-start` via the Skill tool. Checkpoint-done (last task) also auto-triggers `cbp-checkpoint-check` via the Skill tool (`ask`-tier — the permission prompt is the human gate; the model-aware context guard handles oversized contexts via the cbp-clear-prep flow — 200K standard, 800K on `[1m]` sessions). Only the no-task-anywhere session-end fallback surfaces as a single directive (`Next: Run /clear, then /cbp-session-end`) for the user to invoke.
 
 #### 9a — Determine routing context
 
@@ -182,7 +218,7 @@ If no next task is found (no pending work anywhere in the repo), emit directive
 The checkpoint has no remaining tasks. Invoke `cbp-checkpoint-check` via the Skill tool.
 `cbp-checkpoint-check` is `ask`-tier — the harness permission prompt IS the human gate; the
 user confirms (or declines) before checkpoint verification and ship begins. If the context
-window is above the 200K threshold the `cbp-skill-context-guard.sh` hook will block it and
+window is above the model-aware threshold (200K standard, 800K for `[1m]` sessions) the `cbp-skill-context-guard.sh` hook will block it and
 direct you to run `/cbp-clear-prep` first; otherwise checkpoint-check starts on confirmation.
 
 ## Integration
@@ -190,7 +226,7 @@ direct you to run `/cbp-clear-prep` first; otherwise checkpoint-check starts on
 - **Triggered by**: `/cbp-verify` (auto, scope=task, when it writes `verify_verdict.verdict === 'READY'`)
 - **Chain**: `/cbp-verify` (scope=task READY) → `/cbp-finalize`
 - **Reads**: `.codebyplan/state/checkpoints/*.json`, `checkpoints/<id>/tasks/*.json`, `checkpoints/<id>/tasks/<id>/rounds/*.json`, `todos.json` (local-first; `npx codebyplan sync` on miss; MCP `get_current_task`/`get_rounds`/`get_tasks` break-glass) — including each round's `verify_manifest` and `task.context.verify_verdict`
-- **Writes**: `codebyplan task update` for `files_changed` (CLI write-through; MCP `update_task` break-glass); MCP `complete_task` for task completion
+- **Writes**: `codebyplan task update` for `files_changed` (CLI write-through; MCP `update_task` break-glass); MCP `complete_task` for task completion (kept MCP — CLI cannot forward `caller_worktree_id`)
 - **Uses skills (inline, no sub-agent)**: `cleanup` (if deletions), `migration` (if exports renamed)
 - **Triggers**: Same-context transitions auto-trigger via the Skill tool (next task in checkpoint → `cbp-task-start {N}`, `allow`-tier, fires silently). Checkpoint-done → auto-triggers `cbp-checkpoint-check` via Skill tool (`ask`-tier, permission prompt IS the human gate). No-task-anywhere fallback → directive `Next: Run /clear, then /cbp-session-end.`
 - **Checkpoint-bound only** — for standalone tasks use `/cbp-standalone-task-complete`

package/templates/skills/cbp-finalize/reference/checkpoint-done-branching.md

@@ -17,7 +17,7 @@ The skill detects "checkpoint done" at Step 9 by:
 When all siblings are done, the skill invokes `cbp-checkpoint-check` via the Skill tool:
 
 - `cbp-checkpoint-check` is `ask`-tier — the harness permission prompt IS the human gate. The user confirms (or declines) before checkpoint verification and the shipment chain begin.
-- No `/clear` is emitted unconditionally. If the `cbp-skill-context-guard.sh` hook detects the context window is above the 200K threshold it blocks the skill and directs you to run `/cbp-clear-prep` first (which writes a handoff; the user then runs `/clear`, then `/cbp-clear-continue` resumes); otherwise checkpoint-check starts immediately on confirmation.
+- No `/clear` is emitted unconditionally. If the `cbp-skill-context-guard.sh` hook detects the context window is above the model-aware threshold (200K for standard models; 800K for `[1m]`-context models; env vars `CBP_CONTEXT_WARN_TOKENS` / `CBP_CONTEXT_WARN_TOKENS_1M`) it blocks the skill and directs you to run `/cbp-clear-prep` first (which writes a handoff; the user then runs `/clear`, then `/cbp-clear-continue` resumes); otherwise checkpoint-check starts immediately on confirmation.
 
 There is no AskUserQuestion menu. Expanding the checkpoint with more tasks (`/cbp-checkpoint-update`) or wrapping up the session (`/cbp-session-end`) are no longer surfaced as inline alternatives — the deterministic next step on checkpoint-done is `cbp-checkpoint-check`. (The user can still invoke those other skills manually at any time; they are simply not part of the auto-flow.)
 

package/templates/skills/cbp-finalize/reference/next-step-heuristic.md

@@ -19,7 +19,7 @@ No AskUserQuestion, no `/clear`. The skill fires immediately.
 
 Two sub-cases:
 
-**Checkpoint done** (last task in the checkpoint complete): auto-trigger `cbp-checkpoint-check` via the Skill tool. `cbp-checkpoint-check` is `ask`-tier — the permission prompt is the human gate; the 200K context guard handles oversized contexts (via `cbp-clear-prep`) only when context is near the limit. No unconditional `/clear`. (See `checkpoint-done-branching.md`.)
+**Checkpoint done** (last task in the checkpoint complete): auto-trigger `cbp-checkpoint-check` via the Skill tool. `cbp-checkpoint-check` is `ask`-tier — the permission prompt is the human gate; the model-aware context guard handles oversized contexts (via `cbp-clear-prep`) only when context is near the limit — 200K standard, 800K on `[1m]` sessions (env vars `CBP_CONTEXT_WARN_TOKENS` / `CBP_CONTEXT_WARN_TOKENS_1M`). No unconditional `/clear`. (See `checkpoint-done-branching.md`.)
 
 **Session end** (no pending tasks anywhere): emit a single directive line at the end of skill output and stop:
 

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

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

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

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

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

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