codebyplan 1.13.38 → 1.13.40

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

@@ -14,14 +14,14 @@ Inspect the resolved identifier from argument parsing to determine the task kind
 |-----------------|------|
 | `{task}-{round}` (2-segment, e.g. `45-2`) | `standalone` |
 | `{chk}-{task}-{round}` (3-segment, e.g. `141-3-1`) | `checkpoint` |
-| _(empty / free-text)_ | Check `get_current_standalone_task` first; if found → `standalone`. Else → `checkpoint` via `get_current_task`. |
+| _(empty / free-text)_ | Check `get_current_standalone_task` first; if found → `standalone`. Else → `checkpoint` via `get_current_task`. (Kind-detection is MCP-unavoidable — no identifier yet means no local path to probe; subsequent operations are local-first per the rows below.) |
 
 Set `KIND` for the rest of this skill. MCP tool names vary by KIND:
 
 | Operation | `checkpoint` KIND | `standalone` KIND |
 |-----------|------------------|-------------------|
-| Get task | `get_current_task(repo_id)` | `get_current_standalone_task(repo_id)` |
-| Get rounds | `get_rounds(task_id)` | `get_standalone_rounds(standalone_task_id)` |
+| 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)` |
 | Add round | `add_round(task_id, ...)` | `add_standalone_round(standalone_task_id, ...)` |
 | Update round | `update_round(round_id, ...)` | `update_standalone_round(standalone_round_id, ...)` |
 | Update task | `update_task(task_id, ...)` | `update_standalone_task(standalone_task_id, ...)` |
@@ -64,9 +64,13 @@ If the argument matches the numeric regex, resolve the target task/round from DB
 
 ### Step 2: Deep Analysis (MANDATORY — always runs)
 
-**2a:** Load task via KIND-appropriate MCP tool (`get_current_task` or `get_current_standalone_task`) — get `files_changed`, `requirements`, `context`, `qa`
+**2a:** Load task:
+- **checkpoint KIND** — Read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>.json` (local-first). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_current_task(repo_id)` when state dir is absent and sync fails. Get `files_changed`, `requirements`, `context`, `qa`.
+- **standalone KIND** — MCP `get_current_standalone_task(repo_id)`. (Standalone KIND still uses MCP until a later task.)
 
-**2b:** Load all rounds via MCP `get_rounds(task_id)` (checkpoint KIND) or `get_standalone_rounds(standalone_task_id)` (standalone KIND) — get previous round context, testing-qa output
+**2b:** Load all rounds:
+- **checkpoint KIND** — Read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/*.json` (local-first; break-glass: MCP `get_rounds(task_id)`). Get previous round context, testing-qa output.
+- **standalone KIND** — MCP `get_standalone_rounds(standalone_task_id)`.
 
 **2c:** Identify unapproved files from `task.files_changed` where `user_approved === false`
 
@@ -144,10 +148,12 @@ Based on the analysis + user input, create detailed requirements that:
 
 If the new round requirements change the task direction:
 
-1. Update task context via MCP `update_task(task_id, context: { ... })` / `update_standalone_task(standalone_task_id, context: { ... })` per KIND:
+1. Update task context per KIND:
+   - **checkpoint KIND**: `codebyplan task update --id <task_id> --checkpoint-id <checkpoint_id> --context '<json>'` (CLI write-through: local state file + REST). Break-glass fallback: MCP `update_task(task_id, context: { ... })` when the CLI is unavailable.
+   - **standalone KIND**: MCP `update_standalone_task(standalone_task_id, context: { ... })`. (Standalone KIND still uses MCP until a later task.)
    - Add new decisions to `context.decisions[]`
    - Update `context.discoveries[]` if applicable
-2. If checkpoint-level changes needed (checkpoint KIND only), update checkpoint context via MCP `update_checkpoint`
+2. If checkpoint-level changes needed (checkpoint KIND only): `codebyplan checkpoint update --id <checkpoint_id> --context '<json>'` (CLI write-through). Break-glass fallback: MCP `update_checkpoint`.
 
 ### Step 7: Auto-trigger Round Start
 
@@ -166,14 +172,18 @@ Trigger `/cbp-round-start` with the round requirements as arguments.
 If this command is triggered **directly** (not via `/cbp-todo`) and no context is available in the session:
 
 1. Read `.codebyplan/repo.json` for `repo_id`
-2. Use Kind Detection to determine KIND, then use the appropriate MCP tool to load checkpoint + task
-3. Use MCP `get_rounds(task_id)` / `get_standalone_rounds(standalone_task_id)` per KIND to load round history
+2. Use Kind Detection to determine KIND, then:
+   - **checkpoint KIND**: Read local `.codebyplan/state/` files for checkpoint + task (break-glass: MCP `get_current_task`).
+   - **standalone KIND**: MCP `get_current_standalone_task`.
+3. Load round history:
+   - **checkpoint KIND**: Read `.codebyplan/state/checkpoints/<id>/tasks/<id>/rounds/*.json` (break-glass: MCP `get_rounds(task_id)`).
+   - **standalone KIND**: MCP `get_standalone_rounds(standalone_task_id)`.
 4. Continue from Step 2 (deep analysis handles all context loading)
 
 ## Key Rules
 
 - **Deep analysis is MANDATORY** — always runs, even if arguments provided (for context)
-- **Analysis reads from DB (MCP)**, not conversation history
+- **Analysis reads from local state first**, falling back to MCP only when state files are absent and sync fails
 - **Follow-up rounds get same depth as round 1** — no quick-fix behavior
 - **Never ask to git add** — user file approval (git staging) is reconciled by `/cbp-round-complete`
 - **Update all context locations** — task, checkpoint, and round should all have consistent information
@@ -181,6 +191,8 @@ If this command is triggered **directly** (not via `/cbp-todo`) and no context i
 ## Integration
 
 - **Triggered by**: `/cbp-round-update` (auto, not-clean triage), `/cbp-round-complete` (auto, files left unapproved after completing the round), `/cbp-round-execute` (auto, on hard-fail after retry exhausted), `/cbp-todo` (after /clear), user manually
