docs: add molecular chemistry documentation (bd-ul59)

Create docs/MOLECULES.md with comprehensive coverage of: - Layer cake architecture (formulas → protos → molecules → epics → issues) - Phase metaphor (solid/proto, liquid/mol, vapor/wisp) - Phase transitions (pour, wisp create, squash, burn) - Bonding patterns (proto+proto, proto+mol, mol+mol) - Agent pitfalls (temporal language, forgetting to squash) - Orphan vs stale matrix - Progress tracking (computed, not stored) - Parallelism model (default parallel, opt-in sequential) Update CLI_REFERENCE.md with Molecular Chemistry section covering: - Proto/template commands - Pour command - Wisp commands - Bonding commands - Squash and burn commands Update ARCHITECTURE.md with cross-reference to new MOLECULES.md. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-24 19:30:59 -08:00
parent fbae7711bc
commit 5e971bd90a
3 changed files with 417 additions and 0 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -269,6 +269,8 @@ open ──▶ in_progress ──▶ closed

 **Molecules** are template work items that define structured workflows. When spawned, they create **wisps** - ephemeral child issues that track execution steps.

+> **For full documentation** on the molecular chemistry metaphor (protos, pour, bond, squash, burn), see [MOLECULES.md](MOLECULES.md).
+
 ### Wisp Lifecycle

 ```
@@ -317,6 +319,7 @@ The `bd mol squash` command uses hard delete intentionally - tombstones would be

 ## Related Documentation

+- [MOLECULES.md](MOLECULES.md) - Molecular chemistry metaphor (protos, pour, bond, squash, burn)
 - [INTERNALS.md](INTERNALS.md) - FlushManager, Blocked Cache implementation details
 - [DAEMON.md](DAEMON.md) - Daemon management and configuration
 - [EXTENDING.md](EXTENDING.md) - Adding custom tables to SQLite
--- a/docs/CLI_REFERENCE.md
+++ b/docs/CLI_REFERENCE.md
@@ -10,6 +10,7 @@
 - [Dependencies & Labels](#dependencies--labels)
 - [Filtering & Search](#filtering--search)
 - [Advanced Operations](#advanced-operations)
+- [Molecular Chemistry](#molecular-chemistry)
 - [Database Management](#database-management)
 - [Editor Integration](#editor-integration)

@@ -340,6 +341,116 @@ bd rename-prefix kw- --dry-run  # Preview changes
 bd rename-prefix kw- --json     # Apply rename
 ```

