codebyplan 1.12.0 → 1.13.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.12.0",
+  "version": "1.13.3",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
   "homepage": "https://codebyplan.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/codebyplan/codebyplan.git",
+    "url": "https://github.com/midevyou/codebyplan.git",
     "directory": "packages/codebyplan-package"
   },
   "license": "MIT",

package/templates/github-workflows/publish.yml

@@ -0,0 +1,207 @@
+# Generated by: codebyplan scaffold-publish-workflow
+#
+# This workflow publishes the codebyplan npm package on every merge to main
+# where the committed package.json version exceeds the version currently on npm.
+# No release PR, no conventional-commit parsing — the version committed in the
+# feat branch is the version that ships.
+#
+# Two values a consuming repo must adjust:
+#   1. paths: — set to the package directory whose package.json drives versioning
+#              (current value: 'packages/codebyplan-package/**')
+#   2. npm view <package-name> — replace `codebyplan` with the actual package name
+#              in the "Check version vs published" step
+#
+# Everything else (OIDC auth, pnpm 10.12.4, Node 20, build:npm → publish) is
+# intentionally generic and works as-is for any single-package npm publish.
+
+name: Publish codebyplan to npm
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "packages/codebyplan-package/**"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Print what would be published without actually publishing"
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  check-version:
+    name: Check if publish needed
+    runs-on: ubuntu-latest
+    outputs:
+      should_publish: ${{ steps.check.outputs.should_publish }}
+      version: ${{ steps.check.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Check version vs published
+        id: check
+        run: |
+          VERSION=$(jq -r '.version' packages/codebyplan-package/package.json)
+          if [ -z "$VERSION" ] || [ "$VERSION" = "null" ]; then
+            echo "ERROR: could not read .version from packages/codebyplan-package/package.json"
+            exit 1
+          fi
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+          # Pre-release versions (e.g. 1.2.3-beta.1) must never auto-publish to the
+          # 'latest' dist-tag — sort -V is not semver-aware for pre-release suffixes,
+          # and this workflow always publishes to latest. Publish pre-releases
+          # manually with `npm publish --tag <pre-id>`. The version core (X.Y.Z) has
+          # no hyphen, so any '-' marks a pre-release.
+          case "$VERSION" in
+            *-*)
+              echo "VERSION=${VERSION} is a pre-release — skipping auto-publish."
+              echo "should_publish=false" >> "$GITHUB_OUTPUT"
+              exit 0
+              ;;
+          esac
+
+          # Manual dispatch: always publish (recovery / forced re-publish path).
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "Manual dispatch — skipping gt check, will publish."
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Push path: compare committed version against the npm registry.
+          # Distinguish "never published" (E404 → first publish) from a transient
+          # registry/network error (abort rather than blindly publish).
+          NPM_OUT=$(npm view codebyplan version 2>&1)
+          NPM_EXIT=$?
+          if [ "$NPM_EXIT" -ne 0 ]; then
+            if echo "$NPM_OUT" | grep -q "E404"; then
+              echo "Package not yet published — first publish."
+              echo "should_publish=true" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+            echo "ERROR: npm view failed (exit ${NPM_EXIT}): ${NPM_OUT}"
+            exit 1
+          fi
+          PUBLISHED="$NPM_OUT"
+
+          # sort -V: version-aware sort. If VERSION sorts AFTER PUBLISHED, it is greater.
+          GREATER=$(printf '%s\n%s\n' "$PUBLISHED" "$VERSION" | sort -V | tail -n1)
+          if [ "$GREATER" = "$VERSION" ] && [ "$VERSION" != "$PUBLISHED" ]; then
+            echo "VERSION=${VERSION} > PUBLISHED=${PUBLISHED} — will publish."
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "VERSION=${VERSION} <= PUBLISHED=${PUBLISHED} — skipping publish."
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  publish-codebyplan:
+    name: Publish to npm (OIDC)
+    needs: check-version
+    if: needs.check-version.outputs.should_publish == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      # OIDC token for npm Trusted Publishing — no long-lived NPM_TOKEN needed.
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.12.4
+
+      # Deliberately NO registry-url: actions/setup-node would write an
+      # `_authToken=${NODE_AUTH_TOKEN}` line into .npmrc, and that (empty) token
+      # shadows OIDC trusted publishing — npm uses the token path and gets E404
+      # instead of doing the OIDC exchange. publishConfig.registry handles the
+      # target registry for `npm publish`.
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build packages/codebyplan-package
+        working-directory: packages/codebyplan-package
+        run: pnpm build:npm
+
+      # npm Trusted Publishing (OIDC) requires npm >= 11.5.1; Node 20 ships npm 10.x.
+      - name: Upgrade npm for trusted publishing
+        run: |
+          npm install -g npm@latest
+          npm --version
+          echo "OIDC token request URL present: ${ACTIONS_ID_TOKEN_REQUEST_URL:+yes}"
+
+      - name: Dry-run check
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run == true }}
+        working-directory: packages/codebyplan-package
+        run: |
+          echo "dry_run=true — skipping actual publish."
+          echo "Would publish: codebyplan@${{ needs.check-version.outputs.version }}"
+
+      # No NODE_AUTH_TOKEN: npm >= 11.5.1 exchanges the GitHub OIDC token for a
+      # short-lived publish token. Requires a Trusted Publisher configured for
+      # this repo + workflow on npmjs.com.
+      #
+      # NO --provenance by default: npm provenance attestation only supports
+      # PUBLIC source repositories (the registry returns E422 "Unsupported
+      # source repository visibility: private" otherwise). This works for both
+      # public and private repos. If your source repo is PUBLIC and you want
+      # supply-chain attestation, add `--provenance` to the command below.
+      - name: Publish to npm
+        if: ${{ github.event_name != 'workflow_dispatch' || inputs.dry_run != true }}
+        working-directory: packages/codebyplan-package
+        run: npm publish --access public
+
+  tag-and-release:
+    name: Tag + GitHub release
+    needs: [check-version, publish-codebyplan]
+    if: |
+      needs.check-version.outputs.should_publish == 'true' &&
+      needs.publish-codebyplan.result == 'success' &&
+      !(github.event_name == 'workflow_dispatch' && inputs.dry_run == true)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Create tag and release (idempotent)
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ needs.check-version.outputs.version }}
+        run: |
+          TAG="v${VERSION}"
+
+          # Idempotent: skip tag creation if it already exists.
+          if git ls-remote --tags origin "refs/tags/${TAG}" | grep -q "${TAG}"; then
+            echo "Tag ${TAG} already exists — skipping tag creation."
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git tag "${TAG}"
+            git push origin "${TAG}"
+            echo "Created and pushed tag ${TAG}."
+          fi
+
+          # Create GitHub release (idempotent: gh release create fails if exists; check first).
+          if gh release view "${TAG}" > /dev/null 2>&1; then
+            echo "GitHub release ${TAG} already exists — skipping."
+          else
+            gh release create "${TAG}" \
+              --title "codebyplan v${VERSION}" \
+              --notes "codebyplan v${VERSION} — published to npm: https://www.npmjs.com/package/codebyplan/v/${VERSION} (install: npm install -g codebyplan@${VERSION})" \
+              --latest
+            echo "Created GitHub release ${TAG}."
+          fi

