claude-dev-env 1.40.0 → 1.41.0

package/hooks/test__gh_pr_author_swap_utils.py

@@ -0,0 +1,333 @@
+"""Canonical-location tests for the gh-pr-author swap utils module.
+
+The TDD enforcer matches a production filename ``X.py`` to ``test_X.py``;
+``_gh_pr_author_swap_utils.py`` carries a leading underscore that the
+enforcer treats as part of the name. This file's tests are the canonical
+match. The broader behavioural suite lives alongside in
+``blocking/test_gh_pr_author_swap_utils.py``.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import pathlib
+import sys
+import tempfile
+
+import pytest
+
+from config.gh_pr_author_swap_constants import STATE_FILE_PERMISSION_MODE
+
+_HOOKS_ROOT = pathlib.Path(__file__).resolve().parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+utils_module_spec = importlib.util.spec_from_file_location(
+    "_gh_pr_author_swap_utils",
+    _HOOKS_ROOT / "_gh_pr_author_swap_utils.py",
+)
+assert utils_module_spec is not None
+assert utils_module_spec.loader is not None
+utils_module = importlib.util.module_from_spec(utils_module_spec)
+utils_module_spec.loader.exec_module(utils_module)
+
+
+def test_state_file_path_rejects_path_traversal_session_id() -> None:
+    """A session_id containing path-traversal characters must not escape tempdir.
+
+    Regression guard: an unsanitised ``session_id`` containing ``../`` or
+    ``/`` would interpolate into the filename and let the resulting path
+    land outside ``tempfile.gettempdir()``. The sanitiser strips every
+    character outside ``[A-Za-z0-9_-]`` and falls back to the default
+    session id when the result is empty.
+    """
+    sanitised_path = utils_module._state_file_path("../../tmp/evil")
+    temporary_directory_path = pathlib.Path(tempfile.gettempdir()).resolve()
+    assert sanitised_path.parent.resolve() == temporary_directory_path
+
+
+def test_state_file_path_rejects_backslash_in_session_id() -> None:
+    """Backslashes are also unsafe path separators on Windows."""
+    sanitised_path = utils_module._state_file_path("evil\\..\\..\\system32")
+    temporary_directory_path = pathlib.Path(tempfile.gettempdir()).resolve()
+    assert sanitised_path.parent.resolve() == temporary_directory_path
+
+
+def test_state_file_path_rejects_nul_byte_in_session_id() -> None:
+    """A NUL byte inside the session id must not reach the filename."""
+    sanitised_path = utils_module._state_file_path("abc\x00../def")
+    temporary_directory_path = pathlib.Path(tempfile.gettempdir()).resolve()
+    assert sanitised_path.parent.resolve() == temporary_directory_path
+    assert "\x00" not in sanitised_path.name
+
+
+def test_state_file_path_preserves_safe_session_id() -> None:
+    """A well-formed session id passes through unchanged."""
+    safe_session_id = "session-001_abc"
+    produced_path = utils_module._state_file_path(safe_session_id)
+    assert safe_session_id in produced_path.name
+
+
+def test_backtick_substitution_blanks_inner_quoted_literals() -> None:
+    """A ``gh pr create`` literal inside a single-quoted argument of a backtick body must not trigger.
+
+    Mirrors ``$(printf '...')`` behaviour: when the backtick body's
+    quoted literal contains the token, the matcher must blank the
+    quoted region before searching.
+    """
+    stripped_command = utils_module._strip_quoted_regions("foo `printf ';gh pr create'`")
+    assert not utils_module._command_invokes_gh_pr_create_in_stripped(stripped_command)
+
+
+def test_backtick_substitution_matches_unquoted_gh_pr_create_inside_body() -> None:
+    """A bare ``gh pr create`` inside a backtick body still matches.
+
+    Symmetric to ``$(gh pr create)`` — the substitution body is real
+    code, so the matcher must see it.
+    """
+    stripped_command = utils_module._strip_quoted_regions("echo `gh pr create --title T`")
+    assert utils_module._command_invokes_gh_pr_create_in_stripped(stripped_command)
+
+
+def test_state_file_is_attacker_planted_returns_true_for_world_readable_mode(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A state file with mode 0o644 is flagged as attacker-planted on POSIX.
+
+    The enforcer always atomically creates state files at 0o600. A file
+    at the predictable swap-state path with any other mode bits cannot
+    have come from the enforcer running as this user.
+    """
+    if not hasattr(os, "getuid"):
+        return
+    state_file = tmp_path / "gh_pr_author_swap_session-attacker.json"
+    state_file.write_text("{}", encoding="utf-8")
+    os.chmod(state_file, 0o644)
+
+    assert utils_module._state_file_is_attacker_planted(state_file) is True
+
+
+def test_state_file_is_attacker_planted_returns_false_for_well_formed_file(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A state file written exactly the way the enforcer writes is not flagged."""
+    state_file = tmp_path / "gh_pr_author_swap_session-good.json"
+    state_file.write_text("{}", encoding="utf-8")
+    if hasattr(os, "getuid"):
+        os.chmod(state_file, STATE_FILE_PERMISSION_MODE)
+
+    assert utils_module._state_file_is_attacker_planted(state_file) is False
+
+
+def test_state_file_is_attacker_planted_returns_false_for_missing_file(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A missing state file is treated as not-planted so callers can no-op cleanly."""
+    missing_state_file = tmp_path / "gh_pr_author_swap_session-missing.json"
+
+    assert utils_module._state_file_is_attacker_planted(missing_state_file) is False
+
+
+def test_state_file_is_attacker_planted_returns_true_for_non_regular_file(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A FIFO at the predictable swap-state path is flagged as attacker-planted.
+
+    The enforcer only writes regular files; any non-regular file type
+    (symlink, FIFO, device) at the predictable path indicates another
+    party pre-created it to redirect the restore or cleanup hook.
+    """
+    if not hasattr(os, "mkfifo"):
+        pytest.skip("mkfifo not available on this platform")
+    if not hasattr(os, "getuid"):
+        pytest.skip("POSIX ownership semantics not available on this platform")
+    fifo_state_file = tmp_path / "gh_pr_author_swap_session-fifo.json"
+    os.mkfifo(fifo_state_file, STATE_FILE_PERMISSION_MODE)
+
+    assert utils_module._state_file_is_attacker_planted(fifo_state_file) is True
+
+
+def test_state_file_is_attacker_planted_returns_true_when_lstat_raises_os_error(
+    tmp_path: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """An ``OSError`` from ``lstat`` fails closed — the path is treated as planted.
+
+    A path that exists but is unreadable (permission denied, broken
+    filesystem mount, etc.) cannot be proven safe, so the helper
+    returns True to keep the restore or cleanup hook from trusting it.
+    """
+    if not hasattr(os, "getuid"):
+        pytest.skip("POSIX ownership semantics not available on this platform")
+    unreadable_state_file = tmp_path / "gh_pr_author_swap_session-unreadable.json"
+    unreadable_state_file.write_text("{}", encoding="utf-8")
+
+    def raise_permission_error(self: pathlib.Path) -> os.stat_result:
+        raise PermissionError("simulated lstat failure")
+
+    monkeypatch.setattr(pathlib.Path, "lstat", raise_permission_error)
+
+    assert utils_module._state_file_is_attacker_planted(unreadable_state_file) is True
+
+
+def test_strip_bash_comments_preserves_substitution_body_when_hash_is_inside_dollar_paren() -> None:
+    """Regression: ``$(date +%H # 24h) && gh pr create`` must not let the regex eat past the substitution closer.
+
+    Before this fix ``_strip_bash_comments`` ran a flat regex sweep that
+    blanked from ``#`` to end-of-line regardless of substitution depth.
+    A ``#`` preceded by whitespace inside a ``$(...)`` body consumed
+    the closing ``)`` AND every byte after it on the same line,
+    erasing a real ``gh pr create`` invocation from the enforcer's
+    view and silently bypassing the swap.
+    """
+    raw_command = "$(date +%H # 24h) && gh pr create --title T"
+    preprocessed_command = utils_module._preprocess_command_for_matching(raw_command)
+    assert "gh pr create" in preprocessed_command
+    assert utils_module._command_invokes_gh_pr_create_in_stripped(preprocessed_command)
+
+
+def test_strip_bash_comments_preserves_substitution_body_when_hash_is_inside_backtick() -> None:
+    """Regression: a ``#`` inside a backtick body must not erase a trailing ``gh pr create``.
+
+    Backtick substitution is symmetric with ``$(...)``; the
+    substitution-aware comment walker must treat both shapes the same.
+    """
+    raw_command = "foo `cmd # comment` bar && gh pr create"
+    preprocessed_command = utils_module._preprocess_command_for_matching(raw_command)
+    assert "gh pr create" in preprocessed_command
+    assert utils_module._command_invokes_gh_pr_create_in_stripped(preprocessed_command)
+
+
+def test_strip_bash_comments_strips_top_level_trailing_comment() -> None:
+    """Existing behaviour: a top-level trailing ``#`` comment after ``gh pr create`` is blanked.
+
+    The comment-stripping pass must still erase a real top-level
+    comment so the enforcer treats only the command portion as code.
+    """
+    raw_command = "gh pr create # this is a comment"
+    preprocessed_command = utils_module._preprocess_command_for_matching(raw_command)
+    assert "this is a comment" not in preprocessed_command
+
+
+def test_strip_bash_comments_strips_prior_line_comment_only() -> None:
+    """Existing behaviour: a comment on line 1 is blanked but a ``gh pr create`` on line 2 still matches.
+
+    The newline is preserved so the matcher can still tell the two
+    lines apart, and the second-line command stays intact.
+    """
+    raw_command = "echo a # b\ngh pr create"
+    preprocessed_command = utils_module._preprocess_command_for_matching(raw_command)
+    assert "gh pr create" in preprocessed_command
+    assert "# b" not in preprocessed_command
+    assert utils_module._command_invokes_gh_pr_create_in_stripped(preprocessed_command)
+
+
+def test_lstat_indicates_attacker_planted_returns_false_for_well_formed_lstat(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A 0o600 regular file owned by the current user is not flagged.
+
+    Mirrors ``test_state_file_is_attacker_planted_returns_false_for_well_formed_file``
+    but feeds the helper a pre-computed ``lstat`` result so the helper
+    does not perform its own syscall.
+    """
+    state_file = tmp_path / "gh_pr_author_swap_session-well_formed.json"
+    state_file.write_text("{}", encoding="utf-8")
+    if hasattr(os, "getuid"):
+        os.chmod(state_file, STATE_FILE_PERMISSION_MODE)
+
+    file_lstat_result = state_file.lstat()
+
+    assert utils_module._lstat_indicates_attacker_planted(file_lstat_result) is False
+
+
+def test_lstat_indicates_attacker_planted_returns_true_for_world_readable_mode(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A 0o644 regular file is flagged as attacker-planted on POSIX.
+
+    The enforcer always creates state files at 0o600, so a divergent
+    mode is treated as a plant.
+    """
+    if not hasattr(os, "getuid"):
+        pytest.skip("POSIX ownership semantics not available on this platform")
+    state_file = tmp_path / "gh_pr_author_swap_session-mode_wrong.json"
+    state_file.write_text("{}", encoding="utf-8")
+    os.chmod(state_file, 0o644)
+
+    file_lstat_result = state_file.lstat()
+
+    assert utils_module._lstat_indicates_attacker_planted(file_lstat_result) is True
+
+
+def test_lstat_indicates_attacker_planted_returns_true_for_foreign_uid(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A regular 0o600 file owned by a different uid is flagged on POSIX.
+
+    The helper sees only the ``stat_result`` it is given, so the test
+    builds a synthetic ``os.stat_result`` whose ``st_uid`` does not match
+    ``os.getuid()`` and feeds it directly to the helper.
+    """
+    if not hasattr(os, "getuid"):
+        pytest.skip("POSIX ownership semantics not available on this platform")
+    state_file = tmp_path / "gh_pr_author_swap_session-foreign_uid.json"
+    state_file.write_text("{}", encoding="utf-8")
+    os.chmod(state_file, STATE_FILE_PERMISSION_MODE)
+    real_lstat_result = state_file.lstat()
+    foreign_user_id = os.getuid() + 1
+    synthetic_stat_fields = (
+        real_lstat_result.st_mode,
+        real_lstat_result.st_ino,
+        real_lstat_result.st_dev,
+        real_lstat_result.st_nlink,
+        foreign_user_id,
+        real_lstat_result.st_gid,
+        real_lstat_result.st_size,
+        real_lstat_result.st_atime,
+        real_lstat_result.st_mtime,
+        real_lstat_result.st_ctime,
+    )
+    synthetic_stat_result = os.stat_result(synthetic_stat_fields)
+
+    assert utils_module._lstat_indicates_attacker_planted(synthetic_stat_result) is True
+
+
+def test_lstat_indicates_attacker_planted_returns_true_for_non_regular_file(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A FIFO at the predictable swap-state path is flagged.
+
+    Mirrors ``test_state_file_is_attacker_planted_returns_true_for_non_regular_file``
+    but feeds the helper the FIFO's own ``lstat`` result rather than the
+    path.
+    """
+    if not hasattr(os, "mkfifo"):
+        pytest.skip("mkfifo not available on this platform")
+    if not hasattr(os, "getuid"):
+        pytest.skip("POSIX ownership semantics not available on this platform")
+    fifo_state_file = tmp_path / "gh_pr_author_swap_session-fifo.json"
+    os.mkfifo(fifo_state_file, STATE_FILE_PERMISSION_MODE)
+
+    file_lstat_result = fifo_state_file.lstat()
+
+    assert utils_module._lstat_indicates_attacker_planted(file_lstat_result) is True
+
+
+def test_lstat_indicates_attacker_planted_returns_false_on_windows(
+    tmp_path: pathlib.Path,
+) -> None:
+    """On Windows (no ``os.getuid``) the helper short-circuits to False.
+
+    Windows tempdir is already per-user, so the cross-user attack
+    surface this check guards against on POSIX does not exist there.
+    """
+    if hasattr(os, "getuid"):
+        pytest.skip("POSIX has os.getuid; this case asserts Windows-only behaviour")
+    state_file = tmp_path / "gh_pr_author_swap_session-windows.json"
+    state_file.write_text("{}", encoding="utf-8")
+
+    file_lstat_result = state_file.lstat()
+
+    assert utils_module._lstat_indicates_attacker_planted(file_lstat_result) is False

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.40.0",
+    "version": "1.41.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/_shared/pr-loop/scripts/write_audit_outcomes.py

@@ -70,8 +70,8 @@ def _populate_findings(parent: Element, findings_data: list[dict[str, object]])
 
     Scalar finding fields become XML attributes on `<finding>`; the
     body fields named in `ALL_FINDING_BODY_ELEMENT_KEYS` (defined in
-    `config/path_resolver_constants.py` and currently
-    `("title", "excerpt", "description")`) become child elements.
+    `packages/claude-dev-env/skills/_shared/pr-loop/scripts/config/path_resolver_constants.py`
+    and currently `("title", "excerpt", "description")`) become child elements.
     Nested dicts or lists in scalar slots are flattened to string form
     so attribute serialization stays well-defined.
 

package/skills/_shared/pr-loop/scripts/write_fix_outcomes.py

@@ -1,8 +1,8 @@
 """Validate status enum values and write <bugteam_fix> XML at the canonical path.
 
 Status enum (canonical source: `ALL_VALID_FIX_STATUSES` in
-`config/path_resolver_constants.py`): fixed | could_not_address |
-hook_blocked | unverified_fixed.
+`packages/claude-dev-env/skills/_shared/pr-loop/scripts/config/path_resolver_constants.py`):
+fixed | could_not_address | hook_blocked | unverified_fixed.
 
 Each outcome's scalar fields become XML attributes on `<outcome>`; the
 body fields named in `ALL_FIX_OUTCOME_BODY_ELEMENT_KEYS` (currently

package/skills/bugteam/reference/audit-contract.md

@@ -91,6 +91,17 @@ The audit must either produce new Shape A findings citing new file:line referenc
 
 For `/bugteam`, the single audit agent provides per-category coverage by walking all A–K rubrics in one invocation.
 
+## Merge rules
+
+When the LEAD combines findings from multiple sources (primary auditor, Haiku secondary auditor, adversarial pass), it applies these rules:
+
+- **De-dup key**: `(file, line, category)`. Two findings sharing the same `(file, line, category)` tuple are the same finding and collapse into one entry.
+- **Severity conflict**: max wins (`P0 > P1 > P2`). When sources disagree on severity for the same de-dup key, the merged entry keeps the highest severity.
+- **Unique-to-secondary findings**: added to the merged set with the secondary's severity and source annotation.
+- **Unique-to-primary findings**: kept as-is.
+- **Zero secondary findings**: primary set trusted; proceed.
+- **Malformed or non-parseable secondary output**: lead trusts the primary set and logs the event in `loop-<L>-diagnostics.json` under `haiku_findings` as `[{"parse_error": "<message>"}]`.
+
 ## Post-fix self-audit
 
 Audit-and-fix skills (`/qbug`, `/bugteam`) MUST re-audit modified files between `py_compile` and `git add`. This catches fix-induced regressions in the same loop that introduced them rather than on loop N+1.
@@ -109,6 +120,17 @@ Sequence:
 
 `converged` exit condition: `primary_audit_clean AND post_fix_audit_clean` for the committing loop.
 
+## De-dup and merge
+
+Findings from primary, adversarial, Haiku secondary, and post-fix passes are merged into a single deduped finding list before persistence.
+
+- **De-dup key:** `(file, line, category)`. Two findings sharing the same `(file, line, category)` tuple collapse into a single deduped entry.
+- **Severity conflict resolution:** `max wins`. When merged findings disagree on severity, the deduped entry carries the maximum severity (`P0 > P1 > P2`).
+- **Excerpt and failure_mode:** the deduped entry inherits these fields from the highest-severity contributing finding. Ties keep the first observed contributor.
+- **`evidence_files`:** the deduped entry carries the union of every contributor's `evidence_files`, deduplicated and sorted.
+
+The merged list lands in `loop-<L>-diagnostics.json` under both `merged` (one entry per contributing finding) and `deduped` (one entry per unique `(file, line, category)` tuple).
+
 ## Persistence
 
 Every audit loop writes two JSON files under the skill's scoped temp directory (resolved via `tempfile.gettempdir()`):

package/skills/bugteam/reference/github-pr-reviews.md

@@ -22,7 +22,7 @@ python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/post_audit_thread.py"
 
 Capture `<head_sha>` via `git rev-parse HEAD` in the subagent cwd immediately before this call so the review attaches to the commit the audit actually scoped.
 
-`--findings-json` points to a JSON file whose root is a list of objects shaped `{path, line, side, severity, description, fix_summary}`. Build it from the merged Shape A findings: finding `file` → `path`. Each finding's `failure_mode` carries the full audit-to-fix handoff text per [`agents/code-quality-agent.md`](../../../agents/code-quality-agent.md); split `failure_mode` at the literal `Fix:` heading so the failure narrative becomes `description` and the suffix beginning at `Fix:` (including the trailing `Validation:` clause) becomes `fix_summary`. When a finding's `failure_mode` omits the `Fix:` heading, write the full text to BOTH `description` and `fix_summary` so the script's body template (`INLINE_COMMENT_BODY_TEMPLATE` in [`scripts/config/post_audit_thread_constants.py`](../../../_shared/pr-loop/scripts/config/post_audit_thread_constants.py)) renders coherently. Set `side="RIGHT"` for every entry. On CLEAN the list is empty (`[]`); on DIRTY the list carries one entry per finding.
+`--findings-json` points to a JSON file whose root is a list of objects shaped `{path, line, side, severity, description, fix_summary}`. Build it from the merged Shape A findings: finding `file` → `path`. Each finding's `failure_mode` carries the full audit-to-fix handoff text per [`agents/code-quality-agent.md`](../../../agents/code-quality-agent.md); split `failure_mode` at the literal `Fix:` heading so the failure narrative becomes `description` and the suffix beginning at `Fix:` (including the trailing `Validation:` clause) becomes `fix_summary`. When a finding's `failure_mode` omits the `Fix:` heading, write the full text to BOTH `description` and `fix_summary` so the script's body template (`INLINE_COMMENT_BODY_TEMPLATE` in [`packages/claude-dev-env/_shared/pr-loop/scripts/config/post_audit_thread_constants.py`](../../../_shared/pr-loop/scripts/config/post_audit_thread_constants.py)) renders coherently. Set `side="RIGHT"` for every entry. On CLEAN the list is empty (`[]`); on DIRTY the list carries one entry per finding.
 
 The script handles retries internally — 1s / 4s / 16s backoff across four attempts (one initial plus three retries). Exit codes:
 

package/skills/bugteam/scripts/bugteam_fix_hookspath.py

@@ -5,14 +5,20 @@ import subprocess
 import sys
 from pathlib import Path
 
+parent_directory = str(Path(__file__).resolve().parent)
+try:
+    sys.path.remove(parent_directory)
+except ValueError:
+    pass
+if parent_directory not in sys.path:
+    sys.path.insert(0, parent_directory)
+
 for each_cached_module_name in [
     each_module_key
     for each_module_key in list(sys.modules)
     if each_module_key == "config" or each_module_key.startswith("config.")
 ]:
     sys.modules.pop(each_cached_module_name, None)
-if str(Path(__file__).resolve().parent) not in sys.path:
-    sys.path.insert(0, str(Path(__file__).resolve().parent))
 
 from config.bugteam_fix_hookspath_constants import (
     ALL_CANONICAL_HOOKS_DIRECTORY_COMPONENTS,

package/skills/bugteam/scripts/test__claude_permissions_common.py

@@ -19,6 +19,54 @@ if _script_directory not in sys.path:
     sys.path.insert(0, _script_directory)
 
 import _claude_permissions_common as common_module
+import grant_project_claude_permissions as grant_module
+import revoke_project_claude_permissions as revoke_module
+
+
+def test_is_valid_project_root_not_defined_on_common_module() -> None:
+    """The common module must not expose ``is_valid_project_root``.
+
+    Both grant and revoke define their own local copy. A shared copy on
+    the common module would be a third parallel definition with no
+    production caller, so its absence is the asserted contract.
+    """
+    assert not hasattr(common_module, "is_valid_project_root")
+
+
+def test_grant_is_valid_project_root_detects_git_marker(tmp_path: Path) -> None:
+    git_project_root = tmp_path / "git_project"
+    (git_project_root / ".git").mkdir(parents=True)
+    assert grant_module.is_valid_project_root(git_project_root) is True
+
+
+def test_grant_is_valid_project_root_detects_claude_marker(tmp_path: Path) -> None:
+    claude_project_root = tmp_path / "claude_project"
+    (claude_project_root / ".claude").mkdir(parents=True)
+    assert grant_module.is_valid_project_root(claude_project_root) is True
+
+
+def test_grant_is_valid_project_root_rejects_unmarked_directory(tmp_path: Path) -> None:
+    unmarked_directory = tmp_path / "no_marker"
+    unmarked_directory.mkdir()
+    assert grant_module.is_valid_project_root(unmarked_directory) is False
+
+
+def test_revoke_is_valid_project_root_detects_git_marker(tmp_path: Path) -> None:
+    git_project_root = tmp_path / "git_project"
+    (git_project_root / ".git").mkdir(parents=True)
+    assert revoke_module.is_valid_project_root(git_project_root) is True
+
+
+def test_revoke_is_valid_project_root_detects_claude_marker(tmp_path: Path) -> None:
+    claude_project_root = tmp_path / "claude_project"
+    (claude_project_root / ".claude").mkdir(parents=True)
+    assert revoke_module.is_valid_project_root(claude_project_root) is True
+
+
+def test_revoke_is_valid_project_root_rejects_unmarked_directory(tmp_path: Path) -> None:
+    unmarked_directory = tmp_path / "no_marker"
+    unmarked_directory.mkdir()
+    assert revoke_module.is_valid_project_root(unmarked_directory) is False
 
 
 def test_write_atomically_with_mode_releases_fd_when_fdopen_raises(

package/skills/bugteam/scripts/test_claude_permissions_common.py

@@ -118,18 +118,26 @@ def test_default_settings_file_mode_used_when_settings_file_missing(
     assert returned_mode == DEFAULT_SETTINGS_FILE_MODE
 
 
-def test_is_valid_project_root_helper_is_not_orphaned_in_common_module() -> None:
-    """The orphan helper in the common module must be removed.
+def test_is_valid_project_root_exported_from_consumer_modules(
+    tmp_path: Path,
+) -> None:
+    """is_valid_project_root behaviour matches across both consumers.
 
-    Both grant and revoke keep their own local copies and consume them from
-    module scope; the common-module copy was dead code with zero call sites.
+    Grant and revoke each define their own local copy of the helper, so
+    both copies must agree on the .git / .claude marker contract.
     """
-    assert not hasattr(common_module, "is_valid_project_root"), (
-        "is_valid_project_root must not live in _claude_permissions_common — "
-        "neither grant nor revoke imports it from there"
-    )
-    assert callable(grant_module.is_valid_project_root)
-    assert callable(revoke_module.is_valid_project_root)
+    git_marker_project_root = tmp_path / "git_project"
+    (git_marker_project_root / ".git").mkdir(parents=True)
+    claude_marker_project_root = tmp_path / "claude_project"
+    (claude_marker_project_root / ".claude").mkdir(parents=True)
+    bare_directory = tmp_path / "no_marker"
+    bare_directory.mkdir()
+    assert grant_module.is_valid_project_root(git_marker_project_root) is True
+    assert grant_module.is_valid_project_root(claude_marker_project_root) is True
+    assert grant_module.is_valid_project_root(bare_directory) is False
+    assert revoke_module.is_valid_project_root(git_marker_project_root) is True
+    assert revoke_module.is_valid_project_root(claude_marker_project_root) is True
+    assert revoke_module.is_valid_project_root(bare_directory) is False
 
 
 def _reload_with_stale_config_cache(module_name: str) -> ModuleType:

package/skills/pr-converge/SKILL.md

@@ -38,7 +38,8 @@ clean-at SHAs. On tick exit, write updated state before calling ScheduleWakeup
 so the next tick resumes with accurate state.
 
 Fields: `phase`, `tick_count`, `bugbot_clean_at`, `bugteam_clean_at`,
-`copilot_clean_at`, `current_head`, `bugbot_acknowledged_at`, `bugbot_down`.
+`copilot_clean_at`, `current_head`, `bugbot_acknowledged_at`, `bugbot_down`,
+`bugteam_skill_invoked_at_head`, `bugteam_skill_invoked_at_tick`.
 
 ## Gotchas
 
@@ -150,7 +151,12 @@ no longer applies.
 
       Pre-condition: `bugbot_clean_at == current_head` (or `bugbot_down == true`).
 
-      Run `Skill({skill: "bugteam", args: "<PR URL>"})`.
+      Step 5 advances ONLY after `Skill({skill: "bugteam", args: "<PR URL>"})`
+      fires this tick. Substituting an `Agent({subagent_type: "clean-coder"})`
+      audit call for the formal Skill invocation is a protocol violation — the
+      `pr_converge_bugteam_enforcer` hook blocks it. `qbug` is NOT an accepted
+      substitute; `bugteam` is the only allowed skill at this step.
+
       After bugteam completes, re-resolve HEAD.
 
       - [ ] **bugteam pushed new commits** →

package/skills/pr-converge/config/constants.py

@@ -2,7 +2,8 @@
 
 All runtime and API constants live here. Script-specific constants
 (CLI args, markdown patterns, reflow settings) stay in
-``scripts/config/pr_converge_constants.py``, which imports from here.
+``packages/claude-dev-env/skills/pr-converge/scripts/config/pr_converge_constants.py``,
+which imports from here.
 """
 
 CURSOR_BOT_LOGIN = "cursor[bot]"

package/skills/pr-converge/reference/state-schema.md

@@ -1,10 +1,13 @@
 # State across ticks
 
-**Dual persistence:** `<TMPDIR>/pr-converge-<session_id>/state.json`
-exists (multi-PR) → that file is source of truth for `phase`, heads,
-counters, status, not conversation transcript. No `state.json` (typical
-single-PR `/pr-converge`) → track in each assistant turn as
-plain text so next tick re-reads from context:
+**Dual persistence:** Single-PR `/pr-converge` writes loop state to
+`$CLAUDE_JOB_DIR/pr-converge-state.json`; that file is the source of truth
+for `phase`, heads, counters, status. Multi-PR mode additionally maintains
+`<TMPDIR>/pr-converge-<session_id>/state.json` for orchestrator coordination
+across PRs. Both files share most of the fields below; the
+`bugteam_skill_invoked_at_head` and `bugteam_skill_invoked_at_tick` fields
+live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
+(see those field entries below for details).
 
 - `phase`: `BUGBOT`, `BUGTEAM`, or `COPILOT_WAIT`. Start `BUGBOT` on first tick.
 - `bugbot_clean_at`: HEAD SHA where bugbot last reported clean, or `null`.
@@ -34,7 +37,32 @@ plain text so next tick re-reads from context:
   (c) reads this field to decide between "schedule next wakeup" and
   "escalate to bugbot-down".
 - `tick_count`: integer, init `0`. Increment every tick.
+- `bugteam_skill_invoked_at_head`: HEAD SHA (string) at which the formal
+  `Skill({skill: "bugteam"})` was last invoked, or `null`. Stamped by the
+  `pr_converge_bugteam_skill_tracker` hook on every formal bugteam Skill
+  invocation. **On-disk location:** the tracker writes this field to
+  `$CLAUDE_JOB_DIR/pr-converge-state.json` (single-PR mode); it is NOT
+  mirrored into the multi-PR `<TMPDIR>/pr-converge-<session_id>/state.json`
+  file. Operators inspecting these stamps must read the single-PR
+  `pr-converge-state.json` under `$CLAUDE_JOB_DIR`. Reset by overwrite on
+  the next bugteam Skill invocation; staleness is detected by the head/tick
+  equality check rather than by explicit reset. The
+  `pr_converge_bugteam_enforcer` hook reads this field together with
+  `current_head` to confirm the formal Skill registered at the current HEAD
+  before allowing follow-on clean-coder audit-shaped Agent spawns. `qbug`
+  invocations deliberately do NOT update this field.
+- `bugteam_skill_invoked_at_tick`: integer tick number at which the formal
+  bugteam Skill was last invoked, or `null`. Companion to
+  `bugteam_skill_invoked_at_head` and persisted to the same
+  `$CLAUDE_JOB_DIR/pr-converge-state.json` file (single-PR mode only).
+  Reset by overwrite on the next bugteam Skill invocation; staleness is
+  detected by the head/tick equality check rather than by explicit reset.
+  The enforcer requires this value to equal the current `tick_count` so a
+  Skill invocation from a prior tick cannot wave through clean-coder
+  audit-shaped Agent spawns on a later tick at the same HEAD.
 
-Tick begins reading prior state line from most recent assistant message
-(no `state.json`) and ends by emitting updated state line; with
-`state.json`, follow `multi-pr-orchestration.md` §What orchestrator does per tick.
+Single-PR tick begins by reading `$CLAUDE_JOB_DIR/pr-converge-state.json`
+if it exists and ends by writing the updated state back to that same file
+before scheduling the next wakeup. Multi-PR mode additionally coordinates
+across PRs via `<TMPDIR>/pr-converge-<session_id>/state.json` per
+`multi-pr-orchestration.md` §What orchestrator does per tick.