ralphctl 0.8.6 → 0.9.0

package/README.md

@@ -11,7 +11,7 @@
 [![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">
-  <img src="./.github/assets/home.png" alt="ralphctl v0.7.0 home screen — Ralph donut banner with 'The pointy kitty took it!' tagline, demo project tile, WORK / OBSERVE / SYSTEM menus with keybindings, bottom footer" width="900" />
+  <img src="./.github/assets/home.png" alt="ralphctl home screen — Ralph donut banner with 'The pointy kitty took it!' tagline, demo project tile, WORK / OBSERVE / SYSTEM menus with keybindings, bottom footer" width="900" />
 </p>
 
 **Agent harness for long-running AI coding tasks —
@@ -22,17 +22,19 @@ with [GitHub Copilot](https://docs.github.com/en/copilot/github-copilot-in-the-c
 > _"I'm helping!"_ — Ralph Wiggum
 
 > [!NOTE]
-> **Active development.** New features and polish ship regularly. The 0.7.x
-> line landed a burst of structural changes — thanks for sticking with us
-> through it. Upgrades are simple: install the latest version, redo your
-> config, proceed. See [Upgrading](#upgrading) and [CHANGELOG](./CHANGELOG.md).
+> **Active development.** New features and polish ship regularly. **0.9.0** adds
+> opt-in parallel task execution — independent tasks within a dependency wave run
+> concurrently, each in its own git worktree, folded back onto one branch.
+> Upgrades are simple: install the latest version, redo your config, proceed.
+> See [Upgrading](#upgrading) and [CHANGELOG](./CHANGELOG.md).
 
 ---
 
 ## What is ralphctl?
 
 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 — currently Claude Code — in a
+coordinate changes across multiple repositories. ralphctl wraps your chosen AI CLI — Claude Code, with GitHub Copilot
+and OpenAI Codex in preview — 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.
@@ -55,8 +57,9 @@ ralphctl
 ```
 
 That's it. The TUI launches, walks you through registering a project, refining your first ticket, generating a task
-plan, and kicking off implementation. Press `n` from the home screen to start a new sprint, or follow the
-`press r to open Sprints` hint on your project tile. No commands to memorize.
+plan, and kicking off implementation. Press `+` from the home screen to create a new sprint, press `n` to start a
+flow (refine / plan / implement / readiness / …), or open the Sprints submenu and follow its on-screen hint to pick
+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.
@@ -93,15 +96,11 @@ 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
-ralphctl settings set ai.implement.provider claude-code
-ralphctl settings set ai.implement.model      <model-id>
-ralphctl settings set ai.implement.effort     high
-
-# Rebuild a sprint's progress.md from disk
-ralphctl sprint regenerate-progress <sprint-id>
-
-# Single-frame text digest of the active sprint
-ralphctl snapshot [--sprint <id>]
+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
+ralphctl settings set ai.implement.evaluator.provider openai-codex
+ralphctl settings set ai.implement.evaluator.model    <model-id>
 ```
 
 </details>
@@ -125,18 +124,20 @@ ralphctl snapshot [--sprint <id>]
 
 **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 one at a time through a generator-evaluator cycle: a
-second AI pass reviews each task against its spec before the harness marks it done and moves to the next.
+dependency-ordered task graph. **Implement** drives those tasks in dependency order through a generator-evaluator cycle:
+a second AI pass reviews each task against its spec before the harness marks it done and moves on. Independent tasks in
+the same dependency wave can run in parallel (opt-in) when you want a sprint to finish faster.
 
 Key properties:
 
-- **Dependency-ordered execution** — tasks run strictly one at a time in topological order; no task starts until its
-  blockers are done
+- **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`)
 - **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 check scripts
+- **Multi-repo support** — one sprint can span several repositories with per-repo setup and verify scripts
 
 For the full architectural picture see [`.claude/docs/ARCHITECTURE.md`](./.claude/docs/ARCHITECTURE.md) and [
 `.claude/docs/REQUIREMENTS.md`](./.claude/docs/REQUIREMENTS.md).
@@ -148,17 +149,19 @@ For the full architectural picture see [`.claude/docs/ARCHITECTURE.md`](./.claud
 > [!IMPORTANT]
 > Not all three AI providers are equally production-ready inside ralphctl.
 
-| Provider                                  | Status                                  | Headless flag                                               | Native context file               |
-| ----------------------------------------- | --------------------------------------- | ----------------------------------------------------------- | --------------------------------- |
-| **Claude Code** (`claude-code`)           | **Stable — primary verified provider**  | `--permission-mode bypassPermissions` + per-tool deny list  | `CLAUDE.md` at repo root          |
-| **GitHub Copilot CLI** (`github-copilot`) | Preview — not officially verified by us | `--autopilot --allow-all` + `--max-autopilot-continues=200` | `.github/copilot-instructions.md` |
-| **OpenAI Codex** (`openai-codex`)         | Preview — not officially verified by us | `-s workspace-write` (topology-scoped)                      | `AGENTS.md`                       |
+| Provider                                  | Status                                                                          | Headless flag                                               | Native context file               |
+| ----------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------- |
+| **Claude Code** (`claude-code`)           | **Stable — primary verified provider**                                          | `--permission-mode bypassPermissions` + per-tool deny list  | `CLAUDE.md` at repo root          |
+| **GitHub Copilot CLI** (`github-copilot`) | Preview — maturing; works well day-to-day, not yet formally verified end-to-end | `--autopilot --allow-all` + `--max-autopilot-continues=200` | `.github/copilot-instructions.md` |
+| **OpenAI Codex** (`openai-codex`)         | Preview — maturing; works well day-to-day, not yet formally verified end-to-end | `-s workspace-write` (topology-scoped)                      | `AGENTS.md`                       |
 
-"Preview" means the integration exists and the TUI lets you select it, but end-to-end harness behaviour against those
-providers has not been formally verified. Copilot and Codex no-op some features (bundled skill injection, `bodyFile`
-forensic artifacts). Codex cannot fine-grained-deny edits on existing repo files — its sandbox modes are binary, so
-path scope (cwd + `--add-dir`) is the only safety envelope. If you hit a rough edge on a preview provider,
-please [open an issue](https://github.com/lukas-grigis/ralphctl/issues).
+"Preview" means the integration is in active use and increasingly solid — recent releases run Copilot and Codex well
+across the everyday flows — but harness behaviour against them hasn't been put through the same formal end-to-end
+verification as Claude Code. A couple of features still no-op on them (bundled skill injection, `bodyFile` forensic
+artifacts), and Codex can't fine-grained-deny edits on existing repo files — its sandbox modes are binary, so path
+scope (cwd + `--add-dir`) is the only safety envelope. Parallel execution is provider-agnostic: it works with whichever
+provider each implement role is configured to use, under the same per-provider caveats. If you hit a rough edge on a
+preview 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
 `mixed`, `claude-only`, `copilot-only`, or `codex-only`.
@@ -171,6 +174,8 @@ One-shot configuration for any provider: `ralphctl settings apply-preset <name>`
 - **Catch mistakes before they compound** — independent AI review after each task, iterating until quality passes or
   budget is exhausted
 - **Coordinate across repositories** — one sprint can span multiple repos with automatic dependency tracking
+- **Finish sprints faster (opt-in)** — run independent tasks within a dependency wave in parallel, each in its own git
+  worktree, folded back onto one sprint branch (still one PR); default stays serial, zero change
 - **Branch per sprint** — optional shared branch across every affected repo; `ralphctl create-pr --sprint <id>` opens a
   PR / MR via `gh` or `glab` when you're done
 - **Recover from rate limits** — exponential backoff and session resume keep the in-flight task's full context when the
@@ -200,13 +205,15 @@ ralphctl settings apply-preset codex-only     # every flow on OpenAI Codex
 A preset stamps the entire `ai` section in one shot. None is marked default; on a fresh install the welcome
 view silently auto-seeds a preset based on which provider CLIs it detects on `PATH`.
 
-**Per-flow settings.** Each chain (`refine`, `plan`, `implement`, `ideate`, `readiness`) carries its own
-`{provider, model, effort?}` row. Edit individual keys with:
+**Per-flow settings.** Each flow carries its own `{provider, model, effort?}` row: `refine`, `plan`, `readiness`,
+`ideate`, and `createPr`. The `implement` flow instead splits into a nested `generator` / `evaluator` pair
+(`ai.implement.generator.*` and `ai.implement.evaluator.*`), each its own `{provider, model, effort?}` row. Edit
+individual keys with:
 
 ```bash
-ralphctl settings set ai.implement.provider claude-code
-ralphctl settings set ai.implement.model    <model-id>
-ralphctl settings set ai.implement.effort   high
+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
 
 ralphctl settings set ai.plan.provider      github-copilot
 ralphctl settings set ai.plan.model         <model-id>
@@ -218,11 +225,22 @@ row's CLI at launch and exits with a clear error if the binary is missing.
 **Tune the generator-evaluator loop** (under `harness`):
 
 ```bash
-ralphctl settings set harness.maxAttempts 2          # Cap fix attempts per task (1–10, default 1)
+ralphctl settings set harness.maxAttempts 2          # Cap fix attempts per task (1–10, default 3)
 ralphctl settings set harness.maxTurns    8          # Generator-evaluator turns per attempt (1–10)
 ralphctl settings set harness.rateLimitRetries 3     # Adapter-side 429 retries (0–10)
 ```
 
+**Run tasks in parallel** (optional — default is serial):
+
+```bash
+ralphctl settings set concurrency.maxParallelTasks 3   # 1–5; 1 = serial (default), >1 = parallel git worktrees
+```
+
+When `> 1`, independent tasks within a dependency wave run concurrently — each in its own git worktree, with its own
+`setupScript` run, folded back onto the single sprint branch (still one PR per sprint). A task whose worktree setup
+fails is blocked on its own without stopping its siblings; if two same-wave tasks edit the same file, the second is
+blocked at fold time and a relaunch retries it. Dependencies are always respected — only independent tasks overlap.
+
 ### Data directory
 
 All state lives in `~/.ralphctl/` by default (settings under `config/`, sprints + projects under `data/`, advisory locks
@@ -234,16 +252,16 @@ export RALPHCTL_HOME="/path/to/custom/dir"
 
 ### Environment variables
 
-| Variable                     | Default        | Purpose                                                               |
-| ---------------------------- | -------------- | --------------------------------------------------------------------- |
-| `RALPHCTL_HOME`              | `~/.ralphctl/` | Override application root (data + config + state)                     |
-| `RALPHCTL_LOCK_TIMEOUT_MS`   | `30000`        | Stale lock threshold for concurrent-access detection (1–3600000 ms)   |
-| `RALPHCTL_SKIP_LEGACY_CHECK` | unset          | Bypass the v0.6.x legacy-layout detector at boot                      |
-| `RALPHCTL_LOG_LEVEL`         | `info`         | Filter structured-log output (`silent`/`debug`/`info`/`warn`/`error`) |
-| `RALPHCTL_NO_TUI`            | unset          | Force the plain-text CLI fallback even on a TTY                       |
-| `RALPHCTL_JSON`              | unset          | Force JSON log output (one object per line) regardless of TTY         |
-| `NO_COLOR`                   | unset          | Suppress ANSI colors                                                  |
-| `CI`                         | auto-detected  | Disables Ink mount and implicit interactive prompts                   |
+| Variable                     | Default        | Purpose                                              |
+| ---------------------------- | -------------- | ---------------------------------------------------- |
+| `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_NO_TUI`            | unset          | Suppress implicit interactive prompts in `implement` |
+| `NO_COLOR`                   | unset          | Suppress ANSI colors                                 |
+| `CI`                         | auto-detected  | Suppress implicit interactive prompts in `implement` |
+
+Log verbosity is `settings.logging.level` (`silent` / `debug` / `info` / `warn` / `error`, default `info`), set via
+`ralphctl settings set logging.level <level>` or the TUI `Settings` view — not an environment variable.
 
 ---
 
@@ -288,7 +306,6 @@ readiness / create sprint) stay TUI-only by design. The CLI exposes inspection +
 | `ralphctl settings set <key> <value>`   | Set a single settings key                                                               |
 | `ralphctl settings apply-preset <name>` | Stamp the entire `ai` section (`mixed` / `claude-only` / `copilot-only` / `codex-only`) |
 | `ralphctl completion <shell>`           | Print shell tab-completion script                                                       |
-| `ralphctl snapshot [--sprint <id>]`     | Single-frame text digest of sprint state                                                |
 
 ### Project & Sprint Inspection
 
@@ -305,15 +322,15 @@ 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 unblock <id>`       | Reset a blocked task to `todo`            |
 
 ### Sprint Lifecycle
 
-| Command                                    | Description                           |
-| ------------------------------------------ | ------------------------------------- |
-| `ralphctl sprint activate <id>`            | Flip a draft sprint to `active`       |
-| `ralphctl sprint close <id>`               | Transition `review` → `done`          |
-| `ralphctl sprint remove <id>`              | Delete a sprint permanently           |
-| `ralphctl sprint regenerate-progress <id>` | Rebuild `progress.md` from disk state |
+| Command                         | Description                     |
+| ------------------------------- | ------------------------------- |
+| `ralphctl sprint activate <id>` | Flip a draft sprint to `active` |
+| `ralphctl sprint close <id>`    | Transition `review` → `done`    |
+| `ralphctl sprint remove <id>`   | Delete a sprint permanently     |
 
 ### Export & PR
 
@@ -323,6 +340,13 @@ readiness / create sprint) stay TUI-only by design. The CLI exposes inspection +
 | `ralphctl export-context --sprint <id> --project <id> --output <path>` | Render harness context (sprint + project + tasks) to markdown  |
 | `ralphctl create-pr --sprint <id> [--base <branch>] [--draft]`         | Open a PR/MR via `gh` or `glab`, persist the URL on the sprint |
 
+### 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               |
+
 Run `ralphctl <command> --help` for flag-level detail.
 
 </details>