Module loop_context 

Loop context for path resolution in multi-loop scenarios.

When running multiple Ralph loops concurrently, each loop needs its own isolated paths for state files (events, tasks, scratchpad) while sharing memories across loops for cross-loop learning.

Design

• Primary loop: Runs in the main workspace, paths resolve to standard locations
• Worktree loop: Runs in a git worktree, paths resolve to worktree-local locations
• Shared memories: Memories are symlinked in worktrees, pointing to main workspace
• Shared specs/tasks: Specs and code tasks are symlinked in worktrees

Directory Structure

All Ralph state is consolidated under .ralph/:

.ralph/
├── agent/                    # Agent state (memories, tasks, scratchpad)
│   ├── memories.md           # Symlinked in worktrees
│   ├── tasks.jsonl           # Isolated per worktree
│   ├── scratchpad.md         # Isolated per worktree
│   └── context.md            # Worktree metadata (worktrees only)
├── specs/                    # Specification files (symlinked in worktrees)
├── tasks/                    # Code task files (symlinked in worktrees)
├── loop.lock
├── loops.json
├── merge-queue.jsonl
├── events.jsonl
├── current-events
├── history.jsonl
├── diagnostics/
└── planning-sessions/

Example

use ralph_core::loop_context::LoopContext;
use std::path::PathBuf;

// Primary loop runs in current directory
let primary = LoopContext::primary(PathBuf::from("/project"));
assert_eq!(primary.events_path().to_string_lossy(), "/project/.ralph/events.jsonl");
assert_eq!(primary.tasks_path().to_string_lossy(), "/project/.ralph/agent/tasks.jsonl");

// Worktree loop runs in isolated directory
let worktree = LoopContext::worktree(
    "loop-1234-abcd",
    PathBuf::from("/project/.worktrees/loop-1234-abcd"),
    PathBuf::from("/project"),
);
assert_eq!(worktree.events_path().to_string_lossy(),
           "/project/.worktrees/loop-1234-abcd/.ralph/events.jsonl");

Structs

LoopContext

Context for resolving paths within a Ralph loop.