diff --git a/docs/chemistry-design-changes.md b/docs/chemistry-design-changes.md new file mode 100644 index 00000000..f735b07e --- /dev/null +++ b/docs/chemistry-design-changes.md @@ -0,0 +1,375 @@ +# Chemistry Design Changes + +> Implementation roadmap for the molecular chemistry UX described in +> `molecular-chemistry.md` + +## Summary of Changes + +The chemistry metaphor requires the following changes to Beads and Gas Town: + +### Beads Changes + +| Change | Priority | Issue | +|--------|----------|-------| +| Add `bd pour` command (alias for `bd mol spawn --pour`) | P0 | Create | +| Add `bd wisp` command (alias for `bd mol spawn`) | P0 | Create | +| Add `bd pin` command for agent attachment | P1 | Create | +| Add `bd hook` command for hook inspection | P2 | Create | +| Rename `--persistent` to `--pour` in `bd mol spawn` | P0 | Update | +| Add `--pour` flag to `bd mol bond` | P1 | Update | +| Implement digest ID reservation for wisps | P1 | Create | + +### Gas Town Changes + +| Change | Priority | Issue | +|--------|----------|-------| +| Update daemon: remove permanent attachment for patrol | P0 | gt-3x0z.9 | +| Update deacon.md.tmpl: use wisp-based patrol | P0 | gt-3x0z.9 | +| Update witness.md.tmpl: use wisp-based patrol | P1 | Create | +| Add `gt hook` command (thin wrapper around `bd hook`) | P2 | Create | + +--- + +## Detailed Specifications + +### 1. `bd pour` Command + +**Purpose:** Instantiate a proto as a persistent mol (liquid phase). + +**Syntax:** +```bash +bd pour [flags] + +Flags: + --var strings Variable substitution (key=value) + --assignee Assign the root issue to this agent + --dry-run Preview what would be created +``` + +**Implementation:** +- Alias/wrapper for `bd mol spawn --pour` +- Default behavior: creates mol in permanent `.beads/` storage +- Returns the head bead ID of the created mol + +**Example:** +```bash +bd pour mol-feature --var name=auth +# Output: Created mol bd-abc123 from mol-feature +``` + +--- + +### 2. `bd wisp` Command + +**Purpose:** Instantiate a proto as an ephemeral wisp (vapor phase). + +**Syntax:** +```bash +bd wisp [flags] + +Flags: + --var strings Variable substitution (key=value) + --dry-run Preview what would be created +``` + +**Implementation:** +- Alias/wrapper for `bd mol spawn ` (wisp is default) +- Creates wisp in `.beads-wisp/` storage +- Reserves digest ID in permanent storage (placeholder) + +**Example:** +```bash +bd wisp mol-patrol +# Output: Created wisp bd-xyz789 from mol-patrol +``` + +--- + +### 3. `bd pin` Command + +**Purpose:** Attach a mol to an agent's hook (work assignment). + +**Syntax:** +```bash +bd pin [flags] + +Flags: + --for string Agent to pin work for (default: current agent) +``` + +**Implementation:** +1. Look up the mol by ID +2. Set `pinned: true` on the mol's head bead +3. Set `assignee` to the target agent +4. Update `status` to `in_progress` if not already + +**Example:** +```bash +# Pin to myself +bd pin bd-abc123 + +# Pin to specific agent (Witness assigning work) +bd pin bd-abc123 --for polecat-ace +``` + +**Unpin:** +```bash +bd unpin [mol-id] +# Clears pinned flag, optionally releases assignee +``` + +--- + +### 4. `bd hook` Command + +**Purpose:** Inspect what's on an agent's hook. + +**Syntax:** +```bash +bd hook [flags] + +Flags: + --agent string Agent to inspect (default: current agent) + --json Output in JSON format +``` + +**Implementation:** +- Query beads for issues where `pinned: true` AND `assignee: ` +- Display the mol(s) attached to the hook + +**Example:** +```bash +bd hook +# Output: +# Hook: polecat-ace +# Pinned: bd-abc123 (mol-feature) - in_progress +# Step: implement (2 of 5) + +bd hook --agent deacon +# Output: +# Hook: deacon +# (empty - patrol uses wisps, no persistent attachment) +``` + +--- + +### 5. Rename `--persistent` to `--pour` + +**Current:** +```bash +bd mol spawn mol-feature --persistent +``` + +**New:** +```bash +bd mol spawn mol-feature --pour +# or simply: +bd pour mol-feature +``` + +**Migration:** +- Keep `--persistent` as deprecated alias +- Log warning when `--persistent` is used +- Remove in next major version + +--- + +### 6. Add `--pour` flag to `bd mol bond` + +**Purpose:** Override phase when spawning protos during bond. + +**Current behavior:** +- Phase follows target (mol → liquid, wisp → vapor) +- `--wisp` forces vapor + +**New:** +- Add `--pour` to force liquid even when target is vapor + +```bash +# Found important bug during patrol, make it a real issue +bd mol bond mol-critical-bug wisp-patrol-123 --pour +``` + +--- + +### 7. Digest ID Reservation + +**Problem:** When a wisp is created and later squashed, the digest should +have the same ID so cross-phase references remain valid. + +**Solution:** Reserve the ID on wisp creation. + +**Implementation:** + +1. **On wisp creation (`bd wisp`):** + - Generate the head bead ID + - Write a placeholder to permanent beads: + ```json + { + "id": "bd-xyz789", + "title": "[Wisp Placeholder]", + "status": "open", + "labels": ["wisp-placeholder"], + "description": "Reserved for wisp digest" + } + ``` + - Create actual wisp in `.beads-wisp/` with same ID + +2. **On squash (`bd mol squash`):** + - Replace placeholder with actual digest content + - Delete wisp from `.beads-wisp/` + +3. **On burn (`bd mol burn`):** + - Delete placeholder from permanent beads + - Delete wisp from `.beads-wisp/` + +**Edge cases:** +- Crash before squash: Placeholder remains (orphan cleanup needed) +- Multiple wisps: Each has unique ID, no collision + +--- + +### 8. Daemon Patrol Changes (Gas Town) + +**Current behavior (`checkDeaconAttachment`):** +- Checks if Deacon has pinned mol +- If not, spawns `mol-deacon-patrol` and attaches permanently +- This is wrong for wisp-based patrol + +**New behavior:** +- Remove `checkDeaconAttachment` entirely +- Deacon manages its own wisp lifecycle +- Daemon just ensures Deacon session is running and pokes it + +**Code change in `daemon.go`:** +```go +// Remove this function entirely: +// func (d *Daemon) checkDeaconAttachment() error { ... } + +// Or replace with a simpler check: +func (d *Daemon) ensureDeaconReady() error { + // Just verify session is running, don't attach anything + // Deacon self-spawns wisps for patrol + return nil +} +``` + +--- + +### 9. Deacon Template Update + +**Current (`deacon.md.tmpl`):** +```markdown +If no molecule (naked), **start a new patrol**: +```bash +bd mol run mol-deacon-patrol +``` +``` + +**New:** +```markdown +## Patrol Cycle (Wisp-Based) + +Each patrol cycle uses ephemeral wisps: + +```bash +# 1. Spawn wisp for this cycle +bd wisp mol-deacon-patrol + +# 2. Execute steps +bd close +bd close +# ... + +# 3. Squash with summary +bd mol squash --summary="Patrol complete: " + +# 4. Loop +# Repeat from step 1 +``` + +**Why wisps?** +- Patrol cycles are operational, not auditable work +- Each cycle is independent +- Only the digest matters (and only if notable) +- Keeps permanent beads clean +``` + +--- + +## Implementation Order + +### Phase 1: Core Commands (P0) + +1. [ ] Add `bd pour` command +2. [ ] Add `bd wisp` command +3. [ ] Rename `--persistent` to `--pour` (with deprecated alias) +4. [ ] Update daemon to remove `checkDeaconAttachment` +5. [ ] Update `deacon.md.tmpl` for wisp-based patrol + +### Phase 2: Agent Attachment (P1) + +1. [ ] Add `bd pin` command +2. [ ] Add `bd unpin` command +3. [ ] Add `--pour` flag to `bd mol bond` +4. [ ] Implement digest ID reservation for wisps +5. [ ] Update `witness.md.tmpl` for wisp-based patrol + +### Phase 3: Inspection (P2) + +1. [ ] Add `bd hook` command +2. [ ] Add `gt hook` command (thin wrapper) + +--- + +## Testing Plan + +### Manual Tests + +```bash +# Test pour +bd pour mol-quick-fix +bd show # Verify in permanent beads + +# Test wisp +bd wisp mol-patrol +ls .beads-wisp/ # Verify wisp created +bd show # Should work from permanent (placeholder) + +# Test squash +bd mol squash --summary="Test" +ls .beads-wisp/ # Wisp should be gone +bd show # Digest should exist + +# Test pin +bd pour mol-feature +bd pin +bd hook # Should show pinned mol +``` + +### Integration Tests + +- Deacon patrol cycle with wisps +- Cross-phase bonding (mol + wisp) +- Digest ID stability after squash + +--- + +## Migration Notes + +### Existing Code + +- `bd mol spawn` defaults to wisp (vapor) now +- Code using `bd mol spawn` for permanent mols needs `--pour` +- `bd mol run` continues to work (creates mol, not wisp) + +### Deprecation Path + +| Old | New | Deprecation | +|-----|-----|-------------| +| `--persistent` | `--pour` | Warn in 0.x, remove in 1.0 | +| `bd mol spawn` (for mols) | `bd pour` | Keep both, prefer new | + +--- + +*This document tracks the implementation of chemistry UX changes.* diff --git a/docs/molecular-chemistry.md b/docs/molecular-chemistry.md new file mode 100644 index 00000000..32b3a43f --- /dev/null +++ b/docs/molecular-chemistry.md @@ -0,0 +1,646 @@ +# Molecular Chemistry: Work Composition in Gas Town + +> *"Work is fractal. Money is crystallized labor. Blockchain was the mechanism +> searching for its purpose."* + +Gas Town is a **work composition and execution engine**. This document describes +the chemistry-inspired system for expressing, instantiating, and executing work +at any scale - from single tasks to massive polymers that can grind through +weekends of autonomous operation. + +## The Steam Engine Metaphor + +Gas Town is an engine. Engines do work and generate steam. + +``` +Claude = Fire (the energy source) +Claude Code = Steam Engine (harnesses the fire) +Gas Town = Steam Train (coordinates engines on tracks) +Beads = Railroad Tracks (the persistent ledger of work) +``` + +In our chemistry: +- **Proto molecules** are the fuel (templates that define workflows) +- **Mols** are liquid work (flowing, dynamic, adapting as steps complete) +- **Wisps** are the steam (transient execution traces that rise and dissipate) +- **Digests** are the distillate (condensed permanent records of completed work) + +## The Three Phases of Matter + +Work in Gas Town exists in three phases, following the states of matter: + +| Phase | Name | State | Storage | Behavior | +|-------|------|-------|---------|----------| +| **Solid** | Proto | Frozen template | `.beads/` (template label) | Crystallized, immutable, reusable | +| **Liquid** | Mol | Flowing instance | `.beads/` | Dynamic, adapting, persistent | +| **Vapor** | Wisp | Ephemeral trace | `.beads-wisp/` | Transient, dissipates, operational | + +### Proto (Solid Phase) + +Protos are **frozen workflow patterns** - crystallized templates that encode +reusable work structures. They're the "molds" from which instances are cast. + +```markdown +## Molecule: engineer-in-box +Full workflow from design to merge. + +## Step: design +Think carefully about architecture. +Needs: (none) + +## Step: implement +Write the code. +Needs: design + +## Step: test +Write and run tests. +Needs: implement + +## Step: submit +Submit for merge. +Needs: test +``` + +**Properties:** +- Immutable once defined (frozen) +- Named (e.g., `mol-engineer-in-box`, `mol-code-review`) +- Stored in permanent beads with `template` label +- Can be composed into larger protos (polymers) + +### Mol (Liquid Phase) + +Mols are **flowing work instances** - live executions that adapt as steps +complete, status changes, and work evolves. + +**Properties:** +- Identified by head bead ID (e.g., `bd-abc123`) +- Dynamic - steps transition through states +- Persistent - survives sessions, crashes, context compaction +- Auditable - full history in beads + +### Wisp (Vapor Phase) + +Wisps are **ephemeral execution traces** - the steam that rises during work +and dissipates when done. + +**Properties:** +- Stored in `.beads-wisp/` (gitignored, never synced) +- Single-cycle lifetime +- Either evaporates (burn) or condenses to digest (squash) +- Used for patrol cycles, operational loops, routine work + +## Phase Transition Operators + +Work transitions between phases through specific operators: + +``` + ┌─────────────────┐ + │ PROTO │ + │ (solid) │ + └────────┬────────┘ + │ + ┌──────────────┼──────────────┐ + │ │ │ + pour wisp distill + │ │ ↑ + ▼ ▼ │ + ┌───────────────┐ ┌───────────────┐ │ + │ MOL │ │ WISP │ │ + │ (liquid) │ │ (vapor) │ │ + └───────┬───────┘ └───────┬───────┘ │ + │ │ │ + squash squash │ + │ │ │ + ▼ ▼ │ + ┌───────────────┐ ┌───────────────┐ │ + │ DIGEST │ │ (evaporates) │ │ + │ (condensed) │ │ or burn │ │ + └───────────────┘ └───────────────┘ │ + │ │ + └────────────────────────────┘ + (experience crystallizes) +``` + +### Pour: Solid → Liquid + +**Pour** instantiates a proto into a persistent mol - like pouring molten metal +into a mold to create a solid casting that will flow through the workflow. + +```bash +bd pour mol-feature # Create mol from proto +bd pour mol-feature --var version=1.0 # With variable substitution +``` + +**Use cases:** +- Feature work that spans sessions +- Important work needing audit trail +- Anything you might need to reference later + +### Wisp: Solid → Vapor (Sublimation) + +**Wisp** instantiates a proto directly into vapor - sublimation that skips +the liquid phase for ephemeral, operational work. + +```bash +bd wisp mol-patrol # Create wisp from proto +bd wisp mol-health-check # Ephemeral operational task +``` + +**Use cases:** +- Patrol cycles (deacon, witness) +- Health checks and monitoring +- One-shot orchestration runs +- Routine operations with no audit value + +### Squash: Liquid/Vapor → Condensed + +**Squash** condenses work into a permanent digest - the outcome crystallizes +while the execution trace compresses or evaporates. + +```bash +bd mol squash bd-abc123 # Squash mol to digest +bd mol squash bd-abc123 --summary="Completed auth" # With summary +``` + +**For mols:** Creates digest in permanent beads, preserves full outcome +**For wisps:** Creates digest, deletes wisp (vapor condenses to residue) + +### Burn: Vapor → Nothing + +**Burn** discards a wisp without creating a digest - the steam simply +evaporates with no residue. + +```bash +bd mol burn wisp-123 # Discard without digest +``` + +**Use cases:** +- Routine patrol cycles with nothing notable +- Failed attempts that don't need recording +- Test runs + +### Distill: Liquid → Solid (Crystallization) + +**Distill** extracts a reusable proto from an existing mol or epic - the +reverse of pour. Experience crystallizes into a template. + +```bash +bd mol distill bd-abc123 --as "Release Workflow" +bd mol distill bd-abc123 --var feature=auth --var version=1.0 +``` + +**Process:** +1. Analyze the existing work structure +2. Extract the pattern (steps, dependencies) +3. Replace concrete values with `{{variable}}` placeholders +4. Crystallize as a new proto + +**Use cases:** +- Team develops a good workflow organically, wants to reuse it +- Capture tribal knowledge as executable templates +- Create starting points for similar future work + +## The Polymorphic Bond Operator + +**Bond** is Gas Town's polymorphic combiner - it handles different operand +types with different phase behaviors: + +### Bond: Proto + Proto → Compound Proto + +Two solid templates fuse into a larger solid template. + +```bash +bd mol bond mol-review mol-deploy --as "Review and Deploy" +``` + +Creates a compound proto that includes both workflows. The result is a +reusable template (solid phase). + +### Bond: Proto + Mol → Spawn + Attach + +A solid template melts into an existing liquid workflow. + +```bash +bd mol bond mol-hotfix bd-feature-123 +``` + +The proto is instantiated (as liquid by default) and attached to the +existing mol. The new issues become part of the flowing work. + +### Bond: Proto + Wisp → Spawn + Attach (Vapor) + +A solid template sublimates into an existing vapor workflow. + +```bash +bd mol bond mol-extra-check wisp-patrol-456 +``` + +The proto spawns as vapor (following the wisp's phase) and attaches. + +### Bond: Mol + Mol → Compound Mol + +Two liquid workflows merge into a larger flowing structure. + +```bash +bd mol bond bd-feature-123 bd-related-456 +``` + +Links them via dependency edges. Both continue flowing. + +### Bond: Wisp + Wisp → Compound Wisp + +Two vapor traces merge into a larger ephemeral cloud. + +```bash +bd mol bond wisp-123 wisp-456 +``` + +### Phase Override Flags + +Bond's spawning behavior can be overridden: + +```bash +# Force liquid when attaching to wisp (found something important!) +bd mol bond mol-critical-bug wisp-patrol --pour + +# Force vapor when attaching to mol (ephemeral diagnostic) +bd mol bond mol-temp-check bd-feature --wisp +``` + +| Flag | Effect | Use Case | +|------|--------|----------| +| `--pour` | Force spawn as liquid | "This matters, persist it" | +| `--wisp` | Force spawn as vapor | "This is ephemeral, let it evaporate" | + +### Cross-Phase Bonding + +What happens when you bond liquid and vapor directly? + +```bash +bd mol bond bd-feature-123 wisp-456 # Mol + Wisp +``` + +**Answer: Reference-only linking.** They connect via dependency edges but +stay in their respective stores. No phase change occurs - you're linking +across the phase boundary without forcing conversion. + +This enables patterns like: +- Patrol wisp discovers issue → creates liquid mol for the fix +- Feature mol needs diagnostic → spawns vapor wisp for the check +- The reference survives even when the wisp evaporates (ID stable) + +## Agent Attachment: Hooks and Pins + +Agents need work attached to them. In Gas Town, this uses **hooks** and **pins**. + +### The Hook + +Each agent has a **hook** - an anchor point where work hangs. It's the +agent's "pinned bead" - the top of their inbox, the work they're focused on. + +```bash +bd hook # Show what's on my hook +bd hook --agent deacon # Show deacon's hook +``` + +**Hook states:** +- **Empty (naked)**: Agent awaiting work assignment +- **Occupied**: Agent has work to execute +- **Multiple**: Agent managing several concurrent mols (rare) + +### Pin: Attaching Work to Agents + +**Pin** attaches a mol to an agent's hook - the action of assigning work. + +```bash +bd pin bd-feature-123 # Pin to my hook +bd pin bd-feature-123 --for witness # Pin to specific agent's hook +bd unpin # Detach current work +``` + +**The Witness → Polecat flow:** + +```bash +# Witness assigns work to polecat +bd pour mol-feature # Create liquid mol +bd pin bd-abc123 --for polecat-ace # Hang on polecat's hook +gt nudge polecat-ace # Wake the polecat +``` + +### Wisps Don't Need Pinning + +Wisps are single-cycle and don't survive session boundaries in the +traditional sense. Agents hold them in working memory for one cycle: + +```bash +# Deacon self-spawns patrol (no pin needed) +bd wisp mol-deacon-patrol # Create vapor +# ... execute steps ... +bd mol squash --summary="..." # Condense and dissipate +# Loop +``` + +## The Epic-Mol Relationship + +Epics and mols are **isomorphic** but represent different mental models. + +### Epic: The Business View + +An epic is a **simple mol shape** - essentially a TODO list: + +``` +epic-root +├── child.1 +├── child.2 +├── child.3 +└── child.4 +(flat list, no sibling dependencies, execution order implicit) +``` + +**Properties:** +- One level of children via `.N` numbering +- No explicit serial/parallel encoding +- Human-readable, business-oriented +- The natural shape most humans create + +### Mol: The Chemistry View + +A mol is the **general case** - arbitrary graphs with explicit workflow +semantics: + +``` +mol-root +├── phase-A (epic) +│ ├── task.1 ───blocks──→ task.2 (serial) +│ └── task.3 (parallel with task.1) +├── phase-B (epic) ←───blocked-by─── phase-A +│ └── ... +└── standalone (fanout) +(arbitrary DAG, explicit dependencies encode serial/parallel) +``` + +**Properties:** +- Can contain multiple epics as subgraphs +- Dependency edges encode execution order +- `blocks` = serial (bottleneck) +- No dep = parallel (fanout) +- `conditional` = if-fail path + +### The Relationship + +**All epics are mols. Not all mols are epics.** + +| Aspect | Epic | Mol | +|--------|------|-----| +| Shape | Flat (root + children) | Arbitrary DAG | +| Dependencies | Implicit in ordering | Explicit edges | +| Parallelism | Assumed parallel | Encoded in structure | +| Mental model | TODO list | Workflow graph | +| Common use | Simple feature work | Complex orchestration | + +When you `distill` an epic, you get a simple proto. +When you `distill` a complex mol, you get a complex proto (preserving structure). + +## Thermodynamic Properties + +Gas Town's chemistry has thermodynamic properties - work is energy flowing +through the system. + +### Work as Energy + +``` +Proto (potential energy) → Pour/Wisp → Mol/Wisp (kinetic energy) → Squash → Digest (stored work) +``` + +- **Protos** store potential energy - the capability to do work +- **Mols/Wisps** are kinetic - work actively flowing +- **Digests** are stored energy - crystallized outcomes + +### The Audit Trail as Entropy + +Every execution increases entropy - creating more history, more records, +more state. Gas Town manages this through: + +- **Wisps**: High entropy, but evaporates (entropy contained) +- **Squash**: Compresses entropy into minimal digest +- **Distill**: Reduces entropy by extracting reusable pattern + +### The CV Chain + +Every agent has a **chain** of work - their CV: + +``` +Agent CV = ∑(digests) = crystallized capability proof +``` + +Work completed → digest created → agent's chain grows → capability demonstrated. + +This is the foundation for capability-based work matching: your work +history IS your resume. The ledger speaks. + +## The Complete Lifecycle + +### Feature Work (Liquid Path) + +```bash +# 1. Create work from template +bd pour mol-feature --var name=auth + +# 2. Pin to agent +bd pin bd-abc123 --for polecat-ace + +# 3. Agent executes steps +bd update bd-abc123.design --status=in_progress +# ... cognition ... +bd close bd-abc123.design +bd update bd-abc123.implement --status=in_progress +# ... and so on + +# 4. Squash when complete +bd mol squash bd-abc123 --summary="Implemented auth feature" + +# 5. Digest remains in permanent ledger +``` + +### Patrol Work (Vapor Path) + +```bash +# 1. Self-spawn wisp (no pin needed) +bd wisp mol-deacon-patrol + +# 2. Execute cycle steps +bd close +bd close +# ... + +# 3. Generate summary and squash +bd mol squash --summary="Patrol complete, no issues" + +# 4. Loop +bd wisp mol-deacon-patrol +# ... +``` + +### Template Creation (Distillation) + +```bash +# 1. Complete some work organically +# ... team develops release workflow over several iterations ... + +# 2. Distill the pattern +bd mol distill bd-release-v3 --as "Release Workflow" + +# 3. Result: new proto available +bd pour mol-release-workflow --var version=2.0 +``` + +## Polymers: Large-Scale Composition + +Protos can compose into arbitrarily large **polymers** - chains of molecules +that encode complex multi-phase work. + +```bash +# Create polymer from multiple protos +bd mol bond mol-design mol-implement --as "Design and Implement" +bd mol bond mol-design-implement mol-test --as "Full Dev Cycle" +bd mol bond mol-full-dev mol-deploy --as "End to End" +``` + +**Polymer properties:** +- Preserve phase relationships from constituent protos +- Can encode hours, days, or weeks of work +- Enable "weekend warrior" autonomous operation +- Beads tracks progress; agents execute; humans sleep + +### The Cognition Sausage Machine + +A large polymer is a **cognition sausage machine**: + +``` +Proto Polymer (input) + │ + ▼ +┌─────────────────────────────────────────┐ +│ GAS TOWN ENGINE │ +│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ +│ │Pole │ │Pole │ │Pole │ │Pole │ │ +│ │cat │ │cat │ │cat │ │cat │ │ +│ └──┬──┘ └──┬──┘ └──┬──┘ └──┬──┘ │ +│ │ │ │ │ │ +│ └────────┴────────┴────────┘ │ +│ ↓ │ +│ Merge Queue │ +│ ↓ │ +│ Refinery │ +└─────────────────────────────────────────┘ + │ + ▼ +Completed Work + Digests (output) +``` + +Feed in a polymer. Get back completed features, merged PRs, and audit trail. + +## The Proto Library + +Gas Town maintains a **library of curated protos** - the fuel stockpile: + +``` +~/gt/molecules/ +├── mol-engineer-in-box/ # Full quality workflow +├── mol-quick-fix/ # Fast path for small changes +├── mol-code-review/ # Pluggable review dimensions +├── mol-release/ # Release workflow +├── mol-deacon-patrol/ # Deacon monitoring cycle +├── mol-witness-patrol/ # Witness worker monitoring +└── mol-polecat-work/ # Standard polecat lifecycle +``` + +**Library operations:** + +```bash +bd mol list # List available protos +bd mol show mol-code-review # Show proto details +bd pour mol-code-review # Instantiate for use +``` + +### Curated vs Organic + +- **Curated protos**: Refined templates in the library, battle-tested +- **Organic protos**: Distilled from real work, may need refinement +- **Path**: Organic → refine → curate → library + +## Digest ID Stability + +When a wisp is created, its head bead ID is **reserved** in permanent storage. +This ensures cross-phase references remain valid: + +``` +1. bd wisp mol-patrol → Creates wisp-123 (ID reserved) +2. bd mol bond ... wisp-123 → Reference created +3. bd mol squash wisp-123 → Digest takes same ID +4. Reference still valid → Points to digest now +``` + +**Implementation:** +- On wisp creation: Write placeholder/tombstone to permanent beads +- On squash: Replace placeholder with actual digest +- Cross-phase references never break + +## Summary of Operators + +| Operator | From | To | Effect | +|----------|------|------|--------| +| `pour` | Proto | Mol | Instantiate as persistent liquid | +| `wisp` | Proto | Wisp | Instantiate as ephemeral vapor | +| `bond` | Any + Any | Compound | Combine (polymorphic) | +| `squash` | Mol/Wisp | Digest | Condense to permanent record | +| `burn` | Wisp | Nothing | Discard without record | +| `distill` | Mol/Epic | Proto | Extract reusable template | +| `pin` | Mol | Agent | Attach work to agent's hook | + +## Design Implications + +### For Beads + +1. **New commands**: `bd pour`, `bd wisp`, `bd pin` +2. **Flag changes**: `--persistent` → `--pour` (or phase follows operand) +3. **Wisp storage**: `.beads-wisp/` directory, gitignored +4. **Digest ID reservation**: Placeholder in permanent store on wisp creation + +### For Gas Town + +1. **Daemon**: Don't attach permanent molecules for patrol roles +2. **Deacon template**: Use `bd wisp mol-deacon-patrol` pattern +3. **Polecat lifecycle**: Consider wisp-based with digest on completion +4. **Hook inspection**: `bd hook` command for debugging + +### For Agents + +1. **Polecats**: Receive pinned mols, execute, squash, request shutdown +2. **Patrol roles**: Self-spawn wisps, execute cycle, squash, loop +3. **Recovery**: Re-read beads state, continue from last completed step + +--- + +## Appendix: The Vocabulary + +| Term | Meaning | +|------|---------| +| **Proto** | Frozen template molecule (solid phase) | +| **Mol** | Flowing work instance (liquid phase) | +| **Wisp** | Ephemeral execution trace (vapor phase) | +| **Digest** | Condensed permanent record | +| **Pour** | Instantiate proto as mol (solid → liquid) | +| **Wisp** (verb) | Instantiate proto as wisp (solid → vapor) | +| **Bond** | Combine molecules (polymorphic) | +| **Squash** | Condense to digest | +| **Burn** | Discard wisp without digest | +| **Distill** | Extract proto from experience | +| **Hook** | Agent's attachment point for work | +| **Pin** | Attach mol to agent's hook | +| **Polymer** | Large composed proto chain | +| **Epic** | Simple mol shape (flat TODO list) | + +--- + +*The chemistry is the interface. The ledger is the truth. The work gets done.*