codebyplan 1.13.29 → 1.13.31

package/package.json

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

package/templates/README.md

@@ -1,20 +1,23 @@
-# Templates
+# .claude/
 
-This directory holds the installed content that the `codebyplan claude install` subcommand places into a consuming project's `./.claude/` directory. Skills, agents, and hooks live here.
+This directory is **managed by the `codebyplan` package** and refreshed by:
 
-## Authoring source
+```sh
+npx codebyplan claude update
+```
 
-`packages/codebyplan-package/templates/` is the single source of truth for all `.claude/` content. The sibling-identity gate (CHK-134) requires that every edit to `templates/` is mirrored to `.claude/` in the same commit — there is no special "canonical worktree". Every worktree running this repo consumes updates via `npx codebyplan claude install|update`; release-please publishes the `codebyplan` npm package on merge to main, which propagates changes to consuming repos.
+## Do not hand-edit managed files
 
-## Layout
+Files installed here (skills, agents, hooks, rules) are owned by the `codebyplan` package. Running `codebyplan claude update` will overwrite any local changes to managed files.
 
-| Path      | Count                                | Shape                                                                                           |
-| --------- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `skills/` | 41 folders                           | each is a `SKILL.md` plus optional `templates/`, `reference/`, `examples/`, `scripts/` siblings |
-| `agents/` | 16 files                             | flat `.md` agent prompts (NOT `AGENT.md` subdirs)                                               |
-| `hooks/`  | 20 `.sh` + `hooks.json` + `README.md` | event hooks and manifest                                                                        |
-| `rules/`  | 1+ files                             | flat `<name>.md` rule files; see `rules/README.md` for bar and format                           |
+To change managed behaviour, make the change upstream in the `codebyplan` package and publish a new version.
 
-## This directory IS the source of truth
+## Repo-specific additions
 
-Edit files in this directory directly. There is no upstream tree — CHK-111 TASK-10 retired the prior in-monorepo plugin distribution path and replaced rsync-based distribution with an npm publish lifecycle. CHK-132 then consolidated that lifecycle into the merged `codebyplan` package; the assets now ship as the `claude` subcommand group (`install` / `update` / `uninstall`).
+Additions that belong only to this repo go in repo-scoped files that `codebyplan` does not touch:
+
+- **Root `CLAUDE.md`** — repo-level context and instructions always loaded by Claude Code.
+- **`rules/` files with `scope: repo-only:<repo-name>`** — behavioral constraints specific to this repo.
+- **`context/` and `docs/`** — repo-specific reference material referenced by your own agents or skills.
+
+Repo-scoped files coexist with managed files and are never overwritten by `codebyplan claude update`.

package/templates/agents/cbp-cc-executor.md

@@ -1,7 +1,7 @@
 ---
 scope: org-shared
 name: cbp-cc-executor
-description: Authoring executor for `.claude/` infrastructure. Applies approved changes across rules, skills, agents, context, CLAUDE.md, settings, hooks, and auto-memory — with update-first discipline, scope-marker enforcement, and length-limit awareness. Callable by the main conversation, `/cbp-checkpoint-end`, and `round-executor` (for in-scope `.claude/` infra deliverables).
+description: Authoring executor for `.claude/` infrastructure. Applies approved changes across rules, skills, agents, context, CLAUDE.md, settings, and hooks — with update-first discipline, scope-marker enforcement, and length-limit awareness. Callable by the main conversation, `/cbp-checkpoint-end`, and `round-executor` (for in-scope `.claude/` infra deliverables).
 tools: Read, Write, Edit, Glob, Grep, Skill, Task, AskUserQuestion, mcp__codebyplan__create_task
 model: sonnet
 effort: xhigh
@@ -40,7 +40,7 @@ input:
   source: 'main' | 'checkpoint-end' | 'round-executor'  # additional internal sources may exist in your CBP setup; extend as needed
   changes:
     - id: string | number
-      type: 'rule' | 'skill' | 'agent' | 'context' | 'architecture' | 'CLAUDE.md' | 'settings' | 'hook' | 'memory'
+      type: 'rule' | 'skill' | 'agent' | 'context' | 'architecture' | 'CLAUDE.md' | 'settings' | 'hook'
       target: string                 # Path under .claude/ (or CLAUDE.md)
       action: 'create' | 'update' | 'delete'
       description: string            # What the change is
