codebyplan 1.13.45 → 1.13.48

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/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]"

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

@@ -1,24 +1,22 @@
----
-scope: org-shared
----
-
 # Skill Authoring Quality
 
 Quality expectations and structure for `/.claude/skills/{name}/SKILL.md` files. This file adds CBP-specific constraints on top of the official Claude Code skills spec.
 
-## 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 skills** — ones the `codebyplan` package does NOT distribute. A package-managed skill (one with a template twin under `templates/skills/`) is `org-shared` by default and needs **no** marker; an explicit `scope: org-shared` on it is redundant. See `rules/scope-vocabulary.md`.
 
-Every skill MUST have `scope:` in addition to the Claude Code native fields:
+For a user-created skill, 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 skills only)
 name: cbp-skill-name
 description: One sentence — shown in skill list and used for auto-matching
 ---
 ```
 
-`scope:` is a CBP structural marker — not read by Claude Code itself. Missing `scope:` fails validation (`validate-skill.sh` / `validate-structure-scope.sh`).
+`validate-skill.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 skill).
 
 ## What Skills Are
 

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

@@ -46,8 +46,16 @@ fi
 # Description recommended
 grep -qE '^description:\s*' <<< "$fm" || echo "  WARN: no description — Claude will use first paragraph" >&2
 
-# CBP scope required
-grep -qE '^scope:\s*' <<< "$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) —
+# that requirement is enforced centrally by `codebyplan claude verify-parity`.
+# Package-managed skills default to org-shared (markerless). Here we only validate
+# the VALUE when a marker is present.
+if grep -qE '^scope:\s*' <<< "$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
 
 # Model — skills MUST NOT pin a model. A skill's inline turn runs in the user's
 # active session, so it inherits the session model. Pinning one forces a model the

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

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-check
 description: Full re-evaluation of a checkpoint with before/after comparison
 argument-hint: [CHK-NNN]

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

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-complete
 description: Complete a checkpoint after all tasks are done
 argument-hint: [checkpoint-number]

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

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-create
 description: Mechanical checkpoint creation — capture the user's description, infer title + goal, dedup against existing modules, create the checkpoint row + feat branch, then hand off to /cbp-checkpoint-plan for deep planning. Creates ZERO tasks.
 argument-hint: [checkpoint description]
@@ -67,24 +66,24 @@ Ask the user via AskUserQuestion whether to claim this checkpoint now:
 - **Claim for me + this worktree** (default) — resolve `npx codebyplan resolve-worktree 2>/dev/null` and set it as the checkpoint `worktree_id` at create. The creator carries momentum straight through plan → start.
 - **Leave it open** — create with `worktree_id` null so anyone free can claim it later via `/cbp-checkpoint-start`.
 
-Record the choice; it drives both the create call (Step 8) and the plan→start routing in `/cbp-checkpoint-plan`.
+Record the choice; it drives both the create call (Step 7) and the plan→start routing in `/cbp-checkpoint-plan`.
 
-### Step 7: Determine Next Checkpoint Number
-
-Scan `.codebyplan/state/checkpoints/*.json` for the highest `number` field + 1. If state dir is absent, run `npx codebyplan sync` once. Break-glass fallback: MCP `get_checkpoints` when sync fails.
-
-### Step 8: Create Checkpoint Row
+### Step 7: Create Checkpoint Row
 
 `codebyplan checkpoint create` (CLI write-through: writes `.codebyplan/state/checkpoints/<id>.json` + REST). Pass flags:
-- `--repo-id` (from `.codebyplan/repo.json`), `--number`, `--title`, `--goal`, `--deadline`, `--status pending`
+- `--repo-id` (from `.codebyplan/repo.json`), `--title`, `--goal`, `--deadline`, `--status pending`
 - `--ideas` JSON `[{ description: <raw user text> }]`
 - `--worktree-id` the resolved worktree **only if the user chose "claim"**; omit when "leave open"
 