-- **Reads**: MCP `get_current_task` / `get_current_standalone_task`, `get_rounds` / `get_standalone_rounds` (per KIND), file contents (Read tool)
-- **Writes**: MCP `update_task` / `update_standalone_task` (context), `update_checkpoint` (context, if checkpoint KIND and needed)
+- **Reads (checkpoint KIND)**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/<id>.json`, `checkpoints/<id>/tasks/<id>/rounds/*.json` (local-first; break-glass: MCP `get_current_task` / `get_rounds`), file contents (Read tool)
+- **Reads (standalone KIND)**: MCP `get_current_standalone_task` / `get_standalone_rounds` (standalone KIND still uses MCP until a later task)
+- **Writes (checkpoint KIND)**: `codebyplan task update` (context), `codebyplan checkpoint update` (context, if needed). Break-glass: MCP `update_task` / `update_checkpoint`.
+- **Writes (standalone KIND)**: MCP `update_standalone_task` / (checkpoint via MCP `update_checkpoint` if needed). (Standalone KIND still uses MCP until a later task.)
 - **Triggers**: `/cbp-round-start` (auto)

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

@@ -17,16 +17,18 @@ Inspect the resolved identifier from argument parsing to determine the task kind
 | `{chk}-{task}-{round}` (3-segment, e.g. `141-3-1`) | `checkpoint` |
 | _(empty / free-text)_ | Check `get_current_standalone_task` first; if found → `standalone`. Else → `checkpoint` via `get_current_task`. |
 
-Set `KIND` for the rest of this skill. MCP tool names vary by KIND:
+Set `KIND` for the rest of this skill. Read/write sources vary by KIND:
 
 | Operation | `checkpoint` KIND | `standalone` KIND |
 |-----------|------------------|-------------------|
-| Get task | `get_current_task(repo_id)` | `get_current_standalone_task(repo_id)` |
-| Get rounds | `get_rounds(task_id)` | `get_standalone_rounds(standalone_task_id)` |
-| Add round | `add_round(task_id, ...)` | `add_standalone_round(standalone_task_id, ...)` |
-| Update round | `update_round(round_id, ...)` | `update_standalone_round(standalone_round_id, ...)` |
+| 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)` |
+| 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 |
-| Update task | `update_task(task_id, ...)` | `update_standalone_task(standalone_task_id, ...)` |
+| 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 for this task and will be addressed in a later task.
 
 # Round Start Command
 
@@ -94,17 +96,23 @@ round-start: invalid argument `{value}`. Expected:
 
 ### Step 1: Get Current Task
 
-If Step 0 produced an identifier (`target_task` set): resolve directly per the identifier (bound or standalone) — use KIND-appropriate MCP tools per the Kind Detection table above.
+If Step 0 produced an identifier (`target_task` set): resolve directly per the identifier (bound or standalone) — use KIND-appropriate sources per the Kind Detection table above.
 
-Otherwise: use Kind Detection to determine KIND, then use MCP `get_current_task` (checkpoint KIND) or `get_current_standalone_task` (standalone KIND) with repo_id to find the active task.
+Otherwise: use Kind Detection to determine KIND, then:
+- **checkpoint KIND**: read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>.json` (local-first). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_current_task` when the state dir is absent and sync fails (daemon-dead + CLI-unavailable).
+- **standalone KIND**: MCP `get_current_standalone_task(repo_id)` — standalone tools are NOT migrated this task; standalone KIND still uses MCP until a later task.
 
 If no in-progress task and Step 0 produced no identifier, show error: `No active task. Run /cbp-task-start first.`
 
 ### Step 2: Determine Round Number
 
-If Step 0 produced `target_round`: use that as the round number directly (may target an existing round for resume, or N+1 for a new round — disambiguate by checking MCP `get_rounds` / `get_standalone_rounds` per KIND).
+If Step 0 produced `target_round`: use that as the round number directly (may target an existing round for resume, or N+1 for a new round — disambiguate by reading local round files or MCP per KIND below).
+
+Otherwise:
+- **checkpoint KIND**: list `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/` (local-first). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_rounds` when the state dir is absent and sync fails.
+- **standalone KIND**: MCP `get_standalone_rounds(standalone_task_id)` — standalone still uses MCP.
 
-Otherwise: use MCP `get_rounds` (checkpoint KIND) or `get_standalone_rounds` (standalone KIND) for the task; count existing rounds; next is N+1.
+Count existing rounds; next is N+1.
 
 ### Step 3: Gather Round Requirements
 
@@ -122,7 +130,11 @@ Otherwise: use MCP `get_rounds` (checkpoint KIND) or `get_standalone_rounds` (st
 
 ### Step 4: Create Round in DB
 
-Use MCP `add_round` (checkpoint KIND) or `add_standalone_round` (standalone KIND):
+**checkpoint KIND**: `codebyplan round add --task-id <uuid> --checkpoint-id <uuid> --number <N> --status in_progress --started-at <ISO> --triggered-by <user|claude|auto_loop> [--requirements <text>] [--context <json>]` (CLI write-through: writes local state at `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` + REST). Break-glass fallback: MCP `add_round` when the CLI is unavailable.
+
+**standalone KIND**: MCP `add_standalone_round(standalone_task_id, ...)` — standalone still uses MCP.
+
+Fields to supply:
 - `task_id` (checkpoint) / `standalone_task_id` (standalone): current task ID
 - `number`: next round number
 - `status`: "in_progress"
@@ -138,7 +150,9 @@ Load from checkpoint and task:
 - Task context and requirements
 - Resources from checkpoint and task (documentation links, API docs, guides)
 - Previous round results (files_changed, QA results)
-- For round 2+: load the latest completed round's `context.testing_qa_output` and `context.executor_output` via `get_rounds` / `get_standalone_rounds` per KIND
+- For round 2+: load the latest completed round's `context.testing_qa_output` and `context.executor_output`:
+  - **checkpoint KIND**: read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` (local-first). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_rounds` when the state dir is absent and sync fails.
+  - **standalone KIND**: MCP `get_standalone_rounds(standalone_task_id)` — standalone still uses MCP.
 - Identify unapproved files from task.files_changed (where user_approved === false)
 
 ### Step 6: First Round Analysis (Round 1 only)
@@ -149,7 +163,8 @@ For the first round only:
 2. Identify any ambiguities or gaps
 3. If questions are needed, ask user via AskUserQuestion (max 4 per batch)
 4. If task context changes from Q&A answers:
-   - Update task context via MCP `update_task(task_id, context: {...})` / `update_standalone_task(standalone_task_id, context: {...})` per KIND
+   - **checkpoint KIND**: `codebyplan task update --id <task-id> --checkpoint-id <uuid> --context <json>` (CLI write-through: local state at `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>.json` + REST). Break-glass fallback: MCP `update_task` when the CLI is unavailable.
+   - **standalone KIND**: MCP `update_standalone_task(standalone_task_id, context: {...})` — standalone still uses MCP.
    - Save Q&A decisions as `context.decisions[]`
 
 Skip this step for round 2+ (context already established via `/cbp-round-input`).
@@ -219,7 +234,10 @@ Single-wave plans present the existing flat plan view (no wave table) — backwa
 
 ### Step 9: Auto-trigger Round Execute
 
-Save planner output to round context via MCP `update_round` / `update_standalone_round` per KIND, then trigger `/cbp-round-execute`. The `ask`-tier permission prompt on `/cbp-round-execute` is the user's plan approval (see Step 8).
+Save planner output to round context, then trigger `/cbp-round-execute`. The `ask`-tier permission prompt on `/cbp-round-execute` is the user's plan approval (see Step 8).
+
+- **checkpoint KIND**: `codebyplan round update --id <round-id> --task-id <uuid> --checkpoint-id <uuid> --context <json>` (CLI write-through: local state at `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` + REST). Break-glass fallback: MCP `update_round` when the CLI is unavailable.
+- **standalone KIND**: MCP `update_standalone_round(standalone_round_id, ...)` — standalone still uses MCP.
 
 ```
 Starting execution phase...
@@ -235,8 +253,10 @@ Starting execution phase...
 
 ## Integration
 
-- **Reads**: MCP `get_current_task` / `get_current_standalone_task`, `get_rounds` / `get_standalone_rounds` (per KIND)
-- **Writes**: MCP `add_round` / `add_standalone_round`, `update_round` / `update_standalone_round`, `update_task` / `update_standalone_task` (context only) — per KIND
+- **Reads (checkpoint KIND)**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/<id>.json`, `checkpoints/<id>/tasks/<id>/rounds/<id>.json` (local-first; `npx codebyplan sync` on miss; MCP `get_current_task` / `get_rounds` as break-glass)
+- **Reads (standalone KIND)**: MCP `get_current_standalone_task`, `get_standalone_rounds` — standalone still uses MCP
+- **Writes (checkpoint KIND)**: `codebyplan round add` (Step 4), `codebyplan round update` (Step 9), `codebyplan task update` (Step 6 context only) — break-glass: MCP `add_round` / `update_round` / `update_task`
+- **Writes (standalone KIND)**: MCP `add_standalone_round`, `update_standalone_round`, `update_standalone_task` — standalone still uses MCP
 - **Spawns**: `cbp-task-planner`
 - **Triggers**: `/cbp-round-execute` (auto, on plan approval)
 - **Triggered by**: `/cbp-task-start` (round 1), `/cbp-round-input` (round 2+)

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

@@ -17,13 +17,15 @@ Inspect the resolved identifier from argument parsing to determine the task kind
 | `{chk}-{task}-{round}` (3-segment, e.g. `141-3-1`) | `checkpoint` |
 | _(empty / free-text)_ | Check `get_current_standalone_task` first; if found → `standalone`. Else → `checkpoint` via `get_current_task`. |
 
-Set `KIND` for the rest of this skill. round-update is **read + triage only** — it reads round state and routes; it never completes the round or writes file approvals. MCP read/audit tool names vary by KIND:
+Set `KIND` for the rest of this skill. round-update is **read + triage only** — it reads round state and routes; it never completes the round or writes file approvals. Read/write sources vary by KIND:
 
 | Operation | `checkpoint` KIND | `standalone` KIND |
 |-----------|------------------|-------------------|
-| Get task | `get_current_task(repo_id)` | `get_current_standalone_task(repo_id)` |
-| Get rounds | `get_rounds(task_id)` | `get_standalone_rounds(standalone_task_id)` |
-| Update round (audit only) | `update_round(round_id, ...)` | `update_standalone_round(standalone_round_id, ...)` |
+| 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 (audit only) | `codebyplan round update` (break-glass: `update_round`) | `update_standalone_round(standalone_round_id, ...)` |
+
+> **Note**: The `standalone` KIND column uses MCP tools unchanged — standalone local-first migration is out of scope for this task and will be addressed in a later task.
 
 The completion + file-approval reconcile (`sync-approvals`, `complete_round` / `complete_standalone_round`) now lives in `/cbp-round-complete`.
 
@@ -72,9 +74,9 @@ Given the parse from Step 1:
 
 | Parse | Resolution path |
 |-------|-----------------|
-| `{chk}-{task}-{round}` | MCP `get_checkpoints(repo_id)` → filter `number === {chk}`. MCP `get_tasks(checkpoint_id)` → filter `number === {task}`. MCP `get_rounds(task_id)` → filter `number === {round}`. |
-| `{task}-{round}` | MCP `get_standalone_rounds` via `get_current_standalone_task` or direct task lookup → filter `number === {round}`. |
-| _(empty)_ | Use Kind Detection: checkpoint KIND → MCP `get_current_task(repo_id)` + `get_rounds(task_id)`; standalone KIND → MCP `get_current_standalone_task(repo_id)` + `get_standalone_rounds(standalone_task_id)`. |
+| `{chk}-{task}-{round}` | Read `.codebyplan/state/checkpoints/` to find the checkpoint where `number === {chk}` (local-first; `npx codebyplan sync` on miss; break-glass: MCP `get_checkpoints(repo_id)`). Read `checkpoints/<id>/tasks/<taskId>.json` to find task where `number === {task}` (break-glass: MCP `get_tasks`). Read `checkpoints/<id>/tasks/<id>/rounds/<roundId>.json` to find round where `number === {round}` (break-glass: MCP `get_rounds`). |
+| `{task}-{round}` | MCP `get_standalone_rounds` via `get_current_standalone_task` or direct task lookup → filter `number === {round}`. Standalone still uses MCP. |
+| _(empty)_ | checkpoint KIND → read `.codebyplan/state/checkpoints/<id>/tasks/<id>.json` (local-first; sync on miss; break-glass: MCP `get_current_task` + `get_rounds`); standalone KIND → MCP `get_current_standalone_task(repo_id)` + `get_standalone_rounds(standalone_task_id)` — standalone still uses MCP. |
 
 If no task found: `No active task. Nothing to update.`
 
@@ -97,7 +99,7 @@ Display a one-line triage summary, e.g. `"ROUND-N triage: clean"` or `"ROUND-N t
 
 - **Auto-loop** (`round.context.auto_loop_mode === true`): compute `next_index = (round.context.auto_loop_index ?? 0) + 1`.
   - If `next_index > (round.context.auto_loop_cap ?? 5)`: surface the cap-exhausted prompt via AskUserQuestion (a genuine multi-option user decision — keep it). Options: extend cap, stop loop / drop into round-input, close task as-is. Persist `round.context.auto_loop_cap_exhausted = { user_choice, decided_at }` and route per choice.
-  - Otherwise: persist `round.context.auto_loop_decision = { spawned_next: true, next_index, decided_at }` on the current round via `update_round` / `update_standalone_round` (audit trail), then auto-trigger `/cbp-round-input` with NO prompt. Pass `auto_loop_mode: true`, `auto_loop_index: next_index`, `auto_loop_cap: (prior cap ?? 5)` forward — round-start Step 4 persists them on the new round.
+  - Otherwise: persist `round.context.auto_loop_decision = { spawned_next: true, next_index, decided_at }` on the current round (audit trail) — **checkpoint KIND**: `codebyplan round update --id <round-id> --task-id <uuid> --checkpoint-id <uuid> --context <json>` (break-glass: MCP `update_round`); **standalone KIND**: MCP `update_standalone_round(standalone_round_id, ...)` — standalone still uses MCP. Then auto-trigger `/cbp-round-input` with NO prompt. Pass `auto_loop_mode: true`, `auto_loop_index: next_index`, `auto_loop_cap: (prior cap ?? 5)` forward — round-start Step 4 persists them on the new round.
 - **Manual round**: auto-trigger `/cbp-round-input` directly (no prompt).
 
 ## Key Rules
@@ -111,6 +113,8 @@ Display a one-line triage summary, e.g. `"ROUND-N triage: clean"` or `"ROUND-N t
 ## Integration
 
 - **Triggered by**: `/cbp-round-end` (auto), or user manually
-- **Reads**: MCP `get_current_task` / `get_current_standalone_task`, `get_rounds` / `get_standalone_rounds` (per KIND); round context (`testing_qa_output`, `improve_round_findings`, `round_type`, `files_changed[].claude_approved`)
-- **Writes**: MCP `update_round` / `update_standalone_round` — audit only (`auto_loop_decision` / `auto_loop_cap_exhausted`). No completion, no file-approval writes.
+- **Reads (checkpoint KIND)**: `.codebyplan/state/checkpoints/<id>.json`, `checkpoints/<id>/tasks/<id>.json`, `checkpoints/<id>/tasks/<id>/rounds/<id>.json` (local-first; `npx codebyplan sync` on miss; MCP `get_current_task` / `get_checkpoints` / `get_tasks` / `get_rounds` as break-glass)
+- **Reads (standalone KIND)**: MCP `get_current_standalone_task`, `get_standalone_rounds` — standalone still uses MCP
+- **Writes (checkpoint KIND)**: `codebyplan round update` — audit only (`auto_loop_decision` / `auto_loop_cap_exhausted`; break-glass: MCP `update_round`). No completion, no file-approval writes.
+- **Writes (standalone KIND)**: MCP `update_standalone_round` — audit only — standalone still uses MCP
 - **Triggers**: `/cbp-round-complete` (clean triage — `ask`-tier permission prompt is the user confirmation), `/cbp-round-input` (not-clean triage: outstanding findings, hard-fail, or unapproved Claude checks — fires independent of git staging; also the auto-loop dirty spawn), cap-exhausted prompt routes from Step 3b (any of the three options)

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

@@ -17,17 +17,17 @@ Always write a session log for this session — **even if empty**. `/cbp-session
 
 1. Resolve the current session log:
    - Preferred: use the log ID held in context from `/cbp-session-start`.
-   - Fallback: MCP `get_session_logs` (limit 1, most recent open log for this `repo_id`).
-   - If still none found (e.g. session-start was skipped), create one now with MCP `create_session_log`.
-2. Pull facts from the DB rather than narrating from memory:
-   - Rounds added/completed, tasks advanced/completed during this session
+   - Fallback: read `.codebyplan/state/session/current.json` (local-first). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_session_logs` (limit 1, most recent open log for this `repo_id`) when the state dir is absent and sync fails.
+   - If still none found (e.g. session-start was skipped), create one now with `codebyplan session create-log` (break-glass: MCP `create_session_log`).
+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. Call MCP `get_todos({ repo_id, worktree_id })` and take the queue head `rows[0]` (rows are ordered by `sort_order`; `rows[0]` is the current next-action). The worker stamps `command`, `instructions`, `state`, and the entity ids `checkpoint_id` / `task_id` / `round_id` on every row.
+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:
@@ -46,7 +46,7 @@ Snapshot the current next-action so the next `/cbp-session-start` (Step 4.5) can
 
 Continuing Step 1:
 
-3. Use MCP `update_session_log` to finalize:
+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:
    - `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
@@ -58,12 +58,12 @@ Same rule as `/cbp-session-start` Step 5.7 — only commit files that are **not*
 
 1. `git status --porcelain` — list all modified/untracked files. If empty → skip this step.
 2. Resolve **task-related files** (leave these uncommitted):
-   - MCP `get_current_task(repo_id)` → active task
-   - If active task exists: MCP `get_rounds(task_id)`, filter to rounds with status not in `completed` / `cancelled`
+   - Read `.codebyplan/state/todos.json` (local-first; reuse result from Step 1.3 if already fetched) to identify the active task id. Break-glass fallback: MCP `get_current_task(repo_id)` when the state dir is absent and sync fails.
+   - If active task exists: read `.codebyplan/state/checkpoints/<checkpoint_id>/tasks/<task_id>/rounds/` directory and filter to rounds with status not in `completed` / `cancelled`. Break-glass fallback: MCP `get_rounds(task_id)`.
    - Collect `files[]` from those rounds → `task_files` set
    - If no active task exists, `task_files` is empty
 3. `infra_files = changed_files − task_files`
-4. Re-run `git status --porcelain` immediately before showing the commit-prompt (after Steps 1–1.3 have completed their MCP round-trips). Recompute `infra_files` from the fresh listing — eliminates the race where files appear in the index only after the network round-trips complete.
+4. Re-run `git status --porcelain` immediately before showing the commit-prompt (after Steps 1–1.3 have completed their round-trips). Recompute `infra_files` from the fresh listing — eliminates the race where files appear in the index only after network round-trips complete.
 5. If `infra_files` is empty → skip. Otherwise present once:
 
    ```
@@ -145,9 +145,19 @@ Non-blocking — session end proceeds regardless of outcome.
 
 Non-blocking — if kill fails, warn and continue. Silent when no process found.
 
+### Step 2.5: Stop Watch Daemon
+
+Stop this worktree's Realtime watch daemon, non-blocking and non-fatal:
+
+```bash
+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.
+
 ### Step 3: Update Session State
 
-Use MCP `update_session_state` with action `deactivate`.
+Run `codebyplan session update-state --action deactivate` (CLI write-through: writes `.codebyplan/state/session/state.json` + REST). Break-glass fallback: MCP `update_session_state` with action `deactivate` when the CLI is unavailable. Note: the CLI validates `--action` — only `activate`/`deactivate` are accepted; a missing, valueless, or invalid value exits 1 with a usage message.
 
 ### Step 4: Output
 
@@ -160,8 +170,8 @@ You can close this window.
 ## Integration
 
 - **Triggered by**: user invocation (prompted by `/cbp-todo` when no work remains)
-- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.6 home-branch fast-forward), MCP `get_session_logs` (resolve current log), MCP `get_current_task`, MCP `get_rounds`, MCP `get_todos` (Step 1.3 handoff snapshot — queue head `rows[0]`); `npx codebyplan version-status` (Step 1.7 package-freshness gate)
-- **Writes**: MCP `update_session_log` (with `ended_at` + `handoff` per TASK-2 alias surface; or `create_session_log` fallback), MCP `update_session_state` (deactivate)
+- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.6 home-branch fast-forward); local-first reads (with `npx codebyplan sync` + MCP break-glass): `.codebyplan/state/session/current.json` (Step 1 resolve log), `.codebyplan/state/todos.json` (Step 1.3 handoff snapshot + Step 1.5 active-task lookup), `.codebyplan/state/checkpoints/<id>/tasks/<id>/rounds/` (Step 1.5 task-file resolution); `npx codebyplan version-status` (Step 1.7 package-freshness gate)
+- **Writes**: `codebyplan session update-log --id <id> ...` (Step 1 finalize — CLI write-through to `.codebyplan/state/session/current.json`; break-glass: MCP `update_session_log`), `codebyplan session create-log` (Step 1 fallback when no log exists; break-glass: MCP `create_session_log`), `codebyplan session update-state --action deactivate` (Step 3 — CLI write-through to `.codebyplan/state/session/state.json`; break-glass: MCP `update_session_state`)
 - **Spawns**: none
 - **Triggers**: none at the skill-contract level. Step 1.5 may invoke `/cbp-git-commit` inline on user approval; Step 1.7 may invoke `/cbp-git-commit` on the `newer:true AND guarded:false` update path (committing changed `.claude/` and `.codebyplan/` paths).
 - **Paired with**: `/cbp-session-start`

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

@@ -142,18 +142,22 @@ LSP_NUDGE=$(npx codebyplan lsp --check 2>/dev/null || true)
 
 ### Step 3: Update Session State
 
-Use MCP `update_session_state` with action `activate`. This deactivates all other repos automatically.
+Run `codebyplan session update-state --action activate` (CLI write-through: writes `.codebyplan/state/session/state.json` + REST). This deactivates all other repos automatically. Break-glass fallback: MCP `update_session_state` with action `activate` when the CLI is unavailable. Note: the CLI validates `--action` — only `activate`/`deactivate` are accepted; a missing, valueless, or invalid value exits 1 with a usage message.
+
+Note: Step 0 `health_check` stays MCP unconditionally — it tests MCP connectivity itself and must not be replaced.
 
 ### Step 4: Read Last Session Log
 
-Call MCP `get_session_logs({ repo_id, worktree_id, limit: 1 })` — same inclusive-worktree call shape used by Step 4.5 below so the previous-session display and the handoff probe agree on which row is "most recent for this worktree". Take the first (and only) row.
+Read `.codebyplan/state/session/current.json` (local-first). If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_session_logs({ repo_id, worktree_id, limit: 1 })` when the state dir is absent and sync fails (daemon-dead + CLI-unavailable).
+
+Take the first row — same inclusive-worktree scope as Step 4.5 so the previous-session display and the handoff probe agree on which row is "most recent for this worktree".
 
 - If a previous log exists, hold its title/summary/pending items for the Step 6 output so the user sees where they left off.
 - If none exists (first session ever for this worktree), skip silently.
 
 ### Step 5: Create This Session's Log
 
-Use MCP `create_session_log` to open a new session log for the current session. Create it **even if empty** — this establishes the record for session-end to finalize.
+Run `codebyplan session create-log --started-at <now> --repo-id <repo_id> --worktree-id <WORKTREE_ID>` (CLI write-through: writes `.codebyplan/state/session/current.json` + REST). Create it **even if empty** — this establishes the record for session-end to finalize. Break-glass fallback: MCP `create_session_log` when the CLI is unavailable.
 
 Minimal seed content:
 
@@ -167,7 +171,7 @@ Hold the new log's ID in context so `/cbp-session-end` can update the same recor
 
 Probe the most-recent closed session log for a structured handoff payload (the handoff freshness-gate contract is specified inline in this step) and auto-resume directly into the captured command when fresh. Additive — placed BEFORE the existing `/cbp-todo` auto-trigger; ALL failure paths fall through silently to Step 7.
 
-1. Reuse the row held from Step 4 (same `get_session_logs({ repo_id, worktree_id, limit: 1 })` call shape — no extra MCP round-trip).
+1. Reuse the row held from Step 4 (held from Step 4 in memory — do NOT re-read from disk here; at this point `session/current.json` still holds the previous session row, which Step 5 will overwrite).
 2. **Defensive gates** (any failure → silent fall-through to Step 7):
    - No row returned → fall through.
    - Row missing `closed_at` (orphan / still-open session) → fall through.
@@ -175,12 +179,12 @@ Probe the most-recent closed session log for a structured handoff payload (the h
    - `row.content` exists but parse throws or shape mismatch (`command` field absent OR is an empty string) → fall through.
 3. **Freshness gate** — load the row as `handoff = row.content` (per CHK-111 Migration A column alias). Mark stale when ANY of:
    - `(now - row.closed_at) > freshness_window_hours` (read from `.codebyplan/repo.json`, default 24 hours)
-   - Referenced entity in `handoff.context` has shifted. For each id present, run the matching MCP read and find the row whose `id` matches:
-     - `checkpoint_id` → `get_checkpoints({ repo_id })` → find entry where `entry.id === handoff.context.checkpoint_id`
-     - `task_id` → `get_tasks({ checkpoint_id })` if `handoff.context.checkpoint_id` is present, else `get_tasks({ repo_id, standalone: true })` → find entry where `entry.id === handoff.context.task_id`
-     - `round_id` → `get_rounds({ task_id: handoff.context.task_id })` → find entry where `entry.id === handoff.context.round_id`
+   - Referenced entity in `handoff.context` has shifted. For each id present, read the matching local state file and check `updated_at`:
+     - `checkpoint_id` → read `.codebyplan/state/checkpoints/<checkpoint_id>.json` (local-first; sync + MCP break-glass if missing)
+     - `task_id` → read `.codebyplan/state/checkpoints/<checkpoint_id>/tasks/<task_id>.json` (local-first; sync + MCP break-glass if missing)
+     - `round_id` → read `.codebyplan/state/checkpoints/<checkpoint_id>/tasks/<task_id>/rounds/<round_id>.json` (local-first; sync + MCP break-glass if missing)
        Then compare `entry.updated_at > handoff.captured_at` → stale on any inequality.
-   - Entity lookup fails OR the matching `id` is not present in the returned array → stale (referenced entity gone or moved out of reach).
+   - Local file missing after sync attempt → stale (referenced entity gone or moved out of reach).
    - `handoff.context.checkpoint_id` resolves to a checkpoint whose `worktree_id` is non-null AND (caller `WORKTREE_ID` is `null` OR differs from `checkpoint.worktree_id`) → stale (a fresh handoff for another worktree's work — or for assigned work this caller cannot confirm ownership of — must not auto-resume here). Mirrors the cbp-todo Step 1.5 ownership rule.
 4. **On stale OR any defensive gate hit**: fall through silently to Step 7 (existing `/cbp-todo` trigger).
 5. **On fresh hit**: trigger `handoff.command` directly with `handoff.context` / `handoff.state` in the trigger arguments. The downstream skill self-loads its full context — do NOT duplicate `/cbp-todo` Step 2's context-loading matrix here. Skip Step 5.7, Step 6 output, and Step 7.
@@ -191,12 +195,12 @@ Clean the working tree of leftover infra before the session begins. Only commit
 
 1. `git status --porcelain` — list all modified/untracked files. If empty → skip this step.
 2. Resolve **task-related files** (leave these uncommitted):
-   - MCP `get_current_task(repo_id)` → active task
-   - If active task exists: MCP `get_rounds(task_id)`, filter to rounds with status not in `completed` / `cancelled`
+   - Read `.codebyplan/state/todos.json` (local-first) to identify the active task id. If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_current_task(repo_id)` when the state dir is absent and sync fails.
+   - If active task exists: read `.codebyplan/state/checkpoints/<checkpoint_id>/tasks/<task_id>/rounds/` directory and filter to rounds with status not in `completed` / `cancelled`. Break-glass fallback: MCP `get_rounds(task_id)`.
    - Collect `files[]` from those rounds → `task_files` set
    - If no active task exists, `task_files` is empty
 3. `infra_files = changed_files − task_files`
-4. **Re-run `git status --porcelain` immediately before showing the commit-prompt** (after Steps 0–5 have completed all MCP round-trips). Eliminates the race where prior-session staged files appear in the index only after MCP init's network round-trips complete. Recompute `infra_files` from the fresh listing.
+4. **Re-run `git status --porcelain` immediately before showing the commit-prompt** (after Steps 0–5 have completed all their round-trips). Eliminates the race where prior-session staged files appear in the index only after network round-trips complete. Recompute `infra_files` from the fresh listing.
 5. If `infra_files` is empty → skip. Otherwise present once:
 
    ```
@@ -213,7 +217,7 @@ Non-blocking — session start proceeds either way.
 
 ### Step 5.8: Resolve Ownership
 
-Call MCP `get_checkpoints({ repo_id, status: 'active' })`. Partition results into:
+Call MCP `get_checkpoints({ repo_id, status: 'active' })` (MCP only — deliberate: the active-filter query has no local-mirror equivalent). Partition results into:
 
 - `owned[]` — entries where `checkpoint.worktree_id === WORKTREE_ID`, OR both are `null`
 - `cross_worktree[]` — entries where `checkpoint.worktree_id` is non-null AND differs from `WORKTREE_ID` (includes the case where caller `WORKTREE_ID` is `null` but the target has a non-null `worktree_id`)
@@ -253,8 +257,8 @@ Three-branch gate using `owned_count` and `total_count` from Step 5.8:
 
 - **Triggered by**: user invocation, `/clear` recovery
 - **Resolves**: `npx codebyplan resolve-worktree --json` (worktree id + distress signal; non-tuple-miss distress is non-blocking at session-start)
-- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.4 home-branch fast-forward), MCP `get_session_logs` (worktree-filtered, limit 1 — single call shared by Step 4 and Step 4.5), MCP `health_check` (Step 0 hard gate), MCP `get_current_task`, MCP `get_rounds`, MCP `get_checkpoints` (two calls: `{ repo_id, status: 'active' }` for the Step 5.8 ownership partition; `{ repo_id }` unfiltered for the Step 4.5 freshness probe, which may resolve a non-active checkpoint), MCP `get_tasks` / `get_rounds` for the Step 4.5 freshness probe; `scripts/infra-drift.mjs` + a best-effort `git fetch` (Step 1.5 monorepo drift); `npx codebyplan version-status` (Step 1.6 package-freshness gate); `npx codebyplan lsp --check` (Step 1.7 LSP binary nudge — reads `.codebyplan/lsp.json`, non-blocking). Reads at Step 3 and later (session-state, session logs, checkpoints, tasks/rounds) do NOT fire on a Step 0 MCP hard-fail or the Step 1.6 update-and-halt path
-- **Writes**: MCP `create_session_log` (new, possibly empty), MCP `update_session_state` (activate) — both SKIPPED on a Step 0 MCP hard-fail and on the Step 1.6 update-and-halt path
+- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.4 home-branch fast-forward), MCP `health_check` (Step 0 hard gate — stays MCP unconditionally); local-first reads (with `npx codebyplan sync` + MCP break-glass): `.codebyplan/state/session/current.json` (Step 4 previous log + Step 4.5 handoff probe), `.codebyplan/state/checkpoints/<id>.json` / `tasks/<id>.json` / `rounds/<id>.json` (Step 4.5 freshness probe), `.codebyplan/state/todos.json` (Step 5.7 active-task lookup); MCP `get_checkpoints({ repo_id, status: 'active' })` (Step 5.8 ownership partition — MCP only, no local mirror for active-filter query); `scripts/infra-drift.mjs` + a best-effort `git fetch` (Step 1.5 monorepo drift); `npx codebyplan version-status` (Step 1.6 package-freshness gate); `npx codebyplan lsp --check` (Step 1.7 LSP binary nudge — reads `.codebyplan/lsp.json`, non-blocking). Reads at Step 3 and later do NOT fire on a Step 0 MCP hard-fail or the Step 1.6 update-and-halt path
+- **Writes**: `codebyplan session create-log` (Step 5 — CLI write-through; break-glass: MCP `create_session_log`), `codebyplan session update-state --action activate` (Step 3 — CLI write-through to `.codebyplan/state/session/state.json`; break-glass: MCP `update_session_state`) — both SKIPPED on a Step 0 MCP hard-fail and on the Step 1.6 update-and-halt path
 - **Spawns**: none
 - **Triggers**: `/cbp-git-commit` (conditional, on user approval at Step 5.7 or the Step 1.6 update path), `handoff.command` (on fresh handoff hit at Step 4.5), `/cbp-todo` (auto fall-through when owned_count >= 1 or total_count === 0; STOPS with no trigger when total_count >= 1 AND owned_count === 0; NOT triggered on a Step 0 hard-fail or the Step 1.6 update-and-halt path)
 - **Paired with**: `/cbp-session-end`

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

@@ -21,7 +21,7 @@ Step 1 of `/cbp-checkpoint-end` handles branch promotion to main via `/cbp-ship-
 
 | Source                        | What's read                                                                               |
 | ----------------------------- | ----------------------------------------------------------------------------------------- |
-| MCP `get_current_task`        | Active checkpoint (for context.shipment write-back)                                       |
+| Local state `.codebyplan/state/checkpoints/<id>.json`; on miss `npx codebyplan sync` once; MCP `get_current_task` break-glass | Active checkpoint (for context.shipment write-back) |
 | `.codebyplan/git.json` + `.codebyplan/shipment.json`            | `branch_config`, `shipment` section if present (per `ship-configure`)      |
 | Repo scan                     | Detect surfaces from filesystem (vercel.json, eas.json, package.json publishConfig, etc.) |
 | `checkpoint.context.shipment` | Last shipment record (timestamp, surfaces, results)                                       |
@@ -197,7 +197,7 @@ Verification timeouts are conservative (Vercel: 5min, EAS: 30min, TestFlight pro
 
 ### Step 7 — Persist shipment record
 
-Write to `checkpoint.context.shipment` via MCP `update_checkpoint`:
+Write to `checkpoint.context.shipment` via `codebyplan checkpoint update <id> --context '{"shipment": {...}}'` (CLI write-through); use MCP `update_checkpoint` as documented break-glass when the CLI is unavailable:
 
 ```json
 {
@@ -326,7 +326,7 @@ When present, this overrides scan results. `ship-configure` writes here.
 ## Integration
 
 - **Triggered by**: `/cbp-checkpoint-end` (auto, after branch promotion to main via `/cbp-ship-main`); user direct invocation for re-runs
-- **Reads**: MCP `get_current_task`, `.codebyplan/git.json` + `.codebyplan/shipment.json` (`branch_config` + `shipment`), filesystem scan
-- **Writes**: MCP `update_checkpoint` (context.shipment)
+- **Reads**: Local state `.codebyplan/state/checkpoints/<id>.json`; on miss `npx codebyplan sync` once; MCP `get_current_task` as documented break-glass when the state dir is absent and sync fails. Also reads `.codebyplan/git.json` + `.codebyplan/shipment.json` (`branch_config` + `shipment`), filesystem scan.
+- **Writes**: `codebyplan checkpoint update <id> --context '...'` (CLI write-through) for context.shipment; MCP `update_checkpoint` break-glass.
 - **Calls**: per-surface deploy via reference files (vercel CLI, eas CLI, supabase CLI, npm, vsce, railway CLI, gh release)
 - **Triggers**: returns control to caller — does NOT auto-trigger `/cbp-checkpoint-complete` (that's the caller's job)

package/templates/skills/cbp-ship/reference/surface-supabase.md

@@ -35,8 +35,8 @@ This is **always interactive**. The orchestrator does NOT silently apply migrati
 
 1. **List pending migrations**:
    ```bash
-   PROJECT_REF=$(jq -r '.surfaces.supabase.project_ref' .codebyplan/shipment.json)
-   LAST_VERSION=$(jq -r '.surfaces.supabase.last_shipped_migration_version // ""' .codebyplan/shipment.json)
+   PROJECT_REF=$(jq -r '.shipment.surfaces.supabase.project_ref' .codebyplan/shipment.json)
+   LAST_VERSION=$(jq -r '.shipment.surfaces.supabase.last_shipped_migration_version // ""' .codebyplan/shipment.json)
 
    PENDING=$(ls supabase/migrations/*.sql | sort)
    if [ -n "$LAST_VERSION" ]; then
@@ -116,7 +116,7 @@ This is **always interactive**. The orchestrator does NOT silently apply migrati
 7. **Update the last-shipped marker**:
    ```bash
    LAST_APPLIED=$(echo "$PENDING" | tail -1 | xargs basename)
-   jq --arg v "$LAST_APPLIED" '.surfaces.supabase.last_shipped_migration_version = $v' .codebyplan/shipment.json > .codebyplan/shipment.json.tmp
+   jq --arg v "$LAST_APPLIED" '.shipment.surfaces.supabase.last_shipped_migration_version = $v' .codebyplan/shipment.json > .codebyplan/shipment.json.tmp
    mv .codebyplan/shipment.json.tmp .codebyplan/shipment.json
    ```
 

package/templates/skills/cbp-ship-configure/SKILL.md

@@ -126,7 +126,7 @@ The skill's job is to verify these credentials EXIST and are valid; never to sto
 Run the verification step from the surface reference. For Vercel, this is:
 
 ```bash
-vercel inspect "$(jq -r '.surfaces."vercel-web".project_id' .codebyplan/shipment.json)" 2>&1 | head -20
+vercel inspect "$(jq -r '.shipment.surfaces."vercel-web".project_id' .codebyplan/shipment.json)" 2>&1 | head -20
 ```
 
 If verification passes, mark the surface as configured. If it fails, surface the error and offer to retry the failing step.

package/templates/skills/cbp-ship-configure/reference/railway-backend.md

@@ -161,7 +161,7 @@ railway domain
 Verify:
 
 ```bash
-PROJECT_ID=$(jq -r '.surfaces."railway-backend".project_id' .codebyplan/shipment.json)
+PROJECT_ID=$(jq -r '.shipment.surfaces."railway-backend".project_id' .codebyplan/shipment.json)
 railway status --json | jq
 # Expect: project + service info matching saved IDs
 ```
@@ -171,7 +171,7 @@ Test deploy:
 ```bash
 railway up --detach
 # Wait, then verify URL responds
-URL=$(jq -r '.surfaces."railway-backend".url' .codebyplan/shipment.json)
+URL=$(jq -r '.shipment.surfaces."railway-backend".url' .codebyplan/shipment.json)
 curl -sI "$URL/health" | head -1
 ```
 

package/templates/skills/cbp-ship-configure/reference/vercel.md

@@ -98,7 +98,7 @@ Write `.codebyplan/shipment.json`:
 Verify:
 
 ```bash
-PROJECT_ID=$(jq -r '.surfaces."vercel-web".project_id' .codebyplan/shipment.json)
+PROJECT_ID=$(jq -r '.shipment.surfaces."vercel-web".project_id' .codebyplan/shipment.json)
 vercel inspect "$PROJECT_ID" --json | jq -r '.name, .latestDeployments[0].readyState'
 ```
 

package/templates/skills/cbp-ship-main/SKILL.md

@@ -13,7 +13,7 @@ Compose a PR body from checkpoint context, then delegate all git/gh mechanics to
 
 ### Step 1: Read Checkpoint Context
 
-Use MCP `get_current_task` (repo_id) to get the active checkpoint. Collect `checkpoint.title`, completed task titles (`get_tasks(checkpoint_id)` filtered to `status === 'completed'`), and key decisions from `checkpoint.context.decisions[]`.
+Read local state `.codebyplan/state/checkpoints/<id>.json` to get the active checkpoint; on miss run `npx codebyplan sync` once and re-read. Use MCP `get_current_task` as documented break-glass when the state dir is absent and sync fails. Collect `checkpoint.title`, completed task titles (from `.codebyplan/state/checkpoints/<id>/tasks/*.json` filtered to `status === 'completed'`; MCP `get_tasks` break-glass), and key decisions from `checkpoint.context.decisions[]`.
 
 ### Step 2: Compose PR Body
 
@@ -98,4 +98,4 @@ If `branch_deleted === true`, run a conditional Supabase preview-branch teardown
 
 - **Called by**: `/cbp-checkpoint-end`
 - **Delegates to**: `codebyplan ship` CLI
-- **Reads**: MCP `get_current_task`, `get_tasks`
+- **Reads**: Local state `.codebyplan/state/checkpoints/<id>.json` + `.../tasks/<id>.json`; on miss `npx codebyplan sync` once; MCP `get_current_task` / `get_tasks` as documented break-glass when the state dir is absent and sync fails.

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

@@ -169,12 +169,13 @@ Parse the JSON output and store: `pr_url`, `merge_commit`, `branch_deleted`, `fe
 When `branch_deleted === true` in the ship JSON:
 
 - Read `FEAT_BRANCH` from the `feat_branch` field in the ship JSON — NOT from `git branch --show-current`. By the time Step 7.3 runs, `codebyplan ship` has already checked out the base branch, so the live branch is the base, not the feat branch.
-- Call `mcp__supabase__list_branches` with `project_id: rrvtrumtkhrsbhcyrwvf`.
+- Resolve the parent project ref: read `.codebyplan/shipment.json` `.shipment.surfaces.supabase.project_ref`; if absent or empty, read the first line of `supabase/.temp/project-ref`. Use that resolved ref as the `project_id`.
+- Call `mcp__supabase__list_branches` with the resolved `project_id`.
 - Scan the returned list for an entry whose `name` exactly equals `FEAT_BRANCH`.
 - If found: call `mcp__supabase__delete_branch` with its `branch_id`. Report the outcome.
 - If not found: no-op silently — the GitHub integration may have already removed the preview branch on PR close; not-found is success, NOT an error.
 - If the `list_branches` call itself fails (network, auth, or non-success response): emit a non-blocking warning that the Supabase preview branch for `FEAT_BRANCH` may still exist and should be verified in the dashboard. Never treat an API failure as a not-found success.
-- Never delete the parent project `rrvtrumtkhrsbhcyrwvf` itself or any persistent/production branch.
+- Never delete the branch where `is_default` is true in the `list_branches` response (the production/parent project branch) or any other persistent/long-lived branch.
 
 ### Step 7.5: Complete Standalone Task