codebyplan 1.13.43 → 1.13.45

package/package.json

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

package/templates/agents/cbp-task-check.md

@@ -82,9 +82,7 @@ Review all QA items across all rounds:
 - **Auto items**: Verify all passed (build, lint, types, tests)
 - **Default items**: Verify all resolved (pass or skipped with reason)
 
-**E2E pass vs skipped distinction**: When reading `auto_qa.items[]` for `check: 'e2e'`, do NOT conflate `status: 'pass'` with `status: 'skipped'`. A spec that ran with `passed === 0 && skipped > 0` for any path touching `files_changed` is a hard fail, not a pass — verdict text MUST explicitly call this out: "E2E spec authored but assertions did not execute (skip-gated)." Do NOT issue a READY verdict on a zero-assertion e2e run; route to a fix round per `rules/e2e-mandatory.md`.
-
-**Committed-screenshot check**: For any round where `round.context.e2e_eligible[]` is non-empty, verify `round.context.e2e_gallery[]` is non-empty. Refuse a READY verdict when it is empty — verdict text: "E2E ran but produced zero committed screenshots — open a fix round per `rules/e2e-mandatory.md` § Committed-Screenshot Enforcement." Sole exception: when `vscode-test` is the ONLY eligible framework, an empty `e2e_gallery[]` is allowed (SD-3, behavior-only extensions).
+**E2E deterministic gate**: For each round where `round.context.e2e_eligible[]` is non-empty, run `codebyplan e2e verify-round --round-id <round_id> --task-id <task_id>`. Exit 0 = pass. Exit 1 = hard-fail — refuse a READY verdict and surface the stdout JSON's `failed_checks[]` verbatim in the verdict text. The CLI deterministically evaluates all three e2e hard-fails that were previously judged manually: `e2e_eligible_skipped` (eligible framework with no specialist output and no valid skip reason), `zero_assertion_run` (`passed === 0 && skipped > 0` on a path touching `files_changed` — "E2E spec authored but assertions did not execute (skip-gated)"), and `empty_gallery` (eligible UI-touching run with zero committed screenshots, per `rules/e2e-mandatory.md` § Committed-Screenshot Enforcement; the sole vscode-test-only exception is honored by the CLI). On any exit-1, route to a fix round per `rules/e2e-mandatory.md`.
 
 List any pending or failed items. Determine if they are blockers.
 

package/templates/agents/cbp-task-planner.md

@@ -552,13 +552,15 @@ plan.waves:
 
 If `files_to_modify[]` contains ≤5 files across a single app, skip decomposition and emit a single wave or omit `waves[]` entirely (single-wave default in `round-execute` handles this gracefully).
 
-**Verification checklist** before finalising waves:
+**Verification** before finalising waves — invariants I (disjoint files), II (acyclic `depends_on` DAG), and III (3–15 files per wave, with the small-plan lower-bound exemption) are deterministic set/graph checks; run the validator instead of self-checking them in prose:
 
-- [ ] Every file in `files_to_modify[]` appears in exactly one wave
-- [ ] `depends_on[]` forms a DAG (no cycles)
-- [ ] UI-bearing waves have `frontend-design` + `frontend-a11y` in `skill_preloads[]`
-- [ ] Each wave has ≥3 files (if not, merge into sibling wave)
-- [ ] No wave has >15 files (if so, apply the proximity-split algorithm)
+```bash
+printf '%s' "$PLAN_JSON" | codebyplan validate-waves --json
+```
+
+(`$PLAN_JSON` is the `{ "waves": [...] }` structure; pass a file path as the first argument instead of stdin if preferred.) Exit 0 = invariants I–III satisfied. Exit non-zero = one or more violations — the `--json` `violations[]` array names the failing invariant (`I`/`II`/`III`) and offending wave/file; fix the decomposition and re-run before emitting the plan. The validator does NOT check invariant IV (UI skill preloads) — that remains a manual step:
+
+- [ ] UI-bearing waves have `frontend-design` + `frontend-a11y` in `skill_preloads[]` (invariant IV — not covered by `validate-waves`)
 
 ### Phase 6: Build Context Summary
 

package/templates/github-workflows/publish.yml

@@ -2,14 +2,16 @@
 #
 # 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.
+# It also auto-publishes prerelease versions (e.g. 1.14.0-beta.1) from feat/**
+# branches to a scoped dist-tag (e.g. --tag beta) — see the beta channel docs
+# for the full workflow. 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
+#              in the "Check version vs published" and exact-version check steps
 #
 # 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.
