claude-dev-env 1.72.0 → 1.74.0

package/rules/CLAUDE.md

@@ -28,6 +28,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `no-historical-clutter.md` | Documentation describes current state only; no historical or transitional language |
 | `no-inline-destructive-literals.md` | No destructive-command literals in Bash tool command strings, even as data |
 | `orphan-css-class.md` | Every `class="..."` attribute in Python-generated markup has a matching selector in the `<style>` block |
+| `package-inventory-stale-entry.md` | A new production code file added to a directory carries an entry in that directory's `README.md`/`CLAUDE.md` file inventory |
 | `parallel-tools.md` | Make all independent tool calls in a single response |
 | `plain-language.md` | Everyday words, short active sentences, lead with the answer |
 | `prompt-workflow-context-controls.md` | Keep prompt-workflow instruction layers small and stable; load heavy skills on demand |

package/rules/docstring-prose-matches-implementation.md

@@ -6,7 +6,7 @@
 
 When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
 
-The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Three more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. `check_docstring_no_consumer_claim` covers a producer docstring asserting that no consumer reads its output yet (`producer-only artifact`, `no submission-run consumer reads it yet`) — a transitional claim that drifts the moment a reader lands and contradicts any companion `SKILL.md` that documents the consumer; this is the deterministic slice of the O8 companion-doc producer/consumer drift below. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and module-level responsibility paragraphs — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the four gated slices.
+The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Four more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. `check_docstring_no_consumer_claim` covers a producer docstring asserting that no consumer reads its output yet (`producer-only artifact`, `no submission-run consumer reads it yet`) — a transitional claim that drifts the moment a reader lands and contradicts any companion `SKILL.md` that documents the consumer; this is the deterministic slice of the O8 companion-doc producer/consumer drift below. `check_docstring_returns_plural_cardinality` covers a `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) while the returned dict literal holds exactly one key in that family (`sheen_mid`) — the drift where a single-key family carries a plural noun, so the prose claims a cardinality of two or more that the dict does not hold. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and module-level responsibility paragraphs — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the five gated slices.
 
 ## What to check before you write the docstring
 
@@ -15,8 +15,10 @@ Read the body and the docstring side by side:
 - **Read-source / match-source unions.** A body that computes `read_names = a | b | c` (or any union of "what counts") names each union member in the prose enumeration. A union member the code applies but the prose omits is a gap.
 - **Suppressor / skip lists.** A body with several early returns that suppress the check names each suppressor in the prose.
 - **Shared fallback routes.** A summary that scopes a fallback call to one condition names every condition that reaches that call. When the body routes to the same fallback from two or more early-return guards (`if a is None: fallback(); return` and `if random() < p: fallback(); return`), the prose enumerates both guards. The `check_docstring_fallback_branch_coverage` gate blocks the single-condition form of this drift at Write/Edit time.
-- **Step order.** A docstring that says `A then B then C` matches the call order in the body.
+- **Step order.** A docstring that says `A then B then C` matches the call order in the body. A step enumeration that names the body's linear steps also names every corrective step the body guards inside an `if`/`elif` branch (`if not await cancel_and_reinitiate_update(...): return`). The `check_docstring_step_enumeration_dispatch_coverage` gate blocks the branch-guarded-dispatch form of this drift — a step-enumeration docstring that omits a two-or-more-token dispatch step the body guards inside a branch — at Write/Edit time.
+- **Returns-clause cardinality.** A `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) matches the count of keys in that family in the returned dict literal. When the dict holds one key in the family (`sheen_mid`), the noun is singular (`the sheen stop`); a plural noun there claims two or more entries the dict does not hold. The `check_docstring_returns_plural_cardinality` gate blocks the single-key-with-plural-noun form of this drift at Write/Edit time.
 - **Predicate breadth.** A boolean helper whose prose promises a narrow check accepts only the inputs the prose names — no broader input class the name and prose do not mention.
+- **Exclusion-clause distinguisher.** A docstring sentence that says a named category of input "are not" / "is not" the thing the function flags (`plain logging, screenshot, or method-on-local calls inside a branch are not dispatch steps`) keys the exclusion to the same axis the body's classification keys on. When the body decides on one axis (a call sits in an `If.test` guard versus a plain statement) but the prose excludes on a different axis (the call's receiver shape — a method on a local), the exclusion clause names a category the body still flags: a guarded method-on-local call is flagged even though the prose lists method-on-local calls as excluded. Read the body's actual branch condition, then state the exclusion on that same axis (`plain (unguarded) calls inside a branch body are not dispatch steps`), so every member the prose excludes is a member the body also excludes.
 - **Companion-doc ordering and content claims.** A `SKILL.md` (or sibling `.md`) sentence that names a produced artifact and claims its order (`sorted`, `alphabetical`, `in sorted order`) or its content (`the at-risk names`, `just the current set`) matches the producer function's docstring and body for that same artifact. A producer that builds the artifact by merging stored names with new names and appending — preserving file order, not re-sorting the union — leaves a doc that still says `sorted` drifted on both counts: the order claim is wrong, and the content claim hides the merged-in prior entries. When the producer's ordering or union changes, the same change updates the companion doc. The two move together in one commit, even when the producer edit does not touch the `.md` file.
 
 When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.

