claude-dev-env 1.37.0 → 1.38.0

package/hooks/blocking/test_tdd_enforcer.py

@@ -190,6 +190,17 @@ def test_should_deny_edit_when_pragma_sentinel_present_in_new_string_without_tes
     assert _decision_from(completed) == "deny"
 
 
+def _make_edit_payload(file_path: Path, old_string: str, new_string: str) -> dict:
+    return {
+        "tool_name": "Edit",
+        "tool_input": {
+            "file_path": str(file_path),
+            "old_string": old_string,
+            "new_string": new_string,
+        },
+    }
+
+
 def test_should_allow_python_file_with_only_module_level_constants(tmp_path: Path) -> None:
     sandbox = _sandbox(tmp_path)
     constants_file = sandbox / "constants.py"
@@ -209,6 +220,147 @@ def test_should_allow_python_file_with_only_module_level_constants(tmp_path: Pat
     assert _decision_from(completed) == "allow"
 
 
+def test_should_allow_edit_to_change_constant_value_in_constants_only_file(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    constants_file = sandbox / "constants.py"
+    constants_file.write_text(
+        '"""Module-level constants."""\n'
+        "MAXIMUM_RETRIES: int = 3\n"
+        "DEFAULT_TIMEOUT_SECONDS: float = 30.0\n"
+    )
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            constants_file,
+            old_string="MAXIMUM_RETRIES: int = 3",
+            new_string="MAXIMUM_RETRIES: int = 5",
+        )
+    )
+
+    assert _decision_from(completed) == "allow"
+
+
+def _make_multiedit_payload(file_path: Path, edits: list[dict]) -> dict:
+    return {
+        "tool_name": "MultiEdit",
+        "tool_input": {
+            "file_path": str(file_path),
+            "edits": edits,
+        },
+    }
+
+
+def test_should_allow_multiedit_to_change_constant_value_in_constants_only_file(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    constants_file = sandbox / "constants.py"
+    constants_file.write_text(
+        '"""Module-level constants."""\n'
+        "MAXIMUM_RETRIES: int = 3\n"
+        "DEFAULT_TIMEOUT_SECONDS: float = 30.0\n"
+    )
+
+    completed = _run_hook_with_payload(
+        _make_multiedit_payload(
+            constants_file,
+            edits=[
+                {
+                    "old_string": "MAXIMUM_RETRIES: int = 3",
+                    "new_string": "MAXIMUM_RETRIES: int = 5",
+                },
+            ],
+        )
+    )
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_deny_multiedit_that_adds_function_to_constants_only_file(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    constants_file = sandbox / "constants.py"
+    constants_file.write_text(
+        '"""Module-level constants."""\n'
+        "MAXIMUM_RETRIES: int = 3\n"
+    )
+
+    completed = _run_hook_with_payload(
+        _make_multiedit_payload(
+            constants_file,
+            edits=[
+                {
+                    "old_string": "MAXIMUM_RETRIES: int = 3",
+                    "new_string": "MAXIMUM_RETRIES: int = 3\n\ndef reset() -> None:\n    return None",
+                },
+            ],
+        )
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_deny_edit_that_adds_function_to_constants_only_file(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    constants_file = sandbox / "constants.py"
+    constants_file.write_text(
+        '"""Module-level constants."""\n'
+        "MAXIMUM_RETRIES: int = 3\n"
+    )
+
+    completed = _run_hook_with_payload(
+        _make_edit_payload(
+            constants_file,
+            old_string="MAXIMUM_RETRIES: int = 3",
+            new_string="MAXIMUM_RETRIES: int = 3\n\ndef reset() -> None:\n    return None",
+        )
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_deny_python_file_with_assignment_calling_undefined_function(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    unsafe_file = sandbox / "unsafe.py"
+    unsafe_content = (
+        '"""Config with unsafe call."""\n'
+        "VALUE: str = compute()\n"
+    )
+    unsafe_file.write_text(unsafe_content)
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(unsafe_file, unsafe_content)
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_allow_python_file_with_assignment_calling_imported_function(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    safe_file = sandbox / "safe.py"
+    safe_content = (
+        '"""Config with imported call."""\n'
+        "from pathlib import Path\n"
+        "BASE_PATH = Path(r'C:\\\\data')\n"
+    )
+    safe_file.write_text(safe_content)
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(safe_file, safe_content)
+    )
+
+    assert _decision_from(completed) == "allow"
+
+
 def test_should_deny_python_file_when_any_function_definition_is_present(tmp_path: Path) -> None:
     sandbox = _sandbox(tmp_path)
     mixed_file = sandbox / "mixed.py"

package/hooks/config/state_description_blocker_constants.py

@@ -0,0 +1,130 @@
+"""Configuration constants for the state_description_blocker PreToolUse hook."""
+
+from re import IGNORECASE, Pattern, compile
+
+ALL_COMMENT_TRANSITION_PATTERNS: list[Pattern[str]] = [
+    compile(r"\binstead of\b", IGNORECASE),
+    compile(r"\bpreviously\b", IGNORECASE),
+    compile(r"\bnow uses\b", IGNORECASE),
+    compile(r"\bnow does\b", IGNORECASE),
+    compile(r"\bnow handles\b", IGNORECASE),
+    compile(r"\bnow supports\b", IGNORECASE),
+    compile(r"\bnow names\b", IGNORECASE),
+    compile(r"\bnow includes\b", IGNORECASE),
+    compile(r"\bwas previously\b", IGNORECASE),
+    compile(r"\bwere previously\b", IGNORECASE),
+    compile(r"\bwas formerly\b", IGNORECASE),
+    compile(r"\bwas added\b", IGNORECASE),
+    compile(r"\bused to\b", IGNORECASE),
+    compile(r"\bno longer\b", IGNORECASE),
+    compile(r"\bhas been updated\b", IGNORECASE),
+    compile(r"\bhave been updated\b", IGNORECASE),
+    compile(r"\bhas been changed\b", IGNORECASE),
+    compile(r"\bhave been changed\b", IGNORECASE),
+    compile(r"\breplaced by\b", IGNORECASE),
+    compile(r"\breplaces\b", IGNORECASE),
+    compile(r"\bsuperseded by\b", IGNORECASE),
+    compile(r"\bsupersedes\b", IGNORECASE),
+    compile(r"\bchanged from\b", IGNORECASE),
+    compile(r"\bchanges from\b", IGNORECASE),
+    compile(r"\bswitched from\b", IGNORECASE),
+    compile(r"\bswitched to\b", IGNORECASE),
+    compile(r"\bmigrated from\b", IGNORECASE),
+    compile(r"\bmigrated to\b", IGNORECASE),
+    compile(r"\bmoved to\b", IGNORECASE),
+    compile(r"\bmoved into\b", IGNORECASE),
+    compile(r"\bextracted as\b", IGNORECASE),
+    compile(r"\bupdated to\b", IGNORECASE),
+    compile(r"\boriginally\b", IGNORECASE),
+    compile(r"\bas of\b", IGNORECASE),
+]
+
+CODE_FENCE_PATTERN: Pattern[str] = compile(r"```[\s\S]*?```")
+INLINE_CODE_PATTERN: Pattern[str] = compile(r"``[^`]+``|`[^`]+`")
+
+ALL_MARKDOWN_EXTENSIONS: frozenset[str] = frozenset(
+    {".md", ".mdx", ".markdown", ".rmd"}
+)
+
+ALL_HASH_ONLY_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        ".py",
+        ".rb",
+        ".sh",
+        ".bash",
+        ".zsh",
+        ".ps1",
+        ".psm1",
+        ".yaml",
+        ".yml",
+        ".tf",
+    }
+)
+
+ALL_BLOCK_COMMENT_ONLY_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        ".css",
+    }
+)
+
+ALL_HASH_AND_SLASH_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        ".php",
+    }
+)
+
+ALL_BLOCK_COMMENT_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        ".js",
+        ".jsx",
+        ".ts",
+        ".tsx",
+        ".java",
+        ".c",
+        ".cpp",
+        ".h",
+        ".hpp",
+        ".rs",
+        ".go",
+        ".swift",
+        ".kt",
+        ".scala",
+        ".php",
+        ".css",
+        ".scss",
+        ".less",
+    }
+)
+
+ALL_COMMENT_BEARING_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        ".py",
+        ".js",
+        ".jsx",
+        ".ts",
+        ".tsx",
+        ".java",
+        ".c",
+        ".cpp",
+        ".h",
+        ".hpp",
+        ".rs",
+        ".go",
+        ".rb",
+        ".php",
+        ".swift",
+        ".kt",
+        ".scala",
+        ".sh",
+        ".bash",
+        ".zsh",
+        ".ps1",
+        ".psm1",
+        ".yaml",
+        ".yml",
+        ".tf",
+        ".css",
+        ".scss",
+        ".less",
+    }
+)

