claude-dev-env 2.7.1 → 2.8.0

package/scripts/test_invoke_code_review.py

@@ -15,11 +15,37 @@ import pytest
 import invoke_code_review as invoker
 from claude_chain_runner import ChainConfigurationError, ChainInvocationOutcome
 from _code_review_test_support import FIXTURE_SESSION_OPUS
+from dev_env_scripts_constants.claude_chain_constants import TERMINAL_STATUS_SERVED
 from dev_env_scripts_constants.code_review_constants import (
+    ALL_FINDING_SEVERITIES,
+    ALL_LOOP_TERMINALS,
+    ALL_RETAINED_VERIFICATION_VERDICTS,
     DEFAULT_CODE_REVIEW_EFFORT,
+    FINDING_FIELD_SEVERITY,
+    FINDING_FIELD_VERDICT,
     PERMISSION_MODE_ACCEPT_EDITS,
     PERMISSION_MODE_BYPASS,
+    RESULT_KEY_DRAFT_PRESERVED,
+    RESULT_KEY_REVIEWED_HEAD_COUNT,
+    RESULT_KEY_SURVIVING_FINDINGS,
+    RESULT_KEY_TERMINAL,
     REVIEW_PERMISSION_MODE,
+    SEVERITY_BLOCKER,
+    SEVERITY_HIGH,
+    SEVERITY_LOW,
+    SEVERITY_MEDIUM,
+    SEVERITY_NIT,
+    TERMINAL_ADVISOR_BLOCKED,
+    TERMINAL_CLEAN,
+    TERMINAL_NITS_FIXED,
+    VERDICT_CONFIRMED,
+    VERDICT_PLAUSIBLE,
+    VERDICT_REFUTED,
+    all_findings_carry_severity_and_verdict,
+    encode_review_loop_terminal_result,
+    is_nits_only_findings,
+    record_reviewed_head,
+    resolve_review_loop_terminal,
 )
 
 
@@ -66,6 +92,7 @@ def _serve_a_refusing_binary(
         stdout=EMPTY_REVIEW_STDOUT,
         stderr=REVIEW_BINARY_REFUSAL_TEXT,
         attempts=(),
+        terminal_status=TERMINAL_STATUS_SERVED,
     )
 
 
