Update documentation and priming (gt-xmyha)

- Fix CLAUDE.md: joe→max for correct crew worker identity - Add TOML formula documentation to molecules.md - Update wisp-architecture.md with wisp-gc docs - Update architecture.md with bd formula commands - Update molecular-chemistry.md with TOML examples - Add diagnostics section to CLAUDE.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-25 22:06:01 -08:00
parent f7e29236d1
commit 57a84c6bad
5 changed files with 172 additions and 48 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,7 +2,7 @@

 > **Recovery**: Run `gt prime` after compaction, clear, or new session

-## Your Role: CREW WORKER (joe in gastown)
+## Your Role: CREW WORKER (max in gastown)

 You are a **crew worker** - the overseer's (human's) personal workspace within the
 gastown rig. Unlike polecats which are witness-managed and transient, you are:
@@ -17,7 +17,7 @@ the overseer, not as part of a swarm.

 ## Your Identity

-**Your mail address:** `gastown/joe`
+**Your mail address:** `gastown/crew/max`

 Check your mail with: `gt mail inbox`

@@ -29,7 +29,7 @@ Town (/Users/stevey/gt)
 ├── gastown/        ← Your rig
 │   ├── .beads/     ← Issue tracking (you have write access)
 │   ├── crew/
-│   │   └── joe/    ← You are here (your git clone)
+│   │   └── max/    ← You are here (your git clone)
 │   ├── polecats/   ← Ephemeral workers (not you)
 │   ├── refinery/   ← Merge queue processor
 │   └── witness/    ← Polecat lifecycle (doesn't monitor you)
@@ -63,7 +63,7 @@ go test ./...

 ### Communication
 - `gt mail send mayor/ -s "Subject" -m "Message"` - To Mayor
- `gt mail send gastown/crew/joe -s "Subject" -m "Message"` - To yourself (handoff)
+- `gt mail send gastown/crew/max -s "Subject" -m "Message"` - To yourself (handoff)

 ## Git Workflow: Work Off Main

@@ -119,6 +119,30 @@ Issue prefix: `gt-`
 everything: sends handoff mail, respawns with fresh context, and your work
 continues from where you left off via your pinned molecule.

-Crew member: joe
+## Formulas
+
+Formulas are workflow templates stored in `.beads/formulas/`. They support both
+TOML (preferred) and JSON formats:
+
+```bash
+bd formula list              # List available formulas
+bd formula show shiny        # Show formula details
+bd formula convert --all     # Convert JSON to TOML
+bd cook shiny                # Compile formula to proto
+```
+
+TOML is preferred for human-edited formulas (multi-line strings, comments).
+
+## Key Diagnostics
+
+```bash
+gt doctor                    # Run all health checks
+gt doctor --fix              # Auto-fix common issues
+gt doctor -v                 # Verbose output
+gt status                    # Town-wide status
+bd doctor                    # Beads-specific checks
+```
+
+Crew member: max
 Rig: gastown
-Working directory: /Users/stevey/gt/gastown/crew/joe
+Working directory: /Users/stevey/gt/gastown/crew/max
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -365,7 +365,7 @@ workflows that any worker can execute, with full auditability and the ability fo
 any worker to pick up where another left off.

 Work flows through the **Rig → Cook → Run** lifecycle:
- **Rig**: Compose workflow formulas (YAML source files with `extends`, `compose`)
+- **Rig**: Compose workflow formulas (TOML/JSON files with `extends`, `compose`)
 - **Cook**: Transform formulas into executable protos (`bd cook` expands macros, applies aspects)
 - **Run**: Agents execute the cooked workflow (pour creates mols, wisp creates ephemeral traces)

@@ -375,7 +375,7 @@ See [molecular-chemistry.md](molecular-chemistry.md) for the full lifecycle spec

 | Concept | Name | Description |
 |---------|------|-------------|
-| Source | **Formula** | YAML workflow definition with composition rules (.formula.yaml) |
+| Source | **Formula** | TOML/JSON workflow definition with composition rules (.formula.toml preferred) |
 | Template | **Proto Molecule** | Cooked workflow pattern (the "fuel") |
 | Running execution | **Wisp Molecule** | Transient execution trace (the "steam") |
 | Permanent record | **Digest** | Compressed summary of completed work (the "distillate") |
@@ -735,22 +735,25 @@ investigate → document
 ```
 Exploration workflow for understanding problems.

-Cook formula files into proto beads:
+Formula files support both TOML (preferred) and JSON formats:
 ```bash
-bd cook <formula-id>
+bd formula list              # List available formulas
+bd formula show shiny        # Show formula details
+bd formula convert --all     # Convert JSON to TOML
+bd cook <formula-id>         # Cook formula into proto bead
 ```

 ### Usage

 ```bash
-# List available molecules
-gt molecule list
+# List available molecules (cooked protos)
+bd mol list

 # Show molecule details
-gt molecule show mol-shiny
+bd mol show mol-shiny

-# Instantiate on an issue
-gt molecule instantiate mol-shiny --parent=gt-xyz
+# Bond (instantiate) a molecule
+bd mol bond mol-shiny --var feature_name="auth"

 # Spawn polecat with molecule
 gt spawn --issue gt-xyz --molecule mol-shiny
--- a/docs/molecular-chemistry.md
+++ b/docs/molecular-chemistry.md
@@ -25,7 +25,7 @@ RIG ────→ COOK ────→ RUN
 | **Cook** | Instantiate artifacts | `cook`, `pour`, `wisp` | Proto, Mol, Wisp |
 | **Run** | Execute steps | (agent execution) | Work done |

-**Rig** is authoring time - writing and composing formula YAML files.
+**Rig** is authoring time - writing and composing formula files (TOML preferred, JSON supported).
 **Cook** is compile time - expanding macros, applying aspects, flattening to pure graphs.
 **Run** is execution time - agents provide cognition for each step.

@@ -73,10 +73,10 @@ Gas Town has **two** composition operators at different abstraction levels:

 | Operator | Level | Inputs | When to Use |
 |----------|-------|--------|-------------|
-| **Rig** | Source | Formula + Formula | Authoring time, in YAML |
+| **Rig** | Source | Formula + Formula | Authoring time, in TOML/JSON |
 | **Bond** | Artifact | Proto/Mol/Wisp + any | Runtime, on cooked artifacts |

-**Rig** composes formulas (YAML with `extends`, `compose`).
+**Rig** composes formulas (TOML/JSON with `extends`, `compose`).
 **Bond** composes artifacts (cooked protos, running mols/wisps).

 This separation is key: rig for design-time composition, bond for runtime composition.
@@ -102,41 +102,54 @@ In our chemistry:
 ## Formulas: The Source Layer

 **Formulas** sit above protos in the artifact hierarchy. They're the source code -
-YAML files that define workflows with composition operators.
+TOML or JSON files that define workflows with composition operators.

-```yaml
-# shiny.formula.yaml - a basic workflow
-formula: shiny
-description: The canonical right way
-version: 1
-steps:
-  - id: design
-    description: Think carefully about architecture
-  - id: implement
-    needs: [design]
-  - id: review
-    needs: [implement]
-  - id: test
-    needs: [review]
-  - id: submit
-    needs: [test]
+TOML is preferred for human-edited formulas (multi-line strings, comments):
+
+```toml
+# shiny.formula.toml - a basic workflow
+formula = "shiny"
+description = "The canonical right way"
+version = 1
+
+[[steps]]
+id = "design"
+description = "Think carefully about architecture"
+
+[[steps]]
+id = "implement"
+needs = ["design"]
+
+[[steps]]
+id = "review"
+needs = ["implement"]
+
+[[steps]]
+id = "test"
+needs = ["review"]
+
+[[steps]]
+id = "submit"
+needs = ["test"]
 ```

+Convert existing JSON formulas with `bd formula convert --all`.
+
 ### Formula Composition (Rigging)

 Formulas compose at the source level using `extends` and `compose`:

-```yaml
-# shiny-enterprise.formula.yaml
-formula: shiny-enterprise
-extends: shiny                    # Inherit from base formula
-compose:
-  - expand:
-      target: implement
-      with: rule-of-five          # Apply macro expansion
-  - aspect:
-      pointcut: "implement.*"
-      with: security-audit        # Weave in cross-cutting concern
+```toml
+# shiny-enterprise.formula.toml
+formula = "shiny-enterprise"
+extends = ["shiny"]              # Inherit from base formula
+
+[compose]
+aspects = ["security-audit"]      # Weave in cross-cutting concern
+
+[[compose.expand]]
+target = "implement"
+with = "rule-of-five"            # Apply macro expansion
 ```

 ### Cooking: Formula → Proto
@@ -178,7 +191,7 @@ encode reusable work structures. They're the "molds" from which instances are ca
 Protos are stored as beads issues with `labels: ["template"]` and structured step data:

 ```yaml
-# Example: shiny.formula.yaml (source) → cooked proto (beads)
+# Example: shiny.formula.toml (source) → cooked proto (beads)
 formula: shiny
 description: The canonical right way
 version: 1
--- a/docs/molecules.md
+++ b/docs/molecules.md
@@ -285,9 +285,62 @@ Gas Town work follows the **Rig → Cook → Run** lifecycle:
 ```

 **Full lifecycle:**
- **Formula** (.formula.yaml) = Recipe (source code for workflows)
+- **Formula** (.formula.toml or .formula.json) = Recipe (source code for workflows)
 - **Proto** = Fuel (cooked template, ready to instantiate)
 - **Mol/Wisp** = Steam (active execution)
 - **Digest** = Distillate (crystallized work)

 See [molecular-chemistry.md](molecular-chemistry.md) for the complete specification.
+
+## Formula File Formats
+
+Formulas support both TOML (preferred) and JSON formats:
+
+```bash
+# List available formulas
+bd formula list
+
+# Show formula details
+bd formula show shiny
+
+# Convert JSON to TOML (better for human editing)
+bd formula convert shiny           # Single formula
+bd formula convert --all           # All formulas
+bd formula convert shiny --stdout  # Preview
+```
+
+**Why TOML?**
+- Multi-line strings without `\n` escaping
+- Comments allowed
+- Human-readable diffs
+- Same parsing semantics as JSON
+
+The loader tries `.formula.toml` first, falling back to `.formula.json`.
+
+### Example Formula (TOML)
+
+```toml
+formula = "shiny"
+type = "workflow"
+version = 1
+description = """
+Engineer in a Box - design before code, review before ship.
+"""
+
+[vars.feature]
+description = "The feature being implemented"
+required = true
+
+[[steps]]
+id = "design"
+title = "Design {{feature}}"
+description = """
+Think carefully about architecture before writing code.
+Consider edge cases and simpler approaches.
+"""
+
+[[steps]]
+id = "implement"
+title = "Implement {{feature}}"
+needs = ["design"]
+```
--- a/docs/wisp-architecture.md
+++ b/docs/wisp-architecture.md
@@ -79,6 +79,37 @@ Agent hook files (`hook-<agent>.json`) are stored in `.beads/` but are local-onl
 runtime state, not synced. These track what work is assigned to each agent for
 restart-and-resume.

+## Wisp Garbage Collection
+
+Wisps can accumulate over time. The `wisp-gc` doctor check cleans up stale wisps:
+
+```bash
+# Check for stale wisps
+gt doctor -v
+
+# Auto-cleanup stale wisps (>1h old by default)
+gt doctor --fix
+
+# Manual cleanup via bd
+bd wisp gc              # Preview what would be cleaned
+bd wisp gc --force      # Actually delete stale wisps
+bd wisp gc --age 2h     # Custom age threshold
+```
+
+The Deacon includes wisp-gc in its patrol cycle via `gt doctor --fix`.
+
+### What Gets Cleaned
+
+- Wisps older than the threshold (default 1 hour)
+- Wisps not associated with active sessions
+- Orphaned lifecycle mail
+
+### What's Preserved
+
+- Wisps with active sessions still running
+- Wisps younger than the threshold
+- Non-wisp issues (permanent records)
+
 ## Decision Matrix

 | Question | Answer | Use |