prizmkit 1.1.119 → 1.1.121

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

@@ -41,6 +41,17 @@ def run_cli(*args):
     )
 
 
+def _load_progress_parser_module():
+    import importlib.util
+
+    parser_path = PIPELINE_ROOT / "scripts" / "parse-stream-progress.py"
+    spec = importlib.util.spec_from_file_location("parse_stream_progress", parser_path)
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
 def test_cli_help_exposes_python_runtime_command_groups():
     result = run_cli("--help")
 
@@ -791,24 +802,28 @@ 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" / "bootstrap-tier2.md",
+        REPO_ROOT / "dev-pipeline" / "templates" / "sections" / "phase-review-full.md",
         REPO_ROOT / "dev-pipeline" / "templates" / "bootstrap-tier3.md",
         REPO_ROOT / "core" / "skills" / "prizmkit-skill" / "prizmkit-code-review" / "SKILL.md",
     ]
 
     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")
@@ -840,6 +855,145 @@ def test_progress_parser_adds_required_metadata(tmp_path):
     assert data["permission_denial_count"] == 1
 
 
+
+def test_progress_parser_normalizes_claude_subagents_without_double_counting(tmp_path):
+    module = _load_progress_parser_module()
+    tracker = module.ProgressTracker()
+
+    tracker.process_event({"type": "system", "subtype": "init", "session_id": "claude-session", "cwd": str(tmp_path)})
+    tracker.process_event({
+        "type": "assistant",
+        "message": {"content": [{
+            "type": "tool_use",
+            "id": "tool-1",
+            "name": "Agent",
+            "input": {"description": "review code", "prompt": "check", "subagent_type": "reviewer"},
+        }]},
+    })
+    tracker.process_event({
+        "type": "system",
+        "subtype": "task_started",
+        "task_id": "task-1",
+        "tool_use_id": "tool-1",
+        "task_type": "in_process_teammate",
+        "subagent_type": "reviewer",
+        "description": "review code",
+    })
+    tracker.process_event({"type": "assistant", "parent_tool_use_id": "tool-1", "message": {"content": [{"type": "text", "text": "child activity"}]}})
+    tracker.process_event({"type": "system", "subtype": "task_started", "task_id": "bash-1", "task_type": "local_bash", "description": "ls"})
+    tracker.process_event({"type": "system", "subtype": "task_notification", "task_id": "task-1", "tool_use_id": "tool-1", "status": "completed", "summary": "done"})
+
+    data = tracker.to_dict()
+
+    assert data["subagent_stats_source"] == "session_log"
+    assert data["subagent_spawn_count"] == 1
+    assert data["active_subagent_count"] == 0
+    assert data["subagent_states"] == [{"status": "completed", "count": 1}]
+    assert "task-1" in data["subagent_observed_ids"]
+    assert "tool-1" in data["subagent_statistics"]["parent_activity_ids"]
+    assert all("bash" not in record["id"] for record in data["subagent_statistics"]["records"])
+
+
+def test_progress_parser_normalizes_codebuddy_agent_tools_with_deduplication():
+    module = _load_progress_parser_module()
+    tracker = module.ProgressTracker()
+    args = {"prompt": "inspect", "description": "inspect", "subagent_type": "Explore"}
+
+    tracker.process_event({
+        "type": "message",
+        "sessionId": "cb-session",
+        "cwd": "/tmp/project",
+        "role": "assistant",
+        "content": [{"type": "tool_use", "id": "call-1", "name": "Agent", "input": args}],
+    })
+    tracker.process_event({
+        "type": "function_call",
+        "sessionId": "cb-session",
+        "cwd": "/tmp/project",
+        "id": "call-1",
+        "name": "Agent",
+        "arguments": json.dumps(args),
+    })
+    tracker.process_event({
+        "type": "function_call",
+        "sessionId": "cb-session",
+        "cwd": "/tmp/project",
+        "id": "task-call",
+        "name": "TaskCreate",
+        "arguments": json.dumps({"description": "background", "subject": "status"}),
+    })
+
+    data = tracker.to_dict()
+
+    assert data["cb_session_id"] == "cb-session"
+    assert data["subagent_provider"] == "codebuddy"
+    assert data["subagent_spawn_count"] == 2
+    assert data["active_subagent_count"] == 2
+    assert {item["status"] for item in data["subagent_states"]} == {"running"}
+    assert len(data["subagent_statistics"]["records"]) == 2
+
+
+def test_progress_parser_normalizes_codex_collab_metadata_with_missing_fields():
+    module = _load_progress_parser_module()
+    tracker = module.ProgressTracker()
+
+    tracker.process_event({"type": "thread.started", "thread_id": "parent"})
+    tracker.process_event({
+        "type": "item.started",
+        "item": {
+            "type": "collab_tool_call",
+            "tool": "delegate",
+            "receiver_thread_ids": ["thread-a", "thread-b"],
+            "agents_states": {
+                "thread-a": {"status": "running", "message": "working"},
+                "thread-b": {"status": "completed", "message": "done"},
+            },
+        },
+    })
+    tracker.process_event({"type": "item.completed", "item": {"type": "collab_tool_call", "tool": "delegate"}})
+
+    data = tracker.to_dict()
+
+    assert data["event_format"] == "codex-json"
+    assert data["child_thread_ids"] == ["thread-a", "thread-b"]
+    assert data["subagent_spawn_count"] == 2
+    assert data["active_subagent_count"] == 1
+    assert {state["status"]: state["count"] for state in data["subagent_states"]} == {"running": 1, "completed": 1}
+    assert data["subagent_source_metadata"]["child_activity_source"] == "filesystem_liveness_only"
+
+
+def test_progress_parser_keeps_child_files_liveness_only(tmp_path, monkeypatch):
+    module = _load_progress_parser_module()
+    claude_home = tmp_path / "claude"
+    project_key = str(tmp_path).replace("\\", "-").replace("/", "-").replace(":", "")
+    subagents_dir = claude_home / "projects" / project_key / "parent-session" / "subagents"
+    subagents_dir.mkdir(parents=True)
+    child_log = subagents_dir / "agent-child.jsonl"
+    child_log.write_text("child activity", encoding="utf-8")
+    monkeypatch.setenv("CLAUDE_HOME", str(claude_home))
+
+    tracker = module.ProgressTracker()
+    tracker.process_event({"type": "system", "subtype": "init", "session_id": "parent-session", "cwd": str(tmp_path)})
+    tracker.process_event({
+        "type": "system",
+        "subtype": "task_started",
+        "task_id": "task-1",
+        "tool_use_id": "tool-1",
+        "task_type": "in_process_teammate",
+        "description": "agent",
+    })
+    first = tracker.to_dict()
+    child_log.write_text("child activity grew", encoding="utf-8")
+    tracker.refresh_child_session_activity(force=True)
+    second = tracker.to_dict()
+
+    assert first["subagent_spawn_count"] == 1
+    assert second["subagent_spawn_count"] == 1
+    assert second["child_total_bytes"] > first["child_total_bytes"]
+    assert second["child_session_files"]
+    assert second["child_activity_source"] == "filesystem_liveness_only"
+    assert second["subagent_statistics"]["source"] == "session_log"
+
 def test_session_dual_writes_progress_and_recovers_backup(tmp_path):
     from prizmkit_runtime.sessions import AISessionConfig, AISessionLauncher, recover_session_log
 
