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

> Discover SwarmForge's Audit Gate, a mandatory two-step quality checkpoint. Learn how this essential feature verifies Git handoffs, ensuring code integrity before deployment.

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

---

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

```bash

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

```sh

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

```clojure
;; 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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) | Formal specification of the two-call audit gate |
| [`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md#L277) | 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`](https://github.com/unclebob/swarm-forge/blob/main/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.