prizmkit 1.1.100 → 1.1.102

package/bundled/skills/refactor-pipeline-launcher/SKILL.md

@@ -11,8 +11,8 @@ Launch the autonomous refactor pipeline from within an AI CLI conversation. The
 
 Three execution modes are available. The user chooses one before configuring other options:
 
-1. **Foreground** (recommended) — `.prizmkit/dev-pipeline/run-refactor.sh run`. Visible output, direct error feedback, no orphaned processes.
-2. **Background daemon** — `.prizmkit/dev-pipeline/launch-refactor-daemon.sh`. Runs fully detached, survives AI CLI session closure.
+1. **Foreground** (recommended) — `python3 ./.prizmkit/dev-pipeline/cli.py refactor run`. Visible output, direct error feedback, no orphaned processes.
+2. **Background daemon** — `python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor start .prizmkit/plans/refactor-list.json`. Runs fully detached, survives AI CLI session closure.
 3. **Manual** — Display the assembled command(s) only. Do not execute anything. User runs them on their own.
 
 ### When to Use
@@ -45,15 +45,15 @@ Three execution modes are available. The user chooses one before configuring oth
 
 Before any action, validate:
 
-1. **refactor pipeline exists**: Confirm `.prizmkit/dev-pipeline/launch-refactor-daemon.sh` and `.prizmkit/dev-pipeline/run-refactor.sh` are present and executable
+1. **refactor pipeline exists**: Confirm `.prizmkit/dev-pipeline/cli.py` is present
 2. **For start**: `.prizmkit/plans/refactor-list.json` must exist in `.prizmkit/plans/` (or user-specified path)
-3. **Dependencies**: `jq`, `python3`, AI CLI (`cbc` or `claude`) must be in PATH
-4. **Python version**: Requires Python 3.8+ for dev-pipeline scripts
+3. **Dependencies**: `python3`, `git`, and AI CLI (`cbc` or `claude`) must be in PATH
+4. **Python version**: Requires Python 3.10+ for the unified dev-pipeline runtime
 5. **Browser tools** (optional): If any refactor has `browser_interaction` field, check the corresponding tool is available. Refactors may specify `tool: "playwright-cli"`, `tool: "opencli"`, or `tool: "auto"` (AI chooses at runtime).
 
 Quick check:
 ```bash
-command -v jq && command -v python3 && (command -v cbc || command -v claude) && echo "All dependencies OK"
+command -v python3 && command -v git && (command -v cbc || command -v claude) && echo "All dependencies OK"
 # Optional: browser interaction support (check both tools — refactors may use either)
 command -v playwright-cli && echo "playwright-cli OK" || echo "playwright-cli not found (playwright browser verification will be skipped)"
 command -v opencli && echo "opencli OK" || echo "opencli not found (opencli browser verification will be skipped)"
@@ -79,7 +79,7 @@ Detect user intent from their message, then follow the corresponding workflow:
 
 2. **Check not already running**:
    ```bash
-   .prizmkit/dev-pipeline/launch-refactor-daemon.sh status 2>/dev/null
+   python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor status 2>/dev/null
    ```
    If running, inform user and ask: "Refactor pipeline is already running. Want to restart it, check status, or view logs?"
 
@@ -106,10 +106,7 @@ Detect user intent from their message, then follow the corresponding workflow:
    ```
    If pipeline state already exists, use the status command instead:
    ```bash
-   python3 .prizmkit/dev-pipeline/scripts/update-refactor-status.py \
-     --refactor-list .prizmkit/plans/refactor-list.json \
-     --state-dir .prizmkit/state/refactor \
-     --action status 2>/dev/null
+   python3 ./.prizmkit/dev-pipeline/cli.py refactor status .prizmkit/plans/refactor-list.json
    ```
 
 4. **Run preflight checks** (behavior-preservation baseline):
