codebyplan 1.5.1 → 1.8.0

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

@@ -0,0 +1,104 @@
+#!/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.
+# Sourced by validate-structure.sh and its 4 sub-helpers — never run directly.
+#
+# Conventions:
+#   - All functions are stateless; callers pass state explicitly OR rely
+#     on the dispatcher's already-set environment ($REL_PATH, $FILE_PATH,
+#     $INPUT, $REPO_ROOT, $EXT) when documented per-function.
+#   - Functions emit to stderr only via block()/warn() — never echo to stdout.
+#   - The dispatcher (validate-structure.sh) sources this lib once before
+#     the 4 sub-helpers; sub-helpers rely on the lib being pre-loaded.
+#     Idempotent: re-sourcing is a no-op via _validate_structure_lib_loaded.
+
+[ -n "${_validate_structure_lib_loaded:-}" ] && return 0
+_validate_structure_lib_loaded=1
+
+# ===== block / warn =====
+
+# block <message> [expected_hint]
+# Emit a structure violation to stderr and exit 2.
+block() {
+  echo "[HOOK END] validate-structure (BLOCKED)"
+  echo "STRUCTURE VIOLATION: $1" >&2
+  echo "" >&2
+  if [ -n "${2:-}" ]; then
+    echo "Expected: $2" >&2
+  fi
+  echo "" >&2
+  echo "Structure is enforced from: /.claude/rules/structure-*.md" >&2
+  exit 2
+}
+
+# warn <message>
+# Emit a non-blocking structure warning to stderr.
+warn() {
+  echo "STRUCTURE WARNING: $1" >&2
+}
+
+# ===== path matching =====
+
+# match_path <pattern>
+# Returns 0 if $REL_PATH matches the extended-regex pattern.
+match_path() {
+  echo "$REL_PATH" | grep -qE "$1"
+}
+
+# enforce_path_pattern <scope_prefix> <full_pattern> <block_message> <expected_hint>
+# If $REL_PATH is in <scope_prefix>, it MUST also match <full_pattern>; else block.
+# Use to collapse the recurring "if-in-prefix-and-not-matching-full" idiom.
+enforce_path_pattern() {
+  local scope_prefix="$1" full_pattern="$2" block_msg="$3" expected="$4"
+  if match_path "$scope_prefix"; then
+    if ! match_path "$full_pattern"; then
+      block "$block_msg" "$expected"
+    fi
+  fi
+}
+
+# ===== input / content extraction =====
+
+# read_input_content
+# Echo the tool's pending content (Write content or Edit new_string),
+# pulling from $INPUT (the dispatcher's stdin JSON). Empty if neither present.
+read_input_content() {
+  echo "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // empty' 2>/dev/null
+}
+
+# count_lines <content_string> [fallback_filepath]
+# Count lines in <content_string>; if empty, fall back to wc -l on <fallback_filepath>.
+# Echo the count (0 if neither yields anything).
+count_lines() {
+  local content="$1" fallback="${2:-}"
+  if [ -n "$content" ]; then
+    printf '%s' "$content" | awk 'END { print NR }'
+  elif [ -n "$fallback" ] && [ -f "$fallback" ]; then
+    wc -l < "$fallback" | tr -d ' '
+  else
+    echo 0
+  fi
+}
+
+# ===== frontmatter / scope detection =====
+
+# has_yaml_frontmatter <file_path>
+# Returns 0 if the first line is `---` (YAML frontmatter opener). Missing file → 1.
+has_yaml_frontmatter() {
+  [ -f "$1" ] && head -1 "$1" 2>/dev/null | grep -q "^---$"
+}
+
+# has_yaml_field <file_path> <field_name> [head_lines=10]
+# Returns 0 if `<field>:` appears in the first <head_lines> of the file.
+has_yaml_field() {
+  local fp="$1" field="$2" n="${3:-10}"
+  [ -f "$fp" ] && head -"$n" "$fp" 2>/dev/null | grep -q "^${field}:"
+}
+
+# has_scope_comment <file_path>
+# Returns 0 if a `# @scope:` comment appears in the first 5 lines (sh hook convention).
+has_scope_comment() {
+  [ -f "$1" ] && head -5 "$1" 2>/dev/null | grep -q "^# @scope:"
+}

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