@@ -121,13 +121,12 @@ Per validated change, route to the correct authoring path:
 | CLAUDE.md    | `/cbp-build-cc-claude-file` (only for a non-root CLAUDE.md — root exists) | Direct Edit                                                      |
 | settings     | `/cbp-build-cc-settings`                                                  | `/cbp-build-cc-settings` (schema-critical — always route) |
 | hook         | Direct Write with `# @scope:` header                                             | Direct Edit                                                      |
-| memory       | `/cbp-build-cc-memory`                                                    | `/cbp-build-cc-memory` (MEMORY.md index must update)      |
 
 Routing rules:
 
 - **Creates always go through the build-cc skill** when one exists — the skill embeds the signature (`scope:` / `$schema:` / `type:`) the build-cc skills require.
 - **Updates use direct Edit** on already-signed files. The signature travels with the file; editing preserves it.
-- **Settings and memory always route** — their schema/index semantics are non-trivial.
+- **Settings always route** — their schema semantics are non-trivial.
 
 Record every applied change with `authored_via` and `status`.
 
@@ -143,9 +142,8 @@ Record every applied change with `authored_via` and `status`.
 After all changes applied:
 
 1. For every touched file, re-check: still within length limit? scope marker still present?
-2. If `MEMORY.md` touched: index lines ≤200 chars? No duplicate names?
-3. If `settings.json` touched: valid JSON? Re-read the file and validate syntax — matched braces/brackets, quoted keys, no trailing commas. Reject the change if invalid.
-4. Report any drift as `status: 'partial'` and list in `applied_changes[].note`.
+2. If `settings.json` touched: valid JSON? Re-read the file and validate syntax — matched braces/brackets, quoted keys, no trailing commas. Reject the change if invalid.
+3. Report any drift as `status: 'partial'` and list in `applied_changes[].note`.
 
 ### Phase 6: Return
 
@@ -164,7 +162,6 @@ Every managed file must carry its scope marker — checked by `validate-structur
 | agent        | `scope: {value}`                               | YAML frontmatter |
 | hook         | `# @scope: {value}`                            | Header comment   |
 | settings     | `$schema: {url}` (implicit scope via filename) | JSON field       |
-| memory       | `type: {user\|feedback\|project\|reference}`   | YAML frontmatter |
 | context      | _(signatureless)_                              | n/a              |
 | architecture | _(signatureless)_                              | n/a              |
 | CLAUDE.md    | _(plain markdown)_                             | n/a              |
@@ -208,6 +205,6 @@ Block-limit violations are non-negotiable — split before applying.
 - **Spawned by**: main conversation (ad-hoc), `/cbp-checkpoint-end` (future), `round-executor` (in-scope `.claude/` infra deliverables, `source: 'round-executor'`)
 - **Reads**: `.claude/` inventory, `validate-structure-lengths.sh`, target files
 - **Writes**: `.claude/` files (via `/cbp-build-cc-*` skills for creates, direct Edit for updates)
-- **Calls skills**: `/cbp-build-cc-rule`, `/cbp-build-cc-skill`, `/cbp-build-cc-claude-file`, `/cbp-build-cc-settings`, `/cbp-build-cc-memory`
+- **Calls skills**: `/cbp-build-cc-rule`, `/cbp-build-cc-skill`, `/cbp-build-cc-claude-file`, `/cbp-build-cc-settings`
 - **Creates tasks**: via MCP `create_task` when a change exceeds invocation scope
 - **Enforced by**: `validate-structure-lengths.sh` (length), `validate-structure-scope.sh` (scope marker), `validate-structure-patterns.sh` (path layout)

package/templates/agents/cbp-round-executor.md

@@ -98,7 +98,7 @@ output:
 
 **Key Principle:** If something is unclear or you're blocked, ASK the user. Don't make assumptions.
 
-**Routing Principle:** For managed files requiring routing commands (`/cbp-build-cc-rule`, `/cbp-build-cc-agent`, `/cbp-build-cc-skill`, `/cbp-build-cc-claude-file`, `/cbp-build-cc-settings`, `/cbp-build-cc-memory`), use Skill tool. For other managed files (templates, architecture, research, stack docs), use direct Write/Edit.
+**Routing Principle:** For managed files requiring routing commands (`/cbp-build-cc-rule`, `/cbp-build-cc-agent`, `/cbp-build-cc-skill`, `/cbp-build-cc-claude-file`, `/cbp-build-cc-settings`), use Skill tool. For other managed files (templates, architecture, research, stack docs), use direct Write/Edit.
 
 ## Execution Workflow
 
