codebyplan 1.5.1 → 1.9.0

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

@@ -0,0 +1,163 @@
+---
+scope: org-shared
+name: cbp-round-update
+description: Check file approvals, complete round, and route to next step
+argument-hint: [chk-task-round | task-round]
+triggers: [cbp-round-input, cbp-task-check]
+effort: low
+---
+
+# Round Update Command
+
+Checks file approval status, completes the round, and routes to next step. NEVER asks the user to git add or stage anything — it only reads current state.
+
+## HARD GATE — Every Step Must Execute
+
+Step 2 (sync-approvals CLI) MUST exit 0. If it fails, do NOT proceed to Step 3. Before completing the round, verify:
+
+- [ ] `codebyplan round sync-approvals` exited 0
+
+If this is false: DO NOT proceed to Step 3.
+
+## Instructions
+
+### Step 1: Parse `$ARGUMENTS`
+
+Parse the argument using the canonical chk-task-round notation (see `.claude/rules/notation-consistency.md`):
+
+| Shape | Regex | Resolves to |
+|-------|-------|-------------|
+| `{chk}-{task}-{round}` (e.g. `108-1-2`) | `^[0-9]+-[0-9]+-[0-9]+$` | Checkpoint-bound: CHK-{chk} TASK-{task} ROUND-{round} |
+| `{task}-{round}` (e.g. `45-2`) | `^[0-9]+-[0-9]+$` | Standalone: standalone TASK-{task} ROUND-{round} |
+| _(empty)_ | — | Use MCP `get_current_task` / `get_rounds` to find the active task and latest round |
+
+Anything else is malformed — surface this error and stop:
+
+```
+round-update: invalid argument `{value}`. Expected:
+  108-1-2  → CHK-108 TASK-1 ROUND-2 (checkpoint-bound)
+  45-2     → standalone TASK-45 ROUND-2
+  (empty)  → active task and latest round
+```
+
+Error cases: `abc`, `108-`, `-1`, anything with whitespace or non-numeric characters. Note that `108-1` is **valid** here — it resolves to standalone TASK-108 ROUND-1 per the 2-segment task-round form. To target a checkpoint-bound round, use the 3-segment form `108-1-2`.
+
+#### Worked examples
+
+- `round-update 108-1-2` → CHK-108 TASK-1 ROUND-2
+- `round-update 45-2` → standalone TASK-45 ROUND-2
+- `round-update` (no arg) → active task and latest in-progress round via `get_current_task` + `get_rounds`
+- `round-update abc` → error: malformed
+
+### Step 1.5: Get Current Task and Round
+
+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_tasks(repo_id, standalone: true)` → filter `number === {task}`. MCP `get_rounds(task_id)` → filter `number === {round}`. |
+| _(empty)_ | MCP `get_current_task(repo_id)` to find active task. MCP `get_rounds(task_id)` to find latest round (in-progress or completed). |
+
+If no task found: `No active task. Nothing to update.`
+
+### Step 2: Sync git diff + approvals via CLI
+
+Run:
+
+```
+npx codebyplan round sync-approvals --round-id <round_id> --task-id <task_id>
+```
+
+The CLI auto-resolves the worktree id, parses `git status --short`, merges drift + staging + web-UI flag, and writes both round and task.
+
+Read the stdout JSON: `{ added, stale_marked, reactivated, total_files }`.
+
+If the command exits non-zero, surface the stderr and STOP. Do NOT proceed to Step 3.
+
+### Step 3: Complete Round
+
+Calculate duration from `started_at` to now in minutes.
+Use MCP `complete_round(round_id, duration_minutes)`.
+
+### Step 4: Auto-Loop Decision
+
+Read the latest round's `improve_round_findings[]` and `testing_qa_output.totals.hard_fail`. If EITHER is non-clean (findings non-empty OR `hard_fail === true`), the auto-loop must spawn the next round automatically.
+
+Procedure:
+
+1. Compute `next_index = (round.context.auto_loop_index ?? 0) + 1`.
+2. **If `next_index > (round.context.auto_loop_cap ?? 5)`**: surface the cap-exhausted prompt via AskUserQuestion (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.
+3. **Otherwise**: persist `round.context.auto_loop_decision = { spawned_next: true, next_index, decided_at }` on the CURRENT round via `update_round` (audit trail), then auto-trigger `/cbp-round-input` with NO AskUserQuestion. 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.
+
+If BOTH signals are clean, fall through to Step 5 (exit routing).
+
+### Step 5: Exit Routing
+
+**5a: Count files** — Display: `"Files: X total, Y approved, Z pending"`
+
+**5b: Route with four branches** (Step 4 already handled the dirty-loop case; Step 5 is the clean-exit path).
+
+**Branch D — IF `round.context.round_type === 'survey'` (checked FIRST):**
+
+Survey rounds produce no file diff; A/B/C predicates assume `files_changed[]` non-empty. Survey routing is decided by `improve_round_findings[]` instead:
+
+- `improve_round_findings[]` non-empty → auto-trigger `/cbp-round-input`
+- `improve_round_findings[]` empty → auto-trigger `/cbp-task-check`
+
+Output: `"## Round [N] Complete — Survey Round"` with duration, files=0, findings count, routing message. Skip Branches A/B/C.
+
+**Branch A — ELSE IF all files have `user_approved: true`:**
+
+```
+## Round [N] Complete - All Files Approved
+
+**Duration**: [N] minutes
+**Files**: [X] total, [X] approved, 0 pending
+```
+
+Surface AskUserQuestion (clean-exit user-gate):
+
+- **(a) close & complete round** → auto-trigger `/cbp-task-check`
+- **(b) start new round** → auto-trigger `/cbp-round-input`
+
+Persist `round.context.auto_loop_exit = { staged_count, unstaged_count, route, decided_at }`.
+
+**Branch B — ELSE IF unapproved files exist AND every unapproved file has `claude_approved: true` AND `testing_qa_output.totals.hard_fail: false` AND no `improve_round_findings[]`:**
+
+The clean-but-unstaged staging-gate case. Mode-dependent:
+
+- **Auto-loop exit** (the completed round had `auto_loop_mode === true` on its context AND Step 4 fell through here with BOTH signals clean): surface the Branch A clean-exit user-gate — do NOT auto-trigger `/cbp-round-input`. Branch B's entry condition already requires `no improve_round_findings[]`, so the auto-loop's verbatim-from-findings procedure has no input to formulate requirements from; auto-triggering round-input would loop on an empty input. Persist `round.context.auto_loop_exit.degenerate_empty_findings: true` (degenerate sub-case: no findings to feed round-input, so surface the clean-exit user-gate above instead of auto-triggering).
+- **Manual round**: emit staging-gate prompt and STOP. User stages files (never-git-add rule) and re-invokes; command then falls into Branch A.
+
+Manual-mode prompt:
+
+```
+## Round [N] Complete — Files Pending Staging
+
+**Files**: [X] total, [Y] approved, [Z] pending
+
+### Pending (passed all checks; not yet staged):
+- [path]
+
+Stage them (`git add <path>`) and re-run `/cbp-round-update` to proceed.
+Waiting for user to stage files.
+```
+
+**Branch C — ELSE (unapproved AND outstanding findings or `claude_approved: false`):**
+
+Unreachable in the auto-loop path — Step 4 catches it first. Retained for MANUAL invocation. Output `## Round [N] Complete - [Z] Files Pending` with file counts and list of unapproved paths; auto-trigger `/cbp-round-input`.
+
+## Key Rules
+
+- **Step 2 (CLI) must exit 0** — if it fails, STOP. The merge semantics are enforced by the CLI.
+- **Step 4 owns the dirty-loop case**; Step 5 owns the clean-exit case. Step 5 Branch C is for manual invocation only.
+- **NEVER ask user to git add files** — only reads staging status. **NEVER stage files** — Claude does not touch git staging area.
+- Auto-triggered by `/cbp-round-end`, or run manually by user.
+
+## Integration
+
+- **Triggered by**: `/cbp-round-end` (auto), or user manually
+- **Reads**: MCP `get_current_task`, `get_rounds`; delegates git+approval sync to `npx codebyplan round sync-approvals`
+- **Writes**: MCP `update_round` (auto_loop_decision / auto_loop_exit / auto_loop_cap_exhausted), `complete_round`; round+task files_changed written by CLI
+- **Triggers**: `/cbp-round-input` (Step 4 dirty-loop spawn; Branch A 'b' choice; Branch B auto-loop-exit; Branch C manual), `/cbp-task-check` (Branch A 'a' choice; Branch D survey-clean), staging-gate stop (Branch B manual mode), cap-exhausted prompt routes from Step 4 (any of the three options)

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