@@ -20,6 +22,7 @@ on:
   push:
     branches:
       - main
+      - "feat/**"
     paths:
       - "packages/codebyplan-package/**"
   workflow_dispatch:
@@ -40,6 +43,7 @@ jobs:
     outputs:
       should_publish: ${{ steps.check.outputs.should_publish }}
       version: ${{ steps.check.outputs.version }}
+      dist_tag: ${{ steps.check.outputs.dist_tag }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -54,27 +58,80 @@ jobs:
           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.
+          # Compute dist-tag from version:
+          #   prerelease (contains hyphen) → extract id between '-' and first '.'
+          #   e.g.  1.14.0-beta.1 → "beta";  1.14.0-rc.1 → "rc"
+          #   stable → "latest"
           case "$VERSION" in
             *-*)
-              echo "VERSION=${VERSION} is a pre-release — skipping auto-publish."
-              echo "should_publish=false" >> "$GITHUB_OUTPUT"
-              exit 0
+              PRE_ID="${VERSION#*-}"
+              DIST_TAG="${PRE_ID%%.*}"
+              ;;
+            *)
+              DIST_TAG="latest"
               ;;
           esac
+          echo "dist_tag=${DIST_TAG}" >> "$GITHUB_OUTPUT"
 
-          # Manual dispatch: always publish (recovery / forced re-publish path).
+          # ── workflow_dispatch ──────────────────────────────────────────────
+          # Manual trigger: always publish (recovery / forced re-publish path).
+          # Uses the computed dist_tag so manual prerelease publishes are tagged
+          # correctly.
           if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            echo "Manual dispatch — skipping gt check, will publish."
+            echo "Manual dispatch — will publish (dist-tag: ${DIST_TAG})."
             echo "should_publish=true" >> "$GITHUB_OUTPUT"
             exit 0
           fi
 
