npm - claude-dev-env - Versions diffs - 1.94.0 → 2.0.0 - Mend

claude-dev-env 1.94.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (280) hide show

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

@@ -99,7 +99,17 @@ Repeat until an exit condition fires.
       `git merge-base` + `git diff --name-only` live inside the script; see [`../../../_shared/pr-loop/scripts/README.md`](../../../_shared/pr-loop/scripts/README.md) for what lives under this directory, and [`../../../_shared/pr-loop/code-rules-gate.md`](../../../_shared/pr-loop/code-rules-gate.md) for gate-only merge-base / invocation semantics. The lead runs this (not a teammate).
    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 (`mode="bypassPermissions"`) — **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`.
+   3. If exit code **non-zero** → run a **standards-fix pass** through the
+      worker-spawn dispatcher (role `clean-coder`; see **Standards-fix
+      action** below). Instructions: read the gate script’s stderr, edit the
+      repo until a **re-run** of the **same** gate command exits **0**. On
+      tiers 1 and 3 the headless worker edits and runs tests but never
+      commits or pushes — the lead stages with explicit `git add`, mints the
+      code-verifier verdict, then commits and pushes. Tier 2 keeps in-agent
+      commit and push with `mode="bypassPermissions"`. Repeat standards-fix
+      spawns until the gate exits **0** or **5** failed gate rounds (each
+      round = one worker 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 > 20`, exit reason = `cap reached` (counts **audits**, not standards-only rounds).
    5. Execute **AUDIT action** (spawn bugfind). Print progress: `Loop <L> audit: ...`
@@ -116,46 +126,216 @@ Repeat until an exit condition fires.
 ## AUDIT action