package/templates/hooks/README.md

@@ -228,18 +228,6 @@ Denies any `git stash` command (including `git -C <dir> stash` and `git stash po
 
 ---
 
-### `cbp-mcp-worktree-inject.sh` — PreToolUse, matcher `mcp__codebyplan__(update_task|complete_task|complete_round|update_checkpoint)`
-
-Auto-injects `caller_worktree_id` into CodeByPlan MCP mutation calls when it's missing, resolving it via `npx codebyplan resolve-worktree` (with `--fallback-from-branch`). Closes the manual worktree-pinning workaround so MCP writes pass the server-side worktree pre-guard without hand-editing every call.
-
-**Blocks vs warns**: neither — emits an `updatedInput` to add the field when resolvable, otherwise passes the call through unchanged (graceful passthrough preserves backwards-compat).
-
-**Skips when**: the call already carries `caller_worktree_id`, or no worktree can be resolved (both → clean passthrough). A no-op in repos that don't use the CodeByPlan MCP.
-
-**Opt out**: settings.json override removing this entry, or plugin disable.
-
----
-
 ### `cbp-mcp-round-sync.sh` — PostToolUse, matcher `mcp__codebyplan__complete_round`
 
 After a `complete_round` MCP call succeeds, reconciles the round's `files_changed[]` against `git status`: new files in the diff are added (unapproved), and approval records no longer in the diff are flagged `removed_from_diff` (never deleted — lifecycle preserved).
@@ -258,7 +246,7 @@ After a `complete_round` MCP call succeeds, reconciles the round's `files_change
 
 Test suite for the plugin's 10 registered hooks. Runs two passes:
 
-1. **Header check** — every registered hook (`lint-format-on-edit`, `test-coverage-gate`, `pre-commit-quality-gate`, `maestro-yaml-validate`, `notify`, `auto-test-hooks`, `mcp-migration-guard`, `validate-git-stash-deny`, `cbp-mcp-worktree-inject`, `cbp-mcp-round-sync`) carries the required `# Hook:` and `# Purpose:` header comments. `statusline` uses its own `# Claude Code Status Line` marker.
+1. **Header check** — every registered hook (`lint-format-on-edit`, `test-coverage-gate`, `pre-commit-quality-gate`, `maestro-yaml-validate`, `notify`, `auto-test-hooks`, `mcp-migration-guard`, `validate-git-stash-deny`, `cbp-mcp-round-sync`) carries the required `# Hook:` and `# Purpose:` header comments. `statusline` uses its own `# Claude Code Status Line` marker.
 2. **Functional smoke tests** — each hook is invoked with synthetic stdin matching its fast-path / graceful-degrade input; all must exit 0.
 
 Not in `hooks.json` — invoked indirectly via `auto-test-hooks.sh` on hook edits, or directly via `bash ${CLAUDE_PLUGIN_ROOT}/hooks/test-hooks.sh`.

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

@@ -64,6 +64,14 @@ while IFS= read -r FILE; do
     continue
   fi
 
+  # Skip files under a __tests__/ directory — fixtures, helpers, setup, and
+  # other test infrastructure are imported by the test files that exercise
+  # them; requiring a dedicated .test.ts for a fixture is nonsensical.
+  if echo "$FILE" | grep -qE '/__tests__/'; then
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
   # Skip infrastructure / generated / config files (generic skips — harmless if user doesn't have these dirs)
   if echo "$FILE" | grep -qE '^\.claude/|^docs/|^supabase/|\.config\.|\.json$|\.md$|\.ya?ml$|\.sh$|\.scss$|\.css$'; then
     continue

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

@@ -207,48 +207,6 @@ else
   fi
 fi
 
-# --- cbp-mcp-worktree-inject.sh ---
-
-if [ ! -f "$HOOKS_DIR/cbp-mcp-worktree-inject.sh" ]; then
-  test_result "cbp-mcp-worktree-inject.sh present" "passed" "missing"
-else
-  test_result "cbp-mcp-worktree-inject.sh present" "passed" "passed"
-
-  FIRST_LINE=$(head -1 "$HOOKS_DIR/cbp-mcp-worktree-inject.sh")
-  if echo "$FIRST_LINE" | grep -q '^#!/'; then
-    test_result "cbp-mcp-worktree-inject.sh has shebang" "passed" "passed"
-  else
-    test_result "cbp-mcp-worktree-inject.sh has shebang" "passed" "missing"
-  fi
-
-  if grep -q '@scope: org-shared' "$HOOKS_DIR/cbp-mcp-worktree-inject.sh"; then
-    test_result "cbp-mcp-worktree-inject.sh has @scope: org-shared" "passed" "passed"
-  else
-    test_result "cbp-mcp-worktree-inject.sh has @scope: org-shared" "passed" "missing"
-  fi
-
-  FIXTURES_DIR="$HOOKS_DIR/__test-fixtures__/cbp-mcp-worktree-inject"
-  if [ -d "$FIXTURES_DIR" ]; then
-    # already-has-id.json — expect exit 0 (passthrough)
-    ACTUAL_EXIT=$(bash "$HOOKS_DIR/cbp-mcp-worktree-inject.sh" < "$FIXTURES_DIR/already-has-id.json" >/dev/null 2>&1; echo $?)
-    if [ "$ACTUAL_EXIT" = "0" ]; then
-      test_result "cbp-mcp-worktree-inject.sh already-has-id exits 0" "passed" "passed"
-    else
-      test_result "cbp-mcp-worktree-inject.sh already-has-id exits 0" "passed" "failed (exit $ACTUAL_EXIT)"
-    fi
-
-    # missing-id-both-empty.json — resolvers return empty (in test env), expect exit 0
-    ACTUAL_EXIT=$(bash "$HOOKS_DIR/cbp-mcp-worktree-inject.sh" < "$FIXTURES_DIR/missing-id-both-empty.json" >/dev/null 2>&1; echo $?)
-    if [ "$ACTUAL_EXIT" = "0" ]; then
-      test_result "cbp-mcp-worktree-inject.sh missing-id passthrough exits 0" "passed" "passed"
-    else
-      test_result "cbp-mcp-worktree-inject.sh missing-id passthrough exits 0" "passed" "failed (exit $ACTUAL_EXIT)"
-    fi
-  else
-    test_result "cbp-mcp-worktree-inject.sh fixtures dir present" "passed" "missing"
-  fi
-fi
-
 # --- cbp-mcp-round-sync.sh ---
 
 if [ ! -f "$HOOKS_DIR/cbp-mcp-round-sync.sh" ]; then

package/templates/hooks/hooks.json

@@ -35,15 +35,6 @@
             "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-mcp-migration-guard.sh"
           }
         ]
