codebyplan 1.13.62 → 1.13.64

package/package.json

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

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

@@ -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/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-skill-context-guard.sh

@@ -1,11 +1,16 @@
 #!/bin/bash
 # @scope: org-shared
 # Hook: PreToolUse (Skill)
-# Purpose: Deny heavy close-out skills when context window > CBP_CONTEXT_WARN_TOKENS (default 200000).
-#          Reads transcript_path from stdin, sums the latest assistant message.usage — same logic
-#          as cbp-context-window-notify.sh. If total exceeds threshold AND the skill is in the
-#          heavy close-out allowlist, emits hookSpecificOutput.permissionDecision=deny directing
-#          Claude to run /cbp-clear-prep. Always exits 0 — fail-open.
+# Purpose: Deny heavy close-out skills when context window exceeds the model-aware threshold:
+#          200K tokens for standard models (CBP_CONTEXT_WARN_TOKENS, default 200000);
+#          800K tokens for 1M-context models whose id contains "[1m]"
+#          (CBP_CONTEXT_WARN_TOKENS_1M, default 800000).
+#          Reads transcript_path from stdin, extracts the latest assistant message.usage
+#          AND model id in one pass — same logic as cbp-context-window-notify.sh.
+#          If total exceeds the tier threshold AND the skill is in the heavy close-out
+#          allowlist, emits hookSpecificOutput.permissionDecision=deny directing Claude
+#          to run /cbp-clear-prep. Always exits 0 — fail-open.
+#          No model id found → standard tier (fail-conservative).
 
 set -euo pipefail
 
@@ -17,8 +22,6 @@ TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null) || TRAN
 [ -z "$TRANSCRIPT" ] && exit 0
 [ ! -f "$TRANSCRIPT" ] && exit 0
 
-THRESHOLD="${CBP_CONTEXT_WARN_TOKENS:-200000}"
-
 # Heavy close-out allowlist (cbp-clear-prep + cbp-clear-continue deliberately excluded so
 # they always run even when context > threshold).
 HEAVY_SKILLS="cbp-round-build cbp-verify cbp-standalone-task-testing cbp-checkpoint-check cbp-checkpoint-end"
@@ -33,20 +36,37 @@ for heavy in $HEAVY_SKILLS; do
 done
 [ "$IS_HEAVY" = "false" ] && exit 0
 
