---
name: handoff
description:
  "Create a self-contained continuity artifact for an ending session, milestone transfer, staff
  review, or post-merge continuation. Reconcile live repository and tracker state, record completion
  evidence, dependencies, blockers, ownership, and the next actionable step, then write the handoff
  under .scratchpad/backlog/handoffs/. Optionally export the exact agent session with CASS and copy
  the handoff to the clipboard when available."
argument-hint: "[milestone <name> | review | continuation] [--harness <h>] [--session-id <id>]"
disable-model-invocation: true
---

# Handoff

Write a handoff that lets the next agent continue without reconstructing the session. Treat the
handoff as an ephemeral control-plane snapshot, not implementation truth; current code, git state,
trackers, and live services win when they disagree.

## Route the request

Each variant has its own template and output path. Read only the one you routed to.

| Request                 | Variant      | Template                                             | Path                                                        |
| ----------------------- | ------------ | ---------------------------------------------------- | ----------------------------------------------------------- |
| default, ending session | Session      | [session](references/templates/session.md)           | `.scratchpad/backlog/handoffs/session-<STAMP>.md`           |
| `milestone <name>`      | Milestone    | [milestone](references/templates/milestone.md)       | `.scratchpad/backlog/handoffs/milestones/<slug>-<STAMP>.md` |
| `review`                | Review       | [review](references/templates/review.md)             | `.scratchpad/backlog/handoffs/review-<STAMP>.md`            |
| `continuation`          | Continuation | [continuation](references/templates/continuation.md) | `.scratchpad/backlog/handoffs/continuation-<STAMP>.md`      |

Accept an explicit harness, session ID, or working directory when supplied. Do not guess between
multiple plausible sessions.

## Build the evidence snapshot

Gather only evidence relevant to the transfer:

```bash
git status --short --branch
git log --oneline --decorate -10
git diff --stat
git diff --cached --stat
git worktree list
```

Then:

1. Read the user request and the active issue or milestone first.
2. Read `.scratchpad/README.md` and only the linked active documents relevant to this work.
3. Reconcile claims against code, tests, git, and relevant live-service state. Record conflicting
   evidence rather than choosing the more convenient source.
4. Record uncommitted, staged, and untracked files explicitly. Never imply they are committed.
5. Verify remote PR, CI, deploy, or provider state only when it affects the handoff.

Preserve the repository's existing Scratchpad frontmatter. Newly materialized backlog files may use
`status`, `updated`, `milestone`, and `depends_on`; keep dependency reasons, transient blockers, and
per-session ownership in the handoff body. Do not invent claim or lease fields. If ownership is
unknown, write `not recorded`.

## Use precise state language

Apply these states to each completion criterion:

- `done`: verified against current evidence.
- `partial`: some required behavior or evidence remains.
- `not started`: no implementation evidence exists.
- `blocked`: progress cannot continue until a named dependency or external condition changes.

Do not call ordinary remaining work a blocker. For every real blocker, name its evidence, owner if
known, and exact unblock condition. Separate dependencies from blockers: a satisfied dependency is
still useful context but does not prevent progress.

## Export the session when useful

The handoff summary must stand alone. Use a transcript export as a safety net for decisions or
details that do not fit the summary.

1. Prefer an exact known session path or ID.
2. In Codex, use `CODEX_THREAD_ID` when present and match that ID under `~/.codex/sessions`; rollout
   filenames contain the thread ID:

   ```bash
   if [[ -n "${CODEX_THREAD_ID:-}" ]]; then
     fd -HI "$CODEX_THREAD_ID" "$HOME/.codex/sessions" -t f
   fi
   ```

3. Otherwise discover a bounded candidate set without indexing:

   ```bash
   cass sessions --workspace "$PWD" --json --limit 5
   ```

4. If several active sessions share a workspace, compare IDs and timestamps; do not select the
   newest blindly.
5. Export the exact JSONL directly:

   ```bash
   mkdir -p .scratchpad/backlog/handoffs/exports
   cass export "$SESSION_JSONL" --format markdown \
     -o ".scratchpad/backlog/handoffs/exports/${HARNESS}-${SESSION_ID}.md"
   ```

`cass export` reads JSONL directly and includes pre-compaction ancestors by default. Do not run
`cass index` merely to create a handoff. An export of a still-running session is a point-in-time
snapshot; say so.

## Write and deliver the artifact

Use a collision-resistant timestamp and write to the routed path:

```bash
STAMP=$(date +%Y-%m-%d-%H%M%S)
mkdir -p .scratchpad/backlog/handoffs/milestones
```

Do not stage or commit `.scratchpad` by default. After writing and rereading the file, copy it only
when clipboard support exists:

```bash
pbcopy < "$HANDOFF_FILE"
```

Report the handoff path, transcript-export path if any, clipboard outcome, and any evidence that
could not be verified.

## Quality gate

The template carries the structure. Before delivery, check the things it cannot enforce:

- No secrets, and no stale Scratchpad claim presented as current truth.
- No unrun check reported as passed.
- The handoff remains useful without opening the transcript export.