prizmkit 1.1.105 → 1.1.107

package/bundled/dev-pipeline/prizmkit_runtime/sessions.py

@@ -16,7 +16,7 @@ from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass, field
 from pathlib import Path
 
-from .heartbeat import HeartbeatConfig, HeartbeatMonitor, write_stale_marker
+from .heartbeat import HeartbeatConfig, HeartbeatMonitor, HeartbeatState, observe_heartbeat_state, write_stale_marker
 from .processes import ProcessHandle, ProcessSpec, launch_process, terminate_process_tree
 from .status import ProgressSummary
 
@@ -393,6 +393,10 @@ def _format_elapsed(seconds: float) -> str:
     return f"{minutes}m{remainder:02d}s"
 
 
+def _format_stale_minutes(seconds: float) -> str:
+    return f"{max(0, int(seconds)) // 60}m"
+
+
 def _read_json_object(path: Path | None) -> dict[str, object]:
     if path is None or not path.is_file():
         return {}
@@ -403,14 +407,50 @@ def _read_json_object(path: Path | None) -> dict[str, object]:
     return data if isinstance(data, dict) else {}
 
 
-def _compact_progress_line(started_epoch: float, session_log: Path, progress_path: Path | None) -> str:
+def _display_heartbeat_state(
+    session_log: Path,
+    progress_path: Path | None,
+    monitor_state: HeartbeatState | None,
+    fallback_state: HeartbeatState | None,
+    *,
+    interval_seconds: float,
+    stale_threshold_seconds: float,
+) -> HeartbeatState:
+    if monitor_state is not None and monitor_state.last_seen_epoch is not None:
+        return monitor_state
+    return observe_heartbeat_state(
+        HeartbeatConfig(
+            heartbeat_file=session_log.with_name("heartbeat.json"),
+            session_log=session_log,
+            progress_file=progress_path,
+            interval_seconds=interval_seconds,
+            stale_after_seconds=stale_threshold_seconds,
+            kill_after_seconds=0,
+        ),
+        fallback_state,
+    )
+
+
+def _compact_progress_line(
+    started_epoch: float,
+    session_log: Path,
+    progress_path: Path | None,
+    heartbeat_state: HeartbeatState | None = None,
+    *,
+    stale_threshold_seconds: float = 0,
+) -> str:
     data = _read_json_object(progress_path)
-    try:
-        log_size = session_log.stat().st_size
-    except OSError:
-        log_size = 0
+    if heartbeat_state is not None:
+        log_size = heartbeat_state.log_size
+    else:
+        try:
+            log_size = session_log.stat().st_size
+        except OSError:
+            log_size = 0
+    glyph = "⏸" if heartbeat_state is not None and heartbeat_state.details == "no progress" else "▶"
+    stale_seconds = heartbeat_state.stale_seconds if heartbeat_state is not None else 0
     parts = [
-        f"  ▶ [HEARTBEAT] {_format_elapsed(time.time() - started_epoch)}",
+        f"  {glyph} [HEARTBEAT] {_format_elapsed(time.time() - started_epoch)}",
         f"log: {_format_bytes(log_size)}",
     ]
     child_bytes = int(data.get("child_total_bytes") or 0)
@@ -432,15 +472,40 @@ def _compact_progress_line(started_epoch: float, session_log: Path, progress_pat
     tool_calls = int(data.get("total_tool_calls") or 0)
     if tool_calls:
         parts.append(f"{tool_calls} tool calls")
+    parts.append(f"stale: {_format_stale_minutes(stale_seconds)}/{_format_stale_minutes(stale_threshold_seconds)}")
     return " | ".join(parts)
 
 
-def _emit_progress_tick(started_epoch: float, session_log: Path, progress_path: Path | None, last_line: str) -> str:
-    line = _compact_progress_line(started_epoch, session_log, progress_path)
+def _emit_progress_tick(
+    started_epoch: float,
+    session_log: Path,
+    progress_path: Path | None,
+    last_line: str,
+    *,
+    monitor_state: HeartbeatState | None = None,
+    fallback_state: HeartbeatState | None = None,
+    interval_seconds: float = 30,
+    stale_threshold_seconds: float = 0,
+) -> tuple[str, HeartbeatState]:
+    heartbeat_state = _display_heartbeat_state(
+        session_log,
+        progress_path,
+        monitor_state,
+        fallback_state,
+        interval_seconds=interval_seconds,
+        stale_threshold_seconds=stale_threshold_seconds,
+    )
+    line = _compact_progress_line(
+        started_epoch,
+        session_log,
+        progress_path,
+        heartbeat_state,
+        stale_threshold_seconds=stale_threshold_seconds,
+    )
     if line != last_line:
         _emit_live_line(line)
-        return line
-    return last_line
+        return line, heartbeat_state
+    return last_line, heartbeat_state
 
 
 def _emit_session_start(config: AISessionConfig, command: AISessionCommand, session_log: Path, backup_log: Path) -> None:
@@ -601,6 +666,8 @@ class AISessionLauncher:
             handle.popen.stdin.close()
 
         heartbeat = None
+        live_progress_interval = max(1.0, float(self.config.live_progress_interval_seconds or 30))
+        stale_threshold_seconds = max(0.0, float(self.config.stale_kill_threshold_seconds or 0))
         heartbeat_path = self.config.heartbeat_path
         if heartbeat_path is None and self.config.stale_kill_threshold_seconds > 0:
             heartbeat_path = session_log.with_name("heartbeat.json")
@@ -613,8 +680,8 @@ class AISessionLauncher:
                     progress_file=self.config.progress_path,
                     marker_dir=session_log.parent,
                     interval_seconds=0.1,
-                    stale_after_seconds=self.config.stale_kill_threshold_seconds,
-                    kill_after_seconds=self.config.stale_kill_threshold_seconds,
+                    stale_after_seconds=stale_threshold_seconds,
+                    kill_after_seconds=stale_threshold_seconds,
                     grace_seconds=self.config.stale_kill_grace_seconds,
                 ),
             )
