prizmkit 1.0.14 → 1.0.16

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.14",
-  "bundledAt": "2026-03-15T11:21:10.029Z",
-  "bundledFrom": "94ac498"
+  "frameworkVersion": "1.0.16",
+  "bundledAt": "2026-03-15T13:35:03.135Z",
+  "bundledFrom": "d609245"
 }

package/bundled/dev-pipeline/retry-bug.sh

@@ -24,9 +24,27 @@ SCRIPTS_DIR="$SCRIPT_DIR/scripts"
 SESSION_TIMEOUT=${SESSION_TIMEOUT:-0}
 HEARTBEAT_INTERVAL=${HEARTBEAT_INTERVAL:-30}
 
-# AI CLI detection
+# AI CLI detection: AI_CLI env > .prizmkit/config.json > CODEBUDDY_CLI > auto-detect
 if [[ -n "${AI_CLI:-}" ]]; then
     CLI_CMD="$AI_CLI"
+elif [[ -f ".prizmkit/config.json" ]]; then
+    _config_cli=$(python3 -c "
+import json, sys
+try:
+    with open('.prizmkit/config.json') as f:
+        d = json.load(f)
+    v = d.get('ai_cli', '')
+    if v: print(v)
+except: pass
+" 2>/dev/null || true)
+    CLI_CMD="${_config_cli:-}"
+    if [[ -z "$CLI_CMD" ]]; then
+        if [[ -n "${CODEBUDDY_CLI:-}" ]]; then CLI_CMD="$CODEBUDDY_CLI"
+        elif command -v cbc &>/dev/null; then CLI_CMD="cbc"
+        elif command -v claude &>/dev/null; then CLI_CMD="claude"
+        else echo "ERROR: No AI CLI found. Set AI_CLI or configure .prizmkit/config.json" >&2; exit 1
+        fi
+    fi
 elif [[ -n "${CODEBUDDY_CLI:-}" ]]; then
     CLI_CMD="$CODEBUDDY_CLI"
 elif command -v cbc &>/dev/null; then
@@ -34,7 +52,7 @@ elif command -v cbc &>/dev/null; then
 elif command -v claude &>/dev/null; then
     CLI_CMD="claude"
 else
-    echo "ERROR: No AI CLI found. Install CodeBuddy (cbc) or Claude Code (claude)." >&2
+    echo "ERROR: No AI CLI found. Install CodeBuddy (cbc) or Claude Code (claude), or set AI_CLI." >&2
     exit 1
 fi
 

package/bundled/dev-pipeline/retry-feature.sh

@@ -24,9 +24,27 @@ SCRIPTS_DIR="$SCRIPT_DIR/scripts"
 SESSION_TIMEOUT=${SESSION_TIMEOUT:-0}
 HEARTBEAT_INTERVAL=${HEARTBEAT_INTERVAL:-30}
 
-# AI CLI detection: AI_CLI > CODEBUDDY_CLI > auto-detect
+# AI CLI detection: AI_CLI env > .prizmkit/config.json > CODEBUDDY_CLI > auto-detect
 if [[ -n "${AI_CLI:-}" ]]; then
     CLI_CMD="$AI_CLI"
+elif [[ -f ".prizmkit/config.json" ]]; then
+    _config_cli=$(python3 -c "
+import json, sys
+try:
+    with open('.prizmkit/config.json') as f:
+        d = json.load(f)
+    v = d.get('ai_cli', '')
+    if v: print(v)
+except: pass
+" 2>/dev/null || true)
+    CLI_CMD="${_config_cli:-}"
+    if [[ -z "$CLI_CMD" ]]; then
+        if [[ -n "${CODEBUDDY_CLI:-}" ]]; then CLI_CMD="$CODEBUDDY_CLI"
+        elif command -v cbc &>/dev/null; then CLI_CMD="cbc"
+        elif command -v claude &>/dev/null; then CLI_CMD="claude"
+        else echo "ERROR: No AI CLI found. Set AI_CLI or configure .prizmkit/config.json" >&2; exit 1
+        fi
+    fi
 elif [[ -n "${CODEBUDDY_CLI:-}" ]]; then
     CLI_CMD="$CODEBUDDY_CLI"
 elif command -v cbc &>/dev/null; then
@@ -34,7 +52,7 @@ elif command -v cbc &>/dev/null; then
 elif command -v claude &>/dev/null; then
     CLI_CMD="claude"
 else
-    echo "ERROR: No AI CLI found. Install CodeBuddy (cbc) or Claude Code (claude)." >&2
+    echo "ERROR: No AI CLI found. Install CodeBuddy (cbc) or Claude Code (claude), or set AI_CLI." >&2
     exit 1
 fi
 

package/bundled/rules/prizm/prizm-documentation.md

@@ -1,5 +1,5 @@
 ---
-description: "PrizmKit documentation rules"
+description: "PrizmKit .prizm-docs maintenance rules — when/how to update structured AI documentation"
 globs:
   - "**/*.ts"
   - "**/*.tsx"
@@ -11,9 +11,70 @@ globs:
   - "**/*.java"
 ---
 
-When modifying source files in this project:
-1. Check if `.prizm-docs/root.prizm` exists
-2. If it does, read it before making changes to understand project structure
-3. After making changes, update affected `.prizm-docs/` files
-4. Follow the Prizm doc format (KEY: value, not prose)
-5. Size limits: L0 = 4KB, L1 = 3KB, L2 = 5KB
+WHEN TO UPDATE .prizm-docs/:
+- Feature development (new interface, new module, new behavior) → UPDATE .prizm-docs/
+- Bug fix (fixing broken logic, no structural change) → SKIP, do NOT update
+- Rationale: bugs are incomplete features. Recording bug details causes doc bloat with no AI value.
+- Before modifying any source file, read `.prizm-docs/root.prizm` if it exists to understand project structure.
+
+FORMAT RULES (enforced by pre-commit hook — violations block commit):
+- ALL CAPS section headers: MODULE:, FILES:, RESPONSIBILITY:, UPDATED:, etc.
+- KEY: value pairs and dash-prefixed lists only
+- PROHIBITED: prose paragraphs, markdown headers (##/###), code blocks (```), emoji, ASCII art
+- This format is designed for AI token efficiency, not human readability. Do not add human-friendly formatting.
+
+SIZE LIMITS (hard — pre-commit hook blocks commits exceeding these):
+- L0 root.prizm: 4KB max
+- L1 module.prizm: 3KB max
+- L2 detail.prizm: 5KB max
+
+SIZE OVERFLOW HANDLING:
+- L0 approaching 4KB: consolidate MODULE_INDEX, keep only top-5 RULES, remove PATTERNS detail
+- L1 approaching 3KB: move implementation details to L2, keep only INTERFACES signatures
+- L2 approaching 5KB: archive CHANGELOG entries older than 90 days to changelog-archive.prizm
+- NEVER exceed hard limits — pre-commit hook will block the commit
+
+REQUIRED FIELDS PER LEVEL:
+
+L0 root.prizm:
+- PRIZM_VERSION
+- PROJECT
+- LANG
+- MODULE_INDEX (with -> pointers to L1 files)
+- RULES (top-level project rules)
+- UPDATED
+
+L1 module.prizm:
+- MODULE
+- FILES
+- RESPONSIBILITY
+- INTERFACES (public/exported only)
+- DEPENDENCIES
+- UPDATED
+
+L2 detail.prizm:
+- MODULE
+- FILES
+- KEY_FILES
+- DEPENDENCIES
+- TRAPS
+- CHANGELOG
+- UPDATED
+
+L2 GENERATION TEMPLATE (use when AI first touches a sub-module with no L2 doc):
+
+MODULE: <path>
+FILES: <comma-separated file list>
+RESPONSIBILITY: <one-line>
+KEY_FILES:
+- <file>: <role, line count, complexity note>
+DEPENDENCIES:
+- uses: <lib>: <why>
+- imports: <module>: <what>
+TRAPS:
+- <gotcha, race condition, or non-obvious coupling>
+CHANGELOG:
+- <YYYY-MM-DD> | add: initial L2 documentation
+UPDATED: <YYYY-MM-DD>
+
+TRAPS is critical — always record gotchas, race conditions, non-obvious behavior, and surprising coupling between modules.

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.14",
+  "version": "1.0.16",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",
@@ -293,22 +293,45 @@
     "frontend": {
       "label": "前端项目 (React/Vue/Angular)",
       "base": "core",
-      "include": ["prizmkit-tool-perf-profiler", "prizmkit-tool-security-audit", "prizmkit-tool-ci-cd-generator"]
+      "include": [
+        "prizmkit-tool-perf-profiler",
+        "prizmkit-tool-security-audit",
+        "prizmkit-tool-ci-cd-generator"
+      ]
     },
     "backend": {
       "label": "后端服务 (API/微服务)",
       "base": "core",
-      "include": ["prizmkit-tool-db-migration", "prizmkit-tool-api-doc-generator", "prizmkit-tool-monitoring-setup", "prizmkit-tool-deployment-strategy", "prizmkit-tool-security-audit", "prizmkit-tool-error-triage", "prizmkit-tool-log-analyzer"]
+      "include": [
+        "prizmkit-tool-db-migration",
+        "prizmkit-tool-api-doc-generator",
+        "prizmkit-tool-monitoring-setup",
+        "prizmkit-tool-deployment-strategy",
+        "prizmkit-tool-security-audit",
+        "prizmkit-tool-error-triage",
+        "prizmkit-tool-log-analyzer"
+      ]
     },
     "fullstack": {
       "label": "全栈项目",
       "base": "core",
-      "include": ["prizmkit-tool-db-migration", "prizmkit-tool-api-doc-generator", "prizmkit-tool-ci-cd-generator", "prizmkit-tool-security-audit", "prizmkit-tool-deployment-strategy", "prizmkit-tool-perf-profiler"]
+      "include": [
+        "prizmkit-tool-db-migration",
+        "prizmkit-tool-api-doc-generator",
+        "prizmkit-tool-ci-cd-generator",
+        "prizmkit-tool-security-audit",
+        "prizmkit-tool-deployment-strategy",
+        "prizmkit-tool-perf-profiler"
+      ]
     },
     "library": {
       "label": "工具库/SDK",
       "base": "core",
-      "include": ["prizmkit-tool-api-doc-generator", "prizmkit-tool-ci-cd-generator", "prizmkit-tool-dependency-health"]
+      "include": [
+        "prizmkit-tool-api-doc-generator",
+        "prizmkit-tool-ci-cd-generator",
+        "prizmkit-tool-dependency-health"
+      ]
     }
   },
   "external_skills": {
@@ -325,21 +348,30 @@
         "description": "Intelligent file and code search skill",
         "source": "https://skills.sh/skills/find-skill/SKILL.md",
         "registry": "skills.sh",
-        "tags": ["search", "utility"]
+        "tags": [
+          "search",
+          "utility"
+        ]
       },
       {
         "name": "uiuxpromax",
         "description": "UI/UX design review and suggestions",
         "source": "https://skills.sh/skills/uiuxpromax/SKILL.md",
         "registry": "skills.sh",
-        "tags": ["design", "frontend"]
+        "tags": [
+          "design",
+          "frontend"
+        ]
       },
       {
         "name": "thinkthought",
         "description": "Structured reasoning and problem decomposition",
         "source": "https://skills.sh/skills/thinkthought/SKILL.md",
         "registry": "skills.sh",
-        "tags": ["reasoning", "universal"]
+        "tags": [
+          "reasoning",
+          "universal"
+        ]
       }
     ]
   }

