docs: discover Rig/Cook/Run lifecycle - the three phases of work (gt-8tmz)

Key insight: Rig and Bond operate at different abstraction levels: - Rig = source-level composition (formula YAML with extends/compose) - Bond = artifact-level composition (protos, mols, wisps) This preserves the symmetric bond table while cleanly separating authoring (rig) from runtime composition (bond). New docs: - rig-cook-run.md: Canonical spec for the three phases Updated docs: - molecule-algebra.md: Three Phases section, rig/bond distinction - molecular-chemistry.md: Rig/bond clarification in bond section - vision.md: Core Innovation 3 now covers Rig/Cook/Run "This is a discovery, not an invention." 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-23 19:19:04 -08:00
parent 733039a6d6
commit 4716b2ee57
4 changed files with 274 additions and 13 deletions
--- a/docs/molecular-chemistry.md
+++ b/docs/molecular-chemistry.md
@@ -201,8 +201,22 @@ bd mol distill bd-abc123 --var feature=auth --var version=1.0

 ## The Polymorphic Bond Operator

-**Bond** is Gas Town's polymorphic combiner - it handles different operand
-types with different phase behaviors:
+Gas Town has **two composition operators** at different abstraction levels:
+
+| Operator | Level | Inputs | When to Use |
+|----------|-------|--------|-------------|
+| **Rig** | Source | Formula + Formula | Authoring time, in YAML |
+| **Bond** | Artifact | Proto/Mol/Wisp + any | Runtime, on cooked artifacts |
+
+**Rig** composes formulas (source YAML with `extends`, `compose`).
+**Bond** composes artifacts (cooked protos, running mols/wisps).
+
+See [rig-cook-run.md](rig-cook-run.md) for the full Rig/Cook/Run lifecycle.
+
+---
+
+**Bond** is Gas Town's polymorphic combiner for artifacts - it handles different
+operand types with different phase behaviors:

 ### Bond: Proto + Proto → Compound Proto

--- a/docs/molecule-algebra.md
+++ b/docs/molecule-algebra.md
@@ -18,17 +18,35 @@ Molecules = Graph Algebra (mechanical, gt executes)
 Steps = AI Cognition (agent provides)
 ```

+## The Three Phases: Rig, Cook, Run
+
+Gas Town work flows through three phases:
+
+```
+RIG ────→ COOK ────→ RUN
+```
+
+| Phase | What Happens | Operator | Output |
+|-------|--------------|----------|--------|
+| **Rig** | Compose formulas (source level) | extends, compose | Compound Formula |
+| **Cook** | Instantiate work | cook, pour, wisp | Proto, Mol, Wisp |
+| **Run** | Execute steps | (agent execution) | Work done |
+
+See [rig-cook-run.md](rig-cook-run.md) for the full specification.
+
 ## Formulas and Cooking

 > *"Let's cook."* - Walter White

-The molecule algebra lives above molecular chemistry. **Formulas** are the
-source code; **cooking** is the process that produces executable protos.
+**Formulas** are the source code; **rigging** composes them; **cooking**
+produces executable artifacts.

-### The Four-Tier Model
+### The Artifact Tiers

 ```
 Formula (.formula.yaml)     ← "The secret formula" (source code)
+    ↓ rig (compose)         ← "Rig it up" (source-level composition)
+Compound Formula            ← Combined source
    ↓ cook                  ← "Let's cook" (pre-expand, flatten)
 Proto (frozen in beads)     ← "Pure product" (compiled, flat graph)
    ↓ pour/wisp             ← Instantiate
@@ -37,10 +55,22 @@ Mol/Wisp (running)          ← The work flowing

 | Tier | Name | Format | Nature |
 |------|------|--------|--------|
-| Source | **Formula** | YAML | Composable, has macros/aspects |
+| Source | **Formula** | YAML | Composable via `extends`/`compose` |
 | Compiled | **Proto** | Beads issue | Frozen, flat graph, fast instantiation |
 | Running | **Mol/Wisp** | Beads issue | Active, flowing work |

+### Two Composition Operators
+
+| Operator | Level | Inputs | Output |
+|----------|-------|--------|--------|
+| **Rig** | Source | Formula + Formula | Compound Formula |
+| **Bond** | Artifact | Proto/Mol/Wisp + any | Combined artifact |
+
+**Rig** is source-level composition (formula YAML with `extends`, `compose`).
+**Bond** is artifact-level composition (combining cooked protos, linking mols).
+
+See the Bond Table in [rig-cook-run.md](rig-cook-run.md) for full semantics.
+
 ### Why Cook?

 Cooking **pre-expands** all composition at "compile time":
