Completion contract

This is the boundary between client procedure and server-enforced truth. It applies to a new transition of a task to done.

The contract

The client must:

1. re-read the task and use the returned version as expected_version;
2. report a non-empty handoff_completed and handoff_next;
3. pass one work_receipt describing the actual worker, work, next step, blockers, tests, and Git checkpoint when code changed;
4. include the verified write_context;
5. read the task back after a successful write and treat the readback as the durable confirmation.

The server guarantees for a new in_progress/todo/blocked -> done transition:

• missing handoff is rejected with completion_handoff_required;
• a missing receipt is rejected with completion_receipt_required;
• the task update and receipt insert are one transaction;
• a stale expected_version is rejected as version_conflict before a completion can be stored;
• a rejected completion cannot leave a task change or a receipt behind;
• (task_id, session_ref) prevents the same logical receipt from being appended twice.

handoff_blockers may be an empty string when there is no blocker. A blocked task must still include a non-empty blocker. Existing historical done tasks are grandfathered for unrelated metadata edits; reopening and completing a task again uses the current contract.

The server cannot prove that a client ran its local tests, inspected a commit, or read the task back. Those facts are claims in the receipt and must be truthful. The server only guarantees the shape, version, project binding, atomicity, and uniqueness of the durable write.

Client capability map

Client	What it can assist with	What it cannot guarantee by itself
Codex CLI/Desktop	MCP calls, repository AGENTS.md, explicit prompts, Git and test execution	A universal finish hook across every Codex surface; a server-side proof that the model followed local instructions
Claude Code/Desktop	MCP calls, CLAUDE.md, optional .claude/skills, and client-side hooks where enabled	That a skill or hook is installed, enabled, or run in every Claude surface; server correctness still comes from HeyAira
ChatGPT web/desktop	MCP calls and explicit user/system instructions	Repository-local instruction files and a universal post-task hook; a stale connector schema must be reconnected

The repository contains guidance and optional templates, not an implicit activation mechanism. A project owner may copy the relevant template into a client's own configuration after reviewing it. Installing a file in Git does not grant permissions and does not make an unavailable MCP connection work.

Required procedures

Start

Call server_identity, then continuity_context; compare the selected resource, instance, and project before any write. Expand the selected task with task_get and claim it using the current version.

Work

Keep code and files in Git. Keep decisions, task state, handoff, and receipts in HeyAira. Do not treat a local note, a copied transcript, or a client conversation as durable state.

Finish

Run the relevant tests, commit code when applicable, then call task_update with the current version, the complete handoff, and one receipt. Finally call task_get and verify the status, version, handoff, and receipt.

Failure and retry behavior

Lost response

Do not repeat a mutation blindly. Call task_get first. If the receipt with the intended session_ref exists, the write succeeded. If it does not exist, retry only after using the current task version. For memory_add and task_create, reuse the same idempotency key.

Stale version

Treat version_conflict as a concurrency result. Re-read the task, compare the other session's handoff, and decide whether the authorized work should continue. Do not retry the stale payload automatically.

HeyAira unavailable

The client may continue a safe local draft or leave a Git worktree unchanged, but it must not claim that the handoff, receipt, or completion was persisted. When the service returns, re-authenticate, verify identity, read the latest task, and write with the current version. A missing MCP connection is a blocker, not permission to recreate the task elsewhere.

Missing completion data

The server rejects the completion without changing the task or inserting a receipt. Keep the task open, prepare truthful handoff and evidence, then retry with the version still returned by the failed attempt's preceding read (or re-read if another session may have changed it).

Optional client template

The copyable block in runtime/templates/CLIENT_COMPLETION_BLOCK.md is a reminder, not an activated hook or permission grant. The client owner must install it explicitly if that client supports local instructions.