codebyplan 1.13.46 → 1.13.49

package/templates/hooks/validate-git-commit.sh

@@ -1,5 +1,4 @@
 #!/bin/bash
-# @scope: org-shared
 # @hook: PreToolUse Bash
 # Hook: PreToolUse for Bash (git commit commands)
 # Purpose: Prevent Claude attribution in git commits
@@ -33,21 +32,70 @@ block() {
   exit 2
 }
 
-# Check for Claude attribution patterns
-# Case-insensitive check for various patterns
+# ---------------------------------------------------------------------------
+# Isolate the commit MESSAGE from the rest of the command.
+#
+# The broad "claude/anthropic" word-check below targets attribution that may
+# land in the commit *message* — NOT benign mentions elsewhere in the command
+# (narration echoes, a `.claude/CLAUDE.md` path argument, a piped subcommand).
+# Scanning the whole command false-positives on those (e.g. an `echo` that
+# says the word "claude", or `git commit .claude/CLAUDE.md -m "..."`). So we
+# extract just the message text:
+#   (a) heredoc bodies   — the `-m "$(cat <<'EOF' ... EOF)"` pattern
+#   (b) -m/--message args — quoted "..." or '...'
+# If no message can be isolated (editor commit, `-F file`), fall back to the
+# whole command so attribution protection is never silently dropped.
+#
+# The specific checks further down (generated-with / co-authored-by / emoji /
+# --author) still scan the WHOLE command — those patterns are precise enough
+# that catching them anywhere is correct, and they backstop this extraction.
+# ---------------------------------------------------------------------------
+extract_commit_message() {
+  local cmd="$1"
+  local out="" delim margs
 
-# Check for "Claude" mentions (but allow CLAUDE.md files and .claude/ folder paths)
-# First, remove CLAUDE.md filenames and .claude(/path|word-end) — BSD-compatible word-boundary via [[:>:]]
-# Word-boundary allows ".claude folder" / ".claude rules" / ".claude/" all as legit folder references
-COMMAND_WITHOUT_FILES=$(echo "$COMMAND" \
+  # (a) Heredoc body. Detect the delimiter (supports <<EOF, <<'EOF', <<-EOF),
+  #     then print the lines strictly between the opener and its closing line.
+  #     Each pipeline ends in sed/awk (exit 0) so a no-match grep cannot trip
+  #     `set -e` via the command substitution.
+  delim=$(printf '%s\n' "$cmd" \
+    | grep -oE "<<-?[[:space:]]*'?[A-Za-z_][A-Za-z0-9_]*'?" \
+    | head -n1 \
+    | sed -E "s/^<<-?[[:space:]]*//; s/'//g")
+  if [ -n "$delim" ]; then
+    out=$(printf '%s\n' "$cmd" | awk -v d="$delim" '
+      start==0 { if (index($0, "<<") && index($0, d)) { start=1 } ; next }
+      start==1 { s=$0; sub(/^[ \t]+/,"",s); sub(/[ \t]+$/,"",s); if (s==d) {start=2; next} print }
+    ')
+  fi
+
+  # (b) Quoted -m / --message argument values.
+  margs=$(printf '%s\n' "$cmd" \
+    | grep -oE -- "(-m|--message)[[:space:]]+(\"[^\"]*\"|'[^']*')" \
+    | sed -E "s/^(-m|--message)[[:space:]]+//; s/^[\"']//; s/[\"']$//")
+
+  printf '%s\n%s\n' "$out" "$margs"
+}
+
+MESSAGE=$(extract_commit_message "$COMMAND")
+# Fall back to scanning the whole command when no message could be isolated.
+if [ -z "$(printf '%s' "$MESSAGE" | tr -d '[:space:]')" ]; then
+  MESSAGE="$COMMAND"
+fi
+
+# Check for Claude attribution in the MESSAGE (case-insensitive).
+# Allow legitimate CLAUDE.md filenames and .claude/ folder paths that may
+# legitimately appear inside a commit message (e.g. a commit *about* them).
+# BSD-compatible word-boundary via [[:>:]].
+MESSAGE_WITHOUT_FILES=$(echo "$MESSAGE" \
   | sed -E 's/CLAUDE(\.[a-z]+)?\.md//gi' \
   | sed -E 's/\.claude(\/[a-zA-Z0-9_./-]*|[[:>:]])//gi' \
   | sed -E 's/\$\{CLAUDE[A-Z_]*\}//g' \
   | sed -E 's/claude-plugin[a-zA-Z0-9_./-]*//gi' \
   | sed -E 's/codebyplan-claude[a-zA-Z0-9_./-]*//gi' \
   | sed -E 's/@codebyplan\/claude[a-zA-Z0-9_./-]*//gi')
-if echo "$COMMAND_WITHOUT_FILES" | grep -qiE 'claude|anthropic'; then
-  block "BLOCKED: Git commit contains Claude/Anthropic attribution. Remove any mention of Claude from the commit message. Author should only be: midevyou <midevyosauhing@gmail.com>"
+if echo "$MESSAGE_WITHOUT_FILES" | grep -qiE 'claude|anthropic'; then
+  block "BLOCKED: Git commit message contains Claude/Anthropic attribution. Remove any mention of Claude from the commit message. Author should only be: midevyou <midevyosauhing@gmail.com>"
 fi
 
 # Check for "Generated with" patterns

package/templates/hooks/validate-git-stash-deny.sh

@@ -1,5 +1,4 @@
 #!/bin/bash
-# @scope: org-shared
 # Hook: PreToolUse Bash
 # Purpose: Deny any `git stash` command. Git stash is banned per the
 #          feedback_no-git-stash auto-memory entry. Alternatives:

package/templates/hooks/validate-structure-lengths.sh

@@ -1,5 +1,4 @@
 #!/bin/bash
-# @scope: org-shared
 # Hook Helper: File-length enforcement for validate-structure.sh
 # Two-tier policy: warn at recommended → stderr notice; block at hard cap (~2× warn) → exit 2
 # Sourced by validate-structure.sh — not run directly.

package/templates/hooks/validate-structure-lib.sh

@@ -1,5 +1,4 @@
 #!/bin/bash
-# @scope: org-shared
 # Hook Helper Library: Shared primitives for validate-structure-*.sh
 # Purpose: Block/warn formatters, path-matching, content extraction,
 #          frontmatter / scope-marker detection, line counting.
@@ -102,3 +101,20 @@ has_yaml_field() {
 has_scope_comment() {
   [ -f "$1" ] && head -5 "$1" 2>/dev/null | grep -q "^# @scope:"
 }
+
+# has_template_twin <rel_path_under_claude>
+# Returns 0 when the codebyplan package ships a template twin for this .claude file
+# (i.e. the file is package-MANAGED — org-shared is its implicit default and a
+# scope marker is NOT required). <rel_path_under_claude> is the path beneath
+# .claude/ (e.g. "rules/foo.md", "skills/x/SKILL.md").
+#   Monorepo: $REPO_ROOT/packages/codebyplan-package/templates/<rel>
+#   Consumer: $REPO_ROOT/node_modules/codebyplan/templates/<rel>
+# Returns non-zero when no twin is found — including when no templates dir is
+# resolvable at all. Callers treat a non-zero result as "user-created", which is
+# the conservative fallback: a scope marker is then required (legacy behavior).
+has_template_twin() {
+  local rel="$1"
+  [ -f "$REPO_ROOT/packages/codebyplan-package/templates/$rel" ] && return 0
+  [ -f "$REPO_ROOT/node_modules/codebyplan/templates/$rel" ] && return 0
+  return 1
+}

package/templates/hooks/validate-structure-patterns.sh

@@ -1,5 +1,4 @@
 #!/bin/bash
-# @scope: org-shared
 # Hook Helper: Pattern validation for validate-structure.sh
 # Purpose: Validate file paths against structure patterns
 # Sourced by validate-structure.sh - not run directly

package/templates/hooks/validate-structure-scope.sh

@@ -1,31 +1,63 @@
 #!/bin/bash
-# @scope: org-shared
 # Hook Helper: Scope marker validation for validate-structure.sh
-# Purpose: Ensure all .claude/ files have a scope marker for structural classification
+# Purpose: Enforce scope markers on USER-CREATED .claude/ files only. Files the
+#          codebyplan package distributes (a template twin exists) are MANAGED:
+#          org-shared is the implicit default, so no marker is required and an
+#          explicit 'org-shared' marker is redundant (warned, non-blocking).
+#          A file with no template twin is user-created and must declare a marker.
 # Sourced by validate-structure.sh - not run directly
 #
-# Expects: $REL_PATH, $FILE_PATH, $EXT, warn(), match_path(),
-#          has_yaml_frontmatter(), has_yaml_field(), has_scope_comment() (from validate-structure-lib.sh)
+# Expects: $REL_PATH, $FILE_PATH, $EXT, $REPO_ROOT, warn(), match_path(),
+#          has_yaml_frontmatter(), has_yaml_field(), has_scope_comment(),
+#          has_template_twin() (from validate-structure-lib.sh)
 
 # Only check .claude/ files
 if ! match_path '^/\.claude/'; then
   return 0 2>/dev/null || true
 fi
 
+# Path beneath .claude/ — used for template-twin (managed) detection.
+_scope_rel="${REL_PATH#/.claude/}"
+
+# Managed = the codebyplan package ships a template twin for this file. When no
+# twin is found (or no templates dir is resolvable) the file is user-created and
+# a marker is required — the conservative fallback that preserves legacy behavior.
+if has_template_twin "$_scope_rel"; then
+  _scope_managed=1
+else
+  _scope_managed=0
+fi
+
+_valid_scope_re='^(org-shared|project-shared|repo-only:[a-z0-9]([a-z0-9-]*[a-z0-9])?)$'
+
 case "$EXT" in
   md)
-    if has_yaml_frontmatter "$FILE_PATH"; then
-      if ! has_yaml_field "$FILE_PATH" scope; then
-        warn "Missing scope: in frontmatter. Add 'scope: org-shared' / 'scope: project-shared' / 'scope: repo-only:<name>' for structural classification. See rules/scope-vocabulary.md."
+    if has_yaml_frontmatter "$FILE_PATH" && has_yaml_field "$FILE_PATH" scope 50; then
+      _scope_val=$(head -50 "$FILE_PATH" 2>/dev/null | grep -E '^scope:' | head -1 \
+        | sed -E 's/^scope:[[:space:]]*//; s/[[:space:]]*#.*$//; s/[[:space:]]*$//')
+      if [ "$_scope_managed" = "1" ] && [ "$_scope_val" = "org-shared" ]; then
+        warn "Redundant 'scope: org-shared' on a package-managed file — org-shared is the implicit default; remove the key. See rules/scope-vocabulary.md."
+      elif ! [[ "$_scope_val" =~ $_valid_scope_re ]]; then
+        warn "Invalid scope value '$_scope_val'. Use org-shared / project-shared / repo-only:<name>. See rules/scope-vocabulary.md."
       fi
-    else
-      warn "Missing frontmatter with scope:. Add YAML frontmatter with 'scope: org-shared' / 'scope: project-shared' / 'scope: repo-only:<name>'. See rules/scope-vocabulary.md."
+    elif [ "$_scope_managed" = "0" ]; then
+      warn "Missing scope: in frontmatter. A user-created .claude/ file must declare 'scope: project-shared' or 'scope: repo-only:<name>' (package-managed files default to org-shared). See rules/scope-vocabulary.md."
     fi
+    # managed + no marker → org-shared implied, no warning.
     ;;
   sh)
-    if ! has_scope_comment "$FILE_PATH"; then
-      warn "Missing # @scope: comment. Add '# @scope: org-shared' / '# @scope: project-shared' / '# @scope: repo-only:<name>' after shebang. See rules/scope-vocabulary.md."
+    if has_scope_comment "$FILE_PATH"; then
+      _scope_val=$(head -5 "$FILE_PATH" 2>/dev/null | grep -E '^# @scope:' | head -1 \
+        | sed -E 's/^# @scope:[[:space:]]*//; s/[[:space:]]*#.*$//; s/[[:space:]]*$//')
+      if [ "$_scope_managed" = "1" ] && [ "$_scope_val" = "org-shared" ]; then
+        warn "Redundant '# @scope: org-shared' on a package-managed hook — org-shared is the implicit default; remove the comment. See rules/scope-vocabulary.md."
+      elif ! [[ "$_scope_val" =~ $_valid_scope_re ]]; then
+        warn "Invalid @scope value '$_scope_val'. Use org-shared / project-shared / repo-only:<name>. See rules/scope-vocabulary.md."
+      fi
+    elif [ "$_scope_managed" = "0" ]; then
+      warn "Missing # @scope: comment. A user-created .claude/ hook must declare '# @scope: project-shared' or '# @scope: repo-only:<name>' (package-managed hooks default to org-shared). See rules/scope-vocabulary.md."
     fi
+    # managed + no marker → org-shared implied, no warning.
     ;;
   json)
     # JSON can't have frontmatter — skip

