BOI v2

Single-binary Rust harness for orchestrating LLM-powered software-engineering tasks.

✅ CANONICAL BOI (2026-06-03). This repo is the canonical BOI engine — TOML specs ([contract] + [[tasks]]), control-socket daemon, ~/.boi/v2/boi.db. The older boi 2.0.0 at https://github.com/mrap/boi is LEGACY v1 (YAML), frozen. Note the inverted version numbers: this canonical engine reports boi 0.1.0; legacy v1 reports boi 2.0.0. Decision: mrap-hex/me/decisions/boi-canonical-lineage-2026-06-03.md. Cutover (flipping the ~/.boi/bin/boi shim + installer to this engine) is gated on a hardening checklist — until it passes, dispatch via the real binary directly: ~/github.com/mrap/boi-v2/target/release/boi dispatch <spec.toml> (the ~/.boi/bin/boi shim still resolves to v1). See mrap-hex/projects/boi/HOW-TO-DISPATCH-TODAY.md.

Status: canonical engine, hardening to the cutover gate. Reports boi 0.1.0. v1 (boi 2.0.0) at https://github.com/mrap/boi is frozen/legacy.

Build

Requires Rust 1.85+ (pinned via rust-toolchain.toml to floating stable, MSRV enforced via Cargo.toml's rust-version) and a C compiler (for bundled DuckDB).

cargo build --locked

For a fast dev loop without DuckDB compile cost:

cargo check --no-default-features

Dev workflow

brew install just                # if not installed
just                             # list recipes
just check                       # fmt + clippy + test
just lint-scripts                # 3 LDA checks
just ci                          # full local CI suite
just smoke                       # build + run binary

SQLx offline cache (required for the repo layer)

The repo layer uses sqlx::query! macros, which are verified against a live database at compile time. CI runs with SQLX_OFFLINE=true and reads a committed query cache in .sqlx/ — so a fresh clone builds without a database.

Regenerating that cache (only needed when a sqlx::query! macro changes) is a one-time dev-tool install plus a just recipe:

cargo install sqlx-cli --no-default-features --features sqlite,rustls
just prep-sqlx                    # creates .dev.db, migrates, writes .sqlx/

just prep-sqlx reads DATABASE_URL from a gitignored .env (DATABASE_URL=sqlite://.dev.db). Commit the resulting .sqlx/ delta in the same commit as the query change.

Architecture

Single Rust crate. Layered Domain Architecture via module structure:

src/types → src/config → src/repo → src/service → src/runtime → src/cli

Forward-only deps; enforced by scripts/checks/module-dep-audit.sh. LLM phases route through runtime::goose::GooseRuntime (invokes goose run --recipe X.yaml); deterministic phases (workspace verify, validate, commit, merge, teardown) are native Rust functions in runtime::deterministic::DETERMINISTIC_STEPS.

Design source of truth

• docs/design/2026-05-16-design.md — main design (1467 lines, fully locked)
• docs/design/2026-05-17-goose-as-runtime-adapter.md — Goose amendment (Adopted)
• docs/research/frameworks-survey-2026-05-16.md — validates greenfield direction
• docs/plans/2026-05-19-boi-v2-implementation-plan.md — this implementation plan
• docs/plans/phase-0-team-review/99-consensus.md — 4-lens Phase-0 review consensus

License

MIT.