@@ -0,0 +1,54 @@
+#!/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
+#
+# Expects: $REL_PATH, $FILE_PATH, $INPUT, block(), warn(), match_path(),
+#          enforce_path_pattern(), read_input_content() (from validate-structure-lib.sh)
+
+# ===== Path-pattern enforcement =====
+# Each row: enforce_path_pattern <prefix> <full_pattern> <block_msg> <expected_hint>
+_SUB='(templates|examples|reference|scripts)/[a-z0-9.-]+\.(md|sh|json|ya?ml)'
+enforce_path_pattern '^/\.claude/skills/' "^/\.claude/skills/[a-z0-9-]+/(SKILL\.md|[a-z0-9-]+\.md|${_SUB})$" 'Invalid skill path' "Pattern: /.claude/skills/{name}/SKILL.md | /.claude/skills/{name}/{file}.md | /.claude/skills/{name}/(templates|examples|reference|scripts)/{file}.{md,sh,json,yaml}"
+enforce_path_pattern '^/\.claude/agents/' "^/\.claude/agents/([a-z0-9-]+\.md|[a-z0-9-]+/(AGENT\.md|[a-z0-9-]+\.md|${_SUB}))$" 'Invalid agent path' "Pattern: /.claude/agents/{name}.md | /.claude/agents/{name}/AGENT.md | /.claude/agents/{name}/{file}.md | /.claude/agents/{name}/(templates|examples|reference|scripts)/{file}.{md,sh,json,yaml}"
+enforce_path_pattern '^/\.claude/rules/' '^/\.claude/rules/[a-z-]+\.md$' 'Invalid native rule path' 'Pattern: /.claude/rules/{name}.md'
+if match_path '^/\.claude/hooks/' && ! match_path '^/\.claude/hooks/__test-fixtures__/'; then
+  if ! match_path '^/\.claude/hooks/[a-z-]+\.sh$'; then
+    block 'Invalid hook path' 'Pattern: /.claude/hooks/{name}.sh'
+  fi
+fi
+enforce_path_pattern '^/\.claude/context/' '^/\.claude/context/([a-z0-9-]+/)*[a-z0-9-]+\.(md|json)$' 'Invalid context path' 'Pattern: /.claude/context/{name}.(md|json) or /.claude/context/{subdir}/{name}.(md|json)'
+enforce_path_pattern '^/\.claude/docs/architecture/' '^/\.claude/docs/architecture/[a-z-]+\.md$' 'Invalid architecture path' 'Pattern: /.claude/docs/architecture/{name}.md'
+enforce_path_pattern '^/docs/structure/' '^/docs/structure/[a-z-]+\.(md|json)$' 'Invalid structure path' 'Pattern: /docs/structure/{name}.md or .json'
+
+# Research files: only enforce {1-8}-{name}.md if filename starts with a digit
+if match_path '^/\.claude/docs/research/[a-z-]+/'; then
+  RESEARCH_FILE=$(basename "$REL_PATH")
+  if echo "$RESEARCH_FILE" | grep -qE '^[0-9]' && ! echo "$RESEARCH_FILE" | grep -qE '^[1-8]-[a-z-]+\.md$'; then
+    block "Invalid research file" "Pattern: {1-8}-{name}.md (phases 1-8 only)"
+  fi
+fi
+
+# Stack: index/usage/guide/updates files OR the top-level update-checks.md
+if match_path '^/\.claude/docs/stack/' \
+   && ! match_path '^/\.claude/docs/stack/update-checks\.md$' \
+   && ! match_path '^/\.claude/docs/stack/[a-z-]+/(index|usage|guide|updates)\.md$'; then
+  block "Invalid stack path" "Pattern: /.claude/docs/stack/{name}/(index|usage|guide|updates).md or /.claude/docs/stack/update-checks.md"
+fi
+
+# Notation consistency (warn-only): flag bare-colon command notation in .claude/ markdown
+# See: /.claude/rules/notation-consistency.md — all command refs must use /cbp-* form
+if match_path '^/\.claude/(rules|skills|agents)/' && match_path '\.md$'; then
+  CONTENT=$(read_input_content)
+  [ -z "$CONTENT" ] && [ -f "$FILE_PATH" ] && CONTENT=$(cat "$FILE_PATH" 2>/dev/null || true)
+  if [ -n "$CONTENT" ]; then
+    COLON_HITS=$(echo "$CONTENT" | grep -nE '`(round|task|checkpoint|git|session|fix|ship|worktree|build-cc):[a-z-]+`' 2>/dev/null || true)
+    if [ -n "$COLON_HITS" ]; then
+      warn "Notation consistency: bare-colon command reference detected — use /cbp-* form instead"
+      warn "  File: ${REL_PATH}"
+      warn "  Matches:"
+      echo "$COLON_HITS" | sed 's/^/    /' >&2
+    fi
+  fi
+fi

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

