codebyplan 1.13.44 → 1.13.45

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

@@ -56,15 +56,12 @@ Continuing Step 1:
 
 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):
-   - 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 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:
+1. Resolve the active task's round files (local-first):
+   - Read `.codebyplan/state/todos.json` (local-first; reuse the Step 1.3 result 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/` and filter to rounds with status not in `completed` / `cancelled`; collect their `files[]` → `task_files` set. Break-glass fallback: MCP `get_rounds(task_id)`.
+   - If no active task exists, `task_files` is empty.
+2. Run `codebyplan session infra-files --json --task-files "<csv>"` where `<csv>` is the comma-separated task files from step 1. Parse the JSON response (`{ infra_files: string[], task_files: string[], note?: string }`). The CLI re-runs `git status --porcelain` internally and applies the set-math deterministically — the race-safe recompute, reading the index after Steps 1–1.3 round-trips complete.
+3. If `infra_files` is empty → skip. Otherwise present once:
 
    ```
    Commit these non-task files before ending session?
@@ -73,7 +70,7 @@ Same rule as `/cbp-session-start` Step 5.7 — only commit files that are **not*
    Reply: yes | no | select
    ```
 
-6. On `yes`: `git add` the listed files, then trigger `/cbp-git-commit`.
+4. 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.
@@ -84,22 +81,11 @@ Keep this worktree's **home branch** rooted at the freshest production tip — n
 
 Runs after Step 1.5 so any infra commits land first, and before Step 1.7 so the freshness gate's asset update operates on the freshest tree.
 
-Resolve the production branch: read `.codebyplan/git.json` and take `branch_config.production` (fall back to `main` if the file or field is absent). Call this `$PRODUCTION`. Then compare the current branch against the worktree's folder name:
+Run `codebyplan session home-ff` and parse the JSON output (`{ result: 'skipped'|'warn'|'fast_forwarded', reason?, warn? }`):
 
-```bash
-FOLDER="$(basename "$(git rev-parse --show-toplevel)")"
-CURRENT="$(git rev-parse --abbrev-ref HEAD)"
-```
-
-- **`$CURRENT` != `$FOLDER`** (a `feat/*` or any non-home branch): skip silently — no fetch, no output.
-- **`$CURRENT` == `$FOLDER`** (home branch): fast-forward to `origin/$PRODUCTION`, warning once per failure and continuing:
-
-  ```bash
-  git fetch origin "$PRODUCTION" 2>/dev/null \
-    || echo "⚠ home-branch ff: fetch failed — staying on local $CURRENT"
-  git merge --ff-only "origin/$PRODUCTION" 2>/dev/null \
-    || echo "⚠ home-branch ff: $CURRENT not fast-forwardable (ahead/diverged) — left untouched"
-  ```
+- **`result === 'skipped'`** (non-home branch or production mismatch): proceed silently.
+- **`result === 'warn'`** (fast-forward attempt failed): surface the `warn` field as one line, then proceed silently.
+- **`result === 'fast_forwarded'`** (home branch updated): proceed silently.
 
 Never rebase, reset, force-push, or stash. A non-fast-forwardable home branch is a signal to reconcile manually, not to overwrite.
 
@@ -107,31 +93,25 @@ Never rebase, reset, force-push, or stash. A non-fast-forwardable home branch is
 
 Check whether a newer `codebyplan` is published and safe to auto-install on this worktree's current branch, then run the local install + asset update. Runs after the Step 1.6 home-branch fast-forward (so any update lands on the freshest tree) and before Step 2. Fully non-blocking — the guard and skip branches proceed silently; any failure in the install/update commands warns once and continues to Step 2. session-end never halts.
 
-```bash
-VERSION_JSON=$(npx codebyplan version-status 2>/dev/null)
-```
-
-Parse `$VERSION_JSON` as JSON and branch on the result:
+Run `codebyplan session freshness-gate` (WITHOUT `--halt-on-update`; session-end is continue-only) and parse the JSON output (`{ result: 'skipped'|'guarded'|'up_to_date'|'updated'|'error', ... }`):
 
-- **Probe failed / unparseable** — the command errored, produced no output, or the output cannot be parsed as JSON carrying the required keys (`newer`, `guarded`, `installCommand`). This includes an installed `codebyplan` too old to have the `version-status` subcommand (which prints `Unknown command`). → **FAIL-SAFE SKIP**: proceed silently to Step 2. A best-effort freshness probe must never disrupt session-end.
-- **`guarded: true`** (protected/main branch OR the canonical `codebyplan` source monorepo — any `guardReason`) → skip silently, proceed to Step 2. Gate on the `guarded` boolean only; never branch on the specific `guardReason` string. This is the guard that prevents clobbering the canonical monorepo's ahead-of-published `.claude/` and blocks any update or commit on a protected branch.
-- **`newer: false`** (already up to date) → skip silently, proceed to Step 2.
-- **`newer: true` AND `guarded: false`** → run the update path:
-  1. Run the JSON's `installCommand` (e.g. `pnpm add codebyplan@latest`) to LOCALLY install `codebyplan@latest` via the repo's package manager. Never a global `-g` install.
-  2. Run `npx codebyplan claude update` to refresh the worktree's `.claude/` assets on the current branch. If `installCommand` (step 1) or this command exits non-zero, warn once and skip to Step 2 — this path is non-blocking.
-  3. Detect changes across BOTH asset directories in one pass: `git status --porcelain -- .claude/ .codebyplan/`. If non-empty, present a single combined offer (same pattern as Step 1.5):
+- **Probe failed** — the command errored or output cannot be parsed as JSON. → **FAIL-SAFE SKIP**: proceed silently to Step 2. A best-effort freshness probe must never disrupt session-end.
+- **`result === 'skipped'` / `'guarded'` / `'up_to_date'`** → skip silently, proceed to Step 2. Gate on the `result` field only. This guard prevents clobbering the canonical monorepo's ahead-of-published `.claude/` and blocks any update or commit on a protected branch.
+- **`result === 'error'`** → fail-safe skip, proceed to Step 2.
+- **`result === 'updated'`** → the CLI already ran the install + `npx codebyplan claude update`. Parse the JSON response:
+  - If `changed_files[]` is present and non-empty, present a single combined offer (same pattern as Step 1.5):
 
-     ```
-     codebyplan updated. Commit these changes before ending the session?
-     [list of changed paths under .claude/ and .codebyplan/]
+    ```
+    codebyplan updated. Commit these changes before ending the session?
+    [list of changed paths under .claude/ and .codebyplan/]
 
-     Reply: yes | no | select
-     ```
+    Reply: yes | no | select
+    ```
 
-     On `yes`: `git add` the listed paths only (not the whole directories), then trigger `/cbp-git-commit`. On `no`: skip. On `select`: ask which subset.
-  4. Continue to Step 2 — session-end does NOT halt. The update lands in the current worktree on its current branch; main/protected branches and the canonical source repo are already excluded by the `guarded` check above.
+    On `yes`: `git add` the listed paths only (not the whole directories), then trigger `/cbp-git-commit`. On `no`: skip. On `select`: ask which subset.
+  - Continue to Step 2 — session-end does NOT halt. The update lands in the current worktree on its current branch; main/protected branches and the canonical source repo are already excluded by the `result !== 'guarded'` check above.
 
-**Home branches are intentionally not guarded.** A worktree's folder-named home branch (e.g. `codebyplan-web`) is neither protected/main nor the canonical source, so `version-status` returns `guarded:false` there and this gate runs the update exactly as on a feat branch — landing it on whichever branch the worktree currently rests on (the deliberate "update the branch they're on, except main/canonical" behavior).
+**Home branches are intentionally not guarded.** A worktree's folder-named home branch (e.g. `codebyplan-web`) is neither protected/main nor the canonical source, so the freshness gate returns `result !== 'guarded'` there and this gate runs the update exactly as on a feat branch — landing it on whichever branch the worktree currently rests on (the deliberate "update the branch they're on, except main/canonical" behavior).
 
 Non-blocking — session end proceeds regardless of outcome.
 
@@ -170,9 +150,9 @@ 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); 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)
+- **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); `codebyplan session home-ff` (Step 1.6 home-branch fast-forward); `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`)
 - **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).
+- **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)

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

@@ -55,22 +55,11 @@ Pass `WORKTREE_ID` to MCP tools that support it. Null `WORKTREE_ID` means the (d
 
 Keep this worktree's **home branch** rooted at the freshest production tip — no prompt, fully non-blocking. Home branches are the folder-named placeholder branches each worktree rests on (e.g. `codebyplan-web`); `feat/*` branches are deliberately skipped — they integrate via `/cbp-merge-main` with QA, never an auto fast-forward.
 
-Resolve the production branch: read `.codebyplan/git.json` and take `branch_config.production` (fall back to `main` if the file or field is absent). Call this `$PRODUCTION`. Then compare the current branch against the worktree's folder name:
+Run `codebyplan session home-ff` and parse the JSON output (`{ result: 'skipped'|'warn'|'fast_forwarded', reason?, warn? }`):
 
-```bash
-FOLDER="$(basename "$(git rev-parse --show-toplevel)")"
-CURRENT="$(git rev-parse --abbrev-ref HEAD)"
-```
-
-- **`$CURRENT` != `$FOLDER`** (a `feat/*` or any non-home branch): skip silently — no fetch, no output.
-- **`$CURRENT` == `$FOLDER`** (home branch): fast-forward to `origin/$PRODUCTION`, warning once per failure and continuing:
-
-  ```bash
-  git fetch origin "$PRODUCTION" 2>/dev/null \
-    || echo "⚠ home-branch ff: fetch failed — staying on local $CURRENT"
-  git merge --ff-only "origin/$PRODUCTION" 2>/dev/null \
-    || echo "⚠ home-branch ff: $CURRENT not fast-forwardable (ahead/diverged) — left untouched"
-  ```
+- **`result === 'skipped'`** (non-home branch or production mismatch): proceed silently.
+- **`result === 'warn'`** (fast-forward attempt failed): surface the `warn` field as one line, then proceed silently.
+- **`result === 'fast_forwarded'`** (home branch updated): proceed silently.
 
 Never rebase, reset, force-push, or stash. A non-fast-forwardable home branch is a signal to reconcile manually, not to overwrite.
 
@@ -123,40 +112,38 @@ binary simply yields a zero count and no line.
 
 Check whether a newer `codebyplan` is published and safe to auto-install on this worktree's current branch. Runs AFTER the architecture-map drift check (Step 1.55) and BEFORE session activation (Step 3).
 
-```bash
-VERSION_JSON=$(npx codebyplan version-status 2>/dev/null)
-# Populate the claude-status cache best-effort (pure cache population — never gates session-start).
-npx codebyplan claude status --write-cache --quiet 2>/dev/null || true
-```
+Run `codebyplan session freshness-gate --halt-on-update` and parse the JSON output (`{ result: 'skipped'|'guarded'|'up_to_date'|'updated'|'error', ... }`):
+
+- **Probe failed** — the command errored or output cannot be parsed as JSON. → **FAIL-SAFE SKIP**: proceed silently to Step 3. Never disrupt a session over a best-effort freshness probe — the MCP gate (Step 0) is the only vital gate.
+- **`result === 'skipped'` / `'guarded'` / `'up_to_date'`** → skip silently, proceed to Step 3. Gate on the `result` field only.
+- **`result === 'error'`** → fail-safe skip, proceed to Step 3.
+- **`result === 'updated'`** → the CLI already ran the install + `npx codebyplan claude update`. Parse the JSON response:
+  - If `changed_files[]` is present and non-empty, offer the same commit gate as Step 5.7:
 
-Parse `$VERSION_JSON` as JSON and branch on the result:
+    ```
+    codebyplan updated. Commit the resulting .claude/ and .codebyplan/ changes before exiting?
+    [list of changed paths under .claude/ and .codebyplan/]
 
-- **Probe failed / unparseable** — the command errored, produced no output, or the output cannot be parsed as JSON carrying the required keys (`newer`, `guarded`, `installCommand`). This includes an installed `codebyplan` too old to have the `version-status` subcommand (which prints `Unknown command`). → **FAIL-SAFE SKIP**: proceed silently to Step 3. Never disrupt a session over a best-effort freshness probe — the MCP gate (Step 0) is the only vital gate.
-- **`guarded: true`** (protected/main branch OR the canonical `codebyplan` source monorepo — any `guardReason`) → skip silently, proceed to Step 3. Gate on the `guarded` boolean only; never branch on the specific `guardReason` string.
-- **`newer: false`** (already up to date) → skip silently, proceed to Step 3.
-- **`newer: true` AND `guarded: false`** → run the update path:
-  1. Run the JSON's `installCommand` (e.g. `pnpm add codebyplan@latest`) to LOCALLY install `codebyplan@latest` via the repo's package manager. Never a global `-g` install.
-  2. Run `npx codebyplan claude update` to refresh the worktree's `.claude/` assets on the current branch.
-  3. Detect changes across BOTH asset directories in one pass: `git status --porcelain -- .claude/ .codebyplan/`. If non-empty, offer the same commit gate as Step 5.7:
+    Reply: yes | no | select
+    ```
 
-     ```
-     codebyplan updated. Commit the resulting .claude/ and .codebyplan/ changes before exiting?
-     [list of changed paths under .claude/ and .codebyplan/]
+    On `yes`: `git add` the listed paths only, then trigger `/cbp-git-commit`. On `no`: skip. On `select`: ask which subset.
+  - **HALT** — do NOT proceed to Step 3. Print:
 
-     Reply: yes | no | select
-     ```
+    ```
+    ✓ codebyplan updated. Start a FRESH Claude Code session
+    (run /clear or open a new window) so the updated .claude/ takes effect.
+    ```
 
-     On `yes`: `git add` the listed paths only, then trigger `/cbp-git-commit`. On `no`: skip. On `select`: ask which subset.
-  4. **HALT** — do NOT proceed to Step 3. Print:
+    On this update-and-halt path the session is NOT continued: `update_session_state(activate)` is NOT called, `create_session_log` is NOT called, and `/cbp-todo` is NOT triggered.
 
-     ```
-     ✓ codebyplan updated to {latest}. Start a FRESH Claude Code session
-     (run /clear or open a new window) so the updated .claude/ takes effect.
-     ```
+**Home branches are intentionally not guarded.** A worktree's folder-named home branch (e.g. `codebyplan-web`) is neither protected/main nor the canonical source, so the freshness gate returns `result !== 'guarded'` there and this gate fires exactly as on a feat branch. That is deliberate — the update lands on whatever branch the worktree is currently resting on (the "update the branch they're on, except main/canonical" decision), not an accidental halt.
 
-     On this update-and-halt path the session is NOT continued: `update_session_state(activate)` is NOT called, `create_session_log` is NOT called, and `/cbp-todo` is NOT triggered.
+Populate the claude-status cache best-effort (pure cache population — never gates session-start):
 
-**Home branches are intentionally not guarded.** A worktree's folder-named home branch (e.g. `codebyplan-web`) is neither protected/main nor the canonical source, so `version-status` returns `guarded:false` there and this gate fires exactly as on a feat branch. That is deliberate — the update lands on whatever branch the worktree is currently resting on (the "update the branch they're on, except main/canonical" decision), not an accidental halt.
+```bash
+npx codebyplan claude status --write-cache --quiet 2>/dev/null || true
+```
 
 ### Step 1.7: LSP Binary Nudge
 
@@ -221,15 +208,12 @@ Probe the most-recent closed session log for a structured handoff payload (the h
 
 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):
+1. Resolve the active task's round files (local-first):
    - 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 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:
+   - If active task exists: read `.codebyplan/state/checkpoints/<checkpoint_id>/tasks/<task_id>/rounds/` and filter to rounds with status not in `completed` / `cancelled`; collect their `files[]` → `task_files` set. Break-glass fallback: MCP `get_rounds(task_id)`.
+   - If no active task exists, `task_files` is empty.
+2. Run `codebyplan session infra-files --json --task-files "<csv>"` where `<csv>` is the comma-separated task files from step 1. Parse the JSON response (`{ infra_files: string[], task_files: string[], note?: string }`). The CLI re-runs `git status --porcelain` internally and applies the set-math deterministically — the race-safe recompute, reading the index after Steps 0–5 round-trips complete.
+3. If `infra_files` is empty → skip. Otherwise present once:
 
    ```
    Commit these non-task files before starting session?
@@ -238,7 +222,7 @@ Clean the working tree of leftover infra before the session begins. Only commit
    Reply: yes | no | select
    ```
 
-6. On `yes`: `git add` the listed files, then trigger `/cbp-git-commit` (it handles conventional message + commit).
+4. 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.
@@ -288,7 +272,7 @@ 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 `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 arch-map drift` + `.codebyplan/architecture.json` presence (Step 1.55 architecture-map drift nudge, non-blocking); `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
+- **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 arch-map drift` + `.codebyplan/architecture.json` presence (Step 1.55 architecture-map drift nudge, non-blocking); `codebyplan session home-ff` (Step 1.4 home-branch fast-forward); `codebyplan session freshness-gate --halt-on-update` (Step 1.6 package-freshness gate); `codebyplan session infra-files --json --task-files <csv>` (Step 5.7 infra-file set math); `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)

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

@@ -66,9 +66,7 @@ Compute `TARGET`:
 | Task type | TARGET |
 |-----------|--------|
 | Standalone, `task.branch_name` set | `task.branch_name` |
-| Standalone, `branch_name` null | `feat/standalone-TASK-{N}-{kebab-slug-from-task-title}` |
-
-Slug rules: lowercase, words joined by `-`, drop punctuation, truncate to 40 chars.
+| Standalone, `branch_name` null | `feat/standalone-TASK-{N}-{slug}` where slug is computed via `codebyplan slug "{task title}"` |
 
 #### 3.2 — Compare current branch
 
@@ -76,26 +74,19 @@ Run `git branch --show-current`. If `current == TARGET` → continue to Step 3b.
 
 #### 3.3 — Switch automatically (no AskUserQuestion, no blocking)
 
+Run the branch checkout via the deterministic CLI:
+
 ```bash
-# (a) target exists locally
-if git rev-parse --verify "$TARGET" >/dev/null 2>&1; then
-  git checkout "$TARGET"
-
-# (b) target exists on origin (track it)
-elif git rev-parse --verify "origin/$TARGET" >/dev/null 2>&1; then
-  git checkout -t "origin/$TARGET"
-
-# (c) target doesn't exist — create from production branch
-else
-  git fetch origin "$PRODUCTION" 2>/dev/null || true
-  git checkout -b "$TARGET" "origin/$PRODUCTION" 2>/dev/null \
-    || git checkout -b "$TARGET" "$PRODUCTION"
-fi
+RESULT=$(codebyplan branch checkout --target "$TARGET" --production "$PRODUCTION")
+# Parse JSON: { action: "checked_out_local" | "checked_out_tracking" | "created_from_production" | "error", branch, previous?, error? }
+ACTION=$(echo "$RESULT" | jq -r '.action')
 ```
 
-No `git stash`, ever (per `git-safety.md`). No `git add`, ever (per `git-workflow.md`).
+**Interpreting the result:**
+- `action === "error"`: surface the raw `error` field verbatim and stop.
+- Otherwise (all success actions): branch is now `TARGET`. Continue to Step 3.4.
 
-If `git checkout` exits non-zero (would clobber), surface the raw git error verbatim and stop.
+No `git stash`, ever (per `git-safety.md`). No `git add`, ever (per `git-workflow.md`).
 
 #### 3.4 — Persist + verify
 

package/templates/skills/cbp-supabase-migrate/SKILL.md

@@ -3,7 +3,7 @@ scope: org-shared
 name: cbp-supabase-migrate
 description: Scaffold or adopt a Supabase migration for the current PR branch, apply to the branch's preview DB, run advisor checks, regenerate TypeScript types. Includes a fresh-branch dry-run pre-flight that uses one persistent dry-run ephemeral branch per feature branch.
 argument-hint: "[--new <name> | <path-to-sql>]"
-allowed-tools: Read, Edit, Write, Bash(git *), Bash(supabase *), Bash(jq *), Bash(date *), Bash(which *), Bash(cp *), Bash(mv *), Bash(test *), Bash(ls *), Bash(npx codebyplan checkpoint update *), Bash(npx codebyplan task update *), mcp__supabase__apply_migration, mcp__supabase__list_migrations, mcp__supabase__get_advisors, mcp__supabase__generate_typescript_types, mcp__supabase__reset_branch, mcp__supabase__list_branches, mcp__supabase__create_branch, mcp__supabase__get_cost, mcp__supabase__confirm_cost
+allowed-tools: Read, Edit, Write, Bash(codebyplan supabase *), Bash(npx codebyplan supabase *), Bash(npx codebyplan checkpoint update *), Bash(npx codebyplan task update *), Bash(git *), Bash(supabase *), Bash(jq *), Bash(date *), Bash(which *), Bash(cp *), Bash(mv *), Bash(test *), Bash(ls *), mcp__supabase__apply_migration, mcp__supabase__list_migrations, mcp__supabase__get_advisors, mcp__supabase__generate_typescript_types, mcp__supabase__reset_branch, mcp__supabase__list_branches, mcp__supabase__create_branch, mcp__supabase__get_cost, mcp__supabase__confirm_cost, mcp__codebyplan__update_checkpoint, mcp__codebyplan__update_task
 effort: xhigh
 ---
 
@@ -99,16 +99,21 @@ skip.
 
 ### Guard 2 — DB-path / migration intent
 
-Reuse the db_paths detection so the step proceeds only when this invocation actually touches
-the database. Read the globs (default `supabase/**`, `apps/backend/**`, `packages/**/db/**`):
+Delegate the db_paths config + branch diff to the CLI (replaces the former `db_paths` jq +
+`git diff` bash), and capture the parent project ref for the MCP calls below:
 
 ```bash
-DB_PATHS=$(jq -r '.shipment.surfaces.supabase.db_paths[]? // empty' .codebyplan/shipment.json 2>/dev/null)
-[ -z "$DB_PATHS" ] && DB_PATHS=$(printf '%s\n' 'supabase/**' 'apps/backend/**' 'packages/**/db/**')
+codebyplan supabase resolve-preview
 ```
 
+Parse its JSON `{ parent_ref, project_ref, db_changed, base }`. Capture `PARENT_REF=parent_ref`
+(read from `.codebyplan/shipment.json` `.shipment.surfaces.supabase.project_ref` — used by the
+list/create calls below, never a hardcoded literal). `db_changed` reflects the branch diff
+against `origin/<base>` matched against the configured db_paths globs (default `supabase/**`,
+`apps/backend/**`, `packages/**/db/**`).
+
 Proceed when **either**:
-- the branch diff against `origin/$PRODUCTION` touches any `DB_PATHS` glob, **or**
+- `db_changed === true`, **or**
 - this invocation will create/adopt a migration — `$ARGUMENTS` is `--new <name>` or a `.sql`
   path (the migration file may not exist on disk yet, so explicit migrate intent counts as a
   DB change). The bare-picker case (Step 5 Case C) is treated as migrate intent.
@@ -125,11 +130,12 @@ already provisioned the branch. Capture it as `PREVIEW_PROJECT_REF` and jump str
 
 ### Idempotency check (list before create)
 
-Call `mcp__supabase__list_branches` with the parent `project_id` `rrvtrumtkhrsbhcyrwvf`. The
-parent `project_id` for MCP calls is the same ref string stored in `.codebyplan/shipment.json`
-`surfaces.supabase.project_ref` — Supabase uses that one ref as both the project identifier
-and the branch target. Scan the returned list for an entry whose `name` exactly equals
-`$BRANCH` (slashes included — `feat/CHK-144-...` is a valid Supabase branch name).
+Call `mcp__supabase__list_branches` with the parent `project_id` `$PARENT_REF` (resolved by
+`codebyplan supabase resolve-preview` in Guard 2 from `.codebyplan/shipment.json`
+`.shipment.surfaces.supabase.project_ref` — never a hardcoded literal). Supabase uses that one
+ref as both the project identifier and the branch target. Scan the returned list for an entry
+whose `name` exactly equals `$BRANCH` (slashes included — `feat/CHK-144-...` is a valid
+Supabase branch name).
 
 - **Match found**: capture its `project_ref` as `PREVIEW_PROJECT_REF`. Skip creation; proceed
   to "Record connection". This is the idempotent reuse path (covers a branch the GitHub
@@ -148,7 +154,7 @@ Cost confirmation is mandatory before creating a branch — never bypass it:
    stays empty.
 
 After cost is confirmed, call `mcp__supabase__create_branch`:
-- `project_id`: `rrvtrumtkhrsbhcyrwvf` (parent project ref)
+- `project_id`: `$PARENT_REF` (parent project ref from `codebyplan supabase resolve-preview`)
 - `name`: `$BRANCH` (verbatim — slashes included)
 - `confirm_cost_id`: the same id from the `get_cost` response that was passed to `confirm_cost`
 
@@ -276,25 +282,16 @@ Parse `$ARGUMENTS`:
 
 ### Case A: `--new <name>`
 
-Generate a timestamp strictly greater than the latest filename in `supabase/migrations/`:
-
-```bash
-ls supabase/migrations/ | sort | tail -1
-```
-
-Extract the numeric prefix from the `tail -1` output (e.g. `20260520000003` from `20260520000003_chk116_security_and_logging_fixes.sql`). Your `date -u +%Y%m%d%H%M%S` output must be strictly greater than that prefix. If two scaffolds happen in the same UTC second, append `_01`, `_02` to maintain monotonicity. Use the current wall-clock UTC time
-via:
+Scaffold the migration file with a guaranteed-monotonic timestamp via the CLI (replaces the
+former `ls | tail` + `date` + `touch` bash):
 
 ```bash
-date -u +%Y%m%d%H%M%S
+codebyplan supabase new-migration "<name>"
 ```
 
-Create the file:
-
-```bash
-TIMESTAMP=$(date -u +%Y%m%d%H%M%S)
-touch "supabase/migrations/${TIMESTAMP}_<name>.sql"
-```
+Parse its JSON `{ path }`. The CLI creates an empty `supabase/migrations/<timestamp>_<slug>.sql`
+whose timestamp is strictly greater than the latest existing migration's, appending `_01`/`_02`
+on a same-second collision. Record the returned path as `MIGRATION_PATH`.
 
 Open the file for editing — write the migration SQL now. Include both the intended change
 and a comment block at the top:

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

@@ -93,9 +93,7 @@ Compute `TARGET`:
 | Task type | TARGET |
 |-----------|--------|
 | Checkpoint-bound, `checkpoint.branch_name` set | `checkpoint.branch_name` (e.g. `feat/CHK-095-pricing-page`) |
-| Checkpoint-bound, `branch_name` null (legacy) | `feat/CHK-{NNN}-{kebab-slug-from-checkpoint-title}` |
-
-Slug rules: lowercase, words joined by `-`, drop punctuation, truncate to 40 chars.
+| Checkpoint-bound, `branch_name` null (legacy) | `feat/CHK-{NNN}-{slug}` where slug is computed via `codebyplan slug "{checkpoint title}"` |
 
 #### 3.2 — Compare current branch
 
@@ -103,29 +101,19 @@ Run `git branch --show-current`. If `current == TARGET` → continue to Step 3b.
 
 #### 3.3 — Switch automatically (no AskUserQuestion, no blocking)
 
-Run the switch directly. Three sub-cases, in order:
+Run the branch checkout via the deterministic CLI:
 
 ```bash
-# (a) target exists locally
-if git rev-parse --verify "$TARGET" >/dev/null 2>&1; then
-  git checkout "$TARGET"
-
-# (b) target exists on origin (track it)
-elif git rev-parse --verify "origin/$TARGET" >/dev/null 2>&1; then
-  git checkout -t "origin/$TARGET"
-
-# (c) target doesn't exist — create from production branch (main)
-else
-  # First make sure production is up to date
-  git fetch origin "$PRODUCTION" 2>/dev/null || true
-  git checkout -b "$TARGET" "origin/$PRODUCTION" 2>/dev/null \
-    || git checkout -b "$TARGET" "$PRODUCTION"
-fi
+RESULT=$(codebyplan branch checkout --target "$TARGET" --production "$PRODUCTION")
+# Parse JSON: { action: "checked_out_local" | "checked_out_tracking" | "created_from_production" | "error", branch, previous?, error? }
+ACTION=$(echo "$RESULT" | jq -r '.action')
 ```
 
-**Carrying uncommitted work** — `git checkout` carries clean (non-conflicting) working-tree changes to the new branch automatically. This is intended: changes made on `main` while preparing the task move with the user to the new feat branch. No `git stash`, ever (per `git-safety.md`). No `git add`, ever (per `git-workflow.md`).
+**Interpreting the result:**
+- `action === "error"`: surface the raw `error` field verbatim, stop, do NOT attempt recovery. The user resolves git state and re-invokes. This is the only case where `/cbp-task-start` halts on branch state.
+- Otherwise (all success actions): branch is now `TARGET`. Continue to Step 3.4.
 
-**If `git checkout` exits non-zero** (typically "would clobber" because a tracked file has unstaged changes that conflict with target's version): surface the raw git error verbatim, stop, do NOT attempt recovery. The user resolves and re-invokes. This is the only case where `/cbp-task-start` halts on branch state.
+**Carrying uncommitted work** — the CLI respects git's automatic carrying of clean (non-conflicting) working-tree changes. Changes made while preparing the task move with the user to the new feat branch. No `git stash`, ever (per `git-safety.md`). No `git add`, ever (per `git-workflow.md`).
 
 **Note — Supabase preview branch**: no Supabase branch is created at this point. Creation is lazy — it happens on the first DB change when `/cbp-supabase-migrate` runs on the feat branch, which provisions a Supabase branch named identically to the git branch. See `cbp-supabase-migrate` Step 2.3 for the creation protocol.
 

package/templates/skills/cbp-task-testing/SKILL.md

@@ -9,7 +9,7 @@ effort: xhigh
 
 # Task Testing Command
 
-Comprehensive task-level testing — the **cross-round double-check** run once after all rounds complete. Per-round QA (per-app build/lint/types, the `console.log`/debug scan, the OWASP/secret grep, `pnpm audit`) is owned by each round's `testing-qa-agent`; this skill does NOT re-run it. Instead it tests the **entire delivered feature holistically** across the full task diff — catching cross-package and cross-round problems no single round can see. Runs inline — no sub-agent.
+Comprehensive task-level testing — runs all automated tests and walks the user through manual testing one-by-one. Distinct from round-level testing (`testing-qa-agent`): this tests the **entire delivered feature holistically** after all rounds are complete. Runs inline — no sub-agent.
 
 ## When Used
 
@@ -19,13 +19,13 @@ Comprehensive task-level testing — the **cross-round double-check** run once a
 
 ## Scope vs Round-Level Validation
 
-Per-wave `testing-qa-agent` runs inside `/cbp-round-execute` Step 5 and **owns per-round QA**: per-app build/lint/types, the `console.log`/debug scan, the OWASP/secret full-diff grep, and `pnpm audit`. This skill does NOT repeat them. It adds only the cross-round layer invisible within a single round: workspace-wide lint, workspace tsc, and the full test suite (which catch cross-package breakage), plus the cross-round code review (Step 6.5), the autonomous sim screenshot loop (Step 6.x), and the user manual walkthrough (Step 8).
+Per-wave `testing-qa-agent` runs inside `/cbp-round-execute` Step 5. This skill adds the cross-cutting layer that is only visible across the full task diff: whole-repo lint, whole-repo typecheck, full test suite, `pnpm audit` (via `codebyplan check --scope task --json`), and full-diff security scan — each run once here, not per-round.
 
 ## Instructions
 
 ### Step 1: Parse `$ARGUMENTS`
 
-Parse the argument using the canonical chk-task-round notation (see `cbp-round-start` Step 0 "CHK / TASK / ROUND Identifier Notation Vocabulary"):
+Parse the argument using the canonical chk-task-round notation (see `.claude/rules/notation-consistency.md`):
 
 | Shape | Regex | Resolves to |
 |-------|-------|-------------|
@@ -104,14 +104,24 @@ Capture stdout and stderr for each check.
 
 **Hard-fail tests** (block completion):
 
+Run the unified check matrix:
+
+```bash
+codebyplan check --scope task --json
+```
+
+Capture the JSON result. The runner is **whole-repo + baseline**: it runs `turbo run lint|typecheck|test` across every package and diffs each per-package result against the committed `.check-baseline.json`, so only NEW per-package failures fail a check. Five checks run for `--scope task`: `gate6` (sibling-identity parity — ALWAYS hard-fail, never baselined), `lint`, `typecheck`, `tests`, and `audit` (`audit.new_failures` lists new GHSA advisory ids not in the allowlist). A baselined check's `status` is `pass` when its `new_failures` array is empty even if the underlying command exited non-zero. If `any_failed === true` (or `hard_fail_checks` is non-empty), this is a hard fail — surface each failing result's `stdout`/`stderr`/`new_failures` and stop.
+
+For each result entry, record: `category` (from `result.check`), `status` (from `result.status`), `details`, `stdout` (from `result.stdout`), `stderr` (from `result.stderr`), and `new_failures` (from `result.new_failures` — the newly-failing packages / new GHSA ids; the field is omitted/`undefined` for `gate6`, not `null`).
+
+Additional hard-fail checks (not part of the runner):
+
 | Category                | Command                         | Condition                        |
 | ----------------------- | ------------------------------- | -------------------------------- |
-| Full-repo lint          | `pnpm -w lint`                  | Always                           |
-| Full-repo types         | `pnpm exec tsc --noEmit`        | Source files changed             |
-| Full-repo unit tests    | `pnpm test --run`               | Source files in aggregated_files |
 | Per-package E2E         | `pnpm --filter <pkg> e2e:test`  | UI files in aggregated_files     |
+| Full-diff security scan | inline grep or `security-agent` | Always                           |
 
-These are the workspace-wide / cross-package checks only — per-app build/lint/types, the `console.log`/debug scan, the OWASP/secret grep, and `pnpm audit` already ran per-round inside `testing-qa-agent` and are NOT repeated here. Per-file lint + format are enforced by `lint-format-on-edit.sh` per edit. This step catches cross-package issues invisible to per-wave checks.
+Per-file lint + format are enforced by `lint-format-on-edit.sh` hook per edit. This step catches cross-package issues invisible to per-wave checks.
 
 **Soft tests** (report, don't block):
 
@@ -120,8 +130,6 @@ These are the workspace-wide / cross-package checks only — per-app build/lint/
 | Visual     | Screenshot compare via `e2e:visual-check` | UI work + dev server running |
 | API Health | `curl` health endpoint                    | API routes changed           |
 
-For each test, record: `category, status (pass|fail|skipped), details, stdout, stderr`.
-
 #### Step 6.x: Autonomous Sim Screenshot Validation (mobile / on-device)
 
 For mobile rounds (Maestro / XCUITest / Tauri-mobile) where unit tests passed but the round touched component-mount code paths (custom hooks, prop signatures, conditional renders, navigation tabs), unit-test green is NOT sufficient evidence that the screen mounts at runtime. Use the autonomous sim screenshot loop to catch runtime crashes invisible to mocked unit tests.
@@ -168,7 +176,7 @@ For each finding, record: `{category, file, description, severity: 'low'|'medium
 
 Findings with severity `medium` or `high` feed the Step 9 problem classification. `low` findings are recorded in `task_testing_output` for the record but do not block.
 
-If any finding points to a need that exceeds task scope (e.g. a utility worth extracting for the wider codebase, a convention the repo should adopt globally), route per `cbp-task-create` Step 3.5 "Immediate Issue Capture Contract — How to Capture" — default to a NEW TASK in the current checkpoint, not a standalone task. Standalone routing applies only when the finding is genuinely off-axis from every active checkpoint AND the user has confirmed standalone routing.
+If any finding points to a need that exceeds task scope (e.g. a utility worth extracting for the wider codebase, a convention the repo should adopt globally), route per `immediate-issue-capture.md` "How to Capture" — default to a NEW TASK in the current checkpoint, not a standalone task. Standalone routing applies only when the finding is genuinely off-axis from every active checkpoint AND the user has confirmed standalone routing.
 
 ### Step 7: Separate Claude-Testable vs User-Testable