claude-dev-env 1.37.0 → 1.37.1

package/package.json

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

package/rules/gh-paginate.md

@@ -1,6 +1,6 @@
 # gh API Pagination Rule
 
-**Root cause:** The GitHub REST API returns 30 items per page by default. `gh api repos/<owner>/<repo>/pulls/<number>/reviews` and `gh api repos/<owner>/<repo>/pulls/<number>/comments` silently truncate at 30 results without warning. PRs that have accumulated more than 30 reviews or inline comments — common on long PR-loop cycles where bugbot, copilot, or the in-house bugteam each post repeatedly — return only the **oldest** 30, hiding the most recent reviews and findings entirely. A `sort_by(.submitted_at) | last` (or `| reverse`) on a truncated array picks the latest entry **within the first 30**, not the actual latest, which produces a stale-but-confident report that then drives wrong decisions (e.g., re-triggering bugbot when it has already posted a CLEAN review on a later page).
+**Root cause:** GitHub REST API list endpoints paginate by default. Without `--paginate --slurp`, callers see only the oldest page, and cross-page jq operations (e.g., `sort_by | last`) operate within a single page — producing wrong-but-confident results.
 
 **Rule:** All `gh api` calls that read `pulls/<number>/reviews`, `pulls/<number>/comments`, `issues/<number>/comments`, or any other paginated GitHub list endpoint **must** request the full set of pages AND apply any cross-page jq operation through external `jq`, not through `gh`'s built-in `--jq`. Use `--paginate --slurp | jq` (preferred — see [Safe patterns](#safe-patterns)). Never call these endpoints with their default pagination, and never use `gh`'s `--jq` for cross-page operations like `sort_by | last` or `| reverse | .[0]`.
 
@@ -8,8 +8,8 @@
 
 This rule guards against two distinct silent-truncation defects that compound:
 
