claude-dev-env 1.36.1 → 1.36.2

package/_shared/pr-loop/scripts/tests/test_preflight.py

@@ -0,0 +1,333 @@
+"""Tests for preflight git hooks path verification.
+
+Covers:
+- core.hooksPath unset: exits non-zero with correction message
+- core.hooksPath pointing to the correct claude hooks dir: exits zero
+- core.hooksPath pointing elsewhere (husky override): exits non-zero
+- core.hooksPath with trailing slash: must still pass after normalization
+"""
+
+import importlib.util
+import inspect
+import subprocess
+import sys
+from pathlib import Path
+from types import ModuleType
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+def _load_preflight_module() -> ModuleType:
+    module_path = Path(__file__).parent.parent / "preflight.py"
+    spec = importlib.util.spec_from_file_location("preflight", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+preflight = _load_preflight_module()
+
+from config.preflight_constants import PYTEST_NO_TESTS_COLLECTED_EXIT_CODE  # noqa: E402
+
+
+def _make_completed_process(
+    stdout: str, returncode: int
+) -> subprocess.CompletedProcess:
+    process = MagicMock(spec=subprocess.CompletedProcess)
+    process.stdout = stdout
+    process.returncode = returncode
+    return process
+
+
+def test_should_exit_nonzero_when_core_hooks_path_unset(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process("", returncode=1)
+        exit_code = preflight.verify_git_hooks_path()
+    assert exit_code != 0
+    captured = capsys.readouterr()
+    assert "core.hooksPath" in captured.err
+    assert "npx claude-dev-env" in captured.err or "git config" in captured.err
+
+
+def test_should_exit_zero_when_core_hooks_path_points_to_claude_hooks(
+    tmp_path: Path,
+) -> None:
+    claude_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    claude_hooks_path.mkdir(parents=True)
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            str(claude_hooks_path) + "\n", returncode=0
+        )
+        exit_code = preflight.verify_git_hooks_path()
+    assert exit_code == 0
+
+
+def test_should_exit_nonzero_when_core_hooks_path_points_elsewhere(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            "/some/other/path/.husky\n", returncode=0
+        )
+        exit_code = preflight.verify_git_hooks_path()
+    assert exit_code != 0
+    captured = capsys.readouterr()
+    assert "core.hooksPath" in captured.err
+
+
+def test_should_include_correction_commands_in_error_message(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process("", returncode=1)
+        preflight.verify_git_hooks_path()
+    captured = capsys.readouterr()
+    assert (
+        "npx claude-dev-env" in captured.err
+        or "git config --global core.hooksPath" in captured.err
+    )
+
+
+def test_main_should_exit_nonzero_when_hooks_path_unset() -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process("", returncode=1)
+        exit_code = preflight.main(["--no-pytest"])
+    assert exit_code != 0
+
+
+def test_main_should_continue_when_hooks_path_valid(tmp_path: Path) -> None:
+    claude_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    claude_hooks_path.mkdir(parents=True)
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            str(claude_hooks_path) + "\n", returncode=0
+        )
+        exit_code = preflight.main(["--no-pytest"])
+    assert exit_code == 0
+
+
+def test_should_accept_hooks_path_with_trailing_slash() -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            "/home/user/.claude/hooks/git-hooks/\n", returncode=0
+        )
+        exit_code = preflight.verify_git_hooks_path()
+    assert exit_code == 0, (
+        "hooksPath with trailing slash must pass verification after normalization"
+    )
+
+
+def test_should_exit_zero_when_hooks_path_set_at_repo_scope(tmp_path: Path) -> None:
+    claude_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    claude_hooks_path.mkdir(parents=True)
+    repo_root = tmp_path / "my-repo"
+    repo_root.mkdir()
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            str(claude_hooks_path) + "\n", returncode=0
+        )
+        exit_code = preflight.verify_git_hooks_path(repo_root)
+    assert exit_code == 0, (
+        "verify_git_hooks_path must accept a valid path returned by effective "
+        "config query (not restricted to --global scope)"
+    )
+    called_command = mock_run.call_args[0][0]
+    assert "--global" not in called_command, (
+        "verify_git_hooks_path must query effective config, not --global only"
+    )
+    assert "-C" in called_command, (
+        "verify_git_hooks_path must use git -C <repo_root> for repo-effective config"
+    )
+    dash_c_index = called_command.index("-C")
+    assert called_command[dash_c_index + 1] == str(repo_root), (
+        "git -C must receive the resolved repository root path"
+    )
+
+
+def test_should_accept_hooks_path_with_backslash_and_trailing_slash() -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            "C:\\Users\\user\\.claude\\hooks\\git-hooks\\\n", returncode=0
+        )
+        exit_code = preflight.verify_git_hooks_path()
+    assert exit_code == 0, (
+        "Windows hooksPath with trailing backslash must pass after normalization"
+    )
+
+
+def test_should_exit_nonzero_when_git_executable_not_found(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Preflight must not crash with a traceback when git is missing from PATH."""
+    with patch("subprocess.run", side_effect=FileNotFoundError()):
+        exit_code = preflight.verify_git_hooks_path()
+    assert exit_code != 0, (
+        "FileNotFoundError from subprocess.run must produce a non-zero exit, "
+        "not a propagated traceback"
+    )
+    captured = capsys.readouterr()
+    assert "git" in captured.err.lower(), (
+        "Error message must mention git so the user knows what is missing"
+    )
+    assert (
+        "npx claude-dev-env" in captured.err
+        or "git config --global core.hooksPath" in captured.err
+    ), "Error message must include the enforcement-absent remediation hints"
+
+
+def test_should_exit_nonzero_when_subprocess_run_raises_os_error(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Preflight must surface a clean error for other OS-level git launch failures."""
+    with patch("subprocess.run", side_effect=OSError("permission denied")):
+        exit_code = preflight.verify_git_hooks_path()
+    assert exit_code != 0, (
+        "OSError from subprocess.run must produce a non-zero exit, "
+        "not a propagated traceback"
+    )
+    captured = capsys.readouterr()
+    assert "preflight" in captured.err, (
+        "Error message must be prefixed with the preflight tool name for context"
+    )
+    assert "permission denied" in captured.err, (
+        "Error message must include the underlying OSError detail for diagnosis"
+    )
+
+
+def test_preflight_uses_shared_hooks_path_suffix_constant() -> None:
+    """Preflight's expected suffix must come from config.fix_hookspath_constants
+    so the canonical hooks directory is defined in exactly one place."""
+    scripts_directory = str(Path(__file__).parent.parent.resolve())
+    if scripts_directory not in sys.path:
+        sys.path.insert(0, scripts_directory)
+    constants_module_path = (
+        Path(__file__).parent.parent / "config" / "fix_hookspath_constants.py"
+    )
+    constants_specification = importlib.util.spec_from_file_location(
+        "config.fix_hookspath_constants",
+        constants_module_path,
+    )
+    assert constants_specification is not None
+    assert constants_specification.loader is not None
+    constants_module = importlib.util.module_from_spec(constants_specification)
+    constants_specification.loader.exec_module(constants_module)
+    expected_suffix = constants_module.HOOKS_PATH_VERIFICATION_SUFFIX
+
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            f"/some/where/{expected_suffix}\n", returncode=0
+        )
+        exit_code = preflight.verify_git_hooks_path()
+    assert exit_code == 0
+
+
+def test_preflight_skip_uses_shared_env_var_constant(
+    capsys: pytest.CaptureFixture[str],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The preflight skip env-var name must come from config/preflight_constants.py."""
+    scripts_directory = str(Path(__file__).parent.parent.resolve())
+    if scripts_directory not in sys.path:
+        sys.path.insert(0, scripts_directory)
+    constants_module_path = (
+        Path(__file__).parent.parent / "config" / "preflight_constants.py"
+    )
+    constants_specification = importlib.util.spec_from_file_location(
+        "config.preflight_constants",
+        constants_module_path,
+    )
+    assert constants_specification is not None
+    assert constants_specification.loader is not None
+    constants_module = importlib.util.module_from_spec(constants_specification)
+    constants_specification.loader.exec_module(constants_module)
+    skip_env_var_name = constants_module.BUGTEAM_PREFLIGHT_SKIP_ENV_VAR_NAME
+
+    monkeypatch.setenv(skip_env_var_name, "1")
+    exit_code = preflight.main(["--no-pytest"])
+    assert exit_code == 0
+    captured = capsys.readouterr()
+    assert skip_env_var_name in captured.err
+
+
+def test_loop_variables_use_each_prefix_in_preflight_module() -> None:
+    find_root_source = inspect.getsource(preflight.find_repository_root)
+    assert "for each_candidate in" in find_root_source
+
+    discover_tests_source = inspect.getsource(preflight.has_discoverable_tests)
+    assert "for each_path in" in discover_tests_source
+    assert "for each_part in" in discover_tests_source
+
+
+def test_preflight_uses_extracted_directory_marker_constants() -> None:
+    """preflight.py must reference extracted constants instead of inline string literals.
+
+    The CODE_RULES magic-values rule treats inline ``.git`` and ``.venv``
+    string literals in production function bodies as violations. Confirm
+    preflight.py imports them (or a frozenset that contains ``.venv``) from
+    config.preflight_constants instead.
+    """
+    preflight_source = inspect.getsource(preflight)
+    assert "GIT_DIRECTORY_NAME" in preflight_source
+    assert "ALL_TESTS_DIRECTORY_IGNORE_PARTS" in preflight_source
+    find_root_source = inspect.getsource(preflight.find_repository_root)
+    assert "'.git'" not in find_root_source
+    assert '".git"' not in find_root_source
+    discover_tests_source = inspect.getsource(preflight.has_discoverable_tests)
+    assert "'.venv'" not in discover_tests_source
+    assert '".venv"' not in discover_tests_source
+
+
+def test_preflight_does_not_import_unused_venv_directory_name_constant() -> None:
+    """The ``VENV_DIRECTORY_NAME`` constant is not consumed by preflight.py
+    (``.venv`` reaches the function body via ``ALL_TESTS_DIRECTORY_IGNORE_PARTS``).
+    Importing the standalone name is dead code per the unused-imports rule."""
+    preflight_source = inspect.getsource(preflight)
+    assert "VENV_DIRECTORY_NAME" not in preflight_source, (
+        "Dead import must be removed; preflight.py reaches `.venv` via "
+        "ALL_TESTS_DIRECTORY_IGNORE_PARTS instead"
+    )
+
+
+def test_preflight_stderr_uses_bugteam_preflight_prefix(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Preflight's stderr prefix must remain ``bugteam_preflight:`` so the bugteam
+    SKILL.md auto-remediation pattern (`bugteam_preflight: core.hooksPath is`)
+    keeps matching when Phase 2 wires bugteam to import this shared script."""
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            "/some/other/path/.husky\n", returncode=0
+        )
+        preflight.verify_git_hooks_path()
+    captured = capsys.readouterr()
+    assert "bugteam_preflight: core.hooksPath is" in captured.err, (
+        "Stderr prefix must preserve the bugteam SKILL.md auto-remediation contract"
+    )
+
+
+def test_preflight_does_not_import_unused_repository_root_marker_constant() -> None:
+    """The ``ALL_REPOSITORY_ROOT_MARKER_FILENAMES`` constant is not consumed by
+    preflight.py. Importing it is dead code per the unused-imports rule."""
+    preflight_source = inspect.getsource(preflight)
+    assert "ALL_REPOSITORY_ROOT_MARKER_FILENAMES" not in preflight_source, (
+        "Dead import must be removed; preflight.py uses individual marker "
+        "filename constants directly"
+    )
+
+
+def test_pytest_no_tests_collected_helper_returns_named_constant() -> None:
+    """The pytest "no tests collected" exit code must be sourced from the
+    named constant in config/preflight_constants.py rather than the bare
+    literal 5 inside the function body (CODE_RULES magic-values rule)."""
+    assert preflight._pytest_exit_code_no_tests_collected() == (
+        PYTEST_NO_TESTS_COLLECTED_EXIT_CODE
+    )
+    helper_source = inspect.getsource(preflight._pytest_exit_code_no_tests_collected)
+    assert "PYTEST_NO_TESTS_COLLECTED_EXIT_CODE" in helper_source, (
+        "Helper body must return the named constant, not the bare literal 5"
+    )

