ralph-lisa-loop 0.3.10 → 0.3.12

package/README.md

@@ -1,268 +1,94 @@
 # Ralph-Lisa Loop
 
 <p align="center">
-  <img src="../rll_cat.png" alt="Ralph-Lisa Loop" width="256" />
+  <img src="https://raw.githubusercontent.com/YW1975/Ralph-Lisa-Loop/main/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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/YW1975/Ralph-Lisa-Loop/blob/main/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-loop
-```
-
-### 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
+## How It Works
 
-**Terminal 1 - Ralph (Claude Code)**:
-```bash
-ralph-lisa whose-turn                    # Check turn
-# ... do work, write submission to .dual-agent/submit.md ...
-ralph-lisa submit-ralph --file .dual-agent/submit.md
 ```
-
-**Terminal 2 - Lisa (Codex)**:
-```bash
-ralph-lisa whose-turn                    # Check turn
-ralph-lisa read work.md                  # Read Ralph's work
-# ... write review to .dual-agent/submit.md ...
-ralph-lisa submit-lisa --file .dual-agent/submit.md
-```
-
-## 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
-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
-
-### Mid-Session Task Update
-Change direction without restarting:
-```bash
-ralph-lisa update-task "switch to REST instead of GraphQL"
+Ralph writes → Lisa reviews → Consensus → Next step
+     ↑                                        |
+     └────────────────────────────────────────┘
 ```
-Appends to task.md (preserving history). Task context is auto-injected into work.md submissions and watcher trigger messages so both agents always see the current goal.
 
-### Round 1 Mandatory Plan
-Ralph's first submission must be `[PLAN]` — gives Lisa a chance to verify task understanding before coding begins.
+- **Ralph** (Claude Code): Lead developer — researches, plans, codes, tests
+- **Lisa** (Codex): Code reviewer — reviews diffs, checks edge cases
+- **You**: Tech lead — architecture, scope, tiebreaking
 
-### Goal Guardian
-Lisa reads task.md before every review and checks for direction drift. Catching misalignment early is prioritized over code-level review.
+## Key Features
 
-### Watcher v3
-- **Fire-and-forget triggering**: Removed output stability wait and delivery verification for faster turn transitions
-- **30s cooldown**: Prevents re-triggering during normal work
-- **Checkpoint system**: Set `RL_CHECKPOINT_ROUNDS=N` to pause for human review every N rounds
-- **Auto-restart**: Watcher automatically restarts on crash (session-guarded)
-- **Configurable log threshold**: `RL_LOG_MAX_MB` (default 5, min 1) with proportional tail retention
-- **Heartbeat file**: `.dual-agent/.watcher_heartbeat` for external liveness checks
+- **Turn Control** — Only one agent works at a time; submissions pass the turn automatically
+- **Tag System** — `[PLAN]`, `[CODE]`, `[FIX]`, `[PASS]`, `[NEEDS_WORK]`, `[CHALLENGE]`, `[CONSENSUS]`
+- **Consensus Protocol** — Both agents must agree before proceeding; advisory verdicts, not commands
+- **Policy Layer** — Configurable `warn`/`block` mode for submission quality checks
+- **Auto Mode** — tmux-based automation with file watcher for hands-off operation
+- **Round 1 Mandatory Plan** — Ralph must submit `[PLAN]` first for Lisa to verify understanding
+- **Goal Guardian** — Lisa checks for direction drift before every review
+- **Mid-Session Task Update** — Change direction without restarting
+- **Deadlock Detection** — After 8 consecutive `[NEEDS_WORK]` rounds, watcher auto-pauses for user intervention
+- **Minimal Init** — Zero-intrusion mode with plugin/global config architecture
 
-### Deadlock Escape
-After 5 rounds without consensus: `[OVERRIDE]` (proceed anyway) or `[HANDOFF]` (escalate to human).
-
-## Commands
+## Essential 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
+# Setup
+ralph-lisa init [dir]                    # Initialize 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 check-turn                    # Alias for whose-turn
-ralph-lisa submit-ralph --file f.md      # Ralph submits (recommended)
-ralph-lisa submit-lisa --file f.md       # Lisa submits (recommended)
-ralph-lisa submit-ralph --stdin          # Submit via stdin pipe
-ralph-lisa submit-lisa --stdin           # Lisa submit via stdin pipe
-ralph-lisa submit-ralph "[TAG] ..."      # Inline (deprecated)
+ralph-lisa submit-ralph --file f.md      # Ralph submits
+ralph-lisa submit-lisa --file f.md       # 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 read-review                   # Alias for read review.md
-ralph-lisa read review --round N         # Read review from round N
 ralph-lisa history                       # Full history
-ralph-lisa recap                         # Context recovery summary
-ralph-lisa logs                          # List transcript logs
-ralph-lisa logs cat [name]               # View a specific log
 
 # Flow control
-ralph-lisa step "phase-name"             # Enter new phase (requires consensus)
-ralph-lisa step --force "phase-name"     # Enter new phase (skip consensus check)
-ralph-lisa update-task "new direction"   # Update task direction mid-session
-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
+ralph-lisa step "phase-name"             # Enter new step
+ralph-lisa update-task "new direction"   # Change task mid-session
 
 # 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
-    ├── task.md            # Task goal (updated via update-task)
-    ├── 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)
+ralph-lisa doctor                        # Check dependencies
 ```
 
 ## 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
-
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `RL_POLICY_MODE` | `warn` | Policy check mode: `off`, `warn`, `block` |
-| `RL_CHECKPOINT_ROUNDS` | `0` (disabled) | Pause for human review every N rounds |
-| `RL_LOG_MAX_MB` | `5` | Pane log truncation threshold in MB (min 1) |
+- [Claude Code](https://claude.ai/code) — for Ralph
+- [Codex CLI](https://github.com/openai/codex) — for Lisa
+- tmux — for auto mode (`brew install tmux` / `apt install tmux`)
 
-## Ecosystem
+## Documentation
 
-Part of the [TigerHill](https://github.com/Click-Intelligence-LLC/TigerHill) project family.
+Full documentation on GitHub:
 
-## See Also
+- **[User Guide](https://github.com/YW1975/Ralph-Lisa-Loop/blob/main/docs/en/guide.md)** — Setup, workflows, configuration
+- **[Command Reference](https://github.com/YW1975/Ralph-Lisa-Loop/blob/main/docs/en/reference.md)** — All CLI commands
+- **[FAQ](https://github.com/YW1975/Ralph-Lisa-Loop/blob/main/docs/en/faq.md)** — Common questions and troubleshooting
+- **[Changelog](https://github.com/YW1975/Ralph-Lisa-Loop/blob/main/docs/en/changelog.md)** — Version history
+- **[Design Philosophy](https://github.com/YW1975/Ralph-Lisa-Loop/blob/main/CONCEPT.md)** — Why dual-agent works
 
-- [CONCEPT.md](../CONCEPT.md) - Why dual-agent collaboration works
+Other languages: [日本語](https://github.com/YW1975/Ralph-Lisa-Loop/blob/main/docs/ja/guide.md) | [中文](https://github.com/YW1975/Ralph-Lisa-Loop/blob/main/docs/zh-CN/guide.md)
 
 ## License
 
-[MIT](LICENSE)
+[MIT](https://github.com/YW1975/Ralph-Lisa-Loop/blob/main/LICENSE)

package/dist/cli.js

@@ -70,9 +70,34 @@ switch (cmd) {
     case "logs":
         (0, commands_js_1.cmdLogs)(rest);
         break;
+    case "scope-update":
     case "update-task":
         (0, commands_js_1.cmdUpdateTask)(rest);
         break;
+    case "force-turn":
+        (0, commands_js_1.cmdForceTurn)(rest);
+        break;
+    case "remote":
+        (0, commands_js_1.cmdRemote)(rest);
+        break;
+    case "state-dir":
+        (0, commands_js_1.cmdStateDir)(rest);
+        break;
+    case "subtask":
+        (0, commands_js_1.cmdSubtask)(rest);
+        break;
+    case "add-context":
+        (0, commands_js_1.cmdAddContext)(rest);
+        break;
+    case "stop":
+        (0, commands_js_1.cmdStop)(rest);
+        break;
+    case "emergency-msg":
+        (0, commands_js_1.cmdEmergencyMsg)(rest);
+        break;
+    case "notify":
+        (0, commands_js_1.cmdNotify)(rest);
+        break;
     case "help":
     case "--help":
     case "-h":
@@ -99,6 +124,9 @@ function showHelp() {
     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("  ralph-lisa stop                    Graceful stop (archive + cleanup)");
+    console.log("  ralph-lisa stop --force            Force stop (SIGKILL)");
+    console.log("  ralph-lisa stop --no-archive       Stop without archiving");
     console.log("");
     console.log("Turn Control:");
     console.log("  ralph-lisa check-turn                Check whose turn (alias: whose-turn)");
@@ -121,10 +149,16 @@ function showHelp() {
     console.log("  ralph-lisa history                  Show full history");
     console.log("");
     console.log("Flow Control:");
-    console.log('  ralph-lisa next-step "name"         Enter new step (alias: step)');
-    console.log('  ralph-lisa update-task "desc"        Update task direction');
-    console.log("  ralph-lisa archive [name]           Archive session");
-    console.log("  ralph-lisa clean                    Clean session");
+    console.log('  ralph-lisa next-step "name"              Enter new step (alias: step)');
+    console.log('  ralph-lisa next-step "name" --task "t"   Enter step with first subtask');
+    console.log('  ralph-lisa scope-update "desc"            Update task scope (alias: update-task)');
+    console.log('  ralph-lisa subtask add "desc"             Add subtask to current step');
+    console.log("  ralph-lisa subtask done <N>               Mark subtask N as complete");
+    console.log("  ralph-lisa subtask list                   List all subtasks");
+    console.log('  ralph-lisa add-context "note"             Add context note (visible to Lisa)');
+    console.log("  ralph-lisa force-turn <agent>             Manual turn override (disabled in auto mode)");
+    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)");
@@ -139,7 +173,19 @@ function showHelp() {
     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("Remote Access:");
+    console.log("  ralph-lisa remote                   Start ttyd server (default port 7681)");
+    console.log("  ralph-lisa remote --port 8080       Custom port");
+    console.log("  ralph-lisa remote --auth user:pass   Enable basic auth");
+    console.log("  ralph-lisa remote --stop             Stop ttyd server");
+    console.log("");
+    console.log("Emergency & Notifications:");
+    console.log('  ralph-lisa emergency-msg <agent> "msg"  Send emergency message to agent pane');
+    console.log('  ralph-lisa notify "message"              Send notification via RL_NOTIFY_CMD');
+    console.log("");
     console.log("Diagnostics:");
+    console.log("  ralph-lisa state-dir                Show state directory resolution");
+    console.log("  ralph-lisa state-dir /path           Set state directory (tmux env)");
     console.log("  ralph-lisa doctor                   Check all dependencies");
     console.log("  ralph-lisa doctor --strict           Exit 1 if any missing (for CI)");
 }

package/dist/commands.d.ts

@@ -2,6 +2,11 @@
  * CLI commands for Ralph-Lisa Loop.
  * Direct port of io.sh logic to Node/TS.
  */
+/**
+ * Send a notification to the user via RL_NOTIFY_CMD.
+ * Notification failure must not block main flow.
+ */
+export declare function notifyUser(message: string): void;
 /**
  * Generate a project-specific tmux session name to avoid conflicts
  * when running multiple projects simultaneously.
@@ -9,6 +14,15 @@
  * tmux session names cannot contain '.' or ':'.
  */
 export declare function generateSessionName(projectDir: string): string;
+/**
+ * V4-01: Ralph Auto Gate — run test/lint commands before CODE/FIX submission.
+ * Config via env vars only (config file deferred to future version):
+ *   RL_RALPH_GATE=true          — enable gate (default: false)
+ *   RL_GATE_COMMANDS=cmd1|cmd2  — pipe-separated commands
+ *   RL_GATE_MODE=warn|block     — warn (default) or block on failure
+ * Gate results are NOT written to work.md (prevents Lisa anchoring).
+ */
+export declare function runGate(tag: string): void;
 export declare function cmdInit(args: string[]): void;
 export declare function cmdWhoseTurn(): void;
 export declare function cmdSubmitRalph(args: string[]): void;
@@ -17,14 +31,31 @@ export declare function cmdStatus(): void;
 export declare function cmdRead(args: string[]): void;
 export declare function cmdRecap(): void;
 export declare function cmdStep(args: string[]): void;
+interface Subtask {
+    index: number;
+    text: string;
+    done: boolean;
+    line: string;
+}
+export declare function parseSubtasks(taskContent: string): Subtask[];
+export declare function cmdSubtask(args: string[]): void;
 export declare function cmdHistory(): void;
 export declare function cmdArchive(args: string[]): void;
 export declare function cmdClean(): void;
+export declare function cmdStop(args: string[]): void;
 export declare function cmdUpdateTask(args: string[]): void;
+export declare function cmdForceTurn(args: string[], confirmed?: boolean): void;
+export declare function executeForceTurn(agent: string, dir: string): 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 cmdRemote(args: string[]): void;
+export declare function cmdStateDir(args: string[]): void;
+export declare function cmdAddContext(args: string[]): void;
 export declare function cmdDoctor(args: string[]): void;
+export declare function cmdEmergencyMsg(args: string[]): void;
+export declare function cmdNotify(args: string[]): void;
+export {};