--- a/docs/rig-cook-run.md
+++ b/docs/rig-cook-run.md
@@ -0,0 +1,195 @@
+# Rig, Cook, Run: The Gas Town Work Lifecycle
+
+> **Status**: Canonical specification
+> **Discovery**: 2025-12-23
+
+## The Three Phases
+
+Gas Town work flows through three phases:
+
+```
+RIG ────→ COOK ────→ RUN
+```
+
+| Phase | What Happens | Input | Output |
+|-------|--------------|-------|--------|
+| **Rig** | Compose formulas | Formula YAML | Compound Formula |
+| **Cook** | Instantiate work | Formula/Proto | Proto/Mol/Wisp |
+| **Run** | Execute steps | Mol/Wisp | Work done |
+
+## Phase 1: Rig (Authoring)
+
+**Rigging** is source-level composition. You write formula YAML files that
+reference and compose other formulas.
+
+```yaml
+# shiny-enterprise.formula.yaml
+formula: shiny-enterprise
+extends: shiny                    # ← rigging: inherit from shiny
+compose:
+  - expand:
+      target: implement
+      with: rule-of-five          # ← rigging: expand with macro
+  - aspect:
+      pointcut: "implement.*"
+      with: security-audit        # ← rigging: weave in aspect
+```
+
+**Rig operators** (in formula YAML):
+- `extends` - inherit from another formula
+- `compose` - apply transformations (expand, aspect, gate, loop, branch)
+
+**Rigging is static** - it happens before cooking, at authoring time.
+
+## Phase 2: Cook (Instantiation)
+
+**Cooking** transforms formulas into executable work.
+
+```bash
+bd cook shiny-enterprise    # Formula → Proto (flat, expanded)
+bd pour shiny-enterprise    # Proto → Mol (liquid, persistent)
+bd wisp shiny-enterprise    # Proto → Wisp (vapor, ephemeral)
+```
+
+**Cook produces three artifact types:**
+
+| Command | Output | Phase of Matter | Storage |
+|---------|--------|-----------------|---------|
+| `bd cook` | Proto | Solid (frozen) | `.beads/` |
+| `bd pour` | Mol | Liquid (flowing) | `.beads/` |
+| `bd wisp` | Wisp | Vapor (ephemeral) | `.beads-wisp/` |
+
+**Cooking is deterministic** - same formula always produces same structure.
+
+## Phase 3: Run (Execution)
+
+**Running** executes the steps in a mol or wisp.
+
+```bash
+gt sling shiny-enterprise polecat/alpha   # Cook + assign + run
+```
+
+Agents execute mols/wisps by:
+1. Reading the pinned work from their hook
+2. Completing steps in dependency order
+3. Closing steps as they finish
+4. Exiting when all steps complete
+
+**Running is where cognition happens** - agents provide judgment, code, decisions.
+
+## The Two Composition Operators
+
+### Rig (Source-Level)
+
+Operates on **formulas** (YAML source files).
+
+```
+Formula + Formula ──rig──→ Compound Formula
+```
+
+Use rigging when:
+- You're authoring new workflows
+- You want version-controlled composition
+- You need the full algebra (extends, aspects, macros)
+
+### Bond (Artifact-Level)
+
+Operates on **artifacts** (protos, mols, wisps).
+
+```
+Artifact + Artifact ──bond──→ Combined Artifact
+```
+
+**The Bond Table** (symmetric, complete):
+
+| bond | Proto | Mol | Wisp |
+|------|-------|-----|------|
+| **Proto** | Compound Proto | Spawn Mol, attach | Spawn Wisp, attach |
+| **Mol** | Spawn Mol, attach | Link via edges | Link via edges |
+| **Wisp** | Spawn Wisp, attach | Link via edges | Link via edges |
+
+Use bonding when:
+- Runtime dynamic composition (patrol discovers issue → bond bug mol)
+- Ad-hoc combination without writing YAML
+- Combining Mol Mall artifacts without source
+- Programmatic proto generation
+
+## The Complete Picture
+
+```
+                    SOURCE LEVEL
+                    ════════════
+
+Formula ─────rig─────→ Compound Formula
+    │                        │
+    │                        │
+    └──────────┬─────────────┘
+               │
+              cook
+               │
+               ▼
+                    ARTIFACT LEVEL
+                    ══════════════
+
+Proto ──────bond─────→ Compound Proto
+  │ \                      │ \
+  │  \                     │  \
+pour  wisp               pour  wisp
+  │     \                  │     \
+  ▼      ▼                 ▼      ▼
+ Mol    Wisp ───bond───→ Linked Work
+  │       │
+  └───┬───┘
+      │
+     run
+      │
+      ▼
+                    EXECUTION
+                    ═════════
+
+              Steps complete
+              Work gets done
+              Digests created
+```
+
+## Vocabulary Summary
+
+| Term | Meaning | Example |
+|------|---------|---------|
+| **Formula** | Source YAML with composition rules | `shiny.formula.yaml` |
+| **Rig** | Compose formulas (source level) | `extends: shiny` |
+| **Cook** | Transform formula → proto | `bd cook shiny` |
+| **Proto** | Frozen workflow template | Cooked, immutable structure |
+| **Pour** | Instantiate as mol (liquid) | `bd pour shiny` |
+| **Wisp** | Instantiate as wisp (vapor) | `bd wisp shiny` |
+| **Mol** | Flowing persistent work | Tracked in `.beads/` |
+| **Wisp** | Ephemeral transient work | Tracked in `.beads-wisp/` |
+| **Bond** | Combine artifacts (any level) | `bd bond proto-a proto-b` |
+| **Sling** | Cook + assign to agent hook | `gt sling shiny polecat/alpha` |
+| **Run** | Execute mol/wisp steps | Agent follows molecule |
+
+## The Metaphor Sources
+
+| Concept | Breaking Bad | Mad Max |
+|---------|--------------|---------|
+| Formula | Secret recipe | Fuel formula |
+| Rig | Lab setup | War Rig assembly |
+| Cook | "Let's cook" | Refining guzzoline |
+| Proto | 99.1% pure crystal | Refined fuel |
+| Pour/Wisp | Distribution | Pumping/vapor |
+| Mol/Wisp | Product in use | Fuel burning |
+| Bond | Cutting/mixing | Fuel blending |
+| Sling | Dealing | Fuel dispatch |
+| Run | The high | The chase |
+
+## Why This Matters
+
+1. **Clean separation**: Source composition (rig) vs artifact composition (bond)
+2. **Symmetric operations**: Bond table is complete, no holes
+3. **Clear phases**: Rig → Cook → Run, each with distinct purpose
+4. **Metaphor coherence**: Breaking Bad + Mad Max vocabulary throughout
+5. **Implementation clarity**: Each phase maps to specific commands
+
+---
+
+*This is a discovery, not an invention. The structure was always there.*
--- a/docs/vision.md
+++ b/docs/vision.md
@@ -87,9 +87,28 @@ Workers who need help receive it.

 ---

