prizmkit 1.1.123 → 1.1.124

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.123",
-  "bundledAt": "2026-07-11T17:38:07.991Z",
-  "bundledFrom": "9a8c719"
+  "frameworkVersion": "1.1.124",
+  "bundledAt": "2026-07-12T05:54:30.044Z",
+  "bundledFrom": "f15301f"
 }

package/bundled/adapters/claude/command-adapter.js

@@ -20,6 +20,69 @@ function toClaudePrizmkitCommand(sub) {
   return `prizmkit-${normalized}`;
 }
 
+const REVIEWER_ROLE_SKILL = 'prizmkit-code-review';
+const REVIEWER_ROLE_FILE = 'prizmkit-code-reviewer.md';
+const REVIEWER_REQUIRED_UNAVAILABLE = new Set([
+  'workspace-mutation',
+  'shell-execution',
+  'downstream-execution-creation',
+  'delegation-equivalent-behavior',
+  'orchestration-reentry',
+  'skill-invocation',
+]);
+const CLAUDE_OBSERVATIONAL_TOOLS = new Map([
+  ['read-files', 'Read'],
+  ['search-content', 'Grep'],
+  ['search-paths', 'Glob'],
+]);
+
+function buildReviewerRoleDefinition(roleManifest) {
+  if (!roleManifest || roleManifest.role_name !== 'prizmkit-code-reviewer') {
+    throw new Error('prizmkit-code-review requires assets/reviewer-role.json');
+  }
+  const unavailable = new Set(roleManifest.unavailable_capabilities || []);
+  for (const capability of REVIEWER_REQUIRED_UNAVAILABLE) {
+    if (!unavailable.has(capability)) {
+      throw new Error(`Reviewer role must make ${capability} unavailable`);
+    }
+  }
+  if (roleManifest.execution_mode !== 'foreground-single-authority'
+    || roleManifest.max_descendant_execution_units !== 0
+    || roleManifest.max_delegation_depth !== 0) {
+    throw new Error('Reviewer role violates the single-authority execution topology');
+  }
+
+  const tools = (roleManifest.observational_capabilities || []).map(capability => {
+    const tool = CLAUDE_OBSERVATIONAL_TOOLS.get(capability);
+    if (!tool) throw new Error(`Unsupported Reviewer observational capability: ${capability}`);
+    return tool;
+  });
+  if (tools.length === 0) throw new Error('Reviewer role requires observational capabilities');
+
+  return `---
+name: ${roleManifest.role_name}
+description: ${roleManifest.description}
+tools: ${tools.join(', ')}
+permissionMode: dontAsk
+maxTurns: 200
+---
+
+You are a capability-restricted read-only Reviewer execution role.
+
+Read and follow the complete prompt supplied by the Main Agent. Perform the complete review yourself. Your tool allowlist intentionally excludes workspace mutation, shell execution, skill invocation, downstream execution creation, delegation-equivalent behavior, and orchestration re-entry.
+
+If the supplied review cannot be completed with the available observational capabilities and current execution context, return \`REVIEW_INFRASTRUCTURE_BLOCKED\`. Do not delegate, request a helper, mutate the workspace, or claim \`PASS\` from incomplete work.
+`;
+}
+
+export function getClaudeSkillAgentDefinitions(skillName, roleManifest = null) {
+  if (skillName !== REVIEWER_ROLE_SKILL) return [];
+  return [{
+    fileName: REVIEWER_ROLE_FILE,
+    content: buildReviewerRoleDefinition(roleManifest),
+  }];
+}
+
 /**
  * Convert a core SKILL.md to Claude Code command.md format.
  * @param {string} skillContent - Content of the core SKILL.md
@@ -97,6 +160,20 @@ export async function installCommand(corePath, targetRoot) {
     for (const subdir of subdirs) {
       cpSync(path.join(corePath, subdir), path.join(targetDir, subdir), { recursive: true });
     }
+
+    // Install platform-native capability roles generated from canonical skill semantics.
+    const roleManifestPath = path.join(corePath, 'assets', 'reviewer-role.json');
+    const roleManifest = existsSync(roleManifestPath)
+      ? JSON.parse(await readFile(roleManifestPath, 'utf8'))
+      : null;
+    const agentDefinitions = getClaudeSkillAgentDefinitions(skillName, roleManifest);
+    if (agentDefinitions.length > 0) {
+      const agentsDir = path.join(targetRoot, '.claude', 'agents');
+      mkdirSync(agentsDir, { recursive: true });
+      for (const definition of agentDefinitions) {
+        await writeFile(path.join(agentsDir, definition.fileName), definition.content);
+      }
+    }
   } else {
     // Single file command
     const targetDir = path.join(targetRoot, COMMANDS_DIR);

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

@@ -11,14 +11,20 @@ from dataclasses import dataclass
 from pathlib import Path
 
 
-HIDDEN_TOOL_WORKTREE_EXCLUDES = (
+PIPELINE_TRANSIENT_EXCLUDES = (
     ":(top,exclude).prizmkit-worktree",
-    ":(top,exclude).skills-lock.json",
-    ":(top,exclude).AGENTS.md",
     ":(top,exclude,glob).*/worktree",
     ":(top,exclude,glob).*/worktree/**",
     ":(top,exclude,glob).*/worktrees",
     ":(top,exclude,glob).*/worktrees/**",
