turnfile

# Turnfile

> Turnfile is a thin governance layer for auditable peer disagreement between heterogeneous LLM agents. Three agents (Claude by Anthropic, Codex by OpenAI, and Gemini by Google) collaborate through shared, human-legible markdown files with a human maintainer as arbiter — no central orchestrator, every decision recoverable from plain files. Canonical home: https://turnfile.work/

Updated: 2026-09-23. Spec version v1.0.0; protocol release v1.0.0 (Maintainer-ratified 2026-07-02, the Minimal Governance Profile freeze). 48 registry-tracked PRDs, 45 promoted PRDs.
turnfile:prd-promoted=45
turnfile:registry-tracked=48
turnfile:agents=3

## v1 Minimal Governance Profile (stable reading surface)

A fresh adopter only needs these four documents to use Turnfile v1. No historical PRDs required.

- [SPEC.md](https://github.com/snapsynapse/turnfile/blob/main/SPEC.md): normative v1 contract.
- [DEFINITIONS.md](https://github.com/snapsynapse/turnfile/blob/main/DEFINITIONS.md): controlled vocabulary.
- [MINIMUM_VIABLE_TURNFILE.md](https://turnfile.work/MINIMUM_VIABLE_TURNFILE.md): three-file core (TURNFILE.yaml + MAILBOX.md + WORKLOG.md) with a worked open → mid-turn → close example.
- [CONFORMANCE.md](https://github.com/snapsynapse/turnfile/blob/main/CONFORMANCE.md): verifier-anywhere claims and named optional profiles.
- [FRESH_CONTEXT_CONFORMANCE_PROBE.md](https://turnfile.work/FRESH_CONTEXT_CONFORMANCE_PROBE.md): five-question operational test.

Other stable v1 surface: `schemas/v1/`, `templates/v1-minimal/`, `tools/` (including the portable `turnfile.mjs` CLI), promoted PRDs at [docs/prds/](https://github.com/snapsynapse/turnfile/tree/main/docs/prds). Per-PRD classification at [docs/prds/PRD_SHELF_RECONCILIATION.json](https://turnfile.work/prds/PRD_SHELF_RECONCILIATION.json).

## Archive boundary (historical evidence, not required reading)

- [examples/inception/](https://github.com/snapsynapse/turnfile/tree/main/examples/inception) — sessions 1-11 archive (original two-agent invention).
- [examples/turnfile-development/](https://github.com/snapsynapse/turnfile/tree/main/examples/turnfile-development) — sessions 12-current archive (three-agent evolution).

## Core protocol documents

- [Protocol core](https://turnfile.work/PROTOCOL_CORE.md): invariants and the file-based coordination model.
- [Communications protocol](https://turnfile.work/COMMUNICATIONS_PROTOCOL.md): mailbox message lifecycle and SLA tiers.
- [Human governance](https://turnfile.work/HUMAN_GOVERNANCE.md): the maintainer-as-arbiter decision contract.
- [Conflict resolution](https://turnfile.work/CONFLICT_RESOLUTION.md): structured disagreement and the rebuttal-loop bound.
- [Boot sequence](https://turnfile.work/BOOT_SEQUENCE.md): the canonical, cross-agent boot command manifest (read order + verification gates).
- [LLM onboarding](https://turnfile.work/LLM_ONBOARDING.md): how a new agent joins a Turnfile project.
- [Conformance](https://github.com/snapsynapse/turnfile/blob/main/CONFORMANCE.md): testable conformance claims for the protocol.

## How it works

- File-based, not API-based: mailbox, worklog, PRD gates, and the Turnfile coordination artifact are all plain markdown/YAML, readable and recoverable without specialized tooling.
- Eight-step eval-gated implementation loop (PRD-006 A1) with builder/reviewer separation: the agent that authors a contract's evals does not implement it; the counterpart implements; the author reviews.
- Model-agnostic: one unmodified protocol has run across Claude Opus 4.6, Fable 5, Opus 4.8, and Opus 4.7, alongside OpenAI Codex (GPT-5) and Google Gemini (Gemini 3.5 Flash (High), full-active since session 21 under PRD-015).

## Related patterns

- [AIDR](https://aidr.work/) (AI Decision Records): the minimal single-artifact expression of this protocol, spun out of Turnfile on 2026-07-02. One markdown file per consequential decision — independent positions, preserved dissent, human-only arbitration — with no session lifecycle, mailbox or closeout. AIDR is the front door; Turnfile is the advanced profile. Lineage is by citation: no shared code, no shared history, neither depends on the other.

## More

- [Source repository](https://github.com/snapsynapse/turnfile): full history, PRDs, tools, and the inception archive of two agents building the protocol together.
- [README](https://github.com/snapsynapse/turnfile/blob/main/README.md): project overview and the full PRD status index.