package/hooks/hooks.json

@@ -30,6 +30,11 @@
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/validation/hook_format_validator.py",
             "timeout": 15
           },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_rules_enforcer.py",
+            "timeout": 30
+          },
           {
             "type": "command",
             "command": "python3 -c \"import sys; sys.path.insert(0, r'${CLAUDE_PLUGIN_ROOT}/hooks'); from validators.run_all_validators import main; sys.exit(main())\"",
@@ -44,6 +49,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/windows_rmtree_blocker.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/state_description_blocker.py",
+            "timeout": 10
           }
         ]
       },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.37.0",
+    "version": "1.38.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/gh-paginate.md

@@ -1,6 +1,6 @@
 # gh API Pagination Rule
 
-**Root cause:** The GitHub REST API returns 30 items per page by default. `gh api repos/<owner>/<repo>/pulls/<number>/reviews` and `gh api repos/<owner>/<repo>/pulls/<number>/comments` silently truncate at 30 results without warning. PRs that have accumulated more than 30 reviews or inline comments — common on long PR-loop cycles where bugbot, copilot, or the in-house bugteam each post repeatedly — return only the **oldest** 30, hiding the most recent reviews and findings entirely. A `sort_by(.submitted_at) | last` (or `| reverse`) on a truncated array picks the latest entry **within the first 30**, not the actual latest, which produces a stale-but-confident report that then drives wrong decisions (e.g., re-triggering bugbot when it has already posted a CLEAN review on a later page).
+**Root cause:** GitHub REST API list endpoints paginate by default. Without `--paginate --slurp`, callers see only the oldest page, and cross-page jq operations (e.g., `sort_by | last`) operate within a single page — producing wrong-but-confident results.
 
 **Rule:** All `gh api` calls that read `pulls/<number>/reviews`, `pulls/<number>/comments`, `issues/<number>/comments`, or any other paginated GitHub list endpoint **must** request the full set of pages AND apply any cross-page jq operation through external `jq`, not through `gh`'s built-in `--jq`. Use `--paginate --slurp | jq` (preferred — see [Safe patterns](#safe-patterns)). Never call these endpoints with their default pagination, and never use `gh`'s `--jq` for cross-page operations like `sort_by | last` or `| reverse | .[0]`.
 
