ralphctl 0.18.0 → 0.20.0

package/README.md

@@ -8,6 +8,7 @@
 [![Claude Code](https://img.shields.io/badge/Claude_Code-supported-191919?style=flat&logo=anthropic&logoColor=white)](https://docs.anthropic.com/en/docs/claude-code)
 [![GitHub Copilot CLI](https://img.shields.io/badge/GitHub_Copilot_CLI-supported-000?style=flat&logo=githubcopilot&logoColor=white)](https://docs.github.com/en/copilot/github-copilot-in-the-cli)
 [![OpenAI Codex CLI](https://img.shields.io/badge/OpenAI_Codex_CLI-supported-412991?style=flat&logo=openai&logoColor=white)](https://github.com/openai/codex)
+[![OpenCode](https://img.shields.io/badge/OpenCode-supported-f59e0b?style=flat&logo=opencollective&logoColor=white)](https://opencode.ai/)
 [![Built with Donuts](https://img.shields.io/badge/%F0%9F%8D%A9-Built_with_Donuts-ff6f00?style=flat)](https://github.com/lukas-grigis/ralphctl)
 
 <p align="center">
@@ -18,18 +19,15 @@
 
 **A ralph harness for long-running AI coding tasks — a hardened ralph loop that drives your coding agent of choice
 ([Claude Code](https://docs.anthropic.com/en/docs/claude-code),
-[GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli), or
-[OpenAI Codex CLI](https://github.com/openai/codex)) across one or more repositories.**
+[GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli),
+[OpenAI Codex CLI](https://github.com/openai/codex), or [OpenCode](https://opencode.ai/)) across one or more
+repositories.**
 
 > _"I'm helping!"_ — Ralph Wiggum
 
 > [!NOTE]
-> **Active development.** New features and polish ship regularly. All three providers — Claude Code,
-> GitHub Copilot CLI, and OpenAI Codex CLI — are supported; pick one per flow or mix them, in one command,
-> from a preset matrix of 20 presets across five families (`standard`, `economic`, `strong-gate`, `fast`,
-> `frontier`), each in `mixed` / `claude-only` / `copilot-only` / `codex-only` variants.
-> Upgrades are best-effort: install the latest version, redo your config, proceed.
-> See [Upgrading](#upgrading) and [CHANGELOG](./CHANGELOG.md).
+> **Active development.** New features and polish ship regularly. Upgrades are best-effort: install the
+> latest version, redo your config, proceed. See [Upgrading](#upgrading) and [CHANGELOG](./CHANGELOG.md).
 
 ---
 
@@ -50,7 +48,7 @@ plan → generate → evaluate → verify loop turns one-shot prompting into a r
 
 AI coding agents are powerful but lose context on long tasks, need babysitting when things break, and have no way to
 coordinate changes across multiple repositories. ralphctl wraps your chosen AI CLI — Claude Code, GitHub Copilot CLI,
-or OpenAI Codex CLI — in a
+OpenAI Codex CLI, or OpenCode — in a
 structured harness that decomposes your work into dependency-ordered tasks, drives each one through
 a [generator-evaluator loop](https://www.anthropic.com/engineering/harness-design-long-running-apps) that catches issues
 before moving on, and persists context across sessions so nothing gets lost.
@@ -67,14 +65,32 @@ npm install -g ralphctl
 
 > Needs [Node.js](https://nodejs.org/) ≥ 24 — `mise use node@24` or `nvm install 24`.
 
-Install one of the supported CLIs — [Claude Code](https://docs.anthropic.com/en/docs/claude-code),
-[GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli), or
-[OpenAI Codex CLI](https://github.com/openai/codex) — and authenticate it, then confirm ralphctl can see it:
+Want to poke around before setting up a provider CLI? `ralphctl demo` seeds a throwaway sandbox
+project (three sprints, one per pre-flow state) and launches straight into it — zero setup:
 
 ```bash
-ralphctl doctor    # verifies your provider CLI is installed + authenticated — the #1 first-run failure
+ralphctl demo
 ```
 
+Otherwise, install one of the supported CLIs and authenticate it:
+
+| CLI                                                                                | Install                              | Auth                  |
+| ---------------------------------------------------------------------------------- | ------------------------------------ | --------------------- |
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code)                      | `npm i -g @anthropic-ai/claude-code` | Anthropic account     |
+| [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) | `npm i -g @github/copilot`           | GitHub Copilot seat   |
+| [OpenAI Codex CLI](https://github.com/openai/codex)                                | `npm i -g @openai/codex`             | ChatGPT / OpenAI      |
+| [OpenCode](https://opencode.ai/)                                                   | `npm i -g opencode-ai`               | your own key, or none |
+
+Then confirm ralphctl can see it:
+
+```bash
+ralphctl doctor    # checks your provider CLI is on PATH — and reports auth for the CLIs that can answer — the #1 first-run failure
+```
+
+`doctor`'s auth check is only as honest as each CLI lets it be: Claude Code and OpenAI Codex answer locally via their own
+`auth status` / `login status` verbs, OpenCode reports whether it has a saved credential (its free tier works with zero),
+and GitHub Copilot has no non-interactive auth-status command at all — that row always reports `unknown`, not a guess.
+
 When `doctor` is green, launch:
 
 ```bash
@@ -87,7 +103,7 @@ flow (refine / plan / implement / readiness / …), or open the Sprints submenu
 or create a sprint. No commands to memorize.
 
 **Requirements:** [Node.js](https://nodejs.org/) ≥ 24, [Git](https://git-scm.com/), and one supported AI CLI in `PATH`
-and authenticated.
+and authenticated (OpenCode takes your own keys, or runs on its free tier with none).
 
 <details>
 <summary>Prefer the CLI for inspection + one-shot operations?</summary>
@@ -120,7 +136,7 @@ ralphctl export-context --sprint <id> --project <id> --output <path>
 
 # Settings
 ralphctl settings show
-ralphctl settings apply-preset claude-only     # or mixed / copilot-only / codex-only / *-economic / *-strong-gate / *-fast / *-frontier
+ralphctl settings apply-preset claude-only     # or mixed / copilot-only / codex-only / opencode-only / *-economic / *-strong-gate / *-fast / *-frontier
 ralphctl settings set ai.implement.generator.provider claude-code
 ralphctl settings set ai.implement.generator.model    <model-id>
 ralphctl settings set ai.implement.generator.effort   high
@@ -134,19 +150,21 @@ ralphctl settings set ai.implement.evaluator.model    <model-id>
 
 ## How It Works
 
-```
-  You describe what to build              ralphctl drives it to done
-  ─────────────────────────              ────────────────────────────────────────────
-  ┌──────────┐   ┌──────────┐        ┌────────┐   ┌──────┐   ┌───────────┐   ┌────────┐
-  │  Create  │──>│   Add    │───────>│ Refine │──>│ Plan │──>│ Implement │──>│ Review │──> done
-  │  Sprint  │   │ Tickets  │        │ (WHAT) │   │(HOW) │   │   Loop    │   │  Loop  │
-  └──────────┘   └──────────┘        └────────┘   └──────┘   └───────────┘   └────────┘
-                                         │            │            │             │
-                                    AI clarifies  AI builds   AI implements  you steer
-                                    requirements  the task    + AI reviews   revisions,
-                                    with you      graph       each task      close to done
+```mermaid
+flowchart LR
+    A[Create sprint] --> B[Add tickets] --> C[Refine] --> D[Plan] --> E[Implement] --> F[Review] --> G[Done]
+
+    classDef you fill:#eef2ff,stroke:#6366f1,color:#1e1b4b
+    classDef ai fill:#ecfdf5,stroke:#10b981,color:#052e16
+    classDef end_ fill:#f1f5f9,stroke:#94a3b8,color:#0f172a
+    class A,B you
+    class C,D,E,F ai
+    class G end_
 ```
 
+The first two steps are yours (blue); from **Refine** onward ralphctl drives (green), with approval gates where
+your judgement matters.
+
 **Refine** is implementation-agnostic: the AI clarifies requirements with you, ticket by ticket, and flips each one from
 `pending` to `approved`. **Plan** requires every ticket approved — the AI explores the affected repos and generates a
 dependency-ordered task graph. **Implement** drives those tasks in dependency order through a generator-evaluator cycle:
@@ -156,13 +174,41 @@ loop — once every task lands, the sprint enters `review` and you run human-ste
 the AI revises, and the sprint flips to `done` when you're satisfied. Opening a PR (`ralphctl create-pr`) is separate
 and optional.
 
+The loop inside **Implement** is what separates a ralph harness from a bare `while` loop — every task passes an
+independent reviewer before the harness moves on:
+
+```mermaid
+flowchart LR
+    T[Next task] --> G[Generator] --> E{Evaluator}
+    E -->|pass| V{Verify}
+    E -->|fail| R[Retry]
+    V -->|green| D[Done]
+    V -->|red| R
+    R --> G
+    R -.->|attempts exhausted| B[Blocked]
+
+    classDef work fill:#ecfdf5,stroke:#10b981,color:#052e16
+    classDef gate fill:#fefce8,stroke:#eab308,color:#422006
+    classDef ok fill:#f1f5f9,stroke:#94a3b8,color:#0f172a
+    classDef bad fill:#fef2f2,stroke:#ef4444,color:#450a0a
+    class T,G,R work
+    class E,V gate
+    class D ok
+    class B bad
+```
+
+Both gates send the task back, but they spend different budgets: a failed review re-runs the generator
+_within_ the same attempt (up to `harness.maxTurns` turns), while a red verify fails the attempt outright and
+opens a fresh one (up to `harness.maxAttempts`, after which the task is flagged `blocked`).
+
 Key properties:
 
 - **Dependency-ordered execution** — tasks run in topological order; no task starts until its blockers are done.
   Opt-in parallelism (`concurrency.maxParallelTasks` > 1) runs independent tasks within a dependency wave concurrently,
   each in its own git worktree folded onto one branch — default stays serial
 - **Generator-evaluator cycle** — an independent AI reviewer checks each task; if it fails, the generator gets the
-  critique and iterates (up to `harness.maxAttempts` tries before the task is flagged `blocked`)
+  critique and iterates (up to `harness.maxTurns` turns per attempt, across at most `harness.maxAttempts`
+  attempts before the task is flagged `blocked`)
 - **Context persistence** — sprint state, branch, progress history, and per-task context survive across sessions;
   interrupted runs resume automatically
 - **Multi-repo support** — one sprint can span several repositories with per-repo setup and verify scripts
@@ -174,26 +220,45 @@ For the full architectural picture see [`.claude/docs/ARCHITECTURE.md`](./.claud
 
 ## Providers
 
-ralphctl drives three AI coding CLIs. Choose one per flow — or mix them, say plan with one and implement with
-another — through a [preset](#configuration) or per-row settings. All three are supported and in everyday use.
+ralphctl drives four AI coding CLIs. All four run every flow and are supported first-class. Pick one per
+flow — or mix them, say plan with one and implement with another — through a [preset](#configuration) or
+per-row settings.
+
+| Provider                                  | CLI        | Install                              | Auth                  | Context file                      |
+| ----------------------------------------- | ---------- | ------------------------------------ | --------------------- | --------------------------------- |
+| **Claude Code** (`claude-code`)           | `claude`   | `npm i -g @anthropic-ai/claude-code` | Anthropic account     | `CLAUDE.md`                       |
+| **GitHub Copilot CLI** (`github-copilot`) | `copilot`  | `npm i -g @github/copilot`           | GitHub Copilot seat   | `.github/copilot-instructions.md` |
+| **OpenAI Codex CLI** (`openai-codex`)     | `codex`    | `npm i -g @openai/codex`             | ChatGPT / OpenAI      | `AGENTS.md`                       |
+| **OpenCode** (`opencode`)                 | `opencode` | `npm i -g opencode-ai`               | your own key, or none | `AGENTS.md`                       |
+
+**Which one?**
+
+- **Claude Code** — read-only flows deny the edit, shell and network tools at the CLI level, the finest-grained
+  gate of the four.
+- **GitHub Copilot CLI** — no extra billing relationship if you already have a seat. Read-only flows deny the
+  shell tool; file writes stay open, bounded by path scope.
+- **OpenAI Codex CLI** — a natural fit inside the ChatGPT/OpenAI ecosystem. Its sandbox has two modes only,
+  so path scope is the fine-grained safety envelope.
+- **OpenCode** — vendor-neutral: it fronts 75+ providers and local runtimes on a bring-your-own-key model, so
+  you can run a specific model, a local model, or no account at all.
+
+On every backend the `Write` tool stays open by design — the harness's `signals.json` lands through it — so
+path scope (cwd + mounted roots) is always part of the safety envelope. See the
+[provider reference](./docs/providers.md#permission-model-per-backend) for the exact mapping.
+
+Bundled skill injection and forensic capture work on all four; only the on-disk skills directory differs
+(`.claude/` / `.github/` / `.agents/` / `.opencode/`). Parallel execution is provider-agnostic. Claude Code
+has the most real-world mileage simply because it came first — the others are equally supported, with
+correspondingly less of it.
 
-| Provider                                  | CLI       | Headless permission mapping                                                                     | Native context file               |
-| ----------------------------------------- | --------- | ----------------------------------------------------------------------------------------------- | --------------------------------- |
-| **Claude Code** (`claude-code`)           | `claude`  | `--permission-mode bypassPermissions` + per-tool deny list                                      | `CLAUDE.md` at repo root          |
-| **GitHub Copilot CLI** (`github-copilot`) | `copilot` | `--autopilot --max-autopilot-continues=200` + `--allow-all` (per-tool deny list when read-only) | `.github/copilot-instructions.md` |
-| **OpenAI Codex CLI** (`openai-codex`)     | `codex`   | `-s workspace-write` (topology-scoped)                                                          | `AGENTS.md`                       |
+📖 **[Full provider reference →](./docs/providers.md)** — permission mapping per backend, per-provider setup,
+model ids, mixing backends, and known limitations.
 
-Claude Code has the most end-to-end mileage inside the harness — it's the most battle-tested of the three — but Copilot
-and Codex run every flow and are supported first-class. Two small differences worth knowing: bundled skill injection
-and `bodyFile` forensic artifacts currently no-op on Copilot and Codex, and Codex's sandbox has only two modes
-(read-only / workspace-write), so path scope (cwd + `--add-dir`) is its fine-grained safety envelope rather than a
-per-tool deny list. Parallel execution is provider-agnostic — it works with whichever provider each implement role is
-configured to use. Hit a rough edge with any provider? Please [open an
-issue](https://github.com/lukas-grigis/ralphctl/issues).
+Hit a rough edge with any provider? Please [open an issue](https://github.com/lukas-grigis/ralphctl/issues).
 
-One-shot configuration for any provider: `ralphctl settings apply-preset <name>` where `<name>` is one of
-20 presets across five families — `standard`, `economic`, `strong-gate`, `fast`, and `frontier`, each in
-`mixed` / `claude-only` / `copilot-only` / `codex-only` variants.
+One-shot configuration: `ralphctl settings apply-preset <name>` where `<name>` is one of 21 presets —
+`standard`, `economic`, `strong-gate`, `fast`, and `frontier` families, each in `mixed` / `claude-only` /
+`copilot-only` / `codex-only` variants, plus `opencode-only`.
 
 ---
 
@@ -215,6 +280,8 @@ One-shot configuration for any provider: `ralphctl settings apply-preset <name>`
   first — the crashed attempt is settled as aborted (kept in history) and a fresh attempt opens automatically
 - **Pair or let it run** — work alongside your AI agent interactively, or let it execute unattended
 - **Zero-memorization start** — run `ralphctl` with no args for a guided menu
+- **Bring your own model** — four backends to choose from, one of which (OpenCode) is vendor-neutral, so the
+  harness reaches hosted, aggregated, and local models alike
 
 ---
 
@@ -226,7 +293,7 @@ Configure via the TUI `Settings` view or one-shot CLI commands.
 `apply-preset`.
 
 <details>
-<summary>All 20 presets across five families</summary>
+<summary>All 21 presets</summary>
 
 ```bash
 # Standard — flagship model per flow
@@ -234,6 +301,7 @@ ralphctl settings apply-preset mixed               # best-fit provider per flow
 ralphctl settings apply-preset claude-only         # every flow on Claude Code
 ralphctl settings apply-preset copilot-only        # every flow on GitHub Copilot CLI
 ralphctl settings apply-preset codex-only          # every flow on OpenAI Codex CLI
+ralphctl settings apply-preset opencode-only       # every flow on OpenCode's free tier (no auth)
 
 # Economic — implement starts one tier below flagship; escalation ladder climbs only on plateau
 ralphctl settings apply-preset mixed-economic
@@ -260,7 +328,9 @@ ralphctl settings apply-preset copilot-frontier
 ralphctl settings apply-preset codex-frontier
 ```
 
-Twenty presets across five families ship, all equally first-class — none is marked default. Applying a
+Twenty-one presets ship, all equally first-class — none is marked default. `opencode-only` sits outside the
+five-family grid on purpose: every free-tier model is at the same (zero) price point, so `economic` / `frontier`
+variants of it would differ in name only. Applying a
 preset stamps the entire `ai` section plus `harness.escalateOnPlateau` in one transaction (`fast` stamps it
 `false` so a plateau settles; all others stamp it `true`). On a fresh install the welcome view silently
 auto-seeds a preset based on which provider CLIs it detects on `PATH`.
@@ -318,6 +388,7 @@ export RALPHCTL_HOME="/path/to/custom/dir"
 | ---------------------------- | -------------- | ---------------------------------------------------- |
 | `RALPHCTL_HOME`              | `~/.ralphctl/` | Override application root (data + config + state)    |
 | `RALPHCTL_SKIP_LEGACY_CHECK` | unset          | Bypass the v0.6.x legacy-layout detector at boot     |
+| `RALPHCTL_DEBUG_TRACE`       | unset          | Write a `<sprintDir>/events.ndjson` debug trace      |
 | `RALPHCTL_NO_TUI`            | unset          | Suppress implicit interactive prompts in `implement` |
 | `NO_COLOR`                   | unset          | Suppress ANSI colors                                 |
 | `CI`                         | auto-detected  | Suppress implicit interactive prompts in `implement` |
@@ -360,14 +431,17 @@ readiness / create sprint) stay TUI-only by design. The CLI exposes inspection +
 
 ### Getting Started
 
-| Command                                 | Description                                                                                                                                                                                                                    |
-| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `ralphctl`                              | Interactive TUI (primary surface)                                                                                                                                                                                              |
-| `ralphctl doctor`                       | Check environment health                                                                                                                                                                                                       |
-| `ralphctl settings show`                | Print current settings                                                                                                                                                                                                         |
-| `ralphctl settings set <key> <value>`   | Set a single settings key                                                                                                                                                                                                      |
-| `ralphctl settings apply-preset <name>` | Stamp the entire `ai` section — 20 presets across five families: `standard` / `economic` / `strong-gate` / `fast` / `frontier`, each in `mixed` / `*-only` / `*-economic` / `*-strong-gate` / `*-fast` / `*-frontier` variants |
-| `ralphctl completion <shell>`           | Print shell tab-completion script                                                                                                                                                                                              |
+| Command                                 | Description                                                                                                                                                                   |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ralphctl`                              | Interactive TUI (primary surface)                                                                                                                                             |
+| `ralphctl demo`                         | Seed a throwaway sandbox project and launch straight into it — zero setup, no provider CLI required to look around (`--no-launch` to seed only, `--home <dir>` to relocate)   |
+| `ralphctl doctor`                       | Check environment health                                                                                                                                                      |
+| `ralphctl settings show`                | Print current settings                                                                                                                                                        |
+| `ralphctl settings set <key> <value>`   | Set a single settings key                                                                                                                                                     |
+| `ralphctl settings apply-preset <name>` | Stamp the entire `ai` section — 21 presets: `standard` / `economic` / `strong-gate` / `fast` / `frontier` families, each in `mixed` / `*-only` variants, plus `opencode-only` |
+| `ralphctl completion <shell>`           | Print shell tab-completion script                                                                                                                                             |
+| `ralphctl agents list`                  | List bundled + operator agent definitions and the implement role each is bound to                                                                                             |
+| `ralphctl skills list`                  | List bundled + manually-dropped skills — tier, enabled flows, provenance                                                                                                      |
 
 ### Project & Sprint Inspection
 
@@ -384,6 +458,7 @@ readiness / create sprint) stay TUI-only by design. The CLI exposes inspection +
 | `ralphctl ticket list / show <id>`    | Inspect tickets                                                                     |
 | `ralphctl ticket remove <id>`         | Remove a ticket from a draft sprint                                                 |
 | `ralphctl task list / show <id>`      | Inspect tasks (planning generates them)                                             |
+| `ralphctl task evaluation <id>`       | Print the latest evaluator verdict (`evaluation.md`) for the task's last attempt    |
 | `ralphctl task unblock <id>`          | Reset a blocked task to `todo`                                                      |
 
 ### Sprint Lifecycle
@@ -404,10 +479,11 @@ readiness / create sprint) stay TUI-only by design. The CLI exposes inspection +
 
 ### Maintenance
 
-| Command                                                                                    | Description                                     |
-| ------------------------------------------------------------------------------------------ | ----------------------------------------------- |
-| `ralphctl runs list [--flow <name>]`                                                       | List per-run forensic artifacts grouped by flow |
-| `ralphctl runs prune [--older-than 7d] [--keep-last <n>] [--flow <name>] [--dry-run] [-y]` | Delete per-run forensic artifacts               |
+| Command                                                                                    | Description                                                                          |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `ralphctl runs list [--flow <name>]`                                                       | List per-run forensic artifacts grouped by flow                                      |
+| `ralphctl runs stats [--sprint <id>] [--project <id>] [--since <date>] [--json]`           | Harness outcome rollup — outcome mix, first-pass rate, plateaus, escalation efficacy |
+| `ralphctl runs prune [--older-than 7d] [--keep-last <n>] [--flow <name>] [--dry-run] [-y]` | Delete per-run forensic artifacts                                                    |
 
 Run `ralphctl <command> --help` for flag-level detail.
 
@@ -420,6 +496,7 @@ Run `ralphctl <command> --help` for flag-level detail.
 | Resource                                         | Description                                              |
 | ------------------------------------------------ | -------------------------------------------------------- |
 | [Architecture](./ARCHITECTURE.md)                | Data models, harness loop, file storage, error reference |
+| [Providers](./docs/providers.md)                 | Per-backend setup, permission mapping, model ids, limits |
 | [Adding a provider](./docs/adding-a-provider.md) | Extension guide: wire a new AI CLI into the harness      |
 | [Requirements](./.claude/docs/REQUIREMENTS.md)   | Acceptance criteria and feature checklist                |
 | [Contributing](./CONTRIBUTING.md)                | Dev setup, code style, PR process                        |