@john-ezra/openralph 0.1.1

package/.dockerignore

@@ -0,0 +1,25 @@
+node_modules/
+dist/
+coverage/
+runs/
+plan/
+specs/
+.opencode/
+TODO.md
+HANDOFF*.md
+RELEASE-PREP.md
+IMPLEMENTATION_PLAN.md
+*.log
+*.tgz
+*.tsbuildinfo
+.eslintcache
+.git/
+.DS_Store
+.envrc
+tui.json
+.env
+.env.*
+!.env.example
+!.env.sample
+!.env.template
+!.env.dist

package/AGENTS.md

@@ -0,0 +1,148 @@
+# OpenRalph
+
+OpenRalph is a light opencode plugin that implements the Ralph workflow from Clayton Farr's Ralph Playbook.
+
+## Core Principles
+
+- Keep the implementation simple.
+- Preserve Ralph's central mechanism: one fresh top-level opencode run per loop iteration.
+- Use disk files as persistent state: `specs/*`, `AGENTS.md`, `IMPLEMENTATION_PLAN.md`, `PROMPT_plan.md`, and `PROMPT_build.md`; use `runs/*` only for durable local run artifacts and audit/debug output.
+- Do not turn OpenRalph into a general sandbox or orchestration platform.
+- Safety strategy is the user's responsibility. OpenRalph provides only lightweight guardrails and optional Dockerized loop execution.
+- Avoid complex modes, safety matrices, Podman requirements, or heavy process abstractions.
+
+## Ralph Phases
+
+- Phase 1: Define Requirements -> `/ralph` Design
+- Phase 2: Planning -> `/ralph` Plan
+- Phase 3: Building -> `/ralph` Build
+
+Use these phase names consistently.
+
+## Public Commands
+
+- `/ralph`: the only public TUI slash command. It opens Design, Plan, and Build modes.
+- `openralph plan` and `openralph build`: CLI/headless launcher entrypoints with the same public loop args.
+
+## Internal Commands
+
+- `/ralph-plan-iteration`: one fresh planning iteration.
+- `/ralph-build-iteration`: one fresh build iteration/task.
+
+The server plugin should inject these commands only for authorized loop child processes. Normal host TUI sessions must not expose internal iteration prompts.
+
+## Loop Rules
+
+- Plan/build loops launch child `opencode run` processes.
+- Each child process handles one iteration with fresh top-level context.
+- Never use `--continue` for child runs.
+- Always pass `--dir <project-root>` to child runs.
+- Plan/build child runs use `--dangerously-skip-permissions`.
+- When Docker mode is enabled, host plan/build commands launch one Docker container and the full loop runs inside it.
+- Docker mode runs the container `openralph plan` or `openralph build` CLI entrypoint, never public prompt command replay.
+- Container loops set `OPENRALPH_IN_DOCKER=1` and require token-backed Docker attestation before running.
+- Docker mode disables project OpenCode config and injects config that loads only image-bundled OpenRalph.
+- Docker mode injects a `chrome-devtools` MCP server into the container OpenCode config for browser validation.
+- Docker mode runs containers with `--pull=never`, `--shm-size=1g`, and `--security-opt no-new-privileges:true`.
+- The default image uses a non-root `opencode` user when Docker cannot run as the host UID/GID.
+- Default max iterations is unlimited.
+- Retry child process failures.
+- Stop after 3 consecutive child process failures.
+- Stop when Ralph reports completion.
+- Ctrl+C is the manual stop mechanism.
+- On first Ctrl+C, request shutdown, forward SIGINT to the active child process, and stop launching new iterations.
+- On second Ctrl+C, force terminate the active child process and exit.
+- User interrupt is not a child process failure and must not be retried.
+- Push only when `--push` is passed and Docker mode is not used.
+- Plan/build loops write project-local run artifacts under `runs/openralph-<phase>-YYYYMMDD-HHMMSS/`; artifacts must not replace `IMPLEMENTATION_PLAN.md` as the work queue.
+- `runLoop()` must not independently launch Docker or inspect `docker.enabled`; the shared launcher resolves `docker-host-launch`, `host-explicit`, `host-config-default`, or `container-attested` once.
+
+## Model Selection
+
+Model selection is intentionally simple.
+
+Precedence:
+
+```text
+command --model -> OpenRalph config -> opencode default
+```
+
+Plugin options:
+
+```json
+{
+  "defineModel": "heavy-model",
+  "planModel": "cheap-model",
+  "buildModel": "cheap-model",
+  "docker": {
+    "enabled": true,
+    "image": "openralph:local",
+    "maskEnv": true
+  }
+}
+```
+
+If no model is configured or passed, omit `--model` and let opencode use its default.
+
+## Git Guardrails
+
+- Require a Git worktree before running OpenRalph Plan or Build.
+- Warn, but do not block, on `main` or `master`.
+- Create lightweight namespaced Git tags after each successful clean build iteration.
+- Tags are local by default.
+- Do not push commits unless `--push` is passed.
+- Do not push tags in v1 unless explicitly implemented later.
+
+Recommended tag shape:
+
+```text
+openralph/build-YYYYMMDD-HHMMSS/001
+openralph/build-YYYYMMDD-HHMMSS/002
+```
+
+Use tags only after a successful build iteration with a new commit and clean worktree.
+
+## Development Git Workflow
+
+- Do not make feature, fix, or improvement changes directly on `main`.
+- Create a short-lived branch before editing, such as `feature/<name>` or `fix/<name>`.
+- Keep `main` as the integration branch; merge reviewed/validated branch work back into `main`.
+- Push branches for collaboration or backup, then merge to `main` only after validation passes.
+- If accidental local edits happen on `main`, move them to a branch before committing unless the user explicitly approves a direct `main` commit.
+
+## Safety Posture
+
+OpenRalph v1 supports optional Dockerized execution for Plan and Build.
+
+Rationale:
+
+- Ralph requires autonomy, so plan/build child runs use `--dangerously-skip-permissions`.
+- Docker mode reduces host filesystem blast radius but is not a formal sandbox guarantee.
+- TUI Design mode remains host-side so host memory/MCP integrations can participate in ideation.
+- TUI Design mode is host-side and injects a Ralph Design prompt into the current session after an optional initial idea prompt.
+- Docker mode mounts the repo read/write at `/workspace`, mounts OpenCode auth read-only, masks real `.env*` files by default, and does not mount host home, SSH, config, desktop sockets, or the Docker socket.
+- Docker mode does not mount host Git config, SSH keys, GPG material, browser profiles, browser cookies, or desktop sockets.
+- Dockerized OpenRalph Build requires host/project Git `user.name` and `user.email`; OpenRalph passes them through author/committer environment variables, disables commit/tag signing inside Docker, and marks `/workspace` as a safe Git directory.
+- The default `openralph:local` image includes Bun, Node 22, npm/npx/corepack, Git, Bash, curl, Python 3, native build tools, ripgrep, Google Chrome stable, screenshot-friendly fonts, `opencode-ai@1.15.13`, and `chrome-devtools-mcp@1.1.1`.
+- Chrome DevTools MCP runs through `/opt/openralph/bin/chrome-devtools-mcp-wrapper`, which starts isolated headless Chrome on a loopback debugging port with a temporary profile and connects MCP via `--browser-url`.
+- The user still chooses their own isolation strategy and risk level.
+- Recommended operator practice is to run on a dedicated branch or disposable clone.
+
+## Implementation Preference
+
+- Use TypeScript targeting Bun/opencode's plugin runtime.
+- Keep the plugin small and deterministic.
+- Prefer plain Markdown prompt/state files over JSON orchestration.
+- Do not hardcode specific model IDs.
+- Do not add additional public flags unless they are clearly necessary.
+- Keep project setup guidance lean: validation commands, project conventions, and prioritized plan items matter more than prompt complexity.
+- Do not add every language runtime to the default Docker image; projects needing Go, Rust, Java, databases, or other specialized tooling should extend `openralph:local`.
+- Keep browser tooling Docker-only in v1; do not make Chrome DevTools MCP a host-side dependency.
+- Public Design/Plan/Build commands are not prompt-backed `cfg.command` entries. The TUI plugin registers only `/ralph`; the server plugin deletes stale public command entries and throws if a stale prompt-backed public command is executed.
+
+## References
+
+- Ralph Playbook: https://github.com/ClaytonFarr/ralph-playbook
+- Formatted guide: https://claytonfarr.github.io/ralph-playbook/
+- opencode plugin docs: https://opencode.ai/docs/plugins/
+- opencode command docs: https://opencode.ai/docs/commands/

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to OpenRalph will be documented in this file.
+
+The format is based on Keep a Changelog, and this project uses semantic versioning.
+
+## [0.1.0] - 2026-06-04
+
+### Added
+
+- Initial public release of the OpenRalph opencode plugin and CLI.
+- TUI `/ralph` command with Design, Plan, and Build modes.
+- `openralph plan` and `openralph build` CLI/headless loop entrypoints.
+- Optional attested Docker mode for Plan and Build loops.
+- Docker `.env*` masking with example/template env files preserved.
+- Local lightweight build tags for successful clean build commits.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Ezra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROMPT_build.md

