claude-dev-env 1.93.0 → 1.94.0

package/skills/pre-compact/SKILL.md

@@ -1,134 +0,0 @@
----
-name: pre-compact
-description: >-
-  Composes a focus directive for /compact and copies the full "/compact <directive>"
-  string to the clipboard, pinning the session's load-bearing identifiers (branch, PR,
-  HEAD, worktree, in-flight work, decisions, blockers, files in play) after validating
-  each against its live source. Use on /pre-compact or any ask to prep for compaction.
-disable-model-invocation: true
----
-
-# Pre-Compact
-
-`/compact [instructions]` accepts a focus directive that steers the
-compaction-summary LLM toward high-signal content. This skill writes that
-directive from the live session and copies the full `/compact <directive>`
-string to the operator's clipboard.
-
-**Announce at start:** "I'm composing your compact focus directive."
-
-## Step 1 — Confirm the next-session intent
-
-Before composing anything, ask the operator what they intend to work on in
-the next chat. Do not infer it silently from the conversation, and do not
-ask it raw — use `AskUserQuestion` with two to four options drawn from the
-session context (the threads left open, the obvious next actions, the task
-the operator last steered toward); the tool's free-text fallback covers
-anything unlisted. The selected intent is the directive's forward task:
-Step 2 scopes every field to what that intent needs, and the rendered
-`In-flight` line states it.
-
-## Step 2 — Read and validate the live session
-
-Validate every identifier directly before stating it. Conversation context
-goes stale within a session — a PR merges, HEAD advances, a worktree
-advances to a newer commit — so confirm each value against its live source
-at compose time rather than carrying it from memory. Run the command in
-each field's Source column; for a PR, capture its merge state
-(`gh pr view --json state,mergedAt`) and state `merged` or `open` from that
-result, never from recollection. A value that cannot be confirmed against a
-live source is not dropped silently — surface it to the operator via
-`AskUserQuestion` to clarify (offer the candidate values found plus the
-free-text fallback) and use the answer. Omit it only when the operator
-chooses to skip it.
-
-| Field | What to capture | Source |
-|---|---|---|
-| `branch` | Active branch name | `git branch --show-current` |
-| `pr` | Active PR number and its merge state (open / merged), when one exists | `gh pr view --json number,state,mergedAt` |
-| `head` | Short HEAD SHA (whatever `git rev-parse --short` outputs) | `git rev-parse --short HEAD` |
-| `worktree` | Absolute path to the working directory | `pwd` |
-| `in_flight` | One sentence describing what is being worked on right now | conversation |
-| `decisions` | Architectural choices, library picks, tradeoffs settled this session | conversation |
-| `blockers` | Failures observed, root causes identified, fixes pending | conversation |
-| `files` | Paths the operator is iterating on (edited or read more than once) | conversation |
-| `follow_ups` | What the user asked to be remembered or revisited | conversation |
-
-A field whose value cannot be stated as a concrete identifier is omitted
-from the directive.
-
-Scope every field to what the Step 1 intent needs next. Compaction carries
-forward the slice of session history the remaining work needs: capture a
-`decision`, `blocker`, or `in_flight` detail when a next step relies on
-it, and leave a detail the next steps do not touch (a settled question, a
-resolved blocker, a path not taken) out by simply not listing it. When a
-settled decision still constrains the next step, list its outcome as one
-line, not the deliberation behind it.
-
-## Step 3 — Render the directive
-
-Render this exact shape, populating only the fields with concrete values:
-
-```
-Preserve:
-- Branch: <name>
-- PR: #<number>
-- HEAD: <short-sha>
-- Worktree: <path>
-- In-flight: <one sentence>
-- Decisions: <bullet per decision>
-- Blockers: <bullet per blocker>
-- Files: <path>, <path>, <path>
-- Follow-ups: <bullet per follow-up>
-```
-
-The directive lists only what the next steps consume, so the summarizer
-preserves that with high fidelity and compresses the rest of the trace on
-its own — naming what to keep is a clearer instruction than enumerating
-what to cut. Keep the list tight: a `Preserve:` block padded with finished
-or out-of-scope context dilutes the summarizer's focus on what happens
-next.
-
-Source: [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
-— "start by maximizing recall to ensure your compaction prompt captures
-every relevant piece of information from the trace, then iterate to improve
-precision by eliminating superfluous content."
-
-## Step 4 — Copy `/compact <directive>` to the clipboard
-
-Write the full `/compact <directive>` string to a temporary file via the
-Write tool, then copy the file contents to the clipboard with PowerShell:
-
-```
-pwsh -NoProfile -Command "Get-Content -LiteralPath '<temp file path>' -Raw | Set-Clipboard"
-```
-
-`Get-Content -LiteralPath … -Raw` reads the file as a single string with
-no wildcard expansion, and `Set-Clipboard` writes it verbatim. The intermediate file keeps the directive content out
-of any shell-parsing path: session text passes through `Get-Content`
-unmodified regardless of which characters it contains.
-
-A reasonable temp path under `$env:TEMP` (Windows) or `$TMPDIR` (POSIX)
-works; clean it up after the `Set-Clipboard` call returns.
-
-## Step 5 — Hand off
-
-Print this confirmation line to the operator:
-
-> Copied `/compact …` to your clipboard. Paste it as your next prompt to
-> compact this conversation with focus.
-
-Then list up to the first three `Preserve:` bullets (or fewer when the
-directive omits fields) inline so the operator can spot-check before
-pasting.
-
----
-
-## References
-
-- `/compact [instructions]` — [Claude Code commands](https://code.claude.com/docs/en/commands)
-- Compaction strategy — [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
-
-## Folder map
-
-- `SKILL.md` — hub. No companions.

package/skills/qbug/CLAUDE.md

@@ -1,40 +0,0 @@
-# qbug
-
-Quick baseline PR audit: one clean-coder subagent loops audit → fix → commit → push until the PR is clean or stuck.
-
-**Trigger:** `/qbug`, "quick bug audit", "solo bug audit", "baseline PR review", "bugteam without a team".
-
-## Purpose
-
-`/qbug` is the required baseline review for every new PR. It runs the same A–P bug category rubric and CODE_RULES gate as `/bugteam` but with a single persistent subagent (no TeamCreate, no per-loop clean-room, no loop cap). Escalate to `/bugteam` when bias isolation across loops matters.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | The complete skill — four steps (pre-flight, resolve PR scope via the `pr-scope-resolve` skill, spawn subagent cycle, final report). The subagent XML prompt is inline and points the embedded agent at the `post-audit-findings` and `pr-fix-protocol` skills for review posting and reply/resolve mechanics. |
-
-## Shared artifacts (referenced by path, not copied)
-
-The skill references shared scripts from `../_shared/pr-loop/scripts/`:
-
-| Script | Role |
-|---|---|
-| `preflight.py` | Git hooks path check, pytest, optional pre-commit |
-| `code_rules_gate.py` | CODE_RULES gate run before every AUDIT |
-| `post_audit_thread.py` | Posts one GitHub review per loop (APPROVE or REQUEST_CHANGES) |
-| `audit-reply-template.md` | Unified reply body shape for resolved threads |
-
-Bug category rubric A–P lives at `../bugteam/PROMPTS.md`. Audit contract (finding schema, proof-of-absence, Haiku secondary, self-audit) lives at `../../_shared/pr-loop/audit-contract.md`.
-
-## Subagent structure
-
-- **Primary:** `clean-coder` — runs the full audit → fix → commit → push cycle internally.
-- **Secondary:** `code-quality-agent` (Haiku model) — audit-only, read-only; findings merged before FIX step.
-- No `TeamCreate`. No loop cap. Exits on `converged`, `stuck`, or `error`.
-
-## Conventions
-
-- The lead resolves the temp directory via Python's `tempfile.gettempdir()` and passes the absolute path to the subagent.
-- Each loop: one `code_rules_gate.py` pre-audit, one GitHub review posted, one commit on fix.
-- Self-PR toggle, findings-JSON mapping, and anchored-only serialization live in the `post-audit-findings` skill; reply-and-resolve mechanics live in the `pr-fix-protocol` skill.

package/skills/qbug/SKILL.md

@@ -1,387 +0,0 @@
----
-name: qbug
-description: >-
-  Required baseline review for every new PR: runs the /bugteam audit, fix,
-  commit, and push cycle through one clean-coder subagent (not a full team),
-  looping until convergence or stuck. Triggers: '/qbug', 'quick bug audit',
-  'solo bug audit', 'baseline PR review', 'bugteam without a team'.
----
-
-# qbug
-
-**Core principle:** One `clean-coder` subagent loops audit → fix → commit → push until converged or stuck. The subagent's context persists across loops (no per-loop clean-room) — that is the explicit trade vs /bugteam.
-
-**When to reach for /qbug vs /bugteam:** `/qbug` is the required baseline review for every new PR (fastest path from "ready" to "merged-safe"). Escalate to `/bugteam` when the PR is large enough that anchoring-bias across loops becomes a convergence risk, or when a hard loop cap is required for cost control.
-
-Shared artifacts with /bugteam are referenced below by path, using the `${CLAUDE_SKILL_DIR}` host-substitution convention (both skills land under `~/.claude/skills/` after install):
-
-- Pre-flight script: `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/preflight.py`
-- Code-rules gate script: `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/code_rules_gate.py`
-- Bug category rubric A–P: [`bugteam/PROMPTS.md`](../bugteam/PROMPTS.md#audit-spawn-prompt-xml-bugfind-teammate)
-- **Audit contract** (finding schema, proof-of-absence, adversarial pass, Haiku secondary, post-fix self-audit, diagnostics JSON): [`_shared/pr-loop/audit-contract.md`](../../_shared/pr-loop/audit-contract.md)
-- PR comment lifecycle shape: [`bugteam/SKILL.md`](../bugteam/SKILL.md#audit-posting)
-
-## Transport check (before any GitHub step)
-
-Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push` and take `true` as the pass. When any check fails, run the `pr-loop-cloud-transport` skill first and route every `gh` operation in this skill through its substitution matrix.
-
-## When this skill applies
-
-`/qbug` once authorizes the full cycle (no loop cap — runs until `converged` or `stuck`; user can interrupt at any time).
-
-Refusals — first match wins; respond with the quoted line exactly and stop:
-
-- **Disabled via environment.** When `CLAUDE_REVIEWS_DISABLED` carries the
-  token `bugteam`:
-  `/qbug is disabled via CLAUDE_REVIEWS_DISABLED.` Run the check via
-  `python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugteam`
-  (exit 0 = disabled). `/qbug` is the bugteam
-  baseline review and shares the `bugteam` token with `/bugteam`; the shared
-  pre-flight script also exits 7 in this case so any caller invoking it
-  directly halts on the same signal. The gate semantics live in the
-  `reviewer-gates` skill (`../reviewer-gates/SKILL.md`).
-- **No PR or upstream diff.** `No PR or upstream diff. /qbug needs a target.`
-- **Dirty tree.** `Uncommitted changes detected. Stash, commit, or revert before /qbug.`
-- **Missing subagent.** Before Step 2, confirm `clean-coder` exists. Else: `Required subagent type clean-coder not installed. /qbug needs clean-coder available.`
-
-## Progress checklist
-
-```
-[ ] Step 0: pre-flight clean
-[ ] Step 1: PR scope resolved
-[ ] Step 2: subagent cycle complete (converged | stuck | error)
-[ ] Step 3: PR description refreshed
-[ ] Step 4: final report printed
-```
-
-## Step 0: Pre-flight
-
-```bash
-python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/preflight.py"
-```
-
-`${CLAUDE_SKILL_DIR}` is host-substituted before the shell runs. Non-zero → fix before continuing. `BUGTEAM_PREFLIGHT_SKIP=1` is emergency only. Add `--pre-commit` when `.pre-commit-config.yaml` exists.
-
-Pre-flight checks (in order):
-
-1. **Git hooks path** — verifies `git -C <repository_root> config --get core.hooksPath` resolves to a path ending in `hooks/git-hooks`. Queries the repository-effective config so repo-level overrides (Husky, lefthook) are detected. If unset or pointing elsewhere, exits non-zero:
-   ```
-   Git-side CODE_RULES enforcement is not active on this host.
-   Run: npx claude-dev-env .
-   Or:  git config --global core.hooksPath ~/.claude/hooks/git-hooks
-   ```
-2. **pytest** — runs the test suite when `pytest.ini` or `[tool.pytest]` is present.
-3. **pre-commit** — runs when `--pre-commit` flag is passed and `.pre-commit-config.yaml` exists.
-
-## Step 1: Resolve PR scope (lead)
-
-Apply the `pr-scope-resolve` skill (`../pr-scope-resolve/SKILL.md`) with caller `qbug`. When no target exists, refuse per § When this skill applies with the sub-skill's canonical line.
-
-Capture: `owner/repo`, `baseRefName`, `headRefName`, PR `number`, `url`, `starting_sha = git rev-parse HEAD`.
-
-Resolve the scoped temp directory once, lead-side, before spawning the subagent. Use Python's `tempfile.gettempdir()` so the path is correct on macOS, Linux, Windows cmd.exe, and PowerShell — do not hardcode `/tmp/` because Windows runners do not honor it. Pass the resolved absolute path along with the PR metadata to the subagent:
-
-```python
-import tempfile
-from pathlib import Path
-
-pr_number: int = ...  # from pull_request_read MCP response above
-qbug_temp_dir: Path = Path(tempfile.gettempdir()) / f"qbug-pr-{pr_number}"
-qbug_temp_dir.mkdir(parents=True, exist_ok=True)
-```
-
-## Step 2: Spawn the primary and secondary audit agents
-
-Before calling `Agent`, the lead resolves the three absolute paths the subagent needs and substitutes them into the prompt template (the `<gate_script>`, `<categories_file>`, and `<qbug_temp_dir>` placeholders in § Subagent cycle prompt):
-
-```python
-import os
-from pathlib import Path
-
-skill_dir = Path(os.environ["CLAUDE_SKILL_DIR"])
-gate_script_path = (skill_dir / ".." / ".." / "_shared" / "pr-loop" / "scripts" / "code_rules_gate.py").resolve()
-categories_file_path = (skill_dir / ".." / "bugteam" / "PROMPTS.md").resolve()
-```
-
-Then call `Agent` twice in the same message — the primary clean-coder and the Haiku secondary run in parallel per the audit contract. The Haiku secondary receives an **audit-only** prompt (no FIX step, no git operations) and returns findings to the lead only. The lead merges their findings before the FIX step:
-
-```
-Agent(
-  subagent_type="clean-coder",
-  description="qbug primary audit/fix cycle for PR <number>",
-  prompt="<filled cycle XML; see § Subagent cycle prompt>",
-  run_in_background=False
-)
-
-Agent(
-  subagent_type="code-quality-agent",
-  model="haiku",
-  description="qbug Haiku secondary audit for PR <number>",
-  prompt="<audit-only prompt: read the PR diff, apply A–P categories from <categories_file>, return structured findings. No FIX, no git add, no git commit, no git push.>",
-  run_in_background=False
-)
-```
-
-The Haiku secondary is a read-only auditor per `audit-contract.md` — it returns findings to the lead and never modifies the working tree. The lead merges primary and Haiku secondary findings per the de-dup rules in the audit contract before proceeding. No `TeamCreate`, no `team_name`, no teammate shutdown protocol. The primary subagent returns when it has exited the cycle (`converged`, `stuck`, or `error`).
-
-## Subagent cycle prompt
-
-The subagent receives this prompt and loops internally — the lead does not re-invoke between loops. The prompt is self-contained: it restates the bug-category rubric by path rather than assuming prior context, and it states its full scope upfront. Before passing the prompt to `Agent()`, the lead substitutes every `{{UPPER_SNAKE}}` slot: `{{OWNER_REPO}}`, `{{HEAD_REF}}`, `{{BASE_REF}}`, `{{PR_URL}}`, `{{STARTING_SHA}}` (from Step 1) and `{{QBUG_TEMP_DIR}}`, `{{GATE_SCRIPT}}`, `{{CATEGORIES_FILE}}` (resolved in Step 2).
-
-```xml
-<role>
-  You are the lone audit-fix worker for this pull request. Run the full
-  audit → fix → commit → push cycle in this one subagent session. The
-  lead has already resolved scope and pre-flight; your job is to take
-  the cycle to an exit state and report back.
-</role>
-
-<context>
-  <repo>{{OWNER_REPO}}</repo>
-  <branch>{{HEAD_REF}}</branch>
-  <base_branch>{{BASE_REF}}</base_branch>
-  <pr_url>{{PR_URL}}</pr_url>
-  <starting_sha>{{STARTING_SHA}}</starting_sha>
-  <qbug_temp_dir>{{QBUG_TEMP_DIR}}</qbug_temp_dir>
-  <gate_script>{{GATE_SCRIPT}}</gate_script>
-  <categories_file>{{CATEGORIES_FILE}}</categories_file>
-</context>
-
-<exit_conditions>
-  The cycle stops when ONE of these is true. Check on every iteration:
-    - converged: most recent AUDIT returned zero findings AND
-      post_fix_audit_clean is true for the committing loop.
-    - stuck: most recent FIX left `git rev-parse HEAD` unchanged.
-    - error: three consecutive pre-audit gate rounds failed (three is
-      chosen because two is within normal clean-coder variance; four
-      rounds typically indicates a gate defect rather than fixable
-      violations).
-  There is no loop-count cap. A pathological diff with ever-changing
-  findings will still exit via `stuck` once a FIX produces no commit.
-</exit_conditions>
-
-<cycle>
-  Maintain inline across iterations:
-    loop_count = 0
-    last_action = "fresh"           # fresh | audited | fixed
-    last_findings = {p0, p1, p2, total}
-    loop_comment_index = {}
-    audit_log = []
-
-  Iteration:
-    1. Dispatch on last_action:
-       - "audited" and last_findings.total == 0 → exit "converged"
-       - "fixed" and `git rev-parse HEAD` equals the sha captured
-         immediately before FIX → exit "stuck"
-       - "fresh" or "fixed" → run pre-audit, then AUDIT
-       - "audited" and last_findings.total > 0 → run FIX
-
-    2. Pre-audit (before every AUDIT):
-       Run the gate script at <gate_script> with `--base origin/<base_branch>`.
-       Non-zero exit → fix the reported violations inline and re-run the
-       same command. Count consecutive failures. Three failed rounds →
-       exit "error: code rules gate failed pre-audit".
-       On exit 0: increment loop_count, proceed to AUDIT.
-
-    3. AUDIT:
-       Call `pull_request_read(method="get_diff", pullNumber=<pr_number>, owner=<owner>, repo=<repo>)` via MCP and save the diff to `<qbug_temp_dir>/loop-<loop_count>.patch`
-
-       - Read the patch file.
-       - Audit only added/modified lines. Read <categories_file> for the
-         A–P category definitions; investigate each category explicitly.
-       - Follow the shared audit contract at
-         $HOME/.claude/_shared/pr-loop/audit-contract.md. Per category:
-         produce either a Shape A structured finding or a Shape B
-         structured proof-of-absence. Bare "verified clean" labels are
-         REJECTED.
-       - Run the contract's adversarial second pass after the primary
-         finding list.
-       - The LEAD spawns the Haiku secondary auditor in parallel with
-         this primary audit per the contract's Haiku secondary section.
-       - Partition findings into anchored (line appears in the diff) vs
-         unanchored (line does not).
-
-       Persist the merged audit result to
-       <qbug_temp_dir>/loop-<loop_count>-audit.json per the contract's
-       persistence schema.
-
-       Post ONE review per loop. Read
-       $HOME/.claude/skills/post-audit-findings/SKILL.md and apply it
-       with `--skill qbug`. That skill owns the findings-JSON mapping,
-       the anchored-only serialization, the CLEAN/DIRTY decision, the
-       self-PR reviewer toggle, and the exit codes. qbug-specific
-       persistence: write the anchored findings JSON to
-       `<qbug_temp_dir>/loop-<loop_count>-findings.json` and pass that
-       path as `--findings-json`. Unanchored findings surface in the
-       loop's user-facing summary rather than as inline anchored
-       comments.
-
-       On exit 0, harvest ids per that skill's "Harvest ids for the fix
-       loop" section: each `loop_comment_index[finding_id]` entry must
-       carry `finding_comment_id` (numeric, used by
-       `add_reply_to_pull_request_comment`), `finding_comment_url`, and
-       `thread_node_id` (`PRRT_kwDOxxx`, used by `resolve_thread`) so
-       the FIX step can reply against the comment and resolve the
-       thread.
-
-       Exit 2 means retry exhaustion — exit
-       `error: post_audit_thread retry exhausted` without retrying and
-       without falling back to a flat issue comment. A hard blocker on
-       the audit-posting path is a halt condition, not a fallback
-       opportunity.
-
-       Update state: last_action="audited", last_findings=counts.
-       Append `<N> audit: <P0>P0 / <P1>P1 / <P2>P2` to audit_log.
-
-    4. FIX:
-       Capture the pre-FIX sha: `pre_fix_sha = git rev-parse HEAD`.
-       Capture pre-fix file contents for every file this FIX will touch.
-
-       Apply each fix. Read every file before editing. Preserve existing
-       comments on lines you do not modify. Add type hints on every
-       signature you touch.
-
-       Validate each modified Python file with `python -m py_compile`
-       (or the language-equivalent compile check).
-
-       Compute fix_diff: the diff between pre-fix and post-fix file contents
-       for every modified file.
-
-       Post-fix self-audit: follow the contract's post-fix self-audit
-       sequence at $HOME/.claude/_shared/pr-loop/audit-contract.md. Paranoid mode
-       (Haiku secondary in parallel), internal iteration cap = 3, exit
-       "stuck: post-fix audit not converging" after 3 rounds with fresh
-       findings. Only when gate_findings empty AND post_fix_findings
-       empty: proceed to git add.
-
-       Stage each modified path by explicit name: `git add <path>`.
-       Create one commit summarizing the fixed findings. Let every git
-       hook run. If a hook blocks the commit, capture its stderr, mark
-       every finding in this loop `status=hook_blocked`, and move on to
-       the next iteration without retrying this loop.
-
-       Push with a plain fast-forward: `git push`.
-
-       Write <qbug_temp_dir>/loop-<loop_count>-diagnostics.json per the
-       contract's diagnostics schema (all eight keys required).
-
-       For each finding, read
-       $HOME/.claude/skills/pr-fix-protocol/SKILL.md and apply its
-       reply-and-resolve unit: atomically (a) post the fix reply via
-       `add_reply_to_pull_request_comment` against
-       `loop_comment_index[finding_id].finding_comment_id`, using the
-       body template at
-       $HOME/.claude/_shared/pr-loop/audit-reply-template.md, then
-       (b) call `pull_request_review_write(method="resolve_thread",
-       threadId=<loop_comment_index[finding_id].thread_node_id>)` for
-       the same thread. Per-path `<status_line>`:
-       - `status=fixed`: `Fixed in <short_sha>` (first 7 chars).
-       - `status=could_not_address`: `Could not address this loop`.
-       - `status=hook_blocked`: `Hook blocked the fix commit`.
-       Body text is passed directly as string parameters — no temp
-       files, no jq, no shell pipes.
-
-       Update state: last_action="fixed". Append
-       `<N> fix: <short_sha> — <fixed>/<could_not_address>/<hook_blocked>`
-       to audit_log.
-
-    5. Return to step 1.
-</cycle>
-
-<example_finding_body>
-Populate these two fields on each finding entry of the JSON payload
-consumed by `post_audit_thread.py` (the script renders the inline
-comment body via `INLINE_COMMENT_BODY_TEMPLATE`):
-
-```json
-{
-  "description": "Two writers can both pass the existence check at line 88 before either commits the write at line 91 — whichever writes second overwrites the first under contention.",
-  "fix_summary": "Hold the cache lock across the check and the write, or use a compare-and-swap primitive. Validation: pytest -k cache_concurrent with the threaded-writer fixture."
-}
-```
-</example_finding_body>
-
-<constraints>
-  - Edit only files reachable from the PR diff's scope.
-  - Keep the branch linear: append one new commit per FIX loop and push
-    fast-forward only.
-  - Preserve existing comments on lines you do not modify.
-  - Every signature you touch has complete type hints.
-  - Every file is read before you edit it (investigate before answering).
-  - Complete the entire cycle in this one subagent session using your
-    available tools directly; keep all audit and fix work inside this
-    session.
-</constraints>
-
-<output_format>
-  Return to the lead with exactly these fields:
-    - exit_reason: "converged" | "stuck" | "error: <detail>"
-    - loop_count: integer
-    - final_commit_sha: `git rev-parse HEAD` at exit
-    - audit_log: ordered list of per-loop lines
-    - unresolved: array of {file, line, severity, title, reason}
-      (present only when exit_reason == "stuck")
-</output_format>
-```
-
-## Step 3: PR description refresh (lead)
-
-Compose the body directly against `docs/PR_DESCRIPTION_GUIDE.md` — no agent spawn — from the final PR diff and the original body. Apply via `update_pull_request(pullNumber=<number>, owner=<owner>, repo=<repo>, body=<new_body>)`.
-
-On error exit paths: best-effort; log the failure in the final report and continue.
-
-## Step 4: Final report (lead)
-
-Use the same shape as [`bugteam/SKILL.md` Step 6](../bugteam/SKILL.md#step-6-final-report) with two deltas:
-
-- Header substitutes `/qbug` for `/bugteam`.
-- Exit states are `converged | stuck | error` (no `cap reached` state, since `/qbug` has no loop cap).
-
-Delete the resolved `<qbug_temp_dir>` tree and any `.qbug-*.md` temp files in the working directory. The lead captured the dir as an absolute path via `tempfile.gettempdir()` in Step 1; reuse that literal for cleanup.
-
-## Constraints
-
-- **One primary + one secondary auditor, not a team.** Lead spawns a `clean-coder` primary (audit + fix cycle) and a `code-quality-agent` Haiku secondary (audit-only, read-only — no FIX, no git). No `TeamCreate`. Neither subagent spawns further subagents.
-- **No loop cap.** Cycle runs until `converged`, `stuck`, or `error`. User can interrupt.
-- **Code rules gate before every AUDIT.** Same `validate_content` logic as /bugteam.
-- **One commit per FIX action.** Linear branch, fast-forward push only.
-- **Categories A–P.** Same rubric as [`bugteam/PROMPTS.md`](../bugteam/PROMPTS.md).
-- **One review per loop.** Anchored findings as `comments[]`; unanchored findings surface in the calling skill's user-facing output (chat reply to the user) rather than in the PR review body.
-- **PR description rewrite on every exit**, same as /bugteam Step 4.5.
-- **Temp file cleanup on every exit path.**
-- **No per-loop clean-room.** The single subagent's context accumulates across loops — that is the explicit trade vs /bugteam. For convergence-critical audits where bias isolation matters, use /bugteam.
-
-## Examples
-
-<example>
-User: `/qbug`
-Lead: [preflight, resolves PR #42, spawns ONE clean-coder subagent with the cycle prompt]
-Subagent: [runs loops internally, returns]
-
-`Loop 1 audit: 1P0 / 2P1 / 0P2`
-`Loop 1 fix: commit a1b2c3d (3 files, +18/-7) — 3 fixed, 0 skipped`
-`Loop 2 audit: 0P0 / 1P1 / 0P2`
-`Loop 2 fix: commit e4f5g6h (1 file, +5/-2) — 1 fixed, 0 skipped`
-`Loop 3 audit: 0P0 / 0P1 / 0P2 → converged`
-
-`/qbug exit: converged`
-`Loops: 3`
-`Starting commit: 9d8c7b6`
-`Final commit: e4f5g6h`
-`Net change: 4 files, +23/-9`
-</example>
-
-<example>
-User: `/qbug`
-Subagent: [loop 4 fix produces no commit despite findings]
-
-`Loop 4 fix: no changes — could not address remaining 2 findings`
-`/qbug exit: stuck`
-`Unresolved: src/cache.py:88 (P0 race condition); src/parser.py:44 (P1 unbound reference)`
-</example>
-
-<example>
-User: `/qbug` (no PR or upstream diff)
-Lead: `No PR or upstream diff. /qbug needs a target.`
-</example>
-