claude-dev-env 4.3.0 → 7.0.0

package/.agents/skills/autoconverge/reference/convergence.md

@@ -1,219 +0,0 @@
-# Convergence — round shape and the ready definition
-
-## Pre-flight: clear merge conflicts
-
-Before the first round, the workflow checks once whether the PR branch conflicts
-with `origin/main`. When GitHub reports a conflict (`mergeable` false or
-`mergeable_state` dirty), one `clean-coder` rebases the branch onto `origin/main`
-and resolves every conflict — the edit remains in the working tree, review and
-verification follow the [precatch rubric](../../_shared/pr-loop/precatch-rubric.md),
-and the commit step force-pushes with lease. The bug checks then run on a
-conflict-free diff.
-
-A PR that merges cleanly skips the rebase. A conflict that surfaces mid-run, when
-`origin/main` advances during a later round, is caught by the convergence repair
-at the end of the loop, which also rebases.
-
-## Reuse pass (runs after the conflict pre-flight, before convergence)
-
-One reuse lens (`code-quality-agent`) reviews the full `origin/main...HEAD` diff
-for code that re-implements behavior the repository already provides. It reports a
-reuse improvement only when all three criteria hold together, and omits any case
-where even one is in doubt:
-
-1. **Certain** — an existing symbol or module unquestionably covers the new
-   code's behavior, cited at `file:line`.
-2. **Behaviorally the same** — swapping the new code for the existing one
-   changes no observable behavior: same inputs, outputs, side effects, and
-   error handling.
-3. **Autonomously implementable** — the replacement is a mechanical edit (import
-   and call the existing symbol, drop the duplicate) needing no product
-   decision and no human judgment.
-
-The lens reports without editing. Each qualifying improvement runs through the
-same edit → verify → commit fix flow the rounds use, landing in one verified
-commit before convergence begins. The pass is best-effort: when no case clears
-all three criteria the run proceeds straight to convergence. Whatever the reuse
-pass surfaces also joins the round findings, so the code-review lens re-checks
-any improvement that did not land. The run result's `reuseNote` records what
-landed.
-
-## The round loop
-
-The workflow holds five states and moves between them until the PR is ready or
-a blocker ends the run. A single iteration counter increments on every pass
-through any phase and caps the whole run at 20 loop iterations; the round counter
-tracks CONVERGE passes only and is never the cap. The internal lenses drive the
-code to clean first; the external reviewers run only after that, as terminal
-confirmation gates that are expected to return zero.
-
-**CONVERGE** (one round = a static sweep then one parallel lens sweep):
-
-1. Resolve the current PR HEAD SHA. The same preflight step also fetches
-   `origin/main` once for the round and enumerates the diff — the
-   `git diff --name-status origin/main...HEAD` changed-file list and the
-   `git diff --stat` diffstat — and carries both into the round.
-2. Run the **static-sweep lens** on that HEAD: a deterministic pass that runs the
-   CODE_RULES gate (`code_rules_gate.py --base origin/main`), `ruff`, `mypy`, and
-   stem-matched `pytest` over the changed files, mapping each failure to a
-   finding. It uses local commands only, so it runs in any session. When the sweep
-   raises a finding, one `clean-coder` fixes it through the same fix flow below and
-   the round re-runs, so the reading lenses only ever review sweep-clean code.
-3. Run three reading lenses in parallel on that HEAD, each over the full
-   `origin/main...HEAD` diff. Each lens receives the preflight's changed-file
-list and diffstat and reads only the files it needs from that list rather than
-re-deriving the diff; each lens applies the [precatch rubric](../../_shared/pr-loop/precatch-rubric.md#review-judgment).
-   - **Code-review lens** — a correctness-focused review pass (`code-quality-agent`),
-     report-only workflow agent — see runCodeReviewLens in workflow/converge.mjs for its configuration.
-     The built-in `/code-review` command is a separate surface outside this
-     workflow path. On `pacer=workflow`, this lens runs inside `converge.mjs`.
-     On `pacer=portable`, the continuous driver uses the CODE_REVIEW phase
-     through `invoke_code_review.py` instead of `runCodeReviewLens`
-     ([`../../_shared/pr-loop/portable-driver.md`](../../_shared/pr-loop/portable-driver.md)).
-   - **Bug-audit lens** — the bug-audit (`code-quality-agent`) applying the
-     shared A–P rubric from `_shared/pr-loop/audit-contract.md`, then its
-     adversarial second pass, and the doc-parity, test-assertion, and
-     PR-description lanes from `_shared/pr-loop/precatch-rubric.md`, reporting
-     findings without editing.
-   - **Self-review lens** — the semantic parity pass (`code-quality-agent`) that
-     reads `_shared/pr-loop/precatch-rubric.md` and covers doc-vs-code parity,
-     test-assertion completeness, and PR-description-vs-diff parity, reporting
-     findings without editing.
-4. Dedup findings across the three lenses by file, line, and title. A collision
-   keeps the most severe duplicate's severity (P0 > P1 > P2), unions the detail
-   text, and collects every distinct bot thread id so the fix lens resolves all
-   colliding threads.
-5. **Any findings** → one `clean-coder` applies every fix per the
-   shared [fix protocol](../../_shared/pr-loop/fix-protocol.md): a single
-   test-first commit, a push, then a reply and resolve on each finding that
-   carries a GitHub review thread. Before its turn ends, the edit step dry-runs
-   the CODE_RULES commit gate (`code_rules_gate.py --staged`) over its staged
-   changes and keeps fixing until that gate would accept the commit, so the
-   later commit step never hits a gate rejection. A round progresses when the
-   fix lens lands a push that moves HEAD, or when every finding was already
-   addressed so no code change is needed yet each finding thread is still
-   resolved (the fix lens reports `resolvedWithoutCommit` and the run
-   re-converges on the unchanged HEAD). A round whose fix lens reports neither
-   a moved-HEAD push nor a full thread-resolution ends the run with a
-   fix-stalled blocker. The next round re-verifies on the current HEAD.
-6. **Zero findings on a stable HEAD** → post the CLEAN bugteam audit artifact
-   for that HEAD, then move to the terminal Bugbot gate.
-
-A round whose findings are ALL code-standard violations (pure CODE_RULES/style,
-no behavioral impact) passes for convergence purposes: the workflow files a
-follow-up issue listing the findings, opens a draft environment-hardening PR
-(hooks/rules that block those violation classes at Write/Edit time), resolves
-any bot threads with a deferral note, and reports the deferral in
-`standardsNote`. The hardening PRs land in the run result's `deferredPrs` list.
-Standards-only deferral still takes precedence when every finding is category
-`code-standard`.
-
-When the already-deduped findings for a phase are all severity P2 (and not
-standards-only), the phase still applies the fixes once. If the fix does **not**
-move HEAD (for example `resolvedWithoutCommit`), the phase treats that HEAD as
-clean and advances forward. If the fix **does** move HEAD, the run re-enters
-CONVERGE on the fixed SHA so the current review state rebuilds before
-FINALIZE. The three CONVERGE reading lenses stay
-parallel; the P2-only decision is a routing branch on the deduped set after
-`resolveRoundOutcome` / gate classification. Mixed P0/P1 findings keep the
-existing fix + re-converge path.
-
-**BUGBOT** gate (terminal external confirmation):
-
-- Runs once the internal lenses are clean. When Bugbot is off for the run — the
-  default unless `CLAUDE_REVIEWS_ENABLED` lists `bugbot` — opted out via
-  `CLAUDE_REVIEWS_DISABLED`, or unreachable, the gate spawns no agent and moves
-  to the Copilot gate with `bugbotDown` set.
-- Otherwise drive Cursor Bugbot to a verdict on HEAD (trigger and poll its CI
-  check run when needed).
-- Bugbot findings that are not standards-only and not P2-only → fix them and
-  return to CONVERGE on the new HEAD.
-- Bugbot P2-only findings → fix once; advance to Copilot only when HEAD is
-  unchanged, otherwise re-converge on the fixed HEAD.
-- Bugbot clean or approved → move to the Copilot gate.
-- Bugbot down after the poll cap → move to the Copilot gate with `bugbotDown` set.
-
-**COPILOT** gate (terminal external confirmation):
-
-- Request a Copilot review on HEAD (skipping a duplicate request), then poll up
-  to the configured cap, 360 seconds apart.
-- Copilot findings that are not standards-only and not P2-only → fix them and
-  return to CONVERGE on the new HEAD.
-- Copilot P2-only findings → fix once; advance to Codex only when HEAD is
-  unchanged, otherwise re-converge on the fixed HEAD.
-- Copilot clean or approved → move to the Codex gate.
-- Copilot down or out of quota (an out-of-usage notice, or no review after the
-  configured cap) → log a notice and move to the Codex gate with the Copilot gate
-  bypassed.
-
-**CODEX** gate (conditional-required terminal confirmation):
-
-- Runs after Bugbot and Copilot. Honors `reviews_disabled.py --reviewer codex`,
-  the weekly usage probe via `is_codex_review_required` (shared threshold
-  constant — no inline percent), and the wrapper's `codex_down` class.
-- Missing opt-in (the default), opt-out token, or `codex_down` → set
-  `codexDown`, no stamp, move to the
-  convergence check with `--codex-down`. A `codex_down` classification also
-  records a `codexNote` so the skip stays visible in the final report.
-- Usage at/below threshold or null → skip with no stamp; the machine checklist
-  applies the same rule.
-- Above threshold → run the codex-review wrapper against the PR base branch.
-  Non–code-standard, non–P2-only findings → fix and return to CONVERGE.
-  P2-only findings → fix once; when HEAD is unchanged, stamp `codexCleanAt` and
-  move to the convergence check (no re-converge), otherwise re-converge on the
-  fixed HEAD.
-  Standards-only findings → defer a follow-up, stamp `codexCleanAt`, and move to the
-  convergence check (no fix push).
-  Clean → stamp `codexCleanAt` and pass `--codex-clean-at` into the convergence check.
-
-**Convergence check**:
-
-- One agent runs `check_convergence.py` and, on a full pass, marks the PR ready
-  (`draft=false`) in the same turn, ending the run. A failure returns to CONVERGE
-  so the next round addresses the failing gate; the repair path re-runs this same
-  check, and only a passing check marks the PR ready.
-
-## Model tiers
-
-Each spawned agent runs on the model and effort its role needs, so the run spends
-the strongest model only where judgment is dense:
-
-- **sonnet** — the deterministic static-sweep lens, and the verify,
-  commit, and recovery steps that clear a commit-gate or verdict rejection.
-- **opus** — the reading lenses (code-review, bug-audit, self-review,
-  reuse), the terminal Bugbot gate, and the code-editing steps that fix findings
-  (fix-edit, conflict-edit, repair-edit, standards-edit).
-- **haiku** — the mechanical probes: preflight, the Copilot gate, the Codex
-  gate, the CLEAN-audit post, and the convergence check.
-
-## Full-diff rule
-
-Every lens, every round, reviews the full `origin/main...HEAD` diff — every file
-the PR touches. A lens that scopes to recent commits, a single file, or a
-bugbot-flagged path does not satisfy the round; its clean verdict is not a clean.
-
-## The ready definition
-
-`check_convergence.py` (`packages/claude-dev-env/_shared/pr-loop/scripts/check_convergence.py`) is the single
-source of truth for readiness. Ready means the script exits `0` and prints:
-
-```
-All pre-conditions met — PR is ready to mark ready.
-```
-
-The script re-derives every condition from GitHub and prints one PASS/FAIL line
-per label. The exact printed labels (script order) live in
-[`convergence-gates.md`](convergence-gates.md).
-
-The script has no Claude APPROVED review gate. Agent-side checks (Claude
-reviewer presence, broader unresolved-thread sweeps) sit outside this machine
-checklist.
-
-## Audit-trail design
-
-Bugbot and Copilot post their own review threads, which the fix lens replies to
-and resolves. Codex findings are local to the gate (no GitHub review thread) and
-enter the same fix path with `replyToCommentId: null`. The bug-audit lens keeps
-its findings in memory across the round and posts only the terminal CLEAN bugteam
-review once every lens is clean on a stable HEAD — that single artifact is what
-gate 3 reads. This keeps thread churn to the threads the bots raise themselves.

package/.agents/skills/autoconverge/reference/copilot-findings.md

@@ -1,51 +0,0 @@
-# Copilot findings — tier, verify, then route
-
-How the autoconverge Copilot gate handles each finding. The hub
-([`../SKILL.md`](../SKILL.md)) points here; the orchestrating session's
-user-review hold runs the [`copilot-finding-triage`](../../copilot-finding-triage/SKILL.md)
-skill.
-
-The Copilot gate tiers each finding: a **self-healing** finding (style, type
-hints, imports, formatting, magic-value extraction, test-only or doc-vs-code
-fixes — nothing that changes observable runtime behavior) flows into the fix
-round with no user notification. A **code-concern** finding (logic, security,
-data handling, error-handling semantics, concurrency — the tier whenever in
-doubt) goes to a verification stage before any routing.
-
-Each code-concern finding gets its own verifier agent, all in parallel, inside
-the workflow. A verdict is conclusive only when an actual check ran: the verifier
-executes a command against the flagged HEAD — running the code path with crafted
-inputs, forcing the claimed error condition, or running a purpose-built test —
-and captures its output. The verdict carries
-`{ verdict, checkCommand, checkOutput, evidence }`; a conclusive verdict with an
-empty `checkCommand` or `checkOutput` downgrades to inconclusive.
-
-- **confirmed** — the check reproduces the defect. The finding becomes
-  self-healing: it joins the fix round carrying its repro, and the fix re-runs
-  that same check, adds a regression test where the suite covers the surface,
-  lands in one commit, pushes, and replies on the thread with the fix SHA and the
-  before/after output. No page.
-- **refuted** — the check shows the code already behaves correctly in the exact
-  scenario the finding claims is broken. The workflow replies on the thread with
-  the command and output, resolves it, and counts it clean. No page.
-- **inconclusive** — everything else, and the verifier's default: no runnable
-  check exists, the check is infeasible here, the results are ambiguous, or the
-  fix needs a product decision. Any doubt sorts here. Only inconclusive findings
-  page the user.
-
-A round whose code concerns all confirm or refute never returns
-`blocker: "user-review"`. On one or more inconclusive findings, the workflow
-stops with `converged: false`, `blocker: "user-review"`, and a `userReview`
-field carrying
-`{ reviewUrl, findings: [{ file, line, severity, tier, title, evidence }] }` —
-`evidence` is the verifier's one-line note stating what check was attempted and
-why it was not decisive.
-
-A background workflow cannot hold for a human, so the wait belongs to the
-orchestrating session. On a `blocker: "user-review"` return, run the
-[`copilot-finding-triage`](../../copilot-finding-triage/SKILL.md) skill: send the
-ntfy notification (the per-finding summary and evidence note plus the `reviewUrl`
-Copilot review link), then hold with a 45-minute `ScheduleWakeup` for the user's
-response. When the user answers within the window, follow their direction. When
-the window closes with no response, run normal teardown and report the
-inconclusive findings un-reviewed.

package/.agents/skills/autoconverge/reference/gotchas.md

@@ -1,66 +0,0 @@
-# Gotchas
-
-Hard-won lessons for the autoconverge workflow. Append a bullet each time a run
-fails in a new way.
-
-- **The workflow script cannot sleep, and neither can an agent's foreground shell.** `Date.now`, `Math.random`, and timers
-  are unavailable in the script body, and a foreground `sleep` / `Start-Sleep` is blocked in the headless harness. Every
-  reviewer wait lives inside an `agent`'s own poll loop, and that loop waits with the Monitor tool inside the same turn —
-  never a foreground sleep, and never backgrounding a wait and ending the turn to await it, which
-  leaves a schema-bearing agent with no `StructuredOutput` call. Never try to wait in the script itself.
-
-- **Workflow agents start blank.** Spawned agents do not inherit CLAUDE.md,
-  rules, or this skill's context. Each agent prompt is self-contained: it names
-  the exact scripts and flags, the full `origin/main...HEAD` diff scope, and the
-  return contract.
-
-- **Only the fix lens writes.** The three converge lenses read and report; they
-  never edit, commit, or push. Because only the serial fix step pushes, the
-  parallel sweep needs no worktree isolation.
-
-- **Fetch origin/main once before the parallel lenses.** The code-review and
-  bug-audit lenses both diff against `origin/main`. Concurrent `git fetch` calls
-  contend on the worktree `.git` lock and fail intermittently, so the workflow
-  runs a single serial `git fetch origin main` inside the merged `preflight-git`
-  step — the one git-utility agent that also resolves the PR HEAD SHA, probes
-  mergeability, and checks Copilot and Bugbot availability — and the parallel
-  lenses run no git fetch of their own; they
-  diff against the already-current ref. The workflow threads the resolved HEAD
-  through the rounds and re-runs `preflight-git` only after a push or rebase
-  invalidates it, so a round on an unchanged HEAD spawns no git agent at all.
-
-- **The CLEAN bugteam artifact is HEAD-specific.** `check_convergence.py` reads
-  the bugteam review on the current HEAD. Any push moves HEAD and invalidates a
-  prior artifact, so post it only when a round is fully clean, and post a fresh
-  one after any later fix round.
-
-- **Bot login fields differ by endpoint.** `get_reviews` returns `.user.login`
-  (an object), while `get_review_comments` returns `.author` (a string). Match
-  bot logins with case-insensitive substring tests, not strict equality.
-
-- **`scriptPath` takes a real path, not a shell variable.** `$HOME` expands in a
-  Bash command but not in the `Workflow` tool's `scriptPath` argument. Pass the
-  expanded absolute path to `workflow/converge.mjs`.
-
-- **Tilde paths fail on Windows Git Bash.** Inside shell calls, use `$HOME/.claude/...`,
-  not `~/.claude/...`; a tilde resolves to the wrong home and gives a
-  file-not-found error that looks like a script failure.
-
-- **Local identity drift across accounts.** A local run that touches more than
-  one GitHub account must use the selected local account. Cloud runs use the
-  connected GitHub MCP identity and never use local CLI identity commands.
-
-- **Commit or push fails after a repair.** Read the hook or command output,
-  repair the named issue, and record the rerun. Apply the
-  [precatch rubric](../../_shared/pr-loop/precatch-rubric.md) before retrying.
-
-- **A Copilot "down" verdict is valid only after the full poll budget.** A
-  successful review request means the review is in flight — Copilot typically
-  posts within 10–15 minutes of the request. A gate agent that returns
-  `down:true` on a partial poll misreports an in-flight review as reviewer
-  unavailability, and the run marks the PR ready moments before the review
-  lands. After a successful request the only valid gate outcomes are a
-  received review on HEAD, an out-of-usage notice, or the full poll budget
-  spent. The teardown re-checks the PR for a late-arriving Copilot review
-  whenever the gate was bypassed, and routes its findings through one more
-  fix round.

package/.agents/skills/autoconverge/reference/headless-safety.md

@@ -1,44 +0,0 @@
-# Headless-safety preamble
-
-Every agent prompt the workflow authors carries a headless-safety preamble: the
-run is unattended, so 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.
-
-## Two forms
-
-The preamble has two forms. Read-only agents — the review, verify, and utility
-spawns that edit nothing — receive a trimmed form that drops the rm-shape rules,
-since a read-only agent never runs `rm`. Edit agents — the fix and commit spawns
-— receive the full form that carries the rm-shape rules below.
-
-Agents verify destructive-blocker behavior through the committed test suite
-(`python -m pytest`) and keep scratch work in the OS temp dir.
-
-## The rm auto-allow paths (full form)
-
-The full preamble describes three auto-allow paths:
-
-1. **Standalone path** — a standalone Bash call whose target resolves inside the
-   ephemeral namespace (`/tmp`, `/temp`, the OS temp root, or the run worktree).
-   It fails closed on `$(...)` substitution and backtick subshells. It declines a
-   `$`-bearing target only when the literal path is not already under an
-   ephemeral root, so it does not by itself stop a `$VAR` that expands inside an
-   ephemeral root.
-2. **Compound path** — accepts an rm joined with benign reporting segments when
-   every rm target is an absolute ephemeral path. It fails closed on `$(...)`
-   substitution, backtick subshells, and any `$` in the target — including
-   `$CLAUDE_JOB_DIR`.
-3. **Cwd-scoped path** — matches only when the command itself declares an
-   ephemeral working directory (it `cd`s into one, or runs under one). It
-   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. Under a
-   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.

package/.agents/skills/autoconverge/reference/multi-pr.md

@@ -1,128 +0,0 @@
-# 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 in
-   [`SKILL.md`](../SKILL.md) 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.
-5. **Copilot quota pre-check once for the whole run** — run the single-PR
-   pre-flight step 5 check one time:
-   `python "$HOME/.claude/_shared/pr-loop/scripts/copilot_quota.py"`. Every PR in
-   the run shares one account's Copilot premium-request quota, so one check covers
-   them all. Exit 0 sets `copilotDisabled: false` on every PR entry below; any
-   non-zero exit sets `copilotDisabled: true` on every entry, so each child skips
-   the Copilot gate with no agent spawned.
-
-## Launch
-
-Select the pacer once for the multi-PR run (same helper as single-PR):
-
-```
-python "$HOME/.claude/skills/_shared/pr-loop/scripts/select_converge_pacer.py" \
-  --skill autoconverge \
-  --has-workflow <0|1> \
-  --has-schedule-wakeup <0|1>
-```
-
-### `pacer=portable`
-
-Do **not** call `Workflow`. For each PR worktree from pre-flight, run the
-continuous portable driver in
-[`../../_shared/pr-loop/portable-driver.md`](../../_shared/pr-loop/portable-driver.md)
-(serial, or host fan-out when the host can isolate workers). One teardown per
-PR after that PR reaches ready or a named blocker. Shared Copilot quota and
-permission grants from multi-PR pre-flight still apply once.
-
-### `pacer=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",
-    homeDirectory: "<HOME>",
-    transport: "<cloud|local>",
-    prs: [
-      { owner: "<O>", repo: "<R>", prNumber: <N1>, repoPath: "<abs worktree 1>", bugbotDisabled: false, copilotDisabled: false },
-      { owner: "<O>", repo: "<R>", prNumber: <N2>, repoPath: "<abs worktree 2>", bugbotDisabled: false, copilotDisabled: 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. `homeDirectory` is the absolute path to the directory that holds
-`.claude` (resolve it once from `$HOME`, or `$env:USERPROFILE` on Windows, with
-forward slashes); the fan-out forwards it to every child run, which needs it to
-build the codex-review scripts path because the workflow sandbox has no access to
-environment variables. Set `transport: "cloud"` in a Cloud session and
-`transport: "local"` in a local session. Cloud uses the connected GitHub MCP
-tools and skips local CLI authentication. The workflow runs in the background
-and notifies the 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, allDeferredPrs, blocker }`, where
-`results` is one record per PR carrying
-`{ owner, repo, prNumber, converged, rounds, finalSha, blocker, deferredPrs }`.
-Each record's `deferredPrs` is that PR's own list of draft hardening PRs, and
-`allDeferredPrs` is every record's `deferredPrs` flattened into one list. The
-top-level `converged` is true only when every PR converged.
-
-## Multi-PR teardown
-
-### `pacer=portable`
-
-For each PR worktree, run the single-PR **Teardown → pacer=portable** path in
-[`SKILL.md`](../SKILL.md) (`pr-loop-lifecycle` Close, no Workflow journal
-report). Write one durable handoff per PR with that PR's `--pr-number` and
-resume command `/autoconverge <PR URL>`. Revoke project permissions once per
-repository after every PR's close. Print one summary line per PR as
-`#<prNumber>: <converged | blocked> — rounds <N>, final <finalSha>[, blocker <blocker>]`.
-
-### `pacer=workflow` (on workflow completion)
-
-Run the single-PR Teardown in [`SKILL.md`](../SKILL.md) once per entry in
-`results`, using that PR's `owner`, `repo`, `prNumber`, and `finalSha`, and its
-own worktree as the working directory. Write one durable handoff per PR entry —
-each with that PR's own `--pr-number` — so a fresh session can resume any PR on
-its own. 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>]`.

package/.agents/skills/autoconverge/reference/self-closing-loop.md

@@ -1,84 +0,0 @@
-# Self-closing loop: converge the deferred PRs
-
-Every run leaves work behind. When a round holds only code-standard findings, the
-standards-deferral path opens a draft environment-hardening PR and reports it in
-`deferredPrs`. That PR is itself a draft that needs to reach ready, and its own
-convergence can defer more standard findings, opening more hardening PRs. The
-self-closing loop drives that chain to the ground: after teardown, the
-orchestrator (the session that launched the workflow) converges the deferred
-PRs, then the PRs their runs defer, and so on until a generation opens none.
-
-This loop runs by default at the end of every autoconverge run — single-PR and
-multi-PR alike. It stops only when a generation's deferred-PR list comes back
-empty.
-
-## Seed the loop
-
-Collect the first generation of deferred PRs from the run that just finished:
-
-- A single-PR run seeds from its `deferredPrs`.
-- A multi-PR run seeds from its `allDeferredPrs`.
-
-When the seed list is empty, the loop is already done — the run deferred nothing,
-so there is nothing to converge. Report that and stop.
-
-## Each generation
-
-Given a non-empty list of deferred PRs `{ owner, repo, prNumber, copilotDisabled, bugbotDisabled }`
-(a generation may span more than one repository — a hardening PR lands in whichever repo owns
-the surface that blocks the deferred class, so `JonEcho/llm-settings` for hooks
-and `jl-cmd/claude-dev-env` for rules and skills both appear):
-
-1. **Check out each deferred PR.** Run the
-   [multi-PR pre-flight](multi-pr.md#multi-pr-pre-flight-main-session) once per
-   deferred PR. Because a deferred PR can live in a repo the first run never
-   touched, first find a local checkout of that PR's repo; when none exists,
-   clone it under the session temp dir, then add the per-PR worktree on the PR's
-   head ref. Drop any PR whose strict pre-flight fails rather than stopping the
-   whole generation. Grant project permissions once per repository the
-   generation spans.
-2. **Converge the generation.** Launch `workflow/converge_multi.mjs` with one
-   entry per checked-out deferred PR, exactly as the
-   [multi-PR launch](multi-pr.md#launch-the-multi-pr-workflow) describes. Each
-   child run checks Copilot and Bugbot availability through the workflow's own
-   preflight-git probe, carried across rounds, so a reviewer that is down or out
-   of quota is never spawned in any generation; the
-   `copilotDisabled`/`bugbotDisabled` flags each deferred PR carries seed that
-   check for the first round.
-3. **Tear down.** Run the [multi-PR teardown](multi-pr.md#multi-pr-teardown-on-workflow-completion)
-   over the generation's `results`, and revoke project permissions once per
-   repository.
-4. **Take the next seed.** The generation's `allDeferredPrs` is the next
-   generation's seed list. When it is empty, the loop is done.
-
-Repeat from step 1 with each new seed. The depth is unbounded: the loop keeps
-opening generations until one converges every deferred PR without deferring
-anything new.
-
-## Report each generation
-
-Log one line as each generation finishes, so a watcher sees the chain close:
-
-```
-Self-closing generation <k>: <converged>/<total> deferred PR(s) converged, <new> new deferred PR(s) opened
-```
-
-When the loop ends, print a final line naming the generation count and the total
-deferred PRs converged across every generation.
-
-## Conventional titles on deferred PRs
-
-Each hardening PR the loop opens targets a repo whose CI validates the PR title
-as a Conventional Commit. The commit step's prompt directs the agent to title
-the hardening PR as a Conventional Commit — a type prefix, an optional scope,
-then a colon and a short summary — so a deferred PR carries a conforming title
-(`feat(hooks): …`, `chore(rules): …`) before it exists. That prompt is where the
-conforming title is enforced.
-
-The `conventional_pr_title_gate` hook is a best-effort backstop on that title,
-not the guarantee. It blocks a `gh pr create` with a non-conforming `--title`
-only for a repo whose semantic-pull-request workflow leaves the action's
-`types:` input at the default Conventional Commits list. For a repo that pins
-its own explicit `types:` list — which the main target repo does in
-`.github/workflows/pr-check.yml` — the hook fails open and lets the title
-through, and the CI title check on GitHub has the final say.