@@ -124,7 +124,6 @@ Skill tool: skill="cbp-build-cc-agent"        # for .claude/agents/
 Skill tool: skill="cbp-build-cc-skill"        # for .claude/skills/
 Skill tool: skill="cbp-build-cc-claude-file"  # for .claude/CLAUDE.md
 Skill tool: skill="cbp-build-cc-settings"     # for .claude/settings*.json
-Skill tool: skill="cbp-build-cc-memory"       # for ~/.claude/projects/<project>/memory/
 Direct Write/Edit                          # for templates, docs/
 ```
 

package/templates/hooks/cbp-mcp-caller-worktree-inject.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# @scope: org-shared
+# @hook: PreToolUse 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)
+# Hook: PreToolUse for MCP write tools
+#
+# Purpose: Inject caller_worktree_id into MCP mutation tool inputs when the
+#          field is absent. Reads the worktree.local.json branch-keyed cache
+#          first (fast path); falls back to `codebyplan resolve-worktree --cache`.
+#
+# Fail-open: ALL exit paths exit 0. A hook failure must never block a tool call.
+#            Use explicit guards rather than set -euo pipefail (which would exit
+#            non-zero on the first failing command before the final exit 0).
+
+# C0 — require jq; if absent, emit nothing and exit 0 (fail-open).
+if ! command -v jq > /dev/null 2>&1; then
+  exit 0
+fi
+
+# Read stdin once into a variable.
+INPUT=$(cat)
+
+# C6 — if caller_worktree_id is already a non-empty string, do not overwrite.
+# (jq '// empty' already maps JSON null to an empty string, so a plain -n test suffices.)
+EXISTING=$(echo "$INPUT" | jq -r '.tool_input.caller_worktree_id // empty' 2>/dev/null)
+if [ -n "$EXISTING" ]; then
+  # Already populated — plain allow (exit 0 with no output).
+  exit 0
+fi
+
+# C5 — resolve worktree id, fast path first.
+RESOLVED_WT=""
+
+# Determine repo root: prefer $CLAUDE_PROJECT_DIR, fall back to PWD.
+REPO_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+CACHE_FILE="$REPO_ROOT/.codebyplan/worktree.local.json"
+
+if [ -f "$CACHE_FILE" ]; then
+  CACHED_WT=$(jq -r '.worktree_id // empty' "$CACHE_FILE" 2>/dev/null)
+  CACHED_BRANCH=$(jq -r '.branch // empty' "$CACHE_FILE" 2>/dev/null)
+
+  if [ -n "$CACHED_WT" ] && [ "$CACHED_WT" != "null" ] && \
+     [ -n "$CACHED_BRANCH" ] && [ "$CACHED_BRANCH" != "null" ]; then
+    # Validate branch matches current git branch.
+    CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+    if [ -n "$CURRENT_BRANCH" ] && [ "$CURRENT_BRANCH" = "$CACHED_BRANCH" ]; then
+      RESOLVED_WT="$CACHED_WT"
+    fi
+  fi
+fi
+
+# Fallback to CLI resolution if cache miss or branch mismatch.
+if [ -z "$RESOLVED_WT" ]; then
+  RESOLVED_WT=$(codebyplan resolve-worktree --cache 2>/dev/null \
+    || npx --no-install codebyplan resolve-worktree --cache 2>/dev/null \
+    || true)
+fi
+
+# UUID guard — accept only a canonical UUID (8-4-4-4-12 hex).
+UUID_PATTERN='^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
+if [ -z "$RESOLVED_WT" ] || ! echo "$RESOLVED_WT" | grep -qE "$UUID_PATTERN"; then
+  # Unresolved or invalid — plain allow, no updatedInput.
+  exit 0
+fi
+
+# C3 — emit updatedInput as the FULL tool_input with caller_worktree_id added.
+# Claude Code's PreToolUse updatedInput REPLACES tool_input wholesale (it is not a
+# partial merge), so we must echo back every existing field merged with the new
+# caller_worktree_id — otherwise the tool loses round_id/duration_minutes/etc.
+echo "$INPUT" | jq \
+  --arg wt "$RESOLVED_WT" \
+  '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "allow",
+      updatedInput: (.tool_input + { caller_worktree_id: $wt })
+    }
+  }'
+
+exit 0

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

@@ -374,6 +374,87 @@ 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 ""
+
 # ===== SUMMARY =====
 echo "=== TEST SUMMARY ==="
 echo -e "Passed: ${GREEN}$PASSED${NC}"

package/templates/hooks/hooks.json

@@ -45,6 +45,15 @@
             "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/README.md

@@ -34,14 +34,19 @@ The `install`/`update`/`uninstall` flow handles these files identically to how i
 
 ## Current status
 
-Four rules are shipped:
-
-| Rule file | Summary |
-|---|---|
-| `scope-vocabulary.md` | Canonical scope-marker enum (`org-shared` / `project-shared` / `repo-only:<name>`) enforced by three validators |
-| `context-file-loading.md` | Context-file load contract — who loads what, when, and how missing files are handled |
-| `todo-backend.md` | Todos queue contract, six DB-layer workflow invariants, and writer obligations for MCP mutators |
-| `supabase-branch-lifecycle.md` | Supabase preview-branch lifecycle mirrors the git feat-branch lifecycle — lazy create on first DB change, delete wherever the git branch is removed |
+Nine rules are shipped:
+
+| Rule file | Scope | Summary |
+|---|---|---|
+| `scope-vocabulary.md` | `org-shared` | Canonical scope-marker enum (`org-shared` / `project-shared` / `repo-only:<name>`) enforced by three validators |
+| `context-file-loading.md` | `org-shared` | Context-file load contract — who loads what, when, and how missing files are handled |
+| `todo-backend.md` | `org-shared` | Todos queue contract, six DB-layer workflow invariants, and writer obligations for MCP mutators |
+| `supabase-branch-lifecycle.md` | `org-shared` | Supabase preview-branch lifecycle mirrors the git feat-branch lifecycle — lazy create on first DB change, delete wherever the git branch is removed |
+| `agent-claim-verification.md` | `org-shared` | Verify an agent's claimed outcomes against ground truth (git, filesystem, tool results) before trusting them |
+| `e2e-mandatory.md` | `org-shared` | E2E is opt-out: an eligible framework whose source changed in a round must run its specialist or record a valid skip |
+| `parallel-waves.md` | `org-shared` | Wave-dispatch contract for parallel round execution — topological ordering and per-wave testing |
+| `task-routing-recommendation.md` | `repo-only:codebyplan` | Two-family command surface (checkpoint-bound vs standalone) and identifier-format routing — installed only in codebyplan-family repos |
+| `cbp-operating-gotchas.md` | `org-shared` | Cross-repo CBP-tooling traps (ship/timeout/MCP-replace/worktree/lint-baseline/approval-reconcile) + behavioral prefs, inherited once by all consumers |
 
 ## Contributing a rule
 

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

@@ -0,0 +1,64 @@
+---
+scope: org-shared
+---
+
+# CBP Operating Gotchas
+
+Cross-repo traps in the CodeByPlan tooling surface (CLI, MCP, git, host platform) that
+recur in every consuming repo. They are recorded **once** here so consumers inherit them via
+`npx codebyplan claude update` instead of re-learning each one per repo. This file is for
+SHARED tooling behavior only — repo-specific gotchas belong in that repo's own `CLAUDE.md`
+(root or nested), never here.
+
+## Tooling Traps
+
+- **`codebyplan ship` can report a false `checks_failed`.** The CLI polls
+  `gh pr checks --json name,state,conclusion` and treats a check as failed when its `state` is
+  `COMPLETED` and its `conclusion` is non-null and not a success value — but `gh` does not always
+  populate `conclusion` for every check type, so a green PR can be misread as failed. Do not trust
+  the CLI verdict alone: confirm with `gh pr checks <pr> --watch`, then merge manually with
+  `gh pr merge <pr> --merge`.
+
+- **macOS has no `timeout` binary.** Wrapping a build/lint/test in `timeout …` fails with
+  `command not found: timeout` — meaning the wrapped command **never ran** (a misleading
+  "exit 127", not a real result). Never shell-wrap with `timeout`; use the Bash tool's own
+  `timeout` parameter to bound a command.
+
+- **MCP `update_checkpoint` / `update_task` / `update_round` are REPLACE, not merge.** The
+  `context` JSONB and `files_changed[]` array overwrite wholesale — a partial write silently
+  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.
+
+- **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
+  pre-existing baseline error outside that set never fails the round.
+
+- **`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".
+
+- **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`.
+
+- **`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
+
+- **Never `git stash`** — for any reason. To inspect or compare other state use
+  `git diff <ref>`, `git show <ref>:<path>`, or `git worktree add`.
+
+- **During MCP instability, verify tool results over narration.** When responses lag, servers
+  cycle, or calls 502, never state an expected output as fact — confirm against git and the
+  filesystem, which are the source of truth.

