johno/gastown
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Update beads-data-plane.md with three-tier architecture

Browse Source 
- 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>
This commit is contained in:
Steve Yegge
2025-12-23 14:29:13 -08:00
parent 0a8234ba78
commit 804dc75722
1 changed files with 25 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/beads-data-plane.md
View File

@@ -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