@ralph-orchestrator/ralph-cli 2.9.2 → 2.10.0

package/CHANGELOG.md

@@ -4,7 +4,61 @@ All notable changes to ralph-orchestrator are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [2.10.0] - 2026-06-21
+
+### Added
+
+- Forge CLI backend integration.
+- RObot (human-in-the-loop) RPC domain in the control plane, plus a file-backed web mode that drives human interaction through files instead of a live socket.
+- Worktree loops can publish remote review branches, with rebase support.
+- Local file-based hat imports in preflight, including import resolution and schema validation with imported-file context.
+- On-demand export of TUI iteration buffers to disk: `e` exports the current iteration, `E` exports all iterations.
+- Context-window utilization telemetry, surfaced in the TUI.
+
+### Changed
+
+- Updated the Pi backend package reference to `@earendil-works/pi-coding-agent`.
+- Refreshed agent waves observability documentation and added the hat imports design spec.
+
+### Fixed
+
+- TUI search mode now captures typed query characters instead of leaking them to keybindings (e.g. an `e` in the query no longer triggers export); the `Search:` prompt, `N/M` match counter, and `n`/`N` navigation work again.
+- Runtime now requires an explicit completion signal after guidance, preventing premature loop termination.
+- Persist loop continue state across iterations.
+- Honor per-hat scratchpad configuration in generated instructions.
+- Drain ACP terminal output before exit so the final output is no longer truncated.
+- Canonicalize Ralph artifact paths to avoid path-mismatch errors.
+- Deduplicate MCP tool schemas exposed over the API.
+
+## [2.9.3] - 2026-05-08
+
+### Added
+
+- `ralph-docs` skill for `llms.txt`-driven introspection.
+- Unified preset mechanism under `-H <name>`, supporting both YAML and TOML presets.
+- `ralph plan` support for the kiro-acp backend, including a completion fallback.
+- Visual workflow editor (builder) with live agent observation.
+- Per-hat scratchpad configuration.
+- Hats can set a cancellation promise.
+- Improved `--no-tui` UX with a loop banner, per-iteration footer, and resume hint.
+
+### Changed
+
+- Switched Linux distribution targets to musl for Amazon Linux 2 / 2023 compatibility.
+- Documented global user config for hooks, added an FAQ section, and linked the autoloop authoring guide for the TOML preset format.
+
+### Fixed
+
+- Claude child sessions now default to `--setting-sources project,local`, preventing host user-level `~/.claude/settings.json` hooks, plugins, and MCP servers from leaking into Ralph orchestration runs. Users who want the old behavior can opt back in with `cli.args: ["--setting-sources", "user,project,local"]`.
+- Route the text completion fallback through `check_completion_event()`.
+- Propagate the `RALPH_EVENTS_FILE` env var and preserve late termination reasons.
+- Prevent lingering text backends from stalling loop progression.
+- Resolve Rust 1.95 `duration_suboptimal_units` clippy warnings.
+
+### Security
+
+- Replaced `source` with a safe variable parser in `sync-embedded-files.sh`.
+- Use `npm ci` instead of `npm install` in `test-fresh-install.sh`.
 
 ## [2.9.2] - 2026-04-10
 

package/README.md

@@ -46,10 +46,10 @@ ralph init --backend claude
 
 # 2. Plan your feature (interactive PDD session)
 ralph plan "Add user authentication with JWT"
-# Creates: specs/user-authentication/requirements.md, design.md, implementation-plan.md
+# Creates: .ralph/specs/user-authentication/requirements.md, design.md, implementation-plan.md
 
 # 3. Implement the feature
