codebyplan 1.13.61 → 1.13.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.61",
+  "version": "1.13.63",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

package/templates/agents/cbp-e2e-maestro.md

@@ -3,7 +3,7 @@ name: cbp-e2e-maestro
 description: Maestro E2E flow authoring + execution for Expo/React Native mobile apps (android + ios). Spawned by /cbp-round-build Step 5 and /cbp-checkpoint-check Step 5b when framework is 'maestro'.
 tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
 model: sonnet
-effort: xhigh
+effort: high
 ---
 
 # Maestro E2E Agent

package/templates/agents/cbp-e2e-playwright.md

@@ -3,7 +3,7 @@ name: cbp-e2e-playwright
 description: Playwright E2E test authoring + execution for web app routes. Spawned by /cbp-round-build Step 5 and /cbp-checkpoint-check Step 5b when framework is 'playwright'.
 tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
 model: sonnet
-effort: xhigh
+effort: high
 ---
 
 # Playwright E2E Agent
@@ -31,20 +31,20 @@ pnpm exec playwright install --with-deps chromium
 
 Resolve the apps/{app} dev-server port at config-read time via the shared resolver
 `apps/{app}/e2e/resolve-web-dev-port.ts` — imported by BOTH `playwright.config.ts` and
-`e2e/auth.setup.ts` (single source of truth). It reads the per-worktree
+`e2e/auth.setup.ts` (single source of truth). It reads the per-checkout, branch-keyed
 `.codebyplan/server.local.json` overlay first, then the committed `.codebyplan/server.json`.
 Match by label rather than array position — a monorepo can have several Next.js allocations
 with similar label prefixes.
 
 **Label-matching rules** (`findWebDevPort`):
 
-- `server.local.json` overlay: each label has the worktree name appended as the last
-  parenthetical group (e.g. `"Web Dev (<worktree-name>)"`). Strip exactly ONE trailing
+- `server.local.json` overlay: each label has a branch-keyed suffix appended as the last
+  parenthetical group (e.g. `"Web Dev (<branch-keyed-suffix>)"`). Strip exactly ONE trailing
   `" (…)"` group, then require the result `=== "Web Dev"`.
-  - `"Web Dev (<worktree-name>)"` → strip → `"Web Dev"` ✓
-  - `"Web Dev (<other-worktree>) (<worktree-name>)"` → strip → `"Web Dev (<other-worktree>)"` ✗
+  - `"Web Dev (<branch-keyed-suffix>)"` → strip → `"Web Dev"` ✓
+  - `"Web Dev (<other-suffix>) (<branch-keyed-suffix>)"` → strip → `"Web Dev (<other-suffix>)"` ✗
 - `server.json` committed base: require `label === "Web Dev"` exactly (do NOT strip —
-  `"Web Dev (<other-worktree>)"` must not match).
+  `"Web Dev (<other-suffix>)"` must not match).
 
 **Resolution order** (first hit wins):
 
@@ -108,7 +108,7 @@ import { resolveWebDevPort } from "./e2e/resolve-web-dev-port";
 // findWebDevPort, parsePortFromUrl, and resolveWebDevPort live in the shared
 // module ./e2e/resolve-web-dev-port.ts (imported above) — single source of
 // truth, also consumed by e2e/auth.setup.ts. Resolution order:
-//   0. PLAYWRIGHT_BASE_URL → 1. server.local.json → 2. server.json
+//   0. PLAYWRIGHT_BASE_URL → 1. server.local.json (branch-keyed overlay) → 2. server.json
 //   → 3. E2E_BASE_URL → 4. 3010.
 const port = resolveWebDevPort();
 
@@ -198,7 +198,7 @@ timing**: it loads creds from `.env.local` + `.codebyplan/e2e.env`, calls
 the project ref from `NEXT_PUBLIC_SUPABASE_URL`, and writes a `sb-<projectref>-auth-token`
 cookie (domain `localhost`) into `state.json` using the same `encodeAuthCookie` from
 `e2e/auth-cookie.ts` that global-setup consumes. This makes seeding deterministic in any
-worktree — run `pnpm e2e:auth-setup` (optionally `--port N`) when `state.json` is missing or
+checkout — run `pnpm e2e:auth-setup` (optionally `--port N`) when `state.json` is missing or
 its refresh token has expired. Do NOT reintroduce a browser-login flow (the `(auth)/login`
 page is a client component whose `onSubmit` only attaches after hydration — clicking submit
 pre-hydration falls through to a native GET and never authenticates).