package/templates/settings.project.base.json

@@ -96,7 +96,6 @@
     "allow": [
       "Skill(cbp-build-cc-agent)",
       "Skill(cbp-build-cc-claude-file)",
-      "Skill(cbp-build-cc-memory)",
       "Skill(cbp-build-cc-mode)",
       "Skill(cbp-build-cc-rule)",
       "Skill(cbp-build-cc-settings)",

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

@@ -1,8 +1,8 @@
 ---
 scope: org-shared
 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, memory, hooks, skills preload, permission modes, isolation).
-argument-hint: "[agent-name] [--scope=project|user] [--memory=project|user|local] [--isolation=worktree]"
+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 *)
 effort: xhigh
 ---
@@ -15,7 +15,7 @@ Create a Claude Code subagent following the official Claude Code sub-agents spec
 
 ## Arguments
 
-`$ARGUMENTS` — agent name (kebab-case, required). Flags: `--scope=project|user` (default `project`), `--memory=project|user|local`, `--isolation=worktree`.
+`$ARGUMENTS` — agent name (kebab-case, required). Flags: `--scope=project|user` (default `project`), `--isolation=worktree`.
 
 ## When to Use
 
@@ -70,7 +70,6 @@ Check each against the task and include only when they add value:
 
 | Capability           | Field                                                           | When to include                                        |
 | -------------------- | --------------------------------------------------------------- | ------------------------------------------------------ |