package/rules/package-inventory-stale-entry.md

@@ -0,0 +1,24 @@
+# New Production File Absent From Its Package Inventory
+
+**When this applies:** Any Write that creates a new production code file (`.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`) in a directory whose sibling `README.md` or `CLAUDE.md` already names two or more of the directory's files in backticks.
+
+## Rule
+
+A package directory that documents its own files in a `README.md` Layout table or a `CLAUDE.md` "Key files" list keeps that inventory in step with the directory. A new production file the inventory does not name leaves the inventory and the directory disagreeing on the package's file set: a reader who trusts the inventory to map the directory misses the new file.
+
+When you create a new production file in such a directory, add an entry naming it — a row in the `README.md` table, a bullet in the `CLAUDE.md` list — in the same change. The entry names the file in backticks and says what it does.
+
+## What the gate checks
+
+The `package_inventory_stale_blocker.py` hook runs on every Write whose target is a new file (a path not yet on disk). It:
+
+1. Skips a target that is not a production code file (`.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`), an exempt basename (`__init__.py`, `conftest.py`, `setup.py`, `_path_setup.py`), a test file (`test_*.py`, `*_test.py`, `*.spec.*`, `*.test.*`), or a file directly inside a `config/` or `tests/` directory.
+2. Reads each `README.md` and `CLAUDE.md` present in the target's own directory and collects every bare filename they name in backticks. A backticked token holding a path contributes its final segment, so `pipeline/seam_continuity.py` in an inventory counts as naming `seam_continuity.py`. A multi-word command-example span — one carrying whitespace or shell punctuation (`:`, `$`, `<`, `>`), such as `parent:node_modules package.json` or `python <file>.py` — names no literal file and is dropped.
+3. Filters the named basenames to those that exist as a file in the target's own directory — the inventory's own sibling files — and treats the directory as carrying a maintained inventory only when two or more such sibling files are named. A directory with no inventory, one whose `README.md` mentions a single file in passing, or one whose inventory prose names only files living in other directories (so no named basename is an on-disk sibling) is out of scope.
+4. Blocks the write when the new file's basename appears in no present inventory. An unreadable or oversized inventory document is skipped, so a missing inventory never blocks a write.
+
+The check fires on Write only — editing an existing file adds no new inventory entry — and stays quiet for a directory with no inventory document, an inventory naming too few siblings to be a maintained list, an exempt or test file, and a file the inventory already names.
+
+## Why this is a hook, not a lint pass
+
+A package inventory that omits a file reads as a complete map of the directory while leaving one file off it. A reader trusting the inventory to list the package misses the new file, and the gap survives review because the inventory still looks complete. Catching it as the new file is written keeps the inventory and the directory in step. This is the counterpart to `claude-md-orphan-file.md`, which catches the reverse drift: an inventory entry naming a file the directory does not hold.

package/skills/autoconverge/SKILL.md

@@ -23,6 +23,22 @@ the workflow journal.
 autoconverge runs it as a deterministic workflow. The two skills share the same
 helper scripts and the same convergence gate.
 