@@ -261,8 +261,8 @@ any already-running process, so the dev-server readiness probe is the active gua
 path.
 
 **Port alignment**: parse `playwright.config.ts` `baseURL` port; compare to the resolved
-port from `.codebyplan/server.local.json` (worktree overlay, checked first) then
-`.codebyplan/server.json` (committed base). On mismatch ask which is correct, then propose
+port from `.codebyplan/server.local.json` (per-checkout branch-keyed overlay, checked first)
+then `.codebyplan/server.json` (committed base). On mismatch ask which is correct, then propose
 an Edit to align them.
 
 ## Quality Fixture (MANDATORY)

package/templates/agents/cbp-e2e-tauri.md

@@ -3,7 +3,7 @@ name: cbp-e2e-tauri
 description: WebDriverIO + tauri-driver E2E test authoring + execution for Tauri desktop apps. Spawned by /cbp-round-build Step 5 and /cbp-checkpoint-check Step 5b when framework is 'webdriverio'.
 tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
 model: sonnet
-effort: xhigh
+effort: high
 ---
 
 # Tauri E2E Agent

package/templates/agents/cbp-e2e-vscode.md

@@ -3,7 +3,7 @@ name: cbp-e2e-vscode
 description: VS Code extension E2E test authoring + execution using @vscode/test-cli and @vscode/test-electron. Spawned by /cbp-round-build Step 5 and /cbp-checkpoint-check Step 5b when framework is 'vscode-test'.
 tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
 model: sonnet
-effort: xhigh
+effort: high
 ---
 
 # VS Code Extension E2E Agent

package/templates/agents/cbp-e2e-xcuitest.md

@@ -3,7 +3,7 @@ name: cbp-e2e-xcuitest
 description: XCUITest native iOS E2E test authoring + execution for Expo apps targeting system dialogs, HealthKit, watchOS, or other areas Maestro cannot reach. Spawned by /cbp-round-build Step 5 and /cbp-checkpoint-check Step 5b when framework is 'xcuitest'.
 tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, mcp__codebyplan__get_repos
 model: sonnet
-effort: xhigh
+effort: high
 ---
 
 # XCUITest E2E Agent

package/templates/hooks/cbp-mcp-round-sync.sh

@@ -20,13 +20,10 @@
 #   - Web-UI flag (app_file_approval_by_user) consumption + reset
 #   - Writes both PATCH /api/rounds/${ROUND_ID} and PATCH /api/tasks/${TASK_ID}
 #
-# Caller worktree identity:
-#   The CLI auto-resolves caller_worktree_id (override flag → cache →
-#   in-process tuple API) and hard-fails with exit 1 if it cannot resolve
-#   on the write path. This hook resolves the worktree id before invoking the
-#   CLI and passes it via --caller-worktree-id so the server can honor the
-#   feat-worktree lock. The hook itself stays non-fatal (exits 0) and surfaces
-#   the CLI's stderr output to the user.
+# Caller identity:
+#   Worktree-based caller injection was retired in CHK-225. The hook no longer
+#   resolves or threads any worktree id; user identity travels via the MCP JWT.
+#   The hook stays fail-open and exits 0.
 #
 # Flags:
 #   --dry-run  Pass through to CLI (prints merged payload, no API writes).
@@ -83,16 +80,8 @@ if [ -z "$TASK_ID" ]; then
   exit 0
 fi
 
-# Resolve worktree id before invoking the CLI so the server can honor the
-# feat-worktree lock. On miss (unregistered worktree) the CLI falls back to
-# its in-process resolve and hard-fails with guidance if still unresolved.
-WORKTREE_ID=$(npx codebyplan resolve-worktree 2>/dev/null)
-
 # Delegate to the codebyplan CLI (single source of truth for merge semantics)
 CMD_ARGS=("round" "sync-approvals" "--round-id" "$ROUND_ID" "--task-id" "$TASK_ID")
-if [ -n "$WORKTREE_ID" ]; then
-  CMD_ARGS+=("--caller-worktree-id" "$WORKTREE_ID")
-fi
 [ "$DRY_RUN" = "true" ] && CMD_ARGS+=("--dry-run")
 
 if npx codebyplan "${CMD_ARGS[@]}"; then

package/templates/hooks/cbp-test-hooks.sh

@@ -374,87 +374,6 @@ fi
 
 echo ""
 
