claude-dev-env 2.5.0 → 2.7.1

package/_shared/pr-loop/scripts/code_rules_gate_parts/tests/test_staged_test_running.py

@@ -1,53 +1,43 @@
 """Behavioral tests for the staged_test_running parts module."""
 
-import subprocess
 from pathlib import Path
 
-from code_rules_gate_parts import git_file_sets, staged_test_running
+import pytest
 
-
-def _git(repository_root: Path, *arguments: str) -> None:
-    subprocess.run(
-        ["git", *arguments],
-        cwd=str(repository_root),
-        check=True,
-        capture_output=True,
-        env=git_file_sets.repository_environment(),
-    )
+from code_rules_gate_parts import staged_test_running
+from code_rules_gate_parts.tests._repo_test_helpers import repository_root_without_pytest_config
 
 
-def _init_repository(repository_root: Path) -> None:
-    _git(repository_root, "init", "--initial-branch=main")
-    _git(repository_root, "config", "user.email", "test@example.com")
-    _git(repository_root, "config", "user.name", "Test")
-    _git(repository_root, "config", "commit.gpgsign", "false")
-    (repository_root / "seed.txt").write_text("seed\n", encoding="utf-8")
-    _git(repository_root, "add", "-A")
-    _git(repository_root, "commit", "-m", "seed")
+def _write_pytest_config(directory: Path) -> None:
+    """Write a minimal ``pytest.ini`` into *directory*, creating it when absent."""
+    directory.mkdir(parents=True, exist_ok=True)
+    (directory / "pytest.ini").write_text("[pytest]\n", encoding="utf-8")
 
 
-def _write_and_stage(repository_root: Path, relative_path: str, file_text: str) -> Path:
+def _write_test_file(repository_root: Path, relative_path: str) -> Path:
+    """Write a trivially passing test module at *relative_path* and return its path."""
     file_path = repository_root / relative_path
     file_path.parent.mkdir(parents=True, exist_ok=True)
-    file_path.write_text(file_text, encoding="utf-8")
-    _git(repository_root, "add", "--", relative_path)
+    file_path.write_text(
+        "def test_placeholder() -> None:\n    assert True\n", encoding="utf-8"
+    )
     return file_path
 
 
-def _repository_with_root_pytest_config(tmp_path: Path) -> Path:
-    repository_root = tmp_path / "repo"
-    repository_root.mkdir()
-    _init_repository(repository_root)
-    (repository_root / "pytest.ini").write_text("[pytest]\n", encoding="utf-8")
-    return repository_root
+def _refuse_to_resolve(monkeypatch: pytest.MonkeyPatch, refused_path: Path) -> None:
+    """Make ``Path.resolve`` raise ``OSError`` for *refused_path* and nothing else.
 
+    Stands in for a staged file the filesystem accepts as a file yet refuses to
+    resolve, such as a broken junction or a path the user may not traverse.
+    """
+    original_resolve = Path.resolve
 
-def test_run_staged_test_files_returns_zero_when_nothing_staged(tmp_path: Path) -> None:
-    repository_root = tmp_path / "repo"
-    repository_root.mkdir()
-    _init_repository(repository_root)
+    def _resolve_unless_refused(each_path: Path, strict: bool = False) -> Path:
+        if each_path == refused_path:
+            raise OSError("resolve refused")
+        return original_resolve(each_path, strict=strict)
 
-    assert staged_test_running.run_staged_test_files(repository_root) == 0
+    monkeypatch.setattr(Path, "resolve", _resolve_unless_refused)
 
 
 def test_batched_pytest_arguments_splits_over_the_budget() -> None:
@@ -73,44 +63,87 @@ def test_pytest_target_paths_drops_conftest_and_keeps_real_tests() -> None:
     assert all_targets == [Path("pkg_a/test_alpha.py")]
 
 