package/bundled/skills/prizmkit-init/SKILL.md

@@ -39,44 +39,32 @@ BROWNFIELD WORKFLOW (existing project):
 4. Catalog dependencies (external packages)
 5. Count source files per directory
 
-**Step 2: State Assessment**
-2a. Run dependency analysis:
-  - Count outdated dependencies (if lockfile exists)
-  - Note any known vulnerability patterns
-
-2b. Scan for technical debt indicators:
-  - Count TODO/FIXME/HACK/XXX comments
-  - Identify large files (>500 lines)
-  - Check for test directories and coverage config
-
-2c. Generate `ASSESSMENT.md` in project root with findings
-
-**Step 3: Prizm Documentation Generation**
-3a. Invoke prizmkit-prizm-docs `prizmkit.doc.init` algorithm:
+**Step 2: Prizm Documentation Generation**
+2a. Invoke prizmkit-prizm-docs `prizmkit.doc.init` algorithm:
   - Create `.prizm-docs/` directory structure
   - Generate `root.prizm` (L0) with project meta and module index
   - Generate L1 docs for all discovered modules
   - Create `changelog.prizm`
   - Skip L2 (lazy generation)
 
-3b. If project has existing `docs/AI_CONTEXT/`: suggest running `prizmkit.doc.migrate`
+2b. If project has existing `docs/AI_CONTEXT/`: suggest running `prizmkit.doc.migrate`
 