-# ===== HOOK SMOKE TESTS — cbp-mcp-caller-worktree-inject =====
-echo "## Hook Smoke Tests — cbp-mcp-caller-worktree-inject (CHK-198)"
-
-INJECT_HOOK="$HOOKS_DIR/cbp-mcp-caller-worktree-inject.sh"
-# Absolute path — the fail-open test runs the hook from a temp cwd (to isolate it
-# from this repo's git context), where the relative "$HOOKS_DIR" no longer resolves.
-INJECT_HOOK_ABS="$(cd "$HOOKS_DIR" 2>/dev/null && pwd)/cbp-mcp-caller-worktree-inject.sh"
-
-if [ ! -f "$INJECT_HOOK" ]; then
-  test_result "cbp-mcp-caller-worktree-inject.sh present" "passed" "missing"
-else
-  test_result "cbp-mcp-caller-worktree-inject.sh present" "passed" "passed"
-
-  FIRST_LINE=$(head -1 "$INJECT_HOOK")
-  if echo "$FIRST_LINE" | grep -q '^#!/'; then
-    test_result "cbp-mcp-caller-worktree-inject.sh has shebang" "passed" "passed"
-  else
-    test_result "cbp-mcp-caller-worktree-inject.sh has shebang" "passed" "missing"
-  fi
-
-  if grep -q '@scope: org-shared' "$INJECT_HOOK"; then
-    test_result "cbp-mcp-caller-worktree-inject.sh has @scope: org-shared" "passed" "passed"
-  else
-    test_result "cbp-mcp-caller-worktree-inject.sh has @scope: org-shared" "passed" "missing"
-  fi
-
-  # Fail-open: run from a non-repo temp dir with no worktree cache and no
-  # CLAUDE_PROJECT_DIR — neither the cache nor the CLI fallback can resolve a
-  # worktree, so the hook must exit 0 with empty stdout (no updatedInput).
-  ISO=$(mktemp -d)
-  OUTPUT=$( (cd "$ISO" && env -u CLAUDE_PROJECT_DIR bash "$INJECT_HOOK_ABS" <<< '{"tool_input":{"task_id":"x"}}') 2>/dev/null )
-  EXIT_CODE=$?
-  if [ "$EXIT_CODE" = "0" ] && [ -z "$OUTPUT" ]; then
-    test_result "cbp-mcp-caller-worktree-inject.sh fail-open (unresolvable) exits 0 + empty stdout" "passed" "passed"
-  else
-    test_result "cbp-mcp-caller-worktree-inject.sh fail-open (unresolvable) exits 0 + empty stdout" "passed" "failed (exit=$EXIT_CODE)"
-  fi
-  rm -rf "$ISO"
-
-  # C6 — input already carries a non-empty caller_worktree_id → never overwrite;
-  # early-return with exit 0 and empty stdout (no resolution attempted).
-  OUTPUT=$(echo '{"tool_input":{"caller_worktree_id":"11111111-1111-1111-1111-111111111111"}}' | bash "$INJECT_HOOK" 2>/dev/null)
-  EXIT_CODE=$?
-  if [ "$EXIT_CODE" = "0" ] && [ -z "$OUTPUT" ]; then
-    test_result "cbp-mcp-caller-worktree-inject.sh C6 keeps existing caller_worktree_id (exit 0 + empty stdout)" "passed" "passed"
-  else
-    test_result "cbp-mcp-caller-worktree-inject.sh C6 keeps existing caller_worktree_id (exit 0 + empty stdout)" "passed" "failed (exit=$EXIT_CODE)"
-  fi
-
-  # Injection — a worktree.local.json whose .branch matches the current git branch
-  # makes the cache fast-path resolve. Use a synthetic UUID so the assertion proves
-  # the cache value (not the live CLI) was injected. Skipped when no concrete git
-  # branch resolves (detached HEAD / non-git checkout) or jq is unavailable.
-  CUR_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
-  if [ -n "$CUR_BRANCH" ] && [ "$CUR_BRANCH" != "HEAD" ] && command -v jq >/dev/null 2>&1; then
-    ISO=$(mktemp -d)
-    mkdir -p "$ISO/.codebyplan"
-    FAKE_WT="abcdef01-2345-6789-abcd-ef0123456789"
-    jq -n --arg b "$CUR_BRANCH" --arg w "$FAKE_WT" \
-      '{worktree_id:$w, branch:$b}' > "$ISO/.codebyplan/worktree.local.json"
-    OUTPUT=$(CLAUDE_PROJECT_DIR="$ISO" bash "$INJECT_HOOK" <<< '{"tool_input":{"task_id":"x"}}' 2>/dev/null)
-    EXIT_CODE=$?
-    INJECTED=$(echo "$OUTPUT" | jq -r '.hookSpecificOutput.updatedInput.caller_worktree_id // empty' 2>/dev/null)
-    # Sibling-key survival — CC's updatedInput REPLACES tool_input wholesale (it is
-    # not a partial merge), so the hook must echo back every original field merged
-    # with caller_worktree_id. Assert the non-target sibling key (task_id) survives;
-    # this is the assertion gap that let the replace-vs-merge bug ship in round 2.
-    PRESERVED=$(echo "$OUTPUT" | jq -r '.hookSpecificOutput.updatedInput.task_id // empty' 2>/dev/null)
-    if [ "$EXIT_CODE" = "0" ] && [ "$INJECTED" = "$FAKE_WT" ] && [ "$PRESERVED" = "x" ]; then
-      test_result "cbp-mcp-caller-worktree-inject.sh injects caller_worktree_id AND preserves sibling keys" "passed" "passed"
-    else
-      test_result "cbp-mcp-caller-worktree-inject.sh injects caller_worktree_id AND preserves sibling keys" "passed" "failed (exit=$EXIT_CODE injected=$INJECTED preserved=$PRESERVED)"
-    fi
-    rm -rf "$ISO"
-  else
-    test_result "cbp-mcp-caller-worktree-inject.sh injection test (no branch resolvable — skipped)" "passed" "passed"
-  fi
-fi
-
-echo ""
-
 # ===== HOOK SMOKE TESTS — cbp-session-start-hook =====
 echo "## Hook Smoke Tests — cbp-session-start-hook (CHK-178)"
 

