How to send a hand-off

Choose the kind and the addressee

From the record’s actions choose Hand off (the phase-2 record action “Send to QA” is the same thing with the quality reviewer pre-selected). Kinds: review (please check this), data (please supply or link data), decision (please decide this), information (for your awareness). Address a persona; optionally a person. Write a short message; it passes redaction and never carries retrieved source text.

Send, or approve your twin’s proposal

Send calls POST /programs/{program_id}/handoffs with HandoffCreate {to_persona_key, to_user_id?, kind, linked_type, linked_id, message_md}. The API creates the row sent, writes one inbox item per current holder of the addressed persona (one item when a person is named), notifies a named addressee with handoff_received (a persona-wide hand-off goes to the digest), and audits handoff.send. When your twin proposed the hand-off (“EXP-0421 ready for SOP check”), the proposal waits in your inbox like any other write and Approve creates the same row; the record then reads “Proposed by Maya N.’s twin (agent); decided by Maya N.” (illustrative).

What the addressee sees

The item sits under Hand-offs in their inbox with your name, the kind, the linked record and “Why now”. The first holder to Accept (POST .../handoffs/{handoff_id}/accept) becomes to_user_id; the sibling items of the other holders are withdrawn in the same transaction; a program-visible thread opens (visibility = program, scope_type = handoff, pinned to the record) so people, not twins, resolve questions in the open; and the addressee’s twin, if active, runs twin_handoff to prepare (for QA: the check bound to the SOP version in force, filed as a proposal for QA to approve). Decline needs a reason. The board shows the card in the addressee persona’s column.

Complete or withdraw

The person who accepted marks it Complete when the work is in the record (handoff.complete). You can Withdraw a hand-off that is still sent (handoff.withdraw). Each route is scoped to its party: withdraw to the sender, accept and decline to the addressee or a current persona holder, complete to the acceptor.

Read what changed

The hand-off page (/p/<slug>/handoffs/[id]) shows the status chip, both parties, the linked record, the thread and the decision reason. Setup › Audit shows handoff.send, handoff.accept and handoff.complete with actor_kind = human; a twin-proposed hand-off additionally carries interrupt_id, twin_id and the two hashes on the handoff.send row.