claude-dev-env 1.84.0 → 1.86.0

package/hooks/session/task_list_loop_starter.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""SessionStart hook — start a task-list maintenance loop for the session.
+
+At session start this hook emits an ``additionalContext`` directive asking Claude
+to keep the session's task list current on a 10-minute cadence, starting the
+``/loop`` skill when one is not already running. The hook writes nothing and runs
+no tools itself. Claude reads the directive and invokes the ``/loop`` skill.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.task_list_loop_starter_constants import (  # noqa: E402
+    TASK_LIST_LOOP_DIRECTIVE,
+)
+
+
+def build_session_directive() -> str:
+    """Return the task-list loop directive emitted at session start."""
+    return TASK_LIST_LOOP_DIRECTIVE
+
+
+def main() -> None:
+    """Emit the task-list loop directive as SessionStart additionalContext."""
+    print(json.dumps({"additionalContext": build_session_directive()}))
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/test_session_edit_tracker_cleanup.py

@@ -0,0 +1,157 @@
+"""Behavior tests for the session_edit_tracker_cleanup hook.
+
+The cleanup deletes only the running session's own session-edit file, and only
+on a fresh startup (SessionStart with a ``startup`` source) or a session end. A
+SessionStart that continues the same conversation — a compact or a resume —
+keeps the in-flight tracker. A peer session's file is always left alone,
+regardless of its age. These tests redirect ``tempfile.gettempdir`` to a
+temporary directory, seed it with the current session's file and peer-session
+files, run the hook's ``main`` through a lifecycle payload, and confirm which
+files survive.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+import io
+import json
+import os
+import pathlib
+import sys
+import tempfile
+import time
+from unittest import mock
+
+import pytest
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+_HOOKS_TREE = _HOOK_DIR.parent
+for each_path in (str(_HOOK_DIR), str(_HOOKS_TREE)):
+    if each_path not in sys.path:
+        sys.path.insert(0, each_path)
+
+hook_spec = importlib.util.spec_from_file_location(
+    "session_edit_tracker_cleanup",
+    _HOOK_DIR / "session_edit_tracker_cleanup.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+
+from hooks_constants.session_edit_stage_gate_constants import (  # noqa: E402
+    ALL_EDITED_FILE_PATHS_KEY,
+    SESSION_EDIT_FILE_PREFIX,
+    SESSION_EDIT_FILE_SUFFIX,
+    STATE_FILE_DEFAULT_SESSION_ID,
+)
+
+AGED_TRACKER_FILE_SECONDS = 1860
+
+
+def _run_main_with_stdin(input_text: str) -> None:
+    with (
+        mock.patch("sys.stdin", io.StringIO(input_text)),
+        mock.patch("sys.stdout", new_callable=io.StringIO),
+        contextlib.suppress(SystemExit),
+    ):
+        hook_module.main()
+
+
+@pytest.fixture()
+def redirected_temp_directory(
+    tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
+) -> pathlib.Path:
+    monkeypatch.setattr(tempfile, "gettempdir", lambda: str(tmp_path))
+    return tmp_path
+
+
+def _seed_edit_file(temp_directory: pathlib.Path, session_id: str) -> pathlib.Path:
+    edit_file = temp_directory / f"{SESSION_EDIT_FILE_PREFIX}{session_id}{SESSION_EDIT_FILE_SUFFIX}"
+    edit_file.write_text(json.dumps({ALL_EDITED_FILE_PATHS_KEY: []}), encoding="utf-8")
+    return edit_file
+
+
+def _age_file(target_file: pathlib.Path, age_seconds: float) -> None:
+    old_time = time.time() - age_seconds
+    os.utime(target_file, (old_time, old_time))
+
+
+def _session_start_payload(session_id: str) -> str:
+    return json.dumps({"session_id": session_id, "source": "startup"})
+
+
+def _session_continuation_payload(session_id: str, source: str) -> str:
+    return json.dumps({"session_id": session_id, "source": source})
+
+
+def _session_end_payload(session_id: str) -> str:
+    return json.dumps({"session_id": session_id, "hook_event_name": "SessionEnd"})
+
+
+def test_main_keeps_other_session_stale_tracker(
+    redirected_temp_directory: pathlib.Path,
+) -> None:
+    other_session_file = _seed_edit_file(redirected_temp_directory, "idle-live-session")
+    _age_file(other_session_file, AGED_TRACKER_FILE_SECONDS)
+    _run_main_with_stdin(_session_start_payload("currentsession"))
+    assert other_session_file.exists()
+
+
+def test_should_keep_fresh_edit_file(redirected_temp_directory: pathlib.Path) -> None:
+    fresh_file = _seed_edit_file(redirected_temp_directory, "other-live-session")
+    _run_main_with_stdin(_session_start_payload("currentsession"))
+    assert fresh_file.exists()
+
+
+def test_should_remove_current_session_edit_file(
+    redirected_temp_directory: pathlib.Path,
+) -> None:
+    current_file = _seed_edit_file(redirected_temp_directory, "currentsession")
+    _run_main_with_stdin(_session_start_payload("currentsession"))
+    assert not current_file.exists()
+
+
+def test_main_removes_current_session_stale_tracker(
+    redirected_temp_directory: pathlib.Path,
+) -> None:
+    current_file = _seed_edit_file(redirected_temp_directory, "currentsession")
+    _age_file(current_file, AGED_TRACKER_FILE_SECONDS)
+    _run_main_with_stdin(_session_start_payload("currentsession"))
+    assert not current_file.exists()
+
+
+@pytest.mark.parametrize("continuation_source", ["compact", "resume"])
+def test_should_keep_current_session_tracker_on_continuation(
+    redirected_temp_directory: pathlib.Path, continuation_source: str
+) -> None:
+    current_file = _seed_edit_file(redirected_temp_directory, "currentsession")
+    _run_main_with_stdin(
+        _session_continuation_payload("currentsession", continuation_source)
+    )
+    assert current_file.exists()
+
+
+def test_should_remove_current_session_tracker_on_session_end(
+    redirected_temp_directory: pathlib.Path,
+) -> None:
+    current_file = _seed_edit_file(redirected_temp_directory, "currentsession")
+    _run_main_with_stdin(_session_end_payload("currentsession"))
+    assert not current_file.exists()
+
+
+def test_should_exit_zero_on_malformed_stdin(
+    redirected_temp_directory: pathlib.Path,
+) -> None:
+    fresh_file = _seed_edit_file(redirected_temp_directory, "other-live-session")
+    _run_main_with_stdin("not valid json {{{")
+    assert fresh_file.exists()
+
+
+def test_malformed_stdin_keeps_default_session_tracker(
+    redirected_temp_directory: pathlib.Path,
+) -> None:
+    default_file = _seed_edit_file(redirected_temp_directory, STATE_FILE_DEFAULT_SESSION_ID)
+    _run_main_with_stdin("not valid json {{{")
+    assert default_file.exists()

package/hooks/session/test_task_list_loop_starter.py

@@ -0,0 +1,53 @@
+"""Tests for task_list_loop_starter — SessionStart hook that starts a task-list loop."""
+
+import json
+import sys
+from io import StringIO
+from pathlib import Path
+from unittest.mock import patch
+
+_SESSION_DIR = Path(__file__).resolve().parent
+_HOOKS_ROOT = _SESSION_DIR.parent
+for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
+    if each_sys_path_entry not in sys.path:
+        sys.path.insert(0, each_sys_path_entry)
+
+import task_list_loop_starter as starter
+
+from hooks_constants.task_list_loop_starter_constants import (
+    TASK_LIST_LOOP_DIRECTIVE,
+    TASK_LIST_MAINTENANCE_INSTRUCTION,
+)
+
+
+def _run_main() -> str:
+    """Return stdout produced by running the hook's main()."""
+    captured_stdout = StringIO()
+    with patch("sys.stdout", captured_stdout):
+        starter.main()
+    return captured_stdout.getvalue()
+
+
+class TestSessionDirective:
+    def test_main_emits_additional_context(self) -> None:
+        emitted = json.loads(_run_main())
+        assert "additionalContext" in emitted
+
+    def test_directive_carries_the_one_line_instruction(self) -> None:
+        emitted = json.loads(_run_main())
+        assert TASK_LIST_MAINTENANCE_INSTRUCTION in emitted["additionalContext"]
+
+    def test_directive_names_the_ten_minute_cadence(self) -> None:
+        emitted = json.loads(_run_main())
+        assert "10-minute" in emitted["additionalContext"]
+
+    def test_directive_names_the_loop_command(self) -> None:
+        emitted = json.loads(_run_main())
+        assert "/loop 10m" in emitted["additionalContext"]
+
+    def test_directive_is_idempotent_about_an_existing_loop(self) -> None:
+        emitted = json.loads(_run_main())
+        assert "not already running" in emitted["additionalContext"]
+
+    def test_build_session_directive_returns_the_shared_constant(self) -> None:
+        assert starter.build_session_directive() == TASK_LIST_LOOP_DIRECTIVE

