# Hand-over (`docs/history/handovers/YYYY-MM-DD-{slug}.md`)

Record. Use for: the account an **unattended or multi-session build** leaves the person who owns it — written by the orchestrating session as its last act, before the owner's first decision, read in one sitting. It is a **decision queue, an undo manual and a resume file**, in that order: is it done · what must I decide today · what escaped the repository and how do I undo it · can I see it working · what was decided for me and how do I overturn it · what is red and whose it is. Everything below the divider is for the next session, not the owner. It is not a pull-request description (which argues for a diff), not a changelog entry (which carries refinement context) and not a plan (which is frozen). It is mutable while `status: open` — a successor that re-proves a state line corrects it in place and appends one Timeline row — and **freezes when the owner has acted on § 1 (`status: accepted`)**; a correction after that is a new dated hand-over linking back. Raw artefacts (plans, hand-offs, notes) live in a same-named folder beside it.

Required: **Verdict**, **Owner decisions due**, **Live-world ledger** (even when empty), **Ten-minute walkthrough**, **Rulings on the owner's behalf**, **Red board**, **What was built**, **Proof**, **State**, **Open loops**, **Artefacts & mandate**. Optional: Untouched scope, Discoveries, Deferrable debt, Cost, Timeline.

**Reading order is act → verify → understand.** Owner half, ~20 minutes: Verdict (1) · § 1 (2) · § 2 (2) · § 3 (10, at the product) · § 4 (3) · § 5–6 (2). Successor half, read when the job arrives: § 8–14 (~10).

````markdown
---
type: handover
description: "{at most 300 characters: what this document settles and where its boundary sits}"
status: {open | accepted}
date: {YYYY-MM-DD}
as_of: {YYYY-MM-DDTHH:MM±TZ}
as_of_commit: {sha}                # every § 9 claim is true of THIS commit and no other
verdict: {done | done-needs-calls | partial | stopped-at-budget | failed}
decide_today: {N}   irreversible_acts: {N}   decisions: {N}   red_mine: {N}   open_loops: {N}
deployed:
  - { plane: {dev|staging|production}, artifact: {name}, version: "{id}", by: {automatic|manual}, verify: "{command}" }
prs:
  - { n: {N}, base: {branch}, state: {open|draft|merged}, action: "{what the owner does}" }
---

# Hand-over — {what was built}, {YYYY-MM-DD}

