ralph-research 0.1.4 → 0.1.6

package/README.md

@@ -1,6 +1,7 @@
 # ralph-research
 
 [![CI](https://github.com/coyaSONG/ralph-research/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/coyaSONG/ralph-research/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/ralph-research?logo=npm&color=cb3837)](https://www.npmjs.com/package/ralph-research)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js&logoColor=white)](package.json)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6?logo=typescript&logoColor=white)](tsconfig.json)
@@ -15,6 +16,22 @@ Local-first runtime for recursive research improvement over real artifacts.
 4. persist the run, decision, and frontier state
 5. promote only verified improvements
 
+```mermaid
+flowchart LR
+    M[Manifest<br/>ralph.yaml] --> P[Proposer]
+    P -->|candidate change<br/>in worktree| E[Experiment]
+    E -->|outputs| X[Metric extractor]
+    X --> R{Ratchet}
+    R -->|wins frontier| A[Accept → main]
+    R -->|else| J[Reject]
+    A -.->|persists| S[(.ralph/<br/>runs · decisions · frontier)]
+    J -.->|persists| S
+```
+
+If your viewer does not render Mermaid: the diagram is just the five
+numbered steps above, with every transition writing to durable state under
+`.ralph/`. That's the bit that makes the loop resumable.
+
 The current product bar is reliability, not breadth. The bundled success path is the `writing` template, while the runtime itself is manifest-driven and reusable for other local workflows.
 
 ## Trust Signals
@@ -44,8 +61,8 @@ The current product bar is reliability, not breadth. The bundled success path is
 | If you want to... | Use |
 | --- | --- |
 | Check whether a repo is runnable | `rrx validate` then `rrx doctor` |
-| Materialize the bundled example project | `rrx init --template writing` |
-| Run a disposable end-to-end demo | `rrx demo writing` |
+| Materialize the bundled example project | `rrx init --template writing` (or `--template code`) |
+| Run a disposable end-to-end demo | `rrx demo writing` (or `rrx demo code`) |
 | Launch the v1 goal-driven orchestrator | `rrx "improve the holdout top-3 model"` |
 | Launch the v1 goal-driven orchestrator explicitly | `rrx launch "improve the holdout top-3 model"` |
 | Resume a persisted TUI research session | `rrx resume latest` |
@@ -103,7 +120,7 @@ See [docs/operation-model.md](docs/operation-model.md) for the full lifecycle an
 
 ## Current Scope
 
-- Bundled template: `writing`
+- Bundled templates: `writing` (prose ratchet) and `code` (test-pass ratchet over a tiny calculator module)
 - Default template metric: local command metric, no API key required
 - Optional judge path: pairwise LLM judge packs
 - MCP tools:
@@ -113,9 +130,11 @@ See [docs/operation-model.md](docs/operation-model.md) for the full lifecycle an
 
 The runtime supports broader manifests than the bundled template demonstrates, but the shipped onboarding path is intentionally narrow until those flows are equally reliable.
 
-## Writing Template
+## Bundled Templates
 
-The bundled writing template is self-contained:
+### Writing template
+
+Self-contained prose improvement loop:
 
 - `docs/draft.md`: sample draft
 - `scripts/propose.mjs`: bounded rewrite
@@ -125,6 +144,18 @@ The bundled writing template is self-contained:
 
 `templates/writing/ralph.yaml` uses a local command metric by default, so the first run works without model credentials.
 
+### Code template
+
+Self-contained test-pass ratchet over a tiny calculator module:
+
+- `src/calculator.mjs`: deliberately-broken `sum`/`multiply`
+- `tests/calculator.test.mjs`: four assertions using the built-in `node:test` runner
+- `scripts/propose.mjs`: writes the fixed calculator implementation
+- `scripts/experiment.mjs`: runs `node --test --test-reporter=tap` and persists the pass/fail counts
+- `scripts/metric.mjs`: emits the pass count as the `tests_passed` metric
+
+`rrx demo code` materializes the template, runs one cycle, and shows the ratchet promoting the candidate from `tests_passed: 0` to `tests_passed: 4`.
+
 ## Progressive Runs
 
 `rrx run` executes one cycle by default and auto-resumes the latest recoverable run when one exists.
@@ -144,6 +175,7 @@ npx ralph-research run --until-target --until-no-improve 3 --json
 
 ## More Docs
 
+- [docs/quickstart.md](docs/quickstart.md): five-minute walkthrough from `npx ralph-research demo writing` to inspecting the persisted decision evidence
 - [docs/operation-model.md](docs/operation-model.md): lifecycle, persisted state, recovery classes
 - [docs/playbook.md](docs/playbook.md): situation-to-command operator guide
 - [docs/examples.md](docs/examples.md): quickstart and manifest examples pulled from shipped templates and fixtures
@@ -193,6 +225,15 @@ npm run typecheck
 npm run build
 ```
 
+## Support the Project
+
+If `ralph-research` saves you from wiring up your own write-evaluate-accept loop:
+
+- Star the repo on [GitHub](https://github.com/coyaSONG/ralph-research). It is the single clearest signal that the runtime is worth maintaining and helps surface it to other people who need the same shape of tool.
+- File issues with concrete reproductions. The issue templates ask for the version, OS, and exact commands so they convert quickly into fixes.
+- Open a PR for the gaps you actually hit. `CONTRIBUTING.md` covers the local loop; the bar is a Vitest regression that fails against the previous code.
+- If you want to talk shape and direction rather than file an issue, the manifest schema (`src/core/manifest/schema.ts`) and the recovery classifier (`src/core/state/research-session-recovery-classifier.ts`) are the two surfaces I most want feedback on.
+
 ## License
 
 MIT

package/dist/cli/commands/demo.d.ts

@@ -5,5 +5,7 @@ export interface DemoCommandOptions {
     force?: boolean;
     json?: boolean;
 }
+export declare const SUPPORTED_DEMO_TEMPLATES: readonly ["writing", "code"];
+export type SupportedDemoTemplate = (typeof SUPPORTED_DEMO_TEMPLATES)[number];
 export declare function runDemoCommand(template: string, options: DemoCommandOptions, io?: CommandIO): Promise<number>;
 export declare function registerDemoCommand(program: Command): void;

package/dist/cli/commands/demo.js

@@ -6,6 +6,7 @@ import { inspectRun } from "../../app/services/project-state-service.js";
 import { RunCycleService } from "../../app/services/run-cycle-service.js";
 import { DEFAULT_MANIFEST_FILENAME } from "../../core/manifest/schema.js";
 import { copyTemplate } from "../../shared/template-utils.js";
+export const SUPPORTED_DEMO_TEMPLATES = ["writing", "code"];
 const defaultCommandIO = {
     stdout: (message) => {
         process.stdout.write(`${message}\n`);
@@ -15,8 +16,8 @@ const defaultCommandIO = {
     },
 };
 export async function runDemoCommand(template, options, io = defaultCommandIO) {
-    if (template !== "writing") {
-        const message = `Unsupported demo template ${template}; only writing is available in v0.1`;
+    if (!SUPPORTED_DEMO_TEMPLATES.includes(template)) {
+        const message = `Unsupported demo template ${template}; supported templates: ${SUPPORTED_DEMO_TEMPLATES.join(", ")}`;
         if (options.json) {
             io.stderr(JSON.stringify({ ok: false, error: message }, null, 2));
         }
@@ -28,7 +29,7 @@ export async function runDemoCommand(template, options, io = defaultCommandIO) {
     try {
         const targetDir = options.path
             ? resolve(options.path)
-            : await mkdtemp(join(tmpdir(), "rrx-demo-writing-"));
+            : await mkdtemp(join(tmpdir(), `rrx-demo-${template}-`));
         if (options.force) {
             await rm(targetDir, { recursive: true, force: true });
         }
@@ -87,7 +88,7 @@ export function registerDemoCommand(program) {
     program
         .command("demo")
         .description("Create and run a zero-config demo.")
-        .argument("<template>", "Demo template name")
+        .argument("<template>", `Demo template name (one of: ${SUPPORTED_DEMO_TEMPLATES.join(", ")})`)
         .option("-p, --path <path>", "Destination directory")
         .option("--force", "Replace the destination directory if it already exists", false)
         .option("--json", "Emit machine-readable output", false)

package/dist/cli/commands/demo.js.map

@@ -1 +1 @@
-{"version":3,"file":"demo.js","sourceRoot":"","sources":["../../../src/cli/commands/demo.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"demo.js","sourceRoot":"","sources":["../../../src/cli/commands/demo.ts"],"names":[],"mappings":"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"}

package/dist/cli/program.js

@@ -18,7 +18,7 @@ export function createProgram(dependencies = {}) {
     program
         .name("rrx")
         .description("Local-first runtime for recursive research improvement.")
-        .version("0.1.4")
+        .version("0.1.6")
         .argument("[goal]", "Goal to pursue through the v1 TUI research orchestrator")
         .action(async (goal) => {
         if (goal === undefined) {

package/dist/mcp/server.js

@@ -14,7 +14,7 @@ export function createRalphResearchMcpServer(options = {}) {
         (() => new ResearchSessionRecoveryService());
     const server = new McpServer({
         name: "ralph-research",
-        version: "0.1.4",
+        version: "0.1.6",
     });
     server.registerTool("run_research_cycle", {
         description: "Run one or more research cycles using the shared ralph-research service layer.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-research",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Local-first runtime for recursive research improvement.",
   "type": "module",
   "bin": {
@@ -24,9 +24,27 @@
     "research",
     "ratchet",
     "cli",
-    "mcp"
+    "mcp",
+    "agent",
+    "llm",
+    "local-first",
+    "typescript",
+    "nodejs",
+    "codex"
   ],
   "license": "MIT",
+  "author": "coyaSONG",
+  "homepage": "https://github.com/coyaSONG/ralph-research#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coyaSONG/ralph-research.git"
+  },
+  "bugs": {
+    "url": "https://github.com/coyaSONG/ralph-research/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.4",
     "commander": "^14.0.1",

package/templates/code/README.md

@@ -0,0 +1,42 @@
+# Code template
+
+A self-contained `ralph-research` template that drives a test-pass ratchet
+over a tiny JavaScript calculator module. Uses only Node's built-in
+`node:test` runner, so the first cycle runs with no external toolchain.
+
+## What ships in this template
+
+- `src/calculator.mjs` — exports `sum` and `multiply` with deliberate bugs
+- `tests/calculator.test.mjs` — four assertions covering both functions
+- `scripts/propose.mjs` — overwrites `src/calculator.mjs` with the fixed
+  implementation
+- `scripts/experiment.mjs` — runs `node --test --test-reporter=tap` against
+  the test file and parses the TAP summary into `out/test-results.json`
+- `scripts/metric.mjs` — reads `out/test-results.json` and prints the
+  pass count as the `tests_passed` metric
+- `ralph.yaml` — wires the above into a `single_best` frontier with an
+  `epsilon_improve` ratchet
+
+## Running this template
+
+From the directory that contains `ralph.yaml`:
+
+```bash
+rrx validate
+rrx doctor
+rrx run --json
+rrx inspect run-0001 --json
+```
+
+On a fresh checkout the cycle promotes `tests_passed` from `0` to `4` and
+the ratchet accepts. Subsequent cycles run against the already-fixed
+calculator and are rejected because the candidate cannot improve on the
+incumbent.
+
+To extend the template into a real research loop, replace the proposer with
+a real candidate generator (for example, a small LLM call that rewrites
+`src/calculator.mjs` to add a new function) and broaden the test suite so
+the ratchet has something meaningful to compare on each cycle.
+
+See [`docs/operation-model.md`](../../docs/operation-model.md) for the
+runtime contract every manifest must honor.

package/templates/code/ralph.yaml

@@ -0,0 +1,57 @@
+schemaVersion: "0.1"
+
+project:
+  name: code-demo
+  artifact: code
+  baselineRef: main
+  workspace: git
+
+scope:
+  allowedGlobs:
+    - "src/**"
+    - "tests/**"
+    - "out/**"
+  maxFilesChanged: 2
+  maxLineDelta: 40
+
+proposer:
+  type: command
+  command: "node scripts/propose.mjs"
+
+experiment:
+  run:
+    command: "node scripts/experiment.mjs"
+  outputs:
+    - id: test-results
+      path: out/test-results.json
+
+metrics:
+  catalog:
+    - id: tests_passed
+      kind: numeric
+      direction: maximize
+      extractor:
+        type: command
+        command: "node scripts/metric.mjs"
+        parser: plain_number
+
+constraints: []
+
+frontier:
+  strategy: single_best
+  primaryMetric: tests_passed
+
+ratchet:
+  type: epsilon_improve
+  metric: tests_passed
+  epsilon: 0
+
+# Optional progressive-stop contract:
+# stopping:
+#   target:
+#     metric: tests_passed
+#     op: ">="
+#     value: 4
+
+storage:
+  root: .ralph

package/templates/code/scripts/experiment.mjs

@@ -0,0 +1,29 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+mkdirSync(join(process.cwd(), "out"), { recursive: true });
+
+const result = spawnSync(
+  process.execPath,
+  ["--test", "--test-reporter=tap", "tests/calculator.test.mjs"],
+  {
+    cwd: process.cwd(),
+    encoding: "utf8",
+  },
+);
+
+const combined = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+const passMatch = combined.match(/# pass (\d+)/);
+const failMatch = combined.match(/# fail (\d+)/);
+
+const passed = passMatch ? Number(passMatch[1]) : 0;
+const failed = failMatch ? Number(failMatch[1]) : 0;
+
+writeFileSync(
+  join(process.cwd(), "out", "test-results.json"),
+  `${JSON.stringify({ passed, failed }, null, 2)}\n`,
+  "utf8",
+);
+
+console.log("experiment complete");

package/templates/code/scripts/metric.mjs

@@ -0,0 +1,8 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const results = JSON.parse(
+  readFileSync(join(process.cwd(), "out", "test-results.json"), "utf8"),
+);
+
+console.log(Number(results.passed ?? 0));

package/templates/code/scripts/propose.mjs

@@ -0,0 +1,14 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const fixedCalculator = `export function sum(a, b) {
+  return a + b;
+}
+
+export function multiply(a, b) {
+  return a * b;
+}
+`;
+
+writeFileSync(join(process.cwd(), "src", "calculator.mjs"), fixedCalculator, "utf8");
+console.log("proposal complete");

package/templates/code/src/calculator.mjs

@@ -0,0 +1,7 @@
+export function sum(a, b) {
+  return a;
+}
+
+export function multiply(a, b) {
+  return a;
+}

package/templates/code/tests/calculator.test.mjs

@@ -0,0 +1,20 @@
+import { test } from "node:test";
+import { strict as assert } from "node:assert";
+
+import { multiply, sum } from "../src/calculator.mjs";
+
+test("sum adds two positive integers", () => {
+  assert.equal(sum(2, 3), 5);
+});
+
+test("sum handles a zero operand", () => {
+  assert.equal(sum(0, 7), 7);
+});
+
+test("multiply multiplies two positive integers", () => {
+  assert.equal(multiply(3, 4), 12);
+});
+
+test("multiply by one is identity", () => {
+  assert.equal(multiply(1, 9), 9);
+});

package/templates/writing/README.md

@@ -0,0 +1,46 @@
+# Writing template
+
+A self-contained `ralph-research` template that demonstrates the
+write-evaluate-accept loop on a markdown draft.
+
+## What ships in this template
+
+- `docs/draft.md` — the baseline draft the runtime improves
+- `scripts/propose.mjs` — overwrites `docs/draft.md` with a bounded rewrite
+- `scripts/experiment.mjs` — copies the candidate draft into `out/draft.md`
+- `scripts/metric.mjs` — emits a numeric `quality` score from keyword presence
+  (no API key, no LLM call)
+- `prompts/judge.md` — starter prompt for an optional pairwise LLM judge
+- `ralph.yaml` — the manifest that wires the four pieces above into the
+  runtime
+
+The manifest enables `quality` as a numeric metric backed by `metric.mjs`. The
+optional `judgePacks` block is commented-out scaffolding for when you swap
+the numeric metric for an LLM judge.
+
+## Running this template
+
+From the directory that contains `ralph.yaml`:
+
+```bash
+rrx validate           # check the manifest parses
+rrx doctor             # sanity-check the working tree
+rrx run --json         # execute one cycle
+rrx inspect run-0001 --json
+```
+
+`rrx run` writes `.ralph/runs/run-0001/run.json`,
+`.ralph/runs/run-0001/decision.json`, and `.ralph/frontier.json`. Inspecting
+those three files is the fastest way to understand what the runtime
+actually persists.
+
+## Extending this template
+
+- Replace `scripts/metric.mjs` with a real quality metric you trust.
+- Uncomment the `judgePacks` block in `ralph.yaml` and point it at a real
+  judge model to compare candidates pairwise.
+- Add files to `docs/` and broaden the `scope.allowedGlobs` if you want the
+  proposer to touch more than a single draft.
+
+See [`docs/operation-model.md`](../../docs/operation-model.md) for the
+runtime contract every manifest must honor.