claude-dev-env 1.93.0 → 1.94.0

package/skills/bugteam/SKILL.md

@@ -57,12 +57,12 @@ First match wins; respond with the quoted line exactly and stop:
 
 Every internal audit pass (CLEAN or DIRTY) ends with one posted GitHub PR
 review; the mandate applies whether bugteam runs inside `/pr-converge` or
-standalone. Apply the `post-audit-findings` skill
-([../post-audit-findings/SKILL.md](../post-audit-findings/SKILL.md)) with
-`--skill bugteam`: it covers the findings-JSON mapping (the `failure_mode`
-split at the literal `Fix:` heading), the anchored-vs-unanchored partition,
-the `post_audit_thread.py` invocation, the self-PR reviewer toggle
-(`BUGTEAM_REVIEWER_ACCOUNT`), the exit codes, and the id harvest.
+standalone. Run the shared posting helper
+[`_shared/pr-loop/scripts/post_audit_thread.py`](../../_shared/pr-loop/scripts/post_audit_thread.py)
+with `--skill bugteam`: map findings to the review-comment JSON (the
+`failure_mode` split at the literal `Fix:` heading), partition anchored from
+unanchored comments, honor the self-PR reviewer toggle
+(`BUGTEAM_REVIEWER_ACCOUNT`) and the exit codes, and harvest the ids.
 
 Bugteam-only obligations:
 
@@ -72,9 +72,9 @@ Bugteam-only obligations:
   thread_node_id}` triple into `loop_comment_index` (per-loop scope; see
   [reference/team-setup.md](reference/team-setup.md) § Loop state block) so
   the matching FIX action owns the reply-and-resolve unit.
-- Exit 2 from `post_audit_thread.py` is a hard blocker: the lead halts the
-  loop and exits `error: post_audit_thread retry exhausted` without
-  retrying.
+- Exit-code policy: the bugteam row in
+  [`../../_shared/pr-loop/post-audit-thread-contract.md`](../../_shared/pr-loop/post-audit-thread-contract.md)
+  § Per-caller policy.
 
 ## Progress checklist
 
@@ -83,10 +83,9 @@ Bugteam-only obligations:
 [ ] Step 1: PR scope resolved
 [ ] Step 2: loop state set
 [ ] Step 3: cycle complete (converged | cap reached | stuck | error)
-[ ] Step 4: working tree clean
-[ ] Step 4.5: PR description rewritten (or skip warning logged)
-[ ] Step 5: project permissions revoked
-[ ] Step 6: final report printed
+[ ] Step 4: apply pr-loop-lifecycle Close
+    Skill({skill: "pr-loop-lifecycle", args: "--skill bugteam close"})
+    (see pr-loop-lifecycle/SKILL.md "How callers invoke this")
 ```
 
 ## First invocation of a session
@@ -104,7 +103,7 @@ end-to-end mental model before starting Step 0.
 | `--bugbot-retrigger` flag behavior | [reference/team-setup.md](reference/team-setup.md) |
 | AUDIT action and code-rules pre-audit gate, pre-cycle walk, cycle decision tree | [reference/audit-and-teammates.md](reference/audit-and-teammates.md) |
 | FIX action and verify-push semantics | [reference/audit-and-teammates.md](reference/audit-and-teammates.md) |