-**Step 4: PrizmKit Workspace Initialization**
-4a. Create `.prizmkit/` directory:
+**Step 3: PrizmKit Workspace Initialization**
+3a. Create `.prizmkit/` directory:
   - `.prizmkit/config.json` (adoption_mode, speckit_hooks_enabled, platform)
   - `.prizmkit/specs/` (empty)
 
-**Step 5: Hook & Settings Configuration (Platform-Specific)**
+**Step 4: Hook & Settings Configuration (Platform-Specific)**
 
 **If platform is CodeBuddy (or both):**
-5a-cb. Read or create `.codebuddy/settings.json`
-5b-cb. Add UserPromptSubmit hook from `${SKILL_DIR}/../../../assets/hooks/prizm-commit-hook.json`
-5c-cb. Preserve any existing hooks
+4a-cb. Read or create `.codebuddy/settings.json`
+4b-cb. Add UserPromptSubmit hook from `${SKILL_DIR}/../../../assets/hooks/prizm-commit-hook.json`
+4c-cb. Preserve any existing hooks
 
 **If platform is Claude Code (or both):**
-5a-cl. Read or create `.claude/settings.json`
-5b-cl. Add `permissions` and `allowedTools` entries if needed
-5c-cl. Create `.claude/rules/prizm-documentation.md` with glob-scoped rules:
+4a-cl. Read or create `.claude/settings.json`
+4b-cl. Add `permissions` and `allowedTools` entries if needed
+4c-cl. Create `.claude/rules/prizm-documentation.md` with glob-scoped rules:
   ```yaml
   ---
   description: PrizmKit documentation rules
@@ -91,7 +79,7 @@ BROWNFIELD WORKFLOW (existing project):
   2. After changes, update affected `.prizm-docs/` files
   3. Follow Prizm doc format (KEY: value, not prose)
   ```
-5d-cl. Create `.claude/rules/prizm-commit-workflow.md` with commit-scoped rules:
+4d-cl. Create `.claude/rules/prizm-commit-workflow.md` with commit-scoped rules:
   ```yaml
   ---
   description: PrizmKit commit workflow enforcement
@@ -105,33 +93,33 @@ BROWNFIELD WORKFLOW (existing project):
   4. Stage .prizm-docs/ changes
   5. Use /prizmkit-committer for the complete workflow
   ```
-5e-cl. Preserve any existing Claude settings and rules
+4e-cl. Preserve any existing Claude settings and rules
 
-**Step 6: Project Memory Update (Platform-Specific)**
+**Step 5: Project Memory Update (Platform-Specific)**
 
 **If platform is CodeBuddy (or both):**