@@ -168,34 +165,34 @@ Detect user intent from their message, then follow the corresponding workflow:
 
    **Foreground command:**
    ```bash
-   VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 .prizmkit/dev-pipeline/run-refactor.sh run .prizmkit/plans/refactor-list.json
+   VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 python3 ./.prizmkit/dev-pipeline/cli.py refactor run .prizmkit/plans/refactor-list.json
    ```
    With all options:
    ```bash
    VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 MAX_RETRIES=5 ENABLE_DEPLOY=1 PRIZMKIT_EFFORT=high \
-     .prizmkit/dev-pipeline/run-refactor.sh run .prizmkit/plans/refactor-list.json
+     python3 ./.prizmkit/dev-pipeline/cli.py refactor run .prizmkit/plans/refactor-list.json
    ```
 
    **Background daemon command:**
    ```bash
-   .prizmkit/dev-pipeline/launch-refactor-daemon.sh start .prizmkit/plans/refactor-list.json --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1"
+   python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor start .prizmkit/plans/refactor-list.json --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1"
    ```
    With all options:
    ```bash
-   .prizmkit/dev-pipeline/launch-refactor-daemon.sh start .prizmkit/plans/refactor-list.json \
+   python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor start .prizmkit/plans/refactor-list.json \
      --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 MAX_RETRIES=5 ENABLE_DEPLOY=1"
    ```
 
    **Manual mode**: Print the assembled command(s) and **stop here**. Do not execute anything. Do not proceed to step 8.
    ```
    # To run in foreground:
-   VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 .prizmkit/dev-pipeline/run-refactor.sh run .prizmkit/plans/refactor-list.json
+   VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 python3 ./.prizmkit/dev-pipeline/cli.py refactor run .prizmkit/plans/refactor-list.json
 
    # To run in background (detached):
-   .prizmkit/dev-pipeline/launch-refactor-daemon.sh start .prizmkit/plans/refactor-list.json --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1"
+   python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor start .prizmkit/plans/refactor-list.json --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1"
 
    # To check status:
-   .prizmkit/dev-pipeline/run-refactor.sh status .prizmkit/plans/refactor-list.json
+   python3 ./.prizmkit/dev-pipeline/cli.py refactor status .prizmkit/plans/refactor-list.json
    ```
 
 8. **Confirm and launch** (Foreground and Background only — Manual mode ends at step 7):
@@ -209,16 +206,16 @@ Detect user intent from their message, then follow the corresponding workflow:
    **If foreground**: Pipeline runs to completion in the terminal. After it finishes:
    - Summarize results: total refactors, succeeded, failed, skipped
    - If all succeeded: each refactor session has already run `prizmkit-retrospective` internally. Ask user what's next.
-   - If some failed: show failed refactor IDs and suggest `reset-refactor.sh <R-XXX> --clean --run` for a fresh retry
+   - If some failed: show failed refactor IDs and suggest `python3 ./.prizmkit/dev-pipeline/cli.py reset refactor <R-XXX> --clean --run` for a fresh retry
 
    **If background daemon**:
    1. Verify launch:
       ```bash
-      .prizmkit/dev-pipeline/launch-refactor-daemon.sh status
+      python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor status
       ```
    2. Start log monitoring — Use the Bash tool with `run_in_background: true`:
       ```bash
-      tail -f .prizmkit/state/refactor/pipeline-daemon.log
+      python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor logs --follow
       ```
    3. Report to user:
       - Pipeline PID
@@ -232,20 +229,17 @@ Detect user intent from their message, then follow the corresponding workflow:
 
 1. **Check daemon status**:
    ```bash
-   .prizmkit/dev-pipeline/launch-refactor-daemon.sh status
+   python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor status
    ```
 
 2. **Show refactor-level progress**:
    ```bash
-   python3 .prizmkit/dev-pipeline/scripts/update-refactor-status.py \
-     --refactor-list .prizmkit/plans/refactor-list.json \
-     --state-dir .prizmkit/state/refactor \
-     --action status
+   python3 ./.prizmkit/dev-pipeline/cli.py refactor status .prizmkit/plans/refactor-list.json
    ```
 
 3. **Show recent log activity** (last 20 lines):
    ```bash
-   tail -20 .prizmkit/state/refactor/pipeline-daemon.log
+   python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor logs --lines 20
    ```
 
 4. **Summarize** to user: total refactors, completed, in-progress, failed, pending.
@@ -256,12 +250,12 @@ Detect user intent from their message, then follow the corresponding workflow:
 
 1. **Stop the daemon**:
    ```bash
-   .prizmkit/dev-pipeline/launch-refactor-daemon.sh stop
+   python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor stop
    ```
 
 2. **Verify stopped**:
    ```bash
-   .prizmkit/dev-pipeline/launch-refactor-daemon.sh status 2>/dev/null || true
+   python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor status 2>/dev/null || true
    ```
 
 3. **Inform user**: "Refactor pipeline stopped. State is preserved -- you can resume later with 'start refactoring' and it will pick up where it left off."
