claude-dev-env 2.2.0 → 2.3.0

package/scripts/test_claude_chain_usage.py

@@ -0,0 +1,534 @@
+"""Behavioral tests for the claude chain weekly-usage report tool."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+import claude_chain_runner as chain_runner  # noqa: E402
+import claude_chain_usage as usage  # noqa: E402
+from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
+    CHAIN_CONFIG_ERROR_EXIT_CODE,
+    CONFIG_CHAIN_KEY,
+    CONFIG_COMMAND_KEY,
+    CONFIG_CREDENTIALS_PATH_KEY,
+    CONFIG_EXTRA_ARGS_KEY,
+    CONFIG_FILENAME,
+    UTF8_ENCODING,
+)
+from dev_env_scripts_constants.claude_chain_usage_constants import (  # noqa: E402
+    CLI_CONFIG_PATH_FLAG,
+    FULL_WEEKLY_PERCENT,
+    JSON_ACCOUNTS_KEY,
+    JSON_COMMAND_KEY,
+    JSON_ERROR_KEY,
+    JSON_WEEKLY_REMAINING_PERCENT_KEY,
+    RESOLVE_USAGE_WINDOW_MODULE_NAME,
+)
+
+PLACEHOLDER_CREDENTIALS_PRIMARY = "/path/to/account-primary/.credentials.json"
+PLACEHOLDER_CREDENTIALS_SECONDARY = "/path/to/account-secondary/.credentials.json"
+PLACEHOLDER_CREDENTIALS_TERTIARY = "/path/to/account-tertiary/.credentials.json"
+
+
+def _entry(
+    command: str,
+    *,
+    extra_args: list[str] | None = None,
+    credentials_path: str | None = None,
+) -> dict[str, object]:
+    chain_entry: dict[str, object] = {
+        CONFIG_COMMAND_KEY: command,
+        CONFIG_EXTRA_ARGS_KEY: extra_args if extra_args is not None else [],
+    }
+    if credentials_path is not None:
+        chain_entry[CONFIG_CREDENTIALS_PATH_KEY] = credentials_path
+    return chain_entry
+
+
+def _write_chain_config(
+    tmp_path: Path, all_chain_entries: list[dict[str, object]]
+) -> Path:
+    config_file = tmp_path / CONFIG_FILENAME
+    config_file.write_text(
+        json.dumps({CONFIG_CHAIN_KEY: all_chain_entries}), encoding=UTF8_ENCODING
+    )
+    return config_file
+
+
+def _probe_from_utilization_by_path(
+    utilization_by_path: dict[str, float | Exception],
+) -> usage.WeeklyUtilizationProbe:
+    def active_probe(credentials_path: Path) -> float:
+        path_key = credentials_path.as_posix()
+        probe_outcome = utilization_by_path[path_key]
+        if isinstance(probe_outcome, Exception):
+            raise probe_outcome
+        return probe_outcome
+
+    return active_probe
+
+
+def test_remaining_percent_is_full_scale_minus_utilization(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    config_file = _write_chain_config(
+        tmp_path,
+        [
+            _entry("claude", credentials_path=PLACEHOLDER_CREDENTIALS_PRIMARY),
+            _entry("claude-ev", credentials_path=PLACEHOLDER_CREDENTIALS_SECONDARY),
+        ],
+    )
+    monkeypatch.setattr(
+        usage,
+        "weekly_utilization_probe",
+        _probe_from_utilization_by_path(
+            {
+                PLACEHOLDER_CREDENTIALS_PRIMARY: 42.0,
+                PLACEHOLDER_CREDENTIALS_SECONDARY: 9.0,
+            }
+        ),
+    )
+    all_reports = usage.report_chain_weekly_usage(config_path=config_file)
+    assert [each_report.command for each_report in all_reports] == [
+        "claude",
+        "claude-ev",
+    ]
+    assert all_reports[0].weekly_remaining_percent == pytest.approx(
+        FULL_WEEKLY_PERCENT - 42.0
+    )
+    assert all_reports[1].weekly_remaining_percent == pytest.approx(
+        FULL_WEEKLY_PERCENT - 9.0
+    )
+    assert all_reports[0].error is None
+    assert all_reports[1].error is None
+
+
+def test_rank_orders_by_remaining_desc_preserves_ties_and_puts_nulls_last() -> None:
+    all_reports = [
+        usage.AccountUsageReport(command="first", weekly_remaining_percent=40.0),
+        usage.AccountUsageReport(command="second", weekly_remaining_percent=70.0),
+        usage.AccountUsageReport(
+            command="third", weekly_remaining_percent=None, error="probe failed"
+        ),
+        usage.AccountUsageReport(command="fourth", weekly_remaining_percent=70.0),
+        usage.AccountUsageReport(
+            command="fifth", weekly_remaining_percent=None, error="no token"
+        ),
+        usage.AccountUsageReport(command="sixth", weekly_remaining_percent=10.0),
+    ]
+    ranked_reports = usage.rank_accounts_by_weekly_remaining(all_reports)
+    assert [each_report.command for each_report in ranked_reports] == [
+        "second",
+        "fourth",
+        "first",
+        "sixth",
+        "third",
+        "fifth",
+    ]
+
+
+def test_probe_failure_yields_null_remaining_and_error_string(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    config_file = _write_chain_config(
+        tmp_path,
+        [
+            _entry("claude", credentials_path=PLACEHOLDER_CREDENTIALS_PRIMARY),
+            _entry("claude-ev", credentials_path=PLACEHOLDER_CREDENTIALS_SECONDARY),
+        ],
+    )
+    monkeypatch.setattr(
+        usage,
+        "weekly_utilization_probe",
+        _probe_from_utilization_by_path(
+            {
+                PLACEHOLDER_CREDENTIALS_PRIMARY: usage.WeeklyUtilizationProbeError(
+                    "token expired"
+                ),
+                PLACEHOLDER_CREDENTIALS_SECONDARY: 25.0,
+            }
+        ),
+    )
+    all_reports = usage.report_chain_weekly_usage(config_path=config_file)
+    assert all_reports[0].weekly_remaining_percent is None
+    assert all_reports[0].error == "token expired"
+    assert all_reports[1].weekly_remaining_percent == pytest.approx(
+        FULL_WEEKLY_PERCENT - 25.0
+    )
+    assert all_reports[1].error is None
+
+
+def test_missing_config_raises_chain_configuration_error(tmp_path: Path) -> None:
+    missing_config = tmp_path / "absent-chain.json"
+    with pytest.raises(chain_runner.ChainConfigurationError):
+        usage.report_chain_weekly_usage(config_path=missing_config)
+
+
+def test_empty_config_raises_chain_configuration_error(tmp_path: Path) -> None:
+    config_file = _write_chain_config(tmp_path, [])
+    with pytest.raises(chain_runner.ChainConfigurationError):
+        usage.report_chain_weekly_usage(config_path=config_file)
+
+
+def test_entry_without_credentials_path_uses_default(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    default_path = Path("/path/to/default/.credentials.json")
+    monkeypatch.setattr(usage, "_default_credentials_path", lambda: default_path)
+    config_file = _write_chain_config(tmp_path, [_entry("claude")])
+    probed_paths: list[Path] = []
+
+    def active_probe(credentials_path: Path) -> float:
+        probed_paths.append(credentials_path)
+        return 10.0
+
+    monkeypatch.setattr(usage, "weekly_utilization_probe", active_probe)
+    all_reports = usage.report_chain_weekly_usage(config_path=config_file)
+    assert probed_paths == [default_path]
+    assert all_reports[0].weekly_remaining_percent == pytest.approx(
+        FULL_WEEKLY_PERCENT - 10.0
+    )
+
+
+def test_default_credentials_resolution_failure_yields_null_remaining(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    def raise_probe_error() -> Path:
+        raise usage.WeeklyUtilizationProbeError("probe module not found")
+
+    monkeypatch.setattr(usage, "_default_credentials_path", raise_probe_error)
+    config_file = _write_chain_config(tmp_path, [_entry("claude")])
+    all_reports = usage.report_chain_weekly_usage(config_path=config_file)
+    assert all_reports[0].weekly_remaining_percent is None
+    assert all_reports[0].error == "probe module not found"
+
+
+def test_entry_credentials_path_is_passed_to_probe(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    config_file = _write_chain_config(
+        tmp_path,
+        [_entry("claude-ev", credentials_path=PLACEHOLDER_CREDENTIALS_TERTIARY)],
+    )
+    probed_paths: list[Path] = []
+
+    def active_probe(credentials_path: Path) -> float:
+        probed_paths.append(credentials_path)
+        return 0.0
+
+    monkeypatch.setattr(usage, "weekly_utilization_probe", active_probe)
+    usage.report_chain_weekly_usage(config_path=config_file)
+    assert probed_paths == [Path(PLACEHOLDER_CREDENTIALS_TERTIARY)]
+
+
+def test_entry_credentials_path_expands_user_home(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    tilde_credentials_path = "~/.claude-accounts/secondary/.credentials.json"
+    config_file = _write_chain_config(
+        tmp_path,
+        [_entry("claude-ev", credentials_path=tilde_credentials_path)],
+    )
+    probed_paths: list[Path] = []
+
+    def active_probe(credentials_path: Path) -> float:
+        probed_paths.append(credentials_path)
+        return 0.0
+
+    monkeypatch.setattr(usage, "weekly_utilization_probe", active_probe)
+    usage.report_chain_weekly_usage(config_path=config_file)
+    assert probed_paths == [Path(tilde_credentials_path).expanduser()]
+
+
+def test_load_chain_carries_optional_credentials_path(tmp_path: Path) -> None:
+    config_file = _write_chain_config(
+        tmp_path,
+        [
+            _entry("claude"),
+            _entry("claude-ev", credentials_path=PLACEHOLDER_CREDENTIALS_SECONDARY),
+        ],
+    )
+    all_entries = chain_runner.load_chain(config_file)
+    assert all_entries[0].credentials_path is None
+    assert all_entries[1].credentials_path == PLACEHOLDER_CREDENTIALS_SECONDARY
+
+
+def test_invalid_credentials_path_type_raises(tmp_path: Path) -> None:
+    config_file = tmp_path / CONFIG_FILENAME
+    config_file.write_text(
+        json.dumps(
+            {
+                CONFIG_CHAIN_KEY: [
+                    {
+                        CONFIG_COMMAND_KEY: "claude",
+                        CONFIG_EXTRA_ARGS_KEY: [],
+                        CONFIG_CREDENTIALS_PATH_KEY: 12,
+                    }
+                ]
+            }
+        ),
+        encoding=UTF8_ENCODING,
+    )
+    with pytest.raises(chain_runner.ChainConfigurationError):
+        chain_runner.load_chain(config_file)
+
+
+def test_reports_to_json_payload_matches_cli_contract() -> None:
+    all_reports = [
+        usage.AccountUsageReport(command="claude", weekly_remaining_percent=58.0),
+        usage.AccountUsageReport(
+            command="claude-ev",
+            weekly_remaining_percent=None,
+            error="probe failed",
+        ),
+    ]
+    payload = usage.reports_to_json_payload(all_reports)
+    assert payload == {
+        JSON_ACCOUNTS_KEY: [
+            {
+                JSON_COMMAND_KEY: "claude",
+                JSON_WEEKLY_REMAINING_PERCENT_KEY: 58.0,
+            },
+            {
+                JSON_COMMAND_KEY: "claude-ev",
+                JSON_WEEKLY_REMAINING_PERCENT_KEY: None,
+                JSON_ERROR_KEY: "probe failed",
+            },
+        ]
+    }
+
+
+def test_cli_writes_json_accounts_report(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    config_file = _write_chain_config(
+        tmp_path,
+        [
+            _entry("claude", credentials_path=PLACEHOLDER_CREDENTIALS_PRIMARY),
+            _entry("claude-ev", credentials_path=PLACEHOLDER_CREDENTIALS_SECONDARY),
+        ],
+    )
+    monkeypatch.setattr(
+        usage,
+        "weekly_utilization_probe",
+        _probe_from_utilization_by_path(
+            {
+                PLACEHOLDER_CREDENTIALS_PRIMARY: 42.0,
+                PLACEHOLDER_CREDENTIALS_SECONDARY: usage.WeeklyUtilizationProbeError(
+                    "no token"
+                ),
+            }
+        ),
+    )
+    exit_code = usage.main([CLI_CONFIG_PATH_FLAG, str(config_file)])
+    captured = capsys.readouterr()
+    assert exit_code == 0
+    assert captured.err == ""
+    payload = json.loads(captured.out)
+    assert payload == {
+        JSON_ACCOUNTS_KEY: [
+            {
+                JSON_COMMAND_KEY: "claude",
+                JSON_WEEKLY_REMAINING_PERCENT_KEY: FULL_WEEKLY_PERCENT - 42.0,
+            },
+            {
+                JSON_COMMAND_KEY: "claude-ev",
+                JSON_WEEKLY_REMAINING_PERCENT_KEY: None,
+                JSON_ERROR_KEY: "no token",
+            },
+        ]
+    }
+
+
+def test_cli_missing_config_prints_stderr_and_returns_config_error(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    missing_config = tmp_path / "absent-chain.json"
+    exit_code = usage.main([CLI_CONFIG_PATH_FLAG, str(missing_config)])
+    captured = capsys.readouterr()
+    assert exit_code == CHAIN_CONFIG_ERROR_EXIT_CODE
+    assert captured.out == ""
+    assert "not found" in captured.err.lower() or "claude chain" in captured.err.lower()
+
+
+def test_weekly_remaining_from_utilization_uses_full_scale() -> None:
+    assert usage.weekly_remaining_from_utilization(9.0) == pytest.approx(91.0)
+    assert usage.weekly_remaining_from_utilization(0.0) == pytest.approx(
+        FULL_WEEKLY_PERCENT
+    )
+    assert usage.weekly_remaining_from_utilization(100.0) == pytest.approx(0.0)
+
+
+def test_probe_weekly_utilization_reuses_resolver_windows(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    class _FakeWindows:
+        weekly_utilization = 37.5
+
+    class _FakeResolver:
+        def read_oauth_access_token(self, credentials_path: Path, now: object) -> str:
+            assert credentials_path == Path(PLACEHOLDER_CREDENTIALS_PRIMARY)
+            return "token-value"
+
+        def resolve_access_token(self, credentials_path: Path, now: object) -> str:
+            raise AssertionError("probe must not fall back to session ingress")
+
+        def _fetch_usage_payload(self, access_token: str) -> dict[str, object]:
+            assert access_token == "token-value"
+            return {"seven_day": {"utilization": 37.5}}
+
+        def extract_usage_windows(
+            self, usage_payload: dict[str, object]
+        ) -> _FakeWindows:
+            assert usage_payload == {"seven_day": {"utilization": 37.5}}
+            return _FakeWindows()
+
+    monkeypatch.setattr(
+        usage, "_load_resolve_usage_window_module", lambda: _FakeResolver()
+    )
+    weekly_utilization = usage._probe_weekly_utilization(
+        Path(PLACEHOLDER_CREDENTIALS_PRIMARY)
+    )
+    assert weekly_utilization == pytest.approx(37.5)
+
+
+def test_probe_weekly_utilization_raises_when_token_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    class _FakeResolver:
+        def read_oauth_access_token(
+            self, credentials_path: Path, now: object
+        ) -> None:
+            return None
+
+        def resolve_access_token(self, credentials_path: Path, now: object) -> str:
+            return "ingress-token-must-not-be-used"
+
+        def _fetch_usage_payload(self, access_token: str) -> dict[str, object]:
+            raise AssertionError("must not probe with an ingress fallback token")
+
+    monkeypatch.setattr(
+        usage, "_load_resolve_usage_window_module", lambda: _FakeResolver()
+    )
+    with pytest.raises(usage.WeeklyUtilizationProbeError):
+        usage._probe_weekly_utilization(Path(PLACEHOLDER_CREDENTIALS_PRIMARY))
+
+
+def test_probe_ignores_ingress_when_credential_token_missing(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    config_file = _write_chain_config(
+        tmp_path,
+        [_entry("claude-ev", credentials_path=PLACEHOLDER_CREDENTIALS_SECONDARY)],
+    )
+
+    class _FakeResolver:
+        def read_oauth_access_token(
+            self, credentials_path: Path, now: object
+        ) -> None:
+            return None
+
+        def resolve_access_token(self, credentials_path: Path, now: object) -> str:
+            return "ingress-token-must-not-be-used"
+
+        def _fetch_usage_payload(self, access_token: str) -> dict[str, object]:
+            raise AssertionError("must not probe with an ingress fallback token")
+
+    monkeypatch.setattr(
+        usage, "_load_resolve_usage_window_module", lambda: _FakeResolver()
+    )
+    monkeypatch.setattr(usage, "weekly_utilization_probe", usage._probe_weekly_utilization)
+    all_reports = usage.report_chain_weekly_usage(config_path=config_file)
+    assert all_reports[0].weekly_remaining_percent is None
+    assert all_reports[0].error is not None
+    assert "bearer token" in all_reports[0].error.lower()
+
+
+def test_load_failure_yields_per_account_error_and_cli_exits_zero(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    config_file = _write_chain_config(
+        tmp_path,
+        [
+            _entry("claude", credentials_path=PLACEHOLDER_CREDENTIALS_PRIMARY),
+            _entry("claude-ev", credentials_path=PLACEHOLDER_CREDENTIALS_SECONDARY),
+        ],
+    )
+
+    def active_probe(credentials_path: Path) -> float:
+        path_key = credentials_path.as_posix()
+        if path_key == PLACEHOLDER_CREDENTIALS_PRIMARY:
+            raise ImportError("usage probe module failed to import")
+        return 25.0
+
+    monkeypatch.setattr(usage, "weekly_utilization_probe", active_probe)
+    exit_code = usage.main([CLI_CONFIG_PATH_FLAG, str(config_file)])
+    captured = capsys.readouterr()
+    assert exit_code == 0
+    payload = json.loads(captured.out)
+    assert payload[JSON_ACCOUNTS_KEY][0][JSON_WEEKLY_REMAINING_PERCENT_KEY] is None
+    assert "failed to import" in payload[JSON_ACCOUNTS_KEY][0][JSON_ERROR_KEY]
+    assert payload[JSON_ACCOUNTS_KEY][1][JSON_WEEKLY_REMAINING_PERCENT_KEY] == pytest.approx(
+        FULL_WEEKLY_PERCENT - 25.0
+    )
+
+
+def test_failed_exec_module_does_not_poison_sys_modules(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    if RESOLVE_USAGE_WINDOW_MODULE_NAME in sys.modules:
+        del sys.modules[RESOLVE_USAGE_WINDOW_MODULE_NAME]
+    (tmp_path / "resolve_usage_window.py").write_text(
+        "raise ImportError('intentional load failure')\n", encoding="utf-8"
+    )
+    monkeypatch.setattr(usage, "_usage_pause_scripts_directory", lambda: tmp_path)
+    with pytest.raises(ImportError, match="intentional load failure"):
+        usage._load_resolve_usage_window_module()
+    assert RESOLVE_USAGE_WINDOW_MODULE_NAME not in sys.modules
+
+
+def test_load_resolve_usage_window_module_loads_real_probe_api() -> None:
+    if RESOLVE_USAGE_WINDOW_MODULE_NAME in sys.modules:
+        del sys.modules[RESOLVE_USAGE_WINDOW_MODULE_NAME]
+    loaded_module = usage._load_resolve_usage_window_module()
+    assert callable(loaded_module.read_oauth_access_token)
+    assert callable(loaded_module.resolve_access_token)
+    assert callable(loaded_module.extract_usage_windows)
+    assert callable(loaded_module._fetch_usage_payload)
+    assert sys.modules[RESOLVE_USAGE_WINDOW_MODULE_NAME] is loaded_module
+
+
+def test_load_resolve_usage_window_module_reuses_cached_module() -> None:
+    first_load = usage._load_resolve_usage_window_module()
+    second_load = usage._load_resolve_usage_window_module()
+    assert first_load is second_load
+
+
+def test_usage_module_imports_without_preloading_runner() -> None:
+    scripts_directory = str(_SCRIPTS_DIR)
+    import_probe = (
+        "import sys; "
+        f"sys.path.insert(0, {scripts_directory!r}); "
+        "import claude_chain_usage; "
+        "assert callable(claude_chain_usage.report_chain_weekly_usage); "
+        "assert callable(claude_chain_usage.rank_accounts_by_weekly_remaining)"
+    )
+    completed = subprocess.run(
+        [sys.executable, "-S", "-E", "-c", import_probe],
+        capture_output=True,
+        text=True,
+        timeout=60,
+        check=False,
+    )
+    assert completed.returncode == 0, completed.stderr

package/skills/orchestrator/SKILL.md

@@ -30,32 +30,13 @@ The moment it edits a file or runs a test itself, the pairing breaks —
 its own tool use stays orchestration, run-artifact writes, and light
 verification reads.
 
-## Design rule — thin prompts, thick artifacts, thin skill
-
-Three faces of one rule (reading pinned by the audit spec on
-jl-cmd/claude-dev-env#174: thin means high-signal, not short; thick
-context lives outside the window, reachable by pointers):
-
-- **Thin prompts.** A spawn prompt is a dispatch ticket: one task,
-  pointers to the artifacts that hold the context, one done-check, a thin
-  return contract. The prompt can be thin because the context is thick
-  elsewhere.
-- **Thick artifacts.** Durable run state lives in files — the run
-  charter, one assignment file per task, result records — written once,
-  read by every agent that needs them, and still there when any one
-  agent's context is gone.
-- **Thin skill.** This file holds only what changes decisions at
-  orchestration time. Standing policy lives where it loads once:
-  [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
-  for everything advisor, the agent definitions for executor discipline.
-
 ## Process
 
 1. **Invocation guard.** One `/orchestrator` per session. When the
    refresh loop is already running, do not schedule a second one; reuse
    the live advisor bind and go to step 4.
 2. **Register the discipline reminder.** Schedule it with
-   `ScheduleWakeup` at `delaySeconds: 1800`, prompt
+   `ScheduleWakeup` at `delaySeconds: 2700`, prompt
    `/orchestrator-refresh`, where each refresh re-schedules the next one.
 3. **Bind the shared advisor before any executor.** Follow
    [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)

package/skills/orchestrator-refresh/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: orchestrator-refresh
 description: >-
-  Fired by the /orchestrator loop reminder about every 20 minutes to
+  Fired by the /orchestrator loop reminder about every 45 minutes to
   re-assert the advisor discipline mid-run: orchestrate, route hard decisions
   to the shared advisor (ENDORSE / CORRECTION / PLAN / STOP — SendMessage on
   Claude, Claude CLI chain on a third-party host), reuse warm agents. Triggers:

package/skills/pr-converge/SKILL.md

@@ -195,7 +195,7 @@ the `persistent_agents` map
   record it, and continue the tick. Never abort a tick on a stale id;
   never retry the same dead id.
 - **Fresh every round (never persisted):** the Step 5 host-aware
-  `invoke_code_review.py` / `/code-review high --fix` pass and the Step 6
+  `invoke_code_review.py` / `/code-review xhigh --fix` pass and the Step 6
   bugteam audit (unbiased eyes each round; the enforcer needs the formal
   Skill call), and every `code-verifier` — a named code-verifier never fires
   `SubagentStop`, so no verdict mints (see the named-`code-verifier` entry
@@ -253,7 +253,7 @@ post a fresh PR in a fresh branch based on origin main to the user.
   Windows is Git Bash which cannot execute PowerShell cmdlets. Route all
   PowerShell work through the PowerShell tool or `pwsh -NoProfile -File`.
 - **Cross-repo PR: route cwd into the PR worktree before Step 5 review** —
-  `invoke_code_review.py` and `/code-review high --fix` audit the repo of the
+  `invoke_code_review.py` and `/code-review xhigh --fix` audit the repo of the
   cwd (the helper's `--cwd`). When the session is rooted in a different repo
   than the PR, `EnterWorktree` cannot re-root (it is scoped to the session's
   repo); resolve the PR worktree and `cd` into it per
@@ -351,7 +351,7 @@ round as converged. This rule holds every tick, every loop, every PR.
       - [ ] **Static sweep fails** → apply shared fix protocol → push → reset markers
             → stay CODE_REVIEW → Step 5
       - [ ] **`mode == in_session`** (Claude host, session model opus) → run
-            `/code-review high --fix` in-session (no path args)
+            `/code-review xhigh --fix` in-session (no path args)
       - [ ] **`mode == chain`** (any other host or non-opus session) → helper
             already ran the headless review; read `returncode`,
             `served_command`, and `dirty_tree` from JSON

package/skills/pr-converge/reference/examples.md

@@ -18,7 +18,7 @@ resets push-invalidated markers per [ground-rules.md](ground-rules.md) /
 at 270s, re-runs the sweep next tick]
 </example>
 
-<example> CODE_REVIEW tick, static sweep clean, `/code-review high --fix`
+<example> CODE_REVIEW tick, static sweep clean, `/code-review xhigh --fix`
 applies fixes to the working tree. Claude: [commits the applied fixes in one
 commit, pushes, resets push-invalidated markers per
 [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md) (all
@@ -26,7 +26,7 @@ commit, pushes, resets push-invalidated markers per
 stays `phase = CODE_REVIEW`, Step 4 at 270s, returns]
 </example>
 
-<example> CODE_REVIEW tick, static sweep clean and `/code-review high --fix`
+<example> CODE_REVIEW tick, static sweep clean and `/code-review xhigh --fix`
 clean (no changes applied). Claude: [sets `code_review_clean_at = HEAD`,
 `phase = BUGTEAM`, runs `Skill({skill: "bugteam", ...})` in same tick]
 </example>
@@ -94,7 +94,7 @@ applies **Convergence** from `workflows/schedule-wakeup-loop.md`]
 
 <example> CODE_REVIEW tick, review body says "found 3 potential issues"
 against HEAD (a stale prior finding) but the diff is clean. Claude: [the static
-sweep and `/code-review high --fix` both pass, sets `code_review_clean_at =
+sweep and `/code-review xhigh --fix` both pass, sets `code_review_clean_at =
 HEAD`, `phase = BUGTEAM`]
 </example>
 

package/skills/pr-converge/reference/fix-protocol.md

@@ -32,6 +32,6 @@ files during fix phase in multi-PR mode.
 regardless of phase. A new commit **resets the full convergence cycle**: a
 code-review clean, a bugteam clean, and a Bugbot clean on an older SHA do
 **not** count toward convergence on the new `HEAD`. Re-run the static sweep and
-`/code-review high --fix` on `current_head`, then bugteam, then the terminal
+`/code-review xhigh --fix` on `current_head`, then bugteam, then the terminal
 Bugbot gate, all on the same `HEAD` with no intervening push. Re-entering in the
 same tick saves a wakeup cycle.

package/skills/pr-converge/reference/ground-rules.md

@@ -10,11 +10,11 @@
 - **All `*_clean_at`, `merge_state_status`, and `bugbot_down` / `codex_down` reset on every push.**
 - **`bugbot run` comment is load-bearing.** Literal phrase exactly —
   empirically the only re-trigger Cursor Bugbot recognizes.
-- **Production edits go through `clean-coder`, except `/code-review high --fix`.**
+- **Production edits go through `clean-coder`, except `/code-review xhigh --fix`.**
   The lead never hand-edits production files. Every bugbot, bugteam,
   Copilot, or Claude finding spawns `Agent(subagent_type="clean-coder")` to
   apply the fix. The CODE_REVIEW phase is the one exception: `/code-review
-  high --fix` applies its own findings to the working tree, which the next
+  xhigh --fix` applies its own findings to the working tree, which the next
   CODE_REVIEW/BUGTEAM cycle re-reviews after the loop resets.
 - **Adapt when reality contradicts on-disk state.** If `state.json`,
   `git`, or `gh` disagree with live PR, escalate as hard blocker per
@@ -22,7 +22,7 @@
 - **Cross-repo cwd routing is routine, not a fork.** When the PR under
   convergence lives in a different repo than the session is rooted in, route
   the working directory into a checkout of the PR's repo automatically —
-  `/code-review high --fix`, `git`, and every `clean-coder` fix spawn act on the
+  `/code-review xhigh --fix`, `git`, and every `clean-coder` fix spawn act on the
   repo of the current working directory. The resolution is fixed
   ([per-tick.md § Step 1.5](per-tick.md)): resolve the PR worktree, `cd` into
   it, run local work there. Do not pause, ask, or raise it as a material fork.