@@ -935,6 +1089,10 @@ def test_custom_session_launch_writes_existing_logs_and_progress(tmp_path):
     progress_data = json.loads(progress.read_text(encoding="utf-8"))
     assert progress_data["event_type_counts"]["result"] == 1
     assert progress_data["has_usage"] is True
+    assert progress_data["subagent_stats_source"] == "session_log"
+    assert progress_data["subagent_spawn_count"] == 0
+    assert progress_data["subagent_statistics"]["providers"] == []
+    assert progress_data["child_activity_source"] == "filesystem_liveness_only"
 
 
 @pytest.mark.parametrize("platform", ["claude", "codex", "codebuddy"])
@@ -1031,7 +1189,10 @@ def test_compact_progress_line_hides_stale_until_no_progress(tmp_path):
         json.dumps(
             {
                 "child_total_bytes": 2 * 1024 * 1024,
+                "child_session_files": [{"path": "a"}, {"path": "b"}],
                 "subagent_spawn_count": 5,
+                "active_subagent_count": 2,
+                "subagent_states": [{"status": "running", "count": 2}, {"status": "completed", "count": 3}],
                 "current_phase": "stream-derived-phase",
                 "current_tool": "Read",
                 "message_count": 465,
@@ -1059,7 +1220,9 @@ def test_compact_progress_line_hides_stale_until_no_progress(tmp_path):
 
     assert "▶ [HEARTBEAT]" in running_line
     assert "log: 4MB" in running_line
-    assert "child: 2MB/5" in running_line
+    assert "subagents: spawned=5 active=2 states:running=2,completed=3" in running_line
+    assert "child logs: 2MB/2 files" in running_line
+    assert "child: 2MB/5" not in running_line
     assert "phase: Retrospective" in running_line
     assert "stream-derived-phase" not in running_line
     assert "tool: Read" in running_line
@@ -1417,6 +1580,46 @@ def test_recovery_sessions_receive_live_heartbeat_configuration(tmp_path, monkey
     assert config.suppress_stream_output is True
 
 
+
+def test_session_summary_reports_normalized_subagents_and_child_liveness(tmp_path, capsys):
+    import prizmkit_runtime.runners as runners
+    from prizmkit_runtime.runner_models import SessionPaths
+
+    logs = tmp_path / "sessions" / "s1" / "logs"
+    logs.mkdir(parents=True)
+    session_log = logs / "session.log"
+    progress = logs / "progress.json"
+    session_log.write_text("one\ntwo\n", encoding="utf-8")
+    progress.write_text(
+        json.dumps({
+            "subagent_spawn_count": 2,
+            "active_subagent_count": 1,
+            "subagent_states": [{"status": "running", "count": 1}, {"status": "completed", "count": 1}],
+            "subagent_statistics": {"spawned": 2, "active": 1, "providers": ["claude"], "source": "session_log"},
+            "child_total_bytes": 2048,
+            "child_session_files": [{"path": "child-a"}],
+        }),
+        encoding="utf-8",
+    )
+    paths = SessionPaths(
+        session_dir=logs.parent,
+        prompt_path=logs.parent / "bootstrap-prompt.md",
+        logs_dir=logs,
+        session_log=session_log,
+        progress_json=progress,
+        heartbeat_json=logs / "heartbeat.json",
+        session_status_json=logs / "session-status.json",
+    )
+    result = type("Result", (), {"exit_code": 0})()
+    classification = type("Classification", (), {"session_status": "success"})()
+
+    runners._emit_session_summary(result, paths, classification)
+
+    captured = capsys.readouterr()
+    assert "Subagents: spawned=2, active=1, states: running=1, completed=1 (claude; source=session.log)" in captured.err
+    assert "Child log activity: 2KB across 1 files (heartbeat liveness only)" in captured.err
+    assert "Subagent calls detected" not in captured.err
+
 def test_session_live_output_does_not_forward_cli_output_without_verbose(tmp_path, capsys):
     from prizmkit_runtime.sessions import AISessionConfig, AISessionLauncher
 
@@ -1995,8 +2198,8 @@ def test_materialize_worktree_support_assets_copies_ignored_assets_without_retir
     subprocess.run(["git", "add", ".gitignore"], cwd=repo, check=True)
     subprocess.run(["git", "commit", "-m", "ignore support"], cwd=repo, check=True, stdout=subprocess.DEVNULL)
 
-    (repo / ".claude" / "agents").mkdir(parents=True)
-    (repo / ".claude" / "agents" / "prizm-dev-team-dev.md").write_text("dev", encoding="utf-8")
+    (repo / ".claude" / "commands").mkdir(parents=True)
+    (repo / ".claude" / "commands" / "prizmkit.md").write_text("skill", encoding="utf-8")
     (repo / ".prizmkit" / "prizm-docs").mkdir(parents=True)
     (repo / ".prizmkit" / "prizm-docs" / "root.prizm").write_text("PRIZM_VERSION: 1\n", encoding="utf-8")
     (repo / ".prizmkit" / "config.json").write_text("{}", encoding="utf-8")
@@ -2014,12 +2217,12 @@ def test_materialize_worktree_support_assets_copies_ignored_assets_without_retir
     )
     setup = ensure_linked_worktree(runtime)
     assert setup.ok
-    assert not (runtime.worktree_path / ".claude" / "agents" / "prizm-dev-team-dev.md").exists()
+    assert not (runtime.worktree_path / ".claude" / "commands" / "prizmkit.md").exists()
 
     result = materialize_worktree_support_assets(runtime)
 
     assert result.ok
-    assert (runtime.worktree_path / ".claude" / "agents" / "prizm-dev-team-dev.md").is_file()
+    assert (runtime.worktree_path / ".claude" / "commands" / "prizmkit.md").is_file()
     assert (runtime.worktree_path / ".prizmkit" / "prizm-docs" / "root.prizm").is_file()
     assert (runtime.worktree_path / ".prizmkit" / "config.json").is_file()
     assert (runtime.worktree_path / ".prizmkit" / "manifest.json").is_file()

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.119",
+  "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/app-planner/SKILL.md

@@ -47,7 +47,7 @@ If you believe the task is better suited for a different workflow, you MUST:
 - Claude Code → `CLAUDE.md`
 - CodeBuddy → `CODEBUDDY.md`
 - `all` → all three files.
-- Only when the manifest is missing, fall back to installed PrizmKit-owned platform files such as `.codex/agents/*.toml`, `.claude/commands/prizmkit.md`, or `.codebuddy/skills/prizmkit/SKILL.md`. Do not treat a generic `.agents/` directory as Codex.
+- Only when the manifest is missing, fall back to installed PrizmKit-owned platform files such as `.claude/commands/prizmkit.md`, `.agents/skills/prizmkit/SKILL.md`, or `.codebuddy/skills/prizmkit/SKILL.md`. Do not treat a generic `.agents/` directory as Codex.
 
 **After planning is complete**, you MUST:
 1. Present the summary of captured project-level context (vision, conventions, architecture decisions, project brief)
@@ -126,7 +126,7 @@ Before questions, check optional context files (never block if absent):
 Note:
 - This skill **reads** `.prizmkit/config.json` if present.
 - This skill does **not** create `.prizmkit/config.json` directly.
-- Creation/update is handled by bootstrap/init flows (e.g., `prizmkit-init`, `.prizmkit/dev-pipeline/scripts/init-dev-team.py`).
+- Creation/update is handled by bootstrap/init flows (e.g., `prizmkit-init`, `.prizmkit/dev-pipeline/scripts/init-change-artifact.py`).
 
 ## Interaction Style (Hard Rule)
 

package/bundled/skills/app-planner/references/architecture-decisions.md

@@ -29,9 +29,7 @@ After Phase 2 (Confirm constraints and tech assumptions), before Phase 3 (Captur
    - `codex` → append to `AGENTS.md`
    - `claude` → append to `CLAUDE.md`
    - `codebuddy` → append to `CODEBUDDY.md`
-   - `all` → append to all three files. Legacy manifests may contain `both`; treat it as read-only compatibility and append to `CLAUDE.md` and `CODEBUDDY.md` only when encountered.
-   - Only when the manifest is missing, fall back to PrizmKit-owned install artifacts: `.codex/agents/*.toml`, `.claude/commands/prizmkit.md`, `.codebuddy/skills/prizmkit/SKILL.md`.
-   - Do not treat a generic `.agents/` directory as Codex; it may contain unrelated third-party skills.
+   - `all` → append to all three files. 
    - If no platform can be determined, skip (no project instruction file).
 
 2. **Check for existing section** — read the target file and look for `### Architecture Decisions` heading:

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

@@ -1,55 +1,53 @@
 ---
 name: "prizmkit-code-review"
-description: "Iterative review-fix loop against spec and plan. Always uses the dedicated prizm-dev-team-reviewer agent in the active checkout with current-workspace / active-checkout / no-worktree launch; the Main Agent filters findings and applies accepted fixes directly. If the current platform cannot start an active-checkout reviewer, stop with tool 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 a dedicated `prizm-dev-team-reviewer` subagent in the active checkout. 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:
-- `reviewer-agent-active-checkout`: required mode. Always spawn `prizm-dev-team-reviewer` in the current active checkout with no worktree or remote 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 `prizm-dev-team-reviewer` in current-workspace / active-checkout / no-worktree mode, stop with this tool 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 prizm-dev-team-reviewer in the active checkout without worktree 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
-   - 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
 
@@ -69,41 +67,43 @@ python3 --version 2>/dev/null && echo "SCRIPT_MODE" || echo "TEXT_MODE"
 - `round = 1`
 - `max_rounds = 3`
 - `findings_history = []`
-- `review_mode = reviewer-agent-active-checkout` after confirming the dedicated reviewer can launch in the active checkout
+- `review_mode = independent-reviewer-verified-snapshot` after snapshot verification succeeds
 
-### Step 1: Launch Required Reviewer
+### Step 1: Establish Independent Review
 
-Always spawn `prizm-dev-team-reviewer` using the dedicated subagent contract:
+Use the skill-owned review contract:
 
 ```yaml
-subagent_type: prizm-dev-team-reviewer
-isolation: current-workspace / active-checkout / no-worktree
+prompt_reference: ${SKILL_DIR}/references/reviewer-agent-prompt.md
+workspace_protocol: ${SKILL_DIR}/references/reviewer-workspace-protocol.md
+reviewer_contract: independent, read-only, workspace-equivalent
 ```
 
-1. Pass the active-checkout context from Phase 0 and the prompt template from `${SKILL_DIR}/references/reviewer-agent-prompt.md`.
-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`, remote isolation, copied checkouts, `Explore`, or a generic code explorer as a substitute for the PrizmKit reviewer. Do not request or create worktree isolation for this review path, including tool-created `.claude/worktrees/...` directories or pipeline-managed `.prizmkit/state/worktrees/...` directories. Pipeline `USE_WORKTREE` controls implementation infrastructure only; it does not change `/prizmkit-code-review` active-checkout review location.
-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 isolation, stop with the tool 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:
 
@@ -111,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
 
@@ -128,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 Dev Agent for 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: `reviewer-agent-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.

package/bundled/skills/prizmkit-code-review/references/review-report-template.md

@@ -1,13 +1,16 @@
 # Review Report Output Template
 
-Used in Phase 2 of `/prizmkit-code-review`. Always write `review-report.md` to the artifact directory using this format.
+Used in Phase 2 of `/prizmkit-code-review`. Write `review-report.md` to the artifact directory using this format.
 
 ```markdown
 # Review Report
 
 ## Verdict: <PASS|NEEDS_FIXES>
-## Review Mode: <reviewer-agent-active-checkout|not-run-no-changes>
-## Rounds: <number of review rounds completed; use 0 for no-change PASS>
+## Review Mode: <independent-reviewer-verified-snapshot|not-run-no-changes>
+## Reviewer Strategy: <platform-selected strategy summary|not-applicable>
+## Snapshot Verification: <VERIFIED|FAILED|NOT_APPLICABLE>
+## Snapshot Identity: <manifest identity or failure reason>
+## Rounds: <number of completed review rounds; use 0 for no-change PASS or pre-review snapshot failure>
 ## Total findings: <total> → Fixed: <fixed>, Rejected: <rejected>, Unresolved: <unresolved>
 
 ## Round <N>
@@ -15,18 +18,20 @@ Findings: <count> | Accepted: <count>, Rejected: <count>
 
 ### Finding <N>: <short title>
 - Severity: <high|medium|low>
-- Dimension: <goal-alignment|defect|completeness|consistency|security|rules-compliance>
+- Dimension: <goal-alignment|defect|completeness|consistency|security|test-quality|rules-compliance>
 - Location: <filepath:line or project-level>
 - Problem: <what was wrong and why it mattered>
 - Status: <fixed (round N)|rejected — reason|unresolved — reason>
 
 ## Final Summary
-<One to three sentences summarizing the review outcome, including no-change PASS when applicable.>
+<One to three sentences summarizing the review outcome, snapshot verification, and any remaining blocker.>
 ```
 
-For `PASS` with no findings, write `Total findings: 0 → Fixed: 0, Rejected: 0, Unresolved: 0` and `## Round 0: PASS — no workspace changes to review` or `## Round N: PASS — no issues found`.
+For `PASS` with no findings, write `Total findings: 0 → Fixed: 0, Rejected: 0, Unresolved: 0` and either `## Round 0: PASS — no workspace changes to review` or `## Round N: PASS — no issues found`.
+
+For snapshot verification failure, use verdict `NEEDS_FIXES`, snapshot verification `FAILED`, and record the mismatch as an unresolved review blocker rather than an ordinary code finding.
 
 ## Verdict Rules
 
-- `PASS`: Reviewer returned no findings, no workspace changes existed, or all remaining findings were rejected as unreasonable.
-- `NEEDS_FIXES`: Max rounds completed but accepted findings remain unresolved.
+- `PASS`: Reviewer returned no findings from a verified snapshot, no workspace changes existed, or all findings from a verified snapshot were rejected as unreasonable.
+- `NEEDS_FIXES`: Max rounds completed with accepted findings unresolved, or no independent Reviewer could verify an equivalent current snapshot.