+## Molecular Chemistry
+
+Beads uses a chemistry metaphor for template-based workflows. See [MOLECULES.md](MOLECULES.md) for full documentation.
+
+### Phase Transitions
+
+| Phase | State | Storage | Command |
+|-------|-------|---------|---------|
+| Solid | Proto | `.beads/` | `bd mol catalog` |
+| Liquid | Mol | `.beads/` | `bd pour` |
+| Vapor | Wisp | `.beads-wisp/` | `bd wisp create` |
+
+### Proto/Template Commands
+
+```bash
+# List available protos (templates)
+bd mol catalog --json
+
+# Show proto structure and variables
+bd mol show <proto-id> --json
+
+# Extract proto from ad-hoc epic
+bd mol distill <epic-id> --json
+```
+
+### Pour (Proto to Mol)
+
+```bash
+# Instantiate proto as persistent mol (solid → liquid)
+bd pour <proto-id> --var key=value --json
+
+# Preview what would be created
+bd pour <proto-id> --var key=value --dry-run
+
+# Assign root issue
+bd pour <proto-id> --var key=value --assignee alice --json
+
+# Attach additional protos during pour
+bd pour <proto-id> --attach <other-proto> --json
+```
+
+### Wisp Commands
+
+```bash
+# Instantiate proto as ephemeral wisp (solid → vapor)
+bd wisp create <proto-id> --var key=value --json
+
+# List all wisps
+bd wisp list --json
+bd wisp list --all --json    # Include closed
+
+# Garbage collect orphaned wisps
+bd wisp gc --json
+bd wisp gc --age 24h --json  # Custom age threshold
+bd wisp gc --dry-run         # Preview what would be cleaned
+```
+
+### Bonding (Combining Work)
+
+```bash
+# Polymorphic combine - handles proto+proto, proto+mol, mol+mol
+bd mol bond <A> <B> --json
+
+# Bond types
+bd mol bond <A> <B> --type sequential --json   # B runs after A (default)
+bd mol bond <A> <B> --type parallel --json     # B runs alongside A
+bd mol bond <A> <B> --type conditional --json  # B runs only if A fails
+
+# Phase control
+bd mol bond <proto> <mol> --pour --json   # Force persistent spawn
+bd mol bond <proto> <mol> --wisp --json   # Force ephemeral spawn
+
+# Dynamic bonding (custom child IDs)
+bd mol bond <proto> <mol> --ref arm-{{name}} --var name=ace --json
+
+# Preview bonding
+bd mol bond <A> <B> --dry-run
+```
+
+### Squash (Wisp to Digest)
+
+```bash
+# Compress wisp to permanent digest
+bd mol squash <wisp-id> --json
+
+# With agent-provided summary
+bd mol squash <wisp-id> --summary "Work completed" --json
+
+# Preview
+bd mol squash <wisp-id> --dry-run
+
+# Keep wisp children after squash
+bd mol squash <wisp-id> --keep-children --json
+```
+
+### Burn (Discard Wisp)
+
+```bash
+# Delete wisp without digest (destructive)
+bd mol burn <wisp-id> --json
+
+# Preview
+bd mol burn <wisp-id> --dry-run
+
+# Skip confirmation
+bd mol burn <wisp-id> --force --json
+```
+
+**Note:** Most mol commands require `--no-daemon` flag when daemon is running.
+
 ## Database Management

 ### Import/Export
@@ -604,6 +715,7 @@ See also:
 ## See Also

 - [AGENTS.md](../AGENTS.md) - Main agent workflow guide
