rota-pause — Graceful Session Pause

/rota-work with no argument reads the handoff note next session; it goes away when the stream is resumed or abandoned (rota status rm deletes it).

When NOT to Use

• Work complete → /rota-ship
• You can finish in this session
• No active branch, no /rota-work running and no round
• Round finished → rota round wind-down

Copy this checklist and track your progress:

- [ ] Step 1 — Is a Round Running?
- [ ] Step 2 — Resolve the Pause Set
- [ ] Step 3 — Handle Uncommitted Work
- [ ] Step 4 — Write the Handoff Note
- [ ] Step 5 — Pin Status
- [ ] Step 6 — Confirm

Step 1 — Is a Round Running?

Run rota round status --json. A round is in flight when a row in data.slots holds an issue or data.review is non-empty; slots parked on park/<agent> with nothing queued are not a round. If in flight, read `orchestrator-pause.md` and follow it; Steps 2-5 do not apply (the orchestrator sits on the base branch). Otherwise continue with Step 2.

Step 2 — Resolve the Pause Set

The pause set is the (branch, repo) entries to pause: one for a single-repo cycle or scoped umbrella pause, several when a /rota-work wave fanned out across sub-repos.

1. rota status show: take the active streams whose branch matches the current branch. One match is the pause set (repo may be null).
2. Several matches (a /rota-work wave across sub-repos): read `umbrella-wave.md`, Step 2.
3. No match: use git rev-parse --abbrev-ref HEAD and pause [(branch, null)], for /rota-pause before /rota-work registered status.
4. rota git guard feature-branch <branch> exiting 1 means the base branch: tell the user there is no feature work to pause and stop.

Step 3 — Handle Uncommitted Work

Check each entry's tree with git -C <path> status --porcelain (path from rota repo resolve <repo> --json, data.repos[0].path; cwd when repo is null).

All clean: record clean tree. Any dirty: ask once via AskUserQuestion:

• Header: "Uncommitted"
• Question: "N uncommitted files on <branch>. How should I handle them?" For a wave, name the dirty repos instead of N.
• Options (single-select):
  1. "WIP commit (Recommended)" — "Stage the dirty paths by name (git add -- <paths from git status --porcelain>), then git commit -m 'wip: pause before context cutoff'. Keeps changes on the branch."
  2. "Stash" — "git stash push -u -m 'rota-pause <branch>'. Keeps changes out of history."
  3. "Leave in place" — "No action; the handoff note will record that the tree is dirty."

Apply the choice only to dirty entries, with git -C <path>. Record each entry's artifact (commit hash, stash ref, dirty tree, clean tree).

Step 4 — Write the Handoff Note

Find the milestone first: rota backlog milestones <ID>... for the captured items. If none is listed, rota milestone active; include it only if exactly one is active. With several, use the one matching the paused items.

Write one handoff note per (branch, repo) entry. Get the path from rota status handoff "$BRANCH" --canonical ${REPO:+--repo "$REPO"}. Fill the template in references/handoff-template.md from the session: omit sections that do not apply, do not invent content. Always overwrite.

In a wave, read Step 4 in `umbrella-wave.md`.

Fill Stage and Next planned step from the task ledger (`references/task-ledger.md`): rota git base, then the Task: trailers in git log <base>..HEAD. Name the finished tasks and make the first unfinished one the next step.

Gotchas and dead ends go to /rota-learn (Step 6), not the note.

Step 5 — Pin Status

For each entry run rota status add <branch> --items <ids> [--worktree <path>] [--repo <repo>] --if-absent so resume finds it. --if-absent keeps the original startedAt; the note carries the pause time.

Step 6 — Confirm

One compact block. Wave: name every repo, count handoffs, list Uncommitted per repo.

Paused `rota/fix-B07-timer-badge` (web) — handoff note saved.

Stage: mid-hypothesis verification for [B07]
Next: run the verification probe in MenuBarManager.swift:54
Uncommitted: wip commit a1b2c3d

Resume with `/rota-work` in a fresh session.

Show the (web) suffix only when repo is non-null.

Learn nudge (conditional). If the session hit a durable gotcha (a hypothesis that contradicted assumptions, a non-obvious root cause, a tool quirk), add one line: "Run /rota-learn now to preserve session insights durably — handoff captures intent, not learnings." Skip if nothing non-obvious surfaced or /rota-learn already ran.

Rules

• Write what you know. The note is a state snapshot, not a task spec.
• One handoff note per (branch, repo). Overwrite on re-pause.
• A multi-repo wave is one logical pause. cd into a sub-repo to scope to it.
• Never commit .rota/handoff/ (gitignored per-developer scratch).
• Do not delete the handoff note here. Resume or abandon removes it; the next session's hook consumes the orchestrator note.
• A paused round is not a finished round. Never wind down, merge or reclaim from a pause.
• No mutation beyond the handoff note, status pin and the chosen wip commit or stash.

References

• `orchestrator-pause.md`: pausing an orchestrator mid-round; read from Step 1 when a round is in flight.
• `umbrella-wave.md`: multi-repo wave pauses; read from Steps 2 and 4.
• `references/task-ledger.md`: Task: commit trailer; read for the handoff note's Stage and Next planned step.
• `references/handoff-template.md`: handoff note template, written by /rota-pause, read by /rota-work.