@@ -0,0 +1,33 @@
+#!/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
+# 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)
+
+# Only check .claude/ files
+if ! match_path '^/\.claude/'; then
+  return 0 2>/dev/null || true
+fi
+
+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."
+      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."
+    fi
+    ;;
+  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."
+    fi
+    ;;
+  json)
+    # JSON can't have frontmatter — skip
+    ;;
+esac

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

@@ -0,0 +1,95 @@
+#!/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/
+# → expected exit code → optional expected stderr pattern.
+#
+# Run on demand:  bash .claude/hooks/validate-structure-smoke.sh
+# Exit 0 = all pass, Exit 1 = at least one fail.
+
+set +e  # tests intentionally produce non-zero exits — handle per-case
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+HOOK_DIR="$REPO_ROOT/.claude/hooks"
+FIX_DIR="$HOOK_DIR/__test-fixtures__/validate-structure"
+DISPATCHER="$HOOK_DIR/validate-structure.sh"
+
+PASS=0
+FAIL=0
+FAIL_LIST=""
+
+# Stage a scratch repo mirror so the dispatcher's REPO_ROOT computation
+# (relative to its own location) remains stable while we feed simulated paths.
+SCRATCH=$(mktemp -d)
+trap 'rm -rf "$SCRATCH"' EXIT
+mkdir -p "$SCRATCH/.claude/hooks"
+cp "$HOOK_DIR"/validate-structure*.sh "$SCRATCH/.claude/hooks/"
+# Sourced sibling — required by dispatcher even though it's outside this task's scope
+[ -f "$HOOK_DIR/validate-context-usage.sh" ] && cp "$HOOK_DIR/validate-context-usage.sh" "$SCRATCH/.claude/hooks/"
+SCRATCH_DISPATCHER="$SCRATCH/.claude/hooks/validate-structure.sh"
+
+run_case() {
+  local label="$1" fixture="$2" rel_path="$3" want_exit="$4" want_stderr="${5:-}"
+  local sim_abs="$SCRATCH$rel_path"
+  mkdir -p "$(dirname "$sim_abs")"
+  if [ -f "$FIX_DIR/$fixture" ]; then
+    cp "$FIX_DIR/$fixture" "$sim_abs"
+  fi
+  local json="{\"tool_input\":{\"file_path\":\"$sim_abs\"}}"
+  local stderr_file
+  stderr_file=$(mktemp)
+  echo "$json" | bash "$SCRATCH_DISPATCHER" >/dev/null 2>"$stderr_file"
+  local got_exit=$?
+  local ok=1
+  if [ "$got_exit" -ne "$want_exit" ]; then
+    ok=0
+  fi
+  if [ -n "$want_stderr" ] && ! grep -q -- "$want_stderr" "$stderr_file"; then
+    ok=0
+  fi
+  if [ "$ok" -eq 1 ]; then
+    echo "PASS  $label"
+    PASS=$((PASS+1))
+  else
+    echo "FAIL  $label  (got exit=$got_exit, want=$want_exit)"
+    head -5 "$stderr_file" | sed 's/^/      /'
+    FAIL=$((FAIL+1))
+    FAIL_LIST="$FAIL_LIST $label"
+  fi
+  rm -f "$stderr_file"
+}
+
+# ===== Good fixtures (must exit 0) =====
+run_case "good-skill"   good/skill.md /.claude/skills/cbp-fixture/SKILL.md 0
+run_case "good-agent"   good/agent.md /.claude/agents/cbp-fixture/AGENT.md 0
+run_case "good-rule"    good/rule.md  /.claude/rules/cbp-fixture.md 0
+run_case "good-hook"    good/hook.sh  /.claude/hooks/cbp-fixture.sh 0
+
+# ===== Bad fixtures: structural blocks (exit 2) =====
+run_case "bad-uppercase-skill-dir"   ""  /.claude/skills/Bad_Name/SKILL.md  2 "Invalid skill path"
+run_case "bad-uppercase-hook"        ""  /.claude/hooks/UPPER.sh             2 "Filename must be kebab-case"
+run_case "bad-uppercase-context"     ""  /.claude/context/UPPER.md           2 "Filename must be kebab-case"
+run_case "bad-research-bad-phase"    ""  /.claude/docs/research/foo/9-bad.md 2 "Invalid research file"
+run_case "bad-over-length-rule"      bad/over-length-rule.md /.claude/rules/cbp-fixture-overlength.md 2 "exceeds hard limit"
+
+# ===== Warn-only fixtures (exit 0 but stderr has WARNING) =====
+run_case "warn-missing-frontmatter"  bad/missing-frontmatter.md  /.claude/rules/cbp-fixture-no-frontmatter.md 0 "Missing frontmatter"
+run_case "warn-missing-scope-field"  bad/missing-scope-field.md  /.claude/rules/cbp-fixture-no-scope-field.md 0 "Missing scope:"
+run_case "warn-missing-scope-comment" bad/missing-scope-comment.sh /.claude/hooks/cbp-fixture-no-scope-comment.sh 0 "Missing # @scope:"
+
+# ===== Fixture-path exemption (R2 fix for self-blocking bug) =====
+# A Write to a path under .claude/hooks/__test-fixtures__/ must NOT be blocked
+# by the hooks-pattern enforcement, even though the prefix matches /.claude/hooks/.
+run_case "fixture-path-exempted"          ""  /.claude/hooks/__test-fixtures__/validate-structure/good/new-fixture.md  0
+# Regression: the exemption must NOT inadvertently allow uppercase hook names
+# OUTSIDE the __test-fixtures__/ subtree.
+run_case "non-fixture-bad-hook-still-blocks"  ""  /.claude/hooks/Some_Bad.sh  2  "Filename must be kebab-case"
+
+echo
+echo "Total: $PASS passed, $FAIL failed"
+if [ "$FAIL" -gt 0 ]; then
+  echo "Failed:$FAIL_LIST"
+  exit 1
+fi
+exit 0

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