@@ -141,3 +168,274 @@ def test_host_profile_failure_reports_its_reason_on_stderr(
     captured_streams = capsys.readouterr()
     assert outcome.is_stamp_minted is False
     assert HOST_PROFILE_FAILURE_TEXT in captured_streams.err
+
+
+HEAD_SHA_ONE: str = "aaa111"
+HEAD_SHA_TWO: str = "bbb222"
+HEAD_SHA_THREE: str = "ccc333"
+HEAD_SHA_FOUR: str = "ddd444"
+FINDING_FILE_PATH: str = "pkg/module.py"
+FINDING_LINE_NUMBER: int = 12
+FINDING_SUMMARY_TEXT: str = "example finding"
+
+
+def _retained_finding(
+    *,
+    severity: str,
+    verdict: str = VERDICT_CONFIRMED,
+) -> dict[str, object]:
+    return {
+        "file": FINDING_FILE_PATH,
+        "line": FINDING_LINE_NUMBER,
+        "summary": FINDING_SUMMARY_TEXT,
+        FINDING_FIELD_SEVERITY: severity,
+        FINDING_FIELD_VERDICT: verdict,
+    }
+
+
+def test_severity_vocabulary_is_the_frozen_five_token_set() -> None:
+    assert ALL_FINDING_SEVERITIES == (
+        SEVERITY_BLOCKER,
+        SEVERITY_HIGH,
+        SEVERITY_MEDIUM,
+        SEVERITY_LOW,
+        SEVERITY_NIT,
+    )
+    assert ALL_FINDING_SEVERITIES == (
+        "blocker",
+        "high",
+        "medium",
+        "low",
+        "nit",
+    )
+
+
+def test_loop_terminals_are_the_frozen_three_token_set() -> None:
+    assert ALL_LOOP_TERMINALS == (
+        TERMINAL_CLEAN,
+        TERMINAL_NITS_FIXED,
+        TERMINAL_ADVISOR_BLOCKED,
+    )
+
+
+def test_retained_finding_requires_severity_and_verification_verdict() -> None:
+    complete_finding = _retained_finding(severity=SEVERITY_HIGH)
+    missing_severity = {
+        "file": FINDING_FILE_PATH,
+        "line": FINDING_LINE_NUMBER,
+        FINDING_FIELD_VERDICT: VERDICT_CONFIRMED,
+    }
+    missing_verdict = {
+        "file": FINDING_FILE_PATH,
+        "line": FINDING_LINE_NUMBER,
+        FINDING_FIELD_SEVERITY: SEVERITY_HIGH,
+    }
+    refuted_finding = _retained_finding(
+        severity=SEVERITY_LOW,
+        verdict=VERDICT_REFUTED,
+    )
+
+    assert all_findings_carry_severity_and_verdict([complete_finding]) is True
+    assert all_findings_carry_severity_and_verdict([missing_severity]) is False
+    assert all_findings_carry_severity_and_verdict([missing_verdict]) is False
+    assert all_findings_carry_severity_and_verdict([refuted_finding]) is False
+    assert VERDICT_CONFIRMED in ALL_RETAINED_VERIFICATION_VERDICTS
+    assert VERDICT_PLAUSIBLE in ALL_RETAINED_VERIFICATION_VERDICTS
+    assert VERDICT_REFUTED not in ALL_RETAINED_VERIFICATION_VERDICTS
+
+
+def test_review_of_new_head_increments_reviewed_head_count_once() -> None:
+    after_first = record_reviewed_head((), HEAD_SHA_ONE)
+    after_same_head = record_reviewed_head(after_first, HEAD_SHA_ONE)
+    after_second = record_reviewed_head(after_same_head, HEAD_SHA_TWO)
+
+    assert after_first == (HEAD_SHA_ONE,)
+    assert after_same_head == (HEAD_SHA_ONE,)
+    assert after_second == (HEAD_SHA_ONE, HEAD_SHA_TWO)
+    assert len(after_second) == 2
+
+
+def test_empty_findings_return_clean() -> None:
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=(),
+        reviewed_head_count=1,
+        is_gates_passed=True,
+        is_nits_applied=False,
+    )
+
+    assert terminal_status == TERMINAL_CLEAN
+
+
+def test_empty_findings_continue_when_gates_have_not_passed() -> None:
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=(),
+        reviewed_head_count=1,
+        is_gates_passed=False,
+        is_nits_applied=False,
+    )
+
+    assert terminal_status is None
+
+
+def test_nits_only_round_returns_nits_fixed_after_gates() -> None:
+    all_nits = (
+        _retained_finding(severity=SEVERITY_NIT),
+        _retained_finding(severity=SEVERITY_NIT, verdict=VERDICT_PLAUSIBLE),
+    )
+
+    assert is_nits_only_findings(all_nits) is True
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=all_nits,
+        reviewed_head_count=1,
+        is_gates_passed=True,
+        is_nits_applied=True,
+    )
+
+    assert terminal_status == TERMINAL_NITS_FIXED
+
+
+def test_nits_without_retained_verdict_do_not_return_nits_fixed() -> None:
+    severity_only_nit = {
+        "file": FINDING_FILE_PATH,
+        "line": FINDING_LINE_NUMBER,
+        "summary": FINDING_SUMMARY_TEXT,
+        FINDING_FIELD_SEVERITY: SEVERITY_NIT,
+    }
+
+    assert is_nits_only_findings((severity_only_nit,)) is True
+    assert all_findings_carry_severity_and_verdict((severity_only_nit,)) is False
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=(severity_only_nit,),
+        reviewed_head_count=1,
+        is_gates_passed=True,
+        is_nits_applied=True,
+    )
+
+    assert terminal_status is None
+
+
+def test_open_non_nit_findings_continue_at_any_head_count() -> None:
+    all_findings = (
+        _retained_finding(severity=SEVERITY_HIGH),
+        _retained_finding(severity=SEVERITY_NIT),
+    )
+    all_heads = record_reviewed_head((), HEAD_SHA_ONE)
+    all_heads = record_reviewed_head(all_heads, HEAD_SHA_TWO)
+    all_heads = record_reviewed_head(all_heads, HEAD_SHA_THREE)
+    all_heads = record_reviewed_head(all_heads, HEAD_SHA_FOUR)
+
+    assert len(all_heads) == 4
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=all_findings,
+        reviewed_head_count=len(all_heads),
+        is_gates_passed=True,
+        is_nits_applied=False,
+    )
+
+    assert terminal_status is None
+
+
+def test_unclassified_findings_continue_when_advisor_is_reachable() -> None:
+    unclassified_finding = {
+        "file": FINDING_FILE_PATH,
+        "line": FINDING_LINE_NUMBER,
+        "summary": FINDING_SUMMARY_TEXT,
+        FINDING_FIELD_VERDICT: VERDICT_CONFIRMED,
+    }
+
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=(unclassified_finding,),
+        reviewed_head_count=5,
+        is_gates_passed=True,
+        is_nits_applied=False,
+    )
+
+    assert terminal_status is None
+
+
+def test_nits_only_returns_nits_fixed_at_any_head_count() -> None:
+    all_nits = (_retained_finding(severity=SEVERITY_NIT),)
+
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=all_nits,
+        reviewed_head_count=5,
+        is_gates_passed=True,
+        is_nits_applied=True,
+    )
+
+    assert terminal_status == TERMINAL_NITS_FIXED
+
+
+def test_advisor_unreachable_with_unclassified_returns_advisor_blocked() -> None:
+    unclassified_finding = {
+        "file": FINDING_FILE_PATH,
+        "line": FINDING_LINE_NUMBER,
+        FINDING_FIELD_VERDICT: VERDICT_CONFIRMED,
+    }
+
+    terminal_status = resolve_review_loop_terminal(
+        all_findings=(unclassified_finding,),
+        reviewed_head_count=1,
+        is_gates_passed=False,
+        is_nits_applied=False,
+        is_advisor_unreachable=True,
+    )
+
+    assert terminal_status == TERMINAL_ADVISOR_BLOCKED
+
+
+def test_terminal_serialization_preserves_draft_and_findings() -> None:
+    surviving_finding = _retained_finding(severity=SEVERITY_MEDIUM)
+    encoded_payload = encode_review_loop_terminal_result(
+        terminal=TERMINAL_ADVISOR_BLOCKED,
+        all_surviving_findings=(surviving_finding,),
+        reviewed_head_count=4,
+        is_draft_preserved=True,
+    )
+
+    assert encoded_payload[RESULT_KEY_TERMINAL] == TERMINAL_ADVISOR_BLOCKED
+    assert encoded_payload[RESULT_KEY_DRAFT_PRESERVED] is True
+    assert encoded_payload[RESULT_KEY_REVIEWED_HEAD_COUNT] == 4
+    assert encoded_payload[RESULT_KEY_SURVIVING_FINDINGS] == [surviving_finding]
+
+
+def test_advisor_blocked_forces_draft_preserved_when_caller_passes_false() -> None:
+    surviving_finding = _retained_finding(severity=SEVERITY_HIGH)
+    advisor_blocked_payload = encode_review_loop_terminal_result(
+        terminal=TERMINAL_ADVISOR_BLOCKED,
+        all_surviving_findings=(surviving_finding,),
+        reviewed_head_count=1,
+        is_draft_preserved=False,
+    )
+    clean_payload = encode_review_loop_terminal_result(
+        terminal=TERMINAL_CLEAN,
+        all_surviving_findings=(),
+        reviewed_head_count=1,
+        is_draft_preserved=False,
+    )
+
+    assert advisor_blocked_payload[RESULT_KEY_DRAFT_PRESERVED] is True
+    assert clean_payload[RESULT_KEY_DRAFT_PRESERVED] is False
+
+
+def test_fourth_and_later_heads_are_recorded() -> None:
+    all_heads = (HEAD_SHA_ONE, HEAD_SHA_TWO, HEAD_SHA_THREE)
+    after_fourth = record_reviewed_head(all_heads, HEAD_SHA_FOUR)
+
+    assert after_fourth == (
+        HEAD_SHA_ONE,
+        HEAD_SHA_TWO,
+        HEAD_SHA_THREE,
+        HEAD_SHA_FOUR,
+    )
+    assert len(after_fourth) == 4
+
+
+def test_mixed_severities_are_not_nits_only() -> None:
+    all_findings = (
+        _retained_finding(severity=SEVERITY_NIT),
+        _retained_finding(severity=SEVERITY_BLOCKER),
+    )
+
+    assert is_nits_only_findings(all_findings) is False
+    assert is_nits_only_findings(()) is False

