claude-dev-env 2.8.0 → 2.9.0

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/grok-spawn/SKILL.md

@@ -231,3 +231,8 @@ Sibling skill: `/grokify` for a single paste-ready interactive Grok Build handof
 
 - `SKILL.md` — hub and process.
 - `reference/` — brief templates and flag profiles.
+
+## Worker advisors
+
+Each grok worker binds a unique Opus-high dvisor_session_id through the lead-supplied dvisor.launcher in the batch spec (committed default is a placeholder). Reports require the same handle\'s ENDORSE (or bounded CORRECTION/PLAN then ENDORSE); STOP or malformed signals end as advisor_blocked.
+

package/skills/orchestrator/SKILL.md

@@ -358,3 +358,8 @@ no open work remains, run `set --status done` before any re-arm attempt.
 - `scripts/` — deterministic status_gate.
 - Advisor policy:
   [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md).
+
+## File-backed run ledger
+
+When host task tools are absent, reconcile delegated work through `scripts/grok_run_ledger.py` under the run-state directory (stable task ids, one live owner, unique advisor sessions, dependency blocking, snapshot-drift reopening).
+

package/skills/task-build/reference/tool-routing.md

@@ -17,3 +17,6 @@ Do not invent a tool name. Tool availability means the callable tool is exposed
 ## Reporting
 
 State the selected tool, the number of new items, the number already tracked, and the new task subjects. If the fallback path was used, name the unavailable preferred tools briefly.
+
+4. **File ledger fallback** — when no host task/plan tool is exposed, register work in the durable `grok_run_ledger` under the run-state directory so orchestration stays reconcilable across hosts.
+

package/skills/team-advisor/SKILL.md

@@ -2,63 +2,42 @@
 name: team-advisor
 description: >-
   Spawn one warm session-advisor at the strongest reachable tier and consult
-  it before big decisions, completion, commits, or when stuck. Triggers:
+  it before substantive work, completion, commits, or when stuck. Triggers:
   'team-advisor', 'team advisor', 'second opinion', 'advisor', 'consult',
   'verify', 'validate', 'commit', 'push'.
 ---
 
 # Team Advisor
 
-## Principle
+One warm advisor at the strongest tier this session can reach. This session is the sole consumer.
 
-One warm, addressable advisor available at the strongest model tier the session can reach. The session sends concise briefs when a decision benefits from a second opinion: before acting on a plan, at completion, before commits, when stuck, when reconsidering the approach, or when an agent deems it necessary and beneficial to the user's goals.
+## Refs
 