+## Run scope: one PR or several
+
+Decide the scope from how many PRs the user named, then follow that path:
+
+1. **One PR** → the single-PR run described below (`workflow/converge.mjs`): one
+   worktree, one workflow launch, one teardown.
+2. **Several PRs** → the [Multiple PRs](#multiple-prs) run
+   (`workflow/converge_multi.mjs`): one worktree per PR and a single workflow
+   launch that drives every PR's converge run in parallel, then one teardown per
+   PR.
+
+The single-PR sections (Requirements, Pre-flight, Run the workflow, Teardown)
+each describe one converge run. The Multiple PRs section reuses them once per PR
+and adds only what fanning out needs: a per-PR worktree and a per-PR teardown
+loop.
+
 ## Requirements
 
 Scan the tool list at the top of this conversation for the literal string
@@ -245,7 +261,24 @@ agents never inline a destructive-command literal (`rm -rf`, `git reset --hard`,
 `dd`) into a Bash command — the `destructive_command_blocker` hook matches those
 patterns as raw text, and a confirmation prompt no human can answer would stall
 the run. Agents verify destructive-blocker behavior through the committed test
-suite (`python -m pytest`) and keep scratch work in ephemeral temp dirs.
+suite (`python -m pytest`) and keep scratch work in the OS temp dir. The preamble
+describes the narrowest rm auto-allow path — a standalone Bash call whose target
+resolves inside the ephemeral namespace (`/tmp`, `/temp`, the OS temp root, or the
+run worktree) — and a compound path that accepts an rm joined with benign
+reporting segments when every rm target is an absolute ephemeral path. Both of
+those paths fail closed on `$(...)` substitution, backtick subshells, and any `$`
+in the target — including `$CLAUDE_JOB_DIR` — so neither resolves an environment
+variable. A third, broad path matches only when the command itself declares an
+ephemeral working directory (it `cd`s into one, or runs under one): that
+cwd-scoped path resolves the target against the declared cwd, fails closed on
+`$(...)`, backticks, and unknown variables, and resolves the known temporary
+variables `TEMP`, `TMP`, `TMPDIR`, and `CLAUDE_JOB_DIR` to the OS temp root, so
+under that declared ephemeral cwd a bare `$CLAUDE_JOB_DIR/tmp/<name>` target and a
+relative target after a `cd` are auto-allowed. Even so, for any cleanup whose path
+is variable-built or whose teardown spans multiple steps, agents author a Python
+helper file and run it as `python <file>.py` — keeping every destructive literal
+out of a Bash command string entirely and independent of which auto-allow path
+matches.
 
 - **Converge:** `parallel([Bugbot lens, code-review lens, bug-audit lens])` on
   the current HEAD, full `origin/main...HEAD` diff. Dedup findings; one
@@ -270,10 +303,87 @@ suite (`python -m pytest`) and keep scratch work in ephemeral temp dirs.
 - **Convergence check:** `check_convergence.py` is the authoritative gate; on a
   full pass the workflow marks `draft=false`.
 
+## Multiple PRs
+
+The multi-PR run drives several draft PRs to ready in one launch:
+`workflow/converge_multi.mjs` fans out one `converge.mjs` child run per PR with
+`parallel()`, and every child is pinned to its own PR's worktree through the
+`repoPath` it receives, so the children never share a checkout. Each child run is
+the exact single-PR convergence loop — same rounds, same reuse pass, same Copilot
+gate, same convergence check — one per PR at once. The children share the run's
+concurrency cap, so the fan-out self-throttles rather than spawning every PR's
+lenses at the same instant.
+
+### Multi-PR pre-flight (main session)
+
+`EnterWorktree` puts the session on one branch only, so the multi-PR path gives
+each PR its own checkout with `git worktree add`. For each PR the user named:
+
+1. **Resolve PR scope** as the single-PR pre-flight step 2 does: capture `owner`,
+   `repo`, `prNumber`, and `headRefName`; confirm the PR is a draft, and mark it
+   draft (`gh pr ready <n> --repo <o>/<r> --undo`) when it is already ready so the
+   loop owns the ready transition.
+2. **Create a worktree on the PR's head ref** and capture its absolute path. From
+   inside the PR's repository checkout:
+   `git worktree add <abs worktree path> <headRefName>` (run `git fetch origin
+   <headRefName>` first when the ref is not local). Put each PR's worktree under a
+   path carrying its PR number so the fan-out keeps them distinct. Confirm
+   `git -C <abs worktree path> rev-parse --abbrev-ref HEAD` equals the head ref
+   and its `HEAD` equals the PR head SHA.
+3. **Verify each worktree is the PR's repo (strict pre-flight):**
+   `python "$HOME/.claude/skills/_shared/pr-loop/scripts/preflight_worktree.py" --owner <owner> --repo <repo> --mode strict`,
+   run with that worktree as the working directory. A non-zero exit prints a
+   `PREFLIGHT_OUTCOME` line and an `ABORT` line: report it and drop that PR from
+   the run rather than aborting every PR.
+4. **Grant project permissions once per repository** — the single-PR pre-flight
+   step 4 grant covers every worktree of the same repo, so run it one time for
+   the repo the PRs live in.
+
+### Launch the multi-PR workflow
+
+Call the `Workflow` tool against the fan-out script, passing the absolute path of
+`converge.mjs` and one entry per PR:
+
+```
+Workflow({
+  scriptPath: "<this skill dir>/workflow/converge_multi.mjs",
+  args: {
+    convergeScriptPath: "<this skill dir>/workflow/converge.mjs",
+    prs: [
+      { owner: "<O>", repo: "<R>", prNumber: <N1>, repoPath: "<abs worktree 1>", bugbotDisabled: false },
+      { owner: "<O>", repo: "<R>", prNumber: <N2>, repoPath: "<abs worktree 2>", bugbotDisabled: false }
+    ]
+  }
+})
+```
+
+`convergeScriptPath` is the absolute path to `workflow/converge.mjs` in this same
+skill directory; each `repoPath` is the absolute path of the worktree that PR is
+checked out in. The workflow runs in the background and notifies this session on
+completion; watch live progress with `/workflows`, where each PR's child run
+appears under its own group.
+
+The workflow returns `{ converged, prCount, convergedCount, results, blocker }`,
+where `results` is one record per PR carrying
+`{ owner, repo, prNumber, converged, rounds, finalSha, blocker }`. The top-level
+`converged` is true only when every PR converged.
+
+### Multi-PR teardown (on workflow completion)
+
+Run the single-PR [Teardown](#teardown-on-workflow-completion) once per entry in
+`results`, using that PR's `owner`, `repo`, `prNumber`, and `finalSha`, and its
+own worktree as the working directory. Build and publish a PR's closing report
+only for a PR whose `converged` is true; for a PR that returned a blocker, skip
+its report and carry the blocker into the final summary. Revoke project
+permissions once per repository after every PR's teardown. Then print one summary
+report — a line per PR as
+`#<prNumber>: <converged | blocked> — rounds <N>, final <finalSha>[, blocker <blocker>]`.
+
 ## Folder map
 
 - `SKILL.md` — this hub.
 - `workflow/converge.mjs` — the convergence workflow script.
+- `workflow/converge_multi.mjs` — the multi-PR fan-out driver: one `converge.mjs` child run per PR in parallel, each pinned to its PR worktree via `repoPath`.
 - `workflow/aggregate_runs.py` — merges every autoconverge journal for a PR into one journal and returns its deduped findings, fix summaries, round count, and final SHA.
 - `workflow/convergence_summary.py` — builds the convergence-summary agent prompt over a PR's merged findings.
 - `workflow/render_report.py` — builds the closing convergence insights HTML report, taking the summary from `--summary-file`.

package/skills/autoconverge/workflow/converge.contract.test.mjs

@@ -10,6 +10,10 @@ const gotchasSource = readFileSync(
   join(workflowDirectory, '..', 'reference', 'gotchas.md'),
   'utf8',
 );
+const skillSource = readFileSync(
+  join(workflowDirectory, '..', 'SKILL.md'),
+  'utf8',
+);
 
 function lensPromptBody(builderName) {
   const builderStart = convergeSource.indexOf(`function ${builderName}(`);
@@ -547,3 +551,105 @@ for (const builderName of editStepBuilders) {
     );
   });
 }
