Terminal Broadcast vs Git Handoff: How Swarm-Forge Handles Workflow Completion

A terminal broadcast is a special git handoff where the to: field contains every other role in the pack, signaling recipients to merge and stop rather than forward the commit onward.

In the Swarm-Forge framework, git handoffs coordinate work between roles in a software development pack. While most handoffs chain forward through single recipients, the terminal broadcast serves as a clean termination mechanism for completed work. Understanding this distinction is essential for anyone implementing or auditing Swarm-Forge workflows.

---

What Is a Normal Git Handoff?

A standard git handoff transfers a commit from one role to the next role in the sequence. These handoffs are single-recipient by design.

The to: field names exactly one target role. After merging the commit, that recipient must create and forward a new handoff to continue the chain.

type: git_handoff
from: coder
to: cleaner
recipient: cleaner
priority: 50
task: task-1-cave-setup
commit: a1b2c3d9

In this example, cleaner receives the handoff, merges commit a1b2c3d9, then forwards a new handoff to architect. The workflow continues until reaching the final role.

---

What Makes a Terminal Broadcast Different?

A terminal broadcast appears only at the last role in a pack. Instead of naming one recipient, the to: field enumerates every other role in the pack. This structural difference triggers fundamentally different behavior.

Key Distinctions: Terminal Broadcast vs Normal Git Handoff

Feature	Normal Git Handoff	Terminal Broadcast
to: field	Single recipient (next role)	Full list of all other roles
recipient header	Identifies the sole target	Identifies which copy this is (audit trail)
Forwarding behavior	Recipient must forward after merging	Recipients merge only, do not forward
Completion signal	Implicit via chain continuation	Explicit: full recipient list = Done
Partial to: list	Continues normal handoff chain	Not terminal — only complete list counts

The handoff protocol specification in swarmforge/handoff-protocol.md defines these rules explicitly: when the last role's git_handoff contains a complete to: list, it marks the card Done and recipients merge only without re-forwarding [L176-L190].

---

Terminal Broadcast Example

When the QA role (final in a six-pack) completes validation, it broadcasts to all five preceding roles:

type: git_handoff
from: QA
to: coder,cleaner,architect,hardender,specifier
recipient: QA
priority: 50
task: task-1-cave-setup
commit: a1b2c3d9

Each of the five roles receives this handoff, merges the commit, and stops. No forwarding occurs. The card's workflow terminates cleanly.

---

Creating a Terminal Broadcast in Practice

The merge_and_process.sh script assembles broadcast handoffs by building the full recipient list dynamically:

#!/usr/bin/env bash
ROLE="QA"

# Build comma-separated list of all roles from roles.tsv

TO="$(awk -F',' '{print $2}' .swarmforge/roles.tsv | paste -sd',' -)"

cat > "$OUTBOX/tmp/${SEQ}_broadcast.handoff" <<EOF
type: git_handoff
from: $ROLE
to: $TO
recipient: $ROLE
priority: 50
task: $TASK
commit: $COMMIT
EOF

The handshaked.bb daemon monitors outbox/ for these files, validates the broadcast structure, and distributes copies to each recipient's inbox.

---

Why the Terminal Broadcast Design Matters

Auditability

The full to: list preserves complete participation records. Auditors examining any copy can see exactly which roles received the final state.

Clean Termination

Removing the forwarding step eliminates ambiguity about workflow completion. The presence of a complete recipient list serves as an unambiguous terminal signal.

Reliability

By preventing further forwarding, the broadcast reduces risks of:

• Lost handoffs at chain termination
• Duplicate processing from redundant forwards
• Infinite loops from misconfigured routing

The test suite validates this in test/swarmforge/pack_ui_test.clj through cases like two-pack-end-broadcast-marks-the-card-done, ensuring broadcasts properly mark cards as completed.

---

Summary

• Normal git handoffs use single recipients and mandatory forwarding to progress work through a role sequence.
• Terminal broadcasts use complete recipient lists, appear only at the final role, and terminate workflow without forwarding.
• The distinction is enforced by protocol rules in handoff-protocol.md and implementation logic across handshaked.bb, merge_and_process.sh, and ready_for_next_task.sh.
• Terminal broadcasts improve auditability, provide explicit completion signals, and reduce termination errors.

---

Frequently Asked Questions

What happens if a terminal broadcast has a partial to: list?

A partial recipient list does not trigger terminal behavior. According to the handoff protocol, only a complete list of every other role marks the broadcast as terminal. Partial lists are treated as ordinary multi-recipient handoffs that would require forwarding—though such configurations are generally invalid in standard Swarm-Forge operation.

Can any role send a terminal broadcast, or only the last role?

Protocol semantics designate terminal broadcasts for the last role only. While the daemon may technically process any validly-formed handoff, sending a terminal broadcast from a non-terminal role would violate pack workflow invariants and likely cause cards to be incorrectly marked Done before completing their full role sequence.

How does a recipient know whether to forward or stop?

Recipients examine the to: field contents against their knowledge of pack membership. If to: contains all other roles, the handoff is terminal—merge and stop. If to: contains one role (including self), forward after merging. The ready_for_next_task.sh script implements this decision logic.

Where is the terminal broadcast behavior tested?

The test suite in test/swarmforge/pack_ui_test.clj includes specific cases verifying that broadcasts correctly mark cards as done without further forwarding. These tests validate both the protocol semantics and the integration between script components.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}