@@ -0,0 +1,187 @@
+---
+scope: org-shared
+name: cbp-session-end
+description: End a development session
+effort: xhigh
+---
+
+# Session End Command
+
+End the current session. Commits only non-task files — files tied to an unfinished task stay uncommitted so the user finishes them on their terms.
+
+## Instructions
+
+### Step 1: Finalize Session Log
+
+Always write a session log for this session — **even if empty**. `/cbp-session-start` opens the log; session-end finalizes it.
+
+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
+   - 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. Per `.claude/rules/session-resume.md` write-path contract.
+
+1. Call MCP `get_next_action({ repo_id, worktree_id })`.
+2. If the returned `command` is non-empty (active work in flight):
+   ```yaml
+   handoff:
+     command: <result.command> # e.g. "/cbp-round-update"
+     instructions: <result.instructions> # human-readable trigger reason
+     state: <result.state> # workflow state label
+     context: <result.context> # entity ids (checkpoint_id / task_id / round_id) used by freshness probe
+     captured_at: <ISO now> # for entity-drift freshness comparison
+     captured_session_log_id: <current session log id>
+   ```
+3. If `command` is empty / idle / queue-empty: 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. Use MCP `update_session_log` to finalize:
+   - `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
+
+### Step 1.5: Commit Non-Task Files
+
+Same rule as `/cbp-session-start` Step 5.7 — only commit files that are **not** part of an unfinished task.
+
+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`
+   - 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. If `infra_files` is empty → skip. Otherwise present once:
+
+   ```
+   Commit these non-task files before ending session?
+   [list of infra_files]
+
+   Reply: yes | no | select
+   ```
+
+5. On `yes`: `git add` the listed files, then trigger `/cbp-git-commit`.
+   On `no`: skip. On `select`: ask which subset.
+
+Non-blocking — session end proceeds either way.
+
+### Step 1.7: Auto-Update CodeByPlan Assets
+
+Run the latest published CLIs to pull any asset or config changes. Sub-block A runs first, then Sub-block B. A failure in A does **not** skip B — each sub-block has its own retry-and-warn lane.
+
+**a) `codebyplan claude` (asset subcommand group)**
+
+Run the latest published CLI's asset-update verb to pull any skill / agent / hook changes:
+
+```
+npx codebyplan@latest claude update
+```
+
+Always run — do not skip, even when the current repo is the canonical-owner monorepo source.
+
+The command may pause for interactive prompts when:
+
+- a tracked file has been hand-edited locally (overwrite / skip / diff)
+- a new file is being shipped for the first time (opt-in / skip)
+- a file has been removed from the package (remove / keep)
+
+Respond to each prompt in the terminal as it appears. The commit prompt below runs only after all per-file prompts are resolved.
+
+Failure handling:
+
+- On non-zero exit: wait ~5 s, retry once.
+- If retry also fails: print a warning and continue — this step is non-blocking.
+
+After the command exits (success):
+
+1. Run `git status --porcelain -- .claude/` to detect any file changes.
+2. If non-empty, present once (same pattern as Step 1.5):
+
+   ```
+   .claude/ was updated. Commit these changes?
+   [list of changed paths under .claude/]
+
+   Reply: yes | no | select
+   ```
+
+   On `yes`: `git add` the listed paths only (not the whole `.claude/` directory), then trigger `/cbp-git-commit`.
+   On `no`: skip. On `select`: ask which subset.
+
+3. Print the final stdout line from the update command as a one-line session summary (e.g. `codebyplan claude update: 47 files tracked.`). Silent when the command produces no stdout.
+
+Non-blocking — session end proceeds regardless of outcome.
+
+**b) `codebyplan` (project CLI)**
+
+Fetch the latest published version of the project CLI. The `codebyplan` CLI has no `update` verb (subcommands are `setup`, `sync`, `eslint`); the freshness idiom is to invoke a fast read-only flag with `@latest` so npx fetches and caches the newest published version:
+
+```
+npx codebyplan@latest --version
+```
+
+Do **not** run `sync`, `setup`, or any other state-changing subcommand — this step updates the cached binary only.
+
+Failure handling:
+
+- On non-zero exit: wait ~5 s, retry once.
+- If retry also fails: print a warning and continue — this step is non-blocking.
+
+After the command exits (success):
+
+1. Run `git status --porcelain -- .codebyplan/` to detect any file changes.
+2. If non-empty, present once (same pattern as Step 1.5):
+
+   ```
+   .codebyplan/ was updated. Commit these changes?
+   [list of changed paths under .codebyplan/]
+
+   Reply: yes | no | select
+   ```
+
+   On `yes`: `git add` the listed paths only, then trigger `/cbp-git-commit`.
+   On `no`: skip. On `select`: ask which subset.
+
+3. Print the command's stdout (the version line) as a one-line session summary (e.g. `codebyplan 1.4.2`). Silent when the command produces no stdout.
+
+Non-blocking — session end proceeds regardless of outcome.
+
+### Step 2: Auto-Stop Servers
+
+**Skip if `server_type` is `"none"`.**
+
+1. Get `server_port` from `.codebyplan/server.json` context
+2. Check for running process: `lsof -ti:{PORT} 2>/dev/null`
+3. If process found, kill: `lsof -ti:{PORT} | xargs kill -9 2>/dev/null || true`
+
+Non-blocking — if kill fails, warn and continue. Silent when no process found.
+
+### Step 3: Update Session State
+
+Use MCP `update_session_state` with action `deactivate`.
+
+### Step 4: Output
+
+```
+Session ended. Log finalized.
+
+You can close this window.
+```
+
+## Integration
+
+- **Triggered by**: user invocation (prompted by `/cbp-todo` when no work remains)
+- **Reads**: `.codebyplan/repo.json`, MCP `get_session_logs` (resolve current log), MCP `get_current_task`, MCP `get_rounds`, MCP `get_next_action` (Step 1.3 handoff snapshot)
+- **Writes**: MCP `update_session_log` (with `ended_at` + `handoff` per TASK-2 alias surface; or `create_session_log` fallback), MCP `update_session_state` (deactivate)
+- **Spawns**: none
+- **Triggers**: none at the skill-contract level. Steps 1.5 and 1.7 may invoke `/cbp-git-commit` inline on user approval.
+- **Paired with**: `/cbp-session-start`
+- **Pairs with**: `.claude/rules/session-resume.md` (handoff payload shape + write-path contract)

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

