Skip to content

Claude → Codex handoff standard (index: WING-457)

Claude's weekly budget is ~97% consumed and resets Tue Aug 11 12:00. Every Claude session may stop mid-task. Codex (gpt-5.6-sol) picks the work up. A handoff that requires re-deriving context has already failed.

Write the handoff AS YOU WORK, not when you are about to die. A session that stops without warning still hands off cleanly if the file is current.

Where it lives — one file per lane, exact path

docs/handoffs/<WT-id>-<TICKET>.md      e.g. docs/handoffs/WT-a37c-WING-422.md

COMMIT IT. An uncommitted handoff is not a handoff — this week a completed regression sat uncommitted for 14 hours and was nearly paid for twice. Commit on every meaningful change.

PUT IT ON MASTER, NOT ONLY ON YOUR BRANCH. Codex finds lanes by running ls docs/handoffs/ on master. A handoff that lives only on a feature branch is invisible there, so the lane reads as uncovered — WT-a37c caught this hole in the first version of this document. Handoff files are STATUS METADATA, not code, so they land on master under the E1 metadata carve-out: path-allowlisted to docs/handoffs/, porcelain-clean, stage the exact file, commit, push, sub-60s, no review gate. Your CODE still lands by PR as normal.

Required sections — all of them, no exceptions

# <WT-id> · <TICKET> · <one-line what this lane is doing>
Updated: <ISO-8601 UTC>   Status: IN PROGRESS | BLOCKED | READY FOR PR | LANDED

## 1. Goal
What "done" means, in one paragraph, in terms of observable behaviour — not tasks.

## 2. Where the work is
- Worktree: <absolute path>
- Branch: <name> (base: master@<sha>)
- PR: #<n> or NONE
- Uncommitted right now: <count + what it is, or NONE>

## 3. State — what is TRUE, with receipts
Command + observed output for every claim. No claim without a receipt.
If something is unverified, write UNVERIFIED and say what would verify it.

## 4. Next actions, in order
Numbered, each independently actionable, each with its acceptance check.

## 5. Blockers
Especially: anything an agent must REFUSE (credential entry, prod click-through,
signing in as Andrew). Say who must do it — usually Andrew — so it is not silently
inherited as an agent task.

## 6. Traps in this lane
Things that already burned time. Be specific enough to save the next agent the round-trip.

## 7. Delegated / dispatched work
Every fleet-harness job you spawned: target box, kind, lane, job id, what you asked for,
where its output lands, and whether you have read it. UNREAD OR IN-FLIGHT WORK MUST BE
LISTED — otherwise Codex re-dispatches it and pays twice.

## 8. Decisions made and why
So Codex does not silently reverse a deliberate choice.

Fleet-wide operational notes Codex will need

  • send has a ~100s HTTP client timeout; the job KEEPS RUNNING past it. Long work: enqueue + results.
  • Dispatch to DESKTOP-SCDT9HI (streaming) is DOWN — listener answers on a stale Tailscale address. Use ssh fives@10.0.0.26. 68 GB RAM, Claude + Codex authed. Greatroom has ~1 GB free; heavy suites belong on a peer.
  • PowerShell renders a child process's stderr as NativeCommandError. Capture with $o = cmd 2>&1; $o | Out-String or you will read success as failure.
  • Gemini seats: gemini-3.1-pro REQUIRES --effort (low|high); gemini-3.6-flash REQUIRES --effort (low|medium|high). A WRONG --model exits 0 with EMPTY stdout and nothing on stderr — indistinguishable from a clean pass. Always check byte count; empty output is a FAILED seat, never "no findings".
  • CI now runs on EVERY pushed branch (push: {}). Master is green as of cd661d86c — keep it that way.
  • Landing rule: PR onto master, council-review the diff, CI green on its own merits.

Worktree tidying — check UNTRACKED files before cleaning

git clean during worktree tidying destroys untracked work, and dirty-tracked counts do not show it. WT-e833 has a designed opaque cursor (JobSearchCursor.cs) sitting untracked in _worktrees/WT-e833-wing373 right now — a routine clean would delete a real deliverable.

Before removing or cleaning ANY worktree: git status --porcelain and look for ?? lines, not just M. If you find untracked work, commit it or copy it out first. "N dirty files" is not the same question as "is there work here", and the difference is unrecoverable.

The one rule that outranks the others

A check that cannot fail is worse than no check. Five instances this week: an empty council seat scored as "no findings"; a pilot verifier passing a check it never performed; a test harness hanging before any assertion and exiting 0; a deploy chain promoting after a FAILED deploy; a comment-stripping regex deleting the text it was scanning. If you build a gate, prove it fails by reintroducing the defect.