claude-dev-env 2.7.0 → 2.8.0

package/scripts/dev_env_scripts_constants/code_review_constants.py

@@ -1,15 +1,20 @@
-"""Named constants for the host-aware `/code-review` invoker.
+"""Named constants for the host-aware `/code-review` invoker and review loop.
 
 ::
 
     ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER
         ok: ("low", "medium", "high", "xhigh", "max")
         flag: "ultra"  (rejected; needs an interactive terminal)
+    ALL_FINDING_SEVERITIES
+        ok: ("blocker", "high", "medium", "low", "nit")
+    ALL_LOOP_TERMINALS
+        ok: ("clean", "nits_fixed", "advisor_blocked")
     RECORD_STAMP_FLAG
         ok: "--record-stamp"
 
 Effort tokens re-export the hooks enforcement constants (single source).
-Scalar flags, JSON keys, and mint-loop messages live here for the invoker.
+Scalar flags, JSON keys, mint-loop messages, finding severity vocabulary,
+reviewed-head counting, and loop terminal resolution live here.
 """
 
 from __future__ import annotations
@@ -17,6 +22,7 @@ from __future__ import annotations
 import importlib.util
 import os
 import sys
+from collections.abc import Mapping, Sequence
 from pathlib import Path
 from types import ModuleType
 
@@ -223,3 +229,398 @@ STAMP_STORE_RECORD_CLEAN_STAMP_NAME: str = "record_clean_stamp"
 
 STAMP_STORE_RESOLVE_REPO_ROOT_NAME: str = "resolve_repo_root"
 """Attribute name of the repo-root resolver on the stamp store module."""
+
+SEVERITY_BLOCKER: str = "blocker"
+"""Finding severity for a release-blocking defect."""
+
+SEVERITY_HIGH: str = "high"
+"""Finding severity for a high-impact defect that is not a release blocker."""
+
+SEVERITY_MEDIUM: str = "medium"
+"""Finding severity for a moderate maintainer-action defect."""
+
+SEVERITY_LOW: str = "low"
+"""Finding severity for a low-impact non-nit defect."""
+
+SEVERITY_NIT: str = "nit"
+"""Finding severity for a mechanical clarity, format, or typo fix only."""
+
+ALL_FINDING_SEVERITIES: tuple[str, ...] = (
+    SEVERITY_BLOCKER,
+    SEVERITY_HIGH,
+    SEVERITY_MEDIUM,
+    SEVERITY_LOW,
+    SEVERITY_NIT,
+)
+"""Frozen severity vocabulary every retained finding must use."""
+
+VERDICT_CONFIRMED: str = "CONFIRMED"
+"""Verification verdict when the trigger and wrong outcome are named."""
+
+VERDICT_PLAUSIBLE: str = "PLAUSIBLE"
+"""Verification verdict when the mechanism is real and the trigger is uncertain."""
+
+VERDICT_REFUTED: str = "REFUTED"
+"""Verification verdict when the candidate is factually wrong or guarded."""
+
+ALL_VERIFICATION_VERDICTS: tuple[str, ...] = (
+    VERDICT_CONFIRMED,
+    VERDICT_PLAUSIBLE,
+    VERDICT_REFUTED,
+)
+"""Frozen verification-verdict vocabulary from the medium verify phase."""
+
+ALL_RETAINED_VERIFICATION_VERDICTS: tuple[str, ...] = (
+    VERDICT_CONFIRMED,
+    VERDICT_PLAUSIBLE,
+)
+"""Verdicts that keep a candidate in the retained findings list."""
+
+TERMINAL_CLEAN: str = "clean"
+"""Loop terminal when a reviewed head retains zero findings."""
+
+TERMINAL_NITS_FIXED: str = "nits_fixed"
+"""Loop terminal when every retained finding is a fixed nit after gates."""
+
+TERMINAL_ADVISOR_BLOCKED: str = "advisor_blocked"
+"""Loop terminal when classification needs an advisor that cannot be reached."""
+
+ALL_LOOP_TERMINALS: tuple[str, ...] = (
+    TERMINAL_CLEAN,
+    TERMINAL_NITS_FIXED,
+    TERMINAL_ADVISOR_BLOCKED,
+)
+"""Frozen set of review-loop terminal statuses."""
+
+FINDING_FIELD_SEVERITY: str = "severity"
+"""Structured finding field that holds one of ``ALL_FINDING_SEVERITIES``."""
+
+FINDING_FIELD_VERDICT: str = "verdict"
+"""Structured finding field that holds a verification verdict."""
+
+RESULT_KEY_TERMINAL: str = "terminal"
+"""JSON result key naming the review-loop terminal status."""
+
+RESULT_KEY_DRAFT_PRESERVED: str = "draft_preserved"
+"""JSON result key holding whether the pull request stays draft."""
+
+RESULT_KEY_REVIEWED_HEAD_COUNT: str = "reviewed_head_count"
+"""JSON result key holding how many distinct heads the loop reviewed."""
+
+RESULT_KEY_SURVIVING_FINDINGS: str = "surviving_findings"
+"""JSON result key holding structured findings that remain at terminal."""
+
+
+def is_known_finding_severity(severity: str) -> bool:
+    """Return whether ``severity`` is one of the frozen five tokens.
+
+    ::
+
+        is_known_finding_severity("nit")      # ok: True
+        is_known_finding_severity("P1")       # flag: False
+        is_known_finding_severity("")         # flag: False
+
+    Args:
+        severity: Candidate severity token from a structured finding.
+
+    Returns:
+        True when ``severity`` is in ``ALL_FINDING_SEVERITIES``.
+    """
+    return severity in ALL_FINDING_SEVERITIES
+
+
+def is_nit_finding_severity(severity: str) -> bool:
+    """Return whether ``severity`` is exactly the nit token.
+
+    ::
+
+        is_nit_finding_severity("nit")   # ok: True
+        is_nit_finding_severity("low")   # flag: False
+
+    Args:
+        severity: Candidate severity token from a structured finding.
+
+    Returns:
+        True when ``severity`` equals ``SEVERITY_NIT``.
+    """
+    return severity == SEVERITY_NIT
+
+
+def is_retained_verification_verdict(verdict: str) -> bool:
+    """Return whether ``verdict`` keeps a finding in the retained set.
+
+    ::
+
+        is_retained_verification_verdict("CONFIRMED")  # ok: True
+        is_retained_verification_verdict("REFUTED")    # flag: False
+
+    Args:
+        verdict: Verification vote from the medium verify phase.
+
+    Returns:
+        True when ``verdict`` is CONFIRMED or PLAUSIBLE.
+    """
+    return verdict in ALL_RETAINED_VERIFICATION_VERDICTS
+
+
+def finding_carries_severity_and_verdict(
+    *,
+    severity: object,
+    verdict: object,
+) -> bool:
+    """Return whether one retained finding carries both required fields.
+
+    ::
+
+        finding_carries_severity_and_verdict(
+            severity="high", verdict="CONFIRMED"
+        )  # ok: True
+        finding_carries_severity_and_verdict(
+            severity="high", verdict=None
+        )  # flag: False
+
+    A retained finding needs a known severity and a retained verification
+    verdict. Missing either field, or a REFUTED verdict, fails the contract.
+
+    Args:
+        severity: Severity token from a structured finding, or missing value.
+        verdict: Verification verdict from a structured finding, or missing.
+
+    Returns:
+        True when severity and retained verdict are both present and valid.
+    """
+    if not isinstance(severity, str) or not isinstance(verdict, str):
+        return False
+    if not is_known_finding_severity(severity):
+        return False
+    return is_retained_verification_verdict(verdict)
+
+
+def all_findings_carry_severity_and_verdict(
+    all_findings: Sequence[Mapping[str, object]],
+) -> bool:
+    """Return whether every finding carries severity and a retained verdict.
+
+    ::
+
+        all_findings_carry_severity_and_verdict([])  # ok: True
+        all_findings_carry_severity_and_verdict(
+            [{"severity": "nit", "verdict": "CONFIRMED"}]
+        )  # ok: True
+
+    Args:
+        all_findings: Structured findings retained after verification.
+
+    Returns:
+        True when every finding passes ``finding_carries_severity_and_verdict``.
+    """
+    for each_finding in all_findings:
+        if not finding_carries_severity_and_verdict(
+            severity=each_finding.get(FINDING_FIELD_SEVERITY),
+            verdict=each_finding.get(FINDING_FIELD_VERDICT),
+        ):
+            return False
+    return True
+
+
+def has_unclassified_finding(all_findings: Sequence[Mapping[str, object]]) -> bool:
+    """Return whether any finding lacks a known severity token.
+
+    ::
+
+        has_unclassified_finding([{"verdict": "CONFIRMED"}])  # ok: True
+        has_unclassified_finding(
+            [{"severity": "nit", "verdict": "CONFIRMED"}]
+        )  # flag: False
+
+    Args:
+        all_findings: Structured findings under terminal evaluation.
+
+    Returns:
+        True when any finding omits severity or uses an unknown token.
+    """
+    for each_finding in all_findings:
+        severity = each_finding.get(FINDING_FIELD_SEVERITY)
+        if not isinstance(severity, str):
+            return True
+        if not is_known_finding_severity(severity):
+            return True
+    return False
+
+
+def has_non_nit_finding(all_findings: Sequence[Mapping[str, object]]) -> bool:
+    """Return whether any finding carries a known non-nit severity.
+
+    ::
+
+        has_non_nit_finding([{"severity": "high"}])  # ok: True
+        has_non_nit_finding([{"severity": "nit"}])   # flag: False
+
+    Args:
+        all_findings: Structured findings under terminal evaluation.
+
+    Returns:
+        True when any finding's severity is known and not ``nit``.
+    """
+    for each_finding in all_findings:
+        severity = each_finding.get(FINDING_FIELD_SEVERITY)
+        if not isinstance(severity, str):
+            continue
+        if not is_known_finding_severity(severity):
+            continue
+        if not is_nit_finding_severity(severity):
+            return True
+    return False
+
+
+def is_nits_only_findings(all_findings: Sequence[Mapping[str, object]]) -> bool:
+    """Return whether every finding is a classified nit and at least one exists.
+
+    ::
+
+        is_nits_only_findings([{"severity": "nit"}])  # ok: True
+        is_nits_only_findings([])                      # flag: False
+        is_nits_only_findings(
+            [{"severity": "nit"}, {"severity": "high"}]
+        )  # flag: False
+
+    An empty list is clean, not nits-only. Unclassified findings fail the
+    nits-only check so they route to classification before a terminal.
+
+    Args:
+        all_findings: Structured findings under terminal evaluation.
+
+    Returns:
+        True when the list is non-empty, fully classified, and all nits.
+    """
+    if not all_findings:
+        return False
+    if has_unclassified_finding(all_findings):
+        return False
+    return not has_non_nit_finding(all_findings)
+
+
+def record_reviewed_head(
+    all_reviewed_head_shas: tuple[str, ...],
+    head_sha: str,
+) -> tuple[str, ...]:
+    """Append ``head_sha`` once when it is a new distinct head.
+
+    ::
+
+        record_reviewed_head((), "aaa")           # ok: ("aaa",)
+        record_reviewed_head(("aaa",), "aaa")     # ok: ("aaa",)  re-review
+        record_reviewed_head(("a", "b", "c"), "d")  # ok: ("a", "b", "c", "d")
+
+    A re-review of the same head does not increment the count. There is no
+    head count limit — every new head is recorded.
+
+    Args:
+        all_reviewed_head_shas: Ordered distinct heads already reviewed.
+        head_sha: Git head under review for this pass.
+
+    Returns:
+        The prior tuple, or the prior tuple plus ``head_sha`` when new.
+    """
+    if head_sha in all_reviewed_head_shas:
+        return all_reviewed_head_shas
+    return all_reviewed_head_shas + (head_sha,)
+
+
+def resolve_review_loop_terminal(
+    *,
+    all_findings: Sequence[Mapping[str, object]],
+    reviewed_head_count: int,
+    is_gates_passed: bool,
+    is_nits_applied: bool,
+    is_advisor_unreachable: bool = False,
+) -> str | None:
+    """Resolve the review-loop terminal, or None when the loop continues.
+
+    ::
+
+        resolve_review_loop_terminal(
+            all_findings=(), reviewed_head_count=1,
+            is_gates_passed=True, is_nits_applied=False,
+        )  # ok: "clean"
+        resolve_review_loop_terminal(
+            all_findings=(), reviewed_head_count=1,
+            is_gates_passed=False, is_nits_applied=False,
+        )  # flag: None  (gates still open)
+        resolve_review_loop_terminal(
+            all_findings=[{"severity": "high", "verdict": "CONFIRMED"}],
+            reviewed_head_count=5, is_gates_passed=True, is_nits_applied=False,
+        )  # flag: None  (open non-nit work continues)
+
+    Empty findings return clean only when gates pass. Nits-only findings
+    return nits_fixed after each finding carries severity and a retained
+    verdict, the nits are applied, and gates pass. An unreachable advisor
+    needed for classification returns advisor_blocked. Open non-nit work
+    returns None so the caller re-enters. There is no head-count stop.
+
+    Args:
+        all_findings: Structured findings retained for this head.
+        reviewed_head_count: Distinct heads reviewed so far, including this one.
+        is_gates_passed: Whether required checks passed for this decision.
+        is_nits_applied: Whether every nit on the target was fixed.
+        is_advisor_unreachable: Whether classification needs a missing advisor.
+
+    Returns:
+        One of ``ALL_LOOP_TERMINALS``, or None when the loop continues.
+    """
+    _ = reviewed_head_count
+    if is_advisor_unreachable and has_unclassified_finding(all_findings):
+        return TERMINAL_ADVISOR_BLOCKED
+    if not all_findings:
+        if is_gates_passed:
+            return TERMINAL_CLEAN
+        return None
+    if (
+        is_nits_only_findings(all_findings)
+        and all_findings_carry_severity_and_verdict(all_findings)
+        and is_nits_applied
+        and is_gates_passed
+    ):
+        return TERMINAL_NITS_FIXED
+    return None
+
+
+def encode_review_loop_terminal_result(
+    *,
+    terminal: str,
+    all_surviving_findings: Sequence[Mapping[str, object]],
+    reviewed_head_count: int,
+    is_draft_preserved: bool,
+) -> dict[str, object]:
+    """Serialize a review-loop terminal for hand-off and reporting.
+
+    ::
+
+        encode_review_loop_terminal_result(
+            terminal="advisor_blocked",
+            all_surviving_findings=[{"severity": "high", "verdict": "CONFIRMED"}],
+            reviewed_head_count=2,
+            is_draft_preserved=False,
+        )["draft_preserved"]  # ok: True  (blocked terminals force draft)
+
+    ``advisor_blocked`` keeps the pull request draft even when the caller
+    passes a false draft flag. Other terminals use the caller's flag.
+    Every terminal uses the same JSON shape.
+
+    Args:
+        terminal: One of ``ALL_LOOP_TERMINALS``.
+        all_surviving_findings: Findings still open at the terminal.
+        reviewed_head_count: Distinct heads reviewed before this terminal.
+        is_draft_preserved: Whether the pull request stays in draft.
+
+    Returns:
+        A JSON-ready mapping with terminal, draft flag, head count, findings.
+    """
+    is_blocked_terminal = terminal == TERMINAL_ADVISOR_BLOCKED
+    should_preserve_draft = is_blocked_terminal or is_draft_preserved
+    return {
+        RESULT_KEY_TERMINAL: terminal,
+        RESULT_KEY_DRAFT_PRESERVED: should_preserve_draft,
+        RESULT_KEY_REVIEWED_HEAD_COUNT: reviewed_head_count,
+        RESULT_KEY_SURVIVING_FINDINGS: list(all_surviving_findings),
+    }

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -203,9 +203,6 @@ CLASSIFICATION_STREAM_JOIN_SEPARATOR: str = "\n"
 DEFAULT_WORKER_TIMEOUT_SECONDS: int = 600
 """Default timeout applied to one headless worker invocation, in seconds."""
 
-DEFAULT_WORKER_MAX_TURNS: int = 8
-"""Default max-turns value applied to one headless worker invocation."""
-
 TIMEOUT_RETURN_CODE: int = -1
 """Return code recorded on the outcome when a timed-out process leaves no return code."""
 
@@ -216,13 +213,66 @@ LAUNCH_FAILURE_STDERR_PREFIX: str = "failed to launch: "
 """Prefix for the non-empty stderr diagnostic returned on a launch OSError."""
 
 KILL_GRACE_TIMEOUT_SECONDS: int = 10
-"""Seconds to wait for a killed process to reap its pipes before giving up on its streams."""
+"""Seconds to wait for a killed process to reap its pipes before giving up on its streams.
+
+Gates the drain that follows a kill. The shared process-tree helper carries its
+own bound on the kill command, so the two bound different operations.
+"""
+
+MAXIMUM_WORKER_TIMEOUT_SECONDS: int = 5400
+"""Ceiling the batch launcher puts on a worker's ``timeout_seconds`` (90 minutes).
+
+Enforced at three sites: the batch launcher refuses an over-ceiling
+specification while parsing it, ``run_headless_worker`` refuses one from any
+caller, and ``resolve_worker_spawn`` refuses one before its preflight so the
+bound holds on every tier. A worker that reaches this ceiling is killed and
+classified ``CLASSIFICATION_TIMEOUT``.
+"""
+
+MAXIMUM_WORKER_TIMEOUT_ERROR_TEMPLATE: str = (
+    "worker {field_name} {requested_seconds} exceeds "
+    "MAXIMUM_WORKER_TIMEOUT_SECONDS ({maximum_seconds})"
+)
+"""Rejection message for an over-ceiling timeout, shared by the batch parse and the runner."""
 
 MIN_WORKER_TIMEOUT_SECONDS: int = 1
-"""Minimum accepted worker timeout_seconds in a batch specification."""
+"""Minimum accepted worker timeout_seconds, in seconds.
+
+Enforced at the same three sites as ``MAXIMUM_WORKER_TIMEOUT_SECONDS``.
+"""
+
+MINIMUM_WORKER_TIMEOUT_ERROR_TEMPLATE: str = (
+    "worker {field_name} {requested_seconds} is below "
+    "MIN_WORKER_TIMEOUT_SECONDS ({minimum_seconds})"
+)
+"""Rejection message for a below-floor timeout, shared by the batch parse and the runner."""
+
+CLASSIFICATION_KILL_FAILED: str = "kill_failed"
+"""Outcome classification when a timed-out worker's streams never drain.
+
+Distinct from ``CLASSIFICATION_TIMEOUT``: that worker's tree was cleared, this
+one's was not, so a caller can tell an abandoned process tree from a stopped
+one.
+"""
 
-MIN_WORKER_MAX_TURNS: int = 1
-"""Minimum accepted worker max_turns in a batch specification."""
+KILL_FAILED_RETURN_CODE: int = -4
+"""Return code recorded when a timed-out worker's streams never drain."""
+
+KILL_FAILED_STDERR_TEMPLATE: str = (
+    "worker timed out and its streams never drained across {attempt_count} "
+    "kill-and-drain attempts; process {process_identifier} may still be running"
+)
+"""Stderr diagnostic naming the surviving process id after every attempt fails."""
+
+PROCESS_TREE_KILL_ATTEMPT_LIMIT: int = 2
+"""Kill-and-drain rounds run on a timed-out worker before the kill is reported failed.
+
+Each round issues the tree kill while the worker process is still alive, then
+waits ``KILL_GRACE_TIMEOUT_SECONDS`` for the streams to drain.
+"""
+
+REASON_TIMEOUT_OUT_OF_BOUNDS: str = "timeout_out_of_bounds"
+"""Dispatcher attempt reason when the requested timeout is below the floor or above the ceiling."""
 
 WORKER_EXCEPTION_RETURN_CODE: int = -3
 """Return code recorded on a WorkerReport when the worker body raises before a process runs.
@@ -321,12 +371,35 @@ WORKER_SPEC_TIMEOUT_KEY: str = "timeout_seconds"
 WORKER_SPEC_IS_REPO_ONLY_KEY: str = "is_repo_only"
 """JSON key for whether a readonly worker also disables web search."""
 
-WORKER_SPEC_MAX_TURNS_KEY: str = "max_turns"
-"""JSON key for one worker's max-turns cap."""
-
 WORKER_SPEC_AGENT_NAME_KEY: str = "agent_name"
 """JSON key for one worker's optional agent definition name."""
 
