claude-dev-env 1.84.0 → 1.85.0

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

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

@@ -0,0 +1,309 @@
+"""Write durable resume-handoff files for a pr-loop run.
+
+A converge loop can stop mid-run: a paused tick, a budget cutoff, a killed
+session. The next session then has no pointer to where the run was. This writer
+drops that pointer somewhere the OS temp sweep cannot purge.
+
+::
+
+    write_handoff.py --pr-number <N> --head-ref <branch> --phase tick
+        --resume-command "claude --resume /pr-converge" [--state-file <PATH>]
+    writes:  ~/.claude/runtime/pr-loop/<run-name>/handoff.json + HANDOFF.md
+    plus:    state-copy.json  (only when --state-file is given)
+
+It records the resume command, the phase reached, the steps already done, and a
+copy of the loop state, so a fresh session picks up without re-deriving it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+_self_dir = Path(__file__).resolve().parent
+if str(_self_dir) not in sys.path:
+    sys.path.insert(0, str(_self_dir))
+
+from _path_resolver import build_run_name  # noqa: E402
+from skills_pr_loop_constants.handoff_constants import (  # noqa: E402
+    ATOMIC_STAGING_SUFFIX,
+    COMPLETED_STEPS_SEPARATOR,
+    DEFAULT_NEXT_STEP_LINE,
+    ALL_HANDOFF_DIR_SEGMENTS,
+    HANDOFF_JSON_FILENAME,
+    HANDOFF_JSON_INDENT,
+    HANDOFF_MARKDOWN_FILENAME,
+    HANDOFF_MARKDOWN_TEMPLATE,
+    NO_STATE_SNAPSHOT_LINE,
+    NO_STEPS_DONE_LINE,
+    STATE_COPY_FILENAME,
+    STEP_LINE_SEPARATOR,
+)
+
+
+def _now_iso() -> str:
+    """Return the current UTC time as an ISO-format timestamp string.
+
+    Returns:
+        The stamp recorded on the handoff so a reader knows how fresh it is.
+    """
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _handoff_base_dir() -> Path:
+    """Return the durable base directory that holds every run's handoff folder.
+
+    Returns:
+        The ``~/.claude/runtime/pr-loop`` path under the user's home directory.
+    """
+    return Path.home().joinpath(*ALL_HANDOFF_DIR_SEGMENTS)
+
+
+def resolve_handoff_dir(run_name: str) -> Path:
+    """Resolve the durable handoff directory for a run name.
+
+    Args:
+        run_name: Run name token (from build_run_name).
+
+    Returns:
+        Absolute path to the run's handoff directory under the durable base.
+    """
+    return _handoff_base_dir() / run_name
+
+
+def _write_text_atomic(target_path: Path, text: str) -> None:
+    """Write text to a path atomically via a staging file and a rename.
+
+    Args:
+        target_path: Destination file path.
+        text: Full file contents to write.
+    """
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    staging_path = target_path.with_name(
+        f"{target_path.name}{ATOMIC_STAGING_SUFFIX}.{os.getpid()}"
+    )
+    staging_path.write_text(text, encoding="utf-8")
+    os.replace(staging_path, target_path)
+
+
+def _snapshot_state(handoff_dir: Path, state_file: Path | None) -> str | None:
+    """Copy a loop state file into the handoff directory when one is supplied.
+
+    Args:
+        handoff_dir: The run's durable handoff directory.
+        state_file: Loop state file to snapshot, or None to skip the copy.
+
+    Returns:
+        The forward-slash path of the copy to trust, or None when no state
+        file was supplied.
+    """
+    if state_file is None:
+        return None
+    state_copy_path = handoff_dir / STATE_COPY_FILENAME
+    _write_text_atomic(state_copy_path, state_file.read_text(encoding="utf-8"))
+    return state_copy_path.as_posix()
+
+
+def _steps_markdown_block(all_completed_steps: list[str]) -> str:
+    """Render the completed steps as a markdown bullet list.
+
+    Args:
+        all_completed_steps: Steps already finished this run.
+
+    Returns:
+        A bullet list, or a placeholder line when no steps are recorded.
+    """
+    if not all_completed_steps:
+        return NO_STEPS_DONE_LINE
+    return STEP_LINE_SEPARATOR.join(f"- {each_step}" for each_step in all_completed_steps)
+
+
+def _build_handoff_markdown(
+    *,
+    pr_number: int,
+    head_ref: str,
+    phase: str,
+    resume_command: str,
+    trusted_state_path: str | None,
+    all_completed_steps: list[str],
+    note: str | None,
+) -> str:
+    """Build the human-facing HANDOFF.md body for a fresh session.
+
+    Args:
+        pr_number: Pull request number.
+        head_ref: Head branch ref.
+        phase: The checkpoint the run reached.
+        resume_command: The exact command a fresh session runs to resume.
+        trusted_state_path: The state-copy path to trust, or None.
+        all_completed_steps: Steps already finished this run.
+        note: Free-text next-step note, or None.
+
+    Returns:
+        The rendered markdown document.
+    """
+    state_line = (
+        f"Trust this state snapshot: {trusted_state_path}"
+        if trusted_state_path is not None
+        else NO_STATE_SNAPSHOT_LINE
+    )
+    return HANDOFF_MARKDOWN_TEMPLATE.format(
+        pr_number=pr_number,
+        head_ref=head_ref,
+        phase=phase,
+        resume_command=resume_command,
+        state_line=state_line,
+        steps_block=_steps_markdown_block(all_completed_steps),
+        next_step=note if note else DEFAULT_NEXT_STEP_LINE,
+    )
+
+
+def write_handoff(
+    *,
+    pr_number: int,
+    head_ref: str,
+    phase: str,
+    resume_command: str,
+    state_file: Path | None = None,
+    run_id: str | None = None,
+    all_completed_steps: list[str] | None = None,
+    note: str | None = None,
+) -> Path:
+    """Write handoff.json, HANDOFF.md, and an optional state copy for a run.
+
+    Names the run with build_run_name and places the files under the durable
+    handoff directory. When a state file is supplied, its contents are copied to
+    state-copy.json and that copy path is recorded as the state to trust.
+
+    Args:
+        pr_number: Pull request number.
+        head_ref: Head branch ref.
+        phase: The checkpoint the run reached (e.g. 'tick', 'teardown').
+        resume_command: The exact command a fresh session runs to resume.
+        state_file: Loop state file to snapshot, or None to skip the copy.
+        run_id: Workflow run id to resume from, or None.
+        all_completed_steps: Steps already finished this run, or None.
+        note: Free-text next-step note for the fresh session, or None.
+
+    Returns:
+        Path to the run's durable handoff directory.
+    """
+    steps_done = all_completed_steps if all_completed_steps else []
+    run_name = build_run_name(pr_number, head_ref, is_multi_pr=False)
+    handoff_dir = resolve_handoff_dir(run_name)
+    handoff_dir.mkdir(parents=True, exist_ok=True)
+
+    trusted_state_path = _snapshot_state(handoff_dir, state_file)
+    payload = {
+        "pr_number": pr_number,
+        "head_ref": head_ref,
+        "phase": phase,
+        "resume_command": resume_command,
+        "run_id": run_id,
+        "state_file": trusted_state_path,
+        "completed_steps": steps_done,
+        "note": note,
+        "timestamp": _now_iso(),
+    }
+    _write_text_atomic(
+        handoff_dir / HANDOFF_JSON_FILENAME,
+        json.dumps(payload, indent=HANDOFF_JSON_INDENT) + "\n",
+    )
+    _write_text_atomic(
+        handoff_dir / HANDOFF_MARKDOWN_FILENAME,
+        _build_handoff_markdown(
+            pr_number=pr_number,
+            head_ref=head_ref,
+            phase=phase,
+            resume_command=resume_command,
+            trusted_state_path=trusted_state_path,
+            all_completed_steps=steps_done,
+            note=note,
+        ),
+    )
+    return handoff_dir
+
+
+def _split_completed_steps(raw_steps: str) -> list[str]:
+    """Split a comma-separated steps argument into a trimmed, non-empty list.
+
+    Args:
+        raw_steps: The raw --completed-steps CLI value.
+
+    Returns:
+        The individual step names with surrounding whitespace removed.
+    """
+    return [
+        each_segment.strip()
+        for each_segment in raw_steps.split(COMPLETED_STEPS_SEPARATOR)
+        if each_segment.strip()
+    ]
+
+
+def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
+    """Parse command-line arguments.
+
+    Args:
+        all_argv: Command-line argument list.
+
+    Returns:
+        Parsed namespace with the handoff fields.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--pr-number", type=int, required=True)
+    parser.add_argument("--head-ref", required=True)
+    parser.add_argument("--phase", required=True)
+    parser.add_argument("--resume-command", required=True)
+    parser.add_argument("--state-file", type=Path, default=None)
+    parser.add_argument("--run-id", default=None)
+    parser.add_argument("--completed-steps", default="")
+    parser.add_argument("--note", default=None)
+    return parser.parse_args(all_argv)
+
+
+def _write_handoff_from_arguments(arguments: argparse.Namespace) -> Path:
+    """Map parsed CLI arguments onto a write_handoff call.
+
+    Args:
+        arguments: The namespace parse_arguments produced.
+
+    Returns:
+        Path to the run's durable handoff directory.
+    """
+    return write_handoff(
+        pr_number=arguments.pr_number,
+        head_ref=arguments.head_ref,
+        phase=arguments.phase,
+        resume_command=arguments.resume_command,
+        state_file=arguments.state_file,
+        run_id=arguments.run_id,
+        all_completed_steps=_split_completed_steps(arguments.completed_steps),
+        note=arguments.note,
+    )
+
+
+def main(all_arguments: list[str]) -> int:
+    """Entry point: write the handoff files and print the durable directory.
+
+    Args:
+        all_arguments: Command-line arguments.
+
+    Returns:
+        0 on success, 1 on a state-file read or write failure.
+    """
+    arguments = parse_arguments(all_arguments)
+    try:
+        handoff_dir = _write_handoff_from_arguments(arguments)
+    except (OSError, UnicodeDecodeError) as read_or_write_error:
+        print(f"write_handoff failed: {read_or_write_error}", file=sys.stderr)
+        return 1
+    print(handoff_dir.as_posix())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))