Metadata-Version: 2.4
Name: ralphception
Version: 0.2.0
Summary: Codex-native orchestration runtime.
Requires-Python: >=3.12
Requires-Dist: pydantic<3,>=2
Requires-Dist: textual<1.0,>=0.61
Requires-Dist: typer<1.0,>=0.12
Description-Content-Type: text/markdown

# Ralphception

`ralphception` is a Codex-shaped orchestrator for long-running Ralph-loop work:

- one durable task/session per target repo
- Socratic intake that turns a starting prompt into durable artifacts
- explicit PRD, plan, loop-plan, and todo artifacts before execution
- child runs in worktrees for loop execution, verification, merge, and audit
- reopen and continue until the task is explicitly complete or explicitly blocked

The runtime is durable and repo-local. The product surface is now simple:

- `uv run ralphception` launches the inline interactive shell
- `uv run ralphception exec "..."` runs non-interactively
- `uv run ralphception e "..."` is the short alias

## Quick Start

```bash
mise run install
mise run run
```

Equivalent `uv` commands:

```bash
uv sync
uv run ralphception
uv run ralphception exec "port parser"
```

Once the package is published, the intended entry points are:

```bash
uvx ralphception
uvx ralphception exec "port parser"
```

## Interactive Shell

`uv run ralphception` opens the default inline shell in the current repo.

The primary transcript lives in normal terminal scrollback, not inside a boxed full-screen viewport. Ralphception writes durable milestones and loop progress directly into the terminal so you can rely on normal scrollback while work runs.

The default lifecycle is artifact-first:

1. Socratic intake
2. durable intake summary / PRD / plan / todos
3. explicit Ralph-loop planning
4. loop execution in child worktrees
5. consolidation, merge, audit, and reopen if needed

The shell drives the same durable runtime used everywhere else. User replies, blockers, loop progress, and settled outcomes all write into the same `.ralphception/` workspace state.

## Non-Interactive Exec

`uv run ralphception exec "..."` runs the task loop without opening Textual.

Example:

```bash
uv run ralphception exec \
  "port parser" \
  --source-repo /path/to/source-repo
```

Useful flags:

- `--repo-root <path>` to operate on another workspace
- `--source-repo <path>` to attach one or more source repos
- `--approve-all` / `--no-approve-all` to control automatic approval of spec and execution-bundle gates
- `--fake-session-manager` to inject the deterministic fake backend used by the test suite

`exec` defaults to `--approve-all` because it is the non-interactive path. If you want to stop at reviews, use `--no-approve-all` and switch back to the chat shell.

Prompt input can also come from stdin:

```bash
printf '%s\n' "port parser" | uv run ralphception exec -
```

Live execution requires the `codex` CLI backend on your `PATH`. If you are only verifying the local runtime loop, use `--fake-session-manager`.

## Runtime Flow

The durable task loop is:

```mermaid
flowchart TD
    A["Initial prompt + optional source repos"] --> B["Socratic intake"]
    B --> C["Write intake summary / PRD / plan / todos"]
    C --> D["Build explicit plan graph and loop graph"]
    D --> E["Execute one or more Ralph loops in child worktrees"]
    E --> F["Verification + merge"]
    F --> G["Audit + consolidation"]
    G --> H{"Blocked or more loops needed?"}
    H -- yes --> D
    H -- no --> I["Done"]
```

## Runtime State

Ralphception writes disposable runtime state under `.ralphception/`:

```text
.ralphception/
|- approvals/
|- config.toml
|- events/
|- findings/
|- merge/
|- plans/
|- runs/
|- specs/
|- todos/
`- verification/
```

Important early files:

- `.ralphception/runs/run-root/startup.json`
  The captured seed prompt and source repos.
- `.ralphception/runs/run-root/intake.md`
  The intake artifact derived from startup.
- `.ralphception/specs/mission-spec.md`
  The current root spec artifact.
- `.ralphception/plans/mission-plan.md`
  The current root plan artifact.
- `.ralphception/events/run-root.jsonl`
  The root event log.

The directory is intentionally disposable and should not be committed.

## Continuity

Repo-local task state is backed by XDG lease state:

```text
$XDG_STATE_HOME/ralphception/<workspace-hash>/lease.json
```

The recovery layer can:

- replay durable event logs
- reconcile checkpoints
- refuse healthy foreign leases
- steal stale leases in repair mode
- retry, restart, resume, or replace blocked runs

## Development Commands

```bash
mise run install
mise run run
mise run test
mise run typecheck
```

Equivalent:

```bash
uv sync
uv run ralphception
uv run pytest -v
uv run ty check src tests
```

## Codebase Map

If you want to understand the implementation, start here:

- `src/ralphception/app.py`
  Product entry points for the inline shell and exec mode.
- `src/ralphception/cli.py`
  Public CLI surface.
- `src/ralphception/runtime/inline_shell.py`
  Default scrollback-first interactive shell.
- `src/ralphception/runtime/supervisor.py`
  Shared runtime mode resolution and artifact-first orchestration entry points.
- `src/ralphception/runtime/bootstrap.py`
  Durable startup capture and intake artifact creation.
- `src/ralphception/headless.py`
  Long-running headless orchestrator.
- `src/ralphception/workflow/engine.py`
  Core run, stage, and bundle orchestration.
- `src/ralphception/workflow/recovery.py`
  Lease reconciliation and resume operations.
- `src/ralphception/git/worktrees.py`
  Worktree lifecycle.
- `src/ralphception/git/merge.py`
  Merge coordination.
- `src/ralphception/audit/service.py`
  Audit findings and reopen behavior.

## Mental Model For Porting

When using Ralphception for a port:

1. run it in the destination repo
2. point it at one or more source repos on disk
3. reduce source behavior into approved specs
4. turn approved specs into plans and execution bundles
5. execute child runs against the destination repo
6. verify, merge, audit, and reopen until blocking gaps are gone

The source repo is input, not where Ralphception writes its state.