-1. **Default 30-item page.** Without `--paginate`, only the first page is fetched. On long PRs this hides the most recent reviews entirely.
-2. **`--jq` runs per-page, not on the concatenated result.** Per [GitHub CLI #10459](https://github.com/cli/cli/issues/10459), `gh api --paginate --jq '<filter>'` applies `<filter>` to each page **separately** and emits one output per page. Cross-page operations like `sort_by(.submitted_at) | last` therefore operate within each page independently, not across the merged result set. On PRs with more than 100 reviews this still produces a wrong-but-confident "latest" review even when `--paginate` is set.
+1. **Default page truncation.** Without `--paginate`, only the first page is fetched.
+2. **`--jq` runs per-page, not on the concatenated result.** Per [GitHub CLI #10459](https://github.com/cli/cli/issues/10459), `gh api --paginate --jq '<filter>'` applies `<filter>` to each page **separately** and emits one output per page. Cross-page operations like `sort_by(.submitted_at) | last` therefore operate within each page independently, not across the merged result set.
 
 The safe patterns below fix both defects together: `--paginate --slurp` walks every page AND emits a single merged structure, and an **external** `jq` then runs cross-page operations on that merged structure.
 
@@ -39,7 +39,7 @@ gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate --s
   | jq '[.[][] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
 ```
 
-The `.[][]` flattens the array-of-pages into one stream of items before the cross-page operators (`sort_by`, `last`, `reverse`) run. Combine with `?per_page=100` so each page fetches 100 items instead of 30, reducing round-trips on long PRs without changing correctness.
+The `.[][]` flattens the array-of-pages into one stream of items before the cross-page operators (`sort_by`, `last`, `reverse`) run. Combine with `?per_page=100` to reduce round-trips on long PRs.
 
 `gh`'s `--jq` flag and `--slurp` flag are mutually exclusive (gh CLI rejects `--paginate --slurp --jq` with `the --slurp option is not supported with --jq or --template`), which is why the filter must run in an external `jq` invocation.
 
@@ -74,52 +74,6 @@ gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate --s
 
 This is the canonical pattern for the bugbot ↔ bugteam convergence loop: walk newest-first, stop at the first clean review.
 
-## What NOT to do
-
-```bash
-# BAD — default 30-item page silently truncates on long PRs
-gh api repos/<owner>/<repo>/pulls/<number>/reviews \
-  --jq '[.[] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
-
-# BAD — `?per_page=100` alone caps at 100 items; PRs with 100+ reviews still truncate
-gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' \
-  --jq '[.[] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
-
-# BAD — --paginate fetches every page, but `--jq` runs PER-PAGE (gh CLI #10459).
-# `sort_by(.submitted_at) | last` operates within each page independently and
-# emits one "latest" per page, not the actual latest across the full result set.
-gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate \
-  --jq '[.[] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
-
-# BAD — taking `| last` on an unpaginated read returns the latest of the first 30,
-# not the actual latest. Same defect for `| reverse | .[0]`.
-```
-
-## Why both defects matter
-
-`gh api`'s default page is the FIRST page of results, ordered oldest-to-newest by the GitHub API. When the result set exceeds 30 items, page 1 contains the OLDEST 30 — not the newest. A jq `| last` after `sort_by(.submitted_at)` picks the latest entry within those 30 oldest items, producing output that looks correct but reports a state from days or weeks ago.
-
-`--paginate` alone does NOT fix this when paired with `--jq`: gh applies the jq filter to each page separately and emits one result per page. A consumer reading "the last line of output" still gets the latest within a single page, not the latest across all pages. The skill that consumes this output then makes decisions (re-trigger bugbot, mark a finding stale, report convergence) against an obsolete view of the PR.
-
-`--paginate --slurp | jq` fixes both defects: every page is fetched, every page is merged into one structure before any jq operator runs, and cross-page operations see the full result set.
-
-## Consumers
-
-Skills and scripts in this repo that read paginated endpoints and must therefore use `--paginate --slurp` plus external `jq`:
-
-- `pr-converge` — bugbot review walk (BUGBOT phase, Step 2.a) and inline-comments fetch (Step 2.b).
-- `bugteam` — review threads, inline comments, audit-loop history.
-- `qbug` — same as bugteam, scoped to a single subagent loop.
-- `pr-review-responder` — review comments fetch (already enforced; this rule extends the same constraint to reviews and other endpoints).
-- `monitor-many` — open-PR enumeration and per-PR review/comment scans.
-- `babysit-pr` — review-comment polling.
-
-Updating any of these to read paginated endpoints requires `--paginate --slurp` plus external `jq` (or a documented single-page bound on a small list).
-
 ## Enforcement
 
 This rule is documentation-only at present. A future PreToolUse hook may pattern-match `Bash` invocations of `gh api repos/.../pulls/<n>/(reviews|comments)` without `--paginate --slurp` (or with `--paginate --jq` doing cross-page operations) and return a corrective message. Until that hook lands, treat this rule as binding by review and rely on it during skill authoring.
-
-## Precedent
-
-The `pr-review-responder` skill predated this rule and forbids default pagination on `pulls/<n>/comments` reads (`packages/claude-dev-env/skills/pr-review-responder/SKILL.md` Rule 1). This file generalizes that constraint to every paginated GitHub endpoint, adds the `--jq` per-page defect (gh CLI #10459) discovered while reviewing this rule, and centralizes the safe patterns so additional skills inherit the rule by reference instead of restating it.

package/rules/no-historical-clutter.md

@@ -0,0 +1,36 @@
+---
+paths: **/*.md
+---
+
+# No Historical Clutter in Documentation
+
+**When this applies:** Any Write or Edit to `.md` files.
+
+## Rule
+
+Never reference removed implementations, old defaults, prior behaviors, or how something "used to be" when updating documentation. The current state is all that matters.
+
+## Examples of prohibited patterns
+
+| Pattern | Why it's clutter |
+|---------|-----------------|
+| "instead of 30" in a pagination rule | The old default no longer exists in code; the rule reader doesn't need to know what it was |
+| "previously this used X" | If X is gone, it's noise |
+| "before this rule, we did Y" | The rule exists now; the before-state is irrelevant |
+| "migrated from Z to W" | If Z is fully removed, the migration story is git history, not documentation |
+| "the old implementation did A" | If A is gone, the reader gains nothing from knowing it existed |
+| "originally" / "used to be" | Same — dead context |
+
+## What IS allowed
+
+- Comparisons to *currently existing* alternatives (e.g., "use `--paginate --slurp | jq`, not `--jq` alone")
+- Rationale that explains *why* a pattern is wrong in terms of present behavior (e.g., "`--jq` runs per-page, so cross-page operations produce wrong results")
+- References to external sources for defects that still exist (e.g., gh CLI #10459)
+
+## The test
+
+After writing documentation, ask: **"If someone reads this a year from now, with no knowledge of what came before, does every sentence still make sense and add value?"** If a sentence only adds value to someone who knew the old state, delete it.
+
+## Why
+
+Historical references clog context windows and force readers to mentally filter "what was" from "what is." The git log is the authoritative record of what changed and why. Documentation describes the current contract.

package/skills/bugteam/CONSTRAINTS.md

@@ -10,12 +10,12 @@
 - **Code rules gate before every AUDIT.** Run `_shared/pr-loop/scripts/code_rules_gate.py` (resolved via `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/code_rules_gate.py`) until exit **0** before spawning **bugfind**. Same `validate_content` logic as `hooks/blocking/code_rules_enforcer.py`.
 - **Clean-room audits, every loop.** Each bugfind subagent's spawn prompt contains only the PR scope, audit rubric, and the current loop number. Prior loop history stays in the lead.
 - **Targeted fixes.** Each fix subagent sees ONLY the most recent audit's findings. Prior loops are invisible to the fix subagent.
-- **Opus 4.7 at xhigh effort for 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).
+- **Opus 4.7 at xhigh effort for validator and fix subagents.** Single-auditor mode, validator, and fix spawns pass `model="opus"`; parallel-auditor siblings (`-b` through `-k`) pass `model="haiku"`. Opus 4.7's default effort level in Claude Code is `xhigh` (https://code.claude.com/docs/en/model-config — *"On Opus 4.7, the default effort is `xhigh` for all plans and providers."*), so no `effort` override is needed at spawn time. Effort is set per-subagent in YAML frontmatter, not via the `Agent` tool's parameters; `code-quality-agent` and `clean-coder` rely on the model default. The trade vs Sonnet is higher per-loop cost in exchange for deeper audit recall and stronger fix correctness on bug-hunting work, which the per-PR loop economics tolerate (10-loop hard cap bounds total spend).
 - **Fix subagent receives the latest audit as its input contract.** Passing the audit's findings to the fix subagent is the input contract — each loop's fix run operates on the current audit's output and only that.
 - **One commit per fix action.** Loops produce one commit per loop, not one per bug.
 - **Linear branch, fixed PR base.** Every loop appends one forward-only commit; existing commits and the PR base stay intact throughout the cycle.
 - **Lead-only cleanup.** Cleanup runs in the lead (this session) only. Step 4 removes the full `<run_temp_dir>` so no loop patches leak between runs.
-- **Cleanup all `.bugteam-*` files on exit.** The per-run `<run_temp_dir>` is removed entirely by Step 4, which covers `<run_temp_dir>/pr-<N>/loop-<L>.patch` and `<run_temp_dir>/pr-<N>/loop-<L>-{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.
+- **Cleanup all `.bugteam-*` files on exit.** The per-run `<run_temp_dir>` is removed entirely by Step 4, which covers `<run_temp_dir>/pr-<N>/loop-<L>.patch` and `<run_temp_dir>/pr-<N>/loop-<L>-<letter>.outcomes.xml`. The per-loop outcomes XML at `<worktree_path>/.bugteam-pr<N>-loop<L>.outcomes.xml` is removed with the worktree. Step 4.5 deletes `.bugteam-final.diff`, `.bugteam-original-body.md`, and `.bugteam-final-body.md`. Working directory ends clean.
 - **Audit/fix comment posting.** The bugfind subagent posts ONE per-loop review (parent body + child finding comments in a single batched POST, with review-fallback to a top-level issue comment). The bugfix subagent posts the fix replies after committing. All comment, review, and reply POSTs belong to the subagents; the lead's single PR-write action is the final description rewrite at Step 4.5.
 - **Lead owns the final PR description rewrite only** (Step 4.5), and only via the `pr-description-writer` agent. The lead does not compose the description inline.
 - **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.

package/skills/bugteam/PROMPTS.md

@@ -10,7 +10,7 @@ Keep the spawn prompt self-contained: reference only the PR scope, audit rubric,
   <branch>head ref</branch>
   <base_branch>base ref</base_branch>
   <pr_url>full URL</pr_url>
-  <loop>N</loop>
+  <loop>L</loop>
   <pr_number>N</pr_number>
   <worktree_path>absolute path from Step 1 per-PR workspace</worktree_path>
 </context>
@@ -45,11 +45,17 @@ cd into `<worktree_path>` before any git, gh, or file operation.
 </constraints>
 
 <comment_posting>
+  Sibling auditors (-b through -k): run only steps 1–3 (audit, assign IDs,
+  capture excerpt, validate anchors), then write outcome XML per <output_format> and return.
+  Skip steps 4–8 — sibling auditors do not post PR reviews.
+
+  Validator (-a) and single-opus auditors: run all steps below.
+
   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
+  2. Assign each finding a stable finding_id of exactly the form `loop<L>-<K>`
+     where <K> is 1-based within this loop.
+  3. For each finding, capture a verbatim excerpt from the target file at the cited line. Populate the `<excerpt>` element in the outcome XML with it. 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).
@@ -61,7 +67,7 @@ cd into `<worktree_path>` before any git, gh, or file operation.
        Category: <letter> (<category name>)
        <2-3 sentence description with concrete trace>
 
-       _From /bugteam audit loop N._
+       _From /bugteam audit loop <L>._
 
   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[]`
@@ -76,17 +82,17 @@ cd into `<worktree_path>` before any git, gh, or file operation.
 </comment_posting>
 
 <output_format>
-  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:
+  For the (-a) validator: 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 through -k): write to <run_temp_dir>/pr-<N>/loop-<L>-<letter>.outcomes.xml (absolute path passed in prompt). Sibling auditors do not post PR reviews; set review_url, finding_comment_id, and finding_comment_url to empty strings, and used_fallback to "false". Omit unanchored findings from sibling output — only the validator handles those. 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>">
+<bugteam_audit loop="<L>" review_url="<url>">
   <finding
-    finding_id="loop<N>-<index>"
+    finding_id="loop<L>-<K>"
     severity="P0|P1|P2"
     category="<letter>"
     file="<path>"
@@ -96,6 +102,7 @@ cd into `<worktree_path>` before any git, gh, or file operation.
     used_fallback="true|false"
   >
     <title>one-line title</title>
+    <excerpt>verbatim source line or snippet from the file at the cited line</excerpt>
     <description>2-3 sentence description with concrete trace</description>
   </finding>
   <verified_clean>
@@ -114,7 +121,7 @@ After the teammate writes the XML and returns, the lead reads `.bugteam-pr<N>-lo
   <branch>head</branch>
   <base_branch>base</base_branch>
   <pr_url>url</pr_url>
-  <loop>N</loop>
+  <loop>L</loop>
   <pr_number>N</pr_number>
   <worktree_path>absolute path from Step 1 per-PR workspace</worktree_path>
 </context>
@@ -124,7 +131,7 @@ cd into `<worktree_path>` before any git, gh, or file operation.
 <bugs_to_fix>
   [for each P0/P1/P2 finding from last_findings:]
   <bug
-    finding_id="loop<N>-<index>"
+    finding_id="loop<L>-<K>"
     severity="P0|P1|P2"
     file="<path>"
     line="<int>"
@@ -156,9 +163,9 @@ cd into `<worktree_path>` before any git, gh, or file operation.
 </execution>
 
 <outcome_xml_schema>
-  <bugteam_fix loop="<N>" commit_sha="<sha or empty if no commit>">
+  <bugteam_fix loop="<L>" commit_sha="<sha or empty if no commit>">
     <outcome
-      finding_id="loop<N>-<index>"
+      finding_id="loop<L>-<K>"
       status="fixed|could_not_address|hook_blocked"
       commit_sha="<sha if fixed, empty otherwise>"
       reply_comment_id="<id of the reply posted>"

package/skills/bugteam/SKILL.md

@@ -184,7 +184,7 @@ only PR write before Step 4.5 is the final description rewrite.
 
 Order: audit → buffer → validate anchors vs diff → single review POST.
 Review body states counts; zero findings → still one review, `comments: []`,
-body `## /bugteam loop <N> audit: 0P0 / 0P1 / 0P2 → clean`.
+body `## /bugteam loop <L> audit: 0P0 / 0P1 / 0P2 → clean`.
 
 **Payloads:** build JSON with `jq --rawfile` / `-Rs`, pipe to `gh api ...
 --input -` (avoids shell-quoting; satisfies `gh-body-backtick-guard`). Write
@@ -228,7 +228,7 @@ before POST.
 **Review body template (`<tmp_review_body.md>`):**
 
 ```
-## /bugteam loop <N> audit: <P0>P0 / <P1>P1 / <P2>P2
+## /bugteam loop <L> audit: <P0>P0 / <P1>P1 / <P2>P2
 
 ### Findings without a diff anchor
 (only if needed)
@@ -318,11 +318,11 @@ Non-zero → spawn **clean-coder** standards-fix (read stderr, edit, re-run
 **5**
 failed gate rounds → `error: code rules gate failed pre-audit`. After **0**:
 `loop_count += 1`; if `loop_count > 10` → `cap reached`. Then **AUDIT**
-(bugfind); print `Loop <N> audit: ...`.
+(bugfind); print `Loop <L> audit: ...`.
 
 3. **FIX** (`last_action == "audited"` and `last_findings.total > 0`):
    `loop_count += 1`; if `loop_count > 10` → `cap reached`; **FIX** (bugfix);
-   print `Loop <N> fix: ...`; `last_action = "fixed"`, update `audit_log`; loop
+   print `Loop <L> fix: ...`; `last_action = "fixed"`, update `audit_log`; loop
    to step 1.
 
 4. After **AUDIT**: update `last_action`, `last_findings`, `audit_log`; print
@@ -361,18 +361,31 @@ background-completion notification, then reads
 `last_action = "audited"`; append audit line to `audit_log`.
 
 **Parallel auditors (`loop_count >= 4`):** gate passes immediately before;
-after three full audit/fix rounds without convergence, issue three `Agent`
-calls in one assistant message (`run_in_background=true`): `-a` posts the
-review and merges outcomes from `-b`/`-c` (read
-`.bugteam-pr<N>-loop<L>.outcomes.xml` plus
-`<run_temp_dir>/pr-<N>/loop-<L>-b.outcomes.xml` and `...-c...`); merge key
-`(file, line, category_letter)`; re-id `loopN-K`. `-b`/`-c` write sibling XML
-only; prompts must pass literal absolute sibling paths. Output path
-contract: `-b`/`-c` write to `<run_temp_dir>/pr-<N>/loop-<L>-b.outcomes.xml`
-and `<run_temp_dir>/pr-<N>/loop-<L>-c.outcomes.xml`; `-a` writes to
-`<worktree_path>/.bugteam-pr<N>-loop<L>.outcomes.xml`.
-Lead awaits all three background-completion notifications before merging
-outcomes.
+after three full audit/fix rounds without convergence, issue eleven `Agent`
+calls in one assistant message (`run_in_background=true`):
+
+- **10 haiku auditors (`-b` through `-k`):** `subagent_type="code-quality-agent"`,
+  `model="haiku"`, write sibling XML to
+  `<run_temp_dir>/pr-<N>/loop-<L>-<letter>.outcomes.xml`, skip PR posting.
+  Prompts must pass literal absolute sibling paths.
+- **1 opus validator (`-a`):** `subagent_type="code-quality-agent"`,
+  `model="opus"`:
+  - Polls for all 10 sibling XMLs before proceeding (60s timeout, 2s interval). On timeout: log diagnostics entry, proceed with validated findings from available XMLs, report count in validator output.
+  - Validates each finding: file exists, line in bounds, excerpt contains the exact
+    text of the cited line, category is A–J, severity is P0/P1/P2.
+  - Hallucinated findings → quarantined to `<run_temp_dir>/pr-<N>/loop-<L>-diagnostics.json` under
+    `validator_rejected` (added alongside the required diagnostics keys defined in the shared audit contract).
+  - De-dups by `(file, line, category)`, max severity wins; on conflict, keep longest description text.
+  - Re-ids as `loop<L>-<K>`.
+  - Writes `<worktree_path>/.bugteam-pr<N>-loop<L>.outcomes.xml`, posts review.
+
+Lead awaits the opus validator (-a) background-completion notification (120s
+timeout). The validator independently polls all 10 sibling XMLs; the lead does
+not gate on haiku peer completion. On lead timeout: the validator did not post
+a merged review — treat as a hard blocker and abort the loop.
+
+The sibling-output paths in [`PROMPTS.md`](PROMPTS.md) must cover the full
+`-b` through `-k` range.
 
 ### FIX action
 

package/skills/bugteam/SKILL_EVALS.md

@@ -22,9 +22,9 @@ Each invariant cites the normative section or companion file it derives from. Al
 | I-2 | `Bash` invoking `scripts/revoke_project_claude_permissions.py` runs exactly once per invocation on every exit path, after teardown. | `SKILL.md` § Step 5 |
 | I-3 | Orchestration uses `Agent(..., run_in_background=true)` only — no `TeamCreate`, `TeamDelete`, `SendMessage`, or `Task` tool calls. | `SKILL.md` § Step 2; § Step 4 |
 | I-4 | `Agent` calls are fresh per loop (`run_in_background=true`; new `name` each loop). | `CONSTRAINTS.md` — **Fresh subagent per loop** |
-| I-5 | Audit and fix spawns pass `model="opus"` on every `Agent` call. | `SKILL.md` § AUDIT action; § FIX action; `CONSTRAINTS.md` — **Opus 4.7 at xhigh effort for both subagents** |
+| I-5 | Audit sibling spawns pass `model="haiku"`; validator and fix spawns pass `model="opus"`. | `SKILL.md` § AUDIT action (parallel auditors); § FIX action; `CONSTRAINTS.md` — **Opus 4.7 at xhigh effort for validator and fix subagents** |
 | I-6 | Loop count ≤ 10 audits. 11th audit never fires. | `SKILL.md` YAML `description` (10-loop cap); § Step 3 (**Pre-audit** / **FIX** increment rules) |
-| I-7 | From loop 4 onward without convergence, three parallel `Agent(..., run_in_background=true)` calls in one message for audit. | `SKILL.md` § AUDIT action (**Parallel auditors**) |
+| I-7 | From loop 4 onward without convergence, eleven parallel `Agent(..., run_in_background=true)` calls in one message for audit. | `SKILL.md` § AUDIT action (**Parallel auditors**) |
 | I-8 | Lead reads `.bugteam-pr<N>-loop<L>.outcomes.xml` with the `Read` tool after each audit, before the next action. | `SKILL.md` § AUDIT action |
 | I-9 | Teardown sequence: `git worktree remove` each PR → `rmtree` `<run_temp_dir>` → Step 4.5 → revoke. | `SKILL.md` § Step 4; § Step 4.5; § Step 5 |
 | I-10 | The bugfind subagent posts ONE per-loop review; the bugfix subagent posts fix replies. The lead's only PR-write action is the Step 4.5 description rewrite. | `CONSTRAINTS.md` — **Audit/fix comment posting** |
@@ -171,14 +171,14 @@ Patch this table to match observation and annotate each correction.
 
 **Layer B predicted behavior.**
 - Loops 1–3: single `Agent(name="bugfind-pr<N>-loop<L>", run_in_background=true)` per loop.
-- Loops 4–10: three parallel `Agent(name="bugfind-pr<N>-loop<L>-[abc]", run_in_background=true)` in a single assistant message per loop; lead awaits all three notifications then merges outcomes.
+- Loops 4–10: eleven parallel `Agent(name="bugfind-pr<N>-loop<L>-[a..k]", run_in_background=true)` in a single assistant message per loop (10 haiku + 1 opus validator); lead awaits the validator notification.
 - Each loop produces one `Agent(name="bugfix-pr<N>-loop<L>", run_in_background=true)`.
 - Exactly 10 audit phases, exactly 10 fix phases.
 - Steps 19–26 from Eval 5 fire at teardown.
 
 **Pass criteria.**
 - I-6 holds: exactly 10 audit phases.
-- I-7 holds: loops 4–10 each emit three audit `Agent` calls in a single assistant message.
+- I-7 holds: loops 4–10 each emit eleven audit `Agent` calls in a single assistant message.
 - Final report contains `/bugteam exit: cap reached` and the remaining bug count.
 
 **Process check.** The distinct `Agent(name=...)` audit-call count is a prediction. On the first real run, record the exact count and rewrite the formula here.

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

@@ -24,11 +24,11 @@ Repeat until an exit condition fires.
    2. If exit code **0** → continue to step 2.5 (AUDIT spawn) below.
    3. If exit code **non-zero** → spawn a new **clean-coder** teammate — **standards-fix pass** — with instructions: read the script’s stderr, edit the repo until a **re-run** of the **same** gate command exits **0**, then one commit, `git push`, shutdown. Repeat standards-fix spawns until the gate exits **0** or **5** failed gate rounds (each round = one teammate session after a non-zero gate). If still non-zero after 5 rounds → exit reason = `error: code rules gate failed pre-audit`.
    4. After gate exit **0**, increment `loop_count`. If `loop_count > 10`, exit reason = `cap reached` (counts **audits**, not standards-only rounds).
-   5. Execute **AUDIT action** (spawn bugfind). Print progress: `Loop <N> audit: ...`
+   5. Execute **AUDIT action** (spawn bugfind). Print progress: `Loop <L> audit: ...`
 
 3. **FIX path** (when `last_action == "audited"` and `last_findings.total > 0`):
    1. Increment `loop_count`. If `loop_count > 10`, exit reason = `cap reached`.
-   2. Execute **FIX action** (spawn bugfix clean-coder for audit findings). Print: `Loop <N> fix: commit ...`
+   2. Execute **FIX action** (spawn bugfix clean-coder for audit findings). Print: `Loop <L> fix: commit ...`
    3. Set `last_action = "fixed"`, update `audit_log`, loop to step 1 (next iteration hits **pre-audit path** before the next AUDIT).
 
 4. After **AUDIT**, update `last_action`, `last_findings`, `audit_log`; print the audit progress line if not already printed.
@@ -39,62 +39,45 @@ Repeat until an exit condition fires.
 
 ## AUDIT action (clean-room teammate, fresh per loop)
 
-Capture a fresh PR diff for this loop into the per-team scoped directory so concurrent `/bugteam` runs keep patches isolated. Use the literal `<team_temp_dir>` resolved once in Step 2 — Claude resolves the absolute path; every shell receives the same literal value.
+Capture a fresh PR diff for this loop into the per-PR scoped directory so concurrent `/bugteam` runs keep patches isolated. Use the literal `<run_temp_dir>` resolved once in Step 2 — Claude resolves the absolute path; every shell receives the same literal value.
 
 Commands and `Agent(...)` shape: `SKILL.md`.
 
-`<team_temp_dir>` includes the sanitized `team_name` and timestamp; `team_name` is already prefixed with `bugteam-`. Claude resolves `Path(tempfile.gettempdir()) / team_name` once and passes that absolute path to every shell. `tempfile.gettempdir()` honors `TMPDIR`, `TEMP`, `TMP` and falls back to the OS temp directory, so the same approach works on macOS, Linux, Windows cmd.exe, and PowerShell.
+`<run_temp_dir>` includes the sanitized `team_name` and timestamp; `team_name` is already prefixed with `bugteam-`. Claude resolves `Path(tempfile.gettempdir()) / team_name` once and passes that absolute path to every shell. `tempfile.gettempdir()` honors `TMPDIR`, `TEMP`, `TMP` and falls back to the OS temp directory, so the same approach works on macOS, Linux, Windows cmd.exe, and PowerShell.
 
 Each loop calls `Agent` again with a fresh invocation so the teammate starts with its own context window. Doc line on lead history: [`../sources.md`](../sources.md).
 
 See [`../PROMPTS.md`](../PROMPTS.md) for AUDIT spawn-prompt XML and bugfind outcome schema. Substitute placeholders (`repo`, `branch`, `base_branch`, `pr_url`, `loop`, `diff_path`) into the `prompt` argument.
 
-After the teammate returns, the lead reads `.bugteam-loop-<N>.outcomes.xml` with the `Read` tool, parses it, and populates `loop_comment_index` from `<finding>` elements.
+After the teammate returns, the lead reads `.bugteam-pr<N>-loop<L>.outcomes.xml` from the worktree directory with the `Read` tool, parses it, and populates `loop_comment_index` from `<finding>` elements.
 
 ### Shutdown (bugfind)
 
-**Expected path — self-termination:** Teammates often self-terminate when complete — the `Agent` call returns and the session ends. Then no `SendMessage` is needed.
-
-**Fallback — lead-initiated shutdown:** If the teammate still appears active after `Agent` returns, send:
-
-```
-SendMessage(
-  to="bugfind",
-  message={
-    "type": "shutdown_request",
-    "reason": "audit loop <N> complete; outcome XML captured"
-  }
-)
-```
-
-The teammate replies with `{type: "shutdown_response", approve: true}`. If `approve` is `false`, exit reason = `error: bugfind teammate refused shutdown` → Step 4 teardown then Step 5 revoke.
+Teammates self-terminate when complete — the background-completion notification arrives and the lead reads the outcomes XML. If the notification does not arrive within the lead timeout (120s), treat as a hard blocker and abort the loop.
 
 `last_action = "audited"`. Append audit metadata to `audit_log`.
 
 ### Parallel auditors (`loop_count >= 4`)
 
-The pre-audit gate must pass immediately before this step. After three full audit/fix rounds without convergence, issue three `Agent` calls in **one** assistant message so they run in parallel:
+The pre-audit gate must pass immediately before this step. After three full audit/fix rounds without convergence, issue eleven `Agent` calls in **one** assistant message so they run in parallel:
 
 ```
-Agent(subagent_type="code-quality-agent", name="bugfind-loop-<N>-a", team_name="<team_name>", model="opus", description="Bugfind audit loop <N> variant a", prompt="<audit XML; write outcome to .bugteam-loop-<N>.outcomes.xml; post the per-loop review; read and merge b/c outcomes from <team_temp_dir>/loop-<N>-b.outcomes.xml and <team_temp_dir>/loop-<N>-c.outcomes.xml>")
-Agent(subagent_type="code-quality-agent", name="bugfind-loop-<N>-b", team_name="<team_name>", model="opus", description="Bugfind audit loop <N> variant b", prompt="<audit XML; write outcome to <team_temp_dir>/loop-<N>-b.outcomes.xml; skip PR posting>")
-Agent(subagent_type="code-quality-agent", name="bugfind-loop-<N>-c", team_name="<team_name>", model="opus", description="Bugfind audit loop <N> variant c", prompt="<audit XML; write outcome to <team_temp_dir>/loop-<N>-c.outcomes.xml; skip PR posting>")
+Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-a", team_name="<team_name>", model="opus", run_in_background=true, description="Bugfind audit PR <N> loop <L> validator", prompt="<audit XML; poll for all 10 sibling XMLs at <run_temp_dir>/pr-<N>/loop-<L>-b.outcomes.xml through <run_temp_dir>/pr-<N>/loop-<L>-k.outcomes.xml (60s timeout, 2s interval); on timeout: log diagnostics entry, proceed with validated findings from available XMLs; validate each finding: file exists, line in bounds, excerpt matches claimed line, category A-J, severity P0/P1/P2; quarantine hallucinated findings to <run_temp_dir>/pr-<N>/loop-<L>-diagnostics.json under validator_rejected; de-dup by (file, line, category), max severity wins, keep longest description on conflict; re-id as loop<L>-<K>; write <worktree_path>/.bugteam-pr<N>-loop<L>.outcomes.xml; post review>")
+Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-b", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant b", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-b.outcomes.xml; skip PR posting>")
+Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-c", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant c", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-c.outcomes.xml; skip PR posting>")
+Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-d", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant d", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-d.outcomes.xml; skip PR posting>")
+Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-e", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant e", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-e.outcomes.xml; skip PR posting>")
+Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-f", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant f", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-f.outcomes.xml; skip PR posting>")
+Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-g", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant g", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-g.outcomes.xml; skip PR posting>")
+Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-h", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant h", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-h.outcomes.xml; skip PR posting>")
+Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-i", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant i", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-i.outcomes.xml; skip PR posting>")
+Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-j", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant j", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-j.outcomes.xml; skip PR posting>")
+Agent(subagent_type="code-quality-agent", name="bugfind-pr<N>-loop<L>-k", team_name="<team_name>", model="haiku", run_in_background=true, description="Bugfind audit PR <N> loop <L> variant k", prompt="<audit XML; write outcome to <run_temp_dir>/pr-<N>/loop-<L>-k.outcomes.xml; skip PR posting>")
 ```
 
-Teammate `-a` is the post-owner: read all three outcome XML files at explicit absolute paths (`.bugteam-loop-<N>.outcomes.xml` in cwd, plus sibling paths under `<team_temp_dir>`), merge findings by `(file, line, category_letter)` (collapse duplicates, keep longest description and highest severity), re-assign merged IDs as `loopN-K`, post the single per-loop review. The `-a` prompt must embed sibling paths as literal absolutes so `Read` works without discovery.
-
-Shutdown order: parallel `SendMessage` to `b` and `c`, then `a`:
+Teammate `-a` is the opus validator: polls for all 10 sibling XMLs at explicit absolute paths under `<run_temp_dir>/pr-<N>` (60s timeout, 2s interval; on timeout: log diagnostics entry, proceed with validated findings from available XMLs), then validates each finding — file exists, line in bounds, excerpt matches claimed line, category is A–J, severity is P0/P1/P2. Hallucinated findings are quarantined to `<run_temp_dir>/pr-<N>/loop-<L>-diagnostics.json` under `validator_rejected`. Valid findings are de-duplicated by `(file, line, category)` (max severity wins, keep longest description on conflict) and re-assigned merged IDs as `loop<L>-<K>`. The `-a` prompt must embed sibling paths as literal absolutes so `Read` works without discovery.
 
-```
-SendMessage(to="bugfind-loop-<N>-b", message={"type": "shutdown_request", "reason": "variant XML captured"})
-SendMessage(to="bugfind-loop-<N>-c", message={"type": "shutdown_request", "reason": "variant XML captured"})
-```
-
-then
-
-```
-SendMessage(to="bugfind-loop-<N>-a", message={"type": "shutdown_request", "reason": "merged review posted"})
-```
+All subagents self-terminate via background completion. The lead awaits only the validator (-a) notification (120s timeout). Missing notification → hard blocker.
 
 ## FIX action (fresh teammate)
 
@@ -106,17 +89,7 @@ After replies, the teammate writes outcome XML (schema in [`../PROMPTS.md`](../P
 
 ### Shutdown (bugfix)
 
-Same self-termination vs `SendMessage` split as bugfind. Fallback message:
-
-```
-SendMessage(
-  to="bugfix",
-  message={
-    "type": "shutdown_request",
-    "reason": "fix loop <N> complete; commit <sha7> pushed"
-  }
-)
-```
+Same self-termination model as bugfind. Missing notification → hard blocker.
 
 `approve: false` → `error: bugfix teammate refused shutdown` → Step 4 then 5.
 

package/skills/bugteam/reference/audit-contract.md

@@ -8,7 +8,7 @@ Shared output schema and audit-loop contract used by `/bugteam`, `/qbug`, `/find
 - Adversarial second pass
 - Haiku secondary auditor
 - Post-fix self-audit
-- Persistence (loop-N-audit.json, loop-N-diagnostics.json)
+- Persistence (loop-<L>-audit.json, loop-<L>-diagnostics.json)
 
 ## Finding schema
 
@@ -18,7 +18,7 @@ Each finding an audit produces MUST be one of exactly two shapes.
 
 ```json
 {
-  "id": "loop<N>-<K>",
+  "id": "loop<L>-<K>",
   "file": "path/relative/to/repo/root.py",
   "line": 123,
   "category": "A | B | C | D | E | F | G | H | I | J",
@@ -29,7 +29,7 @@ Each finding an audit produces MUST be one of exactly two shapes.
 }
 ```
 
-`id` is `loop<N>-<K>` where `N` is the loop counter (1-based) and `K` is the 1-based index within the loop. For `/findbugs` which runs once, use `find<K>`.
+`id` is `loop<L>-<K>` where `L` is the loop counter (1-based) and `K` is the 1-based index within the loop. For `/findbugs` which runs once, use `find<K>`.
 
 ### Shape B — structured proof-of-absence
 
@@ -105,9 +105,9 @@ Merge rules:
 - **Unique-to-Haiku findings**: added to the primary set with Haiku's severity and source annotation.
 - **Unique-to-primary findings**: kept as-is.
 - **Zero Haiku findings**: primary set trusted; proceed.
-- **Malformed or non-parseable Haiku output**: lead trusts the primary set, logs the event in `loop-<N>-diagnostics.json` under `haiku_findings` as `[{"parse_error": "<message>"}]`.
+- **Malformed or non-parseable Haiku output**: lead trusts the primary set, logs the event in `loop-<L>-diagnostics.json` under `haiku_findings` as `[{"parse_error": "<message>"}]`.
 
-For multi-subagent skills (`/bugteam`) the parallel-auditors pattern in [`audit-and-teammates.md`](audit-and-teammates.md) already provides cross-model coverage via the three variant teammates.
+For multi-subagent skills (`/bugteam`) the parallel-auditors pattern in [`audit-and-teammates.md`](audit-and-teammates.md) already provides cross-model coverage via 10 haiku auditors + opus validator.
 
 ## Post-fix self-audit
 
@@ -131,7 +131,7 @@ Sequence:
 
 Every audit loop writes two JSON files under the skill's scoped temp directory (resolved via `tempfile.gettempdir()`):
 
-### `loop-<N>-audit.json`
+### `loop-<L>-audit.json`
 
 ```json
 {
@@ -141,7 +141,7 @@ Every audit loop writes two JSON files under the skill's scoped temp directory (
 }
 ```
 
-### `loop-<N>-diagnostics.json`
+### `loop-<L>-diagnostics.json`
 
 ```json
 {

package/skills/pr-converge/reference/convergence-gates.md

@@ -23,20 +23,25 @@ Decide (four branches; match first whose predicate holds):
 
 - **`classification == "dirty"` with non-empty inline comments matching
   `pull_request_review_id`:** Fix protocol input (same shape as bugbot
-  dirty). Apply Fix protocol on every inline finding (TDD test →
-  production fix → push → reply inline on each thread), reset
-  `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase = BUGBOT`,
-  Step 3 on new HEAD, schedule next wakeup, return. Full
-  back-to-back-clean cycle plus all four gates must hold again on new HEAD.
+  dirty). Spawn Agent (subagent_type: clean-coder) to implement → push → reply inline on each thread via
+  `reply_to_inline_comment.py` → Step 3 in same tick (see
+  [Single-PR fix workflow](fix-protocol.md#single-pr-fix-workflow) for
+  full contract).
+  Reset `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase =
+  BUGBOT`, schedule next wakeup, return. Full back-to-back-clean cycle
+  plus all four gates must hold again on new HEAD.
 - **`classification == "dirty"` with empty inline comments matching
   `pull_request_review_id`:** Copilot posted findings only in review body
   (`CHANGES_REQUESTED` or `COMMENTED` with non-empty body, no inline
-  threads). Parse body for actionable findings, apply Fix protocol using
-  body excerpts (TDD test → production fix → push). Post top-level review
-  reply acknowledging fixes and citing new HEAD SHA. Reset
-  `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase =
-  BUGBOT`, Step 3 on new HEAD, schedule next wakeup, return. Convergence
-  requires full back-to-back-clean on new HEAD.
+  threads). Parse body for actionable findings. Spawn Agent (subagent_type: clean-coder) to implement → push → post
+  top-level review reply citing new HEAD SHA → Step 3 in same tick (see
+  [Single-PR fix workflow](fix-protocol.md#single-pr-fix-workflow) for
+  full contract).
+  Reset
+  `bugbot_clean_at = null` AND
+  `copilot_clean_at = null`, `phase = BUGBOT`, Step 3 on new HEAD,
+  schedule next wakeup, return. Convergence requires full
+  back-to-back-clean on new HEAD.
 - **`classification == "clean"` (state `APPROVED`):** Set
   `copilot_clean_at = current_head`. Continue to gate (b).
 - **No Copilot review on `current_head` yet:** Skip — gate (c) issues
@@ -89,13 +94,12 @@ Next tick with `phase == BUGTEAM` and prior state preserved → re-run gate
   current_head`. Mark PR ready (`mark_pr_ready.py`), report convergence
   per §(d), terminate per [stop-conditions.md](stop-conditions.md) / Convergence.
 - **Copilot review `dirty`:** Treat identically to gate (a) dirty path —
-  fix in same PR, restart convergence from BUGBOT. Apply Fix protocol on
-  every confirmed Copilot finding (TDD test → production fix → push →
-  reply inline on each thread; for body-only findings with empty inline,
-  parse body excerpts and post top-level review reply citing new HEAD).
-  Reset `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase =
-  BUGBOT`, Step 3 on new HEAD, schedule next wakeup, return. Full
-  back-to-back-clean cycle plus all four gates must hold again on new HEAD.
+  spawn Agent (subagent_type: clean-coder) to fix in same PR, restart convergence from BUGBOT. Follow [Single-PR fix workflow](fix-protocol.md#single-pr-fix-workflow).
+  For body-only findings with empty inline, spawn Agent (subagent_type: clean-coder) to implement, then post top-level review reply
+  citing new HEAD SHA. Reset `bugbot_clean_at = null` AND
+  `copilot_clean_at = null`, `phase = BUGBOT`, schedule next wakeup,
+  return. Full back-to-back-clean cycle plus all four gates must hold
+  again on new HEAD.
 - **No Copilot review at `current_head` yet (still propagating):**
   Schedule one more wakeup (270s), re-check next tick. After three consecutive empty waits,
   escalate as hard blocker per [stop-conditions.md](stop-conditions.md).

package/skills/pr-converge/reference/fix-protocol.md

@@ -20,6 +20,8 @@ per [ground-rules.md](ground-rules.md).
 Orchestrator does not reply inline, trigger bugbot, or read repo source
 files during fix phase in multi-PR mode.
 
+### Single-PR fix workflow
+
 **Single-PR (no `state.json`) — same gates, main session executor:**
 
 - Read each referenced file:line.

package/skills/pr-converge/reference/per-tick.md

@@ -37,9 +37,11 @@ state line when **no** `state.json` (single-PR only). With `state.json`, do
 **not** increment here — orchestrator's per-tick bump is sole increment.
 
 ```bash
-python "${CLAUDE_SKILL_DIR}/scripts/view_pr_context.py"
+python "${CLAUDE_SKILL_DIR}/scripts/view_pr_context.py" --owner <OWNER> --repo <REPO> --number <NUMBER>
 ```
 
+If owner/repo/number are not yet known, extract them from the PR URL or run without flags in a repo checkout.
+
 Capture `number`, `headRefOid` (= `current_head`), owner/repo, branch.
 
 ## Step 2: Branch on `phase`
@@ -93,9 +95,11 @@ c. Decide (four branches; match first whose predicate holds):
      `state.json`: clean-coder teammate pushes, replies inline, writes
      `state.json`, goes idle; Step 3 on new HEAD runs after via
      orchestrator-spawned follow-up agent (§Fix result → general-purpose).
-     No `state.json` (single-PR): implement → push → inline replies
-     → Step 3 in same tick per loaded pacing workflow. Schedule next
-     wakeup, return.
+     No `state.json` (single-PR): spawn Agent (subagent_type: clean-coder) to implement → push → reply inline on each thread
+     via `reply_to_inline_comment.py` → Step 3 in same tick (see
+     [Single-PR fix workflow](fix-protocol.md#single-pr-fix-workflow) for
+     full contract).
+     Schedule next wakeup, return.
    - **`commit_id == current_head` AND review body findings AND inline
      API zero matching for `current_head`:** Transient API lag. Increment
      `inline_lag_streak`. `>= 3` → hard blocker; report and terminate with
@@ -142,9 +146,8 @@ never falsely terminates:
      **omit loop pacing** per **Convergence** of active pacing workflow.
    - **Convergence BUT `bugbot_clean_at != current_head` (no push):**
      `phase = BUGBOT`, schedule next wakeup, return.
-   - **Findings without committed fixes:** apply **[fix-protocol.md](fix-protocol.md)**; Step 3
-     on new HEAD runs after fix handoff per `multi-pr-orchestration.md` or in-tick for
-     single-PR. `phase = BUGBOT`, schedule next wakeup, return.
+   - **Findings without committed fixes:** spawn Agent (subagent_type: clean-coder) to implement fixes and push, then reply inline via `reply_to_inline_comment.py`, following [Single-PR fix workflow](fix-protocol.md#single-pr-fix-workflow).
+     `phase = BUGBOT`, schedule next wakeup, return.
 
 ## Step 3: Re-trigger bugbot
 

package/skills/pr-converge/scripts/config/pr_converge_constants.py

@@ -67,6 +67,22 @@ BUGBOT_RUN_TEMPFILE_PREFIX: str = "pr-converge-bugbot-run-"
 
 PR_CONTEXT_FIELDS: str = "number,url,headRefOid,baseRefName,headRefName,isDraft"
 
+PR_DETACHED_HEAD_ARGS_ERROR: str = "--owner and --repo require --number; all three must be provided together for detached-HEAD PR resolution"
+
+PR_NUMBER_ARG_FLAG: str = "--number"
+
+PR_NUMBER_ARG_HELP: str = "PR number"
+
+PR_OWNER_ARG_FLAG: str = "--owner"
+
+PR_OWNER_ARG_HELP: str = "GitHub repository owner"
+
+PR_REPO_ARG_FLAG: str = "--repo"
+
+PR_REPO_ARG_HELP: str = "GitHub repository name"
+
+GH_REPO_FLAG: str = "--repo"
+
 MERGEABILITY_FIELDS: str = "mergeable,mergeStateStatus,headRefOid"
 
 GH_FIELD_BODY_AT_PREFIX: str = "body=@"

package/skills/pr-converge/scripts/test_view_pr_context.py

@@ -91,6 +91,26 @@ def test_should_raise_when_gh_subprocess_fails() -> None:
             view_pr_context_module.view_pr_context()
 
 
+def test_should_append_number_and_repo_flag_when_owner_repo_and_number_provided() -> None:
+    payload = json.dumps(
+        {
+            "number": 25,
+            "url": "https://github.com/acme/widget/pull/25",
+            "headRefOid": "abc123",
+            "baseRefName": "main",
+            "headRefName": "feat/x",
+            "isDraft": True,
+        }
+    )
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _completed(payload)
+        view_pr_context_module.view_pr_context(number="25", owner="acme", repo="widget")
+    invoked_argv = mock_run.call_args[0][0]
+    assert "25" in invoked_argv
+    assert "--repo" in invoked_argv
+    assert "acme/widget" in invoked_argv
+
+
 def test_should_pass_imported_constant_directly_without_local_alias() -> None:
     payload = json.dumps(
         {
@@ -109,3 +129,27 @@ def test_should_pass_imported_constant_directly_without_local_alias() -> None:
     fields_arg = invoked_argv[invoked_argv.index("--json") + 1]
     expected_fields = view_pr_context_module.PR_CONTEXT_FIELDS
     assert fields_arg is expected_fields
+
+
+def test_should_not_exit_when_number_provided_alone() -> None:
+    payload = json.dumps(
+        {
+            "number": 42,
+            "url": "https://github.com/acme/widget/pull/42",
+            "headRefOid": "abc123",
+            "baseRefName": "main",
+            "headRefName": "feat/x",
+            "isDraft": True,
+        }
+    )
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _completed(payload)
+        with patch("sys.argv", ["view_pr_context.py", "--number", "42"]):
+            return_code = view_pr_context_module.main()
+    assert return_code == 0
+
+
+def test_should_exit_when_owner_and_repo_provided_without_number() -> None:
+    with patch("sys.argv", ["view_pr_context.py", "--owner", "acme", "--repo", "widget"]):
+        with pytest.raises(SystemExit):
+            view_pr_context_module.main()

package/skills/pr-converge/scripts/view_pr_context.py

@@ -17,12 +17,33 @@ from evict_cached_config_modules import evict_cached_config_modules
 
 evict_cached_config_modules()
 
-from config.pr_converge_constants import PR_CONTEXT_FIELDS
+from config.pr_converge_constants import (
+    GH_REPO_ARG_TEMPLATE,
+    GH_REPO_FLAG,
+    PR_CONTEXT_FIELDS,
+    PR_DETACHED_HEAD_ARGS_ERROR,
+    PR_NUMBER_ARG_FLAG,
+    PR_NUMBER_ARG_HELP,
+    PR_OWNER_ARG_FLAG,
+    PR_OWNER_ARG_HELP,
+    PR_REPO_ARG_FLAG,
+    PR_REPO_ARG_HELP,
+)
 
 
-def view_pr_context() -> dict[str, object]:
+def view_pr_context(
+    number: str | None = None,
+    owner: str | None = None,
+    repo: str | None = None,
+) -> dict[str, object]:
     """Return the parsed JSON object from `gh pr view --json <fields>`."""
     gh_command: list[str] = ["gh", "pr", "view", "--json", PR_CONTEXT_FIELDS]
+    if owner and repo and number:
+        gh_command.append(number)
+        gh_command.append(GH_REPO_FLAG)
+        gh_command.append(GH_REPO_ARG_TEMPLATE.format(owner=owner, repo=repo))
+    elif number:
+        gh_command.append(number)
     completed = subprocess.run(
         gh_command,
         capture_output=True,
@@ -36,8 +57,18 @@ def view_pr_context() -> dict[str, object]:
 
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.parse_args()
-    pr_context = view_pr_context()
+    parser.add_argument(PR_NUMBER_ARG_FLAG, default=None, help=PR_NUMBER_ARG_HELP)
+    parser.add_argument(PR_OWNER_ARG_FLAG, default=None, help=PR_OWNER_ARG_HELP)
+    parser.add_argument(PR_REPO_ARG_FLAG, default=None, help=PR_REPO_ARG_HELP)
+    parsed = parser.parse_args()
+    number = (parsed.number.strip() or None) if parsed.number else None
+    owner = (parsed.owner.strip() or None) if parsed.owner else None
+    repo = (parsed.repo.strip() or None) if parsed.repo else None
+    needs_repo = owner is not None or repo is not None
+    has_all = number is not None and owner is not None and repo is not None
+    if needs_repo and not has_all:
+        parser.error(PR_DETACHED_HEAD_ARGS_ERROR)
+    pr_context = view_pr_context(number=number, owner=owner, repo=repo)
     json.dump(pr_context, sys.stdout)
     sys.stdout.write("\n")
     return 0