feat(formula): make primitives discoverable to coding agents (GH#3621) (#3781)

* feat(formula): add bd formula schema reflection-driven primitive index (beads-9ib)

Generates internal/formula/schema_gen.go from types.go via go:generate,
exposing all 18 exported structs (Formula, Step, LoopSpec, OnCompleteSpec,
etc.) with field types, json/toml tags, required-flag, and doc comments.

Surfaced via:
  bd formula schema                 # list every primitive
  bd formula schema loop            # show LoopSpec fields
  bd formula primitives on_complete # alias + snake_case match
  bd formula schema --json          # machine-readable

Lookup prefers exact match over Spec/Rule(s) suffix-strip, so "gate"
resolves to Gate (not GateRule). Fields tagged json:"-" (Step.SourceFormula,
Step.SourceLocation) are excluded.

TestSchemaGenIsCurrent re-runs the AST walker in-memory and byte-diffs
against the committed schema_gen.go, so a new struct in types.go without
a regen will fail CI.

Item 2 of GH#3621.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(formula): point bd formula --help at the primitive index (beads-lnf)

Extends the cobra Long descriptions on `formula`, `formula list`, and
`formula show` so an agent reading any of them is told that
`bd formula schema` (alias `primitives`), the curated
`examples/formulas/primitives/` directory, and the website primitives
reference exist. Without these pointers, agents land on the formula
surface and conclude there is no primitive index — which is the exact
failure mode GH#3621 is closing.

Adds cmd/bd/testdata/formula_help.txt as the regression gate: a
scripttest that runs `bd formula --help` (plus `--help` on the list
and show subcommands) and asserts the four pointers are present. If
someone deletes a pointer, the snapshot fails.

website/docs/cli-reference/formula.md is auto-generated from the Long
descriptions via `bd help --doc formula`, so the website doc inherits
the pointers on its next regeneration with no manual edit.

Item 1 of GH#3621.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(formula): curated primitive examples + smoke harness (beads-0sp)

Adds examples/formulas/primitives/ with one minimal `.formula.toml` per
empirically wired primitive in internal/formula/types.go:

  loop-count    LoopSpec.count       expand body 3x → .iter1.work…
  loop-range    LoopSpec.range/var   {n} substitutes into title
  children-epic Step.Children        epic + children w/ sibling needs
  branch-fanin  ComposeRules.Branch  fork-join, deploy depends on 3 sibs
  condition     Step.Condition       var-driven step inclusion
  gate-timer    Step.Gate            sibling gate-typed issue blocks step

Each fixture has a header doc-comment explaining the primitive in
plain language; README.md indexes them with a one-line description
each and points back at `bd formula schema`.

cmd/bd/formula_primitives_test.go is the smoke harness: for each
fixture it parses, cooks through the full transformation pipeline
(loops → branches → gates → advice → expansions → conditions), and
asserts the primitive's observable effect on the cooked subgraph
(issue IDs, blocking deps, substituted titles, gate await_type).
Cooks against an in-memory subgraph rather than a Dolt-backed temp
DB so the harness exercises the primitive transformation, not the
persistence/auto-export infrastructure.

A subtest fails if a fixture is added to the directory without a
registered assertion in cases[] — the harness exists to prove
primitives are wired, not just that fixtures parse.

Explicitly omits an `on_complete` fixture; that primitive is a
runtime no-op as of v1.0.3 and ships with beads-i02's resolution,
not this epic.

Item 3 of GH#3621.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(formula): satisfy CI gosec G306 + regen CLI doc for new help text

Two CI fixes for the formula primitives PR:

  - internal/formula/cmd/schemagen/main.go:26 — drop WriteFile perms
    from 0644 to 0600 (gosec G306).
  - website/docs/cli-reference/formula.md and the v1.0.0 mirror —
    regenerated from the updated `bd formula --help` Long text via
    scripts/generate-cli-docs.sh, using a CGO_ENABLED=0 bd build to
    match CI.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(formula): distinguish schema from wired primitives

* fix(formula): regen schema_gen.go for rebase onto current main

Upstream main's Formula struct gained an Intent field after PR #3781 was
opened; regenerate schema_gen.go via go generate so
TestSchemaGenIsCurrent passes after rebasing the PR's commits onto
current main.

Maintainer fix-merge for gastownhall/beads#3781.

Agent-Signature: claude-fable-5-medium on behalf of matt wilkie

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
This commit is contained in:
Jack J Garzella 2026-07-06 22:26:41 -07:00 • committed by GitHub
commit 7be354810f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
25 changed files with 2263 additions and 49 deletions

View file

@ -32,8 +32,16 @@ Search paths (in order):
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Commands:
list List available formulas from all search paths
show Show formula details, steps, and composition rules`,
list List available formulas from all search paths
show Show formula details, steps, and composition rules
schema Show the formula schema index (alias: primitives)
Discovering primitives:
bd formula schema # list every declared formula struct
bd formula schema loop # show LoopSpec fields, types, and tags
bd formula primitives gate # alias; same handler as 'schema'
examples/formulas/primitives/ # curated, smoke-tested wired fixtures
website/docs/workflows/formulas.md # narrative reference`,
}
// formulaListCmd lists all available formulas.
@ -50,6 +58,9 @@ Search paths (in order of priority):
Formulas in earlier paths shadow those with the same name in later paths.
To list the declared formula schema structs an agent can write inside a .formula.toml,
use 'bd formula schema' (alias: 'bd formula primitives').
Examples:
bd formula list
bd formula list --json
@ -73,6 +84,9 @@ Displays:
- Composition rules (extends, aspects, expansions)
- Bond points for external composition
To inspect the structure of an individual primitive (e.g. LoopSpec, Gate)
rather than a user-authored formula, use 'bd formula schema <primitive>'.
Examples:
bd formula show shiny
bd formula show rule-of-five

View file

@ -0,0 +1,236 @@
package main
import (
"os"
"path/filepath"
"strings"
"testing"
"github.com/steveyegge/beads/internal/types"
)
// TestFormulaPrimitiveExamples is the smoke harness for
// examples/formulas/primitives/. Each entry parses a fixture, cooks it
// through the full transformation pipeline, and asserts the primitive's
// observable effect on the resulting subgraph.
//
// A new fixture added to the directory without a registered case here is
// a deliberate failure (subTestForUnregisteredFixtures): the harness
// exists to prove primitives are wired, not that fixtures parse.
func TestFormulaPrimitiveExamples(t *testing.T) {
primDir := primitivesDir(t)
cases := []struct {
name string
vars map[string]string // non-nil enables Step.Condition filtering with formula defaults merged in
assert func(t *testing.T, sg *TemplateSubgraph)
}{
{
name: "loop-count",
assert: func(t *testing.T, sg *TemplateSubgraph) {
for _, want := range []string{
"loop-count.process.iter1.work",
"loop-count.process.iter2.work",
"loop-count.process.iter3.work",
} {
if !hasIssueID(sg, want) {
t.Errorf("missing issue %q; have %v", want, allIssueIDs(sg))
}
}
},
},
{
name: "loop-range",
assert: func(t *testing.T, sg *TemplateSubgraph) {
for _, want := range []string{"Move 1", "Move 2", "Move 3"} {
if !hasIssueTitle(sg, want) {
t.Errorf("missing title %q; have %v", want, allIssueTitles(sg))
}
}
},
},
{
name: "children-epic",
assert: func(t *testing.T, sg *TemplateSubgraph) {
// Children get the parent step's ID prefixed to their own.
for _, want := range []string{
"children-epic.ship-feature",
"children-epic.ship-feature.draft",
"children-epic.ship-feature.polish",
} {
if !hasIssueID(sg, want) {
t.Errorf("missing issue %q; have %v", want, allIssueIDs(sg))
}
}
if !hasBlockingDep(sg, "children-epic.ship-feature.polish", "children-epic.ship-feature.draft") {
t.Errorf("polish must block on draft; deps: %v", allDeps(sg))
}
},
},
{
name: "branch-fanin",
assert: func(t *testing.T, sg *TemplateSubgraph) {
for _, src := range []string{"test", "lint", "build"} {
if !hasBlockingDep(sg, "branch-fanin.deploy", "branch-fanin."+src) {
t.Errorf("deploy must block on %s; deps: %v", src, allDeps(sg))
}
}
},
},
{
name: "condition",
vars: map[string]string{}, // trigger filtering with formula's deploy=false default
assert: func(t *testing.T, sg *TemplateSubgraph) {
children := childIssueIDs(sg, "condition")
if len(children) != 2 {
t.Errorf("default deploy=false → want 2 child issues, got %d: %v", len(children), children)
}
if hasIssueID(sg, "condition.deploy") {
t.Error("deploy must be excluded when deploy=false")
}
},
},
{
name: "condition-true",
vars: map[string]string{"deploy": "true"},
assert: func(t *testing.T, sg *TemplateSubgraph) {
children := childIssueIDs(sg, "condition")
if len(children) != 3 {
t.Errorf("deploy=true → want 3 child issues, got %d: %v", len(children), children)
}
if !hasIssueID(sg, "condition.deploy") {
t.Error("deploy must be included when deploy=true")
}
},
},
{
name: "gate-timer",
assert: func(t *testing.T, sg *TemplateSubgraph) {
gate := findGate(sg)
if gate == nil {
t.Fatalf("no gate-typed sibling issue in subgraph; issues: %v", allIssueIDs(sg))
}
if gate.AwaitType != "timer" {
t.Errorf("gate.AwaitType = %q, want %q", gate.AwaitType, "timer")
}
if !hasBlockingDep(sg, "gate-timer.verify", gate.ID) {
t.Errorf("verify must block on gate %s; deps: %v", gate.ID, allDeps(sg))
}
},
},
}
registered := map[string]bool{}
for _, c := range cases {
// "condition-true" is a second pass on the "condition" fixture.
formulaName := strings.TrimSuffix(c.name, "-true")
registered[formulaName] = true
t.Run(c.name, func(t *testing.T) {
sg, err := resolveAndCookFormulaWithVars(formulaName, []string{primDir}, c.vars)
if err != nil {
t.Fatalf("cook %q: %v", formulaName, err)
}
c.assert(t, sg)
})
}
t.Run("every_fixture_has_a_registered_case", func(t *testing.T) {
entries, err := os.ReadDir(primDir)
if err != nil {
t.Fatalf("readdir %s: %v", primDir, err)
}
for _, e := range entries {
if !strings.HasSuffix(e.Name(), ".formula.toml") && !strings.HasSuffix(e.Name(), ".formula.json") {
continue
}
name := strings.TrimSuffix(e.Name(), ".formula.toml")
name = strings.TrimSuffix(name, ".formula.json")
if !registered[name] {
t.Errorf("fixture %q has no smoke assertion in cases[]; add one or delete the fixture", e.Name())
}
}
})
}
func primitivesDir(t *testing.T) string {
t.Helper()
dir, err := filepath.Abs(filepath.Join("..", "..", "examples", "formulas", "primitives"))
if err != nil {
t.Fatalf("abs path: %v", err)
}
if _, err := os.Stat(dir); err != nil {
t.Fatalf("primitives dir missing: %v", err)
}
return dir
}
func hasIssueID(sg *TemplateSubgraph, id string) bool {
for _, i := range sg.Issues {
if i.ID == id {
return true
}
}
return false
}
func hasIssueTitle(sg *TemplateSubgraph, title string) bool {
for _, i := range sg.Issues {
if i.Title == title {
return true
}
}
return false
}
func hasBlockingDep(sg *TemplateSubgraph, from, to string) bool {
for _, d := range sg.Dependencies {
if d.IssueID == from && d.DependsOnID == to && d.Type == "blocks" {
return true
}
}
return false
}
func findGate(sg *TemplateSubgraph) *types.Issue {
for _, i := range sg.Issues {
if i.IssueType == "gate" {
return i
}
}
return nil
}
func childIssueIDs(sg *TemplateSubgraph, rootID string) []string {
var out []string
for _, i := range sg.Issues {
if i.ID != rootID {
out = append(out, i.ID)
}
}
return out
}
func allIssueIDs(sg *TemplateSubgraph) []string {
out := make([]string, 0, len(sg.Issues))
for _, i := range sg.Issues {
out = append(out, i.ID)
}
return out
}
func allIssueTitles(sg *TemplateSubgraph) []string {
out := make([]string, 0, len(sg.Issues))
for _, i := range sg.Issues {
out = append(out, i.Title)
}
return out
}
func allDeps(sg *TemplateSubgraph) []string {
out := make([]string, 0, len(sg.Dependencies))
for _, d := range sg.Dependencies {
out = append(out, d.IssueID+" -> "+d.DependsOnID+" ("+string(d.Type)+")")
}
return out
}