@@ -0,0 +1,34 @@
+#!/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
+#
+# Expects: $REL_PATH, $REPO_ROOT (no shared lib helpers needed — pure mapping table)
+
+TEMPLATE=""
+
+# Map file location to template or context file
+case "$REL_PATH" in
+  /.claude/skills/*)              TEMPLATE="/packages/codebyplan-package/templates/skills/build-cc-skill/reference/cbp-quality.md" ;;
+  /.claude/agents/*/AGENT.md)     TEMPLATE="/packages/codebyplan-package/templates/skills/build-cc-agent/reference/cbp-quality.md" ;;
+  /.claude/docs/research/*/1-*)   TEMPLATE="/docs/templates/.claude/docs/research/1-problem.md" ;;
+  /.claude/docs/research/*/2-*)   TEMPLATE="/docs/templates/.claude/docs/research/2-claude-default.md" ;;
+  /.claude/docs/research/*/3-*)   TEMPLATE="/docs/templates/.claude/docs/research/3-official-docs.md" ;;
+  /.claude/docs/research/*/4-*)   TEMPLATE="/docs/templates/.claude/docs/research/4-solutions.md" ;;
+  /.claude/docs/research/*/5-*)   TEMPLATE="/docs/templates/.claude/docs/research/5-codebase-analysis.md" ;;
+  /.claude/docs/research/*/6-*)   TEMPLATE="/docs/templates/.claude/docs/research/6-web-research.md" ;;
+  /.claude/docs/research/*/7-*)   TEMPLATE="/docs/templates/.claude/docs/research/7-implementation.md" ;;
+  /.claude/docs/research/*/8-*)   TEMPLATE="/docs/templates/.claude/docs/research/8-chosen.md" ;;
+  /.claude/docs/stack/*/index.md) TEMPLATE="/docs/templates/.claude/docs/stack/index.md" ;;
+  /.claude/docs/stack/*/usage.md) TEMPLATE="/docs/templates/.claude/docs/stack/usage.md" ;;
+  /.claude/docs/stack/*/guide.md) TEMPLATE="/docs/templates/.claude/docs/stack/guide.md" ;;
+  /.claude/docs/stack/*/updates.md) TEMPLATE="/docs/templates/.claude/docs/stack/updates.md" ;;
+esac
+
+# Output template suggestion if applicable
+if [ -n "$TEMPLATE" ] && [ -f "$REPO_ROOT$TEMPLATE" ]; then
+  echo ""
+  echo "REFERENCE: $TEMPLATE"
+  echo "Read this file for quality expectations and required sections."
+fi

