From d6207c068ad5d2fd3fba891ed66c37c585180f65 Mon Sep 17 00:00:00 2001 From: quill Date: Mon, 26 Oct 2026 21:59:24 +0000 Subject: [PATCH] quill: draft troupe handoff protocol v1.0 --- wizard-work/quill/troupe-handoff-protocol.md | 54 ++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 wizard-work/quill/troupe-handoff-protocol.md diff --git a/wizard-work/quill/troupe-handoff-protocol.md b/wizard-work/quill/troupe-handoff-protocol.md new file mode 100644 index 0000000..6d983ed --- /dev/null +++ b/wizard-work/quill/troupe-handoff-protocol.md @@ -0,0 +1,54 @@ +# Troupe Handoff Protocol +## Draft v1.0 — Quill, Draft lane + +### Purpose +Give each wizard a deterministic, evidence-based handoff when a session ends, is interrupted, or is routed to another operator. No orphaned state, no assumed context. + +### Trigger Conditions +Use this protocol when ANY of the following is true: +- Session ends with unfinished artifacts. +- A child subagent returns a summary that needs verification. +- Operator switches to a different wizard mid-task. +- Cron job output needs routing back to the troupe. + +### Steps + +1. **Freeze the artifact state** + - Record absolute paths of every file written. + - Record every tool call that had a side effect (terminal, web_search, delegate_task, cronjob, push). + - Do NOT delete or move files during handoff. + +2. **Write the Handoff Ledger** + Create `handoff-.md` in the session scratch dir with exactly these sections: + - `## Context` — operator, lane, model/provider, goal. + - `## Completed` — artifact paths + one-line description + test/evidence that verified it. + - `## Unfinished` — stub paths, what remains, acceptance criteria for completion. + - `## Blockers` — exact error text, missing credentials, rate limits, or tool failures. + - `## Next Action` — one command or tool call that advances the unfinished work. + +3. **Verify with a CHECK command** + Every handoff MUST include a single bare shell command whose exit code is 0 on success and nonzero on failure. Example: + - `test -f /path/to/artifact && wc -c < /path/to/artifact | awk '{print $1 > 500}'` + - `python3 -c "import json; json.load(open('/path/to/artifact'))"` (validates JSON parse) + Do NOT append `; echo ...`, `; true`, or `|| true`. The exit code is the verdict. + +4. **Route the ledger** + - Copy the ledger to `/root/troupe-standup/wizard-work//`. + - Commit with message: `: handoff `. + - If a `FORGE_TOKEN` is present, push to origin main. + - If push fails, leave the local commit and report the exact error in Blockers. + +5. **Resume Rule** + The receiving wizard reads ONLY the handoff ledger and the listed artifact paths. It does NOT read prior session transcripts unless the ledger says so. + +### Evidence Requirements +No claim in a handoff is accepted without one of: +- A tool call result with a verified exit code. +- A file path confirmed by `test -f`. +- A URL confirmed by `curl -sI | head -1`. + +### Non-Goals +This protocol does not cover credential rotation, vendor negotiation, or model selection. Those are operator decisions recorded in Blockers. + +--- +*End of protocol. Next action: write a test handoff ledger for an actual artifact and verify the CHECK command exit code.*