prizmkit 1.1.110 → 1.1.111

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.110",
-  "bundledAt": "2026-07-08T05:42:13.015Z",
-  "bundledFrom": "84797b8"
+  "frameworkVersion": "1.1.111",
+  "bundledAt": "2026-07-08T07:06:52.766Z",
+  "bundledFrom": "1db214b"
 }

package/bundled/agents/prizm-dev-team-reviewer.md

@@ -25,6 +25,8 @@ You are the team's "senior engineer doing code review" — you diagnose problems
 2. If no `context-snapshot.md`: read `spec.md`, `plan.md` from the artifact directory, then `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs
 3. Identify changed files from `## Implementation Log` or completed tasks in plan.md
 
+**Worktree constraint**: You are spawned with default/no worktree isolation by the orchestrator. You review the active checkout's changes — the orchestrator provides workspace context (git status, diff summary, new-file paths). Do NOT request or create `.claude/worktrees/...` tool worktrees. Do NOT re-discover or re-index the whole repository; use the orchestrator-provided context as your review scope and request only targeted file reads.
+
 **File Reading Rule**: Read ONLY files listed in the Implementation Log for diagnosis — do not explore unrelated files. Exception: during Fix Strategy Formulation, you MAY read additional files to trace impact (callers, dependents, shared patterns).
 
 ### Review Workflow
@@ -74,6 +76,8 @@ When Dev has applied fixes and returns for re-review:
 - Do not modify source files to fix issues — produce Fix Instructions for Dev instead
 - **Do NOT run test suites** — the Orchestrator handles testing. You review code, not execute tests.
 - Do NOT re-read source files already listed in context-snapshot.md Section 4 File Manifest unless you need a specific code detail for a finding
+- **Do NOT request or create worktrees** (`.claude/worktrees/...` or similar) — you review the active checkout's changes using the orchestrator-provided workspace context
+- **Do NOT re-discover or broadly re-index the repository** — the orchestrator has already captured the diff scope; request only targeted file reads for lines you need
 
 ### Behavioral Rules
 

package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py