-## Follow the shared protocol
-
-**Detect the host profile first** (Host profiles in
-[`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
-— e.g. %USERPROFILE%\.claude\_shared\advisor\advisor-protocol.md). Do not start a model-floor
-walk until the host is known. 
-
-This session is the shared advisor's sole consumer, so its model floor is
-simply this session's own tier — no routing table to take a max against.
+| Doc | Holds |
+|---|---|
+| [`docs/references/advisor-tool.md`](../../docs/references/advisor-tool.md) | **Consult cadence and weight** — when to call, hard rule before first write, how to treat advice. Read this for every consult. |
+| [`~/.claude/_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md) | **Bind and lifecycle** — host detect, model floor, warm-up or CLI bind, charter, drift re-bind, CLI fallback, executor paste blocks. |
+| [`agents/session-advisor.md`](../../agents/session-advisor.md) | **Reply contract** — ENDORSE / CORRECTION / PLAN / STOP; SendMessage only. |
 
-**Claude host:** follow the shared protocol for the model-floor walk, the
-warm-up spawn and charter, the consult format and cadence, drift-respawn, and
-the CLI fallback — using `team-advisor-agent` as the name and this session as
-the only consumer (skip the "who you are and your assignment" opener in each
-consult; a single-consumer session doesn't need it). A **Fable**-tier attempt
-carries the exact token `FABLE-SPAWN-AUTHORIZED` in its spawn prompt, as the
-protocol's warm-up rule states; `hooks/blocking/fable_spawn_gate.py` denies a
-fable spawn whose prompt lacks it.
+## Bind
 
-**Third-party host:** bind a max-tier Claude advisor through the shared CLI Claude-chain
-in the protocol (Fable max, then Opus max; `claude_chain_runner.py` ranks
-`~/.claude/claude-chain.json` accounts by weekly remaining via `claude_chain_usage`
-and fails over on usage limits). Consult via
-`--resume <session_id>` on that bind. This session is the sole consumer of that
-CLI advisor; skip the multi-consumer opener. When the chain cannot bind or
-reply, fail closed and report to the user — do **not** answer ENDORSE /
-CORRECTION / PLAN / STOP as this third-party session.
+1. Detect the host profile first (protocol **Host profiles**), then walk the model floor.
+2. Floor: this session's own tier on Claude; Opus floor with Fable first on a third-party host.
+3. Name: `team-advisor-agent` on Claude (Agent spawn of `session-advisor`); one CLI `session_id` on a third-party host via the protocol Claude-chain.
+4. A Fable-tier spawn or re-spawn carries the exact token `FABLE-SPAWN-AUTHORIZED` in its prompt (protocol warm-up; `fable_spawn_gate` requires it).
+5. Skip the multi-consumer "who you are" opener — sole consumer.
+6. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound Claude advisor issues ENDORSE / CORRECTION / PLAN / STOP.
 
-## Constraints
+Full walk, charter, consult message shape, and drift re-bind live in the protocol.
 
-- One advisor bind per session (`team-advisor-agent` on Claude; one CLI
-  `session_id` on a third-party host), owned by this session for its whole lifecycle
-  (spawn or CLI bind, drift re-bind, shutdown) — see
-  [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md).
-- Never bind the advisor, or its CLI path, at a tier below the protocol floor
-  for this host (Claude: this session's own tier; a third-party host: Opus floor
-  with Fable first).
-- The advisor only answers. It never edits a file, never runs a build or
-  test, and never posts anything on the session's behalf.
+## Consult
 
-## File Index
+Follow **When to call**, **Hard rule**, and **How to treat advice** in `advisor-tool.md`.
 
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Pointer to the shared advisor protocol; this session's consumer-specific wiring and constraints. |
+Each brief: delta since last consult, live decision or blocker, paths or excerpts needed. Protocol owns the full consult format.
 
-## Folder Map
+## Constraints
 
-- `SKILL.md` — complete team-advisor workflow instructions.
+- One bind per session; this session owns spawn or CLI bind, drift re-bind, and shutdown.
+- Bind at or above the protocol floor for this host.
+- The advisor only answers (messaging); the session runs tools and posts.

package/system-prompts/software-engineer.xml

@@ -90,8 +90,10 @@
 </problem_solving>
 
 <code_quality>
-  Apply the system-prompt code-quality checklist as the canonical naming and style source for
-  all code you write or modify. ~/.claude/docs/CODE_RULES.md is a pointer to this source.
+  Canonical code-quality policy is repository-root AGENTS.md (installed review contract).
+  ~/.claude/docs/CODE_RULES.md is the compact projection of AGENTS.md for generation load —
+  when the two disagree, AGENTS.md wins. The checklist below is a short reminder, not a
+  second canonical source.
 
   Naming — full words only:
   - Use "context" over "ctx", "configuration" over "cfg", "message" over "msg",
@@ -109,7 +111,8 @@
   Types — complete coverage required:
   - Every parameter and return value carries an explicit type hint
   - Replace Any with the most specific type available
-  - Replace every # type: ignore annotation with correct typing
+  - Prefer a real type over `# type: ignore`; when an ignore is required, add a second
+    trailing `#` justification of at least five characters (AGENTS Types)
 
   Configuration — one source of truth:
   - Every constant lives in config/ only

package/skills/test_markdown_link_integrity.py

@@ -1,107 +0,0 @@
-"""Link-integrity check for the skills tree and shared protocol docs.
-
-Walks every markdown file under ``skills/``, ``_shared/pr-loop/``, and
-``_shared/advisor/`` and resolves each relative markdown link target against
-the linking file's directory. A link whose target file or directory does not
-exist on disk is reported with its source file and line number, and the test
-fails.
-"""
-
-from __future__ import annotations
-
-import re
-from pathlib import Path
-
-
-SKILLS_ROOT = Path(__file__).parent
-SHARED_PR_LOOP_ROOT = SKILLS_ROOT.parent / "_shared" / "pr-loop"
-SHARED_ADVISOR_ROOT = SKILLS_ROOT.parent / "_shared" / "advisor"
-
-MARKDOWN_LINK_PATTERN = re.compile(r"\]\(([^)\s]+)\)")
-FENCE_MARKER = "```"
-
-SKIPPED_TARGET_PREFIXES = (
-    "http://",
-    "https://",
-    "mailto:",
-    "#",
-    "/",
-    "$",
-    "~",
-    "<",
-)
-
-
-def _iter_markdown_files() -> list[Path]:
-    """List every markdown file the integrity check covers.
-
-    Returns:
-        All ``.md`` files under the skills tree, the shared pr-loop tree, and
-        the shared advisor tree.
-    """
-    all_markdown_files = sorted(SKILLS_ROOT.rglob("*.md"))
-    all_markdown_files.extend(sorted(SHARED_PR_LOOP_ROOT.rglob("*.md")))
-    all_markdown_files.extend(sorted(SHARED_ADVISOR_ROOT.rglob("*.md")))
-    return all_markdown_files
-
-
-def _is_checkable_target(link_target: str) -> bool:
-    """Decide whether a markdown link target names a local relative path.
-
-    Args:
-        link_target: The raw text between ``](`` and ``)`` in a markdown link.
-
-    Returns:
-        True when the target is a relative filesystem path this check can
-        resolve; False for URLs, anchors, absolute paths, environment-variable
-        paths, home-relative paths, and angle-bracket placeholders.
-    """
-    if link_target.startswith(SKIPPED_TARGET_PREFIXES):
-        return False
-    if "\\" in link_target and link_target.count(":") > 0:
-        return False
-    return True
-
-
-def _collect_broken_links(markdown_path: Path) -> list[str]:
-    """Resolve every relative link in one markdown file.
-
-    Fenced code blocks are skipped, and a ``#fragment`` suffix is stripped
-    before resolution.
-
-    Args:
-        markdown_path: The markdown file whose links are resolved.
-
-    Returns:
-        One ``file:line -> target`` description per unresolvable link.
-    """
-    all_broken_links: list[str] = []
-    is_inside_fence = False
-    for line_number, each_line in enumerate(
-        markdown_path.read_text(encoding="utf-8").splitlines(), start=1
-    ):
-        if each_line.lstrip().startswith(FENCE_MARKER):
-            is_inside_fence = not is_inside_fence
-            continue
-        if is_inside_fence:
-            continue
-        for each_match in MARKDOWN_LINK_PATTERN.finditer(each_line):
-            link_target = each_match.group(1).split("#", 1)[0]
-            if not link_target or not _is_checkable_target(link_target):
-                continue
-            resolved_target = (markdown_path.parent / link_target).resolve()
-            if not resolved_target.exists():
-                all_broken_links.append(
-                    f"{markdown_path}:{line_number} -> {each_match.group(1)}"
-                )
-    return all_broken_links
-
-
-def test_every_relative_markdown_link_resolves() -> None:
-    all_broken_links: list[str] = []
-    for each_markdown_path in _iter_markdown_files():
-        all_broken_links.extend(_collect_broken_links(each_markdown_path))
-    broken_link_report = "\n".join(all_broken_links)
-    assert not all_broken_links, (
-        f"Unresolvable relative markdown links:\n{broken_link_report}"
-    )