package/package.json

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

package/rules/CLAUDE.md

@@ -36,6 +36,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `plain-illustrative-docstrings.md` | Public docstring narrative reads plainly and shows behavior with a diagram block (a `::` example or a doctest), painting a concrete scene a general developer follows on first read; a run-on backstop hook, a prose-wall backstop hook, and Category O9 audit enforce it |
 | `plain-language.md` | Everyday words, short active sentences, lead with the answer |
 | `prompt-workflow-context-controls.md` | Keep prompt-workflow instruction layers small and stable; load heavy skills on demand |
+| `re-stage-before-commit.md` | Stage the files edited this session before `git commit`; the session edit stage gate denies a commit that leaves a tracked session edit unstaged, with `-a`, a pathspec, a preceding `git add`, and `# partial-commit` as escapes |
 | `research-mode.md` | Three anti-hallucination constraints: say "I don't know", verify with citations, quote for factual grounding |
 | `right-sized-engineering.md` | Simple over clever; functions over classes; concrete over abstract |
 | `self-contained-docs.md` | Every document is fully self-contained; no references to the conversation that produced it |

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

@@ -30,7 +30,7 @@ Read the body and the docstring side by side:
 - **Returns-clause cardinality.** A `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) matches the count of keys in that family in the returned dict literal. When the dict holds one key in the family (`sheen_mid`), the noun is singular (`the sheen stop`); a plural noun there claims two or more entries the dict does not hold. The `check_docstring_returns_plural_cardinality` gate blocks the single-key-with-plural-noun form of this drift at Write/Edit time.
 - **Length-constant superlative vs exact gate.** A module docstring that describes an integer `*_LENGTH` constant with a superlative or range word (`the longest color string the swatch accepts`, `no longer than`) matches how the code consumes the constant. When the only consumer compares `len(...)` against the constant with `==`/`!=` — an exact-length gate where every other length is rejected, not accepted at a shorter length — the superlative prose claims a range of accepted lengths the code never allows. State the exact required length (`the exact #AARRGGBB length`), not a longest/range form. The `check_docstring_length_constant_superlative_vs_exact_gate` gate blocks this drift at Write/Edit time, scanning the constant module's package tree so it sees a consumer that lives in a sibling module; a constant genuinely used as a ceiling (`len(x) <= LIMIT`) is left alone.
 - **Args single-line scope vs span body.** An `Args:` entry that scopes a finding to one named line (`a finding blocks only when its block-anchor line is among the changed lines`) matches the line breadth the body scopes by. When the body builds a `range(...)` span over the finding's source lines and scopes it through a span-intersection scoper that blocks when any line of the span is among the changed lines, the single-line Args wording understates the scope: an edit touching a non-anchor line of the span still blocks. State the Args entry on the same span breadth the body uses (`a finding blocks when any line of its block span is among the changed lines`). The `check_docstring_args_single_line_scope_vs_span` gate blocks the single-line-Args-over-span-body form of this drift at Write/Edit time.
