claude-dev-env 2.4.0 → 2.5.0

package/scripts/test_claude_chain_runner.py

@@ -30,6 +30,7 @@ from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
     CLAUDE_HOME_SUBDIRECTORY,
     CLI_ARGUMENTS_SEPARATOR,
     CLI_TIMEOUT_FLAG,
+    CODEC_ERROR_STRATEGY,
     CONFIG_CHAIN_EMPTY_REASON,
     CONFIG_CHAIN_KEY,
     CONFIG_CHAIN_NOT_LIST_REASON,
@@ -50,6 +51,14 @@ from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
     UTF8_ENCODING,
 )
 
+_LARGE_CAPTURE_BYTE_COUNT = 400_000
+_LARGE_CAPTURE_MARKER = "X"
+_STDIN_ECHO_PAYLOAD = "charter body for spool path"
+_UNDECODABLE_STDOUT_BYTES = b"ok \x90 end"
+_DECODED_UNDECODABLE_STDOUT = "ok \ufffd end"
+_CRLF_CHILD_STDOUT_BYTES = b"a\r\nb\rc\n"
+_CRLF_CHILD_STDOUT_NORMALIZED = "a\nb\nc\n"
+
 _A_SIGNATURE = ALL_USAGE_LIMIT_SIGNATURES[0]
 _PROMPT_ARGUMENTS = ["-p", "hello"]
 _EQUAL_WEEKLY_REMAINING_PERCENT = 50.0
