prizmkit 1.1.120 → 1.1.121

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

@@ -904,7 +904,20 @@ def _install_runner_session_fakes(monkeypatch, runners, *, statuses=("success",)
 
     def fake_update(family, invocation, item_id, session_status, session_id, project_root, **metadata):
         updates.append((session_status, session_id, metadata))
-        return SimpleNamespace(ok=True, text="", data={"new_status": update_status})
+        current_update_status = update_status
+        if session_status in {"context_overflow", "infra_error", "crashed", "timed_out", "failed"} and len(status_queue) > 0:
+            current_update_status = "in_progress"
+        return SimpleNamespace(
+            ok=True,
+            text="",
+            data={
+                "new_status": current_update_status,
+                "retry_count": sum(status in {"crashed", "timed_out", "failed"} for status, *_ in updates),
+                "infra_error_count": sum(status == "infra_error" for status, *_ in updates),
+                "continuation_count": len(updates),
+                "context_overflow_count": sum(status == "context_overflow" for status, *_ in updates),
+            },
+        )
 
     def fake_cleanup(runtime, *, delete_branch=True):
         cleanup_calls.append((runtime, delete_branch))
@@ -1096,8 +1109,8 @@ def test_explicit_worktree_materializes_ignored_support_assets_before_prompt_and
     (project / ".prizmkit" / "prizm-docs" / "root.prizm").write_text("PRIZM_VERSION: 1\n", encoding="utf-8")
     (project / ".prizmkit" / "dev-pipeline" / "scripts").mkdir(parents=True)
     (project / ".prizmkit" / "dev-pipeline" / "scripts" / "init-change-artifact.py").write_text("# init", encoding="utf-8")
-    (project / ".prizmkit" / "config.json").write_text("{}", encoding="utf-8")
-    (project / ".prizmkit" / "manifest.json").write_text("{}", encoding="utf-8")
+    (project / ".prizmkit" / "config.json").write_text(json.dumps({"completion_notes": ["Completed durable workflow"]}), encoding="utf-8")
+    (project / ".prizmkit" / "manifest.json").write_text(json.dumps({"completion_notes": ["Completed durable workflow"]}), encoding="utf-8")
 
     paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT, project_root=project)
     family = family_for("feature", paths)