-          # Push path: compare committed version against the npm registry.
+          # ── feat/** push ───────────────────────────────────────────────────
+          # C4 guard: three conditions must hold before publishing from feat/**:
+          #   (1) prerelease-required: stable versions on feat/** are skipped.
+          #   (2) exact-version check: if this exact version is already on npm, skip.
+          #   (3) path filter: already enforced by on.push.paths above.
+          case "${{ github.ref }}" in
+            refs/heads/feat/*)
+              case "$VERSION" in
+                *-*)
+                  # Prerelease — check if this exact version already exists on npm.
+                  EXACT_OUT=$(npm view "codebyplan@${VERSION}" version 2>&1)
+                  EXACT_EXIT=$?
+                  if [ "$EXACT_EXIT" -eq 0 ]; then
+                    echo "VERSION=${VERSION} already published — skipping (exact-version guard)."
+                    echo "should_publish=false" >> "$GITHUB_OUTPUT"
+                    exit 0
+                  fi
+                  if echo "$EXACT_OUT" | grep -q "E404"; then
+                    echo "VERSION=${VERSION} not yet published — will publish (dist-tag: ${DIST_TAG})."
+                    echo "should_publish=true" >> "$GITHUB_OUTPUT"
+                    exit 0
+                  fi
+                  # Non-E404 failure: transient registry error — abort to avoid
+                  # a duplicate publish in a degraded state.
+                  echo "ERROR: npm view codebyplan@${VERSION} failed (exit ${EXACT_EXIT}): ${EXACT_OUT}"
+                  exit 1
+                  ;;
+                *)
+                  # C4 prerelease-required gate: stable versions on feat/** skip.
+                  echo "VERSION=${VERSION} is not a prerelease — feat/** branches require a prerelease version (e.g. run 'codebyplan bump --prerelease beta'). Skipping."
+                  echo "should_publish=false" >> "$GITHUB_OUTPUT"
+                  exit 0
+                  ;;
+              esac
+              ;;
+          esac
+
+          # ── main push ──────────────────────────────────────────────────────
+          # Prerelease versions must never auto-publish to latest from main.
+          # The version core (X.Y.Z) has no hyphen, so any '-' marks a prerelease.
+          case "$VERSION" in
+            *-*)
+              echo "VERSION=${VERSION} is a pre-release — skipping auto-publish on main (use a feat/** branch or workflow_dispatch)."
+              echo "should_publish=false" >> "$GITHUB_OUTPUT"
+              exit 0
+              ;;
+          esac
+
+          # Stable on main: 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)
@@ -88,7 +145,9 @@ jobs:
             echo "ERROR: npm view failed (exit ${NPM_EXIT}): ${NPM_OUT}"
             exit 1
           fi
-          PUBLISHED="$NPM_OUT"
+          # Extract the first semver-looking line so a registry deprecation/advisory
+          # notice in NPM_OUT cannot corrupt the sort -V comparison below.
+          PUBLISHED=$(printf '%s\n' "$NPM_OUT" | grep -E '^[0-9]+\.[0-9]+\.[0-9]+' | head -n1)
 
           # 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)
@@ -147,7 +206,7 @@ jobs:
         working-directory: packages/codebyplan-package
         run: |
           echo "dry_run=true — skipping actual publish."
-          echo "Would publish: codebyplan@${{ needs.check-version.outputs.version }}"
+          echo "Would publish: codebyplan@${{ needs.check-version.outputs.version }} (dist-tag: ${{ needs.check-version.outputs.dist_tag }})"
 
       # 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
@@ -158,10 +217,14 @@ jobs:
       # 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.
+      #
+      # --tag: routes stable publishes to "latest" and prerelease publishes to
+      # the prerelease id (e.g. "beta", "rc"). C1 guarantee: betas never land on
+      # "latest" because dist_tag is computed from the version string.
       - name: Publish to npm
         if: ${{ github.event_name != 'workflow_dispatch' || inputs.dry_run != true }}
         working-directory: packages/codebyplan-package
-        run: npm publish --access public
+        run: npm publish --access public --tag ${{ needs.check-version.outputs.dist_tag }}
 
   tag-and-release:
     name: Tag + GitHub release
@@ -199,9 +262,18 @@ jobs:
           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
+            # C1 guard: prerelease versions get --prerelease (NOT --latest);
+            # stable versions get --latest (existing behaviour preserved).
+            if echo "${VERSION}" | grep -q "-"; then
+              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})" \
+                --prerelease
+            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
+            fi
             echo "Created GitHub release ${TAG}."
           fi

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

@@ -1,4 +1,5 @@
 #!/bin/bash
+# @scope: org-shared
 # @hook: PostToolUse Edit|Write
 # Hook: PostToolUse for Edit|Write on hook files
 # Purpose: Run test-hooks.sh when a plugin hook file is modified.

package/templates/hooks/cbp-e2e-spec-patterns.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# @scope: org-shared
+# @event: PreToolUse
+# @matcher: Edit|Write|MultiEdit
+# Guard spec files against two patterns banned by rules/e2e-mandatory.md and
+# context/testing/e2e.md:
+#
+#  1. In-spec env skip gates — test.skip(!process.env.X, ...) bypasses preflight,
+#     produces zero-assertion runs, and hides missing env vars behind a green check.
+#     (rules/e2e-mandatory.md § No In-Spec Env-Skip Gate)
+#
+#  2. waitForLoadState("networkidle") locators — networkidle is deprecated in
+#     Playwright and causes flaky / hanging tests; use load or domcontentloaded
+#     instead. (context/testing/e2e.md § locator hygiene)
+#
+# Only fires on spec files: file_path ending in .spec.ts OR containing /e2e/
+# or starting with e2e/.  All other file paths exit 0 immediately.
+#
+# Exit codes:
+#   0  — no violation (or not a spec file)
+#   2  — violation found; message on stderr
+
+set -euo pipefail
+
+INPUT_JSON="$(cat)"
+TOOL_NAME="$(echo "$INPUT_JSON" | jq -r '.tool_name // empty')"
+FILE_PATH="$(echo "$INPUT_JSON" | jq -r '.tool_input.file_path // empty')"
+
+# ------------------------------------------------------------------
+# Fast-path: only enforce on spec / e2e files
+# ------------------------------------------------------------------
+is_spec=0
+case "$FILE_PATH" in
+  *.spec.ts) is_spec=1 ;;
+  */e2e/*) is_spec=1 ;;
+  e2e/*) is_spec=1 ;;
+esac
+
+[ "$is_spec" -eq 0 ] && exit 0
+
+# ------------------------------------------------------------------
+# Extract content depending on tool type
+# ------------------------------------------------------------------
+NEW_CONTENT=""
+if [ "$TOOL_NAME" = "Write" ]; then
+  NEW_CONTENT="$(echo "$INPUT_JSON" | jq -r '.tool_input.content // empty')"
+elif [ "$TOOL_NAME" = "Edit" ]; then
+  NEW_CONTENT="$(echo "$INPUT_JSON" | jq -r '.tool_input.new_string // empty')"
+elif [ "$TOOL_NAME" = "MultiEdit" ]; then
+  NEW_CONTENT="$(echo "$INPUT_JSON" | jq -r '[.tool_input.edits[].new_string // ""] | join("\n")')"
+fi
+
+[ -z "$NEW_CONTENT" ] && exit 0
+
+# ------------------------------------------------------------------
+# Check 1: in-spec env-skip gate (test.skip with process.env)
+# Pattern: test.skip( followed by optional whitespace and optional !
+#           then process.env
+# ------------------------------------------------------------------
+if echo "$NEW_CONTENT" | grep -qE 'test\.skip\([[:space:]]*!?process\.env'; then
+  cat >&2 <<'EOF'
+[hook] cbp-e2e-spec-patterns: in-spec env skip gate detected
+
+  Pattern: test.skip(!process.env.X, ...) or test.skip(process.env.X, ...)
+
+  This pattern is banned by rules/e2e-mandatory.md § "No In-Spec Env-Skip Gate":
+    "Spec files MUST NOT contain in-spec env skip gates such as
+     test.skip(!process.env.X, ...). They bypass preflight, produce
+     zero-assertion runs, and hide missing env vars behind a green check."
+
+  The only valid mechanism for env-conditional skipping is pre-flight
+  (context/testing/e2e.md Step 6.5.1). Configure missing env vars in
+  .codebyplan/e2e.json credential_vars and let the preflight block the run.
+
+EOF
+  exit 2
+fi
+
+# ------------------------------------------------------------------
+# Check 2: waitForLoadState("networkidle") locator
+# networkidle is deprecated and causes flaky / hanging tests.
+# ------------------------------------------------------------------
+if echo "$NEW_CONTENT" | grep -qE 'waitForLoadState\(["'"'"']networkidle["'"'"']\)'; then
+  cat >&2 <<'EOF'
+[hook] cbp-e2e-spec-patterns: waitForLoadState("networkidle") detected
+
+  This locator is banned by context/testing/e2e.md locator hygiene rules.
+  "networkidle" is deprecated in Playwright and causes flaky or hanging tests.
+
+  Use one of the stable alternatives:
+    await page.waitForLoadState("load");            // waits for load event
+    await page.waitForLoadState("domcontentloaded"); // waits for DOM ready
+    await page.waitForURL("...");                    // waits for navigation
+    await expect(locator).toBeVisible();             // waits for element
+
+EOF
+  exit 2
+fi
+
+exit 0

package/templates/hooks/cbp-lint-format-on-edit.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+# @scope: org-shared
 # @hook: PostToolUse Edit|Write
 # Hook: Auto-format and auto-fix lint on edited source files
 # Purpose: Continuous Prettier + ESLint --fix after every Edit/Write.

package/templates/hooks/cbp-maestro-yaml-validate.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# @scope: org-shared
 # @event: PreToolUse
 # @matcher: Edit|Write|MultiEdit
 # Validate maestro flow YAML against the installed CLI's accepted property set.

package/templates/hooks/cbp-pre-commit-quality-gate.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+# @scope: org-shared
 # @hook: PreToolUse Bash
 # Hook: PreToolUse for Bash (git commit commands)
 # Purpose: Block git commits that violate greenfield-lint-zero-warnings,

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

@@ -1,4 +1,5 @@
 #!/bin/bash
+# @scope: org-shared
 # @hook: PreToolUse Bash
 # Hook: PreToolUse for Bash (git commit commands)
 # Purpose: Block git commits when new source files lack test companions

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

@@ -1,4 +1,5 @@
 #!/bin/bash
+# @scope: org-shared
 # @hook: NOT-A-HOOK (test suite for plugin hooks; invoked by cbp-auto-test-hooks.sh)
 # Purpose: Test suite for plugin's shipped hooks. Invoked by cbp-auto-test-hooks.sh whenever a
 #          plugin hook file is edited. Not a PreToolUse/PostToolUse/Notification hook itself —

package/templates/hooks/hooks.json

@@ -28,6 +28,10 @@
           {
             "type": "command",
             "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-maestro-yaml-validate.sh"
+          },
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-e2e-spec-patterns.sh"
           }
         ]
       },

package/templates/hooks/verify-parity.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# @scope: org-shared
+# @event: SessionStart
+# Scope + sibling-parity sweep at session start. Calls `codebyplan claude verify-parity --warn-only`.
+# Fires ONLY in the templates source monorepo (self-guards on templates/ presence); no-op for consumers.
+# Always exits 0 — warn-mode, non-blocking.
+
+set -u
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+[ -z "$REPO_ROOT" ] && exit 0
+[ -d "$REPO_ROOT/packages/codebyplan-package/templates" ] || exit 0
+
+# Prefer the installed binary (fast); fall back to npx for fresh checkouts /
+# environments where the workspace bin is not on PATH (matches cbp-mcp-round-sync.sh).
+if command -v codebyplan >/dev/null 2>&1; then
+  codebyplan claude verify-parity --warn-only 2>&1 || true
+else
+  npx codebyplan claude verify-parity --warn-only 2>&1 || true
+fi
+exit 0

package/templates/rules/parallel-waves.md

@@ -12,7 +12,7 @@ Authoritative expansion of `cbp-task-planner` Phase 5.6. The planner reads this
 
 ## Wave Schema
 
-Each entry in `plan.waves[]` carries these fields (source: `.claude/agents/cbp-task-planner.md:540`):
+Each entry in `plan.waves[]` carries these fields (source: `.claude/agents/cbp-task-planner.md` Phase 5.6 "Output" block):
 
 ```yaml
 - name: string               # short identifier, e.g. "web-ui", "backend", "db"
@@ -34,7 +34,7 @@ Each entry in `plan.waves[]` carries these fields (source: `.claude/agents/cbp-t
   - Above 15: apply the proximity-split algorithm below.
   - Sole exception — trivially small plans are exempt from the lower bound: a plan with fewer than 3 total files uses one single wave, and a single-app plan with ≤5 total files MAY skip decomposition entirely (one wave, or `waves[]` omitted — see `cbp-task-planner` Phase 5.6). Zero waves (omitted `waves[]`) trivially satisfies this invariant.
 
-**(IV) UI skill preloads** — for each wave whose `files[]` contains UI-bearing paths (`*.tsx`, `*.jsx`, `*.scss`, etc.), add `"frontend-design"` and `"frontend-a11y"` to `skill_preloads[]` in that order (source: `.claude/agents/cbp-task-planner.md:532`).
+**(IV) UI skill preloads** — for each wave whose `files[]` contains UI-bearing paths (`*.tsx`, `*.jsx`, `*.scss`, etc.), add `"frontend-design"` and `"frontend-a11y"` to `skill_preloads[]` in that order (source: `.claude/agents/cbp-task-planner.md` Phase 5.6 step "Populate `skill_preloads[]`").
 
 ## Proximity-Split Algorithm
 
@@ -52,8 +52,13 @@ When a wave would exceed 15 files, split it in priority order:
 
 When no cross-app or cross-concern independence is found, the planner emits one wave covering all files. The 15-file cap applies to this single wave — if the total exceeds 15, apply the proximity-split algorithm even though the original decomposition was a single wave.
 
+## Enforcement
+
+Invariants I (disjoint files), II (acyclic `depends_on` DAG), and III (3–15 files per wave, with the small-plan lower-bound exemption) are enforced deterministically by `codebyplan validate-waves [--json]` (`packages/codebyplan-package/src/lib/validate-waves.ts`). The planner runs it at Phase 5.6 against the `{ "waves": [...] }` structure (file-path or stdin input); a non-zero exit lists the violated invariant + offending wave/file. Invariant IV (UI skill preloads) is out of the validator's scope and stays a planner manual step.
+
 ## Cross-References
 
-- `agents/cbp-task-planner.md` Phase 5.6 — consumer of this rule; steps 1–6 and verification checklist.
+- `agents/cbp-task-planner.md` Phase 5.6 — consumer of this rule; steps 1–6 and the `validate-waves` verification call.
+- `packages/codebyplan-package/src/lib/validate-waves.ts` — deterministic enforcement of invariants I–III.
 - `agents/cbp-round-executor.md` Step 2.6 — wave-mode skill preloads.
 - `skills/cbp-round-execute/SKILL.md` Step 3 — per-wave executor dispatch.

package/templates/rules/scope-vocabulary.md

@@ -4,7 +4,7 @@ scope: org-shared
 
 # Scope Vocabulary
 
-Canonical scope-marker enum for `.claude/` files. Every CBP-managed agent, skill, rule, and hook script must declare exactly one `scope:` value from the enum below. The marker is enforced by three validators (cross-linked at the bottom of this file).
+Canonical scope-marker enum for `.claude/` files. Every CBP-managed agent, skill, rule, and hook script must declare exactly one `scope:` value from the enum below. The marker is enforced by four validators (cross-linked at the bottom of this file).
 
 ## Enum values
 
@@ -57,8 +57,9 @@ Used by `.sh` hook scripts and `.sh` tooling under `.claude/`. Place the marker
 
 ## Enforcement
 
-Three validators enforce this enum. A file missing the marker (or carrying a non-enum value) fails validation:
+Four validators enforce this enum. A file missing the marker (or carrying a non-enum value) fails validation:
 
-- `.claude/hooks/validate-structure-scope.sh` — warns on missing markers across all `.claude/` files at session start.
+- `.claude/hooks/validate-structure-scope.sh` — warns when a `.claude/` file being edited (PreToolUse `Edit|Write`) lacks a scope marker; sourced by `validate-structure.sh`; it is NOT a session-start sweep.
+- `codebyplan claude verify-parity` — sweeps all `.claude/{rules,skills,agents,hooks}` for missing/non-enum scope markers AND runs the sibling-parity check against `templates/`; invoked automatically at session start via `.claude/hooks/verify-parity.sh` (monorepo only); run manually with `--json` for CI.
 - `.claude/skills/cbp-build-cc-agent/scripts/validate-agent.sh` — blocks agent authoring when `scope:` is absent.
 - `.claude/skills/cbp-build-cc-skill/scripts/validate-skill.sh` — blocks skill authoring when `scope:` is absent.

package/templates/settings.project.base.json

@@ -84,6 +84,8 @@
       "Bash(npx codebyplan upgrade-auth:*)",
       "Bash(codebyplan config:*)",
       "Bash(npx codebyplan config:*)",
+      "Bash(codebyplan doctor:*)",
+      "Bash(npx codebyplan doctor:*)",
       "Bash(codebyplan branch:*)",
       "Bash(npx codebyplan branch:*)",
       "Bash(codebyplan ship:*)",
@@ -178,12 +180,20 @@
       "mcp__codebyplan__update_eslint_repo_config",
       "mcp__codebyplan__update_server_config",
       "mcp__codebyplan__update_task_template",
+      "Bash(codebyplan check:*)",
+      "Bash(npx codebyplan check:*)",
+      "Bash(codebyplan session:*)",
+      "Bash(npx codebyplan session:*)",
+      "Bash(codebyplan supabase:*)",
+      "Bash(npx codebyplan supabase:*)",
       "Bash(codebyplan whoami:*)",
       "Bash(npx codebyplan whoami:*)",
       "Bash(codebyplan resolve-worktree:*)",
       "Bash(npx codebyplan resolve-worktree:*)",
       "Bash(codebyplan version-status:*)",
       "Bash(npx codebyplan version-status:*)",
+      "Bash(codebyplan worktree:*)",
+      "Bash(npx codebyplan worktree:*)",
       "Bash(codebyplan statusline:*)",
       "Bash(npx codebyplan statusline:*)",
       "Bash(codebyplan ports:*)",
@@ -214,6 +224,18 @@
       "Bash(npx codebyplan bump:*)",
       "Bash(codebyplan scaffold-publish-workflow:*)",
       "Bash(npx codebyplan scaffold-publish-workflow:*)",
+      "Bash(codebyplan claude verify-parity:*)",
+      "Bash(npx codebyplan claude verify-parity:*)",
+      "Bash(codebyplan slug:*)",
+      "Bash(npx codebyplan slug:*)",
+      "Bash(codebyplan commit:*)",
+      "Bash(npx codebyplan commit:*)",
+      "Bash(codebyplan migration-collisions:*)",
+      "Bash(npx codebyplan migration-collisions:*)",
+      "Bash(codebyplan validate-waves:*)",
+      "Bash(npx codebyplan validate-waves:*)",
+      "Bash(codebyplan e2e:*)",
+      "Bash(npx codebyplan e2e:*)",
       "Bash(codebyplan arch-map:*)",
       "Bash(npx codebyplan arch-map:*)"
     ]

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

@@ -170,7 +170,17 @@ Other teams' CLAUDE.md files in the ancestor tree get picked up by default. Excl
 
 Managed policy CLAUDE.md cannot be excluded.
 
-### Step 9 — Verify with `/memory`
+### Step 9 — Validate
+
+Run the validator:
+
+```bash
+bash "${CLAUDE_SKILL_DIR}/scripts/validate-claude-file.sh" "{path-to-claude-file}"
+```
+
+It checks: at least one H1 heading present, `@path` imports all resolve relative to the file's directory (or repo root), line count (warns at 200, errors at 400), warns if `scope:` marker appears in frontmatter, warns if filename is neither `CLAUDE.md` nor `CLAUDE.local.md`.
+
+### Step 10 — Verify with `/memory`
 
 Run `/memory` to confirm the file is loaded. The list shows all CLAUDE.md, CLAUDE.local.md, and rules files in effect.
 

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

@@ -0,0 +1,72 @@
+#!/bin/bash
+# @scope: org-shared
+# Validate a CLAUDE.md or CLAUDE.local.md file.
+# Usage: validate-claude-file.sh <path-to-claude-file>
+# Exit 0 = valid, exit 1 = invalid (errors printed to stderr).
+
+set -euo pipefail
+
+FILE="${1:?Usage: validate-claude-file.sh <path-to-claude-file>}"
+
+if [ ! -f "$FILE" ]; then
+  echo "ERROR: file not found: $FILE" >&2
+  exit 1
+fi
+
+errors=0
+err() { echo "  - $1" >&2; errors=$((errors + 1)); }
+
+# Filename check — warn if not a known CLAUDE.md variant
+fname=$(basename "$FILE")
+if [ "$fname" != "CLAUDE.md" ] && [ "$fname" != "CLAUDE.local.md" ]; then
+  echo "  WARN: unexpected filename '$fname' — expected CLAUDE.md or CLAUDE.local.md" >&2
+fi
+
+# At least one H1 heading must be present
+if ! grep -qE '^# ' "$FILE"; then
+  err "missing H1 heading"
+fi
+
+# Line count thresholds
+lines=$(wc -l < "$FILE")
+if [ "$lines" -ge 400 ]; then
+  err "file is $lines lines (hard limit 400; split with @path imports or nested CLAUDE.md files)"
+elif [ "$lines" -ge 200 ]; then
+  echo "  WARN: file is $lines lines (recommended max 200; consider splitting)" >&2
+fi
+
+# @path import resolution — each @path token must resolve to an existing file.
+# Tries both: relative to the file's directory, and relative to cwd (repo root).
+filedir=$(dirname "$FILE")
+while IFS= read -r imp; do
+  [ -z "$imp" ] && continue
+  ipath="${imp#@}"
+  if [ "${ipath:0:1}" = "/" ]; then
+    # absolute path
+    if [ ! -f "$ipath" ]; then
+      err "@import path '$ipath' does not exist"
+    fi
+  elif [ -f "$filedir/$ipath" ]; then
+    : # ok — resolves relative to the file's directory
+  elif [ -f "$ipath" ]; then
+    : # ok — resolves relative to cwd (repo root)
+  else
+    err "@import path '$ipath' does not exist (tried: $filedir/$ipath, $ipath)"
+  fi
+done < <(grep -oE '^[[:space:]]*@[^[:space:]@]+' "$FILE" 2>/dev/null | sed 's/^[[:space:]]*//' 2>/dev/null || true)
+
+# Warn if YAML frontmatter contains a scope: marker (CLAUDE.md is not a rule/skill/agent file)
+if head -1 "$FILE" | grep -qE '^---[[:space:]]*$'; then
+  fm=$(awk '/^---[[:space:]]*$/{n++; next} n==1{print} n==2{exit}' "$FILE")
+  if grep -qE '^scope:[[:space:]]*' <<< "$fm"; then
+    echo "  WARN: CLAUDE.md has a scope: frontmatter field — scope markers belong in rule/skill/agent files, not CLAUDE.md" >&2
+  fi
+fi
+
+if [ "$errors" -gt 0 ]; then
+  echo "validation FAILED ($errors issue(s)) for $FILE" >&2
+  exit 1
+fi
+
+echo "validation OK: $FILE"
+exit 0