package/_shared/pr-loop/scripts/tests/test_preflight_constants.py

@@ -0,0 +1,82 @@
+"""Tests for preflight_constants.py extracted constant set."""
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_constants_module() -> ModuleType:
+    module_path = Path(__file__).parent.parent / "config" / "preflight_constants.py"
+    specification = importlib.util.spec_from_file_location(
+        "config.preflight_constants", module_path
+    )
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+constants_module = _load_constants_module()
+
+
+def test_bugteam_preflight_skip_env_var_name() -> None:
+    assert (
+        constants_module.BUGTEAM_PREFLIGHT_SKIP_ENV_VAR_NAME == "BUGTEAM_PREFLIGHT_SKIP"
+    )
+
+
+def test_bugteam_preflight_skip_enabled_value() -> None:
+    assert constants_module.BUGTEAM_PREFLIGHT_SKIP_ENABLED_VALUE == "1"
+
+
+def test_git_directory_name() -> None:
+    assert constants_module.GIT_DIRECTORY_NAME == ".git"
+
+
+def test_claude_directory_name() -> None:
+    assert constants_module.CLAUDE_DIRECTORY_NAME == ".claude"
+
+
+def test_venv_directory_name() -> None:
+    assert constants_module.VENV_DIRECTORY_NAME == ".venv"
+
+
+def test_pytest_ini_filename() -> None:
+    assert constants_module.PYTEST_INI_FILENAME == "pytest.ini"
+
+
+def test_pyproject_toml_filename() -> None:
+    assert constants_module.PYPROJECT_TOML_FILENAME == "pyproject.toml"
+
+
+def test_pytest_toml_table_prefix() -> None:
+    assert constants_module.PYTEST_TOML_TABLE_PREFIX == "[tool.pytest"
+
+
+def test_pre_commit_config_yaml_filename() -> None:
+    assert constants_module.PRE_COMMIT_CONFIG_YAML_FILENAME == ".pre-commit-config.yaml"
+
+
+def test_all_test_file_patterns_for_discovery() -> None:
+    assert constants_module.ALL_TEST_FILE_PATTERNS_FOR_DISCOVERY == (
+        "test_*.py",
+        "*_test.py",
+    )
+
+
+def test_all_tests_directory_ignore_parts_includes_venv_marker() -> None:
+    assert constants_module.VENV_DIRECTORY_NAME in (
+        constants_module.ALL_TESTS_DIRECTORY_IGNORE_PARTS
+    )
+
+
+def test_all_repository_root_marker_filenames() -> None:
+    assert constants_module.ALL_REPOSITORY_ROOT_MARKER_FILENAMES == (
+        constants_module.GIT_DIRECTORY_NAME,
+        constants_module.PYTEST_INI_FILENAME,
+    )
+
+
+def test_pytest_no_tests_collected_exit_code() -> None:
+    assert constants_module.PYTEST_NO_TESTS_COLLECTED_EXIT_CODE == 5

