beads/examples/formulas/primitives
Julian Knutsen 47eb06e66a docs(bazel): make bazel test the primary build and test path (ga-96smfk.23)
Bazel is beads' build and test system: bazel.yml's lanes gate every PR,
and nogo (lint + vet), gofmt and the repository guards exist only as
Bazel targets. The docs, the Makefile and the hooks now say so.

Makefile: `make test` runs bazel.yml's test lane (`bazel test //...
--config=ci`), `make check` adds the testing.Short policy and the
`make ci-pr-lint` nogo gate, and `make check-docs` runs the docsync and
doc-freshness Bazel targets before the pinned-release CLI flag check.
BAZEL_FLAGS passes --config=fork-cache or --config=remote-exec through.
The plain-Go recipes stay as explicit twins: test-go, check-go,
check-docs-go. No workflow called the primary names, and
TestWorkflowsNameTheirTestEngine keeps it that way.

Hooks: pre-push runs scripts/pre-push-suite.sh for branch pushes whose
commits change Go or Bazel inputs: the test lane with
--config=remote-exec when some rc names an executor, else
--config=fork-cache. Without bazel, or with BD_PREPUSH_SUITE=go, it runs
make test-go under a banner saying that is not what CI gates on.

Docs: AGENTS.md, CONTRIBUTING.md, engdocs/TESTING.md (a per-lane command
table and the fork-cache/remote-exec setup), README, RELEASING, the PR
template and the .bazelrc header. Bazelisk is a required prerequisite;
go test is an inner-loop convenience CI does not enforce.

Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-07 07:12:47 +00:00
..
branch-fanin.formula.toml feat(formula): make primitives discoverable to coding agents (GH#3621) (#3781) 2026-07-06 22:26:41 -07:00
children-epic.formula.toml feat(formula): make primitives discoverable to coding agents (GH#3621) (#3781) 2026-07-06 22:26:41 -07:00
condition.formula.toml feat(formula): make primitives discoverable to coding agents (GH#3621) (#3781) 2026-07-06 22:26:41 -07:00
gate-timer.formula.toml feat(formula): make primitives discoverable to coding agents (GH#3621) (#3781) 2026-07-06 22:26:41 -07:00
loop-count.formula.toml feat(formula): make primitives discoverable to coding agents (GH#3621) (#3781) 2026-07-06 22:26:41 -07:00
loop-range.formula.toml feat(formula): make primitives discoverable to coding agents (GH#3621) (#3781) 2026-07-06 22:26:41 -07:00
README.md docs(bazel): make bazel test the primary build and test path (ga-96smfk.23) 2026-10-07 07:12:47 +00:00

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:

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:

bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestFormulaPrimitiveExamples$'

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.