claude-dev-env 1.93.1 → 1.95.0

package/skills/bugteam/scripts/test_bugteam_preflight.py

@@ -1,316 +1,41 @@
-"""Tests for bugteam_preflight git hooks path verification.
+"""Smoke tests for the skill-path preflight wrap.
 
-Covers:
-- core.hooksPath unset: exits non-zero with correction message
-- core.hooksPath pointing to the correct claude hooks dir: exits zero
-- core.hooksPath pointing elsewhere (husky override): exits non-zero
-- core.hooksPath with trailing slash: must still pass after normalization
+Behavioral coverage lives at
+``_shared/pr-loop/scripts/tests/test_preflight.py``.
 """
 
 from __future__ import annotations
 
 import importlib.util
-import subprocess
-import sys
 from pathlib import Path
 from types import ModuleType
-from unittest.mock import MagicMock, patch
 
-import pytest
 
-
-def _load_preflight_module() -> ModuleType:
+def _load_wrap_module() -> ModuleType:
     module_path = Path(__file__).parent / "bugteam_preflight.py"
-    spec = importlib.util.spec_from_file_location("bugteam_preflight", module_path)
-    assert spec is not None
-    assert spec.loader is not None
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-bugteam_preflight = _load_preflight_module()
-
-
-def _make_completed_process(
-    stdout: str, returncode: int
-) -> subprocess.CompletedProcess:
-    process = MagicMock(spec=subprocess.CompletedProcess)
-    process.stdout = stdout
-    process.returncode = returncode
-    return process
-
-
-def test_should_exit_nonzero_when_core_hooks_path_unset(capsys: pytest.CaptureFixture[str]) -> None:
-    with patch("subprocess.run") as mock_run:
-        mock_run.return_value = _make_completed_process("", returncode=1)
-        exit_code = bugteam_preflight.verify_git_hooks_path(Path("."))
-    assert exit_code != 0
-    captured = capsys.readouterr()
-    assert "core.hooksPath" in captured.err
-    assert "npx claude-dev-env" in captured.err or "git config" in captured.err
-
-
-def test_should_exit_zero_when_core_hooks_path_points_to_claude_hooks(tmp_path: Path) -> None:
-    claude_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
-    claude_hooks_path.mkdir(parents=True)
-    with patch("subprocess.run") as mock_run:
-        mock_run.return_value = _make_completed_process(
-            str(claude_hooks_path) + "\n", returncode=0
-        )
-        exit_code = bugteam_preflight.verify_git_hooks_path(Path("."))
-    assert exit_code == 0
-
-
-def test_should_exit_nonzero_when_core_hooks_path_points_elsewhere(capsys: pytest.CaptureFixture[str]) -> None:
-    with patch("subprocess.run") as mock_run:
-        mock_run.return_value = _make_completed_process(
-            "/some/other/path/.husky\n", returncode=0
-        )
-        exit_code = bugteam_preflight.verify_git_hooks_path(Path("."))
-    assert exit_code != 0
-    captured = capsys.readouterr()
-    assert "core.hooksPath" in captured.err
-
-
-def test_should_include_correction_commands_in_error_message(capsys: pytest.CaptureFixture[str]) -> None:
-    with patch("subprocess.run") as mock_run:
-        mock_run.return_value = _make_completed_process("", returncode=1)
-        bugteam_preflight.verify_git_hooks_path(Path("."))
-    captured = capsys.readouterr()
-    assert (
-        "npx claude-dev-env" in captured.err
-        or "git config --global core.hooksPath" in captured.err
-    )
-
-
-def test_main_should_exit_nonzero_when_hooks_path_unset() -> None:
-    with patch("subprocess.run") as mock_run:
-        mock_run.return_value = _make_completed_process("", returncode=1)
-        exit_code = bugteam_preflight.main(["--no-pytest"])
-    assert exit_code != 0
-
-
-def test_main_should_continue_when_hooks_path_valid(tmp_path: Path) -> None:
-    claude_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
-    claude_hooks_path.mkdir(parents=True)
-    with patch("subprocess.run") as mock_run:
-        mock_run.return_value = _make_completed_process(
-            str(claude_hooks_path) + "\n", returncode=0
-        )
-        exit_code = bugteam_preflight.main(["--no-pytest"])
-    assert exit_code == 0
-
-
-def test_should_accept_hooks_path_with_trailing_slash() -> None:
-    with patch("subprocess.run") as mock_run:
-        mock_run.return_value = _make_completed_process(
-            "/home/user/.claude/hooks/git-hooks/\n", returncode=0
-        )
-        exit_code = bugteam_preflight.verify_git_hooks_path(Path("."))
-    assert exit_code == 0, (
-        "hooksPath with trailing slash must pass verification after normalization"
-    )
-
-
-def test_should_exit_zero_when_hooks_path_set_at_repo_scope(tmp_path: Path) -> None:
-    claude_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
-    claude_hooks_path.mkdir(parents=True)
-    repo_root = tmp_path / "my-repo"
-    repo_root.mkdir()
-    with patch("subprocess.run") as mock_run:
-        mock_run.return_value = _make_completed_process(
-            str(claude_hooks_path) + "\n", returncode=0
-        )
-        exit_code = bugteam_preflight.verify_git_hooks_path(repo_root)
-    assert exit_code == 0, (
-        "verify_git_hooks_path must accept a valid path returned by effective "
-        "config query (not restricted to --global scope)"
-    )
-    called_command = mock_run.call_args[0][0]
-    assert "--global" not in called_command, (
-        "verify_git_hooks_path must query effective config, not --global only"
-    )
-    assert "-C" in called_command, (
-        "verify_git_hooks_path must use git -C <repo_root> for repo-effective config"
-    )
-    dash_c_index = called_command.index("-C")
-    assert called_command[dash_c_index + 1] == str(repo_root), (
-        "git -C must receive the resolved repository root path"
-    )
-
-
-def test_verify_git_hooks_path_accepts_none_repository_root(tmp_path: Path) -> None:
-    """When repository_root is None, the call must use git's cwd-effective config.
-
-    Binds the documented optional contract: passing None must not raise and must
-    omit the `-C <root>` arguments so git falls back to the working directory.
-    """
-    claude_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
-    claude_hooks_path.mkdir(parents=True)
-    with patch("subprocess.run") as mock_run:
-        mock_run.return_value = _make_completed_process(
-            str(claude_hooks_path) + "\n", returncode=0
-        )
-        exit_code = bugteam_preflight.verify_git_hooks_path(None)
-    assert exit_code == 0
-    called_command = mock_run.call_args[0][0]
-    assert "-C" not in called_command, (
-        "verify_git_hooks_path(None) must omit -C so git uses cwd-effective config"
-    )
-
-
-def test_should_accept_hooks_path_with_backslash_and_trailing_slash() -> None:
-    with patch("subprocess.run") as mock_run:
-        mock_run.return_value = _make_completed_process(
-            "C:\\Users\\user\\.claude\\hooks\\git-hooks\\\n", returncode=0
-        )
-        exit_code = bugteam_preflight.verify_git_hooks_path(Path("."))
-    assert exit_code == 0, (
-        "Windows hooksPath with trailing backslash must pass after normalization"
-    )
-
-
-def test_should_exit_nonzero_when_git_executable_not_found(
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    """Preflight must not crash with a traceback when git is missing from PATH."""
-    with patch("subprocess.run", side_effect=FileNotFoundError()):
-        exit_code = bugteam_preflight.verify_git_hooks_path(Path("."))
-    assert exit_code != 0, (
-        "FileNotFoundError from subprocess.run must produce a non-zero exit, "
-        "not a propagated traceback"
-    )
-    captured = capsys.readouterr()
-    assert "git" in captured.err.lower(), (
-        "Error message must mention git so the user knows what is missing"
-    )
-    assert (
-        "npx claude-dev-env" in captured.err
-        or "git config --global core.hooksPath" in captured.err
-    ), "Error message must include the enforcement-absent remediation hints"
-
-
-def test_should_exit_nonzero_when_subprocess_run_raises_os_error(
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    """Preflight must surface a clean error for other OS-level git launch failures."""
-    with patch("subprocess.run", side_effect=OSError("permission denied")):
-        exit_code = bugteam_preflight.verify_git_hooks_path(Path("."))
-    assert exit_code != 0, (
-        "OSError from subprocess.run must produce a non-zero exit, "
-        "not a propagated traceback"
-    )
-    captured = capsys.readouterr()
-    assert "bugteam_preflight" in captured.err, (
-        "Error message must be prefixed with the preflight tool name for context"
-    )
-    assert "permission denied" in captured.err, (
-        "Error message must include the underlying OSError detail for diagnosis"
-    )
-
-
-def test_has_pytest_configuration_finds_pytest_ini(tmp_path: Path) -> None:
-    """has_pytest_configuration must detect pytest.ini at the repo root.
-
-    Regression for loop1-17/loop1-18: the literals "pytest.ini",
-    "pyproject.toml", and "[tool.pytest" were inlined in production function
-    bodies; centralizing them in bugteam_scripts_constants and importing here
-    pins the contract.
-    """
-    repository_root = tmp_path / "repo"
-    repository_root.mkdir()
-    (repository_root / "pytest.ini").write_text("[pytest]\n", encoding="utf-8")
-    assert bugteam_preflight.has_pytest_configuration(repository_root) is True
-
-
-def test_has_pytest_configuration_finds_pyproject_pytest_section(
-    tmp_path: Path,
-) -> None:
-    repository_root = tmp_path / "repo"
-    repository_root.mkdir()
-    (repository_root / "pyproject.toml").write_text(
-        "[tool.pytest.ini_options]\nminversion = '6.0'\n", encoding="utf-8"
-    )
-    assert bugteam_preflight.has_pytest_configuration(repository_root) is True
-
-
-def test_has_pytest_configuration_returns_false_without_either_file(
-    tmp_path: Path,
-) -> None:
-    repository_root = tmp_path / "repo"
-    repository_root.mkdir()
-    assert bugteam_preflight.has_pytest_configuration(repository_root) is False
-
-
-def test_main_should_halt_when_env_var_lists_bugteam(
-    monkeypatch: pytest.MonkeyPatch,
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    """CLAUDE_REVIEWS_DISABLED=bugteam must halt preflight with the dedicated exit code."""
-    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
-    monkeypatch.delenv("BUGTEAM_PREFLIGHT_SKIP", raising=False)
-    exit_code = bugteam_preflight.main(["--no-pytest"])
-    assert exit_code == bugteam_preflight.EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV
-    captured = capsys.readouterr()
-    assert "CLAUDE_REVIEWS_DISABLED" in captured.err
-    assert "bugteam" in captured.err
-
-
-def test_main_should_continue_when_env_var_omits_bugteam(
-    monkeypatch: pytest.MonkeyPatch,
-    tmp_path: Path,
-) -> None:
-    """CLAUDE_REVIEWS_DISABLED without the bugteam token must not halt preflight."""
-    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "copilot,bugbot")
-    monkeypatch.delenv("BUGTEAM_PREFLIGHT_SKIP", raising=False)
-    claude_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
-    claude_hooks_path.mkdir(parents=True)
-    with patch("subprocess.run") as mock_run:
-        mock_run.return_value = _make_completed_process(
-            str(claude_hooks_path) + "\n", returncode=0
-        )
-        exit_code = bugteam_preflight.main(["--no-pytest"])
-    assert exit_code != bugteam_preflight.EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV
-
-
-def test_main_should_halt_when_env_var_contains_uppercase_or_whitespace_bugteam_token(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    """Token matching must be case-insensitive and whitespace-tolerant."""
-    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", " BugTeam , copilot ")
-    monkeypatch.delenv("BUGTEAM_PREFLIGHT_SKIP", raising=False)
-    exit_code = bugteam_preflight.main(["--no-pytest"])
-    assert exit_code == bugteam_preflight.EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV
-
-
-def _was_called_with_argument(
-    mock_subprocess_run: MagicMock, argument_token: str
-) -> bool:
-    return any(
-        argument_token in each_call_args[0][0]
-        for each_call_args in mock_subprocess_run.call_args_list
-    )
-
-
-def test_verify_git_hooks_path_invokes_self_heal_before_effective_query(
-    tmp_path: Path,
-) -> None:
-    """verify_git_hooks_path must delegate to the shared self-heal helper before --get."""
-    canonical_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
-    canonical_hooks_path.mkdir(parents=True)
-    with patch("subprocess.run") as mock_run:
-        mock_run.return_value = _make_completed_process(
-            str(canonical_hooks_path) + "\n", returncode=0
-        )
-        bugteam_preflight.verify_git_hooks_path(tmp_path)
-    assert _was_called_with_argument(mock_run, "--get-all"), (
-        "verify_git_hooks_path must run the --local --get-all read for self-heal"
-    )
-    assert _was_called_with_argument(mock_run, "--get"), (
-        "verify_git_hooks_path must still run the effective --get verification"
-    )
-    first_called_command = mock_run.call_args_list[0][0][0]
-    assert "--get-all" in first_called_command, (
-        "Self-heal must run BEFORE the effective config query, not after"
-    )
+    specification = importlib.util.spec_from_file_location(
+        "bugteam_preflight",
+        module_path,
+    )
+    assert specification is not None
+    assert specification.loader is not None
+    wrap_module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(wrap_module)
+    return wrap_module
+
+
+def test_wrap_main_delegates_to_shared_module() -> None:
+    wrap_module = _load_wrap_module()
+    assert wrap_module.main.__module__ == "preflight"
+    shared_filename = Path(wrap_module.main.__code__.co_filename).name
+    assert shared_filename == "preflight.py"
+
+
+def test_wrap_main_help_exits_cleanly() -> None:
+    wrap_module = _load_wrap_module()
+    try:
+        wrap_module.main(["--help"])
+    except SystemExit as exit_signal:
+        assert exit_signal.code in (0, None)
+        return
+    raise AssertionError("main(['--help']) must raise SystemExit")

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.
+```