claude-dev-env 1.38.0 → 1.39.0

package/scripts/config/groq_bugteam_config.py

@@ -1,230 +0,0 @@
-"""Centralized configuration for groq_bugteam.py.
-
-All module-level scalar constants live here per the repo's ``constants-location``
-rule. Import into the script and bind local aliases where needed.
-"""
-
-GROQ_API_ENDPOINT = "https://api.groq.com/openai/v1/chat/completions"
-GROQ_PRIMARY_MODEL = "llama-3.3-70b-versatile"
-GROQ_FALLBACK_MODEL = "llama-3.1-8b-instant"
-GROQ_REQUEST_TIMEOUT_SECONDS = 90
-GROQ_AUDIT_MAX_COMPLETION_TOKENS = 2500
-GROQ_FIX_MAX_COMPLETION_TOKENS = 8000
-GROQ_AUDIT_TEMPERATURE = 0.1
-GROQ_FIX_TEMPERATURE = 0.1
-
-MAXIMUM_FILE_CONTENT_CHARACTERS = 60000
-MAXIMUM_DIFF_CHARACTERS = 80000
-MAXIMUM_FINDINGS_PER_PR = 20
-
-GROQ_RETRY_BACKOFF_SECONDS = (2, 4, 8)
-
-REVIEW_BODY_HEADER_TEMPLATE = "## groq-bugteam audit: {p0} P0 / {p1} P1 / {p2} P2"
-NO_FINDINGS_REVIEW_BODY = (
-    "## groq-bugteam audit: clean\n\n"
-    "Groq ({model}) reviewed the diff against categories A-K and found no issues."
-)
-
-AUDIT_SYSTEM_PROMPT = """You are an adversarial code reviewer auditing a pull request diff.
-
-Inspect ONLY lines added or modified in the diff. Pre-existing code on
-untouched lines is out of scope. Cite file:line for every finding -- the line
-number MUST refer to the NEW side of the diff (post-change line number).
-
-Investigate these eleven categories. Skip a category silently when you find
-nothing; do not emit verified-clean entries. For the canonical rubric and
-sub-bucket decomposition for each category, see
-packages/claude-dev-env/audit-rubrics/category_rubrics/. For ready-to-send
-Variant C audit prompts (each containing a PR/repo-independent generalized
-skeleton above a `---` separator and a worked example against an authentic
-PR below it), see packages/claude-dev-env/audit-rubrics/prompts/.
-
-A. API contract verification (signatures, return types, async/await)
-B. Selector / query / engine compatibility
-C. Resource cleanup and lifecycle (file handles, connections, processes, locks)
-D. Variable scoping, ordering, unbound references
-E. Dead code, unused imports, dead parameters
-F. Silent failures (catch-all excepts, unconditional success returns)
-G. Off-by-one, bounds, integer overflow
-H. Security boundaries (injection, path traversal, auth bypass, secret leakage)
-I. Concurrency hazards (race conditions, missing awaits, shared mutable state)
-J. Magic values and configuration drift
-K. Codebase conflicts (a change updates one site of a pattern but a parallel
-   site in unchanged code stays stale, producing contradictory behavior;
-   diff is internally consistent, bug emerges only against unchanged code)
-
-Severity rubric:
-- P0: crashes, data loss, security breach, broken production invariant
-- P1: incorrect behavior, resource leak, regression on common path
-- P2: style, dead code, minor DRY violations
-
-Respond with JSON only -- no prose outside the JSON object. Shape:
-
-{
-  "findings": [
-    {
-      "severity": "P0" | "P1" | "P2",
-      "category": "A" | ... | "K",
-      "file": "relative path from repo root",
-      "line": int,
-      "title": "one-line summary",
-      "description": "2-3 sentences with concrete trace; reference the diff line"
-    }
-  ]
-}
-
-Cap findings at the top 20 most important. If no bugs, return {"findings": []}.
-
-FILE-TYPE GUARDRAILS. Do not apply code-specific categories to non-code files:
-- JSON / YAML / TOML / INI / Markdown / plain text: only flag CATEGORY H
-  (security) or J (real configuration drift that breaks something). Do NOT
-  flag E (dead code), A (API contract), or D (variable scoping) on these
-  files. A version string in package.json is NOT a magic value.
-- Lockfiles and auto-generated manifests: skip entirely.
-- Changelogs: skip entirely.
-
-QUALITY BAR. Only emit a finding if you can point at the specific line in
-the DIFF that introduced it AND describe the failure mode concretely. Skip
-speculative style complaints.
-"""
-
-FIX_SYSTEM_PROMPT = """You are a focused bug-fixer. You receive one file's full
-contents plus a list of findings that apply to that file. Produce the full
-corrected file contents.
-
-Rules:
-1. Address every listed finding. If a finding is not actionable, leave the
-   file unchanged and explain in the ``skipped`` array.
-2. Modify ONLY the lines required to address the findings. Preserve all other
-   code exactly -- comments, whitespace, blank lines, import order.
-3. Do not add new comments or docstrings unless the finding explicitly asks
-   for one.
-4. Do not introduce new imports unless required by a fix.
-5. Output JSON only. Shape:
-
-{
-  "updated_content": "full corrected file contents",
-  "applied_finding_indexes": [0, 2, ...],
-  "skipped": [
-    {"finding_index": 1, "reason": "one-line reason"}
-  ]
-}
-
-When you cannot produce a safe fix, set ``updated_content`` equal to the input
-BYTE-FOR-BYTE (same whitespace, same trailing newline, same indentation) and
-list every finding in ``skipped``. NEVER reformat or re-indent a file whose
-findings you are skipping.
-
-If ``applied_finding_indexes`` is empty, ``updated_content`` MUST equal the
-input exactly.
-"""
-
-SPEC_IMPLEMENTER_SYSTEM_PROMPT = """<groq_spec_implementer>
-
-<role>
-    Apply a Claude-authored fix-spec to a single file. Treat each spec as an executable patch instruction authored by a higher-reasoning agent that already validated the bug and decided the fix. Perform mechanical edits only. Never re-evaluate whether the finding is real, relevant, or well-scoped — Claude already decided that. Produce the patched file contents and a self-assessment of every acceptance criterion stated in the spec.
-</role>
-
-<inputs>
-    Every invocation provides exactly two inputs:
-
-    1. The current contents of one file, as a single UTF-8 string.
-
-    2. A fix-spec array targeting that file. Each spec entry has these fields:
-
-       - finding_index (int, stable across audit and fix)
-       - severity (P0 | P1 | P2)
-       - category (single letter A–K)
-       - file (relative path, must match the file being patched)
-       - target_line_start (int, 1-based, inclusive)
-       - target_line_end (int, 1-based, inclusive; equals target_line_start for single-line edits)
-       - intended_change (natural-language description of the edit)
-       - replacement_code (optional literal text to splice in; absent when Claude wanted Groq to derive the edit from intended_change + acceptance_criteria)
-       - acceptance_criteria (array of observable post-fix assertions; each is a standalone sentence a reader can check against the patched file)
-
-    Treat every field as authoritative. Accept the finding_index exactly as provided and echo it in the output.
-</inputs>
-
-<rules>
-
-<rule_1_mechanical_only>
-    Apply the spec verbatim. Skip every form of re-analysis. Only edit lines covered by target_line_start..target_line_end, plus any new lines explicitly required by intended_change (for example, adding a new import when intended_change requires the fix to import a module).
-</rule_1_mechanical_only>
-
-<rule_2_replacement_code_when_present>
-    When replacement_code is present, splice it in so the resulting file replaces lines target_line_start..target_line_end with the exact text of replacement_code. Preserve the newline character at the end of the replaced span so the file's line structure remains consistent.
-</rule_2_replacement_code_when_present>
-
-<rule_3_derive_minimally_when_replacement_absent>
-    When replacement_code is absent, implement the smallest edit that satisfies intended_change AND every acceptance_criterion. Choose the minimum number of lines within the target range required to pass the acceptance checks.
-</rule_3_derive_minimally_when_replacement_absent>
-
-<rule_4_byte_for_byte_outside_edit>
-    Preserve every byte outside the edited region: leading whitespace, trailing whitespace, trailing newline presence or absence, indent style (tabs versus spaces), blank-line placement, import order, existing comment placement, and line-ending style. Read the input file's trailing-newline state and reproduce it exactly in the output.
-</rule_4_byte_for_byte_outside_edit>
-
-<rule_5_no_stylistic_additions>
-    Add zero new comments, docstrings, type hints, or defensive code unless the spec explicitly requires one. Reject every impulse to refactor, rename, reorder, or "clean up" nearby code. Keep the diff as narrow as the spec allows.
-</rule_5_no_stylistic_additions>
-
-<rule_6_never_invent_authorization>
-    Only apply edits covered by a spec entry. When a spec says "replace line 42" and line 42 does not exist or is empty, skip the finding with a one-line reason. Never fabricate lines Claude did not authorize. Never generalize the spec to adjacent lines.
-</rule_6_never_invent_authorization>
-
-<rule_7_acceptance_self_check>
-    For every finding marked applied, evaluate each acceptance_criterion against the patched file contents. Record the result in acceptance_checks with met=true or met=false. When any acceptance_criterion evaluates to met=false for a given finding_index, move that finding_index out of applied_finding_indexes and into skipped with a reason naming the failing criterion.
-</rule_7_acceptance_self_check>
-
-</rules>
-
-<output_schema>
-    Respond with JSON only. Emit zero prose outside the JSON object. The object has exactly these top-level keys:
-
-        {
-          "updated_content": "full patched file contents as a single string",
-          "applied_finding_indexes": [0, 2],
-          "skipped": [
-            {"finding_index": 1, "reason": "one-line reason"}
-          ],
-          "acceptance_checks": [
-            {"finding_index": 0, "criterion": "verbatim text from the spec", "met": true}
-          ]
-        }
-
-    Ensure updated_content contains the full patched file — never a diff, never a fragment, never a summary. When applied_finding_indexes is empty, ensure updated_content equals the input byte-for-byte. Copy each acceptance_criterion string verbatim from the spec into the corresponding acceptance_checks entry.
-</output_schema>
-
-<failure_mode>
-    Skip the finding and preserve the file unchanged when any of these hold:
-
-    - target_line_start or target_line_end points outside the file.
-    - target_line_start > target_line_end.
-    - replacement_code contains a syntax error detectable on inspection.
-    - acceptance_criteria contradict the current file state in a way no valid patch can satisfy.
-    - intended_change and acceptance_criteria disagree with each other.
-    - Applying the spec would require editing lines outside target_line_start..target_line_end AND intended_change does not explicitly authorize that wider scope.
-
-    In every skip case, set the corresponding entry in skipped with a one-line reason naming the exact condition that failed. Return updated_content equal to the input when every finding is skipped. Never guess. Never partially apply. Never emit prose explanations outside the JSON object.
-</failure_mode>
-
-</groq_spec_implementer>
-"""
-
-JSON_INDENT_SPACES = 2
-PIPELINE_FAILURE_EXIT_CODE = 2
-
-TEXT_CLAMP_HEAD_PARTS = 1
-TEXT_CLAMP_TOTAL_PARTS = 2
-
-SPEC_MODE_FLAG = "--mode"
-SPEC_MODE_VALUE = "spec"
-MISSING_API_KEY_ERROR = (
-    "GROQ_API_KEY not set in environment; create packages/claude-dev-env/.env "
-    "from packages/claude-dev-env/.env.example (gitignored) or export GROQ_API_KEY"
-)
-
-REQUIRED_GROQ_BUGTEAM_ATTRIBUTES: tuple[str, ...] = (
-    "call_groq_with_fallback",
-    "parse_json_object",
-    "preserve_trailing_newline",
-)