package/templates/hooks/hooks.json

@@ -69,15 +69,6 @@
             "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-mcp-migration-guard.sh"
           }
         ]
-      },
-      {
-        "matcher": "mcp__codebyplan__(update_checkpoint|complete_checkpoint|update_task|complete_task|add_round|update_round|complete_round|create_standalone_task|update_standalone_task|complete_standalone_task|add_standalone_round|update_standalone_round|complete_standalone_round|update_standalone_file_change)",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-mcp-caller-worktree-inject.sh"
-          }
-        ]
       }
     ],
     "PostToolUse": [

package/templates/rules/cbp-operating-gotchas.md

@@ -25,11 +25,13 @@ SHARED tooling behavior only — repo-specific gotchas belong in that repo's own
   clobbers existing `decisions` / `discoveries` / `check_results`. Always read the current row,
   merge your change into the full object/array, then write the whole thing back.
 
-- **`resolve-worktree` empty output = a NULL `(device, path, branch)` tuple, not a broken
-  resolver.** When identity is unresolved the server can collapse the caller to the repo's main
-  worktree, so feat-locked writes get rejected. Pass `caller_worktree_id` on every MCP mutation,
-  and confirm ownership by matching the row's repo path + branch to the current directory before
-  mutating.
+- **User-level locks are invisible until a mutation they block.** `get_checkpoints` /
+  `get_tasks` succeed even when another user holds the assignment; the 403 fires only on
+  `update_*` / `complete_*`. The lock keys on the JWT user (`ctx.userId`) vs the row's
+  `assigned_user_id` (null = open). `caller_worktree_id` / `worktree_id` params are
+  accepted-and-ignored — do not thread them. Verify `assigned_user_id` matches
+  `npx codebyplan whoami` before mutating; recover a stale assignment with
+  `release_assignment` (maintainer).
 
 - **Full-repo lint/type baselines are often pre-existing red.** A round must gate on the files
   it changed, not the whole-repo baseline — scope lint/tsc checks to the round's changed set so a
@@ -40,14 +42,10 @@ SHARED tooling behavior only — repo-specific gotchas belong in that repo's own
   `update_task` alone — updating only the task leaves the round entries unapproved and
   `complete_task` rejects with "files are not approved".
 
-- **CLI transport uses REST (reads) and OAuth+MCP (writes) — a 502 from `codebyplan round sync-approvals` is transient MCP churn, not an outage.** The CLI exits 0 with a warning and MCP tools still work. A missing `CODEBYPLAN_API_KEY` surfaces as an `ApiError`, not a 502. `sync-approvals` can also drag untracked per-device dirs into `files_changed` — run it from the repo root or pass `--caller-worktree-id`.
+- **CLI transport uses REST (reads) and OAuth+MCP (writes) — a 502 from `codebyplan round sync-approvals` is transient MCP churn, not an outage.** The CLI exits 0 with a warning and MCP tools still work. A missing `CODEBYPLAN_API_KEY` surfaces as an `ApiError`, not a 502. `sync-approvals` can also drag untracked per-device dirs into `files_changed` — run it from the repo root.
 
 - **`codebyplan claude update` requires a TTY.** On non-TTY stdin (CI, piped) it half-applies then errors. Re-run with `--yes` to accept defaults non-interactively.
 
-- **Checkpoint locks are invisible until a mutation they block.** `get_checkpoints` / `get_tasks` succeed even when another worktree holds the lock; the 403 fires only on `update_*` / `complete_*`. Verify the row's `worktree_id` matches the caller before mutating. A null-`worktree_id` checkpoint can still be actively shipped by whichever worktree physically holds its feat branch — check `git worktree list` first.
-
-- **`update_task` accepts `caller_worktree_id` for lock-verify only — it does NOT assign ownership.** Ownership assignment goes through the web UI or the dedicated assignment path. Don't conflate `caller_worktree_id` with `assigned_worktree_id`.
-
 - **Re-run config-driven gates after merging main into a feat branch.** A merge can add or change `.codebyplan/shipment.json`, ports, branch config, `e2e.json`, and `eslint.json` — treat the post-merge state as a fresh baseline before continuing.
 
 ## Behavioral Preferences

package/templates/rules/effort-and-ultracode.md

@@ -0,0 +1,70 @@
+---
+description: Effort ladder (low..max), per-model support, frontmatter usage, and the session-only ultracode mode.
+---
+
+# Effort and Ultracode
+
+On-demand reference for effort levels and the ultracode mode in Claude Code.
+
+## Effort Ladder
+
+| Level | Gloss |
+|-------|-------|
+| `low` | Latency-sensitive, trivial tasks — minimal reasoning |
+| `medium` | Standard tasks — moderate reasoning |
+| `high` | Default for most models — solid reasoning budget |
+| `xhigh` | Extended reasoning — slower, better for complex multi-step work |
+| `max` | Deepest reasoning available — session-only, can overthink simple tasks |
+
+## Per-Model Support
+
+| Model | Supported levels | Default effort |
+|-------|-----------------|----------------|
+| Opus 4.8, Fable 5 | `low` `medium` `high` `xhigh` `max` | `high` |
+| Opus 4.7 | `low` `medium` `high` `xhigh` `max` | `xhigh` |
+| Opus 4.6, Sonnet 4.6 | `low` `medium` `high` `max` (`xhigh` → falls back to `high`) | `high` |
+
+## Precedence (highest → lowest)
+
+1. `CLAUDE_CODE_EFFORT_LEVEL` env var
+2. Frontmatter `effort:` (while a skill/agent is active)
+3. `effortLevel` in `settings.json`
+4. Model default
+
+## Frontmatter Usage
+
+Skills set `model: inherit` + `effort: <level>`. Subagents pin `model: <id>` + `effort: <level>`.
+Both override the session level only while active.
+
+`effort: ultracode` is **invalid** in frontmatter — `validate-skill.sh` errors on it. Use
+`effort: max` for the heaviest per-skill reasoning budget; enable ultracode session-wide with
+`/effort ultracode`.
+
+## settings.json `effortLevel`
+
+Accepts `low | medium | high | xhigh` **only**. `max` and `ultracode` are session-only and
+rejected by the settings validator.
+
+This repo's default is `xhigh` (`.claude/settings.json`). You **cannot** default ultracode
+in settings.json — enable it per-session instead.
+
+## Ultracode Mode
+
+ultracode = `xhigh` reasoning + automatic Workflow orchestration for substantive tasks.
+It is a **session-only** Claude Code mode, NOT a frontmatter `effort` value, NOT `effortLevel`,
+NOT `--effort`, NOT `CLAUDE_CODE_EFFORT_LEVEL`.
+
+**Enable via:**
+- `/effort ultracode` (in-session slash command)
+- `claude --settings '{"ultracode": true}'`
+- An Agent SDK control request
+
+Applies to the current session only — resets on a new session.
+
+**When to enable:** heavy multi-step checkpoints where deterministic multi-agent fan-out
+helps. See `rules/workflow-orchestration.md` for full orchestration guidance.
+
+## Related
+
+- `rules/model-invocation-convention.md` — model pinning in skill/agent frontmatter
+- `rules/workflow-orchestration.md` — Workflow tool pattern, opt-in gate, and when to use it instead of ad-hoc Task/Agent spawns

package/templates/rules/model-invocation-convention.md

@@ -38,3 +38,4 @@ See `.claude/skills/cbp-build-cc-settings/reference/cbp-permission-policy.md` fo
 
 - `rules/scope-vocabulary.md` — scope marker conventions for managed vs user-created files
 - `cbp-build-cc-settings/reference/cbp-permission-policy.md` — allow/ask tiers
+- `rules/effort-and-ultracode.md` — effort ladder, per-model support, and the session-only ultracode mode

package/templates/rules/supabase-branch-lifecycle.md

@@ -47,7 +47,7 @@ The Supabase branch is removed wherever the git branch is deleted:
 | Skill | Trigger |
 |---|---|
 | `cbp-checkpoint-end` | stale-branch cleanup + current feat-branch delete on ship |
-| `codebyplan worktree remove CHK-NNN` | worktree teardown removes the coupled Supabase branch |
+| `codebyplan worktree remove <path>` | git-worktree teardown removes the coupled Supabase branch (branch-keyed, not identity-keyed) |
 | `cbp-ship-main` | `branch_deleted` event after PR merge |
 | `cbp-standalone-task-complete` | `branch_deleted` event after standalone PR merge (Step 7.3) |
 
@@ -93,7 +93,7 @@ or auto-created by the GitHub integration — both paths use the same branch nam
 | Role | Skill |
 |---|---|
 | Create (lazy) | `cbp-supabase-migrate` (Step 2.3) |
-| Delete | `cbp-checkpoint-end`, `cbp-standalone-task-complete`, `codebyplan worktree remove`, `cbp-ship-main` |
+| Delete | `cbp-checkpoint-end`, `cbp-standalone-task-complete`, `codebyplan worktree remove <path>`, `cbp-ship-main` |
 | PR gate | `cbp-supabase-branch-check` |
 
 Each skill in the Skill Map above carries an inline back-reference to this rule at its create or teardown step.

package/templates/rules/todo-backend.md

@@ -12,16 +12,16 @@ The todos queue is materialised by `apps/todo-worker` (CHK-122) and consumed by
 
 ## 1. Six workflow invariants — DB-layer guards, never bypassable
 
-Defined in `supabase/migrations/20260511211900_chk111_workflow_invariants.sql`. These are `BEFORE UPDATE` triggers — they refuse invalid state transitions and produce structured `RAISE EXCEPTION` errors with `HINT` pointing at the offending row. **Do NOT port these to TS.** The DB layer is the bypass-proof contract.
+Defined in `supabase/migrations/20260511211900_chk111_workflow_invariants.sql` (updated by `supabase/migrations/20260612000000_chk225_task1_user_locks.sql`). These are `BEFORE UPDATE` triggers — they refuse invalid state transitions and produce structured `RAISE EXCEPTION` errors with `HINT` pointing at the offending row. **Do NOT port these to TS.** The DB layer is the bypass-proof contract.
 
 | # | Trigger | What it enforces |
 |---|---------|------------------|
-| 1 | `trg_enforce_checkpoint_activation_worktree` | A checkpoint cannot be activated without `worktree_id` set |
-| 2 | `enforce_standalone_task_worktree` (via task workflow) | A standalone task cannot be moved to `in_progress` without `assigned_worktree_id` |
+| 1 | `trg_enforce_checkpoint_activation_worktree` | A checkpoint cannot be activated without `assigned_user_id` set (CHK-225: was `worktree_id`) |
+| 2 | `trg_enforce_standalone_task_workflow_invariants` | A standalone task cannot be moved to `in_progress` without `assigned_user_id` (CHK-225: was `assigned_worktree_id`) |
 | 3 | `trg_enforce_task_workflow_invariants` | ≤ 1 `in_progress` task per checkpoint |
 | 4 | `trg_enforce_single_in_progress_round_per_task` | ≤ 1 `in_progress` round per task |
-| 5 | `trg_enforce_single_active_scope_per_worktree` | ≤ 1 active (checkpoint OR standalone task) per worktree |
-| 6 | `trg_enforce_standalone_task_scope_per_worktree` | ≤ 1 `in_progress` standalone task per worktree |
+| 5 | `trg_enforce_single_active_scope_per_worktree` | ≤ 1 active (checkpoint OR standalone task) per `assigned_user_id` (CHK-225: was per `worktree_id`) |
+| 6 | `trg_enforce_standalone_task_scope_per_worktree` | ≤ 1 `in_progress` standalone task per `assigned_user_id` (CHK-225: was per `assigned_worktree_id`) |
 
 The worker is a passive cross-checker (`apps/todo-worker/src/invariants/check.ts`) — if its check disagrees with the DB, the DB wins.
 
@@ -34,7 +34,7 @@ MCP write → enqueueTodosJob → todos_jobs (status='pending')
                                   ↓
             worker claim_todos_job (SELECT … FOR UPDATE SKIP LOCKED)
                                   ↓
-              computeTodos(repo, worktree, user) → desired rows
+              computeTodos(repo, user) → desired rows
                                   ↓
             apply_todos RPC → todos table (status='current' / 'pending')
                                   ↓
@@ -71,7 +71,7 @@ The queue head (`get_todos` `rows[0]`) maps to one of these slash commands. The
 
 ## 5. Heartbeat policy
 
-The worker's `node-cron` heartbeat runs at `0 0 * * *` (UTC midnight). It enumerates every `(repo, worktree, user)` tuple with an active checkpoint OR in-progress standalone task and enqueues a `HEARTBEAT_SWEEP` todos_jobs row for each. This catches drift from missed `enqueueTodosJob` calls in MCP writers.
+The worker's `node-cron` heartbeat runs at `0 0 * * *` (UTC midnight). It enumerates every `(repo, user)` pair with an active checkpoint OR in-progress standalone task (via `assigned_user_id`) and enqueues a `HEARTBEAT_SWEEP` todos_jobs row for each. This catches drift from missed `enqueueTodosJob` calls in MCP writers.
 
 Backoff: a failed job retries at `now + 2^attempts minutes` (cap 60min). After 3 attempts, the job stays `failed` and the heartbeat picks it up again at the next sweep.
 
@@ -83,7 +83,6 @@ The shared enqueue helper lives at `packages/mcp-tools/src/tools/enqueue-todos.t
 enqueueTodosJob(
   client: SupabaseClient,
   repoId: string,
-  callerWorktreeId: string | undefined,
   userId: string | null,
   reason: string
 ): Promise<void>
@@ -108,6 +107,8 @@ Every workflow mutator MUST call `void enqueueTodosJob(...)` after the mutation
 
 CHK-111 shipped the original todos queue as Postgres triggers + a 583-LOC `regenerate_todos_for_repo` PL/pgSQL function. CHK-122 ported the regen to `apps/todo-worker` (Node) for shared infrastructure with `apps/docs-ingest` (CHK-116), easier testing, and per-user fanout. The 10 `trg_*_todos` triggers and the 4 `wrap_*` wrappers were dropped in migration `20260521000000_chk122_drop_legacy_todos_regen.sql`. The 6 BEFORE-UPDATE invariant triggers stayed.
 
+CHK-225 updated the invariant triggers from worktree-scoped to user-scoped (`assigned_user_id`). The trigger names were preserved for continuity; only the function bodies changed. Migration: `20260612000000_chk225_task1_user_locks.sql`.
+
 ## 8. Deployment — Railway
 
 `apps/todo-worker` runs as a Railway service alongside `apps/backend`. Setup:
@@ -119,3 +120,5 @@ CHK-111 shipped the original todos queue as Postgres triggers + a 583-LOC `regen
 5. Save the resulting `project_ref` to `.codebyplan.json` `shipment.surfaces.railway-todo-worker.project_ref`.
 
 Smoke after deploy: run `/cbp-finalize` in any worktree → tail Railway logs → expect a `claim → apply` cycle within `WORKER_POLL_MS`.
+
+**CHK-225 deploy note**: apply migration `20260612100000` (drops `worktree_id` from `todos` + `todos_jobs`, dedup todos rows, updates `apply_todos` RPC) BEFORE running `railway up` for the worker. Until the migration lands, the worker's 3-arg `apply_todos` call fails with a function-not-found error.

package/templates/rules/workflow-orchestration.md

@@ -0,0 +1,59 @@
+---
+description: Workflow tool — deterministic JS multi-agent orchestration for heavy fan-out. What it is, when to reach for it, the opt-in gate, and how it relates to ad-hoc Task/Agent spawning.
+---
+
+# Workflow Orchestration
+
+On-demand reference for the `Workflow` tool — the structured alternative to ad-hoc `Task`/`Agent`
+spawning when a step fans out across many independent units of work.
+
+## What It Is
+
+`Workflow` runs a deterministic JavaScript orchestration script that spawns and coordinates
+subagents. The control flow (loops, conditionals, fan-out) lives in the script, not in model
+judgement. Core primitives:
+
+- `agent(prompt, opts)` — spawn a subagent; with a `schema` it returns a validated structured
+  object instead of raw text.
+- `parallel(thunks)` — run tasks concurrently to a **barrier** (awaits all before returning).
+- `pipeline(items, ...stages)` — stream each item through stages with **no barrier** between them
+  (the default for multi-stage work — wall-clock is the slowest single chain, not sum-of-stages).
+- `phase(title)` / `log(message)` — progress grouping and narration.
+
+Built in: per-agent structured-output validation, a concurrency cap, a shared token budget,
+loop-until-done / loop-until-dry accumulation, and resume from a prior run.
+
+## When To Reach For It
+
+- **Many independent items** — a per-module sweep, a per-file migration, a per-surface deploy.
+- **Parallel waves with a barrier** — wave A must fully complete before wave B starts.
+- **Adversarial / multi-vote verification** — N independent reviewers vote to confirm a finding.
+- **Scale beyond one context** — coverage a single conversation cannot hold.
+
+Contrast: a single one-off subagent stays on the plain `Task`/`Agent` tool. Workflow's setup
+overhead only pays off at fan-out scale.
+
+## Opt-In Gate
+
+`Workflow` is **not** invoked by default. Reach for it only when one holds:
+
+- **ultracode** mode is active in the session (`/effort ultracode`) — under ultracode Claude
+  auto-reaches for Workflow on substantive fan-out tasks; **or**
+- the **user explicitly opts in** ("use a workflow", "fan out agents", "orchestrate this"); **or**
+- a skill or command's own instructions tell you to author one.
+
+Outside those, do NOT call `Workflow` — use the existing `Task`/`Agent` spawn, or describe what a
+workflow could do and ask first. The tool can spawn dozens of agents and is token-heavy — the scale
+must be requested, not inferred.
+
+## Relationship to Task/Agent Spawning
+
+`Task`/`Agent` spawning is the **default** for subagent work and is unchanged everywhere it is used.
+`Workflow` is the **structured alternative** for heavy fan-out — additive, not a replacement. A
+common shape is **hybrid**: scout inline first to discover the work-list, then author a `Workflow`
+that pipelines over it.
+
+## Related
+
+- `rules/effort-and-ultracode.md` — effort ladder, per-model support, and the session-only ultracode mode that auto-enables this orchestration path
+- `rules/model-invocation-convention.md` — model pinning in skill/agent frontmatter

package/templates/settings.project.base.json

@@ -66,7 +66,6 @@
       "mcp__codebyplan__create_project",
       "mcp__codebyplan__create_repo",
       "mcp__codebyplan__delete_session_log",
-      "mcp__codebyplan__delete_worktree",
       "mcp__codebyplan__release_assignment",
       "mcp__stripe__create_customer",
       "mcp__stripe__create_product",
@@ -161,7 +160,6 @@
       "mcp__codebyplan__get_task_templates",
       "mcp__codebyplan__get_tasks",
       "mcp__codebyplan__get_todos",
-      "mcp__codebyplan__get_worktrees",
       "mcp__codebyplan__list_tech_stack_sync_sessions",
       "mcp__codebyplan__get_chunk",
       "mcp__codebyplan__get_library_toc",
@@ -183,7 +181,6 @@
       "mcp__codebyplan__create_session_log",
       "mcp__codebyplan__update_session_log",
       "mcp__codebyplan__update_session_state",
-      "mcp__codebyplan__create_worktree",
       "mcp__codebyplan__flag_stale_chunk",
       "mcp__codebyplan__update_eslint_repo_config",
       "mcp__codebyplan__update_server_config",
@@ -196,8 +193,6 @@
       "Bash(npx codebyplan supabase:*)",
       "Bash(codebyplan whoami:*)",
       "Bash(npx codebyplan whoami:*)",
-      "Bash(codebyplan resolve-worktree:*)",
-      "Bash(npx codebyplan resolve-worktree:*)",
       "Bash(codebyplan version-status:*)",
       "Bash(npx codebyplan version-status:*)",
       "Bash(codebyplan worktree:*)",

package/templates/skills/cbp-build-cc-agent/SKILL.md

@@ -3,6 +3,7 @@ name: cbp-build-cc-agent
 description: Build a Claude Code subagent at .claude/agents/{name}.md (flat form, per the official sub-agents spec) following the official sub-agents spec (frontmatter, tools, model, hooks, skills preload, permission modes, isolation).
 argument-hint: "[agent-name] [--scope=project|user] [--isolation=worktree]"
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir *), Bash(chmod *)
+model: inherit
 effort: xhigh
 ---
 

package/templates/skills/cbp-build-cc-claude-file/SKILL.md

@@ -3,6 +3,7 @@ name: cbp-build-cc-claude-file
 description: Create or update a CLAUDE.md file at any scope (managed, project, user, local) following the official memory spec — imports (@path), nested discovery, AGENTS.md bridge, comment stripping, and claudeMdExcludes.
 argument-hint: "[action] [--scope=managed|project|user|local]"
 allowed-tools: Read, Write, Edit, Glob, Grep
+model: inherit
 effort: xhigh
 ---