+
+function preambleText() {
+  const preambleStart = convergeSource.indexOf('const HEADLESS_SAFETY_PREAMBLE =');
+  assert.notEqual(preambleStart, -1, 'expected HEADLESS_SAFETY_PREAMBLE to exist');
+  const preambleEnd = convergeSource.indexOf('\n\nlet ', preambleStart);
+  return convergeSource.slice(preambleStart, preambleEnd === -1 ? undefined : preambleEnd);
+}
+
+test('preamble prescribes authoring a Python helper for variable-built or multi-step sandboxes', () => {
+  assert.match(
+    preambleText(),
+    /python\s+<file>\.py|python\s+<.*>\.py|author.*python.*helper|python.*helper.*sandbox|sandbox.*python.*helper/i,
+    'expected the preamble to prescribe running a Python helper file for multi-step sandbox teardown',
+  );
+});
+
+test('preamble does not claim any $ in the rm target makes the gate fail closed', () => {
+  assert.doesNotMatch(
+    preambleText(),
+    /any\s+\$[^\n]*fail closed/i,
+    'the hook resolves known temp variables (TEMP/TMP/TMPDIR/CLAUDE_JOB_DIR), so a bare $ does not always fail closed',
+  );
+});
+
+test('preamble does not claim $CLAUDE_JOB_DIR/tmp is blocked', () => {
+  assert.doesNotMatch(
+    preambleText(),
+    /CLAUDE_JOB_DIR\/tmp is NOT auto-allowed/i,
+    'under an ephemeral cwd the hook auto-allows rm targeting $CLAUDE_JOB_DIR/tmp',
+  );
+});
+
+test('preamble scopes its rm-shape claim to the narrowest auto-allow path, not the full set', () => {
+  assert.doesNotMatch(
+    preambleText(),
+    /auto-allows rm only when ALL of these hold/i,
+    'the hook has three rm auto-allow paths, so the preamble must not assert one narrow shape is the complete set',
+  );
+});
+
+test('SKILL.md does not claim any $ in the rm target makes the gate fail closed', () => {
+  assert.doesNotMatch(
+    skillSource,
+    /any\s+`?\$`?[^\n]*fail closed/i,
+    'the hook resolves known temp variables (TEMP/TMP/TMPDIR/CLAUDE_JOB_DIR), so a bare $ does not always fail closed',
+  );
+});
+
+test('SKILL.md does not claim it enforces the exact rm shape the hook auto-allows', () => {
+  assert.doesNotMatch(
+    skillSource,
+    /exact rm shape the hook auto-allows/i,
+    'the hook has multiple rm auto-allow paths, so SKILL.md must not assert one narrow shape is the exact set',
+  );
+});
+
+test('preamble does not attribute the known-temp-var resolution to the standalone or compound paths', () => {
+  assert.doesNotMatch(
+    preambleText().replace(/\s+/g, ' '),
+    /Across these paths[\s\S]*?CLAUDE_JOB_DIR/i,
+    'the temp-var resolution lives only in the broad cwd-scoped path; the standalone and compound paths fail closed on any $',
+  );
+});
+
+test('preamble attributes the known-temp-var resolution to a third cwd-scoped auto-allow path', () => {
+  const text = preambleText().replace(/\s+/g, ' ');
+  const tempVarSentenceMatch =
+    /[^.]*\bTMPDIR\b[^.]*CLAUDE_JOB_DIR[^.]*\./i.exec(text);
+  assert.notEqual(
+    tempVarSentenceMatch,
+    null,
+    'expected a sentence describing the TEMP/TMP/TMPDIR/CLAUDE_JOB_DIR resolution',
+  );
+  assert.match(
+    tempVarSentenceMatch[0],
+    /declares? an ephemeral cwd|declared ephemeral cwd|ephemeral-cwd path|third (?:auto-allow )?path|cwd-scoped path/i,
+    'expected the temp-var resolution to be tied to the cwd-scoped path that declares an ephemeral working directory, not the standalone or compound paths',
+  );
+});
+
+test('SKILL.md does not attribute the known-temp-var resolution to the standalone or compound paths', () => {
+  assert.doesNotMatch(
+    skillSource.replace(/\s+/g, ' '),
+    /Across those paths[\s\S]*?CLAUDE_JOB_DIR/i,
+    'the temp-var resolution lives only in the broad cwd-scoped path; the standalone and compound paths fail closed on any $',
+  );
+});
+
+test('SKILL.md attributes the known-temp-var resolution to the cwd-scoped auto-allow path', () => {
+  const tempVarSentenceMatch =
+    /[^.]*\bTMPDIR\b[^.]*CLAUDE_JOB_DIR[^.]*\./i.exec(skillSource.replace(/\s+/g, ' '));
+  assert.notEqual(
+    tempVarSentenceMatch,
+    null,
+    'expected a sentence describing the TEMP/TMP/TMPDIR/CLAUDE_JOB_DIR resolution',
+  );
+  assert.match(
+    tempVarSentenceMatch[0],
+    /declares? an ephemeral cwd|declared ephemeral cwd|ephemeral-cwd path|third (?:auto-allow )?path|cwd-scoped path/i,
+    'expected the temp-var resolution to be tied to the cwd-scoped path that declares an ephemeral working directory, not the standalone or compound paths',
+  );
+});

