claude-dev-env 2.8.0 → 2.10.0

package/skills/e-code-review/scripts/finding_pipeline.py

@@ -0,0 +1,140 @@
+"""Collect every real review finding; filter severity only later.
+
+::
+
+    collection = collect_findings(all_seeded)
+        ok: low and nit findings remain in the collection record
+    filtered = filter_findings_by_severity(collection, minimum_severity="medium")
+        ok: consumer stage drops lower severities; collection is unchanged
+
+Collection never drops a real finding by severity. A later consumer stage
+reads the complete collection and may filter for action or display.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from e_code_review_scripts_constants.finding_pipeline_constants import (
+    ALL_COLLECTION_SEVERITIES,
+    COLLECTION_STAGE_NAME,
+    FILTER_STAGE_NAME,
+    FINDING_FIELD_CATEGORY,
+    FINDING_FIELD_EVIDENCE,
+    FINDING_FIELD_FILE,
+    FINDING_FIELD_LINE,
+    FINDING_FIELD_SEVERITY,
+    ALL_SEVERITY_RANK_BY_TOKEN,
+)
+
+
+@dataclass(frozen=True)
+class CollectedFinding:
+    """One real finding retained during the collection stage."""
+
+    file_path: str
+    line_number: int
+    severity: str
+    category: str
+    evidence: str
+
+    def as_mapping(self) -> dict[str, str | int]:
+        """Return the stable field map every retained finding keeps.
+
+        Returns:
+            Mapping with file, line, severity, category, and evidence.
+        """
+        return {
+            FINDING_FIELD_FILE: self.file_path,
+            FINDING_FIELD_LINE: self.line_number,
+            FINDING_FIELD_SEVERITY: self.severity,
+            FINDING_FIELD_CATEGORY: self.category,
+            FINDING_FIELD_EVIDENCE: self.evidence,
+        }
+
+
+@dataclass(frozen=True)
+class FindingCollection:
+    """Unfiltered collection record of every real finding."""
+
+    stage_name: str
+    all_findings: tuple[CollectedFinding, ...]
+
+
+@dataclass(frozen=True)
+class SeverityFilterView:
+    """Severity-filtered view produced by a separate consumer stage."""
+
+    stage_name: str
+    minimum_severity: str
+    all_findings: tuple[CollectedFinding, ...]
+
+
+def collect_findings(
+    all_findings: list[CollectedFinding] | tuple[CollectedFinding, ...],
+) -> FindingCollection:
+    """Retain every real finding with its file, line, evidence, and category.
+
+    Args:
+        all_findings: Seeded real findings of any legal severity.
+
+    Returns:
+        Collection stage record holding every input finding.
+
+    Raises:
+        ValueError: When a finding lacks a required field or legal severity.
+    """
+    all_retained: list[CollectedFinding] = []
+    for each_finding in all_findings:
+        if not each_finding.file_path:
+            raise ValueError("finding requires a non-empty file path")
+        if each_finding.line_number < 1:
+            raise ValueError("finding requires a positive line number")
+        if not each_finding.category:
+            raise ValueError("finding requires a non-empty category")
+        if not each_finding.evidence:
+            raise ValueError("finding requires non-empty evidence")
+        if each_finding.severity not in ALL_COLLECTION_SEVERITIES:
+            raise ValueError(
+                f"unknown collection severity: {each_finding.severity!r}"
+            )
+        all_retained.append(each_finding)
+    return FindingCollection(
+        stage_name=COLLECTION_STAGE_NAME,
+        all_findings=tuple(all_retained),
+    )
+
+
+def filter_findings_by_severity(
+    collection: FindingCollection,
+    *,
+    minimum_severity: str,
+) -> SeverityFilterView:
+    """Filter a complete collection by severity in a separate consumer stage.
+
+    Args:
+        collection: Unfiltered collection record from ``collect_findings``.
+        minimum_severity: Lowest severity to keep (inclusive).
+
+    Returns:
+        Filter-stage view. The input collection record is not mutated.
+
+    Raises:
+        ValueError: When ``minimum_severity`` or a finding severity is unknown.
+    """
+    if minimum_severity not in ALL_SEVERITY_RANK_BY_TOKEN:
+        raise ValueError(f"unknown minimum severity: {minimum_severity!r}")
+    minimum_rank = ALL_SEVERITY_RANK_BY_TOKEN[minimum_severity]
+    all_kept: list[CollectedFinding] = []
+    for each_finding in collection.all_findings:
+        if each_finding.severity not in ALL_SEVERITY_RANK_BY_TOKEN:
+            raise ValueError(
+                f"unknown collection severity: {each_finding.severity!r}"
+            )
+        if ALL_SEVERITY_RANK_BY_TOKEN[each_finding.severity] >= minimum_rank:
+            all_kept.append(each_finding)
+    return SeverityFilterView(
+        stage_name=FILTER_STAGE_NAME,
+        minimum_severity=minimum_severity,
+        all_findings=tuple(all_kept),
+    )

package/skills/e-code-review/scripts/fixtures/demanding.json

@@ -0,0 +1,26 @@
+{
+  "fixture_id": "demanding-multi-surface",
+  "band": "demanding",
+  "description": "Cross-file review with three seeded findings across hooks and tests.",
+  "target_summary": "Hook change drifts docstring, drops a paired test path, and uses a banned identifier.",
+  "seeded_findings": [
+    {
+      "file": "hooks/blocking/sample_gate.py",
+      "line": 88,
+      "category": "docstring-vs-impl",
+      "severity": "high"
+    },
+    {
+      "file": "hooks/blocking/test_sample_gate.py",
+      "line": 1,
+      "category": "paired-test-coverage",
+      "severity": "blocker"
+    },
+    {
+      "file": "hooks/blocking/sample_gate.py",
+      "line": 15,
+      "category": "banned-identifier",
+      "severity": "medium"
+    }
+  ]
+}

package/skills/e-code-review/scripts/fixtures/easy.json

@@ -0,0 +1,14 @@
+{
+  "fixture_id": "easy-comment-preservation",
+  "band": "easy",
+  "description": "Single-file comment-preservation miss with one seeded finding.",
+  "target_summary": "Production helper drops an existing inline comment on an unchanged line.",
+  "seeded_findings": [
+    {
+      "file": "sample_helper.py",
+      "line": 12,
+      "category": "comment-preservation",
+      "severity": "medium"
+    }
+  ]
+}

package/skills/e-code-review/scripts/fixtures/medium.json

@@ -0,0 +1,20 @@
+{
+  "fixture_id": "medium-constants-and-types",
+  "band": "medium",
+  "description": "Two seeded findings: bare type-ignore and a magic timeout literal.",
+  "target_summary": "Service module adds a bare type ignore and a hard-coded timeout.",
+  "seeded_findings": [
+    {
+      "file": "order_service.py",
+      "line": 24,
+      "category": "type-ignore-justification",
+      "severity": "high"
+    },
+    {
+      "file": "order_service.py",
+      "line": 41,
+      "category": "magic-value",
+      "severity": "medium"
+    }
+  ]
+}

package/skills/e-code-review/scripts/grok_code_review.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""Grok medium-review discovery and verification orchestration.
+
+Dispatches exactly eight named finder angles at one target head, binds each
+finder to an isolated identity (worktree path, leader socket, advisor session),
+deduplicates candidates, verifies them, and retains CONFIRMED plus unresolved
+PLAUSIBLE findings with severity. Head drift rejects the whole batch.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from e_code_review_scripts_constants.grok_code_review_constants import (
+    ALL_MEDIUM_FINDER_ANGLES,
+    ALL_SEVERITIES,
+    ALL_VERIFICATION_VERDICTS,
+    MEDIUM_REVIEW_FINDER_COUNT,
+    MEDIUM_REVIEW_SCHEMA_VERSION,
+    VERDICT_CONFIRMED,
+    VERDICT_PLAUSIBLE,
+    VERDICT_REFUTED,
+)
+
+
+@dataclass(frozen=True)
+class FinderCandidate:
+    """One candidate finding from a discovery angle."""
+
+    angle: str
+    file_path: str
+    line_number: int
+    mechanism: str
+    scenario: str
+    worktree_path: str
+    leader_socket: str
+    advisor_session_id: str
+    reviewed_head: str
+
+
+@dataclass(frozen=True)
+class VerifiedFinding:
+    """A retained finding after verification."""
+
+    file_path: str
+    line_number: int
+    mechanism: str
+    scenario: str
+    verdict: str
+    severity: str
+    reviewed_head: str
+
+
+@dataclass
+class MediumReviewBatch:
+    """Result of one medium-review run at a single head."""
+
+    schema_version: str = MEDIUM_REVIEW_SCHEMA_VERSION
+    target_head: str = ""
+    diff_base: str = ""
+    all_finder_angles: tuple[str, ...] = ALL_MEDIUM_FINDER_ANGLES
+    all_retained_findings: list[VerifiedFinding] = field(default_factory=list)
+    is_rejected: bool = False
+    rejection_reason: str | None = None
+
+
+def require_exact_finder_set(all_angles: tuple[str, ...] | list[str]) -> None:
+    """Require exactly the eight named finder angles.
+
+    Args:
+        all_angles: Angle names present in a run.
+
+    Raises:
+        ValueError: When the set is not exactly the eight angles.
+    """
+    angle_set = set(all_angles)
+    expected = set(ALL_MEDIUM_FINDER_ANGLES)
+    if angle_set != expected or len(all_angles) != MEDIUM_REVIEW_FINDER_COUNT:
+        raise ValueError(
+            f"finder angles must be exactly {MEDIUM_REVIEW_FINDER_COUNT}: "
+            f"got {sorted(angle_set)}"
+        )
+
+
+def deduplicate_candidates(
+    all_candidates: list[FinderCandidate],
+) -> list[FinderCandidate]:
+    """Keep the most concrete scenario per file/line/mechanism.
+
+    Args:
+        all_candidates: Raw finder outputs.
+
+    Returns:
+        Deduplicated candidates preserving the longest scenario text.
+    """
+    best_by_key: dict[tuple[str, int, str], FinderCandidate] = {}
+    for each_candidate in all_candidates:
+        key = (
+            each_candidate.file_path,
+            each_candidate.line_number,
+            each_candidate.mechanism,
+        )
+        existing = best_by_key.get(key)
+        if existing is None or len(each_candidate.scenario) > len(existing.scenario):
+            best_by_key[key] = each_candidate
+    return list(best_by_key.values())
+
+
+def retain_verified_findings(
+    *,
+    all_candidates: list[FinderCandidate],
+    verdict_by_key: dict[tuple[str, int, str], str],
+    severity_by_key: dict[tuple[str, int, str], str],
+) -> list[VerifiedFinding]:
+    """Retain CONFIRMED and unresolved PLAUSIBLE findings with severity.
+
+    Args:
+        all_candidates: Deduplicated candidates.
+        verdict_by_key: Verification verdict per file/line/mechanism.
+        severity_by_key: Severity per file/line/mechanism.
+
+    Returns:
+        Retained findings.
+
+    Raises:
+        ValueError: When a retained finding lacks a legal severity or verdict.
+    """
+    all_retained: list[VerifiedFinding] = []
+    for each_candidate in all_candidates:
+        key = (
+            each_candidate.file_path,
+            each_candidate.line_number,
+            each_candidate.mechanism,
+        )
+        verdict = verdict_by_key.get(key)
+        if verdict not in ALL_VERIFICATION_VERDICTS:
+            raise ValueError(f"missing or illegal verdict for {key}")
+        if verdict == VERDICT_REFUTED:
+            continue
+        if verdict not in {VERDICT_CONFIRMED, VERDICT_PLAUSIBLE}:
+            continue
+        severity = severity_by_key.get(key)
+        if severity not in ALL_SEVERITIES:
+            raise ValueError(f"missing or illegal severity for {key}")
+        all_retained.append(
+            VerifiedFinding(
+                file_path=each_candidate.file_path,
+                line_number=each_candidate.line_number,
+                mechanism=each_candidate.mechanism,
+                scenario=each_candidate.scenario,
+                verdict=verdict,
+                severity=severity,
+                reviewed_head=each_candidate.reviewed_head,
+            )
+        )
+    return all_retained
+
+
+def run_medium_review(
+    *,
+    target_head: str,
+    diff_base: str,
+    all_finder_candidates: list[FinderCandidate],
+    verdict_by_key: dict[tuple[str, int, str], str],
+    severity_by_key: dict[tuple[str, int, str], str],
+    live_head: str,
+    is_any_advisor_blocked: bool = False,
+) -> MediumReviewBatch:
+    """Run discovery and verification for one medium-review head.
+
+    Args:
+        target_head: Reviewed head OID.
+        diff_base: Diff base OID.
+        all_finder_candidates: Outputs from the eight finder angles.
+        verdict_by_key: Verification results keyed by file/line/mechanism.
+        severity_by_key: Severities for retained findings.
+        live_head: Live head OID; must match target_head.
+        is_any_advisor_blocked: True when any finder ended advisor_blocked.
+
+    Raises:
+        ValueError: When finder angles are incomplete or duplicated.
+
+    Returns:
+        The medium-review batch (possibly rejected).
+    """
+    batch = MediumReviewBatch(target_head=target_head, diff_base=diff_base)
+    if is_any_advisor_blocked:
+        batch.is_rejected = True
+        batch.rejection_reason = "advisor_blocked"
+        return batch
+    if live_head != target_head:
+        batch.is_rejected = True
+        batch.rejection_reason = "head_drift"
+        return batch
+    for each_candidate in all_finder_candidates:
+        if each_candidate.reviewed_head != target_head:
+            batch.is_rejected = True
+            batch.rejection_reason = "finder_head_mismatch"
+            return batch
+    all_angles = sorted({each.angle for each in all_finder_candidates})
+    finder_count = len(all_angles)
+    all_identities = {
+        (
+            each.angle,
+            each.leader_socket,
+            each.advisor_session_id,
+            each.worktree_path,
+        )
+        for each in all_finder_candidates
+    }
+    all_sockets = {each.leader_socket for each in all_finder_candidates}
+    all_sessions = {each.advisor_session_id for each in all_finder_candidates}
+    all_worktrees = {each.worktree_path for each in all_finder_candidates}
+    if (
+        len(all_identities) != finder_count
+        or len(all_sockets) != finder_count
+        or len(all_sessions) != finder_count
+        or len(all_worktrees) != finder_count
+    ):
+        batch.is_rejected = True
+        batch.rejection_reason = "non_unique_finder_identity"
+        return batch
+    require_exact_finder_set(tuple(all_angles))
+    deduped = deduplicate_candidates(all_finder_candidates)
+    batch.all_retained_findings = retain_verified_findings(
+        all_candidates=deduped,
+        verdict_by_key=verdict_by_key,
+        severity_by_key=severity_by_key,
+    )
+    return batch

package/skills/e-code-review/scripts/test_effort_evaluation.py

@@ -0,0 +1,180 @@
+"""Behavior tests for the effort evaluation harness."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+_CONSTANTS_PARENT = _SCRIPTS_DIRECTORY / "config"
+for each_path in (_SCRIPTS_DIRECTORY, _CONSTANTS_PARENT):
+    path_text = str(each_path)
+    if path_text not in sys.path:
+        sys.path.insert(0, path_text)
+
+from e_code_review_effort_constants import (  # noqa: E402
+    ALL_EFFORT_LEVELS,
+    ALL_FIXTURE_BANDS,
+    ALL_SKILL_EFFORT_LEVELS,
+    MINIMUM_QUALITY_HOLD_SCORE,
+    THINKING_ENABLED_DEFAULT,
+    WORKFLOW_FAMILY_E_CODE_REVIEW,
+)
+from effort_evaluation import (  # noqa: E402
+    build_synthetic_row,
+    evaluation_evidence_path,
+    fixtures_directory,
+    load_evaluation_evidence,
+    load_fixtures,
+    map_evaluation_effort_to_skill_level,
+    quality_holds,
+    recommend_effort_by_band,
+    resolve_skill_effort_for_band,
+    skill_defaults_from_recommendation,
+    validate_evaluation_row,
+)
+
+
+def test_fixtures_directory_points_at_frozen_json() -> None:
+    directory = fixtures_directory()
+    assert directory.is_dir()
+    assert directory.name == "fixtures"
+    assert (directory / "easy.json").is_file()
+
+
+def test_loads_three_frozen_fixture_bands() -> None:
+    all_fixtures = load_fixtures()
+    assert len(all_fixtures) == len(ALL_FIXTURE_BANDS)
+    bands = {str(each_fixture["band"]) for each_fixture in all_fixtures}
+    assert bands == set(ALL_FIXTURE_BANDS)
+    for each_fixture in all_fixtures:
+        assert each_fixture["fixture_id"]
+        assert isinstance(each_fixture["seeded_findings"], list)
+        assert len(each_fixture["seeded_findings"]) >= 1
+
+
+def test_validate_row_accepts_complete_row_and_rejects_thinking_off() -> None:
+    good_row = build_synthetic_row(
+        fixture_id="easy-comment-preservation",
+        fixture_band="easy",
+        effort="low",
+        quality_score=0.9,
+        finding_recall=1.0,
+        finding_precision=1.0,
+        visible_tokens=1200,
+        latency_ms=4000,
+    )
+    assert validate_evaluation_row(good_row) == []
+    assert good_row["thinking_enabled"] is THINKING_ENABLED_DEFAULT
+    bad_row = dict(good_row)
+    bad_row["thinking_enabled"] = False
+    problems = validate_evaluation_row(bad_row)
+    assert any("thinking_enabled" in each_problem for each_problem in problems)
+    bool_score_row = dict(good_row)
+    bool_score_row["quality_score"] = True
+    bool_problems = validate_evaluation_row(bool_score_row)
+    assert any("quality_score" in each_problem for each_problem in bool_problems)
+
+
+def test_recommend_picks_lowest_effort_that_holds_quality() -> None:
+    all_rows = [
+        build_synthetic_row("easy-a", "easy", "low", 0.5, 0.5, 0.5, 100, 1000),
+        build_synthetic_row("easy-a", "easy", "medium", 0.95, 0.95, 0.95, 200, 2000),
+        build_synthetic_row("easy-a", "easy", "xhigh", 0.99, 0.99, 0.99, 400, 5000),
+        build_synthetic_row("medium-a", "medium", "high", 0.9, 0.9, 0.9, 300, 3000),
+        build_synthetic_row(
+            "demanding-a", "demanding", "max", 0.85, 0.85, 0.85, 800, 9000
+        ),
+    ]
+    for each_row in all_rows:
+        assert validate_evaluation_row(each_row) == []
+    recommendation = recommend_effort_by_band(all_rows)
+    by_band = recommendation["recommendation_by_band"]
+    assert isinstance(by_band, dict)
+    assert by_band["easy"]["recommended_effort"] == "medium"
+    assert by_band["easy"]["cited_row"]["effort"] == "medium"
+    assert by_band["medium"]["recommended_effort"] == "high"
+    assert by_band["demanding"]["recommended_effort"] == "max"
+    assert recommendation["thinking_enabled"] is True
+    assert recommendation["cost_latency_lever"] == "effort"
+    assert recommendation["defaults_unchanged"] is True
+
+
+def test_recommend_blocks_band_without_holding_row() -> None:
+    all_rows = [
+        build_synthetic_row("easy-a", "easy", "low", 0.1, 0.1, 0.1, 50, 500),
+    ]
+    recommendation = recommend_effort_by_band(all_rows)
+    easy = recommendation["recommendation_by_band"]["easy"]
+    assert easy["recommended_effort"] is None
+    assert easy["cited_row"] is None
+    assert "quality floor" in str(easy["blocker"])
+
+
+def test_quality_holds_uses_named_floor() -> None:
+    holding = build_synthetic_row(
+        "x", "easy", "low", MINIMUM_QUALITY_HOLD_SCORE, 1.0, 1.0, 1, 1
+    )
+    failing = build_synthetic_row(
+        "x", "easy", "low", MINIMUM_QUALITY_HOLD_SCORE - 0.01, 1.0, 1.0, 1, 1
+    )
+    assert quality_holds(holding) is True
+    assert quality_holds(failing) is False
+
+
+def test_effort_levels_cover_cli_set() -> None:
+    assert "low" in ALL_EFFORT_LEVELS
+    assert "max" in ALL_EFFORT_LEVELS
+    assert len(ALL_EFFORT_LEVELS) == 5
+
+
+def test_evidence_rows_validate_and_skill_defaults_cite_rows() -> None:
+    evidence_path = evaluation_evidence_path()
+    assert evidence_path.is_file()
+    assert evidence_path.name == "effort_defaults_evidence.json"
+    evidence = load_evaluation_evidence()
+    assert evidence["workflow_family"] == WORKFLOW_FAMILY_E_CODE_REVIEW
+    assert evidence["thinking_enabled"] is True
+    all_rows = evidence["all_rows"]
+    assert isinstance(all_rows, list)
+    for each_row in all_rows:
+        assert isinstance(each_row, dict)
+        assert validate_evaluation_row(each_row) == []
+    recommendation = recommend_effort_by_band(all_rows)
+    skill_defaults = skill_defaults_from_recommendation(recommendation)
+    assert skill_defaults["workflow_family"] == WORKFLOW_FAMILY_E_CODE_REVIEW
+    default_by_band = skill_defaults["default_by_band"]
+    assert isinstance(default_by_band, dict)
+    for each_band in ALL_FIXTURE_BANDS:
+        band_default = default_by_band[each_band]
+        assert band_default["skill_effort"] in ALL_SKILL_EFFORT_LEVELS
+        assert band_default["cited_row"] is not None
+        assert band_default["cited_row"]["thinking_enabled"] is True
+
+
+def test_committed_skill_defaults_match_resolver() -> None:
+    assert resolve_skill_effort_for_band("easy") == "medium"
+    assert resolve_skill_effort_for_band("medium") == "xhigh"
+    assert resolve_skill_effort_for_band("demanding") == "xhigh"
+    evidence = load_evaluation_evidence()
+    committed = evidence["skill_defaults"]["default_by_band"]
+    for each_band in ALL_FIXTURE_BANDS:
+        assert committed[each_band]["skill_effort"] == resolve_skill_effort_for_band(
+            each_band
+        )
+        assert committed[each_band]["cited_row"]["effort"] is not None
+
+
+def test_map_high_and_max_to_skill_xhigh() -> None:
+    assert map_evaluation_effort_to_skill_level("high") == "xhigh"
+    assert map_evaluation_effort_to_skill_level("max") == "xhigh"
+    assert map_evaluation_effort_to_skill_level("medium") == "medium"
+
+
+def test_resolve_rejects_unknown_band() -> None:
+    try:
+        resolve_skill_effort_for_band("not-a-band")
+    except ValueError as error:
+        assert "unknown fixture band" in str(error)
+    else:
+        raise AssertionError("expected ValueError for unknown band")