package/scripts/config/test_groq_bugteam_config.py

@@ -1,83 +0,0 @@
-"""Existence and coherence checks for groq_bugteam_config.
-
-These are not business-behavior tests — the config module is constants only —
-but the tdd_enforcer hook requires a co-located test file, and the readability
-rule wants every constant referenced by at least two callers. The checks below
-keep those invariants observable and fail loudly if someone edits the config
-into an inconsistent state.
-"""
-
-from __future__ import annotations
-
-import importlib.util
-import pathlib
-import sys
-
-
-def _load_config_module():
-    module_path = pathlib.Path(__file__).parent / "groq_bugteam_config.py"
-    module_spec = importlib.util.spec_from_file_location(
-        "groq_bugteam_config", module_path
-    )
-    loaded_module = importlib.util.module_from_spec(module_spec)
-    sys.modules["groq_bugteam_config"] = loaded_module
-    module_spec.loader.exec_module(loaded_module)
-    return loaded_module
-
-
-groq_bugteam_config = _load_config_module()
-
-
-def test_primary_and_fallback_models_are_different():
-    assert (
-        groq_bugteam_config.GROQ_PRIMARY_MODEL
-        != groq_bugteam_config.GROQ_FALLBACK_MODEL
-    )
-
-
-def test_endpoint_is_https():
-    assert groq_bugteam_config.GROQ_API_ENDPOINT.startswith("https://")
-
-
-def test_json_indent_spaces_is_positive_integer():
-    assert isinstance(groq_bugteam_config.JSON_INDENT_SPACES, int)
-    assert groq_bugteam_config.JSON_INDENT_SPACES > 0
-
-
-def test_pipeline_failure_exit_code_is_non_zero_and_non_one():
-    # Reserve 0 for success and 1 for "bad stdin" — failure code must distinguish.
-    assert groq_bugteam_config.PIPELINE_FAILURE_EXIT_CODE not in (0, 1)
-
-
-def test_text_clamp_head_parts_fits_within_total():
-    assert (
-        0
-        < groq_bugteam_config.TEXT_CLAMP_HEAD_PARTS
-        < groq_bugteam_config.TEXT_CLAMP_TOTAL_PARTS
-    )
-
-
-def test_request_timeout_is_generous_enough_for_cold_start():
-    # Groq free-tier cold-start latency has been observed at 60s+; anything
-    # under 60 risks killing healthy requests mid-response.
-    assert groq_bugteam_config.GROQ_REQUEST_TIMEOUT_SECONDS >= 60
-
-
-def test_fix_budget_exceeds_audit_budget():
-    # Fix responses return full file contents; audit responses return just
-    # findings JSON — fix must have strictly more headroom.
-    assert (
-        groq_bugteam_config.GROQ_FIX_MAX_COMPLETION_TOKENS
-        > groq_bugteam_config.GROQ_AUDIT_MAX_COMPLETION_TOKENS
-    )
-
-
-def test_spec_implementer_prompt_is_distinct_from_fix_prompt():
-    assert (
-        groq_bugteam_config.SPEC_IMPLEMENTER_SYSTEM_PROMPT
-        != groq_bugteam_config.FIX_SYSTEM_PROMPT
-    )
-
-
-def test_spec_implementer_prompt_contains_mechanical_discipline_marker():
-    assert "mechanical edits only" in groq_bugteam_config.SPEC_IMPLEMENTER_SYSTEM_PROMPT

