# Overseer handover Docs-first handover of the cross-repo overseer role: snapshot truth per repo, update the durable docs (ROADMAP snapshot, next-session plan, coordination doc), then regenerate the living handover block as a projection of them. ## Step 1 - **Owned job:** Snapshot truth per repo, confirmed via muse -C (not ambient). - **Instruction:** Run muse -C <abs path> status and log for each repo (Scooling, Knowtation, MuseHub) and capture branch, HEAD sha, and dirty state. - **Trigger:** Run when a chat is getting long, a chat switch is needed, or a session ends with multi-repo state in flight. - **When not to run:** Skip if no multi-repo state is in flight and no handover is needed. - **Requires:** vault_scope:project, tool:muse_cli - **Boundaries:** - Always target each repo with muse -C <absolute-path> — a bare muse can report an ambient repo - Read only — do not commit or checkout during the snapshot - No secrets in captured output - **Skill refs:** cli:muse -C <abs-repo-path> status, cli:muse -C <abs-repo-path> log - **Outputs:** per_repo_state:text - **Output shape:** A per-repo line for each repo with real branch, HEAD sha, and dirty flag, each confirmed via -C. - **Verification:** artifact_exists — Each repo is confirmed via -C (not ambient) and every repo line carries a real branch and sha. (evidence required: yes) ## Step 2 - **Owned job:** Record the current step, next action, and open gates/blockers. - **Instruction:** Write down the current initiative step, the unambiguous next action, and any open gates or blockers. - **Trigger:** Run after per-repo truth is captured. - **When not to run:** Skip if the next action and gates are already recorded and unchanged. - **Requires:** vault_scope:project - **Boundaries:** - State the next action so it needs no chat history to interpret - **Inputs:** per_repo_state (from flow_overseer_handover#1.outputs.per_repo_state) - **Outputs:** step_and_gates:text - **Output shape:** A current-step line, a next-action line, and an open-gates/blockers list. - **Verification:** human_review — The next action is unambiguous. (evidence required: yes) ## Step 3 - **Owned job:** List the boundaries and the cross-repo wiring touched this session. - **Instruction:** Enumerate the boundaries to honor and the cross-repo wiring touched this session. - **Trigger:** Run after the step and gates are recorded. - **When not to run:** Skip if no cross-repo wiring was touched and boundaries are already listed. - **Requires:** vault_scope:project - **Boundaries:** - Boundaries are stated explicitly, not assumed - **Outputs:** boundaries_and_wiring:text - **Output shape:** An explicit boundaries list and a cross-repo wiring list for the session. - **Verification:** human_review — Boundaries are explicit and the cross-repo wiring touched is listed. (evidence required: yes) ## Step 4 - **Owned job:** Update the durable docs FIRST. - **Instruction:** Update the ROADMAP snapshot, the next-session plan, and the coordination doc so they match reality before any block is written. - **Trigger:** Run after truth, step/gates, and boundaries are captured. - **When not to run:** Never skip when handing off — docs-first ordering is mandatory. - **Requires:** vault_scope:project, file:docs/ROADMAP.md, file:docs/PRODUCT-SURFACES-NEXT-SESSION-PLAN.md, file:docs/CROSS-REPO-COORDINATION.md - **Boundaries:** - Update durable docs before regenerating any handover block - Docs are the source of truth, the block is a projection of them - **Outputs:** docs_update_ref:string - **Output shape:** Updated ROADMAP snapshot, next-session plan, and coordination doc reflecting reality. - **Verification:** artifact_exists — The durable docs are updated and match reality before any block is written. (evidence required: yes) ## Step 5 - **Owned job:** Regenerate the handover block into the living file from the now-current docs. - **Instruction:** Overwrite docs/OVERSEER-HANDOVER.md with a block regenerated from the updated durable docs, not from memory. - **Trigger:** Run only after the durable docs are updated. - **When not to run:** Skip if the docs have not yet been updated this handover. - **Requires:** vault_scope:project, file:docs/OVERSEER-HANDOVER.md - **Boundaries:** - The block is a projection of the docs — never hand-written ahead of them - No secrets in the block - **Inputs:** docs_update_ref (from flow_overseer_handover#4.outputs.docs_update_ref) - **Outputs:** handover_block_ref:string - **Output shape:** An overwritten docs/OVERSEER-HANDOVER.md whose block matches the durable docs. - **Verification:** artifact_exists — The living file is overwritten and its block matches the docs, not memory. (evidence required: yes) ## Step 6 - **Owned job:** Emit the block as the first message of the next chat. - **Instruction:** Paste the regenerated handover block as the first message of the new chat so the overseer role resumes with no prior history. - **Trigger:** Run once the living file holds the current block. - **When not to run:** Skip if no new chat is being started. - **Requires:** vault_scope:project, file:docs/OVERSEER-HANDOVER.md - **Boundaries:** - Emit only the projected block — do not add scope beyond the durable docs - **Inputs:** handover_block_ref (from flow_overseer_handover#5.outputs.handover_block_ref) - **Outputs:** emitted_block:text - **Output shape:** The handover block, emitted as the first message of the next chat. - **Verification:** human_review — A new overseer can resume from the emitted block with no prior chat history. (evidence required: yes)