codebyplan 1.13.62 → 1.13.64

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

@@ -60,35 +60,25 @@ Skip when the description has zero domain matches OR the user already named a ta
 
 Lightweight inference from the description — no deep analysis. **Title**: concise, ≤80 chars. **Goal**: ≤300 chars, a faithful restatement of intent (not a plan).
 
-### Step 6: Claim-or-Open Prompt
-
-Ask the user via AskUserQuestion whether to claim this checkpoint now:
-
-- **Claim for me + this worktree** (default) — resolve `npx codebyplan resolve-worktree 2>/dev/null` and set it as the checkpoint `worktree_id` at create. The creator carries momentum straight through plan → start.
-- **Leave it open** — create with `worktree_id` null so anyone free can claim it later via `/cbp-checkpoint-start`.
-
-Record the choice; it drives both the create call (Step 7) and the plan→start routing in `/cbp-checkpoint-plan`.
-
-### Step 7: Create Checkpoint Row
+### Step 6: Create Checkpoint Row
 
 `codebyplan checkpoint create` (CLI write-through: writes `.codebyplan/state/checkpoints/<id>.json` + REST). Pass flags:
 - `--repo-id` (from `.codebyplan/repo.json`), `--title`, `--goal`, `--deadline`, `--status pending`
 - `--ideas` JSON `[{ description: <raw user text> }]`
-- `--worktree-id` the resolved worktree **only if the user chose "claim"**; omit when "leave open"
 
-Do **not** pass `--number` — the database auto-assigns the next per-repo checkpoint number via a `BEFORE INSERT` trigger (advisory-locked `MAX(number)+1` scoped to `repo_id`). The DB-assigned number comes back on the created row (and is written into `.codebyplan/state/checkpoints/<id>.json`); read it for the branch slug (Step 8) and the result display (Step 9).
+Do **not** pass `--number` — the database auto-assigns the next per-repo checkpoint number via a `BEFORE INSERT` trigger (advisory-locked `MAX(number)+1` scoped to `repo_id`). The DB-assigned number comes back on the created row (and is written into `.codebyplan/state/checkpoints/<id>.json`); read it for the branch slug (Step 7) and the result display (Step 8).
 
 Break-glass fallback: MCP `create_checkpoint` (also omit `number`) when the CLI is unavailable.
 
-This is the first identity-stamping point — when claiming, passing `worktree_id` here engages the CHK-104 hard-lock from birth. No `context`, `research`, `plan`, or tasks are written here.
+Assignment (`assigned_user_id`) is stamped server-side from the caller's JWT when the checkpoint is activated via `/cbp-checkpoint-start` — it is not set at create time. No `context`, `research`, `plan`, or tasks are written here.
 
-### Step 8: Create + Switch to Feat Branch
+### Step 7: Create + Switch to Feat Branch
 
-`{NNN}` below is the DB-assigned checkpoint number read back from the Step 7 `codebyplan checkpoint create` response.
+`{NNN}` below is the DB-assigned checkpoint number read back from the Step 6 `codebyplan checkpoint create` response.
 
 Read `.codebyplan/git.json` `branch_config.production` (default `"main"`) as `BASE`. codebyplan repos are main-only — never create or branch from a `development`/integration branch.
 
-**8.1 — Reuse the cloud-created branch when present.** When the repo is GitHub-connected, the CHK-207 `create-feat-branch` Edge Function fires on the Step 7 row INSERT, creates `feat/CHK-{NNN}-<slug>` on origin, and writes `branch_name` back to the checkpoint row. Creating a second, differently-slugged branch here orphans the cloud one — so re-read the row first:
+**7.1 — Reuse the cloud-created branch when present.** When the repo is GitHub-connected, the CHK-207 `create-feat-branch` Edge Function fires on the Step 6 row INSERT, creates `feat/CHK-{NNN}-<slug>` on origin, and writes `branch_name` back to the checkpoint row. Creating a second, differently-slugged branch here orphans the cloud one — so re-read the row first:
 
 ```bash
 sleep 5  # give the INSERT webhook a moment to write branch_name back
@@ -96,14 +86,14 @@ npx codebyplan sync 2>/dev/null || true
 BRANCH=$(jq -r '.branch_name // empty' ".codebyplan/state/checkpoints/{checkpoint-id}.json" 2>/dev/null)
 ```
 