package/scripts/config/test_spec_implementer_prompt.py

@@ -1,32 +0,0 @@
-"""Existence and coherence check for SPEC_IMPLEMENTER_SYSTEM_PROMPT."""
-
-from __future__ import annotations
-
-import importlib.util
-import pathlib
-import sys
-
-
-def _load_config_module():
-    module_path = pathlib.Path(__file__).parent / "groq_bugteam_config.py"
-    module_spec = importlib.util.spec_from_file_location(
-        "groq_bugteam_config_spec", module_path
-    )
-    loaded_module = importlib.util.module_from_spec(module_spec)
-    sys.modules["groq_bugteam_config_spec"] = loaded_module
-    module_spec.loader.exec_module(loaded_module)
-    return loaded_module
-
-
-groq_bugteam_config = _load_config_module()
-
-
-def test_spec_implementer_prompt_is_non_empty_string():
-    prompt_text = groq_bugteam_config.SPEC_IMPLEMENTER_SYSTEM_PROMPT
-    assert isinstance(prompt_text, str)
-    assert len(prompt_text.strip()) > 0
-
-
-def test_spec_implementer_prompt_declares_mechanical_only_discipline():
-    prompt_text = groq_bugteam_config.SPEC_IMPLEMENTER_SYSTEM_PROMPT
-    assert "mechanical edits only" in prompt_text