-## Core Innovation 3: Molecular Chemistry of Work
+## Core Innovation 3: Rig, Cook, Run

-Work in Gas Town exists in three phases, following the states of matter:
+Work in Gas Town flows through three phases:
+
+```
+RIG ────→ COOK ────→ RUN
+```
+
+| Phase | What Happens | Key Operator |
+|-------|--------------|--------------|
+| **Rig** | Compose formulas (source level) | extends, compose |
+| **Cook** | Instantiate work (pour/wisp) | cook, pour, wisp |
+| **Run** | Execute steps | Agent execution |
+
+**Rig** is source-level composition (formula YAML).
+**Bond** is artifact-level composition (protos, mols, wisps).
+
+See [rig-cook-run.md](rig-cook-run.md) for the full specification.
+
+### The Three Phases of Matter
+
+Work artifacts exist in three phases:

 | Phase | Name | State | Behavior |
 |-------|------|-------|----------|
@@ -138,11 +157,14 @@ Work in Gas Town exists in three phases, following the states of matter:

 ### The Polymorphic Bond Operator

-**Bond** adapts to its operands:
- Proto + Proto → Compound Proto (larger template)
- Proto + Mol → Spawn and attach (template melts into flow)
- Proto + Wisp → Spawn as vapor and attach
- Mol + Mol → Link via dependencies
+**Bond** is the artifact-level combiner (distinct from **rig**, which composes
+source formulas). Bond adapts to its operands:
+
+| bond | Proto | Mol | Wisp |
+|------|-------|-----|------|
+| **Proto** | Compound Proto | Spawn + attach | Spawn wisp + attach |
+| **Mol** | Spawn + attach | Link | Link |
+| **Wisp** | Spawn + attach | Link | Link |

 This enables patterns like:
 - Patrol wisp discovers issue → bonds new work mol