# References and evidence notes

Research and local verification: November 3, 2026.

## Primary-source register

| Source | Supports | Limits |
| --- | --- | --- |
| [Geoffrey Huntley, Ralph Wiggum as a “software engineer”](https://ghuntley.com/ralph/) | Technique's origin; Bash-loop framing; one task per loop; specifications and plans; operator tuning | Practitioner account. Cost and capability anecdotes do not establish general success rates or financial returns. |
| [The Ralph Playbook, ghuntley/how-to-ralph-wiggum](https://github.com/ghuntley/how-to-ralph-wiggum) | Requirements/planning/building separation; durable files; fresh context and feedback | This is a playbook forked from Clayton Farr's repository, not an independently validated benchmark or a universal protocol. Its numerical context heuristics are not treated as empirical laws. |
| [Official Claude Ralph Loop plugin](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/ralph-loop/README.md) | Stop-hook continuation inside the current session; completion phrase and iteration limit | Establishes that implementation's documented behavior. The article does not assume every Ralph implementation resets context. |
| [Pi coding-agent README](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md) | Harness identity; installation; Node requirement | Upstream main changes. No claims about adoption, performance, or security follow from it. |
| [Pi CLI reference](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/cli.md) | Print mode; session and discovery flags; stdin; tool selection | Locally installed help also checked. The reference implementation does not assume tool selection creates a sandbox. |
| [Pi CLI integration](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/cli-integration.md) | Process interface; print/JSON/RPC integration options | Only print mode is used by the runnable controller. JSON and RPC integration were not implemented or tested here. |
| [Pi SDK](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/sdk.md) | createAgentSession, in-memory session management, prompt, disposal | SDK example is a lifecycle sketch with explicitly named application placeholders. It was not compiled or executed as part of preparation. |
| [Pi SDK session example](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/examples/sdk/11-sessions.ts) | In-memory and persisted session lifecycle distinction | Shows upstream API usage, not this article's controller policy. |
| [Pi package manifest](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/package.json) | Current package identity; inspected manifest version 1.5.0 | Upstream main is a moving source reference. The pinned reproduction command was not installed or run with a live provider here. |

## Attribution boundaries

The article's state machine, deterministic first-failing-task scheduler, Python controller, slug exercise, tests, prompts, cost arithmetic, and diagrams are original instructional material. They are not presented as the creator's canonical implementation or pi's built-in Ralph feature.

The historical characterization is deliberately narrow. The original article supplies the Bash-loop starting point and operational concepts. The official plugin supplies a concrete counterexample to the assumption that every implementation resets its conversation. No unsupported claim is made that “Ralph” names one standardized algorithm.

## Verification record

- Local pi executable reported version 1.0.3. Its help confirmed print mode, no-session, no-extensions, no-skills, no-prompt-templates, no-context-files, tools, and model options used in the reference implementation.
- Help also emitted a settings-lock permission warning in this restricted environment. No credential output was requested. Help inspection did not establish provider readiness or a successful live agent run.
- All 13 offline integration tests passed. The controller integration suite uses temporary directories and fake agent subprocesses. It exercises acceptance-driven completion, false completion, restart regression checks, nonzero agent exits, timeout, configuration identity, mutation during verification, project locking, and failure-feedback delivery. See the current test file for the complete set.
- All shipped Python files are parseable with the local Python runtime. The starter remains deliberately incomplete.
- Four original SVG figures are generated by `images/build_figures.py`. PNG exports were rendered and visually inspected; no numerical or empirical result is encoded in these diagrams.
- Local Markdown links and figure targets were checked for existence.

## Evidence limits

No paid-model end-to-end session, model comparison, success-rate benchmark, throughput measurement, cost measurement, or production deployment was performed. The narrated three-attempt trace is explicitly illustrative. Token prices in the worked arithmetic are invented, not current provider pricing.

The controller is suitable for studying orchestration with cooperative local code. It is not a sandbox, production job service, exactly-once effect system, or provider spend limiter. The article identifies those boundaries next to the relevant implementation claims.

## Editorial review

The draft follows the local Pragma AI writing guide and expert-writer guidance. Its framing is a professional exploration of architectural questions, with code as evidence of design choices. Setup instructions remain in the companion README. The article retains concrete mechanisms, failure paths, source links, and evidence limits; it does not invent operational experience or model-performance results.