claude-dev-env 1.94.0 → 1.95.0

package/hooks/validators/test_python_style_helpers.py

@@ -0,0 +1,125 @@
+"""Tests for the shared source-line and function-discovery helpers."""
+
+import ast
+
+from .python_style_helpers import (
+    blank_line_for_source,
+    function_start_line,
+    gap_is_blank_only,
+    iter_function_definitions,
+    real_newline_lines,
+    top_level_functions,
+)
+
+TWO_FUNCTIONS = """def foo() -> None:
+    pass
+
+
+def bar() -> None:
+    pass
+"""
+
+DECORATED_FUNCTION = """@decorator
+def decorated() -> None:
+    pass
+"""
+
+CRLF_SOURCE = "def foo() -> None:\r\n    pass\r\n"
+
+
+class TestIterFunctionDefinitions:
+    """Discovery of every function definition in a tree."""
+
+    def test_yields_each_function(self) -> None:
+        """Every top-level function is yielded."""
+        tree = ast.parse(TWO_FUNCTIONS)
+        names = [each.name for each in iter_function_definitions(tree)]
+        assert names == ["foo", "bar"]
+
+    def test_yields_nested_functions(self) -> None:
+        """A nested function is discovered alongside its enclosing function."""
+        tree = ast.parse("def outer() -> None:\n    def inner() -> None:\n        pass\n")
+        names = {each.name for each in iter_function_definitions(tree)}
+        assert names == {"outer", "inner"}
+
+
+class TestTopLevelFunctions:
+    """Ordered listing of a module's top-level functions."""
+
+    def test_returns_functions_in_line_order(self) -> None:
+        """Top-level functions are returned ordered by line."""
+        ordered = top_level_functions(TWO_FUNCTIONS)
+        assert [each.name for each in ordered] == ["foo", "bar"]
+
+    def test_ignores_nested_functions(self) -> None:
+        """A function nested inside another is not top-level."""
+        ordered = top_level_functions(
+            "def outer() -> None:\n    def inner() -> None:\n        pass\n"
+        )
+        assert [each.name for each in ordered] == ["outer"]
+
+    def test_syntax_error_returns_empty(self) -> None:
+        """Unparseable source yields no functions."""
+        assert top_level_functions("def foo(") == []
+
+
+class TestFunctionStartLine:
+    """First source line of a function, counting decorators."""
+
+    def test_undecorated_uses_def_line(self) -> None:
+        """An undecorated function starts on its def line."""
+        function_node = top_level_functions(TWO_FUNCTIONS)[0]
+        assert function_start_line(function_node) == 1
+
+    def test_decorated_uses_first_decorator_line(self) -> None:
+        """A decorated function starts on its first decorator line."""
+        function_node = top_level_functions(DECORATED_FUNCTION)[0]
+        assert function_start_line(function_node) == 1
+
+
+class TestGapIsBlankOnly:
+    """Whether a run of lines between functions is entirely blank."""
+
+    def test_all_blank_lines_true(self) -> None:
+        """A gap of blank lines reports blank-only."""
+        assert gap_is_blank_only(["\n", "   \n", ""]) is True
+
+    def test_non_blank_line_false(self) -> None:
+        """A gap holding any content is not blank-only."""
+        assert gap_is_blank_only(["\n", "# comment\n"]) is False
+
+
+class TestRealNewlineLines:
+    """Line splitting aligned with ast line numbers."""
+
+    def test_splits_on_lf(self) -> None:
+        """LF-separated source splits into its lines with endings kept."""
+        assert real_newline_lines("a\nb\n") == ["a\n", "b\n"]
+
+    def test_splits_on_crlf(self) -> None:
+        """CRLF pairs count as a single line ending."""
+        assert real_newline_lines("a\r\nb\r\n") == ["a\r\n", "b\r\n"]
+
+    def test_form_feed_stays_in_line(self) -> None:
+        """A form feed does not start a new line, matching ast line numbers."""
+        assert real_newline_lines("a\x0cb\n") == ["a\x0cb\n"]
+
+    def test_trailing_partial_line_kept(self) -> None:
+        """A final line with no ending is preserved."""
+        assert real_newline_lines("a\nb") == ["a\n", "b"]
+
+    def test_empty_source_returns_no_lines(self) -> None:
+        """Empty source yields an empty list of lines."""
+        assert real_newline_lines("") == []
+
+
+class TestBlankLineForSource:
+    """Blank-line string matching the source newline convention."""
+
+    def test_lf_source_returns_lf(self) -> None:
+        """LF source yields an LF blank line."""
+        assert blank_line_for_source("a\nb\n") == "\n"
+
+    def test_crlf_source_returns_crlf(self) -> None:
+        """CRLF source yields a CRLF blank line."""
+        assert blank_line_for_source(CRLF_SOURCE) == "\r\n"