package/scripts/test_resolve_worker_spawn.py

@@ -23,6 +23,10 @@ from claude_chain_runner import (  # noqa: E402
     ChainConfigurationError,
     ChainInvocationOutcome,
 )
+from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
+    TERMINAL_STATUS_CHAIN_EXHAUSTED,
+    TERMINAL_STATUS_SERVED,
+)
 from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     AGENT_FLAG,
     ALL_AGENT_FILENAMES_BY_ROLE,
@@ -133,6 +137,7 @@ def _claude_served(
         stdout=stdout,
         stderr="",
         attempts=(ChainAttempt(command="claude", status="served"),),
+        terminal_status=TERMINAL_STATUS_SERVED,
     )
 
 
@@ -143,6 +148,7 @@ def _claude_exhausted() -> ChainInvocationOutcome:
         stdout="",
         stderr="usage limit reached",
         attempts=(ChainAttempt(command="claude", status="usage_limited"),),
+        terminal_status=TERMINAL_STATUS_CHAIN_EXHAUSTED,
     )
 
 

package/scripts/test_spawn_grok_batch.py

@@ -874,6 +874,107 @@ def test_load_batch_spec_missing_worker_keys_raise_value_error(
     ).lower() or "must be" in str(raised_error.value).lower()
 
 
+def test_load_batch_spec_rejects_an_unknown_worker_key(
+    tmp_path: Path,
+) -> None:
+    header_part, body_part = _write_prompt_parts(tmp_path)
+    working_directory = tmp_path / "project"
+    working_directory.mkdir()
+    worker_payload = _worker_payload(
+        role_name="stray-key-worker",
+        all_prompt_parts=[str(header_part), str(body_part)],
+        working_directory=working_directory,
+        tool_profile=TOOL_PROFILE_BUILD,
+    )
+    worker_payload["timeout_second"] = 30
+    specification_path = _write_batch_spec(
+        tmp_path, all_worker_payloads=[worker_payload]
+    )
+
+    with pytest.raises(ValueError) as raised_error:
+        batch.load_batch_spec(specification_path)
+
+    error_text = str(raised_error.value)
+    assert "timeout_second" in error_text
+    assert WORKER_SPEC_TIMEOUT_KEY in error_text
+
+
+def test_load_batch_spec_names_every_unknown_worker_key(
+    tmp_path: Path,
+) -> None:
+    header_part, body_part = _write_prompt_parts(tmp_path)
+    working_directory = tmp_path / "project"
+    working_directory.mkdir()
+    worker_payload = _worker_payload(
+        role_name="two-stray-keys",
+        all_prompt_parts=[str(header_part), str(body_part)],
+        working_directory=working_directory,
+        tool_profile=TOOL_PROFILE_BUILD,
+    )
+    worker_payload["stray_cap"] = 5
+    worker_payload["notes"] = "operator scratch"
+    specification_path = _write_batch_spec(
+        tmp_path, all_worker_payloads=[worker_payload]
+    )
+
+    with pytest.raises(ValueError) as raised_error:
+        batch.load_batch_spec(specification_path)
+
+    error_text = str(raised_error.value)
+    assert "stray_cap" in error_text
+    assert "notes" in error_text
+
+
+def test_load_batch_spec_rejects_the_retired_turn_cap_key(
+    tmp_path: Path,
+) -> None:
+    header_part, body_part = _write_prompt_parts(tmp_path)
+    working_directory = tmp_path / "project"
+    working_directory.mkdir()
+    worker_payload = _worker_payload(
+        role_name="retired-cap-worker",
+        all_prompt_parts=[str(header_part), str(body_part)],
+        working_directory=working_directory,
+        tool_profile=TOOL_PROFILE_BUILD,
+    )
+    worker_payload[RETIRED_MAX_TURNS_KEYWORD] = 5
+    specification_path = _write_batch_spec(
+        tmp_path, all_worker_payloads=[worker_payload]
+    )
+
+    with pytest.raises(ValueError) as raised_error:
+        batch.load_batch_spec(specification_path)
+
+    error_text = str(raised_error.value)
+    assert RETIRED_MAX_TURNS_KEYWORD in error_text
+    assert WORKER_SPEC_TIMEOUT_KEY in error_text
+
+
+def test_load_batch_spec_accepts_every_documented_worker_key(
+    tmp_path: Path,
+) -> None:
+    header_part, body_part = _write_prompt_parts(tmp_path)
+    working_directory = tmp_path / "project"
+    working_directory.mkdir()
+    worker_payload: dict[str, object] = {
+        "role_name": "every-key-worker",
+        "prompt_parts": [str(header_part), str(body_part)],
+        "cwd": str(working_directory),
+        "tool_profile": TOOL_PROFILE_READONLY,
+        "timeout_seconds": 30,
+        "is_repo_only": True,
+        "agent_name": None,
+    }
+    specification_path = _write_batch_spec(
+        tmp_path, all_worker_payloads=[worker_payload]
+    )
+
+    batch_spec = batch.load_batch_spec(specification_path)
+
+    assert batch_spec.all_workers[0].role_name == "every-key-worker"
+    assert batch_spec.all_workers[0].is_repo_only is True
+
+
 def test_load_batch_spec_rejects_non_positive_timeout(
     tmp_path: Path,
 ) -> None:

package/scripts/tests/CLAUDE.md

@@ -10,6 +10,7 @@ pytest suite for the Python scripts and Pester suite for the PowerShell scripts
 | `test_setup_project_paths_config.py` | Configuration constants used by `setup_project_paths.py` |
 | `test_sweep_empty_dirs.py` | `sweep_empty_dirs.py` — age check, one-shot mode, and continuous-watch behavior |
 | `test_sync_to_cursor.py` | `sync_to_cursor/` package — mapping, hashing, manifest, and path resolution |
+| `test_grok_worker_constants.py` | `grok_worker_constants.py` — the accepted batch worker-key set stays in step with the worker key constants, and the unknown-key message names both its placeholders |
 
 ## PowerShell test files
 

package/scripts/tests/test_grok_worker_constants.py

@@ -0,0 +1,59 @@
+"""Specifications for the accepted-key set on a batch worker entry.
+
+The batch launcher rejects a worker entry carrying any key outside
+``ALL_KNOWN_WORKER_SPEC_KEYS``. That makes the set a gate on the published
+JSON contract: a worker key the module defines but the set omits is rejected
+from every spec that uses it, and a member the module declares nowhere keeps
+accepting a key the launcher drops. Both drifts are silent, so they are
+pinned here.
+"""
+
+from __future__ import annotations
+
+from dev_env_scripts_constants import grok_worker_constants
+
+WORKER_SPEC_KEY_NAME_PREFIX: str = "WORKER_SPEC_"
+WORKER_SPEC_KEY_NAME_SUFFIX: str = "_KEY"
+
+
+def _all_declared_worker_key_values() -> set[str]:
+    """Read every ``WORKER_SPEC_*_KEY`` value the constants module declares."""
+    return {
+        getattr(grok_worker_constants, each_name)
+        for each_name in dir(grok_worker_constants)
+        if each_name.startswith(WORKER_SPEC_KEY_NAME_PREFIX)
+        and each_name.endswith(WORKER_SPEC_KEY_NAME_SUFFIX)
+    }
+
+
+def test_should_accept_every_declared_worker_spec_key() -> None:
+    all_declared_key_values = _all_declared_worker_key_values()
+    all_missing_key_values = (
+        all_declared_key_values - grok_worker_constants.ALL_KNOWN_WORKER_SPEC_KEYS
+    )
+
+    assert not all_missing_key_values, (
+        "worker key constants missing from the accepted set: "
+        f"{sorted(all_missing_key_values)}"
+    )
+
+
+def test_should_accept_only_keys_the_module_declares() -> None:
+    all_declared_key_values = _all_declared_worker_key_values()
+    all_stale_key_values = (
+        grok_worker_constants.ALL_KNOWN_WORKER_SPEC_KEYS - all_declared_key_values
+    )
+
+    assert not all_stale_key_values, (
+        f"accepted keys with no worker key constant: {sorted(all_stale_key_values)}"
+    )
+
+
+def test_should_name_both_placeholders_in_the_unknown_key_message() -> None:
+    formatted_message = grok_worker_constants.UNKNOWN_WORKER_KEY_ERROR_TEMPLATE.format(
+        unknown_keys="timeout_second",
+        accepted_keys="timeout_seconds",
+    )
+
+    assert "timeout_second;" in formatted_message
+    assert formatted_message.endswith("timeout_seconds")