package/_shared/pr-loop/scripts/tests/test_revoke_project_claude_permissions.py

@@ -0,0 +1,49 @@
+"""Smoke tests for revoke_project_claude_permissions wiring.
+
+Confirms the module imports cleanly with the constants now sourced from
+config/claude_permissions_constants.py and config/claude_settings_keys_constants.py.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_revoke_module() -> ModuleType:
+    scripts_directory = Path(__file__).parent.parent
+    parent_directory = str(scripts_directory.resolve())
+    if parent_directory not in sys.path:
+        sys.path.insert(0, parent_directory)
+    sys.modules.pop("config", None)
+    module_path = scripts_directory / "revoke_project_claude_permissions.py"
+    specification = importlib.util.spec_from_file_location(
+        "revoke_project_claude_permissions", module_path
+    )
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+def test_module_imports_constants_from_config_modules() -> None:
+    revoke_module = _load_revoke_module()
+    assert revoke_module.ALL_PERMISSION_ALLOW_TOOLS == ("Edit", "Write", "Read")
+    assert "{project_path}" in revoke_module.AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE
+    assert revoke_module.CLAUDE_SETTINGS_PERMISSIONS_KEY == "permissions"
+
+
+def test_revoke_module_guards_sys_path_insert_against_duplicates() -> None:
+    """revoke_project_claude_permissions.py must guard its sys.path.insert with a
+    membership check so re-imports under test harnesses do not push duplicate
+    entries (consistent with sibling modules in the same directory)."""
+    module_source = (
+        Path(__file__).parent.parent / "revoke_project_claude_permissions.py"
+    ).read_text(encoding="utf-8")
+    assert "if str(Path(__file__).resolve().parent) not in sys.path:" in module_source, (
+        "revoke_project_claude_permissions.py must guard sys.path.insert against "
+        "duplicate entries on reload (consistent with sibling modules)"
+    )

package/_shared/pr-loop/state-schema.md

@@ -0,0 +1,81 @@
+# State schema
+
+State each PR-loop workflow tracks across iterations. Workflows differ on persistence (in-memory vs files) and which fields they use; shapes overlap.
+
+## Common fields
+
+| Field | Type | Purpose |
+|---|---|---|
+| `loop_count` | int | Iterations completed; bumps on each AUDIT or tick |
+| `last_action` | enum | `fresh` \| `audited` \| `fixed` — drives next-step dispatch |
+| `last_findings` | object | `{p0, p1, p2, total}` count of findings from most recent AUDIT |
+| `audit_log` | list[str] | Per-iteration one-line summaries for the final report |
+| `starting_sha` | str | `git rev-parse HEAD` at workflow start |
+| `loop_comment_index` | dict | `{finding_id: {finding_comment_id, finding_comment_url, used_fallback, fix_status, ...}}` |
+
+## Workflow-specific extensions
+
+### bugteam
+
+Adds:
+- `team_name` — `bugteam-pr-<N>-<YYYYMMDDHHMMSS>` or `bugteam-<YYYYMMDDHHMMSS>` for multi-PR
+- `team_temp_dir` — absolute path resolved from `tempfile.gettempdir()`
+- `pre_fix_sha` — `git rev-parse HEAD` immediately before each FIX
+- `gate_round_count` — consecutive pre-audit gate failures (cap: 5 → exit `error`)
+
+State lives inline in the lead session (orchestrator). Cleared on TeamDelete.
+
+### qbug
+
+Adds nothing beyond common. Single subagent loops internally and returns a final summary; orchestrator discards intermediate state. Subagent's loop counter and findings return in the exit payload (`{exit_reason, loop_count, final_commit_sha, audit_log, unresolved}`).
+
+### pr-converge
+
+Adds the same **traffic** fields whether they live in **`state.json`** or in the **conversation state line**; only the **store** differs.
+
+| Field | Type | Purpose |
+|---|---|---|
+| `phase` | enum | `BUGBOT` \| `BUGTEAM` — which reviewer the current tick drives |
+| `current_head` | str | PR `headRefOid` / `git rev-parse` for the PR under work (each tick; from `view_pr_context.py` when no file store) |
+| `bugbot_clean_at` | str \| null | HEAD SHA at which Cursor Bugbot last reported clean, or `null` (reset on every push) |
+| `copilot_clean_at` | str \| null | HEAD SHA at which the GitHub Copilot reviewer (`copilot-pull-request-reviewer[bot]`) last reported clean (review `state == "APPROVED"`), or `null`. Reset on every push. Convergence gates require this equals `current_head` after bugbot+bugteam are clean (see `skills/pr-converge/SKILL.md` § Convergence gates). |
+| `merge_state_status` | str \| null | Last-observed `mergeStateStatus` from `gh pr view --json mergeable,mergeStateStatus,headRefOid` (e.g., `CLEAN`, `DIRTY`, `BLOCKED`, `BEHIND`, `UNKNOWN`), or `null` before the first check. Reset on every push. `DIRTY` triggers the rebase invocation; non-`CLEAN` non-`DIRTY` is a hard blocker per pr-converge `Stop conditions`. |
+| `inline_lag_streak` | int | Consecutive ticks where bugbot's review body claims findings but inline-comments API returns zero rows for `current_head` |
+| `tick_count` | int | Observability only — **no ceiling**; loop ends on convergence or **Stop conditions** in `pr-converge` |
+
+**Dual persistence** (normative: `skills/pr-converge/SKILL.md` § State across ticks, § Multi-PR orchestration model):
+
+| Mode | When it applies | Source of truth | `tick_count` bump |
+|---|---|---|---|
+| **`state.json`** | File exists at `<TMPDIR>/pr-converge-<session_id>/state.json` (multi-PR orchestration or other file-backed session) | JSON: top-level `session_id`; per-PR objects under `prs[<number>]` with `owner`, `repo`, `branch`, `phase`, `current_head`, `bugbot_clean_at`, `inline_lag_streak`, `tick_count`, `last_action`, `status`, `last_updated`. Optional sibling `converged.log` (append-only; multi-PR only). Writes use lock + atomic replace per skill **Concurrency** | **Orchestrator only** at tick start (locked merge for every non-terminal PR); **never** bump `tick_count` in Step 1 when this file is in use |
+| **Conversation state line** | **No** `state.json` (typical single-PR `/pr-converge` in Cursor) | Persist **`phase`**, **`bugbot_clean_at`**, **`inline_lag_streak`**, **`tick_count`** as **plain text** in each assistant turn; next tick reads them from the **most recent assistant message**. **`current_head` is not serialized in that line** — re-resolve each tick via `view_pr_context.py` (same contract as `skills/pr-converge/SKILL.md` § State across ticks). | **Step 1** increments `tick_count` in that line **only** when no `state.json` — must not double-count with any file-backed path |
+
+**`status` (file-backed `prs[...]` only):** `fresh` \| `in_progress` \| `awaiting_bugbot` \| `awaiting_bugteam` \| `converged` \| `blocked`
+
+### monitor-many
+
+Adds per-PR JSON state file at `~/.claude/skills/monitor-many/state/<owner>-<repo>-<pr_number>.json`:
+
+| Field | Type | Description |
+|---|---|---|
+| `repo_name` | str | Full `owner/repo` |
+| `pr_number` | int | PR number |
+| `status` | enum | `open` \| `blocked_escalation` \| `fixing` \| `ready_candidate` \| `closed` |
+| `copilot_review` | enum | `none` \| `requested` \| `pending` \| `commented` \| `approved` |
+| `bugbot_review` | enum | Same vocabulary as `copilot_review` |
+| `last_seen_comment_id` | int \| null | Highest processed review-comment id (incremental polling watermark) |
+| `review_comments` | list[object] | Optional cache; `{id, author, path, line}` per entry |
+| `escalation_queue` | list[object] | Pending human-judgment items: `{comment_id, summary, created_at}` |
+
+## Reset semantics
+
+- bugteam: cleared on each new `/bugteam` invocation
+- qbug: cleared on each new `/qbug` invocation
+- pr-converge: `bugbot_clean_at`, `copilot_clean_at`, and `merge_state_status` all reset to `null` on every push (a new commit invalidates every reviewer's prior clean and the prior mergeability snapshot by definition); `phase` cycles each tick. With `state.json`, orchestrator reads that file at tick start; without it, rely on the prior conversation state line — **never** mix both increment rules for `tick_count` on the same run
+- monitor-many: persists across orchestrator runs; only `last_seen_comment_id` advances monotonically
+
+## Convergence checks
+
+- bugteam, qbug: `last_action == "audited"` AND `last_findings.total == 0` → `converged`
+- pr-converge: `bugbot_clean_at == current_head` AND most-recent bugteam exit is `converged` AND no push during the bugteam tick AND no outstanding Copilot findings on `current_head` AND `merge_state_status == "CLEAN"` (per `skills/pr-converge/SKILL.md` § Convergence gates) → back-to-back clean → `gh pr ready` (read `current_head` / `bugbot_clean_at` / `copilot_clean_at` / `merge_state_status` from `state.json` when file-backed, else from the conversation state line and Step 1 `view_pr_context.py` output)
+- monitor-many: no unresolved comments requiring code changes AND required checks green AND review policy satisfied → `gh pr ready`

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.36.1",
+    "version": "1.36.2",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -19,6 +19,7 @@
         "hooks/",
         "system-prompts/",
         "scripts/",
+        "_shared/",
         "CLAUDE.md"
     ],
     "keywords": [