Imports:
  - Types:
      - ProjectConfig
      - BuildConfig
      - TaskExecutorConfig
      - load_project_config
    From: goga/config
  - Types:
      - resolve_wrapper_path
    Usages:
      - resolve-wrapper-path
    From: goga/agents
  - Types:
      - ensure_in_docker
    Usages:
      - ensure-in-docker
    From: goga/docker
  - Types:
      - run_ralphex
    Usages:
      - run-ralphex
    From: goga/ralphex

Usages:
  conventions: .goga/usages/conventions.md
  ralphex: .goga/usages/cooks/ralphex.md
  agent-wrappers: .goga/usages/cooks/agent-as-claude-wrappers.md

Annotations: |
  The `conventions` practice is used for:
  - Working with the codebase
  - Organizing the REPL development cycle
  - Debugging and testing
  - Organizing the test infrastructure
  - Understanding the general principles and rules of development and testing in the project

  This cell owns the build domain: manifest-commit verification, agent-wrapper resolution,
  ralphex config generation, default prompt/agent copying, and ralphex option resolution
  (CLI > ProjectConfig > omit). It delegates the ralphex launch to `run_ralphex` from
  goga/ralphex (per the `run-ralphex` practice) — ralphex is launched through `run_ralphex`,
  never directly from this cell.

  Use the `conventions` practice for development and testing.
  Use the `ralphex` practice for the ralphex config-generation contract (the .ralphex/config
  key layout written before launch).
  Use the `agent-wrappers` practice for the in-container wrapper naming convention referenced
  when writing claude_command into .ralphex/config.
  Use the `resolve-wrapper-path` practice when calling `resolve_wrapper_path`.
  Use the `run-ralphex` practice from Imports to delegate the launch.
  Write all output to sys.stderr (click is not used).
  Run git external commands via subprocess (the manifest pre-check).

---

"build(plan: str, config: ProjectConfig, cli_options: dict) -> exit_code:int":
  location: build.py
  annotations: |
    Orchestrates code builds through `ralphex`. The function prepares the
    execution environment and launches the build runner.

    `plan`: path to the plan file (markdown)
    `config`: loaded project configuration object
    `cli_options`: dictionary of CLI options (dry_run, worktree, skip_finalize,
                   skip_manifest_check, session_timeout, idle_timeout,
                   wait, max_iterations, review_patience)
    `exit_code`: process exit code (0 = success, 1 = failure)

    Algorithm:
    0. (pre-check) When skip_manifest_check is not set:
       - Verify all project CODEMANIFEST files are committed to git
       - Reject with exit code 1 if any uncommitted manifests are found
    1. Resolve the agent wrapper path by calling `resolve_wrapper_path` with the agent
       field of `TaskExecutorConfig`, per the `resolve-wrapper-path` practice (absolute
       in-container path /home/goga/bin/<name>-as-claude.sh per `agent-wrappers`)
    2. Generate the .ralphex/config file with the resolved agent, per the `ralphex` practice:
       - set claude_command to the resolved wrapper path
       - apply claude_args defaults when missing
       - set codex_enabled from `BuildConfig`
       - set preserve_anthropic_api_key to true
    3. Copy default prompts and agents from the goga package to .ralphex/, using the
       directory paths specified in `BuildConfig`
    4. Resolve the ralphex options with precedence CLI options > `BuildConfig` > omit,
       producing the resolved options for `run_ralphex` (precedence applied HERE in the
       domain — `run_ralphex` performs no precedence resolution)
    5. Delegate the launch to `run_ralphex` (per the `run-ralphex` practice), passing
       `plan`, the resolved options, and dry_run, and return its exit code

    Apply `conventions` for docstring style and intra-package imports.
    Apply `ralphex` for the config-generation contract.
    Apply `agent-wrappers` for the wrapper path semantics in step 2.
    Apply `resolve-wrapper-path` when calling `resolve_wrapper_path` in step 1.
    Apply `run-ralphex` when delegating the launch in step 5.

    Requirements:
    - `ralphex` is launched only through `run_ralphex` — never via a direct subprocess call
    - Return code: the exit code returned by `run_ralphex` (ralphex exit code on success, 1 on error)
    - Minimal output: log each step to sys.stderr
    - claude_command in .ralphex/config MUST be the resolved wrapper path
    - preserve_anthropic_api_key in .ralphex/config MUST be true
    - Resolve ralphex option precedence (CLI > ProjectConfig > omit) before delegating

    Constraints:
    - Wrappers live in the image at /home/goga/bin/ and are referenced by absolute path
    - Agent resolution is uniform — do not branch by agent name
    - Do not assemble the ralphex command or invoke ralphex directly — delegate to `run_ralphex`
    - The .ralphex/ directory lifecycle is owned by the host launcher (goga/commands/build)

"main() -> exit_code:int":
  location: __main__.py
  annotations: |
    Entry point for python -m goga.build execution inside a Docker container.

    `exit_code`: process exit code (0 = success, 1 = failure)

    Algorithm:
    0. Call `ensure_in_docker` as the very first statement — refuse to proceed
       when the process is not running inside the goga Docker image (per the
       `ensure-in-docker` practice)
    1. Parse CLI arguments via argparse (plan + options)
    2. Load project configuration via `load_project_config`
    3. Build cli_options from the parsed argparse results
    4. Invoke `build`(plan, `ProjectConfig`, cli_options)
    5. Return the resulting `exit_code`

    Requirements:
    - The guard at step 0 MUST be covered by tests for both branches:
      success path with GOGA_DOCKER=1 proceeds to argparse; refusal path
      without the marker writes to stderr and exits with code 1 before any
      filesystem or process work

    Apply the `ensure-in-docker` practice at step 0.

---

Author: Mikhail Trifonov
CreatedAt: 15/05/26

Description: |
  Manifest describing the code build orchestration logic through ralphex
