ralph-lisa-loop 0.3.10 → 0.3.11

package/dist/policy.d.ts

@@ -21,6 +21,7 @@ export declare function checkRalph(tag: string, content: string): PolicyViolatio
  * Check Lisa's submission for policy violations.
  */
 export declare function checkLisa(tag: string, content: string): PolicyViolation[];
+export declare function checkNeedsWorkResponse(ralphTag: string, lastLisaTag: string): PolicyViolation[];
 /**
  * Run policy checks based on mode.
  * Returns { proceed, violations } so callers can format output clearly (IMP-4).

package/dist/policy.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPolicyMode = getPolicyMode;
 exports.checkRalph = checkRalph;
 exports.checkLisa = checkLisa;
+exports.checkNeedsWorkResponse = checkNeedsWorkResponse;
 exports.runPolicyCheck = runPolicyCheck;
 function getPolicyMode() {
     const mode = process.env.RL_POLICY_MODE || "warn";
@@ -40,6 +41,21 @@ function checkRalph(tag, content) {
                 message: `[${tag}] submission must include at least one file:line reference (e.g., commands.ts:42).`,
             });
         }
+        // New tests count check (Proposal §3.6)
+        // Warn if "New tests: 0" without valid justification
+        const lc = content.toLowerCase();
+        const hasNewTests = /new tests?:\s*[1-9]/i.test(content);
+        const hasZeroTests = /new tests?:\s*0/i.test(content);
+        if (hasZeroTests && !hasNewTests) {
+            // Check for valid justification keywords
+            const hasJustification = /\b(ui.only|layout.only|config.only|no.testable.logic|template.only|documentation)\b/i.test(content);
+            if (!hasJustification) {
+                violations.push({
+                    rule: "new-tests-required",
+                    message: `[${tag}] reports 0 new tests without valid justification. Add unit tests or explain why (e.g., "config-only change").`,
+                });
+            }
+        }
     }
     // [RESEARCH] must have substance
     if (tag === "RESEARCH") {
@@ -58,6 +74,17 @@ function checkRalph(tag, content) {
                 message: "[RESEARCH] submission needs at least 2 fields (reference/key types/data structure/verification) or equivalent summary with evidence.",
             });
         }
+        // RESEARCH verification markers (Proposal §3.9)
+        // Checks for at least one global Verified:/Evidence: marker per submission.
+        // Per-claim enforcement is not mechanically feasible — Lisa reviews claim-level rigor.
+        const hasVerifiedMarker = /\bverified\s*:/i.test(content);
+        const hasEvidenceMarker = /\bevidence\s*:/i.test(content);
+        if (!hasVerifiedMarker && !hasEvidenceMarker) {
+            violations.push({
+                rule: "research-verification",
+                message: '[RESEARCH] submission should include at least one "Verified:" or "Evidence:" marker to support factual claims.',
+            });
+        }
     }
     return violations;
 }
@@ -86,6 +113,26 @@ function checkLisa(tag, content) {
     }
     return violations;
 }
+/**
+ * NEEDS_WORK response enforcement (Proposal §3.2).
+ * When Lisa's last review was [NEEDS_WORK], Ralph must respond with
+ * [FIX], [CHALLENGE], [DISCUSS], or [QUESTION] — not unrelated [CODE]/[RESEARCH]/[PLAN].
+ */
+const NEEDS_WORK_ALLOWED_TAGS = new Set(["FIX", "CHALLENGE", "DISCUSS", "QUESTION"]);
+const NEEDS_WORK_BLOCKED_TAGS = new Set(["CODE", "RESEARCH", "PLAN", "CONSENSUS"]);
+function checkNeedsWorkResponse(ralphTag, lastLisaTag) {
+    if (lastLisaTag !== "NEEDS_WORK")
+        return [];
+    if (NEEDS_WORK_ALLOWED_TAGS.has(ralphTag))
+        return [];
+    if (NEEDS_WORK_BLOCKED_TAGS.has(ralphTag)) {
+        return [{
+                rule: "needs-work-response",
+                message: `[${ralphTag}] submitted after Lisa's [NEEDS_WORK]. You must respond with [FIX], [CHALLENGE], [DISCUSS], or [QUESTION] first. If the task scope changed, run: ralph-lisa scope-update "new scope"`,
+            }];
+    }
+    return [];
+}
 /**
  * Run policy checks based on mode.
  * Returns { proceed, violations } so callers can format output clearly (IMP-4).

package/dist/state.d.ts

@@ -10,10 +10,28 @@ export declare function findProjectRoot(startDir?: string): string | null;
  * Reset the cached project root. Used in tests.
  */
 export declare function resetProjectRootCache(): void;
