quill: draft troupe handoff protocol v1.0

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-<timestamp>.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/<wizard-name>/`.
+   - Commit with message: `<wizard-name>: handoff <short-goal>`.
+   - 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 <url> | 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.*