@beremaran/ralphie 0.0.0-stage → 0.2.1

package/docs/README.md

@@ -0,0 +1,71 @@
+# Ralphie documentation
+
+This directory is the detailed documentation set for Ralphie. The [root
+README](../README.md) is the concise product overview and first-run guide;
+these pages are the authoritative home for contracts that should not be
+buried in a landing page.
+
+## Suggested reading paths
+
+### New user
+
+1. [Getting started](getting-started.md): prerequisites, installation,
+   authentication, verification, and a safe first run.
+2. [Safety](safety.md): understand what a mutation-enabled run can change.
+3. [Workflows](workflows.md): see how issues are routed and delivered.
+4. [Configuration](configuration.md): write the config file.
+5. [CLI reference](cli-reference.md): choose options and adapt the recipes.
+
+### Operator
+
+1. [Safety](safety.md): review direct-push defaults, invariants, and workspace
+   risks before operating on a real repository.
+2. [Configuration](configuration.md) and [CLI reference](cli-reference.md) -
+   settings, invocation, output, and environment variables.
+3. [Operations and recovery](operations-and-recovery.md): interpret output,
+   inspect artifacts, and understand what remains after interruption.
+4. [Workflows](workflows.md): understand implementation, decomposition, and
+   direct-push delivery.
+
+### Contributor
+
+1. [Development](development.md): local setup, checks, tests, and contribution
+   expectations.
+2. [Architecture](architecture.md): runtime assembly and domain boundaries.
+3. [Workflows](workflows.md): behavior and mutation boundaries to preserve.
+4. [Operations and recovery](operations-and-recovery.md): state and recovery
+   contracts that changes must not break.
+
+### Release maintainer
+
+1. [Getting started](getting-started.md): the installation contract
+   (`bunx @beremaran/ralphie`) and first run.
+2. [Development](development.md): build, package smoke, and the tag-triggered
+   npm publish flow.
+3. [Operations and recovery](operations-and-recovery.md): operational state and
+   cleanup behavior.
+
+## Page map
+
+| Page | Purpose |
+| --- | --- |
+| [Getting started](getting-started.md) | Install Ralphie, configure credentials, verify it, and run the first run. |
+| [Workflows](workflows.md) | Explain issue routing, implementation, decomposition, and direct-push delivery. |
+| [Safety](safety.md) | Define deterministic Git/GitHub safety checks and destructive workspace behavior. |
+| [Configuration](configuration.md) | Define the YAML config file, every key and default, repository overrides, and `--set`. |
+| [CLI reference](cli-reference.md) | Record the command syntax, remaining options, environment variables, and recipes. |
+| [Operations and recovery](operations-and-recovery.md) | Document progress, artifacts, state, cancellation, failure, and cleanup. |
+| [Architecture](architecture.md) | Map runtime, orchestrator, domain services, and source locations. |
+| [Development](development.md) | Explain local development, test commands, optional registry checks, the vendored skills sync, and contribution rules. |
+
+## Keeping documentation current
+
+Keep each contract authoritative on one page. Put new settings in
+[Configuration](configuration.md), new CLI options in the [CLI
+reference](cli-reference.md), workflow behavior in [Workflows](workflows.md),
+recovery behavior in [Operations and recovery](operations-and-recovery.md),
+component changes in [Architecture](architecture.md), and release changes in
+[Development](development.md)'s publishing section. Summaries elsewhere should
+link here rather than copy sections that can drift. Keep safety warnings
+visible before mutation-enabled commands and use relative links so pages work
+on GitHub and in a checkout.

package/docs/architecture.md