-ralph run -p "Implement the feature in specs/user-authentication/"
+ralph run -p "Implement the feature in .ralph/specs/user-authentication/"
 ```
 
 Ralph iterates until it outputs `LOOP_COMPLETE` or hits the iteration limit.
@@ -135,7 +135,7 @@ Use this mode from an MCP client configuration rather than an interactive termin
 
 Ralph implements the [Ralph Wiggum technique](https://ghuntley.com/ralph/) — autonomous task completion through continuous iteration. It supports:
 
-- **Multi-Backend Support** — Claude Code, Kiro, Gemini CLI, Codex, Amp, Copilot CLI, OpenCode
+- **Multi-Backend Support** — Claude Code, Kiro, Gemini CLI, Codex, Forge, Amp, Copilot CLI, OpenCode
 - **Hat System** — Specialized personas coordinating through events
 - **Backpressure** — Gates that reject incomplete work (tests, lint, typecheck)
 - **Memories & Tasks** — Persistent learning and runtime work tracking
@@ -181,6 +181,88 @@ Full documentation is available at **[mikeyobrien.github.io/ralph-orchestrator](
 - [Concepts: Hats & Events](https://mikeyobrien.github.io/ralph-orchestrator/concepts/hats-and-events/)
 - [Architecture](https://mikeyobrien.github.io/ralph-orchestrator/advanced/architecture/)
 
+
+## FAQ
+
+### General
+
+**What is Ralph Orchestrator?**
+Ralph is a hat-based orchestration framework that implements the Ralph Wiggum technique — autonomous task completion through continuous iteration. It keeps AI agents in a loop until the task is done, supporting multiple backends like Claude Code, Gemini CLI, Codex, and more.
+
+**How is Ralph different from other AI coding tools?**
+Unlike single-shot AI assistants, Ralph iterates until completion using a "hat system" with specialized personas. It includes backpressure gates (tests, lint, typecheck) that reject incomplete work, plus persistent memories and tasks for continuous learning.
+
+### Installation & Setup
+
+**What are the system requirements?**
+- Rust 1.75+ (for the `ralph-api` component)
+- Node.js >= 18 + npm (for the web dashboard frontend)
+- An AI coding assistant CLI (Claude Code, Codex, Gemini CLI, etc.)
+
+**Which installation method should I use?**
+- **npm** (recommended for most users): `npm install -g @ralph-orchestrator/ralph-cli`
+- **Cargo**: `cargo install ralph-cli` (best for Rust developers)
+- **GitHub Releases installer**: One-link install with `curl ... | sh`
+
+**Is Homebrew supported?**
+Homebrew is not currently published from this repository's automated release flow. Prefer npm, Cargo, or the GitHub Releases installer.
+
+### Usage
+
+**How do I start a new project with Ralph?**
+```bash
+ralph init --backend claude
+ralph plan "Add user authentication with JWT"
+ralph run -p "Implement the feature in .ralph/specs/user-authentication/"
+```
+
+**What backends does Ralph support?**
+Claude Code, Kiro, Gemini CLI, Codex, Forge, Amp, Copilot CLI, and OpenCode.
+
+**What is the "hat system"?**
+Ralph uses specialized personas (hats) that coordinate through events. Each hat has a specific role — code-assist, debug, research, review, and pdd-to-code-assist — enabling structured multi-step task execution.
+
+### RObot (Human-in-the-Loop)
+
+**What is RObot?**
+RObot enables human interaction during orchestration via Telegram. Agents can ask questions and block until answered; humans can send proactive guidance mid-loop.
+
+**How do I set up Telegram integration?**
+```bash
+ralph bot onboard --telegram   # guided setup
+ralph bot status               # verify config
+ralph bot test                 # send a test message
+```
+
+### Web Dashboard
+
+**How do I access the web dashboard?**
+Run `ralph web` to start the Rust RPC API + frontend and open your browser. The dashboard is currently in Alpha — expect rough edges and breaking changes.
+
+**Can I customize the dashboard ports?**
+Yes: `ralph web --backend-port 4000 --frontend-port 8080`
+
+### MCP Server
+
+**How do I run Ralph as an MCP server?**
+```bash
+ralph mcp serve --workspace-root /path/to/repo
+```
+Each MCP server instance is scoped to a single workspace root. For multi-repo use, run one instance per workspace.
+
+### Troubleshooting
+
+**Ralph fails to start with "node_modules not found"**
+Run `npm install` in the project directory, or let `ralph web` auto-detect and install on first run.
+
+**How do I set up Node.js if not installed?**
+Use nvm (recommended): `nvm install` (reads `.nvmrc`), or install directly from https://nodejs.org/
+
+**Where can I get help?**
+- Join our [Discord server](https://discord.gg/XWUyeUNffh)
+- Report bugs on the [Issue Tracker](https://github.com/mikeyobrien/ralph-orchestrator/issues)
+- Read full documentation at [mikeyobrien.github.io/ralph-orchestrator](https://mikeyobrien.github.io/ralph-orchestrator/)
+
 ## Contributing
 
 Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.

package/npm-shrinkwrap.json

@@ -23,7 +23,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "@ralph-orchestrator/ralph-cli",
-      "version": "2.9.2"
+      "version": "2.10.0"
     },
     "node_modules/@isaacs/balanced-match": {
       "engines": {
@@ -515,5 +515,5 @@
     }
   },
   "requires": true,
-  "version": "2.9.2"
+  "version": "2.10.0"
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "artifactDownloadUrl": "https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.9.2",
+  "artifactDownloadUrl": "https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.10.0",
   "bin": {
     "ralph": "run-ralph.js"
   },
@@ -20,7 +20,7 @@
   },
   "glibcMinimum": {
     "major": 2,
-    "series": 35
+    "series": 31
   },
   "homepage": "https://github.com/mikeyobrien/ralph-orchestrator",
   "license": "MIT",
@@ -41,7 +41,21 @@
       "zipExt": ".tar.xz"
     },
     "aarch64-unknown-linux-gnu": {
-      "artifactName": "ralph-cli-aarch64-unknown-linux-gnu.tar.xz",
+      "artifactName": "ralph-cli-aarch64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "ralph": "ralph"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "aarch64-unknown-linux-musl-dynamic": {
+      "artifactName": "ralph-cli-aarch64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "ralph": "ralph"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "aarch64-unknown-linux-musl-static": {
+      "artifactName": "ralph-cli-aarch64-unknown-linux-musl.tar.xz",
       "bins": {
         "ralph": "ralph"
       },
@@ -55,14 +69,28 @@
       "zipExt": ".tar.xz"
     },
     "x86_64-unknown-linux-gnu": {
-      "artifactName": "ralph-cli-x86_64-unknown-linux-gnu.tar.xz",
+      "artifactName": "ralph-cli-x86_64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "ralph": "ralph"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-unknown-linux-musl-dynamic": {
+      "artifactName": "ralph-cli-x86_64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "ralph": "ralph"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-unknown-linux-musl-static": {
+      "artifactName": "ralph-cli-x86_64-unknown-linux-musl.tar.xz",
       "bins": {
         "ralph": "ralph"
       },
       "zipExt": ".tar.xz"
     }
   },
-  "version": "2.9.2",
+  "version": "2.10.0",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"