package/skills/_shared/pr-loop/scripts/test_build_audit_prompt.py

@@ -378,3 +378,49 @@ def test_main_headless_flavor_emits_outcome_path_on_stdout(
     assert "post_audit_thread.py" in captured.out
     assert "Do not post reviews" in captured.out
     assert "add_comment_to_pending_review" not in captured.out
+
+
+_PACKAGE_ROOT = _SCRIPTS_DIR.parents[3]
+_CODE_QUALITY_AGENT_PATH = _PACKAGE_ROOT / "agents" / "code-quality-agent.md"
+_AUDIT_CONTRACT_PATH = _PACKAGE_ROOT / "_shared" / "pr-loop" / "audit-contract.md"
+_PRECATCH_RUBRIC_PATH = _PACKAGE_ROOT / "_shared" / "pr-loop" / "precatch-rubric.md"
+_CATEGORY_Q_LABEL = (
+    "Cross-surface claim consistency "
+    "(terminology, PR-description claims, message-vs-guard)"
+)
+_CATEGORY_Q_RUBRIC_REFERENCE = (
+    "../audit-rubrics/category_rubrics/category-q-cross-surface-claims.md"
+)
+_A_THROUGH_Q_PATTERN = re.compile(r"A[\u2013-]Q")
+_SEVENTEEN_CATEGORIES_PATTERN = re.compile(r"seventeen categor", re.IGNORECASE)
+_STALE_SIXTEEN_PATTERN = re.compile(r"sixteen categor", re.IGNORECASE)
+_STALE_A_THROUGH_P_PATTERN = re.compile(r"A[\u2013-]P")
+
+
+def test_code_quality_agent_default_scope_is_a_through_q() -> None:
+    agent_text = _CODE_QUALITY_AGENT_PATH.read_text(encoding="utf-8")
+    assert _A_THROUGH_Q_PATTERN.search(agent_text) is not None
+    assert _SEVENTEEN_CATEGORIES_PATTERN.search(agent_text) is not None
+    assert _STALE_SIXTEEN_PATTERN.search(agent_text) is None
+    assert "A through Q" in agent_text
+    assert "A through P" not in agent_text
+    assert _STALE_A_THROUGH_P_PATTERN.search(agent_text) is None
+    assert "## Bug Categories A–Q" in agent_text
+    assert _CATEGORY_Q_LABEL in agent_text
+    assert _CATEGORY_Q_RUBRIC_REFERENCE in agent_text
+    assert "| Q |" in agent_text
+
+
+def test_audit_contract_category_schema_includes_q() -> None:
+    contract_text = _AUDIT_CONTRACT_PATH.read_text(encoding="utf-8")
+    assert '"category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q"' in (
+        contract_text
+    )
+    assert _A_THROUGH_Q_PATTERN.search(contract_text) is not None
+    assert _STALE_A_THROUGH_P_PATTERN.search(contract_text) is None
+
+
+def test_precatch_rubric_adversarial_lane_uses_a_through_q() -> None:
+    rubric_text = _PRECATCH_RUBRIC_PATH.read_text(encoding="utf-8")
+    assert _A_THROUGH_Q_PATTERN.search(rubric_text) is not None
+    assert _STALE_A_THROUGH_P_PATTERN.search(rubric_text) is None