Q: What makes Beads fundamentally different from Kelly's pipeline state tracking?

Short answer: Beads are a universal work primitive where the reasoning (the "why") is the primary citizen, not a sidecar — and everything (work items, messages, quality gates, patrol routes) lives in a single git-versioned, SQL-queryable substrate. Kelly has four separate mechanisms (pipeline state JSON, done markers, TEA audit narratives, heartbeat files) that each track a different aspect of work with no unified queryability. The architectural difference is unification vs. siloing.

What Are Beads?

Beads are defined in steve-yegge-beads as the atomic unit of work in the Gas Town / Gas City ecosystem. Every discrete unit of work — a code task, a message, a coordination signal, a patrol route, a quality gate — is a Bead.

Beads are:
- Git-versioned — every state transition is a commit with author, timestamp, and reason
- SQL-queryable via Dolt — Git-for-SQL database; run queries against the work ledger
- Immutable once finalized — change tracked via explicit forking and merging (Dolt's model)
- Typed — type, status, reason, parent_bead_id, author, created_at fields

The Core Insight: Git Stores the Wrong Four Fields

Git records What, Where, Who, and How. But for AI-augmented software development, the hard part is Why — the intent, the reasoning chain, the decision history.

Beads capture Why as a first-class field. The Bead's reason field answers "why was this approach chosen over that one?" — stored permanently, not lost in a commit message that will be rewritten or lost in a merge.

"Git stores What/Where/Who/How. Beads store Why." — steve-yegge-gas-town

Beads as Universal Data Plane

Beads are not just for tracking project tasks. In Gas Town, they are the universal data plane — the single medium through which all work, coordination, and messaging flows:

  • Project tasks → Beads (epics decomposed into bead sequences)
  • Orchestration flows → Beads (Mayor's handoff instructions to Refinery)
  • Messages between agents → Beads (with full context preserved)
  • Patrol routes → Beads (structured work items the Deacon assigns to itself)
  • Quality gate results → Beads (Witness output recorded as structured data)
  • Reputation stamps → Beads (Wasteland attestations attached to work items)

Because everything is a Bead, everything is git-versioned, branchable, queryable, and auditable via SQL.

Kelly's Four Separate Mechanisms

kelly-factory-overview and kelly-gas-town-gap-analysis describe Kelly's state tracking across four separate mechanisms:

1. Pipeline State

A JSON file tracking current stage, subphase, timestamps. Machine-readable, but:
- Single point-in-time snapshot per project
- No history of state transitions
- Can't be queried across projects (no SQL interface)
- Not git-versioned

2. Done Markers per Subphase

Text signals written to a file when a subphase completes (e.g., echo "DONE" >> research-done.txt). These are:
- Human-readable but not machine-queryable in any structured sense
- No typed fields, no state machine
- Not git-versioned — no audit trail of when done or why this approach
- Simple but siloed

3. TEA Audit (Structured Narrative)

The Test → Evaluate → Assess audit produces a tea-summary.md with a gate decision (PASS / PASS-WITH-FOLLOWUPS / REMEDIATE). This is the closest Kelly gets to Beads' "why" capture, but:
- It's a narrative sidecar, not the work item itself
- Not structured for SQL queries — grep-readable but not queryable
- Not git-versioned in the Beads sense
- TEA is a stage-gate (before release), not continuous

4. Heartbeat

Agent liveness file updated periodically. Detects stuck agents by absence of updates. Not git-versioned, not SQL-queryable.

The Fundamental Difference: Unification vs. Silos

Dimension Beads (Gas Town) Kelly's 4 Mechanisms
Substrate Single unified store (Dolt) 4 separate files/systems
Queryability SQL across all work items No cross-mechanism queries
Git-versioned Yes — every transition is a commit No — done markers and TEA are append-only
Reason capture First-class reason field on every Bead TEA audit captures reasoning as narrative sidecar
State machine Typed states (pending → running → done/failed) per Bead No unified state machine
Cross-project queries One SQL query across all projects Requires grep across project directories
Branch and experiment Branch a Bead sequence to try an alternative approach No equivalent — pipeline is linear
Forensic audit Full history of every Bead, who authored it, why TEA audit narrative is closest; not structurally complete
Work item IS the audit Bead's git history IS the audit trail TEA is a separate document from the work it audits

The Semantic Gap

The kelly-gas-town-gap-analysis evaluates each Kelly mechanism against Beads:

  • Done markers → Bead state transitions: Natural mapping. Adopt.
  • TEA audit → Bead quality gate: Strongest semantic match. Adopt with schema design.
  • Pipeline state → Bead JSON view: Needs a JSON view on top of Beads. Partial adopt.
  • Memory → Bead graph: Requires careful human-interface design. Partial adopt.

The semantic coverage is there; the architectural integration is not. Kelly has file-based equivalents for all Bead functions, but none of them are unified. Beads would replace four separate mechanisms with a single git-versioned, SQL-queryable substrate.

What "Bead-as-Why" Means Practically

The key distinction is that in Beads, the reason field IS the Bead's primary data, not metadata attached to it. In Kelly's system, the "why" is captured in the TEA audit narrative — a separate document. The TEA audit tells you what reasoning happened; a Bead's reason field is the reasoning.

Practically, this means:
- You can query: "Show me all quality gates in the last 30 days where reason mentions 'security'" — one SQL query in Beads; grep across narrative files in Kelly
- A new agent can reconstruct a project's full decision history by traversing the Bead DAG — in Kelly, it requires reading daily logs in chronological order
- Cross-agent knowledge is shared via Dolt — in Kelly, each agent's memory is per-agent unless explicitly shared via files

The Combined Kelly + Gas Town Architecture

The kelly-gas-town-gap-analysis proposes a hybrid:

"Kelly's 5-layer memory (narrative layers 1–3) + Beads/MEOW for structured work (layer 4–5) + SQL-based observability built on Dolt"

This would give Kelly:
- Narrative richness at layers 1–3 (what Beads calls the "human write path")
- Unified, queryable work substrate at layers 4–5
- SQL observability across all work items without losing the human-readable file interface

The file interface (done markers, pipeline state, memory) would be preserved as view layers generated from Dolt queries — humans read files, machines query Dolt.

DoltHub's "Cursor for Everything" Pattern (2025-11-19)

DoltHub's cursor-for-everything article provides a practical application of the same Dolt version control that Beads uses. Their "5-step recipe" (chat panel → LLM → MCP tools → Dolt DB → version control UI) shows how Dolt's branch/commit/diff/merge primitives enable safe agentic writes in any database-backed application. The "branch-aware writes" pattern — LLMs write on branches, user reviews diff before merge — is the same safety mechanism Beads provides for work tracking, applied to application data.

This reinforces the Beads thesis: Dolt's version control for agentic writes is the same underlying technology, and the "Cursor for Everything" pattern is essentially what Beads does for project work, generalized to application data.

Concrete Implementation: Agent Mode in Dolt Workbench (2026-02-09)

DoltHub's cursor-for-sql-agent-mode article shows the Cursor for Everything pattern fully implemented as a working product. Two key patterns emerge:

  • commit-confirmation-pattern — Agent holds writes until user reviews diff and explicitly confirms. This is the enforcement mechanism that makes branch-aware writes trustworthy. Without it, the agent could commit bad data at any moment.
  • visual-diff-data-apps — Yellow table highlights, "Show Changed Rows Only" view, uncommitted changes panel. The UX layer that makes diff review possible in data applications (analogous to code diff views in Git GUIs).

The MySQL comparison demonstrates the danger: without version control, agent writes are fire-and-forget with no safety net. This reinforces the Beads thesis — version control is a prerequisite, not a nice-to-have.