claude-dev-env 1.37.1 → 1.38.1

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.1",
+    "version": "1.38.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/no-historical-clutter.md

@@ -1,25 +1,46 @@
 ---
-paths: **/*.md
+paths: **/*
 ---
 
-# No Historical Clutter in Documentation
+# No Historical Clutter in Documentation or Comments
 
-**When this applies:** Any Write or Edit to `.md` files.
+**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.
+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 |
+| `` `"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
 

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 validator and fix subagents.** Single-auditor mode, validator, and fix spawns pass `model="opus"`; parallel-auditor siblings (`-b` through `-k`) pass `model="haiku"`. 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>-<letter>.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>