ralph.conf

# ralph.conf — project-specific values for the Ralph harness (archi).
#
# Plain shell, sourced by ralph.sh. Precedence:
#   environment  >  ralph.conf  >  script built-in default
# KEY="value", no spaces around `=`, `#` starts a comment.

# --- where the loop operates -------------------------------------------------

# Bind-mount target inside the container (see Makefile: -v $(CURDIR):/workspace).
RALPH_WORKSPACE="/workspace"

# Task list the loop reads the first unchecked task from, relative to workspace.
# Here `tasks.md` is a symlink to the active OpenSpec change's task list:
#   tasks.md -> openspec/changes/add-title-aware-retrieval/tasks.md
# so the loop and OpenSpec stay a single source of truth.
RALPH_TASKS="tasks.md"

# Runtime state dir (heartbeat, per-turn logs, status feed). Gitignored.
RALPH_STATE_DIR=".ralph"

# (Meta) path to THIS config file. Set as an environment variable only, to point
# the scripts at a config that is not ./ralph.conf. Default: ./ralph.conf
# RALPH_CONF="/path/to/ralph.conf"

# --- agent / turn behaviour --------------------------------------------------

# Model id passed to `claude --model`. Empty = account default.
# This is the DEFAULT model, used for any task not tagged with a work class below.
RALPH_MODEL=""

# --- work-class model dispatch (optional cost dial) --------------------------
#
# Match the model to each task's WORK CLASS instead of running one model for
# everything. Tag a task in tasks.md with a trailing class token, e.g.
#     - [ ] 2.3 migrate the session store (stateful)
# and map that class to a model here with a RALPH_MODEL_<CLASS> key (the class
# upper-cased, hyphens -> underscores, so "(pure-logic)" -> RALPH_MODEL_PURE_LOGIC).
# The runner then passes that model as `claude --model` for that task's turn. An
# UNTAGGED task uses RALPH_MODEL above, exactly as before — so this is INERT until
# you both tag tasks and set keys (precedence is env > ralph.conf > default, same
# as every key here).
#
# Classification is YOUR call — the runner never auto-classifies. It is a cost
# dial, not a correctness lever: a misclassified task can at worst stall (the gate
# + commit-as-truth remain the correctness guarantee), never ship a bad commit.
# Spend the stronger model where work is stateful/integration-heavy and run a
# cheaper one on well-specified pure logic. Uncomment and set to your model ids:
# RALPH_MODEL_STATEFUL=""   # stronger model, for stateful/integration tasks tagged (stateful)
# RALPH_MODEL_PURE=""       # cheaper model, for well-specified pure tasks tagged (pure)

# Per-turn wall-clock cap (s). Exceeding it kills + retries the turn. Default 1200.
RALPH_TURN_TIMEOUT="1200"

# Consecutive no-commit turns before the loop halts for review. Default 2.
RALPH_MAX_STALLS="2"

# Fallback wait (s) when a usage-limit reset time can't be parsed. Default 900.
RALPH_LIMIT_POLL="900"

# Inter-turn sleep in loop mode (s). Default 30.
RALPH_POLL_INTERVAL="30"

# --- aggregate log (for an external log aggregator) --------------------------

# Write a single append-only $RALPH_STATE_DIR/log/live.log that interleaves the
# runner's narration with each turn's agent output, every line turn-prefixed and
# ISO-timestamped — one stable tail target for an aggregator (Vector, Logstash,
# …) or a bare `tail -f`. The per-turn turn-<n>.txt files and status.jsonl are
# unaffected. 1 = on, 0 = reproduce the pre-feature behaviour exactly. Default 1.
RALPH_LIVE_LOG="1"

# --- outer-loop review gate (ON by default — this loop is GitHub-dependent) --
#
# After a turn commits, the RUNNER (never the agent) pushes the branch, ensures a
# PR, requests an independent review, and reads the verdict: PASS = zero findings
# AND green CI. Findings go to review-findings.md and become the agent's top
# priority next turn. Requires a git remote, authenticated `gh`, and a non-base
# feature branch (all verified during ralph-init for this repo).

# 1 = push -> PR -> review -> verdict cycle; 0 = offline inner loop. Default 1.
RALPH_REVIEW_GATE="1"

# 1 merges a PASSED PR into the base branch; 0 leaves it for a human. Default 0.
RALPH_AUTO_MERGE="0"

# Consecutive review rounds still producing findings before halting. Default 3.
RALPH_REVIEW_MAX_ROUNDS="3"

# PR base branch. Empty = origin's default branch. archi PRs target `dev`.
RALPH_BASE_BRANCH="dev"

# Reviewer command (`<cmd> <pr-number>`). Empty = built-in GitHub Copilot reviewer.
RALPH_REVIEWER=""

# --- outbound notification (opt-in — ping a human when the loop needs one) ----
#
# The RUNNER (never the agent) invokes this command as `<cmd> <event> <reason>` at
# every needs-human halt — events: review-exhausted, stall, stop, blocked (a new
# docs/questions.md entry). Notification is NON-FATAL: a notifier that errors,
# hangs, or is slow is killed and ignored, never changing the loop's exit code.
# Empty = off. SECURITY: the notifier runs IN the container, so any secret it needs
# (e.g. SLACK_WEBHOOK_URL) lives in the container env — treat it as GH_TOKEN-grade.
RALPH_NOTIFY_CMD=""

# Seconds the notifier may run before it is killed (kept short — a halt is not
# latency-sensitive, and a hung notifier must not delay the halt). Default 30.
RALPH_NOTIFY_TIMEOUT="30"

# The file the agent writes a blocked question to (a decision the specs don't
# cover). A NEW entry mid-run stops the loop immediately with a `blocked`
# notification, instead of burning RALPH_MAX_STALLS no-commit turns first. A
# pre-existing list does NOT stop a fresh loop. Default docs/questions.md.
RALPH_QUESTIONS="docs/questions.md"

# --- container probing (status digest + Makefile) ---------------------------

# Loop container / image name (matches Makefile IMAGE).
RALPH_CONTAINER="archi-loop"

# Container runtime CLI.
RALPH_RUNTIME="podman"