@@ -626,6 +693,7 @@ class AISessionLauncher:
         stale_marker = None
         last_progress_line = ""
         last_progress_emit = 0.0
+        display_heartbeat_state = None
         try:
             while True:
                 timeout = 0.2
@@ -642,16 +710,33 @@ class AISessionLauncher:
                     break
                 except subprocess.TimeoutExpired:
                     if self.config.live_output and (not self.config.verbose or self.config.suppress_stream_output):
-                        interval = max(1.0, float(self.config.live_progress_interval_seconds or 30))
                         now = time.time()
-                        if last_progress_emit == 0.0 or now - last_progress_emit >= interval:
-                            last_progress_line = _emit_progress_tick(started, session_log, self.config.progress_path, last_progress_line)
+                        if last_progress_emit == 0.0 or now - last_progress_emit >= live_progress_interval:
+                            last_progress_line, display_heartbeat_state = _emit_progress_tick(
+                                started,
+                                session_log,
+                                self.config.progress_path,
+                                last_progress_line,
+                                monitor_state=heartbeat.state if heartbeat is not None else None,
+                                fallback_state=display_heartbeat_state,
+                                interval_seconds=live_progress_interval,
+                                stale_threshold_seconds=stale_threshold_seconds,
+                            )
                             last_progress_emit = now
         except KeyboardInterrupt:
             terminate_process_tree(handle, "interrupted", grace_seconds=self.config.stale_kill_grace_seconds)
             raise
         if self.config.live_output and (not self.config.verbose or self.config.suppress_stream_output):
-            _emit_progress_tick(started, session_log, self.config.progress_path, last_progress_line)
+            last_progress_line, display_heartbeat_state = _emit_progress_tick(
+                started,
+                session_log,
+                self.config.progress_path,
+                last_progress_line,
+                monitor_state=heartbeat.state if heartbeat is not None else None,
+                fallback_state=display_heartbeat_state,
+                interval_seconds=live_progress_interval,
+                stale_threshold_seconds=stale_threshold_seconds,
+            )
         reader.join(timeout=5)
         heartbeat_result = heartbeat.stop() if heartbeat is not None else None
         if heartbeat_result and heartbeat_result.killed:

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

@@ -158,8 +158,6 @@ def runtime_paths(args, project_root, task_type, task_id, previous_session_id):
         "bootstrap_prompt": _rel_path(project_root, output_path),
         "session_log": _rel_path(project_root, os.path.join(logs_dir, "session.log")),
         "progress_json": _rel_path(project_root, os.path.join(logs_dir, "progress.json")),
-        "log_monitor_status": _rel_path(project_root, os.path.join(logs_dir, "log-monitor-status.txt")),
-        "log_monitor_baseline": _rel_path(project_root, os.path.join(logs_dir, "log-monitor-baseline.txt")),
         "pid_file": _rel_path(project_root, os.path.join(logs_dir, "ai.pid")),
         "session_status": _rel_path(project_root, session_status),
         "previous_session_log": _rel_path(project_root, previous_log),
@@ -321,8 +319,6 @@ def _build_addendum(context):
         "- Generated bootstrap prompt path: `{}`".format(runtime["bootstrap_prompt"]),
         "- Session log path: `{}`".format(runtime["session_log"]),
         "- Progress JSON path: `{}`".format(runtime["progress_json"]),
-        "- Log monitor status path: `{}`".format(runtime["log_monitor_status"]),
-        "- Log monitor baseline path: `{}`".format(runtime["log_monitor_baseline"]),
         "- PID file: `{}`".format(runtime["pid_file"]),
         "- Session status file: `{}`".format(runtime["session_status"]),
         "",

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

@@ -32,7 +32,6 @@ from continuation import add_continuation_args, append_continuation_handoff, is_
 
 
 DEFAULT_MAX_RETRIES = 3