-Break-glass fallback: MCP `create_checkpoint` when the CLI is unavailable.
+Do **not** pass `--number` — the database auto-assigns the next per-repo checkpoint number via a `BEFORE INSERT` trigger (advisory-locked `MAX(number)+1` scoped to `repo_id`). The DB-assigned number comes back on the created row (and is written into `.codebyplan/state/checkpoints/<id>.json`); read it for the branch slug (Step 8) and the result display (Step 9).
+
+Break-glass fallback: MCP `create_checkpoint` (also omit `number`) when the CLI is unavailable.
 
 This is the first identity-stamping point — when claiming, passing `worktree_id` here engages the CHK-104 hard-lock from birth. No `context`, `research`, `plan`, or tasks are written here.
 
-### Step 9: Create + Switch to Feat Branch
+### Step 8: Create + Switch to Feat Branch
+
+`{NNN}` below is the DB-assigned checkpoint number read back from the Step 7 `codebyplan checkpoint create` response.
 
 Read `.codebyplan/git.json` `branch_config.production` (default `"main"`) as `BASE`. codebyplan repos are main-only — never create or branch from a `development`/integration branch.
 
@@ -107,7 +106,7 @@ Persist the branch via `codebyplan checkpoint update --id <checkpoint-id> --bran
 
 **Note — Supabase preview branch**: no Supabase branch is created here. Creation is lazy — it happens on the first DB change when `/cbp-supabase-migrate` runs on this feat branch, which provisions a Supabase branch named identically to the git branch. See `cbp-supabase-migrate` Step 2.3 for the creation protocol.
 
-### Step 10: Show Result + Auto-Trigger Plan
+### Step 9: Show Result + Auto-Trigger Plan
 
 ```
 ## Checkpoint Created

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

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-end
 description: Single point for all shipment — branch promotion to main via /cbp-ship-main, runtime deploy via /cbp-ship, branch cleanup, summary. Standalone tasks bypass shipment entirely.
 effort: xhigh

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

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-plan
 description: Deep inline planning for a checkpoint — assess, gap-analyse, decide dependencies, compare alternatives, optionally e2e-probe a suspected-broken area, then create tasks as vertical slices. Runs after /cbp-checkpoint-create (mechanical) and before /cbp-checkpoint-start (activate + claim). Does NOT activate or claim.
 argument-hint: [checkpoint-number]

package/templates/skills/cbp-checkpoint-plan/reference/alternative-comparison-template.md

@@ -1,7 +1,3 @@
----
-scope: org-shared
----
-
 # Alternative Comparison Template
 
 Loaded by `/cbp-checkpoint-plan` Step 6. Use when a meaningful design fork has more than one viable answer. Surfacing the alternatives — instead of silently picking one — is what lets the user redirect before tasks are created.

package/templates/skills/cbp-checkpoint-plan/reference/dep-decision-rubric.md

@@ -1,7 +1,3 @@
----
-scope: org-shared
----
-
 # Dependency Decision Rubric
 
 Loaded by `/cbp-checkpoint-plan` Step 5. Use when an idea could be built by extending something already installed OR by pulling in a new dependency. The goal is a deliberate, recorded choice — never a silent `pnpm add`.

package/templates/skills/cbp-checkpoint-plan/reference/e2e-discovery-probe.md

@@ -1,7 +1,3 @@
----
-scope: org-shared
----
-
 # E2E Discovery Probe
 
 Loaded by `/cbp-checkpoint-plan` Step 4. The probe answers one question before you plan a fix: **is this area actually broken, and how?** It reuses the config-matched `cbp-e2e-*` specialist (the framework owners of e2e execution) in `whole_checkpoint_mode` rather than introducing a second smoke-test path. See `context/testing/e2e.md` for the dispatch contract that selects which specialist to spawn.

package/templates/skills/cbp-checkpoint-plan/reference/gap-analysis-playbook.md

@@ -1,7 +1,3 @@
----
-scope: org-shared
----
-
 # Gap Analysis Playbook
 
 Loaded by `/cbp-checkpoint-plan` Step 3. The job: find what the raw request misses, before any task is created. Most "half-ass" outcomes come from planning only what was literally asked and ignoring the foundations it depends on or the adjacent breakage it sits next to.

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

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-start
 description: Activate a planned checkpoint and claim it for the current user/worktree, then route into task work. Runs after /cbp-checkpoint-plan (which produces tasks but never activates). Refuses to start an unplanned checkpoint.
 argument-hint: [checkpoint-number]

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

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-update
 description: Update checkpoint state (activate, update context, etc.)
 argument-hint: [checkpoint-number]