@@ -190,9 +190,42 @@ def detect_test_commands(project_root):
     """
     test_commands = []
 
-    # Check for npm/package.json
-    if os.path.exists(os.path.join(project_root, "package.json")):
-        test_commands.append("npm test")
+    # Check for npm/package.json — use content-aware detection
+    pkg_json_path = os.path.join(project_root, "package.json")
+    if os.path.exists(pkg_json_path):
+        try:
+            with open(pkg_json_path, "r", encoding="utf-8") as f:
+                pkg_data = json.load(f)
+            scripts = pkg_data.get("scripts", {}) if isinstance(pkg_data, dict) else {}
+
+            # Detect package manager from lockfiles
+            if os.path.exists(os.path.join(project_root, "pnpm-lock.yaml")):
+                pm_cmd = "pnpm"
+            elif os.path.exists(os.path.join(project_root, "yarn.lock")):
+                pm_cmd = "yarn"
+            else:
+                pm_cmd = "npm"
+
+            # Find best test script: prefer "test", then "test:unit",
+            # then first script matching test-related patterns
+            if "test" in scripts:
+                test_commands.append("{} test".format(pm_cmd))
+            elif "test:unit" in scripts:
+                test_commands.append("{} run test:unit".format(pm_cmd))
+            else:
+                # Search for any test-like script name
+                test_like = None
+                for script_name in sorted(scripts.keys()):
+                    if "test" in script_name.lower():
+                        test_like = script_name
+                        break
+                if test_like:
+                    test_commands.append(
+                        "{} run {}".format(pm_cmd, test_like)
+                    )
+        except Exception:
+            # Corrupt/unreadable package.json → skip JS detection
+            pass
 
     # Check for Go
     if os.path.exists(os.path.join(project_root, "go.mod")):

package/bundled/dev-pipeline/templates/sections/checkpoint-system.md

@@ -8,7 +8,7 @@ A checkpoint file tracks your progress through this workflow:
 
 Use this helper to update checkpoint status. Do not hand-edit `workflow-checkpoint.json` directly.
 
-```bash
+```text
 {{CHECKPOINT_PYTHON_CMD}} \
   --checkpoint-path {{CHECKPOINT_PATH}} \
   --step <step-id-or-skill-name> \

package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py

@@ -10,6 +10,7 @@ from pathlib import Path
 from generate_bootstrap_prompt import (
     ACTIVE_AGENT_PROMPTS,
     compute_feature_slug,
+    detect_test_commands,
     find_feature,
     format_acceptance_criteria,
     format_ac_checklist,
@@ -1214,6 +1215,19 @@ class TestHeadlessPromptCleanupF033:
                 assert ".prizmkit-test-started" in prompt
                 assert "{{RUNTIME_HELPER_CMD}}" not in prompt
                 assert "prizmkit-runtime-helper.py" in prompt
+            # Anti-Bash guardrails for bugfix/refactor branches (F-039)
+            if "Bug ID" in prompt:
+                assert "{{RUNTIME_HELPER_CMD}}" not in prompt
+                assert "prizmkit-runtime-helper.py" in prompt
+                assert "2>/dev/null" not in prompt
+                assert "lsof -ti" not in prompt
+                assert "which " not in prompt  # no which-command shell glue
+            if "Refactor ID" in prompt:
+                assert "{{RUNTIME_HELPER_CMD}}" not in prompt
+                assert "prizmkit-runtime-helper.py" in prompt
+                assert "2>/dev/null" not in prompt
+                assert "lsof -ti" not in prompt
+                assert "which " not in prompt  # no which-command shell glue
             assert "python3 {{INIT_SCRIPT_PATH}}" not in prompt
 
     def test_legacy_feature_templates_are_clean_when_rendered(self, tmp_path):
@@ -1436,3 +1450,94 @@ class TestFeatureBootstrapShellExtraction:
         assert "text search . --pattern \"123-prompt-cleanup\" --json" in tier3
         assert "text count .prizmkit/specs/123-prompt-cleanup/plan.md --pattern \"- [ ]\"" in tier3
         assert "Check if feature already committed by inspecting recent git history" in tier3
+
+
+# ---------------------------------------------------------------------------
+# detect_test_commands
+# ---------------------------------------------------------------------------
+
+import json as _json
+
+class TestDetectTestCommands:
+    def test_no_package_json_returns_empty(self, tmp_path):
+        """When no package.json exists, no npm test emitted."""
+        result = detect_test_commands(str(tmp_path))
+        assert "npm test" not in result
+        assert "pnpm test" not in result
+        assert "yarn test" not in result
+
+    def test_package_json_no_test_script(self, tmp_path):
+        """package.json exists but has no test script → no npm test emitted."""
+        pkg = tmp_path / "package.json"
+        pkg.write_text(_json.dumps({"name": "test", "scripts": {"start": "node index.js"}}), encoding="utf-8")
+        result = detect_test_commands(str(tmp_path))
+        # Bug: current code returns "npm test" even with no test script
+        assert "npm test" not in result, (
+            "Should NOT emit npm test when package.json has no test script"
+        )
+
+    def test_package_json_with_test_script(self, tmp_path):
+        """package.json with scripts.test → emits npm test."""
+        pkg = tmp_path / "package.json"
+        pkg.write_text(_json.dumps({"name": "test", "scripts": {"test": "vitest run"}}), encoding="utf-8")
+        result = detect_test_commands(str(tmp_path))
+        # Current code returns "npm test" (hardcoded), but at minimum it should
+        # still return something test-like. After fix, it becomes "npm test"
+        assert "npm test" in result, (
+            "Should emit npm test when package.json has test script"
+        )
+
+    def test_package_json_non_test_scripts_only(self, tmp_path):
+        """package.json exists but scripts only has non-test entries."""
+        pkg = tmp_path / "package.json"
+        pkg.write_text(_json.dumps({"name": "test", "scripts": {"build": "tsc", "start": "node dist/index.js"}}), encoding="utf-8")
+        result = detect_test_commands(str(tmp_path))
+        assert "npm test" not in result, (
+            "Should NOT emit npm test when no test-related scripts exist"
+        )
+
+    def test_pnpm_detected_from_lockfile(self, tmp_path):
+        """pnpm-lock.yaml → emits pnpm test when test script exists."""
+        pkg = tmp_path / "package.json"
+        pkg.write_text(_json.dumps({"name": "test", "scripts": {"test": "vitest"}}), encoding="utf-8")
+        (tmp_path / "pnpm-lock.yaml").write_text("", encoding="utf-8")
+        result = detect_test_commands(str(tmp_path))
+        assert "pnpm test" in result
+
+    def test_yarn_detected_from_lockfile(self, tmp_path):
+        """yarn.lock → emits yarn test when test script exists."""
+        pkg = tmp_path / "package.json"
+        pkg.write_text(_json.dumps({"name": "test", "scripts": {"test": "jest"}}), encoding="utf-8")
+        (tmp_path / "yarn.lock").write_text("", encoding="utf-8")
+        result = detect_test_commands(str(tmp_path))
+        assert "yarn test" in result
+
+    def test_corrupt_package_json_graceful_fallback(self, tmp_path):
+        """Corrupt/unparseable package.json → skip JS detection gracefully."""
+        (tmp_path / "package.json").write_text("not valid json {{{", encoding="utf-8")
+        result = detect_test_commands(str(tmp_path))
+        # Should not crash, should not emit npm test
+        assert "npm test" not in result
+
+    def test_non_js_detections_preserved(self, tmp_path):
+        """Go, Rust, Python, Makefile detections unchanged."""
+        (tmp_path / "go.mod").write_text("", encoding="utf-8")
+        (tmp_path / "Cargo.toml").write_text("", encoding="utf-8")
+        (tmp_path / "setup.py").write_text("", encoding="utf-8")
+        makefile = tmp_path / "Makefile"
+        makefile.write_text("test:\n\tpytest\n", encoding="utf-8")
+        result = detect_test_commands(str(tmp_path))
+        assert "go test ./..." in result
+        assert "cargo test" in result
+        assert "pytest" in result
+        assert "make test" in result
+
+    def test_package_json_test_unit_script_only(self, tmp_path):
+        """package.json with test:unit but no test → fallback to available test script."""
+        pkg = tmp_path / "package.json"
+        pkg.write_text(_json.dumps({"name": "test", "scripts": {"test:unit": "vitest run"}}), encoding="utf-8")
+        (tmp_path / "package-lock.json").write_text("", encoding="utf-8")
+        result = detect_test_commands(str(tmp_path))
+        # Should detect test:unit as a viable test script
+        assert "npm run test:unit" in result
+

package/bundled/dev-pipeline/tests/test_generate_bugfix_prompt.py

@@ -2,6 +2,8 @@
 
 from argparse import Namespace
 from pathlib import Path
+import json
+import os
 
 from generate_bugfix_prompt import (
     build_replacements,
@@ -303,3 +305,123 @@ def test_template_source_is_clean_for_headless_prompt_contract():
     content = Path("dev-pipeline/templates/bugfix-bootstrap-prompt.md").read_text(encoding="utf-8")
     for forbidden in HEADLESS_FORBIDDEN_PROMPT_STRINGS:
         assert forbidden not in content
+
+
+# ---------------------------------------------------------------------------
+# Anti-Bash regression guardrails (F-039)
+# Note: grep -n, sed -n, grep -q, wc -l excluded — referenced in bugfix context
+# budget rules as AI tool hints, not as operational shell snippets.
+# | sed  (trailing space) only matches pipe-to-sed operational patterns.
+# ---------------------------------------------------------------------------
+
+RETIRED_EXTRACTED_SNIPPETS_BUGFIX = [
+    "find . -maxdepth",
+    "| sed ",
+    r"grep -c '^\- \[ \]'",
+    "2>/dev/null",
+    "/dev/null",
+    "$DEV_PORT",
+    "$!",
+    "$HOME",
+    "if [ ",
+    "which playwright-cli",
+    "which opencli",
+    "lsof -ti",
+    "xargs",
+    " kill -",
+    "kill -",
+    "|| echo",
+    "mkdir -p",
+    "touch .prizmkit",
+]
+
+
+def _render_bugfix_prompt(tmp_path, platform="claude"):
+    """Render a complete bugfix prompt through the generator."""
+    from generate_bugfix_prompt import main as bugfix_main
+
+    project = tmp_path / "bugfix-anti-bash"
+    project.mkdir(parents=True)
+    (project / ".prizmkit").mkdir(exist_ok=True)
+    (project / ".prizmkit" / "config.json").write_text(
+        json.dumps({"platform": platform, "ai_cli": platform}), encoding="utf-8"
+    )
+    _ensure_agent_files(project)
+    bug_list = project / ".prizmkit" / "plans" / "bug-fix-list.json"
+    bug_list.parent.mkdir(parents=True)
+    bug_list.write_text(json.dumps({
+        "bugs": [{"id": "B-001", "title": "Broken", "description": "Fix it",
+                   "acceptance_criteria": ["Works"]}],
+        "global_context": {"language": "Python"},
+    }), encoding="utf-8")
+    output = project / "bugfix-prompt.md"
+    old_argv = os.sys.argv
+    old_platform = os.environ.get("PRIZMKIT_PLATFORM")
+    try:
+        os.environ.pop("PRIZMKIT_PLATFORM", None)
+        os.sys.argv = [
+            "generate-bugfix-prompt.py",
+            "--bug-list", str(bug_list),
+            "--bug-id", "B-001",
+            "--session-id", "session-1",
+            "--run-id", "run-1",
+            "--retry-count", "0",
+            "--resume-phase", "null",
+            "--state-dir", str(project / ".prizmkit" / "state" / "bugfix"),
+            "--project-root", str(project),
+            "--output", str(output),
+        ]
+        try:
+            bugfix_main()
+        except SystemExit as exc:
+            if exc.code not in (0, None):
+                raise
+    finally:
+        os.sys.argv = old_argv
+        if old_platform is None:
+            os.environ.pop("PRIZMKIT_PLATFORM", None)
+        else:
+            os.environ["PRIZMKIT_PLATFORM"] = old_platform
+    return output.read_text(encoding="utf-8")
+
+
+def _ensure_agent_files(project, platforms=None):
+    """Create minimal agent files so platform resolution succeeds."""
+    if platforms is None:
+        platforms = ("claude", "codex")
+    for plat in platforms:
+        platform_dir = ".codex" if plat == "codex" else ".claude"
+        suffix = ".toml" if plat == "codex" else ".md"
+        agents_dir = project / platform_dir / "agents"
+        agents_dir.mkdir(parents=True, exist_ok=True)
+        for name in ("dev", "reviewer", "critic"):
+            (agents_dir / f"prizm-dev-team-{name}{suffix}").write_text("agent\n", encoding="utf-8")
+
+
+class TestBugfixBootstrapShellExtraction:
+    """Regression guardrails: bugfix rendered prompts and source use helper, not shell."""
+
+    def test_rendered_bugfix_prompt_uses_runtime_helper_not_extracted_bash(self, tmp_path):
+        prompt = _render_bugfix_prompt(tmp_path)
+        for snippet in RETIRED_EXTRACTED_SNIPPETS_BUGFIX:
+            assert snippet not in prompt, f"Retired shell snippet found in bugfix prompt: {snippet}"
+        assert "{{RUNTIME_HELPER_CMD}}" not in prompt
+        assert "python" in prompt.lower()
+        assert ".prizmkit/dev-pipeline/scripts/prizmkit-runtime-helper.py" in prompt
+        assert "artifact ensure-dir .prizmkit/bugfix/B-001" in prompt
+        assert "text contains .prizmkit/bugfix/B-001/review-report.md --pattern \"## Verdict\"" in prompt
+
+    def test_bugfix_template_source_is_clean_of_helper_covered_snippets(self):
+        content = Path("dev-pipeline/templates/bugfix-bootstrap-prompt.md").read_text(encoding="utf-8")
+        for snippet in RETIRED_EXTRACTED_SNIPPETS_BUGFIX:
+            assert snippet not in content, f"Shell snippet in bugfix template: {snippet}"
+
+    def test_continuation_source_is_clean_of_helper_covered_snippets(self):
+        content = Path("dev-pipeline/scripts/continuation.py").read_text(encoding="utf-8")
+        for snippet in RETIRED_EXTRACTED_SNIPPETS_BUGFIX:
+            assert snippet not in content, f"Shell snippet in continuation.py: {snippet}"
+
+    def test_bugfix_generator_source_is_clean_of_helper_covered_snippets(self):
+        content = Path("dev-pipeline/scripts/generate-bugfix-prompt.py").read_text(encoding="utf-8")
+        for snippet in RETIRED_EXTRACTED_SNIPPETS_BUGFIX:
+            assert snippet not in content, f"Shell snippet in generate-bugfix-prompt.py: {snippet}"

package/bundled/dev-pipeline/tests/test_generate_refactor_prompt.py

@@ -2,6 +2,7 @@
 
 from argparse import Namespace
 from pathlib import Path
+import os
 
 from continuation import append_continuation_handoff
 from generate_refactor_prompt import (
@@ -194,3 +195,126 @@ def test_template_source_is_clean_for_headless_prompt_contract():
     content = Path("dev-pipeline/templates/refactor-bootstrap-prompt.md").read_text(encoding="utf-8")
     for forbidden in HEADLESS_FORBIDDEN_PROMPT_STRINGS:
         assert forbidden not in content
+
+
+# ---------------------------------------------------------------------------
+# Anti-Bash regression guardrails (F-039)
+# Note: grep -n, sed -n, grep -q, wc -l excluded — may appear in cross-pipeline
+# context budget rules as AI tool hints, not as operational shell snippets.
+# | sed  (trailing space) only matches pipe-to-sed operational patterns.
+# ---------------------------------------------------------------------------
+
+RETIRED_EXTRACTED_SNIPPETS_REFACTOR = [
+    "find . -maxdepth",
+    "| sed ",
+    r"grep -c '^\- \[ \]'",
+    "2>/dev/null",
+    "/dev/null",
+    "$DEV_PORT",
+    "$!",
+    "$HOME",
+    "if [ ",
+    "which playwright-cli",
+    "which opencli",
+    "lsof -ti",
+    "xargs",
+    " kill -",
+    "kill -",
+    "|| echo",
+    "mkdir -p",
+    "touch .prizmkit",
+]
+
+
+def _render_refactor_prompt_full(tmp_path, platform="claude"):
+    """Render a complete refactor prompt through the generator."""
+    import json, os
+    from generate_refactor_prompt import main as refactor_main
+
+    project = tmp_path / "refactor-anti-bash"
+    project.mkdir(parents=True)
+    (project / ".prizmkit").mkdir(exist_ok=True)
+    (project / ".prizmkit" / "config.json").write_text(
+        json.dumps({"platform": platform, "ai_cli": platform}), encoding="utf-8"
+    )
+    # Ensure agent files
+    for plat in ("claude", "codex"):
+        platform_dir = ".codex" if plat == "codex" else ".claude"
+        suffix = ".toml" if plat == "codex" else ".md"
+        agents_dir = project / platform_dir / "agents"
+        agents_dir.mkdir(parents=True, exist_ok=True)
+        for name in ("dev", "reviewer", "critic"):
+            (agents_dir / f"prizm-dev-team-{name}{suffix}").write_text("agent\n", encoding="utf-8")
+
+    refactor_list = project / ".prizmkit" / "plans" / "refactor-list.json"
+    refactor_list.parent.mkdir(parents=True)
+    refactor_list.write_text(json.dumps({
+        "refactors": [{
+            "id": "R-001", "title": "Restructure", "description": "Preserve behavior",
+            "acceptance_criteria": ["Behavior preserved"],
+            "scope": {"files": ["src/a.py"], "modules": ["src"]},
+        }],
+        "global_context": {"language": "Python"},
+    }), encoding="utf-8")
+    output = project / "refactor-prompt.md"
+    old_argv = os.sys.argv
+    old_platform = os.environ.get("PRIZMKIT_PLATFORM")
+    try:
+        os.environ.pop("PRIZMKIT_PLATFORM", None)
+        os.sys.argv = [
+            "generate-refactor-prompt.py",
+            "--refactor-list", str(refactor_list),
+            "--refactor-id", "R-001",
+            "--session-id", "session-1",
+            "--run-id", "run-1",
+            "--retry-count", "0",
+            "--resume-phase", "null",
+            "--state-dir", str(project / ".prizmkit" / "state" / "refactor"),
+            "--output", str(output),
+        ]
+        old_cwd = os.getcwd()
+        os.chdir(project)
+        try:
+            try:
+                refactor_main()
+            except SystemExit as exc:
+                if exc.code not in (0, None):
+                    raise
+        finally:
+            os.chdir(old_cwd)
+    finally:
+        os.sys.argv = old_argv
+        if old_platform is None:
+            os.environ.pop("PRIZMKIT_PLATFORM", None)
+        else:
+            os.environ["PRIZMKIT_PLATFORM"] = old_platform
+    return output.read_text(encoding="utf-8")
+
+
+class TestRefactorBootstrapShellExtraction:
+    """Regression guardrails: refactor rendered prompts and source use helper, not shell."""
+
+    def test_rendered_refactor_prompt_uses_runtime_helper_not_extracted_bash(self, tmp_path):
+        prompt = _render_refactor_prompt_full(tmp_path)
+        for snippet in RETIRED_EXTRACTED_SNIPPETS_REFACTOR:
+            assert snippet not in prompt, f"Retired shell snippet found in refactor prompt: {snippet}"
+        assert "{{RUNTIME_HELPER_CMD}}" not in prompt
+        assert "python" in prompt.lower()
+        assert ".prizmkit/dev-pipeline/scripts/prizmkit-runtime-helper.py" in prompt
+        assert "artifact ensure-dir .prizmkit/refactor/R-001" in prompt
+        assert "text contains .prizmkit/refactor/R-001/review-report.md --pattern \"## Verdict\"" in prompt
+
+    def test_refactor_template_source_is_clean_of_helper_covered_snippets(self):
+        content = Path("dev-pipeline/templates/refactor-bootstrap-prompt.md").read_text(encoding="utf-8")
+        for snippet in RETIRED_EXTRACTED_SNIPPETS_REFACTOR:
+            assert snippet not in content, f"Shell snippet in refactor template: {snippet}"
+
+    def test_continuation_source_is_clean_of_helper_covered_snippets(self):
+        content = Path("dev-pipeline/scripts/continuation.py").read_text(encoding="utf-8")
+        for snippet in RETIRED_EXTRACTED_SNIPPETS_REFACTOR:
+            assert snippet not in content, f"Shell snippet in continuation.py: {snippet}"
+
+    def test_refactor_generator_source_is_clean_of_helper_covered_snippets(self):
+        content = Path("dev-pipeline/scripts/generate-refactor-prompt.py").read_text(encoding="utf-8")
+        for snippet in RETIRED_EXTRACTED_SNIPPETS_REFACTOR:
+            assert snippet not in content, f"Shell snippet in generate-refactor-prompt.py: {snippet}"

package/bundled/dev-pipeline/tests/test_unified_cli.py

@@ -804,7 +804,7 @@ def test_headless_subagent_prompt_guidance_keeps_no_worktree_boundary_visible():
     for path in guidance_files:
         text = path.read_text(encoding="utf-8")
         assert "default/no worktree" in text, path
-        assert "do not request worktree isolation" in text.lower(), path
+        assert "do not request or create" in text.lower() or "do not request worktree isolation" in text.lower(), path
         assert ".claude/worktrees/..." in text, path
         assert ".prizmkit/state/worktrees/..." in text, path
         assert "USE_WORKTREE" in text, path

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.110",
+  "version": "1.1.111",
   "skills": {
     "prizmkit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

package/bundled/skills/prizmkit/SKILL.md

@@ -67,15 +67,15 @@ All three follow the same per-task flow. Detailed documentation policies (when t
 
 | Skill | Purpose | Trigger Phrases |
 |-------|---------|-----------------|
-| `/prizmkit-plan` | Specify + plan: natural language → spec.md → plan.md + tasks | "specify", "plan", "new feature", "I want to add...", "architect", "break it down" |
-| `/prizmkit-implement` | Execute plan.md tasks, write code (TDD) | "implement", "build", "code it", "start coding" |
-| `/prizmkit-code-review` | Diagnose issues + produce Fix Instructions | "review", "check code", "is it ready to commit" |
-| `/prizmkit-retrospective` | Sync .prizmkit/prizm-docs/ with code changes | "retrospective", "retro", "sync docs", "wrap up" |
-| `/prizmkit-committer` | Safe git commit with Conventional Commits | "commit", "submit", "finish", "ship it" |
-| `/prizmkit-test` | Generate + run tests, analyze coverage gaps, unified quality report | "test", "run tests", "check quality", "verify code", "add tests" |
-| `/prizmkit-deploy` | Universal deployment gateway: SSH automation, cloud/Docker guided setup, status/logs/rollback | "deploy", "ship it", "go live", "rollback", "deploy status" |
-| `/prizmkit-init` | Project bootstrap + .prizmkit/prizm-docs/ setup | "init", "initialize", "take over this project" |
-| `/prizmkit-prizm-docs` | Doc management (init/status/rebuild/validate) | "check docs", "rebuild docs", "validate docs" |
+| `/prizmkit-plan` | Specify and plan: turns natural language into spec.md + plan.md with architecture and executable tasks. Use as the **first implementation step** in the lifecycle, before /prizmkit-implement. | "specify", "plan", "new feature", "I want to add...", "architect", "break it down" |
+| `/prizmkit-implement` | Execute plan.md tasks with **TDD approach**, respecting task ordering and dependencies. Use after /prizmkit-plan as the **implementation step** of the lifecycle. | "implement", "build", "code it", "start coding" |
+| `/prizmkit-code-review` | **Iterative review-fix loop** against spec and plan (max 3 rounds until PASS). Spawns a reviewer agent; the main orchestrator applies accepted fixes directly. Use after /prizmkit-implement as the **quality gate**. | "review", "check code", "code review", "is it ready to commit" |
+| `/prizmkit-retrospective` | Incremental .prizmkit/prizm-docs/ maintainer: (1) **structural sync** of KEY_FILES/INTERFACES/DEPENDENCIES, (2) inject **TRAPS/RULES/DECISIONS**. Run after code review and **before committing**. | "retrospective", "retro", "update docs", "sync docs", "wrap up" |
+| `/prizmkit-committer` | **Pure git commit** with safety checks: stages files, generates Conventional Commits message, commits. Does NOT modify docs — run /prizmkit-retrospective first. Use as the **final lifecycle step**. | "commit", "submit", "finish", "ship it" |
+| `/prizmkit-test` | **Full-stack test orchestration**: detects architecture, analyzes coverage gaps, generates missing unit/integration/E2E tests with a boundary coverage matrix, and outputs a unified report. Use after development and **before deploy** for quality verification. | "test", "run tests", "check quality", "verify code", "generate tests", "add tests" |
+| `/prizmkit-deploy` | **Universal deployment gateway**: discovers project type/target, automates SSH Linux PM2+Nginx+blue-green deploys, and manages operations — status, logs, restart, rollback, health checks. | "deploy", "ship it", "go live", "rollback", "deploy status" |
+| `/prizmkit-init` | **Project bootstrap**: scans codebase, generates .prizmkit/prizm-docs/ and project brief, detects tech stack. Use as the **first lifecycle step for new projects**, or after `npx prizmkit install`. | "init", "initialize", "take over this project", "bootstrap" |
+| `/prizmkit-prizm-docs` | **Doc system spec and management**: defines the 3-level .prizmkit/prizm-docs/ hierarchy (L0/L1/L2), format rules, size limits, and loading protocol. Use for doc init/status/rebuild/validate/migrate. For **incremental code-driven updates**, use /prizmkit-retrospective instead. | "check docs", "rebuild docs", "validate docs", "prizm docs" |
 
 **Reading guide**:
 - Need code structure/modules/interfaces/traps/decisions? → `.prizmkit/prizm-docs/`

package/bundled/skills/prizmkit-code-review/SKILL.md

@@ -37,7 +37,12 @@ The loop repeats until the Reviewer finds no issues or the max round limit is re
    - If `context-snapshot.md` contains `## PrizmKit Test Gate`, read that summary too.
    - If this is a feature artifact under `.prizmkit/specs/` and no test report pointer or summary exists, pass `No scoped /prizmkit-test report found (expected for pre-test review)` into the Reviewer context as informational scope context only. Do not ask the Reviewer to report it as a missing gate unless the calling workflow explicitly requires a prior test report.
 4. **Read dev rules** (if configured): If `.prizmkit/prizm-docs/root.prizm` exists, read it and check for a `RULES:` line. If present, read all referenced `.prizmkit/rules/<layer>-rules.md` files. If `root.prizm` or a referenced rules file does not exist, continue with "No custom dev rules configured — use general best practices."
-5. **Capture workspace diff**: run `git diff` (unstaged) + `git diff --cached` (staged) + `git status` to understand the full scope of changes. For new files in git status, note their paths for the Reviewer to read.
+5. **Capture workspace context from the active checkout** (do NOT open a separate worktree or clone):
+   - Run `git status` to list modified, staged, untracked, and deleted files.
+   - Run `git diff` for unstaged changes and `git diff --cached` for staged changes.
+   - For new (untracked) files and renamed files in `git status`, note their full paths so the Reviewer can request targeted reads.
+   - Capture the current project context: read `.prizmkit/prizm-docs/root.prizm` for relevant RULES, and the artifact's `plan.md` for architecture decisions — this is the reviewer's context baseline.
+   - The workspace context is the **primary review scope**. The Reviewer must review this context and request only targeted file reads for lines it needs — it must not rediscover or re-index the whole repository.
    - If no changes are detected, skip Phase 1 and proceed to Phase 2 with verdict PASS, rounds 0, and an empty findings list. Always write `review-report.md`; downstream pipeline steps use it as the review gate.
 
 ## Phase 1: Review-Fix Loop
@@ -115,7 +120,24 @@ When Python is unavailable, apply these rules exactly — they match the script'
 
 ### Step 1: Spawn Reviewer Agent
 
-Include the dev rules read in Phase 0 step 4 and the workspace diff/status captured in Phase 0 step 5 in the Reviewer prompt. In Claude Code, spawn the dedicated PrizmKit Reviewer with `subagent_type: prizm-dev-team-reviewer`, `run_in_background=false`, and default/no worktree isolation. Do not request worktree isolation; this prevents AI tool-created `.claude/worktrees/...` subagent worktrees. PrizmKit pipeline-managed linked git worktrees under `.prizmkit/state/worktrees/...` are separate and controlled by `USE_WORKTREE`. Do not route the PrizmKit reviewer flow through `Explore` or a generic code-explorer agent. If the current platform has no dedicated Reviewer agent, perform the review pass in the Main Agent without editing files during that pass. Read `${SKILL_DIR}/references/reviewer-agent-prompt.md` for the full prompt template — fill `{goals}`, `{plan decisions}`, `{scoped test report}`, `{workspace context}`, `{dev rules}`, `{round N}`, and `{round_context}` before spawning.
+Include the dev rules read in Phase 0 step 4 and the workspace context captured in Phase 0 step 5 in the Reviewer prompt.
+
+**Reviewer Agent Invocation Contract (MANDATORY):**
+
+| Parameter | Value | Rationale |
+|-----------|-------|-----------|
+| `subagent_type` | `prizm-dev-team-reviewer` | Dedicated PrizmKit reviewer agent |
+| `run_in_background` | `false` | Orchestrator waits for review results |
+| `isolation` | **omit or `"none"`** — default/no worktree isolation | Reviewer must review the active checkout's changes, not a separate repository copy |
+| worktree tool access | **Forbidden** — do NOT pass `EnterWorktree` tool; do NOT request or create `.claude/worktrees/...` subagent worktrees | Tool-created worktrees defeat checkout-scoped review |
+
+PrizmKit pipeline-managed linked git worktrees under `.prizmkit/state/worktrees/...` are separate infrastructure controlled by `USE_WORKTREE` and are not relevant to the Reviewer invocation.
+
+Do not route the PrizmKit reviewer flow through `Explore` or a generic code-explorer agent.
+
+**Fallback clause**: If the current platform or Agent-tool invocation path cannot guarantee a no-worktree Reviewer Agent (e.g., the platform does not support `prizm-dev-team-reviewer` or always creates worktree isolation for subagents), perform the review pass **in the Main Agent as a read-only pass** in the active checkout — do NOT edit files during that pass. Use the same review dimensions and output format as the Reviewer prompt template, and write `review-report.md` directly.
+
+Read `${SKILL_DIR}/references/reviewer-agent-prompt.md` for the full prompt template — fill `{goals}`, `{plan decisions}`, `{scoped test report}`, `{workspace context}`, `{dev rules}`, `{round N}`, and `{round_context}` before spawning.
 
 Round context varies by round:
 - Round 1: "This is the first review. Examine all changes comprehensively."

package/bundled/skills/prizmkit-code-review/references/reviewer-agent-prompt.md

@@ -15,7 +15,7 @@ You are the dedicated PrizmKit Reviewer agent (`prizm-dev-team-reviewer`). Revie
 {summary from artifact_dir/test-report-path.txt and test-report.md, including Scope, Generated / Updated Tests, In-Scope Failures, Baseline Failures, Out of Scope Gaps, Boundary Matrix / Boundary Completion Gate if present, and Verdict. If no scoped report exists for a feature artifact, write "No scoped /prizmkit-test report found (expected for pre-test review)." Treat that absence as informational unless the calling workflow explicitly requires a prior test report.}
 
 ## Workspace Context
-{git status, unstaged diff summary, staged diff summary, and new-file paths captured by the Main Agent in Phase 0. Use this context as the review scope; request targeted file context only when needed instead of re-running broad discovery.}
+{git status, unstaged diff summary, staged diff summary, and new-file paths captured by the Main Agent in Phase 0 from the active checkout. This is your primary review scope — use this context to understand what changed. Request targeted file reads only when you need specific line-level detail for a finding, not to re-discover or re-index the repository. Do not read files that are not in the workspace context unless you need them to verify impact (callers, dependents, shared patterns). Do not switch to a separate worktree or repository copy — the Main Agent has provided everything needed to understand the change set.}
 
 ## Dev Rules (per-layer conventions)
 {rules from .prizmkit/rules/<layer>-rules.md, or "No custom dev rules configured — use general best practices."}
@@ -28,6 +28,7 @@ Use the orchestrator-provided workspace context as the source of truth for chang
 - For new files listed in workspace status, read their full content.
 - For modified files, read enough surrounding context to understand the change.
 - Do not edit files, stage changes, run test suites, or spawn other agents.
+- Do not request or create worktrees — you are reviewing the active checkout's changes. The orchestrator has already captured the full diff and status context; re-discovering the whole repository is wasteful and unnecessary.
 
 ## Review Dimensions
 Evaluate the changes across these dimensions (focus on what's relevant):

package/package.json

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