134
cmd/bd/formula_schema.go Normal file
View file

@ -0,0 +1,134 @@
package main
import (
"fmt"
"os"
"strings"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/formula"
"github.com/steveyegge/beads/internal/ui"
)
var formulaSchemaCmd = &cobra.Command{
Use: "schema [primitive]",
Aliases: []string{"primitives"},
Short: "Show the formula schema index (every exported struct in types.go)",
Long: `Show the formula schema index: every exported struct declared
in a .formula.toml/.formula.json, with field names, types, and tags.
The index is generated from internal/formula/types.go via go:generate; the
struct definitions are the source of truth, so this list cannot drift. It is
structural reference, not proof that every declared runtime behavior is wired.
Examples:
bd formula schema # list every declared schema struct
bd formula schema loop # show LoopSpec fields
bd formula primitives gate # alias; shows Gate fields
bd formula schema --json # machine-readable index
Curated smoke-tested fixtures for wired primitives live in
examples/formulas/primitives/ (with a smoke harness that proves they work).`,
Args: cobra.MaximumNArgs(1),
Run: runFormulaSchema,
}
func runFormulaSchema(cmd *cobra.Command, args []string) {
if len(args) == 0 {
runFormulaSchemaList()
return
}
runFormulaSchemaShow(args[0])
}
func runFormulaSchemaList() {
if jsonOutput {
outputJSON(formula.Primitives)
return
}
fmt.Printf("Formula schema structs (%d):\n\n", len(formula.Primitives))
for _, p := range formula.Primitives {
fmt.Printf(" %-18s %s\n", p.Name, firstDocLine(p.Doc))
}
fmt.Printf("\n%s\n", ui.RenderMuted("Show fields: bd formula schema <name>"))
fmt.Printf("%s\n", ui.RenderMuted("Wired examples: examples/formulas/primitives/"))
fmt.Printf("%s\n", ui.RenderMuted("Note: schema output is structural; smoke-tested examples are the verified authoring surface."))
}
func runFormulaSchemaShow(name string) {
p := formula.PrimitiveByName(name)
if p == nil {
fmt.Fprintf(os.Stderr, "Error: unknown primitive %q\n\n", name)
fmt.Fprintf(os.Stderr, "Available primitives:\n")
for _, prim := range formula.Primitives {
fmt.Fprintf(os.Stderr, " %s\n", prim.Name)
}
os.Exit(1)
}
if jsonOutput {
outputJSON(p)
return
}
fmt.Printf("%s\n", ui.RenderAccent(p.Name))
if p.Doc != "" {
for _, line := range strings.Split(p.Doc, "\n") {
fmt.Printf(" %s\n", line)
}
}
if len(p.Fields) == 0 {
fmt.Printf("\n %s\n", ui.RenderMuted("(no exposed fields)"))
return
}
fmt.Printf("\nFields:\n")
maxName, maxType := 0, 0
for _, f := range p.Fields {
if n := len(f.JSONName); n > maxName {
maxName = n
}
if n := len(f.Type); n > maxType {
maxType = n
}
}
if maxName < 8 {
maxName = 8
}
if maxType < 8 {
maxType = 8
}
for _, f := range p.Fields {
req := ""
if f.Required {
req = " " + ui.RenderFail("required")
}
fmt.Printf(" %-*s %-*s%s\n", maxName, f.JSONName, maxType, f.Type, req)
if f.Doc != "" {
for _, line := range strings.Split(f.Doc, "\n") {
fmt.Printf(" %s\n", ui.RenderMuted(line))
}
}
if f.TOMLName != "" && f.TOMLName != f.JSONName {
fmt.Printf(" %s\n", ui.RenderMuted(fmt.Sprintf("toml: %s", f.TOMLName)))
}
fmt.Println()
}
}
func firstDocLine(doc string) string {
if doc == "" {
return ""
}
if i := strings.IndexByte(doc, '\n'); i >= 0 {
return doc[:i]
}
return doc
}
func init() {
formulaCmd.AddCommand(formulaSchemaCmd)
}

View file

@ -0,0 +1,126 @@
package main
import (
"encoding/json"
"strings"
"testing"
"github.com/steveyegge/beads/internal/formula"
)
func TestFormulaSchemaList_HumanOutput(t *testing.T) {
prevJSON := jsonOutput
jsonOutput = false
defer func() { jsonOutput = prevJSON }()
out := captureStdout(t, func() error {
runFormulaSchemaList()
return nil
})
for _, prim := range formula.Primitives {
if !strings.Contains(out, prim.Name) {
t.Errorf("primitive %s missing from list output", prim.Name)
}
}
if !strings.Contains(out, "examples/formulas/primitives/") {
t.Error("list output must point users at examples/formulas/primitives/")
}
}
func TestFormulaSchemaList_JSON(t *testing.T) {
prevJSON := jsonOutput
jsonOutput = true
defer func() { jsonOutput = prevJSON }()
out := captureStdout(t, func() error {
runFormulaSchemaList()
return nil
})
// outputJSON injects a schema_version on objects but passes arrays
// through unchanged. Primitives is a slice → we get a bare JSON array.
var got []formula.PrimitiveDoc
if err := json.Unmarshal([]byte(out), &got); err != nil {
t.Fatalf("invalid JSON: %v\noutput: %s", err, out)
}
if len(got) != len(formula.Primitives) {
t.Errorf("got %d primitives, want %d", len(got), len(formula.Primitives))
}
}
func TestFormulaSchemaShow_RendersFields(t *testing.T) {
prevJSON := jsonOutput
jsonOutput = false
defer func() { jsonOutput = prevJSON }()
out := captureStdout(t, func() error {
runFormulaSchemaShow("loop")
return nil
})
for _, want := range []string{"LoopSpec", "count", "until", "max", "range", "var", "body", "[]*Step"} {
if !strings.Contains(out, want) {
t.Errorf("loop output missing %q\nfull output:\n%s", want, out)
}
}
}
func TestFormulaSchemaShow_AliasResolution(t *testing.T) {
prevJSON := jsonOutput
jsonOutput = false
defer func() { jsonOutput = prevJSON }()
for _, input := range []string{"on_complete", "OnComplete", "OnCompleteSpec"} {
out := captureStdout(t, func() error {
runFormulaSchemaShow(input)
return nil
})
if !strings.Contains(out, "OnCompleteSpec") {
t.Errorf("%q did not resolve to OnCompleteSpec; output:\n%s", input, out)
}
if !strings.Contains(out, "for_each") {
t.Errorf("%q output missing for_each field", input)
}
}
}
func TestFormulaSchemaCmd_AliasRegistered(t *testing.T) {
// `bd formula primitives` must route to the same handler as `bd formula schema`.
found := false
for _, alias := range formulaSchemaCmd.Aliases {
if alias == "primitives" {
found = true
break
}
}
if !found {
t.Fatalf("formulaSchemaCmd.Aliases = %v, want to contain \"primitives\"", formulaSchemaCmd.Aliases)
}
}
func TestFormulaSchemaShow_JSON(t *testing.T) {
prevJSON := jsonOutput
jsonOutput = true
defer func() { jsonOutput = prevJSON }()
out := captureStdout(t, func() error {
runFormulaSchemaShow("loop")
return nil
})
// Single-primitive output goes through outputJSON which injects
// schema_version into objects. Decode into a generic map and assert
// the payload fields are present.
var got map[string]interface{}
if err := json.Unmarshal([]byte(out), &got); err != nil {
t.Fatalf("invalid JSON: %v\noutput: %s", err, out)
}
if got["name"] != "LoopSpec" {
t.Errorf("name = %v, want LoopSpec", got["name"])
}
fields, ok := got["fields"].([]interface{})
if !ok || len(fields) == 0 {
t.Fatalf("fields missing or empty in JSON output: %v", got["fields"])
}
}

