Handover
append-only records with computed front matter and required sections, created atomically, never staged; --resolve finds the right one for this worktree and branch and labels how far git has moved since
append-only records with computed front matter and required sections, created atomically, never staged; --resolve finds the right one for this worktree and branch and labels how far git has moved since
Where it lives
State it owns
What implements it
Specified in
The command that acts on it
majordomus handover
Write an append-only continuation record, and resolve the most relevant prior one.
- state-mutating
- active task optional
majordomus handover [--derive] [--close] [--no-task] < body.md
See it refuse, and accept
A handover is the one artifact designed to be read by someone who was not there. It carries the sections the policy requires and no transcript.
Given this repository
# ... and an active task scoped to lib, with work done inside that scope. . "$FIXTURE_SETUP/installed.sh" "$MJ" start "narrow the parser" --scope lib >/dev/null echo work >> lib/a
Run
$ majordomus handover < body.md
Output contains
- .ai/local/state/handovers/
exit
0
Objective, Current State and Next Action. The front matter — task, branch, head, worktree — is computed, so the body cannot disagree with git about where it was written.
Given this repository
# ... and an active task scoped to lib, with work done inside that scope. . "$FIXTURE_SETUP/installed.sh" "$MJ" start "narrow the parser" --scope lib >/dev/null echo work >> lib/a
Run
$ majordomus handover < body.md
Output contains
- missing or empty section
exit
10
The sections are named in the refusal. A handover without a Next Action is the failure mode this record exists to prevent, so it is not accepted and quietly filed.
What enforces it
- majordomus.handover-integrity blocking enforced by doctor, watch The resolver runs and reports either the record for this worktree and branch or its clean absence; a malformed record is never silently skipped, and a record describing a history this checkout no longer has is reported.
- majordomus.note-integrity blocking enforced by finish Every outcome needs a note carrying the sections that outcome requires, and no transcript.
- majordomus.task-continuity advisory enforced by finish A task finished as partial or blocked should leave a handover record, not only a note section.
What is guaranteed
- guaranteed handover writes an append-only record with computed front matter and required sectionsproved by test/cases/05_handover.sh
- guaranteed Handovers carry durable facts, never conversation transcriptsproved by test/cases/05_handover.sh
- guaranteed The right prior record is resolved by worktree and branch, and an unrelated one is never offeredproved by test/cases/23_context.sh
The moments this answers
- re-explained the same context to a brand-new session Repository knowledge that only ever existed in a conversation has to be re-transmitted by hand to every worker that follows.
- found five worktrees and could not say which of them still mattered Isolation is cheap to create and expensive to reason about: nothing records what a worktree was for or whether its work landed.
- went looking for why we chose this and found a chat log A decision that was reached in a session is stored where only that session can read it, so it is neither reviewable nor discoverable.
- lost a failure a worker had already reproduced, because the session ended A failure observed inside a session is described in that session and nowhere else, so the next one starts from the report rather than the evidence.
- watched a worker spend a day on an approach that had already been ruled out Negative results are the majority of experimental output and the part nobody records, so the search space is re-explored.