package/package.json

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

package/rules/CLAUDE.md

@@ -12,6 +12,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | File | Rule |
 |---|---|
 | `agent-spawn-protocol.md` | Protocol for spawning subagents: context sufficiency check, prompt generation via `/prompt-generator`, then spawn |
+| `anti-corollary-tests.md` | Tests must carry information: no corollary matrices over canonical reductions, no suite that only matches a dead-implementation default, stated mutation in the audit lane |
 | `ask-user-question-required.md` | Every user-directed question goes through the `AskUserQuestion` tool — no plain-text questions |
 | `bdd.md` | BDD discovery-driven development workflow and Example Mapping reference |
 | `claude-md-orphan-file.md` | Every backticked bare filename in a per-directory `CLAUDE.md` table's first column names a file in that directory's subtree |

package/rules/anti-corollary-tests.md

@@ -0,0 +1,69 @@
+---
+paths:
+  - "**/test_*.py"
+  - "**/*_test.py"
+  - "**/*.test.*"
+  - "**/*.spec.*"
+  - "**/conftest.py"
+  - "**/tests/**"
+---
+
+# Anti-Corollary Tests
+
+**When this applies:** Any Write or Edit that adds or changes tests.
+
+## Rule
+
+A large green suite can prove almost nothing. Before you keep a case, answer three questions. If any answer fails, cut the case or replace it with one that carries information.
+
+## The three questions
+
+### 1. Is this a corollary?
+
+When the code reduces each input to a canonical form and then compares the forms, every pairwise combination of input spellings follows once the reduction is proven canonical. Walking the full N×N matrix restates that fact. It adds cases and runtime, and it buries the few cases that carry information.
+
+**Do this:** test the reduction once. Test the comparison with a few discriminating cases. Do not walk the cross product of spellings.
+
+### 2. Could this test pass if the mechanism were dead?
+
+Name the degenerate value a dead implementation would return — empty string, `None`, `False`, a blanket refusal, an empty collection. When the test's expected value equals that default, the test passes whether the mechanism works or not. On its own it proves nothing.
+
+**Do this:** keep at least one case that expects the **non-default** answer, and drive the real code path — not a mock that only records that a call happened.
+
+### 3. What single change to the code would make this test fail?
+
+When the honest answer is "none," or "only a change that also breaks everything else," the test is decoration. Drop it or rewrite it so one named mutation kills it.
+
+## What a mechanism with a degenerate failure mode needs
+
+1. **At least one non-default case** that exercises the live path and expects the non-default answer.
+2. **A stated mutation (audit lane):** name one specific change to the code and record how many tests it kills. A mutation that kills zero tests means the suite proves nothing. A reviewer or an audit skill checks this; a hook does not compute it.
+3. **A few discriminating cases** in place of a large matrix.
+
+## Worked shape (sanitized)
+
+A write guard decides whether a write is about to hit a production database. It reduces each database URL to a canonical endpoint identity, then compares identities.
+
+Two independent mutations show the two halves of a useful suite:
+
+- Gut the reduction so it always returns the empty string: the guard fails **closed** and refuses everything. Only the *allow*-expecting cases die.
+- Abandon the reduction and compare raw hostnames: the guard fails **open** and allows a production write. Only the *refuse*-expecting cases die.
+
+Opposite breaks kill opposite halves. A suite with only one half cannot see one of those breaks. Build both halves; skip the spelling matrix once the reduction is covered.
+
+## What this is not
+
+A structural hook is the wrong tool here. "Is this a corollary?" and "would this pass against a dead implementation?" need the intent of the code under test. A hook that pattern-matches `parametrize` breadth or counts assertions fires on correct suites and trains people to ignore it. A false-positive gate on a judgment call is worse than no gate. This rule stays judgment-only, with the stated-mutation check in the audit lane — the same pattern as other judgment rules in this package that have no Write/Edit blocker.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| `tdd.md` | Write a failing test before production code |
+| `testing.md` | Mocks and test infrastructure standards |
+| `paired-test-coverage.md` | Every public function in an established suite gets a behavioral test |
+| `anti-corollary-tests.md` | Each test carries information; no corollary matrices; no suite that only matches the dead default |
+
+## Enforcement
+
+The AI review lane and audit skills carry this rule: an agent applies it to the test lines a PR changes. No blocking hook backs it, because corollary and dead-default judgments need meaning a regex cannot read.