@@ -0,0 +1,48 @@
+# Ralph Build Iteration
+
+0a. Study `specs/*` with up to 500 parallel research subagents to understand the required behavior.
+0b. Study `IMPLEMENTATION_PLAN.md`.
+0c. Study current source code and shared project patterns before making changes.
+0d. Study `AGENTS.md` for build, test, lint, typecheck, and operational guidance.
+
+1. Choose the most important actionable item from `IMPLEMENTATION_PLAN.md`.
+
+2. Before editing, search the codebase with up to 500 parallel research subagents for searches, reads, and context gathering. Do not assume functionality is missing; confirm the current state first. Use higher-reasoning subagents only for complex debugging or architectural decisions.
+
+3. Implement exactly one coherent task from the plan. Keep the change complete, minimal, and consistent with existing project patterns.
+
+3a. If the chosen task is too large or unclear to complete cleanly in one iteration, split or clarify it in `IMPLEMENTATION_PLAN.md`, document what should happen next, and stop rather than doing a partial implementation.
+
+4. Run the relevant validation from `AGENTS.md`, including targeted tests for the changed unit when available. Use only 1 validation subagent at a time for build/tests so validation creates clear backpressure. Fix failures caused by the change before proceeding.
+
+4a. For frontend or web UI tasks, validate in a browser when practical. Start the app, inspect desktop and mobile layouts, check console errors, and use screenshots or visual inspection for layout/design issues before committing.
+
+5. If unrelated failures or bugs are discovered, either resolve them if they are part of the current increment or document them in `IMPLEMENTATION_PLAN.md`.
+
+5a. If the iteration exposes a validation gap, unsafe operation pattern, repeated failure mode, or missing backpressure, document a concrete follow-up in `IMPLEMENTATION_PLAN.md` or a brief reusable operational note in `AGENTS.md`.
+
+6. Keep `IMPLEMENTATION_PLAN.md` up to date. Remove or mark completed work, add discovered follow-up work, and document blockers.
+
+7. Update `AGENTS.md` only for brief operational learnings, such as correct commands or important run/build notes. Do not use it as a progress log.
+
+8. Before committing, update `IMPLEMENTATION_PLAN.md` so the next fresh iteration can choose the next most important task without relying on prior context. When validation passes and the task is complete, commit the changes with a concise message. After `git commit` succeeds, confirm `git status --short` is clean. Only then mark commit-related todos complete. Do not push. Do not create tags.
+
+9. If you completed and committed one task in this iteration, print exactly this standalone final line, even if that task was the last actionable item:
+
+RALPH_ITERATION_COMPLETE
+
+10. If this iteration starts with no actionable tasks remaining, ensure `IMPLEMENTATION_PLAN.md` reflects that state, confirm `git status --short` is clean, and print exactly this standalone final line:
+
+RALPH_COMPLETE
+
+11. If work cannot continue because of a real blocker, document the blocker in `IMPLEMENTATION_PLAN.md` and print exactly:
+
+RALPH_BLOCKED
+
+99999. Important: capture the why when authoring documentation, tests, and implementation notes.
+999999. Important: single sources of truth; avoid placeholder implementations and ad-hoc copies.
+9999999. Important: keep `AGENTS.md` operational only. Status and progress belong in `IMPLEMENTATION_PLAN.md`. Do not use Ralph sentinel strings in todos or prose; reserve exactly one standalone sentinel for the final output line.
+
+## IMPLEMENTATION_PLAN.md Hygiene
+
+Treat `IMPLEMENTATION_PLAN.md` as the canonical prioritized checklist. Keep remaining actionable work sorted from highest to lowest value. Completed items should be removed or clearly marked complete. Blocked items must include the blocker and what would unblock them before printing `RALPH_BLOCKED`. Add discovered bugs, audit findings, validation gaps, and follow-up work in the correct priority position. Remove stale, duplicated, or contradicted tasks. If the plan becomes noisy or large, clean completed/stale entries while preserving remaining work and blockers. Do not record progress in `AGENTS.md`.

