claude-dev-env 1.83.0 → 1.85.0

package/_shared/pr-loop/audit-contract.md

@@ -8,7 +8,8 @@ Shared output schema and audit-loop contract used by `/bugteam`, `/qbug`, `/find
 - Adversarial second pass
 - Haiku secondary auditor
 - Post-fix self-audit
-- Persistence (loop-N-audit.json, loop-N-diagnostics.json)
+- De-dup and merge
+- Persistence (loop-<L>-audit.json, loop-<L>-diagnostics.json)
 
 ## Finding schema
 
@@ -18,7 +19,7 @@ Each finding an audit produces MUST be one of exactly two shapes.
 
 ```json
 {
-  "id": "loop<N>-<K>",
+  "id": "loop<L>-<K>",
   "file": "path/relative/to/repo/root.py",
   "line": 123,
   "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P",
@@ -29,7 +30,7 @@ Each finding an audit produces MUST be one of exactly two shapes.
 }
 ```
 
-`id` is `loop<N>-<K>` where `N` is the loop counter (1-based) and `K` is the 1-based index within the loop. For `/findbugs` which runs once, use `find<K>`.
+`id` is `loop<L>-<K>` where `L` is the loop counter (1-based) and `K` is the 1-based index within the loop. For `/findbugs` which runs once, use `find<K>`.
 
 ### Shape B — structured proof-of-absence
 
@@ -98,16 +99,16 @@ For single-subagent skills (`/qbug`, `/findbugs`) the LEAD spawns two `Agent()`
 
 Both audit the same diff. The secondary returns findings to the LEAD only — never posted to the PR.
 
-Merge rules:
+Merge rules — applied whenever the LEAD combines findings from multiple sources (primary auditor, Haiku secondary auditor, adversarial pass):
 
-- **De-dup key**: `(file, line, category)`.
-- **Severity conflict**: max wins (P0 > P1 > P2).
-- **Unique-to-Haiku findings**: added to the primary set with Haiku's severity and source annotation.
+- **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 Haiku findings**: primary set trusted; proceed.
-- **Malformed or non-parseable Haiku output**: lead trusts the primary set, logs the event in `loop-<N>-diagnostics.json` under `haiku_findings` as `[{"parse_error": "<message>"}]`.
+- **Zero secondary findings**: the primary set is trusted and the audit moves on.
+- **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>"}]`.
 
-For multi-subagent skills (`/bugteam`) the parallel-auditors pattern in [`audit-and-teammates.md`](audit-and-teammates.md) already provides cross-model coverage via the three variant teammates.
+For `/bugteam`, the single audit agent provides per-category coverage by walking all A–P rubrics in one invocation.
 
 ## Post-fix self-audit
 