@@ -272,17 +266,17 @@ Detect user intent from their message, then follow the corresponding workflow:
 
 1. **Check if running**:
    ```bash
-   .prizmkit/dev-pipeline/launch-refactor-daemon.sh status 2>/dev/null
+   python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor status 2>/dev/null
    ```
 
 2. **If running** -- Start live tail with Bash tool `run_in_background: true`:
    ```bash
-   tail -f .prizmkit/state/refactor/pipeline-daemon.log
+   python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor logs --follow
    ```
 
 3. **If not running** -- Show last 50 lines:
    ```bash
-   tail -50 .prizmkit/state/refactor/pipeline-daemon.log
+   python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor logs --lines 50
    ```
 
 4. **For per-refactor session logs** (when user asks about a specific refactor):
@@ -300,12 +294,12 @@ Detect user intent from their message, then follow the corresponding workflow:
 When user says "retry R-001" or "clean retry R-001":
 
 ```bash
-.prizmkit/dev-pipeline/reset-refactor.sh R-001 --clean --run .prizmkit/plans/refactor-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py reset refactor R-001 --clean --run .prizmkit/plans/refactor-list.json
 ```
 
 Notes:
-- `reset-refactor.sh --clean --run` performs a full clean (deletes session history and artifacts) before retrying — this gives a fresh start.
-- Keep pipeline daemon mode for main run management (`launch-refactor-daemon.sh`).
+- `python3 ./.prizmkit/dev-pipeline/cli.py reset refactor <R-XXX> --clean --run .prizmkit/plans/refactor-list.json` performs a full clean (deletes session history and artifacts) before retrying the selected refactor — this gives a fresh start.
+- Keep pipeline daemon mode for main run management (`python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor start`, `python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor status`, or `python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor stop`).
 
 ---
 

package/bundled/skills/refactor-pipeline-launcher/references/configuration.md

@@ -37,17 +37,18 @@ Not exposed in interactive menu, pass via `--env`:
 | `.prizmkit/plans/refactor-list.json` not found | Tell user to run `refactor-planner` skill first |
 | Circular dependencies in refactor list | Fix dependency graph in `.prizmkit/plans/refactor-list.json` before launching |
 | Test baseline failing | Fix failing tests before starting refactoring — behavior preservation requires a green baseline |
-| `jq` not installed | Suggest: `brew install jq` |
+| `python3` not installed | Install Python 3.10+ and rerun the Python runtime command |
+| `git` not installed | Install git; the Python runtime uses git for branch/worktree/status operations |
 | `cbc`/`claude` not in PATH | Check AI CLI installation |
 | Refactor pipeline already running | Show status, ask if user wants to stop and restart |
-| PID file stale (process dead) | `launch-refactor-daemon.sh` auto-cleans, retry start |
-| Launch failed (process died immediately) | Show last 20 lines of log: `tail -20 .prizmkit/state/refactor/pipeline-daemon.log` |
-| Refactor stuck/blocked | Use `reset-refactor.sh <R-XXX> --clean --run` for a fresh retry |
-| All refactors blocked/failed | Show status, suggest recovery: `.prizmkit/dev-pipeline/reset-refactor.sh <R-XXX> --clean --run .prizmkit/plans/refactor-list.json` |
+| PID file stale (process dead) | `python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor start .prizmkit/plans/refactor-list.json` auto-cleans, retry start |
+| Launch failed (process died immediately) | Show last 20 lines of log: `python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor logs --lines 20` |
+| Refactor stuck/blocked | Use `python3 ./.prizmkit/dev-pipeline/cli.py reset refactor <R-XXX> --clean --run` for a fresh retry |
+| All refactors blocked/failed | Show status, suggest recovery: `python3 ./.prizmkit/dev-pipeline/cli.py reset refactor <R-XXX> --clean --run .prizmkit/plans/refactor-list.json` |
 | `playwright-cli` not installed | Browser verification skipped for playwright refactors (non-blocking). Suggest: `npm install -g @playwright/cli@latest && playwright-cli install --skills` |
 | `opencli` not installed | Browser verification skipped for opencli refactors (non-blocking). Install opencli for Chrome session-based browser verification |
 | Deploy session failed | Pipeline completed but deploy session exited non-zero. Check `.prizmkit/state/refactor/deploy/<session_id>/logs/session.log`. Retry manually: `/prizmkit-deploy`. |
