Build

Execute an approved plan — the bridge between the workflow and actual code. The build engine reads the plan and produces the implementation, one task per iteration, inside an isolated Docker container.

Synopsis

goga build <plan> [OPTIONS]

The full reference — options, configuration, exit codes, and the step-by-step algorithm — lives in the goga build CLI reference.

What happens during a build

1. The host side validates preconditions: Docker is reachable, the build configuration is present with an agent, no CODEMANIFEST files are left uncommitted, and the host and image goga versions agree (see Runtime — Pre-launch version check).
2. The image is refreshed only with --update; a declared project Dockerfile is built once automatically on the first run even without it.
3. The build launches inside the configured image. Persistent build state lives under ~/.goga/runtime/builds/<project>/<branch>/ on the host — never inside the project directory — and survives across runs, so an interrupted build can be resumed (--clean wipes it for a fresh start).
4. Inside the container, the build engine executes the plan: one task per iteration, following the execution protocol (declaration → contract tests → implementation → interface verification → logic tests → debugging → contract re-verification → lint → completion → review → approval → next task). CODEMANIFEST files remain read-only throughout the build.
5. After a successful final pass, the plan moves to <plan_dir>/completed/<plan_name>. A failed run leaves it in place for resumption.

A run with review on is always two passes — a tasks pass on the build.agent wrapper, then a review pass on the review agent's wrapper (build.review.agent, inheriting build.agent when unset). --skip-review (or build.review.skip: true) runs a tasks-only pass; a failed tasks pass skips the review. Before the first pass, the build/validate_build hooks gate may veto the run.

When to use

• After plan and review(plan), when the plan is approved.
• Whenever an execution plan exists under .goga/history/ and is ready to be executed.

Inputs and outputs

Input	.goga/history/<year>/<topic>/plan.md — the execution plan
Output	Implemented code in the project tree; after a successful run the plan itself moves to .goga/history/<year>/<topic>/completed/plan.md

Examples

goga build .goga/history/<year>/json-export/plan.md
goga build .goga/history/<year>/json-export/plan.md --dry-run
goga build .goga/history/<year>/json-export/plan.md --clean   # fresh state

What happens next

• The completed plan now lives in .goga/history/<year>/<topic>/completed/ — nothing further reads it, but it stays for reference.
• Test the produced implementation manually.
• If bugs or defects are found — fix them with change.
• Once the implementation is stable — run accept for final sign-off.