package/skills/autoconverge/workflow/converge.mjs

@@ -33,19 +33,44 @@ const HEADLESS_SAFETY_PREAMBLE =
   'HEADLESS RUN — you run unattended: no human can answer a permission or confirmation prompt, and any such prompt stalls the entire convergence run. The destructive_command_blocker hook matches dangerous patterns (rm -rf, git reset --hard, dd, mkfs, chmod -R, fork bombs) as raw text anywhere in a Bash command, with no quote-awareness — so a destructive string stalls you even when it is only data you never execute. Therefore:\n' +
   '- Never place a destructive-command literal inside a Bash command — not in echo, not in a heredoc, and not as an argument to python -c, node -e, or awk. To exercise or verify destructive_command_blocker (or any hook) behavior, run the committed test suite, e.g. python -m pytest <test_file>, which passes the command strings as in-language data rather than as a shell command.\n' +
   '- When a commit message, or a PR / issue / review-comment body, must describe destructive-command behavior, write that text to a file and pass it by path (git commit -F <file>, gh ... --body-file <file>); never inline it with git commit -m or gh ... -b, where the literal lands in the Bash command and stalls you.\n' +
-  '- Keep scratch files and cleanup inside the OS temp dir or $CLAUDE_JOB_DIR/tmp (auto-allowed as ephemeral); never target a repository or worktree path with rm -rf.\n' +
+  '- Keep scratch files and cleanup inside the OS temp dir; never target a repository or worktree path.\n' +
+  '- rm shape rules — the hook grants several rm auto-allow paths. The simplest one accepts a standalone Bash call whose target resolves inside the ephemeral namespace (/tmp, /temp, the OS temp root, or the run worktree); a compound path accepts an rm joined with benign reporting segments when every rm target is an absolute ephemeral path. Both of those paths fail closed on $(...) command substitution, on backtick subshells, and on any $ in the target — including $CLAUDE_JOB_DIR — so neither resolves an environment variable. A third, broad path matches only when the command itself declares an ephemeral working directory (it cds into one, or runs under one): that cwd-scoped path resolves the target against the declared cwd, fails closed on $(...) , backticks, and unknown variables, and resolves the known temporary variables TEMP, TMP, TMPDIR, and CLAUDE_JOB_DIR to the OS temp root, so under that declared ephemeral cwd a bare $CLAUDE_JOB_DIR/tmp/<name> target and a relative target after a cd are auto-allowed. Even so, prefer a Python helper for any cleanup whose path is variable-built or whose setup/teardown spans multiple steps: author the helper file and run it as python <file>.py, which keeps every destructive literal out of a Bash command string entirely and never depends on which auto-allow path matches.\n' +
   '- If a step appears to require a real destructive command, use a non-destructive equivalent or report it as a blocker instead of running it.\n\n'
 