-Spawn one audit agent that walks all A–P categories:
-```
-Agent(
-  subagent_type="code-quality-agent",
-  name="bugfind-pr<N>-loop<L>",
-  model="opus",
-  run_in_background=true,
-  description="Audit {owner}/{repo}#{N} loop {L}",
-  prompt="<output of build_audit_prompt.py; see ../../_shared/pr-loop/scripts/build_audit_prompt.py>"
-)
-```
+Walk all A–Q categories through the worker-spawn dispatcher
+([`worker-spawn.md`](../../../_shared/pr-loop/worker-spawn.md)). Every loop
+is a fresh process or a fresh agent context.
+1. **Build the headless audit prompt** and write it to a prompt file under the
+   per-PR workspace:
+   ```bash
+   python "${CLAUDE_SKILL_DIR}/../_shared/pr-loop/scripts/build_audit_prompt.py" \
+     --owner <O> --repo <R> --pr-number <N> --loop <L> \
+     --head-ref <head> --base-ref <base> \
+     --worktree-path <worktree_path> --run-temp-dir <run_temp_dir> \
+     --flavor headless \
+     > "${run_temp_dir}/pr-<N>/loop-<L>.audit-prompt.xml"
+   ```
+   Optional: `--pr-body-file <path>` when the PR body is available on disk.
+2. **Dispatch** via
+   [`resolve_worker_spawn.py`](../../../scripts/resolve_worker_spawn.py). Role
+   `bugteam` maps to primary agent `code-quality-agent`:
+   ```bash
+   python "${CLAUDE_SKILL_DIR}/../../scripts/resolve_worker_spawn.py" \
+     --role bugteam \
+     --prompt-file "${run_temp_dir}/pr-<N>/loop-<L>.audit-prompt.xml" \
+     --cwd <worktree_path> \
+     --run-temp-dir <run_temp_dir>
+   ```
+   The lead **blocks on the process** and reads the stdout JSON result.
+3. **Follow the result:**
+   - **Tier 1 or 3 served** (`tier_used` is `1` or `3`, exit `0`): the
+     dispatcher ran the worker to completion. Read the outcome XML at
+     `<worktree_path>/.bugteam-pr<N>-loop<L>.outcomes.xml`. The **lead**
+     posts the audit review with
+     [`post_audit_thread.py`](../../../_shared/pr-loop/scripts/post_audit_thread.py)
+     (see [SKILL.md § Audit posting](../SKILL.md#audit-posting)).
+   - **`claude_agent_required`** (exit `2`, attempts include tier `2` with
+     that reason): rebuild the prompt with default `--flavor agent` (omit
+     `--flavor` or pass `agent`) and spawn the Agent-tool worker, including
+     in-worker posting:
+     ```
+     Agent(
+       subagent_type="code-quality-agent",
+       name="bugfind-pr<N>-loop<L>",
+       model="opus",
+       run_in_background=true,
+       description="Audit {owner}/{repo}#{N} loop {L}",
+       prompt="<output of build_audit_prompt.py --flavor agent>"
+     )
+     ```
 The audit prompt XML is emitted by
 [`build_audit_prompt.py`](../../_shared/pr-loop/scripts/build_audit_prompt.py).
-Run it with `--owner --repo --pr-number --loop --head-ref --base-ref --worktree-path --run-temp-dir`
-to generate the complete `<spawn_prompt>` XML on stdout.
+`--flavor headless` targets the dispatcher path (gh reads, outcome file, no
+MCP/TaskCreate/Artifact). Default `--flavor agent` targets the Agent-tool
+path (MCP posting).
 `last_action = "audited"`. Append audit metadata to `audit_log`.
-## FIX action (fresh teammate)
-Spawn:
+## Standards-fix action
+Route through the worker-spawn dispatcher
+([`worker-spawn.md`](../../../_shared/pr-loop/worker-spawn.md)). Role
+`clean-coder` maps to primary agent `clean-coder`. Every round is a fresh
+process or a fresh agent context. The **5-round cap** stays (each round = one
+worker session after a non-zero gate).
+1. **Write a standards-fix prompt** under the per-PR workspace that includes
+   the gate stderr, the exact gate re-run command, and the worktree path. On
+   headless tiers the permission flag maps to each CLI's own flag
+   (`--permission-mode bypassPermissions`).
+2. **Dispatch:**
+   ```bash
+   python "${CLAUDE_SKILL_DIR}/../../scripts/resolve_worker_spawn.py" \
+     --role clean-coder \
+     --prompt-file "${run_temp_dir}/pr-<N>/loop-<L>.standards-fix-prompt.txt" \
+     --cwd <worktree_path> \
+     --run-temp-dir <run_temp_dir>
+   ```
+3. **Follow the result:**
+   - **Tier 1 or 3 served** (`tier_used` is `1` or `3`, exit `0`): the
+     headless worker edits and runs tests but never commits or pushes. The
+     lead session stages the worker's files itself with an explicit `git add`
+     (the session edit tracker does not see files the lead did not edit),
+     mints the code-verifier verdict in its own context, then commits and
+     pushes — so the commit gate and the staged-commit scans fire on the real
+     diff. Re-run the gate command; if still non-zero, start the next round.
+   - **`claude_agent_required`** (exit `2`, attempts include tier `2` with
+     that reason): spawn the Agent-tool worker with in-agent commit and push:
+     ```
+     Agent(
+       subagent_type="clean-coder",
+       name="standards-fix-pr<N>-loop<L>-round<R>",
+       model="opus",
+       mode="bypassPermissions",
+       run_in_background=true,
+       description="Standards-fix {owner}/{repo}#{N} loop {L} round {R}",
+       prompt="<gate stderr + re-run command + commit/push/shutdown>"
+     )
+     ```
+The missing-subagent refusal in [`../SKILL.md`](../SKILL.md) applies to tier 2
+only; headless tiers rely on the preflight's agent-definition-file check.
-```
-Agent(
-  subagent_type="clean-coder",
-  name="bugfix-pr<N>-loop<L>",
-  mode="bypassPermissions",
-  run_in_background=true,
-  description="Bugfix PR <N> loop <L>",
-  prompt="<output of build_fix_prompt.py; see ../../_shared/pr-loop/scripts/build_fix_prompt.py>"
-)
-```
-The teammate sees only the latest audit’s findings — each `Agent` call starts with a fresh context window; prior-loop findings, fix history, and chat stay in the lead.
-Pass finding comment URL, comment id, and thread node id for each finding (from `loop_comment_index`) in the XML prompt so the teammate owns both the reply and the thread resolution. After commit, the teammate posts one reply per finding using the unified template at [`../../../_shared/pr-loop/audit-reply-template.md`](../../../_shared/pr-loop/audit-reply-template.md) — the full header / horizontal rule / `<action_heading> ✅` / explanation / anchored-bullet / closing-paragraph skeleton, with `<status_line>` set per the path (`Fixed in <short_sha>` for `status=fixed`, `Could not address this loop` for `status=could_not_address`, `Hook blocked the fix commit` for `status=hook_blocked`). Per-thread reply and `resolve_thread` are atomic; the mechanics follow the shared 13-step sequence in [`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md) (step 12 carries the exact reply-and-resolve sequence). Same identity model as bugfind: teammate posts; lead waits.
+## FIX action (fresh teammate)
-After replies, the teammate writes outcome XML (schema in [`../PROMPTS.md`](../PROMPTS.md)).
+Route through the worker-spawn dispatcher
+([`worker-spawn.md`](../../../_shared/pr-loop/worker-spawn.md)). Role
+`clean-coder` maps to primary agent `clean-coder`. Every loop is a fresh
+process or a fresh agent context. The teammate sees only the latest audit’s
+findings — prior-loop findings, fix history, and chat stay in the lead.
+Pass finding comment URL, comment id, and thread node id for each finding
+(from `loop_comment_index`) in the XML prompt.
+1. **Build the headless fix prompt** and write it to a prompt file under the
+   per-PR workspace:
+   ```bash
+   python "${CLAUDE_SKILL_DIR}/../_shared/pr-loop/scripts/build_fix_prompt.py" \
+     --owner <O> --repo <R> --pr-number <N> --loop <L> \
+     --head-ref <head> --base-ref <base> \
+     --worktree-path <worktree_path> \
+     --findings-json <findings_json_path> \
+     --flavor headless \
+     > "${run_temp_dir}/pr-<N>/loop-<L>.fix-prompt.xml"
+   ```
+2. **Dispatch** via
+   [`resolve_worker_spawn.py`](../../../scripts/resolve_worker_spawn.py):
+   ```bash
+   python "${CLAUDE_SKILL_DIR}/../../scripts/resolve_worker_spawn.py" \
+     --role clean-coder \
+     --prompt-file "${run_temp_dir}/pr-<N>/loop-<L>.fix-prompt.xml" \
+     --cwd <worktree_path> \
+     --run-temp-dir <run_temp_dir>
+   ```
+   The lead **blocks on the process** and reads the stdout JSON result.
+3. **Follow the result:**
+   - **Tier 1 or 3 served** (`tier_used` is `1` or `3`, exit `0`): On tiers 1
+     and 3 the headless worker edits and runs tests but never commits or
+     pushes. The lead session stages the worker's files itself with an
+     explicit `git add` (the session edit tracker does not see files the lead
+     did not edit), mints the code-verifier verdict in its own context, then
+     commits and pushes — so the commit gate and the staged-commit scans fire
+     on the real diff. Read the outcome XML at
+     `<worktree_path>/.bugteam-pr<N>-loop<L>.fix-outcomes.xml`. The **lead**
+     posts one reply per finding using the unified template at
+     [`../../../_shared/pr-loop/audit-reply-template.md`](../../../_shared/pr-loop/audit-reply-template.md)
+     — the full header / horizontal rule / `<action_heading> ✅` /
+     explanation / anchored-bullet / closing-paragraph skeleton, with
+     `<status_line>` set per the path (`Fixed in <short_sha>` for
+     `status=fixed`, `Could not address this loop` for
+     `status=could_not_address`, `Hook blocked the fix commit` for
+     `status=hook_blocked`). Per-thread reply and `resolve_thread` are
+     atomic; the mechanics follow the shared 13-step sequence in
+     [`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md)
+     (step 12 carries the exact reply-and-resolve sequence).
+   - **`claude_agent_required`** (exit `2`, attempts include tier `2` with
+     that reason): Tier 2 keeps the current behavior end to end, including
+     in-agent commit and push and `mode="bypassPermissions"`. Rebuild the
+     prompt with default `--flavor agent` (omit `--flavor` or pass `agent`)
+     and spawn the Agent-tool worker, pinning model opus:
+     ```
+     Agent(
+       subagent_type="clean-coder",
+       name="bugfix-pr<N>-loop<L>",
+       model="opus",
+       mode="bypassPermissions",
+       run_in_background=true,
+       description="Bugfix PR <N> loop <L>",
+       prompt="<output of build_fix_prompt.py --flavor agent>"
+     )
+     ```
+     After commit, the teammate posts one reply per finding using the same
+     unified template and writes outcome XML (schema in
+     [`../PROMPTS.md`](../PROMPTS.md)).
+The fix prompt XML is emitted by
+[`build_fix_prompt.py`](../../_shared/pr-loop/scripts/build_fix_prompt.py).
+`--flavor headless` targets the dispatcher path (gh reads, outcome file, no
+commit/push/MCP/TaskCreate/Artifact). Default `--flavor agent` targets the
+Agent-tool path (in-agent commit, push, and MCP replies). On headless tiers
+the permission flag maps to each CLI's own flag
+(`--permission-mode bypassPermissions`).
+### Tier-1 flag profiles
+When tier-1 (headless grok) runs for audit or fix work and the **grok-spawn**
+skill is installed on the host, take CLI flag profiles from that skill's
+flag-profiles reference. Do not restate those flags here. When the skill is
+absent, use the host's grok headless defaults from the worker-spawn protocol
+and the headless runner. This page keeps the Agent-tool spawn shape for
+Claude-host teammates.
 ### Shutdown (bugfix)
@@ -163,9 +343,9 @@ Same self-termination model as bugfind. Missing notification → hard blocker.
 `approve: false` → `error: bugfix teammate refused shutdown` → Step 4 (`pr-loop-lifecycle` Close).
-Substitute placeholders from `last_findings` into the fix prompt per [`../PROMPTS.md`](../PROMPTS.md). The spawn XML includes TaskCreate/self_audit_checklist for task tracking — the FIX subagent MUST create tasks before starting.
+Substitute placeholders from `last_findings` into the fix prompt per [`../PROMPTS.md`](../PROMPTS.md). The agent-flavor spawn XML includes TaskCreate/self_audit_checklist for task tracking — the tier-2 FIX subagent MUST create tasks before starting. Headless flavors omit TaskCreate.
-**Verify push:** `git rev-parse HEAD` after fix must differ from before; new HEAD must exist on `origin/<branch>` (`git fetch origin <branch> && git rev-parse origin/<branch>` matches `HEAD`). If HEAD did not change → `stuck — bugfix teammate could not address findings`.
+**Verify push:** `git rev-parse HEAD` after fix must differ from before; new HEAD must exist on `origin/<branch>` (`git fetch origin <branch> && git rev-parse origin/<branch>` matches `HEAD`). If HEAD did not change → `stuck — bugfix teammate could not address findings`. On tiers 1 and 3 this check runs after the **lead** commit and push.
 **Scope verification.** Run `git diff HEAD~1 --name-only` and compare against the set of files referenced in `bugs_to_fix`. When the commit touches files NOT in the `bugs_to_fix` list, judge whether the extras are a coherent part of the fix: a shared helper the auditor did not think to name, a test file that exercises the fix, a config update the fix requires. If the extras are coherent with the fix, note them in the outcome XML's `<scope_notes>` and keep the outcome as `fixed`. If the extras look unrelated, suspicious, or out of scope, downgrade to `unverified_fixed` with reason `commit touched unexpected files: <list>`. The auditor's file list is a default, not a contract — the fix's coherence is the contract.

package/skills/bugteam/reference/design-rationale.md CHANGED Viewed

@@ -2,7 +2,7 @@
 ## Core principle (expanded)
-One audit agent (`code-quality-agent`, opus) walks all A–P categories per loop. One fix agent (`clean-coder`, opus) addresses the audit's findings.
+One audit agent (`code-quality-agent`, opus) walks all A–Q categories per loop. One fix agent (`clean-coder`, opus) addresses the audit's findings.
 Fresh-spawn clean-room isolation: each `Agent` call creates a new subagent with its own context window and no access to prior conversation. After the subagent writes its outcome XML and self-terminates, the lead reads the file. Results never accumulate in the lead’s context beyond the XML artifact. Verbatim Anthropic quotes and URLs: [`../sources.md`](../sources.md).

package/skills/bugteam/reference/obstacles/CLAUDE.md CHANGED Viewed

@@ -8,7 +8,7 @@ Per-step obstacle guides for the `bugteam` skill. Each file addresses a specific
 |---|---|
 | `audit-assign-ids.md` | Assigning stable finding IDs in the audit output. |
 | `audit-capture-excerpts.md` | Capturing code excerpts for each finding. |
-| `audit-walk-categories.md` | Walking all A–P categories without skipping. |
+| `audit-walk-categories.md` | Walking all A–Q categories without skipping. |
 | `audit-write-xml.md` | Writing the outcome XML from an audit pass. |
 | `fix-append-summary.md` | Appending the fix summary to the outcome XML. |
 | `fix-apply-fixes.md` | Applying code fixes from the finding list. |

package/skills/bugteam/reference/team-setup.md CHANGED Viewed

@@ -110,8 +110,14 @@ truth.
   `<run_temp_dir>` and pass that literal path to every shell command that follows.
 - **Subagent roles (spawned per loop, not at invocation start):**
-  - `bugfind` — `code-quality-agent`, model opus (Opus 4.7 at default xhigh effort)
-  - `bugfix` — `clean-coder`, no model pin (the lead picks the model per task)
+  - `bugfind` — `code-quality-agent`, model opus; routes through
+    `resolve_worker_spawn.py` with role `bugteam` (primary agent
+    `code-quality-agent`)
+  - `bugfix` — `clean-coder`, model opus; routes through
+    `resolve_worker_spawn.py` with role `clean-coder` (primary agent
+    `clean-coder`). Tier 2 Agent spawn pins `model="opus"`.
+  - `standards-fix` — `clean-coder` via the same dispatcher role; 5-round
+    cap; tier 2 pins `model="opus"` and `mode="bypassPermissions"`
 ### Loop state block

package/skills/closeout/SKILL.md ADDED Viewed

@@ -0,0 +1,153 @@
+---
+name: closeout
+description: >-
+  Harvests session obstacles into GitHub issues backed by quoted evidence at
+  session end, validates each draft with the user, dedupes against open and
+  closed issues, routes each to its repo, files children then a parent
+  checklist, and prints a computed cloud handoff prompt. Triggers: /closeout,
+  close out this session, close out the session, file the session obstacles,
+  session closeout, harvest session obstacles, end-of-session issue filing.
+  Near-miss: not session-log, which journals the session to the vault; closeout
+  files GitHub issues and prints a handoff prompt, and writes no session
+  journal.
+---
+# Closeout
+**Core principle:** At the end of a working session, turn the obstacles the session hit into user-approved GitHub issues — each backed by a quoted line — plus a computed cloud handoff prompt, never guessing, never filing without approval, never touching the host repo's live pipeline.
+## Gotchas
+Highest-signal content. Append a bullet each time a run fails in a new way.
+- An obstacle stated from memory drifts. File only what the session can quote word for word — the actual error text, the exact command, the exact log line. A candidate that cannot be quoted goes under "Unverified candidates" for the user to judge, never into a filed issue as fact.
+- Skipping the confirmation gate files noise to a shared server that other people read. Every parent and child draft passes the AskUserQuestion gate before any write.
+- A body that leans on chat context reads as a puzzle to anyone who opens the issue cold. Write each body so a reader with zero session context acts on it: name the failure, the count, and the quoted line.
+- A `--body` string mangles backticks on GitHub — they land as literal `\``. Every `gh` create and comment uses `--body-file <path>`.
+- A dedupe search that skips closed issues re-files a twin the team already resolved. The search covers `--state all`.
+- A volatile path in an issue body breaks the moment the job scratch is cleaned. Keep temp dirs, worktrees, and `$CLAUDE_JOB_DIR` out of every body.
+## When this skill applies
+Run this skill **at the end** of a working session, from inside that same session, when the session hit obstacles worth filing — hook blocks, gates that fired wrongly, tools that failed, forced workarounds, dead ends.
+Triggers: `/closeout`, "close out this session", "file the session obstacles", "session closeout", "harvest session obstacles", "end-of-session issue filing".
+**Refusal cases — first match wins:**
+- **Mid-session, work still open.** Respond: `Closeout runs at session end. Keep working, and run /closeout once the session's work is done.`
+- **Asked to journal the session.** Respond: `Closeout files GitHub issues; it does not write a session journal. For a session report to the vault, use /session-log.`
+- **No obstacles this session.** Respond: `No obstacles to file — the session hit no hook blocks, tool failures, or dead ends worth an issue. Nothing to close out.`
+## The process
+```
+- [ ] Phase 1 — Harvest obstacles from the three sources; quote verbatim evidence
+- [ ] Phase 1 — Run the PII pass over every candidate
+- [ ] Phase 2 — Draft the parent + children set
+- [ ] Phase 2 — Confirmation gate: AskUserQuestion, file only on approval
+- [ ] Phase 3 — Dedupe each candidate against open and closed issues
+- [ ] Phase 4 — Route each issue to its repo
+- [ ] Phase 5 — File children, then the parent checklist
+- [ ] Phase 6 — Print the computed cloud handoff prompt in chat
+```
+### Track the phases on the task list
+At invocation, copy the six phases onto the session task list — one task each via TaskCreate: harvest, draft + user validation, dedupe, repo routing, filing, handoff prompt. Mark a task `in_progress` with TaskUpdate when its phase starts and `completed` when the phase finishes.
+Hold one line on the filing task: never mark it `completed` while any planned issue is still uncreated. A filing phase that lands fewer issues than the approved set keeps the filing task open, with the missing issues named on it.
+### Phase 1 — Harvest obstacles
+Read three sources, in order:
+1. **This session's conversation** — the chat log visible in context.
+2. **The session task list** — TaskCreate/TaskUpdate records read through TaskList and TaskGet.
+3. **Tool results still in the context window** — hook denials, command output, log tails.
+An obstacle is a hook block, a gate that fired wrongly, a tool that failed, a forced workaround, or a dead end.
+**Non-negotiable evidence rule:** every filed issue quotes verbatim evidence captured this session — the actual error text, the exact command, the exact log line. An obstacle you cannot quote is dropped, or listed under a "Unverified candidates" section of the drafts for the user to decide. It is never filed as fact.
+**PII pass (runs on every run):** strip personal data from every issue body and from the handoff prompt — emails, real names, home paths, private hosts and IPs, account ids, tokens. The pass runs whether the target repo is public or private; repository visibility changes only how aggressive the redaction is (public repos get the strictest pass), never whether the pass runs. Checklist and swaps: [reference/pii-redaction-checklist.md](reference/pii-redaction-checklist.md).
+### Phase 2 — Draft and validate with the user
+Build the parent → children issue set as drafts. Body shapes and worked examples: [reference/issue-body-templates.md](reference/issue-body-templates.md).
+Then the **mandatory confirmation gate**. Present through AskUserQuestion:
+- Each drafted parent and child — title, target repo, one line of scope each.
+- Any PII concern the pass found.
+- Any closed twin a dedupe search surfaced (see Phase 3), as a reopen/comment/file-new choice.
+Filing to GitHub is an irreversible write to a shared server that other people read. File only on explicit user approval. The user validates every finding before anything is posted.
+### Phase 3 — Dedupe
+Before filing each candidate, search open and closed issues on the target repo:
+```
+gh issue list --search "<terms>" --state all
+```
+- **Open twin exists** → comment on it, rather than filing a new issue.
+- **Closed twin exists** → do not silently file or comment. Surface it in the Phase 2 gate as "previously closed twin — reopen, comment, or file new" for the user to decide.
+`gh issue list` needs no pagination flags. If you show a `gh api` read of a paginated list endpoint anywhere, show `--paginate --slurp` piped to external `jq` — `gh`'s built-in `--jq` runs per page and gives wrong cross-page results.
+### Phase 4 — Repo routing
+Route each issue by a deterministic rule:
+- The evidence names a file under the dev-env tree — `packages/claude-dev-env/hooks/`, `rules/`, `skills/`, `commands/`, `agents/`, `bin/`, or `docs/` — or an installed copy of those under `~/.claude/` (hooks, rules, skills, commands, agents) → file against **claude-dev-env**.
+- Otherwise → the **working repo**, read live:
+```
+gh repo view --json nameWithOwner
+```
+- **Cross-repo case** — a hook shipped by repo B blocked work in repo A → file against **B** and reference A in the body.
+### Phase 5 — File
+File **children first**, then the parent. The parent body is a checklist of `- [ ] owner/repo#N` lines, one per child created.
+- Every `gh issue create` and `gh issue comment` uses `--body-file <path>`, never `--body`.
+- No volatile paths in any body: no temp dirs, no worktrees, no `$CLAUDE_JOB_DIR`, no `.claude-editor/jobs` or `.claude/worktrees` paths.
+- Bodies are self-contained and specific: the failure mode, the count, and the quoted line — not "improve error handling".
+### Phase 6 — Computed handoff prompt
+Print **in chat** (not a file) a prompt the user pastes into a cloud session that opens PRs for the filed issues and drives them to convergence. Template and worked example: [reference/handoff-prompt-template.md](reference/handoff-prompt-template.md).
+The prompt is computed, not a bare list. It carries:
+1. **Safety boundaries** — what must never be run, merged, deployed, or synced. The working repo's pipeline is live in production.
+2. **Base branch and verification commands** — read the base branch and the per-package verification commands from the target repo's CLAUDE.md and docs at runtime.
+3. **Dependency order** — which issue must land before which, and which issues touch the same files and so must stack on one branch rather than run in parallel.
+If any issue cannot be done from a cloud session — it needs a local environment, physical devices, or a private network — the prompt says so per issue and scopes the cloud work to what a cloud session can reach.
+## Skill boundaries
+This skill runs inside a repo whose pipeline is live in production. Hold these lines:
+- It never runs that pipeline, never merges, never deploys, never syncs.
+- It never runs the host repo's automations.
+- It creates issues and comments and prints text. Nothing else.
+## File index
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | This hub — core principle, gotchas, refusal cases, six-phase process, boundaries |
+| `reference/issue-body-templates.md` | Parent and child issue body shapes with worked examples |
+| `reference/pii-redaction-checklist.md` | The PII pass: categories, swaps, public-versus-private aggression |
+| `reference/handoff-prompt-template.md` | The computed cloud handoff prompt shape with a worked example |
+## Folder map
+- `SKILL.md` — hub: principle, gotchas, refusal, six-phase process, boundaries.
+- `reference/` — issue body templates, PII redaction checklist, handoff prompt template.

package/skills/closeout/reference/handoff-prompt-template.md ADDED Viewed

@@ -0,0 +1,72 @@
+# Handoff prompt template
+The closing session prints this prompt in chat. The user pastes it into a cloud session that opens PRs for the filed issues and drives them to convergence. The prompt is computed from the filed set — the safety lines, base branch, verification commands, and dependency order are read at runtime, not guessed.
+## Contents
+- [Shape](#shape)
+- [How to compute each block](#how-to-compute-each-block)
+- [Worked example](#worked-example)
+## Shape
+```markdown
+# Cloud handoff — <parent issue owner/repo#N>
+## Task
+Open a PR per filed issue below and drive each to convergence.
+## Safety — never do these
+- Never run, merge, deploy, or sync the <working repo> pipeline. It is live in production.
+- Never run the host repo's automations.
+- <any repo-specific never line read from the target CLAUDE.md>
+## Base branch and verification
+- Base branch: <base>
+- Per-package verification commands:
+  - <package A>: <command>
+  - <package B>: <command>
+## Issues, in dependency order
+1. owner/repo#<N> — <title>. <cloud-doable? yes / no + why>.
+2. owner/repo#<N> — <title>. Depends on #<N> landing first.
+3. owner/repo#<N> — <title>. Touches the same files as #<N>; stack on one branch, do not run in parallel.
+## Cannot be done from a cloud session
+- owner/repo#<N> — needs <local environment / physical device / private network>. Scope the cloud work to <what a cloud session can reach>.
+```
+## How to compute each block
+- **Safety lines** — read the working repo's CLAUDE.md and docs for the pipeline, deploy, and sync commands the cloud session must never run. Name each one.
+- **Base branch** — read it live from the target repo (its default branch), not from memory.
+- **Verification commands** — read the per-package test and check commands from the target repo's CLAUDE.md or docs. List one line per package a filed issue touches.
+- **Dependency order** — for each pair of issues, decide: does one need the other's change to land first? Do they touch the same files? Same-file issues stack on one branch; independent issues run in parallel.
+- **Cloud reachability** — for each issue, decide whether a cloud session can do the work. An issue needing a local environment, physical devices, or a private network is marked, and the cloud work is scoped to the reachable part.
+## Worked example
+```markdown
+# Cloud handoff — jl-cmd/claude-dev-env#100
+## Task
+Open a PR per filed issue below and drive each to convergence.
+## Safety — never do these
+- Never run, merge, deploy, or sync the claude-dev-env publish pipeline. It is live in production (publishes to npm).
+- Never run the host repo's automations.
+- Never hand-edit .cursor/BUGBOT.md; it is generated from AGENTS.md.
+## Base branch and verification
+- Base branch: main
+- Per-package verification commands:
+  - claude-dev-env (JS): cd packages/claude-dev-env && npm test
+  - claude-dev-env (Python): python -m pytest packages/claude-dev-env
+## Issues, in dependency order
+1. jl-cmd/claude-dev-env#101 — inline-collection gate fires in exempt test files. Cloud-doable: yes.
+2. jl-cmd/claude-dev-env#102 — boolean-naming gate flags a fixture variable. Touches the same file as #101 (code_rules_enforcer.py); stack on one branch with #101, do not run in parallel.
+## Cannot be done from a cloud session
+- None. Both issues are pure hook-logic changes with local pytest coverage a cloud session can run.
+```

package/skills/closeout/reference/issue-body-templates.md ADDED Viewed

@@ -0,0 +1,108 @@
+# Issue body templates
+Body shapes for the parent tracking issue and its child issues, plus a worked example. Every body is self-contained: a reader with zero session context understands it. Every body carries a quoted line of evidence captured this session. Write each body to a temp file and pass it with `gh issue create --body-file <path>`.
+## Contents
+- [Child issue body](#child-issue-body)
+- [Parent tracking issue body](#parent-tracking-issue-body)
+- [Worked example — child](#worked-example--child)
+- [Worked example — parent](#worked-example--parent)
+- [Body rules](#body-rules)
+## Child issue body
+One obstacle per child. Fill every section:
+```markdown
+## What happened
+<One sentence: the failure mode, in plain terms.>
+## Evidence
+<The verbatim line captured this session — error text, command, or log line — in a fenced block.>
+```
+<exact quoted text>
+```
+## Where
+<The file, hook, gate, or tool the evidence names. Path relative to the repo root.>
+## Impact
+<What the obstacle cost: work blocked, count of times hit, workaround forced.>
+## Proposed fix
+<The specific change. Name the failure mode and the condition, not "improve error handling".>
+```
+## Parent tracking issue body
+The parent gathers the children. Its body is a checklist, one line per child created:
+```markdown
+## Session closeout — <short session label>
+Obstacles this session, filed as child issues:
+- [ ] owner/repo#<N> — <child title>
+- [ ] owner/repo#<N> — <child title>
+- [ ] owner/repo#<N> — <child title>
+## Handoff
+A cloud handoff prompt for these issues was printed in the closing session. It carries the safety boundaries, base branch, per-package verification commands, and the dependency order among the children.
+```
+## Worked example — child
+```markdown
+## What happened
+The code_rules_enforcer hook blocked a valid list literal in a test file, where test files are exempt from the magic-value gate.
+## Evidence
+```
+BLOCKED: [MAGIC_VALUE] Inline list literal [200, 404, 500] in a function body -- extract to a named constant in config/.
+```
+## Where
+packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py — the inline-collection check.
+## Impact
+Hit 3 times in one session on three test files. Forced a workaround: moving each literal to a module constant the test did not need.
+## Proposed fix
+Extend the test-file exemption that already covers the magic-value gate to also cover the inline-collection check, so list and set literals in test bodies pass.
+```
+## Worked example — parent
+```markdown
+## Session closeout — hook exemptions for test files
+Obstacles this session, filed as child issues:
+- [ ] jl-cmd/claude-dev-env#101 — inline-collection gate fires in exempt test files
+- [ ] jl-cmd/claude-dev-env#102 — boolean-naming gate flags a fixture variable
+## Handoff
+A cloud handoff prompt for these issues was printed in the closing session. It carries the safety boundaries, base branch, per-package verification commands, and the dependency order among the children.
+```
+## Body rules
+- **Quoted evidence is required.** No child ships without a fenced block holding a line captured this session.
+- **No volatile paths.** No temp dirs, worktrees, `$CLAUDE_JOB_DIR`, `.claude-editor/jobs`, or `.claude/worktrees` paths in any body. Paste text inline; for a binary artifact, upload it to a durable release and link that URL.
+- **No chat references.** Drop "as discussed" and "the choice we picked". State each fact on its own.
+- **Specific over vague.** "The gate fires on `[200, 404, 500]` in a test body" beats "the gate is too strict".
+- **PII stripped.** Run the PII pass (see the PII redaction checklist) over every body before it reaches the confirmation gate.