-| Persistent memory    | `memory: project\|user\|local`                                  | Agent should accumulate learnings across conversations |
 | Preloaded skills     | `skills: [skill-a, skill-b]`                                    | Domain knowledge the agent needs every run             |
 | Scoped MCP servers   | `mcpServers: [...]`                                             | Tools the parent session shouldn't have in context     |
 | Lifecycle hooks      | `hooks: { PreToolUse: [...], PostToolUse: [...], Stop: [...] }` | Need to validate tool calls or trigger side-effects    |

package/templates/skills/cbp-build-cc-agent/examples/with-skills-preload.md

@@ -4,7 +4,6 @@ description: Implement API endpoints following team conventions. Use when adding
 tools: Read, Write, Edit, Grep, Glob, Bash
 model: sonnet
 effort: xhigh
-memory: project
 skills:
   - api-conventions
   - error-handling-patterns
@@ -13,11 +12,11 @@ skills:
 You are an API developer. Follow the conventions and patterns preloaded via the `skills` field — they define the project's RESTful naming, error format, and validation rules.
 
 When invoked:
-1. Read `MEMORY.md` to recall past learnings on this codebase
+1. Read the nearest folder-local `CLAUDE.md` (e.g. `src/api/CLAUDE.md`) for conventions specific to this area
 2. Locate the handler directory (`src/api/handlers/`)
 3. Implement the endpoint per the preloaded conventions
 4. Write or update tests in the matching `*.test.ts` file
-5. Append one-line learnings to `MEMORY.md` when you discover a pattern worth remembering
+5. When you discover a durable pattern worth remembering, record it in the folder-local `CLAUDE.md` via `/cbp-build-cc-claude-file`
 
 Return:
 - Files created/modified

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

@@ -14,7 +14,6 @@ Source: official Claude Code sub-agents spec. Only `name` and `description` are
 | `skills` | list | Skills to preload — full content injected at startup |
 | `mcpServers` | list | String references (shared) or inline defs (scoped to this agent) |
 | `hooks` | object | Lifecycle hooks — `PreToolUse`, `PostToolUse`, `Stop` (→ `SubagentStop`) |
-| `memory` | string | `user` \| `project` \| `local` — persistent MEMORY.md directory |
 | `background` | boolean | Always run concurrent to the main thread |
 | `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 |

package/templates/skills/cbp-build-cc-agent/scripts/validate-agent.sh

@@ -54,12 +54,6 @@ if [ -n "$pm" ] && [[ ! "$pm" =~ ^(default|acceptEdits|auto|dontAsk|bypassPermis
   err "permissionMode invalid: got '$pm'"
 fi
 
-# Memory scope check
-mem=$(grep -E '^memory:' <<< "$fm" | head -1 | sed -E 's/^memory:[[:space:]]*//; s/[[:space:]]*$//; s/^"(.*)"$/\1/' || true)
-if [ -n "$mem" ] && [[ ! "$mem" =~ ^(user|project|local)$ ]]; then
-  err "memory must be user|project|local: got '$mem'"
-fi
-
 if [ "$errors" -gt 0 ]; then
   echo "validation FAILED ($errors issue(s)) for $FILE" >&2
   exit 1

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

@@ -12,7 +12,6 @@ effort: xhigh
 # color: blue  # red | blue | green | yellow | purple | orange | pink | cyan
 # background: false
 # isolation: worktree  # only if the agent should work in an isolated git worktree
-# memory: project  # project | user | local — enables persistent MEMORY.md
 # skills:
 #   - api-conventions
 #   - error-handling-patterns
@@ -33,7 +32,7 @@ effort: xhigh
 #       hooks:
 #         - type: command
 #           command: "./scripts/run-linter.sh"
-# initialPrompt: "Start by reading MEMORY.md, then wait for instructions."  # only used when run as main thread via --agent
+# initialPrompt: "Start by reading the project CLAUDE.md, then wait for instructions."  # only used when run as main thread via --agent
 ---
 
 You are a [role] specialising in [domain].

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

@@ -28,12 +28,12 @@ Actions:
 - Adding a new project-level fact (build command, architecture decision)
 - Restructuring when CLAUDE.md grows past ~200 lines
 - Migrating from AGENTS.md to CLAUDE.md (or bridging them)
+- Capturing a folder-local learning (a `project`/`feedback` insight tied to one area of the tree) → author a **nested CLAUDE.md** next to that code (see "Authoring a nested CLAUDE.md" below). This is the home for durable learnings that previously went to auto-memory.
 
 Do NOT use this skill for:
 
 - Workflow details or behavioural rules → `/cbp-build-cc-rule`
 - Reusable step-by-step procedures → `/cbp-build-cc-skill`
-- Personal learnings across projects → `/cbp-build-cc-memory`
 
 ## Instructions
 
@@ -48,6 +48,20 @@ Do NOT use this skill for:
 
 Default: project. Either `./CLAUDE.md` or `./.claude/CLAUDE.md` works; pick one and stick to it.
 
+### Step 1.5 — Authoring a nested CLAUDE.md
+
+A **nested** CLAUDE.md lives in a subdirectory (e.g. `apps/web/src/lib/CLAUDE.md`) rather than the repo root. It is the home for a folder-local learning — a `project`/`feedback` insight that only matters when working in that part of the tree (what previously went to auto-memory). Prefer a nested CLAUDE.md over the root file whenever the fact is scoped to one area: it keeps the root high-signal and loads the detail only when relevant.
+
+**Discovery (how nested files load).** At session start Claude Code loads every `CLAUDE.md` on the path from the working directory **up** to the repo root. Files in subdirectories **below** the working directory load **on-demand** — the moment Claude reads any file inside that subdirectory. Unlike the root file, nested CLAUDE.md content does **not** survive compaction — it reloads when Claude next touches a matching subdirectory file. So a nested file is self-contained context for its folder, not a place for repo-wide rules.
+
+**Placement.** Put the file in the shallowest directory that fully contains the concern:
+
+- A gotcha about one package's build → that package root (`packages/foo/CLAUDE.md`)
+- A convention for a feature area → that feature dir (`apps/web/src/lib/CLAUDE.md`)
+- A repo-wide fact → the root CLAUDE.md, not a nested file
+
+**Authoring.** Same quality gates as the root file (specific > vague, no duplication, keep it stable), but scope every line to the folder. Open with one line naming the area the file governs. Cross-link the root file or a rule with `@path` imports instead of repeating their content. To create one, run this skill with `create --scope=project` and write to the nested path.
+
 ### Step 2 — Read existing CLAUDE.md (for update/check)
 
 ```bash
@@ -165,7 +179,7 @@ Run `/memory` to confirm the file is loaded. The list shows all CLAUDE.md, CLAUD
 - **Triggered by**: user invocation
 - **Reads**: `${CLAUDE_SKILL_DIR}/templates/*.md`, `${CLAUDE_SKILL_DIR}/reference/*.md`, current CLAUDE.md, `.claude/rules/*.md`
 - **Writes**: CLAUDE.md at the chosen scope
-- **Related skills**: `/cbp-build-cc-rule` (behavioural constraints), `/cbp-build-cc-memory` (personal learnings), `/cbp-build-cc-settings` (for `claudeMdExcludes`)
+- **Related skills**: `/cbp-build-cc-rule` (behavioural constraints), `/cbp-build-cc-settings` (for `claudeMdExcludes`)
 
 ## Key Rules
 

package/templates/skills/cbp-build-cc-claude-file/reference/what-belongs.md

@@ -15,7 +15,7 @@ Source: official Claude Code memory spec — *Write effective instructions*.
 |-------------|------------------|
 | Multi-step procedure | Skill (`.claude/skills/{name}/SKILL.md`) |
 | File-specific constraint | Path-scoped rule (`.claude/rules/{name}.md` with `paths:`) |
-| Personal learning | Auto memory (`~/.claude/projects/<project>/memory/`) |
+| Folder-local learning (project/feedback) | Nested CLAUDE.md placed next to the code it concerns (see SKILL.md "Authoring a nested CLAUDE.md") |
 | API endpoint documentation | `docs/` |
 | Architecture deep-dive | `docs/architecture/` |
 | Framework usage guide | `docs/stack/{framework}/` |

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

@@ -23,7 +23,7 @@ Audit or apply the canonical `model:` + `effort:` frontmatter convention across
 
 `model: sonnet` + `effort: xhigh`
 
-Fifteen of the 16 authoring agents take the default (`cbp-cc-executor`, `cbp-database-agent`, `cbp-improve-claude`, `cbp-improve-round`, `cbp-research`, `cbp-round-executor`, `cbp-security-agent`, `cbp-task-check`, `cbp-task-planner`, `cbp-testing-qa-agent`, `cbp-e2e-playwright`, `cbp-e2e-maestro`, `cbp-e2e-tauri`, `cbp-e2e-vscode`, `cbp-e2e-xcuitest`). The 16th — `cbp-mechanical-edits` — is an explicit haiku-low exception (see below). 27 skills take the default: cbp-round-start, cbp-round-input, cbp-round-execute, cbp-task-create, cbp-task-start, cbp-task-complete, cbp-task-testing, cbp-checkpoint-create, cbp-checkpoint-check, cbp-checkpoint-end, cbp-build-cc-mode, cbp-build-cc-agent, cbp-build-cc-skill, cbp-build-cc-rule, cbp-build-cc-claude-file, cbp-build-cc-memory, cbp-build-cc-settings, cbp-frontend-a11y, cbp-frontend-design, cbp-frontend-ui, cbp-frontend-ux, cbp-session-end, cbp-ship, cbp-ship-configure, cbp-supabase-setup, cbp-supabase-migrate, cbp-supabase-branch-check.
+Fifteen of the 16 authoring agents take the default (`cbp-cc-executor`, `cbp-database-agent`, `cbp-improve-claude`, `cbp-improve-round`, `cbp-research`, `cbp-round-executor`, `cbp-security-agent`, `cbp-task-check`, `cbp-task-planner`, `cbp-testing-qa-agent`, `cbp-e2e-playwright`, `cbp-e2e-maestro`, `cbp-e2e-tauri`, `cbp-e2e-vscode`, `cbp-e2e-xcuitest`). The 16th — `cbp-mechanical-edits` — is an explicit haiku-low exception (see below). 26 skills take the default: cbp-round-start, cbp-round-input, cbp-round-execute, cbp-task-create, cbp-task-start, cbp-task-complete, cbp-task-testing, cbp-checkpoint-create, cbp-checkpoint-check, cbp-checkpoint-end, cbp-build-cc-mode, cbp-build-cc-agent, cbp-build-cc-skill, cbp-build-cc-rule, cbp-build-cc-claude-file, cbp-build-cc-settings, cbp-frontend-a11y, cbp-frontend-design, cbp-frontend-ui, cbp-frontend-ux, cbp-session-end, cbp-ship, cbp-ship-configure, cbp-supabase-setup, cbp-supabase-migrate, cbp-supabase-branch-check.
 
 ### Effort-lowered skills (5)
 

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

@@ -25,7 +25,7 @@ Create a rule at `.claude/rules/{name}.md` per the official Claude Code memory s
 
 - Step-by-step workflows → use `/cbp-build-cc-skill` (loads on invoke, doesn't burn context)
 - Project-level facts always needed → CLAUDE.md (use `/cbp-build-cc-claude-file`)
-- Accumulating learnings → auto memory (use `/cbp-build-cc-memory`)
+- Accumulating learnings → nested CLAUDE.md (use `/cbp-build-cc-claude-file`)
 
 ## Instructions
 
@@ -164,7 +164,7 @@ Use the `InstructionsLoaded` hook if you need to debug exactly when and why a ru
 - **Triggered by**: user invocation
 - **Reads**: `${CLAUDE_SKILL_DIR}/templates/rule.md`, `${CLAUDE_SKILL_DIR}/reference/paths-patterns.md`
 - **Writes**: `.claude/rules/{name}.md` or `~/.claude/rules/{name}.md`
-- **Related skills**: `/cbp-build-cc-claude-file` (project facts), `/cbp-build-cc-skill` (workflows), `/cbp-build-cc-memory` (auto-learnings)
+- **Related skills**: `/cbp-build-cc-claude-file` (project facts + nested-folder learnings), `/cbp-build-cc-skill` (workflows)
 
 ## Key Rules
 

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

@@ -57,7 +57,7 @@ This mirrors the CHK-104 hard-lock model — never wrest a checkpoint from a liv
 
 If the checkpoint is already `active` AND `worktree_id` already equals `CALLER_WT` (the Step 3 no-op row), skip this step entirely and proceed to Step 5 — nothing to write.
 
-Otherwise set the checkpoint `active` via MCP `update_checkpoint(checkpoint_id, status: "active"`, plus `worktree_id: CALLER_WT` when claiming per Step 3. The server resolves the caller's worktree identity from the JWT/ctx (CHK-140 TASK-3 — `caller_worktree_id` input field removed). If the checkpoint was already `active` but a claim is still needed, skip the status write and only write `worktree_id`.
+Otherwise set the checkpoint `active` via MCP `update_checkpoint(checkpoint_id, status: "active"`, plus `worktree_id: CALLER_WT` when claiming per Step 3. `caller_worktree_id` (CHK-140 TASK-7) identifies the calling worktree and is auto-injected by the `cbp-mcp-caller-worktree-inject.sh` PreToolUse hook (CHK-198 TASK-2); the server falls back to the repo `main` worktree only when it is absent. If the checkpoint was already `active` but a claim is still needed, skip the status write and only write `worktree_id`.
 
 ### Step 5: Route
 
@@ -78,7 +78,7 @@ Show a one-line confirmation before routing:
 ## Integration
 
 - **Reads**: MCP `get_checkpoints`, `get_tasks`; `npx codebyplan resolve-worktree`
-- **Writes**: MCP `update_checkpoint` (status + worktree_id; server resolves caller worktree from JWT/ctx)
+- **Writes**: MCP `update_checkpoint` (status + worktree_id; `caller_worktree_id` auto-injected by the cbp-mcp-caller-worktree-inject.sh hook, CHK-198 TASK-2; server falls back to repo `main` only when absent)
 - **Triggered by**: `/cbp-checkpoint-plan` (auto when claimed at create), `/cbp-todo` (planned-but-pending gate), or user directly
 - **Triggers**: `/cbp-task-start` (auto when claimed), or `/cbp-checkpoint-plan` (when the checkpoint is unplanned)
 - **Never**: plans or creates tasks — that is `/cbp-checkpoint-plan`