-- **Cardinal-count enumerations.** A docstring that states a count of an outcome family (`the four outcome branches`) and lists those members names every member of that family the module references. When the module imports and exercises a fifth `OUTCOME_*` constant the summary leaves out, the count and the list both under-describe the code. The `check_docstring_cardinal_count_matches_constant_family` gate blocks this drift — a cardinal-count docstring that names two or more members of a referenced `UPPER_SNAKE` constant family, leaves at least one referenced member out, and states a count below the family size — at Write/Edit time, on test modules as well as production modules.
+- **Cardinal-count enumerations.** A docstring that states a count of an outcome family (`the four outcome branches`) and lists those members names every member of that family the module references. When the module imports and exercises a fifth `OUTCOME_*` constant the summary leaves out, the count and the list both under-describe the code. The `check_docstring_cardinal_count_matches_constant_family` gate blocks this drift — a cardinal-count docstring that names two or more members of a referenced `UPPER_SNAKE` constant family, leaves at least one referenced member out, and states a count that differs from the family size (a count above it and one below it both trip) — at Write/Edit time, on test modules as well as production modules.
 - **Raises-clause reachability for `LargeZipFile`.** A `Raises:` clause that names `zipfile.LargeZipFile` matches a writer the body opens with ZIP64 forbidden. `zipfile` raises `LargeZipFile` only when an entry needs ZIP64 and `allowZip64` is False; a function that opens its `zipfile.ZipFile` writer in a write mode (`w`/`a`/`x`) with `allowZip64` at its default of True allows ZIP64 and never raises it, so the clause documents an unreachable exception. Drop the entry, or pass `allowZip64=False` when forbidding ZIP64 is the goal. The `check_docstring_raises_unraisable_largezipfile` gate blocks the default-ZIP64-writer form of this drift at Write/Edit time; a writer that forbids ZIP64 on any open, a read-only open, and a function that opens no writer are all left alone.
 - **Module summary scope versus data-schema constants.** A module whose one-line docstring scopes its contents to user-facing text (`User-facing strings: CLI flag names, help text, and log messages`) names every category of constant the body holds. When the body also defines serialization field keys (`JSONL_FIELD_*`), run-metadata schema keys (`RUN_METADATA_CLI_ARG_KEY_*`), or runtime config (`STDOUT_ENCODING`, `MAIN_LOGGING_FORMAT_STRING`), the strings-only summary under-describes the module — the module-responsibility drift the repo flags. Broaden the summary to name the data-schema keys and runtime config. The `check_module_docstring_scope_omits_data_schema_constants` gate blocks this drift at Write/Edit time, and fires only when the summary claims a user-facing-text scope and names no data-schema or runtime-config category, so a summary that already names `field keys`, `schema`, or `runtime config` passes.
 - **Field meaning: run mode versus per record.** A dataclass or `TypedDict` field documented in the class `Attributes:` block states what the field means for one record. When the code sets that field the same way for every record (a run-mode flag such as `is_dry_run = not is_execute` at each write site), the description states the run-mode meaning, not a per-record outcome. A field named `is_dry_run` documented as `True when no STP was written` reads as a per-record write result, but the value tracks the run mode, so a record that writes no file during an execute run still stores `False`. State the run-mode meaning the assignment gives the field. The `check_docstring_field_runmode_outcome` gate blocks the single-file shape of this drift at Write/Edit time — an `Attributes:` entry for a run-mode flag field (a name carrying `dry_run`) whose description carries a per-record write-outcome phrase and no run-mode phrase. The assignment that sets the field sits in another module, out of reach of that single-file gate, so any shape the gate cannot key on stays an O6 audit-lane judgment finding.

