ralph-lisa-loop 0.3.0 → 0.3.9

package/README.md

@@ -36,7 +36,7 @@ Ralph writes → Lisa reviews → Consensus → Next step
 ### 1. Install
 
 ```bash
-npm i -g ralph-lisa
+npm i -g ralph-lisa-loop
 ```
 
 ### 2. Initialize Project
@@ -61,22 +61,16 @@ ralph-lisa auto "implement login feature"
 **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"
+# ... 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
-ralph-lisa submit-lisa "[PASS] Plan looks good
-
-- Clear structure
-- Good separation of concerns"
+# ... write review to .dual-agent/submit.md ...
+ralph-lisa submit-lisa --file .dual-agent/submit.md
 ```
 
 ## Features
@@ -126,7 +120,7 @@ export RL_POLICY_MODE=warn
 # Enable block mode (rejects non-compliant submissions)
 export RL_POLICY_MODE=block
 
-# Disable (default)
+# Disable
 export RL_POLICY_MODE=off
 ```
 
@@ -144,6 +138,27 @@ Policy rules:
 - 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"
+```
+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.
+
+### Goal Guardian
+Lisa reads task.md before every review and checks for direction drift. Catching misalignment early is prioritized over code-level review.
+
+### 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
+
 ### Deadlock Escape
 After 5 rounds without consensus: `[OVERRIDE]` (proceed anyway) or `[HANDOFF]` (escalate to human).
 
@@ -161,17 +176,28 @@ 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
+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)
 
 # 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
+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
 
@@ -199,6 +225,7 @@ your-project/
 │   └── 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
@@ -220,14 +247,21 @@ 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) |
+
 ## 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
+- [CONCEPT.md](../CONCEPT.md) - Why dual-agent collaboration works
 
 ## License
 

package/dist/cli.js

@@ -21,6 +21,7 @@ switch (cmd) {
         (0, commands_js_1.cmdUninit)();
         break;
     case "whose-turn":
+    case "check-turn":
         (0, commands_js_1.cmdWhoseTurn)();
         break;
     case "submit-ralph":
@@ -35,10 +36,14 @@ switch (cmd) {
     case "read":
         (0, commands_js_1.cmdRead)(rest);
         break;
+    case "read-review":
+        (0, commands_js_1.cmdRead)(["review.md", ...rest]);
+        break;
     case "recap":
         (0, commands_js_1.cmdRecap)();
         break;
     case "step":
+    case "next-step":
         (0, commands_js_1.cmdStep)(rest);
         break;
     case "history":
@@ -65,6 +70,9 @@ switch (cmd) {
     case "logs":
         (0, commands_js_1.cmdLogs)(rest);
         break;
+    case "update-task":
+        (0, commands_js_1.cmdUpdateTask)(rest);
+        break;
     case "help":
     case "--help":
     case "-h":
@@ -93,11 +101,13 @@ function showHelp() {
     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("  ralph-lisa check-turn                Check whose turn (alias: whose-turn)");
+    console.log("  ralph-lisa submit-ralph --file <f>   Ralph submits from file (recommended)");
+    console.log("  ralph-lisa submit-lisa --file <f>    Lisa submits from file (recommended)");
+    console.log("  ralph-lisa submit-ralph --stdin      Ralph submits from stdin");
+    console.log("  ralph-lisa submit-lisa --stdin       Lisa submits from stdin");
+    console.log('  ralph-lisa submit-ralph "[TAG]..."   Ralph submits inline (deprecated)');
+    console.log('  ralph-lisa submit-lisa "[TAG]..."    Lisa submits inline (deprecated)');
     console.log("");
     console.log("Tags:");
     console.log("  Ralph: [PLAN] [RESEARCH] [CODE] [FIX] [CHALLENGE] [DISCUSS] [QUESTION] [CONSENSUS]");
@@ -105,12 +115,14 @@ function showHelp() {
     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 read-review              Read Lisa's review (alias: read review.md)");
+    console.log("  ralph-lisa read <file>              Read work.md/review.md/etc");
     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 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("");
@@ -137,6 +149,6 @@ function showVersion() {
         console.log(`ralph-lisa-loop v${pkg.version}`);
     }
     catch {
-        console.log("ralph-lisa-loop v0.3.0");
+        console.log("ralph-lisa-loop v0.3.9");
     }
 }

package/dist/commands.d.ts

@@ -2,6 +2,13 @@
  * CLI commands for Ralph-Lisa Loop.
  * Direct port of io.sh logic to Node/TS.
  */
+/**
+ * Generate a project-specific tmux session name to avoid conflicts
+ * when running multiple projects simultaneously.
+ * Format: rll-{sanitized-dirname}-{short-hash}
+ * tmux session names cannot contain '.' or ':'.
+ */
+export declare function generateSessionName(projectDir: string): string;
 export declare function cmdInit(args: string[]): void;
 export declare function cmdWhoseTurn(): void;
 export declare function cmdSubmitRalph(args: string[]): void;
@@ -13,6 +20,7 @@ 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 cmdUpdateTask(args: string[]): void;
 export declare function cmdUninit(): void;
 export declare function cmdInitProject(args: string[]): void;
 export declare function cmdStart(args: string[]): void;