claude-dev-env 1.28.0 → 1.29.0

package/scripts/config/groq_bugteam_config.py

@@ -0,0 +1,118 @@
+"""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-J 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 ten categories. Skip a category silently when you find
+nothing; do not emit verified-clean entries.
+
+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
+
+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" | ... | "J",
+      "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.
+"""
+
+JSON_INDENT_SPACES = 2
+PIPELINE_FAILURE_EXIT_CODE = 2
+
+TEXT_CLAMP_HEAD_PARTS = 1
+TEXT_CLAMP_TOTAL_PARTS = 2

package/scripts/config/test_groq_bugteam_config.py

@@ -0,0 +1,72 @@
+"""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
+    )

package/scripts/groq_bugteam.README.md

@@ -0,0 +1,129 @@
+# 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.
+- `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.
+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.