package/rules/env-var-table-code-drift.md

@@ -22,7 +22,7 @@ The `env_var_table_code_drift_blocker.py` hook runs on every Write, Edit, and Mu
 3. Resolves the named code file under the repository root (the nearest `.git`-bearing ancestor of the markdown file) and reads its source.
 4. Blocks the write when the file resolves yet its source never references the variable name. For an Edit, drift the file already held on an untouched row is excluded, so only drift the edit introduces is reported.
 
-The check stays quiet for a row whose code file resolves nowhere under the repository root (it cannot prove the drift), a row whose second cell holds no code-file path, a table row inside a fenced code block, and any test file.
+The check stays quiet for a row whose code file resolves nowhere under the repository root (it cannot prove the drift), a row whose second cell holds no code-file path, and a table row inside a fenced code block.
 
 ## Why this is a hook, not a lint pass
 

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

@@ -10,7 +10,7 @@ paths:
 
 # New Production File Absent From Its Package Inventory
 
-**When this applies:** Any Write that creates a new production code file (`.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`) in a directory whose sibling `README.md` or `CLAUDE.md` already names two or more of the directory's files in backticks, or in a skill's `scripts/` subdirectory whose parent `SKILL.md` Layout table already names two or more of those scripts.
+**When this applies:** Any Write that creates a new production code file (`.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`) in a directory whose sibling `README.md` or `CLAUDE.md` already names two or more of the directory's files in backticks, in a directory whose own `SKILL.md` names two or more of the directory's files, or in a skill's `scripts/` subdirectory whose parent `SKILL.md` Layout table already names two or more of those scripts.
 
 ## Rule
 