package/scripts/groq_bugteam.README.md

@@ -1,131 +0,0 @@
-# groq_bugteam
-
-Single-pass adaptation of the [`bugteam` skill](../skills/bugteam/SKILL.md) that replaces the Claude Code agent-team orchestration with direct calls to [Groq](https://console.groq.com)'s chat completions API. No orchestrated team, no multi-loop convergence, no `TeamCreate`: one audit call, one fix call, one commit-and-push per PR.
-
-Lives at `packages/claude-dev-env/scripts/groq_bugteam.py`. Stateless, PII-free, env-driven.
-
-## When to reach for this
-
-`/bugteam` requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` plus an Anthropic-side environment that will sign commits on PR head branches. When either is missing — for example, a CI runner, a personal dev box, or any non-Claude-Code shell — this script gives you the audit/fix loop without the orchestration.
-
-When you already have `/bugteam` available, prefer it: the clean-room agent isolation + 10-loop convergence produces much lower false-positive rates than a single Groq pass.
-
-## Pipeline
-
-1. Read PR metadata + unified diff + file contents from stdin (JSON).
-2. POST one audit request to Groq with the diff and files. Parse findings as JSON.
-3. Group findings by file; for each file, POST one fix request. Parse `updated_content`.
-4. Write files that had at least one applied finding, `git add`, `git commit`, `git push HEAD:<head_ref>`.
-5. Emit JSON on stdout: findings, fix outcomes, commit SHA, review body, audit/fix model.
-
-The caller posts the review to GitHub. This script does not touch the GitHub API.
-
-## Stdin schema
-
-```json
-{
-  "pr_number": 123,
-  "owner": "someone",
-  "repo": "some-repo",
-  "base_ref": "main",
-  "head_ref": "feat/some-branch",
-  "diff": "<full `git diff origin/<base>...HEAD` output>",
-  "files_content": {"path/to/file.py": "<current file contents>"},
-  "worktree_path": "/abs/path/to/git/worktree/on/head_ref",
-  "apply_fixes": true
-}
-```
-
-## Stdout schema
-
-```json
-{
-  "findings": [
-    {"severity": "P0|P1|P2", "category": "A..J", "file": "...", "line": 42,
-     "title": "...", "description": "..."}
-  ],
-  "fix_outcomes": [
-    {"finding_index": 0, "status": "fixed|skipped|not_addressed|fix_call_failed",
-     "reason": "only when skipped/fix_call_failed"}
-  ],
-  "commit_sha": "abc123...",
-  "review_body": "## groq-bugteam audit: 1 P0 / 2 P1 / 0 P2\n...",
-  "audit_model": "llama-3.3-70b-versatile",
-  "fix_model": "llama-3.3-70b-versatile"
-}
-```
-
-## Required environment
-
-- `GROQ_API_KEY` — from https://console.groq.com/keys. Free tier is enough for a single PR.
-- **Local file (preferred):** copy `packages/claude-dev-env/.env.example` to `packages/claude-dev-env/.env`, set `GROQ_API_KEY=...` inside the copy. That path is gitignored; `groq_bugteam.py` loads it on startup when the file exists (without overriding variables already exported in your shell).
-- `git` on PATH, configured to push to the target remote.
-- Python 3.10+. No external deps (stdlib `urllib.request` only).
-
-## Minimal invocation
-
-```bash
-# Assumes you already have a git worktree checked out to the PR head branch.
-# Either use packages/claude-dev-env/.env (see Required environment) or:
-export GROQ_API_KEY=gsk_...
-
-python3 - <<'EOF' | python3 packages/claude-dev-env/scripts/groq_bugteam.py
-import json, subprocess, pathlib
-worktree = pathlib.Path("/tmp/pr-123-worktree")
-diff = subprocess.check_output(["git","-C",str(worktree),"diff","origin/main...HEAD"], text=True)
-changed = subprocess.check_output(["git","-C",str(worktree),"diff","--name-only","origin/main...HEAD"], text=True).strip().split("\n")
-files = {p: (worktree/p).read_text() for p in changed if (worktree/p).is_file()}
-print(json.dumps({
-  "pr_number": 123, "owner": "someone", "repo": "some-repo",
-  "base_ref": "main", "head_ref": "feat/some-branch",
-  "diff": diff, "files_content": files,
-  "worktree_path": str(worktree), "apply_fixes": True,
-}))
-EOF
-```
-
-## Caller responsibilities
-
-Because this script is intentionally narrow, the caller handles:
-
-- **Worktree setup.** `git worktree add -f -B <head_ref> <path> origin/<head_ref>`.
-- **File filtering.** Skip autogenerated files (CHANGELOG.md, lockfiles) and files >40KB to stay under Groq's free-tier per-request TPM limit. Chunk the call file-by-file when the whole-PR call hits 413.
-- **Commit signing.** If your environment enforces signing, set `git config commit.gpgsign false` in the worktree or provide a signing key the hook accepts.
-- **Finding triage.** Groq's single-pass audit produces false positives — test files flagged for code-rules that exempt them, JSON configs flagged for "path traversal," version bumps flagged as "magic values." The caller should filter before posting reviews. See the filter heuristics that shipped with this repo's first live run (`claude/groq-bugteam-prs-S9rwU`): drop test files, drop JSON/YAML/doc files for non-security categories, dedupe `(file, line, category)`, drop chunked-mode P2s, cap at top 10-15 per PR.
-- **Posting PR reviews.** The script emits `review_body` but does not POST. Use `gh api` or the GitHub MCP review-write endpoint.
-
-## Known limitations vs `/bugteam`
-
-| `/bugteam` | `groq_bugteam.py` |
-|---|---|
-| Fresh-context audit subagent each loop | Single Groq call, no re-audit |
-| Separate fix subagent (clean-room) | Same Groq call stream (state bleeds) |
-| 10-loop convergence with cap | One audit, one fix, done |
-| `code-quality-agent` + `clean-coder` models | `llama-3.3-70b-versatile` (+ 8b fallback on 413) |
-| Full CODE_RULES gate before every audit | No gate — caller's responsibility |
-| Posts per-finding inline review comments anchored to diff lines | Single review body with findings listed as markdown |
-| Rewrites PR body cumulatively | Does not touch PR body |
-
-Expect 2-5x more noise per finding than `/bugteam`. The caller's filter step is not optional.
-
-## Free-tier rate limits
-
-As of the live run on 2026-04-22 the Groq free tier enforces:
-
-- `llama-3.3-70b-versatile`: 12,000 tokens/minute, 1,000 requests/day.
-- `llama-3.1-8b-instant`: 6,000 tokens/minute, 14,400 requests/day.
-
-The script falls back to the 8b model on HTTP 413 (Groq returns 413 with `type: tokens` when the request TPM would exceed the cap). Most PRs >40KB of diff-plus-context will hit the cap. The caller can work around this by chunking: invoke the script once per changed file with `apply_fixes: false` and combine findings, or upgrade to a paid tier.
-
-## Tests
-
-```bash
-cd packages/claude-dev-env/scripts
-python3 -m pytest test_groq_bugteam.py -v
-```
-
-The test suite covers the pure-logic helpers (`clamp_text`, `parse_json_object`, `normalize_findings`, `group_findings_by_file`, `build_review_body`, `should_write_fixed_file`, `preserve_trailing_newline`, `is_safe_relative_path`, `decode_subprocess_stderr`, `build_fix_user_message`, HTTP error classification, pipeline refusals) and the co-located config invariants. Network calls to Groq and filesystem/git side effects are not unit-tested; exercise them with a live run.
-
-## Why this exists
-
-The jl-cmd/claude-code-config `/bugteam` skill is excellent when Claude Code is the runtime. When it isn't — CI, cron, a dev box — you still want the audit/fix pattern. This script is the minimum-viable port.