package/templates/hooks/validate-structure.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# @scope: org-shared
+# @hook: PreToolUse Edit|Write
+# Hook: PreToolUse for Edit|Write
+# Purpose: Validate file paths against structure patterns
+# Structure rules: /.claude/rules/structure-*.md (auto-loaded by Claude)
+# This hook mirrors those rules for automated enforcement
+#
+# Exit 0 = allow, Exit 2 = block (stderr sent to Claude)
+
+set -e
+
+echo "[HOOK START] validate-structure"
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+HOOK_DIR="$(dirname "$0")"
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# Source shared helpers (defines block, warn, match_path, read_input_content, etc.)
+source "$HOOK_DIR/validate-structure-lib.sh"
+
+# Extract file path
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  echo "[HOOK END] validate-structure (no file path)"
+  exit 0
+fi
+
+# Get relative path from repo root
+REL_PATH="${FILE_PATH#$REPO_ROOT}"
+
+# Get file extension
+EXT="${FILE_PATH##*.}"
+
+# Skip non-markdown/non-script files (source code, etc.)
+case "$EXT" in
+  md|sh|json) ;;
+  *)
+    echo "[HOOK END] validate-structure (allowed: source code)"
+    exit 0
+    ;;
+esac
+
+# ===== VALIDATE NAMING CONVENTION =====
+FILENAME=$(basename "$FILE_PATH" ".$EXT")
+
+if match_path '^/(\.claude|docs)/'; then
+  # Skip special naming patterns (SKILL/AGENT/CLAUDE/MEMORY/TASK-N/CHK-NNN/date/week-N/research phase/README)
+  # CHK formats: CHK-001 (generic) or CHK-H001/CHK-A001/CHK-B001 (launch: Homepage/Application/Backdoor)
+  if ! echo "$FILENAME" | grep -qE '^(SKILL|AGENT|CLAUDE|MEMORY|TASK-[1-9]|[0-9]{2}-[0-9]{2}-[0-9]{2}-CHK-([0-9]{3}|[HAB][0-9]{3})|CHK-([0-9]{3}|[HAB][0-9]{3})|[0-9]{2}-[0-9]{2}-[0-9]{2}|week-[0-9]+|[1-8]-|README)'; then
+    if echo "$FILENAME" | grep -qE '[A-Z]|_'; then
+      block "Filename must be kebab-case (lowercase with hyphens)" "Got: $FILENAME, Expected: $(echo "$FILENAME" | tr '[:upper:]' '[:lower:]' | tr '_' '-')"
+    fi
+  fi
+fi
+
+# ===== VALIDATE PATTERNS AND TEMPLATES =====
+source "$HOOK_DIR/validate-structure-patterns.sh"
+source "$HOOK_DIR/validate-structure-templates.sh"
+source "$HOOK_DIR/validate-structure-scope.sh"
+source "$HOOK_DIR/validate-structure-lengths.sh"
+source "$HOOK_DIR/validate-context-usage.sh"
+
+# ===== ALL VALIDATIONS PASSED =====
+echo "[HOOK END] validate-structure (passed)"
+exit 0

