ralph-lisa-loop 0.3.0

package/README.md

@@ -0,0 +1,234 @@
+# Ralph-Lisa Loop
+
+<p align="center">
+  <img src="../rll_cat.png" alt="Ralph-Lisa Loop" width="256" />
+</p>
+
+Turn-based dual-agent collaboration: Ralph codes, Lisa reviews, consensus required.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/ralph-lisa-loop.svg)](https://www.npmjs.com/package/ralph-lisa-loop)
+
+## The Problem
+
+Single-agent coding is like grading your own exam. The same model writes code AND decides if it's done. No external validation. No second opinion.
+
+## The Solution
+
+**Ralph-Lisa Loop** enforces a strict turn-based workflow:
+
+```
+Ralph writes → Lisa reviews → Consensus → Next step
+     ↑                                        |
+     └────────────────────────────────────────┘
+```
+
+- **Ralph** (Claude Code): Lead developer - researches, plans, codes, tests
+- **Lisa** (Codex): Code reviewer - reviews, provides feedback
+- **Turn Control**: Only one agent works at a time
+- **Consensus Required**: Both must agree before proceeding
+- **Research First**: When involving reference implementations/protocols/APIs, Ralph must submit [RESEARCH] before coding
+- **Test Results Required**: [CODE] and [FIX] submissions must include test results
+- **Policy Layer**: Configurable warn/block mode for submission quality checks
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm i -g ralph-lisa
+```
+
+### 2. Initialize Project
+
+```bash
+cd your-project
+ralph-lisa init
+```
+
+### 3. Start Collaboration
+
+```bash
+# Manual mode (recommended)
+ralph-lisa start "implement login feature"
+
+# Or auto mode (experimental, requires tmux)
+ralph-lisa auto "implement login feature"
+```
+
+### 4. Work Flow
+
+**Terminal 1 - Ralph (Claude Code)**:
+```bash
+ralph-lisa whose-turn                    # Check turn
+# ... do work ...
+ralph-lisa submit-ralph "[PLAN] Login feature design
+
+1. Create login form component
+2. Add validation
+3. Connect to API"
+```
+
+**Terminal 2 - Lisa (Codex)**:
+```bash
+ralph-lisa whose-turn                    # Check turn
+ralph-lisa read work.md                  # Read Ralph's work
+ralph-lisa submit-lisa "[PASS] Plan looks good
+
+- Clear structure
+- Good separation of concerns"
+```
+
+## Features
+
+### Turn Control
+Agents must check `whose-turn` before any action. Submissions automatically pass the turn.
+
+### Tag System
+Every submission requires a tag:
+
+| Ralph Tags | Lisa Tags | Shared |
+|------------|-----------|--------|
+| `[PLAN]` | `[PASS]` | `[CHALLENGE]` |
+| `[RESEARCH]` | `[NEEDS_WORK]` | `[DISCUSS]` |
+| `[CODE]` | | `[QUESTION]` |
+| `[FIX]` | | `[CONSENSUS]` |
+
+- `[RESEARCH]`: Submit research results before coding (when involving reference implementations, protocols, or external APIs)
+- `[CHALLENGE]`: Explicitly disagree with the other agent's suggestion, providing counter-argument
+- `[CODE]`/`[FIX]`: Must include Test Results section
+
+### Consensus Protocol
+Lisa's verdict is advisory. Ralph can agree or use `[CHALLENGE]` to disagree. Both must reach genuine consensus before `/next-step`. Silent acceptance (bare `[FIX]` without reasoning) is not allowed.
+
+### Minimal Init (Zero Intrusion)
+
+When using the Claude Code plugin + Codex global config, you don't need project-level role files:
+
+```bash
+ralph-lisa init --minimal
+```
+
+This only creates `.dual-agent/` session state. No CLAUDE.md, CODEX.md, or command files are written. Requires:
+- Claude Code plugin installed (provides Ralph role via hooks)
+- Codex global config at `~/.codex/` (provides Lisa role)
+
+`start` and `auto` commands work with both full and minimal init.
+
+### Policy Layer
+
+**Inline checks** (during `submit-ralph`/`submit-lisa`):
+
+```bash
+# Enable warn mode (prints warnings, doesn't block)
+export RL_POLICY_MODE=warn
+
+# Enable block mode (rejects non-compliant submissions)
+export RL_POLICY_MODE=block
+
+# Disable (default)
+export RL_POLICY_MODE=off
+```
+
+**Standalone checks** (for scripts/hooks — always exit non-zero on violations, ignoring `RL_POLICY_MODE`):
+
+```bash
+ralph-lisa policy check ralph           # Check Ralph's latest submission
+ralph-lisa policy check lisa            # Check Lisa's latest submission
+ralph-lisa policy check-consensus       # Both agents submitted [CONSENSUS]?
+ralph-lisa policy check-next-step       # Comprehensive: consensus + all policy checks
+```
+
+Policy rules:
+- Ralph's [CODE]/[FIX] must include "Test Results" section
+- Ralph's [RESEARCH] must have substantive content
+- Lisa's [PASS]/[NEEDS_WORK] must include at least 1 reason
+
+### Deadlock Escape
+After 5 rounds without consensus: `[OVERRIDE]` (proceed anyway) or `[HANDOFF]` (escalate to human).
+
+## Commands
+
+```bash
+# Project setup
+ralph-lisa init [dir]                    # Initialize project (full)
+ralph-lisa init --minimal [dir]          # Minimal init (session only, no project files)
+ralph-lisa uninit                        # Remove from project
+ralph-lisa start "task"                  # Launch both agents
+ralph-lisa start --full-auto "task"      # Launch without permission prompts
+ralph-lisa auto "task"                   # Auto mode (tmux)
+ralph-lisa auto --full-auto "task"       # Auto mode without permission prompts
+
+# Turn control
+ralph-lisa whose-turn                    # Check whose turn
+ralph-lisa submit-ralph "[TAG] ..."      # Ralph submits
+ralph-lisa submit-lisa "[TAG] ..."       # Lisa submits
+
+# Information
+ralph-lisa status                        # Current status
+ralph-lisa read work.md                  # Ralph's latest
+ralph-lisa read review.md                # Lisa's latest
+ralph-lisa history                       # Full history
+
+# Flow control
+ralph-lisa step "phase-name"             # Enter new phase
+ralph-lisa archive [name]                # Archive session
+ralph-lisa clean                         # Clean session
+
+# Policy
+ralph-lisa policy check <ralph|lisa>     # Check submission (hard gate)
+ralph-lisa policy check-consensus        # Check if both [CONSENSUS]
+ralph-lisa policy check-next-step        # Comprehensive pre-step check
+
+# Diagnostics
+ralph-lisa doctor                        # Check all dependencies
+ralph-lisa doctor --strict               # Exit 1 if any missing (for CI)
+```
+
+## Project Structure After Init
+
+**Full init** (`ralph-lisa init`):
+```
+your-project/
+├── CLAUDE.md              # Ralph's role (auto-loaded by Claude Code)
+├── CODEX.md               # Lisa's role (loaded via .codex/config.toml)
+├── .claude/
+│   └── commands/          # Claude slash commands
+├── .codex/
+│   ├── config.toml        # Codex configuration
+│   └── skills/            # Codex skills
+└── .dual-agent/           # Session state
+    ├── turn.txt           # Current turn
+    ├── work.md            # Ralph's submissions
+    ├── review.md          # Lisa's submissions
+    └── history.md         # Full history
+```
+
+**Minimal init** (`ralph-lisa init --minimal`):
+```
+your-project/
+└── .dual-agent/           # Session state only (zero project files)
+```
+
+## Requirements
+
+- [Node.js](https://nodejs.org/) >= 18
+- [Claude Code](https://claude.ai/code) - for Ralph
+- [Codex CLI](https://github.com/openai/codex) - for Lisa
+
+For auto mode:
+- tmux (required)
+- fswatch (macOS) or inotify-tools (Linux) — optional, speeds up turn detection; falls back to polling without them
+
+## Ecosystem
+
+Part of the [TigerHill](https://github.com/Click-Intelligence-LLC/TigerHill) project family.
+
+## See Also
+
+- [CONCEPT.md](CONCEPT.md) - Why dual-agent collaboration works
+- [UPGRADE_PLAN_V3.md](UPGRADE_PLAN_V3.md) - V3 design document
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * ralph-lisa CLI - Turn-based dual-agent collaboration.
+ * Replaces io.sh with Node/TS implementation.
+ *
+ * Usage: ralph-lisa <command> [args...]
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * ralph-lisa CLI - Turn-based dual-agent collaboration.
+ * Replaces io.sh with Node/TS implementation.
+ *
+ * Usage: ralph-lisa <command> [args...]
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const commands_js_1 = require("./commands.js");
+const args = process.argv.slice(2);
+const cmd = args[0] || "";
+const rest = args.slice(1);
+switch (cmd) {
+    case "init":
+        // If first arg after init looks like a path, use cmdInitProject
+        // If it looks like a task description, also use cmdInitProject (with no path)
+        (0, commands_js_1.cmdInitProject)(rest);
+        break;
+    case "uninit":
+        (0, commands_js_1.cmdUninit)();
+        break;
+    case "whose-turn":
+        (0, commands_js_1.cmdWhoseTurn)();
+        break;
+    case "submit-ralph":
+        (0, commands_js_1.cmdSubmitRalph)(rest);
+        break;
+    case "submit-lisa":
+        (0, commands_js_1.cmdSubmitLisa)(rest);
+        break;
+    case "status":
+        (0, commands_js_1.cmdStatus)();
+        break;
+    case "read":
+        (0, commands_js_1.cmdRead)(rest);
+        break;
+    case "recap":
+        (0, commands_js_1.cmdRecap)();
+        break;
+    case "step":
+        (0, commands_js_1.cmdStep)(rest);
+        break;
+    case "history":
+        (0, commands_js_1.cmdHistory)();
+        break;
+    case "archive":
+        (0, commands_js_1.cmdArchive)(rest);
+        break;
+    case "clean":
+        (0, commands_js_1.cmdClean)();
+        break;
+    case "start":
+        (0, commands_js_1.cmdStart)(rest);
+        break;
+    case "auto":
+        (0, commands_js_1.cmdAuto)(rest);
+        break;
+    case "policy":
+        (0, commands_js_1.cmdPolicy)(rest);
+        break;
+    case "doctor":
+        (0, commands_js_1.cmdDoctor)(rest);
+        break;
+    case "logs":
+        (0, commands_js_1.cmdLogs)(rest);
+        break;
+    case "help":
+    case "--help":
+    case "-h":
+    case "":
+        showHelp();
+        break;
+    case "--version":
+    case "-v":
+        showVersion();
+        break;
+    default:
+        console.error(`Unknown command: ${cmd}`);
+        console.error('Run "ralph-lisa --help" for usage.');
+        process.exit(1);
+}
+function showHelp() {
+    console.log("Ralph Lisa Dual-Agent Loop - CLI");
+    console.log("");
+    console.log("Project Setup:");
+    console.log("  ralph-lisa init [dir]              Initialize project");
+    console.log("  ralph-lisa init --minimal [dir]    Minimal init (session only, no project files)");
+    console.log("  ralph-lisa uninit                  Remove from project");
+    console.log('  ralph-lisa start "task"             Launch both agents');
+    console.log('  ralph-lisa start --full-auto "task" Launch without permission prompts');
+    console.log('  ralph-lisa auto "task"              Auto mode (tmux)');
+    console.log('  ralph-lisa auto --full-auto "task"  Auto mode without permission prompts');
+    console.log("");
+    console.log("Turn Control:");
+    console.log("  ralph-lisa whose-turn               Check whose turn");
+    console.log('  ralph-lisa submit-ralph "[TAG]..."   Ralph submits');
+    console.log("  ralph-lisa submit-ralph --file <f>   Ralph submits from file");
+    console.log('  ralph-lisa submit-lisa "[TAG]..."    Lisa submits');
+    console.log("  ralph-lisa submit-lisa --file <f>    Lisa submits from file");
+    console.log("");
+    console.log("Tags:");
+    console.log("  Ralph: [PLAN] [RESEARCH] [CODE] [FIX] [CHALLENGE] [DISCUSS] [QUESTION] [CONSENSUS]");
+    console.log("  Lisa:  [PASS] [NEEDS_WORK] [CHALLENGE] [DISCUSS] [QUESTION] [CONSENSUS]");
+    console.log("");
+    console.log("Information:");
+    console.log("  ralph-lisa status                   Show current status");
+    console.log("  ralph-lisa read <file>              Read work.md/review.md");
+    console.log("  ralph-lisa recap                    Context recovery summary");
+    console.log("  ralph-lisa history                  Show full history");
+    console.log("");
+    console.log("Flow Control:");
+    console.log('  ralph-lisa step "name"              Enter new step');
+    console.log("  ralph-lisa archive [name]           Archive session");
+    console.log("  ralph-lisa clean                    Clean session");
+    console.log("");
+    console.log("Policy:");
+    console.log("  ralph-lisa policy check <ralph|lisa> Check submission (hard gate)");
+    console.log("  ralph-lisa policy check-consensus   Check if both [CONSENSUS]");
+    console.log("  ralph-lisa policy check-next-step   Comprehensive pre-step check");
+    console.log("");
+    console.log("  Standalone policy check always exits non-zero on violations.");
+    console.log("  RL_POLICY_MODE (warn|block|off) affects inline submit checks (default: warn).");
+    console.log("");
+    console.log("Logs:");
+    console.log("  ralph-lisa logs                     List all transcript logs");
+    console.log("  ralph-lisa logs cat                  View live pane logs");
+    console.log("  ralph-lisa logs cat <file>            View specific log file");
+    console.log("");
+    console.log("Diagnostics:");
+    console.log("  ralph-lisa doctor                   Check all dependencies");
+    console.log("  ralph-lisa doctor --strict           Exit 1 if any missing (for CI)");
+}
+function showVersion() {
+    try {
+        const pkg = require("../package.json");
+        console.log(`ralph-lisa-loop v${pkg.version}`);
+    }
+    catch {
+        console.log("ralph-lisa-loop v0.3.0");
+    }
+}

package/dist/commands.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CLI commands for Ralph-Lisa Loop.
+ * Direct port of io.sh logic to Node/TS.
+ */
+export declare function cmdInit(args: string[]): void;
+export declare function cmdWhoseTurn(): void;
+export declare function cmdSubmitRalph(args: string[]): void;
+export declare function cmdSubmitLisa(args: string[]): void;
+export declare function cmdStatus(): void;
+export declare function cmdRead(args: string[]): void;
+export declare function cmdRecap(): void;
+export declare function cmdStep(args: string[]): void;
+export declare function cmdHistory(): void;
+export declare function cmdArchive(args: string[]): void;
+export declare function cmdClean(): void;
+export declare function cmdUninit(): void;
+export declare function cmdInitProject(args: string[]): void;
+export declare function cmdStart(args: string[]): void;
+export declare function cmdAuto(args: string[]): void;
+export declare function cmdPolicy(args: string[]): void;
+export declare function cmdLogs(args: string[]): void;
+export declare function cmdDoctor(args: string[]): void;