claude-dev-env 2.4.0 → 2.5.0

package/skills/plan-to-pr/scripts/test_validate_packet.py

@@ -0,0 +1,256 @@
+"""Mutation-style tests for the Plan-to-PR packet validator."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+VALIDATOR_PATH = Path(__file__).with_name("validate_packet.py")
+
+
+def write_packet(packet_directory: Path) -> None:
+    """Create a complete packet and its grounded source file."""
+    packet_directory.mkdir(parents=True)
+    repository_root = packet_directory.parents[2]
+    source_file = repository_root / "src" / "auth.py"
+    source_file.parent.mkdir(parents=True, exist_ok=True)
+    source_file.write_text(
+        "def authenticate_user():\n    return True\n", encoding="utf-8"
+    )
+    task_details = "## Tasks\n- task-1: Login validation; src/auth.py; python -m pytest tests/test_auth.py; python -m pytest tests/test_auth.py; python -m compileall src/auth.py\n"
+    for filename, sections in {
+        "context.md": (
+            "Request",
+            "Repository Facts",
+            "Constraints",
+            "Source References",
+        ),
+        "plan.md": ("Implementation", "Decisions", "Dependencies", "Risks"),
+        "tasks.md": (),
+        "handoff.md": ("Approval", "Task Order"),
+    }.items():
+        headings = "\n".join(
+            f"## {section}\nGrounded packet detail." for section in sections
+        )
+        if filename == "tasks.md":
+            headings = task_details.rstrip()
+        if filename == "handoff.md":
+            headings += "\nPacket: add-login\nApproval: approved\nTask Order: task-1\nTask task-1: Login validation\nAllowed files: src/auth.py\nAcceptance command: python -m pytest tests/test_auth.py\nTest command: python -m pytest tests/test_auth.py\nVerification command: python -m compileall src/auth.py"
+        (packet_directory / filename).write_text(headings + "\n", encoding="utf-8")
+    payload = {
+        "schema_version": 1,
+        "slug": packet_directory.name,
+        "status": "approved",
+        "request": "Add login validation.",
+        "allowed_files": ["src/auth.py"],
+        "sources": [
+            {
+                "path": "src/auth.py",
+                "locator": "section authenticate_user",
+                "fact": "The helper returns the login decision.",
+            }
+        ],
+        "decisions": ["Reuse the existing helper."],
+        "open_questions": [],
+        "tasks": [
+            {
+                "id": "task-1",
+                "deliverable": "Login validation",
+                "allowed_files": ["src/auth.py"],
+                "acceptance_command": "python -m pytest tests/test_auth.py",
+                "test_command": "python -m pytest tests/test_auth.py",
+                "verification_command": "python -m compileall src/auth.py",
+                "commit": 1,
+            }
+        ],
+        "validation": {
+            "schema_valid": True,
+            "boundary_valid": True,
+            "markdown_matches": True,
+            "validated_by": "native-plan-to-pr",
+        },
+    }
+    (packet_directory / "packet.json").write_text(json.dumps(payload), encoding="utf-8")
+
+
+def run_validator(packet_directory: Path) -> subprocess.CompletedProcess[str]:
+    """Run the validator as a real CLI process."""
+    return subprocess.run(
+        [sys.executable, str(VALIDATOR_PATH), str(packet_directory)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def test_valid_packet_passes(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_packet(packet_directory)
+    validator_run = run_validator(packet_directory)
+    assert validator_run.returncode == 0
+    assert validator_run.stdout.strip() == "packet validation passed"
+
+
+def test_missing_packet_file_reports_field(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_packet(packet_directory)
+    (packet_directory / "plan.md").unlink()
+    validator_run = run_validator(packet_directory)
+    assert validator_run.returncode != 0
+    assert "missing required file: plan.md" in validator_run.stderr
+
+
+def test_placeholder_packet_fails(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_packet(packet_directory)
+    (packet_directory / "context.md").write_text(
+        "## Request\nTODO: fill this in", encoding="utf-8"
+    )
+    validator_run = run_validator(packet_directory)
+    assert validator_run.returncode != 0
+    assert "context.md: contains unresolved" in validator_run.stderr
+
+
+def test_task_scope_outside_allowed_files_fails(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_packet(packet_directory)
+    packet_file = packet_directory / "packet.json"
+    packet_payload = json.loads(packet_file.read_text(encoding="utf-8"))
+    packet_payload["tasks"][0]["allowed_files"] = ["src/other.py"]
+    packet_file.write_text(json.dumps(packet_payload), encoding="utf-8")
+    validator_run = run_validator(packet_directory)
+    assert validator_run.returncode != 0
+    assert "outside packet scope" in validator_run.stderr
+
+
+def test_unknown_schema_field_fails(tmp_path: Path) -> None:
+    """Schema-shaped packets reject fields outside the packet contract."""
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_packet(packet_directory)
+    packet_file = packet_directory / "packet.json"
+    packet_payload = json.loads(packet_file.read_text(encoding="utf-8"))
+    packet_payload["unexpected"] = True
+    packet_file.write_text(json.dumps(packet_payload), encoding="utf-8")
+    validator_run = run_validator(packet_directory)
+    assert validator_run.returncode != 0
+    assert "unknown field: unexpected" in validator_run.stderr
+
+
+def test_cyclic_dependencies_fail(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_packet(packet_directory)
+    packet_file = packet_directory / "packet.json"
+    packet_payload = json.loads(packet_file.read_text(encoding="utf-8"))
+    packet_payload["tasks"].append(
+        {
+            "id": "task-2",
+            "deliverable": "Second change",
+            "allowed_files": ["src/auth.py"],
+            "acceptance_command": "python -m pytest tests/test_auth.py",
+            "test_command": "python -m pytest tests/test_auth.py",
+            "verification_command": "python -m compileall src/auth.py",
+            "commit": 1,
+            "dependencies": ["task-1"],
+        }
+    )
+    packet_payload["tasks"][0]["dependencies"] = ["task-2"]
+    packet_file.write_text(json.dumps(packet_payload), encoding="utf-8")
+    validator_run = run_validator(packet_directory)
+    assert validator_run.returncode != 0
+    assert "dependency cycle detected" in validator_run.stderr
+
+
+def test_duplicate_dependencies_fail(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_packet(packet_directory)
+    packet_file = packet_directory / "packet.json"
+    packet_payload = json.loads(packet_file.read_text(encoding="utf-8"))
+    packet_payload["tasks"][0]["dependencies"] = ["task-1", "task-1"]
+    packet_file.write_text(json.dumps(packet_payload), encoding="utf-8")
+    validator_run = run_validator(packet_directory)
+    assert validator_run.returncode != 0
+    assert "dependencies: entries must be unique" in validator_run.stderr
+
+
+def test_incomplete_handoff_fails(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_packet(packet_directory)
+    (packet_directory / "handoff.md").write_text(
+        "## Approval\nApproval: approved\n## Task Order\nTask Order: task-1\n",
+        encoding="utf-8",
+    )
+    validator_run = run_validator(packet_directory)
+    assert validator_run.returncode != 0
+    assert "handoff.md: task task-1 missing deliverable" in validator_run.stderr
+
+
+def test_handoff_rejects_wrong_slug_approval_order_and_suffixed_commands(
+    tmp_path: Path,
+) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_packet(packet_directory)
+    handoff_file = packet_directory / "handoff.md"
+    handoff_text = handoff_file.read_text(encoding="utf-8")
+    handoff_file.write_text(
+        handoff_text.replace("Packet: add-login", "Packet: add-login-extra")
+        .replace("Approval: approved", "Approval: pending")
+        .replace("Task Order: task-1", "Task Order: task-2, task-1")
+        .replace(
+            "Acceptance command: python -m pytest tests/test_auth.py",
+            "Acceptance command: python -m pytest tests/test_auth.py --quiet",
+        ),
+        encoding="utf-8",
+    )
+    validator_run = run_validator(packet_directory)
+    assert validator_run.returncode != 0
+    assert "missing packet slug" in validator_run.stderr
+    assert "missing approval state" in validator_run.stderr
+    assert "task order does not match" in validator_run.stderr
+    assert "missing acceptance command" in validator_run.stderr
+
+
+def test_task_markdown_rejects_suffixed_commands(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_packet(packet_directory)
+    tasks_file = packet_directory / "tasks.md"
+    task_text = tasks_file.read_text(encoding="utf-8")
+    tasks_file.write_text(
+        task_text.replace(
+            "python -m pytest tests/test_auth.py;",
+            "python -m pytest tests/test_auth.py --quiet;",
+        ),
+        encoding="utf-8",
+    )
+    validator_run = run_validator(packet_directory)
+    assert validator_run.returncode != 0
+    assert "tasks.md: task task-1 missing acceptance_command" in validator_run.stderr
+
+
+def test_handoff_rejects_undeclared_task(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_packet(packet_directory)
+    handoff_file = packet_directory / "handoff.md"
+    handoff_file.write_text(
+        handoff_file.read_text(encoding="utf-8") + "\nTask task-2: Undeclared task\n",
+        encoding="utf-8",
+    )
+    validator_run = run_validator(packet_directory)
+    assert validator_run.returncode != 0
+    assert "handoff.md: declared tasks do not match packet.json" in validator_run.stderr
+
+
+def test_source_locator_and_path_boundaries_fail(tmp_path: Path) -> None:
+    packet_directory = tmp_path / "docs" / "plans" / "add-login"
+    write_packet(packet_directory)
+    packet_file = packet_directory / "packet.json"
+    packet_payload = json.loads(packet_file.read_text(encoding="utf-8"))
+    packet_payload["sources"][0]["locator"] = "authenticate_user"
+    packet_payload["sources"][0]["path"] = "src/auth..py"
+    packet_file.write_text(json.dumps(packet_payload), encoding="utf-8")
+    validator_run = run_validator(packet_directory)
+    assert validator_run.returncode != 0
+    assert "locator: must be line, lines, or section locator" in validator_run.stderr
+    assert "path: must be a repository-relative path" in validator_run.stderr

package/skills/plan-to-pr/scripts/test_validate_protocol.py

@@ -0,0 +1,135 @@
+"""Exercise the protocol validator through its command-line interface."""
+
+import hashlib
+import importlib.util
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+SCRIPT_PATH = Path(__file__).with_name("validate_protocol.py")
+SCHEMA_PATH = SCRIPT_PATH.parent.parent / "reference" / "run-record.schema.json"
+sys.path.insert(0, str(SCRIPT_PATH.parent))
+VALIDATE_PROTOCOL_SPEC = importlib.util.spec_from_file_location("validate_protocol", SCRIPT_PATH)
+assert VALIDATE_PROTOCOL_SPEC is not None
+assert VALIDATE_PROTOCOL_SPEC.loader is not None
+VALIDATE_PROTOCOL_MODULE = importlib.util.module_from_spec(VALIDATE_PROTOCOL_SPEC)
+VALIDATE_PROTOCOL_SPEC.loader.exec_module(VALIDATE_PROTOCOL_MODULE)
+ProtocolValidationError = VALIDATE_PROTOCOL_MODULE.ProtocolValidationError
+validate_record = VALIDATE_PROTOCOL_MODULE.validate_record
+
+
+def valid_record() -> dict[str, object]:
+    verification = {"acceptance_output": "passed: pytest", "verifier_output": "passed: clean", "verified_commit_gate": "passed: exact surface", "surface_hash": "a" * 64}
+    return {
+        "task_identity": "task-3", "deliverable": "validator", "allowed_files": ["validator.py"],
+        "acceptance_check": "pytest", "baseline": "clean", "worker_route": "implementation worker; effort=low", "commit": "a1b2c3d",
+        "review_record": {"resolved_model": "Luna", "effort": "low", "command": "/e-code-review low", "findings": [], "repair_status": "clean", "surface_hash": "a" * 64, "findings_only": True, "has_repair_flag": False},
+        "repair_record": {"resolved_model": "Luna", "effort": "low", "confirmed_findings": [], "repair_status": "not-required", "surface_hash": "a" * 64},
+        "reverification_record": verification, "verification_record": verification.copy(),
+    }
+
+
+def run_validator(record_path: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run([sys.executable, str(SCRIPT_PATH), str(record_path)], capture_output=True, text=True, check=False)
+
+
+def mutate_record(record: dict[str, object], field_name: str, mutated_field: object) -> None:
+    if field_name in ("findings_only", "review_extra"):
+        review_record = record["review_record"]
+        assert isinstance(review_record, dict)
+        review_record[field_name] = mutated_field
+    elif mutated_field is None:
+        del record[field_name]
+    else:
+        record[field_name] = mutated_field
+
+
+def test_cli_accepts_valid_record(tmp_path: Path) -> None:
+    record_path = tmp_path / "record.json"
+    record_path.write_text(json.dumps(valid_record()), encoding="utf-8")
+    completed_run = run_validator(record_path)
+    assert completed_run.returncode == 0
+    assert completed_run.stdout.strip() == "protocol validation passed"
+    assert completed_run.stderr == ""
+
+
+def test_cli_rejects_invalid_utf8_record(tmp_path: Path) -> None:
+    record_path = tmp_path / "invalid-utf8.json"
+    record_path.write_bytes(b"{\xff")
+
+    completed_run = run_validator(record_path)
+
+    assert completed_run.returncode == 2
+    assert completed_run.stdout == ""
+    assert completed_run.stderr == "protocol validation failed: invalid UTF-8\n"
+
+
+def test_cli_rejects_invalid_mutations(tmp_path: Path) -> None:
+    mutations: tuple[tuple[str, str, object], ...] = (("bad-commit", "commit", "not-a-commit"), ("bad-review", "findings_only", False), ("missing-evidence", "verification_record", None), ("bad-type", "allowed_files", "file.py"), ("empty-allowed-files", "allowed_files", []), ("extra-review-field", "review_extra", "unexpected"))
+    for each_name, each_field, mutated_field in mutations:
+        record = valid_record()
+        mutate_record(record, each_field, mutated_field)
+        record_path = tmp_path / f"{each_name}.json"
+        record_path.write_text(json.dumps(record), encoding="utf-8")
+        completed_run = run_validator(record_path)
+        assert completed_run.returncode == 2
+        assert completed_run.stdout == ""
+        assert completed_run.stderr.startswith("protocol validation failed:")
+
+
+def test_validate_record_rejects_absolute_allowed_file_paths() -> None:
+    for each_absolute_path in ("/absolute/file.py", r"C:\absolute\file.py", "C:/absolute/file.py"):
+        record = valid_record()
+        record["allowed_files"] = [each_absolute_path]
+
+        try:
+            validate_record(record, SCHEMA_PATH)
+        except ProtocolValidationError as error:
+            assert str(error) == "allowed_files contains an absolute path"
+        else:
+            raise AssertionError("absolute allowed file paths must be rejected")
+
+
+def test_validate_record_enforces_modified_schema(tmp_path: Path) -> None:
+    schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+    assert isinstance(schema, dict)
+    required_fields = schema["required"]
+    assert isinstance(required_fields, list)
+    required_fields.append("schema_added_field")
+    modified_schema_path = tmp_path / "modified-schema.json"
+    modified_schema_path.write_text(json.dumps(schema), encoding="utf-8")
+
+    try:
+        validate_record(valid_record(), modified_schema_path)
+    except ProtocolValidationError as error:
+        assert "schema_added_field" in str(error)
+    else:
+        raise AssertionError("modified schema must reject a record missing its new required field")
+
+
+def test_validate_record_accepts_worktree_with_matching_committed_surface_hash(tmp_path: Path) -> None:
+    worktree_path = tmp_path / "worktree"
+    worktree_path.mkdir()
+    subprocess.run(["git", "init"], cwd=worktree_path, check=True, capture_output=True)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=worktree_path, check=True)
+    subprocess.run(["git", "config", "user.name", "Protocol Test"], cwd=worktree_path, check=True)
+    tracked_file = worktree_path / "validator.py"
+    tracked_file.write_text("baseline\n", encoding="utf-8")
+    subprocess.run(["git", "add", "validator.py"], cwd=worktree_path, check=True)
+    subprocess.run(["git", "commit", "-m", "baseline"], cwd=worktree_path, check=True, capture_output=True)
+    tracked_file.write_text("validated\n", encoding="utf-8")
+    subprocess.run(["git", "add", "validator.py"], cwd=worktree_path, check=True)
+    subprocess.run(["git", "commit", "-m", "validated"], cwd=worktree_path, check=True, capture_output=True)
+    commit_hash = subprocess.run(["git", "rev-parse", "HEAD"], cwd=worktree_path, check=True, capture_output=True, text=True).stdout.strip()
+    committed_surface = subprocess.run(["git", "diff", f"{commit_hash}^", commit_hash, "--", "validator.py"], cwd=worktree_path, check=True, capture_output=True).stdout
+    surface_hash = hashlib.sha256(committed_surface).hexdigest()
+    record = valid_record()
+    record["worktree"] = str(worktree_path)
+    record["commit"] = commit_hash
+    for each_field_name in ("review_record", "repair_record", "reverification_record", "verification_record"):
+        nested_record = record[each_field_name]
+        assert isinstance(nested_record, dict)
+        nested_record["surface_hash"] = surface_hash
+
+    validate_record(record, SCHEMA_PATH)

package/skills/plan-to-pr/scripts/test_validate_run.py

@@ -0,0 +1,158 @@
+"""Regression tests for set-level task validation."""
+
+import json
+import importlib.util
+import subprocess
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+
+SCRIPT_DIRECTORY = Path(__file__).parent
+sys.path.insert(0, str(SCRIPT_DIRECTORY))
+VALIDATE_PROTOCOL_SPEC = importlib.util.spec_from_file_location("validate_protocol", SCRIPT_DIRECTORY / "validate_protocol.py")
+assert VALIDATE_PROTOCOL_SPEC is not None
+assert VALIDATE_PROTOCOL_SPEC.loader is not None
+VALIDATE_PROTOCOL_MODULE = importlib.util.module_from_spec(VALIDATE_PROTOCOL_SPEC)
+sys.modules["validate_protocol"] = VALIDATE_PROTOCOL_MODULE
+VALIDATE_PROTOCOL_SPEC.loader.exec_module(VALIDATE_PROTOCOL_MODULE)
+SCHEMA_PATH = SCRIPT_DIRECTORY.parent / "reference" / "run-record.schema.json"
+ProtocolValidationError = VALIDATE_PROTOCOL_MODULE.ProtocolValidationError
+TEST_VALIDATE_PROTOCOL_SPEC = importlib.util.spec_from_file_location("test_validate_protocol", SCRIPT_DIRECTORY / "test_validate_protocol.py")
+assert TEST_VALIDATE_PROTOCOL_SPEC is not None
+assert TEST_VALIDATE_PROTOCOL_SPEC.loader is not None
+TEST_VALIDATE_PROTOCOL_MODULE = importlib.util.module_from_spec(TEST_VALIDATE_PROTOCOL_SPEC)
+TEST_VALIDATE_PROTOCOL_SPEC.loader.exec_module(TEST_VALIDATE_PROTOCOL_MODULE)
+valid_record = TEST_VALIDATE_PROTOCOL_MODULE.valid_record
+VALIDATE_RUN_SPEC = importlib.util.spec_from_file_location("validate_run", SCRIPT_DIRECTORY / "validate_run.py")
+assert VALIDATE_RUN_SPEC is not None
+assert VALIDATE_RUN_SPEC.loader is not None
+VALIDATE_RUN_MODULE = importlib.util.module_from_spec(VALIDATE_RUN_SPEC)
+VALIDATE_RUN_SPEC.loader.exec_module(VALIDATE_RUN_MODULE)
+main = VALIDATE_RUN_MODULE.main
+validate_run = VALIDATE_RUN_MODULE.validate_run
+
+
+def test_validate_run_accepts_one_record_per_commit() -> None:
+    task_record = valid_record()
+    validate_run([task_record], {"a1b2c3d"}, SCHEMA_PATH, {})
+
+
+def test_validate_run_accepts_matching_explicit_mapping() -> None:
+    task_record = valid_record()
+    validate_run(
+        [task_record],
+        {"a1b2c3d"},
+        SCHEMA_PATH,
+        {"task-3": "a1b2c3d"},
+    )
+
+
+@pytest.mark.parametrize(
+    "explicit_mapping",
+    [
+        {"wrong-task": "a1b2c3d"},
+        {"task-3": "deadbeef"},
+    ],
+)
+def test_validate_run_rejects_mismatched_explicit_mapping(
+    explicit_mapping: dict[str, str],
+) -> None:
+    with pytest.raises(ProtocolValidationError, match="explicit task mappings"):
+        validate_run([valid_record()], {"a1b2c3d"}, SCHEMA_PATH, explicit_mapping)
+
+
+def test_validate_run_rejects_duplicate_commits_in_explicit_mapping() -> None:
+    first_record = valid_record()
+    second_record = valid_record()
+    second_record["task_identity"] = "task-4"
+    second_record["commit"] = "deadbeef"
+    with pytest.raises(ProtocolValidationError, match="unique commits"):
+        validate_run(
+            [first_record, second_record],
+            {"a1b2c3d"},
+            SCHEMA_PATH,
+            {"task-1": "a1b2c3d", "task-4": "a1b2c3d"},
+        )
+
+
+@pytest.mark.parametrize(
+    "mutation",
+    [
+        lambda record: record.update(task_identity="task-3"),
+        lambda record: record.update(commit="outside"),
+    ],
+)
+def test_validate_run_rejects_invalid_commit_or_identity(
+    mutation: Callable[[dict[str, object]], None],
+) -> None:
+    first_record = valid_record()
+    second_record = valid_record()
+    second_record["task_identity"] = "task-4"
+    mutation(second_record)
+    with pytest.raises(ProtocolValidationError):
+        validate_run(
+            [first_record, second_record], {"a1b2c3d", "deadbeef"}, SCHEMA_PATH, {}
+        )
+
+
+def test_validate_run_rejects_count_mismatch_without_mapping() -> None:
+    with pytest.raises(ProtocolValidationError):
+        validate_run([valid_record()], {"a1b2c3d", "deadbeef"}, SCHEMA_PATH, {})
+
+
+def create_committed_worktree(worktree_path: Path) -> str:
+    worktree_path.mkdir()
+    initialize_worktree(worktree_path)
+    tracked_file = worktree_path / "validator.py"
+    tracked_file.write_text("validated\n", encoding="utf-8")
+    commit_file(worktree_path)
+    return read_head(worktree_path)
+
+
+def initialize_worktree(worktree_path: Path) -> None:
+    subprocess.run(["git", "init"], cwd=worktree_path, check=True, capture_output=True)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=worktree_path, check=True)
+    subprocess.run(["git", "config", "user.name", "Protocol Test"], cwd=worktree_path, check=True)
+
+
+def commit_file(worktree_path: Path) -> None:
+    subprocess.run(["git", "add", "validator.py"], cwd=worktree_path, check=True)
+    subprocess.run(["git", "commit", "-m", "validated"], cwd=worktree_path, check=True, capture_output=True)
+
+
+def read_head(worktree_path: Path) -> str:
+    return subprocess.run(["git", "rev-parse", "HEAD"], cwd=worktree_path, check=True, capture_output=True, text=True).stdout.strip()
+
+
+def test_main_rejects_surface_mismatch_when_worktree_is_selected(
+    tmp_path: Path,
+) -> None:
+    worktree_path = tmp_path / "worktree"
+    commit_hash = create_committed_worktree(worktree_path)
+    task_record = valid_record()
+    task_record["commit"] = commit_hash
+    task_record["allowed_files"] = ["validator.py"]
+    for each_field_name in (
+        "review_record",
+        "repair_record",
+        "reverification_record",
+        "verification_record",
+    ):
+        nested_record = task_record[each_field_name]
+        assert isinstance(nested_record, dict)
+        nested_record["surface_hash"] = "0" * 64
+    record_path = tmp_path / "records.json"
+    record_path.write_text(json.dumps([task_record]), encoding="utf-8")
+    exit_code = main(
+        [
+            "validate_run.py",
+            str(record_path),
+            "--commits",
+            commit_hash,
+            "--worktree",
+            str(worktree_path),
+        ]
+    )
+    assert exit_code == 2