v2.4.2

# What's Changed in v2.4.2

This release focuses on **completion integrity**, **preflight validation**, **spec-driven pipeline alignment**, and a major **KISS cleanup** removing ~2,500 lines of dead code and redundant presets.

## Highlights

- 🔒 **Loop completion now requires a proper JSONL event** — agents can no longer confabulate completion by printing the completion promise string; they must emit it via `ralph emit` (#141)
- 🛫 **`ralph preflight` validates your environment before orchestration starts** — catches misconfigured backends, dirty git state, and incomplete specs before wasting iterations (#146)
- 🧹 **KISS cleanup across 8 items** — removed chaos_mode dead code (~560 LOC), 13 redundant presets, and reduced constraint density in SOPs by 77% (253 → 59 MUSTs) (#146)

## Features

- **Completion only via JSONL event**: `LOOP_COMPLETE` is now only accepted as a structured event, preventing agents from confabulating completion (#141)
- **Graceful `/stop` command**: New Telegram `/stop` and CLI `ralph stop` for clean loop shutdown via signal file (#141)
- **`ralph bot token set`**: Secure Telegram bot token management with keychain support (#141)
- **`ralph preflight`**: Environment validation (backends, git state, spec completeness) that auto-runs before `ralph run` (#146)
- **`ralph doctor`**: Diagnostic command to inspect local environment, similar to `brew doctor` (#146)
- **`ralph tutorial`**: Interactive onboarding for first-time users (#146)
- **`ralph skill list`**: Improved skill discovery across nested directories and parent workspaces (#146)
- **Persistent mode**: `persistent: true` keeps the loop alive after `LOOP_COMPLETE` for daemon-style orchestration (#146)
- **Self-Healer hat**: Five automated recovery strategies (rollback, skip, reduce-scope, fallback, escalate) (#146)
- **Spec acceptance criteria parser & test stub generation**: Structured Given/When/Then extraction with 1:1 test stub mapping for TDD automation (#146)
- **Spec verification backpressure gate**: Blocks `build.done` when spec acceptance criteria aren't satisfied by passing tests (#146)
- **New backpressure gates**: cargo audit, coverage, verifier quality, and performance regression (#146)
- **`extra_instructions` config**: YAML anchors for sharing instruction blocks across hats (#146)
- **Separate `human_pending` queue**: Human-in-the-loop events get their own EventBus queue, preventing message drops during busy iterations (#146)
- **TUI shows max iterations**: Header displays `[iter 3/50]` for operator visibility (#146)
- **`--yolo` flag for Codex adapter**: Enables unattended Codex operation (#146)
- **Session recorder behind feature flag**: `recording` feature gate reduces default binary size (#146)

## Fixes

- **Fix `human.interact` event file resolution**: `wait_for_response()` now reads from the `current-events` marker instead of hardcoded `events.jsonl`, fixing responses never being received (#146)
- **Fix wide character rendering in TUI**: `ContentPane` now uses `unicode-width` for proper emoji/CJK display (#146)
- **Preserve TUI iteration buffers across `task.start`**: No longer wipes output history and iteration count on task reset (#146)
- **Fix UTF-8 boundary truncation**: Content truncation no longer splits multi-byte characters (#146)
- **Fix nested skill discovery**: Skills in nested directories and parent workspaces are now found correctly (#146)
- **Allow partial merge queue ID resolution**: `ralph loops merge` accepts prefix matches (#146)
- **Drain PTY output after exit**: Last lines of agent output in TUI mode are no longer lost (#146)
- **Resolve 26 clippy warnings**: Accumulated pedantic warnings cleaned up across workspace (#146)

## Documentation

- Fix `.agent/` paths to `.ralph/agent/` in concept docs (#144) — thanks @Ahmed-Abdalla-Abdelrehim!
- Rename `interact.human` → `human.interact` for naming consistency (#146)
- Updated installation guide, getting started tutorial, and backend configuration docs (#146)
- Added Rust code examples to API reference docs (#146)
- Added GitHub issue templates (#146)

## Refactors & Cleanup

- **Remove chaos_mode dead code** (~560 LOC across 10 files) (#146)
- **Remove 13 redundant presets**, slimming from 27 to 14 core presets (#146)
- **Decouple telegram from core** via `RobotService` trait in ralph-proto, enabling future Slack/Discord backends (#146)
- **Consolidate ralph-loop + ralph-diagnostics** into single ralph-operations skill (-318 LOC) (#146)
- **Unify TDD skills** into single test-driven-development skill with 3 input modes (-240 LOC) (#146)
- **Remove unused ralph-adapters dep from ralph-tui** (#146)
- **Reduce SOP constraint density by 77%** (code-assist: 111→32, PDD: 85→19, code-task-generator: 57→8 MUSTs) (#146)

## Testing

- Massive test coverage expansion: 20+ test commits adding integration tests for preflight, run, presets, skills, tasks, web, and more (#146)

**Full Changelog**: https://github.com/mikeyobrien/ralph-orchestrator/compare/v2.4.1...v2.4.2

---

# ralph-bench 2.4.2

## Install ralph-bench 2.4.2

### Install prebuilt binaries via shell script

```sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-bench-installer.sh | sh
```

### Install prebuilt binaries into your npm project

```sh
npm install @ralph-orchestrator/ralph-bench@2.4.2
```

## Download ralph-bench 2.4.2

|  File  | Platform | Checksum |
|--------|----------|----------|
| [ralph-bench-aarch64-apple-darwin.tar.xz](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-bench-aarch64-apple-darwin.tar.xz) | Apple Silicon macOS | [checksum](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-bench-aarch64-apple-darwin.tar.xz.sha256) |
| [ralph-bench-x86_64-apple-darwin.tar.xz](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-bench-x86_64-apple-darwin.tar.xz) | Intel macOS | [checksum](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-bench-x86_64-apple-darwin.tar.xz.sha256) |
| [ralph-bench-aarch64-unknown-linux-gnu.tar.xz](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-bench-aarch64-unknown-linux-gnu.tar.xz) | ARM64 Linux | [checksum](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-bench-aarch64-unknown-linux-gnu.tar.xz.sha256) |
| [ralph-bench-x86_64-unknown-linux-gnu.tar.xz](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-bench-x86_64-unknown-linux-gnu.tar.xz) | x64 Linux | [checksum](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-bench-x86_64-unknown-linux-gnu.tar.xz.sha256) |

# ralph-cli 2.4.2

## Install ralph-cli 2.4.2

### Install prebuilt binaries via shell script

```sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-cli-installer.sh | sh
```

### Install prebuilt binaries into your npm project

```sh
npm install @ralph-orchestrator/ralph-cli@2.4.2
```

## Download ralph-cli 2.4.2

|  File  | Platform | Checksum |
|--------|----------|----------|
| [ralph-cli-aarch64-apple-darwin.tar.xz](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-cli-aarch64-apple-darwin.tar.xz) | Apple Silicon macOS | [checksum](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-cli-aarch64-apple-darwin.tar.xz.sha256) |
| [ralph-cli-x86_64-apple-darwin.tar.xz](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-cli-x86_64-apple-darwin.tar.xz) | Intel macOS | [checksum](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-cli-x86_64-apple-darwin.tar.xz.sha256) |
| [ralph-cli-aarch64-unknown-linux-gnu.tar.xz](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-cli-aarch64-unknown-linux-gnu.tar.xz) | ARM64 Linux | [checksum](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-cli-aarch64-unknown-linux-gnu.tar.xz.sha256) |
| [ralph-cli-x86_64-unknown-linux-gnu.tar.xz](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-cli-x86_64-unknown-linux-gnu.tar.xz) | x64 Linux | [checksum](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-cli-x86_64-unknown-linux-gnu.tar.xz.sha256) |

# ralph-e2e 2.4.2

## Install ralph-e2e 2.4.2

### Install prebuilt binaries via shell script

```sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-e2e-installer.sh | sh
```

### Install prebuilt binaries into your npm project

```sh
npm install @ralph-orchestrator/ralph-e2e@2.4.2
```

## Download ralph-e2e 2.4.2

|  File  | Platform | Checksum |
|--------|----------|----------|
| [ralph-e2e-aarch64-apple-darwin.tar.xz](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-e2e-aarch64-apple-darwin.tar.xz) | Apple Silicon macOS | [checksum](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-e2e-aarch64-apple-darwin.tar.xz.sha256) |
| [ralph-e2e-x86_64-apple-darwin.tar.xz](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-e2e-x86_64-apple-darwin.tar.xz) | Intel macOS | [checksum](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-e2e-x86_64-apple-darwin.tar.xz.sha256) |
| [ralph-e2e-aarch64-unknown-linux-gnu.tar.xz](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-e2e-aarch64-unknown-linux-gnu.tar.xz) | ARM64 Linux | [checksum](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-e2e-aarch64-unknown-linux-gnu.tar.xz.sha256) |
| [ralph-e2e-x86_64-unknown-linux-gnu.tar.xz](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-e2e-x86_64-unknown-linux-gnu.tar.xz) | x64 Linux | [checksum](https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.4.2/ralph-e2e-x86_64-unknown-linux-gnu.tar.xz.sha256) |