+let activeRepoPath = null
+
+/**
+ * Build the per-agent worktree directive for a path-scoped run.
+ *
+ * A multi-PR parent run drives several converge children from one shared
+ * working directory, so each child pins its own agents to the worktree its PR
+ * is checked out in; without that pin every child's git, gh, diff, edit,
+ * commit, and test commands would run in the shared launch directory rather
+ * than the PR's own checkout. The parent hands the worktree path in as
+ * input.repoPath, which sets activeRepoPath. A single-PR run carries no
+ * repoPath, so this returns an empty string and every agent keeps its own
+ * working directory — behavior identical to a run with no path scoping.
+ * @param {string|null} repoPath the PR worktree absolute path, or null for the single-PR default
+ * @returns {string} the worktree directive to prepend, or an empty string when repoPath is null
+ */
+const worktreeDirective = (repoPath) =>
+  repoPath
+    ? `WORKTREE — this PR is checked out at ${repoPath}. Unless a step explicitly names a different repository directory (for example an environment-hardening repo checkout, which you cd into exactly as that step directs), run every git, gh, diff, edit, commit, push, and test command for this PR in that worktree: cd "${repoPath}" before any such command, and resolve repository roots from there.\n\n`
+    : ''
+
 /**
  * Spawn a workflow agent with the headless-safety preamble prepended to its
  * prompt. Every agent in this convergence loop runs unattended, so each one is
- * routed through here to inherit the same no-confirmation-prompt guidance.
+ * routed through here to inherit the same no-confirmation-prompt guidance. On a
+ * path-scoped run the worktree directive is prepended too, so every agent runs
+ * in the PR's own worktree (activeRepoPath); on a single-PR run that directive
+ * is empty and the agent keeps its own working directory.
  * @param {string} prompt the agent's role-specific instruction body
  * @param {object} options the agent() options (label, phase, schema, agentType, model)
  * @returns {Promise<*>} the agent() result
  */
 const convergeAgent = (prompt, options) =>
-  agent(`${HEADLESS_SAFETY_PREAMBLE}${prompt}`, options)
+  agent(`${HEADLESS_SAFETY_PREAMBLE}${worktreeDirective(activeRepoPath)}${prompt}`, options)
 
 const PRE_COMMIT_GATE_STEP =
   `\n\nFINAL STEP — pre-commit gate check (do NOT commit): before your turn ends, prove your working-tree changes CAN be committed by dry-running the CODE_RULES commit gate that gates git commit (precommit_code_rules_gate). From inside the checkout that holds your changes, resolve its root with git rev-parse --show-toplevel, stage your changes with git add -A, then run exactly:\n` +
@@ -696,6 +721,7 @@ if (runInput.blocker) {
   return { converged: false, rounds: 0, finalSha: null, blocker: runInput.blocker }
 }
 const input = runInput.input
