claude-dev-env 2.8.0 → 2.9.0

package/skills/_shared/end-of-run-gotcha-recommendations.md

@@ -0,0 +1,156 @@
+# End-of-run gotcha recommendations
+
+**Shared close-out** for every skill.
+
+After the deliverable, recommend pasteable gotchas from issues **this run** hit.
+
+## When
+
+- **With issues:** end of work, after the deliverable.
+- **Clean run:** end with the deliverable only.
+
+## What counts
+
+Keep only items that **bit this run**:
+
+- Wrong **path, file, or config**
+- **Command / CLI** failed or needed different flags
+- **Auth, permission, or environment** blocked a step
+- **Data shape** mismatch (empty set, wrong schema, bad field)
+- **Tool, UI, or selector** missed the target
+- **Timing** needed a retry or longer wait
+- **Dependency or install** gap or wrong version
+- **Output format** wrong for the next step
+- A **workaround** required to finish
+
+## What to produce
+
+**Order (hard):**
+
+1. Show findings in chat; categorize as P0-P3.
+2. Then `AskUserQuestion`.
+3. On confirm only, file via `issue-tracker`.
+
+### Cold-reader frame
+
+Assume zero context.
+
+**Exactly two setup sentences**, each on its **own rendered line**:
+
+1. What we were doing.
+2. Why these notes matter.
+
+### 1. Chat findings (always first)
+
+#### Sentence law (HARD)
+
+| Rule | Required |
+|---|---|
+| **One sentence per rendered line** | Exactly one terminal `.` `?` or `!` on that line |
+| **No collapsed pairs** | A single markdown newline is **not** a line break — it joins sentences |
+| **Force the break** | Blank line between every prose sentence, **or** one list item per sentence |
+| **No clause glue** | No em-dash or semicolon joining two clauses |
+| **One idea** | If you can split it, split it |
+| **Heavy detail** | Prefer an **ASCII infographic** over a stack of sentences |
+
+**Self-check before send:** paste the chat into a viewer that collapses soft breaks.
+
+If two periods appear on one visual line, **split or diagram**.
+
+#### Per gotcha (HARD shape)
+
+| Part | Form |
+|---|---|
+| **Title** | Heading fragment only |
+| **Broke** | One sentence alone on its rendered line |
+| **Fix** | One sentence alone on its rendered line |
+| **ASCII** | Required for path, flag, or before/after |
+
+**Cap: two prose sentences per gotcha.**
+
+```markdown
+## Session close-out
+
+We built phone-theme prompts from a project style catalog.
+
+Keep these traps for the next run.
+
+## Gotcha recommendations
+
+### Wrong catalog folder
+
+The style picker failed outside the project.
+
+Run from the project root with data/midjourney_sref_catalog.json.
+
+```text
+wrong folder --> fail
+project root --> data/midjourney_sref_catalog.json
+```
+```
+
+**Wrong (soft break joins sentences into one line):**
+
+```markdown
+The style picker failed outside the project.
+Run from the project root with data/midjourney_sref_catalog.json.
+```
+
+Renders as one line with **two** sentences.
+
+**Right (blank line forces two lines):**
+
+```markdown
+The style picker failed outside the project.
+
+Run from the project root with data/midjourney_sref_catalog.json.
+```
+
+**Right (list items):**
+
+```markdown
+- The style picker failed outside the project.
+- Run from the project root with data/midjourney_sref_catalog.json.
+```
+
+### 2. Issue offer (`AskUserQuestion`)
+
+Only after the chat block.
+
+| Field | Limit |
+|---|---|
+| **Question** | One short sentence |
+| **Header** | `File issues` |
+| **label** | Plain name |
+| **description** | One short sentence |
+
+Detail and ASCII stay in chat.
+
+**On confirm:** file via `issue-tracker`.
+
+Cold-reader issue body.
+
+Clean run: skip.
+
+## Built-in skill gotcha
+
+**Two sentences on one rendered line.**
+
+Markdown soft-breaks join prose.
+
+Review the close-out before send.
+
+Split with a blank line or a list item.
+
+Or move the detail into an ASCII infographic.
+
+## Rules
+
+- Cold-reader first.
+- Chat first, then ask.
+- One sentence per **rendered** line.
+- Blank line or list item between prose sentences.
+- Two prose sentences per gotcha max.
+- ASCII for path, flag, or before/after.
+- File only on confirm.
+- Lived issues only.

package/skills/_shared/pr-loop/CLAUDE.md

@@ -12,7 +12,24 @@ those skills invoke during each loop tick.
 | `prompts/` | XML agent prompt templates. |
 | `scripts/` | Python scripts for loop state management, prompt building, outcome recording, path resolution, pacer selection, and preflight checks. |
 
-## Key files
+## Canonical-path stubs (`~/.claude/_shared/pr-loop/`)
+
+Open a stub, then load the `@` target:
+
+| Stub here | Load |
+|---|---|
+| `audit-contract.md` | `@~/.claude/_shared/pr-loop/audit-contract.md` |
+| `audit-reply-template.md` | `@~/.claude/_shared/pr-loop/audit-reply-template.md` |
+| `code-rules-gate.md` | `@~/.claude/_shared/pr-loop/code-rules-gate.md` |
+| `fix-protocol.md` | `@~/.claude/_shared/pr-loop/fix-protocol.md` |
+| `gh-payloads.md` | `@~/.claude/_shared/pr-loop/gh-payloads.md` |
+| `post-audit-thread-contract.md` | `@~/.claude/_shared/pr-loop/post-audit-thread-contract.md` |
+| `precatch-rubric.md` | `@~/.claude/_shared/pr-loop/precatch-rubric.md` |
+| `state-schema.md` | `@~/.claude/_shared/pr-loop/state-schema.md` |
+| `worker-spawn.md` | `@~/.claude/_shared/pr-loop/worker-spawn.md` |
+| `scripts/RUNTIME_SCRIPTS.md` | `@~/.claude/_shared/pr-loop/scripts/` |
+
+## Key files (live in this tree)
 
 | File | Role |
 |---|---|

package/skills/_shared/pr-loop/audit-contract.md

@@ -0,0 +1,5 @@
+# Audit contract
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/audit-contract.md

package/skills/_shared/pr-loop/audit-reply-template.md

@@ -0,0 +1,5 @@
+# Audit reply template
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/audit-reply-template.md

package/skills/_shared/pr-loop/code-rules-gate.md

@@ -0,0 +1,5 @@
+# Code rules gate
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/code-rules-gate.md

package/skills/_shared/pr-loop/fix-protocol.md

@@ -0,0 +1,5 @@
+# Fix protocol
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/fix-protocol.md

package/skills/_shared/pr-loop/gh-payloads.md

@@ -0,0 +1,5 @@
+# Gh payloads
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/gh-payloads.md

package/skills/_shared/pr-loop/post-audit-thread-contract.md

@@ -0,0 +1,5 @@
+# Post-audit thread contract
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/post-audit-thread-contract.md

package/skills/_shared/pr-loop/precatch-rubric.md

@@ -0,0 +1,5 @@
+# Precatch rubric
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/precatch-rubric.md

package/skills/_shared/pr-loop/scripts/CLAUDE.md

@@ -2,7 +2,14 @@
 
 Python scripts that run the PR audit-fix loop at runtime. Both `bugteam` and `pr-converge` invoke these scripts during each loop tick.
 
-## Key files
+## Two script homes
+
+| Home | Path |
+|---|---|
+| **Skill-local** (this folder) | Converge helpers: `build_*_prompt.py`, `init_loop_state.py`, `portable_converge_driver.py`, … |
+| **Runtime** (top-level shared) | Gate / preflight / review helpers — see `RUNTIME_SCRIPTS.md` → `@~/.claude/_shared/pr-loop/scripts/` |
+
+## Key files (skill-local)
 
 | File | Role |
 |---|---|

package/skills/_shared/pr-loop/scripts/RUNTIME_SCRIPTS.md

@@ -0,0 +1,29 @@
+# PR-loop runtime scripts
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/scripts/code_rules_gate.py
+
+@~/.claude/_shared/pr-loop/scripts/preflight.py
+
+@~/.claude/_shared/pr-loop/scripts/post_audit_thread.py
+
+@~/.claude/_shared/pr-loop/scripts/post_audit_review.py
+
+@~/.claude/_shared/pr-loop/scripts/gh_util.py
+
+@~/.claude/_shared/pr-loop/scripts/reviews_disabled.py
+
+@~/.claude/_shared/pr-loop/scripts/reviewer_availability.py
+
+@~/.claude/_shared/pr-loop/scripts/copilot_quota.py
+
+@~/.claude/_shared/pr-loop/scripts/grant_project_claude_permissions.py
+
+@~/.claude/_shared/pr-loop/scripts/revoke_project_claude_permissions.py
+
+@~/.claude/_shared/pr-loop/scripts/verify_review.py
+
+@~/.claude/_shared/pr-loop/scripts/README.md
+
+Skill-local converge helpers (`build_*_prompt.py`, `init_loop_state.py`, and siblings) live in this `scripts/` folder. Runtime gate, preflight, and review helpers live under `~/.claude/_shared/pr-loop/scripts/`.

package/skills/_shared/pr-loop/state-schema.md

@@ -0,0 +1,5 @@
+# State schema
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/state-schema.md

package/skills/_shared/pr-loop/worker-spawn.md

@@ -0,0 +1,5 @@
+# Worker spawn
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/worker-spawn.md

package/skills/e-code-review/SKILL.md

@@ -46,8 +46,13 @@ Triggers: `/e-code-review <level> [--fix] [loop]`. `<level>` is `low`, `medium`,
 | `reference/xhigh.md` | xhigh review procedure — 10 angles, 1-vote verify, gap sweep |
 | `reference/fix.md` | Fix application, code-rules gate, skip logging, outcome reporting |
 | `reference/loop.md` | Repeat review/fix rounds until clean |
+| `scripts/grok_code_review.py` | Grok medium-review discovery and verification |
+| `scripts/test_grok_code_review.py` | Behavioral tests for the Grok medium-review module |
+| `scripts/e_code_review_scripts_constants/` | Skill-local constants (unique package name; avoids bare `config` import shadow) |
+| `reference/runner-selection.md` | Runner selection map |
 
 ## Folder map
 
 - `SKILL.md` — route and dispatch.
-- `reference/` — one procedure per level, plus `fix.md` and `loop.md`.
+- `reference/` — level procedures, fix/loop, runner selection.
+- `scripts/` — medium-review module, tests, `e_code_review_scripts_constants/`.

package/skills/e-code-review/reference/runner-selection.md

@@ -0,0 +1,40 @@
+# Runner selection (medium review)
+
+How `/e-code-review medium` (and loop) should pick a **harness runner** for
+finder/verify work. This file is the map; `SKILL.md` only points here.
+
+## What lives here
+
+| Topic | Content |
+|---|---|
+| Goal | One skill surface; many possible runners (Grok, Codex, Claude headless, …) |
+| Today | `scripts/grok_code_review.py` is the Grok medium orchestration module |
+| Target | A thin selector chooses a runner by availability and task flags |
+| Non-goals | Reimplementing every harness inside this skill |
+
+## Today
+
+- Medium procedure: `reference/medium.md` (angles, verify, output fields).
+- Grok orchestration API: `scripts/grok_code_review.py` (discovery, dedupe,
+  retain, head-drift).
+- Constants: `scripts/e_code_review_scripts_constants/`.
+
+## Target shape (tracked separately)
+
+1. **Runner protocol** — shared inputs (diff base, head, angles) and outputs
+   (candidates, verdicts, severities).
+2. **Detection** — which runners are installed/configured (PATH, skills,
+   account chain).
+3. **Selection** — pick one runner without baking a single vendor into
+   `SKILL.md` process steps.
+4. **Adapters** — thin wrappers: Grok (current module), Codex, Claude, …
+
+Open issue for implementation work should link this file and keep PRs small
+(Google small-CL practice: one concern per PR).
+
+## Related always-on docs
+
+- Skill hub: `../SKILL.md` (levels, fix, loop — not runner internals).
+- Medium procedure: `medium.md`.
+- Shared worker spawn (when applicable):
+  `packages/claude-dev-env/_shared/pr-loop/worker-spawn.md` in the package tree.

package/skills/e-code-review/scripts/e_code_review_scripts_constants/__init__.py

@@ -0,0 +1 @@
+"""Constants package for e-code-review scripts."""

package/skills/e-code-review/scripts/e_code_review_scripts_constants/grok_code_review_constants.py

@@ -0,0 +1,55 @@
+"""Named constants for Grok medium-review discovery and verification."""
+
+from __future__ import annotations
+
+MEDIUM_REVIEW_SCHEMA_VERSION: str = "1.0.0"
+"""Schema version for medium-review run documents."""
+
+MEDIUM_REVIEW_FINDER_COUNT: int = 8
+"""Exactly eight finder angles execute per medium review head."""
+
+ALL_MEDIUM_FINDER_ANGLES: tuple[str, ...] = (
+    "correctness",
+    "security",
+    "code_rules",
+    "tests",
+    "docs",
+    "concurrency",
+    "api_contracts",
+    "regressions",
+)
+"""Named finder angles for one medium-review discovery batch."""
+
+VERDICT_CONFIRMED: str = "CONFIRMED"
+"""Verification retained a concrete failure scenario."""
+
+VERDICT_PLAUSIBLE: str = "PLAUSIBLE"
+"""Verification could not refute the finding."""
+
+VERDICT_REFUTED: str = "REFUTED"
+"""Verification rejected the finding."""
+
+ALL_VERIFICATION_VERDICTS: frozenset[str] = frozenset(
+    {VERDICT_CONFIRMED, VERDICT_PLAUSIBLE, VERDICT_REFUTED}
+)
+"""Legal verification verdict tokens."""
+
+SEVERITY_BLOCKER: str = "blocker"
+SEVERITY_HIGH: str = "high"
+SEVERITY_MEDIUM: str = "medium"
+SEVERITY_LOW: str = "low"
+SEVERITY_NIT: str = "nit"
+
+ALL_SEVERITIES: frozenset[str] = frozenset(
+    {
+        SEVERITY_BLOCKER,
+        SEVERITY_HIGH,
+        SEVERITY_MEDIUM,
+        SEVERITY_LOW,
+        SEVERITY_NIT,
+    }
+)
+"""Legal severity tokens on retained findings."""
+
+UTF8_ENCODING: str = "utf-8"
+"""Text encoding for review artifacts."""

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