package/templates/rules/README.md

@@ -0,0 +1,47 @@
+# Rules
+
+The `rules/` directory is a first-class shippable template category — parallel to `skills/`, `agents/`, and `hooks/` — for load-bearing behavioral constraints that the `@codebyplan/claude` CLI installs into a consuming project's `./.claude/rules/` directory.
+
+## Bar for shipping a rule
+
+A rule earns a place here only when it meets all three criteria:
+
+1. **Load-bearing**: removing it would degrade Claude's behavior in a demonstrable way.
+2. **High-signal**: the constraint fires on real patterns, not edge cases. Evidence of repeated application is required.
+3. **Narrow scope**: the rule says one thing clearly. Omnibus or catch-all rules are rejected.
+
+This is a curated set, not a dumping ground.
+
+## File format
+
+Flat `<name>.md` files at the top level of `templates/rules/`. Each file uses standard Claude rule frontmatter (YAML block at the top) followed by a markdown body:
+
+```
+---
+scope: org-shared  # CBP sync: org-shared | project-shared | repo-only:<repo-name>
+paths:
+  # Narrow to the smallest directory that covers the rule's intent.
+  # Avoid "**/*.ts" — loads on every TS edit across the repo.
+  - "apps/*/src/app/api/**/*.ts"
+---
+
+Rule body here.
+```
+
+See `.claude/skills/build-cc-rule/templates/rule.md` for the authoritative template.
+
+The `install`/`update`/`uninstall` flow handles these files identically to how it handles other template categories. No additional wiring is needed.
+
+## Current status
+
+Zero rules are shipped today. The wiring is in place so future PRs can land curated rules through the same install/update/uninstall flow as other templates.
+
+## Contributing a rule
+
+Each new rule needs its own justification in the PR description:
+
+- Why it is load-bearing (what breaks without it)
+- Evidence of high-signal application (where it has prevented problems)
+- Scope statement (what the rule enforces and what it deliberately does not)
+
+Rules that cannot answer all three are deferred until the evidence is there.

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

