codebyplan 1.13.43 → 1.13.45

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

@@ -30,7 +30,7 @@ Set `KIND` for the rest of this skill. MCP tool names vary by KIND:
 
 # Round Check Command
 
-Run automated checks independently with mandatory execution. Updates round QA. Hard fails if mandatory checks (build/lint/types) fail.
+Run automated checks independently with mandatory execution. Updates round QA. Hard fails if mandatory checks (gate6/lint/typecheck/tests) fail.
 
 ## Instructions
 
@@ -41,80 +41,80 @@ Use Kind Detection above to set KIND. Then:
 - **checkpoint KIND**: Read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>.json` (local-first) to find active task, then read `.codebyplan/state/checkpoints/<checkpointId>/tasks/<taskId>/rounds/<roundId>.json` to find the in-progress round. If missing/stale, run `npx codebyplan sync` once and re-read. Break-glass fallback: MCP `get_current_task(repo_id)` + `get_rounds(task_id)` when state dir is absent and sync fails.
 - **standalone KIND**: MCP `get_current_standalone_task(repo_id)` to find active task, then `get_standalone_rounds(standalone_task_id)` to find the in-progress round. (Standalone KIND still uses MCP until a later task.)
 
-### Step 2: Determine Project Root
+### Step 2: Run Core Check Matrix
+
+From the repo root, run:
 
-Find the correct app directory:
 ```bash
-REPO_ROOT="$(git rev-parse --show-toplevel)"
+codebyplan check --scope round --json
 ```
-Identify app dir from project structure (e.g., `apps/web/` for Next.js).
 
-### Step 3: Execute Mandatory Checks (Hard Fail)
+Capture the JSON output. 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 a pre-existing failure in an unrelated package does NOT fail the check — only a NEW failure does. The result shape is:
 
-For each check, EXECUTE the command and capture stdout + stderr. Log execution status.
+```json
+{
+  "results": [
+    {"check": "gate6"|"lint"|"typecheck"|"tests"|"audit", "status": "pass"|"fail"|"skipped",
+     "exit_code": number|null, "command": string, "stdout": string, "stderr": string,
+     "executed": boolean, "new_failures"?: string[]}
+  ],
+  "any_failed": boolean,
+  "hard_fail_checks": [ ...names of checks that FAILED ]
+}
+```
 
-| Check | Command | Hard Fail |
-|-------|---------|-----------|
-| **Build** | `cd {app_dir} && npm run build 2>&1` | YES |
-| **Lint** | `cd {app_dir} && npm run lint 2>&1` | YES |
-| **Types** | `cd {app_dir} && npx tsc --noEmit 2>&1` | YES |
+Five checks run in order: `gate6` (sibling-identity parity — `node scripts/check-sibling-identity.mjs`), `lint`, `typecheck`, `tests`, `audit`. For the baselined checks (`lint`/`typecheck`/`tests`) `new_failures` lists the packages that newly fail (not in the baseline); `status` is `pass` when `new_failures` is empty **even if the underlying command exited non-zero** (those failures are pre-existing/baselined). `audit.new_failures` lists new GHSA advisory ids not in the allowlist. **`gate6` is ALWAYS hard-fail — it is never baselined**; its `new_failures` field is omitted (absent/`undefined` in the JSON, not `null`), and a sibling-parity divergence fails the round regardless of the baseline.
 
-For each:
-- Run the command via Bash tool
-- Log `EXECUTED: <command>` or `FAILED: <command> (exit code: N)`
-- If skipping (infrastructure-only changes): log `SKIPPED: <command> (reason: no app code changed)`
+`hard_fail_checks` is dynamic — it lists only the checks that failed (`[]` when all pass; e.g. `["gate6"]` or `["typecheck","tests"]`), drawn from `results[].check`. The hard-fail checks for `--scope round` are `gate6`, `lint`, `typecheck`, and `tests` (`audit` is `--scope task` only). If `any_failed === true` (equivalently, `hard_fail_checks` is non-empty), this is a **hard fail** — surface each failing result's `stdout`/`stderr` (and `new_failures`) and stop.
 
-### Step 4: Execute Conditional Checks
+### Step 3: Execute Conditional Checks
 
 | Check | Command | Condition |
 |-------|---------|-----------|
-| **Tests** | `cd {app_dir} && npx vitest --run 2>&1` | Test files exist |
 | **A11y** | Static check (aria, alt, focus) | UI files changed |
 | **API Health** | `curl -s -o /dev/null -w "%{http_code}" http://localhost:{PORT}/` | API routes changed |
 | **Visual** | Visual check flow (page-map + visual-check) | UI work + dev server running |
 
-### Step 5: Analyze Build Output
+### Step 4: Analyze Output
 
-Scan all captured output for:
+Scan each runner result's `stdout`/`stderr` for:
 - **Warnings** (not just errors)
 - **Deprecation notices** (`grep -i "deprecat"` in output)
 - **Console.log in changed files**: `grep -rn "console\.\(log\|debug\|info\)" {changed_files}` (exclude tests)
 - **Bundle size warnings**
 
-### Step 6: Save QA Results
+### Step 5: Save QA Results
 
 Update round QA:
 - **checkpoint KIND**: `codebyplan round update --id <round_id> --task-id <task_id> --checkpoint-id <checkpoint_id> --qa '<json>'` (CLI write-through: local state file + REST). Break-glass fallback: MCP `update_round(round_id, qa: ...)` when the CLI is unavailable.
 - **standalone KIND**: MCP `update_standalone_round(standalone_round_id, qa: ...)`. (Standalone KIND still uses MCP until a later task.)
 