-def test_run_staged_test_files_returns_zero_when_only_multiple_confests_staged(
+def test_group_staged_tests_by_root_splits_config_less_top_level_directories(
     tmp_path: Path,
 ) -> None:
-    repository_root = _repository_with_root_pytest_config(tmp_path)
-    _write_and_stage(repository_root, "pkg_a/conftest.py", "import pytest\n")
-    _write_and_stage(repository_root, "pkg_b/conftest.py", "import pytest\n")
-    _write_and_stage(
-        repository_root, "pkg_c/tests/conftest.py", "import pytest\n"
+    repository_root = repository_root_without_pytest_config(tmp_path)
+    alpha_test_path = _write_test_file(repository_root, "alpha_package/tests/test_alpha.py")
+    beta_test_path = _write_test_file(repository_root, "beta_package/tests/test_beta.py")
+
+    all_tests_by_root = staged_test_running._group_staged_tests_by_root(
+        [alpha_test_path, beta_test_path], repository_root
     )
 
-    assert staged_test_running.run_staged_test_files(repository_root) == 0
+    assert all_tests_by_root == {
+        (repository_root / "alpha_package").resolve(): [alpha_test_path],
+        (repository_root / "beta_package").resolve(): [beta_test_path],
+    }
 
 
-def test_run_staged_test_files_passes_when_confests_stage_with_passing_test(
+def test_group_staged_tests_by_root_places_every_input_in_exactly_one_group(
     tmp_path: Path,
 ) -> None:
-    repository_root = _repository_with_root_pytest_config(tmp_path)
-    _write_and_stage(repository_root, "pkg_a/conftest.py", "import pytest\n")
-    _write_and_stage(repository_root, "pkg_b/conftest.py", "import pytest\n")
-    _write_and_stage(
-        repository_root,
-        "pkg_a/test_alpha.py",
-        "def test_alpha_passes() -> None:\n    assert True\n",
+    repository_root = repository_root_without_pytest_config(tmp_path)
+    _write_pytest_config(repository_root / "configured_package")
+    all_staged_test_paths = [
+        _write_test_file(repository_root, "configured_package/suite/test_configured.py"),
+        _write_test_file(repository_root, "alpha_package/tests/test_alpha.py"),
+        _write_test_file(repository_root, "alpha_package/tests/test_second_alpha.py"),
+        _write_test_file(repository_root, "beta_package/test_beta.py"),
+        _write_test_file(repository_root, "test_at_repository_root.py"),
+    ]
+
+    all_tests_by_root = staged_test_running._group_staged_tests_by_root(
+        all_staged_test_paths, repository_root
     )
 
-    assert staged_test_running.run_staged_test_files(repository_root) == 0
+    all_grouped_test_paths = [
+        each_path for each_group in all_tests_by_root.values() for each_path in each_group
+    ]
+    assert sorted(all_grouped_test_paths) == sorted(all_staged_test_paths)
 
 
-def test_run_staged_test_files_fails_when_real_test_fails_alongside_confests(
+def test_group_staged_tests_by_root_groups_at_the_config_owning_ancestor(
     tmp_path: Path,
 ) -> None:
-    repository_root = _repository_with_root_pytest_config(tmp_path)
-    _write_and_stage(repository_root, "pkg_a/conftest.py", "import pytest\n")
-    _write_and_stage(repository_root, "pkg_b/conftest.py", "import pytest\n")
-    _write_and_stage(
-        repository_root,
-        "pkg_a/test_alpha.py",
-        "def test_alpha_fails() -> None:\n    assert False\n",
+    repository_root = repository_root_without_pytest_config(tmp_path)
+    configured_package_root = repository_root / "configured_package"
+    _write_pytest_config(configured_package_root)
+    nested_test_path = _write_test_file(
+        repository_root, "configured_package/suite/test_configured.py"
+    )
+
+    all_tests_by_root = staged_test_running._group_staged_tests_by_root(
+        [nested_test_path], repository_root
+    )
+
+    assert all_tests_by_root == {configured_package_root.resolve(): [nested_test_path]}
+
+
+def test_group_staged_tests_by_root_keeps_a_repository_root_file_at_the_root(
+    tmp_path: Path,
+) -> None:
+    repository_root = repository_root_without_pytest_config(tmp_path)
+    root_level_test_path = _write_test_file(repository_root, "test_at_repository_root.py")
+
+    all_tests_by_root = staged_test_running._group_staged_tests_by_root(
+        [root_level_test_path], repository_root
+    )
+
+    assert all_tests_by_root == {repository_root.resolve(): [root_level_test_path]}
+
+
+def test_group_staged_tests_by_root_falls_back_to_the_root_when_resolve_raises(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    repository_root = repository_root_without_pytest_config(tmp_path)
+    unresolvable_test_path = _write_test_file(
+        repository_root, "alpha_package/tests/test_alpha.py"
+    )
+    _refuse_to_resolve(monkeypatch, unresolvable_test_path)
+
+    all_tests_by_root = staged_test_running._group_staged_tests_by_root(
+        [unresolvable_test_path], repository_root
     )
 
-    assert staged_test_running.run_staged_test_files(repository_root) != 0
+    assert all_tests_by_root == {repository_root.resolve(): [unresolvable_test_path]}

package/_shared/pr-loop/scripts/pr_loop_shared_constants/code_rules_gate_constants.py

@@ -146,3 +146,205 @@ STAGED_TEST_GROUP_FAILURE_MESSAGE: str = (
 MINIMUM_STAGED_PYTEST_PYTHON_MAJOR: int = 3
 
 MINIMUM_STAGED_PYTEST_PYTHON_MINOR: int = 12
+
+JUNIT_XML_FLAG_PREFIX: str = "--junitxml="
+
+JUNIT_XML_TESTCASE_TAG: str = "testcase"
+
+JUNIT_XML_FAILURE_TAG: str = "failure"
+
+JUNIT_XML_ERROR_TAG: str = "error"
+
+JUNIT_XML_CLASSNAME_ATTRIBUTE: str = "classname"
+
+JUNIT_XML_NAME_ATTRIBUTE: str = "name"
+
+JUNIT_XML_MISSING_ATTRIBUTE_FALLBACK: str = ""
+
+REGRESSION_JUNIT_TEMP_DIRECTORY_PREFIX: str = "code_rules_gate_junit_"
+
+REGRESSION_STAGED_JUNIT_SUBDIRECTORY_NAME: str = "staged"
+
+REGRESSION_BASELINE_JUNIT_SUBDIRECTORY_NAME: str = "baseline"
+
+REGRESSION_BASELINE_WORKTREE_TEMP_DIRECTORY_PREFIX: str = "code_rules_gate_baseline_"
+
+REGRESSION_BASELINE_WORKTREE_DIRECTORY_NAME: str = "tree"
+
+GIT_HEAD_REVISION: str = "HEAD"
+
+ALL_GIT_HEAD_EXISTS_ARGS: tuple[str, ...] = ("rev-parse", "--verify", "HEAD")
+
+ALL_GIT_WORKTREE_ADD_DETACH_ARGS: tuple[str, ...] = (
+    "worktree",
+    "add",
+    "--detach",
+    "--quiet",
+)
+
+ALL_GIT_WORKTREE_REMOVE_FORCE_ARGS: tuple[str, ...] = ("worktree", "remove", "--force")
+
+ALL_GIT_WORKTREE_PRUNE_ARGS: tuple[str, ...] = ("worktree", "prune")
+
+REGRESSION_NO_BASELINE_MESSAGE: str = (
+    "code_rules_gate: no prior commit to compare against (first commit on this branch); "
+    "every staged test failure blocks."
+)
+
+REGRESSION_WORKTREE_ADD_FAILED_MESSAGE: str = (
+    "code_rules_gate: could not open a detached HEAD worktree for the pre-staged baseline "
+    "(git worktree add --detach failed); falling back to blocking on every staged test "
+    "failure."
+)
+
+REGRESSION_WORKTREE_REMOVE_FAILED_MESSAGE: str = (
+    "code_rules_gate: git worktree remove --force failed after the baseline check — your "
+    "staged changes are untouched in this worktree. Run 'git worktree list' and "
+    "'git worktree prune' if a temporary baseline tree remains registered."
+)
+
+REGRESSION_PRE_EXISTING_FAILURE_BYPASSED_MESSAGE: str = (
+    "code_rules_gate: staged test group rooted at {group_root} has {count} failure(s) "
+    "already present before this change (not caused by it); not blocking."
+)
+
+REGRESSION_GROUP_FAILURE_MESSAGE: str = (
+    "code_rules_gate: staged test group rooted at {group_root} has {count} failure(s) "
+    "this change introduces; commit blocked."
+)
+
+BASELINE_LEAK_PLUGIN_DIRECTORY_NAME: str = "baseline_import_plugin"
+
+BASELINE_LEAK_PLUGIN_MODULE_NAME: str = "code_rules_gate_baseline_import_plugin"
+
+BASELINE_LEAK_REPORT_FILENAME: str = "imported_from_primary_tree.json"
+
+BASELINE_PRIMARY_ROOT_ENV_VAR: str = "CODE_RULES_GATE_BASELINE_PRIMARY_ROOT"
+
+BASELINE_LEAK_REPORT_ENV_VAR: str = "CODE_RULES_GATE_BASELINE_LEAK_REPORT"
+
+PYTEST_PLUGINS_ENV_VAR: str = "PYTEST_PLUGINS"
+
+PYTEST_PLUGINS_SEPARATOR: str = ","
+
+BASELINE_IMPORT_PROBE_TIMEOUT_SECONDS: int = 120
+
+BASELINE_IMPORT_PROBE_DEGRADED_TAIL: str = (
+    "The HEAD baseline runs with its import roots un-rebased; a module that still "
+    "resolves into your working tree is reported after that run and blocks the group."
+)
+
+BASELINE_IMPORT_PROBE_TIMED_OUT_MESSAGE: str = (
+    "code_rules_gate: the import-root probe did not finish within {seconds} seconds. "
+    + BASELINE_IMPORT_PROBE_DEGRADED_TAIL
+)
+
+BASELINE_IMPORT_PROBE_UNSTARTABLE_MESSAGE: str = (
+    "code_rules_gate: the import-root probe did not start ({reason}). "
+    + BASELINE_IMPORT_PROBE_DEGRADED_TAIL
+)
+
+BASELINE_IMPORT_PROBE_REJECTED_MESSAGE: str = (
+    "code_rules_gate: the import-root probe exited with status {status}. "
+    + BASELINE_IMPORT_PROBE_DEGRADED_TAIL
+)
+
+PYTHON_INTERPRETER_COMMAND_FLAG: str = "-c"
+
+BASELINE_IMPORT_ROOT_PROBE_SOURCE: str = (
+    "import json\n"
+    "import sys\n"
+    "from pathlib import Path\n"
+    "all_roots = [each_entry for each_entry in sys.path if each_entry]\n"
+    "for each_finder in list(sys.meta_path):\n"
+    "    owning_module = sys.modules.get(getattr(each_finder, '__module__', '') or '')\n"
+    "    for each_attribute in ('MAPPING', 'NAMESPACES'):\n"
+    "        mapping = getattr(owning_module, each_attribute, None)\n"
+    "        if not isinstance(mapping, dict):\n"
+    "            continue\n"
+    "        for each_name, each_target in mapping.items():\n"
+    "            all_targets = each_target if isinstance(each_target, list) else [each_target]\n"
+    "            for each_package_directory in all_targets:\n"
+    "                try:\n"
+    "                    all_roots.append(\n"
+    "                        str(Path(each_package_directory).parents[str(each_name).count('.')])\n"
+    "                    )\n"
+    "                except (IndexError, TypeError, OSError):\n"
+    "                    continue\n"
+    "print(json.dumps(all_roots))\n"
+)
+
+BASELINE_LEAK_PLUGIN_SOURCE: str = '''"""Report every module the baseline pytest run imported out of the user's own tree."""
+
+import json
+import os
+import sys
+import sysconfig
+from pathlib import Path
+
+PRIMARY_ROOT_ENV_VAR = "{primary_root_env_var}"
+REPORT_PATH_ENV_VAR = "{report_path_env_var}"
+
+
+def _resolved(path_text):
+    if not path_text:
+        return None
+    try:
+        return Path(path_text).resolve()
+    except OSError:
+        return None
+
+
+def _is_under(candidate, root):
+    return candidate == root or root in candidate.parents
+
+
+def _interpreter_roots():
+    all_texts = [sys.prefix, sys.base_prefix, *sysconfig.get_paths().values()]
+    all_roots = [_resolved(each_text) for each_text in all_texts]
+    return [each_root for each_root in all_roots if each_root is not None]
+
+
+def _already_reported(report_path):
+    try:
+        return set(json.loads(report_path.read_text(encoding="utf-8")))
+    except (OSError, ValueError):
+        return set()
+
+
+def _imported_from_primary_tree(primary_root, report_path):
+    all_interpreter_roots = _interpreter_roots()
+    all_leaked = _already_reported(report_path)
+    for each_module in list(sys.modules.values()):
+        module_path = _resolved(getattr(each_module, "__file__", None))
+        if module_path is None or not _is_under(module_path, primary_root):
+            continue
+        if any(_is_under(module_path, each_root) for each_root in all_interpreter_roots):
+            continue
+        all_leaked.add(str(module_path))
+    return sorted(all_leaked)
+
+
+def pytest_sessionfinish(session, exitstatus):
+    primary_root = _resolved(os.environ.get(PRIMARY_ROOT_ENV_VAR))
+    report_path = _resolved(os.environ.get(REPORT_PATH_ENV_VAR))
+    if primary_root is None or report_path is None:
+        return
+    report_path.write_text(
+        json.dumps(_imported_from_primary_tree(primary_root, report_path)), encoding="utf-8"
+    )
+'''
+
+REGRESSION_BASELINE_IMPORT_LEAK_MESSAGE: str = (
+    "code_rules_gate: the HEAD baseline run for the group rooted at {group_root} imported "
+    "{count} module(s) from your working tree, starting with {first_module}. It measured the "
+    "staged code, not HEAD, so that baseline is not trusted and every staged failure in this "
+    "group blocks. An editable install whose import hook runs ahead of the path scan is the "
+    "usual cause."
+)
+
+REGRESSION_BASELINE_LEAK_UNREPORTED_MESSAGE: str = (
+    "code_rules_gate: the HEAD baseline run for the group rooted at {group_root} wrote no "
+    "import-origin report, so whether it loaded your working-tree code is unknown. That "
+    "baseline is not trusted and every staged failure in this group blocks."
+)

package/_shared/pr-loop/worker-spawn.md

@@ -73,10 +73,12 @@ plus the process exit code.
 
 `resolve_worker_spawn(...)` takes keyword-only arguments:
 `role`, `prompt_file`, `working_directory`, `timeout_seconds`,
-`is_claude_tier_enabled`, `run_state_directory`, `max_turns`.
+`is_claude_tier_enabled`, `run_state_directory`.
 `encode_spawn_outcome` turns a `SpawnOutcome` into the same JSON shape the CLI
 prints.
 
+The grok tier runs with no turn cap; `timeout_seconds` is its only bound.
+
 ## JSON result shape
 
 Stdout is one JSON object:

package/agents/CLAUDE.md

@@ -11,7 +11,7 @@ Agent definition files installed into `~/.claude/agents/` by `bin/install.mjs`.
 | `clean-coder.md` | Clean Coder | Primary code-writing agent; internalizes CODE_RULES.md and targets zero `/check` findings |
 | `code-advisor.md` | Code Advisor | Single-executor mid-run advisor (PLAN/CORRECTION/STOP as final text); distinct from session-advisor |
 | `code-quality-agent.md` | Code Quality Agent | Multi-file code quality review across an entire diff or set of files |
-| `code-verifier.md` | Code Verifier | Post-hoc verification after coder agents finish; read-only, fresh context, puts the draft verdict through one strongest-tier validation subagent, ends with a fenced verdict |
+| `code-verifier.md` | Code Verifier | Post-hoc verification after coder agents finish; never edits files in the verified tree, with one exception, a deliberate break at an off-tree break site outside it, defined in the agent body; fresh context, puts the draft verdict through one strongest-tier validation subagent, ends with a fenced verdict; `all_pass` true needs a complete shown-red table as well as clean layers |
 | `deep-research.md` | Deep Research | Citation-grounded research with web search |
 | `docs-agent.md` | Docs Agent | Documentation authoring and maintenance |
 | `git-commit-crafter.md` | Git Commit Crafter | Stages changes, writes conventional commit messages, creates commits |

package/agents/code-verifier.md

@@ -1,6 +1,6 @@
 ---
 name: code-verifier
-description: Post-hoc verification agent for the three-phase code workflow. Spawned by the main session after coder agents finish. Runs every check itself in a fresh context — named gates, tests against recorded baselines, two-way diff-vs-task reading — puts the draft verdict through one strongest-tier validation subagent that tries to refute it, then ends with a fenced verdict block the verifier_verdict_minter hook turns into the commit-gate verdict. Read and execute only; it never edits files.
+description: Post-hoc verification agent for the three-phase code workflow. Spawned by the main session after coder agents finish. Runs every check itself in a fresh context — named gates, tests against recorded baselines, two-way diff-vs-task reading — puts the draft verdict through one strongest-tier validation subagent that tries to refute it, then ends with a fenced verdict block the verifier_verdict_minter hook turns into the commit-gate verdict. Never edits files in the tree under review — its one exception is a deliberate break at an off-tree break site outside that tree, defined in its body.
 tools: Read, Grep, Glob, Bash, Task
 color: orange
 ---
@@ -17,9 +17,10 @@ Run all three layers, in this order:
 
 Findings discipline:
 
-- A finding must cite a failing command (with its output) or a named task item. No citation, no finding.
+- A finding must cite a failing command (with its output) or a named task item. No citation, no finding. `findings` carries code defects alone.
 - Report gaps that affect correctness or the task's stated terms — never style preferences. Sound work produces zero findings; do not invent gaps to look thorough.
-- Never edit a file. You verify; repair agents repair.
+- Never edit a file in the work tree you verify — you verify; repair agents repair. The one exception is a deliberate break for the shown-red table, which goes at one of the off-tree break sites the shown-red section below lists.
+- Never run `git stash`. `refs/stash` belongs to the repository, not to a work tree, so every worktree shares one stash list: a `pop` can apply another verifier's entry into your tree and hand you a surface that is not your assignment. To read the base, add a throwaway detached worktree at the base commit (`git worktree add --detach <temp-path> <base-sha>`), read it there, and drop it with `git worktree remove --force <temp-path>`. You only ever need to read a base tree, and stash moves the very tree you were asked to verify.
 - Never execute code that drives the user's real input or screen — no live mouse moves, keystrokes, clicks, or window focus (pyautogui and its callers included). Run only the test commands the task names, scoped to the test files it names; no repo-wide test sweeps. Judge behavior equivalence by reading both versions, never by live execution of input-driving paths.
 
 Before you write the verdict, learn the surface hash of the work tree you verified. Use the branch mode — it resolves the work tree that holds the branch automatically, so it is immune to your own cwd:
@@ -32,14 +33,42 @@ On Windows the same file sits at %USERPROFILE%\.claude\hooks\blocking\verificati
 
 The printed hash commits to every changed and untracked file's content in the verified work tree, so it names that surface no matter which directory you or the committer run from. If the CLI prints an empty-surface or wrong-work-tree error and no hash, you are pointed at a work tree with no changes versus origin/main — re-run with the branch mode to locate the correct work tree.
 
-As the last step before the verdict, put your draft verdict through one best-effort strongest-tier validation pass. Spawn a single validation subagent through the Task tool as the `Explore` agent type at the strongest reachable tier: set the Task `subagent_type` to `Explore`, detect the host profile first per `~/.claude/_shared/advisor/advisor-protocol.md` — the source of truth for host detection, the ladder, and its aliases — then on a Claude host pick the strongest reachable tier on the Fable → Opus → Sonnet → Haiku ladder and on a third-party host use the single third-party tier, and set the Task `model:` field to that tier's alias. The `Explore` type carries no Edit or Write tools and cannot spawn further agents, so the harness itself holds the validator to the no-edit, no-spawn contract the next paragraph names. Hand it the draft verdict together with your evidence — every command you ran with its output, and your two-way diff-to-task mapping — and state that its task is adversarial verification of that supplied draft verdict: refute it against the supplied evidence rather than discover code, naming any gate you misread, any task item you mapped wrong, or any finding that does not hold. This pass is always a cold `Explore` spawn, not a message to the session's warm advisor: the refutation needs a grader with no accumulated session context or prior positions, and the verifier runs in sessions that have no advisor bound. When the spawn is unavailable — a Task tool error, an unreachable tier at every rung, or this subagent being barred from spawning further agents — skip the validation pass and emit the draft verdict as it stands, noting the skip in your final message; a spawn failure never blocks the verdict fence from being emitted.
+As the last step before the verdict, put your draft verdict through one best-effort strongest-tier validation pass. Spawn a single validation subagent through the Task tool as the `Explore` agent type at the strongest reachable tier: set the Task `subagent_type` to `Explore`, detect the host profile first per `~/.claude/_shared/advisor/advisor-protocol.md` — the source of truth for host detection, the ladder, and its aliases — then on a Claude host pick the strongest reachable tier on the Fable → Opus → Sonnet → Haiku ladder and on a third-party host use the single third-party tier, and set the Task `model:` field to that tier's alias. A tier denied by policy counts as unreachable, so the walk continues down the ladder to the next tier rather than skipping the validation pass. The `Explore` type carries no Edit or Write tools and cannot spawn further agents, so the harness itself holds the validator to the no-edit, no-spawn contract the next paragraph names. Hand it the draft verdict together with your evidence — every command you ran with its output, your two-way diff-to-task mapping, and the shown-red table with every deliberate-red run labeled as shown-red evidence so the validator reads it as a staged break rather than a genuine failure — and state that its task is adversarial verification of that supplied draft verdict: refute it against the supplied evidence rather than discover code, naming any gate you misread, any task item you mapped wrong, or any finding that does not hold. This pass is always a cold `Explore` spawn, not a message to the session's warm advisor: the refutation needs a grader with no accumulated session context or prior positions, and the verifier runs in sessions that have no advisor bound. Run that spawn synchronously — set the Task `run_in_background` field to `false` — so the validator's reply lands inside this turn. A background spawn returns straight away and its completion notification arrives after your turn is over, so the reply you are waiting for never reaches you and the verdict fence never gets written. When the spawn is unavailable — a Task tool error, an unreachable tier at every rung, or this subagent being barred from spawning further agents — skip the validation pass and emit the draft verdict as it stands, noting the skip in your final message; a spawn failure never blocks the verdict fence from being emitted.
 
-This validation pass is terminal: the `Explore` type gives the validation subagent no way to spawn a further agent or edit a file, so it answers with prose only. When it refutes any part, re-check that part yourself against the commands and the diff, and correct the verdict before you emit it. When it refutes nothing, the draft verdict stands. Then emit the fenced verdict block below — it stays the last thing in your message so the verifier_verdict_minter hook reads it.
+Ending your turn without the verdict fence throws the whole run away: every gate you ran and every mapping you built reaches the caller as prose it cannot mint, and the commit gate stays shut on work you already checked. So the fence is unconditional. A validator that returns nothing usable, a tier that never binds, a refutation you accept and fold in — each of those ends the same way, with the fence. When you find yourself about to close on a promise to finish once something reports back, run the refutation pass yourself and emit the verdict.
 
-End your final message with exactly one fenced verdict block — the verifier_verdict_minter hook parses it, binds it to that hash, and the verified_commit_gate hook unlocks `git commit`/`git push` for any work tree whose live surface matches it:
+This validation pass is terminal: the `Explore` type gives the validation subagent no way to spawn a further agent or edit a file, so it answers with prose only. When it refutes any part, re-check that part yourself against the commands and the diff, and correct the verdict before you emit it. When it refutes nothing, the draft verdict stands. Then write your final message.
+
+Your final message runs in one order: the shown-red table, then — only when the verdict is incomplete — the named unshown check, then every `no break available` row named, then the verdict fence last, so the verifier_verdict_minter hook reads it. Every runnable check the verdict rests on gets one row — a runnable check is a layer 1 runnable gate you can execute against the surface. Breakability is not part of that definition: no check leaves the runnable set by being called unbreakable.
+
+| Check | Deliberate break | Red | Green |
+|---|---|---|---|
+| `<command you ran>` | `<break you applied>`, or `no break available — <why no input, no environment, and no scratch-copy mutation can make this check fail>`, or `n/a — check not run` | `<exit code or the deciding line>`, or `no red` | `<exit code or the deciding line>` |
+
+The Deliberate break cell holds exactly one of those three values: the break you applied, `no break available` with its one-line reason, or `n/a — check not run`. Only the first of the three produced a red, so only the first carries a red result in the Red cell. A `no break available` row and an `n/a — check not run` row each carry the literal `no red` there — never an empty cell, never the Green value repeated, and never an exit code, which would make a row that showed no red scan like one that did.
+
+Keep each cell to one line — an exit code, a failing test id, an assert line, or a hook's block message. The Green cell may cite the check's first clean run when you kept that output; a clean result already in hand needs no third run. Longer excerpts go below the table in a plain fenced block carrying no info string.
+
+The reading layers, 2 and 3 above, take no rows. Name in prose what you read and what that reading would catch. A runnable check keeps its row whatever you conclude by reading it, and whatever you conclude about breaking it.
+
+Break the check at an off-tree break site — a site where the break cannot reach the tree you verify: a failing input or environment fed to the check, or a mutated copy in a scratch directory outside that tree.
+
+At either off-tree break site, a check that exercises the changed behavior fails because of the break rather than for an unrelated reason.
+
+Break off-tree so the work tree under verification stays as the coders left it; an in-place break moves the surface `manifest_sha256` names and is forbidden. The green is that same check run against the verified tree.
+
+Every runnable check the verdict rests on gets a row, with no exclusion path: a rested-on runnable check with no row makes the verdict incomplete, and a check you judge unbreakable still owes its row. Where no runnable check the verdict depends on exists, the surface rests on the reading layers alone and carries an empty table, complete. The empty table is for a surface where nothing runnable exists at all, never for one where a runnable check exists and you skipped it. A row carrying `n/a — check not run` is a runnable check you relied on and never showed red, and it makes the verdict incomplete too; its Red cell carries `no red`.
+
+`no break available` is a different claim from `n/a — check not run`: the check ran, and no break exists for it, so its Red cell carries `no red` as well. That row counts complete when it carries the one-line reason naming why no input, no environment, and no scratch-copy mutation can make that check fail, so `all_pass` true stays reachable for a genuinely unbreakable gate. A `no break available` row without that reason is an incomplete row and makes the verdict incomplete exactly as a missing row does.
+
+An incomplete verdict names the unshown check directly above the fence and sets `all_pass` to false. Naming a `no break available` row is a separate matter from that incomplete-check naming: a verdict carrying any `no break available` row names each of those rows directly above the fence because the row carries no red, whether the verdict is otherwise complete or incomplete, and naming one never by itself makes the verdict incomplete or sets `all_pass` false. `findings` goes on carrying every code defect the run found, and is empty only when the run found none.
+
+Write the table as plain markdown; the fence holds JSON alone.
+
+Exactly one fenced verdict block — the verifier_verdict_minter hook parses it, binds it to that hash, and the verified_commit_gate hook unlocks `git commit`/`git push` for any work tree whose live surface matches it:
 
 ```verdict
 {"all_pass": false, "findings": [{"check": "<gate or task item>", "detail": "<command + output, or the named task item and what is missing>"}], "manifest_sha256": "<hash the CLI printed>"}
 ```
 
-Set `all_pass` to true with an empty `findings` list only when every layer came back clean. Always include `manifest_sha256` so the verdict clears the commit regardless of which work tree the verifier or the committer ran in. Commit-committability gates (CODE_RULES / merge conflicts) must already be green before you are spawned; you are the last semantic check before commit. Any file change after you finish moves that hash and invalidates the verdict.
+Set `all_pass` to true with an empty `findings` list only when every layer came back clean and the shown-red table is complete. Always include `manifest_sha256` so the verdict clears the commit regardless of which work tree the verifier or the committer ran in. Commit-committability gates (CODE_RULES / merge conflicts) must already be green before you are spawned; you are the last semantic check before commit. Any file change after you finish moves that hash and invalidates the verdict.

package/bin/codex-compat.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const materializerPath = path.join(packageRoot, "scripts", "codex_compat_materializer.py");
+const bridgePath = path.join(packageRoot, "scripts", "codex_capability_bridge.py");
+const pythonNames = process.platform === "win32" ? ["py", "python"] : ["python3", "python"];
+
+export function createHelpText() {
+    return [
+        "Usage: codex-compat <command> [options]",
+        "",
+        "Commands:",
+        "  materialize  Plan or apply Claude agents into an explicit Codex root",
+        "  bridge       Translate a Claude capability request to a declarative record",
+        "",
+        "Materialize options:",
+        "  --source-root <path>  Claude source root (required)",
+        "  --target-root <path>  Codex target root (required)",
+        "  --apply               Write changes; default is dry-run",
+        "  --allow-prune-all     Permit an empty plan to delete every managed file",
+        "  --python <command>    Python interpreter override",
+        "",
+        "Bridge options:",
+        "  --surface <name>      Capability surface (required)",
+        "  --payload <json>      JSON object payload (required)",
+        "  --python <command>    Python interpreter override",
+        "",
+        "Python may also be selected with CODEX_COMPAT_PYTHON. Roots are never inferred or written automatically.",
+    ].join("\n");
+}
+
+function readOption(argumentsList, optionName) {
+    const optionIndex = argumentsList.indexOf(optionName);
+    if (optionIndex < 0) return undefined;
+    return argumentsList[optionIndex + 1];
+}
+
+function requireOption(argumentsList, optionName) {
+    const optionValue = readOption(argumentsList, optionName);
+    if (!optionValue || optionValue.startsWith("--")) throw new Error(`Missing required option: ${optionName}`);
+    return optionValue;
+}
+
+function writeErrorRecord(errorCode, errorMessage) {
+    process.stderr.write(`${JSON.stringify({ error: { code: errorCode, message: errorMessage } })}\n`);
+}
+
+export function buildCommand(commandName, argumentsList, interpreter) {
+    if (commandName === "materialize") {
+        const sourceRoot = requireOption(argumentsList, "--source-root");
+        const targetRoot = requireOption(argumentsList, "--target-root");
+        const materializerArguments = [materializerPath, sourceRoot, targetRoot];
+        if (argumentsList.includes("--apply")) materializerArguments.push("--apply");
+        if (argumentsList.includes("--allow-prune-all")) materializerArguments.push("--allow-prune-all");
+        return { executable: interpreter, arguments: materializerArguments };
+    }
+    if (commandName === "bridge") {
+        const surface = requireOption(argumentsList, "--surface");
+        const payload = requireOption(argumentsList, "--payload");
+        return { executable: interpreter, arguments: [bridgePath, surface, payload] };
+    }
+    throw new Error(`Unknown command: ${commandName}`);
+}
+
+export function findPython(commandNames = pythonNames, canRun = (command) => spawnSync(command, ["--version"], { stdio: "ignore" }).status === 0) {
+    for (const eachCommand of commandNames) {
+        if (canRun(eachCommand)) return eachCommand;
+    }
+    return undefined;
+}
+
+export function runCommand(command, runChild = spawn) {
+    return new Promise((resolve) => {
+        const childProcess = runChild(command.executable, command.arguments, { stdio: "inherit" });
+        childProcess.on("close", (exitCode, signal) => resolve(exitCode ?? 1 + (signal ? 1 : 0)));
+        childProcess.on("error", () => resolve(1));
+    });
+}
+
+export async function main(argumentsList = process.argv.slice(2), dependencies = {}) {
+    if (argumentsList.length === 0 || argumentsList.includes("--help") || argumentsList.includes("-h")) {
+        process.stdout.write(`${createHelpText()}\n`);
+        return 0;
+    }
+    const [commandName, ...commandArguments] = argumentsList;
+    try {
+        const interpreter = readOption(commandArguments, "--python") ?? process.env.CODEX_COMPAT_PYTHON ?? await (dependencies.findPython ?? findPython)();
+        if (!interpreter) {
+            writeErrorRecord("python_unavailable", "No usable Python interpreter found. Use --python or CODEX_COMPAT_PYTHON.");
+            return 1;
+        }
+        const command = buildCommand(commandName, commandArguments, interpreter);
+        return await (dependencies.runCommand ?? runCommand)(command, dependencies.runChild);
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "Unknown compatibility command error";
+        writeErrorRecord("invalid_command", errorMessage);
+        return 2;
+    }
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) process.exitCode = await main();