-6a-cb. Read existing `CODEBUDDY.md` (or create if missing)
-6b-cb. Append PrizmKit section from `${SKILL_DIR}/../../../assets/codebuddy-md-template.md`
-6c-cb. Do not duplicate if already present
+5a-cb. Read existing `CODEBUDDY.md` (or create if missing)
+5b-cb. Append PrizmKit section from `${SKILL_DIR}/../../../assets/codebuddy-md-template.md`
+5c-cb. Do not duplicate if already present
 
 **If platform is Claude Code (or both):**
-6a-cl. Read existing `CLAUDE.md` (or create if missing)
-6b-cl. Append PrizmKit section from `${SKILL_DIR}/../../../assets/claude-md-template.md`
-6c-cl. Adjust command references to use `/command-name` format (not `prizmkit.xxx`)
-6d-cl. Do not duplicate if already present
+5a-cl. Read existing `CLAUDE.md` (or create if missing)
+5b-cl. Append PrizmKit section from `${SKILL_DIR}/../../../assets/claude-md-template.md`
+5c-cl. Adjust command references to use `/command-name` format (not `prizmkit.xxx`)
+5d-cl. Do not duplicate if already present
 
-**Step 7: Report**
-Output summary: platform detected, tech stack detected, modules discovered, L1 docs generated, assessment highlights, platform-specific configuration applied, next recommended steps.
+**Step 6: Report**
+Output summary: platform detected, tech stack detected, modules discovered, L1 docs generated, platform-specific configuration applied, next recommended steps.
 
 Include platform-specific guidance:
 - CodeBuddy: "Use `prizmkit.specify` to start your first feature"
 - Claude Code: "Use `/prizmkit-specify` to start your first feature"
 
 GREENFIELD WORKFLOW (new project):
-- Skip Steps 1-2 (no code to scan)
-- Step 3: Create minimal `.prizm-docs/` with just `root.prizm` skeleton
-- Steps 4-6: Same as brownfield
-- Step 7: Recommend starting with specify for first feature (platform-appropriate command format)
+- Skip Step 1 (no code to scan)
+- Step 2: Create minimal `.prizm-docs/` with just `root.prizm` skeleton
+- Steps 3-5: Same as brownfield
+- Step 6: Recommend starting with specify for first feature (platform-appropriate command format)
 
 ### Gradual Adoption Path
 After init, PrizmKit operates in phases:

package/bundled/templates/hooks/commit-intent-claude.json

@@ -6,7 +6,18 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo 'PRIZMKIT_DOC_UPDATE_REQUIRED: Before committing, you MUST update .prizm-docs/ per Prizm auto-update protocol. Steps: 1) Run git diff --cached --name-status. 2) Map changed files to modules via root.prizm MODULE_INDEX. 3) Read and update affected .prizm files (only changed sections). 4) Append to changelog.prizm. 5) Stage .prizm files with git add .prizm-docs/. 6) Then proceed with commit using prizmkit-committer workflow. RULES: Never rewrite entire .prizm files. Never add prose. Only update affected sections.'"
+            "command": "SRC=$(git diff --cached --name-only 2>/dev/null | grep -cE '\\.(ts|tsx|js|jsx|py|go|rs|java)$'); if [ \"$SRC\" -gt 0 ]; then PRIZM=$(git diff --cached --name-only 2>/dev/null | grep -c '^\\.prizm-docs/'); if [ \"$PRIZM\" -gt 0 ]; then echo \"PRIZMKIT_DOC_STATUS: $SRC source file(s) staged | .prizm-docs/ updated ($PRIZM file(s))\"; else echo \"PRIZMKIT_DOC_STATUS: $SRC source file(s) staged | .prizm-docs/ NOT UPDATED — update if this is a feature change\"; fi; fi"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if echo \"$CLAUDE_TOOL_INPUT\" 2>/dev/null | grep -qE 'git (commit|merge|rebase)' 2>/dev/null; then DRIFT=$(sh .prizmkit/scripts/diff-prizm-docs.sh 2>/dev/null); if [ -n \"$DRIFT\" ]; then echo \"PRIZMKIT_DRIFT_DETECTED: prizm-docs structural differences found after git operation:\"; echo \"$DRIFT\"; echo \"Please update affected .prizm-docs/ files using /prizmkit-prizm-docs.\"; fi; fi"
           }
         ]
       }

package/bundled/templates/hooks/commit-intent-codebuddy.json

@@ -6,7 +6,18 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo 'PRIZMKIT_DOC_UPDATE_REQUIRED: Before committing, you MUST update .prizm-docs/ per Prizm auto-update protocol. Steps: 1) Run git diff --cached --name-status. 2) Map changed files to modules via root.prizm MODULE_INDEX. 3) Read and update affected .prizm files (only changed sections). 4) Append to changelog.prizm. 5) Stage .prizm files with git add .prizm-docs/. 6) Then proceed with commit using prizmkit-committer workflow. RULES: Never rewrite entire .prizm files. Never add prose. Only update affected sections.'"
+            "command": "SRC=$(git diff --cached --name-only 2>/dev/null | grep -cE '\\.(ts|tsx|js|jsx|py|go|rs|java)$'); if [ \"$SRC\" -gt 0 ]; then PRIZM=$(git diff --cached --name-only 2>/dev/null | grep -c '^\\.prizm-docs/'); if [ \"$PRIZM\" -gt 0 ]; then echo \"PRIZMKIT_DOC_STATUS: $SRC source file(s) staged | .prizm-docs/ updated ($PRIZM file(s))\"; else echo \"PRIZMKIT_DOC_STATUS: $SRC source file(s) staged | .prizm-docs/ NOT UPDATED — update if this is a feature change\"; fi; fi"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "TOOL_INPUT=\"${CLAUDE_TOOL_INPUT:-${CODEBUDDY_TOOL_INPUT:-}}\"; if echo \"$TOOL_INPUT\" | grep -qE 'git (commit|merge|rebase)' 2>/dev/null; then DRIFT=$(sh .prizmkit/scripts/diff-prizm-docs.sh 2>/dev/null); if [ -n \"$DRIFT\" ]; then echo \"PRIZMKIT_DRIFT_DETECTED: prizm-docs structural differences found:\"; echo \"$DRIFT\"; echo \"Please update affected .prizm-docs/ files.\"; fi; fi"
           }
         ]
       }

