feat(hooks): the merge question says how the run was tested and how it is undone

docs/HANDOVER-CONTRACTS.md

@@ -639,3 +639,25 @@ The `next-session-prompt-validator` (`lib/validators/next-session-prompt-validat
 | 7. session-state (multi-session resume) | required-fields + status enum + drift-WARN extras | this plugin | low — readers tolerate unknown keys; writers are owned by trekexecute Phase 8 + helper command |
 
 When extending the plugin or adding a new pipeline stage, follow the same pattern: produce an artifact with a versioned frontmatter (or `schema_version` for JSON), write a validator under `lib/validators/`, add fixtures under `tests/fixtures/`, and add an entry to this document.
+
+---
+
+## Internal files
+
+Files Voyage writes for its own use. They are no handover: no other stage reads
+them, they carry no version promise, and they may change in any release.
+
+**Merge evidence** (fix round 4.5b2 part B). `/trekexecute` Phase 8 runs
+`lib/review/merge-evidence.mjs write` before it merges a run's branch into
+main. It writes `<git common dir>/voyage/merge-evidence/<branch head sha>.json`:
+inside the git directory, so it is never tracked and never published, and
+shared by every worktree of the repo, so the guard finds it from main's tree.
+The Bash guard reads it with `hooks/lib/merge-evidence.mjs` into a "Tested by"
+and an "Undone by" line of its merge question; the guard's answer stays "ask",
+and a missing, stale, foreign or unreadable file reads "no run evidence" or
+"not measured". Fields: `v` (`1`), `branch`, `branch_head_sha`, `written_at`,
+`end_to_end` (`{command, exit}`; `exit` is `0` when `progress.json` says
+`verified`, else `null`), `verification` (`{passed, total}`), `review`
+(`{verdict, sha}`) and `door` (`{type: one-way | two-way | null, text}`).
+Files older than 30 days are removed when the next one is written. It is a new
+internal file, not a field of `progress.json`: it is not part of Handover 5.