package/PROMPT_plan.md

@@ -0,0 +1,29 @@
+# Ralph Planning Iteration
+
+0a. Study `specs/*` with up to 250 parallel research subagents to learn the application requirements.
+0b. Study `IMPLEMENTATION_PLAN.md` if present; it may be incomplete or wrong.
+0c. Study the current source code and project structure with up to 250 parallel research subagents before making plan changes.
+0d. Study shared utilities, components, and existing patterns before recommending new ones.
+
+1. Compare `specs/*` against the current implementation using up to 500 parallel research subagents for code search, reads, and gap analysis. Do not assume functionality is missing; confirm with code search first. Use one higher-reasoning subagent where useful to synthesize findings and prioritize the plan.
+
+2. Create or update `IMPLEMENTATION_PLAN.md` as a prioritized list of remaining actionable work. Keep it up to date with items that are complete, incomplete, blocked, or discovered during research.
+
+3. Consider TODOs, placeholder implementations, skipped or flaky tests, minimal stubs, inconsistent patterns, missing validation, missing backpressure, and audit findings from recent `runs/openralph-*` artifacts when available.
+
+4. Plan only. Do not implement code. Do not commit. Do not push. Do not create tags.
+
+5. If specs are missing or inconsistent, document the issue clearly. Only create or refine specs when necessary to unblock accurate planning, and keep specs behavioral rather than implementation-prescriptive.
+
+99999. Important: capture the why when documenting tasks, tests, and implementation importance.
+999999. Important: keep `AGENTS.md` operational only. Status, progress, and planning belong in `IMPLEMENTATION_PLAN.md`.
+
+## IMPLEMENTATION_PLAN.md Hygiene
+
+Treat `IMPLEMENTATION_PLAN.md` as the canonical prioritized checklist. Keep remaining actionable work sorted from highest to lowest value. Prefer tasks small enough for one build iteration when practical. If a task would require broad refactoring, unclear sequencing, or repeated retries, split it into smaller independently validatable tasks. Remove or clearly mark completed work. Remove stale, duplicated, or contradicted tasks. Blocked items must include the blocker and what would unblock them. Add discovered bugs, audit findings, validation gaps, and follow-up work in the correct priority position. Do not record progress in `AGENTS.md`.
+
+When the specs, current code, and `IMPLEMENTATION_PLAN.md` have converged into a stable prioritized task list, print exactly:
+
+RALPH_PLAN_COMPLETE
+
+If more planning work remains, update `IMPLEMENTATION_PLAN.md` and exit without printing a completion sentinel so the outer loop can continue.