package/bundled/templates/hooks/diff-prizm-docs.sh

@@ -0,0 +1,158 @@
+#!/bin/sh
+# PrizmKit: diff-prizm-docs.sh
+# Outputs structural differences between .prizm-docs/ and source code.
+# Silent (exit 0) if no differences or if .prizm-docs doesn't exist.
+# POSIX sh only — no arrays, no bashisms.
+
+set -e
+
+ROOT_PRIZM=".prizm-docs/root.prizm"
+
+# 1. Exit silently if no root.prizm
+[ -f "$ROOT_PRIZM" ] || exit 0
+
+# 2. Detect language from LANG: field
+LANG_VAL=$(grep '^LANG:' "$ROOT_PRIZM" | head -1 | sed 's/^LANG:[[:space:]]*//' | tr '[:upper:]' '[:lower:]')
+
+case "$LANG_VAL" in
+  go)
+    FILE_PATTERN="*.go"
+    ;;
+  javascript|typescript|javascript/typescript|typescript/javascript)
+    FILE_PATTERN="*.ts *.tsx *.js *.jsx"
+    ;;
+  python)
+    FILE_PATTERN="*.py"
+    ;;
+  rust)
+    FILE_PATTERN="*.rs"
+    ;;
+  *)
+    FILE_PATTERN=""
+    ;;
+esac
+
+# Helper: count source files in a directory (maxdepth 1) by language
+count_source_files() {
+  _dir="$1"
+  [ -d "$_dir" ] || { echo 0; return; }
+  if [ -z "$FILE_PATTERN" ]; then
+    # All non-hidden files
+    find "$_dir" -maxdepth 1 -type f ! -name '.*' 2>/dev/null | wc -l | tr -d ' '
+  else
+    _count=0
+    for _pat in $FILE_PATTERN; do
+      _c=$(find "$_dir" -maxdepth 1 -type f -name "$_pat" 2>/dev/null | wc -l | tr -d ' ')
+      _count=$((_count + _c))
+    done
+    echo "$_count"
+  fi
+}
+
+# 3. Parse MODULE_INDEX from root.prizm
+# Extract lines between MODULE_INDEX: and next ALL-CAPS header or EOF
+# Each module line: "- src/auth: ..." -> source path is text before first ":" after "- "
+REGISTERED_PATHS=""
+_in_index=0
+while IFS= read -r line; do
+  case "$line" in
+    MODULE_INDEX:*)
+      _in_index=1
+      continue
+      ;;
+  esac
+  if [ "$_in_index" -eq 1 ]; then
+    # Check for next ALL-CAPS section header (word followed by colon, all uppercase letters)
+    _header=$(echo "$line" | grep '^[A-Z_][A-Z_]*:' || true)
+    if [ -n "$_header" ]; then
+      break
+    fi
+    # Extract source path from "- src/auth: ..."
+    case "$line" in
+      "- "*)
+        _path=$(echo "$line" | sed 's/^- //' | sed 's/:.*//')
+        if [ -n "$_path" ]; then
+          REGISTERED_PATHS="${REGISTERED_PATHS}${_path}
+"
+        fi
+        ;;
+    esac
+  fi
+done < "$ROOT_PRIZM"
+
+# 4. Check each registered module for drift
+echo "$REGISTERED_PATHS" | while IFS= read -r source_path; do
+  [ -z "$source_path" ] && continue
+
+  # Derive L1 prizm file path
+  l1_file=".prizm-docs/${source_path}.prizm"
+
+  if [ ! -f "$l1_file" ]; then
+    continue
+  fi
+
+  # Read declared FILES: count
+  declared=$(grep '^FILES:' "$l1_file" | head -1 | awk '{print $2}')
+  [ -z "$declared" ] && continue
+
+  # Count actual source files
+  actual=$(count_source_files "$source_path")
+
+  if [ "$actual" -gt 0 ] && [ "$declared" != "$actual" ]; then
+    echo "MODULE_DRIFT: $source_path | declared FILES: $declared | actual: $actual"
+  fi
+done
+
+# 5. Find orphan docs
+find .prizm-docs -name '*.prizm' 2>/dev/null | while IFS= read -r prizm_file; do
+  _basename=$(basename "$prizm_file")
+  case "$_basename" in
+    root.prizm|changelog.prizm|changelog-archive.prizm)
+      continue
+      ;;
+  esac
+
+  # Derive source path: remove .prizm-docs/ prefix and .prizm suffix
+  source_path=$(echo "$prizm_file" | sed 's|^\.prizm-docs/||' | sed 's|\.prizm$||')
+
+  if [ ! -d "$source_path" ]; then
+    echo "ORPHAN_DOC: $prizm_file | source dir missing"
+  fi
+done
+
+# 6. Find unregistered directories
+find . -mindepth 1 -maxdepth 3 -type d \
+  ! -path '*/.*' \
+  ! -path '*/node_modules/*' ! -path './node_modules' \
+  ! -path '*/vendor/*' ! -path './vendor' \
+  ! -path '*/dist/*' ! -path './dist' \
+  ! -path '*/build/*' ! -path './build' \
+  ! -path '*/__pycache__/*' ! -path './__pycache__' \
+  ! -path '*/target/*' ! -path './target' \
+  ! -path '*/tests/*' ! -path './tests' \
+  ! -path '*/__tests__/*' ! -path './__tests__' \
+  ! -path '*/.prizm-docs/*' ! -path './.prizm-docs' \
+  ! -path '*/.claude/*' ! -path './.claude' \
+  ! -path '*/.codebuddy/*' ! -path './.codebuddy' \
+  ! -path '*/dev-pipeline/*' ! -path './dev-pipeline' \
+  ! -path '*/coverage/*' ! -path './coverage' \
+  ! -path '*/.nyc_output/*' ! -path './.nyc_output' \
+  ! -path '*/out/*' ! -path './out' \
+  ! -path '*/tmp/*' ! -path './tmp' \
+  2>/dev/null | while IFS= read -r candidate; do
+  # Normalize: remove leading ./
+  candidate_clean=$(echo "$candidate" | sed 's|^\./||')
+
+  # Count source files
+  file_count=$(count_source_files "$candidate_clean")
+
+  if [ "$file_count" -ge 3 ]; then
+    # Check if registered in MODULE_INDEX
+    _match=$(echo "$REGISTERED_PATHS" | grep -Fx "$candidate_clean" || true)
+    if [ -z "$_match" ]; then
+      echo "UNREGISTERED: $candidate_clean | $file_count source files | not in MODULE_INDEX"
+    fi
+  fi
+done
+
+exit 0

package/bundled/templates/hooks/prizm-pre-commit.sh

@@ -0,0 +1,59 @@
+#!/bin/sh
+# prizm-pre-commit.sh — git pre-commit hook for .prizm-docs validation
+
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+
+# Only run in prizm projects
+[ -f "$PROJECT_ROOT/.prizm-docs/root.prizm" ] || exit 0
+
+VALIDATE_SCRIPT="$PROJECT_ROOT/.prizmkit/scripts/validate-prizm-docs.sh"
+[ -f "$VALIDATE_SCRIPT" ] || VALIDATE_SCRIPT="$PROJECT_ROOT/dev-pipeline/scripts/validate-prizm-docs.sh"
+
+if [ -f "$VALIDATE_SCRIPT" ]; then
+    sh "$VALIDATE_SCRIPT" --staged
+    exit $?
+fi
+
+# Inline fallback: core checks for staged .prizm files
+FILES=$(git diff --cached --name-only 2>/dev/null | grep '\.prizm$')
+[ -z "$FILES" ] && exit 0
+
+ERRORS=0
+for FILE in $FILES; do
+    [ -f "$FILE" ] || continue
+
+    if grep -qE '^#{1,6} ' "$FILE"; then
+        echo "ERROR: $FILE contains markdown headers (##). Use KEY: value format." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    if grep -q '^```' "$FILE"; then
+        echo "ERROR: $FILE contains code blocks. Use file_path:line_number reference." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    SIZE=$(wc -c < "$FILE" | tr -d ' ')
+    case "$FILE" in
+        *root.prizm) LIMIT=4096 ;;
+        *)
+            DIR=$(dirname "$FILE")
+            if [ "$DIR" = ".prizm-docs" ]; then
+                LIMIT=3072
+            else
+                LIMIT=5120
+            fi
+            ;;
+    esac
+
+    if [ "$SIZE" -gt "$LIMIT" ]; then
+        echo "ERROR: $FILE exceeds size limit (${SIZE}B > ${LIMIT}B)." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+done
+
+if [ "$ERRORS" -gt 0 ]; then
+    echo "PrizmKit: $ERRORS format error(s) in .prizm files. Fix before committing." >&2
+    exit 1
+fi
+
+exit 0

package/bundled/templates/hooks/validate-prizm-docs.sh

@@ -0,0 +1,84 @@
+#!/bin/sh
+# validate-prizm-docs.sh — validate .prizm file format and size limits
+# Usage: validate-prizm-docs.sh [--all | --staged]
+
+MODE="${1:---staged}"
+ERRORS=0
+
+# Not a prizm project — exit silently
+[ -f ".prizm-docs/root.prizm" ] || exit 0
+
+# Collect files to check
+if [ "$MODE" = "--all" ]; then
+    FILES=$(find .prizm-docs -name '*.prizm' 2>/dev/null)
+elif [ "$MODE" = "--staged" ]; then
+    FILES=$(git diff --cached --name-only 2>/dev/null | grep '\.prizm$')
+else
+    echo "Usage: validate-prizm-docs.sh [--all | --staged]" >&2
+    exit 1
+fi
+
+# Nothing to check — exit silently
+[ -z "$FILES" ] && exit 0
+
+for FILE in $FILES; do
+    [ -f "$FILE" ] || continue
+
+    # Check markdown headers
+    if grep -qE '^#{1,6} ' "$FILE"; then
+        echo "ERROR: $FILE contains markdown headers (##). Use KEY: value format." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    # Check code blocks
+    if grep -q '^```' "$FILE"; then
+        echo "ERROR: $FILE contains code blocks. Use file_path:line_number reference." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    # Size limits — determine level by path depth
+    SIZE=$(wc -c < "$FILE" | tr -d ' ')
+    case "$FILE" in
+        *root.prizm)
+            LIMIT=4096; LEVEL="L0"
+            HINT="Consolidate MODULE_INDEX, keep top-5 RULES."
+            ;;
+        *)
+            # L1 = direct child of .prizm-docs/, L2 = nested deeper
+            DIR=$(dirname "$FILE")
+            if [ "$DIR" = ".prizm-docs" ]; then
+                LIMIT=3072; LEVEL="L1"
+                HINT="Move implementation details to L2."
+            else
+                LIMIT=5120; LEVEL="L2"
+                HINT="Archive CHANGELOG entries older than 90 days."
+            fi
+            ;;
+    esac
+
+    if [ "$SIZE" -gt "$LIMIT" ]; then
+        echo "ERROR: $FILE exceeds $LEVEL limit (${SIZE}B > ${LIMIT}B). $HINT" >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    # Required fields in root.prizm
+    case "$FILE" in
+        *root.prizm)
+            if ! grep -q 'PRIZM_VERSION:' "$FILE"; then
+                echo "ERROR: $FILE missing required field PRIZM_VERSION:" >&2
+                ERRORS=$((ERRORS + 1))
+            fi
+            if ! grep -q 'MODULE_INDEX:' "$FILE"; then
+                echo "ERROR: $FILE missing required field MODULE_INDEX:" >&2
+                ERRORS=$((ERRORS + 1))
+            fi
+            ;;
+    esac
+done
+
+if [ "$ERRORS" -gt 0 ]; then
+    echo "PrizmKit: $ERRORS format error(s) in .prizm files. Fix before committing." >&2
+    exit 1
+fi
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {

package/src/detect-platform.js

@@ -6,9 +6,9 @@
 import { execFileSync } from 'child_process';
 
 /**
- * 允许检测的命令白名单
+ * 允许检测的命令白名单（仅用于 which 检测）
  */
-const ALLOWED_COMMANDS = ['cbc', 'claude'];
+const ALLOWED_COMMANDS = ['cbc', 'claude', 'claude-internal'];
 
 /**
  * 检查命令是否存在于 PATH 中
@@ -26,21 +26,33 @@ function commandExists(cmd) {
 }
 
 /**
- * 检测已安装的 AI CLI 工具，并返回推荐的默认平台。
- * @returns {{ cbc: boolean, claude: boolean, suggested: string }}
+ * 检测已安装的 AI CLI 工具，并返回推荐的默认平台和 CLI 命令。
+ *
+ * 注意：platform 控制目录结构（.codebuddy/ 或 .claude/），
+ *       suggestedCli 是实际运行的可执行命令，二者相互独立。
+ *
+ * @returns {{ cbc: boolean, claude: boolean, claudeInternal: boolean, suggested: string, suggestedCli: string }}
  */
 export function detectPlatform() {
   const cbc = commandExists('cbc');
   const claude = commandExists('claude');
+  const claudeInternal = commandExists('claude-internal');
 
+  // platform 建议：基于目录结构，优先 both
   let suggested = 'codebuddy';
-  if (cbc && claude) {
+  if ((cbc) && (claude || claudeInternal)) {
     suggested = 'both';
-  } else if (claude && !cbc) {
+  } else if ((claude || claudeInternal) && !cbc) {
     suggested = 'claude';
-  } else if (cbc && !claude) {
+  } else if (cbc && !claude && !claudeInternal) {
     suggested = 'codebuddy';
   }
 
-  return { cbc, claude, suggested };
+  // CLI 命令建议：优先 cbc，其次 claude-internal，再次 claude
+  let suggestedCli = '';
+  if (cbc) suggestedCli = 'cbc';
+  else if (claudeInternal) suggestedCli = 'claude-internal';
+  else if (claude) suggestedCli = 'claude';
+
+  return { cbc, claude, claudeInternal, suggested, suggestedCli };
 }

package/src/index.js

@@ -33,6 +33,7 @@ export async function runScaffold(directory, options) {
   const cliStatus = [
     detected.cbc ? chalk.green('cbc ✓') : chalk.gray('cbc ✗'),
     detected.claude ? chalk.green('claude ✓') : chalk.gray('claude ✗'),
+    detected.claudeInternal ? chalk.green('claude-internal ✓') : chalk.gray('claude-internal ✗'),
   ].join('  ');
   console.log(`  检测到的 CLI 工具:  ${cliStatus}`);
   console.log(`  目标目录:          ${projectRoot}`);
@@ -64,16 +65,16 @@ export async function runScaffold(directory, options) {
 
   // === 交互式模式 ===
   try {
-    // 1. 选择平台
+    // 1. 选择平台（控制安装的目录结构）
     const platform = await select({
-      message: '选择目标平台:',
+      message: '选择目标平台 (决定安装的目录结构):',
       choices: [
         {
-          name: `CodeBuddy CLI (cbc)${detected.cbc ? chalk.green(' ← 已检测到') : ''}`,
+          name: `CodeBuddy (.codebuddy/)${detected.cbc ? chalk.green(' ← 已检测到 cbc') : ''}`,
           value: 'codebuddy',
         },
         {
-          name: `Claude Code CLI (claude)${detected.claude ? chalk.green(' ← 已检测到') : ''}`,
+          name: `Claude Code (.claude/)${(detected.claude || detected.claudeInternal) ? chalk.green(' ← 已检测到') : ''}`,
           value: 'claude',
         },
         {
@@ -84,11 +85,10 @@ export async function runScaffold(directory, options) {
       default: detected.suggested,
     });
 
-    // 1.5. AI CLI 命令配置
-    const defaultCli = detected.cbc ? 'cbc' : detected.claude ? 'claude' : '';
+    // 1.5. AI CLI 命令配置（独立于平台，决定实际运行的可执行命令）
     const aiCli = await input({
-      message: '底层 AI CLI 可执行命令 (留空自动检测):',
-      default: defaultCli,
+      message: '底层 AI CLI 可执行命令 (可自定义，如 claude-internal --dangerously-skip-permissions):',
+      default: detected.suggestedCli,
     });
 
     // 2. 选择技能套件

package/src/scaffold.js

@@ -439,6 +439,69 @@ async function installSettings(platform, projectRoot, options, dryRun) {
   }
 }
 
+/**
+ * 安装 git pre-commit hook（prizm 格式校验）
+ */
+async function installGitHook(projectRoot, dryRun) {
+  const gitDir = path.join(projectRoot, '.git');
+
+  if (dryRun) {
+    console.log(chalk.gray('      [dry-run] .git/hooks/pre-commit (prizm format check)'));
+    return;
+  }
+
+  if (!fs.existsSync(gitDir)) return;
+
+  const templatePath = path.join(getTemplatesDir(), 'hooks', 'prizm-pre-commit.sh');
+  const hooksDir = path.join(gitDir, 'hooks');
+  const preCommitPath = path.join(hooksDir, 'pre-commit');
+
+  fs.mkdirSync(hooksDir, { recursive: true });
+
+  if (fs.existsSync(preCommitPath)) {
+    const existing = fs.readFileSync(preCommitPath, 'utf8');
+    if (existing.includes('PrizmKit')) return;
+    const hookContent = fs.readFileSync(templatePath, 'utf8');
+    fs.writeFileSync(preCommitPath, existing + '\n\n' + hookContent);
+  } else {
+    await fs.copy(templatePath, preCommitPath);
+    fs.chmodSync(preCommitPath, 0o755);
+  }
+
+  console.log(chalk.green('      ✓ .git/hooks/pre-commit (prizm format check)'));
+}
+
+/**
+ * 安装 PrizmKit 脚本到 .prizmkit/scripts/（始终安装）
+ */
+async function installPrizmkitScripts(projectRoot, dryRun) {
+  const scriptsDir = path.join(projectRoot, '.prizmkit', 'scripts');
+  const templateHooksDir = path.join(getTemplatesDir(), 'hooks');
+
+  const scripts = [
+    'validate-prizm-docs.sh',
+    'diff-prizm-docs.sh',
+  ];
+
+  if (dryRun) {
+    for (const s of scripts) {
+      console.log(chalk.gray(`      [dry-run] .prizmkit/scripts/${s}`));
+    }
+    return;
+  }
+
+  await fs.ensureDir(scriptsDir);
+
+  for (const s of scripts) {
+    const src = path.join(templateHooksDir, s);
+    if (!fs.existsSync(src)) continue;
+    const tgt = path.join(scriptsDir, s);
+    await fs.copy(src, tgt);
+    fs.chmodSync(tgt, 0o755);
+    console.log(chalk.green(`      ✓ .prizmkit/scripts/${s}`));
+  }
+}
+
 /**
  * 安装项目记忆文件（CODEBUDDY.md / CLAUDE.md）
  */
@@ -653,6 +716,14 @@ export async function scaffold(config) {
     }
   }
 
+  // 10. Git pre-commit hook
+  console.log(chalk.blue('    Git Hook:'));
+  await installGitHook(projectRoot, dryRun);
+
+  // 11. PrizmKit scripts (always installed)
+  console.log(chalk.blue('    PrizmKit 脚本:'));
+  await installPrizmkitScripts(projectRoot, dryRun);
+
   // === 完成 ===
   console.log('');
   console.log(chalk.bold('  ════════════════════════════════════════════════'));
@@ -667,7 +738,8 @@ export async function scaffold(config) {
   if (!dryRun) {
     // 打印下一步提示
     const mainPlatform = platforms.includes('claude') ? 'claude' : 'codebuddy';
-    const cli = mainPlatform === 'claude' ? 'claude' : 'cbc';
+    const defaultCli = mainPlatform === 'claude' ? 'claude' : 'cbc';
+    const cli = aiCli || defaultCli;
 
     console.log('');
     console.log('  下一步:');