From 804dc75722d70d942b5359c31f4b373f0bbcb9d5 Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Tue, 23 Dec 2025 14:29:13 -0800
Subject: [PATCH] Update beads-data-plane.md with three-tier architecture
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Renamed from "Two-Level" to "Three-Tier" to include wisps
- Added rig wisps tier (.beads-wisp/) for ephemeral patrol state
- Clarified deacon uses town beads (not rig beads)
- Added git tracking status for each tier

Related: gt-ci84 (deacon wisp storage bug)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/beads-data-plane.md | 32 +++++++++++++++++++++++++-------
 1 file changed, 25 insertions(+), 7 deletions(-)

diff --git a/docs/beads-data-plane.md b/docs/beads-data-plane.md
index 642126c2..7423f25e 100644
--- a/docs/beads-data-plane.md
+++ b/docs/beads-data-plane.md
@@ -112,18 +112,20 @@ How does the system know if an issue is mail or work?
 
 The `from:` label is the canonical discriminator. Regular issues don't have senders.
 
-## Two-Level Beads Architecture
+## Three-Tier Beads Architecture
 
-Gas Town uses beads at two levels:
+Gas Town uses beads at three tiers - two persistent, one ephemeral:
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │  TOWN LEVEL: ~/gt/.beads/                                   │
 │  ─────────────────────────────────────────────────────────  │
 │  Prefix: hq-*                                               │
+│  Git tracked: Yes                                           │
 │  Contains:                                                  │
 │    - All mail (cross-agent communication)                   │
 │    - Mayor coordination issues                              │
+│    - Deacon patrol wisps (town-level ephemeral work)        │
 │    - Cross-rig work items                                   │
 │  Sync: Direct commit to main (single location)              │
 └─────────────────────────────────────────────────────────────┘
@@ -131,21 +133,37 @@ Gas Town uses beads at two levels:
          │ gt mail commands auto-route here
          ▼
 ┌─────────────────────────────────────────────────────────────┐
-│  RIG LEVEL: ~/gt/gastown/crew/max/.beads/                   │
+│  RIG LEVEL: ~/gt/<rig>/crew/<name>/.beads/                  │
 │  ─────────────────────────────────────────────────────────  │
-│  Prefix: gt-*                                               │
+│  Prefix: gt-* (or rig-specific)                             │
+│  Git tracked: Yes (via beads-sync branch)                   │
 │  Contains:                                                  │
 │    - Project issues (bugs, features, tasks)                 │
 │    - Molecules (work patterns)                              │
-│    - Agent hook states                                      │
+│    - Agent hook states (pinned molecules)                   │
 │  Sync: Via beads-sync branch (multiple clones)              │
+└─────────────────────────────────────────────────────────────┘
+         │
+         │ Ephemeral patrol state (not synced)
+         ▼
+┌─────────────────────────────────────────────────────────────┐
+│  RIG WISPS: ~/gt/<rig>/.beads-wisp/                         │
+│  ─────────────────────────────────────────────────────────  │
+│  Git tracked: NO (gitignored)                               │
+│  Contains:                                                  │
+│    - Witness patrol cycles                                  │
+│    - Refinery patrol cycles                                 │
+│    - Any rig-level ephemeral molecule execution             │
+│  Lifecycle: Created → Executed → Squashed to digest → Deleted│
 └─────────────────────────────────────────────────────────────┘
 ```
 
 Key points:
-- **Mail always uses town beads** (`~/gt/.beads/`) - `gt mail` routes automatically
+- **Mail uses town beads** (`~/gt/.beads/`) - `gt mail` routes automatically
+- **Deacon uses town beads** - town-level role, no rig dependency
 - **Project work uses rig beads** (in your clone) - `bd` commands use local `.beads/`
-- **Different sync strategies**: Town is single-writer, rig uses branch-based sync
+- **Patrol wisps use rig wisp storage** - ephemeral, never synced, squashed after cycles
+- **Different sync strategies**: Town is single-writer, rig uses branch-based sync, wisps don't sync
 
 ## The Query Model