codebyplan 1.13.0 → 1.13.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.0",
+  "version": "1.13.4",
   "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

@@ -2,7 +2,7 @@
 
 The `codebyplan` npm package ships a small, portable set of Claude Code hooks. They run in your project, use only generic primitives (`git rev-parse`, `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_PLUGIN_ROOT}`), and degrade gracefully (exit 0) when their preconditions aren't met.
 
-Hook registration lives in [`hooks/hooks.json`](./hooks.json) — PreToolUse, PostToolUse, and Notification events are wired. (`SessionStart`, `SessionEnd`, `Stop`, and `SubagentStop` are also schema-permitted but unused here.)
+Hook registration lives in [`hooks/hooks.json`](./hooks.json) — PreToolUse and PostToolUse events are wired. (`Notification`, `SessionStart`, `SessionEnd`, `Stop`, and `SubagentStop` are also schema-permitted but unused here.)
 
 **`cbp-statusline.sh` is auto-wired via `settings.project.base.json`.** The `statusLine` block is shipped inside `templates/settings.project.base.json` and merged into the consumer's `.claude/settings.json` automatically by `codebyplan claude install` (and on every `codebyplan claude update`). No manual copy-paste is required.
 
@@ -176,22 +176,6 @@ Walks up from the edited file to the nearest `package.json` and uses that packag
 
 ---
 
-### `notify.sh` — Notification, matcher `*`
-
-Sends a desktop notification when Claude Code emits a notification event (waiting for input, task complete, etc.). Title is `[<project-name>] Claude Code`; body is the notification message; clicking the notification focuses VS Code at the project directory (macOS only).
-
-**Cross-platform graceful skip**: exits 0 silently when `terminal-notifier` is not on `$PATH`. Linux, Windows, and macOS hosts without Homebrew see a no-op — no errors, no warnings.
-
-**VS Code click action**: only attached when running on macOS (`$OSTYPE` matches `darwin*`) AND the `code` CLI is on `$PATH`. On other hosts the notification still fires but is non-clickable.
-
-**Install hint** (macOS): `brew install terminal-notifier`. On other platforms the hook is a no-op — substitute your own notification mechanism via a settings.json override if desired.
-
-**Blocks vs warns**: never blocks — exit 0 always. Notification hooks must never block Claude.
-
-**Opt out**: settings.json override or plugin disable.
-
----
-
 ### `auto-test-hooks.sh` — PostToolUse, matcher `Edit|Write`
 
 Triggers `test-hooks.sh` automatically when any `*/hooks/*.sh` file is edited. Catches accidental breakage of the plugin's own hooks (or your project's `.claude/hooks/` if you author your own) at edit time, before the broken hook runs against future tool calls.
@@ -244,9 +228,9 @@ After a `complete_round` MCP call succeeds, reconciles the round's `files_change
 
 ### `test-hooks.sh` — invoked by `auto-test-hooks.sh`
 
-Test suite for the plugin's 10 registered hooks. Runs two passes:
+Test suite for the plugin's 9 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-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`, `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-hooks.sh

@@ -62,7 +62,7 @@ for hook_file in "$HOOKS_DIR"/*.sh; do
 
   # Check for header comments (required for documentation generation).
   # Accept either marker convention used across the plugin's hooks:
-  #   - "# Hook:" + "# Purpose:" (used by notify, auto-test-hooks, etc.)
+  #   - "# Hook:" + "# Purpose:" (used by auto-test-hooks, etc.)
   #   - "# @event:" + a description line (used by maestro-yaml-validate, etc.)
   if (grep -q '^# Hook:' "$hook_file" && grep -q '^# Purpose:' "$hook_file") \
      || grep -q '^# @event:' "$hook_file"; then
@@ -77,14 +77,6 @@ echo ""
 # ===== FUNCTIONAL SMOKE TESTS =====
 echo "## Functional Smoke Tests"
 
-# cbp-notify.sh — graceful-degrade: exit 0 whether or not terminal-notifier is installed
-ACTUAL_EXIT=$(echo '{"message":"test","cwd":"/tmp"}' | bash "$HOOKS_DIR/cbp-notify.sh" >/dev/null 2>&1; echo $?)
-if [ "$ACTUAL_EXIT" = "0" ]; then
-  test_result "cbp-notify.sh graceful-degrade exits 0" "passed" "passed"
-else
-  test_result "cbp-notify.sh graceful-degrade exits 0" "passed" "failed"
-fi
-
 # cbp-lint-format-on-edit.sh — graceful-degrade: CLAUDE_PROJECT_DIR unset → exit 0
 if [ ! -f "$HOOKS_DIR/cbp-lint-format-on-edit.sh" ]; then
   test_result "cbp-lint-format-on-edit.sh present" "passed" "missing"

package/templates/hooks/hooks.json

@@ -60,17 +60,6 @@
           }
         ]
       }
-    ],
-    "Notification": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-notify.sh"
-          }
-        ]
-      }
     ]
   }
 }

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-setup-eslint/SKILL.md

@@ -181,13 +181,14 @@ command + which apps still need their `eslint.config.mjs` generated.
   `reference/*.md`, never silently skip
 - `codebyplan eslint init` failure is non-fatal — print the manual command and still write eslint.json
 - Atomic write (tmp + mv) — never leave eslint.json partial
-- Reference docs track the **latest official** flat-config setup and flag where CBP's DB
-  presets diverge (e.g. ESLint v10 + `eslint-plugin-react-hooks@7` bundled compiler rules)
+- Reference docs contain **only the official upstream ESLint setup** per stack (verbatim from each
+  tool's own docs) — they are not CBP preset opinions. `codebyplan eslint init` generates from the DB
+  presets, which may differ; the reference docs are the canonical official guidance
 
 ## Additional resources
 
 - TypeScript foundation (ESLint v10 flat config): [reference/base.md](reference/base.md)
-- Next.js: [reference/nextjs.md](reference/nextjs.md) · React (+ Storybook): [reference/react.md](reference/react.md)
+- Next.js: [reference/nextjs.md](reference/nextjs.md) · React: [reference/react.md](reference/react.md)
 - Node / Hono / Express: [reference/node.md](reference/node.md) · NestJS: [reference/nestjs.md](reference/nestjs.md)
 - CLI tools: [reference/cli.md](reference/cli.md) · Tailwind CSS: [reference/tailwind.md](reference/tailwind.md)
 - React Native / Expo: [reference/react-native.md](reference/react-native.md)