codebyplan 1.13.44 → 1.13.46

package/package.json

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

@@ -93,8 +93,7 @@ jobs:
               case "$VERSION" in
                 *-*)
                   # Prerelease — check if this exact version already exists on npm.
-                  EXACT_OUT=$(npm view "codebyplan@${VERSION}" version 2>&1)
-                  EXACT_EXIT=$?
+                  EXACT_OUT=$(npm view "codebyplan@${VERSION}" version 2>&1) && EXACT_EXIT=0 || EXACT_EXIT=$?
                   if [ "$EXACT_EXIT" -eq 0 ]; then
                     echo "VERSION=${VERSION} already published — skipping (exact-version guard)."
                     echo "should_publish=false" >> "$GITHUB_OUTPUT"
@@ -134,8 +133,7 @@ jobs:
           # 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)
-          NPM_EXIT=$?
+          NPM_OUT=$(npm view codebyplan version 2>&1) && NPM_EXIT=0 || NPM_EXIT=$?
           if [ "$NPM_EXIT" -ne 0 ]; then
             if echo "$NPM_OUT" | grep -q "E404"; then
               echo "Package not yet published — first publish."
@@ -147,7 +145,7 @@ jobs:
           fi
           # 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)
+          PUBLISHED=$(printf '%s\n' "$NPM_OUT" | grep -E '^[0-9]+\.[0-9]+\.[0-9]+' | head -n1) || true
 
           # 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)

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

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

@@ -39,11 +39,12 @@ A skill that carries a `model:` line is a **gap** — remove it unless a deliber
 
 ### Agents — `model:` + `effort:`
 
-Default `model: sonnet` + `effort: xhigh`. Fifteen of the 16 authoring agents take the default (`cbp-cc-executor`, `cbp-database-agent`, `cbp-improve-claude`, `cbp-improve-round`, `cbp-research`, `cbp-round-executor`, `cbp-security-agent`, `cbp-task-check`, `cbp-task-planner`, `cbp-testing-qa-agent`, `cbp-e2e-playwright`, `cbp-e2e-maestro`, `cbp-e2e-tauri`, `cbp-e2e-vscode`, `cbp-e2e-xcuitest`). The 16th is the one exception:
+Default `model: sonnet` + `effort: xhigh`. Fifteen of the 17 authoring agents take the default (`cbp-cc-executor`, `cbp-database-agent`, `cbp-improve-claude`, `cbp-improve-round`, `cbp-research`, `cbp-round-executor`, `cbp-security-agent`, `cbp-task-check`, `cbp-task-planner`, `cbp-testing-qa-agent`, `cbp-e2e-playwright`, `cbp-e2e-maestro`, `cbp-e2e-tauri`, `cbp-e2e-vscode`, `cbp-e2e-xcuitest`). The other two are exceptions:
 
-| agent                | model | effort | reason                                                                              |
-| -------------------- | ----- | ------ | ----------------------------------------------------------------------------------- |
-| cbp-mechanical-edits | haiku | low    | Mechanical rename/substitution/frontmatter-edit subagent; no judgment, pure dispatch |
+| agent                | model  | effort | reason                                                                              |
+| -------------------- | ------ | ------ | ----------------------------------------------------------------------------------- |
+| cbp-mechanical-edits | haiku  | low    | Mechanical rename/substitution/frontmatter-edit subagent; no judgment, pure dispatch |
+| cbp-map-architecture | sonnet | high   | Read-only module analyzer; bounded structured-map generation, lighter than xhigh     |
 
 `model: inherit` is NOT permitted for agents — pin an explicit alias (`sonnet` / `haiku`) or a full ID.
 
@@ -53,18 +54,13 @@ A skill's `effort:` applies to the inline-running turn (the orchestrator turn th
 
 ## Audit Mode
 
-Invoked with no arguments. Procedure:
-
-1. Glob `packages/codebyplan-package/templates/agents/*.md` and `packages/codebyplan-package/templates/skills/*/SKILL.md`.
-2. For each file, read the frontmatter and parse `model:` + `effort:`.
-3. Apply the convention by surface:
-   - **Skill**: `model:` MUST be ABSENT; `effort:` MUST be present and one of `low`/`medium`/`high`/`xhigh`/`max` (default `xhigh`).
-   - **Agent**: `model:` MUST be present (per the agent table; default `sonnet`); `effort:` present (default `xhigh`).
-4. Emit one pipe-delimited line per file: `path | current_model/current_effort | expected | status`.
-5. Status values:
-   - `ok` — matches the convention.
-   - `gap` — a skill that carries a `model:` line, a skill missing `effort:`, an agent missing/incorrect `model:`, or any missing/invalid `effort:`.
-6. Print a summary: total audited, count `ok`, count `gap`.
+Run `codebyplan claude audit-mode` — it scans `packages/codebyplan-package/templates/agents/*.md` and `packages/codebyplan-package/templates/skills/*/SKILL.md`, applies the convention from the matrix above, and emits a pipe-delimited table:
+
+```
+path | surface | model/effort | expected | status
+```
+
+Plus a summary line: `N audited, N ok, N gaps`. Exits 0 when all files comply; exits 1 on any gap. Pass `--json` for a machine-readable entries array.
 
 The audit is read-only.
 

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

