claude-dev-env 1.94.0 → 2.0.0

package/hooks/blocking/test_code_rules_shared.py

@@ -0,0 +1,181 @@
+"""Tests for the harness session scratchpad exemption in code_rules_shared."""
+
+import importlib.util
+import os
+import tempfile
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+SHARED_MODULE_PATH = Path(__file__).parent / "code_rules_shared.py"
+FIXED_USER_ID = 4242
+WORKING_DIRECTORY = "/home/user/project"
+SESSION_ID = "session-abc-123"
+
+
+def _load_shared_module() -> ModuleType:
+    module_spec = importlib.util.spec_from_file_location(
+        "code_rules_shared_under_test", SHARED_MODULE_PATH
+    )
+    assert module_spec is not None and module_spec.loader is not None
+    loaded_module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(loaded_module)
+    return loaded_module
+
+
+_SHARED_MODULE = _load_shared_module()
+
+
+def _install_fixed_user_id(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(os, "getuid", lambda: FIXED_USER_ID, raising=False)
+
+
+def _point_temporary_directory_at(monkeypatch: pytest.MonkeyPatch, temporary_root: Path) -> None:
+    monkeypatch.setattr(tempfile, "gettempdir", lambda: str(temporary_root))
+
+
+def _build_scratchpad_directory(temporary_root: Path) -> Path:
+    mangled_working_directory = WORKING_DIRECTORY.replace("/", "-")
+    scratchpad_directory = (
+        temporary_root
+        / f"claude-{FIXED_USER_ID}"
+        / mangled_working_directory
+        / SESSION_ID
+        / "scratchpad"
+    )
+    scratchpad_directory.mkdir(parents=True)
+    return scratchpad_directory
+
+
+def _session_payload() -> dict[str, str]:
+    return {"cwd": WORKING_DIRECTORY, "session_id": SESSION_ID}
+
+
+def test_returns_true_for_file_inside_reconstructed_scratchpad(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install_fixed_user_id(monkeypatch)
+    _point_temporary_directory_at(monkeypatch, tmp_path)
+    scratchpad_directory = _build_scratchpad_directory(tmp_path)
+    throwaway_script = scratchpad_directory / "one_off_tool.py"
+
+    assert (
+        _SHARED_MODULE.is_under_session_scratchpad(str(throwaway_script), _session_payload())
+        is True
+    )
+
+
+def test_returns_false_for_file_outside_scratchpad(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install_fixed_user_id(monkeypatch)
+    _point_temporary_directory_at(monkeypatch, tmp_path)
+    _build_scratchpad_directory(tmp_path)
+    project_module = tmp_path / "elsewhere" / "orders.py"
+
+    assert (
+        _SHARED_MODULE.is_under_session_scratchpad(str(project_module), _session_payload()) is False
+    )
+
+
+def test_resolves_symlink_into_scratchpad_to_true(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install_fixed_user_id(monkeypatch)
+    _point_temporary_directory_at(monkeypatch, tmp_path)
+    scratchpad_directory = _build_scratchpad_directory(tmp_path)
+    real_script = scratchpad_directory / "real_tool.py"
+    real_script.write_text("value = 1\n")
+    link_outside = tmp_path / "link_to_scratchpad.py"
+    link_outside.symlink_to(real_script)
+
+    assert _SHARED_MODULE.is_under_session_scratchpad(str(link_outside), _session_payload()) is True
+
+
+def test_symlink_resolving_outside_scratchpad_is_false(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install_fixed_user_id(monkeypatch)
+    _point_temporary_directory_at(monkeypatch, tmp_path)
+    scratchpad_directory = _build_scratchpad_directory(tmp_path)
+    real_target_outside = tmp_path / "outside_target.py"
+    real_target_outside.write_text("value = 1\n")
+    link_inside_scratchpad = scratchpad_directory / "sneaky_link.py"
+    link_inside_scratchpad.symlink_to(real_target_outside)
+
+    assert (
+        _SHARED_MODULE.is_under_session_scratchpad(str(link_inside_scratchpad), _session_payload())
+        is False
+    )
+
+
+def test_missing_session_id_signal_returns_false(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install_fixed_user_id(monkeypatch)
+    _point_temporary_directory_at(monkeypatch, tmp_path)
+    scratchpad_directory = _build_scratchpad_directory(tmp_path)
+    throwaway_script = scratchpad_directory / "one_off_tool.py"
+    payload_without_session = {"cwd": WORKING_DIRECTORY}
+
+    assert (
+        _SHARED_MODULE.is_under_session_scratchpad(str(throwaway_script), payload_without_session)
+        is False
+    )
+
+
+def test_missing_working_directory_signal_returns_false(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install_fixed_user_id(monkeypatch)
+    _point_temporary_directory_at(monkeypatch, tmp_path)
+    scratchpad_directory = _build_scratchpad_directory(tmp_path)
+    throwaway_script = scratchpad_directory / "one_off_tool.py"
+    payload_without_cwd = {"session_id": SESSION_ID}
+
+    assert (
+        _SHARED_MODULE.is_under_session_scratchpad(str(throwaway_script), payload_without_cwd)
+        is False
+    )
+
+
+def test_absent_getuid_returns_false(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    _install_fixed_user_id(monkeypatch)
+    _point_temporary_directory_at(monkeypatch, tmp_path)
+    scratchpad_directory = _build_scratchpad_directory(tmp_path)
+    throwaway_script = scratchpad_directory / "one_off_tool.py"
+    monkeypatch.delattr(os, "getuid", raising=False)
+
+    assert (
+        _SHARED_MODULE.is_under_session_scratchpad(str(throwaway_script), _session_payload())
+        is False
+    )
+
+
+def test_nonexistent_scratchpad_directory_returns_false(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install_fixed_user_id(monkeypatch)
+    _point_temporary_directory_at(monkeypatch, tmp_path)
+    mangled_working_directory = WORKING_DIRECTORY.replace("/", "-")
+    unbuilt_target = (
+        tmp_path
+        / f"claude-{FIXED_USER_ID}"
+        / mangled_working_directory
+        / SESSION_ID
+        / "scratchpad"
+        / "one_off_tool.py"
+    )
+
+    assert (
+        _SHARED_MODULE.is_under_session_scratchpad(str(unbuilt_target), _session_payload()) is False
+    )
+
+
+def test_empty_file_path_returns_false(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    _install_fixed_user_id(monkeypatch)
+    _point_temporary_directory_at(monkeypatch, tmp_path)
+    _build_scratchpad_directory(tmp_path)
+
+    assert _SHARED_MODULE.is_under_session_scratchpad("", _session_payload()) is False

package/hooks/blocking/test_inventory_deadlock_resolution.py

@@ -0,0 +1,154 @@
+"""End-to-end tests for the inventory/orphan pending-intent deadlock resolution.
+
+Each test drives the two real hook binaries through their production ``main()``
+stdin path over a temp directory tree whose ``CLAUDE.md`` inventory names two
+sibling files. A shared ``session_id`` and an isolated ``TMPDIR`` make the two
+hooks read one shared intent-records file, so a deny by one hook opens the gate
+for the sibling's second write — in either add order.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+BLOCKING_DIRECTORY = Path(__file__).resolve().parent
+
+INVENTORY_HOOK = "package_inventory_stale_blocker.py"
+ORPHAN_HOOK = "claude_md_orphan_file_blocker.py"
+
+SESSION_ID = "deadlock-session"
+
+INVENTORY_TABLE_HEADER = "# pkg\n\n| File | Purpose |\n|---|---|\n"
+ALPHA_ROW = "| `alpha.py` | Does A |\n"
+BETA_ROW = "| `beta.py` | Does B |\n"
+GAMMA_ROW = "| `gamma.py` | Does G |\n"
+EPSILON_ROW = "| `epsilon.py` | Does E |\n"
+
+BASE_INVENTORY = INVENTORY_TABLE_HEADER + ALPHA_ROW + BETA_ROW
+INVENTORY_WITH_GAMMA = BASE_INVENTORY + GAMMA_ROW
+INVENTORY_WITH_EPSILON = BASE_INVENTORY + EPSILON_ROW
+
+MODULE_BODY = "x = 1\n"
+
+
+def _package_directory(tmp_path: Path) -> Path:
+    """Return a package directory holding a CLAUDE.md table naming two siblings."""
+    package_directory = tmp_path / "pkg"
+    package_directory.mkdir()
+    (package_directory / "CLAUDE.md").write_text(BASE_INVENTORY, encoding="utf-8")
+    (package_directory / "alpha.py").write_text(MODULE_BODY, encoding="utf-8")
+    (package_directory / "beta.py").write_text(MODULE_BODY, encoding="utf-8")
+    return package_directory
+
+
+def _run_hook(
+    hook_filename: str, tool_name: str, tool_input: dict, temp_directory: Path
+) -> subprocess.CompletedProcess:
+    """Run one hook binary over a payload, sharing an isolated intent-records store."""
+    payload = json.dumps(
+        {"tool_name": tool_name, "tool_input": tool_input, "session_id": SESSION_ID}
+    )
+    hook_environment = dict(os.environ)
+    hook_environment["TMPDIR"] = str(temp_directory)
+    return subprocess.run(
+        [sys.executable, str(BLOCKING_DIRECTORY / hook_filename)],
+        input=payload,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=hook_environment,
+    )
+
+
+def _decision(completed: subprocess.CompletedProcess) -> str | None:
+    """Return the permission decision a hook emitted, or None when it allowed."""
+    if not completed.stdout.strip():
+        return None
+    return json.loads(completed.stdout)["hookSpecificOutput"]["permissionDecision"]
+
+
+def _reason(completed: subprocess.CompletedProcess) -> str:
+    """Return the deny reason a hook emitted."""
+    return json.loads(completed.stdout)["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_file_first_order_resolves_after_one_deny(tmp_path: Path) -> None:
+    package_directory = _package_directory(tmp_path)
+    new_file = package_directory / "gamma.py"
+    claude_md = package_directory / "CLAUDE.md"
+
+    first_write = _run_hook(
+        INVENTORY_HOOK, "Write", {"file_path": str(new_file), "content": MODULE_BODY}, tmp_path
+    )
+    assert _decision(first_write) == "deny"
+    assert "gamma.py" in _reason(first_write)
+    assert "recorded" in _reason(first_write)
+
+    row_write = _run_hook(
+        ORPHAN_HOOK,
+        "Write",
+        {"file_path": str(claude_md), "content": INVENTORY_WITH_GAMMA},
+        tmp_path,
+    )
+    assert _decision(row_write) is None
+
+    claude_md.write_text(INVENTORY_WITH_GAMMA, encoding="utf-8")
+    retry_write = _run_hook(
+        INVENTORY_HOOK, "Write", {"file_path": str(new_file), "content": MODULE_BODY}, tmp_path
+    )
+    assert _decision(retry_write) is None
+
+
+def test_row_first_order_resolves_after_one_deny(tmp_path: Path) -> None:
+    package_directory = _package_directory(tmp_path)
+    new_file = package_directory / "gamma.py"
+    claude_md = package_directory / "CLAUDE.md"
+
+    first_row = _run_hook(
+        ORPHAN_HOOK,
+        "Write",
+        {"file_path": str(claude_md), "content": INVENTORY_WITH_GAMMA},
+        tmp_path,
+    )
+    assert _decision(first_row) == "deny"
+    assert "gamma.py" in _reason(first_row)
+    assert "recorded" in _reason(first_row)
+
+    file_write = _run_hook(
+        INVENTORY_HOOK, "Write", {"file_path": str(new_file), "content": MODULE_BODY}, tmp_path
+    )
+    assert _decision(file_write) is None
+
+    new_file.write_text(MODULE_BODY, encoding="utf-8")
+    retry_row = _run_hook(
+        ORPHAN_HOOK,
+        "Write",
+        {"file_path": str(claude_md), "content": INVENTORY_WITH_GAMMA},
+        tmp_path,
+    )
+    assert _decision(retry_row) is None
+
+
+def test_new_file_with_no_row_attempt_stays_blocked(tmp_path: Path) -> None:
+    package_directory = _package_directory(tmp_path)
+    new_file = package_directory / "delta.py"
+    file_write = _run_hook(
+        INVENTORY_HOOK, "Write", {"file_path": str(new_file), "content": MODULE_BODY}, tmp_path
+    )
+    assert _decision(file_write) == "deny"
+    assert "delta.py" in _reason(file_write)
+
+
+def test_row_naming_uncreated_file_stays_blocked(tmp_path: Path) -> None:
+    package_directory = _package_directory(tmp_path)
+    claude_md = package_directory / "CLAUDE.md"
+    row_write = _run_hook(
+        ORPHAN_HOOK,
+        "Write",
+        {"file_path": str(claude_md), "content": INVENTORY_WITH_EPSILON},
+        tmp_path,
+    )
+    assert _decision(row_write) == "deny"
+    assert "epsilon.py" in _reason(row_write)

package/hooks/blocking/test_pii_payload_scan.py

@@ -0,0 +1,168 @@
+"""Behavior tests for the Write/Edit payload PII evaluation."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_HOOK_DIR = Path(__file__).parent
+_HOOKS_DIR = _HOOK_DIR.parent
+
+try:
+    from pii_payload_scan import evaluate_post_body_texts, evaluate_write_edit_payload
+except ImportError:
+    for each_bootstrap_directory in (str(_HOOK_DIR), str(_HOOKS_DIR)):
+        if each_bootstrap_directory not in sys.path:
+            sys.path.insert(0, each_bootstrap_directory)
+    from pii_payload_scan import evaluate_post_body_texts, evaluate_write_edit_payload
+
+_ALLOW_SLUG = "AllowOwner/allow-repo"
+_OTHER_SLUG = "OtherOwner/other-repo"
+
+
+def test_post_body_with_pii_is_blocked_by_default() -> None:
+    deny_reason = evaluate_post_body_texts([_assembled_fixture_email()])
+    assert deny_reason is not None
+    assert "post body" in deny_reason
+
+
+def test_post_body_allowlisted_values_plumb_through_to_the_scan() -> None:
+    allowed_value = _assembled_fixture_email()
+    deny_reason = evaluate_post_body_texts(
+        [allowed_value], all_allowlisted_values=frozenset({allowed_value})
+    )
+    assert deny_reason is None
+
+
+def test_post_body_unlisted_value_still_blocked_beside_allowlist() -> None:
+    deny_reason = evaluate_post_body_texts(
+        [_assembled_unlisted_email()],
+        all_allowlisted_values=frozenset({_assembled_fixture_email()}),
+    )
+    assert deny_reason is not None
+    assert "post body" in deny_reason
+
+
+def _assembled_fixture_email() -> str:
+    return "owner.fixture" + "@" + "acme-corp" + ".example" + ".io"
+
+
+def _assembled_unlisted_email() -> str:
+    return "other.person" + "@" + "different-co" + ".example" + ".io"
+
+
+def _write_allowlist_identity(identity_path: Path, slug: str, value: str) -> None:
+    identity_path.write_text(
+        json.dumps({"pii_allowlisted_values": {slug: [value]}}),
+        encoding="utf-8",
+    )
+
+
+def _init_repo_with_github_origin(repository_root: Path, origin_slug: str) -> None:
+    repository_root.mkdir(parents=True, exist_ok=True)
+    subprocess.run(["git", "init", "-q"], cwd=repository_root, check=True)
+    origin_url = "https://github.com/" + origin_slug + ".git"
+    subprocess.run(
+        ["git", "remote", "add", "origin", origin_url],
+        cwd=repository_root,
+        check=True,
+    )
+
+
+def _write_deny_reason(target_path: Path, value: str) -> str | None:
+    content = "owner email " + value + "\n"
+    return evaluate_write_edit_payload(
+        "Write", {"file_path": str(target_path), "content": content}
+    )
+
+
+def test_write_payload_with_a_fixture_email_is_flagged(tmp_path: Path) -> None:
+    deny_reason = _write_deny_reason(tmp_path / "notes.md", _assembled_fixture_email())
+    assert deny_reason is not None
+    assert "email" in deny_reason
+
+
+def test_allowlisted_value_under_the_allowlisted_repo_is_allowed(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    allowed_value = _assembled_fixture_email()
+    identity_path = tmp_path / "local-identity.json"
+    _write_allowlist_identity(identity_path, _ALLOW_SLUG, allowed_value)
+    monkeypatch.setenv("CLAUDE_LOCAL_IDENTITY_PATH", str(identity_path))
+    repository_root = tmp_path / "repo"
+    _init_repo_with_github_origin(repository_root, _ALLOW_SLUG)
+    assert _write_deny_reason(repository_root / "notes.md", allowed_value) is None
+
+
+def test_allowlisted_value_in_a_different_repo_is_blocked(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    allowed_value = _assembled_fixture_email()
+    identity_path = tmp_path / "local-identity.json"
+    _write_allowlist_identity(identity_path, _ALLOW_SLUG, allowed_value)
+    monkeypatch.setenv("CLAUDE_LOCAL_IDENTITY_PATH", str(identity_path))
+    repository_root = tmp_path / "repo"
+    _init_repo_with_github_origin(repository_root, _OTHER_SLUG)
+    deny_reason = _write_deny_reason(repository_root / "notes.md", allowed_value)
+    assert deny_reason is not None
+    assert "email" in deny_reason
+
+
+def test_unlisted_value_in_the_allowlisted_repo_is_blocked(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    identity_path = tmp_path / "local-identity.json"
+    _write_allowlist_identity(identity_path, _ALLOW_SLUG, _assembled_fixture_email())
+    monkeypatch.setenv("CLAUDE_LOCAL_IDENTITY_PATH", str(identity_path))
+    repository_root = tmp_path / "repo"
+    _init_repo_with_github_origin(repository_root, _ALLOW_SLUG)
+    deny_reason = _write_deny_reason(
+        repository_root / "notes.md", _assembled_unlisted_email()
+    )
+    assert deny_reason is not None
+    assert "email" in deny_reason
+
+
+def test_clean_write_payload_skips_repository_resolution(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    identity_path = tmp_path / "local-identity.json"
+    _write_allowlist_identity(identity_path, _ALLOW_SLUG, _assembled_fixture_email())
+    monkeypatch.setenv("CLAUDE_LOCAL_IDENTITY_PATH", str(identity_path))
+    repository_root = tmp_path / "repo"
+    _init_repo_with_github_origin(repository_root, _ALLOW_SLUG)
+
+    def _fail_if_called(_working_directory: str | None) -> None:
+        raise AssertionError(
+            "resolve_repository_root should not run for a payload with no PII"
+        )
+
+    monkeypatch.setattr(
+        sys.modules["pii_payload_scan"], "resolve_repository_root", _fail_if_called
+    )
+    deny_reason = evaluate_write_edit_payload(
+        "Write",
+        {
+            "file_path": str(repository_root / "notes.md"),
+            "content": "nothing sensitive here\n",
+        },
+    )
+    assert deny_reason is None
+
+
+def test_allowlisted_value_under_missing_nested_parent_is_allowed(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    allowed_value = _assembled_fixture_email()
+    identity_path = tmp_path / "local-identity.json"
+    _write_allowlist_identity(identity_path, _ALLOW_SLUG, allowed_value)
+    monkeypatch.setenv("CLAUDE_LOCAL_IDENTITY_PATH", str(identity_path))
+    repository_root = tmp_path / "repo"
+    _init_repo_with_github_origin(repository_root, _ALLOW_SLUG)
+    nested_target = repository_root / "new_dir" / "deeper" / "notes.md"
+    assert not nested_target.parent.exists()
+    assert _write_deny_reason(nested_target, allowed_value) is None

package/hooks/blocking/test_plain_language_blocker_allowlist.py

@@ -0,0 +1,184 @@
+"""Tests for the per-project domain-vocabulary allowlist in plain_language_blocker."""
+
+import importlib.util
+import json
+from pathlib import Path
+from types import ModuleType
+
+BLOCKER_PATH = Path(__file__).parent / "plain_language_blocker.py"
+ALLOWLIST_RELATIVE_PATH = Path(".claude") / "plain-language-allow.json"
+ALWAYS_HEAVY_WORD = "utilize"
+
+
+def _load_blocker() -> ModuleType:
+    module_spec = importlib.util.spec_from_file_location(
+        "plain_language_blocker_allowlist_under_test", BLOCKER_PATH
+    )
+    assert module_spec is not None and module_spec.loader is not None
+    loaded_module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(loaded_module)
+    return loaded_module
+
+
+_BLOCKER = _load_blocker()
+
+
+def _init_repo(root: Path) -> Path:
+    (root / ".git").mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def _write_allowlist(project_root: Path, all_words: list[str]) -> None:
+    allowlist_path = project_root / ALLOWLIST_RELATIVE_PATH
+    allowlist_path.parent.mkdir(parents=True, exist_ok=True)
+    allowlist_path.write_text(json.dumps(all_words), encoding="utf-8")
+
+
+def _write_raw_allowlist(project_root: Path, raw_text: str) -> None:
+    allowlist_path = project_root / ALLOWLIST_RELATIVE_PATH
+    allowlist_path.parent.mkdir(parents=True, exist_ok=True)
+    allowlist_path.write_text(raw_text, encoding="utf-8")
+
+
+def _markdown_write_payload(project_root: Path, prose: str) -> dict[str, object]:
+    document_path = project_root / "docs" / "notes.md"
+    return {
+        "tool_name": "Write",
+        "cwd": str(project_root),
+        "tool_input": {"file_path": str(document_path), "content": prose},
+    }
+
+
+def _ask_user_question_payload(project_root: Path, prose: str) -> dict[str, object]:
+    return {
+        "tool_name": "AskUserQuestion",
+        "cwd": str(project_root),
+        "tool_input": {"questions": [{"question": prose, "options": []}]},
+    }
+
+
+def test_allowlisted_word_passes_in_markdown_write(tmp_path: Path) -> None:
+    prose = "Please submit the release notes."
+    project_without_allowlist = _init_repo(tmp_path / "control")
+    project_with_allowlist = _init_repo(tmp_path / "domain")
+    _write_allowlist(project_with_allowlist, ["submit"])
+
+    control_deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(project_without_allowlist, prose)
+    )
+    allowlisted_deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(project_with_allowlist, prose)
+    )
+
+    assert control_deny_reason is not None and "submit" in control_deny_reason
+    assert allowlisted_deny_reason is None
+
+
+def test_allowlisted_word_passes_in_ask_user_question(tmp_path: Path) -> None:
+    prose = "Which theme should we identify first?"
+    project_without_allowlist = _init_repo(tmp_path / "control")
+    project_with_allowlist = _init_repo(tmp_path / "domain")
+    _write_allowlist(project_with_allowlist, ["identify"])
+
+    control_deny_reason = _BLOCKER.evaluate(
+        _ask_user_question_payload(project_without_allowlist, prose)
+    )
+    allowlisted_deny_reason = _BLOCKER.evaluate(
+        _ask_user_question_payload(project_with_allowlist, prose)
+    )
+
+    assert control_deny_reason is not None and "identify" in control_deny_reason
+    assert allowlisted_deny_reason is None
+
+
+def test_non_allowlisted_heavy_word_still_blocked(tmp_path: Path) -> None:
+    _init_repo(tmp_path)
+    _write_allowlist(tmp_path, ["submit"])
+
+    deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(tmp_path, f"Please {ALWAYS_HEAVY_WORD} the cache now.")
+    )
+
+    assert deny_reason is not None and ALWAYS_HEAVY_WORD in deny_reason
+
+
+def test_allowlist_match_is_case_insensitive(tmp_path: Path) -> None:
+    prose = "Please SUBMIT the release notes."
+    project_without_allowlist = _init_repo(tmp_path / "control")
+    project_with_allowlist = _init_repo(tmp_path / "domain")
+    _write_allowlist(project_with_allowlist, ["Submit"])
+
+    control_deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(project_without_allowlist, prose)
+    )
+    allowlisted_deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(project_with_allowlist, prose)
+    )
+
+    assert control_deny_reason is not None and "submit" in control_deny_reason
+    assert allowlisted_deny_reason is None
+
+
+def test_malformed_allowlist_json_is_ignored(tmp_path: Path) -> None:
+    _init_repo(tmp_path)
+    _write_raw_allowlist(tmp_path, "{ this is not valid json ")
+
+    deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(tmp_path, "Please submit the release notes.")
+    )
+
+    assert deny_reason is not None and "submit" in deny_reason
+
+
+def test_allowlist_in_a_different_project_root_is_not_applied(tmp_path: Path) -> None:
+    project_with_allowlist = _init_repo(tmp_path / "project_a")
+    project_without_allowlist = _init_repo(tmp_path / "project_b")
+    _write_allowlist(project_with_allowlist, ["submit"])
+
+    deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(project_without_allowlist, "Please submit the notes.")
+    )
+
+    assert deny_reason is not None and "submit" in deny_reason
+
+
+def test_allowlist_above_the_repo_root_is_not_applied(tmp_path: Path) -> None:
+    _write_allowlist(tmp_path, ["submit"])
+    repository_root = _init_repo(tmp_path / "repo")
+
+    deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(repository_root, "Please submit the notes.")
+    )
+
+    assert deny_reason is not None and "submit" in deny_reason
+
+
+def test_allowlist_at_the_repo_root_is_applied(tmp_path: Path) -> None:
+    repository_root = _init_repo(tmp_path / "repo")
+    _write_allowlist(repository_root, ["submit"])
+
+    deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(repository_root, "Please submit the notes.")
+    )
+
+    assert deny_reason is None
+
+
+def test_allowlist_without_a_repo_root_is_not_applied(tmp_path: Path) -> None:
+    _write_allowlist(tmp_path, ["submit"])
+
+    deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(tmp_path, "Please submit the notes.")
+    )
+
+    assert deny_reason is not None and "submit" in deny_reason
+
+
+def test_find_banned_terms_skips_allowlisted_terms() -> None:
+    matched_without_allowlist = _BLOCKER.find_banned_terms("Please submit the notes.")
+    matched_with_allowlist = _BLOCKER.find_banned_terms(
+        "Please submit the notes.", frozenset({"submit"})
+    )
+
+    assert any(each_term == "submit" for each_term, _ in matched_without_allowlist)
+    assert all(each_term != "submit" for each_term, _ in matched_with_allowlist)