@@ -955,6 +964,128 @@ def test_real_subprocess_capture_preserves_utf8_text(
     assert chain_result.stdout == "report ✅ done"
 
 
+def test_run_captured_subprocess_spools_large_stdout_and_stderr() -> None:
+    child_code = (
+        "import sys;"
+        f"sys.stdout.write({_LARGE_CAPTURE_MARKER!r} * {_LARGE_CAPTURE_BYTE_COUNT});"
+        "sys.stderr.write('err-marker');"
+        "sys.exit(3)"
+    )
+    completion = runner._run_captured_subprocess(
+        [sys.executable, "-c", child_code],
+        encoding=UTF8_ENCODING,
+        errors=CODEC_ERROR_STRATEGY,
+        timeout=60,
+        check=False,
+        input=None,
+    )
+    assert completion.returncode == 3
+    assert len(completion.stdout) == _LARGE_CAPTURE_BYTE_COUNT
+    assert completion.stdout == _LARGE_CAPTURE_MARKER * _LARGE_CAPTURE_BYTE_COUNT
+    assert completion.stderr == "err-marker"
+
+
+def test_run_captured_subprocess_forwards_stdin_input() -> None:
+    child_code = "import sys; sys.stdout.write(sys.stdin.read())"
+    completion = runner._run_captured_subprocess(
+        [sys.executable, "-c", child_code],
+        encoding=UTF8_ENCODING,
+        errors=CODEC_ERROR_STRATEGY,
+        timeout=60,
+        check=False,
+        input=_STDIN_ECHO_PAYLOAD,
+    )
+    assert completion.returncode == 0
+    assert completion.stdout == _STDIN_ECHO_PAYLOAD
+    assert completion.stderr == ""
+
+
+def test_run_captured_subprocess_replaces_undecodable_stdout_bytes() -> None:
+    child_code = (
+        "import sys;"
+        f"sys.stdout.buffer.write({_UNDECODABLE_STDOUT_BYTES!r})"
+    )
+    completion = runner._run_captured_subprocess(
+        [sys.executable, "-c", child_code],
+        encoding=UTF8_ENCODING,
+        errors=CODEC_ERROR_STRATEGY,
+        timeout=60,
+        check=False,
+        input=None,
+    )
+    assert completion.returncode == 0
+    assert completion.stdout == _DECODED_UNDECODABLE_STDOUT
+
+
+def test_run_captured_subprocess_normalizes_crlf_to_lf() -> None:
+    """Spool decode matches subprocess text=True universal-newline translation."""
+    child_code = (
+        "import sys;"
+        f"sys.stdout.buffer.write({_CRLF_CHILD_STDOUT_BYTES!r})"
+    )
+    completion = runner._run_captured_subprocess(
+        [sys.executable, "-c", child_code],
+        encoding=UTF8_ENCODING,
+        errors=CODEC_ERROR_STRATEGY,
+        timeout=60,
+        check=False,
+        input=None,
+    )
+    assert completion.returncode == 0
+    assert completion.stdout == _CRLF_CHILD_STDOUT_NORMALIZED
+
+
+def test_run_captured_subprocess_honors_cwd(tmp_path: Path) -> None:
+    child_code = "import os, sys; sys.stdout.write(os.getcwd())"
+    completion = runner._run_captured_subprocess(
+        [sys.executable, "-c", child_code],
+        encoding=UTF8_ENCODING,
+        errors=CODEC_ERROR_STRATEGY,
+        timeout=60,
+        check=False,
+        cwd=str(tmp_path),
+    )
+    assert completion.returncode == 0
+    assert Path(completion.stdout).resolve() == tmp_path.resolve()
+
+
+def test_run_captured_subprocess_timeout_keeps_partial_stdout() -> None:
+    child_code = (
+        "import sys, time;"
+        "sys.stdout.write('partial-before-timeout');"
+        "sys.stdout.flush();"
+        "time.sleep(30)"
+    )
+    with pytest.raises(subprocess.TimeoutExpired) as raised:
+        runner._run_captured_subprocess(
+            [sys.executable, "-c", child_code],
+            encoding=UTF8_ENCODING,
+            errors=CODEC_ERROR_STRATEGY,
+            timeout=1,
+            check=False,
+            input=None,
+        )
+    assert raised.value.stdout == "partial-before-timeout"
+    assert isinstance(raised.value.stdout, str)
+
+
+def test_run_captured_subprocess_reads_stdin_stream(tmp_path: Path) -> None:
+    prompt_path = tmp_path / "prompt_body.txt"
+    prompt_path.write_text(_STDIN_ECHO_PAYLOAD, encoding=UTF8_ENCODING)
+    child_code = "import sys; sys.stdout.write(sys.stdin.read())"
+    with prompt_path.open(encoding=UTF8_ENCODING) as prompt_stream:
+        completion = runner._run_captured_subprocess(
+            [sys.executable, "-c", child_code],
+            encoding=UTF8_ENCODING,
+            errors=CODEC_ERROR_STRATEGY,
+            timeout=60,
+            check=False,
+            stdin=prompt_stream,
+        )
+    assert completion.returncode == 0
+    assert completion.stdout == _STDIN_ECHO_PAYLOAD
+
+
 def test_cli_emits_utf8_when_console_encoding_is_legacy(tmp_path: Path) -> None:
     tmp_home = tmp_path / "home"
     claude_directory = tmp_home / CLAUDE_HOME_SUBDIRECTORY

package/scripts/test_invoke_code_review_chain.py

@@ -0,0 +1,70 @@
+"""Chain-invocation argv assembly, empty stdin, and working directory."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+import invoke_code_review as invoker
+from _code_review_test_support import (
+    FIXTURE_SESSION_OPUS,
+    FIXTURE_SESSION_SONNET,
+    HOST_PROFILE_THIRD_PARTY,
+    claude_served,
+    init_git_repository,
+    install_seams,
+    run_review,
+)
+from dev_env_scripts_constants.code_review_constants import (
+    CODE_REVIEW_MODEL_ALIAS,
+    DEFAULT_CODE_REVIEW_EFFORT,
+    PERMISSION_MODE_BYPASS,
+    PERMISSION_MODE_FLAG,
+)
+from dev_env_scripts_constants.grok_worker_constants import (
+    MODEL_FLAG,
+    OUTPUT_FORMAT_FLAG,
+    OUTPUT_FORMAT_JSON,
+    SINGLE_TURN_FLAG,
+)
+
+
+def test_chain_argv_assembly(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    working_directory = init_git_repository(tmp_path / "repo")
+    call_log = install_seams(
+        monkeypatch,
+        host_profile=HOST_PROFILE_THIRD_PARTY,
+        claude_outcome=claude_served(),
+        working_directory=working_directory,
+    )
+
+    run_review(working_directory, session_model=FIXTURE_SESSION_SONNET)
+
+    assert call_log.claude_arguments == [
+        SINGLE_TURN_FLAG,
+        invoker.build_code_review_prompt(DEFAULT_CODE_REVIEW_EFFORT),
+        MODEL_FLAG,
+        CODE_REVIEW_MODEL_ALIAS,
+        OUTPUT_FORMAT_FLAG,
+        OUTPUT_FORMAT_JSON,
+        PERMISSION_MODE_FLAG,
+        PERMISSION_MODE_BYPASS,
+    ]
+
+
+def test_chain_redirects_empty_stdin_and_sets_cwd(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    working_directory = init_git_repository(tmp_path / "repo")
+    call_log = install_seams(
+        monkeypatch,
+        host_profile=HOST_PROFILE_THIRD_PARTY,
+        claude_outcome=claude_served(),
+        working_directory=working_directory,
+    )
+
+    run_review(working_directory, session_model=FIXTURE_SESSION_OPUS)
+
+    assert call_log.is_stdin_empty is True
+    assert call_log.claude_working_directory == working_directory

package/scripts/test_invoke_code_review_cli.py

@@ -0,0 +1,192 @@
+"""CLI JSON output for in-session, error, effort, and record-stamp paths."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+import invoke_code_review as invoker
+from _code_review_test_support import (
+    DriftingReview,
+    EFFORT_LOW,
+    FIXTURE_CHAIN_CONFIG_ERROR_MESSAGE,
+    FIXTURE_HOST_PROFILE_ERROR_MESSAGE,
+    FIXTURE_SESSION_OPUS,
+    HOST_PROFILE_CLAUDE,
+    HOST_PROFILE_THIRD_PARTY,
+    REJECTED_ULTRA_EFFORT,
+    init_git_repository,
+    install_seams,
+    prepared_surface_repo,
+    run_record_stamp_cli,
+    run_review_cli,
+)
+from claude_chain_runner import ChainConfigurationError
+from dev_env_scripts_constants.claude_chain_constants import (
+    CHAIN_CONFIG_ERROR_EXIT_CODE,
+)
+from dev_env_scripts_constants.code_review_constants import (
+    CLI_SESSION_MODEL_FLAG,
+    HOST_PROFILE_ERROR_RETURNCODE,
+    IN_SESSION_RETURNCODE,
+    INVALID_EFFORT_RETURNCODE,
+    MAXIMUM_STAMP_MINT_PASSES,
+    MODE_CHAIN,
+    MODE_IN_SESSION,
+    RESULT_KEY_BOUND_HASH,
+    RESULT_KEY_DIRTY_TREE,
+    RESULT_KEY_MODE,
+    RESULT_KEY_PASS_COUNT,
+    RESULT_KEY_RETURNCODE,
+    RESULT_KEY_SERVED_COMMAND,
+    RESULT_KEY_STAMP_MINTED,
+    STAMP_DID_NOT_CONVERGE_RETURNCODE,
+)
+from dev_env_scripts_constants.grok_worker_constants import CWD_FLAG
+
+
+def test_cli_prints_result_json_only(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    working_directory = init_git_repository(tmp_path / "repo")
+    install_seams(
+        monkeypatch,
+        host_profile=HOST_PROFILE_CLAUDE,
+        claude_outcome=None,
+        working_directory=working_directory,
+    )
+
+    exit_code = run_review_cli(working_directory, session_model=FIXTURE_SESSION_OPUS)
+
+    assert exit_code == IN_SESSION_RETURNCODE
+    captured = capsys.readouterr()
+    assert captured.err == ""
+    parsed_payload = json.loads(captured.out)
+    assert parsed_payload == {
+        RESULT_KEY_MODE: MODE_IN_SESSION,
+        RESULT_KEY_SERVED_COMMAND: None,
+        RESULT_KEY_RETURNCODE: IN_SESSION_RETURNCODE,
+        RESULT_KEY_DIRTY_TREE: False,
+    }
+
+
+def test_cli_emits_json_on_chain_configuration_error(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    working_directory = init_git_repository(tmp_path / "repo")
+    install_seams(
+        monkeypatch,
+        host_profile=HOST_PROFILE_THIRD_PARTY,
+        claude_outcome=ChainConfigurationError(FIXTURE_CHAIN_CONFIG_ERROR_MESSAGE),
+        working_directory=working_directory,
+    )
+    exit_code = run_review_cli(working_directory, session_model=FIXTURE_SESSION_OPUS)
+
+    assert exit_code == CHAIN_CONFIG_ERROR_EXIT_CODE
+    captured = capsys.readouterr()
+    parsed_payload = json.loads(captured.out)
+    assert parsed_payload == {
+        RESULT_KEY_MODE: MODE_CHAIN,
+        RESULT_KEY_SERVED_COMMAND: None,
+        RESULT_KEY_RETURNCODE: CHAIN_CONFIG_ERROR_EXIT_CODE,
+        RESULT_KEY_DIRTY_TREE: False,
+    }
+    config_error_outcome = invoker.CodeReviewOutcome(
+        mode=MODE_CHAIN,
+        served_command=None,
+        returncode=CHAIN_CONFIG_ERROR_EXIT_CODE,
+        is_dirty_tree=False,
+    )
+    assert invoker.is_code_review_clean_stamp_allowed(config_error_outcome) is False
+
+
+def test_cli_emits_json_on_host_profile_value_error(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    working_directory = init_git_repository(tmp_path / "repo")
+
+    def fake_host_profile_raises(setting_by_name: object | None = None) -> str:
+        del setting_by_name
+        raise ValueError(FIXTURE_HOST_PROFILE_ERROR_MESSAGE)
+
+    monkeypatch.setattr(
+        invoker, "review_host_profile_detector", fake_host_profile_raises
+    )
+
+    exit_code = run_review_cli(working_directory, session_model=FIXTURE_SESSION_OPUS)
+
+    assert exit_code == HOST_PROFILE_ERROR_RETURNCODE
+    captured = capsys.readouterr()
+    parsed_payload = json.loads(captured.out)
+    assert parsed_payload == {
+        RESULT_KEY_MODE: MODE_CHAIN,
+        RESULT_KEY_SERVED_COMMAND: None,
+        RESULT_KEY_RETURNCODE: HOST_PROFILE_ERROR_RETURNCODE,
+        RESULT_KEY_DIRTY_TREE: False,
+    }
+
+
+def test_cli_rejects_ultra_effort_with_nonzero_exit(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    install_seams(
+        monkeypatch,
+        host_profile=HOST_PROFILE_CLAUDE,
+        claude_outcome=None,
+        working_directory=tmp_path,
+    )
+    exit_code = invoker.main(
+        [
+            CWD_FLAG,
+            str(tmp_path),
+            CLI_SESSION_MODEL_FLAG,
+            FIXTURE_SESSION_OPUS,
+            REJECTED_ULTRA_EFFORT,
+        ]
+    )
+    assert exit_code == INVALID_EFFORT_RETURNCODE
+    assert REJECTED_ULTRA_EFFORT in capsys.readouterr().err
+
+
+def test_cli_record_stamp_returns_non_convergence_code_on_cap(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    working_directory = prepared_surface_repo(monkeypatch, tmp_path)
+    monkeypatch.setattr(invoker, "invoke_code_review", DriftingReview())
+    exit_code = run_record_stamp_cli(working_directory, effort=EFFORT_LOW)
+    assert exit_code == STAMP_DID_NOT_CONVERGE_RETURNCODE
+    parsed_payload = json.loads(capsys.readouterr().out)
+    assert parsed_payload[RESULT_KEY_STAMP_MINTED] is False
+    assert parsed_payload[RESULT_KEY_PASS_COUNT] == MAXIMUM_STAMP_MINT_PASSES
+    assert parsed_payload[RESULT_KEY_BOUND_HASH] is None
+
+
+def test_cli_record_stamp_reports_missing_store_dependency(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    def raise_missing_store(*all_args: object, **all_keywords: object) -> object:
+        del all_args, all_keywords
+        raise ModuleNotFoundError("store missing", name="code_review_stamp_store")
+
+    working_directory = prepared_surface_repo(monkeypatch, tmp_path)
+    monkeypatch.setattr(invoker, "load_code_review_stamp_store", raise_missing_store)
+    exit_code = run_record_stamp_cli(working_directory, effort=EFFORT_LOW)
+    assert exit_code == INVALID_EFFORT_RETURNCODE
+    captured = capsys.readouterr()
+    assert "stamp store" in captured.err
+    parsed_payload = json.loads(captured.out)
+    assert parsed_payload[RESULT_KEY_STAMP_MINTED] is False

package/scripts/test_invoke_code_review_contract.py

@@ -0,0 +1,256 @@
+"""Argument contract, encoding, clean-stamp rules, effort tokens, and stamps."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+import invoke_code_review as invoker
+from _code_review_test_support import (
+    DriftingReview,
+    EFFORT_LOW,
+    FIXTURE_CHAIN_RETURNCODE,
+    FIXTURE_FAILED_RETURNCODE,
+    FIXTURE_SERVED_COMMAND,
+    FIXTURE_SESSION_OPUS,
+    HOST_PROFILE_THIRD_PARTY,
+    MISSING_STORE_FILE_NAME,
+    REJECTED_ULTRA_EFFORT,
+    SINGLE_PASS_CAP,
+    claude_failed,
+    init_git_repository,
+    install_seams,
+    prepared_surface_repo,
+    run_review,
+    stable_clean_review,
+    surface_changing_review,
+)
+from dev_env_scripts_constants.code_review_constants import (
+    CODE_REVIEW_MODEL_ALIAS,
+    DEFAULT_CODE_REVIEW_EFFORT,
+    IN_SESSION_RETURNCODE,
+    MAXIMUM_STAMP_MINT_PASSES,
+    MODE_CHAIN,
+    MODE_IN_SESSION,
+    PERMISSION_MODE_BYPASS,
+    PERMISSION_MODE_FLAG,
+    RESULT_KEY_BOUND_HASH,
+    RESULT_KEY_DIRTY_TREE,
+    RESULT_KEY_MODE,
+    RESULT_KEY_PASS_COUNT,
+    RESULT_KEY_RETURNCODE,
+    RESULT_KEY_SERVED_COMMAND,
+    RESULT_KEY_STAMP_MINTED,
+)
+from dev_env_scripts_constants.grok_worker_constants import (
+    MODEL_FLAG,
+    OUTPUT_FORMAT_FLAG,
+    OUTPUT_FORMAT_JSON,
+    SINGLE_TURN_FLAG,
+)
+from dev_env_scripts_constants.timing import DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS
+
+CLEAN_SUCCESS_OUTCOME = invoker.CodeReviewOutcome(
+    mode=MODE_CHAIN,
+    served_command=FIXTURE_SERVED_COMMAND,
+    returncode=FIXTURE_CHAIN_RETURNCODE,
+    is_dirty_tree=False,
+)
+DIRTY_SUCCESS_OUTCOME = invoker.CodeReviewOutcome(
+    mode=MODE_CHAIN,
+    served_command=FIXTURE_SERVED_COMMAND,
+    returncode=FIXTURE_CHAIN_RETURNCODE,
+    is_dirty_tree=True,
+)
+FAILED_SERVE_OUTCOME = invoker.CodeReviewOutcome(
+    mode=MODE_CHAIN,
+    served_command=None,
+    returncode=FIXTURE_FAILED_RETURNCODE,
+    is_dirty_tree=False,
+)
+IN_SESSION_READY_OUTCOME = invoker.CodeReviewOutcome(
+    mode=MODE_IN_SESSION,
+    served_command=None,
+    returncode=IN_SESSION_RETURNCODE,
+    is_dirty_tree=False,
+)
+
+
+def test_build_code_review_arguments_matches_contract() -> None:
+    all_arguments = invoker.build_code_review_arguments()
+    assert all_arguments == [
+        SINGLE_TURN_FLAG,
+        invoker.build_code_review_prompt(DEFAULT_CODE_REVIEW_EFFORT),
+        MODEL_FLAG,
+        CODE_REVIEW_MODEL_ALIAS,
+        OUTPUT_FORMAT_FLAG,
+        OUTPUT_FORMAT_JSON,
+        PERMISSION_MODE_FLAG,
+        PERMISSION_MODE_BYPASS,
+    ]
+
+
+def test_chain_failure_preserves_returncode(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    working_directory = init_git_repository(tmp_path / "repo")
+    install_seams(
+        monkeypatch,
+        host_profile=HOST_PROFILE_THIRD_PARTY,
+        claude_outcome=claude_failed(),
+        working_directory=working_directory,
+    )
+
+    review_outcome = run_review(working_directory, session_model=FIXTURE_SESSION_OPUS)
+
+    assert review_outcome.mode == MODE_CHAIN
+    assert review_outcome.served_command is None
+    assert review_outcome.returncode == FIXTURE_FAILED_RETURNCODE
+    assert review_outcome.is_dirty_tree is False
+    assert invoker.is_successful_code_review(review_outcome) is False
+    assert invoker.is_code_review_clean_stamp_allowed(review_outcome) is False
+
+
+def test_clean_stamp_allowed_only_on_successful_clean_serve() -> None:
+    assert invoker.is_code_review_clean_stamp_allowed(CLEAN_SUCCESS_OUTCOME) is True
+    assert invoker.is_code_review_clean_stamp_allowed(DIRTY_SUCCESS_OUTCOME) is False
+    assert invoker.is_code_review_clean_stamp_allowed(FAILED_SERVE_OUTCOME) is False
+    assert invoker.is_code_review_clean_stamp_allowed(IN_SESSION_READY_OUTCOME) is True
+    assert invoker.is_successful_code_review(FAILED_SERVE_OUTCOME) is False
+    assert invoker.is_successful_code_review(CLEAN_SUCCESS_OUTCOME) is True
+
+
+def test_encode_code_review_outcome_shape() -> None:
+    review_outcome = invoker.CodeReviewOutcome(
+        mode=MODE_CHAIN,
+        served_command=FIXTURE_SERVED_COMMAND,
+        returncode=FIXTURE_CHAIN_RETURNCODE,
+        is_dirty_tree=True,
+    )
+    encoded_payload = invoker.encode_code_review_outcome(review_outcome)
+    assert encoded_payload == {
+        RESULT_KEY_MODE: MODE_CHAIN,
+        RESULT_KEY_SERVED_COMMAND: FIXTURE_SERVED_COMMAND,
+        RESULT_KEY_RETURNCODE: FIXTURE_CHAIN_RETURNCODE,
+        RESULT_KEY_DIRTY_TREE: True,
+    }
+
+
+@pytest.mark.parametrize("valid_effort", ["low", "medium", "high", "xhigh", "max"])
+def test_validate_effort_token_accepts_known_tokens(valid_effort: str) -> None:
+    assert invoker.validate_effort_token(valid_effort) is None
+
+
+def test_validate_effort_token_rejects_ultra_loudly() -> None:
+    error_message = invoker.validate_effort_token(REJECTED_ULTRA_EFFORT)
+    assert error_message is not None
+    assert REJECTED_ULTRA_EFFORT in error_message
+
+
+def test_validate_effort_token_rejects_unknown_token() -> None:
+    error_message = invoker.validate_effort_token("bogus")
+    assert error_message is not None
+    assert "bogus" in error_message
+
+
+def test_build_code_review_prompt_reads_as_slash_command() -> None:
+    assert invoker.build_code_review_prompt(EFFORT_LOW) == "/code-review low --fix"
+    assert invoker.build_code_review_prompt("xhigh") == "/code-review xhigh --fix"
+
+
+def test_encode_stamp_mint_outcome_includes_mint_metadata() -> None:
+    review_outcome = invoker.CodeReviewOutcome(
+        mode=MODE_CHAIN,
+        served_command=FIXTURE_SERVED_COMMAND,
+        returncode=FIXTURE_CHAIN_RETURNCODE,
+        is_dirty_tree=False,
+    )
+    mint_outcome = invoker.StampMintOutcome(
+        review_outcome=review_outcome,
+        is_stamp_minted=True,
+        pass_count=SINGLE_PASS_CAP,
+        bound_hash="abc123",
+    )
+    encoded_payload = invoker.encode_stamp_mint_outcome(mint_outcome)
+    assert encoded_payload[RESULT_KEY_STAMP_MINTED] is True
+    assert encoded_payload[RESULT_KEY_PASS_COUNT] == SINGLE_PASS_CAP
+    assert encoded_payload[RESULT_KEY_BOUND_HASH] == "abc123"
+
+
+def test_record_stamp_mints_on_surface_stable_clean_pass(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    working_directory = prepared_surface_repo(monkeypatch, tmp_path)
+    monkeypatch.setattr(invoker, "invoke_code_review", stable_clean_review)
+    mint_outcome = invoker.invoke_code_review_and_record_stamp(
+        working_directory=working_directory,
+        session_model=CODE_REVIEW_MODEL_ALIAS,
+        timeout_seconds=DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS,
+        effort=EFFORT_LOW,
+    )
+    assert mint_outcome.is_stamp_minted is True
+    assert mint_outcome.bound_hash is not None
+    store_module = invoker.load_code_review_stamp_store()
+    assert store_module.stamp_covers_surface(
+        str(working_directory), mint_outcome.bound_hash, EFFORT_LOW
+    )
+
+
+def test_record_stamp_does_not_mint_when_review_changes_surface(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    working_directory = prepared_surface_repo(monkeypatch, tmp_path)
+    monkeypatch.setattr(invoker, "invoke_code_review", surface_changing_review)
+    mint_outcome = invoker.invoke_code_review_and_record_stamp(
+        working_directory=working_directory,
+        session_model=CODE_REVIEW_MODEL_ALIAS,
+        timeout_seconds=DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS,
+        effort=EFFORT_LOW,
+        maximum_passes=SINGLE_PASS_CAP,
+    )
+    assert mint_outcome.is_stamp_minted is False
+    assert mint_outcome.pass_count == SINGLE_PASS_CAP
+    assert mint_outcome.bound_hash is None
+
+
+def test_record_stamp_hits_cap_without_minting(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    working_directory = prepared_surface_repo(monkeypatch, tmp_path)
+    monkeypatch.setattr(invoker, "invoke_code_review", DriftingReview())
+    mint_outcome = invoker.invoke_code_review_and_record_stamp(
+        working_directory=working_directory,
+        session_model=CODE_REVIEW_MODEL_ALIAS,
+        timeout_seconds=DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS,
+        effort=EFFORT_LOW,
+        maximum_passes=MAXIMUM_STAMP_MINT_PASSES,
+    )
+    assert mint_outcome.is_stamp_minted is False
+    assert mint_outcome.pass_count == MAXIMUM_STAMP_MINT_PASSES
+
+
+def test_load_code_review_stamp_store_records_and_covers_surface(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    working_directory = prepared_surface_repo(monkeypatch, tmp_path)
+    store_module = invoker.load_code_review_stamp_store()
+    surface_hash = store_module.live_surface_hash(str(working_directory))
+    assert surface_hash is not None
+    stamp_path = store_module.record_clean_stamp(
+        str(working_directory), surface_hash, EFFORT_LOW
+    )
+    assert stamp_path.exists()
+    assert store_module.stamp_covers_surface(
+        str(working_directory), surface_hash, EFFORT_LOW
+    )
+
+
+def test_load_code_review_stamp_store_raises_when_file_absent(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        invoker, "STAMP_STORE_MODULE_FILE_NAME", MISSING_STORE_FILE_NAME
+    )
+    with pytest.raises(ModuleNotFoundError):
+        invoker.load_code_review_stamp_store()