@@ -153,7 +153,17 @@ ln -s ~/company-standards/security.md .claude/rules/security.md
 
 Claude Code resolves symlinks normally. Circular symlinks are detected.
 
-### Step 8 — Verify loading
+### Step 8 — Validate
+
+Run the validator:
+
+```bash
+bash "${CLAUDE_SKILL_DIR}/scripts/validate-rule.sh" "{scope-path}/{name}.md"
+```
+
+It checks: YAML frontmatter present, `scope:` field present and valid enum value, H1 heading present and its kebab-case form matches the filename, `paths:` field (warns if absent — unconditional rules burn context on every session), line count (warns at 100, errors at 200).
+
+### Step 9 — Verify loading
 
 Run `/memory` in a fresh Claude Code session to confirm the rule is listed. If path-scoped, open a file matching the glob to confirm it triggers.
 

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

@@ -0,0 +1,69 @@
+#!/bin/bash
+# @scope: org-shared
+# Validate a Claude Code rule file at .claude/rules/{name}.md.
+# Usage: validate-rule.sh <path-to-rule-file>
+# Exit 0 = valid, exit 1 = invalid (errors printed to stderr).
+
+set -euo pipefail
+
+FILE="${1:?Usage: validate-rule.sh <path-to-rule-file>}"
+
+if [ ! -f "$FILE" ]; then
+  echo "ERROR: file not found: $FILE" >&2
+  exit 1
+fi
+
+errors=0
+err() { echo "  - $1" >&2; errors=$((errors + 1)); }
+
+# Frontmatter must be present
+if ! head -1 "$FILE" | grep -qE '^---[[:space:]]*$'; then
+  err "missing YAML frontmatter opener '---'"
+fi
+
+# Extract frontmatter block
+fm=$(awk '/^---[[:space:]]*$/{n++; next} n==1{print} n==2{exit}' "$FILE")
+
+# scope: field required + must match enum
+if ! grep -qE '^scope:[[:space:]]*' <<< "$fm"; then
+  err "missing CBP required field: scope (org-shared|project-shared|repo-only:<repo-name>)"
+else
+  scope_val=$(grep -E '^scope:' <<< "$fm" | head -1 | sed -E 's/^scope:[[:space:]]*//; s/[[:space:]]*$//')
+  if ! [[ "$scope_val" =~ ^(org-shared|project-shared|repo-only:[a-z0-9]([a-z0-9-]*[a-z0-9])?)$ ]]; then
+    err "scope value '$scope_val' is not a valid enum value (org-shared|project-shared|repo-only:<slug>)"
+  fi
+fi
+
+# H1 heading must be present and its kebab-case form must match the filename (sans .md)
+h1=$(grep -m1 '^# ' "$FILE" | sed 's/^# //' || true)
+if [ -z "$h1" ]; then
+  err "missing H1 heading"
+else
+  # Convert H1 to kebab-case: lowercase, spaces→hyphens, strip non-alnum chars (except hyphens)
+  h1_kebab=$(echo "$h1" | tr '[:upper:]' '[:lower:]' | sed 's/ /-/g; s/_/-/g; s/[^a-z0-9-]//g')
+  fname=$(basename "$FILE" .md)
+  if [ "$h1_kebab" != "$fname" ]; then
+    err "H1 '$h1' (kebab: '$h1_kebab') does not match filename '$(basename "$FILE")'"
+  fi
+fi
+
+# paths: warning only — unconditional rules load at every session start (use sparingly)
+if ! grep -qE '^paths:[[:space:]]*' <<< "$fm"; then
+  echo "  WARN: no paths: field — rule loads unconditionally at session start; use sparingly" >&2
+fi
+
+# Line count thresholds (matches cbp-build-cc-rule hook: warn ≥ 100, error ≥ 200)
+lines=$(wc -l < "$FILE")
+if [ "$lines" -ge 200 ]; then
+  err "rule file is $lines lines (hard limit 200; split on topic)"
+elif [ "$lines" -ge 100 ]; then
+  echo "  WARN: rule file is $lines lines (recommended max 100; consider splitting)" >&2
+fi
+
+if [ "$errors" -gt 0 ]; then
+  echo "validation FAILED ($errors issue(s)) for $FILE" >&2
+  exit 1
+fi
+
+echo "validation OK: $FILE"
+exit 0

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

@@ -183,8 +183,8 @@ Applied to every session. Full env-var catalogue: the official Claude Code env-v
 ### Step 9 — Validate and verify
 
 ```bash
-# Pretty-print and validate JSON
-jq . .claude/settings.json
+# Validate structure, $schema, and permission-rule syntax
+bash "${CLAUDE_SKILL_DIR}/scripts/validate-settings.sh" "{scope-path}/settings.json"
 
 # Ask Claude Code itself
 # (inside a session)