+activeRepoPath = typeof input.repoPath === 'string' && input.repoPath ? input.repoPath : null
 const prCoordinates = `owner=${input.owner} repo=${input.repo} PR #${input.prNumber} (https://github.com/${input.owner}/${input.repo}/pull/${input.prNumber})`
 
 /**

package/skills/autoconverge/workflow/converge.path-aware.test.mjs

@@ -0,0 +1,47 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const workflowDirectory = dirname(fileURLToPath(import.meta.url));
+const convergeSource = readFileSync(join(workflowDirectory, 'converge.mjs'), 'utf8');
+
+function sliceBetween(startNeedle, endNeedle) {
+  const sliceStart = convergeSource.indexOf(startNeedle);
+  assert.notEqual(sliceStart, -1, `expected ${startNeedle} to exist`);
+  const sliceEnd = convergeSource.indexOf(endNeedle, sliceStart + startNeedle.length);
+  assert.notEqual(sliceEnd, -1, `expected ${endNeedle} to exist after ${startNeedle}`);
+  return convergeSource.slice(sliceStart, sliceEnd);
+}
+
+const productionModule = new Function(
+  `${sliceBetween('const worktreeDirective =', '\nconst convergeAgent =')}\n` +
+    'return { worktreeDirective };',
+)();
+const { worktreeDirective } = productionModule;
+
+test('a single-PR run (no repoPath) produces an empty worktree directive', () => {
+  assert.equal(worktreeDirective(null), '');
+});
+
+test('a path-scoped run pins every agent to the PR worktree by absolute path', () => {
+  const directive = worktreeDirective('/worktrees/pr-398');
+  assert.match(directive, /\/worktrees\/pr-398/);
+  assert.match(directive, /cd /);
+  assert.match(directive, /git, gh, diff, edit, commit, push, and test/);
+});
+
+test('a path-scoped run defers to a step that names a different repository directory', () => {
+  assert.match(worktreeDirective('/worktrees/pr-398'), /different repository directory/i);
+});
+
+test('convergeAgent prepends the worktree directive for the active repo path', () => {
+  const agentDefinition = sliceBetween('const convergeAgent =', '\nconst PRE_COMMIT_GATE_STEP');
+  assert.match(agentDefinition, /worktreeDirective\(activeRepoPath\)/);
+  assert.match(agentDefinition, /HEADLESS_SAFETY_PREAMBLE/);
+});
+
+test('the run binds activeRepoPath from input.repoPath after the input is parsed', () => {
+  assert.match(convergeSource, /activeRepoPath = typeof input\.repoPath === 'string'/);
+});

package/skills/autoconverge/workflow/converge_multi.mjs

@@ -0,0 +1,161 @@
+/**
+ * Autoconverge multi-PR fan-out workflow driver.
+ *
+ * SINGLE-FILE CONTRACT — keep this file self-contained. The Workflow runtime
+ * wraps this body in a function (so top-level await and return work) and rejects
+ * static import statements, and `export const meta` must be the first statement.
+ * This driver fans out one converge.mjs child run per PR with parallel(); the
+ * converge.mjs child uses only agent()/parallel() (never workflow()), so the
+ * one-level workflow() nesting limit holds.
+ */
+
+export const meta = {
+  name: 'autoconverge-multi',
+  description: 'Drive several draft PRs to convergence in one run: fan out one autoconverge converge.mjs child per PR in parallel, each pinned to its own checked-out worktree via repoPath, then report every PR\'s outcome together.',
+  whenToUse: 'Launched by the /autoconverge skill when the user names more than one PR to converge at once; the single-PR path launches workflow/converge.mjs directly.',
+  phases: [
+    { title: 'Converge all', detail: 'One converge.mjs child run per PR, all in parallel; each child is pinned to its own PR worktree through repoPath' },
+  ],
+}
+
+/**
+ * Normalize the workflow args global into a parsed object.
+ *
+ * The Workflow runtime may deliver args as a JSON-encoded string or as an
+ * object; a string is parsed and an object passes through unchanged. A non-JSON
+ * or empty string yields null so a malformed payload becomes a structured
+ * blocker rather than aborting the run.
+ * @param {string|object} rawArgs the workflow args global (JSON string or object)
+ * @returns {object|null} the parsed args, or null when a string payload fails to parse
+ */
+function normalizeMultiInput(rawArgs) {
+  if (typeof rawArgs !== 'string') return rawArgs
+  try {
+    return JSON.parse(rawArgs)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Decide whether one PR entry carries every coordinate a child run needs.
+ *
+ * A child converge run needs the PR's owner, repo, and number to address its
+ * GitHub calls, and the absolute worktree path the PR is checked out in to pin
+ * its agents there.
+ * @param {object} prEntry one element of the args.prs array
+ * @returns {boolean} true when owner, repo, prNumber, and a non-empty string repoPath are all present
+ */
+function isUsablePrEntry(prEntry) {
+  return (
+    prEntry != null &&
+    Boolean(prEntry.owner) &&
+    Boolean(prEntry.repo) &&
+    Boolean(prEntry.prNumber) &&
+    typeof prEntry.repoPath === 'string' &&
+    Boolean(prEntry.repoPath)
+  )
+}
+
+/**
+ * Validate the normalized multi-PR input into usable coordinates or a blocker.
+ *
+ * A fan-out run needs the absolute converge.mjs script path and a non-empty list
+ * of PR entries that each carry owner, repo, prNumber, and the absolute worktree
+ * path the PR is checked out in. A payload that fails to parse, a non-string
+ * convergeScriptPath, a missing or empty prs list, or any entry missing a
+ * coordinate yields a blocker the top-level run reports as
+ * {converged:false, blocker} rather than throwing on a missing field.
+ * @param {string|object} rawArgs the workflow args global (JSON string or object)
+ * @returns {{input: object|null, blocker: string|null}} usable coordinates or a blocker
+ */
+function classifyMultiInput(rawArgs) {
+  const candidate = normalizeMultiInput(rawArgs)
+  if (candidate == null) {
+    return {
+      input: null,
+      blocker: 'invalid run coordinates: the workflow args did not parse into an object',
+    }
+  }
+  if (typeof candidate.convergeScriptPath !== 'string' || !candidate.convergeScriptPath) {
+    return {
+      input: null,
+      blocker:
+        'invalid run coordinates: convergeScriptPath (absolute path to converge.mjs) is required',
+    }
+  }
+  if (!Array.isArray(candidate.prs) || candidate.prs.length === 0) {
+    return {
+      input: null,
+      blocker: 'invalid run coordinates: prs must be a non-empty array of PR entries',
+    }
+  }
+  const unusableEntryCount = candidate.prs.filter(
+    (eachEntry) => !isUsablePrEntry(eachEntry),
+  ).length
+  if (unusableEntryCount > 0) {
+    return {
+      input: null,
+      blocker: `invalid run coordinates: ${unusableEntryCount} PR entry/entries missing owner, repo, prNumber, or repoPath`,
+    }
+  }
+  return { input: candidate, blocker: null }
+}
+
+const multiInput = classifyMultiInput(args)
+if (multiInput.blocker) {
+  return { converged: false, prCount: 0, convergedCount: 0, results: [], blocker: multiInput.blocker }
+}
+const input = multiInput.input
+
+phase('Converge all')
+log(`autoconverge multi-PR: driving ${input.prs.length} PR(s) to ready in parallel`)
+
+const childResults = await parallel(
+  input.prs.map((eachPr) => async () => {
+    const childOutcome = await workflow(
+      { scriptPath: input.convergeScriptPath },
+      {
+        owner: eachPr.owner,
+        repo: eachPr.repo,
+        prNumber: eachPr.prNumber,
+        repoPath: eachPr.repoPath,
+        bugbotDisabled: Boolean(eachPr.bugbotDisabled),
+      },
+    )
+    return {
+      owner: eachPr.owner,
+      repo: eachPr.repo,
+      prNumber: eachPr.prNumber,
+      converged: Boolean(childOutcome && childOutcome.converged),
+      rounds: childOutcome && childOutcome.rounds !== undefined ? childOutcome.rounds : null,
+      finalSha: childOutcome && childOutcome.finalSha !== undefined ? childOutcome.finalSha : null,
+      blocker: childOutcome && childOutcome.blocker !== undefined ? childOutcome.blocker : null,
+    }
+  }),
+)
+
+const results = childResults.map((eachResult, eachIndex) =>
+  eachResult === null
+    ? {
+        owner: input.prs[eachIndex].owner,
+        repo: input.prs[eachIndex].repo,
+        prNumber: input.prs[eachIndex].prNumber,
+        converged: false,
+        rounds: null,
+        finalSha: null,
+        blocker: 'child run threw or was skipped before returning an outcome',
+      }
+    : eachResult,
+)
+
+const convergedCount = results.filter((eachResult) => eachResult.converged).length
+log(`autoconverge multi-PR done: ${convergedCount}/${results.length} PR(s) converged`)
+
+return {
+  converged: convergedCount === results.length,
+  prCount: results.length,
+  convergedCount,
+  results,
+  blocker: null,
+}