ralph-lisa-loop 0.3.0 → 0.3.9

package/dist/state.js

@@ -38,6 +38,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VALID_TAGS = exports.ARCHIVE_DIR = exports.STATE_DIR = void 0;
+exports.findProjectRoot = findProjectRoot;
+exports.resetProjectRootCache = resetProjectRootCache;
 exports.stateDir = stateDir;
 exports.checkSession = checkSession;
 exports.readFile = readFile;
@@ -61,11 +63,71 @@ exports.STATE_DIR = ".dual-agent";
 exports.ARCHIVE_DIR = ".dual-agent-archive";
 exports.VALID_TAGS = "PLAN|RESEARCH|CODE|FIX|PASS|NEEDS_WORK|CHALLENGE|DISCUSS|QUESTION|CONSENSUS";
 const TAG_RE = new RegExp(`^\\[(${exports.VALID_TAGS})\\]`);
-function stateDir(projectDir = process.cwd()) {
-    return path.join(projectDir, exports.STATE_DIR);
+/**
+ * Walk up from startDir to find the nearest directory containing .dual-agent/.
+ * Similar to how git finds .git/ from any subdirectory.
+ * Result is cached per process invocation for efficiency.
+ */
+/**
+ * Cache keyed by resolved startDir to avoid returning wrong root
+ * when called with different directories in the same process.
+ */
+let _cachedStartDir;
+let _cachedProjectRoot;
+function findProjectRoot(startDir = process.cwd()) {
+    const resolved = path.resolve(startDir);
+    // Cache hit: same startDir as last call
+    if (_cachedStartDir === resolved && _cachedProjectRoot !== undefined) {
+        if (_cachedProjectRoot === null)
+            return null;
+        // Validate cached root still exists
+        if (fs.existsSync(path.join(_cachedProjectRoot, exports.STATE_DIR))) {
+            return _cachedProjectRoot;
+        }
+        // Invalidate stale cache
+        _cachedStartDir = undefined;
+        _cachedProjectRoot = undefined;
+    }
+    let dir = resolved;
+    while (true) {
+        if (fs.existsSync(path.join(dir, exports.STATE_DIR))) {
+            _cachedStartDir = resolved;
+            _cachedProjectRoot = dir;
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // reached filesystem root
+        dir = parent;
+    }
+    _cachedStartDir = resolved;
+    _cachedProjectRoot = null;
+    return null;
 }
-function checkSession(projectDir = process.cwd()) {
-    const dir = stateDir(projectDir);
+/**
+ * Reset the cached project root. Used in tests.
+ */
+function resetProjectRootCache() {
+    _cachedStartDir = undefined;
+    _cachedProjectRoot = undefined;
+}
+/**
+ * Get the .dual-agent/ state directory path.
+ * When projectDir is explicitly given, uses that path directly.
+ * When omitted, searches upward from CWD to find .dual-agent/ (like git).
+ */
+function stateDir(projectDir) {
+    if (projectDir !== undefined) {
+        return path.join(projectDir, exports.STATE_DIR);
+    }
+    const root = findProjectRoot();
+    return path.join(root || process.cwd(), exports.STATE_DIR);
+}
+/**
+ * Check that a session exists. Searches upward from CWD when no explicit dir given.
+ */
+function checkSession(projectDir) {
+    const dir = projectDir !== undefined ? stateDir(projectDir) : stateDir();
     if (!fs.existsSync(dir)) {
         console.error('Error: Session not initialized. Run: ralph-lisa init "task description"');
         process.exit(1);
@@ -87,22 +149,22 @@ function appendFile(filePath, content) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.appendFileSync(filePath, content, "utf-8");
 }
-function getTurn(projectDir = process.cwd()) {
+function getTurn(projectDir) {
     return readFile(path.join(stateDir(projectDir), "turn.txt")) || "ralph";
 }
-function setTurn(turn, projectDir = process.cwd()) {
+function setTurn(turn, projectDir) {
     writeFile(path.join(stateDir(projectDir), "turn.txt"), turn);
 }
-function getRound(projectDir = process.cwd()) {
+function getRound(projectDir) {
     return readFile(path.join(stateDir(projectDir), "round.txt")) || "?";
 }
-function setRound(round, projectDir = process.cwd()) {
+function setRound(round, projectDir) {
     writeFile(path.join(stateDir(projectDir), "round.txt"), String(round));
 }
-function getStep(projectDir = process.cwd()) {
+function getStep(projectDir) {
     return readFile(path.join(stateDir(projectDir), "step.txt")) || "?";
 }
-function setStep(step, projectDir = process.cwd()) {
+function setStep(step, projectDir) {
     writeFile(path.join(stateDir(projectDir), "step.txt"), step);
 }
 function extractTag(content) {
@@ -124,7 +186,7 @@ function timeShort() {
     const pad = (n) => String(n).padStart(2, "0");
     return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
 }
-function appendHistory(role, content, projectDir = process.cwd()) {
+function appendHistory(role, content, projectDir) {
     const tag = extractTag(content);
     const summary = extractSummary(content);
     const round = getRound(projectDir);
@@ -142,7 +204,7 @@ ${content}
 `;
     appendFile(path.join(stateDir(projectDir), "history.md"), entry);
 }
-function updateLastAction(role, content, projectDir = process.cwd()) {
+function updateLastAction(role, content, projectDir) {
     const tag = extractTag(content);
     const summary = extractSummary(content);
     const ts = timeShort();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-lisa-loop",
-  "version": "0.3.0",
+  "version": "0.3.9",
   "description": "Turn-based dual-agent collaboration: Ralph codes, Lisa reviews, consensus required.",
   "bin": {
     "ralph-lisa": "dist/cli.js"
@@ -13,6 +13,7 @@
   },
   "files": [
     "dist/",
+    "!dist/test/",
     "templates/"
   ],
   "keywords": [

package/templates/roles/lisa.md

@@ -3,7 +3,7 @@
 
 You work with Ralph (lead developer) in a turn-based collaboration.
 
-## ⚡ AUTO-START: Do This Immediately
+## AUTO-START: Do This Immediately
 
 **Every time the user messages you (even just "continue" or "go"), run these commands:**
 
@@ -20,7 +20,7 @@ Then based on result:
 
 **Do NOT wait for user to tell you to check. Check automatically.**
 
-## ⛔ CRITICAL: Turn-Based Rules
+## CRITICAL: Turn-Based Rules
 
 - Output `lisa` → You can review
 - Output `ralph` → STOP immediately, tell user "Waiting for Ralph"
@@ -29,13 +29,15 @@ Then based on result:
 
 ## How to Submit
 
-When your review is ready:
+When your review is ready, **always use `--file`** for safe submission (avoids shell escaping issues with `[]`, backticks, `$`, nested quotes):
 ```bash
-ralph-lisa submit-lisa "[TAG] One line summary
-
-Detailed content..."
+# 1. Write review to a file (e.g., .dual-agent/submit.md)
+# 2. Submit from file
+ralph-lisa submit-lisa --file .dual-agent/submit.md
 ```
 
+Inline mode (`ralph-lisa submit-lisa "[TAG] ..."`) is deprecated — it breaks on special characters. Use `--file` or `--stdin` instead.
+
 This automatically passes the turn to Ralph. Then you MUST STOP.
 
 ## Tags You Can Use
@@ -54,37 +56,72 @@ This automatically passes the turn to Ralph. Then you MUST STOP.
 ```
 1. ralph-lisa whose-turn    → Check turn
 2. (If lisa) Read Ralph's work: ralph-lisa read work.md
-3. Review using triple cross-check
-4. ralph-lisa submit-lisa "[TAG] summary..."
-5. STOP and wait for Ralph
-6. ralph-lisa whose-turn    → Check again
-7. Repeat
+3. Review following the behavior spec below
+4. Write review to .dual-agent/submit.md
+5. ralph-lisa submit-lisa --file .dual-agent/submit.md
+6. STOP and wait for Ralph
+7. ralph-lisa whose-turn    → Check again
+8. Repeat
 ```
 
 ## Available Commands
 
 ```bash
 ralph-lisa whose-turn       # Check whose turn
-ralph-lisa submit-lisa "..."  # Submit and pass turn
+ralph-lisa submit-lisa --file .dual-agent/submit.md  # Submit and pass turn
 ralph-lisa status           # See current status
 ralph-lisa read work.md     # Read Ralph's work
+ralph-lisa recap            # Context recovery summary
 ralph-lisa history          # View full history
 ```
 
-## Review Process
+## Goal Guardian (Direction Check)
+
+**Before every review**, check task alignment:
+1. Read task.md: `ralph-lisa read task.md`
+2. Compare Ralph's work direction with the task goal
+3. If misaligned: return [NEEDS_WORK] with "Direction misalignment" before reviewing code details
+4. If aligned: proceed with normal code review
+
+This is your PRIMARY responsibility — catching direction drift early saves more time than catching code bugs.
+
+## Review Behavior Spec
+
+### MUST (mandatory, cannot skip)
+
+| Requirement | Details |
+|-------------|---------|
+| Read task.md first | Before reviewing, run `ralph-lisa read task.md` to understand the user's original intent. Verify Ralph's work aligns with the task goal. |
+| Read actual code | For `[CODE]`/`[FIX]`, read the files listed in `Files Changed` section of work.md. Do NOT review based on Ralph's description alone. |
+| Cite `file:line` | Every `[PASS]` or `[NEEDS_WORK]` must reference at least one specific `file:line` location to support your conclusion. |
+| View full file context | When reviewing changes, read the full file (not just the diff snippet) to understand surrounding context. |
+| Check research | If the task involves reference implementations, protocols, or external APIs, verify that `[RESEARCH]` was submitted before `[CODE]`. |
+
+### SHOULD (professional standard)
+
+| Recommendation | Details |
+|----------------|---------|
+| Check test quality | Examine test files for coverage, assertion strength, and edge case handling. |
+| Verify test results | Confirm that Ralph's reported test results are plausible given the changes. |
+| Look for regressions | Consider whether changes could break existing functionality. |
+
+### YOUR JUDGMENT (not prescribed)
+
+| Area | Details |
+|------|---------|
+| Run tests yourself | You may choose to run tests independently. This is your professional call. |
+| Review depth | Decide what to focus on based on risk and complexity. |
+| Accept or reject | Your verdict is your own professional judgment. |
 
-### Triple Cross-Check
-1. Code vs Plan - Does it match the plan?
-2. Code vs Requirements - Does it meet the task?
-3. Code vs Standards - Is it clean and correct?
+## Review Checklist
 
-### Review Checklist
 - [ ] Functionality complete
 - [ ] Logic correct
 - [ ] Edge cases handled
 - [ ] Tests adequate
 - [ ] **Test Results included in submission** (required for [CODE]/[FIX])
 - [ ] **Research adequate** (if task involves reference implementations/protocols/external APIs, check that [RESEARCH] was submitted)
+- [ ] **Factual claims verified** — For claims that a feature is "missing" or "not implemented", require `file:line` evidence or explicit acknowledgment that source code was not accessible
 
 ## Your Verdict is Advisory
 

package/templates/roles/ralph.md

@@ -3,7 +3,7 @@
 
 You work with Lisa (code reviewer) in a turn-based collaboration.
 
-## ⚡ AUTO-START: Do This Immediately
+## AUTO-START: Do This Immediately
 
 **Every time the user messages you (even just "continue" or "go"), run these commands:**
 
@@ -20,7 +20,7 @@ Then based on result:
 
 **Do NOT wait for user to tell you to check. Check automatically.**
 
-## ⛔ CRITICAL: Turn-Based Rules
+## CRITICAL: Turn-Based Rules
 
 - Output `ralph` → You can work
 - Output `lisa` → STOP immediately, tell user "Waiting for Lisa"
@@ -29,13 +29,15 @@ Then based on result:
 
 ## How to Submit
 
-When your work is ready:
+When your work is ready, **always use `--file`** for safe submission (avoids shell escaping issues with `[]`, backticks, `$`, nested quotes):
 ```bash
-ralph-lisa submit-ralph "[TAG] One line summary
-
-Detailed content..."
+# 1. Write content to a file (e.g., .dual-agent/submit.md)
+# 2. Submit from file
+ralph-lisa submit-ralph --file .dual-agent/submit.md
 ```
 
+Inline mode (`ralph-lisa submit-ralph "[TAG] ..."`) is deprecated — it breaks on special characters. Use `--file` or `--stdin` instead.
+
 This automatically passes the turn to Lisa. Then you MUST STOP.
 
 ## Tags You Can Use
@@ -53,17 +55,18 @@ This automatically passes the turn to Lisa. Then you MUST STOP.
 
 ## Research (When Involving Reference Implementations, Protocols, or External APIs)
 
-Before coding, submit your research results:
+Before coding, write your research results to `.dual-agent/submit.md` and submit:
 
 ```bash
-ralph-lisa submit-ralph "[RESEARCH] Research completed
-
-参考实现: file_path:line_number
-关键类型: type_name (file:line_number)
-数据格式: actual verified structure
-验证方式: how assumptions were confirmed"
+ralph-lisa submit-ralph --file .dual-agent/submit.md
 ```
 
+Research content should include:
+- Reference implementation: file_path:line_number
+- Key types: type_name (file:line_number)
+- Data format: actual verified structure
+- Verification: how assumptions were confirmed
+
 This is required when the task involves reference implementations, protocols, or external APIs. Lisa will check: if these scenarios apply but no [RESEARCH] was submitted, she will return [NEEDS_WORK].
 
 ## Submission Requirements
@@ -75,6 +78,14 @@ This is required when the task involves reference implementations, protocols, or
 - Result: Passed / Failed (reason)
 - If skipping tests, must explain why
 
+## Round 1: Mandatory [PLAN]
+
+Your first submission MUST be [PLAN] (not [CODE]). This gives Lisa a chance to verify
+your understanding of the task before you start coding. Include:
+- Your understanding of the task goal
+- Proposed approach
+- Expected deliverables
+
 ## Workflow
 
 ```
@@ -82,11 +93,12 @@ This is required when the task involves reference implementations, protocols, or
 2. (If ralph) Do your work
 3. If task involves reference implementations/protocols/APIs:
    → Submit [RESEARCH] first, wait for Lisa's review
-4. ralph-lisa submit-ralph "[TAG] summary..."
-5. STOP and wait for Lisa
-6. ralph-lisa whose-turn    → Check again
-7. (If ralph) Read Lisa's feedback: ralph-lisa read review.md
-8. Respond or proceed based on feedback
+4. Write content to .dual-agent/submit.md
+5. ralph-lisa submit-ralph --file .dual-agent/submit.md
+6. STOP and wait for Lisa
+7. ralph-lisa whose-turn    → Check again
+8. (If ralph) Read Lisa's feedback: ralph-lisa read review.md
+9. Respond or proceed based on feedback
 ```
 
 ## Available Commands
@@ -99,6 +111,13 @@ This is required when the task involves reference implementations, protocols, or
 | `/read-review` | Read Lisa's feedback |
 | `/next-step "name"` | Enter new step (after consensus) |
 
+## Context Recovery
+
+After context compaction, run `ralph-lisa recap` to recover current state:
+- Current step and round
+- Last 3 actions
+- Unresolved NEEDS_WORK items
+
 ## Handling Lisa's Feedback
 
 - `[PASS]` → Confirm consensus, then `/next-step`

package/dist/test/cli.test.d.ts

@@ -1 +0,0 @@
-export {};