-(Break-glass: MCP `get_checkpoints` and read the row's `branch_name`.) If `BRANCH` is non-empty, check out the existing remote branch and skip 8.2 entirely — do NOT push (it already exists on origin) and do NOT persist `--branch-name` (the Edge Function already recorded it):
+(Break-glass: MCP `get_checkpoints` and read the row's `branch_name`.) If `BRANCH` is non-empty, check out the existing remote branch and skip 7.2 entirely — do NOT push (it already exists on origin) and do NOT persist `--branch-name` (the Edge Function already recorded it):
 
 ```bash
 git fetch origin "$BRANCH"
 git checkout -b "$BRANCH" --track "origin/$BRANCH"
 ```
 
-**8.2 — Fallback: create the branch locally.** Only when `BRANCH` is empty (repo not GitHub-connected, or the webhook hasn't landed). Compute the slug deterministically:
+**7.2 — Fallback: create the branch locally.** Only when `BRANCH` is empty (repo not GitHub-connected, or the webhook hasn't landed). Compute the slug deterministically:
 
 ```bash
 SLUG=$(codebyplan slug "{checkpoint title}")
@@ -122,13 +112,13 @@ Persist the branch via `codebyplan checkpoint update --id <checkpoint-id> --bran
 
 **Note — Supabase preview branch**: no Supabase branch is created here. Creation is lazy — it happens on the first DB change when `/cbp-supabase-migrate` runs on this feat branch, which provisions a Supabase branch named identically to the git branch. See `cbp-supabase-migrate` Step 2.3 for the creation protocol.
 
-### Step 9: Show Result + Auto-Trigger Plan
+### Step 8: Show Result + Auto-Trigger Plan
 
 ```
 ## Checkpoint Created
 
 **CHK-NNN**: [title]  •  **Deadline**: [date]  •  **Branch**: feat/CHK-NNN-slug
-**Claim**: [claimed by this worktree / left open]
+**Assignment**: stamped on activation via /cbp-checkpoint-start
 **Worktree**: `npx codebyplan worktree add CHK-{NNN}`
 
 Now planning CHK-NNN… handing off to /cbp-checkpoint-plan.
@@ -139,6 +129,6 @@ Auto-trigger `/cbp-checkpoint-plan {NNN}` in the same context. This skill create
 ## Integration
 
 - **Runs inline**: mechanical setup only — no assessment, research, Q&A, plan, or tasks
-- **Reads**: `.codebyplan/state/checkpoints/*.json` (local-first; `npx codebyplan sync` if stale; MCP `get_checkpoints` break-glass); `.codebyplan/repo.json`, `.codebyplan/git.json`; `npx codebyplan resolve-worktree`
-- **Writes**: `codebyplan checkpoint create` (description-only ideas + deadline + optional worktree_id), `codebyplan checkpoint update --branch-name` (break-glass: MCP `create_checkpoint` / `update_checkpoint`)
+- **Reads**: `.codebyplan/state/checkpoints/*.json` (local-first; `npx codebyplan sync` if stale; MCP `get_checkpoints` break-glass); `.codebyplan/repo.json`, `.codebyplan/git.json`
+- **Writes**: `codebyplan checkpoint create` (description-only ideas + deadline), `codebyplan checkpoint update --branch-name` (break-glass: MCP `create_checkpoint` / `update_checkpoint`)
 - **Triggers**: `/cbp-checkpoint-plan` (auto)

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

@@ -265,6 +265,41 @@ After the feat branch git delete, run the same conditional Supabase teardown for
   - If not found: no-op silently — idempotent, not-found is success.
   - If the `list_branches` call itself fails (network, auth, or a non-success response — distinct from a successful lookup that returns no match): emit a non-blocking warning that the Supabase preview branch for `$FEAT_BRANCH` may still exist and should be verified in the dashboard. Do not treat an API failure as a not-found success.
 
+### Step 9.5: Physical Git-Worktree Cleanup
+
+After the feat branch has been git-deleted (Step 9), check whether a git worktree is still
+checked out to that now-deleted branch and clean it up if safe.
+
+```bash
+git worktree list --porcelain
+```
+
+Scan the output for any `worktree` entry whose `branch` field matches `refs/heads/$FEAT_BRANCH`
+(i.e. the feat branch just deleted in Step 9). For each matching worktree path:
+
+**Case A — the current session is NOT inside that worktree path:**
+
+```bash
+codebyplan worktree remove <path>
+git worktree prune
+```
+
+Record the removed path in `WORKTREES_REMOVED[]`. If `codebyplan worktree remove` exits
+non-zero, emit a non-blocking warning and continue — a failed removal does not halt shipment.
+
+**Case B — the current session IS inside that worktree path (i.e. `$PWD` starts with
+`<path>`):**
+
+Do NOT self-remove. Surface a single directive (no A/B/C menu):
+
+> "This session is inside the worktree at `<path>`. After switching to your main checkout,
+> run `codebyplan worktree remove <path>` to clean it up."
+
+Record the path in `WORKTREES_REMOVED[]` as `{ path, status: 'pending_manual_cleanup' }`.
+
+If `git worktree list --porcelain` finds no worktree checked out to the deleted feat branch,
+skip this step silently — `WORKTREES_REMOVED` stays empty.
+
 ### Step 10: Save Shipment Results and Summary
 
 Update checkpoint context via `codebyplan checkpoint update <id> --context '{"shipment": {...}}'` (CLI write-through); use MCP `update_checkpoint` as documented break-glass when the CLI is unavailable. The `shipment` block contains both branch promotion AND runtime surface results (from `/cbp-ship` Step 7):
@@ -280,6 +315,7 @@ context.shipment: {
   stale_branches_cleaned: [list of deleted git branches],
   feat_branch_deleted: true/false,
   supabase_branches_deleted: [list of Supabase preview branch names removed in Steps 8–9],
+  worktrees_removed: WORKTREES_REMOVED,      // from Step 9.5 — paths removed or pending manual cleanup
   e2e_images_uploaded: E2E_IMAGES_UPLOADED   // from Step 7.5 — { count, stored_paths, skipped, error? } (CHK-171)
 }
 ```
@@ -310,6 +346,7 @@ Present summary:
 - Stale branches deleted: [N] ([list])
 - Feat branch: [deleted/kept]
 - Supabase preview branches deleted: [N] ([list from supabase_branches_deleted], or "none")
+- Git worktrees cleaned: [N] ([paths from worktrees_removed], or "none")
 
 ### Before/After Branch State
 - Before: [list of feat/* branches]

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

@@ -8,7 +8,7 @@ effort: xhigh
 
 # Checkpoint Plan Command
 
-Runs INLINE (no subagent) — all analysis and Q&A stay in the main session. This is the rigour stage that prevents half-baked plans: it discovers shortcomings, decides whether existing dependencies suffice or a new one is warranted, compares competing approaches, and only THEN creates tasks. It produces `plan.steps[]` + tasks but **never activates the checkpoint and never claims a user/worktree** — that is `/cbp-checkpoint-start`.
+Runs INLINE (no subagent) — all analysis and Q&A stay in the main session. This is the rigour stage that prevents half-baked plans: it discovers shortcomings, decides whether existing dependencies suffice or a new one is warranted, compares competing approaches, and only THEN creates tasks. It produces `plan.steps[]` + tasks but **never activates the checkpoint and never claims a user** — that is `/cbp-checkpoint-start`.
 
 ## Pipeline
 
@@ -37,7 +37,7 @@ Malformed (non-numeric, contains `-`): surface `checkpoint-plan: invalid argumen
 2. Read task files under `.codebyplan/state/checkpoints/<id>/tasks/*.json` (fallback: MCP `get_tasks(checkpoint_id)`) — load existing tasks. This sets the mode:
    - **fresh** — zero tasks: full plan + create all tasks.
    - **additive re-plan** — tasks exist: gap-analyse against them; only ADD new tasks or refine requirements for gaps. NEVER delete or overwrite an in-flight task.
-3. Note whether `worktree_id` is set (claimed at create) — drives routing in Step 11.
+3. Note whether `assigned_user_id` is set (claimed at activation) — drives routing in Step 11.
 
 ### Step 2: Assess Ideas + Codebase
 
@@ -134,16 +134,18 @@ Final write of the complete `checkpoint.context` JSONB via `codebyplan checkpoin
 ...
 ```
 
-This skill does **NOT** activate the checkpoint and does **NOT** claim a user/worktree.
+This skill does **NOT** activate the checkpoint and does **NOT** claim a user.
 
-- **Claimed by THIS session** — `worktree_id` is set AND equals `npx codebyplan resolve-worktree 2>/dev/null`: auto-trigger `/cbp-checkpoint-start` in the same context (the creator carries momentum into activation).
-- **Otherwise** — `worktree_id` is null, set to a different worktree, or `resolve-worktree` is empty: surface a single directive — `Next: /cbp-checkpoint-start` — so the owning session (or anyone free, if open) claims and starts it. Never auto-activate a checkpoint owned by a different worktree.
+Resolve the current user: `npx codebyplan whoami --json` → `user_id`.
+
+- **Open or yours** — `whoami` returns a `user_id` AND `assigned_user_id` is either null (unclaimed) or equals caller `user_id`: auto-trigger `/cbp-checkpoint-start` in the same context. `assigned_user_id` is stamped on activation, so a freshly-created checkpoint (null) is claimed by `/cbp-checkpoint-start` itself — the creator carries momentum into activation.
+- **Owned by another, or no identity** — `assigned_user_id` is non-null and differs from caller `user_id`, or `whoami` returns no `user_id`: surface a single directive — `Next: /cbp-checkpoint-start` — so the owning session (or anyone free, if open) claims and starts it. Never auto-activate a checkpoint owned by a different user.
 
 ## Integration
 
-- **Reads**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/*.json`, `session/current.json` (local-first; `npx codebyplan sync` if stale; break-glass: MCP `get_current_task`, `get_checkpoints`, `get_tasks`)
+- **Reads**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/*.json`, `session/current.json` (local-first; `npx codebyplan sync` if stale; break-glass: MCP `get_current_task`, `get_checkpoints`, `get_tasks`); `npx codebyplan whoami --json`
 - **Writes**: `codebyplan checkpoint update` (ideas assessment, context, plan, research), `codebyplan task create` (break-glass: MCP `update_checkpoint`, `create_task`)
 - **Spawns**: `cbp-research` (level 2+ only), config-matched `cbp-e2e-*` specialist (opt-in discovery probe, `whole_checkpoint_mode` — see `context/testing/e2e.md` dispatch contract)
 - **Triggered by**: `/cbp-checkpoint-create` (auto), or user directly
-- **Triggers**: `/cbp-checkpoint-start` (auto when claimed at create; directive when left open)
-- **Never**: activates the checkpoint or claims a user/worktree — that is `/cbp-checkpoint-start`
+- **Triggers**: `/cbp-checkpoint-start` (auto when open/unclaimed or assigned to the current user; directive when owned by another or no identity)
+- **Never**: activates the checkpoint or claims a user — that is `/cbp-checkpoint-start`

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

@@ -8,7 +8,7 @@ effort: high
 
 # Checkpoint Start Command
 
-The activation + claim gate of the checkpoint pipeline. `/cbp-checkpoint-plan` produces tasks but deliberately leaves the checkpoint `pending` and possibly unclaimed so it can sit in a team queue. This skill flips it to `active`, claims it for the caller's worktree if still open, and routes into the first task.
+The activation + claim gate of the checkpoint pipeline. `/cbp-checkpoint-plan` produces tasks but deliberately leaves the checkpoint `pending` and unclaimed so it can sit in a team queue. This skill flips it to `active` — the server auto-stamps `assigned_user_id` from the caller's JWT on activation — and routes into the first task.
 
 ## Pipeline
 
@@ -20,7 +20,13 @@ The activation + claim gate of the checkpoint pipeline. `/cbp-checkpoint-plan` p
 
 ### Step 0: Parse `$ARGUMENTS`
 
-Source `repo_id` from `.codebyplan/repo.json`. Resolve caller worktree once for the whole skill: `CALLER_WT=$(npx codebyplan resolve-worktree 2>/dev/null)`.
+Source `repo_id` from `.codebyplan/repo.json`. Resolve the current user once for the whole skill:
+
+```bash
+npx codebyplan whoami --json   # → {"user_id":"<uuid>","email":"…"} or null
+```
+
+`USER_ID` = `user_id` from the result (may be null for anonymous/keychain-empty callers).
 
 | Shape | Resolves to |
 |-------|-------------|
@@ -31,55 +37,57 @@ Malformed (non-numeric, contains `-`): surface `checkpoint-start: invalid argume
 
 ### Step 1: Load Checkpoint + Tasks
 
-Read `.codebyplan/state/checkpoints/<id>.json` for `status`, `worktree_id`, `plan` (local-first; if missing/stale run `npx codebyplan sync` once; break-glass: MCP `get_checkpoints`). Read task files under `.codebyplan/state/checkpoints/<id>/tasks/*.json` (fallback: MCP `get_tasks(checkpoint_id)`).
+Read `.codebyplan/state/checkpoints/<id>.json` for `status`, `assigned_user_id`, `plan` (local-first; if missing/stale run `npx codebyplan sync` once; break-glass: MCP `get_checkpoints`). Read task files under `.codebyplan/state/checkpoints/<id>/tasks/*.json` (fallback: MCP `get_tasks(checkpoint_id)`).
 
 ### Step 2: Planned-Gate
 
 A checkpoint must be planned before it can start.
 
-- **No tasks AND empty `plan.steps[]`** → refuse: surface `CHK-NNN is not planned yet.` and auto-trigger `/cbp-checkpoint-plan {NNN}`. STOP. (An unplanned checkpoint is `worktree_id`-null, so there is nothing to own yet — always kick off planning, matching `/cbp-todo` Rule A.)
+- **No tasks AND empty `plan.steps[]`** → refuse: surface `CHK-NNN is not planned yet.` and auto-trigger `/cbp-checkpoint-plan {NNN}`. STOP. (An unplanned checkpoint is unassigned, so there is nothing to own yet — always kick off planning, matching `/cbp-todo` Rule A.)
 - **Already `active`** → no activation needed; skip to Step 3 for a claim-check only, then Step 5.
 - **`pending` with tasks** → proceed.
 
 ### Step 3: Claim Logic
 
-Compare the checkpoint's `worktree_id` against `CALLER_WT`:
+Compare the checkpoint's `assigned_user_id` against `USER_ID`:
 
-| Checkpoint `worktree_id` | Action |
-|--------------------------|--------|
-| null (left open at create) | Claim it: in Step 4 pass `worktree_id: CALLER_WT`. If `CALLER_WT` is empty, warn the checkpoint will stay unclaimed and proceed without it. |
-| equals `CALLER_WT` | Already yours — no-op. |
-| a DIFFERENT worktree | STOP. Surface: `CHK-NNN is claimed by worktree {other}; current worktree is {CALLER_WT}. If {other} is dead, a maintainer can release it via the release_assignment MCP tool, then re-run /cbp-checkpoint-start.` Do not activate. |
+| Checkpoint `assigned_user_id` | Action |
+|-------------------------------|--------|
+| null (open — not yet claimed) | Proceed to Step 4 activation. The server will stamp `assigned_user_id = USER_ID` (from JWT) on `status=active`. If `USER_ID` is null (anonymous caller), warn the checkpoint will stay unclaimed and proceed. |
+| equals `USER_ID` | Already yours — no-op. Proceed to Step 5. |
+| a DIFFERENT user (non-null) | STOP. Surface: `CHK-NNN is assigned to user <assigned_user_id-email-or-uuid>; you are <USER_ID-email-or-uuid>. Ask the owner to release the assignment, or a maintainer can use the release_assignment tool, then re-run /cbp-checkpoint-start.` Do not activate. |
 
-This mirrors the CHK-104 hard-lock model — never wrest a checkpoint from a live worktree.
+Never wrest a checkpoint from another user.
 
 ### Step 4: Activate
 
-If the checkpoint is already `active` AND `worktree_id` already equals `CALLER_WT` (the Step 3 no-op row), skip this step entirely and proceed to Step 5 — nothing to write.
+If the checkpoint is already `active` AND `assigned_user_id` already equals `USER_ID` (the Step 3 no-op row), skip this step entirely and proceed to Step 5 — nothing to write.
+
+Otherwise set the checkpoint `active` via `codebyplan checkpoint update --id <checkpoint-id> --status active` (CLI write-through; break-glass: MCP `update_checkpoint`). The server auto-stamps `assigned_user_id = ctx.userId` (from the JWT) on activation — no client-side user param required. After the write, read the row back to confirm `assigned_user_id` is non-null.
 
-Otherwise set the checkpoint `active` via `codebyplan checkpoint update --id <checkpoint-id> --status active` (CLI write-through; break-glass: MCP `update_checkpoint`), plus `--worktree-id CALLER_WT` when claiming per Step 3. For MCP break-glass path: `caller_worktree_id` identifies the calling worktree and 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. If the checkpoint was already `active` but a claim is still needed, skip the status write and only write `worktree_id`.
+If the checkpoint was already `active` but `assigned_user_id` is still null (edge case: prior activation without a valid JWT), re-read and surface a warning rather than silently proceeding.
 
 ### Step 5: Route
 
 Follow the close-out routing convention — auto-trigger the next same-context step, never an A/B/C menu. `{first-pending-task}` is the lowest-numbered pending task from Step 1 (not necessarily TASK-1, since additive re-planning may have completed earlier ones):
 
-- **Claimed by THIS session** (`CALLER_WT` now owns the checkpoint): auto-trigger `/cbp-task-start {chk}-{first-pending-task}` in the same context.
-- **`CALLER_WT` empty / unresolved**: surface a single directive — `Next: /cbp-task-start {chk}-{first-pending-task}` — and let the user proceed.
+- **Claimed by THIS session** (`USER_ID` is non-null and now owns the checkpoint): auto-trigger `/cbp-task-start {chk}-{first-pending-task}` in the same context.
+- **`USER_ID` null / anonymous**: surface a single directive — `Next: /cbp-task-start {chk}-{first-pending-task}` — and let the user proceed.
 
 Show a one-line confirmation before routing:
 
 ```
 ## Checkpoint Started
 
-**CHK-NNN**: [title]  •  **Status**: active  •  **Claimed by**: [worktree or "open"]
+**CHK-NNN**: [title]  •  **Status**: active  •  **Claimed by**: [user email or "open"]
 **Next task**: TASK-[N] — [title]
 **Worktree**: `npx codebyplan worktree add CHK-{NNN}`
 ```
 
 ## Integration
 
-- **Reads**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/*.json` (local-first; `npx codebyplan sync` if stale; break-glass: MCP `get_checkpoints`, `get_tasks`); `npx codebyplan resolve-worktree`
-- **Writes**: `codebyplan checkpoint update --status active [--worktree-id <id>]` (CLI write-through; break-glass: MCP `update_checkpoint`; `caller_worktree_id` auto-injected by cbp-mcp-caller-worktree-inject.sh hook on the MCP path)
-- **Triggered by**: `/cbp-checkpoint-plan` (auto when claimed at create), `/cbp-todo` (planned-but-pending gate), or user directly
+- **Reads**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/*.json` (local-first; `npx codebyplan sync` if stale; break-glass: MCP `get_checkpoints`, `get_tasks`); `npx codebyplan whoami --json`
+- **Writes**: `codebyplan checkpoint update --status active` (CLI write-through; break-glass: MCP `update_checkpoint`; server auto-stamps `assigned_user_id` from JWT on activation)
+- **Triggered by**: `/cbp-checkpoint-plan` (auto when open/unclaimed or assigned to the current user), `/cbp-todo` (planned-but-pending gate), or user directly
 - **Triggers**: `/cbp-task-start` (auto when claimed), or `/cbp-checkpoint-plan` (when the checkpoint is unplanned)
 - **Never**: plans or creates tasks — that is `/cbp-checkpoint-plan`

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

@@ -43,7 +43,7 @@ Given the parse from Step 0.5:
 | Parse | Resolution path |
 |-------|-----------------|
 | `{chk}` | Scan `.codebyplan/state/checkpoints/*.json` for `number === {chk}` (local-first; if missing/stale run `npx codebyplan sync` once; break-glass: MCP `get_checkpoints`). |
-| _(empty)_ | Read `.codebyplan/state/session/current.json` (with worktree_id from `npx codebyplan resolve-worktree`) to find the active checkpoint (fallback: MCP `get_current_task`). If no active checkpoint, scan local state for `pending` checkpoints (fallback: MCP `get_checkpoints` filtered by `pending`). |
+| _(empty)_ | Read `.codebyplan/state/session/current.json` to find the active checkpoint (fallback: MCP `get_current_task`). If no active checkpoint, scan local state for `pending` checkpoints (fallback: MCP `get_checkpoints` filtered by `pending`). |
 
 ### Step 1.5: Detect Entry Context (from `/cbp-finalize` expand path)
 

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

@@ -119,4 +119,4 @@ The user must run both commands manually.
 - **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)
+- **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

@@ -153,7 +153,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 +182,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

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

@@ -25,7 +25,7 @@ Set `KIND` for the rest of this skill. MCP tool names vary by KIND:
 | Get task | local state (break-glass: `get_current_task`) | `get_current_standalone_task(repo_id)` |
 | Get rounds | local state (break-glass: `get_rounds`) | `get_standalone_rounds(standalone_task_id)` |
 | Update round | `update_round(round_id, ...)` | `update_standalone_round(standalone_round_id, ...)` |
-| Complete round | `complete_round(round_id, duration_minutes?)` | `complete_standalone_round(standalone_round_id, duration_minutes?, caller_worktree_id)` ⚠️ `caller_worktree_id` is REQUIRED for standalone |
+| Complete round | `complete_round(round_id, duration_minutes?)` | `complete_standalone_round(standalone_round_id, duration_minutes?)` |
 
 # Round Complete Command
 
@@ -84,20 +84,7 @@ Reconcile which files the user has approved by staging them. Run:
 npx codebyplan round sync-approvals --round-id <round_id> --task-id <task_id>
 ```
 
-The CLI auto-resolves the caller worktree id with the following precedence:
-1. `--caller-worktree-id <uuid>` override (if passed — skips all resolution)
-2. Per-device branch-keyed cache (`.codebyplan/worktree.local.json`)
-3. In-process tuple API call: `POST /worktrees/resolve` using `(device_id, repo_path, branch)`
-
-On the write path (non `--dry-run`), if the worktree id cannot be resolved the CLI **hard-fails with exit 1** and prints an actionable message. To pre-populate the cache:
-
-```
-npx codebyplan resolve-worktree --cache
-```
-
-If this worktree is not yet registered, run `npx codebyplan setup` first, then re-run `/cbp-round-complete`.
-
-The CLI parses `git status --short`, merges drift + staging + web-UI flag, and writes both round and task (forwarding `caller_worktree_id` on both writes so the server honors the feat-worktree lock). A **cleanly staged** file (`git add`-ed, no further unstaged changes) becomes `user_approved: true`.
+The CLI parses `git status --short`, merges drift + staging + web-UI flag, and writes both round and task. A **cleanly staged** file (`git add`-ed, no further unstaged changes) becomes `user_approved: true`.
 
 Read the stdout JSON: `{ added, stale_marked, reactivated, total_files }`.
 
@@ -110,14 +97,7 @@ This is the **single** explicit reconcile owned by this skill. (The `cbp-mcp-rou
 Calculate duration from the round's `started_at` to now in minutes.
 
 - **checkpoint KIND**: `codebyplan round complete --id <round_id> --task-id <task_id> --checkpoint-id <checkpoint_id>` (CLI write-through: local state file + REST). Break-glass fallback: MCP `complete_round(round_id, duration_minutes)` when the CLI is unavailable. Note: the CLI does not accept `duration_minutes`; the backend computes duration server-side.
-- **standalone KIND**: MCP `complete_standalone_round(standalone_round_id, duration_minutes, caller_worktree_id)`. ⚠️ `caller_worktree_id` is REQUIRED — resolve via `CALLER_WT=$(npx codebyplan resolve-worktree 2>/dev/null)`. If `CALLER_WT` is empty, surface this warning and ask the user to confirm before proceeding:
-
-  ```
-  Warning: could not resolve caller_worktree_id (npx codebyplan resolve-worktree returned empty).
-  The complete_standalone_round call may be rejected by the pre-guard. Proceed anyway? (yes / no)
-  ```
-
-  If the user confirms yes, proceed with `caller_worktree_id: ""`. If no, stop.
+- **standalone KIND**: MCP `complete_standalone_round(standalone_round_id, duration_minutes)`. The server keys on the JWT user (`ctx.userId`) — no worktree param needed or accepted.
 
 `complete_round` / `complete_standalone_round` sets the round `completed`, locks all `file_changes` for the round (`approval_locked: true`), and returns `unapproved_files[]` + `unapproved_count`. Hold those for routing.
 
@@ -158,7 +138,6 @@ Payload: `round.context.round_complete = { staged_count, unstaged_count, route,
 - **Permission prompt = confirmation** — gated by `ask`-tier `Skill(cbp-round-complete)`. Because the skill is `disable-model-invocation: true`, this gate applies to the user's **direct** `/cbp-round-complete` invocation. NEVER add an AskUserQuestion to confirm running; the harness prompt is the gate. A declined permission is a clean no-op.
 - **Step 2 (CLI) must exit 0** — if it fails, STOP before `complete_round`. The merge semantics are enforced by the CLI.
 - **NEVER ask the user to git add files** — Step 2 only reads staging status. **NEVER stage files** — Claude does not touch the git staging area; the user's `git add` is the approval signal.
-- **standalone KIND Step 3**: `caller_worktree_id` is REQUIRED for `complete_standalone_round` — always resolve and pass it.
 
 ## Integration
 

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

@@ -25,7 +25,7 @@ Set `KIND` for the rest of this skill. Read/write sources vary by KIND:
 | Get rounds | local state (break-glass: `get_rounds`) | `get_standalone_rounds(standalone_task_id)` |
 | Add round | `codebyplan round add` (break-glass: `add_round`) | `add_standalone_round(standalone_task_id, ...)` |
 | Update round | `codebyplan round update` (break-glass: `update_round`) | `update_standalone_round(standalone_round_id, ...)` |
-| Complete round | `complete_round(round_id, duration_minutes?)` | `complete_standalone_round(standalone_round_id, duration_minutes?, caller_worktree_id)` ⚠️ `caller_worktree_id` is REQUIRED for standalone |
+| Complete round | `complete_round(round_id, duration_minutes?)` | `complete_standalone_round(standalone_round_id, duration_minutes?)` |
 | Update task | `codebyplan task update` (break-glass: `update_task`) | `update_standalone_task(standalone_task_id, ...)` |
 
 > **Note**: The `standalone` KIND column uses MCP tools unchanged — standalone local-first migration is out of scope and will be addressed in a later task.

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

@@ -22,35 +22,46 @@ 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
-
-### Step 1.3: Capture Handoff Snapshot
-
-Snapshot the current next-action so the next `/cbp-session-start` (Step 4.5) can auto-resume. The handoff write-path + payload shape are specified inline here and in `/cbp-session-start` Step 4.5 (freshness gate).
-
-1. Read `.codebyplan/state/todos.json` (local-first) and take the queue head `rows[0]` (rows are ordered by `sort_order`; `rows[0]` is the current next-action). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_todos({ repo_id, worktree_id })` when the state dir is absent and sync fails. The worker stamps `command`, `instructions`, `state`, and the entity ids `checkpoint_id` / `task_id` / `round_id` on every row.
-2. If `rows[0]` exists and its `command` is non-empty (active work in flight):
-   ```yaml
-   handoff:
-     command: <rows[0].command> # e.g. "/cbp-verify"
-     instructions: <rows[0].instructions> # human-readable trigger reason
-     state: <rows[0].state> # workflow state label
-     context: # entity ids used by the Step 4.5 freshness probe
-       checkpoint_id: <rows[0].checkpoint_id>
-       task_id: <rows[0].task_id>
-       round_id: <rows[0].round_id>
-     captured_at: <ISO now> # for entity-drift freshness comparison
-     captured_session_log_id: <current session log id>
-   ```
-3. If the queue is empty or `rows[0].command` is empty / idle: set `handoff = null` so the next session's probe falls through to `/cbp-todo`.
-4. Hold `handoff` in context for Step 1's `update_session_log` call below — it ships in the same write as `ended_at` and `summary`.
-
-Continuing Step 1:
-
-3. Run `codebyplan session update-log --id <log-id> --ended-at <now> --summary <text> --pending <text> --handoff <json>` (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> --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:
    - `ended_at`: now (maps to the `closed_at` column per TASK-2 alias)
-   - `handoff`: from Step 1.3 (jsonb or `null`; MCP write surface aliases to the `content` column transparently per CHK-111 Migration A — `handoff` wins over `content` when both are passed)
    - `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).
+
+### 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.
+
+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:
+     ```
+     Write handoff file for next session?
+     <path>
+
+     Reply: yes | no
+     ```
+   - On `yes`: write the file with this structure:
+     ```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>
+     ```
+   - The file is committed with the session's final commit (Step 1.5) or the user can stage it manually.
+
+3. **If the queue is empty or `rows[0].command` is empty/idle**: skip — no handoff file is written.
 
 ### Step 1.5: Commit Non-Task Files
 
@@ -117,7 +128,7 @@ Stop this worktree's Realtime watch daemon, non-blocking and non-fatal:
 npx codebyplan watch stop 2>/dev/null || true
 ```
 
-This SIGTERMs the per-worktree pidfile daemon started by `cbp-session-start-hook.sh`. Silently ignored when no daemon is running for this worktree. If there is no daemon to stop (e.g. session-start was skipped), `watch stop` itself exits 0 — the `|| true` guard is defense-in-depth only, so Step 3's session-state write never sees a failure from this step.
+This SIGTERMs the per-worktree pidfile daemon started by `cbp-session-start-hook.sh`. Silently ignored when no daemon is running. If there is no daemon to stop (e.g. session-start was skipped), `watch stop` itself exits 0 — the `|| true` guard is defense-in-depth only, so Step 3's session-state write never sees a failure from this step.
 
 ### Step 3: Update Session State
 
@@ -134,9 +145,8 @@ You can close this window.
 ## Integration
 
 - **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 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`)
+- **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`)
 - **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`
-- **Pairs with**: `/cbp-session-start` Step 4.5 (handoff payload shape + freshness-gate contract; specified inline — no separate rule file)