+Map each runner result entry to a QA item:
+
 ```json
 {
   "items": [
-    {"type": "auto", "check": "build", "status": "pass", "ran_at": "...", "notes": null, "executed": true},
-    {"type": "auto", "check": "lint", "status": "fail", "ran_at": "...", "notes": "3 errors", "executed": true},
-    {"type": "auto", "check": "types", "status": "pass", "ran_at": "...", "notes": null, "executed": true},
-    {"type": "auto", "check": "tests", "status": "skipped", "ran_at": "...", "notes": "no test files", "executed": false}
+    {"type": "auto", "check": "gate6", "status": "pass", "ran_at": "...", "notes": null, "executed": true},
+    {"type": "auto", "check": "lint", "status": "pass", "ran_at": "...", "notes": null, "executed": true},
+    {"type": "auto", "check": "typecheck", "status": "fail", "ran_at": "...", "notes": "1 new failing package", "executed": true},
+    {"type": "auto", "check": "tests", "status": "pass", "ran_at": "...", "notes": "no new failures (baselined)", "executed": true}
   ]
 }
 ```
 
-### Step 7: Show Results
+### Step 6: Show Results
 
 ```
 ## Round Check Results
 
 | Check | Status | Executed | Notes |
 |-------|--------|----------|-------|
-| Build | pass | yes | - |
-| Lint | fail | yes | 3 errors |
-| Types | pass | yes | - |
-| Tests | skipped | no | no test files |
-| Visual | pass | yes | screenshots saved |
-
-### Build Analysis
-- Warnings: [N]
-- Deprecations: [N]
-- Console.logs in code: [N]
+| gate6 | pass   | yes      | sibling-identity OK |
+| lint  | pass   | yes      | -     |
+| typecheck | fail | yes    | 1 new failing package |
+| tests | pass   | yes      | no new failures (baselined) |
+| A11y  | pass   | yes      | -     |
+| Visual| pass   | yes      | screenshots saved |
 
 **Result**: [N] passed, [N] failed, [N] skipped
 **Hard fail**: [yes/no]
@@ -129,4 +129,5 @@ If soft failures only: `Run /cbp-round-start to trigger auto-fix, or fix manuall
 - **Reads (standalone KIND)**: MCP `get_current_standalone_task` / `get_standalone_rounds` (standalone KIND still uses MCP until a later task)
 - **Writes (checkpoint KIND)**: `codebyplan round update` (qa field). Break-glass: MCP `update_round`.
 - **Writes (standalone KIND)**: MCP `update_standalone_round` (qa field). (Standalone KIND still uses MCP until a later task.)
+- **Runner**: `codebyplan check --scope round --json` (whole-repo + baseline via `turbo run`; runs gate6 + lint + typecheck + tests; `--files` is accepted but ignored in whole-repo mode)
 - **Standalone**: Can be run independently at any time

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

@@ -178,7 +178,13 @@ Per-wave hard-fail signal — true when ANY hold:
 
 - `testing_qa_output.totals.hard_fail === true`.
 - For any framework `f` in `round.context.e2e_outputs`: `e2e_outputs[f].status === 'failed'` OR `e2e_outputs[f].test_results?.failed > 0`.
-- **`e2e_eligible_skipped`**: any framework in `round.context.e2e_eligible[]` for which no specialist output exists in `round.context.e2e_outputs` AND no valid skip reason is recorded (per the `rules/e2e-mandatory.md` valid-skip list). A silently-skipped eligible framework is a hard-fail.
+- **E2E deterministic gate** (replaces the former judgment-based `e2e_eligible_skipped` evaluation): when `round.context.e2e_eligible[]` is non-empty, first persist `e2e_eligible` / `e2e_outputs` to round context via MCP `update_round` (the Step 7 write, pulled forward — the CLI reads the round row from the DB), then run:
+
+  ```bash
+  codebyplan e2e verify-round --round-id <round_id> --task-id <task_id>
+  ```
+
+  Exit 0 = e2e pass. Exit 1 = one or more deterministic hard-fails — the stdout JSON's `failed_checks[]` identifies which (`e2e_eligible_skipped`, `zero_assertion_run`, `empty_gallery`); the `rules/e2e-mandatory.md` valid-skip list and the vscode-test empty-gallery exception are honored by the CLI. When `e2e_eligible[]` is empty, skip the CLI call — nothing to verify.
 
 **All waves hard_fail: false** → proceed to Step 7. **Any wave hard_fail: true**:
 
@@ -197,9 +203,9 @@ When `cbp-testing-qa-agent` spawn fails OR the resolved `testing_profile` is `cl
 
 `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.
 
-- `context`: { ...existing, executor_output, testing_qa_output, e2e_eligible, e2e_outputs, frontend_ui_review }
+- `context`: { ...existing, executor_output, testing_qa_output, e2e_eligible, e2e_outputs, frontend_ui_review } — when e2e ran, `e2e_eligible` / `e2e_outputs` were already persisted by the Step 6 pull-forward write; re-include them in this merge payload (the `update_round` REPLACE contract requires re-sending every field that should remain — this is a consolidating merge, not a second write of new data).
 
-`e2e_outputs` (a framework-keyed map of specialist outputs, e.g. `{ playwright: {...}, maestro: {...} }`) and `frontend_ui_review` are present only when the gates above admitted them (≥1 eligible framework ran AND Step 5b ran). `e2e_eligible[]` records which frameworks were eligible this round and drives the Step 6 `e2e_eligible_skipped` check.
+`e2e_outputs` (a framework-keyed map of specialist outputs, e.g. `{ playwright: {...}, maestro: {...} }`) is present when ≥1 eligible framework ran. `frontend_ui_review` is present only when ≥1 eligible framework ran AND Step 5b ran (non-empty screenshots). `e2e_eligible[]` records which frameworks were eligible this round and drives the Step 6 E2E deterministic gate.
 
 ### Step 8: Auto-trigger Round End
 

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: