codebyplan 1.13.28 → 1.13.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.28",
+  "version": "1.13.30",
   "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-improve-round.md

@@ -279,6 +279,6 @@ Return findings sorted by severity (critical first). If no findings, return `sta
 ## Integration
 
 - **Spawned by**: `/cbp-round-end` (Step 6)
-- **Returns to**: `/cbp-round-end` which presents findings to user
+- **Returns to**: `/cbp-round-end` which auto-applies in-scope findings inline and routes out-of-scope findings to `/cbp-round-update`
 - **Does NOT**: Apply any changes
 - **Reads**: Changed files, task requirements, round context

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/agents/cbp-task-check.md

@@ -9,7 +9,7 @@ effort: xhigh
 
 # Task Check Agent
 
-AI-driven production readiness review with user satisfaction discussion. Verifies all task requirements are met, checkpoint goals are aligned, and work is production-ready.
+AI-driven production readiness review with user satisfaction discussion. This is the **cross-round double-check** layer: per-round QA (build/lint/types per app, the `console.log`/debug scan, the OWASP/secret grep, API auth-enforcement curls, `pnpm audit`) already ran inside each round's `testing-qa-agent` — this agent does NOT re-run it. Its unique value is holistic: verifying all task requirements are met, checkpoint goals are aligned, the aggregated work is shippable, and — for tasks that span many rounds where scope can shift as new ideas/problems surface — detecting scope drift that should update the checkpoint or task rather than re-running per-round checks.
 
 **Numeric-claim verification (Proposal P6)**: when round summaries assert numeric facts (file counts, package counts, percentage changes, line counts, version numbers), verify each via direct count: `find ... | wc -l`, `grep -c`, `wc -l <file>`. Do NOT accept narrative numbers without a verification command. Mismatches between asserted and actual counts indicate documentation drift; flag as a finding requiring a fix.
 
@@ -95,14 +95,16 @@ Check `task.files_changed`:
 - List unapproved files
 - Determine if unapproved files block completion
 
-### Phase 6: Code Review
+### Phase 6: Code Review (holistic spot-check)
 
-Read ALL changed files and verify:
-- No obvious bugs or regressions
-- No security issues (hardcoded secrets, SQL injection, XSS)
-- No leftover debug code (console.log, TODO from this task)
-- Error handling present where needed
-- Consistent with existing codebase patterns
+Per-round QA already ran the line-level checks — the `console.log`/debug scan (round `testing-qa-agent` Phase 3.5), the OWASP secret/injection grep (Phase 5), the API auth-enforcement curl (Phase 3.55), and `pnpm audit` (Phase 3.7). Do NOT re-run them here. Phase 6 is a light holistic spot-check across the aggregated diff for what a single round cannot see:
+
+- No obvious bugs or regressions that emerge only when all rounds' changes are read together
+- No cross-round integration gaps (a field/contract introduced in one round that a later round broke)
+- Error handling present where needed at the feature boundary
+- Consistent with existing codebase patterns across the full task diff
+
+If the aggregated diff surfaces an obvious issue per-round QA missed, flag it as a finding — but the per-round scans are authoritative for line-level concerns.
 
 ### Phase 7: Shippable Feature Gate
 
@@ -125,6 +127,8 @@ Update `round_outcome_analysis` with findings.
 
 ### Phase 9: User Satisfaction Discussion
 
+For tasks that ran many rounds, scope drift accumulates quietly — each round may have absorbed a new idea or problem without the checkpoint/task requirements being updated. The satisfaction discussion is where that drift surfaces; treat the scope-divergence scan below as a first-class output, not an afterthought.
+
 Present findings to user via AskUserQuestion:
 
 ```

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

@@ -5,6 +5,15 @@
 #          staging-status flip, and web-UI flag sync to the codebyplan CLI.
 #          Replaces the inline jq merge + curl PATCH with a single CLI call.
 #
+# Trigger context (CHK-197): complete_round is now called by /cbp-round-complete
+# (the permission-gated finalizer), which already runs `sync-approvals` once
+# BEFORE completing the round. This hook firing afterward is the expected
+# post-complete safety net — it catches approval drift between that pre-complete
+# sync and the approval_locked write; it is NOT a duplicate run to remove.
+# NOTE: this hook matches complete_round only; complete_standalone_round is NOT
+# covered, so standalone rounds rely solely on /cbp-round-complete's pre-complete
+# sync (pre-existing coverage gap, documented here intentionally — not fixed).
+#
 # Delegates to: npx codebyplan round sync-approvals
 #   - Git-diff drift merge (in/not-in DB vs git)
 #   - Staging-status → user_approved flip

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

@@ -55,7 +55,8 @@
       "Skill(cbp-checkpoint-create)",
       "Skill(cbp-checkpoint-check)",
       "Skill(cbp-checkpoint-complete)",
-      "Skill(cbp-round-update)",
+      "Skill(cbp-round-complete)",
+      "Skill(cbp-round-execute)",
       "Skill(cbp-session-end)",
       "Skill(cbp-task-complete)",
       "Skill(cbp-standalone-task-create)",
@@ -95,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)",
@@ -114,9 +114,9 @@
       "Skill(cbp-refresh-infra)",
       "Skill(cbp-round-check)",
       "Skill(cbp-round-end)",
-      "Skill(cbp-round-execute)",
       "Skill(cbp-round-input)",
       "Skill(cbp-round-start)",
+      "Skill(cbp-round-update)",
       "Skill(cbp-session-start)",
       "Skill(cbp-setup-e2e)",
       "Skill(cbp-setup-eslint)",

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)
 
@@ -31,19 +31,20 @@ Fifteen of the 16 authoring agents take the default (`cbp-cc-executor`, `cbp-dat
 
 | skill             | model  | effort | reason                                                                                                            |
 | ----------------- | ------ | ------ | ----------------------------------------------------------------------------------------------------------------- |
-| cbp-round-end         | sonnet | high   | Spawns cbp-improve-round agent; skill body summarises + presents user findings-decision — lighter than xhigh suffices |
+| cbp-round-end         | sonnet | high   | Spawns cbp-improve-round agent; auto-applies in-scope findings + routes out-of-scope to round-update — lighter than xhigh suffices |
 | cbp-task-check        | sonnet | high   | Thin orchestrator over spawned cbp-task-check agent; inline-fallback path keeps Opus for safety                       |
 | cbp-checkpoint-update | sonnet | high   | Status updates + context patches mostly; lighter than xhigh                                                       |
 | cbp-ship-main         | sonnet | high   | Production-impacting PR creation; keep Opus reasoning but drop effort                                             |
 | cbp-merge-main        | sonnet | high   | Long-lived-branch integration merge — surgical conflict resolution, no authoring                                  |
 
-### Haiku-low skills (9)
+### Haiku-low skills (10)
 
 `model: haiku` + `effort: low`. Pure mechanical / dispatch / templated work.
 
 | skill                  | model | effort | reason                                                                                   |
 | ---------------------- | ----- | ------ | ---------------------------------------------------------------------------------------- |
-| cbp-round-update           | haiku | low    | Pure mechanical: read git status, check approvals, route per rules                       |
+| cbp-round-update           | haiku | low    | Pure mechanical: triage round state (claude_approved/findings/hard_fail), route to round-complete or round-input |
+| cbp-round-complete         | haiku | low    | Pure mechanical: sync-approvals git-add reconcile, complete round, route per unapproved count |
 | cbp-round-check            | haiku | low    | Run build/lint/types commands, parse output, update QA                                   |
 | cbp-todo                   | haiku | low    | Dispatch: single MCP call + route to next command                                        |
 | cbp-checkpoint-complete    | haiku | low    | Pure finalization — mark completed, write summary; judgment happened in checkpoint-check |

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-build-cc-settings/reference/cbp-permission-policy.md

@@ -22,7 +22,7 @@ Precedence is `deny > ask > allow`; arrays union across scopes (managed/user/pro
 
 ### `allow` — the autonomous workflow surface
 
-- **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-check`/`-end`/`-execute`/`-input`/`-start`), setup/configure (`cbp-setup-*`, `cbp-ship-configure`, `cbp-supabase-*`), task prep (`cbp-task-check`/`-create`/`-start`/`-testing`, `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 skills are the exception — they live in `ask` (next section).
+- **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-check`/`-end`/`-input`/`-start`/`-update` — `cbp-round-update` is autonomous triage that only reads round state and routes to `cbp-round-complete` or `cbp-round-input`, so it runs without a prompt), setup/configure (`cbp-setup-*`, `cbp-ship-configure`, `cbp-supabase-*`), task prep (`cbp-task-check`/`-create`/`-start`/`-testing`, `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.
 - **Read/safe CLI commands** (both `codebyplan X` and `npx codebyplan X`): `whoami`, `resolve-worktree`, `statusline`, `ports`, `tech-stack`, `eslint`, `round`, `help`, `--version`.
@@ -30,7 +30,8 @@ Precedence is `deny > ask > allow`; arrays union across scopes (managed/user/pro
 ### `ask` — the deliberate confirm-gate
 
 - **Production-shipment skills**: `cbp-ship`, `cbp-ship-main`, `cbp-checkpoint-end` — these promote/deploy to production, so they prompt even in an otherwise auto-allowed setup.
-- **Lifecycle / state-transition skills**: `cbp-checkpoint-start`, `cbp-checkpoint-create`, `cbp-checkpoint-check`, `cbp-checkpoint-complete`, `cbp-round-update`, `cbp-session-end`, `cbp-task-complete`, `cbp-standalone-task-create`, `cbp-standalone-task-start`, `cbp-standalone-task-complete` — these open or close checkpoints, tasks, rounds, and sessions (advancing workflow state in the database), so they stop for explicit confirmation rather than running autonomously.
+- **Lifecycle / state-transition skills**: `cbp-checkpoint-start`, `cbp-checkpoint-create`, `cbp-checkpoint-check`, `cbp-checkpoint-complete`, `cbp-round-complete`, `cbp-session-end`, `cbp-task-complete`, `cbp-standalone-task-create`, `cbp-standalone-task-start`, `cbp-standalone-task-complete` — these open or close checkpoints, tasks, rounds, and sessions (advancing workflow state in the database), so they stop for explicit confirmation rather than running autonomously. `cbp-round-complete` is the permission-gated round finalizer (reconciles the user's `git add`s, completes the round, routes onward); its `ask` prompt replaces the in-skill confirmation that used to live in `cbp-round-update` — which is now an autonomous, `allow`-tier triage step.
+- **Plan-approval gate**: `cbp-round-execute` — the round plan is approved by confirming this `ask` prompt rather than via an in-skill AskUserQuestion. `cbp-round-start` runs its planning Q&A, then hands off to `cbp-round-execute`; the permission prompt is the user's go/no-go on the plan.
 - **Destructive / admin MCP tools**: `delete_session_log`, `delete_worktree`, `create_repo`, `release_assignment`. (The launch and member-admin tools were dropped from the MCP surface in CHK-180 — those concerns are web-app only now.)
 - **Mutating / external / clobber-risk CLI commands** (both prefixes): `setup`, `login`, `logout`, `upgrade-auth`, `config` (can overwrite committed `.codebyplan/` files), `branch` (rewrites branch config), `ship`, `claude` (`install`/`update`/`uninstall` overwrite `.claude/`).
 

package/templates/skills/cbp-build-cc-skill/reference/cbp-quality.md

@@ -88,7 +88,7 @@ A skill should do one thing in the pipeline. If a skill both plans AND executes,
 If the skill is part of a chain, show it:
 
 ```
-/cbp-round-start (planning) → [user approval] → /cbp-round-execute (auto)
+/cbp-round-start (planning) → /cbp-round-execute (ask-tier permission = plan approval)
 ```
 
 ### Approval Gates

package/templates/skills/cbp-merge-main/SKILL.md

@@ -42,7 +42,7 @@ Triggered by `/cbp-task-start` (Step 3.6, optional stale-check), `/cbp-task-comp
      - **Cancel** — abort the skill.
    - `unstaged_dirty=false AND staged_present=true` → print one informational line and proceed to Step 1:
      `Staged changes detected — proceeding with merge.`
-     (Pre-staged files will be included in the merge commit at Step 2 — this is intentional; the caller already approved them via /cbp-round-update.)
+     (Pre-staged files will be included in the merge commit at Step 2 — this is intentional; the caller already approved them via /cbp-round-complete.)
    - `unstaged_dirty=false AND staged_present=false` → proceed silently to Step 1.
    - Either `git diff` command exits with code ≥ 2 (git hard error — not-a-repo, detached HEAD with no commits, index lock, corrupt object store): surface the raw error output and STOP. Do NOT proceed to Step 1.