View file

@ -213,17 +213,24 @@ func captureStdout(t *testing.T, fn func() error) string {
r, w, _ := os.Pipe()
os.Stdout = w
done := make(chan string, 1)
go func() {
var buf bytes.Buffer
_, _ = buf.ReadFrom(r)
done <- buf.String()
}()
err := fn()
w.Close()
var buf bytes.Buffer
buf.ReadFrom(r)
os.Stdout = oldStdout
out := <-done
_ = r.Close()
if err != nil {
t.Errorf("unexpected error: %v", err)
}
return buf.String()
return out
}
// captureStderr captures stderr output from fn and returns it as a string.

19
cmd/bd/testdata/formula_help.txt vendored Normal file
View file

@ -0,0 +1,19 @@
# Test that bd formula --help surfaces the primitive-discoverability pointers.
#
# Failure of any of these assertions means an agent reading 'bd formula --help'
# would not be told that 'bd formula schema' / 'bd formula primitives' /
# examples/formulas/primitives/ exist. That is the exact failure mode GH#3621
# is closing, so this test is the regression gate.
bd formula --help
stdout 'bd formula schema'
stdout 'bd formula primitives'
stdout 'examples/formulas/primitives/'
stdout 'website/docs/workflows/formulas.md'
# The list and show subcommands also point at the schema index so agents
# arriving via either subcommand find the primitive surface.
bd formula list --help
stdout 'bd formula schema'
bd formula show --help
stdout 'bd formula schema'

View file