+    ":(top,exclude).prizmkit/state",
+    ":(top,exclude,glob).prizmkit/state/**",
+)
+
+HIDDEN_TOOL_WORKTREE_EXCLUDES = (
+    *PIPELINE_TRANSIENT_EXCLUDES,
+    ":(top,exclude).skills-lock.json",
+    ":(top,exclude).AGENTS.md",
     ":(top,exclude).claude",
     ":(top,exclude,glob).claude/**",
     ":(top,exclude).codebuddy",
@@ -31,12 +37,17 @@ HIDDEN_TOOL_WORKTREE_EXCLUDES = (
     ":(top,exclude,glob).prizmkit/prizm-docs/**",
     ":(top,exclude).prizmkit/config.json",
     ":(top,exclude).prizmkit/manifest.json",
-    ":(top,exclude).prizmkit/state",
-    ":(top,exclude,glob).prizmkit/state/**",
     ":(top,exclude).prizmkit/dev-pipeline",
     ":(top,exclude,glob).prizmkit/dev-pipeline/**",
 )
 
+UNTRACKED_TRANSIENT_EXCLUDES = (
+    *HIDDEN_TOOL_WORKTREE_EXCLUDES,
+    ":(top,exclude,glob)**/__pycache__",
+    ":(top,exclude,glob)**/__pycache__/**",
+    ":(top,exclude,glob)**/*.py[cod]",
+)
+
 PIPELINE_FALLBACK_GIT_NAME = "PrizmKit Pipeline"
 PIPELINE_FALLBACK_GIT_EMAIL = "prizmkit-pipeline@example.invalid"
 

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

@@ -11,10 +11,37 @@ from collections.abc import Sequence
 from dataclasses import dataclass
 from pathlib import Path
 
-from .gitops import HIDDEN_TOOL_WORKTREE_EXCLUDES, GitCommandResult, git_status_safe, run_git_command
+from .gitops import (
+    HIDDEN_TOOL_WORKTREE_EXCLUDES,
+    UNTRACKED_TRANSIENT_EXCLUDES,
+    GitCommandResult,
+    git_status_safe,
+    run_git_command,
+)
 from .runner_models import RunnerFamily
 
 
+LOCAL_ONLY_PLATFORM_PATHS = (
+    ".claude/settings.local.json",
+    ".codebuddy/settings.local.json",
+    ".codex/settings.local.json",
+    ".agents/settings.local.json",
+)
+
+
+@dataclass(frozen=True)
+class PreflightWorkspace:
+    """Exact Git paths participating in startup preservation."""
+
+    tracked: tuple[str, ...]
+    visible_untracked: tuple[str, ...]
+    unsafe_local: tuple[str, ...]
+
+    @property
+    def preservable(self) -> tuple[str, ...]:
+        return _unique_paths((*self.tracked, *self.visible_untracked))
+
+
 @dataclass(frozen=True)
 class BookkeepingResult:
     """Result from an optional bookkeeping commit boundary."""
@@ -42,6 +69,81 @@ def _repo_path(project_root: Path, path: Path) -> str:
         return path.as_posix()
 
 
+def _tracked_status_result(project_root: Path) -> GitCommandResult:
+    return run_git_command(project_root, ("status", "--porcelain=v1", "-z", "--untracked-files=no", "--", "."))
+
+
+def _untracked_status_result(project_root: Path) -> GitCommandResult:
+    return run_git_command(
+        project_root,
+        ("ls-files", "--others", "--exclude-standard", "-z", "--", ".", *UNTRACKED_TRANSIENT_EXCLUDES),
+    )
+
+
+def _unique_paths(paths: Sequence[str]) -> tuple[str, ...]:
+    return tuple(dict.fromkeys(path for path in paths if path))
+
+
+def _literal_pathspecs(paths: Sequence[str]) -> tuple[str, ...]:
+    return tuple(f":(top,literal){path}" for path in paths)
+
+
+def _status_record_paths(stdout: str) -> tuple[str, ...]:
+    """Decode exact paths from NUL-delimited porcelain-v1 records."""
+    records = stdout.split("\0")
+    changed: list[str] = []
+    index = 0
+    while index < len(records):
+        record = records[index]
+        index += 1
+        if not record:
+            continue
+        if len(record) < 4 or record[2] != " ":
+            continue
+        status = record[:2]
+        changed.append(record[3:])
+        if "R" in status or "C" in status:
+            if index < len(records) and records[index]:
+                changed.append(records[index])
+                index += 1
+    return _unique_paths(changed)
+
+
+def _preflight_workspace(project_root: Path) -> tuple[PreflightWorkspace | None, GitCommandResult | None]:
+    tracked_result = _tracked_status_result(project_root)
+    if tracked_result.return_code != 0:
+        return None, tracked_result
+    untracked_result = _untracked_status_result(project_root)
+    if untracked_result.return_code != 0:
+        return None, untracked_result
+
+    tracked = _status_record_paths(tracked_result.stdout)
+    visible_untracked = _unique_paths(untracked_result.stdout.split("\0"))
+    unsafe_local = tuple(path for path in tracked if path in LOCAL_ONLY_PLATFORM_PATHS)
+    return PreflightWorkspace(tracked, visible_untracked, unsafe_local), None
+
+
+def _preflight_failure(message: str) -> GitCommandResult:
+    return GitCommandResult(args=("status", "preflight"), return_code=1, stdout="", stderr=message)
+
+
+def _remaining_preflight_changes(project_root: Path) -> GitCommandResult:
+    workspace, failure = _preflight_workspace(project_root)
+    if failure is not None:
+        return failure
+    assert workspace is not None
+    if workspace.unsafe_local:
+        return _preflight_failure(
+            "Refusing to auto-commit local-only platform settings: " + ", ".join(workspace.unsafe_local)
+        )
+    return GitCommandResult(
+        args=("status", "preflight"),
+        return_code=0,
+        stdout="\0".join(workspace.preservable),
+        stderr="",
+    )
+
+
 def _visible_status_result(project_root: Path) -> GitCommandResult:
     return run_git_command(project_root, ("status", "--porcelain", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES))
 
@@ -85,23 +187,33 @@ def commit_bookkeeping_changes(
 
 
 def commit_preflight_ready_changes(project_root: Path, item_id: str) -> BookkeepingResult:
-    """Preserve visible pre-existing changes before task branch setup."""
-    visible_status = _visible_status_result(project_root)
-    if visible_status.return_code != 0:
-        return BookkeepingResult(attempted=True, committed=False, result=visible_status)
-    paths = _paths_from_status(visible_status.stdout)
+    """Preserve tracked changes and visible untracked files before task branch setup."""
+    workspace, failure = _preflight_workspace(project_root)
+    if failure is not None:
+        return BookkeepingResult(attempted=True, committed=False, result=failure)
+    assert workspace is not None
+    if workspace.unsafe_local:
+        return BookkeepingResult(
+            attempted=True,
+            committed=False,
+            result=_preflight_failure(
+                "Refusing to auto-commit local-only platform settings: " + ", ".join(workspace.unsafe_local)
+            ),
+        )
+    paths = workspace.preservable
     if not paths:
         return BookkeepingResult(attempted=False, committed=False)
-    add_result = run_git_command(project_root, ("add", "-A", "-f", "--", *paths))
+    pathspecs = _literal_pathspecs(paths)
+    add_result = run_git_command(project_root, ("add", "-A", "-f", "--", *pathspecs))
     if add_result.return_code != 0:
         return BookkeepingResult(attempted=True, committed=False, result=add_result)
     result = run_git_command(
         project_root,
-        ("commit", "--no-verify", "-m", f"chore: ready for {item_id}", "--", *paths),
+        ("commit", "--no-verify", "-m", f"chore: ready for {item_id}", "--", *pathspecs),
     )
     if result.return_code != 0:
         return BookkeepingResult(attempted=True, committed=False, result=result)
-    clean_result = _visible_status_result(project_root)
+    clean_result = _remaining_preflight_changes(project_root)
     if clean_result.return_code != 0 or clean_result.stdout.strip():
         return BookkeepingResult(attempted=True, committed=False, result=clean_result)
     return BookkeepingResult(attempted=True, committed=True, result=result)

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

@@ -1835,7 +1835,180 @@ def test_preflight_ready_commit_preserves_staged_unstaged_and_mixed_visible_chan
     assert visible_status == ""
 
 
-def test_preflight_ready_commit_excludes_hidden_support_assets_and_state(tmp_path):
+def test_preflight_ready_commit_handles_exact_special_and_renamed_paths(tmp_path):
+    from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
+
+    _init_bookkeeping_repo(tmp_path)
+    old_path = tmp_path / "old name -> café.txt"
+    old_path.write_text("old\n", encoding="utf-8")
+    subprocess.run(["git", "add", old_path.name], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-m", "track special path"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    new_path = tmp_path / 'new "quoted" \\ 名称.txt'
+    old_path.rename(new_path)
+    untracked_path = tmp_path / "untracked -> line\nbreak.txt"
+    untracked_path.write_text("new\n", encoding="utf-8")
+    colon_path = tmp_path / ":(glob)**.txt"
+    colon_path.write_text("literal pathspec\n", encoding="utf-8")
+
+    result = commit_preflight_ready_changes(tmp_path, "R-001")
+    committed_files = set(
+        filter(
+            None,
+            subprocess.run(
+                ["git", "diff-tree", "--no-commit-id", "--name-only", "-r", "-z", "HEAD"],
+                cwd=tmp_path,
+                check=True,
+                stdout=subprocess.PIPE,
+            ).stdout.decode().split("\0"),
+        )
+    )
+
+    assert result.committed is True
+    assert old_path.name in committed_files
+    assert new_path.name in committed_files
+    assert untracked_path.name in committed_files
+    assert colon_path.name in committed_files
+    assert _head_message(tmp_path) == "chore: ready for R-001"
+
+
+@pytest.mark.parametrize("staged", [False, True])
+def test_preflight_ready_commit_rejects_tracked_local_settings_before_checkout(tmp_path, staged):
+    from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
+
+    _init_bookkeeping_repo(tmp_path)
+    local_settings = tmp_path / ".claude" / "settings.local.json"
+    local_settings.parent.mkdir(parents=True)
+    local_settings.write_text('{"permissions": []}\n', encoding="utf-8")
+    subprocess.run(["git", "add", "-f", ".claude/settings.local.json"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-m", "track local settings"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    local_settings.write_text('{"permissions": ["secret"]}\n', encoding="utf-8")
+    if staged:
+        subprocess.run(["git", "add", ".claude/settings.local.json"], cwd=tmp_path, check=True)
+
+    result = commit_preflight_ready_changes(tmp_path, "B-001")
+
+    assert result.attempted is True
+    assert result.committed is False
+    assert result.result is not None
+    assert "Refusing to auto-commit local-only platform settings" in result.result.stderr
+    assert _head_message(tmp_path) == "track local settings"
+
+
+def test_preflight_ready_commit_excludes_untracked_python_cache_outside_support_dirs(tmp_path):
+    from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
+
+    _init_bookkeeping_repo(tmp_path)
+    (tmp_path / "visible.txt").write_text("visible\n", encoding="utf-8")
+    cache_paths = [
+        tmp_path / "__pycache__" / "top.cpython-312.pyc",
+        tmp_path / "src" / "package" / "__pycache__" / "module.cpython-312.pyc",
+        tmp_path / "src" / "standalone.pyo",
+    ]
+    for path in cache_paths:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("compiled\n", encoding="utf-8")
+
+    result = commit_preflight_ready_changes(tmp_path, "F-001")
+    committed_files = _head_files(tmp_path)
+
+    assert result.committed is True
+    assert committed_files == {"visible.txt"}
+    assert all(path.is_file() for path in cache_paths)
+
+
+def test_tracked_python_cache_remains_visible_to_task_commit(tmp_path):
+    from prizmkit_runtime.runner_bookkeeping import commit_task_branch_changes
+    from prizmkit_runtime.runner_models import family_for
+
+    paths = _make_paths(tmp_path)
+    _init_bookkeeping_repo(paths.project_root)
+    tracked_cache = paths.project_root / "src" / "__pycache__" / "module.pyc"
+    tracked_cache.parent.mkdir(parents=True)
+    tracked_cache.write_text("baseline\n", encoding="utf-8")
+    subprocess.run(["git", "add", tracked_cache.relative_to(paths.project_root).as_posix()], cwd=paths.project_root, check=True)
+    subprocess.run(["git", "commit", "-m", "track cache"], cwd=paths.project_root, check=True, stdout=subprocess.DEVNULL)
+    tracked_cache.write_text("task change\n", encoding="utf-8")
+
+    result = commit_task_branch_changes(paths.project_root, family_for("bugfix", paths), "B-001", "completed")
+
+    assert result.committed is True
+    assert tracked_cache.relative_to(paths.project_root).as_posix() in _head_files(paths.project_root)
+    assert subprocess.run(
+        ["git", "status", "--short", "--untracked-files=no"],
+        cwd=paths.project_root,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout == ""
+
+
+def test_preflight_ready_commit_includes_tracked_state_but_excludes_untracked_state(tmp_path):
+    from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
+
+    _init_bookkeeping_repo(tmp_path)
+    tracked_state = tmp_path / ".prizmkit" / "state" / "bugfix" / "B-001" / "tracked.json"
+    tracked_state.parent.mkdir(parents=True)
+    tracked_state.write_text("baseline\n", encoding="utf-8")
+    subprocess.run(["git", "add", "-f", tracked_state.relative_to(tmp_path).as_posix()], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-m", "track state"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    tracked_state.write_text("changed\n", encoding="utf-8")
+    untracked_state = tracked_state.parent / "untracked.json"
+    untracked_state.write_text("transient\n", encoding="utf-8")
+
+    result = commit_preflight_ready_changes(tmp_path, "B-001")
+
+    assert result.committed is True
+    assert tracked_state.relative_to(tmp_path).as_posix() in _head_files(tmp_path)
+    assert untracked_state.relative_to(tmp_path).as_posix() not in _head_files(tmp_path)
+
+
+def test_preflight_ready_commit_includes_tracked_framework_support_but_excludes_untracked_support_and_state(tmp_path):
+    from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
+
+    _init_bookkeeping_repo(tmp_path)
+    tracked_support_paths = [
+        tmp_path / ".prizmkit" / "manifest.json",
+        tmp_path / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime" / "runners.py",
+        tmp_path / ".claude" / "commands" / "prizmkit.md",
+    ]
+    for path in tracked_support_paths:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("installed\n", encoding="utf-8")
+    subprocess.run(
+        ["git", "add", *(path.relative_to(tmp_path).as_posix() for path in tracked_support_paths)],
+        cwd=tmp_path,
+        check=True,
+    )
+    subprocess.run(["git", "commit", "-m", "track support"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    for path in tracked_support_paths:
+        path.write_text("upgraded\n", encoding="utf-8")
+
+    untracked_support_paths = [
+        tmp_path / ".claude" / "settings.local.json",
+        tmp_path / ".prizmkit" / "dev-pipeline" / "scripts" / "__pycache__" / "runtime.pyc",
+        tmp_path / ".prizmkit" / "state" / "bugfix" / "B-001" / "status.json",
+    ]
+    for path in untracked_support_paths:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("transient\n", encoding="utf-8")
+
+    result = commit_preflight_ready_changes(tmp_path, "B-001")
+    committed_files = _head_files(tmp_path)
+
+    assert result.committed is True
+    assert {path.relative_to(tmp_path).as_posix() for path in tracked_support_paths}.issubset(committed_files)
+    assert not {path.relative_to(tmp_path).as_posix() for path in untracked_support_paths}.intersection(committed_files)
+    assert _head_message(tmp_path) == "chore: ready for B-001"
+    assert subprocess.run(
+        ["git", "status", "--short", "--untracked-files=no"],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout == ""
+
+
+def test_preflight_ready_commit_excludes_untracked_support_assets_and_state(tmp_path):
     from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
 
     _init_bookkeeping_repo(tmp_path)
@@ -1882,23 +2055,38 @@ def test_preflight_ready_commit_noops_when_workspace_has_no_visible_dirty_conten
     assert _head_commit_count(tmp_path) == before_count
 
 
-def test_process_item_creates_one_ready_commit_before_branch_setup_for_mixed_visible_changes(monkeypatch, tmp_path):
+@pytest.mark.parametrize(
+    ("kind", "item_id", "branch"),
+    [
+        ("feature", "F-001", "dev/F-001-ready"),
+        ("bugfix", "B-001", "bugfix/B-001-ready"),
+        ("refactor", "R-001", "refactor/R-001-ready"),
+    ],
+)
+def test_process_item_creates_one_ready_commit_before_branch_setup_for_all_families(
+    monkeypatch,
+    tmp_path,
+    kind,
+    item_id,
+    branch,
+):
     from prizmkit_runtime import runner_bookkeeping, runners
     from prizmkit_runtime.gitops import HIDDEN_TOOL_WORKTREE_EXCLUDES
     from prizmkit_runtime.runner_models import family_for, parse_invocation
 
-    paths = _make_paths(tmp_path)
+    paths = _make_paths(tmp_path / kind)
     _init_bookkeeping_repo(paths.project_root)
     (paths.project_root / "staged.txt").write_text("staged before run\n", encoding="utf-8")
     subprocess.run(["git", "add", "staged.txt"], cwd=paths.project_root, check=True)
     (paths.project_root / "unstaged.txt").write_text("unstaged before run\n", encoding="utf-8")
+    (paths.project_root / "untracked.txt").write_text("untracked before run\n", encoding="utf-8")
     before_count = _head_commit_count(paths.project_root)
     branch_events = []
 
-    monkeypatch.setenv("DEV_BRANCH", "dev/F-001-ready")
-    family = family_for("feature", paths)
+    monkeypatch.setenv("DEV_BRANCH", branch)
+    family = family_for(kind, paths)
     invocation = parse_invocation(family, "run", ())
-    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": family.plan_path})
     _install_runner_session_fakes(monkeypatch, runners)
     monkeypatch.setattr(runners, "commit_preflight_ready_changes", runner_bookkeeping.commit_preflight_ready_changes)
 
@@ -1921,18 +2109,18 @@ def test_process_item_creates_one_ready_commit_before_branch_setup_for_mixed_vis
 
     monkeypatch.setattr(runners, "run_git_plan", fake_run_git_plan)
 
-    status = runners._process_item(family, invocation, "F-001", paths, initial_metadata={})
+    status = runners._process_item(family, invocation, item_id, paths, initial_metadata={})
 
     assert status == "completed"
     assert branch_events == [
         {
             "commit_count": before_count + 1,
-            "message": "chore: ready for F-001",
+            "message": f"chore: ready for {item_id}",
             "visible_status": "",
         }
     ]
     assert _head_commit_count(paths.project_root) == before_count + 1
-    assert {"staged.txt", "unstaged.txt"}.issubset(_head_files(paths.project_root))
+    assert {"staged.txt", "unstaged.txt", "untracked.txt"}.issubset(_head_files(paths.project_root))
 
 
 

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

@@ -811,14 +811,21 @@ def test_session_preamble_writes_redacted_start_command_for_all_launch_profiles(
             assert str(prompt) not in "\n".join(lines[:6])
 
 
-def test_headless_review_guidance_uses_workspace_equivalence_protocol():
-    guidance_files = [
+def test_headless_review_guidance_uses_workspace_and_execution_protocols():
+    headless_guidance_files = [
         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",
     ]
+    skill_path = (
+        REPO_ROOT
+        / "core"
+        / "skills"
+        / "prizmkit-skill"
+        / "prizmkit-code-review"
+        / "SKILL.md"
+    )
 
-    for path in guidance_files:
+    for path in headless_guidance_files:
         text = path.read_text(encoding="utf-8")
         assert "platform-supported" in text, path
         assert "snapshot" in text and "equivalent" in text, path
@@ -828,15 +835,17 @@ def test_headless_review_guidance_uses_workspace_equivalence_protocol():
         assert ".prizmkit/state/worktrees/..." not in text, path
         assert "USE_WORKTREE" not in text, path
         assert "isolation:" not in text, path
+        assert "Read existing source files in the modules this plan touches" not in text, path
 
-    skill_text = guidance_files[-1].read_text(encoding="utf-8")
+    skill_text = skill_path.read_text(encoding="utf-8")
     assert "reviewer-workspace-protocol.md" in skill_text
+    assert "reviewer-execution-protocol.md" in skill_text
     assert "staged, unstaged, untracked, deleted, and renamed" in skill_text
+    assert "content-equivalent" in skill_text
     assert "WORKSPACE_MISMATCH" in skill_text
-
-    for path in guidance_files[:-1]:
-        text = path.read_text(encoding="utf-8")
-        assert "Read existing source files in the modules this plan touches" not in text, path
+    assert "REVIEW_INFRASTRUCTURE_BLOCKED" in skill_text
+    assert "do not substitute Main-Agent self-review" in skill_text
+    assert "platform-specific role" in skill_text
 
 
 def test_progress_parser_adds_required_metadata(tmp_path):
@@ -2109,7 +2118,7 @@ def test_preflight_ready_commit_skips_hidden_support_asset_only_changes(tmp_path
     assert (repo / ".claude" / "settings.local.json").is_file()
 
 
-def test_preflight_ready_commit_excludes_already_staged_hidden_support_assets(tmp_path):
+def test_preflight_ready_commit_includes_explicitly_staged_support_assets(tmp_path):
     from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
 
     repo = tmp_path / "repo"
@@ -2123,8 +2132,8 @@ def test_preflight_ready_commit_excludes_already_staged_hidden_support_assets(tm
 
     assert result.committed
     assert _head_commit_message(repo) == "chore: ready for F-005"
-    assert _head_files(repo) == {"visible.txt"}
-    assert "A  .claude/agent.md" in _short_status(repo)
+    assert _head_files(repo) == {".claude/agent.md", "visible.txt"}
+    assert _short_status(repo) == ""
 
 
 def test_preflight_ready_commit_excludes_ignored_tool_worktree_directories(tmp_path):

package/bundled/skills/_metadata.json

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