+- [MOLECULES.md](MOLECULES.md) - Molecular chemistry metaphor (protos, pour, bond, squash, burn)
 - [DAEMON.md](DAEMON.md) - Daemon management and event-driven mode
 - [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - Git workflows and merge strategies
 - [LABELS.md](../LABELS.md) - Label system guide
--- a/docs/MOLECULES.md
+++ b/docs/MOLECULES.md
@@ -0,0 +1,302 @@
+# Molecular Chemistry in Beads
+
+This document explains beads' molecular chemistry metaphor for template-based workflows.
+
+## The Layer Cake
+
+Beads has a layered architecture where each layer builds on the one below:
+
+```
+Formulas (YAML compile-time macros)
+    ↓
+Protos (template issues, read-only)
+    ↓
+Molecules (pour, bond, squash, burn)
+    ↓
+Epics (parent-child, dependencies) ← DATA PLANE
+    ↓
+Issues (JSONL, git-backed) ← STORAGE
+```
+
+**Key insight:** Molecules work without protos. You can create ad-hoc molecules (epics with children) directly. Protos are templates FOR molecules, not the other way around.
+
+## Phase Metaphor
+
+The chemistry metaphor uses phase transitions to describe where work lives:
+
+| Phase | State | Storage | Synced | Use Case |
+|-------|-------|---------|--------|----------|
+| **Solid** | Proto | `.beads/` | Yes | Reusable templates |
+| **Liquid** | Mol | `.beads/` | Yes | Persistent work |
+| **Vapor** | Wisp | `.beads-wisp/` | No | Ephemeral operations |
+
+### Phase Transitions
+
+```
+Proto (solid) ──pour──→ Mol (liquid)    # Persistent instantiation
+Proto (solid) ──wisp──→ Wisp (vapor)    # Ephemeral instantiation
+Wisp (vapor) ──squash──→ Digest (solid) # Compress to permanent record
+Wisp (vapor) ──burn──→ (nothing)        # Discard without trace
+```
+
+## Core Concepts
+
+### Protos (Templates)
+
+A proto is an issue with the `template` label. It defines a reusable pattern of work:
+
+```bash
+# List available protos
+bd mol catalog
+
+# Show proto structure
+bd mol show <proto-id>
+```
+
+Protos can contain:
+- Template variables using `{{variable}}` syntax
+- Hierarchical child issues (subtasks)
+- Dependencies between children
+
+### Molecules (Instances)
+
+A molecule is a spawned instance of a proto (or an ad-hoc epic). When you "pour" a proto, you create real issues from the template:
+
+```bash
+# Pour: proto → persistent mol (liquid phase)
+bd pour <proto-id> --var key=value
+
+# The mol lives in .beads/ and is synced with git
+```
+
+### Wisps (Ephemeral Molecules)
+
+Wisps are ephemeral molecules for operational workflows that shouldn't accumulate:
+
+```bash
+# Wisp: proto → ephemeral wisp (vapor phase)
+bd wisp create <proto-id> --var key=value
+
+# The wisp lives in .beads-wisp/ and is NOT synced
+```
+
+Use wisps for:
+- Patrol cycles (deacon, witness)
+- Health checks and monitoring
+- One-shot orchestration runs
+- Routine operations with no audit value
+
+### Bonding (Combining Work)
+
+The `bond` command polymorphically combines protos and molecules:
+
+```bash
+# proto + proto → compound proto (reusable template)
+bd mol bond mol-feature mol-deploy
+
+# proto + mol → spawn proto, attach to molecule
+bd mol bond mol-review bd-abc123
+
+# mol + mol → join into compound molecule
+bd mol bond bd-abc123 bd-def456
+```
+
+Bond types:
+- `sequential` (default) - B runs after A completes
+- `parallel` - B runs alongside A
+- `conditional` - B runs only if A fails
+
+Phase control for bonding:
+```bash
+# Force spawn as liquid (persistent), even when attaching to wisp
+bd mol bond mol-critical-bug wisp-patrol --pour
+
+# Force spawn as vapor (ephemeral), even when attaching to mol
+bd mol bond mol-temp-check bd-feature --wisp
+```
+
+### Squashing (Compressing)
+
+Squash compresses a wisp's execution into a permanent digest:
+
+```bash
+# Squash wisp → permanent digest
+bd mol squash <wisp-id>
+
+# With agent-provided summary
+bd mol squash <wisp-id> --summary "Brief description of what was done"
+
+# Preview what would be squashed
+bd mol squash <wisp-id> --dry-run
+```
+
+### Burning (Discarding)
+
+Burn deletes a wisp without creating any digest:
+
+```bash
+# Delete wisp with no trace
+bd mol burn <wisp-id>
+
+# Preview what would be deleted
+bd mol burn <wisp-id> --dry-run
+```
+
+## Lifecycle Patterns
+
+### Patrol Cycle (Ephemeral)
+
+```
+1. bd wisp create mol-patrol    # Create ephemeral wisp
+2. (execute patrol steps)       # Work through children
+3. bd mol squash <id>           # Compress to digest
+   # or
+   bd mol burn <id>             # Discard without trace
+```
+
+### Feature Work (Persistent)
+
+```
+1. bd pour mol-feature --var name=auth    # Create persistent mol
+2. (implement feature)                     # Work through children
+3. bd close <children>                     # Complete subtasks
+4. bd close <root>                         # Complete the feature
+```
+
+### Dynamic Bonding (Christmas Ornament Pattern)
+
+Attach work dynamically using custom IDs:
+
+```bash
+# Spawn per-worker arms on a patrol
+bd mol bond mol-polecat-arm bd-patrol --ref arm-{{name}} --var name=ace
+# Creates: bd-patrol.arm-ace (and children like bd-patrol.arm-ace.capture)
+```
+
+## Progress Tracking
+
+Molecule progress is **computed, not stored**:
+
+- `progress.Completed` = count of closed children
+- `progress.Total` = count of all children
+
+This means:
+- No state to get out of sync
+- Dynamic fanout works automatically (new children increase Total)
+- Closing children increases Completed
+
+## Parallelism Model
+
+**Default: Parallel.** Issues without `depends_on` relationships run in parallel.
+
+**Opt-in Sequential:** Add blocking dependencies to create sequence:
+
+```bash
+# phase-2 depends on phase-1 (phase-1 must complete first)
+bd dep add phase-2 phase-1
+```
+
+**Cognitive trap:** Temporal language ("Phase 1 comes before Phase 2") inverts dependencies. Think requirements: "Phase 2 **needs** Phase 1."
+
+## Common Agent Pitfalls
+
+### 1. Temporal Language Inverting Dependencies
+
+**Wrong thinking:** "Phase 1 comes before Phase 2" → `bd dep add phase1 phase2`
+
+**Right thinking:** "Phase 2 needs Phase 1" → `bd dep add phase2 phase1`
+
+**Solution:** Use requirement language, not temporal language. Verify with `bd blocked`.
+
+### 2. Confusing Protos with Molecules
+
+- **Proto** = Template (has `template` label, read-only pattern)
+- **Molecule** = Instance (real work, created by pour/wisp)
+
+You can create molecules without protos (ad-hoc epics). Protos are just reusable patterns.
+
+### 3. Forgetting to Squash/Burn Wisps
+
+Wisps accumulate in `.beads-wisp/` if not cleaned up. At session end:
+
+```bash
+bd wisp list                    # Check for orphaned wisps
+bd mol squash <id> --summary "" # Compress to digest
+# or
+bd mol burn <id>                # Discard if not needed
+# or
+bd wisp gc                      # Garbage collect old wisps
+```
+
+### 4. Thinking Phases Imply Sequence
+
+Phases, steps, or numbered items in a plan do NOT create sequence. Only dependencies do.
+
+```bash
+# These tasks run in PARALLEL (no dependencies)
+bd create "Step 1: Do X" ...
+bd create "Step 2: Do Y" ...
+bd create "Step 3: Do Z" ...
+
+# Add dependencies to create sequence
+bd dep add step2 step1    # step2 needs step1
+bd dep add step3 step2    # step3 needs step2
+```
+
+## Orphan vs Stale Matrix
+
+A molecule can be in one of four states based on two dimensions:
+
+| | Assigned | Unassigned |
+|---|---|---|
+| **Blocking** | Active work | Orphaned (needs pickup) |
+| **Not blocking** | In progress | Stale (complete but unclosed) |
+
+- **Orphaned:** Complete-but-unclosed molecules blocking other assigned work
+- **Stale:** Complete-but-unclosed molecules not blocking anything
+
+Graph pressure (blocking other work) determines urgency, not time.
+
+## Commands Reference
+
+### Proto/Template Commands
+
+```bash
+bd mol catalog                  # List available protos
+bd mol show <id>                # Show proto/molecule structure
+bd mol distill <epic-id>        # Extract proto from ad-hoc epic
+```
+
+### Phase Transition Commands
+
+```bash
+bd pour <proto> --var k=v       # Proto → Mol (liquid)
+bd wisp create <proto> --var k=v # Proto → Wisp (vapor)
+bd mol squash <id>              # Wisp → Digest (solid)
+bd mol burn <id>                # Wisp → nothing
+```
+
+### Bonding Commands
+
+```bash
+bd mol bond <A> <B>             # Polymorphic combine
+bd mol bond <A> <B> --type parallel
+bd mol bond <A> <B> --pour      # Force persistent
+bd mol bond <A> <B> --wisp      # Force ephemeral
+bd mol bond <A> <B> --ref <ref> # Dynamic child ID
+```
+
+### Wisp Management
+
+```bash
+bd wisp list                    # List all wisps
+bd wisp list --all              # Include closed
+bd wisp gc                      # Garbage collect orphaned wisps
+bd wisp gc --age 24h            # Custom age threshold
+```
+
+## Related Documentation
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) - Overall bd architecture
+- [CLI_REFERENCE.md](CLI_REFERENCE.md) - Complete command reference
+- [../CLAUDE.md](../CLAUDE.md) - Quick reference for agents