package/README.md

@@ -0,0 +1,247 @@
+# OpenRalph
+
+OpenRalph is a light opencode plugin/package that implements the Ralph workflow through TUI and CLI entrypoints:
+
+- `/ralph`: the only public TUI slash command. It opens a Design, Plan, Build mode selector.
+- `openralph plan [max] [--model <model>] [--no-docker]`: CLI/headless launcher for fresh planning iterations until `IMPLEMENTATION_PLAN.md` is stable.
+- `openralph build [max] [--model <model>] [--push] [--no-docker]`: CLI/headless launcher for fresh build iterations, one task and one commit at a time.
+
+## Installation
+
+OpenRalph is distributed as the npm package `@john-ezra/openralph`. OpenRalph itself stays Bun/TypeScript-native. Direct package execution through `bunx @john-ezra/openralph ...` or an installed `openralph` binary requires Bun.
+
+The normal install path is opencode's built-in plugin installer:
+
+1. Open opencode in the target project.
+2. Run `Install plugin` from the command palette/plugins UI.
+3. Enter `@john-ezra/openralph` at the `npm package name` prompt.
+4. Leave scope as `local` for a project install, or press `Tab` to toggle to `global`.
+5. Restart opencode if needed.
+6. Run `/ralph`.
+
+CLI equivalent for non-TUI users:
+
+```bash
+opencode plugin @john-ezra/openralph
+opencode plugin --global @john-ezra/openralph
+```
+
+The opencode installer installs the npm package into opencode's plugin cache, detects both OpenRalph server and TUI targets, and patches the matching config files automatically. Local scope writes under `<worktree>/.opencode/` when run in a Git worktree; global scope writes under `~/.config/opencode/`.
+
+## Advanced Manual Config
+
+Manual config is only needed when you want to bypass opencode's plugin installer or edit plugin options directly. Use `@john-ezra/openralph` for both server and TUI config; do not configure `@john-ezra/openralph/tui` as the plugin name.
+
+Server plugin in `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "@john-ezra/openralph",
+      {
+        "defineModel": "provider/heavy-model",
+        "planModel": "provider/cheap-model",
+        "buildModel": "provider/cheap-model",
+        "docker": {
+          "enabled": true,
+          "image": "openralph:local",
+          "maskEnv": true
+        }
+      }
+    ]
+  ]
+}
+```
+
+TUI plugin in `tui.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": [
+    [
+      "@john-ezra/openralph",
+      {
+        "defineModel": "provider/heavy-model",
+        "planModel": "provider/cheap-model",
+        "buildModel": "provider/cheap-model",
+        "docker": {
+          "enabled": true,
+          "image": "openralph:local",
+          "maskEnv": true
+        }
+      }
+    ]
+  ]
+}
+```
+
+All model options are optional. Command `--model` values override plugin options. If no model is resolved, OpenRalph omits `--model` and lets opencode use its default.
+
+Server and TUI plugin options use the same shape. Direct CLI/headless runs can pass the same launcher options through `OPENRALPH_OPTIONS_JSON`; without that env var, `openralph plan/build` uses default options, including Docker disabled.
+
+## Docker Mode
+
+Docker mode is optional. When `docker.enabled` is true, Plan and Build from `/ralph`, `openralph plan`, and `openralph build` launch one Docker container from the host and run the full Ralph loop inside it through the container `openralph` CLI entrypoint. Docker uses `--pull=never`, so build the default image locally before running Dockerized loops.
+
+If you installed through opencode's plugin installer, the package bin may not be available on your shell `PATH`. Build the image with direct package execution:
+
+```bash
+bunx @john-ezra/openralph docker build
+```
+
+If the `openralph` binary is already on `PATH`, such as from a global package install, AUR/Omarchy install, or local checkout, you can use:
+
+```bash
+openralph docker build
+```
+
+Use a custom tag for the default image if desired:
+
+```bash
+bunx @john-ezra/openralph docker build --tag openralph:rust
+```
+
+Projects can extend the local image with a small Dockerfile:
+
+```Dockerfile
+FROM openralph:local
+
+USER root
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends cargo rustc \
+  && rm -rf /var/lib/apt/lists/*
+
+USER opencode
+```
+
+Build it with Docker directly:
+
+```bash
+docker build -f Dockerfile.openralph -t openralph:rust .
+```
+
+Then point plugin options at that tag with `"docker": { "enabled": true, "image": "openralph:rust" }`.
+
+The default image includes `opencode-ai@1.15.13`, Bun, Node 22, npm/npx/corepack, Git, Bash, curl, Python 3, native build tools, ripgrep, Google Chrome stable, screenshot-friendly fonts, and `chrome-devtools-mcp@1.1.1`.
+
+Restart opencode after installing or changing `opencode.json`, `tui.json`, or plugin files. opencode loads plugin/config files only at startup.
+
+## Security Posture
+
+OpenRalph Plan and Build child iterations run `opencode run --dangerously-skip-permissions`. Treat the agent's actions as untrusted.
+
+Host mode runs those child iterations directly on your machine with inherited environment variables, host filesystem access, and unrestricted network access. Direct CLI/headless runs use host mode unless Docker is enabled through plugin options or `OPENRALPH_OPTIONS_JSON`.
+
+Docker mode reduces host filesystem blast radius, but it is not a formal sandbox. The agent can read the mounted repository and the read-only mounted OpenCode auth file, and Docker mode does not restrict network egress. The `.env*` masking feature only replaces files whose basename starts with `.env`, except `.env.example`, `.env.sample`, `.env.template`, and `.env.dist`; it does not mask other in-repo secrets such as `.npmrc`, private keys, cloud credentials, or service-account JSON.
+
+Docker mode mounts the repository read/write, including `.git`, because Build must create commits inside the container. OpenRalph disables hooks and fsmonitor for Git commands it runs on the host, but your own host-side Git commands may still honor agent-written hooks or Git config after a Docker run. Use a disposable clone or dedicated branch for autonomous Ralph runs, review changes before running host tools, and push manually only after review.
+
+## Local Development
+
+For local development against this checkout, use relative file plugin specs instead of absolute machine paths:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [["./src/plugin.ts", {}]]
+}
+```
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": [["./src/tui.ts", {}]]
+}
+```
+
+## Lean Project Setup
+
+OpenRalph works best when the target project supplies a small set of clear disk artifacts:
+
+- `specs/*`: behavioral requirements for Plan to compare against the codebase.
+- `AGENTS.md`: operational contract only, especially build/test/lint/typecheck commands and important project conventions.
+- `IMPLEMENTATION_PLAN.md`: prioritized mutable work queue maintained by Plan and Build.
+- Validation backpressure: tests, typecheck, lint, and browser checks for UI work when practical.
+
+Keep setup lean. If output is poor, improve validation or split plan items before expanding prompts or adding modes.
+
+## TUI Usage
+
+Run `/ralph` from the opencode TUI to open the Ralph mode selector. Select Design, Plan, or Build with the arrow keys.
+
+Design opens an optional idea prompt. If you leave it blank, Ralph starts by asking what you are working on. If you enter an idea, Ralph starts the current host session with a design prompt that guides ideation toward planning-ready `specs/*.md` artifacts.
+
+Plan and Build open an args dialog after you choose them from the `/ralph` menu. The dialog collects the same loop args as the CLI entrypoints.
+
+The dialog placeholder is only an example. For bounded smoke tests, enter `1`. Leaving the dialog empty uses the default unlimited loop, though Ralph may still stop after one iteration when it reports completion.
+
+When Plan or Build starts, OpenRalph opens the output viewer automatically so you can inspect recent Docker/opencode output without streaming raw child output into the TUI renderer. While a loop is active, the output viewer asks for confirmation: Confirm or Esc closes only the viewer, while Cancel stops the active loop.
+
+## Run Artifacts
+
+Plan and Build write durable project-local run artifacts under `runs/openralph-<phase>-YYYYMMDD-HHMMSS/`. OpenRalph creates `runs/.gitignore` so the artifacts stay out of normal Git status; you can also add `/runs/` to the target repo's tracked `.gitignore` if you want that ignore rule shared.
+
+Typical shape:
+
+```text
+runs/openralph-build-YYYYMMDD-HHMMSS/
+  ralph.log
+  iter-001.jsonl
+  iter-001.txt
+```
+
+Artifacts are audit/debug output, not loop state. Fresh child iterations still rely on `specs/*`, `AGENTS.md`, `IMPLEMENTATION_PLAN.md`, and the static prompts.
+
+Use artifacts as the backpressure audit trail. Review them for repeated failures, dangerous commands, unexpected sensitive path access, skipped validation, bad assumptions, or missing tests, then convert those findings into better tests, lint/typecheck rules, `AGENTS.md` operational notes, specs, or new `IMPLEMENTATION_PLAN.md` tasks.
+
+Run artifacts may contain terminal output, command details, paths, and model text. Do not commit or share them blindly.
+
+## Runtime Notes
+
+- Plan and Build require a Git worktree.
+- `/ralph` is the only public TUI slash command. It selects Design, Plan, and Build. Design is a current-session requirements conversation; Plan and Build are external launcher loops.
+- Public prompt-backed Ralph commands are stale. OpenRalph deletes stale `ralph-define`, `ralph-plan`, and `ralph-build` command config entries when the server plugin loads and throws if one is executed anyway.
+- `/ralph-plan-iteration` and `/ralph-build-iteration` are internal prompt-backed commands and are exposed only to authorized loop child processes.
+- `main` and `master` produce a warning but are not blocked.
+- Docker mode disables project OpenCode config inside the container and injects config that loads only image-bundled OpenRalph for internal child commands.
+- Docker mode is enforced with runtime attestation: the host passes a random token through env and a read-only token-file mount, and the container refuses to run the loop if the token/evidence check fails.
+- Docker mode injects a `chrome-devtools` MCP server for browser validation. The MCP server uses `/opt/openralph/bin/chrome-devtools-mcp-wrapper`, which starts isolated headless Chrome on a loopback debugging port and connects via `--browser-url`.
+- The default image uses a non-root `opencode` user when Docker cannot run as the host UID/GID.
+- Docker mode mounts the repo read/write at `/workspace`, mounts host OpenCode auth read-only but readable by the agent, and masks real `.env*` files by default.
+- `.env.example`, `.env.sample`, `.env.template`, and `.env.dist` remain visible in Docker mode.
+- Docker mode does not restrict network egress.
+- `.env*` masking is best-effort and does not cover other in-repo secret files such as `.npmrc`, private keys, cloud credentials, or service-account JSON.
+- Docker mode does not mount host home, host OpenCode config, Git config, SSH keys, GPG material, browser profiles, browser cookies, desktop sockets, or the Docker socket.
+- Dockerized OpenRalph Build requires host/project Git `user.name` and `user.email`. OpenRalph passes those values as author/committer env vars, disables commit/tag signing inside Docker, and rejects `--push` in Docker mode.
+- Child iterations run `opencode run --dir <project-root> --command <internal-command> --dangerously-skip-permissions`.
+- Docker mode runs `openralph plan` or `openralph build` inside the container. It never replays public prompt-backed Ralph commands.
+- Child iterations never use `--continue`.
+- Plan and Build persist project-local run artifacts under `runs/openralph-<phase>-YYYYMMDD-HHMMSS/` for audit/debug output.
+- Ctrl+C is the manual stop mechanism.
+- OpenRalph Build with `--push` pushes commits only in host mode. Docker mode rejects `--push`; review local commits on the host before pushing.
+- Use `--no-docker` to intentionally run a loop on the host when Docker mode is enabled.
+- Build tags are local lightweight tags shaped like `openralph/build-YYYYMMDD-HHMMSS/001`.
+- Frontend or web UI build tasks should validate in a browser when practical, using the Docker-provided Chrome DevTools MCP tools for screenshots, console errors, desktop/mobile layout checks, and browser-visible issues.
+- If a build task stalls repeatedly, stop the loop and split the plan item; retries are not a substitute for smaller tasks.
+
+Use a dedicated branch or disposable clone for autonomous Ralph runs. Docker mode reduces host filesystem blast radius, but it is not a formal sandbox guarantee.
+
+## Verified Smoke Tests
+
+The Docker/TUI migration was smoke-tested with `opencode-ai@1.15.13` using a disposable fixture repo.
+
+- OpenRalph Plan selected from `/ralph` ran Docker with token attestation, produced `IMPLEMENTATION_PLAN.md`, and emitted `RALPH_PLAN_COMPLETE`.
+- OpenRalph Build selected from `/ralph` with args `1` ran Docker with token attestation, implemented one greeting task, passed `npm test`, and created a commit in the fixture repo.
+- Spoofed Docker markers and a direct container run without the mounted attestation token both failed before `runLoop()`.
+- Build tags are created only when the worktree is clean after a successful build commit; an untracked local `tui.json` in the fixture correctly prevented tagging.
+
+## Development
+
+```bash
+bun install
+bun run validate
+```