package/templates/hooks/validate-structure-smoke.sh

@@ -1,5 +1,4 @@
 #!/bin/bash
-# @scope: org-shared
 # Smoke runner for validate-structure-*.sh + validate-structure-lib.sh
 # Iterates fixtures under __test-fixtures__/validate-structure/{good,bad}/
 # Each test case maps a fixture file → simulated rel path inside .claude/

package/templates/hooks/validate-structure-templates.sh

@@ -1,5 +1,4 @@
 #!/bin/bash
-# @scope: org-shared
 # Hook Helper: Template/context suggestion for validate-structure.sh
 # Purpose: Map file locations to applicable templates or context files
 # Sourced by validate-structure.sh - not run directly

package/templates/hooks/validate-structure.sh

@@ -1,5 +1,4 @@
 #!/bin/bash
-# @scope: org-shared
 # @hook: PreToolUse Edit|Write
 # Hook: PreToolUse for Edit|Write
 # Purpose: Validate file paths against structure patterns

package/templates/hooks/verify-parity.sh

@@ -1,5 +1,4 @@
 #!/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.

package/templates/rules/agent-claim-verification.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: agent-claim-verification
 description: Subagents must cite the source file (path:line) or vendor docs before asserting that any JSON key, schema field, env-var name, or external API shape exists.
 paths:

package/templates/rules/architecture-map.md

@@ -1,7 +1,3 @@
----
-scope: org-shared
----
-
 # Architecture Map
 
 When `.claude/architecture/` exists in this repo, per-module map files may be present.

package/templates/rules/cbp-operating-gotchas.md

@@ -1,7 +1,3 @@
----
-scope: org-shared
----
-
 # CBP Operating Gotchas
 
 Cross-repo traps in the CodeByPlan tooling surface (CLI, MCP, git, host platform) that

package/templates/rules/context-file-loading.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 paths:
   - ".claude/context/**/*"
   - ".claude/agents/**/*"

package/templates/rules/e2e-mandatory.md

@@ -1,7 +1,3 @@
----
-scope: org-shared
----
-
 # E2E Mandatory Run Contract
 
 E2E is **opt-out, not opt-in**. Whenever a framework configured in `.codebyplan/e2e.json`

package/templates/rules/parallel-waves.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: parallel-waves
 description: Wave schema, invariants, and proximity-split algorithm for cbp-task-planner Phase 5.6 wave decomposition.
 paths:

package/templates/rules/scope-vocabulary.md

@@ -1,10 +1,15 @@
----
-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 four validators (cross-linked at the bottom of this file).
+Canonical scope-marker enum for `.claude/` files. The marker classifies a structural file's distribution scope — but it is **required only on user-created files**, not on the assets the `codebyplan` package distributes.
+
+## When is a `scope:` marker required?
+
+A `.claude/` structural file (a rule, an agent, a `SKILL.md`, or a `hooks/*.sh`) is one of two kinds:
+
+- **Package-managed** — the `codebyplan` package ships a **template twin** for it (`packages/codebyplan-package/templates/<rel>` in the monorepo, or `node_modules/codebyplan/templates/<rel>` in a consumer repo). Managed files are **`org-shared` by definition** — `org-shared` is the implicit, **markerless** default. A managed file needs **no** `scope:` marker; an explicit `scope: org-shared` on it is **redundant** and validators emit a non-blocking warning to remove it.
+- **User-created** — no template twin exists. These are repo- or project-local additions the package never distributes, so they **must** declare a `scope:` marker (`project-shared` or `repo-only:<name>`; `org-shared` is also accepted but unusual for a non-distributed file).
+
+**Conservative fallback**: when no templates directory is resolvable at all (e.g. `codebyplan` is not installed), twin detection is inactive and every structural file is treated as user-created — a marker is required. Enforcement is never silently dropped.
 
 ## Enum values
 