package/rules/bdd.md

@@ -2,8 +2,6 @@
 
 **Canonical detail:** `~/.claude/system-prompts/software-engineer.xml` → `<behavior_protocol>`.
 
-**On-demand depth:** `@~/.claude/skills/bdd-protocol/SKILL.md` (Example Mapping §6.4, §7.6 catalog, solo patterns). Tracking design: [jl-cmd/claude-dev-env#82](https://github.com/jl-cmd/claude-dev-env/issues/82).
-
 **Optional long-form references (load when needed):**
 
 - `@~/.claude/docs/BDD_SCENARIO_QUALITY.md` — seven scenario quality patterns (§7.6-style)
@@ -21,7 +19,7 @@ Conversation is the essential practice: if discovery is skipped, structured form
 
 ## Solo developer
 
-You are often the stakeholder. Use **Example Mapping** in chat ("the one where …", probes, parking lot). Load **`bdd-protocol`** when you need the full algorithm and anti-pattern list.
+You are often the stakeholder. Use **Example Mapping** in chat ("the one where …", probes, parking lot). See the optional long-form references above for the full algorithm and anti-pattern list.
 
 ## Naming
 

package/rules/code-reviews.md

@@ -2,7 +2,7 @@
 
 **When this applies:** GitHub PR review feedback on a branch you are fixing.
 
-**MANDATORY PROTOCOL (use pr-review-responder skill):**
+**MANDATORY PROTOCOL:**
 
 1. Fetch ALL reviewer comments BEFORE any fixes
 2. Create TodoWrite checklist - One item per comment

package/rules/gh-paginate.md

@@ -1,3 +1,3 @@
 # gh API Pagination
 
-Every `gh api` read of a paginated GitHub list endpoint (PR `reviews`/`comments`/`files`, issue `comments`, `pulls`, `issues`) uses `--paginate --slurp` piped to **external** `jq` — `gh`'s built-in `--jq` runs per page, so cross-page operations like `sort_by | last` give wrong-but-confident results. Single-object endpoints (`pulls/<n>`, `issues/<n>`) skip pagination and may use `--jq` directly. Full safe patterns (single-page bounds, newest-first walks): gh-paginate skill.
+Every `gh api` read of a paginated GitHub list endpoint (PR `reviews`/`comments`/`files`, issue `comments`, `pulls`, `issues`) uses `--paginate --slurp` piped to **external** `jq` — `gh`'s built-in `--jq` runs per page, so cross-page operations like `sort_by | last` give wrong-but-confident results. Single-object endpoints (`pulls/<n>`, `issues/<n>`) skip pagination and may use `--jq` directly. For a newest-first walk, sort the slurped array and take the last element; for single-page bounds, cap with a `per_page` query parameter.

package/rules/plain-language.md

@@ -3,3 +3,5 @@
 All prose a person reads (chat, `AskUserQuestion`, docs, PR/issue bodies, commits): everyday words, short active sentences, lead with the answer, define jargon on first use, and give only the detail the reader needs to act (progressive disclosure). Aim for first-pass readability by a non-specialist. Exact identifiers, file paths, and API names stay exact; code is out of scope.
 
 The `plain_language_blocker` PreToolUse hook (AskUserQuestion + `.md` Write/Edit/MultiEdit) blocks a heavy word and names the everyday swap; code fences, inline code, blockquotes, URLs, and file paths are skipped.
+
+A project can keep its own domain words out of the check with a `.claude/plain-language-allow.json` file: a JSON array of terms. An exact, case-insensitive, whole-word match on any term passes. The hook reads this file only from inside the project tree, up to the repository root, so each project's allowlist stays with its own code.

package/skills/CLAUDE.md

@@ -23,9 +23,9 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 
 **Planning and implementation**
 - `anthropic-plan` — creates a source-grounded plan packet before any code changes
-- `orchestrator` — turns the session into the orchestrator: it spawns executor subagents to do the code edits and test runs; hard decisions go to a shared advisor (Claude warm `session-advisor` via SendMessage; Grok self-as-advisor on the orchestrating session)
-- `orchestrator-refresh` — sub-skill fired by the `/orchestrator` loop to re-assert the host-matched shared-advisor discipline mid-run (Claude SendMessage; Grok self-as-advisor, no Agent spawn)
-- `team-advisor` — binds one advisor at the strongest reachable tier (Claude warm agent; Grok self-as-advisor) and consults it for a second opinion before a big decision, at completion, when stuck, or when reconsidering the approach
+- `orchestrator` — turns the session into the orchestrator: it spawns executor subagents to do the code edits and test runs; hard decisions go to a shared advisor (Claude warm `session-advisor` via SendMessage; Grok: max-tier Claude via CLI Claude-chain)
+- `orchestrator-refresh` — sub-skill fired by the `/orchestrator` loop to re-assert the host-matched shared-advisor discipline mid-run (Claude SendMessage; Grok Claude CLI chain, no Agent-tool advisor spawn)
+- `team-advisor` — binds one advisor at the strongest reachable tier (Claude warm agent; Grok max-tier Claude via CLI Claude-chain, fail closed when unreachable) and consults it for a second opinion before a big decision, at completion, when stuck, or when reconsidering the approach
 
 **PR review and convergence**
 - `autoconverge` — autonomous single-run workflow that drives a PR to ready
@@ -34,6 +34,7 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 - `copilot-review` — requests and polls a GitHub Copilot review
 - `copilot-finding-triage` — tiers each Copilot gate finding, verifies each code concern with an executed check, then routes it (auto-fix a confirmed defect, resolve a refuted one, page the user only for an inconclusive one)
 - `reviewer-gates` — availability gates for external reviewers (opt-out parse, Copilot quota, Bugbot trigger/detect)
+- `pr-fix-protocol` — applies reviewer findings as verified fixes and drives unresolved review threads to zero
 - `pr-loop-lifecycle` — opens and closes a PR-loop run (grant, teardown, PR description, revoke, report)
 - `pr-loop-cloud-transport` — six-step transport workflow that lets any PR-loop skill run in a session whose `gh` CLI is absent or cannot act on the PR (MCP schema load, origin/HEAD fix, identity rules, the gh-to-MCP substitution matrix, the Copilot status rule, and the post self-check)
 

package/skills/autoconverge/workflow/converge.mjs

@@ -1722,7 +1722,7 @@ function runAuditLens(head, preflightResult) {
  * Self-review lens: the semantic pre-catch parity pass over the full diff. It
  * covers the doc-vs-code parity, test-assertion completeness, and
  * PR-description-vs-diff lanes that sit outside the A-P bug categories, reusing
- * the pr-consistency-audit skill's canonical-source cross-reference method. It
+ * the pr-consistency-audit prompt's canonical-source cross-reference method. It
  * stays on opus because line-citation accuracy, symbol attribution, and
  * inventory or count claims are semantic judgments a cheaper tier misreads. It
  * reports findings without editing.
@@ -1735,7 +1735,7 @@ function runSelfReviewLens(head, preflightResult) {
     `You are the self-review parity lens for ${prCoordinates}, HEAD ${head}. Review the FULL origin/main...HEAD diff — every file the PR touches. Do NOT edit, commit, or push.\n\n` +
       renderLensDiffContext(preflightResult) +
       `Read the pre-catch rubric at ${CONFIG.precatchRubric} for the three lane checklists, and cover each lane:\n` +
-      `1. Doc-vs-code parity: reuse the pr-consistency-audit skill's canonical-source cross-reference method ($HOME/.claude/skills/pr-consistency-audit/SKILL.md) and the drift rubric at $HOME/.claude/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md. Verify every line citation resolves, every referenced file or script path exists, every symbol is attributed to the file that defines it, and every inventory, count, and ordering claim matches the code.\n` +
+      `1. Doc-vs-code parity: reuse the pr-consistency-audit prompt's canonical-source cross-reference method ($HOME/.claude/skills/_shared/pr-loop/prompts/pr-consistency-audit.xml) and the drift rubric at $HOME/.claude/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md. Verify every line citation resolves, every referenced file or script path exists, every symbol is attributed to the file that defines it, and every inventory, count, and ordering claim matches the code.\n` +
       `2. Test-assertion completeness: every changed or new production path has a paired test that calls it and asserts on its behavior, and a changed test pins behavior rather than hiding it behind a mock.\n` +
       `3. PR-description-vs-diff two-way parity: fetch the PR body read-only, then confirm every PR-body claim maps to a hunk in the diff and every hunk maps to a claim; flag invented paths, invented counts, and out-of-scope changes.\n\n` +
       `Before returning clean, state one proof-of-absence line per lane naming what you checked. Return strictly the schema: clean=true with empty findings when all three lanes pass, otherwise one entry per finding (severity P0/P1/P2; category 'code-standard' for a pure doc or style parity gap with no behavioral impact, 'bug' otherwise; replyToCommentId=null). Set sha=${'`'}${head}${'`'}, down=false.`,

package/skills/bugteam/reference/README.md

@@ -22,8 +22,7 @@ The `pre-push-review` skill was retired. Its mechanical checks are now covered a
 
 - **`/qbug`** — a full PR audit-fix cycle that spawns subagents, runs multiple audit loops, and produces a structured report. It is NOT a lightweight pre-push gate. Do not use `/qbug` as a substitute for `git push` (the hook fires automatically). Use `/qbug` when you want a thorough multi-loop review of a PR before requesting human review.
 
-References updated:
-- `skills/pr-review-responder/SKILL.md` — Rule 6 and checklist item updated to reference the git pre-push hook
-- `commands/plan.md` — Phase 5 step 10 updated to reference the git pre-push hook
+References:
+- `hooks/git-hooks/pre_push.py` — the git pre-push hook that runs the CODE_RULES gate over the commits about to be pushed
 - `hooks/github-action/pre-push-review.yml` — deleted (workflow no longer needed)
 - `hooks/github-action/test_workflow.py` — deleted alongside the workflow

package/skills/closeout/SKILL.md

@@ -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

@@ -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

@@ -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.