claude-dev-env 2.7.1 → 2.9.0

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

@@ -0,0 +1,221 @@
+#!/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 = [each.angle 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_sockets) != len(all_finder_candidates)
+        or len(all_sessions) != len(all_finder_candidates)
+        or len(all_worktrees) != len(all_finder_candidates)
+    ):
+        batch.is_rejected = True
+        batch.rejection_reason = "non_unique_finder_identity"
+        return batch
+    require_exact_finder_set(tuple(sorted(set(all_angles))))
+    if len(set(all_angles)) != MEDIUM_REVIEW_FINDER_COUNT:
+        raise ValueError("each finder angle must run exactly once")
+    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_grok_code_review.py

@@ -0,0 +1,212 @@
+"""Behavioral tests for Grok medium-review discovery and verification."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS = Path(__file__).resolve().parent
+if str(_SCRIPTS) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS))
+
+from e_code_review_scripts_constants.grok_code_review_constants import (  # noqa: E402
+    ALL_MEDIUM_FINDER_ANGLES,
+    MEDIUM_REVIEW_FINDER_COUNT,
+    VERDICT_CONFIRMED,
+    VERDICT_PLAUSIBLE,
+    VERDICT_REFUTED,
+)
+from grok_code_review import (  # noqa: E402
+    FinderCandidate,
+    deduplicate_candidates,
+    require_exact_finder_set,
+    retain_verified_findings,
+    run_medium_review,
+)
+
+
+def _candidate(
+    angle: str,
+    *,
+    file_path: str = "a.py",
+    line_number: int = 1,
+    mechanism: str = "m",
+    scenario: str = "short",
+    suffix: str = "",
+    head: str = "head1",
+) -> FinderCandidate:
+    token = suffix or angle
+    return FinderCandidate(
+        angle=angle,
+        file_path=file_path,
+        line_number=line_number,
+        mechanism=mechanism,
+        scenario=scenario,
+        worktree_path=f"/wt/{token}",
+        leader_socket=f"sock-{token}",
+        advisor_session_id=f"adv-{token}",
+        reviewed_head=head,
+    )
+
+
+def test_require_exact_finder_set_accepts_all_angles() -> None:
+    require_exact_finder_set(ALL_MEDIUM_FINDER_ANGLES)
+    with pytest.raises(ValueError):
+        require_exact_finder_set(ALL_MEDIUM_FINDER_ANGLES[:-1])
+
+
+def test_deduplicate_keeps_most_concrete_scenario() -> None:
+    short = _candidate("correctness", scenario="short")
+    long = _candidate("security", scenario="much more concrete failure path")
+    # same key different angles - force same file/line/mech
+    short = FinderCandidate(
+        angle="correctness",
+        file_path="a.py",
+        line_number=3,
+        mechanism="null",
+        scenario="x",
+        worktree_path="/wt/a",
+        leader_socket="s1",
+        advisor_session_id="a1",
+        reviewed_head="h",
+    )
+    long = FinderCandidate(
+        angle="security",
+        file_path="a.py",
+        line_number=3,
+        mechanism="null",
+        scenario="concrete long scenario",
+        worktree_path="/wt/b",
+        leader_socket="s2",
+        advisor_session_id="a2",
+        reviewed_head="h",
+    )
+    kept = deduplicate_candidates([short, long])
+    assert len(kept) == 1
+    assert kept[0].scenario == "concrete long scenario"
+
+
+def test_run_medium_review_happy_path() -> None:
+    head = "abc123"
+    all_finders = [
+        _candidate(each_angle, head=head, suffix=each_angle)
+        for each_angle in ALL_MEDIUM_FINDER_ANGLES
+    ]
+    # make unique keys per angle
+    all_finders = [
+        FinderCandidate(
+            angle=each_angle,
+            file_path=f"{each_angle}.py",
+            line_number=1,
+            mechanism="m",
+            scenario=f"scenario {each_angle}",
+            worktree_path=f"/wt/{each_angle}",
+            leader_socket=f"sock-{each_angle}",
+            advisor_session_id=f"adv-{each_angle}",
+            reviewed_head=head,
+        )
+        for each_angle in ALL_MEDIUM_FINDER_ANGLES
+    ]
+    verdicts = {
+        (f"{each}.py", 1, "m"): VERDICT_CONFIRMED
+        for each in ALL_MEDIUM_FINDER_ANGLES
+    }
+    severities = {
+        (f"{each}.py", 1, "m"): "medium" for each in ALL_MEDIUM_FINDER_ANGLES
+    }
+    # refute one
+    first = ALL_MEDIUM_FINDER_ANGLES[0]
+    verdicts[(f"{first}.py", 1, "m")] = VERDICT_REFUTED
+    batch = run_medium_review(
+        target_head=head,
+        diff_base="base",
+        all_finder_candidates=all_finders,
+        verdict_by_key=verdicts,
+        severity_by_key=severities,
+        live_head=head,
+    )
+    assert batch.is_rejected is False
+    assert len(batch.all_finder_angles) == MEDIUM_REVIEW_FINDER_COUNT
+    assert all(each.reviewed_head == head for each in batch.all_retained_findings)
+    assert all(each.verdict in {VERDICT_CONFIRMED, VERDICT_PLAUSIBLE} for each in batch.all_retained_findings)
+    assert len(batch.all_retained_findings) == MEDIUM_REVIEW_FINDER_COUNT - 1
+
+
+def test_head_drift_rejects_batch() -> None:
+    head = "h1"
+    all_finders = [
+        FinderCandidate(
+            angle=each_angle,
+            file_path=f"{each_angle}.py",
+            line_number=1,
+            mechanism="m",
+            scenario="s",
+            worktree_path=f"/wt/{each_angle}",
+            leader_socket=f"sock-{each_angle}",
+            advisor_session_id=f"adv-{each_angle}",
+            reviewed_head=head,
+        )
+        for each_angle in ALL_MEDIUM_FINDER_ANGLES
+    ]
+    batch = run_medium_review(
+        target_head=head,
+        diff_base="b",
+        all_finder_candidates=all_finders,
+        verdict_by_key={},
+        severity_by_key={},
+        live_head="other",
+    )
+    assert batch.is_rejected is True
+    assert batch.rejection_reason == "head_drift"
+
+
+def test_advisor_blocked_rejects_batch() -> None:
+    head = "h1"
+    all_finders = [
+        FinderCandidate(
+            angle=each_angle,
+            file_path=f"{each_angle}.py",
+            line_number=1,
+            mechanism="m",
+            scenario="s",
+            worktree_path=f"/wt/{each_angle}",
+            leader_socket=f"sock-{each_angle}",
+            advisor_session_id=f"adv-{each_angle}",
+            reviewed_head=head,
+        )
+        for each_angle in ALL_MEDIUM_FINDER_ANGLES
+    ]
+    batch = run_medium_review(
+        target_head=head,
+        diff_base="b",
+        all_finder_candidates=all_finders,
+        verdict_by_key={},
+        severity_by_key={},
+        live_head=head,
+        is_any_advisor_blocked=True,
+    )
+    assert batch.is_rejected is True
+    assert batch.rejection_reason == "advisor_blocked"
+
+
+def test_retain_verified_findings_keeps_confirmed() -> None:
+    candidate = FinderCandidate(
+        angle="correctness",
+        file_path="a.py",
+        line_number=2,
+        mechanism="null",
+        scenario="boom",
+        worktree_path="/wt/x",
+        leader_socket="s",
+        advisor_session_id="a",
+        reviewed_head="h",
+    )
+    kept = retain_verified_findings(
+        all_candidates=[candidate],
+        verdict_by_key={("a.py", 2, "null"): VERDICT_CONFIRMED},
+        severity_by_key={("a.py", 2, "null"): "high"},
+    )
+    assert len(kept) == 1
+    assert kept[0].verdict == VERDICT_CONFIRMED

package/skills/fresh-branch/CLAUDE.md

@@ -1,14 +1,14 @@
 # fresh-branch
 
-Creates a new branch from fresh-fetched `origin/main` inside an isolated worktree under `<repo-root>/.claude/worktrees/<agent>/<branch-name>`. Does not push, open a PR, or run `checkout -b` in the caller tree.
+Creates a new branch from fresh-fetched `origin/main` inside an isolated worktree under a configured root. Default: `<repo-root>/.claude/worktrees/<agent>/<branch-name>`. Optional absolute `--worktree-root` relocates the root (agent and branch still nest under it). Relative roots and path escape fail closed. Does not push, open a PR, or run `checkout -b` in the caller tree.
 
 ## Key files
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Phases, checklist, execute-vs-read for the CLI, gotchas |
-| `scripts/create_fresh_branch.py` | Deterministic CLI: fetch base, `git worktree add -b`, JSON stdout |
+| `SKILL.md` | Phases, checklist, configured-root contract, execute-vs-read for the CLI, gotchas |
+| `scripts/create_fresh_branch.py` | Deterministic CLI: resolve configured root (fail closed before fetch), fetch base, `git worktree add -b`, JSON stdout |
 | `scripts/fresh_branch_git_commands.py` | Git command helpers: fetch, ref checks, `git worktree add -b --no-track` |
-| `scripts/test_create_fresh_branch.py` | Behavioral tests with temporary git repos |
+| `scripts/test_create_fresh_branch.py` | Behavioral tests with temporary git repos (default root, explicit root, escape, collisions) |
 | `scripts/test_fresh_branch_git_commands.py` | Behavioral tests for the git command helpers |
-| `scripts/fresh_branch_scripts_constants/` | Constants package (`fresh_branch_cli_constants`) for the CLI |
+| `scripts/fresh_branch_scripts_constants/` | Constants package (`fresh_branch_cli_constants`) for CLI flags and error strings |

package/skills/fresh-branch/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: fresh-branch
 description: >-
-  Fresh git branch from origin/main in an isolated worktree under the repo's .claude/worktrees/ (never checkout -b in the caller tree).
+  Fresh git branch from origin/main in an isolated worktree under a configured root (default: <repo>/.claude/worktrees/<agent>/; never checkout -b in the caller tree).
   Triggers: fresh branch, new branch from main, /fresh-branch, start fresh, clean branch off main,
   worktree branch, branch in temp.
 ---
 
 # fresh-branch
 
-Creates a new branch from a fresh-fetched `origin/main` inside an isolated git worktree under the repository's `.claude/worktrees/<agent>/` root. Shared primitive: other skills invoke `/fresh-branch` when they need a clean branch without touching the caller's dirty tree.
+Creates a new branch from a fresh-fetched `origin/main` inside an isolated git worktree under a **configured isolated root**. Default root is the repository's `.claude/worktrees/`; pass `--worktree-root` for an absolute alternate root (including outside the repo). Every worktree path must resolve under that root. Shared primitive: other skills invoke `/fresh-branch` when they need a clean branch without touching the caller's dirty tree.
 
 **Announce at start:** "Creating a fresh branch from origin/main."
 
@@ -62,15 +62,21 @@ Optional flags:
 | Flag | Role |
 |------|------|
 | `--repo <path>` | Source repo (default: current directory) |
-| `--agent <slug>` | Worktree-root segment: `claude`, `grok`, `cursor`, `codex`, … |
+| `--agent <slug>` | Agent segment under the configured root: `claude`, `grok`, `cursor`, `codex`, … |
 | `--base <ref>` | Base ref (default: `origin/main`) |
+| `--worktree-root <abs-path>` | Absolute isolated root for all worktrees (default: `<repo-root>/.claude/worktrees`) |
 
 Agent resolution inside the script: `--agent` → `FRESH_BRANCH_AGENT` env → host markers → `claude`.
 
-Worktree path:
+Configured-root contract:
 
-- `<repo-root>/.claude/worktrees/<agent>/<branch-name>`, on every platform
+- Default configured root: `<repo-root>/.claude/worktrees`
+- Explicit `--worktree-root` must be absolute; a relative value fails closed with a deterministic error before any git fetch
+- Absolute roots outside the repository are legal; the agent and branch still nest under that root
+- Worktree path: `<configured-root>/<agent>/<branch-name>`, on every platform
+- Every allocated path must resolve under the configured root; traversal that escapes fails closed
 - If the path exists, the script suffixes `-2`, `-3`, …
+- Permission-rule cleanup (`stale_worktree_rule_sweep`) only walks `~/.claude/worktrees`; external `--worktree-root` trees are outside that sweep until a follow-up ships
 
 On exit 0, stdout is one JSON object:
 
@@ -100,10 +106,12 @@ Further edits for the new branch belong in `worktree_path`, not in the caller's
 
 ## Gotchas
 
-- **Dirty caller cwd blocks `checkout -b` and pollutes the tree.** Phase 3 always uses `git worktree add -b` into `<repo-root>/.claude/worktrees/<agent>/…`. If you reconstruct Phase 3 by hand with `checkout -b` in the session cwd, local modifications block the checkout and leave the user on a half-switched branch.
+- **Dirty caller cwd blocks `checkout -b` and pollutes the tree.** Phase 3 always uses `git worktree add -b` into `<configured-root>/<agent>/…`. If you reconstruct Phase 3 by hand with `checkout -b` in the session cwd, local modifications block the checkout and leave the user on a half-switched branch.
 - **Caller HEAD must stay put.** After success, the original repo's checked-out branch and dirty files are unchanged; only the new worktree has the new branch.
 - **Branch name collision.** If the branch already exists, the script exits non-zero with `{"error":...}`. Pick a new name; do not delete remote branches unless the user asks.
 - **Path already occupied.** A leftover folder at the preferred worktree path gets a numeric suffix (`-2`, …); report the path from JSON, not the path you assumed.
+- **Relative `--worktree-root` is refused before fetch.** Only an absolute path is accepted; the default root applies when the flag is omitted. Validation runs before `git fetch`, so a bad root never touches the network or remote-tracking refs.
+- **External roots and stale permission rules.** `stale_worktree_rule_sweep` only walks `~/.claude/worktrees`. Edit rules granted under an external `--worktree-root` are not swept when that tree is deleted.
 
 ## File index