package/rules/paired-test-coverage.md

@@ -23,7 +23,7 @@ Two complementary checks in `code_rules_paired_test.py` (both dispatched from `c
 `check_public_function_missing_paired_test` runs on a production Python write or edit and flags a public function when all of these hold:
 
 1. The target is production code — not a test module, hook infrastructure, config module, migration, workflow registry, or `__init__.py`.
-2. A stem-matched test file (`test_<stem>.py` or `<stem>_test.py`) exists for the module.
+2. A stem-matched test file exists for the module — `test_<stem>.py` or `<stem>_test.py` beside the module, or `test_<stem>.py` under an ancestor `tests/` directory.
 3. That suite already exercises the module — referencing at least one public function the module defines, or referencing one of its private (underscore-prefixed) helper functions by name — the signature of a maintained per-module suite rather than a placeholder or unrelated test file.
 4. The public function is referenced by no test file in the directory that holds the stem-matched test.
 

package/rules/re-stage-before-commit.md

@@ -0,0 +1,31 @@
+# Re-Stage Session Edits Before Commit
+
+**When this applies:** Any `git commit` run through the Bash tool in a git repository.
+
+## Rule
+
+Stage the files you edited this session right before you commit them. A file this session changed but left unstaged is dropped by a plain `git commit` — the commit records the staged snapshot and the edit stays behind in the working tree.
+
+The `session_edit_stage_gate` hook holds you to this. It reads the per-session tracker that records every file the session edited, checks which of those files are tracked yet still unstaged at commit time, and denies the commit when any are left out. The denial names each file and gives the exact fix: `git add <paths>`, `git commit -a`, or a `# partial-commit` marker.
+
+## What the gate allows
+
+The gate steps aside for a commit that skips staged files on purpose:
+
+- **`-a` / `--all`** — the commit already takes every tracked change, so nothing is dropped.
+- **A pathspec** — `git commit -- <paths>` or `git commit <paths>` commits only the named paths on purpose.
+- **A preceding `git add` / `git stage`** — `git add <paths> && git commit …` stages the files in its own segment before the commit runs, so they are staged by the time the commit records the index.
+- **`# partial-commit`** — add this marker to the command to commit the staged set on purpose and leave the rest.
+
+A `--amend` does not step the gate aside: an amend records the staged snapshot too, so an unstaged session edit is dropped the same way a plain commit drops it.
+
+A missing tracker file or any git failure allows the commit, so the gate never blocks on a tooling problem.
+
+## Companion hooks
+
+- `session_file_edit_tracker` (PostToolUse) records the resolved absolute path of each Write, Edit, and MultiEdit into the per-session tracker file.
+- `session_edit_tracker_cleanup` (SessionStart, SessionEnd) deletes the running session's own tracker file: at a fresh SessionStart so a new session begins with an empty record, and at SessionEnd so a clean exit leaves nothing behind. A tracker is read only by the session that wrote it, so a file a crashed session leaves behind is inert and no peer session touches it.
+
+## Why
+
+A stale git index is a quiet failure: the commit succeeds, the branch looks right, and one file you meant to include never lands. Catching it at commit time keeps the staged set and the session's edits in step.

package/skills/_shared/pr-loop/CLAUDE.md

@@ -21,6 +21,7 @@ Shared infrastructure for the PR audit-fix loop used by `bugteam` and `pr-conver
 | `packages/claude-dev-env/skills/_shared/pr-loop/scripts/write_fix_outcomes.py` | Writes the per-loop fix outcome XML into the workspace. |
 | `packages/claude-dev-env/skills/_shared/pr-loop/scripts/preflight_worktree.py` | Verifies the working directory is a healthy worktree for the target PR's repo. |
 | `packages/claude-dev-env/skills/_shared/pr-loop/scripts/teardown_worktrees.py` | Removes loop worktrees on clean exit. |
+| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/write_handoff.py` | Writes durable resume-handoff files under `~/.claude/runtime/pr-loop/<run-name>/` at each converge checkpoint. |
 | `packages/claude-dev-env/skills/_shared/pr-loop/scripts/_path_resolver.py` | Resolves workspace and worktree paths from PR metadata. |
 | `packages/claude-dev-env/skills/_shared/pr-loop/scripts/_cli_utils.py` | Shared CLI argument parsing helpers. |
 | `packages/claude-dev-env/skills/_shared/pr-loop/scripts/_xml_utils.py` | XML serialization helpers. |

package/skills/_shared/pr-loop/scripts/CLAUDE.md

@@ -13,6 +13,7 @@ Python scripts that run the PR audit-fix loop at runtime. Both `bugteam` and `pr
 | `write_fix_outcomes.py` | Writes per-loop fix outcome XML into the workspace. |
 | `preflight_worktree.py` | Verifies the working directory is a healthy git worktree for the target PR's repo. Supports `--mode strict` to abort when the repo does not match. |
 | `teardown_worktrees.py` | Removes per-PR worktrees after a clean loop exit. |
+| `write_handoff.py` | Writes durable resume-handoff files under the run's `~/.claude/runtime/pr-loop` directory at each converge checkpoint. |
 | `_path_resolver.py` | Resolves workspace and worktree paths from PR owner, repo, and number. |
 | `_cli_utils.py` | Shared CLI argument parsing helpers (argparse wrappers). |
 | `_xml_utils.py` | XML serialization helpers for outcome files. |

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/CLAUDE.md

@@ -9,6 +9,7 @@ Python package of named constants for the `pr-loop` shared scripts. All constant
 | `__init__.py` | Package marker. |
 | `path_resolver_constants.py` | Path template strings and format constants: workspace directory naming, worktree directory name, diff patch filename pattern, outcome XML filename patterns, fix status values, audit constraint texts, audit category entries, fix execution steps, and fix constraint texts. |
 | `preflight_constants.py` | Constants used by `preflight_worktree.py` for exit codes and output marker strings. |
+| `handoff_constants.py` | Filename, path-segment, and template constants for the durable handoff writer. |
 
 ## Usage
 

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/handoff_constants.py

@@ -0,0 +1,45 @@
+"""Filename, path-segment, and template constants for the durable handoff writer.
+
+Consumed by `write_handoff.py`, which writes each pr-loop run's resume-handoff
+files under `~/.claude/runtime/pr-loop/<run-name>/`.
+"""
+
+ALL_HANDOFF_DIR_SEGMENTS = (".claude", "runtime", "pr-loop")
+HANDOFF_JSON_FILENAME = "handoff.json"
+HANDOFF_MARKDOWN_FILENAME = "HANDOFF.md"
+STATE_COPY_FILENAME = "state-copy.json"
+ATOMIC_STAGING_SUFFIX = ".tmp"
+HANDOFF_JSON_INDENT = 2
+COMPLETED_STEPS_SEPARATOR = ","
+STEP_LINE_SEPARATOR = "\n"
+
+NO_STATE_SNAPSHOT_LINE = (
+    "No state snapshot was captured. Rebuild loop state from the PR before resuming."
+)
+DEFAULT_NEXT_STEP_LINE = "Continue from the resume command above."
+NO_STEPS_DONE_LINE = "- (none recorded yet)"
+
+HANDOFF_MARKDOWN_TEMPLATE = """# Resume handoff — PR {pr_number} ({head_ref})
+
+Goal: drive PR {pr_number} to convergence. This run stopped at phase `{phase}`.
+
+## Resume command
+
+Run this exactly:
+
+```
+{resume_command}
+```
+
+## State file to trust
+
+{state_line}
+
+## Steps already done
+
+{steps_block}
+
+## Next step
+
+{next_step}
+"""

package/skills/_shared/pr-loop/scripts/test_write_handoff.py

@@ -0,0 +1,201 @@
+"""Tests for write_handoff: the durable per-run handoff writer."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+
+def _load_write_handoff_module() -> ModuleType:
+    module_path = _SCRIPTS_DIR / "write_handoff.py"
+    spec = importlib.util.spec_from_file_location("write_handoff", 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
+
+
+write_handoff = _load_write_handoff_module()
+
+
+_FROZEN_TIMESTAMP = "2026-07-03T12:00:00+00:00"
+
+
+def _point_base_dir_at(monkeypatch: pytest.MonkeyPatch, base: Path) -> None:
+    monkeypatch.setattr(write_handoff, "_handoff_base_dir", lambda: base)
+    monkeypatch.setattr(write_handoff, "_now_iso", lambda: _FROZEN_TIMESTAMP)
+
+
+def test_resolve_handoff_dir_joins_run_name_under_base(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """resolve_handoff_dir places the run's directory under the durable base."""
+    _point_base_dir_at(monkeypatch, tmp_path)
+    resolved = write_handoff.resolve_handoff_dir("bugteam-pr-4")
+    assert resolved == tmp_path / "bugteam-pr-4"
+
+
+def test_handoff_base_dir_lives_under_home_runtime_pr_loop(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The durable base sits under the user home, not the OS temp directory."""
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+    monkeypatch.setenv("HOME", str(tmp_path))
+    base = write_handoff._handoff_base_dir()
+    assert base == tmp_path / ".claude" / "runtime" / "pr-loop"
+
+
+def test_write_handoff_records_resume_command_and_phase(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """write_handoff writes handoff.json and HANDOFF.md carrying the resume
+    command, phase, run id, completed steps, and a timestamp."""
+    _point_base_dir_at(monkeypatch, tmp_path)
+    handoff_dir = write_handoff.write_handoff(
+        pr_number=4,
+        head_ref="feat/pr-loop-durable-handoff",
+        phase="tick",
+        resume_command="claude --resume /pr-converge",
+        run_id="wf_abc123",
+        all_completed_steps=["preflight", "audit"],
+        note="Copilot wait-gate still open.",
+    )
+    assert handoff_dir == tmp_path / "bugteam-pr-4"
+
+    payload = json.loads((handoff_dir / "handoff.json").read_text(encoding="utf-8"))
+    assert payload["resume_command"] == "claude --resume /pr-converge"
+    assert payload["phase"] == "tick"
+    assert payload["run_id"] == "wf_abc123"
+    assert payload["completed_steps"] == ["preflight", "audit"]
+    assert payload["timestamp"] == _FROZEN_TIMESTAMP
+
+    markdown = (handoff_dir / "HANDOFF.md").read_text(encoding="utf-8")
+    assert "claude --resume /pr-converge" in markdown
+    assert "preflight" in markdown
+    assert "Copilot wait-gate still open." in markdown
+
+
+def test_write_handoff_copies_state_file_when_given(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A supplied --state-file is copied to state-copy.json and the copy path is
+    recorded in handoff.json."""
+    _point_base_dir_at(monkeypatch, tmp_path)
+    source_state = tmp_path / "loop-state.json"
+    source_state.write_text('{"loop_count": 3}', encoding="utf-8")
+
+    handoff_dir = write_handoff.write_handoff(
+        pr_number=4,
+        head_ref="feat/branch",
+        phase="teardown",
+        resume_command="claude --resume /autoconverge",
+        state_file=source_state,
+    )
+
+    state_copy = handoff_dir / "state-copy.json"
+    assert json.loads(state_copy.read_text(encoding="utf-8")) == {"loop_count": 3}
+    payload = json.loads((handoff_dir / "handoff.json").read_text(encoding="utf-8"))
+    assert payload["state_file"] == state_copy.as_posix()
+
+
+def test_write_handoff_omits_state_copy_when_absent(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """With no --state-file, no state-copy.json is written and state_file is null."""
+    _point_base_dir_at(monkeypatch, tmp_path)
+    handoff_dir = write_handoff.write_handoff(
+        pr_number=4,
+        head_ref="feat/branch",
+        phase="tick",
+        resume_command="claude --resume /pr-converge",
+    )
+    assert not (handoff_dir / "state-copy.json").exists()
+    payload = json.loads((handoff_dir / "handoff.json").read_text(encoding="utf-8"))
+    assert payload["state_file"] is None
+
+
+def test_parse_arguments_reads_completed_steps_value() -> None:
+    """The CLI captures the raw comma-separated --completed-steps value."""
+    arguments = write_handoff.parse_arguments(
+        [
+            "--pr-number",
+            "4",
+            "--head-ref",
+            "feat/branch",
+            "--phase",
+            "tick",
+            "--resume-command",
+            "claude --resume /pr-converge",
+            "--completed-steps",
+            "preflight,audit,fix",
+        ]
+    )
+    assert arguments.completed_steps == "preflight,audit,fix"
+
+
+def test_main_writes_handoff_and_prints_dir(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """main writes the handoff files and prints the durable directory path."""
+    _point_base_dir_at(monkeypatch, tmp_path)
+    exit_code = write_handoff.main(
+        [
+            "--pr-number",
+            "4",
+            "--head-ref",
+            "feat/branch",
+            "--phase",
+            "tick",
+            "--resume-command",
+            "claude --resume /pr-converge",
+            "--completed-steps",
+            "preflight,audit",
+        ]
+    )
+    assert exit_code == 0
+    printed = capsys.readouterr().out.strip()
+    assert "\\" not in printed
+    assert printed.endswith("bugteam-pr-4")
+    payload = json.loads(
+        (tmp_path / "bugteam-pr-4" / "handoff.json").read_text(encoding="utf-8")
+    )
+    assert payload["completed_steps"] == ["preflight", "audit"]
+
+
+def test_main_returns_one_on_non_utf8_state_file(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """main exits 1 rather than crashing when --state-file holds non-UTF-8 bytes."""
+    _point_base_dir_at(monkeypatch, tmp_path)
+    bad_state = tmp_path / "loop-state.json"
+    bad_state.write_bytes(b"\xff\xfe not valid utf-8")
+    exit_code = write_handoff.main(
+        [
+            "--pr-number",
+            "4",
+            "--head-ref",
+            "feat/branch",
+            "--phase",
+            "teardown",
+            "--resume-command",
+            "claude --resume /autoconverge",
+            "--state-file",
+            str(bad_state),
+        ]
+    )
+    assert exit_code == 1
+    assert "write_handoff failed" in capsys.readouterr().err