docs: add Formula + Cook terminology and example formulas (gt-8tmz)

Updates to molecule-algebra.md: - Added Formulas and Cooking section - Four-tier model: Formula → cook → Proto → pour/wisp → Mol/Wisp - Breaking Bad × Mad Max naming (Let's cook!) - Updated vision diagram New example formulas: - shiny.formula.yaml (Engineer in a Box) - rule-of-five.formula.yaml (Jeffrey's Rule expansion macro) - security-audit.formula.yaml (AOP aspect) - shiny-enterprise.formula.yaml (composed example)
2025-12-23 18:20:39 -08:00
parent e63ac65b86
commit 93d9726bbc
5 changed files with 371 additions and 4 deletions
--- a/.beads/formulas/rule-of-five.formula.yaml
+++ b/.beads/formulas/rule-of-five.formula.yaml
@@ -0,0 +1,61 @@
+# rule-of-five.formula.yaml
+# Jeffrey's Rule: Agents converge on best output in 4-5 iterations
+# Breadth-first cognition, then editorial passes
+
+formula: rule-of-five
+type: expansion
+description: |
+  Jeffrey Emanuel's discovery: LLM agents (and humans) produce their best
+  work through iterative refinement. The first pass is breadth-first
+  exploration; subsequent passes are editorial refinement.
+
+  Apply this to any step that benefits from iteration:
+  - Writing (code, docs, plans)
+  - Analysis (reviews, investigations)
+  - Design (architecture, interfaces)
+
+  The expansion replaces one step with five sequential steps.
+version: 1
+
+# This is a macro/expansion template
+# When applied to a target step, it expands to 5 steps
+
+template:
+  - id: "{target}.draft"
+    description: |
+      Initial attempt at: {target.description}
+
+      Don't aim for perfection. Get the shape right.
+      Breadth over depth. Explore the space.
+
+  - id: "{target}.refine-1"
+    description: |
+      First refinement pass. Focus: CORRECTNESS.
+
+      Review the draft. Fix errors, bugs, mistakes.
+      Is the logic sound? Are the facts right?
+    needs: ["{target}.draft"]
+
+  - id: "{target}.refine-2"
+    description: |
+      Second refinement pass. Focus: CLARITY.
+
+      Can someone else understand this?
+      Simplify. Remove jargon. Add explanations where needed.
+    needs: ["{target}.refine-1"]
+
+  - id: "{target}.refine-3"
+    description: |
+      Third refinement pass. Focus: EDGE CASES.
+
+      What could go wrong? What's missing?
+      Handle the unusual inputs, the error paths, the corner cases.
+    needs: ["{target}.refine-2"]
+
+  - id: "{target}.refine-4"
+    description: |
+      Final polish. Focus: EXCELLENCE.
+
+      This is the last pass. Make it shine.
+      Is this something you'd be proud to ship?
+    needs: ["{target}.refine-3"]
--- a/.beads/formulas/security-audit.formula.yaml
+++ b/.beads/formulas/security-audit.formula.yaml
@@ -0,0 +1,48 @@
+# security-audit.formula.yaml
+# AOP aspect for security scanning at implementation boundaries
+
+formula: security-audit
+type: aspect
+description: |
+  Cross-cutting security concern. Applies security scanning
+  before and after implementation steps.
+
+  This is an ASPECT - it doesn't run standalone. Apply it
+  to other formulas using --with-aspect.
+version: 1
+
+pointcuts:
+  - glob: "*.implement"
+  - glob: "*.submit"
+
+advice:
+  around:
+    before:
+      - id: security-prescan
+        description: |
+          Pre-implementation security check.
+
+          - Review for secrets/credentials in scope
+          - Check dependencies for known vulnerabilities
+          - Verify security requirements are understood
+        args:
+          target: "{step.id}"
+
+    after:
+      - id: security-postscan
+        description: |
+          Post-implementation security scan.
+
+          - Scan new code for vulnerabilities (SAST)
+          - Check for hardcoded secrets
+          - Verify auth/authz patterns
+          - Review for OWASP Top 10 issues
+        args:
+          target: "{step.id}"
+        output:
+          approved: boolean
+          findings: list
+
+      - gate:
+          condition: "security-postscan.output.approved == true"
+          message: "Security approval required before proceeding"
--- a/.beads/formulas/shiny-enterprise.formula.yaml
+++ b/.beads/formulas/shiny-enterprise.formula.yaml
@@ -0,0 +1,66 @@
+# shiny-enterprise.formula.yaml
+# Full enterprise engineering workflow with all the bells and whistles
+
+formula: shiny-enterprise
+extends: shiny
+description: |
+  Enterprise-grade engineering workflow.
+
+  Builds on Shiny with:
+  - Rule of Five on implementation (5x refinement)
+  - Security scanning (pre and post)
+  - Performance testing branch
+  - Review loop until approved
+  - Full logging
+
+  Cook this to get a ~30 step proto ready for serious work.
+version: 1
+
+compose:
+  # Apply Rule of Five to the implement step
+  # This expands implement → 5 steps: draft, refine-1..4
+  - expand:
+      target: implement
+      with: rule-of-five
+
+  # Apply security aspect to all implementation steps
+  # Adds security-prescan before and security-postscan after
+  - aspect:
+      pointcut: "implement.*"
+      with: security-audit
+
+  # Gate on security approval before submit
+  - gate:
+      before: submit
+      condition: "security-postscan.approved == true"
+      message: "Cannot submit without security approval"
+
+  # Parallel performance testing branch
+  # These run in parallel after implementation, before review
+  - branch:
+      from: implement.refine-4
+      steps:
+        - id: perf-test
+          description: Run performance benchmarks
+        - id: load-test
+          description: Run load/stress tests
+        - id: chaos-test
+          description: Run chaos engineering tests (fault injection)
+      join: review
+
+  # Loop review until approved (max 3 attempts)
+  - loop:
+      step: review
+      until: "review.output.approved == true"
+      max: 3
+      on-max: escalate
+
+  # Logging on all steps (AOP-style advice)
+  - advice:
+      target: "*"
+      before:
+        - id: log-start
+          description: "Log: Starting {step.id}"
+      after:
+        - id: log-end
+          description: "Log: Completed {step.id} with status {step.status}"
--- a/.beads/formulas/shiny.formula.yaml
+++ b/.beads/formulas/shiny.formula.yaml
@@ -0,0 +1,67 @@
+# shiny.formula.yaml
+# Engineer in a Box - the canonical right way to do engineering
+# Named for Mad Max: "Shiny and chrome!"
+
+formula: shiny
+description: |
+  The canonical engineering workflow. Design before you code.
+  Review before you ship. Test before you submit.
+
+  This is what "doing it right" looks like.
+version: 1
+
+vars:
+  feature: "{{feature}}"           # What you're building
+  assignee: "{{assignee}}"         # Who's doing the work
+
+steps:
+  - id: design
+    description: |
+      Think carefully about architecture before writing code.
+
+      Consider:
+      - How does this fit into the existing system?
+      - What are the edge cases?
+      - What could go wrong?
+      - Is there a simpler approach?
+
+      Output a brief design doc or notes.
+
+  - id: implement
+    description: |
+      Write the code for {{feature}}.
+
+      Follow the design. Keep it simple. Don't gold-plate.
+      Write code that's easy to review.
+    needs: [design]
+
+  - id: review
+    description: |
+      Review the implementation.
+
+      Check for:
+      - Does it match the design?
+      - Are there obvious bugs?
+      - Is it readable and maintainable?
+      - Are there security concerns?
+    needs: [implement]
+
+  - id: test
+    description: |
+      Write and run tests.
+
+      - Unit tests for new code
+      - Integration tests if needed
+      - Run the full test suite
+      - Fix any regressions
+    needs: [review]
+
+  - id: submit
+    description: |
+      Submit for merge.
+
+      - Final check: git status, git diff
+      - Commit with clear message
+      - Push and create PR (or merge directly if crew)
+      - Notify relevant parties
+    needs: [test]
--- a/docs/molecule-algebra.md
+++ b/docs/molecule-algebra.md
@@ -18,6 +18,124 @@ Molecules = Graph Algebra (mechanical, gt executes)
 Steps = AI Cognition (agent provides)
 ```

+## 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.
+
+### The Four-Tier Model
+
+```
+Formula (.formula.yaml)     ← "The secret formula" (source code)
+    ↓ cook                  ← "Let's cook" (pre-expand, flatten)
+Proto (frozen in beads)     ← "Pure product" (compiled, flat graph)
+    ↓ pour/wisp             ← Instantiate
+Mol/Wisp (running)          ← The work flowing
+```
+
+| Tier | Name | Format | Nature |
+|------|------|--------|--------|
+| Source | **Formula** | YAML | Composable, has macros/aspects |
+| Compiled | **Proto** | Beads issue | Frozen, flat graph, fast instantiation |
+| Running | **Mol/Wisp** | Beads issue | Active, flowing work |
+
+### Why Cook?
+
+Cooking **pre-expands** all composition at "compile time":
+- Macros (Rule of Five) expand to flat steps
+- Aspects apply to matching pointcuts
+- Branches and gates wire up
+- Result: pure step graph with no interpretation needed
+
+Instantiation then becomes pure **copy + variable substitution**. Fast, mechanical,
+deterministic.
+
+### Formula Format
+
+Formulas are YAML files with `.formula.yaml` extension:
+
+```yaml
+# shiny.formula.yaml
+formula: shiny
+description: Engineer in a Box - 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]
+```
+
+Formulas with composition:
+
+```yaml
+# shiny-enterprise.formula.yaml
+formula: shiny-enterprise
+extends: shiny
+version: 1
+
+compose:
+  - expand:
+      target: implement
+      with: rule-of-five
+  - aspect:
+      pointcut: "implement.*"
+      with: security-audit
+  - gate:
+      before: submit
+      condition: "security-postscan.approved"
+```
+
+### CLI
+
+```bash
+# Cook a formula into a proto
+bd cook shiny-enterprise.formula.yaml
+# "Cooking shiny-enterprise..."
+# "✓ Cooked proto: shiny-enterprise (30 steps)"
+
+# Preview without saving
+bd cook shiny-enterprise.formula.yaml --dry-run
+
+# List available formulas
+bd formula list
+
+# Show formula details
+bd formula show rule-of-five
+
+# Instantiate the cooked proto
+bd pour shiny-enterprise --var feature="auth"
+```
+
+### Formula Storage
+
+```
+~/.beads/formulas/          # User formulas
+~/gt/.beads/formulas/       # Town formulas
+.beads/formulas/            # Project formulas
+```
+
+### Breaking Bad × Mad Max
+
+The naming spans both universes:
+- **Formula** = the chemistry, the secret (Breaking Bad, mad scientist)
+- **Cook** = the process, the craft (Breaking Bad iconic)
+- **Proto** = the pure product, crystallized (the "blue sky")
+- Both work in Mad Max (fuel formulas, cooking up schemes)
+
+Heisenberg's formula is worthless without the cook. The cook is where purity
+comes from. Same here: formulas define the algebra, but cooking produces the
+pure proto.
+
 ## The Phases of Matter

 Work in Gas Town exists in three phases:
@@ -528,21 +646,28 @@ This keeps evaluation decidable and safe for mechanical execution.
               │           MOL MALL (Marketplace)        │
               │  ┌─────────┐ ┌─────────┐ ┌───────────┐  │
               │  │ Shiny   │ │ Rule of │ │ Security  │  │
-               │  │         │ │ Five    │ │ Aspect    │  │
+               │  │ Formula │ │ Five    │ │ Aspect    │  │
               │  └─────────┘ └─────────┘ └───────────┘  │
               │  ┌─────────┐ ┌─────────┐ ┌───────────┐  │
               │  │Planning │ │ Release │ │ Company   │  │
-               │  │ Form    │ │ Cycle   │ │ Onboard   │  │
+               │  │ Formula │ │ Formula │ │ Onboard   │  │
               │  └─────────┘ └─────────┘ └───────────┘  │
               └─────────────────────────────────────────┘
                              │
                              ▼ compose
               ┌─────────────────────────────────────────┐
-               │         YOUR ORGANIZATION WORKFLOW       │
+               │       YOUR ORGANIZATION FORMULA          │
               │                                          │
               │  Planning + Shiny + R5 + Security +     │
               │  Release + Onboarding = Company in Box   │
               │                                          │
+               └─────────────────────────────────────────┘
+                              │
+                              ▼ cook ("Let's cook")
+               ┌─────────────────────────────────────────┐
+               │              PURE PROTO                  │
+               │  Pre-expanded, flat graph, 99.1% pure   │
+               │  No macros, no aspects, just steps      │
               └─────────────────────────────────────────┘
                              │
                              ▼ pour/wisp
@@ -558,4 +683,4 @@ From issues in git → work composition algebra → companies in a box.

 ---

-*The algebra is the interface. The ledger is the truth. The work gets done.*
+*The formula is the secret. The cook is the craft. The work gets done.*