@@ -0,0 +1,159 @@
+# Architecture
+
+This page is for contributors and maintainers who need the runtime and domain
+boundaries, component map, or source locations. It is the authoritative
+architecture overview. Return to the [documentation index](README.md).
+
+## Runtime boundaries
+
+Ralphie uses Bun's built-in argument parser and native promises. Services are
+assembled as an explicit dependency object, which keeps the runtime small and
+makes tests straightforward without a framework-specific execution model.
+
+```mermaid
+flowchart LR
+    U[Operator] --> CLI["Inbound adapter<br/>command.ts / cli.ts / options.ts"]
+    CLI --> CTX["Bounded contexts<br/>agent · config · git · github · harness · issues<br/>process · progress · run · workflow · workspace"]
+    CTX --> PORTS["<context>/ports.ts + /domain"]
+    PORTS -. implemented by .-> AD["<context>/adapters/"]
+    AD --> GH[GitHub API]
+    AD --> REPO[Workspace checkout]
+    AD --> LLM[Harness CLIs]
+    AD --> DISK[State, artifacts, diagnostics]
+    AD --> TERM[Terminal or JSON Lines]
+```
+
+Each bounded context owns its contract, domain model, and adapters together:
+`<context>/ports.ts` (and `issues/domain/`) declares the core-owned types,
+`<context>/adapters/` implements them, and application logic lives beside them
+(`issues/app/`, `agent/`, `workflow/`). `src/runtime.ts` is the composition root
+that binds concrete adapters into the runtime bundle.
+
+| Context | Location | Responsibility |
+| --- | --- | --- |
+| `agent` | `src/agent/` | Prompts, structured-output and text-task helpers, and the role-to-session mapping (access mode, timeouts) over the harness port. Kept apart from `harness` on purpose: `agent` holds Ralphie's own prompts and role policy, while `harness` stays provider-neutral session plumbing that knows nothing about issues. |
+| `config` | `src/config/` | YAML configuration: the zod schema (`settings.ts`), layering and `--set` overrides (`load.ts`, `overrides.ts`), and the file-reader port with its Bun YAML adapter. |
+| `harness` | `src/harness/` | Provider-neutral harness port (session request, events, typed failures, structured results), the service that runs sessions and repairs invalid results, and one CLI adapter per harness (Claude Code, Codex, pi and OpenCode). Every workflow session runs through it, wrapped by session isolation, the read-only fingerprint guard and skill injection; `app/roles.ts` resolves the configured role assignments. The vendored skills live in `vendor/mattpocock-skills/` (see [Development](development.md#vendored-skills)). |
+| `github` | `src/github/` | Issue value objects, repository slug parsing, and the Octokit/`gh` adapters. |
+| `git` | `src/git/` | Checkout preparation, checkpoints, issue operations, invariants, and remote-safety adapters. |
+| `issues` | `src/issues/` | Domain (`domain/`), executors and artifact/recovery logic (`app/`), filesystem adapters (`adapters/`). |
+| `progress` | `src/progress/` | `ports.ts` contract plus the OpenTUI interactive adapter and the plain/JSON adapters. It renders only harness-neutral session events and imports nothing from `agent` or a harness adapter. |
+| `run` | `src/run/` | Versioned run-state schemas, the state/event-log ports, and their adapters. |
+| `process` | `src/process/` | Bounded command runner port (timeout, abort, stdin, streamed stdout lines), the helper, and its adapter. |
+| `workspace` | `src/workspace/` | Path expansion, the workspace port, and the protected-removal adapter. |
+| `workflow` | `src/workflow/` | Issue-workflow orchestration, the runtime bundle port, and exit-code policy. |
+| Inbound adapter | `src/command.ts`, `src/cli.ts`, `src/options.ts` | CLI parsing, terminal detection, and the top-level error boundary. |
+| Composition root | `src/runtime.ts` | Builds concrete adapters and exposes them as the workflow runtime bundle. |
+| Shared kernel | `src/shared/` | Errors and terminal-control sanitization used by every context. |
+
+Dependency direction is one-way. Contexts import each other's `ports.ts`,
+domain modules and pure `app/` helpers (no I/O, no process or vendor imports),
+never another context's `adapters/`; only the composition root
+(`runtime.ts`, `command.ts`) instantiates adapters. Non-adapter code imports no
+`node:fs`, `node:child_process`, vendor SDK, or process stream. The `issues`
+context defines its file-system ports (`IssueArtifactFileSystem`,
+`RecoveryFileSystem`) in `issues/app/` and its node implementations live in
+`issues/adapters/`, so the atomic-write and diagnostic logic never touches
+`node:fs`. Adapters receive their dependencies instead of constructing them:
+the GitHub capability adapters share one adapter-owned session, git adapters
+receive the command runner, and the run receives a composition-resolved
+`RunLayout` plus injected `Clock` and `IdGenerator`, so no application code
+reads the clock, generates ids, or composes workspace paths itself.
+Cross-cutting composed services such as parent completion and issue
+preparation live in `issues/app/`, and `workflow/ports.ts` exposes the
+driving `IssueWorkflow` port that the CLI invokes.
+
+The progress contract lives in `src/progress/ports.ts`; `src/progress/adapters/`
+implements it and is imported only by the composition root. `src/command.ts`
+owns the terminal decision and passes one shared `RunEventLog` to the
+coordinator (for persistence) and the runtime (the run closes it before
+removing the workspace). `tests/architecture.test.ts` enforces the adapter
+import rules, the no-I/O rule for non-adapter code, the Octokit confinement
+(the `github` context is the only place the SDK appears), composition-root
+isolation, and process-stream ownership. `tests/contracts/` holds the shared
+behavioral suites that both the in-memory fakes and the live adapters pass: the
+`RunEventLog` and `IssueArtifactStore` suites, the harness adapter suite that
+every `HarnessAdapter` must pass (`harness-adapter.contract.ts`), and the
+harness service suite (`harness-service.contract.ts`).
+
+## Skill injection
+
+For each session, skill injection copies the pinned skills into the harness's
+project skills location (`SKILL_SUPPORT` in `src/harness/app/skill-injection.ts`),
+shadows any same-named repository skill until the session ends, and adds the
+copies to `.git/info/exclude`. The spec also allows a per-invocation skills
+option where a harness has one. Of the four, only pi does (`--skill <path>`).
+Claude Code's `--plugin-dir` would load the skills as a plugin and rename them
+`plugin:name`, and Codex and OpenCode have no such flag. Ralphie therefore uses
+the project location for every harness, so shadowing and exclusion live in one
+place. A new harness adds one `SKILL_SUPPORT` entry, its location and invocation
+syntax together.
+
+## OpenCode adapter findings
+
+Spike against OpenCode v2.0.22 (the published docs mostly describe v1). The recorded streams live in `tests/harness/fixtures/opencode/`.
+
+- **Invocation**: `opencode run --standalone --format json`, prompt on stdin (with no message it prints an `error` event, "You must provide a message"). `--standalone` starts a private server, so the invocation's working directory and environment apply; the background service is shared and is never used.
+- **Events**: one JSON object per line: `step_start`, `text` (whole block), `tool_use` (one event with input and output once the tool finished; `state.status` is `completed` or `error`, and a tool can report failure through `metadata.metadata.error` while `completed`), `step_finish` (`tokens` and `cost` per step) and `error` (`error.type` such as `provider.no-route` or `provider.quota`). There is no terminal result event, so a run succeeded when it exited 0, printed no `error` event and produced text. An error makes the process exit 1.
+- **Usage**: the adapter sums every `step_finish` into one usage event per turn. `cost` is 0 for the recorded runs, so `costUsd` is omitted then. There is no budget cap flag.
+- **Sessions**: `--session <id>` resumes, or creates the session when it does not exist. Session ids look like `ses_...`.
+- **Model and effort**: `--model provider/model#variant`; the variant plays the part of effort and is only applied together with a model.
+- **Access**: there is no sandbox. Read-only uses `--agent plan`, which denies edit tools but still allows shell commands, so it is not a hard guarantee. `--auto` approves every permission that is not denied and is the only editing mode; `safe` is refused with an `access` failure before anything runs. Without `--auto` a headless run cannot answer approval prompts.
+- **Structured output**: none native. The service falls back to the fenced JSON block protocol.
+- **Skills**: a skill under `.opencode/skills/<name>/` is loaded headlessly through the `skill` tool (recorded in `skill.jsonl`). Skills hidden from the model (user-only) were not tested.
+- **Not verified live**: the spike had no usable model credits, so a successful read-only `--agent plan` run, resuming with `--session`, and user-only skills headlessly are untested against the real CLI. The recorded success streams come from earlier notes; only the error streams were recorded fresh. Until that run passes, startup refuses OpenCode unless the configuration sets `harnesses.opencode.experimental: true` (`UNVERIFIED_HARNESSES` in `src/harness/ports.ts`). Run [the live smoke script](development.md#live-smoke-script) with `--harness opencode` to verify it, and drop it from that list once it passes. The smoke script opts in on its own.
+
+## Dependency and side-effect rules
+
+Agents own reasoning and edits within their permitted tool boundary. They do not
+own commits, pushes, issue mutations, or delivery sequencing. Deterministic
+services under `src/git/adapters/` and `src/github/adapters/` perform those side
+effects and verify their invariants. The explicit runtime object makes these
+boundaries testable without a framework-specific execution model.
+
+The `GitRepositoryFactsService` port in `src/git/ports.ts` reads HEAD, branch, status, recent log, and tracked files so read-only prompts, whose sessions have no shell, receive them as a `<repository-facts>` block.
+
+Agent configuration is separate from persistent workspace state: the
+`harnesses` and `roles` configuration keys choose the harness, model, and
+effort per role, and each harness CLI keeps its own login and credentials.
+Ralphie never stores agent configuration under the
+workspace; run state and recovery artifacts belong under the workspace's
+`.ralphie` directory.
+
+For workflow behavior and the agent/deterministic boundary, see [Workflows](workflows.md)
+and [Safety](safety.md). For state transitions and retained diagnostics, see
+[Operations and recovery](operations-and-recovery.md).
+
+## Distribution boundary
+
+Ralphie's only distribution channel is the published npm package (see
+[Getting started](getting-started.md#published-package)); the former native
+binary, installer, Homebrew, and container distribution machinery was removed.
+
+The package boundary is the bundled `dist/ralphie.js` CLI reached from
+`index.ts` through `src/cli.ts`, `src/command.ts`, and runtime assembly. Tests
+and helper probes are verification-only consumers. In particular, a type-only
+import can document or check a contract but does not make a module runtime
+reachable. The deterministic source audit is described in
+[Development](development.md#source-reachability-boundary) and runs as part of
+the normal check gate.
+
+## Source map
+
+| Concern | Primary source |
+| --- | --- |
+| Configuration schema, layering, and file loading | `src/config/` |
+| Public trigger and flags | `index.ts`, `src/cli.ts`, `src/command.ts`, `src/options.ts` |
+| Runtime dependency assembly | `src/runtime.ts` |
+| Run orchestration, queue, state transitions | `src/workflow/workflow.ts`, `src/issues/domain/queue.ts` |
+| Pre-flight routing | `src/issues/app/issue-routing.ts`, `src/issues/app/execution-model.ts` (outcomes and execution context), `src/issues/app/preflight.ts` |
+| Hand-offs | `src/issues/domain/hand-off.ts`, `src/issues/app/hand-off.ts`, `src/github/adapters/hand-off.ts` |
+| AFK triage | `src/workflow/triage-phase.ts`, `src/issues/app/triage.ts`, `src/github/adapters/triage.ts` |
+| Implementation/review/delivery | `src/issues/app/implementation-executor.ts` (attempts and delivery), `src/issues/app/implementation-attempt.ts` (prompt, result, retry policy), `src/issues/app/candidate-review.ts` (candidate commits and the two-axis review gate), `src/issues/app/verification.ts`, `src/git/adapters/issue-operations.ts`, `src/git/adapters/remote-safety.ts` |
+| Decomposition and GitHub mutations | `src/issues/app/decomposition-executor.ts`, `src/github/adapters/issue-mutations.ts`, `src/github/adapters/issue-relationships.ts` |
+| Role assignments, session requests, and structured results | `src/harness/app/roles.ts`, `src/agent/` |
+| Harness sessions, structured results, and the harness adapters | `src/harness/ports.ts`, `src/harness/app/`, `src/harness/adapters/` |
+| Git checkpoints, safety, and branches | `src/git/` |
+| Durable run state, artifacts, diagnostics, and event audit | `src/issues/app/artifacts.ts`, `src/issues/app/recovery.ts`, `src/run/`, `src/issues/adapters/` |
+| Driving port and runtime bundle | `src/workflow/ports.ts`, `src/runtime.ts` |
+| Execution contracts, presentation, and exit semantics | `src/*/ports.ts`, `src/progress/adapters/` (OpenTUI, plain, JSON), `src/workflow/exit-code.ts` |

package/docs/cli-reference.md

@@ -0,0 +1,126 @@
+# CLI reference
+
+This page is for operators automating Ralphie. It is the authoritative
+reference for invocation syntax, command-line options, environment variables,
+and common recipes. Settings live in the [configuration file](configuration.md). Return to the
+[documentation index](README.md) for suggested reading paths.
+
+## Invocation
+
+```text
+bunx @beremaran/ralphie [owner/]repository [options]
+```
+
+`[owner/]repository` is required. It accepts an `owner/name` slug, a GitHub
+HTTPS/SSH clone URL, or a bare repository name whose owner comes from
+`defaultOwner` or the authenticated `gh` login (see
+[Configuration](configuration.md#choosing-a-repository)). Nothing is inferred
+from the current directory. Extra positional arguments are rejected. When
+running from a source checkout, replace the package runner with
+`bun run index.ts`.
+
+Run `bunx @beremaran/ralphie --help` for the help generated from the current
+command schema.
+
+> [!CAUTION]
+> Ralphie commits and pushes directly to the selected branch. Test against a
+> repository you control, and read the [safety model](safety.md) before
+> running it.
+
+## `init`
+
+```text
+bunx @beremaran/ralphie init [--config <path>]
+```
+
+Detects the harnesses on PATH and writes a commented starter config at
+`--config` or the default location. It never overwrites an existing file and
+fails when no supported harness is found. See
+[Getting started](getting-started.md#create-the-config-file).
+
+## Options
+
+All behavior settings live in the [configuration file](configuration.md).
+These options remain on the command line:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--config <path>` | `$XDG_CONFIG_HOME/ralphie/config.yaml`, else `~/.config/ralphie/config.yaml` | Read configuration from this file. A missing file is an error. |
+| `--set <path=value>` | none | Override one configuration key for this run; repeatable. The path is dotted, a key containing a slash is double-quoted (`repos."owner/repo".branch=develop`), and the value is YAML. Applied after the file and the matching `repos` entry. |
+| `--output <mode>` | `default` | Output mode: `default` renders the full-screen TUI on a terminal and plain append-only lines when piped or in CI; `json` writes JSON Lines on stdout. |
+
+The short aliases are `-h` for `--help` and `-v` for `--version`. Former flags
+fail with an error naming the configuration key that replaces them; the
+mapping is in [Configuration](configuration.md#removed-flags).
+
+Every run processes the entire matching open-issue queue, sequentially, in the
+order set by `intake.sort`.
+
+## Environment variables
+
+Ralphie also reads these environment variables:
+
+| Variable | Purpose |
+| --- | --- |
+| `GH_TOKEN` | GitHub.com token for noninteractive `gh` authentication (preferred). |
+| `GITHUB_TOKEN` | Fallback GitHub.com token alias for `gh`. |
+
+For interactive `github.com` use, authenticate with `gh auth login` and verify
+with `gh auth status`. For unattended use, provide `GH_TOKEN` (preferred) or
+`GITHUB_TOKEN` as an environment input; it does not need to be printed or
+exposed. A mounted GitHub CLI profile is not required when an environment token
+is provided. This authentication contract covers `github.com` only. See
+[Getting started](getting-started.md) for the first-run setup.
+
+## Common recipes
+
+Run the issue queue with settings from the default config file:
+
+```bash
+bunx @beremaran/ralphie owner/repository
+```
+
+Use a different config file and a bare repository name:
+
+```bash
+bunx @beremaran/ralphie repository --config ./ralphie.yaml
+```
+
+Override settings for one run:
+
+```bash
+bunx @beremaran/ralphie owner/repository \
+  --set 'intake.requireLabels=[bug]' \
+  --set 'repos."owner/repository".branch=develop'
+```
+
+Choose a model and effort for one run with `--set` (see
+[Configuration](configuration.md#harnesses-and-roles)):
+
+```bash
+bunx @beremaran/ralphie owner/repository \
+  --set harnesses.claude.model=opus \
+  --set harnesses.claude.effort=high
+```
+
+Write machine-readable progress to stdout:
+
+```bash
+bunx @beremaran/ralphie owner/repository --output json > ralphie.jsonl
+```
+
+The workflow commits and pushes directly to the selected branch. It is not a
+wait-for-human-review mode: approved work is committed, the remote head is
+revalidated, and the commit is pushed without force before the source issue is
+closed. Read [Workflows](workflows.md) and [Safety](safety.md) before running
+it; the workspace is deleted, so read [Workspace risk](safety.md#workspace-risk)
+first.
+
+## Version and help
+
+`ralphie --version` prints only the release version. For automation,
+`ralphie --version --output json` prints a stable object containing `version`
+and `commitSha`. Both forms work without a repository, GitHub credentials, or
+a model provider. Release builds embed the immutable commit SHA supplied by
+the build entry point; local builds use the documented `local` commit sentinel
+when no release SHA is supplied.

package/docs/configuration.md

@@ -0,0 +1,269 @@
+# Configuration
+
+Ralphie reads its settings from a YAML file instead of command-line flags. This
+page is the authoritative reference for the file location, every key, its
+default, and how settings are layered. Return to the
+[documentation index](README.md) for reading paths, and see the
+[CLI reference](cli-reference.md) for the few options that remain on the
+command line.
+
+## File location
+
+Ralphie loads the first of these that applies:
+
+1. The path given with `--config <path>`. A missing file is an error.
+2. `$XDG_CONFIG_HOME/ralphie/config.yaml`, when `XDG_CONFIG_HOME` is an
+   absolute path.
+3. `~/.config/ralphie/config.yaml`.
+
+There is no built-in fallback: when no file exists, Ralphie stops at startup,
+names the path it looked for, and points at `ralphie init`, which writes a
+starter file. An empty file is valid and means "all
+defaults".
+
+The file is validated with a strict schema before anything else runs. Unknown
+keys, wrong types, and unknown values fail with the offending path, for
+example `limits.reviewRounds: Invalid input: expected number, received string`. Errors caused
+by a `--set` override are marked `(from --set)`.
+
+## Choosing a repository
+
+Ralphie is invoked as `ralphie [owner/]repo`. Nothing is inferred from the
+current directory.
+
+| Argument | Resolved to |
+| --- | --- |
+| `owner/repo` or a GitHub HTTPS/SSH clone URL | Used as given. |
+| `repo` | `defaultOwner/repo`, else the login `gh` is authenticated as (`gh api user`, honoring `GH_TOKEN`/`GITHUB_TOKEN`). |
+
+## Layering
+
+For the selected repository, settings are layered from lowest to highest
+precedence:
+
+1. Built-in defaults.
+2. Top-level settings in the file.
+3. The matching `repos."owner/repo"` entry. Repository keys match
+   case-insensitively.
+4. `--set path=value` overrides, in command-line order.
+
+Mappings merge key by key. Lists and scalars replace the lower layer
+entirely: a `repos` entry that sets `intake.requireLabels` does not add to the
+top-level list.
+
+### `--set path=value`
+
+`--set` is repeatable. The path is dotted; a key containing dots or a slash
+is double-quoted, and the value is read as YAML:
+
+```bash
+ralphie acme/api \
+  --set limits.reviewRounds=3 \
+  --set 'intake.requireLabels=[bug, backend]' \
+  --set 'repos."acme/api".branch=develop'
+```
+
+A `--set` path under `repos."owner/repo"` applies to that repository like
+any file entry. Quote the whole argument for your shell when the value
+contains spaces or brackets.
+
+## Keys
+
+```yaml
+defaultOwner: acme
+workspace: ~/.ralphie
+approval: safe
+harnesses:
+  claude:
+    model: opus
+    effort: high
+    approval: safe
+roles:
+  default: claude
+  reviewer:
+    harness: claude
+    model: sonnet
+intake:
+  requireLabels: [bug]
+  sort: created:asc
+triage:
+  enabled: false
+labels:
+  needs-triage: needs-triage
+  needs-info: needs-info
+  ready-for-agent: ready-for-agent
+  ready-for-human: ready-for-human
+  wontfix: wontfix
+skills:
+  dir: ./my-skills
+limits:
+  implementationAttempts: 3
+  reviewRounds: 5
+  verificationFixes: 5
+  maxDecompositionDepth: 3
+  sessionTimeoutMinutes:
+    edit: 60
+    readOnly: 15
+  maxBudgetUsd: 5
+repos:
+  acme/api:
+    branch: develop
+    verify:
+      - bun run check
+    intake:
+      requireLabels: [bug, backend]
+```
+
+Every key is optional. The values above are the defaults, except
+`defaultOwner`, `branch`, `verify`, `skills.dir`, and `limits.maxBudgetUsd`, which have none.
+
+### Top level
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `defaultOwner` | none | Owner added to a bare `repo` argument. Top level only. |
+| `approval` | `safe` | Approval mode of the editing roles (`implementer`, `fixer`): `safe` or `yolo`. Overridable per repository and per harness. See [Approval modes](safety.md#approval-modes). |
+| `workspace` | `~/.ralphie` | Root directory for repository checkouts and run artifacts. Ralphie deletes this directory; use a path dedicated to Ralphie (see [Workspace risk](safety.md#workspace-risk)). Overridable per repository. |
+| `repos` | none | Per-repository overrides, keyed by `owner/repo`. Top level only. |
+
+### `harnesses` and `roles`
+
+Every agent session runs as a role on a harness. The harnesses are `claude`
+(Claude Code), `codex`, `pi`, and `opencode`. Sessions run through the
+harness's own command-line program, which brings its own login and
+credentials; Ralphie stores none.
+
+`harnesses.<name>` sets the defaults for sessions on that harness:
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `harnesses.<name>.model` | harness default | Model passed to the harness. |
+| `harnesses.<name>.effort` | harness default | Reasoning effort passed to the harness. |
+| `harnesses.<name>.approval` | top-level `approval` | Approval mode for editing roles that run on this harness. |
+| `harnesses.<name>.experimental` | `false` | Opt in to a harness whose adapter has not been verified against a live model. Currently only `opencode` needs it: startup refuses any role assigned to OpenCode until `harnesses.opencode.experimental: true` is set. Other harnesses ignore it. |
+
+`roles` assigns a harness to each role. A value is a harness name, or a
+mapping `{ harness, model, effort }` whose `model` and `effort` override the
+harness defaults for that role.
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `roles.default` | `claude` | Harness for every role without its own assignment. |
+| `roles.reviewer` | `roles.default` | Assignment both `standards-reviewer` and `spec-reviewer` inherit. |
+| `roles.triager`, `preflight`, `implementer`, `resolution-verifier`, `decomposer` | `roles.default` | Per-role assignment. |
+| `roles.standards-reviewer`, `roles.spec-reviewer` | `roles.reviewer`, else `roles.default` | Per-role assignment. |
+| `roles.fixer` | the resolved `implementer` | Per-role assignment. |
+
+The sessions map onto the roles as follows: AFK triage is the `triager`; the
+pre-flight session and hand-off confirmation are the `preflight`;
+implementation is the `implementer` (it also writes the commit message);
+repair sessions are the `fixer`; the review gate runs the `standards-reviewer`
+and the `spec-reviewer`; issue-resolution checks are the `resolution-verifier`;
+and decomposition is the `decomposer`.
+
+Startup checks each assigned harness (the `triager` only when
+`triage.enabled` is true) by running its `--version`. A harness older than the
+minimum below stops the run with an error naming the harness and the version it
+needs. Output that contains no readable version only produces a warning.
+
+| Harness | Minimum version |
+| --- | --- |
+| Claude Code (`claude`) | 2.1.289 |
+| Codex (`codex`) | 0.160.0 |
+| OpenCode (`opencode`) | 2.0.22 |
+| pi (`pi`) | 1.0.2 |
+
+Only the editing roles (`implementer`, `fixer`) may edit the checkout; the
+others run read-only. How the editing roles are approved is described under
+[Approval modes](safety.md#approval-modes), and each session's time limit is
+under `limits.sessionTimeoutMinutes`. `pi` and `opencode` editing roles need
+`approval: yolo`.
+
+### `intake`
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `intake.requireLabels` | `[]` | An issue must carry every listed label to enter the queue (AND filter). Added to the mandatory `labels.ready-for-agent` label. Children created by decomposition inherit the parent's labels listed here, plus the agent-ready label (see [Decomposition](workflows.md#decomposition-workflow)). |
+| `intake.sort` | `created:asc` | Queue order: `created`, `updated`, or `comments`, optionally suffixed `:asc` or `:desc`. Without a suffix the order is ascending. |
+
+### `triage`
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `triage.enabled` | `false` | Run AFK triage before the queue. See [AFK triage](workflows.md#afk-triage). |
+
+### `labels`
+
+Maps Matt Pocock's five canonical triage roles to the label names used in the
+tracker. Each value is a non-empty label name and defaults to the role's own
+name. Two roles may not share one label (compared case-insensitively).
+
+| Key | Default |
+| --- | --- |
+| `labels.needs-triage` | `needs-triage` |
+| `labels.needs-info` | `needs-info` |
+| `labels.ready-for-agent` | `ready-for-agent` |
+| `labels.ready-for-human` | `ready-for-human` |
+| `labels.wontfix` | `wontfix` |
+
+### `skills`
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `skills.dir` | the skills bundled with Ralphie | Directory whose subdirectories are skills (each holds a `SKILL.md`). Relative paths resolve against the current directory. |
+
+Before each session Ralphie copies these skills into the harness's project
+skills directory (`.claude/skills`, `.agents/skills` for Codex, `.pi/skills`,
+`.opencode/skills`). A repository skill with the same name is set aside for the
+session and restored afterwards, so Ralphie's copy wins while other repository
+skills stay available. Everything injected is added to the checkout's
+`.git/info/exclude`, and is removed again when the session ends. Sessions that
+overlap in one working directory (the parallel reviewers) share one injection:
+the first prepares the checkout, and the last to finish restores it. If the
+repository has no `docs/agents/issue-tracker.md` or
+`docs/agents/triage-labels.md`, Ralphie generates them for the session: the
+label table comes from `labels`, and the tracker doc says issue content is in
+the prompt and sessions must not use `gh`. Committed versions always win.
+
+### `limits`
+
+All limits are positive; counts are integers.
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `limits.implementationAttempts` | `3` | Implementation attempts allowed when sessions leave an unresolved empty diff or an implementer session times out. After the last attempt the issue is handed off `ready-for-human`. |
+| `limits.reviewRounds` | `5` | Review rounds before the issue escalates to decomposition. At most `20`. |
+| `limits.verificationFixes` | `5` | Repair attempts allowed after a failing `verify` command. |
+| `limits.sessionTimeoutMinutes.edit` | `60` | Wall-clock limit of one session in an editing role. Exceeding it kills the session's process group and counts as a failed attempt. |
+| `limits.sessionTimeoutMinutes.readOnly` | `15` | The same limit for read-only roles. |
+| `limits.maxBudgetUsd` | none | Spend cap in US dollars for each session. Only Claude Code enforces it; Codex, pi and OpenCode ignore it, and startup warns for every assigned harness that cannot. |
+| `limits.maxDecompositionDepth` | `3` | Maximum generated-child lineage depth. Reaching it hands the issue off as `ready-for-human` and continues independent work. |
+
+### Repository entries
+
+Each `repos."owner/repo"` entry accepts `workspace`, `approval`, `harnesses`, `roles`,
+`intake`, `triage`, `labels`, `skills`, and `limits` (overriding the top level for that repository
+only) plus two keys that exist only here:
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `branch` | `main`, otherwise `master` | Base branch that verified work is pushed to directly. |
+| `verify` | `[]` | Deterministic gate commands run in order after changes are staged, each under a 30-minute deadline. When empty, the gate is skipped and review proceeds on the staged diff alone. |
+
+## Removed flags
+
+Each former flag now fails with an error naming its replacement.
+
+| Former flag | Config key |
+| --- | --- |
+| `-b`, `--branch` | `repos."owner/repo".branch` |
+| `--verify-command` | `repos."owner/repo".verify` |
+| `--issue-label` | `intake.requireLabels` |
+| `--issue-sort` | `intake.sort` |
+| `--implementation-attempts` | `limits.implementationAttempts` |
+| `--max-decomposition-depth` | `limits.maxDecompositionDepth` |
+| `--workspace` | `workspace` |
+| `--model` | `harnesses.<harness>.model` or `roles.<role>.model` |
+| `--thinking` | `harnesses.<harness>.effort` or `roles.<role>.effort` |
+| `--notify-needs-attention` | none: hand-offs are always on |
+| `--needs-attention-label` | `labels.ready-for-human` |