@@ -0,0 +1,155 @@
+---
+scope: org-shared
+name: cbp-session-start
+description: Start a development session
+triggers: [cbp-todo]
+effort: low
+---
+
+# Session Start Command
+
+Activate the session, open a fresh session log, and surface the previous log's pending items so the user can pick up where they left off.
+
+## Instructions
+
+Do Steps 0–5 and Step 4.5 silently (no intermediate output). Step 5.7 may surface an approval gate. Produce ONE output block at Step 6, then auto-trigger `/cbp-todo`.
+
+### Step 0: MCP Health Check
+
+Call MCP `health_check` tool.
+
+- **If succeeds**: Continue silently
+- **If fails**: Show warning:
+
+  ```
+  ⚠ MCP connection failed. Check:
+  1. Network connectivity
+  2. API key validity (CODEBYPLAN_API_KEY env var)
+  3. codebyplan.com availability
+
+  Session continues but MCP-dependent features will be unavailable.
+  ```
+
+  Continue to Step 1 (non-blocking).
+
+### Step 1: Load Config
+
+Read per-concern config files from the project root. Single load point for the session:
+
+- `repo_id` (UUID) — from `.codebyplan/repo.json`, required for all MCP operations
+- `server_port`, `server_type`, `auto_push_enabled` — from `.codebyplan/server.json`
+- `git_branch` — from `.codebyplan/git.json`
+
+Resolve `worktree_id` at runtime (CHK-108: never read from `.codebyplan/repo.json`):
+
+```bash
+WORKTREE_ID=$(npx codebyplan resolve-worktree 2>/dev/null)
+```
+
+Pass `WORKTREE_ID` to MCP tools that support it. Empty output means the (device, path, branch) tuple is unregistered — see fallback note below.
+
+**If `worktree_id` resolves to empty** (the (device, path, branch) tuple does not match any registered worktree row): the session continues, but downstream MCP calls treat this caller as untagged — every hard-lock pre-guard sees a NULL `caller_worktree_id` and may reject mutations on assigned rows. Surface a one-line note in the Step 6 output instructing the user to run `npx codebyplan setup` from this directory to register the worktree.
+
+### Step 2: Check Dev Server
+
+**Skip if `server_type` is `"none"`.**
+
+1. Get `server_port` from `.codebyplan/server.json`
+2. Check if running: `lsof -ti:{PORT} 2>/dev/null`
+3. If running, verify health: `curl -s -o /dev/null -w "%{http_code}" http://localhost:{PORT}/ --max-time 2`
+4. If NOT running, note in output that user should start via desktop app
+
+### Step 3: Update Session State
+
+Use MCP `update_session_state` with action `activate`. This deactivates all other repos automatically.
+
+### 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.
+
+- 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.
+
+Minimal seed content:
+
+- `started_at`: now
+- `repo_id` from config; `worktree_id` from `WORKTREE_ID` resolved in Step 1
+- `summary`: empty (session-end fills this in)
+
+Hold the new log's ID in context so `/cbp-session-end` can update the same record.
+
+### Step 4.5: Handoff Auto-Resume Probe
+
+Probe the most-recent closed session log for a structured handoff payload (per `.claude/rules/session-resume.md`) 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).
+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.
+   - `row.content` is `null` → no handoff captured at end-of-session → fall through.
+   - `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`
+       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).
+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.
+
+### Step 5.7: Commit Non-Task Files
+
+Clean the working tree of leftover infra before the session begins. Only commit files that are **not** part of an unfinished task.
+
+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`
+   - 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.
+5. If `infra_files` is empty → skip. Otherwise present once:
+
+   ```
+   Commit these non-task files before starting session?
+   [list of infra_files]
+
+   Reply: yes | no | select
+   ```
+
+6. On `yes`: `git add` the listed files, then trigger `/cbp-git-commit` (it handles conventional message + commit).
+   On `no`: skip. On `select`: ask which subset.
+
+Non-blocking — session start proceeds either way.
+
+### Step 6: Output
+
+```
+Session active | Worktree: [worktree_id or "main"]
+
+Previous session: [title or "none"]
+  Pending: [pending items from previous log, or "—"]
+
+[⚠ Dev server not running — start via desktop app — only if applicable]
+```
+
+### Step 7: Auto-trigger Todo
+
+Trigger `/cbp-todo` to determine what to work on.
+
+## Integration
+
+- **Triggered by**: user invocation, `/clear` recovery
+- **Reads**: `.codebyplan/repo.json`, MCP `get_session_logs` (worktree-filtered, limit 1 — single call shared by Step 4 and Step 4.5), MCP `health_check`, MCP `get_current_task`, MCP `get_rounds`, MCP `get_checkpoints` / `get_tasks` / `get_rounds` for freshness probe (Step 4.5)
+- **Writes**: MCP `create_session_log` (new, possibly empty), MCP `update_session_state` (activate)
+- **Spawns**: none
+- **Triggers**: `/cbp-git-commit` (conditional, on user approval), `handoff.command` (on fresh handoff hit at Step 4.5), `/cbp-todo` (auto fall-through)
+- **Paired with**: `/cbp-session-end`
+- **Pairs with**: `.claude/rules/session-resume.md` (handoff payload shape + freshness gate contract)