-| Permission denied on script | Run `chmod +x .prizmkit/dev-pipeline/launch-refactor-daemon.sh .prizmkit/dev-pipeline/run-refactor.sh` |
+| Permission denied running Python CLI | Ensure Python is installed and the command uses `python3 ./.prizmkit/dev-pipeline/cli.py ...` |
 
 ## Advanced Configuration Round
 

package/bundled/skills/refactor-workflow/SKILL.md

@@ -234,7 +234,7 @@ AskUserQuestion:
 
 1. **Initial status check**:
    ```bash
-   .prizmkit/dev-pipeline/launch-refactor-daemon.sh status
+   python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor status
    ```
 
 2. **Offer monitoring options**:
@@ -244,10 +244,7 @@ AskUserQuestion:
 
 3. **Periodic progress reports** (when user asks):
    ```bash
-   python3 .prizmkit/dev-pipeline/scripts/update-refactor-status.py \
-     --refactor-list .prizmkit/plans/refactor-list.json \
-     --state-dir .prizmkit/state/refactor \
-     --action status
+   python3 ./.prizmkit/dev-pipeline/cli.py refactor status .prizmkit/plans/refactor-list.json
    ```
 
 4. **Completion report** (when pipeline finishes all refactor items):
@@ -306,7 +303,7 @@ While the pipeline runs, the user can continue the conversation:
 | No tests exist for target module | WARN user, recommend writing tests first before refactoring |
 | `refactor-planner` cannot parse goals | Refine the goals summary and retry |
 | `.prizmkit/plans/refactor-list.json` generation failed | Show error, retry with refined input |
-| Pipeline launch failed | Show daemon log, suggest manual start |
+| Pipeline launch failed | Show daemon log, suggest manual start with `python3 ./.prizmkit/dev-pipeline/cli.py refactor run .prizmkit/plans/refactor-list.json` or `python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor start .prizmkit/plans/refactor-list.json` |
 | All refactor items blocked/failed | Show status, suggest retrying specific items |
 | User wants to cancel mid-brainstorming | Save conversation context, offer to resume later |
 | Behavior regression detected during pipeline | Pipeline handles per-item — failed items are retried or reported |

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

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "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 '^\\.prizmkit/prizm-docs/'); if [ \"$PRIZM\" -gt 0 ]; then echo \"PRIZMKIT_DOC_STATUS: $SRC source file(s) staged | .prizmkit/prizm-docs/ updated ($PRIZM file(s))\"; else echo \"PRIZMKIT_DOC_STATUS: $SRC source file(s) staged | .prizmkit/prizm-docs/ NOT UPDATED — update if this is a feature change\"; fi; fi"
+            "command": "python3 -c \"import subprocess,sys; r=subprocess.run(['git','diff','--cached','--name-only'],text=True,encoding='utf-8',errors='replace',stdout=subprocess.PIPE,stderr=subprocess.DEVNULL); files=[p for p in r.stdout.splitlines() if p.strip()] if r.returncode==0 else []; src=[p for p in files if p.endswith(('.ts','.tsx','.js','.jsx','.py','.go','.rs','.java'))]; prizm=[p for p in files if p.startswith('.prizmkit/prizm-docs/')]; print(f'PRIZMKIT_DOC_STATUS: {len(src)} source file(s) staged | .prizmkit/prizm-docs/ updated ({len(prizm)} file(s))' if src and prizm else (f'PRIZMKIT_DOC_STATUS: {len(src)} source file(s) staged | .prizmkit/prizm-docs/ NOT UPDATED — update if this is a feature change' if src else ''), end='')\""
           }
         ]
       }
@@ -17,7 +17,7 @@
         "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 .prizmkit/prizm-docs/ files.\"; fi; fi"
