claude-dev-env 2.2.1 → 2.4.0

package/hooks/blocking/test_code_review_push_gate.py

@@ -0,0 +1,189 @@
+"""Behavioral tests for the push code-review gate.
+
+Each test drives the gate against a real git work tree with a change surface
+and a real stamp store under an isolated home, so the deny/allow decision runs
+the same hash-and-coverage path the hook runs in production.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import subprocess
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+_HOOK_DIR = Path(__file__).resolve().parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+GIT_TIMEOUT_SECONDS = 30
+LOW_EFFORT = "low"
+XHIGH_EFFORT = "xhigh"
+CODE_SOURCE = "def add(a: int, b: int) -> int:\n    return a + b\n"
+CODE_CHANGE = "def add(a: int, b: int) -> int:\n    return a - b\n"
+DOCS_SOURCE = "# Notes\n\nfirst line\n"
+DOCS_CHANGE = "# Notes\n\nsecond line\n"
+BYPASS_MARKER = "# code-review-skip"
+
+
+def _load_module(module_name: str) -> ModuleType:
+    module_spec = importlib.util.spec_from_file_location(
+        module_name, _HOOK_DIR / f"{module_name}.py"
+    )
+    assert module_spec is not None
+    assert 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
+
+
+gate_module = _load_module("code_review_push_gate")
+store_module = _load_module("code_review_stamp_store")
+
+
+def _run_git(repository_directory: Path, *git_arguments: str) -> None:
+    subprocess.run(
+        ["git", "-C", str(repository_directory), *git_arguments],
+        check=True,
+        capture_output=True,
+        text=True,
+        timeout=GIT_TIMEOUT_SECONDS,
+    )
+
+
+def _init_pushed_repo(tmp_path: Path, tracked_name: str, base_text: str) -> Path:
+    origin_directory = tmp_path / "origin.git"
+    work_directory = tmp_path / "work"
+    work_directory.mkdir()
+    subprocess.run(
+        ["git", "init", "--bare", "--initial-branch=main", str(origin_directory)],
+        check=True,
+        capture_output=True,
+        text=True,
+        timeout=GIT_TIMEOUT_SECONDS,
+    )
+    _run_git(work_directory, "init", "--initial-branch=main")
+    _run_git(work_directory, "config", "user.email", "tests@example.com")
+    _run_git(work_directory, "config", "user.name", "Reviewer")
+    (work_directory / tracked_name).write_text(base_text, encoding="utf-8")
+    _run_git(work_directory, "add", "-A")
+    _run_git(work_directory, "commit", "-m", "base")
+    _run_git(work_directory, "remote", "add", "origin", str(origin_directory))
+    _run_git(work_directory, "push", "-u", "origin", "main")
+    return work_directory
+
+
+def _make_code_surface_repo(tmp_path: Path) -> Path:
+    work_directory = _init_pushed_repo(tmp_path, "app.py", CODE_SOURCE)
+    (work_directory / "app.py").write_text(CODE_CHANGE, encoding="utf-8")
+    return work_directory
+
+
+def _make_docs_surface_repo(tmp_path: Path) -> Path:
+    work_directory = _init_pushed_repo(tmp_path, "notes.md", DOCS_SOURCE)
+    (work_directory / "notes.md").write_text(DOCS_CHANGE, encoding="utf-8")
+    return work_directory
+
+
+def _isolate_home(monkeypatch: pytest.MonkeyPatch, fake_home: Path) -> None:
+    home_text = str(fake_home)
+    monkeypatch.setenv("HOME", home_text)
+    monkeypatch.setenv("USERPROFILE", home_text)
+    monkeypatch.delenv("HOMEDRIVE", raising=False)
+    monkeypatch.delenv("HOMEPATH", raising=False)
+
+
+def _prepared_code_repo(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    return _make_code_surface_repo(tmp_path)
+
+
+def _record_stamp(work_directory: Path, effort: str) -> None:
+    surface_hash = store_module.live_surface_hash(str(work_directory))
+    assert surface_hash is not None
+    store_module.record_clean_stamp(str(work_directory), surface_hash, effort)
+
+
+def _run_main(monkeypatch: pytest.MonkeyPatch, command_text: str, work_directory: Path) -> str:
+    payload_text = json.dumps(
+        {
+            "tool_name": "Bash",
+            "tool_input": {"command": command_text},
+            "cwd": str(work_directory),
+        }
+    )
+    monkeypatch.setattr(sys, "stdin", io.StringIO(payload_text))
+    captured_stdout = io.StringIO()
+    monkeypatch.setattr(sys, "stdout", captured_stdout)
+    gate_module.main()
+    return captured_stdout.getvalue()
+
+
+def test_push_without_low_stamp_denies(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    work_directory = _prepared_code_repo(monkeypatch, tmp_path)
+    deny_reason = gate_module.deny_reason_for_directory(str(work_directory))
+    assert deny_reason is not None
+    assert "PUSH_GATE" in deny_reason
+
+
+def test_covering_low_stamp_allows_push(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    work_directory = _prepared_code_repo(monkeypatch, tmp_path)
+    _record_stamp(work_directory, LOW_EFFORT)
+    assert gate_module.deny_reason_for_directory(str(work_directory)) is None
+
+
+def test_covering_xhigh_stamp_allows_push(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    work_directory = _prepared_code_repo(monkeypatch, tmp_path)
+    _record_stamp(work_directory, XHIGH_EFFORT)
+    assert gate_module.deny_reason_for_directory(str(work_directory)) is None
+
+
+def test_docs_only_surface_is_exempt(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    work_directory = _make_docs_surface_repo(tmp_path)
+    assert gate_module.deny_reason_for_directory(str(work_directory)) is None
+
+
+def test_git_push_payload_denies(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    work_directory = _prepared_code_repo(monkeypatch, tmp_path)
+    emitted = _run_main(monkeypatch, "git push origin main", work_directory)
+    assert "PUSH_GATE" in emitted
+
+
+def test_git_push_with_leading_flags_denies(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    work_directory = _prepared_code_repo(monkeypatch, tmp_path)
+    emitted = _run_main(monkeypatch, "git push --force-with-lease origin main", work_directory)
+    assert "PUSH_GATE" in emitted
+
+
+def test_git_commit_is_not_gated_by_push_hook(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    work_directory = _prepared_code_repo(monkeypatch, tmp_path)
+    emitted = _run_main(monkeypatch, "git commit -m change", work_directory)
+    assert emitted == ""
+
+
+def test_git_stash_push_is_not_gated(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    work_directory = _prepared_code_repo(monkeypatch, tmp_path)
+    emitted = _run_main(monkeypatch, "git stash push", work_directory)
+    assert emitted == ""
+
+
+def test_code_review_skip_marker_allows_push(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    work_directory = _prepared_code_repo(monkeypatch, tmp_path)
+    emitted = _run_main(monkeypatch, f"git push origin main {BYPASS_MARKER}", work_directory)
+    assert emitted == ""

package/hooks/blocking/test_code_review_stamp_directory_write_blocker.py

@@ -0,0 +1,180 @@
+"""Behavioral tests for the code-review stamp-directory write blocker.
+
+The blocker denies shell and file-tool access to
+``~/.claude/code-review-stamps/`` and shell references to the stamp store
+module or its mint call, while the sanctioned invoker command and unrelated
+paths pass.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+_HOOK_DIR = Path(__file__).resolve().parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+STAMP_STORE_IMPORT_FORGE = (
+    'python -c "from code_review_stamp_store import record_clean_stamp; '
+    "record_clean_stamp(root, live_hash, 'low')\""
+)
+MINT_CALL_FORGE = "python -c \"record_clean_stamp(root, live_hash, 'xhigh')\""
+PYTEST_RUN = "python -m pytest test_code_review_stamp_store.py"
+SANCTIONED_INVOKER = "python invoke_code_review.py --record-stamp --cwd . --session-model opus low"
+ABSOLUTE_STAMP_ACCESS = "cat ~/.claude/code-review-stamps/abc1234567890abc.json"
+DECOY_ECHO_THEN_FORGE = (
+    'echo "invoke_code_review.py --record-stamp" >/dev/null; '
+    "echo x > ~/.claude/code-review-stamps/abc1234567890123.json"
+)
+DECOY_INVOKER_THEN_FORGE = (
+    "python invoke_code_review.py --record-stamp --cwd . low ; "
+    "echo pwned > ~/.claude/code-review-stamps/evil.json"
+)
+
+
+def _load_module(module_name: str) -> ModuleType:
+    module_spec = importlib.util.spec_from_file_location(
+        module_name, _HOOK_DIR / f"{module_name}.py"
+    )
+    assert module_spec is not None
+    assert 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_module = _load_module("code_review_stamp_directory_write_blocker")
+
+
+def _isolate_home(monkeypatch: pytest.MonkeyPatch, fake_home: Path) -> None:
+    home_text = str(fake_home)
+    monkeypatch.setenv("HOME", home_text)
+    monkeypatch.setenv("USERPROFILE", home_text)
+    monkeypatch.delenv("HOMEDRIVE", raising=False)
+    monkeypatch.delenv("HOMEPATH", raising=False)
+
+
+def test_absolute_stamp_path_is_blocked() -> None:
+    assert blocker_module.references_stamp_directory(ABSOLUTE_STAMP_ACCESS)
+
+
+def test_store_module_import_forge_is_blocked() -> None:
+    assert blocker_module.references_stamp_directory(STAMP_STORE_IMPORT_FORGE)
+
+
+def test_mint_call_forge_is_blocked() -> None:
+    assert blocker_module.references_stamp_directory(MINT_CALL_FORGE)
+
+
+def test_pytest_run_naming_store_test_is_not_blocked() -> None:
+    assert not blocker_module.references_stamp_directory(PYTEST_RUN)
+
+
+def test_sanctioned_invoker_command_is_not_blocked() -> None:
+    assert not blocker_module.references_stamp_directory(SANCTIONED_INVOKER)
+
+
+def test_decoy_echo_of_invoker_then_stamp_forge_is_blocked() -> None:
+    assert blocker_module.references_stamp_directory(DECOY_ECHO_THEN_FORGE)
+
+
+def test_decoy_invoker_run_then_stamp_forge_is_blocked() -> None:
+    assert blocker_module.references_stamp_directory(DECOY_INVOKER_THEN_FORGE)
+
+
+def test_write_tool_to_stamp_directory_is_blocked(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    stamp_path = fake_home / ".claude" / "code-review-stamps" / "abc.json"
+    assert blocker_module.path_targets_stamp_directory(str(stamp_path))
+
+
+def test_write_tool_elsewhere_is_allowed(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    other_path = tmp_path / "src" / "module.py"
+    assert not blocker_module.path_targets_stamp_directory(str(other_path))
+
+
+def test_write_payload_to_stamp_directory_denies(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    stamp_path = fake_home / ".claude" / "code-review-stamps" / "abc.json"
+    payload = {
+        "tool_name": "Write",
+        "tool_input": {"file_path": str(stamp_path), "content": "{}"},
+    }
+    deny_decision = blocker_module.decision_for_payload(payload)
+    assert deny_decision is not None
+    assert deny_decision["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_bash_forge_payload_denies() -> None:
+    payload = {
+        "tool_name": "Bash",
+        "tool_input": {"command": STAMP_STORE_IMPORT_FORGE},
+    }
+    deny_decision = blocker_module.decision_for_payload(payload)
+    assert deny_decision is not None
+    assert deny_decision["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_sanctioned_invoker_payload_is_not_denied() -> None:
+    payload = {
+        "tool_name": "Bash",
+        "tool_input": {"command": SANCTIONED_INVOKER},
+    }
+    assert blocker_module.decision_for_payload(payload) is None
+
+
+def test_main_emits_deny_for_bash_forge(monkeypatch: pytest.MonkeyPatch) -> None:
+    payload_text = json.dumps({"tool_name": "Bash", "tool_input": {"command": MINT_CALL_FORGE}})
+    monkeypatch.setattr(sys, "stdin", io.StringIO(payload_text))
+    captured_stdout = io.StringIO()
+    monkeypatch.setattr(sys, "stdout", captured_stdout)
+    blocker_module.main()
+    assert "STAMP_DIRECTORY_GUARD" in captured_stdout.getvalue()
+
+
+STAMP_OBFUSCATION_PATH = "/.claude/code-review-stamps/a.json"
+BENIGN_OBFUSCATION_PATH = "/tmp/x"
+SPLIT_CD_FORGE = "cd ~/.claude && cd code-review-stamps && echo x > f.json"
+
+
+def _hex_forge(path_text: str) -> str:
+    return f"python -c \"open(bytes.fromhex('{path_text.encode().hex()}'),'w').write('x')\""
+
+
+def _chr_chain_forge(path_text: str) -> str:
+    chr_chain = "+".join(f"chr({ord(each_character)})" for each_character in path_text)
+    return f"python -c \"open({chr_chain},'w').write('x')\""
+
+
+def test_split_directory_change_into_stamp_is_blocked() -> None:
+    assert blocker_module.references_stamp_directory(SPLIT_CD_FORGE)
+
+
+def test_hex_obfuscated_stamp_path_is_blocked() -> None:
+    assert blocker_module.references_stamp_directory(_hex_forge(STAMP_OBFUSCATION_PATH))
+
+
+def test_chr_chain_obfuscated_stamp_path_is_blocked() -> None:
+    assert blocker_module.references_stamp_directory(_chr_chain_forge(STAMP_OBFUSCATION_PATH))
+
+
+def test_benign_decode_to_other_path_is_not_blocked() -> None:
+    assert not blocker_module.references_stamp_directory(_hex_forge(BENIGN_OBFUSCATION_PATH))

package/hooks/blocking/test_code_review_stamp_store.py

@@ -0,0 +1,205 @@
+"""Behavioral tests for the per-work-tree code-review stamp store.
+
+Each test builds a real git repository with a real origin remote and records or
+reads real stamp files under an isolated home, so it exercises the same store
+surface the push and PR-create gates call: record a clean stamp, then ask
+whether it covers the live branch surface at a given effort.
+"""
+
+import importlib.util
+import pathlib
+import subprocess
+import sys
+
+import pytest
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+_store_spec = importlib.util.spec_from_file_location(
+    "code_review_stamp_store",
+    _HOOK_DIR / "code_review_stamp_store.py",
+)
+assert _store_spec is not None
+assert _store_spec.loader is not None
+_store_module = importlib.util.module_from_spec(_store_spec)
+_store_spec.loader.exec_module(_store_module)
+
+record_clean_stamp = _store_module.record_clean_stamp
+stamp_covers_surface = _store_module.stamp_covers_surface
+live_surface_hash = _store_module.live_surface_hash
+stamp_path_for_repo = _store_module.stamp_path_for_repo
+
+_verdict_store_module = sys.modules["verification_verdict_store"]
+root_key_for_repo = _verdict_store_module.root_key_for_repo
+
+_constants_spec = importlib.util.spec_from_file_location(
+    "code_review_enforcement_constants",
+    _HOOK_DIR / "config" / "code_review_enforcement_constants.py",
+)
+assert _constants_spec is not None
+assert _constants_spec.loader is not None
+_constants_module = importlib.util.module_from_spec(_constants_spec)
+_constants_spec.loader.exec_module(_constants_module)
+PUSH_REQUIRED_EFFORT = _constants_module.PUSH_REQUIRED_EFFORT
+PR_CREATE_REQUIRED_EFFORT = _constants_module.PR_CREATE_REQUIRED_EFFORT
+ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER = _constants_module.ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER
+
+PRODUCTION_SOURCE = "def add(left: int, right: int) -> int:\n    return left + right\n"
+CHANGED_SOURCE = "def add(left: int, right: int) -> int:\n    return left - right\n"
+FURTHER_CHANGED_SOURCE = "def add(left: int, right: int) -> int:\n    return left * right\n"
+
+
+def _run_git(repo_dir: pathlib.Path, *git_arguments: str) -> None:
+    subprocess.run(
+        ["git", "-C", str(repo_dir), *git_arguments],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+
+def _make_repo_with_origin(tmp_path: pathlib.Path) -> pathlib.Path:
+    origin_dir = tmp_path / "origin.git"
+    work_dir = tmp_path / "work"
+    work_dir.mkdir()
+    subprocess.run(
+        ["git", "init", "--bare", "--initial-branch=main", str(origin_dir)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    empty_hooks_dir = tmp_path / "nohooks"
+    empty_hooks_dir.mkdir()
+    _run_git(work_dir, "init", "--initial-branch=main")
+    _run_git(work_dir, "config", "user.email", "tests@example.com")
+    _run_git(work_dir, "config", "user.name", "Stamp Store Tests")
+    _run_git(work_dir, "config", "core.hooksPath", str(empty_hooks_dir))
+    (work_dir / "src").mkdir()
+    (work_dir / "src" / "app.py").write_text(PRODUCTION_SOURCE, encoding="utf-8")
+    _run_git(work_dir, "add", "-A")
+    _run_git(work_dir, "commit", "-m", "base")
+    _run_git(work_dir, "remote", "add", "origin", str(origin_dir))
+    _run_git(work_dir, "push", "-u", "origin", "main")
+    return work_dir
+
+
+def _isolate_home(monkeypatch: pytest.MonkeyPatch, fake_home: pathlib.Path) -> None:
+    home_text = str(fake_home)
+    monkeypatch.setenv("HOME", home_text)
+    monkeypatch.setenv("USERPROFILE", home_text)
+    monkeypatch.delenv("HOMEDRIVE", raising=False)
+    monkeypatch.delenv("HOMEPATH", raising=False)
+
+
+def _repo_with_change(tmp_path: pathlib.Path, changed_source: str) -> pathlib.Path:
+    work_dir = _make_repo_with_origin(tmp_path)
+    (work_dir / "src" / "app.py").write_text(changed_source, encoding="utf-8")
+    return work_dir
+
+
+def test_recorded_low_stamp_covers_the_push_surface(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    _isolate_home(monkeypatch, tmp_path / "home")
+    work_dir = _repo_with_change(tmp_path, CHANGED_SOURCE)
+    surface_hash = live_surface_hash(str(work_dir))
+    assert surface_hash is not None
+    record_clean_stamp(str(work_dir), surface_hash, PUSH_REQUIRED_EFFORT)
+    assert stamp_covers_surface(str(work_dir), surface_hash, PUSH_REQUIRED_EFFORT) is True
+
+
+def test_low_stamp_does_not_cover_the_pr_create_surface(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    _isolate_home(monkeypatch, tmp_path / "home")
+    work_dir = _repo_with_change(tmp_path, CHANGED_SOURCE)
+    surface_hash = live_surface_hash(str(work_dir))
+    assert surface_hash is not None
+    record_clean_stamp(str(work_dir), surface_hash, PUSH_REQUIRED_EFFORT)
+    assert stamp_covers_surface(str(work_dir), surface_hash, PR_CREATE_REQUIRED_EFFORT) is False
+
+
+def test_xhigh_stamp_covers_both_push_and_pr_create(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    _isolate_home(monkeypatch, tmp_path / "home")
+    work_dir = _repo_with_change(tmp_path, CHANGED_SOURCE)
+    surface_hash = live_surface_hash(str(work_dir))
+    assert surface_hash is not None
+    record_clean_stamp(str(work_dir), surface_hash, PR_CREATE_REQUIRED_EFFORT)
+    assert stamp_covers_surface(str(work_dir), surface_hash, PUSH_REQUIRED_EFFORT) is True
+    assert stamp_covers_surface(str(work_dir), surface_hash, PR_CREATE_REQUIRED_EFFORT) is True
+
+
+def test_stamp_bound_to_one_hash_does_not_cover_a_different_hash(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    _isolate_home(monkeypatch, tmp_path / "home")
+    work_dir = _repo_with_change(tmp_path, CHANGED_SOURCE)
+    surface_hash = live_surface_hash(str(work_dir))
+    assert surface_hash is not None
+    record_clean_stamp(str(work_dir), surface_hash, PUSH_REQUIRED_EFFORT)
+    other_hash = "f" * len(surface_hash)
+    assert stamp_covers_surface(str(work_dir), other_hash, PUSH_REQUIRED_EFFORT) is False
+
+
+def test_editing_a_file_after_minting_drops_coverage(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    _isolate_home(monkeypatch, tmp_path / "home")
+    work_dir = _repo_with_change(tmp_path, CHANGED_SOURCE)
+    minted_hash = live_surface_hash(str(work_dir))
+    assert minted_hash is not None
+    record_clean_stamp(str(work_dir), minted_hash, PUSH_REQUIRED_EFFORT)
+    (work_dir / "src" / "app.py").write_text(FURTHER_CHANGED_SOURCE, encoding="utf-8")
+    live_hash_after_edit = live_surface_hash(str(work_dir))
+    assert live_hash_after_edit is not None
+    assert live_hash_after_edit != minted_hash
+    assert stamp_covers_surface(str(work_dir), live_hash_after_edit, PUSH_REQUIRED_EFFORT) is False
+
+
+def test_no_stamp_file_reads_as_not_covered(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    _isolate_home(monkeypatch, tmp_path / "home")
+    work_dir = _repo_with_change(tmp_path, CHANGED_SOURCE)
+    surface_hash = live_surface_hash(str(work_dir))
+    assert surface_hash is not None
+    assert not stamp_path_for_repo(str(work_dir)).exists()
+    assert stamp_covers_surface(str(work_dir), surface_hash, PUSH_REQUIRED_EFFORT) is False
+
+
+def test_recording_a_second_effort_keeps_the_first(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    _isolate_home(monkeypatch, tmp_path / "home")
+    work_dir = _repo_with_change(tmp_path, CHANGED_SOURCE)
+    surface_hash = live_surface_hash(str(work_dir))
+    assert surface_hash is not None
+    record_clean_stamp(str(work_dir), surface_hash, PUSH_REQUIRED_EFFORT)
+    record_clean_stamp(str(work_dir), surface_hash, PR_CREATE_REQUIRED_EFFORT)
+    assert stamp_covers_surface(str(work_dir), surface_hash, PUSH_REQUIRED_EFFORT) is True
+    assert stamp_covers_surface(str(work_dir), surface_hash, PR_CREATE_REQUIRED_EFFORT) is True
+
+
+def test_live_surface_hash_is_none_when_nothing_changed(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    _isolate_home(monkeypatch, tmp_path / "home")
+    work_dir = _make_repo_with_origin(tmp_path)
+    assert live_surface_hash(str(work_dir)) is None
+
+
+def test_push_required_effort_is_the_lowest_known_token() -> None:
+    assert PUSH_REQUIRED_EFFORT == ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER[0]
+
+
+def test_stamp_path_for_repo_stem_matches_the_shared_root_key(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path
+) -> None:
+    _isolate_home(monkeypatch, tmp_path / "home")
+    work_dir = tmp_path / "work-tree"
+    work_dir.mkdir()
+    assert stamp_path_for_repo(str(work_dir)).stem == root_key_for_repo(str(work_dir))