Handoff and communication contracts

Guild Stack communication is a file-first handoff bus:

agent -> handoff receipt -> lead -> review -> verification

A specialist can use host chat to say a receipt is ready, but the chat message is not the handoff. The contract is the receipt file under .guild/runs/<run-id>/handoffs/, plus the run-state, bus, review, and trace files that surround it.

Handoff Contract

A dispatched lane is expected to receive an assignment and focused context, but the production assignment path is not yet the authoritative per-attempt contract described in the design. The durable completion boundary is shipped today: when a lane finishes, it writes one receipt:

.guild/runs/<run-id>/handoffs/<specialist>-<task-id>.md

That receipt wraps a compact guild.handoff.v2 envelope inside a guild.handoff_receipt.v1 Markdown record. The envelope carries task id, tier, status, summary, artifacts, issues, optional escalation reason, notes, and learning candidates. Learning entries are candidates only; they do not promote themselves into .guild/wiki/**.

The receipt gives three audiences the same truth at different depths:

Audience	What they inspect
Beginner Users	The final receipt that explains what the specialist did.
Power Users	Receipt status, artifacts, issues, review packets, and verification results.
Harness Developers	guild.handoff.v2, guild.handoff_receipt.v1, task assignments, agent-bus events, and validation paths.

Assignment path: shipped and target

Do not treat the current pane assignment file as proof that every task was delivered and acknowledged.

State	What is true
Shipped	The tmux launcher writes one guild.task_assignment.v1 file per specialist pane and exports its path. Production workers do not yet read and acknowledge that file as a required startup step. When a specialist owns several planned tasks, the pane assignment represents the first task rather than a complete per-task queue.
Target	Every dispatch attempt gets an authoritative assignment keyed by task_run_id and attempt. The worker must read and acknowledge it before work begins, and every planned task remains individually traceable.

The handoff receipt remains the shipped completion boundary. Assignment acknowledgements are a target contract and must not be inferred from pane creation or environment export.

Schema And File Map

Use this map before reading implementation detail:

Concern	Contract	Path
Pane assignment (shipped launcher file; no required worker acknowledgement)	guild.task_assignment.v1	.guild/runs/<run-id>/tasks/<specialist>.json
Dispatch attempt	guild.task_run.v1	.guild/runs/<run-id>/task-runs/<task-id>.yaml
Context bundle	context bundle Markdown	.guild/context/<run-id>/<specialist>-<task-id>.md
Completion receipt	guild.handoff_receipt.v1 wrapping guild.handoff.v2	.guild/runs/<run-id>/handoffs/<specialist>-<task-id>.md
Lifecycle stream	guild.agent_bus_event.v1	.guild/runs/<run-id>/agent-bus/events.ndjson
General artifact bus	guild.bus_event.v1, CAS metadata, subscribers	.guild/runs/<run-id>/bus/
Lane liveness	structured heartbeat	.guild/runs/<run-id>/in-progress/<specialist>.json
Review output	review packet/result/trail files	.guild/runs/<run-id>/review/<gate>/
Canonical trace	trace JSONL	.guild/runs/<run-id>/logs/v1.4-events.jsonl

Two bus names matter:

Bus	Shipped role
Agent bus	The shipped lifecycle stream for task-created, task-completed, and idle events.
Artifact bus	A generalized publish/consume substrate with CAS and subscribers. It exists as code, but review paths still write co-located review files in v2.0.

Do not conflate them. They have different schemas, logs, and runtime roles.

Validation Points

Receipt validation is split by execution path:

Path	Validation behavior
Claude-hooked writes	comms-format-lint checks written receipts; blocking is opt-in with GUILD_COMMS_FORMAT_ENFORCE=1.
Agent-team completion	task-completed validates the envelope before accepting lane completion.
Non-Claude panes	The orchestrator or reaping path validates when it consumes the receipt.
Idle lane with no receipt	teammate-idle nudges; repeated failure routes to lane failure/dead-letter handling.

The canonical validator lives in plugin/hooks/lib/handoff-v2.ts. The communication module keeps a lint mirror in plugin/src/modules/communication/workflows/comms-format-lint.ts, and reaping keeps another local mirror. A schema change must update the validator and mirrors together.

Module Ownership

The communication boundary is implemented across a small set of modules:

Module	Owns
communication	Handoff-envelope linting, artifact bus, agent-team communication hooks, and protected communication-surface guards.
dispatch	guild.task_assignment.v1, backend launch, and pane/channel setup.
lifecycle	guild.task_run.v1, run lifecycle records, and task-run writers.
review	Review packets, review results, trails, and gate outcomes.
telemetry	Canonical trace and additive structured trace events.

Implementation source paths:

Need	Source
Communication module reference	docs/v2/architecture/modules/communication.md
Dispatch module reference	docs/v2/architecture/modules/dispatch.md
Handoff validator	plugin/hooks/lib/handoff-v2.ts
Task assignment writer	plugin/src/modules/dispatch/workflows/task-assignment.ts
Completion hook	plugin/hooks/agent-team/task-completed.ts
Artifact bus	plugin/src/modules/communication/resources/scripts/lib/artifact-bus.ts

Host Boundary

The file bus is what makes host adaptation possible. A Claude pane, a Codex pane, an app surface, or a connector path can all lose host-specific chat features while preserving the receipt contract.

What may degrade:

Degraded surface	What remains stable
Host chat / SendMessage	Receipt files under .guild/runs/<run-id>/handoffs/.
Parallelism	Topological task execution and receipts.
Native approval UI	File-backed approval request and recorded decision.
Model-tier availability	Tier key plus recorded collapse/unavailable path.

What must not degrade silently:

Contract	Reason
Handoff receipt	Review and verification need a durable lane result.
Context pointer	The lane must be reconstructable.
Trace event	Degradation and run history must be explainable later.
Review/verification file	A chat transcript cannot substitute for a gate result.

What This Is Not

• Not a chat protocol.
• Not proof of host parity.
• Not a real-time message broker requirement.
• Not an auto-promotion path for knowledge or skills.
• Not a replacement for review and verification gates.

The durable answer is the receipt. Other channels point to it, validate it, or summarize it.