+            "command": "python3 -c \"import os,re,subprocess,sys; data=os.environ.get('CLAUDE_TOOL_INPUT') or os.environ.get('CODEBUDDY_TOOL_INPUT') or ''; script='.prizmkit/scripts/diff-prizm-docs.py'; should=bool(re.search(r'git\\s+(commit|merge|rebase)', data)); res=subprocess.run([sys.executable, script],text=True,encoding='utf-8',errors='replace',stdout=subprocess.PIPE,stderr=subprocess.DEVNULL) if should and os.path.isfile(script) else None; drift=(res.stdout.strip() if res else ''); print('PRIZMKIT_DRIFT_DETECTED: prizm-docs structural differences found:\\n'+drift+'\\nPlease update affected .prizmkit/prizm-docs/ files.') if drift else None\""
           }
         ]
       }

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

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Report structural drift between .prizmkit/prizm-docs and source files."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path, PurePosixPath
+
+DOCS_ROOT = Path(".prizmkit/prizm-docs")
+ROOT_PRIZM = DOCS_ROOT / "root.prizm"
+SUPPORTED_EXTENSIONS = {
+    "go": [".go"],
+    "javascript": [".js", ".jsx"],
+    "typescript": [".ts", ".tsx"],
+    "javascript/typescript": [".ts", ".tsx", ".js", ".jsx"],
+    "typescript/javascript": [".ts", ".tsx", ".js", ".jsx"],
+    "python": [".py"],
+    "rust": [".rs"],
+}
+EXCLUDED_DIR_NAMES = {
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+    "__pycache__",
+    "target",
+    "tests",
+    "__tests__",
+    ".claude",
+    ".codebuddy",
+    "dev-pipeline",
+    "coverage",
+    ".nyc_output",
+    "out",
+    "tmp",
+}
+ALL_CAPS_HEADER_RE = re.compile(r"^[A-Z_][A-Z_]*:")
+
+
+def read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def section_lines(lines: list[str], section: str) -> list[str]:
+    in_section = False
+    collected: list[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if stripped == f"{section}:":
+            in_section = True
+            continue
+        if in_section and ALL_CAPS_HEADER_RE.match(stripped):
+            break
+        if in_section:
+            collected.append(line.rstrip("\n"))
+    return collected
+
+
+def strip_tags(value: str) -> str:
+    return re.sub(r"\s+\[[^\]]*\]", "", value).strip()
+
+
+def parse_module_line(line: str) -> tuple[str, str | None] | None:
+    stripped = line.strip()
+    if not stripped.startswith("- "):
+        return None
+    body = stripped[2:].strip()
+    pointer: str | None = None
+    if "->" in body:
+        body, pointer_part = body.split("->", 1)
+        pointer = pointer_part.strip().split()[0] if pointer_part.strip() else None
+    if ":" in body:
+        body = body.split(":", 1)[0]
+    source_path = strip_tags(body).strip()
+    if not source_path:
+        return None
+    return source_path, pointer
+
+
+def parse_registered_modules(root_text: str) -> dict[str, str | None]:
+    lines = root_text.splitlines()
+    modules: dict[str, str | None] = {}
+    for section in ["MODULE_INDEX", "MODULE_GROUPS"]:
+        for line in section_lines(lines, section):
+            parsed = parse_module_line(line)
+            if parsed:
+                source_path, pointer = parsed
+                modules[source_path] = pointer
+    return modules
+
+
+def parse_lang(root_text: str) -> list[str] | None:
+    for line in root_text.splitlines():
+        if line.startswith("LANG:"):
+            lang_value = line.split(":", 1)[1].strip().lower()
+            if lang_value in SUPPORTED_EXTENSIONS:
+                return SUPPORTED_EXTENSIONS[lang_value]
+            extensions: list[str] = []
+            for key, value in SUPPORTED_EXTENSIONS.items():
+                if key in lang_value:
+                    extensions.extend(value)
+            return sorted(set(extensions)) or None
+    return None
+
+
+def count_source_files(source_dir: Path, extensions: list[str] | None) -> int:
+    if not source_dir.is_dir():
+        return 0
+    count = 0
+    for child in source_dir.iterdir():
+        if not child.is_file() or child.name.startswith("."):
+            continue
+        if extensions is None or child.suffix in extensions:
+            count += 1
+    return count
+
+
+def l1_path_for(source_path: str, pointer: str | None) -> Path:
+    if pointer:
+        pointer_path = PurePosixPath(pointer)
+        if pointer_path.is_absolute():
+            return Path(pointer)
+        if pointer.startswith(".prizmkit/prizm-docs/"):
+            return Path(pointer)
+        return DOCS_ROOT / pointer
+    return DOCS_ROOT / f"{source_path}.prizm"
+
+
+def parse_declared_files(l1_path: Path) -> int | None:
+    if not l1_path.is_file():
+        return None
+    lines = read_text(l1_path).splitlines()
+    for index, line in enumerate(lines):
+        if not line.startswith("FILES:"):
+            continue
+        inline = line.split(":", 1)[1].strip()
+        if inline:
+            first = inline.split()[0]
+            if first.isdigit():
+                return int(first)
+            if "," in inline:
+                return len([part for part in inline.split(",") if part.strip()])
+            return 1
+        count = 0
+        for section_line in lines[index + 1 :]:
+            stripped = section_line.strip()
+            if ALL_CAPS_HEADER_RE.match(stripped):
+                break
+            if stripped.startswith("- "):
+                count += 1
+        return count
+    return None
+
+
+def iter_prizm_docs() -> list[Path]:
+    return sorted(path for path in DOCS_ROOT.rglob("*.prizm") if path.is_file())
+
+
+def source_path_for_doc(prizm_file: Path) -> str | None:
+    if prizm_file.name == "root.prizm":
+        return None
+    rel = prizm_file.relative_to(DOCS_ROOT).as_posix()
+    if len(PurePosixPath(rel).parts) > 1:
+        return None
+    return rel[: -len(".prizm")] if rel.endswith(".prizm") else rel
+
+
+def should_skip_dir(dir_path: Path) -> bool:
+    parts = dir_path.parts
+    return any(part.startswith(".") for part in parts) or any(part in EXCLUDED_DIR_NAMES for part in parts)
+
+
+def iter_candidate_dirs(max_depth: int = 3) -> list[Path]:
+    candidates: list[Path] = []
+    for root, dirs, _files in os.walk("."):
+        root_path = Path(root)
+        rel_path = Path(".") if root_path == Path(".") else root_path.relative_to(".")
+        depth = 0 if rel_path == Path(".") else len(rel_path.parts)
+        dirs[:] = [d for d in dirs if not should_skip_dir(rel_path / d)]
+        if depth == 0:
+            continue
+        if depth > max_depth:
+            dirs[:] = []
+            continue
+        if not should_skip_dir(rel_path):
+            candidates.append(rel_path)
+    return candidates
+
+
+def main() -> int:
+    if not ROOT_PRIZM.is_file():
+        return 0
+
+    root_text = read_text(ROOT_PRIZM)
+    extensions = parse_lang(root_text)
+    registered = parse_registered_modules(root_text)
+    registered_paths = set(registered.keys())
+
+    for source_path, pointer in registered.items():
+        l1_file = l1_path_for(source_path, pointer)
+        declared = parse_declared_files(l1_file)
+        if declared is None:
+            continue
+        actual = count_source_files(Path(source_path), extensions)
+        if actual > 0 and declared != actual:
+            print(f"MODULE_DRIFT: {source_path} | declared FILES: {declared} | actual: {actual}")
+
+    for prizm_file in iter_prizm_docs():
+        source_path = source_path_for_doc(prizm_file)
+        if source_path is None:
+            continue
+        if not Path(source_path).is_dir():
+            print(f"ORPHAN_DOC: {prizm_file.as_posix()} | source dir missing")
+
+    for candidate in iter_candidate_dirs():
+        candidate_clean = candidate.as_posix()
+        file_count = count_source_files(candidate, extensions)
+        if file_count >= 3 and candidate_clean not in registered_paths:
+            print(f"UNREGISTERED: {candidate_clean} | {file_count} source files | not in MODULE_INDEX")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Git pre-commit hook that runs Prizm docs validation."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def run_git(args: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args],
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        check=False,
+    )
+
+
+def main() -> int:
+    root_result = run_git(["rev-parse", "--show-toplevel"])
+    if root_result.returncode != 0:
+        return 0
+
+    project_root = Path(root_result.stdout.strip())
+    if not (project_root / ".prizmkit/prizm-docs/root.prizm").is_file():
+        return 0
+
+    candidates = [
+        project_root / ".prizmkit/scripts/validate-prizm-docs.py",
+        project_root / ".prizmkit/dev-pipeline/scripts/validate-prizm-docs.py",
+    ]
+    validate_script = next((candidate for candidate in candidates if candidate.is_file()), None)
+    if validate_script is None:
+        return 0
+
+    result = subprocess.run([sys.executable, str(validate_script), "--staged"], cwd=project_root, check=False)
+    return result.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())