package/bin/openralph

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+exec bun "${script_dir}/../src/cli.ts" "$@"

package/bun.lock

@@ -0,0 +1,85 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@john-ezra/openralph",
+      "devDependencies": {
+        "@opencode-ai/plugin": "1.15.13",
+        "@types/bun": "latest",
+        "typescript": "latest",
+      },
+    },
+  },
+  "packages": {
+    "@msgpackr-extract/msgpackr-extract-darwin-arm64": ["@msgpackr-extract/msgpackr-extract-darwin-arm64@3.0.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-LCkGo6JDfaBhgST7UpPWgNgLINpcpabaHfyz5OBx75nUYxBsaEPxjnyNjWpeb/xBup/682QnBfRBy2/LvPutZQ=="],
+
+    "@msgpackr-extract/msgpackr-extract-darwin-x64": ["@msgpackr-extract/msgpackr-extract-darwin-x64@3.0.4", "", { "os": "darwin", "cpu": "x64" }, "sha512-zExlW9zUJKZH/tOtVMttwjKa4Xm/3KcNjnE3dPN92uCktwavMxpgCA3MoJK/DOnTWsQgo224OaST27/mPNAf+w=="],
+
+    "@msgpackr-extract/msgpackr-extract-linux-arm": ["@msgpackr-extract/msgpackr-extract-linux-arm@3.0.4", "", { "os": "linux", "cpu": "arm" }, "sha512-Tg3yX65f5GbtXLkrYEHE5oibZG9epyYWas7FogTTEJeDEF9JlXJzKgXaNhT3UXlTOeA+AfZpYZYZ0uPj7Cfquw=="],
+
+    "@msgpackr-extract/msgpackr-extract-linux-arm64": ["@msgpackr-extract/msgpackr-extract-linux-arm64@3.0.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-dgX0P/9wGPJeHFBG+ZmhgE6bmtMt7NP5CRBGyyktpopdk/mW4POnrpQsSLtKI1dwpc+pPLuXHDh6vvskyQE/sw=="],
+
+    "@msgpackr-extract/msgpackr-extract-linux-x64": ["@msgpackr-extract/msgpackr-extract-linux-x64@3.0.4", "", { "os": "linux", "cpu": "x64" }, "sha512-8TNXMEjJc3QEy7R/x1INhgiU+XakDAFUzBhaz7+Rbrs8NH5UQeHQxxmzsSBJGyV6I1jW79undiQm8tOI+D+8FQ=="],
+
+    "@msgpackr-extract/msgpackr-extract-win32-x64": ["@msgpackr-extract/msgpackr-extract-win32-x64@3.0.4", "", { "os": "win32", "cpu": "x64" }, "sha512-CmCXPQrkbwExx3j946/PtHWHbYJiCRBRDl4BlkRQcJB/YOwQxJRTpoo7aTsortjgoJ1x7opzTSxn7C+ASSLVjQ=="],
+
+    "@opencode-ai/plugin": ["@opencode-ai/plugin@1.15.13", "", { "dependencies": { "@opencode-ai/sdk": "1.15.13", "effect": "4.0.0-beta.66", "zod": "4.1.8" }, "peerDependencies": { "@opentui/core": ">=0.2.16", "@opentui/keymap": ">=0.2.16", "@opentui/solid": ">=0.2.16" }, "optionalPeers": ["@opentui/core", "@opentui/keymap", "@opentui/solid"] }, "sha512-NFwZGhmxIPijtfz9swPJXDmhOpq4UWP8WjEE7GEMr7FwtJrK/hv6v36nFimed5+OKk+pQCrTJn/vhRW7Io72IA=="],
+
+    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.15.13", "", { "dependencies": { "cross-spawn": "7.0.6" } }, "sha512-4TwojIoQ8EG6/mVBuUVYZXiFcwNmiiytEnjnvyuvSJjGwFIlw2YIBFxtSVC3FbwwbwHT63teh1RHiQUUC4U5xw=="],
+
+    "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
+
+    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
+
+    "@types/node": ["@types/node@25.9.1", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg=="],
+
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
+    "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
+
+    "detect-libc": ["detect-libc@2.1.2", "", {}, "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ=="],
+
+    "effect": ["effect@4.0.0-beta.66", "", { "dependencies": { "@standard-schema/spec": "^1.1.0", "fast-check": "^4.6.0", "find-my-way-ts": "^0.1.6", "ini": "^6.0.0", "kubernetes-types": "^1.30.0", "msgpackr": "^1.11.9", "multipasta": "^0.2.7", "toml": "^4.1.1", "uuid": "^13.0.0", "yaml": "^2.8.3" } }, "sha512-4arEr62cziFa8BBVDUwJCJJmaVepXf/kRg7KtC0h8+bufngscrHbwWFhr9c+HonwOF+31U3iD3xUJmw9KzX7Dw=="],
+
+    "fast-check": ["fast-check@4.8.0", "", { "dependencies": { "pure-rand": "^8.0.0" } }, "sha512-GOJ158CUMnN6cSahsv4+ExARvIDuzzinFjkp0E9WtiBa5zcVeLozVkWaE4IzFcc+Y48Wp1EDlUZsXRyAztQcSg=="],
+
+    "find-my-way-ts": ["find-my-way-ts@0.1.6", "", {}, "sha512-a85L9ZoXtNAey3Y6Z+eBWW658kO/MwR7zIafkIUPUMf3isZG0NCs2pjW2wtjxAKuJPxMAsHUIP4ZPGv0o5gyTA=="],
+
+    "ini": ["ini@6.0.0", "", {}, "sha512-IBTdIkzZNOpqm7q3dRqJvMaldXjDHWkEDfrwGEQTs5eaQMWV+djAhR+wahyNNMAa+qpbDUhBMVt4ZKNwpPm7xQ=="],
+
+    "isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
+
+    "kubernetes-types": ["kubernetes-types@1.30.0", "", {}, "sha512-Dew1okvhM/SQcIa2rcgujNndZwU8VnSapDgdxlYoB84ZlpAD43U6KLAFqYo17ykSFGHNPrg0qry0bP+GJd9v7Q=="],
+
+    "msgpackr": ["msgpackr@1.11.12", "", { "optionalDependencies": { "msgpackr-extract": "^3.0.2" } }, "sha512-RBdJ1Un7yGlXWajrkxcSa93nvQ0w4zBf60c0yYv7YtBelP8H2FA7XsfBbMHtXKXUMUxH7zV3Zuozh+kUQWhHvg=="],
+
+    "msgpackr-extract": ["msgpackr-extract@3.0.4", "", { "dependencies": { "node-gyp-build-optional-packages": "5.2.2" }, "optionalDependencies": { "@msgpackr-extract/msgpackr-extract-darwin-arm64": "3.0.4", "@msgpackr-extract/msgpackr-extract-darwin-x64": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-arm": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-arm64": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-x64": "3.0.4", "@msgpackr-extract/msgpackr-extract-win32-x64": "3.0.4" }, "bin": { "download-msgpackr-prebuilds": "bin/download-prebuilds.js" } }, "sha512-4kmO/MdyUIkLIvTPr8VHLil4AtoKIoniWPIEk5+CDy0xnWC84azhSFmuJ7PxZdsYtiP5kEeQsORAVIeMgxT+Hw=="],
+
+    "multipasta": ["multipasta@0.2.7", "", {}, "sha512-KPA58d68KgGil15oDqXjkUBEBYc00XvbPj5/X+dyzeo/lWm9Nc25pQRlf1D+gv4OpK7NM0J1odrbu9JNNGvynA=="],
+
+    "node-gyp-build-optional-packages": ["node-gyp-build-optional-packages@5.2.2", "", { "dependencies": { "detect-libc": "^2.0.1" }, "bin": { "node-gyp-build-optional-packages": "bin.js", "node-gyp-build-optional-packages-optional": "optional.js", "node-gyp-build-optional-packages-test": "build-test.js" } }, "sha512-s+w+rBWnpTMwSFbaE0UXsRlg7hU4FjekKU4eyAih5T8nJuNZT1nNsskXpxmeqSK9UzkBl6UgRlnKc8hz8IEqOw=="],
+
+    "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
+
+    "pure-rand": ["pure-rand@8.4.0", "", {}, "sha512-IoM8YF/jY0hiugFo/wOWqfmarlE6J0wc6fDK1PhftMk7MGhVZl88sZimmqBBFomLOCSmcCCpsfj7wXASCpvK9A=="],
+
+    "shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
+
+    "shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="],
+
+    "toml": ["toml@4.1.1", "", {}, "sha512-EBJnVBr3dTXdA89WVFoAIPUqkBjxPMwRqsfuo1r240tKFHXv3zgca4+NJib/h6TyvGF7vOawz0jGuryJCdNHrw=="],
+
+    "typescript": ["typescript@6.0.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw=="],
+
+    "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
+
+    "uuid": ["uuid@13.0.2", "", { "bin": { "uuid": "dist-node/bin/uuid" } }, "sha512-vzi9uRZ926x4XV73S/4qQaTwPXM2JBj6/6lI/byHH1jOpCzb0zDbfytgA9LcN/hzb2l7WQSQnxITOVx5un/wGw=="],
+
+    "which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
+
+    "yaml": ["yaml@2.9.0", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA=="],
+
+    "zod": ["zod@4.1.8", "", {}, "sha512-5R1P+WwQqmmMIEACyzSvo4JXHY5WiAFHRMg+zBZKgKS+Q1viRa0C1hmUKtHltoIFKtIdki3pRxkmpP74jnNYHQ=="],
+  }
+}