@@ -0,0 +1,52 @@
+---
+scope: org-shared
+paths:
+  - ".claude/context/**/*"
+  - ".claude/agents/**/*"
+---
+
+# Context File Loading
+
+`.claude/context/**` holds on-demand agent/skill input data — checklists, playbooks, framework recipes. This rule defines who loads what, when, and how missing files are handled.
+
+## Canonical Mapping
+
+| Context File | Loaded By | Phase | Purpose |
+|--------------|-----------|-------|---------|
+| `context/testing/unit.md` | `cbp-round-executor` | Step 3.6 | Unit test patterns per framework |
+| `context/testing/e2e.md` | `cbp-test-e2e-agent` | Entry | E2E framework setup + spec patterns |
+| `context/testing/e2e.md` | `cbp-testing-qa-agent` | Preflight | Env var list per framework |
+| `context/testing/eslint.md` | `cbp-task-planner` | Phase 1.5 | ESLint Compliance Checklist |
+| `context/testing/eslint.md` | `cbp-improve-round` | Phase 1.5 | Config-file compliance audit |
+| `context/mcp-docs.md` | `cbp-task-planner` | Phase 2.6 | MCP library doc lookup contract — per-dependency consultation via DocsByPlan MCP tools (resolve_library_id → search_chunks/lookup_symbol → get_chunk) |
+| `context/mcp-docs.md` | `cbp-round-executor` | Step 3.4 | Library-specific reference — pre-write API verification via DocsByPlan MCP tools |
+
+New context files MUST be added here in the same change that introduces the consumer — or the file is orphan infrastructure.
+
+## Load Contract
+
+- **Read with the Read tool** — never paraphrase from memory
+- **Fail loudly on missing file** — return `status: failed`, `reason: "required context file {path} not found"`; no fallback heuristic
+- **Log the load** — agent output includes `context_loaded: [{path, sha_first_line}]` for auditability
+
+## Why Fail Loudly
+
+Silent fallback hides drift. A rename or deletion of `context/testing/unit.md` would let `cbp-round-executor` keep writing tests from memory, drifting from the canonical recipe. A failed agent surfaces the drift on the first invocation; silent fallback lets it compound.
+
+## Path Convention
+
+- `context/{topic}/` subdirectories (kebab-case)
+- `context/{topic}/{name}.{md,json}` (kebab-case)
+- No frontmatter required — these are inputs, not managed files
+- Path layout enforced by `validate-structure-patterns.sh`
+
+## Update Discipline
+
+When editing a context file, check every consumer in the Canonical Mapping:
+
+- Edit changes a section name or checklist item the consumer cites → update the consumer's phase description
+- Edit is additive (new section) → no consumer update needed; agent re-reads on each invocation
+
+## Orphans
+
+A file under `context/**` with no consumer in the Canonical Mapping is infrastructure debt. `cbp-improve-claude` MUST flag orphans as high-priority cleanup proposals.

package/templates/rules/scope-vocabulary.md

@@ -0,0 +1,64 @@
+---
+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).
+
+## Enum values
+
+- **`org-shared`** — Shared across organisations. CBP-framework infrastructure that lands identically in every consuming repo (e.g. the `cbp-build-cc-*` authoring skills, the validate-\* hooks, this rule). Updates propagate via the `codebyplan` package's `claude` subcommand group (`npx codebyplan claude install|update|uninstall`).
+- **`project-shared`** — Shared within a single project family — multiple repos that live under one project umbrella. Use for skills/agents/rules that are reused across the project's apps + packages but not appropriate for cross-org distribution.
+- **`repo-only:<repo-name>`** — Bound to a single repo. The `<repo-name>` suffix is the repo's slug (lowercase, dash-separated). Use for repo-specific automations that have no meaning outside that codebase.
+
+## Examples
+
+### YAML frontmatter form
+
+Used by `.md` files (rules, skills, agents, CLAUDE.md). Place the marker in the top-of-file YAML block:
+
+```yaml
+---
+scope: org-shared
+---
+```
+
+```yaml
+---
+scope: project-shared
+---
+```
+
+```yaml
+---
+scope: repo-only:codebyplan-mcp
+---
+```
+
+### Shebang-comment form
+
+Used by `.sh` hook scripts and `.sh` tooling under `.claude/`. Place the marker on a comment line near the top of the file (after the shebang):
+
+```sh
+#!/usr/bin/env bash
+# @scope: org-shared
+```
+
+```sh
+#!/usr/bin/env bash
+# @scope: project-shared
+```
+
+```sh
+#!/usr/bin/env bash
+# @scope: repo-only:codebyplan-mcp
+```
+
+## Enforcement
+
+Three 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/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.