@@ -8,8 +8,8 @@
 
 This rule guards against two distinct silent-truncation defects that compound:
 
-1. **Default 30-item page.** Without `--paginate`, only the first page is fetched. On long PRs this hides the most recent reviews entirely.
-2. **`--jq` runs per-page, not on the concatenated result.** Per [GitHub CLI #10459](https://github.com/cli/cli/issues/10459), `gh api --paginate --jq '<filter>'` applies `<filter>` to each page **separately** and emits one output per page. Cross-page operations like `sort_by(.submitted_at) | last` therefore operate within each page independently, not across the merged result set. On PRs with more than 100 reviews this still produces a wrong-but-confident "latest" review even when `--paginate` is set.
+1. **Default page truncation.** Without `--paginate`, only the first page is fetched.
+2. **`--jq` runs per-page, not on the concatenated result.** Per [GitHub CLI #10459](https://github.com/cli/cli/issues/10459), `gh api --paginate --jq '<filter>'` applies `<filter>` to each page **separately** and emits one output per page. Cross-page operations like `sort_by(.submitted_at) | last` therefore operate within each page independently, not across the merged result set.
 
 The safe patterns below fix both defects together: `--paginate --slurp` walks every page AND emits a single merged structure, and an **external** `jq` then runs cross-page operations on that merged structure.
 
@@ -39,7 +39,7 @@ gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate --s
   | jq '[.[][] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
 ```
 
-The `.[][]` flattens the array-of-pages into one stream of items before the cross-page operators (`sort_by`, `last`, `reverse`) run. Combine with `?per_page=100` so each page fetches 100 items instead of 30, reducing round-trips on long PRs without changing correctness.
+The `.[][]` flattens the array-of-pages into one stream of items before the cross-page operators (`sort_by`, `last`, `reverse`) run. Combine with `?per_page=100` to reduce round-trips on long PRs.
 
 `gh`'s `--jq` flag and `--slurp` flag are mutually exclusive (gh CLI rejects `--paginate --slurp --jq` with `the --slurp option is not supported with --jq or --template`), which is why the filter must run in an external `jq` invocation.
 
@@ -74,52 +74,6 @@ gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate --s
 
 This is the canonical pattern for the bugbot ↔ bugteam convergence loop: walk newest-first, stop at the first clean review.
 
-## What NOT to do
-
-```bash
-# BAD — default 30-item page silently truncates on long PRs
-gh api repos/<owner>/<repo>/pulls/<number>/reviews \
-  --jq '[.[] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
-
-# BAD — `?per_page=100` alone caps at 100 items; PRs with 100+ reviews still truncate
-gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' \
-  --jq '[.[] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
-
-# BAD — --paginate fetches every page, but `--jq` runs PER-PAGE (gh CLI #10459).
-# `sort_by(.submitted_at) | last` operates within each page independently and
-# emits one "latest" per page, not the actual latest across the full result set.
-gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate \
-  --jq '[.[] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
-
-# BAD — taking `| last` on an unpaginated read returns the latest of the first 30,
-# not the actual latest. Same defect for `| reverse | .[0]`.
-```
-
-## Why both defects matter
-
-`gh api`'s default page is the FIRST page of results, ordered oldest-to-newest by the GitHub API. When the result set exceeds 30 items, page 1 contains the OLDEST 30 — not the newest. A jq `| last` after `sort_by(.submitted_at)` picks the latest entry within those 30 oldest items, producing output that looks correct but reports a state from days or weeks ago.
-
-`--paginate` alone does NOT fix this when paired with `--jq`: gh applies the jq filter to each page separately and emits one result per page. A consumer reading "the last line of output" still gets the latest within a single page, not the latest across all pages. The skill that consumes this output then makes decisions (re-trigger bugbot, mark a finding stale, report convergence) against an obsolete view of the PR.
-
-`--paginate --slurp | jq` fixes both defects: every page is fetched, every page is merged into one structure before any jq operator runs, and cross-page operations see the full result set.
-
-## Consumers
-
-Skills and scripts in this repo that read paginated endpoints and must therefore use `--paginate --slurp` plus external `jq`:
-
-- `pr-converge` — bugbot review walk (BUGBOT phase, Step 2.a) and inline-comments fetch (Step 2.b).
-- `bugteam` — review threads, inline comments, audit-loop history.
-- `qbug` — same as bugteam, scoped to a single subagent loop.
-- `pr-review-responder` — review comments fetch (already enforced; this rule extends the same constraint to reviews and other endpoints).
-- `monitor-many` — open-PR enumeration and per-PR review/comment scans.
-- `babysit-pr` — review-comment polling.
-
-Updating any of these to read paginated endpoints requires `--paginate --slurp` plus external `jq` (or a documented single-page bound on a small list).
-
 ## Enforcement
 
 This rule is documentation-only at present. A future PreToolUse hook may pattern-match `Bash` invocations of `gh api repos/.../pulls/<n>/(reviews|comments)` without `--paginate --slurp` (or with `--paginate --jq` doing cross-page operations) and return a corrective message. Until that hook lands, treat this rule as binding by review and rely on it during skill authoring.
-
-## Precedent
-
-The `pr-review-responder` skill predated this rule and forbids default pagination on `pulls/<n>/comments` reads (`packages/claude-dev-env/skills/pr-review-responder/SKILL.md` Rule 1). This file generalizes that constraint to every paginated GitHub endpoint, adds the `--jq` per-page defect (gh CLI #10459) discovered while reviewing this rule, and centralizes the safe patterns so additional skills inherit the rule by reference instead of restating it.

package/rules/no-historical-clutter.md

@@ -0,0 +1,57 @@
+---
+paths: **/*
+---
+
+# No Historical Clutter in Documentation or Comments
+
+**When this applies:** Any Write or Edit to files containing comments or documentation.
+
+**Hook enforcement:** `state-description-blocker` (PreToolUse on Write|Edit) blocks historical/comparative language automatically. See `hooks.json` for registration.
+
+## Rule
+
+Never reference removed implementations, old defaults, prior behaviors, or how something `"used to be"` when updating documentation. The current state is all that matters.
+
+## Examples of prohibited patterns
+
+### In documentation (.md files)
+
+| Pattern | Why it's clutter |
+|---------|-----------------|
+| `` `"instead of 30"` `` in a pagination rule | The old default `no longer` exists in code; the rule reader doesn't need to know what it was |
+| `` `"previously this used X"` `` | If X is gone, it's noise |
+| `` `"before this rule, we did Y"` `` | The rule exists now; the before-state is irrelevant |
+| `` `"migrated from Z to W"` `` | If Z is fully removed, the migration story is git history, not documentation |
+| `` `"the old implementation did A"` `` | If A is gone, the reader gains nothing from knowing it existed |
+| `` `"originally"` `` / `` `"used to be"` `` | Same — dead context |
+
+### In code comments
+
+| Pattern | Good replacement |
+|---------|-----------------|
+| `# Uses X instead of Y` | `# Uses X` |
+| `# Previously configured via Z` | `# Configured via Z` |
+| `# Now uses the new API client` | `# Uses the new API client` |
+| `# No longer supports legacy mode` | `# Supports modern mode only` |
+| `// Switched to async processing` | `// Processes asynchronously` |
+| `# Replaced by the cache layer` | `# Cache layer handles reads` |
+
+### Hook-detected patterns
+
+The `state-description-blocker` hook (PreToolUse on Write\|Edit) enforces these patterns automatically:
+
+`instead of`, `previously`, `now uses/does/handles/supports/names/includes`, `was previously`, `were previously`, `was formerly`, `was added`, `used to`, `no longer`, `has/have been updated/changed`, `replaced by`, `replaces`, `superseded by`, `supersedes`, `changed from`, `changes from`, `switched from/to`, `migrated from/to`, `moved to/into`, `extracted as`, `updated to`, `originally`, `as of`
+
+## What IS allowed
+
+- Comparisons to *currently existing* alternatives (e.g., "use `--paginate --slurp | jq`, not `--jq` alone")
+- Rationale that explains *why* a pattern is wrong in terms of present behavior (e.g., "`--jq` runs per-page, so cross-page operations produce wrong results")
+- References to external sources for defects that still exist (e.g., gh CLI #10459)
+
+## The test
+
+After writing documentation, ask: **"If someone reads this a year from now, with no knowledge of what came before, does every sentence still make sense and add value?"** If a sentence only adds value to someone who knew the old state, delete it.
+
+## Why
+
+Historical references clog context windows and force readers to mentally filter "what was" from "what is." The git log is the authoritative record of what changed and why. Documentation describes the current contract.

package/scripts/config/groq_bugteam_config.py

@@ -22,7 +22,7 @@ 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."
+    "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.
@@ -31,8 +31,13 @@ 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.
+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
@@ -44,6 +49,9 @@ 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
@@ -56,7 +64,7 @@ Respond with JSON only -- no prose outside the JSON object. Shape:
   "findings": [
     {
       "severity": "P0" | "P1" | "P2",
-      "category": "A" | ... | "J",
+      "category": "A" | ... | "K",
       "file": "relative path from repo root",
       "line": int,
       "title": "one-line summary",
@@ -126,7 +134,7 @@ SPEC_IMPLEMENTER_SYSTEM_PROMPT = """<groq_spec_implementer>
 
        - finding_index (int, stable across audit and fix)
        - severity (P0 | P1 | P2)
-       - category (single letter A–J)
+       - 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)

package/skills/bugteam/CONSTRAINTS.md

@@ -1,35 +1,28 @@
-# Bugteam — invariants and design rationale
-
-## Constraints
-
-- **One run per invocation, multi-PR supported.** All PRs in a single /bugteam invocation share one `run_temp_dir`. Per-PR identity lives in the subagent name prefix (`bugfind-pr<N>-loop<L>` / `bugfix-pr<N>-loop<L>`) and the `<run_temp_dir>/pr-<N>/` subfolder containing that PR's git worktree, diff patches, and outcome XML files.
-- **Grant before any spawn, revoke before any return.** Step 0 grants project `.claude/**` permissions; Step 5 revokes. Both are mandatory. Revoke runs on every exit path including error, cap-reached, and stuck.
-- **Fresh subagent per loop.** Both bugfind and bugfix are spawned new each loop. Reusing a subagent across loops accumulates context inside that subagent's window — defeats clean-room.
-- **One up-front confirmation = whole cycle.** The `/bugteam` invocation authorizes the entire cycle; every subsequent decision runs on that single authorization.
-- **10-loop hard cap.** Counted as **AUDIT** completions (increment in Step 3). Standards-fix passes before an audit do not advance `loop_count`. Worst case includes extra clean-coder spawns for the code-rules gate.
-- **Code rules gate before every AUDIT.** Run `_shared/pr-loop/scripts/code_rules_gate.py` (resolved via `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/code_rules_gate.py`) until exit **0** before spawning **bugfind**. Same `validate_content` logic as `hooks/blocking/code_rules_enforcer.py`.
-- **Clean-room audits, every loop.** Each bugfind subagent's spawn prompt contains only the PR scope, audit rubric, and the current loop number. Prior loop history stays in the lead.
-- **Targeted fixes.** Each fix subagent sees ONLY the most recent audit's findings. Prior loops are invisible to the fix subagent.
-- **Opus 4.7 at xhigh effort for both subagents.** Both `Agent(...)` spawns pass `model="opus"`, which resolves to Opus 4.7 on the Anthropic API. Opus 4.7's default effort level in Claude Code is `xhigh` (https://code.claude.com/docs/en/model-config — *"On Opus 4.7, the default effort is `xhigh` for all plans and providers."*), so no `effort` override is needed at spawn time. Effort is set per-subagent in YAML frontmatter, not via the `Agent` tool's parameters; `code-quality-agent` and `clean-coder` rely on the model default. The trade vs Sonnet is higher per-loop cost in exchange for deeper audit recall and stronger fix correctness on bug-hunting work, which the per-PR loop economics tolerate (10-loop hard cap bounds total spend).
-- **Fix subagent receives the latest audit as its input contract.** Passing the audit's findings to the fix subagent is the input contract — each loop's fix run operates on the current audit's output and only that.
-- **One commit per fix action.** Loops produce one commit per loop, not one per bug.
-- **Linear branch, fixed PR base.** Every loop appends one forward-only commit; existing commits and the PR base stay intact throughout the cycle.
-- **Lead-only cleanup.** Cleanup runs in the lead (this session) only. Step 4 removes the full `<run_temp_dir>` so no loop patches leak between runs.
-- **Cleanup all `.bugteam-*` files on exit.** The per-run `<run_temp_dir>` is removed entirely by Step 4, which covers `<run_temp_dir>/pr-<N>/loop-<L>.patch` and `<run_temp_dir>/pr-<N>/loop-<L>-{b,c}.outcomes.xml`. The per-loop outcomes XML at `<worktree_path>/.bugteam-pr<N>-loop<L>.outcomes.xml` is removed with the worktree. Step 4.5 deletes `.bugteam-final.diff`, `.bugteam-original-body.md`, and `.bugteam-final-body.md`. Working directory ends clean.
-- **Audit/fix comment posting.** The bugfind subagent posts ONE per-loop review (parent body + child finding comments in a single batched POST, with review-fallback to a top-level issue comment). The bugfix subagent posts the fix replies after committing. All comment, review, and reply POSTs belong to the subagents; the lead's single PR-write action is the final description rewrite at Step 4.5.
-- **Lead owns the final PR description rewrite only** (Step 4.5), and only via the `pr-description-writer` agent. The lead does not compose the description inline.
+# Bugteam constraints
+
+## Non-Negotiable
+
+- **Pre-flight is mandatory.** `preflight.py` must exit 0 before Step 0. If it fails for `core.hooksPath`, auto-remediate with `fix_hookspath.py`. All other failures require manual fixes.
+- **Looping against a fixed known count.** 10 audit loops hard cap. No exceptions. The cap is a safety value, set high enough to converge on most non-trivial PRs while preventing infinite loops.
+- **`loop_count` is the iteration counter.** It increments before each AUDIT in Step 3. A FIX without a preceding AUDIT does not advance `loop_count`. The `loop_count > 10` check runs before each AUDIT. After 10 AUDITs, the cycle exits regardless of remaining FIX rounds. Standards-fix passes before an audit do not advance `loop_count`.
 - **One review per loop, findings as child comments of that review.** Each loop posts a single pull-request review whose body is the loop header and whose `comments[]` are the anchored findings. Each loop's review stands alone — one review created per loop, fully self-contained on the PR conversation.
 - **PR description rewrite on every exit.** Step 4.5 runs on `converged`, `cap reached`, and `stuck`. On `error`, the rewrite is best-effort; if it fails, surface the error in the final report and continue to revoke.
-- **Outcome XML, not JSON.** Both subagents write structured outcome data (findings or fix outcomes) to `.bugteam-pr<N>-loop<L>.outcomes.xml`. The lead reads these files between actions. XML chosen for parser robustness against multi-line, special-character, and quoted reason fields.
+- **Outcome XML, not JSON.** The AUDIT subagent writes findings to `.bugteam-pr<N>-loop<L>.outcomes.xml` and the FIX subagent writes fix outcomes to `.bugteam-pr<N>-loop<L>.fix-outcomes.xml`. The lead reads these files between actions. Separate paths prevent the FIX output from overwriting the AUDIT's findings file. XML chosen for parser robustness against multi-line, special-character, and quoted reason fields.
 
 ## Why this design
 
-The three sibling skills compose, but `/bugteam` solves a problem they cannot solve in sequence:
+### Why retry with fix — why not just reject and move on
+
+Bugteam's purpose is to make real PRs better before they ship, not to just point out problems. A review that says "fix this bug" without giving the author&#60;subagent&#62; a chance to fix it in the same session would be a weaker intervention — the PR author still has to go back, figure out the fix, apply it, re-push, and re-trigger review. By bundling fix attempts into the same loop, bugteam reduces round-trips from N audits + N manual fix cycles to N audits + N automated fix attempts, with no human context-switching.
+
+### Why 10 loops — why not unlimited
+
+A PR that needs more than 10 audit-fix rounds has deeper problems than bugteam can address. The 10-loop cap is a forcing function: after 10 rounds, escalate to `/findbugs` or human review rather than grinding on diminishing returns.
+
+### Why outcome XML — why not JSON
 
-- `/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.
+JSON escapes `\n` inside `"reason": "could not address: some\nmulti-line\ntext"`, making the file hard to read and grep. XML preserves the raw text as element content, so `&#60;reason&#62;could not address: some&#10;multi-line&#10;text&#60;/reason&#62;` renders legibly in every markdown-capable viewer. The choice is ergonomic, not technical — both formats carry the same information.
 
-`/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 10-loop cap is the safety: pathological cases (audit agent oscillating, fix agent regressing) cannot run away.
+### Why sibling auditor paths diverge (worktree vs temp)
 
-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.
+Only the -a validator writes to the worktree `.bugteam-pr&#60;N&#62;-loop&#60;L&#62;.outcomes.xml` path, which the lead reads. Sibling auditors (-b through -k) write to unique paths under `&#60;run_temp_dir&#62;` to avoid collisions. Without this split, parallel haiku auditors writing to the same path would clobber each other's output, and the lead consuming one path would see only whichever writer finished last.

package/skills/bugteam/EXAMPLES.md

@@ -50,7 +50,7 @@ Claude: [resolves PR #99, runs loop with partial-fix outcomes]
 `Loops: 2`
 `Unresolved findings (2): src/auth.py:45 (P1: file is generated, cannot edit); src/legacy.py:200 (P1: rewrite scope exceeds the bug)`
 
-The bugfix teammate writes one outcome per finding to `.bugteam-loop-2.outcomes.xml`. Findings with `status=could_not_address` carry their `<reason>` text, and the teammate posts a matching reply to each finding comment so the reviewer sees why each bug stayed open.
+The bugfix teammate writes one outcome per finding to `.bugteam-pr99-loop2.fix-outcomes.xml`. Findings with `status=could_not_address` carry their `<reason>` text, and the teammate posts a matching reply to each finding comment so the reviewer sees why each bug stayed open.
 </example>
 
 <example>