From 98d665c6fdd7e30a95b878deba775e6db9c4b3e9 Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Sun, 21 Dec 2025 21:08:51 -0800
Subject: [PATCH] docs: add Wisps and Molecules architecture section

Document that wisps are intentionally local-only and use hard delete
instead of tombstones. This is by design - wisps never sync to other
clones, so tombstones are unnecessary overhead.

Closes bd-4bsb
---
 docs/ARCHITECTURE.md | 50 ++++++++++++++++++++++++++++++++++++++++++++
 docs/DELETIONS.md    | 37 ++++++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index e1d37f37..514e5223 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -265,6 +265,56 @@ open ──▶ in_progress ──▶ closed
 | Import logic | `cmd/bd/import.go`, `internal/importer/` |
 | Auto-sync | `internal/autoimport/`, `internal/flush/` |
 
+## Wisps and Molecules
+
+**Molecules** are template work items that define structured workflows. When spawned, they create **wisps** - ephemeral child issues that track execution steps.
+
+### Wisp Lifecycle
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   bd mol spawn  │───▶│  Wisp Issues    │───▶│  bd mol squash  │
+│   (from template)│    │  (local-only)   │    │  (→ digest)     │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+1. **Spawn:** Create wisps from a molecule template
+2. **Execute:** Agent works through wisp steps (local SQLite only)
+3. **Squash:** Compress wisps into a permanent digest issue
+
+### Why Wisps Don't Sync
+
+Wisps are intentionally **local-only**:
+
+- They exist only in the spawning agent's SQLite database
+- They are **never exported to JSONL**
+- They cannot resurrect from other clones (they were never there)
+- They are **hard-deleted** when squashed (no tombstones needed)
+
+This design enables:
+
+- **Fast local iteration:** No sync overhead during execution
+- **Clean history:** Only the digest (outcome) enters git
+- **Agent isolation:** Each agent's execution trace is private
+- **Bounded storage:** Wisps don't accumulate across clones
+
+### Wisp vs Regular Issue Deletion
+
+| Aspect | Regular Issues | Wisps |
+|--------|---------------|-------|
+| Exported to JSONL | Yes | No |
+| Tombstone on delete | Yes | No |
+| Can resurrect | Yes (without tombstone) | No (never synced) |
+| Deletion method | `CreateTombstone()` | `DeleteIssue()` (hard delete) |
+
+The `bd mol squash` command uses hard delete intentionally - tombstones would be wasted overhead for data that never leaves the local database.
+
+### Future Directions
+
+- **Separate wisp repo:** Keep wisps in a dedicated ephemeral git repo
+- **Digest migration:** Explicit step to promote digests to main repo
+- **Wisp retention:** Option to preserve wisps in local git history
+
 ## Related Documentation
 
 - [INTERNALS.md](INTERNALS.md) - FlushManager, Blocked Cache implementation details
diff --git a/docs/DELETIONS.md b/docs/DELETIONS.md
index 56c4e92e..7a564d00 100644
--- a/docs/DELETIONS.md
+++ b/docs/DELETIONS.md
@@ -200,8 +200,45 @@ Clock skew between machines can cause issues:
 
 The 1-hour grace period ensures tombstones propagate even with minor clock drift.
 
+## Wisps: Intentional Tombstone Bypass
+
+**Wisps** (ephemeral issues created by `bd mol spawn`) are intentionally excluded from tombstone tracking.
+
+### Why Wisps Don't Need Tombstones
+
+Tombstones exist to prevent resurrection during sync. Wisps don't sync:
+
+| Property | Regular Issues | Wisps |
+|----------|---------------|-------|
+| Exported to JSONL | Yes | No |
+| Synced to other clones | Yes | No |
+| Can resurrect | Yes | No |
+| Tombstone on delete | Yes | No (hard delete) |
+
+Since wisps never leave the local SQLite database, they cannot resurrect from remote clones. Creating tombstones for them would be unnecessary overhead.
+
+### How Wisp Deletion Works
+
+When `bd mol squash` compresses wisps into a digest:
+
+1. The digest issue is created (permanent, syncs normally)
+2. Wisp children are **hard-deleted** via `DeleteIssue()`
+3. No tombstones are created
+4. The wisps simply disappear from local SQLite
+
+This is intentional, not a bug. See [ARCHITECTURE.md](ARCHITECTURE.md#wisps-and-molecules) for the full design rationale.
+
+### If You Need Wisp History
+
+Wisps exist in local git history (SQLite database commits) until garbage collected. Future enhancements may include:
+
+- Separate ephemeral repository for wisp storage
+- Explicit migration step to promote wisps to permanent storage
+- Configurable wisp retention policies
+
 ## Related
 
+- [ARCHITECTURE.md](ARCHITECTURE.md) - Overall architecture including Wisps and Molecules
 - [CONFIG.md](CONFIG.md) - Configuration options
 - [DAEMON.md](DAEMON.md) - Daemon auto-sync behavior
 - [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - General troubleshooting