---
name: wrap
description: Close a Maven work session cleanly. Runs the tests, updates the durable docs, commits in reviewable slices with the Vikunja ref, pushes so the PR opens, records state in Vikunja, and leaves a disposable handoff only if work remains. Use when the user says "wrap", "wrap up", "done for now", or when context passes roughly half.
---

# Wrap

Run every step. A partial wrap is worse than none, because the next session trusts
the parts that did run.

## 1. Prove it works

`make test`. If something fails, fix it or say plainly in the handoff and in Vikunja
that it fails, with the output. Never wrap on an untested claim.

## 2. Update the durable docs

Ask what a future agent would have to learn the hard way, and write that down.

- `CLAUDE.md` when a fact an agent needs before touching code has changed: routing
  behaviour, a measured number, a flag default, a constraint. A commit that changed
  routing or phrasing without touching the matching CLAUDE.md section is a bug.
  Correct stale text in place. Do not append a new paragraph next to the wrong one.
- `AGENTS.md` when the recipe to build, run or preview changed.
- The one file under `docs/` that owns the area, plus its `Last verified: <date> @ <sha>`
  line. Only a doc directly under `docs/` carries that line.
- A new dated file under `docs/evals/` when you measured something. Never edit an
  existing dated file. A newer measurement is a new file, and the living doc points
  at it.

Nothing that must survive tonight goes anywhere else. Not into the handoff, not into
a commit message, not into a comment in the code.

## 3. Commit in slices

Under 300 changed lines per commit in non-markdown files, enforced by `.githooks/pre-commit`.
Markdown is exempt and may land as one batch.

Each commit is one idea, subject in the repo's voice, lowercase area prefix, and it
ends with the Vikunja ref:

```
router: narrow the single-token rule (V-359)
```

If a change genuinely cannot split under 300 lines, say why in the commit body before
reaching for `--no-verify`.

## 4. Land it

```sh
task pr
```

It refuses a dirty tree, pushes, opens or refreshes the PR against the repo default
branch, labels the Vikunja task in-review, comments the PR url on it, and pushes an
ntfy. Do not push by hand and do not call `tea` yourself.

## 5. Record what `task pr` cannot know

Comment on the Vikunja task: what you measured, what is still open. List every
assumption that turned out to be wrong. If the session found new work, create a task
for it now rather than describing it in prose.

This step is what makes the handoff disposable.

## 6. Leave the handoff, or leave none

If the task is finished, delete `HANDOFF.md` and stop. An empty root is the correct
end state.

If work remains, write `HANDOFF.md` with nothing but what the next agent needs to
resume, and no history:

```markdown
# Handoff — <date>

Task: V-359 <one line>
Branch: task/359-<slug>, cut from master

## Where I stopped
<two sentences, mid-thought detail that is nowhere else>

## Next action
<the single concrete next step>

## Do not
<the trap I nearly fell into, or the approach already ruled out>
```

Nothing else goes in it. No summary of what landed, that is in git and Vikunja. No
design rationale, that is in `docs/`. No fact an agent needs on any task, that is in
`CLAUDE.md`. If a line in the handoff would still matter next week, it is in the wrong
file.