-# Token sum — same logic as cbp-context-window-notify.sh
-TOTAL=$(tail -n 400 "$TRANSCRIPT" \
+# Extract model id AND token sum from the latest assistant message with usage, in one pass.
+# Outputs two tab-separated fields: MODEL_ID <tab> TOTAL.
+# Use cut -f1/f2 (not read -r A B) to correctly handle an empty first field (no .message.model).
+_TSV=$(tail -n 400 "$TRANSCRIPT" \
   | jq -rR 'fromjson? | select(.message.usage != null)
-      | (.message.usage
-         | ((.input_tokens // 0) + (.cache_creation_input_tokens // 0) + (.cache_read_input_tokens // 0)))' \
-  2>/dev/null | tail -1) || TOTAL=0
+      | [ (.message.model // ""),
+          ((.message.usage.input_tokens // 0)
+           + (.message.usage.cache_creation_input_tokens // 0)
+           + (.message.usage.cache_read_input_tokens // 0)) ]
+      | @tsv' 2>/dev/null | tail -1) || _TSV=""
+MODEL_ID=$(printf '%s' "${_TSV:-}" | cut -f1)
+TOTAL=$(printf '%s' "${_TSV:-}" | cut -f2)
+MODEL_ID="${MODEL_ID:-}"
 TOTAL="${TOTAL:-0}"
 
+# Tier selection: [1m] in model id → 1M tier; otherwise standard (fail-conservative)
+if printf '%s' "$MODEL_ID" | grep -qF '[1m]'; then
+  THRESHOLD="${CBP_CONTEXT_WARN_TOKENS_1M:-800000}"
+  TIER="1M"
+else
+  THRESHOLD="${CBP_CONTEXT_WARN_TOKENS:-200000}"
+  TIER="standard"
+fi
+
 if [ "$TOTAL" -ge "$THRESHOLD" ] 2>/dev/null; then
   jq -n \
     --argjson tokens "$TOTAL" \
     --argjson threshold "$THRESHOLD" \
     --arg skill "$SKILL_NAME" \
-    '{hookSpecificOutput:{permissionDecision:"deny",permissionDecisionReason:("Context window at \($tokens) tokens (threshold \($threshold)) is too large to safely run /\($skill). Run /cbp-clear-prep now to capture a handoff, then /clear, then /cbp-clear-continue to resume.")}}'
+    --arg tier "$TIER" \
+    '{hookSpecificOutput:{permissionDecision:"deny",permissionDecisionReason:("Context window at \($tokens) tokens (\($tier) tier, threshold \($threshold)) is too large to safely run /\($skill). Run /cbp-clear-prep now to capture a handoff, then /clear, then /cbp-clear-continue to resume.")}}'
 fi
 
 exit 0

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

@@ -614,6 +614,91 @@ else
 
 fi
 
+echo ""
+
+# ===== HOOK SMOKE TESTS — cbp-skill-context-guard model-aware tier (CHK-224) =====
+echo "## Hook Smoke Tests — cbp-skill-context-guard model-aware tier (CHK-224)"
+
+FIXTURES_GUARD_MODEL="$HOOKS_DIR/__test-fixtures__/cbp-skill-context-guard"
+
+# Case M1: standard model @201K → deny (standard tier, 200K threshold)
+if [ -f "$FIXTURES_GUARD_MODEL/over-threshold-standard.jsonl" ]; then
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD_MODEL/over-threshold-standard.jsonl" \
+    --arg s "cbp-round-build" \
+    '{transcript_path:$t,tool_input:{skill:$s}}')
+  OUTPUT=$(echo "$STDIN" | CBP_CONTEXT_WARN_TOKENS=200000 bash "$GUARD_HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] \
+     && echo "$OUTPUT" | jq -e '.hookSpecificOutput.permissionDecision == "deny"' >/dev/null 2>&1; then
+    test_result "cbp-skill-context-guard.sh standard model @201K → deny (standard tier)" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh standard model @201K → deny (standard tier)" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+  fi
+fi
+
+# Case M2: [1m] model @201K → empty stdout (allowed; 201K is below 800K 1M-tier threshold)
+if [ -f "$FIXTURES_GUARD_MODEL/over-threshold-1m.jsonl" ]; then
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD_MODEL/over-threshold-1m.jsonl" \
+    --arg s "cbp-round-build" \
+    '{transcript_path:$t,tool_input:{skill:$s}}')
+  OUTPUT=$(echo "$STDIN" | CBP_CONTEXT_WARN_TOKENS_1M=800000 bash "$GUARD_HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-skill-context-guard.sh [1m] model @201K → empty stdout (under 800K 1M tier)" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh [1m] model @201K → empty stdout (under 800K 1M tier)" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+  fi
+fi
+
+# Case M3: [1m] model @850K → deny (1M tier, 800K threshold)
+if [ -f "$FIXTURES_GUARD_MODEL/over-threshold-1m-denied.jsonl" ]; then
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD_MODEL/over-threshold-1m-denied.jsonl" \
+    --arg s "cbp-round-build" \
+    '{transcript_path:$t,tool_input:{skill:$s}}')
+  OUTPUT=$(echo "$STDIN" | CBP_CONTEXT_WARN_TOKENS_1M=800000 bash "$GUARD_HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] \
+     && echo "$OUTPUT" | jq -e '.hookSpecificOutput.permissionDecision == "deny"' >/dev/null 2>&1; then
+    test_result "cbp-skill-context-guard.sh [1m] model @850K → deny (1M tier)" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh [1m] model @850K → deny (1M tier)" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+  fi
+fi
+
+# Case M4: env override CBP_CONTEXT_WARN_TOKENS=150000 + standard model @201K → deny
+if [ -f "$FIXTURES_GUARD_MODEL/over-threshold-standard.jsonl" ]; then
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD_MODEL/over-threshold-standard.jsonl" \
+    --arg s "cbp-round-build" \
+    '{transcript_path:$t,tool_input:{skill:$s}}')
+  OUTPUT=$(echo "$STDIN" | CBP_CONTEXT_WARN_TOKENS=150000 bash "$GUARD_HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] \
+     && echo "$OUTPUT" | jq -e '.hookSpecificOutput.permissionDecision == "deny"' >/dev/null 2>&1; then
+    test_result "cbp-skill-context-guard.sh env CBP_CONTEXT_WARN_TOKENS=150000 + standard @201K → deny" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh env CBP_CONTEXT_WARN_TOKENS=150000 + standard @201K → deny" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+  fi
+fi
+
+# Case M5: env override CBP_CONTEXT_WARN_TOKENS_1M=900000 + [1m] model @850K → empty stdout (allowed)
+if [ -f "$FIXTURES_GUARD_MODEL/over-threshold-1m-denied.jsonl" ]; then
+  STDIN=$(jq -n \
+    --arg t "$FIXTURES_GUARD_MODEL/over-threshold-1m-denied.jsonl" \
+    --arg s "cbp-round-build" \
+    '{transcript_path:$t,tool_input:{skill:$s}}')
+  OUTPUT=$(echo "$STDIN" | CBP_CONTEXT_WARN_TOKENS_1M=900000 bash "$GUARD_HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-skill-context-guard.sh env CBP_CONTEXT_WARN_TOKENS_1M=900000 + [1m] @850K → empty stdout (override keeps allowed)" "passed" "passed"
+  else
+    test_result "cbp-skill-context-guard.sh env CBP_CONTEXT_WARN_TOKENS_1M=900000 + [1m] @850K → empty stdout (override keeps allowed)" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+  fi
+fi
+
 # ===== STRUCTURAL ASSERTIONS — cbp-clear-* skills (CHK-217) =====
 echo ""
 echo "## Structural Assertions — cbp-clear-* skills (CHK-217)"

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/architecture-map.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - "apps/**"
+  - "packages/**"
+---
+
 # Architecture Map
 
 When `.claude/architecture/` exists in this repo, per-module map files may be present.

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

@@ -38,7 +38,9 @@ SHARED tooling behavior only — repo-specific gotchas belong in that repo's own
 - **`complete_task` checks file approval on the round's `files_changed`, not the task's.**
   Reconcile approvals via `update_round` (set each entry `user_approved: true`), not
   `update_task` alone — updating only the task leaves the round entries unapproved and
-  `complete_task` rejects with "files are not approved".
+  `complete_task` rejects with "files are not approved". After a merge-main pulls in foreign
+  files or carried directory-slash round artifacts, `complete_task` can hard-fail "N files not
+  approved"; fix by re-writing each affected round's `files_changed` via `update_round`.
 
 - **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`.
 
@@ -50,6 +52,16 @@ SHARED tooling behavior only — repo-specific gotchas belong in that repo's own
 
 - **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.
 
+- **MCP write calls can return 403 via Cloudflare WAF when the JSONB payload contains DDL
+  keywords (table-drop statements, function-drop statements, or raw query clauses).** Paraphrase
+  or base64-encode any user-provided SQL content before embedding it in a JSONB field — never
+  pass raw DDL verbatim in MCP context payloads.
+
+- **A "Merge origin/main" commit can integrate ZERO commits if it merged a stale local ref.**
+  Always `git fetch` and re-check the behind-count before treating a merge as complete — a
+  clean merge with no new commits is a sign the local ref was stale, not that the branch was
+  already up to date.
+
 ## Behavioral Preferences
 
 - **Never `git stash`** — for any reason. To inspect or compare other state use

package/templates/rules/e2e-mandatory.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - "apps/**"
+---
+
 # E2E Mandatory Run Contract
 
 E2E is **opt-out, not opt-in**. Whenever a framework configured in `.codebyplan/e2e.json`

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

@@ -32,7 +32,7 @@ not via `disable-model-invocation`:
    under what condition, so the intent is auditable and overridable.
 
 See `.claude/skills/cbp-build-cc-settings/reference/cbp-permission-policy.md` for the full
-`allow` vs `ask` split and the auto-trigger + 200K context-guard model.
+`allow` vs `ask` split and the auto-trigger + model-aware context-guard (200K standard / 800K on `[1m]` sessions).
 
 ## Related
 

package/templates/rules/scope-vocabulary.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - ".claude/**"
+---
+
 # Scope Vocabulary
 
 Canonical scope-marker enum for `.claude/` files. The marker classifies a structural file's distribution scope — but it is **required only on user-created files**, not on the assets the `codebyplan` package distributes.

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/task-routing-recommendation.md

@@ -45,7 +45,7 @@ After task completion, routes use single-directive form (never A/B/C menus):
 
 **Checkpoint-bound task complete:**
 - More tasks in checkpoint → auto-triggers next task (same context)
-- Last task in checkpoint → auto-triggers `cbp-checkpoint-check` (ask-tier permission prompt is the human gate; the 200K context guard handles oversized contexts)
+- Last task in checkpoint → auto-triggers `cbp-checkpoint-check` (ask-tier permission prompt is the human gate; the model-aware context guard handles oversized contexts — 200K standard, 800K on `[1m]` sessions)
 
 **Standalone task complete:**
 - Always → `Next: /cbp-session-end` (or `/cbp-standalone-task-create` for new work)

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/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",
@@ -148,23 +147,16 @@
       "mcp__codebyplan__get_checkpoints",
       "mcp__codebyplan__get_current_task",
       "mcp__codebyplan__get_eslint_presets",
-      "mcp__codebyplan__get_eslint_repo_config",
       "mcp__codebyplan__get_file_changes",
-      "mcp__codebyplan__get_library_doc_job",
       "mcp__codebyplan__get_repos",
       "mcp__codebyplan__get_rounds",
       "mcp__codebyplan__get_server_config",
       "mcp__codebyplan__get_session_log",
       "mcp__codebyplan__get_session_logs",
       "mcp__codebyplan__get_session_state",
-      "mcp__codebyplan__get_task_template",
-      "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",
       "mcp__codebyplan__list_migrations",
       "mcp__codebyplan__lookup_symbol",
       "mcp__codebyplan__resolve_library_id",
@@ -183,11 +175,18 @@
       "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",
-      "mcp__codebyplan__update_task_template",
+      "mcp__codebyplan__get_standalone_tasks",
+      "mcp__codebyplan__get_current_standalone_task",
+      "mcp__codebyplan__get_standalone_rounds",
+      "mcp__codebyplan__create_standalone_task",
+      "mcp__codebyplan__update_standalone_task",
+      "mcp__codebyplan__complete_standalone_task",
+      "mcp__codebyplan__add_standalone_round",
+      "mcp__codebyplan__update_standalone_round",
+      "mcp__codebyplan__complete_standalone_round",
       "Bash(codebyplan check:*)",
       "Bash(npx codebyplan check:*)",
       "Bash(codebyplan session:*)",
@@ -196,8 +195,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

@@ -77,6 +77,7 @@ Check each against the task and include only when they add value:
 | Background execution | `background: true`                                              | Agent should always run concurrently                   |
 | Bounded turns        | `maxTurns: N`                                                   | Cap runaway loops                                      |
 | Subagent spawning    | `tools: Agent(worker, researcher)`                              | Only if run as main thread via `--agent`               |
+| Memory store         | `memory: user \| project \| local`                              | Which memory store the agent reads/writes              |
 
 Cross-references for complex cases:
 
@@ -136,5 +137,7 @@ Report:
 - Subagents cannot spawn other subagents — the `Agent` tool only applies when the agent runs as the main thread
 - `bypassPermissions` and `acceptEdits` inherited from the parent cannot be weakened by the child
 - Preloaded skills inject _full content_ at startup — don't preload `disable-model-invocation: true` skills
+- `Task(` was renamed to `Agent(` in v2.1.63 — use `Agent(...)` in `tools:` allowlists; `Task()` is a stale alias that still works but should not appear in new agents
+- Plugin agents (`.claude/agents/`) ignore `hooks`, `mcpServers`, and `permissionMode` — these fields parse without error but have no runtime effect for plugin agents
 - Restart the session or use `/agents` to load a newly written agent file
 - Flat form `.claude/agents/{name}.md` is the default and matches all 12 existing CBP agents; folder form `{name}/AGENT.md` is optional and only for agents that bundle supporting files alongside them

package/templates/skills/cbp-build-cc-agent/reference/frontmatter-fields.md

@@ -18,6 +18,7 @@ Source: official Claude Code sub-agents spec. Only `name` and `description` are
 | `effort` | string | `low` \| `medium` \| `high` \| `xhigh` \| `max`. **Plugin agents authored in CBP MUST set this explicitly** (no commented-out placeholder); see [/cbp-build-cc-mode](../../build-cc-mode/SKILL.md) for the matrix |
 | `isolation` | string | `worktree` — gives the agent a temporary git worktree |
 | `color` | string | `red` \| `blue` \| `green` \| `yellow` \| `purple` \| `orange` \| `pink` \| `cyan` |
+| `memory` | string | Which memory store the agent reads/writes: `user` \| `project` \| `local` |
 | `initialPrompt` | string | Auto-submitted first user turn when the agent is the main session agent |
 
 ## Tool-allowlist special forms
@@ -34,3 +35,33 @@ Source: official Claude Code sub-agents spec. Only `name` and `description` are
 2. Per-invocation `model` parameter passed by Claude
 3. The `model` field in this file
 4. Main conversation's model
+
+## Task( → Agent( rename (v2.1.63)
+
+The `Agent` tool replaces the older `Task` tool. `Task()` still works as a stale alias but new agents should use `Agent(...)` in their `tools:` allowlists. Example: `tools: Agent(worker, researcher)` — not `Task(worker, researcher)`. The runtime accepts both forms; prefer `Agent`.
+
+## Plugin agent limitations
+
+Plugin agents (those defined in `.claude/agents/`) ignore the following fields — they are parsed without error but have **no runtime effect**:
+
+- `hooks` — lifecycle hooks are silently no-opped for plugin agents
+- `mcpServers` — scoped MCP server definitions are ignored
+- `permissionMode` — the parent session's permission mode applies unchanged; the child cannot set its own
+
+This is distinct from agents run as the main thread via `claude --agent`, where these fields take full effect.
+
+## Skills-preload constraint
+
+Skills listed in `skills:` are preloaded — their full content is injected into the agent's context at startup. Do NOT preload skills that carry `disable-model-invocation: true`. A preloaded skill with that flag is loaded at startup but can never be invoked at runtime, so its content wastes context and its intent cannot be fulfilled.
+
+## CBP-only fields (not read by Claude Code)
+
+`scope:` is **CBP framework metadata** — it is NOT part of the official Claude Code sub-agents spec and is not read by the Claude Code runtime. It declares the agent's distribution class:
+
+| Value | Meaning |
+|-------|---------|
+| `org-shared` | Ships identically to every consuming repo via the `codebyplan` package |
+| `project-shared` | Shared across repos in a single project family |
+| `repo-only:<name>` | Bound to one repo; `<name>` is the repo slug |
+
+Required only on user-created agents (no template twin). Package-managed agents are `org-shared` by default — no marker needed. See [rules/scope-vocabulary.md](../../../../rules/scope-vocabulary.md).

package/templates/skills/cbp-build-cc-agent/reference/permission-modes.md

@@ -16,3 +16,9 @@ Source: official Claude Code sub-agents and permission-modes specs.
 - If parent is `bypassPermissions` or `acceptEdits`, child cannot weaken it
 - If parent is `auto`, child inherits `auto` and its `permissionMode` is ignored
 - Otherwise the child's `permissionMode` takes effect as declared
+
+## Plugin agents
+
+Plugin agents (those defined in `.claude/agents/` and loaded by the runtime, not run via `claude --agent`) **ignore `permissionMode` entirely**. The field is valid YAML and parses without error, but has no runtime effect — the parent session's permission mode applies unchanged.
+
+Likewise, `hooks` and `mcpServers` are ignored for plugin agents regardless of the parent session's permission mode. These fields only take effect when the agent runs as the main thread via `claude --agent`.

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

@@ -6,6 +6,7 @@ tools: Read, Grep, Glob, Bash
 # disallowedTools: Write, Edit  # alternative to tools — inherits then removes
 # review with /cbp-build-cc-mode if defaults don't fit this agent's purpose
 model: sonnet
+# memory: user  # user | project | local — which memory store this agent reads/writes
 # permissionMode: default  # default | acceptEdits | auto | dontAsk | bypassPermissions | plan
 # maxTurns: 20
 effort: xhigh

package/templates/skills/cbp-build-cc-settings/reference/cbp-permission-policy.md

@@ -24,7 +24,7 @@ Precedence is `deny > ask > allow`; arrays union across scopes (managed/user/pro
 
 - **Non-lifecycle, non-shipment `/cbp-*` skills** — authoring (`cbp-build-cc-*`), frontend (`cbp-frontend-*`), git (`cbp-git-*`, `cbp-merge-main`, `cbp-refresh-infra`), round work (`cbp-round-plan`, `cbp-verify` — `cbp-verify` is the autonomous verify stage that runs deterministic gates, proves execution, spawns the fresh-context reviewer, and routes to `cbp-round-complete` or `cbp-round-plan`, so it runs without a prompt), setup/configure (`cbp-setup-*`, `cbp-ship-configure`, `cbp-supabase-*`), task prep (`cbp-task-create`/`-start`, `cbp-standalone-task-check`/`-testing`), planning (`cbp-checkpoint-plan`/`-update`), plus `cbp-session-start` and `cbp-todo`. Invoking a skill is the intended mode of operation; the gated side effects happen inside via the Bash/MCP tools the skill calls, which carry their own tiering. The lifecycle/state-transition and plan-approval skills are the exception — they live in `ask` (next section).
 - **All `mcp__codebyplan__*` reads** (`get_*`, `list_*`, `search_*`, `health_check`, `lookup_symbol`, `resolve_library_id`, `get_chunk`).
-- **Routine workflow-write MCP tools** the pipeline calls many times per task: create/update/complete checkpoint, task, and round; session log + session-state writes; `create_worktree`, `add_library`, `flag_stale_chunk`, `update_server_config`, `update_eslint_repo_config`, `update_task_template`. Gating these with `ask` would make the autonomous workflow unusable.
+- **Routine workflow-write MCP tools** the pipeline calls many times per task: create/update/complete checkpoint, task, and round; session log + session-state writes; `create_worktree`, `add_library`, `flag_stale_chunk`, `update_server_config`, `update_eslint_repo_config`. Gating these with `ask` would make the autonomous workflow unusable.
 - **Read/safe CLI commands** (both `codebyplan X` and `npx codebyplan X`): `whoami`, `resolve-worktree`, `statusline`, `ports`, `tech-stack`, `eslint`, `round`, `help`, `--version`.
 
 ### `ask` — the deliberate confirm-gate
@@ -66,11 +66,18 @@ This means:
 - A skill in `ask` that is auto-triggered shows a permission prompt — that prompt is the gate;
   say so in the routing prose.
 
-### The 200K context guard
+### The model-aware context guard
 
 The `cbp-skill-context-guard.sh` PreToolUse hook denies heavy close-out skills when the
-context window exceeds `CBP_CONTEXT_WARN_TOKENS` (default 200 000 tokens). The heavy allowlist
-is: `cbp-round-build`, `cbp-verify`, `cbp-standalone-task-testing`,
+context window exceeds the model-aware threshold:
+
+- **Standard models**: `CBP_CONTEXT_WARN_TOKENS` (default 200 000 tokens)
+- **1M-context models** (model id contains `[1m]`): `CBP_CONTEXT_WARN_TOKENS_1M` (default 800 000 tokens)
+
+When no model id is found in the transcript the hook fails conservative to the standard 200K
+tier. Each env var overrides only its own tier — the other tier is unaffected.
+
+The heavy allowlist is: `cbp-round-build`, `cbp-verify`, `cbp-standalone-task-testing`,
 `cbp-checkpoint-check`, `cbp-checkpoint-end`.
 
 When the guard fires, it directs the model to run `/cbp-clear-prep` instead. The flow is: