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

> Understand the Swarm-Forge chain forwarding rule. Learn why intermediate roles must forward git handoffs for deterministic pipeline progression. Ensure your Git workflows are seamless.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: deep-dive
- Published: 2026-08-30

---

**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`](https://github.com/unclebob/swarm-forge/blob/main/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)

```bash

# 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)

```bash
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)

```bash

# 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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) | Defines handoff format, audit process, and chain‑forwarding rule |
| [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.sh) | Validates outbound handoffs and enforces forwarding semantics |
| [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) | Configures each role's receive mode: `forward-only`, `back-one`, or `back-all` |

The propagation token in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/handoff-protocol.md) lines 160‑173.