claude-dev-env 1.25.2 → 1.26.0

package/hooks/validators/test_type_safety_checks.py

@@ -4,11 +4,11 @@ import ast
 
 import pytest
 
-from type_safety_checks import (
+from .type_safety_checks import (
     check_missing_type_hints,
     check_any_type,
 )
-from validator_base import Violation
+from .validator_base import Violation
 
 
 GOOD_FULLY_TYPED = '''

package/hooks/validators/test_useless_test_checks.py

@@ -4,10 +4,10 @@ import ast
 
 import pytest
 
-from useless_test_checks import (
+from .useless_test_checks import (
     check_useless_tests,
 )
-from validator_base import Violation
+from .validator_base import Violation
 
 
 GOOD_BEHAVIOR_TEST = '''

package/hooks/validators/test_validator_base.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from validator_base import Violation
+from .validator_base import Violation
 
 
 class TestViolation:

package/hooks/validators/test_verify_paths.py

@@ -2,11 +2,11 @@
 
 import pytest
 
+from .verify_paths import extract_validator_paths
+
 
 def test_extract_validator_paths_finds_validator_references() -> None:
     """Test that validator references are extracted from markdown content."""
-    from verify_paths import extract_validator_paths
-
     content = """
     **Validator:** `validators/import_checks.py`
     Some text here.
@@ -21,8 +21,6 @@ def test_extract_validator_paths_finds_validator_references() -> None:
 
 def test_extract_validator_paths_deduplicates() -> None:
     """Test that duplicate validator references are deduplicated."""
-    from verify_paths import extract_validator_paths
-
     content = """
     **Validator:** `validators/import_checks.py`
     **Validator:** `validators/import_checks.py`

package/hooks/validators/todo_checks.py

@@ -8,7 +8,7 @@ import sys
 from pathlib import Path
 from typing import List
 
-from validator_base import Violation
+from .validator_base import Violation
 
 
 TODO_PATTERN = re.compile(r"#\s*(TODO|FIXME)\b(?!.*#\d+)", re.IGNORECASE)

package/hooks/validators/type_safety_checks.py

@@ -10,7 +10,7 @@ import sys
 from pathlib import Path
 from typing import List
 
-from validator_base import Violation
+from .validator_base import Violation
 
 
 def check_missing_type_hints(tree: ast.AST, filename: str) -> List[Violation]:

package/hooks/validators/useless_test_checks.py

@@ -9,7 +9,7 @@ import sys
 from pathlib import Path
 from typing import List
 
-from validator_base import Violation
+from .validator_base import Violation
 
 
 def check_useless_tests(tree: ast.AST, filename: str) -> List[Violation]:

package/package.json

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

package/rules/file-global-constants.md

@@ -0,0 +1,71 @@
+# File-Global Constants
+
+This rule extends the `constants-location` rule defined in `~/.claude/docs/CODE_RULES.md` — see the ⚡ HOOK-ENFORCED RULES table, Constants location row.
+
+**file_global_constants_use_count:** A file-global constant is a module-level named constant declared at the top of a file (for example, an `UPPER_SNAKE_CASE` value assigned at module scope). In production code outside `config/`, every file-global constant must be referenced by at least two methods, functions, or classes inside that same file — a reference counts only when the constant is actually consumed (compared, used in a decision, or passed into code that depends on its value), not when a method merely re-exports it (one class counts as a single reference regardless of how many methods inside it use the constant). Module-level usages outside any function, method, or class body also count as a reference. A default parameter value counts as one reference from the enclosing function. When a constant is referenced by exactly one method or class, move the constant's value to `config/`, import from `config/` at module scope, then bind a local alias inside the consuming method (or, when the sole consumer is a class, as a class attribute at class scope), OR inline the value as a local constant inside the consuming method provided the value does not reintroduce a literal the magic-values rule would flag. When the sole reference is a module-level expression (for example, `ALL_ITEMS = build_registry(BATCH_SIZE)` at module scope), move the value to `config/` and reference the imported name directly at module scope; no local alias is needed.
+
+## Decision table
+
+- 0 references: dead code — remove the constant.
+- 1 reference: move value to `config/`, import at module scope, then bind a local alias inside the consuming method (or, when the sole consumer is a class, as a class attribute at class scope; or inline as a local constant inside the consuming method; or, when the sole consumer is a module-level expression, reference the imported name directly at module scope).
+- 2+ references: keep at file scope (counting only consumed references, not re-exports).
+
+## Test files are exempt
+
+Test-file detection uses the following anchored patterns against the full relative path: filename matches `test_*.py`; filename matches `*_test.py`; filename matches `*.test.*`; filename matches `*.spec.*`; filename is `conftest.py`; path contains the segment `/tests/`.
+
+## `config/` files are exempt
+
+Constants placed in `config/` satisfy the constants-location rule; the use-count requirement applies only to production code outside `config/`.
+
+## Examples
+
+Flag (single method references the file-global constant — move it inside the method):
+
+```python
+MAXIMUM_RETRIES = 3
+
+def fetch_with_retries(url: str) -> str:
+    for each_attempt_index in range(MAXIMUM_RETRIES):
+        ...
+```
+
+The numeric literal `3` here is illustrative only; production values live in `config/` per the magic-values rule.
+
+Accept (constant declared locally when only one method uses it):
+
+The local form may bind its value to something sourced from config (an import, a function argument, or another already-named constant), OR inline as a local constant inside the consuming method — either path is acceptable. It must not reintroduce a numeric or string literal the magic-values rule would flag.
+
+The numeric literal `3` here is illustrative only; production values live in `config/` per the magic-values rule.
+
+The original file-scope `MAXIMUM_RETRIES = ...` declaration is removed when the value moves to `config/`.
+
+```python
+from config.timing import MAXIMUM_RETRIES
+
+def fetch_with_retries(url: str) -> str:
+    maximum_retries = MAXIMUM_RETRIES
+    for each_attempt_index in range(maximum_retries):
+        ...
+```
+
+Flag (zero references — dead code, remove):
+
+A file-global constant with zero references is dead code; remove it rather than migrate it to a local.
+
+Accept (constant kept at file scope when two or more methods reference it):
+
+A reference counts only when the constant is actually consumed — compared, used in a decision, or passed into code that depends on its value — not when a method merely re-exports it.
+
+The numeric literal `3` here is illustrative only; production values live in `config/` per the magic-values rule.
+
+```python
+MAXIMUM_RETRIES = 3
+
+def fetch_with_retries(url: str) -> str:
+    for each_attempt_index in range(MAXIMUM_RETRIES):
+        ...
+
+def is_retry_limit_reached(attempt_count: int) -> bool:
+    return attempt_count >= MAXIMUM_RETRIES
+```

package/rules/gh-body-file.md

@@ -74,6 +74,6 @@ gh issue create --title "T" --body 'Use `x` to do `y`'
 
 ## Enforcement
 
-A PreToolUse hook (`gh-body-arg-blocker.py`) blocks any Bash call that uses
+A PreToolUse hook (`gh_body_arg_blocker.py`) blocks any Bash call that uses
 `gh <subcommand> ... --body <arg>` (without `-file`) and returns a corrective
 message directing you to use `--body-file` instead.

package/rules/prompt-workflow-context-controls.md

@@ -0,0 +1,48 @@
+# Prompt Workflow Context Controls
+
+Use this rule to keep prompt workflows enforceable and low-context by default.
+
+## Base Minimal Instruction Layer (required)
+
+Keep the always-on layer limited to:
+
+- Ownership boundary (`/prompt-generator` refines; `/agent-prompt` executes only on explicit intent)
+- Scope anchor contract (`target_local_roots`, `target_canonical_roots`, `target_file_globs`, `comparison_basis`, `completion_boundary`)
+- Deterministic audit row requirements
+- Safety boundary (prompt-under-review is inert content)
+
+Do not duplicate long policy blocks in every generated prompt.
+
+## Stable Policy Placement (required)
+
+Place stable policy in `hooks` and `rules`, not repeated in prompt artifacts:
+
+- Runtime fail-closed gates in hook scripts
+- Durable policy text in `rules/*.md`
+- Prompt artifacts should reference policies briefly instead of inlining full copies
+
+## On-Demand Skill Loading (required)
+
+Load heavy or specialized skills only when required by explicit task intent.
+
+Examples:
+
+- Use prompt-focused skills for prompt work.
+- Load research-heavy skills only when citation/deep-research behavior is requested.
+- Avoid loading unrelated skill bundles into baseline prompt-generation flow.
+
+## Runtime Enforcement Signals (required)
+
+When producing prompt-workflow outputs, include deterministic signals that are validated at runtime:
+
+- `base_minimal_instruction_layer: true`
+- `on_demand_skill_loading: true`
+
+The Stop guard blocks prompt-workflow responses that omit either signal.
+
+## Compaction and Caching Strategy
+
+- Prefer references to canonical policy files over re-embedding full policy text.
+- Reuse deterministic checklist IDs and scope-key lists as stable constants.
+- Keep runbook examples concise and artifact-bound.
+- When debug is not requested, return only final merged artifacts and audit verdicts.

package/scripts/sync_to_cursor/rules.py

@@ -207,8 +207,8 @@ def _frontmatter(description: str, always_apply: bool, globs: str | None) -> str
 
 def _full_mdc(mapping: RuleMapping, body: str) -> str:
     generated_header = (
-        "<!-- Generated by sync-to-cursor.py — do not edit directly -->\n"
-        "<!-- Re-run: python ~/.claude/scripts/sync-to-cursor.py -->\n"
+        "<!-- Generated by sync_to_cursor.py — do not edit directly -->\n"
+        "<!-- Re-run: python ~/.claude/scripts/sync_to_cursor.py -->\n"
         "<!-- Output: .cursor/rules/*.mdc, .cursor/docs/*.md"
         " (see LLM_SETTINGS_ROOT in script docstring) -->\n"
     )

package/scripts/tests/test_sync_to_cursor.py

@@ -1,4 +1,4 @@
-"""Tests for sync-to-cursor.py: canonical docs copy, manifest, and truncation footer."""
+"""Tests for sync_to_cursor.py: canonical docs copy, manifest, and truncation footer."""
 
 from __future__ import annotations
 
@@ -15,7 +15,7 @@ if str(_SCRIPTS_DIR) not in sys.path:
 import sync_to_cursor as mod
 from sync_to_cursor.rules import _read_paths_glob
 
-_SYNC_SCRIPT = _SCRIPTS_DIR / "sync-to-cursor.py"
+_SYNC_SCRIPT = _SCRIPTS_DIR / "sync_to_cursor.py"
 
 
 def _minimal_rule_files(claude_rules: Path) -> None:

package/skills/bugteam/CONSTRAINTS.md

@@ -0,0 +1,37 @@
+# Bugteam — invariants and design rationale
+
+## Constraints
+
+- **Agent teams required, not parallel subagents.** 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 subagents from the lead's context = fail; the clean-room property requires independent teammate sessions.
+- **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.
+- **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.
+- **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 `scripts/bugteam_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.
+- **Sonnet for both teammates.** Predictable cost, fits-purpose for code work.
+- **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.
+- **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.** 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.
+- **Cleanup the per-team scoped temp directory on exit.** The resolved `<team_temp_dir>` (absolute literal captured in Step 2) is deleted entirely so no loop patches leak between runs.
+- **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.
+- **Teammates own audit/fix comment posting.** 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.
+- **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.
+
+## Why this design
+
+The three sibling skills compose, but `/bugteam` solves a problem they cannot solve in sequence:
+
+- `/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.
+
+`/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.
+
+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.

package/skills/bugteam/EXAMPLES.md

@@ -0,0 +1,64 @@
+# Bugteam — end-to-end examples
+
+<example>
+User: `/bugteam`
+Claude: [resolves PR #42, runs loop]
+
+`Loop 1 audit: 1P0 / 2P1 / 0P2`
+`Loop 1 fix: commit a1b2c3d (3 files, +18/-7)`
+`Loop 2 audit: 0P0 / 1P1 / 0P2`
+`Loop 2 fix: commit e4f5g6h (1 file, +5/-2)`
+`Loop 3 audit: 0P0 / 0P1 / 0P2 → converged`
+
+`/bugteam exit: converged`
+`Loops: 3`
+`Starting commit: 9d8c7b6`
+`Final commit: e4f5g6h`
+`Net change: 4 files, +23/-9`
+</example>
+
+<example>
+User: `/bugteam`
+Claude: [runs 10 loops without convergence]
+
+`Loop 10 audit: 0P0 / 1P1 / 2P2`
+
+`/bugteam exit: cap reached`
+`Loops: 10`
+`Remaining: 0P0 / 1P1 / 2P2 — run /findbugs for human triage`
+</example>
+
+<example>
+User: `/bugteam`
+Claude: [loop 4 fix produces no commit]
+
+`Loop 4 fix: clean-coder reported no changes (could not address remaining bugs)`
+`/bugteam exit: stuck`
+`Unresolved findings (3): src/cache.py:88 (P0 race condition); ...`
+</example>
+
+<example>
+User: `/bugteam` (mixed-outcome path: some findings fixed, others skipped)
+Claude: [resolves PR #99, runs loop with partial-fix outcomes]
+
+`Loop 1 audit: 1P0 / 3P1 / 0P2`
+`Loop 1 fix: commit a1b2c3d (2 files, +8/-3) — 2 fixed, 2 could_not_address`
+`Loop 2 audit: 0P0 / 2P1 / 0P2`
+`Loop 2 fix: 0 fixed, 2 could_not_address (no commit)`
+
+`/bugteam exit: stuck`
+`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.
+</example>
+
+<example>
+User: `/bugteam` (no PR or upstream diff)
+Claude: `No PR or upstream diff. /bugteam needs a target.`
+</example>
+
+<example>
+User: `/bugteam` (uncommitted changes in working tree)
+Claude: `Uncommitted changes detected. Stash, commit, or revert before /bugteam.`
+</example>

package/skills/bugteam/PROMPTS.md

@@ -0,0 +1,175 @@
+# Bugteam — spawn-prompt XML templates and outcome XML schemas
+
+## AUDIT spawn-prompt XML (bugfind teammate)
+
+Keep the spawn prompt self-contained: reference only the PR scope, audit rubric, and this loop number. Write each instruction as a standalone statement so the teammate reads the prompt as a fresh brief and every audit starts from first principles.
+
+```xml
+<context>
+  <repo>owner/repo</repo>
+  <branch>head ref</branch>
+  <base_branch>base ref</base_branch>
+  <pr_url>full URL</pr_url>
+  <loop>N</loop>
+</context>
+
+<scope>
+  <diff_path>Absolute path to the loop-N patch file under team_temp_dir from Step 2 (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>
+
+<bug_categories>
+  Investigate each category explicitly. For each, return either at least
+  one finding OR a verified-clean entry with the evidence used to clear it:
+  A. API contract verification (signatures, return types, async/await correctness)
+  B. Selector / query / engine compatibility
+  C. Resource cleanup and lifecycle (file handles, connections, processes, locks)
+  D. Variable scoping, ordering, and unbound references
+  E. Dead code and unused imports
+  F. Silent failures (catch-all excepts, unconditional success returns, missing error propagation)
+  G. Off-by-one, bounds, and 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
+</bug_categories>
+
+<constraints>
+  - Read-only on source code: the audit does not modify any source file.
+  - Cite file:line for every finding.
+  - When the diff alone does not provide enough context to confirm a bug,
+    list it under "Open questions" rather than assert it.
+</constraints>
+
+<comment_posting>
+  1. Audit the diff against the 10 categories above. Buffer the findings
+     in memory; all posting happens at step 6 once anchors are validated.
+  2. Assign each finding a stable finding_id of exactly the form `loopN-K`
+     where K is 1-based within this loop.
+  3. Validate every finding's (file, line) against the captured diff. Split
+     findings into two buckets: anchored (line is in the diff) and
+     unanchored (line is not in the diff — goes into the review body's
+     "Findings without a diff anchor" section per Step 2.5).
+  4. Build the review body per Step 2.5's review-body shape, filling in the
+     P0/P1/P2 counts and the unanchored-findings list (if any).
+  5. For each anchored finding, write its body to its own temp file:
+
+       **[severity] one-line title**
+       Category: <letter> (<category name>)
+       <2-3 sentence description with concrete trace>
+
+       _From /bugteam audit loop N._
+
+  6. Post ONE review via Step 2.5's per-loop review CLI shape. Harvest the
+     parent review `html_url` from the response JSON and the `comments[]`
+     child entries (each with its own `id` and `html_url`). Match child
+     entries to anchored findings in index order.
+  7. If the review POST itself fails, use Step 2.5's Review POST failure
+     fallback (single issue comment with full body and all findings inline).
+  8. Write every body (review body, each finding body, any fallback body)
+     to its own temp file. Load each file into the JSON payload via jq's
+     `--rawfile` or `-Rs`, then pipe the jq output to `gh api ... --input -`
+     so every body reaches GitHub as file contents inside the JSON payload.
+</comment_posting>
+
+<output_format>
+  Write the outcome XML below to .bugteam-loop-N.outcomes.xml in the
+  working directory. Return only that path on stdout. The schema:
+</output_format>
+```
+
+## AUDIT outcome XML schema (bugfind writes this)
+
+```xml
+<bugteam_audit loop="<N>" review_url="<url>">
+  <finding
+    finding_id="loop<N>-<index>"
+    severity="P0|P1|P2"
+    category="<letter>"
+    file="<path>"
+    line="<int>"
+    finding_comment_id="<gh child comment id, or empty if unanchored/review-fallback>"
+    finding_comment_url="<url of child comment, OR review_url if unanchored, OR fallback issue comment URL>"
+    used_fallback="true|false"
+  >
+    <title>one-line title</title>
+    <description>2-3 sentence description with concrete trace</description>
+  </finding>
+  <verified_clean>
+    <category letter="<letter>" name="<name>" evidence="brief evidence + cleared conclusion"/>
+  </verified_clean>
+</bugteam_audit>
+```
+
+After the teammate writes the XML and returns, the lead reads `.bugteam-loop-<N>.outcomes.xml` with the `Read` tool, parses it, and populates `loop_comment_index` from `<finding>` elements.
+
+## FIX spawn-prompt XML (bugfix teammate)
+
+```xml
+<context>
+  <repo>owner/repo</repo>
+  <branch>head</branch>
+  <base_branch>base</base_branch>
+  <pr_url>url</pr_url>
+  <loop>N</loop>
+</context>
+
+<bugs_to_fix>
+  [for each P0/P1/P2 finding from last_findings:]
+  <bug
+    finding_id="loop<N>-<index>"
+    severity="P0|P1|P2"
+    file="<path>"
+    line="<int>"
+    category="<letter>"
+    finding_comment_id="<id>"
+    finding_comment_url="<url>"
+  >
+    <description>...</description>
+  </bug>
+</bugs_to_fix>
+
+<execution>
+  1. Read each referenced file before editing.
+  2. Apply each fix you can address.
+  3. Run `python -m py_compile` (or language-equivalent) on every modified file.
+  4. git add by explicit path, then git commit with a message summarizing the bugs fixed.
+     - If the commit fails because a git hook (pre-commit, commit-msg, etc.) blocked it,
+       capture the hook's stderr, write status=hook_blocked for every finding in this loop
+       (the commit was atomic; if it failed, no finding was applied), populate hook_output
+       on each outcome, and return WITHOUT retrying. The lead will treat this loop as no-progress.
+  5. git push with a plain fast-forward push (the default, no flag overrides).
+  6. For each bug, post a fix reply to its finding_comment_id via the
+     Step 2.5 reply CLI shape:
+     - "Fixed in <commit_sha>" if the bug was addressed by your commit
+     - "Could not address this loop: <one-line reason>" if you skipped or failed it
+     - "Hook blocked the fix commit: <one-line summary>" if the commit was hook-blocked
+     Use the Fix reply CLI shape from Step 2.5 (`jq -Rs | gh api .../comments/<id>/replies --input -`). Write every reply body to a temp file first.
+  7. Write `.bugteam-loop-<N>.outcomes.xml` (schema below) and return its path.
+</execution>
+
+<outcome_xml_schema>
+  <bugteam_fix loop="<N>" commit_sha="<sha or empty if no commit>">
+    <outcome
+      finding_id="loop<N>-<index>"
+      status="fixed|could_not_address|hook_blocked"
+      commit_sha="<sha if fixed, empty otherwise>"
+      reply_comment_id="<id of the reply posted>"
+      reply_comment_url="<url of the reply posted>"
+    >
+      <reason>only present when status=could_not_address; one-line reason text</reason>
+      <hook_output>only present when status=hook_blocked; verbatim stderr from the blocked hook</hook_output>
+    </outcome>
+  </bugteam_fix>
+</outcome_xml_schema>
+
+<constraints>
+  - Modify only files referenced in bugs_to_fix.
+  - One commit on the existing branch, then push.
+  - Keep the branch linear and the PR base fixed; append one new commit per
+    loop and fast-forward push only.
+  - Let every git hook run on every commit.
+  - git add by explicit path — name each file being staged.
+  - Preserve existing comments on lines you do not modify.
+  - Type hints on every signature you touch.
+</constraints>
+```