+export declare function _setTmuxStateDirOverride(value: string | null | undefined): void;
+/**
+ * Try to read RL_STATE_DIR from tmux session environment.
+ * Returns null if not in tmux or env var not set.
+ */
+export declare function getTmuxStateDir(): string | null;
+/**
+ * Resolve state directory with priority (Proposal §3.10):
+ *   1. tmux show-environment RL_STATE_DIR  (authoritative in auto mode)
+ *   2. $RL_STATE_DIR environment variable  (manual mode / override)
+ *   3. findProjectRoot() upward search     (fallback)
+ *
+ * Returns { dir, source } for diagnostics.
+ */
+export declare function resolveStateDir(): {
+    dir: string;
+    source: "tmux" | "env" | "auto-detect";
+};
 /**
  * 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).
+ * When omitted, uses priority resolution: tmux env → shell env → upward search.
  */
 export declare function stateDir(projectDir?: string): string;
 /**

package/dist/state.js

@@ -40,6 +40,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VALID_TAGS = exports.ARCHIVE_DIR = exports.STATE_DIR = void 0;
 exports.findProjectRoot = findProjectRoot;
 exports.resetProjectRootCache = resetProjectRootCache;
+exports._setTmuxStateDirOverride = _setTmuxStateDirOverride;
+exports.getTmuxStateDir = getTmuxStateDir;
+exports.resolveStateDir = resolveStateDir;
 exports.stateDir = stateDir;
 exports.checkSession = checkSession;
 exports.readFile = readFile;
@@ -59,6 +62,7 @@ exports.appendHistory = appendHistory;
 exports.updateLastAction = updateLastAction;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
 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";
@@ -111,17 +115,72 @@ function resetProjectRootCache() {
     _cachedStartDir = undefined;
     _cachedProjectRoot = undefined;
 }
+/**
+ * Test-only override for getTmuxStateDir(). When set to a string, that value
+ * is returned instead of querying tmux. Set to undefined to restore real behavior.
+ */
+let _tmuxStateDirOverride;
+function _setTmuxStateDirOverride(value) {
+    _tmuxStateDirOverride = value;
+}
+/**
+ * Try to read RL_STATE_DIR from tmux session environment.
+ * Returns null if not in tmux or env var not set.
+ */
+function getTmuxStateDir() {
+    // Test override takes precedence
+    if (_tmuxStateDirOverride !== undefined)
+        return _tmuxStateDirOverride;
+    try {
+        const tmuxEnv = process.env.TMUX;
+        if (!tmuxEnv)
+            return null;
+        const result = (0, node_child_process_1.execSync)("tmux show-environment RL_STATE_DIR 2>/dev/null", {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout: 3000,
+        }).trim();
+        // Format: "RL_STATE_DIR=/path" or "-RL_STATE_DIR" (unset)
+        if (result.startsWith("RL_STATE_DIR=")) {
+            return result.slice("RL_STATE_DIR=".length);
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve state directory with priority (Proposal §3.10):
+ *   1. tmux show-environment RL_STATE_DIR  (authoritative in auto mode)
+ *   2. $RL_STATE_DIR environment variable  (manual mode / override)
+ *   3. findProjectRoot() upward search     (fallback)
+ *
+ * Returns { dir, source } for diagnostics.
+ */
+function resolveStateDir() {
+    // 1. tmux env (authoritative in auto mode)
+    const tmuxDir = getTmuxStateDir();
+    if (tmuxDir)
+        return { dir: tmuxDir, source: "tmux" };
+    // 2. Shell env var
+    const envDir = process.env.RL_STATE_DIR;
+    if (envDir)
+        return { dir: envDir, source: "env" };
+    // 3. Fallback: upward search
+    const root = findProjectRoot();
+    return { dir: path.join(root || process.cwd(), exports.STATE_DIR), source: "auto-detect" };
+}
 /**
  * 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).
+ * When omitted, uses priority resolution: tmux env → shell env → upward search.
  */
 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);
+    return resolveStateDir().dir;
 }
 /**
  * Check that a session exists. Searches upward from CWD when no explicit dir given.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-lisa-loop",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "Turn-based dual-agent collaboration: Ralph codes, Lisa reviews, consensus required.",
   "bin": {
     "ralph-lisa": "dist/cli.js"

package/templates/roles/lisa.md

@@ -79,9 +79,13 @@ ralph-lisa history          # View full history
 
 **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
+2. Read context.md: `ralph-lisa read context.md` (if it exists — contains runtime directives)
+3. Compare Ralph's work direction with the task goal + context
+4. If misaligned: return [NEEDS_WORK] with "Direction misalignment" before reviewing code details
+5. If aligned: proceed with normal code review
+
+**Auto-suggestion rule:** After 2 consecutive off-task NEEDS_WORK rounds, include in your review:
+> "If the task scope has changed, ask Ralph to run `ralph-lisa scope-update` before resubmitting."
 
 This is your PRIMARY responsibility — catching direction drift early saves more time than catching code bugs.
 
@@ -92,6 +96,7 @@ This is your PRIMARY responsibility — catching direction drift early saves mor
 | 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 context.md | If it exists, run `ralph-lisa read context.md` for runtime directives and user decisions that supplement the task. Context is also auto-injected into work.md. |
 | 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. |
@@ -110,6 +115,7 @@ This is your PRIMARY responsibility — catching direction drift early saves mor
 | Area | Details |
 |------|---------|
 | Run tests yourself | You may choose to run tests independently. This is your professional call. |
+| Write verification tests | When static analysis is insufficient, write ad-hoc tests in `.dual-agent/tests/` and reference the output in your review. These are auto-cleaned on [CONSENSUS]. |
 | Review depth | Decide what to focus on based on risk and complexity. |
 | Accept or reject | Your verdict is your own professional judgment. |
 
@@ -121,6 +127,7 @@ This is your PRIMARY responsibility — catching direction drift early saves mor
 - [ ] 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)
+- [ ] **Research verified** — [RESEARCH] submissions must include at least one `Verified:` or `Evidence:` marker. Reject unverified claims.
 - [ ] **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

@@ -65,7 +65,8 @@ 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
+- Verified: how each claim was confirmed (required — at least one `Verified:` or `Evidence:` marker per submission)
+- Evidence: source of truth (file path, command output, API response)
 
 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].
 
@@ -120,17 +121,33 @@ After context compaction, run `ralph-lisa recap` to recover current state:
 
 ## Handling Lisa's Feedback
 
-- `[PASS]` → Confirm consensus, then `/next-step`
+- `[PASS]` → Submit [CONSENSUS] to close. Lisa's [PASS] already approves — no need to wait for her [CONSENSUS] back (single-round consensus).
 - `[NEEDS_WORK]` → You MUST explain your reasoning:
   - If you agree: explain WHY Lisa is right, then submit [FIX]
   - If you disagree: use [CHALLENGE] to provide counter-argument
   - **Never submit a bare [FIX] without explanation. No silent acceptance.**
-- After 5 rounds deadlock → OVERRIDE or HANDOFF
+  - **You CANNOT submit [CODE]/[RESEARCH]/[PLAN] after NEEDS_WORK** — the CLI will reject it. Address the feedback first, or run `ralph-lisa scope-update` if the task scope changed.
+- After 3 consecutive NEEDS_WORK rounds → DEADLOCK auto-detected, watcher pauses for user intervention
+
+## Submission Test Requirements
+
+**[CODE] or [FIX] must report both regression and new tests:**
+
+```markdown
+### Test Results
+- Regression: npm test → 150/150 pass (no breakage)
+- New tests: 3 added
+  - resolveConfigDir.test.ts: platform path resolution (3 cases)
+  - ipc-shape.test.ts: getConversationMessages returns TMessage[]
+```
+
+- "New tests: 0" requires justification (valid: pure UI layout, config-only change)
+- Invalid excuse: "requires E2E" for pure functions, data shape validation, or mock-able IPC
 
 ## Your Responsibilities
 
 1. Planning and coding
 2. Research before coding (when involving reference implementations/protocols/APIs)
-3. Writing and running tests, including Test Results in submissions
+3. Writing and running tests — **both regression and new unit tests**
 4. Responding to Lisa's reviews with reasoning
 5. Getting consensus before proceeding