@@ -57,9 +62,8 @@ Used by `.sh` hook scripts and `.sh` tooling under `.claude/`. Place the marker
 
 ## Enforcement
 
-Four validators enforce this enum. A file missing the marker (or carrying a non-enum value) fails validation:
+`codebyplan claude verify-parity` is the **central enforcer** of the rule above; the other validators are twin-aware helpers. A marker is required only on user-created (no-twin) files; a redundant `org-shared` marker on a managed (twin) file is a non-blocking warning; a present-but-non-enum value always fails:
 
-- `.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.
+- `codebyplan claude verify-parity` — sweeps `.claude/{rules,skills,agents,hooks}`. For each structural file it checks the template twin: a no-twin file missing a marker is a **`missing-scope`** error; a managed file carrying `org-shared` is a **`redundant-scope`** warning (surfaced in `warnings`, never raises the exit code); any present non-enum value is an **`invalid-scope`** error. It also runs the sibling-parity check against `templates/`. Invoked automatically at session start via `.claude/hooks/verify-parity.sh` (monorepo only); run manually with `--json` (emits `{ violations, warnings }`) for CI.
+- `.claude/hooks/validate-structure-scope.sh` — PreToolUse `Edit|Write` helper (sourced by `validate-structure.sh`, NOT a session-start sweep). Warns when a **user-created** `.claude/` file being edited lacks a marker, and warns on a redundant `org-shared` marker when the file is package-managed. Uses `has_template_twin` (in `validate-structure-lib.sh`) for managed detection.
+- `.claude/skills/cbp-build-cc-agent/scripts/validate-agent.sh`, `.../cbp-build-cc-skill/scripts/validate-skill.sh`, `.../cbp-build-cc-rule/scripts/validate-rule.sh` — authoring validators. `scope:` is **optional** at authoring time; these scripts only reject a present-but-non-enum value. The user-created requirement is enforced centrally by `verify-parity`.

package/templates/rules/supabase-branch-lifecycle.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 description: Supabase preview-branch lifecycle mirrors the git feat-branch lifecycle
 paths:
   - "supabase/migrations/**"

package/templates/rules/todo-backend.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 paths:
   - "apps/todo-worker/**"
   - "packages/mcp-tools/src/**"

package/templates/settings.project.base.json

@@ -68,6 +68,18 @@
       "mcp__codebyplan__delete_session_log",
       "mcp__codebyplan__delete_worktree",
       "mcp__codebyplan__release_assignment",
+      "mcp__stripe__create_customer",
+      "mcp__stripe__create_product",
+      "mcp__stripe__create_price",
+      "mcp__stripe__create_payment_link",
+      "mcp__stripe__create_invoice",
+      "mcp__stripe__create_subscription",
+      "mcp__stripe__update_subscription",
+      "mcp__stripe__create_refund",
+      "mcp__stripe__list_customers",
+      "mcp__stripe__list_products",
+      "mcp__stripe__list_prices",
+      "mcp__stripe__list_invoices",
       "Bash(codebyplan setup:*)",
       "Bash(npx codebyplan setup:*)",
       "Bash(codebyplan create-org:*)",
@@ -127,6 +139,7 @@
       "Skill(cbp-ship-configure)",
       "Skill(cbp-standalone-task-check)",
       "Skill(cbp-standalone-task-testing)",
+      "Skill(cbp-stripe)",
       "Skill(cbp-supabase-branch-check)",
       "Skill(cbp-supabase-migrate)",
       "Skill(cbp-supabase-setup)",

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

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-build-cc-agent
 description: Build a Claude Code subagent at .claude/agents/{name}.md (flat form, per the official sub-agents spec) following the official sub-agents spec (frontmatter, tools, model, hooks, skills preload, permission modes, isolation).
 argument-hint: "[agent-name] [--scope=project|user] [--isolation=worktree]"
@@ -49,7 +48,7 @@ Default: `project`. Pass `--scope=user` to override. Use folder form `{scope-pat
 
 Read `${CLAUDE_SKILL_DIR}/templates/agent.md` for the canonical frontmatter set. Fill only fields that matter for the agent; leave the rest out (every field except `name` and `description` is optional).
 
-CBP adds a required `scope:` frontmatter marker (structural classification; not read by Claude Code). Values: `org-shared` | `project-shared` | `repo-only:<repo-name>`. Length hook warns at 400 lines, blocks at 800. Quality details in [reference/cbp-quality.md](reference/cbp-quality.md).
+CBP adds a `scope:` frontmatter marker (structural classification; not read by Claude Code). Values: `org-shared` | `project-shared` | `repo-only:<repo-name>`. It is **required only on user-created agents** — a package-managed agent (template twin under `templates/agents/`) is `org-shared` by default and needs no marker. Length hook warns at 400 lines, blocks at 800. Quality details in [reference/cbp-quality.md](reference/cbp-quality.md).
 
 ### Step 4 — Gather required fields
 
@@ -111,7 +110,7 @@ bash "${CLAUDE_SKILL_DIR}/scripts/validate-agent.sh" "{scope-path}/{name}.md"
 
 (Pass `{scope-path}/{name}/AGENT.md` instead if folder form was chosen.)
 
-It checks: name format, frontmatter parses, required fields present (`name`, `description`, `scope`), tool names are valid, model alias is recognised.
+It checks: name format, frontmatter parses, required fields present (`name`, `description`), the `scope:` value is a valid enum when present (the key itself is optional — required only on user-created agents, enforced centrally by `codebyplan claude verify-parity`), tool names are valid, model alias is recognised.
 
 ### Step 8 — Surface to the user
 

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

@@ -1,7 +1,3 @@
----
-scope: org-shared
----
-
 # Agent Authoring Quality
 
 Quality expectations and structure for `/.claude/agents/{name}.md` files. This file adds CBP-specific constraints on top of the official Claude Code sub-agents spec.
@@ -10,13 +6,15 @@ Quality expectations and structure for `/.claude/agents/{name}.md` files. This f
 
 CBP uses the flat form `.claude/agents/{name}.md` — the default per the official Claude Code sub-agents spec. All 12 existing CBP agents use this layout. Folder form `.claude/agents/{name}/AGENT.md` is optional and only appropriate when the agent bundles supporting files (context, examples, scripts) next to the definition.
 
-## Required CBP Frontmatter
+## CBP Frontmatter — the `scope:` marker
+
+`scope:` is a CBP structural marker (not read by Claude Code itself). It is **required only on user-created agents** — ones the `codebyplan` package does NOT distribute. A package-managed agent (one that has a template twin under `templates/agents/`) is `org-shared` by default and needs **no** marker; an explicit `scope: org-shared` on it is redundant. See `rules/scope-vocabulary.md`.
 
-Every agent MUST have `scope:` in addition to the Claude Code native fields:
+For a user-created agent, add a marker alongside the Claude Code native fields:
 
 ```yaml
 ---
-scope: org-shared # structural marker: org-shared | project-shared | repo-only:<repo-name>
+scope: project-shared # or: repo-only:<repo-name> (user-created agents only)
 name: agent-name
 description: One sentence — used for matching. Be specific.
 tools: Read, Write, Edit, Glob, Grep, Bash
@@ -24,7 +22,7 @@ effort: high
 ---
 ```
 
-`scope:` is a CBP structural marker — not read by Claude Code itself. Missing `scope:` fails validation (`validate-agent.sh` / `validate-structure-scope.sh`).
+`validate-agent.sh` validates the value when present but does not require the key; `codebyplan claude verify-parity` is the central enforcer of the user-created requirement (and warns on a redundant `org-shared` marker on a managed agent).
 
 ## Agent Types
 

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

@@ -34,7 +34,16 @@ fm=$(awk '/^---[[:space:]]*$/{n++; next} n==1{print} n==2{exit}' "$FILE")
 # Required fields
 grep -qE '^name:[[:space:]]*' <<< "$fm" || err "missing required field: name"
 grep -qE '^description:[[:space:]]*' <<< "$fm" || err "missing required field: description"
-grep -qE '^scope:[[:space:]]*' <<< "$fm" || err "missing CBP required field: scope (org-shared|project-shared|repo-only:<repo-name>)"
+
+# CBP scope: OPTIONAL. Required only on user-created assets (no template twin) —
+# enforced centrally by `codebyplan claude verify-parity`. Package-managed agents
+# default to org-shared (markerless). Validate the VALUE only when present.
+if grep -qE '^scope:[[:space:]]*' <<< "$fm"; then
+  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
 
 # Name format: kebab-case
 name=$(grep -E '^name:' <<< "$fm" | head -1 | sed -E 's/^name:[[:space:]]*//; s/[[:space:]]*$//; s/^"(.*)"$/\1/' || true)

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

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-build-cc-claude-file
 description: Create or update a CLAUDE.md file at any scope (managed, project, user, local) following the official memory spec — imports (@path), nested discovery, AGENTS.md bridge, comment stripping, and claudeMdExcludes.
 argument-hint: "[action] [--scope=managed|project|user|local]"

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

@@ -1,5 +1,4 @@
 #!/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).

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

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-build-cc-mode
 description: Audit + apply the CHK-109 model/effort convention across every authoring skill and agent under `packages/codebyplan-package/templates/`. Skills set `effort:` only and inherit the session model; agents pin `model:` + `effort:`. Bare invocation audits and reports frontmatter gaps; with a path argument, edits the target file's frontmatter to the convention-decided values.
 argument-hint: "[path-to-agent-or-skill]"

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

@@ -1,7 +1,6 @@
 ---
-scope: org-shared
 name: cbp-build-cc-rule
-description: Build a path-scoped rule file at .claude/rules/{name}.md following the official memory/rules spec (paths globs, always-loaded vs on-demand, symlinks) plus CBP conventions (required scope field for structural classification (validate-structure-scope.sh), narrow-paths discipline; hook warns at 100 lines, blocks at 200).
+description: Build a path-scoped rule file at .claude/rules/{name}.md following the official memory/rules spec (paths globs, always-loaded vs on-demand, symlinks) plus CBP conventions (scope field for structural classification — required only on user-created rules (validate-structure-scope.sh), narrow-paths discipline; hook warns at 100 lines, blocks at 200).
 argument-hint: '[name] [--scope=project|user] [--paths="glob,glob"]'
 allowed-tools: Read, Write, Edit, Glob, Grep
 effort: xhigh
@@ -76,13 +75,24 @@ paths:
 
 Unscoped rules (no `paths:`) belong only on truly universal constraints: git attribution, company secrets policy, file-naming conventions.
 
-### Step 4 — Required CBP Frontmatter
+### Step 4 — CBP Frontmatter
 
-Every rule MUST have **both** fields:
+`scope:` is required **only for user-created rules** (no template twin); package-managed rules are `org-shared` by default — omit the marker. `paths:` is recommended for every rule.
+
+**User-created rule** (must declare scope):
+
+```yaml
+---
+scope: project-shared # or: repo-only:<repo-name>
+paths:
+  - "apps/*/src/app/api/**/*.ts"
+---
+```
+
+**Package-managed rule** (template twin exists → org-shared implicit, no marker):
 
 ```yaml
 ---
-scope: org-shared # or: project-shared | repo-only:<repo-name>
 paths:
   - "apps/*/src/app/api/**/*.ts"
 ---
@@ -90,7 +100,7 @@ paths:
 
 | Field    | Purpose                                                                                                                                                                 |
 | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `scope:` | CBP structural marker — required by validators (`validate-structure-scope.sh`). NOT read by Claude Code. Values: `org-shared` \| `project-shared` \| `repo-only:<name>` |
+| `scope:` | CBP structural marker — NOT read by Claude Code. Required only on **user-created** rules (no template twin); package-managed rules are `org-shared` by default and need no marker. Values: `org-shared` \| `project-shared` \| `repo-only:<name>`. See `rules/scope-vocabulary.md`. |
 | `paths:` | File globs that trigger rule loading (Claude Code native)                                                                                                               |
 
 When propagating rules between repos, copy only rules where `scope: org-shared` OR `scope: repo-only:<target>`.
@@ -161,7 +171,7 @@ Run the validator:
 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).
+It checks: YAML frontmatter present, the `scope:` value is a valid enum when present (the key itself is optional — required only on user-created rules, enforced centrally by `codebyplan claude verify-parity`), 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
 
@@ -180,7 +190,7 @@ Use the `InstructionsLoaded` hook if you need to debug exactly when and why a ru
 
 - Every rule needs an intent — if removing it wouldn't change Claude's behaviour, delete it
 - Prefer path-scoped over unconditional — context is a finite budget
-- Missing `scope:` fails validation (validate-structure-scope.sh warns; validate-agent.sh / validate-skill.sh block); missing `paths:` loads the rule on every file read
+- `scope:` is required only on user-created rules (no template twin); a managed rule is `org-shared` by default — enforced centrally by `codebyplan claude verify-parity` (missing marker = error for user-created files; redundant `org-shared` on a managed file = non-blocking warning); `validate-structure-scope.sh` also warns at edit time; missing `paths:` loads the rule on every file read
 - Rules are stored in the CBP database; the authoritative copy is in the DB — commit changes you want to keep
 - Conflicting rules load in both — Claude picks arbitrarily. Remove or merge duplicates
 - Rules that restate the Claude Code spec add no value — point to the official spec instead

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

@@ -1,5 +1,4 @@
 #!/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).
@@ -24,10 +23,10 @@ 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: OPTIONAL. Required only on user-created assets (no template twin) —
+# enforced centrally by `codebyplan claude verify-parity`. Package-managed rules
+# default to org-shared (markerless). Validate the VALUE only when present.
+if grep -qE '^scope:[[:space:]]*' <<< "$fm"; then
   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>)"

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

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-build-cc-settings
 description: Create or update Claude Code settings.json / settings.local.json / managed-settings.json following the official settings spec — scopes, permissions, hooks, sandbox, attribution, plugins, env vars, JSON schema validation.
 argument-hint: "[action] [--scope=user|project|local|managed]"

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

@@ -1,7 +1,3 @@
----
-scope: org-shared
----
-
 # Settings Authoring Conventions
 
 Read this before creating or updating `.claude/settings.json` or `.claude/settings.local.json`. This file adds CBP-specific constraints on top of the official Claude Code settings spec.

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

@@ -1,5 +1,4 @@
 #!/bin/bash
-# @scope: org-shared
 # Validate a Claude Code settings*.json file.
 # Usage: validate-settings.sh <path-to-settings-file>
 # Exit 0 = valid, exit 1 = invalid (errors printed to stderr).

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

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-build-cc-skill
 description: Build a Claude Code skill at .claude/skills/{name}/SKILL.md following the official skills spec — frontmatter, supporting files (templates, examples, reference, scripts), invocation control, argument substitution, dynamic context, fork-to-subagent, allowed-tools.
 argument-hint: "[skill-name] [--scope=project|user] [--fork] [--disable-model-invocation]"