claude-dev-env 1.36.1 → 1.37.0

package/hooks/blocking/test_code_rules_enforcer_unused_imports.py

@@ -165,7 +165,7 @@ def test_should_flag_each_unused_in_multi_import() -> None:
     )
 
 
-def test_should_not_flag_when_referenced_in_string_annotation() -> None:
+def test_should_not_flag_when_referenced_in_annotation() -> None:
     source = (
         "from typing import List\n\ndef run(xs: List[int]) -> None:\n    return None\n"
     )
@@ -242,3 +242,159 @@ def test_should_skip_star_import() -> None:
     assert issues == [], (
         f"Star imports cannot be meaningfully tracked - skip to avoid false positives, got: {issues}"
     )
+
+
+def test_should_flag_when_name_only_appears_in_comment() -> None:
+    source = (
+        "import json\n"
+        "\n"
+        "# json reserved for later\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert any("json" in each_issue for each_issue in issues), (
+        f"Mentions in comments must not count as references, got: {issues}"
+    )
+
+
+def test_should_not_skip_when_type_checking_only_in_string_constant() -> None:
+    source = (
+        'from config.constants import UNUSED_NAME\n'
+        '\n'
+        'HELP_TEXT = "See TYPE_CHECKING docs"\n'
+        '\n'
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert any("UNUSED_NAME" in each_issue for each_issue in issues), (
+        f"Substring TYPE_CHECKING in prose must not skip the scan, got: {issues}"
+    )
+
+
+def test_should_flag_when_noqa_lists_only_non_f401_codes() -> None:
+    source = (
+        "from config.constants import UNUSED  # noqa: E402\n"
+        "\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert any("UNUSED" in each_issue for each_issue in issues), (
+        f"E402-only noqa must not suppress unused-import findings, got: {issues}"
+    )
+
+
+def test_should_skip_when_noqa_is_bare() -> None:
+    source = (
+        "from config.constants import UNUSED  # noqa\n"
+        "\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Bare noqa must suppress unused import, got: {issues}"
+
+
+def test_should_flag_import_when_only_shadowed_local_name_is_loaded() -> None:
+    source = (
+        "import json\n"
+        "\n"
+        "def run(json: object) -> object:\n"
+        "    return json\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert any("json" in each_issue for each_issue in issues), (
+        f"Local shadow bindings must not count as import references, got: {issues}"
+    )
+
+
+def test_should_skip_when_type_checking_uses_imported_alias() -> None:
+    source = (
+        "from typing import TYPE_CHECKING as IS_TYPE_CHECKING\n"
+        "from config.constants import UNUSED_NAME\n"
+        "\n"
+        "if IS_TYPE_CHECKING:\n"
+        "    from somewhere import OtherName\n"
+        "\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"TYPE_CHECKING imported aliases must skip annotation-only files, got: {issues}"
+    )
+
+
+def test_should_skip_when_type_checking_uses_module_alias() -> None:
+    source = (
+        "import typing as t\n"
+        "from config.constants import UNUSED_NAME\n"
+        "\n"
+        "if t.TYPE_CHECKING:\n"
+        "    from somewhere import OtherName\n"
+        "\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"TYPE_CHECKING module aliases must skip annotation-only files, got: {issues}"
+    )
+
+
+def test_should_not_flag_when_referenced_in_quoted_annotation() -> None:
+    source = (
+        "from typing import List\n"
+        "\n"
+        "def run(xs: \"List[int]\") -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Quoted annotations must count as import references, got: {issues}"
+    )
+
+
+def test_should_flag_when_noqa_only_appears_inside_string_literal() -> None:
+    source = (
+        "from config.constants import UNUSED; MARKER = '# noqa: F401'\n"
+        "\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert any("UNUSED" in each_issue for each_issue in issues), (
+        f"String literal noqa text must not suppress unused imports, got: {issues}"
+    )
+
+
+def test_should_not_flag_when_class_body_binding_matches_import_used_in_method() -> None:
+    source = (
+        "import os\n"
+        "\n"
+        "class Foo:\n"
+        "    os = 'linux'\n"
+        "\n"
+        "    def bar(self) -> str:\n"
+        "        return os.path.join('a', 'b')\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Class body bindings must not shadow module-level imports inside methods, got: {issues}"
+    )
+
+
+def test_should_not_flag_when_comprehension_variable_matches_import_used_after() -> None:
+    source = (
+        "import os\n"
+        "\n"
+        "def run() -> str:\n"
+        "    result = [x for os in [1, 2, 3]]\n"
+        "    return os.path.join('a', 'b')\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Comprehension iteration variables must not shadow enclosing scope bindings, got: {issues}"
+    )

package/hooks/config/test_unused_module_import_constants.py

@@ -0,0 +1,48 @@
+"""Tests for unused module import constants."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_HOOKS_ROOT = Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from config.unused_module_import_constants import line_suppresses_unused_import_via_noqa
+
+
+def test_line_suppresses_bare_noqa() -> None:
+    assert line_suppresses_unused_import_via_noqa(
+        "from x import y  # noqa"
+    )
+
+
+def test_line_suppresses_noqa_with_f401_code() -> None:
+    assert line_suppresses_unused_import_via_noqa(
+        "from x import y  # noqa: F401"
+    )
+
+
+def test_line_suppresses_noqa_with_mixed_codes_including_f401() -> None:
+    assert line_suppresses_unused_import_via_noqa(
+        "from x import y  # noqa: E402, F401"
+    )
+
+
+def test_line_does_not_suppress_noqa_with_only_non_f401_codes() -> None:
+    assert not line_suppresses_unused_import_via_noqa(
+        "from x import y  # noqa: E402"
+    )
+
+
+def test_line_does_not_suppress_without_noqa() -> None:
+    assert not line_suppresses_unused_import_via_noqa(
+        "from x import y  # type: ignore"
+    )
+
+
+def test_line_does_not_suppress_noqa_inside_string_literal() -> None:
+    assert not line_suppresses_unused_import_via_noqa(
+        "from x import y; marker = '# noqa: F401'"
+    )

package/hooks/config/unused_module_import_constants.py

@@ -1,7 +1,48 @@
 """Constants for the unused module-level import scan in ``code_rules_enforcer``."""
 
+import io
+import re
+import tokenize
+
+PYFLAKES_UNUSED_IMPORT_RULE_CODE: str = "F401"
+NOQA_DIRECTIVE_PATTERN: re.Pattern[str] = re.compile(
+    r"#\s*noqa\b(?:\s*:\s*([^\n#]+))?",
+    re.IGNORECASE,
+)
 MAX_UNUSED_IMPORT_ISSUES: int = 25
 UNUSED_IMPORT_GUIDANCE: str = (
     "remove unused import; if kept for side effects, mark with `# noqa: F401`"
 )
 TYPE_CHECKING_IDENTIFIER: str = "TYPE_CHECKING"
+ALL_TYPING_MODULE_NAMES: frozenset[str] = frozenset({"typing", "typing_extensions"})
+
+
+def _comment_text_from_line(line_text: str) -> str | None:
+    try:
+        for each_token in tokenize.generate_tokens(io.StringIO(line_text).readline):
+            if each_token.type == tokenize.COMMENT:
+                return each_token.string
+    except tokenize.TokenError:
+        return None
+    return None
+
+
+def line_suppresses_unused_import_via_noqa(line_text: str) -> bool:
+    """Return True only for bare ``# noqa`` / ``#noqa`` or a code list that includes F401."""
+    comment_text = _comment_text_from_line(line_text)
+    if comment_text is None:
+        return False
+    match = NOQA_DIRECTIVE_PATTERN.search(comment_text)
+    if match is None:
+        return False
+    codes_part = match.group(1)
+    if codes_part is None or not codes_part.strip():
+        return True
+    for each_fragment in codes_part.split(","):
+        stripped = each_fragment.strip()
+        if not stripped:
+            continue
+        first_token = stripped.split()[0]
+        if first_token.upper() == PYFLAKES_UNUSED_IMPORT_RULE_CODE:
+            return True
+    return False

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.36.1",
+    "version": "1.37.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -19,6 +19,7 @@
         "hooks/",
         "system-prompts/",
         "scripts/",
+        "_shared/",
         "CLAUDE.md"
     ],
     "keywords": [

package/skills/bg-agent/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: bg-agent
+description: Delegates a task to a background agent. Invoked as "bg-agent [task to do]". Claude picks a suitable agent type from the available agents list and spawns it via Agent with run_in_background: true. Triggers on "/bg-agent", "bg-agent", "background agent for this".
+---
+
+# bg-agent
+
+## Overview
+
+Delegates a task to a background agent so the main session can continue without waiting. This is the programmatic invocation path for background work — other skills (e.g. gotcha) and the user can both invoke it.
+
+**Announce at start:** "Delegating to a background agent: `<one-line summary of task>`."
+
+## Instructions
+
+### Step 1 — Parse the task
+
+The user (or calling skill) provides a task description after `bg-agent`. Example:
+
+```
+bg-agent add a gotcha to the rebase skill about force-push lease format
+```
+
+Extract the full task description from the arguments.
+
+### Step 2 — Select the right agent
+
+Review the available agent types (listed in the system prompt's Agent tool description) and pick the most suitable one for the task:
+
+- **Read-only tasks** (research, search, exploring code) → Explore agent or general-purpose agent.
+- **Code authoring tasks** (writing/editing skill files, creating PRs) → general-purpose agent with `run_in_background: true`.
+- **Specialized tasks** → pick the agent whose description best matches the task. For example, use `pr-description-writer` for PR descriptions, `git-commit-crafter` for commits.
+
+If no specialized agent fits, use the general-purpose agent.
+
+### Step 3 — Spawn the background agent
+
+Use the `Agent` tool with `run_in_background: true`. Write a self-contained prompt that:
+
+- States the exact goal and expected output.
+- Lists the files or directories involved (from the caller's context).
+- Includes any constraints (do not create a PR, do not push, etc.).
+- Specifies what success looks like.
+
+Example for a gotcha-adding task:
+
+```
+Agent({
+  description: "Add gotcha to skill file",
+  prompt: "Add a gotcha entry to packages/claude-dev-env/skills/rebase/SKILL.md. The gotcha is: 'force-push --force-with-lease requires the full <branch>:<sha> format, not just the branch name.' Add it under the ## Gotchas section. If no ## Gotchas section exists, create one at the bottom of the file.",
+  subagent_type: "general-purpose",
+  run_in_background: true
+})
+```
+
+### Step 4 — Report spawn
+
+Confirm the agent was spawned and state its task in one sentence. The caller does not need to wait for completion — background agents notify on completion automatically.
+
+## Constraints
+
+- Always use `run_in_background: true`. This skill is specifically for background delegation.
+- Never run the task inline in the main session. The point is to offload it.
+- If the task requires a PR, the spawned agent handles the full flow (branch → commit → push → PR).
+- Return control to the caller immediately after spawning. Do not poll for completion.
+
+## Gotchas
+
+See the gotcha reference at the bottom of this file. When a new gotcha is discovered during use, invoke `/gotcha` to add it here.

package/skills/bugteam/CONSTRAINTS.md

@@ -1,35 +1,26 @@
 # Bugteam — invariants and design rationale
 
-## Path A vs Path B
-
-**Path A** (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`): the constraints below apply as written — `TeamCreate`, isolated teammate sessions, lead-only `TeamDelete`. **Path B** (Task harness): read [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md) for harness-only steps; **agent types** (`code-quality-agent`, `clean-coder`), **models**, **one commit per fix**, **gate-before-AUDIT**, **10-loop cap**, and **outcome XML** remain identical to `SKILL.md`. Path B intentionally uses **`Task`** from the lead instead of teammate isolation — see that file **Clean-room note**.
-
 ## Constraints
 
-- **Path A — agent teams required, not parallel subagents from the lead without `TeamCreate`.** On Path A, the skill MUST use Claude Code's agent teams feature (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). Spawning `code-quality-agent` and `clean-coder` as parallel **Agents** with `team_name` from the lead is the supported pattern. Spawning ad-hoc `generalPurpose` workers in place of those roles = fail. **Path B** does not use `TeamCreate`; it uses **`Task`** carrying the same Path A spawn contracts per [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md) (AUDIT/FIX spawn; when the host rejects `subagent_type="clean-coder"`, apply **Path B — Cursor `Task` registry**). Not a substitute for skipping `code-quality-agent` / `clean-coder` work.
-- **Path B — Cursor `Task` registry.** When the host `Task` tool rejects `subagent_type="clean-coder"`, Path B FIX MUST use `subagent_type: "generalPurpose"` plus the mandatory **Read** of `clean-coder.md` in the FIX prompt per [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md) (FIX spawn, Cursor host split). This is the documented shim, not an ad-hoc `generalPurpose` bypass of the clean-coder contract.
-- **Path A — orchestrator-only `TeamCreate`.** Only the lead session (this session, when `/bugteam` is invoked) calls `TeamCreate`. Teammates never call `TeamCreate` — if a teammate's spawn prompt instructs it to, that is a skill defect. When additional parallel work is needed (e.g., parallel auditors from loop 4 onward, supplementary audit of adjacent files), the lead spawns additional teammates into the EXISTING team by passing the current `team_name` to every `Agent(...)` call. Multiple teammate "sets" live inside one team under one orchestrator. The runtime enforces this: `TeamCreate` called while the session already leads a team returns the error `Already leading team "<name>". A leader can only manage one team at a time. Use TeamDelete to end the current team before creating a new one.` — direct quote from the runtime's response when this invariant is violated. The Step 2 lifecycle resolution in [Team lifecycle](SKILL.md#team-lifecycle-path-a-only) parses this exact error in `auto` mode to attach to the existing team rather than fail. **Path B:** no `TeamCreate`; parallel work uses parallel **`Task`** calls per [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md).
-- **One team per invocation, multi-PR supported.** All PRs in a single /bugteam invocation share one team created by the orchestrator. Per-PR identity lives in the teammate name prefix (`bugfind-pr<N>-loop<L>` / `bugfix-pr<N>-loop<L>`) and the `<team_temp_dir>/pr-<N>/` subfolder containing that PR's git worktree, diff patches, and outcome XML files.
+- **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 teammate per loop.** Both bugfind and bugfix are spawned new each loop and shut down after their action. Reusing a teammate across loops accumulates context inside that teammate's window — defeats clean-room.
+- **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 teammate'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 teammate sees ONLY the most recent audit's findings. Prior loops are invisible to the fix teammate.
-- **Opus 4.7 at xhigh effort for both teammates.** 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 teammate receives the latest audit as its input contract.** Passing the audit's findings to the fix teammate is the input contract — each loop's fix run operates on the current audit's output and only that.
+- **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, gated by `team_owned`.** Per the docs: *"Always use the lead to clean up. Teammates should not run cleanup because their team context may not resolve correctly, potentially leaving resources in an inconsistent state."* This session is the lead, and cleanup runs here only. Step 4 calls `TeamDelete` **only when `team_owned == true`** (this invocation called `TeamCreate` itself). When `team_owned == false` (lifecycle `attach`, or `auto` after the runtime's `Already leading team` fallback), the orchestrator that originally created the team owns teardown — see [Team lifecycle](SKILL.md#team-lifecycle-path-a-only).
-- **Orchestrators must use `attach` mode, not `owned`.** When `/bugteam` runs inside an orchestrator that is itself managing a long-lived team across PRs (`pr-converge` multi-PR mode, `monitor-open-prs`), the orchestrator passes `BUGTEAM_TEAM_LIFECYCLE=attach` and `BUGTEAM_TEAM_NAME=<existing>`. `owned` mode under such an orchestrator would either error out (the session already leads a team) or, worse, tear down the orchestrator's team mid-sweep on the first invocation's Step 4. `auto` is the safe default for ambiguous callers; `attach` is the explicit-orchestrator contract.
-- **Cleanup the per-team scoped temp directory on exit, gated by `team_owned`.** When `team_owned == true`, the resolved `<team_temp_dir>` is removed entirely so no loop patches leak between runs. When `team_owned == false`, only this invocation's per-PR subfolders (`<team_temp_dir>/pr-<N>/`) are removed; the orchestrator-owned parent stays so the next attached invocation can write its own per-PR subfolders without colliding.
-- **Cleanup all `.bugteam-*` files on exit.** `.bugteam-loop-*.patch`, `.bugteam-loop-*.outcomes.xml`, `.bugteam-final.diff`, `.bugteam-original-body.md`, `.bugteam-final-body.md`. Working directory ends clean.
-- **Audit/fix comment posting.** **Path A:** Bugfind posts ONE per-loop review (parent body + child finding comments in a single batched POST, with review-fallback to a top-level issue comment). Bugfix posts the fix replies after committing. All comment, review, and reply POSTs belong to the teammates; the lead's single PR-write action is the final description rewrite at Step 4.5. **Path B:** the **lead** performs the same POSTs after Task handoffs (`SKILL.md` Step 2.5 + [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md) § Step 2.5).
+- **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.
 - **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 teammates write structured outcome data (findings or fix outcomes) to `.bugteam-loop-<N>.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.** 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.
 
 ## Why this design
 

package/skills/bugteam/PROMPTS.md

@@ -18,7 +18,7 @@ Keep the spawn prompt self-contained: reference only the PR scope, audit rubric,
 cd into `<worktree_path>` before any git, gh, or file operation.
 
 <scope>
-  <diff_path>Absolute path to the per-PR patch file: <team_temp_dir>/pr-<N>/loop-<L>.patch (same path as gh pr diff redirect in AUDIT)</diff_path>
+  <diff_path>Absolute path to the per-PR patch file: <run_temp_dir>/pr-<N>/loop-<L>.patch (same path as gh pr diff redirect in AUDIT)</diff_path>
   <scope_rule>Audit only lines added or modified in the diff. Pre-existing code on untouched lines is out of scope.</scope_rule>
 </scope>
 
@@ -76,8 +76,8 @@ cd into `<worktree_path>` before any git, gh, or file operation.
 </comment_posting>
 
 <output_format>
-  Write the outcome XML below to .bugteam-pr<N>-loop<L>.outcomes.xml inside
-  the PR's worktree directory (<worktree_path>). Return only that path on stdout. The schema:
+  For the primary (-a) auditor: write the outcome XML below to .bugteam-pr<N>-loop<L>.outcomes.xml inside
+  the PR's worktree directory (<worktree_path>). For sibling auditors (-b/-c): write to <run_temp_dir>/pr-<N>/loop-<L>-{b,c}.outcomes.xml (absolute path passed in prompt). Return only that path on stdout. The schema:
 </output_format>
 ```