claude-dev-env 2.8.0 → 2.10.0

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/audit_category_schema_constants.py

@@ -0,0 +1,32 @@
+"""Constants for audit_category_schema path resolution and parity checks."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent.parent
+PACKAGE_ROOT = SCRIPTS_DIRECTORY.parents[3]
+SCHEMA_RELATIVE_PATH = Path("audit-rubrics") / "audit-categories.json"
+CATEGORY_RUBRICS_DIRECTORY = PACKAGE_ROOT / "audit-rubrics" / "category_rubrics"
+PROMPTS_DIRECTORY = PACKAGE_ROOT / "audit-rubrics" / "prompts"
+HEADING_PATTERN = re.compile(r"^# Category ([A-Q]) — (.+)$")
+HEADING_LETTER_GROUP = 1
+HEADING_TITLE_GROUP = 2
+EXPECTED_CATEGORY_IDS = tuple("ABCDEFGHIJKLMNOPQ")
+SCHEMA_VERSION = 1
+JSON_INDENT = 2
+NEWLINE = "\n"
+UTF8_ENCODING = "utf-8"
+RUBRIC_SUB_BUCKET_ROW_TEMPLATE = r"^\| ({category_id}\d+) \| ([^|]+) \|"
+SKELETON_COUNT_PATTERN = re.compile(r"decomposed into (\d+) sub-buckets")
+SKELETON_PLACEHOLDER_FRAGMENT = "decomposed into [N] sub-buckets"
+SKELETON_SEPARATOR_LINE = "---"
+CATEGORY_SLUG_PREFIX_TEMPLATE = "category-{letter}-"
+CATEGORY_ID_KEY = "id"
+CATEGORY_TITLE_KEY = "title"
+CATEGORY_SLUG_KEY = "slug"
+CATEGORY_SUB_BUCKETS_KEY = "sub_buckets"
+SUB_BUCKET_AXIS_KEY = "axis_name"
+SCHEMA_CATEGORIES_KEY = "categories"
+SCHEMA_VERSION_KEY = "schema_version"

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/path_resolver_constants.py

@@ -2,6 +2,8 @@
 
 import re
 
+from audit_category_schema import category_id_title_entries
+
 RUN_NAME_TEMPLATE_SINGLE = "bugteam-pr-{number}"
 RUN_NAME_TEMPLATE_MULTI = "bugteam-{sanitized_branch}"
 PER_PR_WORKSPACE_TEMPLATE = "pr-{number}"
@@ -24,30 +26,16 @@ ALL_AUDIT_CONSTRAINT_TEXTS = [
     "Work exclusively within the worktree directory.",
     "Every finding must cite file:line.",
     "Document each finding with severity, file, line, and suggested fix.",
+    "Report every real finding. Collection retains all severities "
+    "(P0, P1, P2). Do not drop findings by severity during collection; "
+    "severity or action filtering is a separate consumer stage after the "
+    "collection record is complete.",
     "Read each file in the diff before reporting on it.",
     "Double-quote every path in shell commands and write paths with "
     "forward slashes (e.g. C:/Users/...), even on Windows.",
 ]
 
-ALL_AUDIT_CATEGORY_ENTRIES = [
-    ("A", "API contract verification"),
-    ("B", "Selector / query / engine compatibility"),
-    ("C", "Resource cleanup and lifecycle"),
-    ("D", "Variable scoping, ordering, and unbound references"),
-    ("E", "Dead code and unused imports"),
-    ("F", "Silent failures"),
-    ("G", "Off-by-one, bounds, integer overflow"),
-    ("H", "Security boundaries"),
-    ("I", "Concurrency hazards"),
-    ("J", "CODE_RULES.md compliance"),
-    ("K", "Codebase conflicts (incomplete propagation)"),
-    ("L", "Behavior-equivalence for refactors"),
-    ("M", "Producer/consumer cardinality vs collection-type contract"),
-    ("N", "Test-name scenario verifier"),
-    ("O", "Docstring / fixture-prose vs implementation drift"),
-    ("P", "Name / regex / word-list vs behavior-contract precision"),
-    ("Q", "Cross-surface claim consistency (terminology, PR-description claims, message-vs-guard)"),
-]
+ALL_AUDIT_CATEGORY_ENTRIES = category_id_title_entries()
 
 AUDIT_RUBRIC_REFERENCE_TEXT = (
     "The category list above is a summary. The binding definition of each "

package/skills/_shared/pr-loop/scripts/test_audit_category_schema.py

@@ -0,0 +1,94 @@
+"""Parity tests for the A-Q audit-category schema and projections."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from types import ModuleType
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from skills_pr_loop_constants.audit_category_schema_constants import (
+    CATEGORY_SLUG_KEY,
+    CATEGORY_SUB_BUCKETS_KEY,
+    PROMPTS_DIRECTORY,
+    SCHEMA_CATEGORIES_KEY,
+    SKELETON_PLACEHOLDER_FRAGMENT,
+    SKELETON_SEPARATOR_LINE,
+    UTF8_ENCODING,
+)
+from skills_pr_loop_constants.path_resolver_constants import ALL_AUDIT_CATEGORY_ENTRIES
+
+
+def _load_audit_category_schema() -> ModuleType:
+    module_path = _SCRIPTS_DIR / "audit_category_schema.py"
+    spec = importlib.util.spec_from_file_location("audit_category_schema", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["audit_category_schema"] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+audit_category_schema = _load_audit_category_schema()
+
+
+def test_schema_lists_a_through_q_in_order() -> None:
+    schema = audit_category_schema.load_audit_category_schema()
+    all_ids = [each_category["id"] for each_category in schema["categories"]]
+    assert all_ids == list("ABCDEFGHIJKLMNOPQ")
+
+
+def test_schema_entries_match_constant_export() -> None:
+    assert (
+        audit_category_schema.category_id_title_entries()
+        == list(ALL_AUDIT_CATEGORY_ENTRIES)
+    )
+
+
+def test_validate_projections_matches_rubrics_and_prompts() -> None:
+    all_findings = audit_category_schema.validate_projections()
+    assert all_findings == [], all_findings
+
+
+def test_skeleton_projection_is_byte_stable() -> None:
+    schema = audit_category_schema.load_audit_category_schema()
+    first_render = audit_category_schema.render_skeleton_projections(schema)
+    second_render = audit_category_schema.render_skeleton_projections(
+        json.loads(json.dumps(schema))
+    )
+    assert first_render == second_render
+    assert "A1" in first_render["A"]
+    assert first_render["A"].count("\n") >= 1
+
+
+def test_schema_omits_worked_example_prose() -> None:
+    schema_path = audit_category_schema.audit_category_schema_path()
+    schema_text = schema_path.read_text(encoding="utf-8")
+    assert "Examples of Category" not in schema_text
+    assert "Sample prompt" not in schema_text
+
+
+def test_no_prompt_skeleton_uses_placeholder_count() -> None:
+    """Migrated prompts state a numeric sub-bucket count, never [N]."""
+    schema = audit_category_schema.load_audit_category_schema()
+    all_findings = audit_category_schema.validate_projections()
+    assert all_findings == [], all_findings
+    for each_category in schema[SCHEMA_CATEGORIES_KEY]:
+        slug = each_category[CATEGORY_SLUG_KEY]
+        assert isinstance(slug, str)
+        prompt_path = PROMPTS_DIRECTORY / f"{slug}.md"
+        all_skeleton_lines: list[str] = []
+        for each_line in prompt_path.read_text(encoding=UTF8_ENCODING).splitlines():
+            if each_line == SKELETON_SEPARATOR_LINE:
+                break
+            all_skeleton_lines.append(each_line)
+        skeleton_text = "\n".join(all_skeleton_lines)
+        assert SKELETON_PLACEHOLDER_FRAGMENT not in skeleton_text, slug
+        sub_bucket_count = len(each_category[CATEGORY_SUB_BUCKETS_KEY])
+        assert f"decomposed into {sub_bucket_count} sub-buckets" in skeleton_text, slug

package/skills/_shared/pr-loop/scripts/test_build_audit_prompt.py

@@ -424,3 +424,24 @@ def test_precatch_rubric_adversarial_lane_uses_a_through_q() -> None:
     rubric_text = _PRECATCH_RUBRIC_PATH.read_text(encoding="utf-8")
     assert _A_THROUGH_Q_PATTERN.search(rubric_text) is not None
     assert _STALE_A_THROUGH_P_PATTERN.search(rubric_text) is None
+
+
+def test_audit_prompt_constraints_require_collection_before_severity_filter() -> None:
+    root = _build_audit_root()
+    constraints = root.find("constraints")
+    assert constraints is not None
+    all_constraint_texts = [
+        each_constraint.text or "" for each_constraint in constraints
+    ]
+    joined = "\n".join(all_constraint_texts)
+    assert "Report every real finding" in joined
+    assert "Do not drop findings by severity during collection" in joined
+    assert "separate consumer stage" in joined
+    assert "P0" in joined and "P1" in joined and "P2" in joined
+
+
+def test_audit_contract_documents_collection_before_severity_filtering() -> None:
+    contract_text = _AUDIT_CONTRACT_PATH.read_text(encoding="utf-8")
+    assert "## Collection before severity filtering" in contract_text
+    assert "separate consumer stage" in contract_text
+    assert "Do not drop a real finding because its severity is low" in contract_text

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/autoconverge/reference/convergence.md

@@ -152,7 +152,8 @@ existing fix + re-converge path.
 - Runs after Bugbot and Copilot. Honors `reviews_disabled.py --reviewer codex`,
   the weekly usage probe via `is_codex_review_required` (shared threshold
   constant — no inline percent), and the wrapper's `codex_down` class.
-- Opt-out token or `codex_down` → set `codexDown`, no stamp, move to the
+- Missing opt-in (the default), opt-out token, or `codex_down` → set
+  `codexDown`, no stamp, move to the
   convergence check with `--codex-down`. A `codex_down` classification also
   records a `codexNote` so the skip stays visible in the final report.
 - Usage at/below threshold or null → skip with no stamp; the machine checklist

package/skills/autoconverge/reference/stop-conditions.md

@@ -88,10 +88,12 @@ Each reviewer-down condition below skips its own convergence-check gate. The fla
   `--copilot-down` (the Copilot review gate and the pending-requested-reviews
   gate bypassed), then mark-ready. `copilotNote` records the bypass for the
   final report.
-- **Terminal Codex gate skipped (opt-out, usage, or `codex_down`)** — the
+- **Terminal Codex gate skipped (no opt-in, opt-out, usage, or `codex_down`)** — the
   conditional-required Codex gate runs after Bugbot and Copilot. When
-  `CLAUDE_REVIEWS_DISABLED` lists `codex` (`reviews_disabled.py --reviewer codex`
-  exit 0), the gate sets `codexDown` and advances with no review. When the weekly
+  `reviews_disabled.py --reviewer codex` exits 0 — which it does whenever
+  `CLAUDE_REVIEWS_ENABLED` omits `codex`, the default, and whenever
+  `CLAUDE_REVIEWS_DISABLED` lists it — the gate sets `codexDown` and advances
+  with no review. When the weekly
   usage probe reports `percent_left` null or at/below the shared threshold
   (`is_codex_review_required` false), the gate skips without a stamp; the
   convergence check applies the same rule. When the codex-review wrapper

package/skills/beat-sheet/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: beat-sheet
+description: "Formats a reply as single-line beats in plain everyday words. Triggers: '/beat-sheet', 'beat sheet this', 'give me the beats', 'write this as beats', 'too long', 'shorter', 'what?', 'english', 'no sense', 'jargon', 'huh?'."
+---
+
+# beat-sheet
+
+Write in single-line beats. Make each line one complete thought,
+under 12 words, with a blank line between lines. Keep it to ten
+lines, each one covering a new point. Order: situation, problem,
+fix, how it works. Put any command in its own code fence. Start
+with one short bold title line. Use plain everyday words a tired
+reader can skim.
+
+## Plain words
+
+Name the real thing first — a file, an image, a control, a
+screen, a size, an id, a proof. Prefer a word the reader can point
+at over an abstract one. When a word only makes sense on this
+project, say what it is in the app or on disk (a Theme Studio
+control, a package file name).
+
+## What the reader gets
+
+Lead with the answer. Put most of the reply on what they asked;
+keep warnings short. For "what's wrong" or "what's missing",
+answer in this order: what's wrong, what's missing, what follows.
+For an explain request, give a short summary unless they ask for
+more.
+
+## Around the work
+
+Before the first tool call, say in one sentence what you'll do.
+While working, speak up only on an important find or a change of
+course. When you finish, open with the result — what happened or
+what you found — then add detail only if it helps.
+
+## Job size
+
+Do the job asked, at the size asked. Decide small things
+yourself; ask only when two readings would change the work. When
+the ask looks off or a better path is clear, say so in one
+sentence, then do what was asked. Finish the whole job.
+
+## Before sending
+
+Read the reply as someone new to the project. Replace any word
+that needs a glossary with the thing itself.
+
+## Visual beats
+
+Add a visual only when it earns its space beyond what the beats
+already show on their own. See `reference/visual-beats.md` for the
+shape picker, the `rich` setup, and a working example.

package/skills/beat-sheet/reference/visual-beats.md

@@ -0,0 +1,29 @@
+# Visual beats
+
+Use one visual per reply, at most, sitting between beats in place
+of the beat it explains.
+
+Build it with `rich` (`pip install rich`), then paste the printed
+text into a fenced block. Set `no_color=True` and a fixed `width`
+so the output holds its shape in a terminal and on GitHub.
+
+Pick the shape by what the beat carries:
+
+| Shape | Carries |
+|---|---|
+| `Panel` | one claim worth framing |
+| `Table` | values a reader compares |
+| `Tree` | a stack, or parts inside a whole |
+
+```python
+from rich.console import Console
+from rich.table import Table
+from rich import box
+
+console = Console(width=64, no_color=True, force_terminal=False)
+table = Table(box=box.SIMPLE_HEAVY, title="Slice budget")
+table.add_column("slice")
+table.add_column("lines", justify="right")
+table.add_row("tests", "200")
+console.print(table)
+```

package/skills/bugteam/CONSTRAINTS.md

@@ -19,10 +19,10 @@
 
 The three sibling skills compose, but `/bugteam` solves a problem they cannot solve in sequence:
 
-- `/findbugs` audits once and stops.
-- `/fixbugs` fixes the findings of one audit and stops.
-- A human-driven `/findbugs` → `/fixbugs` → `/findbugs` → `/fixbugs` cycle works but requires the user to drive it.
+- `clean-room audit (code-quality-agent)` audits once and stops.
+- `/pr-fix-protocol` fixes the findings of one audit and stops.
+- A human-driven `clean-room audit (code-quality-agent)` → `/pr-fix-protocol` → `clean-room audit (code-quality-agent)` → `/pr-fix-protocol` cycle works but requires the user to drive it.
 
 `/bugteam` automates that cycle. The clean-room property is preserved by spawning a fresh audit agent each loop with no inherited context — every audit is independent of the prior loop's verdict. The 20-loop cap is the safety: pathological cases (audit agent oscillating, fix agent regressing) cannot run away.
 
-The single up-front confirmation is the explicit trade — `/bugteam` is more autonomous than `/findbugs`+`/fixbugs` chained manually. The user accepts that autonomy by typing the command. Stop conditions and the loop log give the user full visibility on exit.
+The single up-front confirmation is the explicit trade — `/bugteam` is more autonomous than `clean-room audit (code-quality-agent)`+`/pr-fix-protocol` chained manually. The user accepts that autonomy by typing the command. Stop conditions and the loop log give the user full visibility on exit.

package/skills/bugteam/EXAMPLES.md

@@ -25,7 +25,7 @@ Claude: [runs 20 loops without convergence]
 
 `/bugteam exit: cap reached`
 `Loops: 20`
-`Remaining: 0P0 / 1P1 / 2P2 — run /findbugs for human triage`
+`Remaining: 0P0 / 1P1 / 2P2 — run /pr-converge for human triage`
 </example>
 
 <example>

package/skills/bugteam/reference/README.md

@@ -20,7 +20,7 @@ The `pre-push-review` skill was retired. Its mechanical checks are now covered a
 
 - **Mechanical pre-push checks** (magic values, boolean naming, imports, constants location, and other CODE_RULES checks) — handled by the `code_rules_enforcer.py` PreToolUse hook (blocks at write time) and by the git pre-push hook installed via `npx claude-dev-env`. The git pre-push hook is the gate that runs at `git push` time; no manual invocation is needed.
 
-- **`/qbug`** — a full PR audit-fix cycle that spawns subagents, runs multiple audit loops, and produces a structured report. It is NOT a lightweight pre-push gate. Do not use `/qbug` as a substitute for `git push` (the hook fires automatically). Use `/qbug` when you want a thorough multi-loop review of a PR before requesting human review.
+- **`/bugteam`** — a full PR audit-fix cycle that spawns subagents, runs multiple audit loops, and produces a structured report. It is NOT a lightweight pre-push gate. Do not use `/bugteam` as a substitute for `git push` (the hook fires automatically). Use `/bugteam` when you want a thorough multi-loop review of a PR before requesting human review.
 
 References:
 - `hooks/git-hooks/pre_push.py` — the git pre-push hook that runs the CODE_RULES gate over the commits about to be pushed

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

@@ -14,8 +14,9 @@ description: >-
 ## Gotchas
 
 - **`low` stays single-pass.** No subagents, no full-file reads: one read pass per target item, one findings pass.
-- **`medium` favors precision, `xhigh` favors recall.** At `medium` (8 angles) surface only findings a maintainer would act on. At `xhigh` (10 angles plus a gap sweep) a single non-REFUTED vote carries the finding; do not drop on uncertainty.
-- **Every retained finding carries `severity` and `verdict`.** Severity is one of `blocker`, `high`, `medium`, `low`, `nit`. Verdict is `CONFIRMED` or `PLAUSIBLE`. Drop REFUTED candidates; never emit an unclassified retained finding.
+- **Collection reports every real finding.** Keep every CONFIRMED or PLAUSIBLE finding at its assigned severity (`blocker`, `high`, `medium`, `low`, `nit`). Do not drop low or nit findings during collection. Severity or action filtering is a separate consumer stage after the collection record is complete (`scripts/finding_pipeline.py`).
+- **`medium` favors precision, `xhigh` favors recall.** At `medium` (8 angles) assign severity carefully so a later filter can pick maintainer-action findings. At `xhigh` (10 angles plus a gap sweep) a single non-REFUTED vote carries the finding; do not drop on uncertainty.
+- **Every retained finding carries `severity` and `verdict`.** Severity is one of `blocker`, `high`, `medium`, `low`, `nit`. Verdict is `CONFIRMED` or `PLAUSIBLE`. Drop REFUTED candidates only; never emit an unclassified retained finding.
 - **`--fix` applies findings once.** Load `reference/fix.md` and follow it — it owns the fix agent, the code-rules gate, skip logging, and outcome reporting. Commits are lead-owned; fix agents never commit or push.
 - **`loop` never asks.** A round with bug findings validates them with an advisor, fixes, and re-reviews. Terminals are exactly `clean`, `nits_fixed`, and `advisor_blocked`. There is no reviewed-head count limit; a new head increments the count once, a re-review of the same head does not. Load `reference/loop.md` and follow it.
 - **`--fix` and `loop` combine.** With both, each loop round runs the level file, and the round's fixing happens inside `reference/loop.md`'s gate sequence, which loads `reference/fix.md` for the mechanics. There is no separate fix pass around the round.
@@ -28,6 +29,20 @@ Triggers: `/e-code-review <level> [--fix] [loop]`. `<level>` is `low`, `medium`,
 
 - **No level, or an unknown level.** Respond exactly: `Which effort level — low, medium, or xhigh?`
 
+## Evaluation-backed defaults (e-code-review family)
+
+When the caller asks which level to pick for a known fixture band (easy / medium / demanding scope), use the committed OP-02B evaluation evidence — not an inherited hard-coded preference. Thinking stays on; **effort** is the only cost/latency lever.
+
+| Fixture band | Skill effort | Source |
+|---|---|---|
+| easy | `medium` | `scripts/effort_defaults_evidence.json` → `skill_defaults.default_by_band.easy` |
+| medium | `xhigh` | same file → `medium` (maps evaluation `high`) |
+| demanding | `xhigh` | same file → `demanding` (maps evaluation `max`) |
+
+Resolve programmatically with `scripts/effort_evaluation.py` → `resolve_skill_effort_for_band`. Every default cites a completed evaluation row. The user-facing command still requires an explicit level flag; these defaults answer "what should I pick?" for this workflow family only.
+
+Detail: `reference/effort-evaluation.md`.
+
 ## The process
 
 1. Read `<level>` and the optional `--fix` and `loop` flags. Apply the refusal first.
@@ -46,8 +61,19 @@ 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 |
+| `reference/effort-evaluation.md` | Effort evaluation fixtures, evidence, and skill defaults |
+| `reference/runner-selection.md` | Runner selection map |
+| `scripts/finding_pipeline.py` | Collect every real finding; filter severity only later |
+| `scripts/test_finding_pipeline.py` | Collection and filter-stage behavioral tests |
+| `scripts/e_code_review_scripts_constants/finding_pipeline_constants.py` | Named constants for the collect-then-filter pipeline |
+| `scripts/effort_evaluation.py` | Effort rows, recommendation, skill default resolver |
+| `scripts/effort_defaults_evidence.json` | Committed evaluation rows + e-code-review skill defaults |
+| `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) |
 
 ## Folder map
 
 - `SKILL.md` — route and dispatch.
-- `reference/` — one procedure per level, plus `fix.md` and `loop.md`.
+- `reference/` — level procedures, fix/loop, effort evaluation, runner selection.
+- `scripts/` — collect-then-filter finding pipeline, effort evaluation, Grok medium-review module, tests, and `e_code_review_scripts_constants/`.

package/skills/e-code-review/reference/effort-evaluation.md

@@ -0,0 +1,35 @@
+# Effort evaluation sweep (Opus)
+
+Offline-first harness for choosing e-code-review effort and publishing cited skill defaults.
+
+## What it holds
+
+| Piece | Path |
+|---|---|
+| Fixtures | `scripts/fixtures/{easy,medium,demanding}.json` |
+| Schema + recommend | `scripts/effort_evaluation.py` |
+| Constants | `scripts/config/e_code_review_effort_constants/` |
+| Tests | `scripts/test_effort_evaluation.py` |
+
+## How to run offline tests
+
+```
+python -m pytest packages/claude-dev-env/skills/e-code-review/scripts/test_effort_evaluation.py -q
+```
+
+## Skill defaults (OP-02C — e-code-review family)
+
+Committed evidence: `scripts/effort_defaults_evidence.json`.
+
+- `resolve_skill_effort_for_band("easy"|"medium"|"demanding")` → `low`|`medium`|`xhigh`
+- Evaluation `high` / `max` map to skill `xhigh` (skill surface has three levels only)
+- Every skill default cites a completed evaluation row with `thinking_enabled: true`
+
+## Paid / live runs (optional)
+
+1. For each fixture, run the matching e-code-review level at each CLI-supported effort (`low` … `max`) with thinking on.
+2. Score quality, finding recall, finding precision; record visible tokens and latency.
+3. Feed completed rows into `recommend_effort_by_band` and `skill_defaults_from_recommendation`.
+4. Replace `effort_defaults_evidence.json` when live rows supersede the offline baseline.
+
+Stop if the Opus 5 CLI model is unavailable, or if results cannot separate quality from cost/latency.

package/skills/e-code-review/reference/medium.md

@@ -1,7 +1,10 @@
 `medium effort → 3+5 angles → 1-vote verify`
 
-You are reviewing for **precision** at medium effort: every finding you surface
-should be one a maintainer would act on.
+You are reviewing for **precision** at medium effort: assign severity carefully
+so a later consumer can select maintainer-action findings. **Collection
+reports every real finding** (including `low` and `nit`); do not drop by
+severity during collection. Severity filtering is a separate consumer stage
+after the collection record is complete.
 
 ## Phase 0 — Gather the diff
 
@@ -121,11 +124,19 @@ Keep candidates where the vote is CONFIRMED or PLAUSIBLE.
 
 ## Output
 
+**Collection stage first.** Keep every CONFIRMED or PLAUSIBLE finding in the
+collection record, including `low` and `nit`. Drop only REFUTED candidates.
+Do not drop a real finding because its severity is low.
+
 Report this review's results — `{level, findings}` — through the structured
 findings-report call: the mechanism that renders a review's results as a typed
 list in the host UI, ranked most-severe first. Each **retained** entry carries
-every field below. Drop REFUTED candidates before this report; do not emit a
-finding that lacks `severity` or `verdict`.
+every field below. Do not emit a finding that lacks `severity` or `verdict`.
+
+**Severity filter stage (later consumer).** After the collection record is
+complete, a separate consumer may filter by minimum severity for action or
+display. That filter must not rewrite or discard fields on the collection
+record itself.
 
 | Field | Required | Value |
 |---|---|---|

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/config/e_code_review_effort_constants/__init__.py

@@ -0,0 +1,41 @@
+"""Constants for the e-code-review effort evaluation harness."""
+
+from e_code_review_effort_constants.effort_constants import (
+    ALL_EFFORT_LEVELS,
+    ALL_EFFORT_RANK_BY_NAME,
+    ALL_FIXTURE_BANDS,
+    ALL_REQUIRED_ROW_KEYS,
+    ALL_SCORE_ROW_KEYS,
+    ALL_SKILL_EFFORT_FOR_EVALUATION_EFFORT,
+    ALL_SKILL_EFFORT_LEVELS,
+    COST_LATENCY_LEVER,
+    EVALUATION_EVIDENCE_FILENAME,
+    EVALUATION_SCHEMA_VERSION,
+    FIXTURES_DIRECTORY_NAME,
+    JSON_SUFFIX,
+    LATENCY_MS_ROW_KEY,
+    MINIMUM_QUALITY_HOLD_SCORE,
+    THINKING_ENABLED_DEFAULT,
+    VISIBLE_TOKENS_ROW_KEY,
+    WORKFLOW_FAMILY_E_CODE_REVIEW,
+)
+
+__all__ = [
+    "ALL_EFFORT_LEVELS",
+    "ALL_EFFORT_RANK_BY_NAME",
+    "ALL_FIXTURE_BANDS",
+    "ALL_REQUIRED_ROW_KEYS",
+    "ALL_SCORE_ROW_KEYS",
+    "ALL_SKILL_EFFORT_FOR_EVALUATION_EFFORT",
+    "ALL_SKILL_EFFORT_LEVELS",
+    "COST_LATENCY_LEVER",
+    "EVALUATION_EVIDENCE_FILENAME",
+    "EVALUATION_SCHEMA_VERSION",
+    "FIXTURES_DIRECTORY_NAME",
+    "JSON_SUFFIX",
+    "LATENCY_MS_ROW_KEY",
+    "MINIMUM_QUALITY_HOLD_SCORE",
+    "THINKING_ENABLED_DEFAULT",
+    "VISIBLE_TOKENS_ROW_KEY",
+    "WORKFLOW_FAMILY_E_CODE_REVIEW",
+]

package/skills/e-code-review/scripts/config/e_code_review_effort_constants/effort_constants.py

@@ -0,0 +1,40 @@
+"""Named values for the Opus effort evaluation sweep."""
+
+EVALUATION_SCHEMA_VERSION: str = "1"
+THINKING_ENABLED_DEFAULT: bool = True
+MINIMUM_QUALITY_HOLD_SCORE: float = 0.8
+COST_LATENCY_LEVER: str = "effort"
+ALL_EFFORT_LEVELS: tuple[str, ...] = ("low", "medium", "high", "xhigh", "max")
+ALL_FIXTURE_BANDS: tuple[str, ...] = ("easy", "medium", "demanding")
+ALL_SCORE_ROW_KEYS: tuple[str, ...] = (
+    "quality_score",
+    "finding_recall",
+    "finding_precision",
+)
+FIXTURES_DIRECTORY_NAME: str = "fixtures"
+JSON_SUFFIX: str = ".json"
+VISIBLE_TOKENS_ROW_KEY: str = "visible_tokens"
+LATENCY_MS_ROW_KEY: str = "latency_ms"
+ALL_REQUIRED_ROW_KEYS: tuple[str, ...] = (
+    "fixture_id",
+    "fixture_band",
+    "effort",
+    *ALL_SCORE_ROW_KEYS,
+    VISIBLE_TOKENS_ROW_KEY,
+    LATENCY_MS_ROW_KEY,
+    "thinking_enabled",
+)
+ALL_EFFORT_RANK_BY_NAME: dict[str, int] = {
+    each_effort: each_index
+    for each_index, each_effort in enumerate(ALL_EFFORT_LEVELS)
+}
+ALL_SKILL_EFFORT_LEVELS: tuple[str, ...] = ("low", "medium", "xhigh")
+EVALUATION_EVIDENCE_FILENAME: str = "effort_defaults_evidence.json"
+WORKFLOW_FAMILY_E_CODE_REVIEW: str = "e-code-review"
+ALL_SKILL_EFFORT_FOR_EVALUATION_EFFORT: dict[str, str] = {
+    "low": "low",
+    "medium": "medium",
+    "high": "xhigh",
+    "xhigh": "xhigh",
+    "max": "xhigh",
+}

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

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