@@ -1225,7 +1238,7 @@ def test_has_branch_completion_evidence_requires_task_branch_ahead_of_base(tmp_p
     subprocess.run(["git", "config", "user.name", "Test"], cwd=tmp_path, check=True)
     artifact_dir = tmp_path / ".prizmkit" / "specs" / "001-done"
     artifact_dir.mkdir(parents=True)
-    (artifact_dir / "completion-summary.json").write_text("{}", encoding="utf-8")
+    (artifact_dir / "completion-summary.json").write_text(json.dumps({"completion_notes": ["Completed durable workflow"]}), encoding="utf-8")
     (tmp_path / "base.txt").write_text("base", encoding="utf-8")
     subprocess.run(["git", "add", "base.txt"], cwd=tmp_path, check=True)
     subprocess.run(["git", "commit", "-m", "base"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
@@ -1405,7 +1418,7 @@ def test_default_branch_names_keep_timestamp_for_each_runner_family(monkeypatch,
         ("refactor", "R-001", "refactor/R-001-20260707010203"),
     ],
 )
-def test_no_worktree_failure_stays_on_task_branch_without_merge_for_all_families(monkeypatch, tmp_path, kind, item_id, branch):
+def test_no_worktree_exhausted_failure_stays_on_task_branch_without_merge_for_all_families(monkeypatch, tmp_path, kind, item_id, branch):
     from prizmkit_runtime import runners
     from prizmkit_runtime.runner_models import family_for, parse_invocation
 
@@ -1415,7 +1428,7 @@ def test_no_worktree_failure_stays_on_task_branch_without_merge_for_all_families
     invocation = parse_invocation(family, "run", ())
     plan_path = {"feature": paths.feature_plan, "bugfix": paths.bugfix_plan, "refactor": paths.refactor_plan}[kind]
     invocation = invocation.__class__(**{**invocation.__dict__, "list_path": plan_path})
-    _install_runner_session_fakes(monkeypatch, runners, statuses=("crashed",), update_status="pending")
+    _install_runner_session_fakes(monkeypatch, runners, statuses=("crashed",), update_status="failed")
     events = []
     final_commits = []
     wip_commits = []
@@ -1431,12 +1444,12 @@ def test_no_worktree_failure_stays_on_task_branch_without_merge_for_all_families
 
     status = runners._process_item(family, invocation, item_id, paths, initial_metadata={})
 
-    assert status == "pending"
+    assert status == "failed"
     assert events[0] == "branch_create"
     assert "branch_merge" not in events
     assert events[-1] == ("return", "main", branch)
-    assert final_commits == [(paths.project_root, item_id, "pending")]
-    assert wip_commits == [(paths.project_root, item_id, "pending")]
+    assert final_commits == [(paths.project_root, item_id, "failed")]
+    assert wip_commits == [(paths.project_root, item_id, "failed")]
 
 
 def test_no_worktree_runner_ignores_recovery_side_effect_branch(monkeypatch, tmp_path):
@@ -1845,7 +1858,7 @@ def test_bookkeeping_commits_only_runner_owned_paths(tmp_path):
     item_state.mkdir(parents=True)
     plan = plans / "feature-list.json"
     plan.write_text('{"features": []}', encoding="utf-8")
-    (item_state / "status.json").write_text("{}", encoding="utf-8")
+    (item_state / "status.json").write_text(json.dumps({"completion_notes": ["Completed durable workflow"]}), encoding="utf-8")
     source = tmp_path / "src.txt"
     source.write_text("base", encoding="utf-8")
     subprocess.run(["git", "add", ".prizmkit/plans/feature-list.json", ".prizmkit/state/features/F-001/status.json", "src.txt"], cwd=tmp_path, check=True)
@@ -1899,6 +1912,8 @@ def test_context_overflow_reuses_worktree_and_skips_cleanup_until_terminal_outco
     invocation = parse_invocation(family, "run", ())
     invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
     observed = _install_runner_session_fakes(monkeypatch, runners, statuses=("context_overflow", "success"))
+    sleep_calls = []
+    monkeypatch.setattr(runners.time, "sleep", lambda seconds: sleep_calls.append(seconds))
     setup_calls = []
     monkeypatch.setattr(runners, "ensure_linked_worktree", lambda runtime: (setup_calls.append(runtime) or SimpleNamespace(ok=True, runtime=runtime, reason="")), raising=False)
 
@@ -1911,6 +1926,7 @@ def test_context_overflow_reuses_worktree_and_skips_cleanup_until_terminal_outco
     assert observed.prompt_calls[0].get("continuation") is None
     assert observed.prompt_calls[1]["continuation"]["previous_session_id"] == "F-001-session-1"
     assert observed.updates[0][0] == "context_overflow"
+    assert sleep_calls == [5]
     assert len(observed.cleanup_calls) == 1
     assert observed.cleanup_calls[0][1] is True
 
@@ -1959,7 +1975,7 @@ def test_classification_accepts_late_infra_error_with_completed_checkpoint_and_c
     assert classification.reason == "completed_checkpoint_with_late_runtime_error"
 
 
-def test_classification_rejects_late_infra_when_head_diff_has_no_commit_range(tmp_path):
+def test_classification_accepts_late_infra_with_completion_artifact_without_new_commit(tmp_path):
     from prizmkit_runtime.runner_classification import classify_session
     from prizmkit_runtime.runner_models import PromptGenerationResult
     from prizmkit_runtime.sessions import AISessionCommand, AISessionResult
@@ -1983,7 +1999,7 @@ def test_classification_rejects_late_infra_when_head_diff_has_no_commit_range(tm
     subprocess.run(["git", "checkout", "side"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
     artifact_dir = tmp_path / ".prizmkit" / "specs" / "001-done"
     artifact_dir.mkdir(parents=True)
-    (artifact_dir / "completion-summary.json").write_text("{}", encoding="utf-8")
+    (artifact_dir / "completion-summary.json").write_text(json.dumps({"completion_notes": ["Completed durable workflow"]}), encoding="utf-8")
     log = tmp_path / "session.log"
     log.write_text("quota exceeded", encoding="utf-8")
     raw = AISessionResult(
@@ -2004,7 +2020,8 @@ def test_classification_rejects_late_infra_when_head_diff_has_no_commit_range(tm
 
     classification = classify_session(raw, project_root=tmp_path, base_head=side_head, prompt=prompt)
 
-    assert classification.session_status == "infra_error"
+    assert classification.session_status == "success"
+    assert classification.reason == "completed_checkpoint_with_late_runtime_error"
 
 
 def test_classification_keeps_pre_completion_provider_error_as_infra_error(tmp_path):
@@ -2060,7 +2077,7 @@ def test_classification_accepts_terminal_success_with_completed_checkpoint_witho
     artifact_dir.mkdir(parents=True)
     checkpoint = artifact_dir / "workflow-checkpoint.json"
     checkpoint.write_text(json.dumps({"steps": [{"id": "S01", "skill": "done", "name": "Done", "status": "completed"}]}), encoding="utf-8")
-    (artifact_dir / "completion-summary.json").write_text("{}", encoding="utf-8")
+    (artifact_dir / "completion-summary.json").write_text(json.dumps({"completion_notes": ["Completed durable workflow"]}), encoding="utf-8")
     log = tmp_path / "session.log"
     log.write_text("terminal success", encoding="utf-8")
     raw = AISessionResult(
@@ -2122,8 +2139,8 @@ def test_classification_preserves_success_before_context_overflow(tmp_path):
     )
 
     classification = classify_session(raw, project_root=tmp_path, base_head=base_head)
-    assert classification.session_status == "success"
-    assert classification.reason == "commit_since_base"
+    assert classification.session_status == "context_overflow"
+    assert classification.reason == "context_overflow"
 
 
 def test_classification_crash_with_commit_since_base_does_not_become_success(tmp_path):
@@ -2256,7 +2273,7 @@ def _write_family_case(paths, kind, item_id=""):
         state_dir = paths.refactor_state_dir
         plan = paths.refactor_plan
     state_dir.mkdir(parents=True, exist_ok=True)
-    (state_dir / "pipeline.json").write_text("{}", encoding="utf-8")
+    (state_dir / "pipeline.json").write_text(json.dumps({"completion_notes": ["Completed durable workflow"]}), encoding="utf-8")
     item_state = state_dir / item_id
     item_state.mkdir(parents=True, exist_ok=True)
     (item_state / "status.json").write_text(
@@ -2517,7 +2534,7 @@ def test_invalid_existing_checkpoint_blocks_terminal_success_with_completion_sum
     artifact_dir.mkdir(parents=True)
     checkpoint = artifact_dir / "workflow-checkpoint.json"
     checkpoint.write_text(json.dumps({"steps": [{"id": "S01", "skill": "done", "name": "Done", "status": "not-valid"}]}), encoding="utf-8")
-    (artifact_dir / "completion-summary.json").write_text("{}", encoding="utf-8")
+    (artifact_dir / "completion-summary.json").write_text(json.dumps({"completion_notes": ["Completed durable workflow"]}), encoding="utf-8")
     prompt = PromptGenerationResult(output_path=tmp_path / "prompt.md", checkpoint_path=checkpoint, artifact_path=artifact_dir)
 
     classification = classify_session(_terminal_success_result(tmp_path), project_root=tmp_path, base_head=base_head, prompt=prompt)
@@ -2597,3 +2614,190 @@ def test_invalid_existing_checkpoint_blocks_workspace_auto_commit_success(tmp_pa
 
     assert classification.session_status == "crashed"
     assert classification.reason == "invalid_workflow_checkpoint:empty_steps"
+
+
+@pytest.mark.parametrize(
+    ("kind", "item_id", "branch"),
+    [
+        ("feature", "F-001", "dev/F-001-ai-retry"),
+        ("bugfix", "B-001", "bugfix/B-001-ai-retry"),
+        ("refactor", "R-001", "refactor/R-001-ai-retry"),
+    ],
+)
+@pytest.mark.parametrize("retry_status", ["infra_error", "crashed", "timed_out"])
+def test_retryable_ai_errors_continue_in_process_for_all_families(monkeypatch, tmp_path, kind, item_id, branch, retry_status):
+    from prizmkit_runtime import runners
+    from prizmkit_runtime.runner_models import family_for, parse_invocation
+
+    monkeypatch.setenv("DEV_BRANCH", branch)
+    paths = _make_paths(tmp_path / kind / retry_status)
+    family = family_for(kind, paths)
+    invocation = parse_invocation(family, "run", ())
+    plan_path = {"feature": paths.feature_plan, "bugfix": paths.bugfix_plan, "refactor": paths.refactor_plan}[kind]
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": plan_path})
+    observed = _install_runner_session_fakes(monkeypatch, runners, statuses=(retry_status, "success"))
+    sleep_calls = []
+    branch_plans = []
+    monkeypatch.setattr(runners.time, "sleep", lambda seconds: sleep_calls.append(seconds))
+    monkeypatch.setattr(
+        runners,
+        "run_git_plan",
+        lambda project_root, plan: (branch_plans.append(plan.name) or SimpleNamespace(ok=True, plan=plan, results=())),
+    )
+
+    status = runners._process_item(family, invocation, item_id, paths, initial_metadata={})
+
+    assert status == "completed"
+    assert sleep_calls == [5]
+    assert len(observed.launch_cwds) == 2
+    assert observed.launch_cwds[0] == observed.launch_cwds[1]
+    assert branch_plans.count("branch_create") == 1
+    assert observed.updates[0][0] == retry_status
+    continuation = observed.prompt_calls[1]["continuation"]
+    assert continuation["previous_session_id"].endswith("session-1")
+    assert continuation["failure_classification"] == retry_status
+    assert continuation["active_dev_branch"] == branch
+
+
+def test_unique_session_ids_do_not_collide_when_wall_clock_second_is_frozen(monkeypatch):
+    from prizmkit_runtime import runners
+
+    monkeypatch.setattr(runners.time, "strftime", lambda _fmt: "20260711030000")
+    values = iter((101, 102))
+    monkeypatch.setattr(runners.time, "time_ns", lambda: next(values))
+
+    first = runners._session_id("F-001")
+    second = runners._session_id("F-001")
+
+    assert first != second
+    assert first.endswith("-101")
+    assert second.endswith("-102")
+
+
+@pytest.mark.parametrize("summary_text", ["{}", "{not-json", '{"completion_notes": []}', '{"completion_notes": [""]}'])
+def test_invalid_completion_summary_does_not_prove_late_runtime_success(tmp_path, summary_text):
+    from prizmkit_runtime.runner_classification import classify_session
+    from prizmkit_runtime.runner_models import PromptGenerationResult
+    from prizmkit_runtime.sessions import AISessionCommand, AISessionResult
+    from prizmkit_runtime.status import ProgressSummary
+
+    subprocess.run(["git", "init", "-b", "main"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=tmp_path, check=True)
+    (tmp_path / "base.txt").write_text("base", encoding="utf-8")
+    subprocess.run(["git", "add", "base.txt"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-m", "base"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    base_head = subprocess.run(["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True).stdout.strip()
+    artifact_dir = tmp_path / ".prizmkit" / "specs" / "001-invalid"
+    artifact_dir.mkdir(parents=True)
+    (artifact_dir / "completion-summary.json").write_text(summary_text, encoding="utf-8")
+    log = tmp_path / "session.log"
+    log.write_text("quota exceeded", encoding="utf-8")
+    result = AISessionResult(
+        command=AISessionCommand(("fake",), None, "codebuddy", "stdin"),
+        exit_code=1,
+        timed_out=False,
+        termination_reason=None,
+        stale_marker=None,
+        fatal_error_code="api_error",
+        progress_summary=ProgressSummary(terminal_result_text="quota exceeded"),
+        session_log=log,
+        backup_log=tmp_path / "backup.log",
+        log_recovery=None,
+        started_epoch=0,
+        ended_epoch=1,
+    )
+
+    classification = classify_session(
+        result,
+        project_root=tmp_path,
+        base_head=base_head,
+        prompt=PromptGenerationResult(output_path=tmp_path / "prompt.md", artifact_path=artifact_dir),
+    )
+
+    assert classification.session_status == "infra_error"
+
+
+def test_non_utf8_completion_summary_does_not_abort_classification(tmp_path):
+    from prizmkit_runtime.runner_classification import classify_session
+    from prizmkit_runtime.runner_models import PromptGenerationResult
+    from prizmkit_runtime.sessions import AISessionCommand, AISessionResult
+    from prizmkit_runtime.status import ProgressSummary
+
+    subprocess.run(["git", "init", "-b", "main"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=tmp_path, check=True)
+    (tmp_path / "base.txt").write_text("base", encoding="utf-8")
+    subprocess.run(["git", "add", "base.txt"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-m", "base"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    base_head = subprocess.run(["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True).stdout.strip()
+    artifact_dir = tmp_path / ".prizmkit" / "specs" / "001-corrupt"
+    artifact_dir.mkdir(parents=True)
+    (artifact_dir / "completion-summary.json").write_bytes(b"\xff\xfe")
+    log = tmp_path / "session.log"
+    log.write_text("quota exceeded", encoding="utf-8")
+    result = AISessionResult(
+        command=AISessionCommand(("fake",), None, "codebuddy", "stdin"),
+        exit_code=1,
+        timed_out=False,
+        termination_reason=None,
+        stale_marker=None,
+        fatal_error_code="api_error",
+        progress_summary=ProgressSummary(terminal_result_text="quota exceeded"),
+        session_log=log,
+        backup_log=tmp_path / "backup.log",
+        log_recovery=None,
+        started_epoch=0,
+        ended_epoch=1,
+    )
+
+    classification = classify_session(
+        result,
+        project_root=tmp_path,
+        base_head=base_head,
+        prompt=PromptGenerationResult(output_path=tmp_path / "prompt.md", artifact_path=artifact_dir),
+    )
+
+    assert classification.session_status == "infra_error"
+
+
+@pytest.mark.parametrize(
+    ("timed_out", "termination_reason", "expected_status", "expected_reason"),
+    [
+        (True, "timeout", "timed_out", "timeout"),
+        (False, "stale_session", "crashed", "stale_session"),
+    ],
+)
+def test_timeout_and_stale_termination_override_provider_error_markers(tmp_path, timed_out, termination_reason, expected_status, expected_reason):
+    from prizmkit_runtime.runner_classification import classify_session
+    from prizmkit_runtime.sessions import AISessionCommand, AISessionResult
+    from prizmkit_runtime.status import ProgressSummary
+
+    subprocess.run(["git", "init", "-b", "main"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=tmp_path, check=True)
+    (tmp_path / "base.txt").write_text("base", encoding="utf-8")
+    subprocess.run(["git", "add", "base.txt"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-m", "base"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    base_head = subprocess.run(["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True).stdout.strip()
+    log = tmp_path / "session.log"
+    log.write_text("gateway API error", encoding="utf-8")
+    result = AISessionResult(
+        command=AISessionCommand(("fake",), None, "codebuddy", "stdin"),
+        exit_code=1,
+        timed_out=timed_out,
+        termination_reason=termination_reason,
+        stale_marker=None,
+        fatal_error_code="api_error",
+        progress_summary=ProgressSummary(terminal_result_text="provider gateway error"),
+        session_log=log,
+        backup_log=tmp_path / "backup.log",
+        log_recovery=None,
+        started_epoch=0,
+        ended_epoch=1,
+    )
+
+    classification = classify_session(result, project_root=tmp_path, base_head=base_head)
+
+    assert classification.session_status == expected_status
+    assert classification.reason == expected_reason

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

@@ -802,7 +802,7 @@ def test_session_preamble_writes_redacted_start_command_for_all_launch_profiles(
             assert str(prompt) not in "\n".join(lines[:6])
 
 
-def test_headless_subagent_prompt_guidance_keeps_no_worktree_boundary_visible():
+def test_headless_review_guidance_uses_workspace_equivalence_protocol():
     guidance_files = [
         REPO_ROOT / "dev-pipeline" / "templates" / "sections" / "phase-review-full.md",
         REPO_ROOT / "dev-pipeline" / "templates" / "bootstrap-tier3.md",
@@ -811,15 +811,19 @@ 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
-            or "current-workspace / active-checkout / no-worktree" in text
-            or "current workspace / active checkout / no worktree" in text
-        ), 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
+        assert "platform-supported" in text, path
+        assert "snapshot" in text and "equivalent" in text, path
+        assert "Main-Agent self-review" in text, path
+        assert "current-workspace / active-checkout / no-worktree" not in text, path
+        assert ".claude/worktrees/..." not in text, path
+        assert ".prizmkit/state/worktrees/..." not in text, path
+        assert "USE_WORKTREE" not in text, path
+        assert "isolation:" not in text, path
+
+    skill_text = guidance_files[-1].read_text(encoding="utf-8")
+    assert "reviewer-workspace-protocol.md" in skill_text
+    assert "staged, unstaged, untracked, deleted, and renamed" in skill_text
+    assert "WORKSPACE_MISMATCH" in skill_text
 
     for path in guidance_files[:-1]:
         text = path.read_text(encoding="utf-8")

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.120",
+  "version": "1.1.121",
   "skills": {
     "prizmkit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",
@@ -65,11 +65,11 @@
       "hasScripts": false
     },
     "prizmkit-test": {
-      "description": "Full-stack test generation and orchestration. Detects architecture, discovers/runs existing tests, analyzes coverage gaps, generates missing tests (unit/integration/E2E), outputs unified report.",
+      "description": "Auditable project-native test evidence with request-driven execution, runner-generated receipts, differential proof, replay, and deterministic validation.",
       "tier": "1",
       "category": "prizmkit-skill",
-      "hasAssets": false,
-      "hasScripts": false
+      "hasAssets": true,
+      "hasScripts": true
     },
     "feature-workflow": {
       "description": "One-stop entry point for feature development. Orchestrates feature-planner → feature-pipeline-launcher → background execution. Handles multi-feature batch development from a single request.",

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

@@ -1,56 +1,53 @@
 ---
 name: "prizmkit-code-review"
-description: "Iterative review-fix loop against spec and plan. Always uses an independent inline reviewer subagent in the active checkout with a skill-owned prompt reference and no worktree/copy/remote isolation; the Main Agent filters findings and applies accepted fixes directly. If the platform cannot start an active-checkout inline reviewer, stop with checkout-isolation incompatibility instead of falling back to Main-Agent self-review. Loops until PASS or max 3 rounds. Use after /prizmkit-implement for Full path quality gate or when the user says 'review', 'check code', 'code review', or 'is it ready to commit'. (project)"
+description: "Iterative independent review-fix loop against spec, plan, workspace changes, and test evidence. Establishes a verified review snapshot using any platform-supported subagent strategy while keeping review judgment separate from Main-Agent filtering and fixes. Use after /prizmkit-implement as a Full path quality gate or when the user asks to review, check code, validate implementation, or decide whether changes are ready to commit. Loops until PASS or max 3 rounds. (project)"
 ---
 
 # PrizmKit Code Review
 
-An iterative review-fix loop that checks workspace changes against the task spec and plan. It separates review judgment from fix application by requiring an independent inline reviewer subagent launched from the active checkout with a prompt loaded from this skill's references. Main Agent applies accepted fixes directly after filtering reviewer findings.
+Run an iterative review-fix loop against the current change. Keep review judgment independent from fix application: an independent read-only Reviewer evaluates a verified snapshot, then the Main Agent filters findings and applies accepted fixes.
 
 Review modes:
-- `inline-reviewer-active-checkout`: required mode. Always spawn an independent reviewer subagent in the current active checkout with no worktree, copied checkout, remote checkout, or branch isolation.
+- `independent-reviewer-verified-snapshot`: an independent Reviewer verified that its review snapshot is equivalent to the Main Agent's current change.
 - `not-run-no-changes`: no workspace changes were detected.
 
-If the platform cannot launch an inline reviewer subagent in current-workspace / active-checkout / no-worktree mode, stop with this checkout-isolation incompatibility message:
+The skill defines review invariants rather than platform tool parameters. Choose any platform-supported subagent launch and snapshot transport strategy that satisfies `${SKILL_DIR}/references/reviewer-workspace-protocol.md`.
 
-```text
-Cannot run /prizmkit-code-review because this platform cannot start an inline reviewer subagent in the active checkout without worktree, copy, remote, or branch isolation.
-```
+If no independent Reviewer can receive and verify an equivalent snapshot, stop normal review and report the workspace verification failure. Do not replace the independent review with Main-Agent self-review because that would remove the separation between judgment and implementation.
 
 ### When to Use
 - After `/prizmkit-implement` as the Full path quality gate
-- For Fast path only when risk, scope, or user request warrants review
-- User says "review", "check code", "review my implementation", or "is it ready to commit"
+- For Fast path when risk, scope, or the user warrants review
+- When the user says "review", "check code", "review my implementation", or "is it ready to commit"
 - Before `/prizmkit-committer` when the chosen lifecycle path requires review
 
 ### When NOT to Use
 - Direct edit or low-risk Fast path where review is not required
-- No spec.md or plan.md exists and there is no clear task goal to review against
+- No `spec.md` or `plan.md` exists and there is no clear task goal to review against
 - Trivial typo, formatting, or config-only changes that the user wants committed directly
 
 ## Input
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `artifact_dir` | No | Directory containing `spec.md` + `plan.md`. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a completed `plan.md`. When invoked as a handoff step, reuse the caller's `artifact_dir` rather than re-detecting. |
+| `artifact_dir` | No | Directory containing `spec.md` and `plan.md`. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a completed `plan.md`. When invoked as a handoff step, reuse the caller's `artifact_dir` rather than re-detecting. |
 
-## Phase 0: Context Loading
+## Phase 0: Context and Snapshot
 
 1. Read `spec.md` from the artifact directory and extract goals plus acceptance criteria.
 2. Read `plan.md` from the artifact directory and extract architecture decisions plus completed tasks.
-3. Read scoped `/prizmkit-test` report when present:
+3. Read a scoped `/prizmkit-test` report when present:
    - If `{artifact_dir}/test-report-path.txt` exists, read the pointed report.
    - Extract Scope, Generated / Updated Tests, In-Scope Failures, Baseline Failures, Out of Scope Gaps, Boundary Matrix / Boundary Completion Gate, and Verdict when present.
-   - If no test report exists, pass `No scoped /prizmkit-test report found` as informational context. Do not treat missing tests as a review finding unless the current lifecycle path explicitly required testing.
+   - If no report exists, pass `No scoped /prizmkit-test report found` as informational context. Treat missing tests as a finding only when the lifecycle path required testing before review.
 4. Read dev rules when configured: load `.prizmkit/prizm-docs/root.prizm`, then referenced `.prizmkit/rules/<layer>-rules.md` files if any exist.
-5. Capture active checkout workspace context:
-   - `git status`
-   - `git diff`
-   - `git diff --cached`
-   - full paths for untracked and renamed files
-   - expected active checkout git top-level from `git rev-parse --show-toplevel`
-   - relevant root.prizm RULES and plan decisions
-6. If no changes are detected, skip Phase 1 and write `review-report.md` with verdict PASS, rounds 0, and review mode `not-run-no-changes`.
+5. Capture the current workspace manifest and review payload according to `${SKILL_DIR}/references/reviewer-workspace-protocol.md`. Include:
+   - baseline repository and revision identity
+   - `git status`, `git diff`, and `git diff --cached` evidence
+   - staged, unstaged, untracked, deleted, and renamed path inventory
+   - changed content and stable content identities sufficient to detect missing, stale, or mixed snapshots
+   - relevant root Prizm rules and plan decisions
+6. If no changes are detected, skip Phase 1 and write `review-report.md` with verdict PASS, rounds 0, review mode `not-run-no-changes`, and snapshot verification `NOT_APPLICABLE`.
 
 ## Phase 1: Review-Fix Loop
 
@@ -70,42 +67,43 @@ python3 --version 2>/dev/null && echo "SCRIPT_MODE" || echo "TEXT_MODE"
 - `round = 1`
 - `max_rounds = 3`
 - `findings_history = []`
-- `review_mode = inline-reviewer-active-checkout` after confirming an inline reviewer subagent can launch in the active checkout
+- `review_mode = independent-reviewer-verified-snapshot` after snapshot verification succeeds
 
-### Step 1: Launch Required Inline Reviewer
+### Step 1: Establish Independent Review
 
-Always spawn an independent reviewer subagent using this skill-owned inline contract:
+Use the skill-owned review contract:
 
 ```yaml
 prompt_reference: ${SKILL_DIR}/references/reviewer-agent-prompt.md
-isolation: current-workspace / active-checkout / no-worktree
-subagent_kind: inline reviewer prompt, not a platform-installed named agent
+workspace_protocol: ${SKILL_DIR}/references/reviewer-workspace-protocol.md
+reviewer_contract: independent, read-only, workspace-equivalent
 ```
 
-1. Read `${SKILL_DIR}/references/reviewer-agent-prompt.md` and fill it with the active-checkout context from Phase 0.
-2. The captured git diff, staged diff, untracked files, spec, plan, dev rules, and scoped test report are the primary review scope.
-3. Never use worktree isolation, remote isolation, copied checkouts, branch switching, broad repository exploration, or a generic code explorer as a substitute for the required inline reviewer prompt. Do not request or create tool-managed worktrees, pipeline-managed worktrees, copied repositories, or remote checkouts. Do not use `.claude/worktrees/...` or `.prizmkit/state/worktrees/...`. Pipeline runner `USE_WORKTREE` controls outer infrastructure only; it does not change this skill's active-checkout reviewer requirement.
-4. Never perform Main-Agent self-review or fallback review; the Main Agent's job is filtering and fixing, not acting as the reviewer.
-5. If the platform cannot launch the reviewer in the active checkout without worktree/copy/remote/branch isolation, stop with the checkout-isolation incompatibility message from this skill's introduction.
+1. Read both references and fill the Reviewer prompt with Phase 0 context plus the workspace manifest and payload.
+2. Choose a subagent launch and snapshot transport strategy supported by the current platform. Strategy choice belongs to the Main Agent because platforms expose different capabilities; do not treat a particular tool parameter, checkout layout, branch name, or transport as part of the skill contract.
+3. Require the Reviewer to verify snapshot equivalence before reviewing. Different physical paths or execution environments are acceptable when the verified review view is content-equivalent to the captured Main-Agent workspace.
+4. If the Reviewer returns `WORKSPACE_MISMATCH`, repair or replace the strategy only when equivalence can be established safely. Otherwise write a `NEEDS_FIXES` report with the verification failure unresolved and stop; do not perform Main-Agent self-review.
+5. After the Main Agent applies fixes, capture and verify a fresh snapshot for the next round because the previous snapshot is stale by definition.
 
 ### Step 2: Run Review
 
 Round context:
 - Round 1: examine all current changes comprehensively.
-- Round 2+: focus on whether prior fixes are correct, whether fixes introduced new issues, and whether accepted findings remain.
+- Round 2+: verify prior fixes, look for regressions introduced by the fixes, and identify accepted findings that remain.
 
 Review result:
 - `PASS`: no findings.
 - `NEEDS_FIXES`: one or more findings with severity, dimension, location, problem, and suggested fix.
+- `WORKSPACE_MISMATCH`: snapshot equivalence was not established; this is a review transport failure, not a code verdict.
 
 ### Step 3: Loop Exit Gate
 
-Call the gate only in these cases:
+Call the gate only when:
 
 1. Review returned `PASS`.
-2. Main Agent has filtered `NEEDS_FIXES` findings.
+2. The Main Agent has filtered `NEEDS_FIXES` findings.
 
-Do not call the gate for `NEEDS_FIXES` before filtering because `accepted_count` is not known yet.
+Do not call the gate for `NEEDS_FIXES` before filtering because `accepted_count` is not known. Handle `WORKSPACE_MISMATCH` through Step 1 rather than passing it to the code-verdict gate.
 
 Script mode invocation:
 
@@ -113,7 +111,7 @@ Script mode invocation:
 echo '{"reviewer_result":"NEEDS_FIXES","accepted_count":2,"findings_count":3,"round":1,"findings_history":[],"max_rounds":3,"filtering_done":true}' | python3 ${SKILL_DIR}/scripts/check_loop.py
 ```
 
-Gate output determines whether to end the loop. If `divergenceWarning` is true, warn the user that the loop may not be converging.
+The gate output determines whether to end the loop. If `divergenceWarning` is true, warn the user that the loop may not be converging.
 
 ### Text Fallback Constraints
 
@@ -130,36 +128,39 @@ When Python is unavailable, apply these rules manually:
 
 For each finding, decide whether it is reasonable:
 
-- Is this relevant to the current changes?
-- Is this a real problem rather than subjective style preference?
-- Would fixing this improve the code without broad out-of-scope refactoring?
-- Does it conflict with spec, plan, dev rules, or current test evidence?
+- Is the finding relevant to the current changes?
+- Is it a real problem rather than a subjective style preference?
+- Would the fix improve the code without broad out-of-scope refactoring?
+- Does the finding conflict with the spec, plan, dev rules, or current test evidence?
 
 Output per finding:
 - Accepted: queue for direct Main Agent fix work.
-- Rejected: record a short reason such as out of scope, not a defect, or too risky for current task.
+- Rejected: record a short reason such as out of scope, not a defect, or too risky for the current task.
 
 After filtering, call the Loop Exit Gate. If `endLoop=true`, proceed to Phase 2.
 
 ### Step 5: Main Agent Applies Accepted Fixes
 
-The Main Agent applies accepted findings directly in the active checkout. Do not spawn a separate implementation subagent for review fixes.
+The Main Agent applies accepted findings directly in its current workspace. Keeping fix ownership with the Main Agent prevents the read-only Reviewer from becoming a second, conflicting implementation authority.
 
-If an accepted finding cannot be safely fixed within scope, record the reason and carry it into `review-report.md` as unresolved.
+If an accepted finding cannot be fixed safely within scope, record the reason and carry the finding into `review-report.md` as unresolved.
 
-After fixes are complete, record results, increment the round, and return to Step 2.
+After fixes are complete, record results, increment the round, capture a fresh workspace snapshot, and return to Step 1.
 
 ## Phase 2: Output
 
-Always write `review-report.md` to the artifact directory, including no-change PASS results. Read `${SKILL_DIR}/references/review-report-template.md` for the full output format.
+Write `review-report.md` to the artifact directory, including no-change PASS and workspace-verification failure results. Read `${SKILL_DIR}/references/review-report-template.md` for the full output format.
 
 Required report fields:
 - Verdict: `PASS` or `NEEDS_FIXES`
-- Review Mode: `inline-reviewer-active-checkout` or `not-run-no-changes`
+- Review Mode: `independent-reviewer-verified-snapshot` or `not-run-no-changes`
+- Reviewer Strategy: concise strategy summary without relying on platform-specific parameter names
+- Snapshot Verification: `VERIFIED`, `FAILED`, or `NOT_APPLICABLE`
+- Snapshot Identity: manifest identity or failure reason
 - Rounds and total findings
 - Fixed, rejected, and unresolved findings
 - Final summary
 
 Completion summary:
 - `PASS`: hand off to `/prizmkit-retrospective` when docs or durable knowledge changed, otherwise `/prizmkit-committer`.
-- `NEEDS_FIXES`: inform the caller of remaining unresolved findings.
+- `NEEDS_FIXES`: inform the caller of unresolved code findings or snapshot-verification blockers.