claude-dev-env 1.52.0 → 1.52.1

package/package.json

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

package/skills/pr-converge/SKILL.md

@@ -31,6 +31,18 @@ proceed to any state-modifying operation until the working directory
 contains `.claude/worktrees/`. If `EnterWorktree` fails, report the failure
 and stop; do not continue in place.
 
+`EnterWorktree` isolates the session's **own** repo. When the PR under
+convergence shares that repo, its worktree is where the CODE_REVIEW phase
+runs. When the PR lives in a different repo, `EnterWorktree` cannot
+re-root into it; Step 1.5 resolves a **PR worktree** — a checkout of the
+PR's repo on its head branch — and routes the working directory into it.
+Routing the working directory into the PR's repo is routine and
+automatic, never a fork to pause on. The Pre-flight `.claude/worktrees/`
+gate covers the session repo's own isolation; for a cross-repo PR the
+working directory routes into the PR's repo for local work and returns to
+the session worktree before teardown. See
+[`reference/per-tick.md` § Step 1.5](reference/per-tick.md).
+
 ## State persistence
 
 Single-PR mode persists loop state to `$CLAUDE_JOB_DIR/pr-converge-state.json`.
@@ -84,6 +96,14 @@ post a fresh PR in a fresh branch based on origin main to the user.
   `pwsh` calls run through the PowerShell tool, not Bash. Bash on
   Windows is Git Bash which cannot execute PowerShell cmdlets. Route all
   PowerShell work through the PowerShell tool or `pwsh -NoProfile -File`.
+- **Cross-repo PR: route cwd into the PR worktree before `/code-review`** —
+  `/code-review --fix` (Step 5) audits the repo of the current working
+  directory. When the session is rooted in a different repo than the PR,
+  `EnterWorktree` cannot re-root (it is scoped to the session's repo);
+  resolve the PR worktree and `cd` into it per
+  [Step 1.5](reference/per-tick.md). Skipping this reviews and edits the
+  wrong repo. The route is routine and automatic — never a material fork
+  to pause on.
 
 ## Progress checklist
 
@@ -117,9 +137,14 @@ round as converged. This rule holds every tick, every loop, every PR.
 - [ ] **Step 0: Grant project permissions**
       `python "$HOME/.claude/skills/bugteam/scripts/grant_project_claude_permissions.py"`
 
-- [ ] **Step 1: Resolve PR scope**
-      Capture owner, repo, number, head SHA, branch.
+- [ ] **Step 1: Resolve PR scope + PR worktree**
+      Capture owner, repo, number, head SHA, branch. Resolve the **PR
+      worktree** — the local checkout every local step this tick targets:
+      the `EnterWorktree` checkout when the PR shares the session's repo,
+      else a checkout of the PR's repo that the working directory routes
+      into via `cd`. Cross-repo routing is automatic, not a fork.
       See: [`reference/per-tick.md` § Step 1](reference/per-tick.md)
+      and [§ Step 1.5](reference/per-tick.md)
 
 - [ ] **Step 2: Initialize loop state**
       `phase = BUGBOT`; all counters at zero; `run_name` resolved.
@@ -168,6 +193,13 @@ round as converged. This rule holds every tick, every loop, every PR.
 
       Pre-condition: `bugbot_clean_at == current_head` (or `bugbot_down == true`).
 
+      Pre-condition: the working directory is the Step 1.5 PR worktree on
+      `current_head` (`git rev-parse --show-toplevel` is that checkout).
+      When the session is rooted in a different repo than the PR, `cd`
+      into the PR worktree first — `/code-review` audits the repo of the
+      current working directory, so this routing targets the real PR
+      diff. This `cd` is routine and automatic.
+
       Run Claude Code's built-in `/code-review --fix` on the full
       `origin/main...HEAD` diff —
       the [local diff review](https://code.claude.com/docs/en/code-review#review-a-diff-locally)

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

@@ -25,6 +25,15 @@ files during fix phase in multi-PR mode.
 
 **Single-PR (no `state.json`) — same gates, main session executor:**
 
+Run every command below in the PR worktree (the working directory routed in
+[per-tick.md § Step 1.5](per-tick.md)). The `git add`, `git commit`, and
+`git push` act on the repo of the current working directory, so a cross-repo
+PR's fix lands in the PR's repo only when the cwd is its worktree. A spawned
+`clean-coder` does not inherit the lead's working directory — name the PR
+worktree path in its prompt and direct it to edit, stage, and commit there,
+matching the worktree-path handoff bugteam embeds in its fix worker's spawn
+prompt.
+
 - Read each referenced file:line.
 - Write failing test first when finding has behavior to test. Pure doc /
   comment / naming nits with no behavior → straight to fix.

package/skills/pr-converge/reference/ground-rules.md

@@ -15,3 +15,10 @@
 - **Adapt when reality contradicts on-disk state.** If `state.json`,
   `git`, or `gh` disagree with live PR, escalate as hard blocker per
   [stop-conditions.md](stop-conditions.md).
+- **Cross-repo cwd routing is routine, not a fork.** When the PR under
+  convergence lives in a different repo than the session is rooted in, route
+  the working directory into a checkout of the PR's repo automatically —
+  `/code-review --fix`, `git`, and every `clean-coder` fix spawn act on the
+  repo of the current working directory. The resolution is fixed
+  ([per-tick.md § Step 1.5](per-tick.md)): resolve the PR worktree, `cd` into
+  it, run local work there. Do not pause, ask, or raise it as a material fork.

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

@@ -45,6 +45,89 @@ If `current_head` changed since last tick, reset `bugbot_down` to `false`
 
 Capture `number`, `head.sha` (= `current_head`), owner/repo, branch.
 
+## Step 1.5: Resolve the PR worktree (cwd routing)
+
+The **PR worktree** is the local working tree of the PR's repo on its head
+branch. Every local operation this tick runs there: the CODE_REVIEW
+`/code-review --fix`, every `clean-coder` fix spawn, and every commit and
+push. `/code-review` and `git` both act on the repo of the current working
+directory, so the working directory must be the PR worktree before any local
+work begins. Re-resolve it every tick — a rebase or a fresh HEAD can move the
+branch tip.
+
+Read the current working tree's origin and parse its `<owner>/<repo>`,
+accepting the `https://github.com/<owner>/<repo>`,
+`git@github.com:<owner>/<repo>`, and `ssh://git@github.com/<owner>/<repo>`
+forms and dropping any trailing `.git`:
+
+```bash
+git remote get-url origin
+```
+
+- **Parsed owner/repo matches the PR** (case-insensitive): the `EnterWorktree`
+  pre-flight checkout is the PR worktree, and the working directory already
+  points here, so no `cd` is needed. Bring the branch to the PR head with the
+  same deterministic `checkout -B` the cross-repo case uses, after confirming
+  the tree carries no uncommitted edits — a non-empty `git status --porcelain`
+  means a prior tick left a fix mid-flight, so escalate as a hard blocker:
+  ```bash
+  git fetch origin
+  git checkout -B <branch> origin/<branch>
+  ```
+
+- **Parsed owner/repo differs** (the session is rooted in another repo — for
+  example, the PR lives in `llm-settings` while the session runs from
+  `claude-code-config`): route the working directory into a checkout of the
+  PR's repo. This is routine and automatic — never pause, and never raise it as
+  a fork (see [ground-rules.md](ground-rules.md)). `EnterWorktree` is scoped to
+  the session's own repo and cannot re-root into the PR's repo.
+
+  `<run_temp_dir>` is pr-converge's own `pr-converge-pr-<N>` directory under the
+  system temp directory — named apart from bugteam's `bugteam-pr-<N>` run dir so
+  the two never share a checkout when Step 6 runs bugteam on the same PR.
+  pr-converge fills this path by hand; it does not route through the shared
+  `_path_resolver` that bugteam uses. Reuse its `checkout` across ticks; create
+  it once when it is absent. A fresh clone honors the global `core.hooksPath`, so git-side
+  CODE_RULES enforcement covers the fix commit.
+
+  1. Clone the PR branch when the checkout is absent:
+     ```bash
+     gh repo clone <owner>/<repo> "<run_temp_dir>/checkout" -- --branch <branch>
+     ```
+  2. Bring it to the PR head. On a reused checkout, confirm it carries no
+     uncommitted edits first — a non-empty `git -C "<run_temp_dir>/checkout"
+     status --porcelain` means a prior tick left a fix mid-flight, so escalate
+     as a hard blocker rather than discard it. On a clean tree:
+     ```bash
+     git -C "<run_temp_dir>/checkout" fetch origin
+     git -C "<run_temp_dir>/checkout" checkout -B <branch> origin/<branch>
+     ```
+  3. Change into it in a standalone Bash call so the working directory persists
+     into the `/code-review` invocation that follows:
+     ```bash
+     cd "<run_temp_dir>/checkout"
+     ```
+  4. Confirm the route took before any local work:
+     ```bash
+     git rev-parse --show-toplevel
+     git rev-parse HEAD
+     ```
+     The top level reads `<run_temp_dir>/checkout` and HEAD equals
+     `current_head`.
+
+  Spawn every `clean-coder` fix worker with the PR worktree path in its prompt
+  so its edits land in the PR's repo — the same worktree-path handoff bugteam
+  gives its fix worker. The
+  GitHub API steps (BUGBOT fetch, convergence gates) and the bugteam Skill
+  invocation are URL-driven and need no local checkout.
+
+  Capture the session worktree path (the `EnterWorktree` checkout) before
+  routing away. Step 0 grant, Step 8 working-tree cleanup, and Step 10 revoke
+  read the current working directory and target the session repo, so `cd` back
+  to the session worktree before Step 8 and remove `<run_temp_dir>` there with
+  a Windows-safe recursive remove (per
+  `$HOME/.claude/rules/windows-filesystem-safe.md`).
+
 ## Step 2: Branch on `phase`
 
 ### `phase == BUGBOT`
@@ -126,12 +209,16 @@ a. Run Claude Code's built-in `/code-review --fix` on the FULL
    [local diff review](https://code.claude.com/docs/en/code-review#review-a-diff-locally).
    It reviews the diff and applies its findings to the working tree.
 
-   Before running, confirm the working tree sits on the PR's HEAD with no
-   uncommitted edits, then invoke `/code-review --fix` with no path
-   arguments so it audits the whole branch diff against `origin/main`. Do
-   not delta-scope to commits added since the prior clean SHA, do not
-   scope to a single file, do not scope to bugbot's flagged paths. A
-   partial-scope round does not count and cannot set
+   Before running, confirm the working directory is the PR worktree resolved
+   in [Step 1.5](#step-15-resolve-the-pr-worktree-cwd-routing) — `git rev-parse
+   --show-toplevel` is that checkout and `git rev-parse HEAD` equals
+   `current_head` — with no uncommitted edits. When the session is rooted in a
+   different repo than the PR, the `cd` from Step 1.5 supplies this; the
+   persisted working directory is what `/code-review` audits. Then invoke
+   `/code-review --fix` with no path arguments so it audits the whole branch
+   diff against `origin/main`. Do not delta-scope to commits added since the
+   prior clean SHA, do not scope to a single file, do not scope to bugbot's
+   flagged paths. A partial-scope round does not count and cannot set
    `code_review_clean_at`. Pass no effort argument, so the review uses
    the session's current effort.