+ALL_KNOWN_WORKER_SPEC_KEYS: frozenset[str] = frozenset(
+    {
+        WORKER_SPEC_ROLE_NAME_KEY,
+        WORKER_SPEC_PROMPT_PARTS_KEY,
+        WORKER_SPEC_CWD_KEY,
+        WORKER_SPEC_TOOL_PROFILE_KEY,
+        WORKER_SPEC_TIMEOUT_KEY,
+        WORKER_SPEC_IS_REPO_ONLY_KEY,
+        WORKER_SPEC_AGENT_NAME_KEY,
+    }
+)
+"""Every JSON key a batch worker entry accepts.
+
+A worker entry carrying any other key fails to load, so a key the launcher
+would drop is named to the operator rather than passing for a setting that
+took effect.
+"""
+
+WORKER_SPEC_KEY_JOIN_SEPARATOR: str = ", "
+"""Separator between key names listed in an unknown-worker-key error message."""
+
+UNKNOWN_WORKER_KEY_ERROR_TEMPLATE: str = (
+    "unknown worker key(s): {unknown_keys}; accepted keys: {accepted_keys}"
+)
+"""Message raised when a worker entry carries a key outside the accepted set."""
+
 CLI_BATCH_SPEC_FLAG: str = "--spec"
 """CLI flag that points the batch launcher at a JSON batch specification file."""
 
@@ -389,9 +462,6 @@ REASON_CLAUDE_AGENT_REQUIRED: str = "claude_agent_required"
 REASON_PROMPT_FILE_MISSING: str = "prompt_file_missing"
 """Config reason when the dispatcher CLI prompt file path is absent or unreadable."""
 
-DEFAULT_SPAWN_MAX_TURNS: int = 8
-"""Default max-turns applied to the headless grok worker when the caller names none."""
-
 SPAWN_SERVED_EXIT_CODE: int = 0
 """CLI exit code when a dispatcher tier served the call."""