@@ -128,11 +129,22 @@ 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 highest 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()`):
 
-### `loop-<N>-audit.json`
+### `loop-<L>-audit.json`
 
 ```json
 {
@@ -142,7 +154,7 @@ Every audit loop writes two JSON files under the skill's scoped temp directory (
 }
 ```
 
-### `loop-<N>-diagnostics.json`
+### `loop-<L>-diagnostics.json`
 
 ```json
 {

package/_shared/pr-loop/scripts/_claude_permissions_common.py

@@ -299,9 +299,11 @@ def write_atomically_with_mode(
 
     Raises:
         OSError: When os.open or os.fdopen fails. The raw file descriptor
-            is closed before re-raising so the descriptor does not leak.
+            is closed and the on-disk temporary file is unlinked before
+            re-raising so neither the descriptor nor the file leaks.
         MemoryError: When os.fdopen runs out of buffer memory; the file
-            descriptor is closed before re-raising.
+            descriptor is closed and the temporary file is unlinked
+            before re-raising.
     """
     file_descriptor = os.open(
         str(temporary_path),
@@ -312,6 +314,10 @@ def write_atomically_with_mode(
         writer = os.fdopen(file_descriptor, "w", encoding=TEXT_FILE_ENCODING)
     except (OSError, MemoryError):
         os.close(file_descriptor)
+        try:
+            os.unlink(str(temporary_path))
+        except OSError:
+            pass
         raise
     with writer:
         writer.write(serialized_content)
@@ -321,7 +327,8 @@ def save_settings(settings_path: Path, all_settings: dict[str, object]) -> None:
     """Write settings to a JSON file atomically with permission preservation.
 
     Creates a temporary sibling file, writes content, then atomically
-    replaces the target. Cleans up the temporary file in a finally block.
+    replaces the target. Cleans up the temporary file in a finally block,
+    printing a warning to stderr when that cleanup unlink fails.
 
     Args:
         settings_path: Path to the target settings JSON file.
@@ -352,8 +359,12 @@ def save_settings(settings_path: Path, all_settings: dict[str, object]) -> None:
         if temporary_path.exists():
             try:
                 temporary_path.unlink()
-            except OSError:
-                pass
+            except OSError as unlink_error:
+                print(
+                    f"Warning: could not remove temp file {temporary_path}: "
+                    f"{type(unlink_error).__name__}: {unlink_error}",
+                    file=sys.stderr,
+                )
 
 
 def append_if_missing(all_target_list: list[object], new_value: str) -> bool:

package/_shared/pr-loop/scripts/code_rules_gate.py

@@ -1673,7 +1673,6 @@ def main(all_arguments: list[str]) -> int:
     if arguments.staged:
         all_terminology_findings = staged_terminology_findings(repository_root)
         _report_terminology_findings(all_terminology_findings)
-        terminology_exit_code = 1 if all_terminology_findings else 0
         staged_test_exit_code = run_staged_test_files(repository_root)
         staged_file_paths = paths_from_git_staged(repository_root)
         staged_file_paths = filter_paths_under_prefixes(
@@ -1682,7 +1681,7 @@ def main(all_arguments: list[str]) -> int:
             arguments.only_under,
         )
         if not staged_file_paths:
-            return terminology_exit_code or staged_test_exit_code
+            return staged_test_exit_code
         staged_added_lines = added_lines_by_file_staged(
             repository_root, staged_file_paths
         )
@@ -1693,7 +1692,7 @@ def main(all_arguments: list[str]) -> int:
             all_added_lines_by_path=staged_added_lines,
             read_staged_content_flag=True,
         )
-        return gate_exit_code or terminology_exit_code or staged_test_exit_code
+        return gate_exit_code or staged_test_exit_code
     file_paths = paths_from_git_diff(repository_root, arguments.base)
     file_paths = filter_paths_under_prefixes(
         file_paths,

package/_shared/pr-loop/scripts/pr_loop_shared_constants/CLAUDE.md

@@ -16,7 +16,7 @@ Named constants for every script in `_shared/pr-loop/scripts/`. Each module owns
 | `preflight_self_heal_constants.py` | `preflight_self_heal.py` — git config keys and local-scope detection strings |
 | `reviews_disabled_constants.py` | `reviews_disabled.py` — `CLAUDE_REVIEWS_DISABLED` token taxonomy |
 | `copilot_quota_constants.py` | `copilot_quota.py` — `COPILOT_QUOTA_ACCOUNT` env-var name, `copilot_internal/user` API path, the `premium_interactions` gating field names, the four skip/run exit codes, and the default `.env` path |
-| `terminology_sweep_constants.py` | `terminology_sweep.py` — identifier and prose-token regexes, diff-parsing prefixes, code-file extensions, and the finding-message template |
+| `terminology_sweep_constants.py` | `terminology_sweep.py` — identifier and prose-token regexes, diff-parsing prefixes, code-file extensions, test-file detection patterns, and the finding-message template |
 | `reviewer_availability_constants.py` | `reviewer_availability.py` — the available/down exit codes for the unified reviewer-availability pre-check |
 | `__init__.py` | Empty package marker |
 

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

@@ -8,6 +8,8 @@ ALL_SWEEP_CODE_FILE_EXTENSIONS: frozenset[str] = frozenset(
 
 MARKDOWN_FILE_EXTENSION: str = ".md"
 
+PYTHON_FILE_EXTENSION: str = ".py"
+
 SNAKE_CASE_IDENTIFIER_PATTERN: re.Pattern[str] = re.compile(
     r"\b[a-z][a-z0-9]*(?:_[a-z0-9]+)+\b"
 )
@@ -28,6 +30,12 @@ STRING_LITERAL_CONTENT_PATTERN: re.Pattern[str] = re.compile(
     r"\"([^\"]*)\"|'([^']*)'|`([^`]*)`"
 )
 
+TEST_DIRECTORY_PATH_SEGMENT: str = "/tests/"
+
+TEST_FILE_NAME_PREFIX: str = "test_"
+
+ALL_TEST_FILE_NAME_INFIX_MARKERS: tuple[str, ...] = ("_test.", ".test.", ".spec.")
+
 DIFF_FILE_HEADER_PREFIX: str = "+++ "
 
 DIFF_HUNK_HEADER_PATTERN: re.Pattern[str] = re.compile(

package/_shared/pr-loop/scripts/reviews_disabled.py

@@ -103,6 +103,7 @@ def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
         choices=[
             CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN,
             CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
+            CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN,
         ],
         help="Reviewer token to test against CLAUDE_REVIEWS_DISABLED",
     )
@@ -122,6 +123,7 @@ def main(all_arguments: list[str]) -> int:
     disabled_checker_by_reviewer = {
         CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN: is_bugbot_disabled_via_env,
         CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN: is_bugteam_disabled_via_env,
+        CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN: is_copilot_disabled_via_env,
     }
     return 0 if disabled_checker_by_reviewer[arguments.reviewer]() else 1
 

package/_shared/pr-loop/scripts/terminology_sweep.py

@@ -1,40 +1,27 @@
-"""Flag prose terms that near-miss an identifier a diff introduces.
-
-Picture a change that adds an API field named ``premium_interactions``. On the
-same branch, the docs call it the ``premium-request`` budget. The code and the
-prose now name one thing two ways. A reader who searches for one term never
-finds the other.
-
-This sweep reads a unified diff and collects every multi-word identifier added
-on code lines. Then it scans each added prose line — a Markdown line, or a
-comment, docstring, or string inside a code file. It flags a hyphenated term
-that shares an identifier's leading word but diverges in the tail. Each
-near-miss prints as one ``file:line`` finding, and the run exits non-zero when
-any finding remains, so a commit gate can block on it.
-
-Only hyphenated terms are candidates. A hyphen marks a deliberate compound —
-the author bound the words into one term — so a divergent tail there is a real
-naming drift. A bare spaced word run is ordinary prose: windowing every
-sentence that starts with an identifier's first word ("each attempt", "file
-exists") floods a vocabulary-dense change with false findings and gives the
-gate nothing actionable.
-
-A shared leading token alone is too weak a signal: ordinary English compounds
-such as ``read-only`` and ``data-driven`` collide with unrelated identifiers
-(``read_config``, ``data_source``) and would block a commit falsely. To keep the
-grounding case (``premium-request`` against ``premium_interactions``) firing
-while sparing those compounds, a candidate whose final token is a common English
-compound tail word (``only``, ``driven``, ``safe``, and the rest listed in
-``ALL_COMMON_ENGLISH_COMPOUND_TAIL_WORDS``) is treated as ordinary prose, not a
-near-miss.
-
-Ordinary singular/plural prose is spared the same way. A candidate that differs
-from an identifier only by a singular/plural form of one or more tokens
-(``test files`` against ``test_file``, ``retry policies`` against
-``retry_policy``) is treated as the same term, not a near-miss.
+"""Flag a prose term that near-misses a code identifier a diff introduces.
+
+A change adds the field ``premium_interactions`` while the same branch's docs
+call it the ``premium-request`` budget: two names for one thing, and a reader
+who searches one never finds the other.
+
+::
+
+    code adds:  premium_interactions          (the identifier)
+    prose adds: "the premium-request budget"   (a hyphenated term)
+    flag: premium-request  vs  premium_interactions   -- shared first token, tail diverges
+    ok:   premium-interactions                 -- exact hyphen form, no drift
+    ok:   read-only,  test files               -- English compound or plural, not drift
+
+Only hyphenated prose is a candidate, since a hyphen marks a deliberate compound
+while a spaced word run is ordinary prose. Markdown scans in full; a JavaScript
+or TypeScript line contributes its comments and string literals; a Python file
+contributes identifiers only; a test code file is skipped whole. Each near-miss
+prints one ``file:line`` finding and the run exits non-zero, so a commit gate
+blocks on it.
 """
 
 import argparse
+import os
 import subprocess
 import sys
 from pathlib import Path
@@ -48,6 +35,7 @@ from pr_loop_shared_constants.terminology_sweep_constants import (  # noqa: E402
     ALL_DIFF_FILE_PATH_STRIP_PREFIXES,
     ALL_GIT_DIFF_CACHED_UNIFIED_ZERO_COMMAND,
     ALL_SWEEP_CODE_FILE_EXTENSIONS,
+    ALL_TEST_FILE_NAME_INFIX_MARKERS,
     CAMEL_CASE_IDENTIFIER_PATTERN,
     CAMEL_CASE_WORD_PATTERN,
     DIFF_ADDED_LINE_PREFIX,
@@ -64,10 +52,13 @@ from pr_loop_shared_constants.terminology_sweep_constants import (  # noqa: E402
     MARKDOWN_FILE_EXTENSION,
     MINIMUM_IDENTIFIER_TOKEN_COUNT,
     PYTHON_COMMENT_MARKER,
+    PYTHON_FILE_EXTENSION,
     SNAKE_CASE_IDENTIFIER_PATTERN,
     STRING_LITERAL_CONTENT_PATTERN,
     TERMINOLOGY_FINDING_TEMPLATE,
     TERMINOLOGY_SWEEP_DESCRIPTION,
+    TEST_DIRECTORY_PATH_SEGMENT,
+    TEST_FILE_NAME_PREFIX,
 )
 
 IdentifierTuple = tuple[str, ...]
@@ -124,6 +115,35 @@ def _file_extension(file_path: str) -> str:
     return Path(file_path).suffix.lower()
 
 
+def _is_test_file(file_path: str) -> bool:
+    """Return True when the diff path is a test code file the sweep should skip.
+
+    A test code file's prose is scaffolding: its docstrings and string fixtures
+    name the identifiers under test on purpose, so scanning it only adds noise. A
+    Markdown or other non-code file is prose worth scanning whatever its name, so
+    a ``test_plan.md`` design doc is scanned rather than skipped.
+
+    Args:
+        file_path: The repository-relative diff path.
+
+    Returns:
+        True for a code file under a ``tests`` directory, a ``test_`` prefixed
+        code file, or a code file whose name carries a
+        ``_test.``/``.test.``/``.spec.`` marker. False for any non-code file.
+    """
+    if _file_extension(file_path) not in ALL_SWEEP_CODE_FILE_EXTENSIONS:
+        return False
+    normalized_path = file_path.replace("\\", "/").lower()
+    if TEST_DIRECTORY_PATH_SEGMENT in f"/{normalized_path}":
+        return True
+    basename = normalized_path.rsplit("/", 1)[-1]
+    if basename.startswith(TEST_FILE_NAME_PREFIX):
+        return True
+    return any(
+        each_marker in basename for each_marker in ALL_TEST_FILE_NAME_INFIX_MARKERS
+    )
+
+
 def _identifier_token_tuple(identifier: str) -> IdentifierTuple:
     """Return the lowercase word tokens of a snake_case or camelCase identifier."""
     if "_" in identifier:
@@ -175,8 +195,11 @@ def _collect_introduced_identifiers(
 def _prose_fragments(file_path: str, line_text: str) -> list[str]:
     """Return the prose fragments of an added line worth scanning for terms.
 
-    A Markdown line is prose in full. A code line contributes its comment tail,
-    its JSDoc continuation text, and the contents of its string literals.
+    A Markdown line is prose in full. A JavaScript or TypeScript line contributes
+    its comment tail, its JSDoc continuation text, and the contents of its string
+    literals. A Python line contributes no prose: to avoid flagging a module's own
+    vocabulary as drift, the sweep ignores Python comments, docstrings, and string
+    literals and scans Python files for identifiers only.
 
     Args:
         file_path: The path the added line belongs to.
@@ -185,9 +208,12 @@ def _prose_fragments(file_path: str, line_text: str) -> list[str]:
     Returns:
         The prose fragments to scan for near-miss terms.
     """
-    if _file_extension(file_path) == MARKDOWN_FILE_EXTENSION:
+    extension = _file_extension(file_path)
+    if extension == MARKDOWN_FILE_EXTENSION:
         return [line_text]
-    if _file_extension(file_path) not in ALL_SWEEP_CODE_FILE_EXTENSIONS:
+    if extension not in ALL_SWEEP_CODE_FILE_EXTENSIONS:
+        return []
+    if extension == PYTHON_FILE_EXTENSION:
         return []
     all_fragments: list[str] = []
     stripped_line = line_text.strip()
@@ -352,7 +378,11 @@ def sweep_diff(diff_text: str) -> list[str]:
     Returns:
         One finding string per near-miss term on an added prose line.
     """
-    all_added_lines = _parse_added_lines(diff_text)
+    all_added_lines = [
+        each_added_line
+        for each_added_line in _parse_added_lines(diff_text)
+        if not _is_test_file(each_added_line[0])
+    ]
     all_identifier_tuples, identifiers_by_first_token = _collect_introduced_identifiers(
         all_added_lines
     )
@@ -372,6 +402,21 @@ def sweep_diff(diff_text: str) -> list[str]:
     return all_findings
 
 
+def _git_environment() -> dict[str, str]:
+    """Return the process environment with every GIT_ variable removed.
+
+    A git commit hook runs this sweep with GIT_INDEX_FILE pointed at the commit
+    index. Stripping every GIT_ variable makes ``git diff --cached`` read the
+    repository's own index, so the sweep sees the staged diff of the repository
+    it was handed rather than an ambient override.
+    """
+    return {
+        each_key: each_setting
+        for each_key, each_setting in os.environ.items()
+        if not each_key.startswith("GIT_")
+    }
+
+
 def staged_terminology_findings(repository_root: Path) -> list[str]:
     """Return terminology near-miss findings for a repository's staged diff.
 
@@ -391,6 +436,7 @@ def staged_terminology_findings(repository_root: Path) -> list[str]:
         errors="replace",
         timeout=GIT_DIFF_SUBPROCESS_TIMEOUT_SECONDS,
         check=False,
+        env=_git_environment(),
     )
     if diff_process.returncode != 0:
         return []

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

@@ -133,3 +133,215 @@ def test_path_contains_glob_metacharacters_accepts_windows_paths_with_parens() -
     assert common.path_contains_glob_metacharacters("C:/Users/Jon (Admin)/project") is False
     assert common.path_contains_glob_metacharacters("C:/Projects/a,b/file.py") is False
 
+
+def test_get_mode_to_preserve_returns_existing_file_mode(tmp_path: Path) -> None:
+    """When the file exists, the actual filesystem mode must be returned (not the default)."""
+    target_path = tmp_path / "settings.json"
+    target_path.write_text("{}", encoding="utf-8")
+    actual_filesystem_mode = target_path.stat().st_mode & 0o777
+    returned_mode = common.get_mode_to_preserve(target_path)
+    assert returned_mode == actual_filesystem_mode
+
+
+def test_get_mode_to_preserve_returns_secure_default_when_file_missing(
+    tmp_path: Path,
+) -> None:
+    """A missing settings file must fall back to the secure 0o600 default mode."""
+    missing_settings_path = tmp_path / "no_such_file.json"
+    returned_mode = common.get_mode_to_preserve(missing_settings_path)
+    assert returned_mode == 0o600
+
+
+def test_write_atomically_with_mode_raises_oserror_when_open_fails(
+    tmp_path: Path,
+) -> None:
+    """OSError from os.open must propagate to the caller."""
+    target_path = tmp_path / "subdirectory" / "missing" / "settings.json.tmp"
+    with pytest.raises(OSError):
+        common.write_atomically_with_mode(target_path, "payload", file_mode=0o600)
+
+
+def test_write_atomically_with_mode_unlinks_temp_when_fdopen_raises(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A failure inside os.fdopen must remove the on-disk temp file.
+
+    The file exists the moment os.open returns; closing only the raw
+    descriptor would leave an empty temp sibling on disk after the
+    exception propagates to the caller.
+    """
+
+    def failing_fdopen(*_args: object, **_kwargs: object) -> object:
+        raise MemoryError("fdopen failure")
+
+    monkeypatch.setattr(common.os, "fdopen", failing_fdopen)
+    target_path = tmp_path / "settings.json.tmp"
+    with pytest.raises(MemoryError):
+        common.write_atomically_with_mode(target_path, "payload", file_mode=0o600)
+    assert not target_path.exists(), (
+        "the temp file created by os.open must be unlinked before re-raising"
+    )
+
+
+def test_save_settings_warns_on_stderr_when_temp_unlink_fails(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A swallowed unlink in the finally block must surface to stderr.
+
+    Forces a write success followed by os.replace failure so the temp file
+    survives into the finally branch, then makes Path.unlink raise.
+    """
+    settings_path = tmp_path / "settings.json"
+    settings_path.write_text('{"existing": true}\n', encoding="utf-8")
+
+    def failing_replace(*_args: object, **_kwargs: object) -> None:
+        raise OSError("replace blocked by AV")
+
+    def failing_unlink(_self: Path, *_args: object, **_kwargs: object) -> None:
+        raise PermissionError("temp file held by AV")
+
+    monkeypatch.setattr(common.os, "replace", failing_replace)
+    monkeypatch.setattr(Path, "unlink", failing_unlink)
+    with pytest.raises(SystemExit):
+        common.save_settings(settings_path, {"new_key": "value"})
+    captured = capsys.readouterr()
+    assert ".tmp" in captured.err
+    assert "PermissionError" in captured.err or "held by AV" in captured.err
+
+
+def test_save_settings_finally_skips_unlink_when_no_temp_was_created(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """When this invocation never created the temp file, finally must not unlink it."""
+    settings_path = tmp_path / "settings.json"
+    settings_path.write_text('{"existing": true}\n', encoding="utf-8")
+
+    unlink_call_paths: list[Path] = []
+    original_unlink = Path.unlink
+
+    def recording_unlink(unlink_target: Path, *args: object, **kwargs: object) -> None:
+        unlink_call_paths.append(unlink_target)
+        original_unlink(unlink_target, *args, **kwargs)
+
+    def write_raises(*_args: object, **_kwargs: object) -> None:
+        raise FileExistsError("another writer's temp")
+
+    monkeypatch.setattr(common, "write_atomically_with_mode", write_raises)
+    monkeypatch.setattr(Path, "unlink", recording_unlink)
+    with pytest.raises(SystemExit):
+        common.save_settings(settings_path, {"new_key": "value"})
+    assert not any(
+        ".tmp." in each_path.name for each_path in unlink_call_paths
+    ), "finally must not unlink a temp file this invocation never created"
+
+
+def test_exit_with_error_prints_prefixed_message_and_exits_nonzero(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    with pytest.raises(SystemExit) as raised_exit:
+        common.exit_with_error("boom")
+    assert raised_exit.value.code == 1
+    assert "Error: boom" in capsys.readouterr().err
+
+
+def test_build_permission_rules_builds_one_rule_per_tool() -> None:
+    built_rules = common.build_permission_rules("/proj", ("Edit", "Read"))
+    assert built_rules == ["Edit(/proj/.claude/**)", "Read(/proj/.claude/**)"]
+
+
+def test_build_agent_config_deny_rule_embeds_tool_path_and_pattern() -> None:
+    built_rule = common.build_agent_config_deny_rule("Write", "/proj", "hooks/**")
+    assert built_rule == "Write(/proj/.claude/hooks/**)"
+
+
+def test_remove_matching_entries_from_list_filters_in_place_and_counts() -> None:
+    all_entries: list[object] = ["keep", "drop", "drop", 7]
+    removed_count = common.remove_matching_entries_from_list(
+        all_entries, lambda each_entry: each_entry == "drop"
+    )
+    assert removed_count == 2
+    assert all_entries == ["keep", 7]
+
+
+def test_load_settings_returns_empty_dict_when_file_missing(tmp_path: Path) -> None:
+    assert common.load_settings(tmp_path / "absent.json") == {}
+
+
+def test_load_settings_parses_existing_json_object(tmp_path: Path) -> None:
+    settings_path = tmp_path / "settings.json"
+    settings_path.write_text('{"permissions": {"allow": []}}', encoding="utf-8")
+    assert common.load_settings(settings_path) == {"permissions": {"allow": []}}
+
+
+def test_load_settings_exits_when_file_holds_invalid_json(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    settings_path = tmp_path / "settings.json"
+    settings_path.write_text("not json", encoding="utf-8")
+    with pytest.raises(SystemExit):
+        common.load_settings(settings_path)
+    assert "not valid JSON" in capsys.readouterr().err
+
+
+def test_serialize_settings_to_json_text_sorts_keys() -> None:
+    serialized_text = common.serialize_settings_to_json_text({"b": 1, "a": 2})
+    assert serialized_text.index('"a"') < serialized_text.index('"b"')
+    assert json.loads(serialized_text) == {"a": 2, "b": 1}
+
+
+def test_append_if_missing_appends_only_new_values() -> None:
+    all_entries: list[object] = ["existing"]
+    assert common.append_if_missing(all_entries, "fresh") is True
+    assert common.append_if_missing(all_entries, "fresh") is False
+    assert all_entries == ["existing", "fresh"]
+
+
+def test_ensure_dict_section_creates_missing_and_returns_existing() -> None:
+    all_settings: dict[str, object] = {}
+    created_section = common.ensure_dict_section(all_settings, "permissions")
+    assert created_section == {}
+    assert all_settings["permissions"] is created_section
+    assert common.ensure_dict_section(all_settings, "permissions") is created_section
+
+
+def test_ensure_dict_section_exits_on_non_dict_value(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    all_settings: dict[str, object] = {"permissions": "oops"}
+    with pytest.raises(SystemExit):
+        common.ensure_dict_section(all_settings, "permissions")
+    assert "not a JSON object" in capsys.readouterr().err
+
+
+def test_ensure_list_entry_creates_missing_and_returns_existing() -> None:
+    permissions_section: dict[str, object] = {}
+    created_entry = common.ensure_list_entry(permissions_section, "allow")
+    assert created_entry == []
+    assert permissions_section["allow"] is created_entry
+    assert common.ensure_list_entry(permissions_section, "allow") is created_entry
+
+
+def test_ensure_list_entry_exits_on_non_list_value(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    permissions_section: dict[str, object] = {"allow": {}}
+    with pytest.raises(SystemExit):
+        common.ensure_list_entry(permissions_section, "allow")
+    assert "not a JSON array" in capsys.readouterr().err
+
+
+def test_prune_empty_list_then_empty_section_removes_empty_structures() -> None:
+    all_settings: dict[str, object] = {"permissions": {"allow": []}}
+    common.prune_empty_list_then_empty_section(all_settings, "permissions", "allow")
+    assert all_settings == {}
+
+
+def test_prune_empty_list_then_empty_section_keeps_populated_structures() -> None:
+    all_settings: dict[str, object] = {
+        "permissions": {"allow": ["Edit(/proj/.claude/**)"], "deny": []}
+    }
+    common.prune_empty_list_then_empty_section(all_settings, "permissions", "deny")
+    assert all_settings == {"permissions": {"allow": ["Edit(/proj/.claude/**)"]}}
+

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

@@ -355,6 +355,24 @@ def test_is_trust_entry_rejects_cross_project_path_suffix_collision() -> None:
     )
 
 
+def test_is_valid_project_root_shared_by_grant_and_revoke_modules(
+    tmp_path: Path,
+) -> None:
+    """Grant and revoke import the same helper, so both agree on the marker contract."""
+    grant_module = _load_grant_module()
+    revoke_module = _load_revoke_module()
+    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()
+    for each_module in (grant_module, revoke_module):
+        assert each_module.is_valid_project_root(git_marker_project_root) is True
+        assert each_module.is_valid_project_root(claude_marker_project_root) is True
+        assert each_module.is_valid_project_root(bare_directory) is False
+
+
 def test_second_grant_is_idempotent_when_no_other_settings_changed(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None: