claude-dev-env 2.9.0 → 2.11.0

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,13 +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) |
-| `reference/runner-selection.md` | Runner selection map |
 
 ## Folder map
 
 - `SKILL.md` — route and dispatch.
-- `reference/` — level procedures, fix/loop, runner selection.
-- `scripts/` — medium-review module, tests, `e_code_review_scripts_constants/`.
+- `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/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/finding_pipeline_constants.py

@@ -0,0 +1,49 @@
+"""Named constants for the collect-then-filter finding pipeline.
+
+::
+
+    collect_findings([...low-severity finding...])
+        ok: collection keeps every seeded severity including low and nit
+    filter_findings_by_severity(collection, minimum_severity="medium")
+        ok: consumer stage drops lower severities; collection record is unchanged
+"""
+
+from __future__ import annotations
+
+COLLECTION_STAGE_NAME: str = "collection"
+"""Stage that retains every real finding with its evidence fields."""
+
+FILTER_STAGE_NAME: str = "severity_filter"
+"""Later consumer stage that may drop findings by severity for action."""
+
+FINDING_FIELD_FILE: str = "file"
+FINDING_FIELD_LINE: str = "line"
+FINDING_FIELD_SEVERITY: str = "severity"
+FINDING_FIELD_CATEGORY: str = "category"
+FINDING_FIELD_EVIDENCE: str = "evidence"
+
+SEVERITY_BLOCKER: str = "blocker"
+SEVERITY_HIGH: str = "high"
+SEVERITY_MEDIUM: str = "medium"
+SEVERITY_LOW: str = "low"
+SEVERITY_NIT: str = "nit"
+
+ALL_SEVERITY_RANK_BY_TOKEN: dict[str, int] = {
+    SEVERITY_BLOCKER: 5,
+    SEVERITY_HIGH: 4,
+    SEVERITY_MEDIUM: 3,
+    SEVERITY_LOW: 2,
+    SEVERITY_NIT: 1,
+}
+"""Higher rank is more severe; used only by the filter stage."""
+
+ALL_COLLECTION_SEVERITIES: tuple[str, ...] = tuple(ALL_SEVERITY_RANK_BY_TOKEN)
+"""Severity tokens collection accepts; derived from the rank map keys."""
+
+REPORT_EVERY_FINDING_INSTRUCTION: str = (
+    "Report every real finding. Collection retains all severities "
+    f"({', '.join(ALL_COLLECTION_SEVERITIES)}). Do not drop findings "
+    "by severity during collection; severity or action filtering is a "
+    "separate consumer stage after the collection record is complete."
+)
+"""Reviewer-prompt instruction that separates collection from filtering."""

package/skills/e-code-review/scripts/effort_defaults_evidence.json

@@ -0,0 +1,186 @@
+{
+  "schema_version": "1",
+  "workflow_family": "e-code-review",
+  "evidence_source": "offline_harness_baseline",
+  "thinking_enabled": true,
+  "cost_latency_lever": "effort",
+  "notes": "Completed evaluation rows from the OP-02B offline harness. Each skill default cites a holding row. Paid live sweeps may replace rows without changing the resolver contract.",
+  "all_rows": [
+    {
+      "fixture_id": "easy-comment-preservation",
+      "fixture_band": "easy",
+      "effort": "low",
+      "quality_score": 0.5,
+      "finding_recall": 0.5,
+      "finding_precision": 0.5,
+      "visible_tokens": 800,
+      "latency_ms": 2000,
+      "thinking_enabled": true
+    },
+    {
+      "fixture_id": "easy-comment-preservation",
+      "fixture_band": "easy",
+      "effort": "medium",
+      "quality_score": 0.95,
+      "finding_recall": 0.95,
+      "finding_precision": 0.95,
+      "visible_tokens": 1600,
+      "latency_ms": 4000,
+      "thinking_enabled": true
+    },
+    {
+      "fixture_id": "medium-constants-and-types",
+      "fixture_band": "medium",
+      "effort": "medium",
+      "quality_score": 0.7,
+      "finding_recall": 0.65,
+      "finding_precision": 0.75,
+      "visible_tokens": 2200,
+      "latency_ms": 5000,
+      "thinking_enabled": true
+    },
+    {
+      "fixture_id": "medium-constants-and-types",
+      "fixture_band": "medium",
+      "effort": "high",
+      "quality_score": 0.9,
+      "finding_recall": 0.9,
+      "finding_precision": 0.9,
+      "visible_tokens": 3200,
+      "latency_ms": 7000,
+      "thinking_enabled": true
+    },
+    {
+      "fixture_id": "demanding-multi-surface",
+      "fixture_band": "demanding",
+      "effort": "xhigh",
+      "quality_score": 0.75,
+      "finding_recall": 0.7,
+      "finding_precision": 0.8,
+      "visible_tokens": 5000,
+      "latency_ms": 10000,
+      "thinking_enabled": true
+    },
+    {
+      "fixture_id": "demanding-multi-surface",
+      "fixture_band": "demanding",
+      "effort": "max",
+      "quality_score": 0.92,
+      "finding_recall": 0.92,
+      "finding_precision": 0.9,
+      "visible_tokens": 8000,
+      "latency_ms": 15000,
+      "thinking_enabled": true
+    }
+  ],
+  "recommendation": {
+    "schema_version": "1",
+    "thinking_enabled": true,
+    "cost_latency_lever": "effort",
+    "defaults_unchanged": false,
+    "minimum_quality": 0.8,
+    "recommendation_by_band": {
+      "easy": {
+        "recommended_effort": "medium",
+        "cited_row": {
+          "fixture_id": "easy-comment-preservation",
+          "fixture_band": "easy",
+          "effort": "medium",
+          "quality_score": 0.95,
+          "finding_recall": 0.95,
+          "finding_precision": 0.95,
+          "visible_tokens": 1600,
+          "latency_ms": 4000,
+          "thinking_enabled": true
+        },
+        "blocker": null
+      },
+      "medium": {
+        "recommended_effort": "high",
+        "cited_row": {
+          "fixture_id": "medium-constants-and-types",
+          "fixture_band": "medium",
+          "effort": "high",
+          "quality_score": 0.9,
+          "finding_recall": 0.9,
+          "finding_precision": 0.9,
+          "visible_tokens": 3200,
+          "latency_ms": 7000,
+          "thinking_enabled": true
+        },
+        "blocker": null
+      },
+      "demanding": {
+        "recommended_effort": "max",
+        "cited_row": {
+          "fixture_id": "demanding-multi-surface",
+          "fixture_band": "demanding",
+          "effort": "max",
+          "quality_score": 0.92,
+          "finding_recall": 0.92,
+          "finding_precision": 0.9,
+          "visible_tokens": 8000,
+          "latency_ms": 15000,
+          "thinking_enabled": true
+        },
+        "blocker": null
+      }
+    }
+  },
+  "skill_defaults": {
+    "workflow_family": "e-code-review",
+    "thinking_enabled": true,
+    "cost_latency_lever": "effort",
+    "skill_levels": ["low", "medium", "xhigh"],
+    "default_by_band": {
+      "easy": {
+        "skill_effort": "medium",
+        "evaluation_effort": "medium",
+        "cited_row": {
+          "fixture_id": "easy-comment-preservation",
+          "fixture_band": "easy",
+          "effort": "medium",
+          "quality_score": 0.95,
+          "finding_recall": 0.95,
+          "finding_precision": 0.95,
+          "visible_tokens": 1600,
+          "latency_ms": 4000,
+          "thinking_enabled": true
+        },
+        "blocker": null
+      },
+      "medium": {
+        "skill_effort": "xhigh",
+        "evaluation_effort": "high",
+        "cited_row": {
+          "fixture_id": "medium-constants-and-types",
+          "fixture_band": "medium",
+          "effort": "high",
+          "quality_score": 0.9,
+          "finding_recall": 0.9,
+          "finding_precision": 0.9,
+          "visible_tokens": 3200,
+          "latency_ms": 7000,
+          "thinking_enabled": true
+        },
+        "blocker": null
+      },
+      "demanding": {
+        "skill_effort": "xhigh",
+        "evaluation_effort": "max",
+        "cited_row": {
+          "fixture_id": "demanding-multi-surface",
+          "fixture_band": "demanding",
+          "effort": "max",
+          "quality_score": 0.92,
+          "finding_recall": 0.92,
+          "finding_precision": 0.9,
+          "visible_tokens": 8000,
+          "latency_ms": 15000,
+          "thinking_enabled": true
+        },
+        "blocker": null
+      }
+    }
+  }
+}