@ -244,6 +244,7 @@ Reference for bd Latest. Generated from `bd help --all`.
- [bd formula](#bd-formula) — Manage workflow formulas
- [bd formula convert](#bd-formula-convert) — Convert formula from JSON to TOML
- [bd formula list](#bd-formula-list) — List available formulas
- [bd formula schema](#bd-formula-schema) — Show the formula schema index (every exported struct in types.go)
- [bd formula show](#bd-formula-show) — Show formula details
- [bd github](#bd-github) — GitHub integration commands
- [bd github pull](#bd-github-pull) — Pull specific items from GitHub
@ -5697,8 +5698,16 @@ Search paths (in order):
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Commands:
list List available formulas from all search paths
show Show formula details, steps, and composition rules
list List available formulas from all search paths
show Show formula details, steps, and composition rules
schema Show the formula schema index (alias: primitives)
Discovering primitives:
bd formula schema # list every declared formula struct
bd formula schema loop # show LoopSpec fields, types, and tags
bd formula primitives gate # alias; same handler as 'schema'
examples/formulas/primitives/ # curated, smoke-tested wired fixtures
website/docs/workflows/formulas.md # narrative reference
```
bd formula
@ -5747,6 +5756,9 @@ Search paths (in order of priority):
Formulas in earlier paths shadow those with the same name in later paths.
To list the declared formula schema structs an agent can write inside a .formula.toml,
use 'bd formula schema' (alias: 'bd formula primitives').
Examples:
bd formula list
bd formula list --json
@ -5763,6 +5775,30 @@ bd formula list [flags]
--type string Filter by type (workflow, expansion, aspect, convoy)
```
#### bd formula schema
Show the formula schema index: every exported struct declared
in a .formula.toml/.formula.json, with field names, types, and tags.
The index is generated from internal/formula/types.go via go:generate; the
struct definitions are the source of truth, so this list cannot drift. It is
structural reference, not proof that every declared runtime behavior is wired.
Examples:
bd formula schema # list every declared schema struct
bd formula schema loop # show LoopSpec fields
bd formula primitives gate # alias; shows Gate fields
bd formula schema --json # machine-readable index
Curated smoke-tested fixtures for wired primitives live in
examples/formulas/primitives/ (with a smoke harness that proves they work).
```
bd formula schema [primitive]
```
**Aliases:** primitives
#### bd formula show
Show detailed information about a formula.
@ -5774,6 +5810,9 @@ Displays:
- Composition rules (extends, aspects, expansions)
- Bond points for external composition
To inspect the structure of an individual primitive (e.g. LoopSpec, Gate)
rather than a user-authored formula, use 'bd formula schema &lt;primitive&gt;'.
Examples:
bd formula show shiny
bd formula show rule-of-five

View file

@ -0,0 +1,54 @@
# Formula primitive examples
One curated `.formula.toml` per *empirically wired* primitive in
`internal/formula/types.go`. Each fixture is minimal, self-documenting,
and exercises exactly one primitive.
## What's here
| Fixture | Primitive | One-line behavior |
|-------------------------------|--------------------|-------------------|
| `loop-count.formula.toml` | `LoopSpec.count` | Body expanded N times into `.iterN.<id>` step IDs. |
| `loop-range.formula.toml` | `LoopSpec.range` | Body expanded over a numeric range; `loop.var` substitutes into title/description. |
| `children-epic.formula.toml` | `Step.children` | Nested steps form an epic with sibling `needs` honored. |
| `branch-fanin.formula.toml` | `ComposeRules.branch` | Fork-join: parallel steps fan in to a single join step. |
| `condition.formula.toml` | `Step.condition` | Variable-driven step inclusion at cook time. |
| `gate-timer.formula.toml` | `Step.gate` | Sibling `gate`-typed issue with `await_type` blocks the target step. |
For the full schema index - every exported struct declared in
`internal/formula/types.go`, with field types and tags -
run:
```sh
bd formula schema # list every declared schema struct
bd formula schema loop # show LoopSpec fields
bd formula primitives gate # alias
bd formula schema --json # machine-readable
```
Treat `bd formula schema` as structural reference. Treat this directory
as the verified authoring surface: every fixture here is smoke-tested for
an observable parse-to-cook effect.
## Smoke harness
`cmd/bd/formula_primitives_test.go` walks this directory, parses and
cooks every fixture, and asserts each primitive's observable effect on
the cooked subgraph. A new fixture added here without a registered
assertion is a deliberate test failure: the harness exists to prove
primitives are wired, not just that fixtures parse.
Run with `make test`, or in isolation:
```sh
go test -tags gms_pure_go -run TestFormulaPrimitiveExamples ./cmd/bd/
```
## What's NOT here
* `on_complete` — runtime no-op for every valid configuration as of
v1.0.3 (tracked in `beads-i02`). Its fixture and smoke test ship with
that issue's resolution PR, not here.
* Anything in `internal/formula/types.go` without a verified end-to-end
parse → cook → pour audit. New primitives earn a fixture once they're
empirically wired, not when they're declared.

View file

@ -0,0 +1,35 @@
# Compose.Branch — fork-join parallel execution with a join step.
#
# `compose.branch` creates a fork-join pattern: every step in `steps` runs
# after `from` completes, and `join` runs after every parallel step
# completes. The smoke harness asserts `deploy` blocks on each of `test`,
# `lint`, and `build`.
formula = "branch-fanin"
description = "Compose.Branch: deploy fans in after parallel test/lint/build."
version = 1
type = "workflow"
[[steps]]
id = "prepare"
title = "Prepare workspace"
[[steps]]
id = "test"
title = "Run tests"
[[steps]]
id = "lint"
title = "Run linter"
[[steps]]
id = "build"
title = "Build artifacts"
[[steps]]
id = "deploy"
title = "Deploy build"
[[compose.branch]]
from = "prepare"
steps = ["test", "lint", "build"]
join = "deploy"

View file

@ -0,0 +1,24 @@
# Step.Children — nested steps form an epic with sub-tasks.
#
# A step with `children` becomes an epic; each child becomes a sub-issue
# whose parent is the outer step. `needs` between siblings still wires
# blocking dependencies. The smoke harness asserts the parent epic + 2
# children exist and that `polish` blocks on `draft` (sibling needs).
formula = "children-epic"
description = "Step.Children: epic step with two children where polish needs draft."
version = 1
type = "workflow"
[[steps]]
id = "ship-feature"
title = "Ship the feature"
type = "epic"
[[steps.children]]
id = "draft"
title = "Draft the implementation"
[[steps.children]]
id = "polish"
title = "Polish and document"
needs = ["draft"]

View file

@ -0,0 +1,30 @@
# Step.Condition — variable-driven step inclusion.
#
# A step with `condition` is filtered out at cook time when the condition
# evaluates to false against the current variable bindings. With the
# default {{deploy}} = "false", the deploy step is excluded (2 child
# issues). Override at cook time with --var deploy=true to include it
# (3 child issues). The smoke harness exercises both branches.
formula = "condition"
description = "Step.Condition: deploy step is included only when deploy var is true."
version = 1
type = "workflow"
[vars.deploy]
description = "Whether to include the deploy step"
default = "false"
[[steps]]
id = "build"
title = "Build the project"
[[steps]]
id = "test"
title = "Run tests"
needs = ["build"]
[[steps]]
id = "deploy"
title = "Deploy to production"
needs = ["test"]
condition = "{{deploy}} == true"

View file

@ -0,0 +1,25 @@
# Step.Gate — async wait condition that blocks a step until satisfied.
#
# A step with `gate` is split at cook time into two issues:
# * a sibling `gate`-typed issue capturing the wait (await_type, timeout)
# * the original step, with a blocking dep on the gate issue
# The smoke harness asserts the gate issue exists with await_type=timer
# and that the target step blocks on it.
formula = "gate-timer"
description = "Step.Gate: timer gate blocks the verify step until it elapses."
version = 1
type = "workflow"
[[steps]]
id = "deploy"
title = "Deploy build"
[[steps]]
id = "verify"
title = "Verify deployment after soak"
depends_on = ["deploy"]
[steps.gate]
type = "timer"
await_id = "soak-30m"
timeout = "30m"

View file

@ -0,0 +1,21 @@
# Loop.count — fixed-iteration loop.
#
# A step with `loop.count = N` is replaced at cook time by N copies of its
# `loop.body`. Each copy gets the iteration index baked into its step ID:
# the body step `work` becomes `process.iter1.work`, `process.iter2.work`,
# `process.iter3.work`. The smoke harness asserts those three IDs exist.
formula = "loop-count"
description = "Loop.count: expand body 3 times into .iter1.work, .iter2.work, .iter3.work."
version = 1
type = "workflow"
[[steps]]
id = "process"
title = "Process items"
[steps.loop]
count = 3
[[steps.loop.body]]
id = "work"
title = "Do unit of work"

View file

@ -0,0 +1,22 @@
# Loop.range — computed-bound loop with an iteration variable.
#
# `loop.range = "1..3"` plus `loop.var = "n"` exposes {n} = 1, 2, 3 to the
# body's title and description. The body step `move` becomes three issues
# titled "Move 1", "Move 2", "Move 3" — the smoke harness asserts those
# substituted titles appear.
formula = "loop-range"
description = "Loop.range with var=n exposes {n} for title substitution."
version = 1
type = "workflow"
[[steps]]
id = "moves"
title = "Tower moves"
[steps.loop]
range = "1..3"
var = "n"
[[steps.loop.body]]
id = "move"
title = "Move {n}"

View file

@ -0,0 +1,30 @@
// Command schemagen regenerates internal/formula/schema_gen.go from
// internal/formula/types.go. Driven by the //go:generate directive in
// internal/formula/schema.go; not invoked at runtime.
package main
import (
"flag"
"fmt"
"os"
"github.com/steveyegge/beads/internal/formula/schemagen"
)
func main() {
var (
typesPath = flag.String("types", "types.go", "path to types.go")
outPath = flag.String("out", "schema_gen.go", "output path")
)
flag.Parse()
src, err := schemagen.Generate(*typesPath)
if err != nil {
fmt.Fprintf(os.Stderr, "schemagen: %v\n", err)
os.Exit(1)
}
if err := os.WriteFile(*outPath, src, 0600); err != nil {
fmt.Fprintf(os.Stderr, "schemagen: write %s: %v\n", *outPath, err)
os.Exit(1)
}
}

View file

@ -0,0 +1,91 @@
package formula
//go:generate go run ./cmd/schemagen -types types.go -out schema_gen.go
// PrimitiveDoc describes one exported struct (a "primitive") in this package.
// The slice Primitives in schema_gen.go is generated from types.go and serves
// as the discoverability index surfaced by `bd formula schema`.
type PrimitiveDoc struct {
// Name is the Go struct name (e.g. "Formula", "LoopSpec").
Name string `json:"name"`
// Doc is the struct's leading doc comment, trimmed.
Doc string `json:"doc,omitempty"`
// Fields are the struct's exported, JSON-visible fields, in source order.
Fields []FieldDoc `json:"fields,omitempty"`
}
// FieldDoc describes one exported field of a primitive struct.
// Fields tagged json:"-" are excluded from the schema entirely.
type FieldDoc struct {
// Name is the Go field name.
Name string `json:"name"`
// Type is the Go type rendered as source (e.g. "string", "[]*Step",
// "map[string]*VarDef").
Type string `json:"type"`
// JSONName is the field name used in JSON output. Falls back to Name
// when the json tag is absent.
JSONName string `json:"json_name,omitempty"`
// TOMLName is the field name used in TOML output. Falls back to JSONName
// when no toml tag is present.
TOMLName string `json:"toml_name,omitempty"`
// Required is true when the field has no `,omitempty` option in its json
// tag. This is a structural signal, not a guarantee the parser enforces
// presence.
Required bool `json:"required,omitempty"`
// Doc is the field's leading doc comment, trimmed.
Doc string `json:"doc,omitempty"`
}
// PrimitiveByName returns the PrimitiveDoc that matches name, or nil.
// Matching is case-insensitive and ignores underscores/dashes; an exact
// (normalized) match wins over a suffix-stripped match. So "gate" returns
// Gate, "gaterule" returns GateRule, and "loop" or "on_complete" return
// LoopSpec / OnCompleteSpec via the Spec/Rule suffix fallback.
func PrimitiveByName(name string) *PrimitiveDoc {
if name == "" {
return nil
}
target := normalizePrimitiveName(name)
for i := range Primitives {
if normalizePrimitiveName(Primitives[i].Name) == target {
return &Primitives[i]
}
}
for i := range Primitives {
if stripPrimitiveSuffix(normalizePrimitiveName(Primitives[i].Name)) == target {
return &Primitives[i]
}
}
return nil
}
func normalizePrimitiveName(s string) string {
out := make([]byte, 0, len(s))
for i := 0; i < len(s); i++ {
c := s[i]
if c == '_' || c == '-' || c == ' ' {
continue
}
if c >= 'A' && c <= 'Z' {
c += 'a' - 'A'
}
out = append(out, c)
}
return string(out)
}
func stripPrimitiveSuffix(s string) string {
for _, suf := range []string{"spec", "rules", "rule"} {
if len(s) > len(suf) && s[len(s)-len(suf):] == suf {
return s[:len(s)-len(suf)]
}
}
return s
}

View file

@ -0,0 +1,824 @@
// Code generated by internal/formula/cmd/schemagen. DO NOT EDIT.
package formula
// Primitives is the discoverability index of every exported struct in
// types.go. Surfaced via `bd formula schema`. Regenerate with `go generate ./...`.
var Primitives = []PrimitiveDoc{
{
Name: "AdviceRule",
Doc: `AdviceRule defines a step transformation rule.
Advice operators insert steps before, after, or around matching targets.`,
Fields: []FieldDoc{
{
Name: "Target",
Type: "string",
JSONName: "target",
Required: true,
Doc: `Target is a glob pattern matching step IDs to apply advice to.
Examples: "*.implement", "design", "shiny.*"`,
},
{
Name: "Before",
Type: "*AdviceStep",
JSONName: "before",
Doc: `Before inserts a step before the target.`,
},
{
Name: "After",
Type: "*AdviceStep",
JSONName: "after",
Doc: `After inserts a step after the target.`,
},
{
Name: "Around",
Type: "*AroundAdvice",
JSONName: "around",
Doc: `Around wraps the target with before and after steps.`,
},
},
},
{
Name: "AdviceStep",
Doc: `AdviceStep defines a step to insert via advice.`,
Fields: []FieldDoc{
{
Name: "ID",
Type: "string",
JSONName: "id",
Required: true,
Doc: `ID is the step identifier. Supports {step.id} substitution.`,
},
{
Name: "Title",
Type: "string",
JSONName: "title",
Doc: `Title is the step title. Supports {step.id} substitution.`,
},
{
Name: "Description",
Type: "string",
JSONName: "description",
Doc: `Description is the step description.`,
},
{
Name: "Type",
Type: "string",
JSONName: "type",
Doc: `Type is the issue type (task, bug, etc).`,
},
{
Name: "Args",
Type: "map[string]string",
JSONName: "args",
Doc: `Args are additional context passed to the step.`,
},
{
Name: "Output",
Type: "map[string]string",
JSONName: "output",
Doc: `Output defines expected outputs from this step.`,
},
},
},
{
Name: "AroundAdvice",
Doc: `AroundAdvice wraps a target with before and after steps.`,
Fields: []FieldDoc{
{
Name: "Before",
Type: "[]*AdviceStep",
JSONName: "before",
Doc: `Before is a list of steps to insert before the target.`,
},
{
Name: "After",
Type: "[]*AdviceStep",
JSONName: "after",
Doc: `After is a list of steps to insert after the target.`,
},
},
},
{
Name: "BondPoint",
Doc: `BondPoint is a named attachment site for composition.`,
Fields: []FieldDoc{
{
Name: "ID",
Type: "string",
JSONName: "id",
Required: true,
Doc: `ID is the unique identifier for this bond point.`,
},
{
Name: "Description",
Type: "string",
JSONName: "description",
Doc: `Description explains what should be attached here.`,
},
{
Name: "AfterStep",
Type: "string",
JSONName: "after_step",
Doc: `AfterStep is the step ID after which to attach.
Mutually exclusive with BeforeStep.`,
},
{
Name: "BeforeStep",
Type: "string",
JSONName: "before_step",
Doc: `BeforeStep is the step ID before which to attach.
Mutually exclusive with AfterStep.`,
},
{
Name: "Parallel",
Type: "bool",
JSONName: "parallel",
Doc: `Parallel makes attached steps run in parallel with the anchor step.`,
},
},
},
{
Name: "BranchRule",
Doc: `BranchRule defines parallel execution paths that rejoin.
Creates a fork-join pattern: from -> [parallel steps] -> join.`,
Fields: []FieldDoc{
{
Name: "From",
Type: "string",
JSONName: "from",
Required: true,
Doc: `From is the step ID that precedes the parallel paths.
All branch steps will depend on this step.`,
},
{
Name: "Steps",
Type: "[]string",
JSONName: "steps",
Required: true,
Doc: `Steps are the step IDs that run in parallel.
These steps will all depend on From.`,
},
{
Name: "Join",
Type: "string",
JSONName: "join",
Required: true,
Doc: `Join is the step ID that follows all parallel paths.
This step will depend on all Steps completing.`,
},
},
},
{
Name: "ComposeRules",
Doc: `ComposeRules define how formulas can be bonded together.`,
Fields: []FieldDoc{
{
Name: "BondPoints",
Type: "[]*BondPoint",
JSONName: "bond_points",
Doc: `BondPoints are named locations where other formulas can attach.`,
},
{
Name: "Hooks",
Type: "[]*Hook",
JSONName: "hooks",
Doc: `Hooks are automatic attachments triggered by labels or conditions.`,
},
{
Name: "Expand",
Type: "[]*ExpandRule",
JSONName: "expand",
Doc: `Expand applies an expansion template to a single target step.
The target step is replaced by the expanded template steps.`,
},
{
Name: "Map",
Type: "[]*MapRule",
JSONName: "map",
Doc: `Map applies an expansion template to all steps matching a pattern.
Each matching step is replaced by the expanded template steps.`,
},
{
Name: "Branch",
Type: "[]*BranchRule",
JSONName: "branch",
Doc: `Branch defines fork-join parallel execution patterns.
Each rule creates dependencies for parallel paths that rejoin.`,
},
{
Name: "Gate",
Type: "[]*GateRule",
JSONName: "gate",
Doc: `Gate defines conditional waits before steps.
Each rule adds a condition that must be satisfied at runtime.`,
},
{
Name: "Aspects",
Type: "[]string",
JSONName: "aspects",
Doc: `Aspects lists aspect formula names to apply to this formula.
Aspects are applied after expansions, adding before/after/around
steps to matching targets based on the aspect's advice rules.
Example: ["security-audit", "logging"]`,
},
},
},
{
Name: "ExpandRule",
Doc: `ExpandRule applies an expansion template to a single target step.`,
Fields: []FieldDoc{
{
Name: "Target",
Type: "string",
JSONName: "target",
Required: true,
Doc: `Target is the step ID to expand.`,
},
{
Name: "With",
Type: "string",
JSONName: "with",
Required: true,
Doc: `With is the name of the expansion formula to apply.`,
},
{
Name: "Vars",
Type: "map[string]string",
JSONName: "vars",
Doc: `Vars are variable overrides for the expansion.`,
},
},
},
{
Name: "Formula",
Doc: `Formula is the root structure for .formula.json files.`,
Fields: []FieldDoc{
{
Name: "Formula",
Type: "string",
JSONName: "formula",
Required: true,
Doc: `Formula is the unique identifier/name for this formula.
Convention: mol-<name> for molecules, exp-<name> for expansions.`,
},
{
Name: "Description",
Type: "string",
JSONName: "description",
Doc: `Description explains what this formula does.`,
},
{
Name: "Version",
Type: "int",
JSONName: "version",
Required: true,
Doc: `Version is the schema version (currently 1).`,
},
{
Name: "Type",
Type: "FormulaType",
JSONName: "type",
Required: true,
Doc: `Type categorizes the formula: workflow, expansion, or aspect.`,
},
{
Name: "Extends",
Type: "[]string",
JSONName: "extends",
Doc: `Extends is a list of parent formulas to inherit from.
The child formula inherits all vars, steps, and compose rules.
Child definitions override parent definitions with the same ID.`,
},
{
Name: "Vars",
Type: "map[string]*VarDef",
JSONName: "vars",
Doc: `Vars defines template variables with defaults and validation.`,
},
{
Name: "Steps",
Type: "[]*Step",
JSONName: "steps",
Doc: `Steps defines the work items to create.`,
},
{
Name: "Template",
Type: "[]*Step",
JSONName: "template",
Doc: `Template defines expansion template steps (for TypeExpansion formulas).
Template steps use {target} and {target.description} placeholders
that get substituted when the expansion is applied to a target step.`,
},
{
Name: "Compose",
Type: "*ComposeRules",
JSONName: "compose",
Doc: `Compose defines composition/bonding rules.`,
},
{
Name: "Advice",
Type: "[]*AdviceRule",
JSONName: "advice",
Doc: `Advice defines step transformations (before/after/around).
Applied during cooking to insert steps around matching targets.`,
},
{
Name: "Pointcuts",
Type: "[]*Pointcut",
JSONName: "pointcuts",
Doc: `Pointcuts defines target patterns for aspect formulas.
Used with TypeAspect to specify which steps the aspect applies to.`,
},
{
Name: "Phase",
Type: "string",
JSONName: "phase",
Doc: `Phase indicates the recommended instantiation phase: "liquid" (pour) or "vapor" (wisp).
If "vapor", bd pour will warn and suggest using bd mol wisp instead.
Patrol and release workflows should typically use "vapor" since they're operational.`,
},
{
Name: "Pour",
Type: "bool",
JSONName: "pour",
Doc: `Pour controls whether steps are materialized as individual child issues.
If true, each step becomes a DB row with dependency tracking (checkpoint recovery).
If false (default), only the root issue is created; steps are read inline at prime time.
Reserve pour=true for critical, infrequent work (e.g. releases) where step-level
tracking is worth the DB overhead. Patrol formulas should NOT set this.`,
},
{
Name: "Source",
Type: "string",
JSONName: "source",
Doc: `Source tracks where this formula was loaded from (set by parser).`,
},
{
Name: "Intent",
Type: "string",
JSONName: "intent",
Doc: `Intent is an optional caller-defined hint about the formula's runtime
intent (e.g. "mail_only"). Opaque to bd; consumed by downstream tools.`,
},
},
},
{
Name: "Gate",
Doc: `Gate defines an async wait condition for formula steps.
When a step has a Gate, bd cook creates a gate issue that blocks the step.
The gate must be closed (manually or via watchers) to unblock the step.`,
Fields: []FieldDoc{
{
Name: "Type",
Type: "string",
JSONName: "type",
Required: true,
Doc: `Type is the condition type: gh:run, gh:pr, timer, human, mail.`,
},
{
Name: "ID",
Type: "string",
JSONName: "id",
Doc: `ID is the condition identifier (e.g., workflow name for gh:run).`,
},
{
Name: "AwaitID",
Type: "string",
JSONName: "await_id",
Doc: `AwaitID is the runtime condition identifier. This is preferred by
formula authors because it maps directly to Issue.AwaitID.`,
},
{
Name: "Timeout",
Type: "string",
JSONName: "timeout",
Doc: `Timeout is how long to wait before escalation (e.g., "1h", "24h").`,
},
},
},
{
Name: "GateRule",
Doc: `GateRule defines a condition that must be satisfied before a step proceeds.
Gates are evaluated at runtime by the patrol executor.`,
Fields: []FieldDoc{
{
Name: "Before",
Type: "string",
JSONName: "before",
Required: true,
Doc: `Before is the step ID that the gate applies to.
The condition must be satisfied before this step can start.`,
},
{
Name: "Condition",
Type: "string",
JSONName: "condition",
Required: true,
Doc: `Condition is the expression to evaluate.
Format matches condition evaluator syntax (e.g., "tests.status == 'complete'").`,
},
},
},
{
Name: "Hook",
Doc: `Hook defines automatic formula attachment based on conditions.`,
Fields: []FieldDoc{
{
Name: "Trigger",
Type: "string",
JSONName: "trigger",
Required: true,
Doc: `Trigger is what activates this hook.
Formats: "label:security", "type:bug", "priority:0-1".`,
},
{
Name: "Attach",
Type: "string",
JSONName: "attach",
Required: true,
Doc: `Attach is the formula to attach when triggered.`,
},
{
Name: "At",
Type: "string",
JSONName: "at",
Doc: `At is the bond point to attach at (default: end).`,
},
{
Name: "Vars",
Type: "map[string]string",
JSONName: "vars",
Doc: `Vars are variable overrides for the attached formula.`,
},
},
},
{
Name: "LoopSpec",
Doc: `LoopSpec defines iteration over a body of steps.
One of Count, Until, or Range must be specified.`,
Fields: []FieldDoc{
{
Name: "Count",
Type: "int",
JSONName: "count",
Doc: `Count is the fixed number of iterations.
When set, the loop body is expanded Count times.`,
},
{
Name: "Until",
Type: "string",
JSONName: "until",
Doc: `Until is a condition that ends the loop.
Format matches condition evaluator syntax (e.g., "step.status == 'complete'").`,
},
{
Name: "Max",
Type: "int",
JSONName: "max",
Doc: `Max is the maximum iterations for conditional loops.
Required when Until is set, to prevent unbounded loops.`,
},
{
Name: "Range",
Type: "string",
JSONName: "range",
Doc: `Range specifies a computed range for iteration.
Format: "start..end" where start and end can be:
- Integers: "1..10"
- Expressions: "1..2^{disks}" (evaluated at cook time)
- Variables: "{start}..{count}" (substituted from Vars)
Supports: + - * / ^ (power) and parentheses.`,
},
{
Name: "Var",
Type: "string",
JSONName: "var",
Doc: `Var is the variable name exposed to body steps.
For Range loops, this is set to the current iteration value.
Example: var: "move_num" with range: "1..7" exposes {move_num}=1,2,...,7`,
},
{
Name: "Body",
Type: "[]*Step",
JSONName: "body",
Required: true,
Doc: `Body contains the steps to repeat.`,
},
},
},
{
Name: "MapRule",
Doc: `MapRule applies an expansion template to all matching steps.`,
Fields: []FieldDoc{
{
Name: "Select",
Type: "string",
JSONName: "select",
Required: true,
Doc: `Select is a glob pattern matching step IDs to expand.
Examples: "*.implement", "shiny.*"`,
},
{
Name: "With",
Type: "string",
JSONName: "with",
Required: true,
Doc: `With is the name of the expansion formula to apply.`,
},
{
Name: "Vars",
Type: "map[string]string",
JSONName: "vars",
Doc: `Vars are variable overrides for the expansion.`,
},
},
},
{
Name: "OnCompleteSpec",
Doc: `OnCompleteSpec defines actions triggered when a step completes.
Used for runtime expansion over step output (the for-each construct).
Example YAML:
step: survey-workers
on_complete:
for_each: output.workers
bond: mol-worker-arm
vars:
worker_name: "{item.name}"
rig: "{item.rig}"
parallel: true`,
Fields: []FieldDoc{
{
Name: "ForEach",
Type: "string",
JSONName: "for_each",
Doc: `ForEach is the path to the iterable collection in step output.
Format: "output.<field>" or "output.<field>.<nested>"
The collection must be an array at runtime.`,
},
{
Name: "Bond",
Type: "string",
JSONName: "bond",
Doc: `Bond is the formula to instantiate for each item.
A new molecule is created for each element in the ForEach collection.`,
},
{
Name: "Vars",
Type: "map[string]string",
JSONName: "vars",
Doc: `Vars are variable bindings for each iteration.
Supports placeholders:
- {item} - the current item value (for primitives)
- {item.field} - a field from the current item (for objects)
- {index} - the zero-based iteration index`,
},
{
Name: "Parallel",
Type: "bool",
JSONName: "parallel",
Doc: `Parallel runs all bonded molecules concurrently (default behavior).
Set to true to make this explicit.`,
},
{
Name: "Sequential",
Type: "bool",
JSONName: "sequential",
Doc: `Sequential runs bonded molecules one at a time.
Each molecule starts only after the previous one completes.
Mutually exclusive with Parallel.`,
},
},
},
{
Name: "Pointcut",
Doc: `Pointcut defines a target pattern for advice application.
Used in aspect formulas to specify which steps the advice applies to.`,
Fields: []FieldDoc{
{
Name: "Glob",
Type: "string",
JSONName: "glob",
Doc: `Glob is a glob pattern to match step IDs.
Examples: "*.implement", "shiny.*", "review"`,
},
{
Name: "Type",
Type: "string",
JSONName: "type",
Doc: `Type matches steps by their type field.
Examples: "task", "bug", "epic"`,
},
{
Name: "Label",
Type: "string",
JSONName: "label",
Doc: `Label matches steps that have a specific label.`,
},
},
},
{
Name: "Step",
Doc: `Step defines a work item to create when the formula is instantiated.`,
Fields: []FieldDoc{
{
Name: "ID",
Type: "string",
JSONName: "id",
Required: true,
Doc: `ID is the unique identifier within this formula.
Used for dependency references and bond points.`,
},
{
Name: "Title",
Type: "string",
JSONName: "title",
Required: true,
Doc: `Title is the issue title (supports {{variable}} substitution).`,
},
{
Name: "Description",
Type: "string",
JSONName: "description",
Doc: `Description is the issue description (supports substitution).`,
},
{
Name: "Notes",
Type: "string",
JSONName: "notes",
Doc: `Notes are additional notes for the issue (supports substitution).`,
},
{
Name: "Type",
Type: "string",
JSONName: "type",
Doc: `Type is the issue type: task, bug, feature, epic, chore.`,
},
{
Name: "Priority",
Type: "*int",
JSONName: "priority",
Doc: `Priority is the issue priority (0-4).`,
},
{
Name: "Labels",
Type: "[]string",
JSONName: "labels",
Doc: `Labels are applied to the created issue.`,
},
{
Name: "Metadata",
Type: "map[string]interface{}",
JSONName: "metadata",
Doc: `Metadata is carried through to the created issue's Metadata field as
JSON. Lets formulas pre-declare keys that downstream tooling can project
without a post-pour compose step.`,
},
{
Name: "DependsOn",
Type: "[]string",
JSONName: "depends_on",
Doc: `DependsOn lists step IDs this step blocks on (within the formula).`,
},
{
Name: "Needs",
Type: "[]string",
JSONName: "needs",
Doc: `Needs is a simpler alias for DependsOn - lists sibling step IDs that must complete first.
Either Needs or DependsOn can be used; they are merged during cooking.`,
},
{
Name: "WaitsFor",
Type: "string",
JSONName: "waits_for",
Doc: `WaitsFor specifies a fanout gate type for this step.
Values: "all-children" (wait for all dynamic children) or "any-children" (wait for first).
When set, the cooked issue gets a "gate:<value>" label.`,
},
{
Name: "Assignee",
Type: "string",
JSONName: "assignee",
Doc: `Assignee is the default assignee (supports substitution).`,
},
{
Name: "Expand",
Type: "string",
JSONName: "expand",
Doc: `Expand references an expansion formula to inline here.
When set, this step is replaced by the expansion's template steps.
See ApplyInlineExpansions in expand.go for implementation.`,
},
{
Name: "ExpandVars",
Type: "map[string]string",
JSONName: "expand_vars",
Doc: `ExpandVars are variable overrides for the expansion.
Merged with the expansion formula's default vars during inline expansion.`,
},
{
Name: "Condition",
Type: "string",
JSONName: "condition",
Doc: `Condition makes this step optional based on a variable.
Format: "{{var}}" (truthy), "!{{var}}" (negated), "{{var}} == value", "{{var}} != value".
Evaluated at cook/pour time via FilterStepsByCondition.`,
},
{
Name: "Children",
Type: "[]*Step",
JSONName: "children",
Doc: `Children are nested steps (for creating epic hierarchies).`,
},
{
Name: "Gate",
Type: "*Gate",
JSONName: "gate",
Doc: `Gate defines an async wait condition for this step.
When set, bd cook creates a gate issue that blocks this step.
Close the gate issue (bd close bd-xxx.gate-stepid) to unblock.`,
},
{
Name: "Loop",
Type: "*LoopSpec",
JSONName: "loop",
Doc: `Loop defines iteration for this step.
When set, the step becomes a container that expands its body.`,
},
{
Name: "OnComplete",
Type: "*OnCompleteSpec",
JSONName: "on_complete",
Doc: `OnComplete defines actions triggered when this step completes.
Used for runtime expansion over step output (the for-each construct).`,
},
},
},
{
Name: "VarDef",
Doc: `VarDef defines a template variable with optional validation.`,
Fields: []FieldDoc{
{
Name: "Description",
Type: "string",
JSONName: "description",
Doc: `Description explains what this variable is for.`,
},
{
Name: "Default",
Type: "*string",
JSONName: "default",
Doc: `Default is the value to use if not provided.
nil means no default (variable must be provided if referenced).
Non-nil (including &"") means the variable has an explicit default.`,
},
{
Name: "Required",
Type: "bool",
JSONName: "required",
Doc: `Required indicates the variable must be provided (no default).`,
},
{
Name: "Enum",
Type: "[]string",
JSONName: "enum",
Doc: `Enum lists the allowed values (if non-empty).`,
},
{
Name: "Pattern",
Type: "string",
JSONName: "pattern",
Doc: `Pattern is a regex pattern the value must match.`,
},
{
Name: "Type",
Type: "string",
JSONName: "type",
Doc: `Type is the expected value type: string (default), int, bool.`,
},
},
},
{
Name: "WaitsForSpec",
Doc: `WaitsForSpec holds the parsed waits_for field.`,
Fields: []FieldDoc{
{
Name: "Gate",
Type: "string",
JSONName: "Gate",
Required: true,
Doc: `Gate is the gate type: "all-children" or "any-children"`,
},
{
Name: "SpawnerID",
Type: "string",
JSONName: "SpawnerID",
Required: true,
Doc: `SpawnerID is the step ID whose children to wait for.
Empty means infer from context (typically first step in needs).`,
},
},
},
}

View file

@ -0,0 +1,52 @@
package formula_test
import (
"os"
"path/filepath"
"runtime"
"testing"
"github.com/steveyegge/beads/internal/formula/schemagen"
)
// TestSchemaGenIsCurrent re-runs the schemagen walker over types.go
// in-memory and asserts the result byte-equals the committed schema_gen.go.
// Failure means someone changed types.go without running `go generate`.
func TestSchemaGenIsCurrent(t *testing.T) {
_, thisFile, _, ok := runtime.Caller(0)
if !ok {
t.Fatal("runtime.Caller failed")
}
pkgDir := filepath.Dir(thisFile)
typesPath := filepath.Join(pkgDir, "types.go")
committedPath := filepath.Join(pkgDir, "schema_gen.go")
want, err := os.ReadFile(committedPath)
if err != nil {
t.Fatalf("read %s: %v", committedPath, err)
}
got, err := schemagen.Generate(typesPath)
if err != nil {
t.Fatalf("schemagen.Generate: %v", err)
}
if string(got) != string(want) {
t.Fatalf("schema_gen.go is stale relative to types.go.\n"+
"Run `go generate ./...` from %s and commit the result.\n"+
"first diff at byte %d", pkgDir, firstDiff(got, want))
}
}
func firstDiff(a, b []byte) int {
n := len(a)
if len(b) < n {
n = len(b)
}
for i := 0; i < n; i++ {
if a[i] != b[i] {
return i
}
}
return n
}

View file

@ -0,0 +1,90 @@
package formula
import "testing"
func TestPrimitiveByName_ExactBeatsSuffixStrip(t *testing.T) {
// "gate" must resolve to Gate (the field-bearing struct), not GateRule.
// Same logic for any other Foo / FooRule / FooSpec collision.
cases := []struct {
input string
want string
}{
{"Gate", "Gate"},
{"gate", "Gate"},
{"gaterule", "GateRule"},
{"gate_rule", "GateRule"},
}
for _, c := range cases {
got := PrimitiveByName(c.input)
if got == nil {
t.Errorf("PrimitiveByName(%q) = nil, want %s", c.input, c.want)
continue
}
if got.Name != c.want {
t.Errorf("PrimitiveByName(%q) = %s, want %s", c.input, got.Name, c.want)
}
}
}
func TestPrimitiveByName_SuffixStripFallback(t *testing.T) {
cases := []struct {
input string
want string
}{
{"loop", "LoopSpec"},
{"Loop", "LoopSpec"},
{"loop_spec", "LoopSpec"},
{"on_complete", "OnCompleteSpec"},
{"OnComplete", "OnCompleteSpec"},
{"branch", "BranchRule"},
{"compose", "ComposeRules"},
{"map", "MapRule"},
{"expand", "ExpandRule"},
{"advice", "AdviceRule"},
{"waits_for", "WaitsForSpec"},
}
for _, c := range cases {
got := PrimitiveByName(c.input)
if got == nil {
t.Errorf("PrimitiveByName(%q) = nil, want %s", c.input, c.want)
continue
}
if got.Name != c.want {
t.Errorf("PrimitiveByName(%q) = %s, want %s", c.input, got.Name, c.want)
}
}
}
func TestPrimitiveByName_Unknown(t *testing.T) {
for _, in := range []string{"", "bogus", "thing-that-does-not-exist", "step!!!"} {
if got := PrimitiveByName(in); got != nil {
t.Errorf("PrimitiveByName(%q) = %s, want nil", in, got.Name)
}
}
}
func TestPrimitivesIndex_NonEmpty(t *testing.T) {
if len(Primitives) == 0 {
t.Fatal("Primitives is empty; did go generate run?")
}
// Spot-check a few that should always be present.
for _, name := range []string{"Formula", "Step", "LoopSpec", "OnCompleteSpec"} {
if PrimitiveByName(name) == nil {
t.Errorf("expected %s in Primitives index", name)
}
}
}
func TestPrimitivesIndex_StepExcludesSourceFields(t *testing.T) {
// Step.SourceFormula and Step.SourceLocation are tagged json:"-"
// and must never appear in the public schema.
step := PrimitiveByName("Step")
if step == nil {
t.Fatal("Step missing from Primitives")
}
for _, f := range step.Fields {
if f.Name == "SourceFormula" || f.Name == "SourceLocation" {
t.Errorf("Step exposes internal field %s; json:\"-\" fields must be filtered", f.Name)
}
}
}

View file

@ -0,0 +1,291 @@
// Package schemagen walks an internal/formula types.go file and produces
// the body of internal/formula/schema_gen.go (a `var Primitives` index of
// every exported struct). The package is consumed both by the standalone
// generator binary in cmd/schemagen and by the TestSchemaGenIsCurrent test
// in internal/formula.
package schemagen
import (
"bytes"
"fmt"
"go/ast"
"go/format"
"go/parser"
"go/printer"
"go/token"
"sort"
"strconv"
"strings"
)
// Primitive is the in-memory representation of one PrimitiveDoc. Kept
// distinct from formula.PrimitiveDoc to avoid an import cycle: this package
// generates the source that defines formula.Primitives.
type Primitive struct {
Name string
Doc string
Fields []Field
}
// Field is the in-memory representation of one FieldDoc.
type Field struct {
Name string
Type string
JSONName string
TOMLName string
Required bool
Doc string
}
// Generate parses typesPath and returns gofmt'd source for schema_gen.go.
// The output is deterministic given the same input.
func Generate(typesPath string) ([]byte, error) {
prims, err := Parse(typesPath)
if err != nil {
return nil, err
}
return Render(prims)
}
// Parse extracts every exported struct in typesPath, sorted by name.
func Parse(typesPath string) ([]Primitive, error) {
fset := token.NewFileSet()
file, err := parser.ParseFile(fset, typesPath, nil, parser.ParseComments)
if err != nil {
return nil, fmt.Errorf("parse %s: %w", typesPath, err)
}
var prims []Primitive
for _, decl := range file.Decls {
gen, ok := decl.(*ast.GenDecl)
if !ok || gen.Tok != token.TYPE {
continue
}
for _, spec := range gen.Specs {
ts, ok := spec.(*ast.TypeSpec)
if !ok {
continue
}
if !ts.Name.IsExported() {
continue
}
st, ok := ts.Type.(*ast.StructType)
if !ok {
continue
}
doc := extractDoc(ts.Doc, gen.Doc)
fields := collectFields(fset, st)
prims = append(prims, Primitive{
Name: ts.Name.Name,
Doc: doc,
Fields: fields,
})
}
}
sort.Slice(prims, func(i, j int) bool {
return prims[i].Name < prims[j].Name
})
return prims, nil
}
func collectFields(fset *token.FileSet, st *ast.StructType) []Field {
if st.Fields == nil {
return nil
}
var fields []Field
for _, f := range st.Fields.List {
jsonTag, tomlTag := extractTags(f.Tag)
// Skip fields explicitly excluded from JSON serialization — these
// are internal implementation details (e.g. Step.SourceFormula).
if jsonTag.name == "-" {
continue
}
typeStr := renderType(fset, f.Type)
doc := extractDoc(f.Doc, nil)
for _, name := range f.Names {
if !name.IsExported() {
continue
}
jsonName := jsonTag.name
if jsonName == "" {
jsonName = name.Name
}
tomlName := tomlTag.name
if tomlName == "" {
tomlName = jsonName
}
required := !jsonTag.omitempty && jsonTag.name != "-"
fields = append(fields, Field{
Name: name.Name,
Type: typeStr,
JSONName: jsonName,
TOMLName: tomlName,
Required: required,
Doc: doc,
})
}
}
return fields
}
type structTag struct {
name string
omitempty bool
}
func extractTags(tag *ast.BasicLit) (jsonTag, tomlTag structTag) {
if tag == nil {
return
}
raw, err := strconv.Unquote(tag.Value)
if err != nil {
return
}
st := newReflectStructTag(raw)
if v, ok := st.lookup("json"); ok {
jsonTag = parseTagValue(v)
}
if v, ok := st.lookup("toml"); ok {
tomlTag = parseTagValue(v)
}
return
}
func parseTagValue(v string) structTag {
parts := strings.Split(v, ",")
t := structTag{name: parts[0]}
for _, p := range parts[1:] {
if p == "omitempty" {
t.omitempty = true
}
}
return t
}
// reflectStructTag is a tiny stand-in for reflect.StructTag.Lookup that
// avoids depending on reflect at codegen time. Behavior matches the stdlib:
// keys are space-separated, values are double-quoted.
type reflectStructTag string
func newReflectStructTag(s string) reflectStructTag { return reflectStructTag(s) }
func (t reflectStructTag) lookup(key string) (string, bool) {
tag := string(t)
for tag != "" {
i := 0
for i < len(tag) && tag[i] == ' ' {
i++
}
tag = tag[i:]
if tag == "" {
break
}
i = 0
for i < len(tag) && tag[i] > ' ' && tag[i] != ':' && tag[i] != '"' {
i++
}
if i == 0 || i+1 >= len(tag) || tag[i] != ':' || tag[i+1] != '"' {
break
}
name := tag[:i]
tag = tag[i+1:]
i = 1
for i < len(tag) && tag[i] != '"' {
if tag[i] == '\\' {
i++
}
i++
}
if i >= len(tag) {
break
}
quoted := tag[:i+1]
tag = tag[i+1:]
if name == key {
value, err := strconv.Unquote(quoted)
if err != nil {
return "", false
}
return value, true
}
}
return "", false
}
func renderType(fset *token.FileSet, expr ast.Expr) string {
var buf bytes.Buffer
cfg := printer.Config{Mode: printer.RawFormat, Tabwidth: 8}
if err := cfg.Fprint(&buf, fset, expr); err != nil {
return fmt.Sprintf("<unprintable: %v>", err)
}
return buf.String()
}
func extractDoc(primary, fallback *ast.CommentGroup) string {
g := primary
if g == nil {
g = fallback
}
if g == nil {
return ""
}
return strings.TrimRight(g.Text(), "\n")
}
// Render emits a gofmt'd schema_gen.go body from prims.
func Render(prims []Primitive) ([]byte, error) {
var buf bytes.Buffer
buf.WriteString("// Code generated by internal/formula/cmd/schemagen. DO NOT EDIT.\n")
buf.WriteString("\n")
buf.WriteString("package formula\n")
buf.WriteString("\n")
buf.WriteString("// Primitives is the discoverability index of every exported struct in\n")
buf.WriteString("// types.go. Surfaced via `bd formula schema`. Regenerate with `go generate ./...`.\n")
buf.WriteString("var Primitives = []PrimitiveDoc{\n")
for _, p := range prims {
buf.WriteString("\t{\n")
fmt.Fprintf(&buf, "\t\tName: %q,\n", p.Name)
if p.Doc != "" {
fmt.Fprintf(&buf, "\t\tDoc: %s,\n", goStringLit(p.Doc))
}
if len(p.Fields) > 0 {
buf.WriteString("\t\tFields: []FieldDoc{\n")
for _, f := range p.Fields {
buf.WriteString("\t\t\t{\n")
fmt.Fprintf(&buf, "\t\t\t\tName: %q,\n", f.Name)
fmt.Fprintf(&buf, "\t\t\t\tType: %q,\n", f.Type)
fmt.Fprintf(&buf, "\t\t\t\tJSONName: %q,\n", f.JSONName)
if f.TOMLName != "" && f.TOMLName != f.JSONName {
fmt.Fprintf(&buf, "\t\t\t\tTOMLName: %q,\n", f.TOMLName)
}
if f.Required {
buf.WriteString("\t\t\t\tRequired: true,\n")
}
if f.Doc != "" {
fmt.Fprintf(&buf, "\t\t\t\tDoc: %s,\n", goStringLit(f.Doc))
}
buf.WriteString("\t\t\t},\n")
}
buf.WriteString("\t\t},\n")
}
buf.WriteString("\t},\n")
}
buf.WriteString("}\n")
return format.Source(buf.Bytes())
}
// goStringLit emits a Go string literal — backtick-quoted when the content
// is "clean" (no backticks, no control chars except newline), otherwise
// double-quoted via strconv.Quote so escapes survive.
func goStringLit(s string) string {
if strings.ContainsRune(s, '`') {
return strconv.Quote(s)
}
for _, r := range s {
if r < 0x20 && r != '\n' && r != '\t' {
return strconv.Quote(s)
}
}
return "`" + s + "`"
}

View file

@ -22,8 +22,16 @@ Search paths (in order):
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Commands:
list List available formulas from all search paths
show Show formula details, steps, and composition rules
list List available formulas from all search paths
show Show formula details, steps, and composition rules
schema Show the formula schema index (alias: primitives)
Discovering primitives:
bd formula schema # list every declared formula struct
bd formula schema loop # show LoopSpec fields, types, and tags
bd formula primitives gate # alias; same handler as 'schema'
examples/formulas/primitives/ # curated, smoke-tested wired fixtures
website/docs/workflows/formulas.md # narrative reference
```
bd formula [flags]
@ -72,6 +80,9 @@ Search paths (in order of priority):
Formulas in earlier paths shadow those with the same name in later paths.
To list the declared formula schema structs an agent can write inside a .formula.toml,
use 'bd formula schema' (alias: 'bd formula primitives').
Examples:
bd formula list
bd formula list --json
@ -88,6 +99,30 @@ bd formula list [flags]
--type string Filter by type (workflow, expansion, aspect, convoy)
```
### bd formula schema
Show the formula schema index: every exported struct declared
in a .formula.toml/.formula.json, with field names, types, and tags.
The index is generated from internal/formula/types.go via go:generate; the
struct definitions are the source of truth, so this list cannot drift. It is
structural reference, not proof that every declared runtime behavior is wired.
Examples:
bd formula schema # list every declared schema struct
bd formula schema loop # show LoopSpec fields
bd formula primitives gate # alias; shows Gate fields
bd formula schema --json # machine-readable index
Curated smoke-tested fixtures for wired primitives live in
examples/formulas/primitives/ (with a smoke harness that proves they work).
```
bd formula schema [primitive]
```
**Aliases:** primitives
### bd formula show
Show detailed information about a formula.
@ -99,6 +134,9 @@ Displays:
- Composition rules (extends, aspects, expansions)
- Bond points for external composition
To inspect the structure of an individual primitive (e.g. LoopSpec, Gate)
rather than a user-authored formula, use 'bd formula schema &lt;primitive&gt;'.
Examples:
bd formula show shiny
bd formula show rule-of-five

View file

@ -117,16 +117,10 @@ position = "before"
### Hooks
Execute actions on step completion:
```toml
[[steps]]
id = "build"
title = "Build project"
[steps.on_complete]
run = "make build"
```
Step-completion hooks are not currently exposed as runnable formula
actions. The historical `on_complete.run` example was invalid: `run` is
not a formula field, and `on_complete` runtime expansion is tracked
separately until it is wired end to end.
### Pinning Work

View file

@ -22,8 +22,16 @@ Search paths (in order):
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Commands:
list List available formulas from all search paths
show Show formula details, steps, and composition rules
list List available formulas from all search paths
show Show formula details, steps, and composition rules
schema Show the formula schema index (alias: primitives)
Discovering primitives:
bd formula schema # list every declared formula struct
bd formula schema loop # show LoopSpec fields, types, and tags
bd formula primitives gate # alias; same handler as 'schema'
examples/formulas/primitives/ # curated, smoke-tested wired fixtures
website/docs/workflows/formulas.md # narrative reference
```
bd formula
@ -72,6 +80,9 @@ Search paths (in order of priority):
Formulas in earlier paths shadow those with the same name in later paths.
To list the declared formula schema structs an agent can write inside a .formula.toml,
use 'bd formula schema' (alias: 'bd formula primitives').
Examples:
bd formula list
bd formula list --json
@ -88,6 +99,30 @@ bd formula list [flags]
--type string Filter by type (workflow, expansion, aspect, convoy)
```
### bd formula schema
Show the formula schema index: every exported struct declared
in a .formula.toml/.formula.json, with field names, types, and tags.
The index is generated from internal/formula/types.go via go:generate; the
struct definitions are the source of truth, so this list cannot drift. It is
structural reference, not proof that every declared runtime behavior is wired.
Examples:
bd formula schema # list every declared schema struct
bd formula schema loop # show LoopSpec fields
bd formula primitives gate # alias; shows Gate fields
bd formula schema --json # machine-readable index
Curated smoke-tested fixtures for wired primitives live in
examples/formulas/primitives/ (with a smoke harness that proves they work).
```
bd formula schema [primitive]
```
**Aliases:** primitives
### bd formula show
Show detailed information about a formula.
@ -99,6 +134,9 @@ Displays:
- Composition rules (extends, aspects, expansions)
- Bond points for external composition
To inspect the structure of an individual primitive (e.g. LoopSpec, Gate)
rather than a user-authored formula, use 'bd formula schema &lt;primitive&gt;'.
Examples:
bd formula show shiny
bd formula show rule-of-five

View file

@ -256,24 +256,10 @@ The `max` field is required for `until` loops to prevent unbounded iteration.
## Runtime Expansion (on_complete)
Steps can trigger dynamic work when they complete using `on_complete` with `for_each`:
```toml
[[steps]]
id = "survey"
title = "Survey available workers"
[steps.on_complete]
for_each = "output.workers"
bond = "worker-arm"
parallel = true
[steps.on_complete.vars]
worker_name = "{item.name}"
rig = "{item.rig}"
```
This creates a new molecule from the `worker-arm` formula for each item in the `output.workers` array. Use `sequential = true` instead of `parallel` to run them one at a time.
`on_complete` is present in the formula schema, but runtime expansion is
not wired end to end in the current release. Do not author new formulas
that depend on `on_complete` creating follow-up molecules until the
runtime implementation ships with a smoke-tested primitive example.
## Formula Inheritance

View file

@ -117,16 +117,10 @@ position = "before"
### Hooks
Execute actions on step completion:
```toml
[[steps]]
id = "build"
title = "Build project"
[steps.on_complete]
run = "make build"
```
Step-completion hooks are not currently exposed as runnable formula
actions. The historical `on_complete.run` example was invalid: `run` is
not a formula field, and `on_complete` runtime expansion is tracked
separately until it is wired end to end.
### Pinning Work