prizmkit 1.1.106 → 1.1.108

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

@@ -19,12 +19,11 @@ import os
 import re
 import sys
 
-from utils import enrich_global_context, load_json_file, read_platform_conventions, setup_logging
+from utils import enrich_global_context, load_json_file, read_checkpoint_system_section, resolve_prompt_platform, setup_logging
 from continuation import add_continuation_args, append_continuation_handoff, is_continuation
 
 
 DEFAULT_MAX_RETRIES = 3
-DEFAULT_MAX_LOG_SIZE = 2097152
 
 LOGGER = setup_logging("generate-bugfix-prompt")
 
@@ -66,27 +65,6 @@ def read_text_file(path):
 
 
 
-def _format_bytes(n):
-    """Format a byte count to a human-readable string."""
-    if n >= 1048576:
-        return "{}MB".format(n // 1048576)
-    elif n >= 1024:
-        return "{}KB".format(n // 1024)
-    return "{}B".format(n)
-
-
-def _parse_non_negative_int_env(name, default):
-    """Parse a non-negative integer environment variable."""
-    value = os.environ.get(name, str(default))
-    try:
-        parsed = int(value)
-    except ValueError:
-        raise ValueError("{} must be a non-negative integer".format(name))
-    if parsed < 0:
-        raise ValueError("{} must be a non-negative integer".format(name))
-    return parsed
-
-
 def _parse_positive_int_env(name, default):
     """Parse a positive integer environment variable."""
     value = os.environ.get(name, str(default))
@@ -99,23 +77,6 @@ def _parse_positive_int_env(name, default):
     return parsed
 
 
-def load_log_size_section(script_dir):
-    """Load the optional log-size awareness prompt section."""
-    max_log_size = _parse_non_negative_int_env("MAX_LOG_SIZE", DEFAULT_MAX_LOG_SIZE)
-    if max_log_size == 0:
-        return ""
-
-    section_path = os.path.join(
-        script_dir, "..", "templates", "sections", "log-size-awareness.md",
-    )
-    if not os.path.isfile(section_path):
-        return ""
-
-    content, err = read_text_file(section_path)
-    if err:
-        return ""
-    return content
-
 def find_bug(bugs, bug_id):
     """Find and return the bug dict matching the given ID."""
     for bug in bugs:
@@ -287,17 +248,9 @@ def build_replacements(args, bug, global_context, script_dir):
     project_root = _args_project_root(args, script_dir)
 
     # Platform-aware agent/team path resolution
-    platform = os.environ.get("PRIZMKIT_PLATFORM", "")
+    platform = resolve_prompt_platform(project_root)
     home_dir = os.path.expanduser("~")
 
-    if not platform:
-        if os.path.isdir(os.path.join(project_root, ".codex", "agents")):
-            platform = "codex"
-        elif os.path.isdir(os.path.join(project_root, ".claude", "agents")):
-            platform = "claude"
-        else:
-            platform = "codebuddy"
-
     if platform == "claude":
         agents_dir = os.path.join(project_root, ".claude", "agents")
         team_config_path = os.path.join(project_root, ".claude", "team-info.json")
@@ -373,12 +326,7 @@ def build_replacements(args, bug, global_context, script_dir):
             browser_enabled = True
             browser_verify_steps = "   # (reproduce bug and verify fix)"
 
-    max_log_size = _parse_non_negative_int_env("MAX_LOG_SIZE", DEFAULT_MAX_LOG_SIZE)
-
     replacements = {
-        "{{LOG_SIZE_AWARENESS}}": load_log_size_section(script_dir),
-        "{{MAX_LOG_SIZE}}": str(max_log_size),
-        "{{MAX_LOG_SIZE_HUMAN}}": _format_bytes(max_log_size),
         "{{SESSION_LOG_PATH}}": os.path.join(
             ".prizmkit", "state", "bugfix", args.bug_id,
             "sessions", args.session_id, "logs", "session.log",
@@ -398,12 +346,15 @@ def build_replacements(args, bug, global_context, script_dir):
         ),
         "{{ENVIRONMENT}}": format_environment(bug.get("environment")),
         "{{GLOBAL_CONTEXT}}": format_global_context(global_context, project_root),
-        "{{PLATFORM_CONVENTIONS}}": read_platform_conventions(project_root),
         "{{TEAM_CONFIG_PATH}}": team_config_path,
         "{{DEV_SUBAGENT_PATH}}": dev_subagent,
         "{{REVIEWER_SUBAGENT_PATH}}": reviewer_subagent,
         "{{SESSION_STATUS_PATH}}": session_status_path,
         "{{PROJECT_ROOT}}": project_root,
+        "{{CHECKPOINT_PATH}}": os.path.join(
+            ".prizmkit", "bugfix", args.bug_id, "workflow-checkpoint.json",
+        ),
+        "{{CHECKPOINT_SYSTEM}}": read_checkpoint_system_section(script_dir),
         "{{FIX_SCOPE}}": fix_scope,
         "{{TIMESTAMP}}": "",  # Placeholder, agent fills in the timestamp
         "{{BROWSER_ENABLED}}": "true" if browser_enabled else "false",
@@ -659,15 +610,6 @@ def main():
 
     # Build replacements
     replacements = build_replacements(args, bug, global_context, script_dir)
-    if is_continuation(args):
-        replacements["{{LOG_SIZE_AWARENESS}}"] = ""
-
-    # Add checkpoint path to replacements
-    checkpoint_rel = os.path.join(
-        ".prizmkit", "bugfix", args.bug_id, "workflow-checkpoint.json",
-    )
-    replacements["{{CHECKPOINT_PATH}}"] = checkpoint_rel
-
     # Render the template
     rendered = render_template(template_content, replacements, bug)
 
@@ -678,6 +620,7 @@ def main():
 
     # Generate checkpoint file
     project_root = _args_project_root(args, script_dir)
+    checkpoint_rel = replacements["{{CHECKPOINT_PATH}}"]
     checkpoint_path = os.path.join(project_root, checkpoint_rel)
     checkpoint_dir = os.path.dirname(checkpoint_path)
     os.makedirs(checkpoint_dir, exist_ok=True)

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

@@ -19,12 +19,11 @@ import os
 import re
 import sys
 
-from utils import enrich_global_context, load_json_file, read_platform_conventions, setup_logging
+from utils import enrich_global_context, load_json_file, read_checkpoint_system_section, resolve_prompt_platform, setup_logging
 from continuation import add_continuation_args, append_continuation_handoff, is_continuation
 
 
 DEFAULT_MAX_RETRIES = 3
-DEFAULT_MAX_LOG_SIZE = 2097152
 
 LOGGER = setup_logging("generate-refactor-prompt")
 
@@ -135,6 +134,7 @@ def parse_args():
     parser.add_argument("--resume-phase", required=True, help='Phase to resume from, or "null" for fresh start')
     parser.add_argument("--state-dir", default=None, help="State directory (default: .prizmkit/state/refactor)")
     parser.add_argument("--output", required=True, help="Output path for the rendered prompt")
+    parser.add_argument("--project-root", default=None, help="AI-visible project root used for rendered prompt paths")
     parser.add_argument("--template", default=None, help="Custom template path. Defaults to {script_dir}/../templates/refactor-bootstrap-prompt.md")
     parser.add_argument("--mode", default=None, help="Pipeline execution mode override: lite, standard, full")
     parser.add_argument("--critic", default=None, help="Enable critic agent: true/false")
@@ -156,27 +156,6 @@ def read_text_file(path):
 
 
 
-def _format_bytes(n):
-    """Format a byte count to a human-readable string."""
-    if n >= 1048576:
-        return "{}MB".format(n // 1048576)
-    elif n >= 1024:
-        return "{}KB".format(n // 1024)
-    return "{}B".format(n)
-
-
-def _parse_non_negative_int_env(name, default):
-    """Parse a non-negative integer environment variable."""
-    value = os.environ.get(name, str(default))
-    try:
-        parsed = int(value)
-    except ValueError:
-        raise ValueError("{} must be a non-negative integer".format(name))
-    if parsed < 0:
-        raise ValueError("{} must be a non-negative integer".format(name))
-    return parsed
-
-
 def _parse_positive_int_env(name, default):
     """Parse a positive integer environment variable."""
     value = os.environ.get(name, str(default))
@@ -189,23 +168,6 @@ def _parse_positive_int_env(name, default):
     return parsed
 
 
-def load_log_size_section(script_dir):
-    """Load the optional log-size awareness prompt section."""
-    max_log_size = _parse_non_negative_int_env("MAX_LOG_SIZE", DEFAULT_MAX_LOG_SIZE)
-    if max_log_size == 0:
-        return ""
-
-    section_path = os.path.join(
-        script_dir, "..", "templates", "sections", "log-size-awareness.md",
-    )
-    if not os.path.isfile(section_path):
-        return ""
-
-    content, err = read_text_file(section_path)
-    if err:
-        return ""
-    return content
-
 def find_refactor(refactors, refactor_id):
     """Find and return the refactor dict matching the given ID."""
     for refactor in refactors:
@@ -422,22 +384,39 @@ def resolve_project_root(script_dir):
     return os.path.abspath(pipeline_parent)
 
 
+def _project_root_from_prizmkit_path(path):
+    """Infer project root from a path nested under .prizmkit/."""
+    if not path:
+        return ""
+    current = os.path.abspath(path)
+    if not os.path.isdir(current):
+        current = os.path.dirname(current)
+    while current and current != os.path.dirname(current):
+        if os.path.basename(current) == ".prizmkit":
+            return os.path.abspath(os.path.dirname(current))
+        current = os.path.dirname(current)
+    return ""
+
+
+def _args_project_root(args, script_dir):
+    """Return explicit AI-visible project root, plan-path root, or script-layout default."""
+    explicit = getattr(args, "project_root", None)
+    if explicit:
+        return os.path.abspath(explicit)
+    plan_root = _project_root_from_prizmkit_path(getattr(args, "refactor_list", ""))
+    if plan_root:
+        return plan_root
+    return resolve_project_root(script_dir)
+
+
 def build_replacements(args, refactor, refactors, global_context, script_dir):
     """Build the full dict of placeholder -> replacement value."""
-    project_root = resolve_project_root(script_dir)
+    project_root = _args_project_root(args, script_dir)
 
     # Platform-aware agent/team path resolution
-    platform = os.environ.get("PRIZMKIT_PLATFORM", "")
+    platform = resolve_prompt_platform(project_root)
     home_dir = os.path.expanduser("~")
 
-    if not platform:
-        if os.path.isdir(os.path.join(project_root, ".codex", "agents")):
-            platform = "codex"
-        elif os.path.isdir(os.path.join(project_root, ".claude", "agents")):
-            platform = "claude"
-        else:
-            platform = "codebuddy"
-
     if platform == "claude":
         agents_dir = os.path.join(project_root, ".claude", "agents")
         team_config_path = os.path.join(project_root, ".claude", "team-info.json")
@@ -454,10 +433,16 @@ def build_replacements(args, refactor, refactors, global_context, script_dir):
     dev_subagent = os.path.join(agents_dir, f"prizm-dev-team-dev{agent_ext}")
     reviewer_subagent = os.path.join(agents_dir, f"prizm-dev-team-reviewer{agent_ext}")
 
-    # Session status path
+    # Session status is controlled by the main runner state dir, even when
+    # rendered project paths are AI-visible worktree paths.
+    state_dir = (
+        os.path.abspath(args.state_dir)
+        if args.state_dir
+        else os.path.join(project_root, ".prizmkit", "state", "refactor")
+    )
     session_status_path = os.path.join(
-        project_root, ".prizmkit", "state", "refactor", args.refactor_id,
-        "sessions", args.session_id, "session-status.json"
+        state_dir, args.refactor_id, "sessions", args.session_id,
+        "session-status.json",
     )
 
     # Scope
@@ -518,12 +503,7 @@ def build_replacements(args, refactor, refactors, global_context, script_dir):
             browser_enabled = True
             browser_verify_steps = "   # (validate UI renders correctly and feature still works)"
 
-    max_log_size = _parse_non_negative_int_env("MAX_LOG_SIZE", DEFAULT_MAX_LOG_SIZE)
-
     replacements = {
-        "{{LOG_SIZE_AWARENESS}}": load_log_size_section(script_dir),
-        "{{MAX_LOG_SIZE}}": str(max_log_size),
-        "{{MAX_LOG_SIZE_HUMAN}}": _format_bytes(max_log_size),
         "{{SESSION_LOG_PATH}}": os.path.join(
             ".prizmkit", "state", "refactor", args.refactor_id,
             "sessions", args.session_id, "logs", "session.log",
@@ -557,8 +537,8 @@ def build_replacements(args, refactor, refactors, global_context, script_dir):
         "{{CHECKPOINT_PATH}}": os.path.join(
             ".prizmkit", "refactor", args.refactor_id, "workflow-checkpoint.json",
         ),
+        "{{CHECKPOINT_SYSTEM}}": read_checkpoint_system_section(script_dir),
         "{{TIMESTAMP}}": "",  # Placeholder — agent fills in timestamp
-        "{{PLATFORM_CONVENTIONS}}": read_platform_conventions(project_root),
         "{{BROWSER_ENABLED}}": "true" if browser_enabled else "false",
         "{{BROWSER_TOOL}}": browser_tool,
         "{{BROWSER_VERIFY_STEPS}}": browser_verify_steps,
@@ -726,9 +706,6 @@ def main():
 
     # Build replacements
     replacements = build_replacements(args, refactor, refactors, global_context, script_dir)
-    if is_continuation(args):
-        replacements["{{LOG_SIZE_AWARENESS}}"] = ""
-
     # Render the template
     rendered = render_template(template_content, replacements, args.resume_phase, refactor)
 
@@ -738,7 +715,7 @@ def main():
         emit_failure(err)
 
     # Generate checkpoint file
-    project_root = resolve_project_root(script_dir)
+    project_root = _args_project_root(args, script_dir)
     checkpoint_rel = os.path.join(
         ".prizmkit", "refactor", args.refactor_id, "workflow-checkpoint.json",
     )

package/bundled/dev-pipeline/scripts/utils.py

@@ -79,6 +79,46 @@ def error_out(message, code=1):
     sys.exit(code)
 
 
+def read_checkpoint_system_section(script_dir):
+    """Read the shared checkpoint prompt section for feature/bugfix/refactor prompts."""
+    path = os.path.join(
+        os.path.abspath(script_dir), "..", "templates", "sections", "checkpoint-system.md"
+    )
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return f.read()
+    except IOError:
+        return """## Workflow Checkpoint System
+
+A checkpoint file tracks your progress through this workflow:
+
+**Path**: `{{CHECKPOINT_PATH}}`
+
+### Checkpoint Update Helper
+
+Use this helper to update checkpoint status. Do not hand-edit `workflow-checkpoint.json` directly.
+
+```bash
+python3 .prizmkit/dev-pipeline/scripts/update-checkpoint.py \\
+  --checkpoint-path {{CHECKPOINT_PATH}} \\
+  --step <step-id-or-skill-name> \\
+  --status <in_progress|completed|failed|skipped> \\
+  --note "<optional note>"
+```
+
+- Use the step `skill` value such as `prizmkit-implement`, or the step id such as `S04`.
+- Omit `--note` when there is no useful failure or handoff note.
+
+### Rules
+
+1. **Before each skill**: Read `workflow-checkpoint.json`, verify the previous step has `status: "completed"` or `status: "skipped"`. If it is still `"pending"` or `"in_progress"`, complete it first before moving on.
+2. **Starting a skill**: Use the checkpoint update helper to mark the current step as `status: "in_progress"`.
+3. **After each skill completes**: Use the checkpoint update helper to mark the current step as `status: "completed"`.
+4. **On failure**: Use the checkpoint update helper to mark the step as `status: "failed"`, write `failure-log.md` with the reason, and continue only when the workflow rules allow it.
+5. **On session exit**: The checkpoint file reflects your actual progress. Do NOT manually set future steps to `"completed"`.
+"""
+
+
 def pad_right(text, width):
     """Pad text with spaces to fill width, accounting for ANSI escape codes."""
     i = 0
@@ -520,6 +560,89 @@ def enrich_global_context(global_context, project_root):
     return global_context
 
 
+
+def read_json_object(path):
+    """Read a JSON object, returning an empty dict when unavailable."""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except (IOError, OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def platform_from_command(command):
+    """Map an AI CLI command/config value to a PrizmKit platform name."""
+    cmd = str(command or "").strip().lower()
+    if not cmd:
+        return ""
+    base = os.path.basename(cmd.split()[0])
+    if base in ("claude", "claude-code") or "claude" in base:
+        return "claude"
+    if base in ("codex", "openai-codex") or "codex" in base:
+        return "codex"
+    if base in ("cbc", "codebuddy") or "codebuddy" in base:
+        return "codebuddy"
+    return ""
+
+
+def valid_prompt_platform(value):
+    """Normalize a platform value for prompt path rendering."""
+    value = str(value or "").strip().lower()
+    if value in ("claude", "codex", "codebuddy"):
+        return value
+    return ""
+
+
+def resolve_prompt_platform(project_root):
+    """Resolve the platform whose agent paths should appear in prompts.
+
+    Explicit ``PRIZMKIT_PLATFORM`` wins. Otherwise prefer active/configured AI
+    CLI because mixed installs contain several platform directories. Filesystem
+    markers are only a final fallback.
+    """
+    explicit = valid_prompt_platform(os.environ.get("PRIZMKIT_PLATFORM", ""))
+    if explicit:
+        return explicit
+
+    for env_name in ("AI_CLI", "CLAUDECODE", "CLAUDE_CODE"):
+        detected = platform_from_command(os.environ.get(env_name, ""))
+        if detected:
+            return detected
+
+    config = read_json_object(os.path.join(project_root, ".prizmkit", "config.json"))
+    for key in ("ai_cli", "aiCli"):
+        detected = platform_from_command(config.get(key, ""))
+        if detected:
+            return detected
+    detected = valid_prompt_platform(config.get("platform", ""))
+    if detected:
+        return detected
+
+    manifest = read_json_object(os.path.join(project_root, ".prizmkit", "manifest.json"))
+    options = manifest.get("options", {}) if isinstance(manifest.get("options"), dict) else {}
+    for value in (manifest.get("aiCli", ""), options.get("aiCli", "")):
+        detected = platform_from_command(value)
+        if detected:
+            return detected
+    detected = valid_prompt_platform(manifest.get("platform", ""))
+    if detected:
+        return detected
+
+    marker_order = (
+        ("claude", os.path.join(project_root, ".claude", "agents")),
+        ("codex", os.path.join(project_root, ".codex", "agents")),
+        ("codebuddy", os.path.join(project_root, ".codebuddy", "agents")),
+    )
+    for candidate, marker in marker_order:
+        if os.path.isdir(marker):
+            return candidate
+
+    raise RuntimeError(
+        "PrizmKit agents not found. None of .claude/agents/, .codex/agents/, or .codebuddy/agents/ exists. "
+        "Run `npx prizmkit install` first, set .prizmkit/config.json ai_cli/platform, or set PRIZMKIT_PLATFORM=claude|codex|codebuddy explicitly."
+    )
+
 def read_platform_conventions(project_root):
     """Resolve the platform-specific project conventions file.
 

package/bundled/dev-pipeline/templates/agent-prompts/critic-plan-challenge.md

@@ -1,7 +1,8 @@
 "Read {{CRITIC_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
 **MODE: Plan Challenge**
 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has project context, Section 4 has file manifest.
-2. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules.
-3. Read existing source files in the modules this plan touches.
-4. Challenge plan.md against the project's existing architecture, patterns, and style.
+2. Use context-snapshot.md as the shared source of truth. Do not create or enter AI tool-created `.claude/worktrees/...` subagent worktrees; use default/no worktree isolation and do not request worktree isolation.
+3. PrizmKit pipeline-managed linked git worktrees under `.prizmkit/state/worktrees/...` are a separate runner feature controlled by `USE_WORKTREE`; do not confuse them with AI tool-created `.claude/worktrees/...`.
+4. Read additional `.prizmkit/prizm-docs/` or source excerpts only when needed to verify a specific challenge.
+5. Challenge plan.md against the project's existing architecture, patterns, and style.
 Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report.md` with findings (or 'No significant challenges')."

package/bundled/dev-pipeline/templates/agent-prompts/reviewer-review.md

@@ -1,7 +1,6 @@
 "Read {{REVIEWER_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
-1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/spec.md` (if it exists) for goals and Verification Gates; if spec.md does not exist, read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` Section 1 Task Contract instead
-2. Read `.prizmkit/specs/{{FEATURE_SLUG}}/plan.md` for architecture decisions and completed tasks
-3. Run /prizmkit-code-review with artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/. The skill will run its internal review-fix loop (Reviewer → filter → Dev fix, max 3 rounds) and write review-report.md.
-4. Do not run test suites here. The orchestrator runs `/prizmkit-test` after review completes and then fixes code/tests until the scoped gate passes.
-5. review-report.md will be written to .prizmkit/specs/{{FEATURE_SLUG}}/ by prizmkit-code-review.
-Report: verdict (PASS/NEEDS_FIXES), number of rounds, findings fixed/rejected."
+1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/spec.md` (if it exists) for goals and Verification Gates; if spec.md does not exist, read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` Section 1 Task Contract instead.
+2. Read `.prizmkit/specs/{{FEATURE_SLUG}}/plan.md` for architecture decisions and completed tasks.
+3. Review the current workspace changes and return structured findings only. Do not run `/prizmkit-code-review`, do not apply fixes, do not run test suites, and do not spawn other agents.
+4. The main orchestrator owns the review-fix loop: Reviewer Agent → filter → orchestrator fix.
+Report: PASS/NEEDS_FIXES, findings with severity/location/problem/suggestion/verification, and a concise summary."

package/bundled/dev-pipeline/templates/bootstrap-prompt.md

@@ -44,7 +44,7 @@ Infer what needs to be done from the feature context above and follow the standa
 - Do NOT push to remote — the user will push manually.
 - Write all artifacts to `.prizmkit/specs/{{FEATURE_SLUG}}/`.
 - If a step fails after 3 attempts, write a status report and stop.
-- **Anti re-read**: once you read a file into context, do NOT read it again — use `grep -n`/`sed -n` for specific lines. 3 full Reads of same file → report BLOCKED.
+- **Never re-read unmodified files**: once you read a file into context, do NOT read it again unless it was modified by an Edit/Write after your last read — use `grep -n`/`sed -n` for specific lines. Before issuing a Read, ask: "Have I read this file before, and has it changed since?" If no — do NOT read it. Subagents (Critic, Reviewer) must rely on context-snapshot.md rather than re-reading files the orchestrator already read.
 - **Read offset safety**: if Read returns "shorter than offset"/"empty" — run `wc -l` then `sed -n`, do NOT retry same offset.
 - **Hard Round Cap**: after 6 total test-fix rounds, STOP trial-and-error. Switch to read-once-then-rewrite. Do NOT exceed 7 rounds.
 - **Layered test**: debug with single-file tests, only run full suite as gate when single-file is green.

package/bundled/dev-pipeline/templates/bootstrap-tier1.md

@@ -46,22 +46,18 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 
 1. **context-snapshot.md is your single source of truth** — After Phase 1 builds it, ALWAYS read context-snapshot.md instead of re-reading individual source files
 2. **Never re-read your own writes** — After you create/modify a file, do NOT read it back to verify. Trust your write was correct.
-3. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
+3. **Never re-read unmodified files** — Once you have read a file into context, do NOT read it again unless it was modified by an Edit/Write operation after your last read. Use `grep -n '<pattern>' <file>` or `sed -n '<start>,<end>p' <file>` for targeted line lookups instead of full-file Read. Before issuing a Read, ask yourself: "Have I read this file before, and has it changed since?" If the answer is "no, it hasn't changed" — do NOT read it. This applies to all files including those summarized in context-snapshot.md Section 4. Subagents (Critic, Reviewer) must receive context-snapshot.md and rely on it rather than independently re-reading the same files the orchestrator already read.
+4. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
 4. **One task at a time** — In Phase 3 (implement), complete and test one task before starting the next.
 5. **Minimize tool output** — Never load full command output into context. First capture to a temp file (`cmd 2>&1 | tee /tmp/out.txt | tail -20`), then scan the head/tail to identify relevant fields, and use targeted filtering (`grep`, `sed`, `awk`) to extract only the information needed for the current task. Only read the filtered result — never the raw full output.
 6. **No intermediate commits** — Do NOT run `git add`/`git commit` during Phase 1-3. All changes are committed once at the end in Phase 4 via `/prizmkit-committer`.
-7. **Capture test output once** — When running test suites, always use `($TEST_CMD) 2>&1 | tee /tmp/test-out.txt | tail -20`. Then grep `/tmp/test-out.txt` for details. Never re-run the suite just to apply a different filter.
-8. **Scaffold / generated file awareness** — Files created by scaffolding tools (`npm init`, `npx create-*`, etc.) are boilerplate. Tag them, record in context-snapshot.md, and NEVER re-read them. If you need to modify one, edit directly without reading first.
+7. **Capture test output once** — When running test suites, always use `<test-command> 2>&1 | tee /tmp/test-out.txt | tail -20`. Then grep `/tmp/test-out.txt` for details. Never re-run the suite just to apply a different filter.
 9. **Package version verification (BLOCKING)** — Before writing ANY dependency version, verify it exists via registry query (`npm view <pkg> dist-tags.latest`, `pip index versions <pkg>`, etc.). NEVER guess version numbers.
 10. **Build artifact hygiene** — After build/compile, ensure output is in `.gitignore`. Never commit binaries/build output.
-11. **Anti re-read hard rule (BLOCKING)** — Once you have read a file into context, do NOT read the full file again. Use `grep -n '<pattern>' <file>` or `sed -n '<start>,<end>p' <file>` for specific lines. **20-step window**: full Read forbidden within 20 tool calls of last read. **3-strike**: 3 full Reads of same file → report BLOCKED. Applies to orchestrator AND subagents.
-12. **Read offset safety (BLOCKING)** — If Read returns "shorter than offset"/"File is empty"/"Wasted call" — do NOT retry same offset. Run `wc -l <file>` to get real line count, then `sed -n` for exact range. 2 consecutive offset errors → STOP Reading that file. Never guess offsets — `grep -n '<anchor>'` first.
+11. **Read offset safety (BLOCKING)** — If Read returns "shorter than offset"/"File is empty"/"Wasted call" — do NOT retry same offset. Run `wc -l <file>` to get real line count, then `sed -n` for exact range. 2 consecutive offset errors → STOP Reading that file. Never guess offsets — `grep -n '<anchor>'` first.
 
 ---
 
-{{LOG_SIZE_AWARENESS}}
----
-
 ## PrizmKit Directory Convention
 
 ```
@@ -115,7 +111,7 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
 
 If plan.md missing, run `/prizmkit-plan` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to generate `plan.md`:
 - The plan.md should include: key components, data flow, files to create/modify, and a Tasks section with `[ ]` checkboxes (each task = one implementable unit). Keep under 80 lines.
-- Resolve any `[NEEDS CLARIFICATION]` markers using the feature description — do NOT pause for interactive input.
+- Resolve uncertain requirements from the feature description, existing code, and conservative existing-project patterns.
 
 **Database Design Gate** (if feature involves data persistence — new tables, schema changes, new entities):
 Before proceeding past CP-1:
@@ -125,7 +121,7 @@ Before proceeding past CP-1:
 
 **CP-1**: plan.md exists with Tasks section.
 
-### Phase 3: Implement + Test
+### Phase 3: Implement
 
 **Build artifacts**: After any build/compile command (`go build`, `npm run build`, `tsc`, etc.), ensure the output binary or build directory is in `.gitignore`:
 ```bash
@@ -134,51 +130,56 @@ grep -q '^/binary-name$' .gitignore || echo '/binary-name' >> .gitignore
 ```
 Never commit compiled binaries, build output, or generated artifacts.
 
-**3a.** Detect test commands and record baseline:
-
-You know this project's tech stack. Identify ALL test commands that apply (e.g., `go test ./...`, `npm test`, `cargo test`, `pytest`, `make test`, etc.). Record them as `TEST_CMDS` (one or more commands). Then record baseline:
-```bash
-# Run each test command, capture output
-($TEST_CMD) 2>&1 | tee /tmp/test-baseline.txt | tail -20
-```
-
-**3b.** Run `/prizmkit-implement` — this handles the full implementation cycle:
+**3a.** Run `/prizmkit-implement` — this handles the implementation cycle:
 - Reads plan.md Tasks section from `.prizmkit/specs/{{FEATURE_SLUG}}/`
 - Reads context from `context-snapshot.md` (Prizm docs, TRAPS, file manifest)
 - Implements task-by-task, marking each `[x]` immediately
 - Creates/updates L2 `.prizm` docs when creating new modules or significantly modifying existing ones — AI selectively decides which modules warrant L2 based on complexity and importance
-- Defers scoped/full test execution until after review
+- Does not run the scoped/full test gate; testing happens after code review in the PrizmKit Test phase
 - Writes '## Implementation Log' to `context-snapshot.md`
 
-**3b-checkpoint.** Context management — if plan.md has more than 5 tasks, update durable checkpoints/artifacts after every 3 tasks, minimize output, and continue. If context overflow occurs in a headless run, the runner starts a fresh continuation session from those checkpoints and artifacts. In an interactive Claude Code session operated manually outside the headless pipeline, `/compact` may be used as an optional convenience only.
-
-**3c.** After implement completes, verify:
+**3b.** After implement completes, verify:
 1. All tasks in plan.md are `[x]`
 2. **Verification Gate Self-Check**: for each acceptance criterion, write one line of evidence (test name / file:line / fixture path). Any gate without evidence is BLOCKED, not success.
-3. **Layered test strategy**: do not run mandatory periodic/full-suite tests during implementation. Use only tiny targeted checks when needed for local debugging; the scoped feature test gate runs after review.
-4. Verify each acceptance criterion from Section 1 of context-snapshot.md is met — check mentally, do NOT re-read files you already wrote
-5. If any criterion is not met, fix it now using the convergence-based recovery loop below
+3. Use only tiny targeted checks when needed for local debugging; the scoped feature test gate runs after review.
+4. If any criterion is not met, fix it within this feature scope before proceeding.
+
+**CP-2**: All acceptance criteria met or blocked gates documented in `failure-log.md`. Test execution is deferred until after code review.
 
-**CP-2**: All acceptance criteria met, all tests pass.
+### Review — Code Review
 
-### Test Failure Recovery (Convergence-Based)
+Review the completed implementation before the scoped feature test gate runs. Use `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` so the code-review skill can read spec, plan, context snapshot, implementation log, and current diff artifacts. Do not require or read a prior `/prizmkit-test` report here; test generation and test-fix looping happen in the next phase.
 
-When tests fail, use convergence recovery — keep fixing while progress is being made:
+Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`.
 
-1. **Run tests, record results**: count failures, exclude baseline failures
-2. **Check termination**: All pass → done | Plateau (same failures 3 rounds) → stop | Failures decreased → continue
-3. **Fix and iterate**: analyze, fix, re-run `($TEST_CMD)`, go back to step 1
+The skill runs an internal review-fix loop (Reviewer Agent → filter → orchestrator fix, max 3 rounds) and writes `review-report.md` to the artifact directory.
 
-**Key rule**: If failures decrease (even by 1), plateau counter resets. Do NOT block commit for unresolved failures — document and defer to next session.
+**Gate Check — Review Report**:
+After `/prizmkit-code-review` returns, verify the review report:
+```bash
+grep -q "## Verdict" .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md && echo "GATE:PASS" || echo "GATE:MISSING"
+```
+If GATE:MISSING:
+- Do not re-run `/prizmkit-code-review` in an unbounded report-repair loop.
+- Perform one bounded status check; retry at most once: inspect the skill output, `review-report.md` path, and any Reviewer agent spawn messages.
+- If the missing report is caused by Reviewer agent spawn or review skill error, retry `/prizmkit-code-review` at most once only if it appears transient.
+- If the report is still missing after that single check/retry, write `failure-log.md` with the spawn/skill error and last observable state, then either perform a safe inline fallback review (spec/plan/diff/tests → write `review-report.md` with `## Verdict`) or stop with a clear recovery failure.
 
-**Hard Round Cap (BLOCKING)**: After **6 total test-fix rounds**, STOP trial-and-error. Write failure-log listing all hypotheses tried. Switch to: read full relevant source section ONCE (via `grep -n`+`sed -n`, never full Read), understand control flow, rewrite failing block in one shot. Do NOT exceed 7 total rounds.
+Read `review-report.md` and check the Verdict:
+- `PASS` → proceed to next phase
+- `NEEDS_FIXES` → the skill exhausted its max rounds; log the remaining findings and proceed (do not retry externally)
 
+**CP-3**: Review complete, report written.
 
 ### Scoped Feature Test Gate — PrizmKit Test
 
 Run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` after review and before commit.
 
-Before invoking the skill, create `.prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started` so stale reports are ignored.
+Before invoking the skill, create a current-run marker so stale reports are ignored:
+```bash
+mkdir -p .prizmkit/specs/{{FEATURE_SLUG}}
+touch .prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started
+```
 
 Gate requirements:
 - Generate or update tests only for this feature's changed files, changed public interfaces, and acceptance criteria.