Chain Forwarding Rule in Swarm‑Forge: Why Intermediate Roles Must Forward Git Handoffs

The chain forwarding rule requires every intermediate role in a Swarm‑Forge pack pipeline to forward received git_handoff messages unchanged to the next role, ensuring deterministic work progression while allowing only the terminal role to mark a card as Done.

In the unclebob/swarm-forge repository, the handoff protocol governs how multi‑agent pipelines coordinate work through Git commits. Understanding why intermediate roles must forward rather than terminate handoffs is essential for correctly implementing custom packs and troubleshooting stuck dashboard cards.

What Is the Chain Forwarding Rule?

The chain forwarding rule is defined in swarmforge/handoff-protocol.md (section Chain forwarding, lines 160‑173). It mandates that:

• Intermediate roles — any role except the last in a pack — must always forward the git_handoff to the next role in sequence
• Terminal roles — the final role — emit a special terminal handoff with to: listing all other roles, which moves the card to Done

This creates a linear relay where each role passes the identical commit reference downstream until the final role completes the cycle.

Why Intermediate Roles Cannot Terminate Handoffs

According to the Swarm‑Forge source code, five core requirements make forwarding mandatory:

Ensure Dashboard Progression

The board only transitions a card to Done when the last role emits a terminal handoff containing all other roles in its to: field. Intermediate forward‑only handoffs keep the card actively travelling through the pipeline stages. Without this rule, cards would stall mid‑pipeline with no visual indication of completion.

Maintain Single Source of Truth

Each git_handoff contains a 10‑character commit hash that must resolve to a unique commit. By forwarding the handoff unchanged, every subsequent role works against the exact same repository snapshot. This prevents:

• Drift — different roles building from different commits
• Duplicate work — redundant processing of the same task

Trigger Audit Cycle Exactly Once

The first call to git_handoff returns AUDIT_REQUIRED. The forwarding mechanism ensures subsequent unchanged calls are accepted without re‑incrementing the audit counter. This guarantees the handoff is processed exactly once after audit passes, not repeatedly at each intermediate stage.

Preserve Back‑Propagation Semantics

When configured with back-one or back-all, a role creates merge‑only copies for earlier roles. However, only the forward handoff moves the card. Forwarding therefore cleanly separates:

• Copy‑only actions — back‑propagation for visibility
• Progression actions — the forward handoff that advances pipeline state

Support Flexible Pack Topologies

Swarm‑Forge supports multiple pack structures:

Pack Type	Role Count
Two‑pack	2
Four‑pack	4
Six‑pack	6

The chain forwarding rule guarantees that any added, removed, or reordered intermediate role participates correctly without custom logic per topology.

Code Examples: Forward vs. Terminal Handoffs

Forward‑Only Handoff (Intermediate Roles)

# In an intermediate role's script

swarm_handoff.sh <<EOF
type: git_handoff
to: next_role
priority: 10
task: my-feature
commit: a1b2c3d4e5   # 10-char abbrev

EOF

This handoff passes unchanged to the next role. The card remains in progress.

Terminal Handoff (Last Role Only)

swarm_handoff.sh <<EOF
type: git_handoff
to: role1,role2,role3   # all earlier roles

priority: 10
task: my-feature
commit: f6e7d8c9b0
EOF

The explicit enumeration of all roles triggers the Done transition.

Back‑Propagation Copy (Non‑Moving)

# If the role is configured with `back-one`

swarm_handoff.sh ...        # forward handoff as above

# Helper automatically creates merge-only copy for previous role

The merge‑only copy provides visibility without affecting card state.

Key Configuration Files

File	Purpose
swarmforge/handoff-protocol.md	Defines handoff format, audit process, and chain‑forwarding rule
swarmforge/scripts/swarm_handoff.sh	Validates outbound handoffs and enforces forwarding semantics
swarmforge/swarmforge.conf	Configures each role's receive mode: forward-only, back-one, or back-all

The propagation token in swarmforge.conf determines whether a role creates back‑propagation copies while still being required to forward the primary handoff.

Summary

• Chain forwarding requires intermediate roles to pass git_handoff messages unchanged to the next role
• Only terminal handoffs from the last role move cards to Done
• Forwarding preserves commit consistency, prevents duplicate audits, and enables correct back‑propagation
• The rule works across all pack topologies without modification

Frequently Asked Questions

What happens if an intermediate role forgets to forward a git handoff?

The card stalls on the dashboard. Since the board only marks cards Done upon receiving a terminal handoff that lists all roles, missing forward handoffs break the relay chain. The swarm_handoff.sh validation script will reject improperly terminated handoffs, but manual intervention may be needed to recover the pipeline state.

Can an intermediate role modify the commit hash before forwarding?

No. Modifying the 10‑character commit hash violates the single‑source‑of‑truth guarantee. The swarm_handoff.sh validator enforces hash consistency, and changed hashes would trigger a new audit cycle (AUDIT_REQUIRED) rather than the intended forward acceptance. The next role would also work from a different snapshot than predecessors.

Does the chain forwarding rule apply to all pack sizes equally?

Yes. The rule is topology‑agnostic. Whether using a two‑pack, four‑pack, or six‑pack, every role except the last follows identical forwarding semantics. The swarmforge.conf propagation token configures back‑propagation behavior independently, but forwarding remains mandatory.

How does the terminal handoff differ syntactically from forward handoffs?

The terminal handoff lists all other roles in its to: field (comma‑separated), while forward handoffs specify only the single next role. This explicit enumeration is the machine‑readable signal that triggers the Done transition, per the protocol definition in handoff-protocol.md lines 160‑173.

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