-      },
-      {
-        "matcher": "mcp__codebyplan__(update_task|complete_task|complete_round|update_checkpoint)",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-mcp-worktree-inject.sh"
-          }
-        ]
       }
     ],
     "PostToolUse": [

package/templates/settings.project.base.json

@@ -13,7 +13,9 @@
   "spinnerTipsEnabled": true,
   "terminalProgressBarEnabled": true,
   "viewMode": "default",
-  "worktree": { "baseRef": "fresh" },
+  "worktree": {
+    "baseRef": "fresh"
+  },
   "autoScrollEnabled": true,
   "cleanupPeriodDays": 30,
   "includeGitInstructions": true,
@@ -45,10 +47,159 @@
       "Bash(pnpm install:*)",
       "Bash(npm install:*)",
       "Bash(npm i:*)",
-      "Bash(npx add:*)"
+      "Bash(npx add:*)",
+      "Skill(cbp-checkpoint-end)",
+      "Skill(cbp-ship)",
+      "Skill(cbp-ship-main)",
+      "mcp__codebyplan__accept_invite",
+      "mcp__codebyplan__change_role",
+      "mcp__codebyplan__create_launch",
+      "mcp__codebyplan__update_launch",
+      "mcp__codebyplan__delete_launch",
+      "mcp__codebyplan__create_repo",
+      "mcp__codebyplan__delete_session_log",
+      "mcp__codebyplan__delete_worktree",
+      "mcp__codebyplan__invite_member",
+      "mcp__codebyplan__remove_member",
+      "mcp__codebyplan__revoke_invite",
+      "mcp__codebyplan__release_assignment",
+      "Bash(codebyplan setup:*)",
+      "Bash(npx codebyplan setup:*)",
+      "Bash(codebyplan login:*)",
+      "Bash(npx codebyplan login:*)",
+      "Bash(codebyplan logout:*)",
+      "Bash(npx codebyplan logout:*)",
+      "Bash(codebyplan upgrade-auth:*)",
+      "Bash(npx codebyplan upgrade-auth:*)",
+      "Bash(codebyplan config:*)",
+      "Bash(npx codebyplan config:*)",
+      "Bash(codebyplan branch:*)",
+      "Bash(npx codebyplan branch:*)",
+      "Bash(codebyplan ship:*)",
+      "Bash(npx codebyplan ship:*)",
+      "Bash(codebyplan claude:*)",
+      "Bash(npx codebyplan claude:*)"
+    ],
+    "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)",
+      "Skill(cbp-build-cc-skill)",
+      "Skill(cbp-checkpoint-check)",
+      "Skill(cbp-checkpoint-complete)",
+      "Skill(cbp-checkpoint-create)",
+      "Skill(cbp-checkpoint-plan)",
+      "Skill(cbp-checkpoint-start)",
+      "Skill(cbp-checkpoint-update)",
+      "Skill(cbp-frontend-a11y)",
+      "Skill(cbp-frontend-design)",
+      "Skill(cbp-frontend-ui)",
+      "Skill(cbp-frontend-ux)",
+      "Skill(cbp-git-branch-feat-create)",
+      "Skill(cbp-git-commit)",
+      "Skill(cbp-git-worktree-create)",
+      "Skill(cbp-git-worktree-remove)",
+      "Skill(cbp-merge-main)",
+      "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-end)",
+      "Skill(cbp-session-start)",
+      "Skill(cbp-setup-e2e)",
+      "Skill(cbp-setup-eslint)",
+      "Skill(cbp-ship-configure)",
+      "Skill(cbp-supabase-branch-check)",
+      "Skill(cbp-supabase-migrate)",
+      "Skill(cbp-supabase-setup)",
+      "Skill(cbp-task-check)",
+      "Skill(cbp-task-complete)",
+      "Skill(cbp-task-create)",
+      "Skill(cbp-task-start)",
+      "Skill(cbp-task-testing)",
+      "Skill(cbp-todo)",
+      "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_launch",
+      "mcp__codebyplan__get_launches",
+      "mcp__codebyplan__get_library_doc_job",
+      "mcp__codebyplan__get_next_action",
+      "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_work_plan",
+      "mcp__codebyplan__get_worktrees",
+      "mcp__codebyplan__list_tech_stack_sync_sessions",
+      "mcp__codebyplan__get_chunk",
+      "mcp__codebyplan__list_migrations",
+      "mcp__codebyplan__lookup_symbol",
+      "mcp__codebyplan__resolve_library_id",
+      "mcp__codebyplan__search_chunks",
+      "mcp__codebyplan__health_check",
+      "mcp__codebyplan__add_library",
+      "mcp__codebyplan__add_round",
+      "mcp__codebyplan__complete_round",
+      "mcp__codebyplan__update_round",
+      "mcp__codebyplan__complete_checkpoint",
+      "mcp__codebyplan__create_checkpoint",
+      "mcp__codebyplan__update_checkpoint",
+      "mcp__codebyplan__complete_task",
+      "mcp__codebyplan__create_task",
+      "mcp__codebyplan__update_task",
+      "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__list_invites",
+      "mcp__codebyplan__list_members",
+      "mcp__codebyplan__update_eslint_repo_config",
+      "mcp__codebyplan__update_server_config",
+      "mcp__codebyplan__update_task_template",
+      "Bash(codebyplan whoami:*)",
+      "Bash(npx codebyplan whoami:*)",
+      "Bash(codebyplan resolve-worktree:*)",
+      "Bash(npx codebyplan resolve-worktree:*)",
+      "Bash(codebyplan statusline:*)",
+      "Bash(npx codebyplan statusline:*)",
+      "Bash(codebyplan ports:*)",
+      "Bash(npx codebyplan ports:*)",
+      "Bash(codebyplan tech-stack:*)",
+      "Bash(npx codebyplan tech-stack:*)",
+      "Bash(codebyplan eslint:*)",
+      "Bash(npx codebyplan eslint:*)",
+      "Bash(codebyplan round:*)",
+      "Bash(npx codebyplan round:*)",
+      "Bash(codebyplan help:*)",
+      "Bash(npx codebyplan help:*)",
+      "Bash(codebyplan --version:*)",
+      "Bash(npx codebyplan --version:*)",
+      "Bash(codebyplan bump:*)",
+      "Bash(npx codebyplan bump:*)",
+      "Bash(codebyplan scaffold-publish-workflow:*)",
+      "Bash(npx codebyplan scaffold-publish-workflow:*)"
     ]
   },