**{VERDICT TOKEN}.** {One sentence in the product's words: what exists and what a person can now do.}

| | |
| --- | --- |
| Built | {N} units · {N} plans · ledger rows {N}, discharged {N}, blocked {N} |
| Proof | {N} tests pass / {N} fail — on `{sha}`, verified {HH:MM} |
| Decide today | **{N}** — § 1 |
| Touched the live world | **{N}** acts, **{N}** irreversible — § 2 |
| Red | {N} mine · {N} pre-existing · {N} environment — § 5 |
| See it work | {N} min — § 3 |
| Taken alone | {N} decisions, {N} stops filed of {N} — § 4 |

**Start here:** `{the one command that brings the reader's machine to the state everything below describes}`
**Single most urgent act:** {act} — by {YYYY-MM-DD}, or {consequence}.

## 1. Owner decisions due

| # | Decision or act | Why today | Default on silence | Decide by | Do it (exact) | Evidence |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | {one line, no mechanism} | {what a week costs} | {the outcome silence produces} | {date} | `{command}` / {PR link} / {UI path} | `{path:line · sha · PR}` |

## 2. Live-world ledger

Everything that left the repository, hardest to undo first. Verified {HH:MM}.

| # | Act (past tense, dated) | Target (system + id) | Command | Reversible | Undo — exact | Evidence / backup + expiry |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | {what was done, {YYYY-MM-DD HH:MM}} | {named system} | `{exact}` | {no / with loss / yes} | `{command}` or {runbook path} — {or "forward only: …"} | {artefact · where · when it expires} |

**Did not happen, and the proof:** {claim} — `{command}`.

## 3. Ten-minute walkthrough

**Prerequisite:** `{command}` · **Sign in as:** {who} · **Total:** {N} min

| # | Do (URL → click) | Expected result | It proves | If not |
| --- | --- | --- | --- | --- |
| 1 | {url} → {action} | {an observable a person can be wrong about} | {unit from § 6} | {§ 5 row, or "file it — new"} |

## 4. Rulings on the owner's behalf

Each was taken because waiting would have stopped the run. Sorted by cost to reverse.

| # | Ruling | Instead of | Why | Authority | Landed at | Overturn — exact | Default on silence | Hardens when |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| D-1 | {the ruling} | {the alternative, fairly} | {the constraint} | {owner said so HH:MM "…" / auto-ruled as recommended / taken alone — by {agent · model}} | `{file:line}` | `{edit or command}` | {default} | {event} |

*Bulk: {N} per-plan questions ruled `as recommended, overturnable` — index at `{path}`. Only rows costing more than one commit to reverse are listed.*

## 5. Red board

| What's red | Where | Mine? | Proof | Blocks | Next step + owner |
| --- | --- | --- | --- | --- | --- |
| {test or command} | `{file:line}` | {mine / pre-existing / environment} | `{the command or stash that settled it}` | {what it stops, or nothing} | {act} — {who} |

## 6. What was built

| Unit | Role for a person | Landed | Proof |
| --- | --- | --- | --- |
| {name} | {one clause, behaviour before mechanism} | {branch · PR · release} | {suite + counts, or "driven only", or empty} |

## 7. Untouched scope

| Thing | State | Why untouched |
| --- | --- | --- |

---

*Everything above is for the owner. Everything below is for the next session.*

## 8. Proof

| Unit | Promise (clause) | Code @ | Pinned @ | Independent? | Rows p/o/b | Gap |
| --- | --- | --- | --- | --- | --- | --- |
| {plan} | {ruling n — five words} | `{sha7}` | `{sha7}` | {yes / **no — {who did both}**} | {n}/{n}/{n} | {G-n / —} |

| # | Claim that is not proven | Why | What would prove it | Sev |
| --- | --- | --- | --- | --- |
| G-1 | {stated as the build would state it} | {blocked row / never driven / self-authored pin / no suite on this head / not recorded} | `{exact command}` | P{0-3} |

## 9. State

Present tense; every row true of `as_of_commit`, and every row re-provable by its own command.

| Repo · branch | HEAD | vs upstream | Working tree | Worktrees | Re-prove |
| --- | --- | --- | --- | --- | --- |

| Plane | Artifact | Version | Deployed by | Re-prove |
| --- | --- | --- | --- | --- |

| Store | Env | Last destructive act | Backup + expiry | Re-prove |
| --- | --- | --- | --- | --- |

| Process / connection / token | Where | State | Check or stop |
| --- | --- | --- | --- |

## 10. Open loops

| # | Loop | Whose | Next command or ask | Blocked by | Evidence |
| --- | --- | --- | --- | --- | --- |
| L-1 | {present tense} | {session / owner / external} | `{command}` or {the question, with the default in force} | {id / —} | `{path:line}` |

## 11. Discoveries

| # | Trap | The truth | Cost paid | Guard |
| --- | --- | --- | --- | --- |
| X-1 | {what it looks like from outside} | {present-tense fact} | {hours / runs} | `{command}` or `none — {what would hold it}` |

## 12. Deferrable debt

| # | What | Why not now | Re-open when | Parked at |
| --- | --- | --- | --- | --- |
| T-1 | {one line} | {the ruling} | {a trigger, not a date} | `{backlog row · issue · path:line}` |

## 13. Cost

**Wall-clock:** {Nh Nm} ({start} → {end}) · **unattended:** {Nh} · **Agents:** {N} · **Tokens:** {N | unmeasured — {what would measure it}} · **Rework:** {what was thrown away} · **Stops filed:** {N} of {N}

## 14. Artefacts & mandate

| Path | Holds | Volatile | Safe to delete after |
| --- | --- | --- | --- |

**Corpus:** {tracked at `{path}` @ {sha} | **UNTRACKED at `{path}` — {what would durably hold it}**}
**May, alone:** {one line each} · **Must file or ask:** {one line each} · **Never:** {one line each}

## 15. Timeline

<!-- Append only. Never rewritten. -->

- {YYYY-MM-DD HH:MM} — {event} (`{sha7}` / PR #{n})
````

## Field rules

- **Verdict (≤14 lines).** One token from the closed set — `DONE` · `DONE, NEEDS YOUR CALLS` · `PARTIAL` · `STOPPED AT BUDGET` · `FAILED` — first in the body; a paragraph before it is a format violation. The scoreboard is always the same seven rows in that order, and a zero is written `0` — `Touched the live world: 0` is one of the most valuable lines the file can carry. `Start here` is exactly one command.
- **§ 1 Owner decisions due (≤7 rows).** Owner-only acts, sorted by cost of deferral descending. `Do it (exact)` is a command, a link or a literal UI path — `git revert -m 1 {sha}`, never "revert the merge". `Default on silence` is mandatory and honest. **A decision has an alternative and belongs in § 4; an act outside the repository with no alternative is a chore and belongs here.**
- **§ 2 Live-world ledger.** Required even when empty — `none — nothing left the repository`, with the command that proves it. Sorted hardest-to-undo first, never chronologically. `Reversible` takes three values: `no` states what now exists in the world, `with loss` names what is lost, `yes` carries the command. An act reversible only forward (redeploy, reseed, a superseding publish) is `no`, and the forward path goes in `Undo`. A backup states its expiry; copying a volatile backup somewhere durable is row 1 of § 1.
- **§ 3 Ten-minute walkthrough (≤6 steps, ≤10 min).** Every `Expected result` is an observable a person can be wrong about — a number, a named control, a status code — never "the page loads". It is the only check the owner performs with his own eyes rather than on the build's word.
- **§ 4 Rulings on the owner's behalf (≤10 rows).** Sorted by cost to reverse. `Authority` takes exactly three values — the owner said so (with the words and the time) · auto-ruled as recommended · taken alone — recorded per decision, never per run: it is the distinction an unattended run exists to preserve. `Overturn` is an edit or a command. `Hardens when` names the event after which reversal stops being cheap. A ruling with no reversal path is a constraint, not a decision — it moves to § 12.
- **§ 5–7.** One home per fact: a red appears in § 5 even when a decision caused it, and the decision cites the row. `Mine?` is proved by the command or stash in `Proof`; `mine` is the default when no proof is offered. § 6 leads with behaviour, not plan slugs. § 7 exists so an owner scanning the repository does not mistake somebody else's branch for the run's debris.
- **§ 8 Proof.** **An unproven claim is an empty cell, never a sentence** — prose has no empty cell to scan for. `Independent?` reads `no` whenever one agent authored both the code and its pin, or found, fixed and pinned the same defect, and names who. Ledger counts are parsed from the plan, never quoted from an agent's summary, so `blocked` cannot hide inside "discharged". Every `G-n` names the command that would close it.
- **§ 9 State.** Present tense; a claim that cannot be re-proved by its `Re-prove` command does not belong here — it moves to § 15 as a dated event. Volatile things (`/tmp`, pid files, ports, tokens, browser connections) declare a lifetime and the command that makes them durable.
- **§ 10–12.** A loop is a runnable command or a named question, never a noun phrase and never "investigate"; one needing a person's judgment states the question and the default in force. A discovery is a present-tense fact with a guard — "Workers Builds does not fire on a `dev` merge", not "we found that it didn't"; `none — {what would hold it}` is an honest guard that feeds the backlog. Debt names where it now lives, so this file can be deleted without losing it.
- **§ 13–14.** Every uninstrumented number reads `unmeasured — {what would measure it}`; a blank reports a cheaper run than the one that happened. **State whether the run's own corpus is version-controlled** — an untracked corpus is one `rm -rf` from being three PR descriptions, and archiving it is a § 1 row.
- **Ids are stable and run-global** — `D-`, `G-`, `L-`, `X-`, `T-` — so a PR comment or a successor cites a row instead of re-describing it. A withdrawn row keeps its id and states what disproved it.
- **Evidence is an address that outlives the run** — `path:line`, a 7-char sha, a PR number, a URL, or a command. A branch name is not a pointer; a `/tmp` log is not evidence — copy it into the record folder first.
- **Blanket claims are banned.** "All suites green", "every ledger discharged", "nothing was deployed" carry a count and the sha they are true of, or they become a `G-n` row.
- **The last act before showing the file is a contradiction pass**: the scoreboard against § 2, § 6 against § 1, every count against its source, every `{…}` resolved. An unresolved placeholder in an action cell is a defect of the same class as a broken command.