-DEFAULT_MAX_LOG_SIZE = 2097152
 
 LOGGER = setup_logging("generate-bootstrap-prompt")
 
@@ -161,27 +160,6 @@ def compute_feature_slug(feature_id, title):
     return "{}-{}".format(numeric, slug)
 
 
-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:
-        emit_failure("{} must be a non-negative integer".format(name))
-    if parsed < 0:
-        emit_failure("{} 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))
@@ -196,11 +174,7 @@ def _parse_positive_int_env(name, default):
 
 
 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 ""
-
+    """Load passive checkpoint guidance for normal prompt generation."""
     section_path = os.path.join(
         script_dir, "..", "templates", "sections", "log-size-awareness.md",
     )
@@ -1299,17 +1273,16 @@ def load_section(sections_dir, name):
 ACTIVE_AGENT_PROMPTS = {
     "critic-plan-challenge.md": "{{AGENT_PROMPT_CRITIC_PLAN_CHALLENGE}}",
     "reviewer-review.md": "{{AGENT_PROMPT_REVIEWER_REVIEW}}",
-    "dev-fix.md": "{{AGENT_PROMPT_DEV_FIX}}",
-    "dev-resume.md": "{{AGENT_PROMPT_DEV_RESUME}}",
 }
 
 
 def load_active_agent_prompts(templates_dir):
     """Load explicit active agent prompt templates.
 
-    The retired top-level Dev implementation prompt is intentionally not loaded;
-    feature implementation is performed by the main orchestrator. Remaining
-    prompt placeholders support Critic/Reviewer and review-fix helper flows.
+    Retired Dev implementation and review-fix prompts are intentionally not
+    loaded; feature implementation and accepted review fixes are performed by
+    the main orchestrator. Remaining prompt placeholders support Critic and
+    read-only Reviewer handoffs.
     """
     agent_prompts_dir = os.path.join(templates_dir, "agent-prompts")
     if not os.path.isdir(agent_prompts_dir):
@@ -1470,9 +1443,8 @@ def assemble_sections(pipeline_mode, sections_dir, init_done, is_resume,
     sections.append(("context-budget-rules",
                       load_section(sections_dir, "context-budget-rules.md")))
 
-    # --- Log Size Awareness (only disabled when MAX_LOG_SIZE is explicitly 0) ---
-    max_log_size = _parse_non_negative_int_env("MAX_LOG_SIZE", DEFAULT_MAX_LOG_SIZE)
-    if max_log_size != 0 and os.path.isfile(os.path.join(sections_dir, "log-size-awareness.md")):
+    # --- Session checkpoint guidance ---
+    if os.path.isfile(os.path.join(sections_dir, "log-size-awareness.md")):
         sections.append(("log-size-awareness",
                           load_section(sections_dir, "log-size-awareness.md")))
 
@@ -1949,8 +1921,6 @@ def build_replacements(args, feature, features, global_context, script_dir):
         pass  # Keep default 3000 on any error
     dev_url = f"http://localhost:{dev_port}"
 
-    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),
         "{{RUN_ID}}": args.run_id,
@@ -1997,8 +1967,6 @@ def build_replacements(args, feature, features, global_context, script_dir):
         "{{COVERAGE_TARGET}}": coverage_target,
         "{{DEV_PORT}}": dev_port,
         "{{DEV_URL}}": dev_url,
-        "{{MAX_LOG_SIZE}}": str(max_log_size),
-        "{{MAX_LOG_SIZE_HUMAN}}": _format_bytes(max_log_size),
         "{{SESSION_LOG_PATH}}": os.path.join(
             ".prizmkit", "state", "features", args.feature_id,
             "sessions", args.session_id, "logs", "session.log",

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

@@ -24,7 +24,6 @@ from continuation import add_continuation_args, append_continuation_handoff, is_
 
 
 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))
@@ -100,11 +78,7 @@ def _parse_positive_int_env(name, default):
 
 
 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 ""
-
+    """Load passive checkpoint guidance for normal prompt generation."""
     section_path = os.path.join(
         script_dir, "..", "templates", "sections", "log-size-awareness.md",
     )
@@ -373,12 +347,8 @@ 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",

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

@@ -24,7 +24,6 @@ from continuation import add_continuation_args, append_continuation_handoff, is_
 
 
 DEFAULT_MAX_RETRIES = 3
-DEFAULT_MAX_LOG_SIZE = 2097152
 
 LOGGER = setup_logging("generate-refactor-prompt")
 
@@ -156,27 +155,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))
@@ -190,11 +168,7 @@ def _parse_positive_int_env(name, default):
 
 
 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 ""
-
+    """Load passive checkpoint guidance for normal prompt generation."""
     section_path = os.path.join(
         script_dir, "..", "templates", "sections", "log-size-awareness.md",
     )
@@ -518,12 +492,8 @@ 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",

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-tier1.md

@@ -50,12 +50,11 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 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.
+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.
 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.
 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.
 
 ---
 
@@ -125,7 +124,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,45 +133,46 @@ 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