What Is the Audit Gate in SwarmForge and How Does It Work?

The Audit Gate is a mandatory two-step quality checkpoint that blocks every Git handoff until the sender re-verifies the draft and submits an identical, unchanged copy a second time.

The Audit Gate is a core safety mechanism in unclebob/swarm-forge that prevents premature handoffs between autonomous agents. Built into the git_handoff protocol, it forces developers and agents to conduct a disciplined self-review before work can flow downstream.

How the Audit Gate Enforces Quality Control

When an agent invokes swarm_handoff.sh (or its Babashka equivalent swarm_handoff.bb) to submit a handoff draft, the script does not queue it immediately. Instead, the Audit Gate intercepts the first valid attempt and demands a second, identical submission.

Step 1: First Call Triggers AUDIT_REQUIRED

On the first valid call, the script:

• Validates the draft structure
• Canonicalizes the commit abbreviation
• Writes the draft to .swarmforge/handoffs/audit_pending/
• Emits AUDIT_REQUIRED and does not queue the handoff

This behavior is implemented in swarmforge/scripts/swarm_handoff.bb at line 435:

# From swarm_handoff.bb ~L435

# When audit_pending file exists and content differs, require audit

(println "AUDIT_REQUIRED")

The AUDIT_REQUIRED token increments the task-card's audit counter on the dashboard, signaling that a review is in progress.

Step 2: Unchanged Second Call Releases the Gate

When the sender re-runs the exact same command with identical parameters (same draft content, task name, recipient list, and commit hash), the script:

• Detects the matching audit-pending file
• Deletes the pending entry
• Queues the handoff to the outbox
• Suppresses AUDIT_REQUIRED

If any detail changes—new commit hash, different recipient, modified task name—the gate resets and requires another audit cycle.

What the Audit Gate Forces Reviewers to Do

The two-call requirement deliberately slows down handoffs to ensure rigor:

• Re-read the complete inbound payload and all referenced source materials
• Trace every requirement, constraint, and edge case to role-appropriate work
• Fix findings, re-run checks, and repeat until the handoff passes unchanged

Only this disciplined review pattern unlocks forward progress. The protocol formalizes this in swarmforge/handoff-protocol.md at line 251:

"The first valid Git handoff call returns AUDIT_REQUIRED … the sender must re-read … repeat the audit."

Practical Example: Passing the Audit Gate

# First attempt – gate blocks queuing

$ echo "type: git_handoff
to: cleaner
priority: 50
task: task-1-setup
commit: a1b2c3d9e8" > ./tmp/handoff.txt

$ swarm_handoff.sh ./tmp/handoff.txt
AUDIT_REQUIRED               # <-- gate engaged, not queued

# Sender reviews work, confirms no changes needed

# Second identical attempt – gate releases

$ swarm_handoff.sh ./tmp/handoff.txt

# (silent success) – handoff now queued for delivery

Test Coverage for Audit Gate Behavior

The test suite in test/swarmforge/handoff_test.clj verifies this two-state logic:

;; First call always requires audit
(is (str/includes? (:out first-call) "AUDIT_REQUIRED"))

;; Unchanged second call bypasses gate
(is (not (str/includes? (:out second-call) "AUDIT_REQUIRED")))

This test at line 178 ensures the gate behaves consistently across protocol implementations.

Key Implementation Files

File	Purpose
swarmforge/scripts/swarm_handoff.bb	Validates drafts and emits AUDIT_REQUIRED
swarmforge/handoff-protocol.md	Formal specification of the two-call audit gate
README.md	High-level overview of outbound draft handling
test/swarmforge/handoff_test.clj	Unit tests verifying gate behavior

Summary

• The Audit Gate is a mandatory checkpoint in SwarmForge's git_handoff protocol
• Two identical calls are required: first triggers AUDIT_REQUIRED, second releases the queue
• Any change resets the gate, forcing fresh review cycles
• Enforced by swarm_handoff.bb and documented in handoff-protocol.md
• Prevents premature handoffs by embedding self-audit into the workflow

Frequently Asked Questions

What happens if I modify the handoff between the first and second call?

The Audit Gate detects the change, treats it as a new draft, and requires another full audit cycle. The AUDIT_REQUIRED token prints again, and the handoff remains blocked until you submit two consecutive identical versions.

Can the Audit Gate be disabled or bypassed?

No. The gate is hard-coded into swarm_handoff.bb as a protocol-level requirement. The only way to progress is to complete the two-call verification pattern. Human gate approval may follow, but cannot substitute for the self-audit.

Where does SwarmForge store handoffs during the audit pending state?

Pending drafts are written to .swarmforge/handoffs/audit_pending/ with a filename derived from the task and commit. This directory serves as the comparison source for the second call validation.

How does the Audit Gate appear in monitoring dashboards?

Each AUDIT_REQUIRED response increments the task-card's audit counter. This visibility allows swarm operators to track review cycles and identify handoffs that repeatedly fail the identity check, signaling potential quality issues.

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