-| Posting the end-of-pass audit review (APPROVE on CLEAN, REQUEST_CHANGES with inline anchored comments on DIRTY) | [§ Audit posting](#audit-posting), which applies [../post-audit-findings/SKILL.md](../post-audit-findings/SKILL.md) |
+| Posting the end-of-pass audit review (APPROVE on CLEAN, REQUEST_CHANGES with inline anchored comments on DIRTY) | [§ Audit posting](#audit-posting), which runs [`_shared/pr-loop/scripts/post_audit_thread.py`](../../_shared/pr-loop/scripts/post_audit_thread.py) |
 | Posting per-finding fix replies via GitHub MCP `add_reply_to_pull_request_comment` (rendered with the unified template at [`_shared/pr-loop/audit-reply-template.md`](../../_shared/pr-loop/audit-reply-template.md)) | [reference/github-pr-reviews.md](reference/github-pr-reviews.md) |
 | Teardown, PR description rewrite composed by the lead, permission revoke, final report | [../pr-loop-lifecycle/reference/teardown-publish-permissions.md](../pr-loop-lifecycle/reference/teardown-publish-permissions.md) |
 | Spawn-prompt XML, A–P category bindings, outcome XML schemas | [PROMPTS.md](PROMPTS.md) |

package/skills/bugteam/reference/CLAUDE.md

@@ -7,7 +7,7 @@ Expanded workflow detail for the `bugteam` skill. Load a file from this director
 | File | Purpose |
 |---|---|
 | `README.md` | Index of all files in this directory with one-line domain summaries. |
-| `team-setup.md` | Permissions grant, PR scope resolution (applies the `pr-scope-resolve` skill), run name, temp dir, and loop state. |
+| `team-setup.md` | Permissions grant, PR scope resolution, run name, temp dir, and loop state. |
 | `audit-and-teammates.md` | Pre-audit CODE_RULES gate, full cycle numbering, AUDIT and FIX action detail. |
 | `github-pr-reviews.md` | Per-loop review posting, `jq`+`gh api` payloads, inline anchors, fallbacks, REST endpoints. |
 | `design-rationale.md` | Why clean-room subagents, when `/bugteam` applies, refusal reasons. |

package/skills/bugteam/reference/audit-and-teammates.md

@@ -153,7 +153,7 @@ Agent(
 
 The teammate sees only the latest audit’s findings — each `Agent` call starts with a fresh context window; prior-loop findings, fix history, and chat stay in the lead.
 
-Pass finding comment URL, comment id, and thread node id for each finding (from `loop_comment_index`) in the XML prompt so the teammate owns both the reply and the thread resolution. After commit, the teammate posts one reply per finding using the unified template at [`../../../_shared/pr-loop/audit-reply-template.md`](../../../_shared/pr-loop/audit-reply-template.md) — the full header / horizontal rule / `<action_heading> ✅` / explanation / anchored-bullet / closing-paragraph skeleton, with `<status_line>` set per the path (`Fixed in <short_sha>` for `status=fixed`, `Could not address this loop` for `status=could_not_address`, `Hook blocked the fix commit` for `status=hook_blocked`). Per-thread reply and `resolve_thread` are atomic; the mechanics follow the `pr-fix-protocol` skill ([`../../pr-fix-protocol/SKILL.md`](../../pr-fix-protocol/SKILL.md)), which frames the shared 13-step sequence in [`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md) (step 12 carries the exact reply-and-resolve sequence). Same identity model as bugfind: teammate posts; lead waits.
+Pass finding comment URL, comment id, and thread node id for each finding (from `loop_comment_index`) in the XML prompt so the teammate owns both the reply and the thread resolution. After commit, the teammate posts one reply per finding using the unified template at [`../../../_shared/pr-loop/audit-reply-template.md`](../../../_shared/pr-loop/audit-reply-template.md) — the full header / horizontal rule / `<action_heading> ✅` / explanation / anchored-bullet / closing-paragraph skeleton, with `<status_line>` set per the path (`Fixed in <short_sha>` for `status=fixed`, `Could not address this loop` for `status=could_not_address`, `Hook blocked the fix commit` for `status=hook_blocked`). Per-thread reply and `resolve_thread` are atomic; the mechanics follow the shared 13-step sequence in [`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md) (step 12 carries the exact reply-and-resolve sequence). Same identity model as bugfind: teammate posts; lead waits.
 
 After replies, the teammate writes outcome XML (schema in [`../PROMPTS.md`](../PROMPTS.md)).
 
@@ -161,7 +161,7 @@ After replies, the teammate writes outcome XML (schema in [`../PROMPTS.md`](../P
 
 Same self-termination model as bugfind. Missing notification → hard blocker.
 
-`approve: false` → `error: bugfix teammate refused shutdown` → Step 4 then 5.
+`approve: false` → `error: bugfix teammate refused shutdown` → Step 4 (`pr-loop-lifecycle` Close).
 
 Substitute placeholders from `last_findings` into the fix prompt per [`../PROMPTS.md`](../PROMPTS.md). The spawn XML includes TaskCreate/self_audit_checklist for task tracking — the FIX subagent MUST create tasks before starting.
 

package/skills/bugteam/reference/copilot-gap-analysis.md

@@ -1,5 +1,7 @@
 # Copilot gap analysis
 
+> **Of-record gate location:** skill-local `bugteam_code_rules_gate.py` is a thin re-export. The of-record implementation is `_shared/pr-loop/scripts/code_rules_gate.py`.
+
 > **Status: HISTORICAL — patch plan partially superseded.**
 >
 > This file documents the read-only investigation that motivated the K–N rubric addendum and the Step 2.6 / Step 3.5 standards-review phases. **The audit-rubric portion of the patch plan was reverted in [PR #292](https://github.com/jl-cmd/claude-dev-env/pull/292):** PROMPTS.md no longer carries the K–N addendum or the `<copilot_derived_addendum_source>` block, and SKILL.md no longer runs the Step 2.6 / Step 3.5 standards-review phases.

package/skills/bugteam/reference/github-pr-reviews.md

@@ -1,13 +1,15 @@
-# GitHub PR comments
+# GitHub PR comments (bugteam-only)
 
-Per-loop pull-request reviews and post-fix replies use two distinct transports:
+Transport, exit codes, retry/backoff, and payload shapes live in
+[`../../../_shared/pr-loop/gh-payloads.md`](../../../_shared/pr-loop/gh-payloads.md)
+and
+[`post_audit_thread.py`](../../../_shared/pr-loop/scripts/post_audit_thread.py).
+Read those for how the review POST runs; this file covers only bugteam lead and
+FIX behavior around that transport.
 
-- **Per-loop audit review** — posted via [`post_audit_thread.py`](../../../_shared/pr-loop/scripts/post_audit_thread.py). One review per audit pass. `APPROVE` on CLEAN (the request event; GitHub stores it as `state=APPROVED`; body documents "no findings", zero inline comments). `REQUEST_CHANGES` on DIRTY (one inline anchored comment per finding; each becomes its own resolvable thread).
-- **Fix replies** — posted via the GitHub MCP `add_reply_to_pull_request_comment` after the fix commit lands. The reply body uses the unified template at [`../../../_shared/pr-loop/audit-reply-template.md`](../../../_shared/pr-loop/audit-reply-template.md); reply and `resolve_thread` are atomic per thread.
+## Lead posts the audit review
 
-## Per-loop audit review (post_audit_thread.py)
-
-Run the script at the end of every audit pass:
+The lead runs `post_audit_thread.py` at the end of every audit pass:
 
 ```
 python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/post_audit_thread.py" \
@@ -20,23 +22,55 @@ python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/post_audit_thread.py"
   --findings-json <path>
 ```
 
-Capture `<head_sha>` via `git rev-parse HEAD` in the subagent cwd immediately before this call so the review attaches to the commit the audit actually scoped.
+Capture `<head_sha>` via `git rev-parse HEAD` in the subagent cwd immediately
+before this call so the review attaches to the commit the audit actually scoped.
+
+- **CLEAN** — `APPROVE` event (GitHub stores `state=APPROVED`); body documents
+  "no findings"; empty findings list (`[]`); zero inline comments.
+- **DIRTY** — `REQUEST_CHANGES`; one inline anchored comment per finding (each
+  becomes its own resolvable thread).
+
+## Findings JSON (Shape A `Fix:` split)
+
+`--findings-json` is a JSON list of
+`{path, line, side, severity, description, fix_summary}`. Build it from the
+merged Shape A findings: finding `file` → `path`. Each finding's `failure_mode`
+carries the full audit-to-fix handoff text per
+[`agents/code-quality-agent.md`](../../../agents/code-quality-agent.md); split
+`failure_mode` at the literal `Fix:` heading so the failure narrative becomes
+`description` and the suffix beginning at `Fix:` (including the trailing
+`Validation:` clause) becomes `fix_summary`. When a finding's `failure_mode`
+omits the `Fix:` heading, write the full text to BOTH `description` and
+`fix_summary`. Set `side="RIGHT"` for every entry.
 
-`--findings-json` points to a JSON file whose root is a list of objects shaped `{path, line, side, severity, description, fix_summary}`. Build it from the merged Shape A findings: finding `file` → `path`. Each finding's `failure_mode` carries the full audit-to-fix handoff text per [`agents/code-quality-agent.md`](../../../agents/code-quality-agent.md); split `failure_mode` at the literal `Fix:` heading so the failure narrative becomes `description` and the suffix beginning at `Fix:` (including the trailing `Validation:` clause) becomes `fix_summary`. When a finding's `failure_mode` omits the `Fix:` heading, write the full text to BOTH `description` and `fix_summary` so the script's body template (`INLINE_COMMENT_BODY_TEMPLATE` in [`packages/claude-dev-env/_shared/pr-loop/scripts/pr_loop_shared_constants/post_audit_thread_constants.py`](../../../_shared/pr-loop/scripts/pr_loop_shared_constants/post_audit_thread_constants.py)) renders coherently. Set `side="RIGHT"` for every entry. On CLEAN the list is empty (`[]`); on DIRTY the list carries one entry per finding.
+## Anchor validation before JSON
 
-The script handles retries internally — 1s / 4s / 16s backoff across four attempts (one initial plus three retries). Exit codes:
+Validate `(path, line)` against the captured diff before adding a finding to the
+findings JSON. GitHub rejects the entire review POST when any inline comment
+targets a line missing from the diff at `--commit`. Findings without a diff
+anchor stay out of the JSON; surface them in the calling skill's user-facing
+output so the audit pass still completes.
 
-- `0` — review posted; the new review's `html_url` is on stdout.
-- `1` — user input error (bad arguments, malformed findings JSON, missing template).
-- `2` — retry exhaustion. Hard blocker; the lead exits `error: post_audit_thread retry exhausted` without retrying and without falling back to a flat issue comment.
+## FIX waits for harvest (`loop_comment_index`)
 
-Harvest the parent review URL from stdout, then extract the numeric review id from the URL's `#pullrequestreview-<id>` suffix (the trailing URL fragment of `html_url`, the part after `#`). Fetch child-comment URLs via `pull_request_read(method="get_review_comments", owner=<owner>, repo=<repo>, pullNumber=<N>)` filtered to that review id. That same response carries each comment's PR review thread node id (e.g. `PRRT_kwDOxxx`) — capture it alongside the numeric comment id. Match children to findings in the order they appear in the findings JSON, and store the mapping as `loop_comment_index[finding_id]` carrying both `finding_comment_id` (numeric) and `thread_node_id` (`PRRT_kwDOxxx`) for the FIX step to reply against and resolve.
+FIX does not reply until harvest completes. After a successful post:
 
-The script reads its body skeleton from [`../../../_shared/pr-loop/audit-reply-template.md`](../../../_shared/pr-loop/audit-reply-template.md) at runtime, so the template doc remains the single source of truth for the body shape — edits there propagate without restarting the caller.
+1. Read the parent review URL from stdout; extract the numeric review id from
+   the `#pullrequestreview-<id>` suffix.
+2. Fetch child comments via
+   `pull_request_read(method="get_review_comments", ...)` filtered to that
+   review id.
+3. Capture each comment's PR review thread node id (`PRRT_kwDOxxx`) alongside
+   the numeric comment id.
+4. Match children to findings in findings-JSON order; store
+   `loop_comment_index[finding_id]` with `finding_comment_id` (numeric) and
+   `thread_node_id` (`PRRT_kwDOxxx`).
 
-## Fix reply (MCP)
+## Atomic reply + resolve
 
-After the fix commit lands, post one reply per finding thread and resolve the thread atomically.
+After the fix commit lands, post one reply per finding thread and resolve that
+thread as one atomic action. Do not yield to the lead between the two calls. Do
+not batch all replies before any resolves.
 
 ```
 mcp__plugin_github_github__add_reply_to_pull_request_comment(
@@ -46,13 +80,7 @@ mcp__plugin_github_github__add_reply_to_pull_request_comment(
   commentId=<finding_comment_id>,
   body="<reply body using unified template>"
 )
-```
-
-The reply body uses the unified template from [`../../../_shared/pr-loop/audit-reply-template.md`](../../../_shared/pr-loop/audit-reply-template.md). Per-status `<status_line>` / `<action_heading>` values live in [`../PROMPTS.md`](../PROMPTS.md) § FIX execution step 8.
-
-Immediately after the reply call returns, resolve the same thread:
 
-```
 mcp__plugin_github_github__pull_request_review_write(
   method="resolve_thread",
   owner="<owner>",
@@ -62,18 +90,8 @@ mcp__plugin_github_github__pull_request_review_write(
 )
 ```
 
-`<thread_node_id>` is the PR review thread node ID (`PRRT_kwDOxxx`) harvested above when calling `get_review_comments`, distinct from the numeric comment ID used in the reply call. See [obstacles/fix-resolve-thread.md](obstacles/fix-resolve-thread.md) for the full identifier-shape rationale.
-
-The two calls form one atomic per-thread action. Do not yield to the lead between them. Do not batch all replies before any resolves.
-
-## Anchor validation
-
-GitHub's reviews endpoint rejects the entire POST if any inline comment in `comments[]` targets a line not present in the diff at `--commit`. Validate `(path, line)` against the captured diff before adding a finding to the findings JSON. Findings without a diff anchor stay out of the JSON; surface them in the calling skill's user-facing output instead so the audit pass still completes.
-
-## GitHub MCP tools used
-
-- `add_reply_to_pull_request_comment` — fix replies on existing review comments.
-- `pull_request_review_write` (`method="resolve_thread"`) — thread resolution after the reply lands; called atomically with the reply.
-- `pull_request_read` (`method="get_review_comments"`) — harvest child-comment ids/urls after the script's parent review posts.
-
-Reference: https://github.com/github/github-mcp-server.
+Reply body template:
+[`../../../_shared/pr-loop/audit-reply-template.md`](../../../_shared/pr-loop/audit-reply-template.md).
+Per-status `<status_line>` / `<action_heading>` values live in
+[`../PROMPTS.md`](../PROMPTS.md) § FIX execution step 8. Identifier-shape
+rationale: [obstacles/fix-resolve-thread.md](obstacles/fix-resolve-thread.md).

package/skills/bugteam/reference/team-setup.md

@@ -4,10 +4,12 @@
 
 ### Utility scripts
 
-Bugteam-specific utilities (preflight, fix_hookspath, grant, revoke) live in
-the skill-local [`scripts/`](../scripts/) directory. Shared utilities remain in
-[`_shared/pr-loop/scripts/`](../../_shared/pr-loop/scripts/) (run, do not paste
-into context). Utility scripts are **executed**, not loaded as primary context
+Skill-path thin entries for preflight and fix_hookspath live in the skill-local
+[`scripts/`](../scripts/) directory and delegate to package shared
+[`_shared/pr-loop/scripts/`](../../_shared/pr-loop/scripts/). Shared homes for
+grant, revoke, and code_rules_gate also live under `_shared/pr-loop/scripts/`
+(run, do not paste into context). Utility scripts are **executed**, not loaded
+as primary context
 ([`sources.md`](../sources.md) § Progressive disclosure and utility scripts).
 
 ```bash
@@ -60,16 +62,14 @@ python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/grant_project_claude_p
 
 The script reads `Path.cwd()` and writes idempotent allow rules into `~/.claude/settings.json`. Run from the project root. If it fails (non-zero exit), surface the error and stop — do not proceed without the grant.
 
-This is the **first** action of every `/bugteam` invocation, before any subagent spawn. The corresponding revoke runs at Step 5 regardless of how the cycle exits.
+This is the **first** action of every `/bugteam` invocation, before any subagent spawn. The matching revoke runs inside Step 4 (`pr-loop-lifecycle` Close) regardless of how the cycle exits.
 
 ## Step 1 — Resolve PR scope (detail)
 
-Apply the `pr-scope-resolve` skill
-([../../pr-scope-resolve/SKILL.md](../../pr-scope-resolve/SKILL.md)) with
-caller `bugteam`. Its resolution ladder hands back `owner`, `repo`, `number`,
-`head_ref`, `base_ref`, `url`, and `head_sha`; when no PR and no upstream
-diff exist, respond exactly `No PR or upstream diff. /bugteam needs a
-target.` and stop.
+Resolve the PR scope for caller `bugteam`: from the current branch's open PR
+(or an explicit PR argument), capture `owner`, `repo`, `number`, `head_ref`,
+`base_ref`, `url`, and `head_sha`; when no PR and no upstream diff exist,
+respond exactly `No PR or upstream diff. /bugteam needs a target.` and stop.
 
 Capture `<owner>/<repo>`, head branch, base branch, PR number, PR URL. This scope persists across every loop — `/bugteam` runs to completion from the single up-front confirmation.
 

package/skills/bugteam/scripts/CLAUDE.md

@@ -6,9 +6,9 @@ Python scripts executed by the bugteam lead or teammates at runtime. These are n
 
 | File | Purpose |
 |---|---|
-| `bugteam_preflight.py` | Run pytest and optional `pre-commit` before the first loop. Skips pytest when `BUGTEAM_PREFLIGHT_SKIP=1` or no test files exist. |
-| `bugteam_fix_hookspath.py` | Auto-remediate a stale `core.hooksPath` override, set the canonical global value, re-run preflight. |
-| `bugteam_code_rules_gate.py` | Run `validate_content` from `code_rules_enforcer.py` on PR-scoped files. Exit 1 on mandatory rule failures. |
+| `bugteam_preflight.py` | Skill-path thin entry for shared `_shared/pr-loop/scripts/preflight.py`. Skips pytest when `BUGTEAM_PREFLIGHT_SKIP=1` or no test files exist. |
+| `bugteam_fix_hookspath.py` | Skill-path thin entry for shared `_shared/pr-loop/scripts/fix_hookspath.py`. Auto-remediates a stale `core.hooksPath` override. |
+| `bugteam_code_rules_gate.py` | Thin skill-path entry; re-exports shared `_shared/pr-loop/scripts/code_rules_gate.py` (of record). |
 | `windows_safe_rmtree.py` | Remove a directory tree on Windows by stripping ReadOnly attributes and retrying on failure. |
 | `probe_code_rules_enforcer_check.py` | Load `code_rules_enforcer.py` and invoke a named check function against a fixture file. |
 | `reflow_skill_md.py` | Reflow the bugteam SKILL.md body to fit line-length limits. |
@@ -17,9 +17,9 @@ Python scripts executed by the bugteam lead or teammates at runtime. These are n
 
 | File | Tests |
 |---|---|
-| `test_bugteam_preflight.py` | `bugteam_preflight.py` |
-| `test_bugteam_code_rules_gate.py` | `bugteam_code_rules_gate.py` |
-| `test_bugteam_fix_hookspath.py` | `bugteam_fix_hookspath.py` |
+| `test_bugteam_preflight.py` | Smoke for thin wrap; behavioral suite is `_shared/pr-loop/scripts/tests/test_preflight.py` |
+| `test_bugteam_code_rules_gate.py` | Smoke for thin wrap; behavioral suite is `_shared/pr-loop/scripts/tests/test_code_rules_gate.py` |
+| `test_bugteam_fix_hookspath.py` | Smoke for thin wrap; behavioral suite is `_shared/pr-loop/scripts/tests/test_fix_hookspath.py` |
 | `test_probe_code_rules_enforcer_check.py` | `probe_code_rules_enforcer_check.py` |
 | `test_windows_safe_rmtree.py` | `windows_safe_rmtree.py` |
 

package/skills/bugteam/scripts/README.md

@@ -4,14 +4,16 @@ Scripts in this directory are **executed** by the lead or teammates. They are no
 
 | Script | Purpose |
 |--------|---------|
-| `bugteam_preflight.py` | Run pytest (when configured) and optional `pre-commit` before `/bugteam`. |
-| `bugteam_fix_hookspath.py` | Auto-remediate a stale local `core.hooksPath` override, set canonical global value, re-run `bugteam_preflight.py`. Invoked by Claude when preflight reports a `core.hooksPath` failure. |
-| `bugteam_code_rules_gate.py` | Run `validate_content` from `code-rules-enforcer.py` on PR-scoped files (`git diff` vs merge-base). Exit `1` if any mandatory rule fails. Invoked **before each audit**; the fixer clears it before the auditor runs. |
-| `windows_safe_rmtree.py` | Recursively remove a directory tree on Windows by stripping ReadOnly attributes and retrying the failing syscall. Invoked from SKILL.md Step 4 to delete `<run_temp_dir>` after teardown. |
+| `bugteam_preflight.py` | Run pytest (when configured) and optional `pre-commit` before `/bugteam`. Skill-path thin entry; implementation lives at package shared `_shared/pr-loop/scripts/preflight.py`. |
+| `bugteam_fix_hookspath.py` | Auto-remediate a stale local `core.hooksPath` override, set canonical global value, re-run preflight. Skill-path thin entry; implementation lives at package shared `_shared/pr-loop/scripts/fix_hookspath.py`. Invoked by Claude when preflight reports a `core.hooksPath` failure. |
+| `bugteam_code_rules_gate.py` | Thin skill-path entry that re-exports shared `_shared/pr-loop/scripts/code_rules_gate.py`. **Not the pre-audit gate of record** — invoke the shared script for live pre-audit (see `reference/audit-and-teammates.md`). |
+| `windows_safe_rmtree.py` | Windows-safe recursive directory removal (strips ReadOnly, retries). Standalone helper with unit tests; run-temp teardown is `skills/_shared/pr-loop/scripts/teardown_worktrees.py` under `pr-loop-lifecycle` Close. |
 | `probe_code_rules_enforcer_check.py` | Dynamically load `~/.claude/hooks/blocking/code_rules_enforcer.py` and invoke a named check function against a fixture file. Used by the historical Copilot gap-analysis investigation as a verification shape (see `reference/copilot-gap-analysis.md`). |
 
 ## `bugteam_preflight.py`
 
+Skill-path thin entry; implementation lives at `_shared/pr-loop/scripts/preflight.py`.
+
 From the repository root:
 
 ```bash
@@ -25,6 +27,8 @@ python "${CLAUDE_SKILL_DIR}/scripts/bugteam_preflight.py"
 
 ## `bugteam_fix_hookspath.py`
 
+Skill-path thin entry; implementation lives at `_shared/pr-loop/scripts/fix_hookspath.py`.
+
 From the repository root:
 
 ```bash
@@ -35,13 +39,21 @@ python "${CLAUDE_SKILL_DIR}/scripts/bugteam_fix_hookspath.py"
 - Sets `git config --global core.hooksPath ~/.claude/hooks/git-hooks` when the global value is unset or non-canonical.
 - Refuses to run (exit non-zero) when `~/.claude/hooks/git-hooks` does not exist on disk — install via `npx claude-dev-env .` first.
 - Idempotent: a second invocation is a clean no-op.
-- Re-runs `bugteam_preflight.py --no-pytest` and propagates its exit code.
+- Re-runs package-shared `preflight.py --no-pytest` and propagates its exit code.
 
 The bugteam SKILL invokes this automatically when preflight stderr indicates a `core.hooksPath` failure, so Claude does not surface the error to the user.
 
-## `bugteam_code_rules_gate.py`
+## `bugteam_code_rules_gate.py` (thin skill-path entry)
+
+Skill-path thin entry; re-exports `main` from package-shared `_shared/pr-loop/scripts/code_rules_gate.py`.
+
+**Not the pre-audit gate of record.** The live pre-audit gate is the package-shared script:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/code_rules_gate.py" --base origin/<baseRefName>
+```
 
-From the repository root (same merge-base rules as the PR head vs base — default `--base origin/main`):
+See `reference/audit-and-teammates.md`. Keep this wrap for callers that still invoke the skill-local path.
 
 ```bash
 python "${CLAUDE_SKILL_DIR}/scripts/bugteam_code_rules_gate.py"
@@ -53,4 +65,4 @@ Optional explicit files instead of `git diff`:
 python "${CLAUDE_SKILL_DIR}/scripts/bugteam_code_rules_gate.py" path/to/a.py path/to/b.ts
 ```
 
-This loads `validate_content` from `hooks/blocking/code-rules-enforcer.py` inside `claude-dev-env` (same logic as the PreToolUse hook). Exit `0` = mandatory checks pass on scanned files; exit `1` = violations printed to stderr.
+Both the wrap and the shared script load `validate_content` from `hooks/blocking/code_rules_enforcer.py` inside `claude-dev-env` (same logic as the PreToolUse hook). Exit `0` = mandatory checks pass on scanned files; exit `1` = violations printed to stderr.