-  "attribution": { "commit": "", "pr": "" },
+  "attribution": {
+    "commit": "",
+    "pr": ""
+  },
   "showClearContextOnPlanAccept": false,
   "syntaxHighlightingDisabled": false
 }

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

@@ -76,6 +76,8 @@ Rules follow `Tool` or `Tool(specifier)`. Evaluated in order: **deny → ask →
 
 Full patterns: [reference/permission-rules.md](reference/permission-rules.md).
 
+CBP-specific policy — which `codebyplan` CLI commands, `mcp__codebyplan__*` tools, and `/cbp-*` skills are pre-categorized `allow` vs `ask`, why, and how `codebyplan claude install/update` auto-populates them: [reference/cbp-permission-policy.md](reference/cbp-permission-policy.md).
+
 Common examples:
 
 ```json

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

@@ -0,0 +1,48 @@
+# CodeByPlan Permission Policy
+
+How the CodeByPlan surface — CLI commands, `mcp__codebyplan__*` tools, and `/cbp-*` skills — is pre-categorized into `permissions.allow` / `permissions.ask` in the settings the `codebyplan` package ships. Authored by CHK-157.
+
+## Where it lives + how it propagates
+
+The curated arrays live in `templates/settings.project.base.json` inside the `codebyplan` npm package. `codebyplan claude install` and `codebyplan claude update` **union-merge** those `allow` / `ask` / `deny` arrays into the consuming repo's `.claude/settings.json` (the merge engine is `mergeBaseSettingsIntoSettings` in `src/lib/settings-merge.ts`); `codebyplan claude uninstall` strips them back out (`stripBaseSettingsFromSettings`). A user's own permission entries are preserved across all three operations (union on merge, membership-filter on strip).
+
+No new plumbing was added — the categorization is **data** in the base template plus the completeness guard described below.
+
+## The interaction with `bypassPermissions`
+
+CBP repos ship `permissions.defaultMode: "bypassPermissions"`. Under that mode, routine tool calls are auto-allowed without prompting — so the `allow` list is mostly an **explicit, documented enumeration** (and it takes effect verbatim if a repo ever lowers the mode). The harness still honors `ask` and `deny` under bypass, which is why the base settings have always carried an `ask` list (`git push --force`, `pnpm add`, …). Therefore:
+
+- **`ask` is the operative "decide carefully" surface** — the deliberate stop-and-confirm set.
+- **`deny`** is the hard block (dangerous `rm -rf` variants).
+- **`allow`** is the explicit full enumeration of the rest of the CBP surface.
+
+Precedence is `deny > ask > allow`; arrays union across scopes (managed/user/project/local).
+
+## The three tiers
+
+### `allow` — the autonomous workflow surface
+
+- **All `/cbp-*` skills** except the production-shipment trio below. 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.
+- **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`.
+
+### `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.
+- **Destructive / admin / external MCP tools**: `delete_session_log`, `delete_worktree`, `delete_launch`, `create_repo`, `create_launch`, `update_launch`, `release_assignment`, and the membership tools `invite_member`, `remove_member`, `change_role`, `accept_invite`, `revoke_invite`.
+- **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/`).
+
+### `deny` — unchanged
+
+The pre-existing dangerous-`rm -rf` blocks. This policy does not alter `deny` semantics.
+
+## Completeness guard (the "decide carefully" guarantee)
+
+`src/lib/settings-permissions-completeness.test.ts` re-derives the live surface from source — skill directory names under `templates/skills/`, `registerToolWithAuthz(server, "...")` names in `packages/mcp-tools/src/tools/*.ts`, and `arg === "..."` CLI subcommands in `src/index.ts` — and fails if any item is not in exactly one tier. So a **newly-added skill, MCP tool, or CLI subcommand forces a deliberate allow-vs-ask decision** before the suite goes green; nothing slips in uncategorized. The test also round-trips the curated arrays through the install-merge and uninstall-strip engine.
+
+When you add a skill / MCP tool / CLI subcommand, add its matching rule (`Skill(<name>)`, `mcp__codebyplan__<name>`, or `Bash(codebyplan <sub>:*)` + `Bash(npx codebyplan <sub>:*)`) to `allow` or `ask` in `templates/settings.project.base.json` — and mirror it into any dogfooding `.claude/settings.json`.
+
+## Scope
+
+`scope: org-shared` — CBP-framework infrastructure that lands identically in every consuming repo via the `codebyplan` package.

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

@@ -30,6 +30,8 @@ Before any shipment logic, ensure the feat branch is current against main. Shipm
 2. If the skill exits with failure (offline, unresolved conflicts, user-aborted): surface the failure and STOP `/cbp-checkpoint-end` — shipment is not safe until the branch is reconciled. The user resolves and re-invokes.
 3. On clean success: continue to Step 1.
 
+> **Version bumps ride this shipment automatically.** `codebyplan ship` (invoked by `/cbp-ship-main` in Step 5) patch-bumps every changed workspace package and commits `chore(release): bump versions` on the feat branch AFTER this main-sync merge and BEFORE push + PR creation — so the bump rides the same feat→main PR (no separate release PR). No manual bump step is required here; the planned bumps surface in the Step 5 report. See `cbp-ship/reference/versioning.md` (`in-branch-bump` mode).
+
 ### Step 1: Get Active Checkpoint
 
 Use MCP `get_current_task` with repo_id. Get the active checkpoint.
@@ -195,6 +197,7 @@ context.shipment: {
   timestamp: [ISO],
   branch_config: { base, protected },
   feat_to_base: { pr_url, merged: true/false },
+  version_bumps: [...],     // from `codebyplan ship` bumps[] — packages patch-bumped on the feat branch this shipment
   surfaces: [...],          // populated by /cbp-ship — per-surface deploy results
   skipped: [...],           // populated by /cbp-ship — surfaces explicitly skipped
   stale_branches_cleaned: [list of deleted git branches],
@@ -211,6 +214,10 @@ Present summary:
 ### Branch Promotion
 - **feat -> [BASE]**: [PR URL] (merged)
 
+### Version Bumps
+- [package]: [currentVersion] → [nextVersion]
+(From `context.shipment.version_bumps[]` — committed as `chore(release): bump versions`; publishes on merge. Omit this section if no packages were bumped.)
+
 ### Runtime Surfaces (via /cbp-ship)
 | Surface | Variant | Status | URL/ID |
 | ... | ... | ... | ... |

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, plus `caller_worktree_id: CALLER_WT` so the hard-lock pre-guard accepts the call (omit `caller_worktree_id` only when `CALLER_WT` is empty). 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. 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`.
 
 ### 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, with caller_worktree_id pre-guard)
+- **Writes**: MCP `update_checkpoint` (status + worktree_id; server resolves caller worktree from JWT/ctx)
 - **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`

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

@@ -49,7 +49,7 @@ RESOLVE_JSON=$(npx codebyplan resolve-worktree --json)
 
 Extract `worktree_id` and `error_kind` from the JSON output.
 
-- `error_kind` is `null` or `"tuple_miss"` → healthy. `WORKTREE_ID` = `worktree_id` (may be `null`: a legitimate main-repo or unregistered-worktree case — proceed normally; downstream hard-lock pre-guards may reject mutations on assigned rows).
+- `error_kind` is `null` or `"tuple_miss"` → healthy. `WORKTREE_ID` = `worktree_id` (may be `null`: a legitimate main-repo or unregistered-worktree case — proceed normally; the server resolves worktree identity from the JWT/ctx, falling back to the repo main-worktree when no specific worktree is matched).
 - `error_kind` is `local_config_read_failed`, `local_config_write_failed`, `legacy_file_blocks_dir`, `api_failed`, `git_failed`, or `unhandled` → **broken local state**. Hold the `error_kind` for Step 6 to display as a distress warning. Session continues (non-blocking — unlike `/cbp-todo`, session-start does NOT hard-stop on a non-tuple-miss distress).
 
 Pass `WORKTREE_ID` to MCP tools that support it. Null `WORKTREE_ID` means the (device, path, branch) tuple is unregistered — note this for Step 6.

package/templates/skills/{cbp-e2e-setup → cbp-setup-e2e}/SKILL.md

@@ -1,6 +1,6 @@
 ---
 scope: org-shared
-name: cbp-e2e-setup
+name: cbp-setup-e2e
 description: Detect installed E2E frameworks, ask which to enable, record credentials source (gitignored env-file path + var names only, never secrets), and write/refresh .codebyplan/e2e.json. Interactive, idempotent.
 argument-hint: "[--force]"
 model: sonnet