ralph.rb 1.2.435535439

data/specs/output.md

@@ -0,0 +1,104 @@
+# Output Specification
+
+All terminal output in Ralph is structured as callable output classes under the `Ralph::Output` namespace. Each class encapsulates a single output concern — a banner, a warning, a summary — and exposes a `self.call` class method as its only public interface.
+
+## Namespace & File Layout
+
+```
+lib/ralph/output/
+  no_plugin_warning.rb    # Ralph::Output::NoPluginWarning
+  banner.rb               # Ralph::Output::Banner
+  iteration.rb            # Ralph::Output::Iteration::Header
+                          # Ralph::Output::Iteration::Summary
+                          # Ralph::Output::Iteration::Error
+  ...
+```
+
+Each file defines one or more classes inside `module Ralph; module Output; ... end; end`.
+
+When several output classes share a common concern (e.g. iteration lifecycle), they are grouped under a nested module in a single file. The submodule acts as a namespace — it contains only classes, no logic of its own.
+
+## Interface: The Callable Object Pattern
+
+Every output class follows the same shape:
+
+```ruby
+module Ralph
+  module Output
+    class ExampleWarning
+      def self.call(thing:, count:)
+        warn "Warning: #{thing} happened #{count} times"
+      end
+    end
+  end
+end
+```
+
+### Rules
+
+| Rule | Detail |
+|------|--------|
+| **Entry point** | `self.call` — a class method, never instantiated |
+| **Arguments** | All inputs passed as **keyword arguments** for clarity at the call site |
+| **Return value** | None expected. These are fire-and-forget side-effect methods |
+| **Single responsibility** | One output concern per class. If a method prints a banner, that's one class. If it prints an iteration summary, that's another |
+| **Grouping** | Related output classes may be grouped under a nested module in a single file (e.g. `Output::Iteration::Header`, `Output::Iteration::Summary`, `Output::Iteration::Error` all live in `iteration.rb`) |
+| **No base class** | Plain `Object` inheritance. No shared superclass or included module required |
+
+## Output Channels
+
+Use the appropriate channel based on the nature of the output:
+
+| Channel | Ruby method | When to use |
+|---------|-------------|-------------|
+| **stdout** | `puts` | Informational output: banners, summaries, progress, status |
+| **stderr** | `warn` or `$stderr.puts` | Warnings, errors, and diagnostics that should not pollute stdout |
+
+`warn` is preferred over `$stderr.puts` for single-line warnings because it respects Ruby's `-W` flag and is idiomatic.
+
+## Requiring & Usage
+
+Output classes are required where they are used, not auto-loaded:
+
+```ruby
+require_relative "output/no_plugin_warning"
+
+# Later, at the call site:
+Output::NoPluginWarning.call(chosen_agent: @agent_config.type)
+```
+
+There is no `lib/ralph/output.rb` barrel file. Each class is required individually by the code that needs it.
+
+## Reference Implementation
+
+`lib/ralph/output/no_plugin_warning.rb` is the canonical example:
+
+```ruby
+module Ralph
+  module Output
+    class NoPluginWarning
+      def self.call(chosen_agent:)
+        case chosen_agent
+        when :claude_code
+          warn "Warning: --no-plugins has no effect with Claude Code agent"
+        when :codex
+          warn "Warning: --no-plugins has no effect with Codex agent"
+        end
+      end
+    end
+  end
+end
+```
+
+Key things to note:
+
+- The class decides **what** to print based on its arguments (the `case` on `chosen_agent`).
+- The caller does not need to know the message text — it passes data, and the output class formats it.
+- The caller (`Loop#call` in `lib/ralph/loop.rb`) reads as `Output::NoPluginWarning.call(chosen_agent: ...)` — intent is clear at the call site.
+
+## Formatting Conventions
+
+- **Box-drawing characters** (`═`, `║`, `╔`, `╗`, `╚`, `╝`, `─`) are used for prominent banners and completion boxes.
+- **Unicode symbols** (checkmarks, warning signs, emoji) are used sparingly for status indicators.
+- **Line width** is 68 characters for horizontal rules and box borders.
+- Formatting logic lives inside the output class, not at the call site.

data/specs/storage/local-data-structure.md

@@ -0,0 +1,246 @@
+# Ralph Storage Architecture Specification
+
+## Overview
+
+The Ralph autonomous agent maintains persistent state across sessions through a modular storage system. All state is stored in the `.ralph/` directory within the project root, providing persistence for autonomous coding sessions, iteration history, context management, and task tracking.
+
+## File Structure
+
+### Root Directory Layout
+```
+.ralph/
+├── ralph-loop.state.json     # Main loop state
+├── ralph-history.json         # Complete iteration history  
+├── ralph-context.md           # Persistent AI context
+├── ralph-tasks.md             # Task management
+└── ralph-opencode.config.json # OpenCode plugin configuration
+```
+
+## Storage Module Architecture
+
+### Directory Structure
+```
+lib/ralph/storage/
+├── history.rb      # Ralph::Storage::History class
+├── state.rb        # Ralph::Storage::State class  
+├── context.rb      # Ralph::Storage::Context class
+├── tasks.rb        # Ralph::Storage::Tasks class + Task/Tasks models
+└── .               # Main storage module file
+```
+
+### Module Organization
+
+#### Ralph::Storage::History
+**Purpose**: Manages complete iteration history across Ralph sessions.
+
+**Responsibilities**:
+- Save/load iteration history to `.ralph/ralph-history.json`
+- Track struggle indicators and performance metrics
+- Maintain chronology of all iterations
+- Provide history analytics
+
+**Data Structure**:
+```ruby
+RalphHistory = Struct.new(
+  :iterations,          # Array<IterationHistory>
+  :total_duration_ms,   # Integer
+  :struggle_indicators, # StruggleIndicators
+  keyword_init: true
+)
+
+IterationHistory = Struct.new(
+  :iteration,           # Integer
+  :started_at,          # String (ISO 8601)
+  :ended_at,            # String (ISO 8601) 
+  :duration_ms,         # Integer
+  :tools_used,          # Hash<String, Integer>
+  :files_modified,      # Array<String>
+  :exit_code,           # Integer
+  :completion_detected, # Boolean
+  :errors               # Array<String>
+)
+```
+
+**File Format**: JSON with iteration data, total duration, and struggle indicators.
+
+#### Ralph::Storage::State
+**Purpose**: Manages the active loop state for current Ralph session.
+
+**Responsibilities**:
+- Save/load loop state to `.ralph/ralph-loop.state.json`
+- Track session metadata (iteration count, timing, configuration)
+- Handle session lifecycle (start, stop, resume)
+- File change detection via git snapshots
+- OpenCode configuration management
+
+**Data Structure**:
+```ruby
+RalphState = Struct.new(
+  :active,              # Boolean
+  :iteration,           # Integer
+  :min_iterations,      # Integer
+  :max_iterations,      # Integer
+  :completion_promise,  # String
+  :tasks_mode,          # Boolean
+  :task_promise,        # String
+  :prompt,              # String
+  :started_at,          # String (ISO 8601)
+  :model,               # String
+  :agent,               # String
+  keyword_init: true
+)
+```
+
+**File Format**: JSON with loop configuration and session state.
+
+**Additional Features**:
+- `capture_file_snapshot()` - Git-based file state tracking
+- `modified_files_since_snapshot()` - Change detection
+- `ensure_ralph_config()` - OpenCode plugin configuration
+- `load_plugins_from_config()` - Plugin discovery from config files
+
+#### Ralph::Storage::Context
+**Purpose**: Manages persistent AI context for maintaining conversational continuity.
+
+**Responsibilities**:
+- Load context from `.ralph/ralph-context.md`
+- Clear context when sessions end
+- Provide context for AI prompt building
+
+**File Format**: Markdown file with structured context sections.
+
+#### Ralph::Storage::Tasks
+**Purpose**: Manages task tracking and workflow coordination.
+
+**Responsibilities**:
+- Save/load tasks to `.ralph/ralph-tasks.md`
+- Parse and render task lists in markdown format
+- Track task status (todo, in_progress, complete)
+- Handle subtasks and task hierarchy
+- Provide task analytics and display methods
+
+**Data Structures**:
+```ruby
+Task = Struct.new(
+  :text,              # String
+  :status,            # Symbol (:todo, :in_progress, :complete)
+  :subtasks,          # Array<Task>
+  :original_line,     # String (for round-trip preservation)
+  keyword_init: true
+)
+
+Tasks = Enumerable collection of Task objects
+```
+
+**File Format**: Markdown with checkbox syntax:
+```markdown
+# Ralph Tasks
+
+- [ ] Task 1 description
+- [/] Task 2 in progress
+  - [ ] Subtask 2.1
+  - [x] Subtask 2.2
+- [x] Task 3 complete
+```
+
+## State Persistence Patterns
+
+### Atomic Operations
+All write operations use atomic file writing to prevent corruption:
+- Write to temporary file first
+- Rename/replace original file atomically
+- Handle filesystem errors gracefully
+
+### Error Handling
+- All load operations handle missing files gracefully
+- JSON parsing errors return empty/default states
+- Filesystem errors are caught and logged
+- State corruption recovery with fallback to empty state
+
+### Directory Management
+- `.ralph/` directory created automatically when needed
+- Directory permissions set appropriately
+- Cleanup operations preserve important state files
+
+## Configuration Integration
+
+### OpenCode Configuration
+Storage::State manages OpenCode plugin configuration through:
+- `.ralph/ralph-opencode.config.json` - Generated config file
+- User config discovery: `~/.config/opencode/opencode.json`
+- Project config discovery: `.ralph/opencode.json` or `.opencode/opencode.json`
+- Plugin filtering and permission management
+
+### Config File Format
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["auth-plugin"],
+  "permission": {
+    "read": "allow",
+    "edit": "allow",
+    // ... all tool permissions
+  }
+}
+```
+
+## Migration Strategy
+
+### Backward Compatibility
+The original `State` module in `lib/ralph/state.rb` remains as a thin wrapper:
+- Requires the new Storage module
+- Delegates all existing methods to appropriate Storage classes
+- Maintains identical public interface
+- No functional changes to existing code
+
+### Update Dependencies
+Files requiring state management will need minimal updates:
+- Add `require_relative "storage"` where needed
+- All existing `State.method` calls continue to work unchanged
+- Gradual migration to use Storage classes directly is optional
+
+## Data Lifecycle
+
+### Session Start
+1. Load existing state from `.ralph/ralph-loop.state.json`
+2. Check for active sessions (prevent concurrent loops)
+3. Load history and context
+4. Initialize new session state if needed
+5. Create task file if tasks mode enabled
+
+### During Session
+1. Update state after each iteration
+2. Append to history with iteration results
+3. Track file changes via git snapshots
+4. Update context as needed
+
+### Session End
+1. Clear active state flag
+2. Save final history and state
+3. Optionally clear context (based on configuration)
+4. Cleanup temporary files
+
+### Error Recovery
+1. Automatic state clearing on crashes/interrupts
+2. History preservation through graceful degradation
+3. Context recovery from last good state
+4. Task file preservation across all scenarios
+
+## Security Considerations
+
+### File Permissions
+- `.ralph/` directory permissions restricted to owner
+- Sensitive configuration files protected appropriately
+- No world-readable state files
+
+### Data Sanitization
+- JSON validation on all loaded data
+- Markdown sanitization for context/tasks
+- Plugin configuration validation
+- Safe handling of file paths and content
+
+### Integrity Checks
+- JSON schema validation for structured data
+- File content checksums where appropriate
+- Consistency checks between related files
+- Recovery procedures for corrupted state

data/specs/tasks.md

@@ -0,0 +1,295 @@
+# Task Management Specification
+
+Task management lets Ralph break large projects into discrete units of work tracked in a markdown file. Instead of sending the entire project goal every iteration, Ralph focuses the agent on one task at a time, advancing through the list as each task is completed. This reduces per-iteration context size, improves agent focus, and lowers cost.
+
+## File Format
+
+Tasks are stored in `.ralph/ralph-tasks.md`. The file uses markdown checkbox syntax with three status characters.
+
+### Status Characters
+
+| Character | Symbol | Status | Meaning |
+|-----------|--------|--------|---------|
+| ` ` (space) | `[ ]` | `:todo` | Not started |
+| `/` | `[/]` | `:in_progress` | Currently being worked on |
+| `x` | `[x]` | `:complete` | Finished |
+
+### Structure
+
+```markdown
+# Ralph Tasks
+
+- [ ] First task description
+- [/] Second task (in progress)
+  - [ ] Subtask A
+  - [x] Subtask B
+- [x] Third task (complete)
+```
+
+**Rules:**
+
+- Top-level tasks start at column 0 with `- [<status>] <text>`.
+- Subtasks are indented with two spaces followed by the same `- [<status>] <text>` pattern.
+- Subtasks are **single-level only** — no nesting subtasks under subtasks.
+- The `# Ralph Tasks` header is written on save but not required for parsing.
+- Lines that do not match the task pattern are ignored during parsing.
+
+### Round-Trip Preservation
+
+Each `Task` stores its `original_line` (the raw line from disk). This is used for diagnostics and debugging. On save, the canonical `- [<status>] <text>` format is always written, so whitespace and formatting are normalized.
+
+## Data Models
+
+### `Ralph::Storage::Task`
+
+Represents a single task (top-level or subtask).
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `text` | `String` | Task description text |
+| `status` | `Symbol` | One of `:todo`, `:in_progress`, `:complete` |
+| `subtasks` | `Array<Task>` | Child tasks (empty for subtasks themselves) |
+| `original_line` | `String` or `nil` | Raw line from disk, for diagnostics |
+
+**Status query methods:**
+
+- `todo?` — true when status is `:todo`
+- `in_progress?` — true when status is `:in_progress`
+- `complete?` — true when status is `:complete`
+
+**Status mutation methods:**
+
+- `mark_todo!` — sets status to `:todo`
+- `mark_in_progress!` — sets status to `:in_progress`
+- `mark_complete!` — sets status to `:complete`
+- `toggle_status` — cycles `:todo` → `:in_progress` → `:complete` → `:todo`
+
+**Serialization:**
+
+`to_s` returns the canonical line: `- [<status_char>] <text>`
+
+### `Ralph::Storage::TasksCollection`
+
+An `Enumerable` collection of top-level `Task` objects.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `each` | `(&block)` | Yields each top-level task |
+| `empty?` | `-> Boolean` | True when collection has no tasks |
+| `length` | `-> Integer` | Number of top-level tasks |
+| `any?` | `-> Boolean` | True when collection has at least one task |
+| `add` | `(Task) -> self` | Appends a task to the collection |
+| `remove_at` | `(Integer) -> Task` | Removes task at 1-based index; raises `IndexError` if out of range |
+| `current` | `-> Task or nil` | First task with `:in_progress` status |
+| `next` | `-> Task or nil` | First task with `:todo` status |
+| `all_complete?` | `-> Boolean` | True when non-empty and every task is `:complete` |
+
+**Class methods:**
+
+- `TasksCollection.parse(content)` — Parses a markdown string into a `TasksCollection`. Handles top-level tasks and single-level subtasks. Returns a new collection (empty if no tasks found).
+
+**Display:**
+
+- `display_with_indices` — Prints a numbered list of tasks with status icons to stdout. Used by the `--list-tasks` subcommand.
+
+**Status icons** (for display only):
+
+| Status | Icon |
+|--------|------|
+| `:complete` | `✅` |
+| `:in_progress` | `🔄` |
+| `:todo` | `⏸️` |
+
+## Storage
+
+### `Ralph::Storage::Tasks`
+
+Manages the task file on disk. Always instantiate with `Tasks.new`.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `load_tasks` | `-> TasksCollection or nil` | Reads and parses `.ralph/ralph-tasks.md`. Returns `nil` if the file does not exist or cannot be parsed. |
+| `save_tasks` | `(TasksCollection) -> void` | Writes the collection to `.ralph/ralph-tasks.md` with the `# Ralph Tasks` header. Writes top-level tasks and their subtasks. |
+| `clear_tasks` | `-> void` | Deletes the tasks file if it exists. Silently ignores errors. |
+| `tasks_exist?` | `-> Boolean` | True when `.ralph/ralph-tasks.md` exists on disk. |
+| `add_task` | `(String) -> Task` | Loads existing tasks (or creates a new collection), appends a new `:todo` task, saves, and returns the new task. |
+| `remove_task` | `(Integer) -> Task` | Removes the task at the given 1-based index. Raises `RuntimeError` if no tasks file exists. Raises `IndexError` if the index is out of range. |
+| `initialize_tasks_file` | `-> String` | Creates a starter tasks file with a header and usage hint. Returns the file path. |
+
+**Class methods:**
+
+- `Tasks.dir` — Returns the `.ralph/` directory path (relative to `Dir.pwd`).
+- `Tasks.path` — Returns the full path to `ralph-tasks.md`.
+
+**Directory management:** The constructor creates `.ralph/` if it does not exist.
+
+## Task Lifecycle in the Loop
+
+When `--tasks` (or `-t`) is enabled, the loop coordinates task progression across iterations.
+
+### Task Selection
+
+Each iteration, the prompt builder determines the current focus:
+
+1. **Find in-progress task:** Look for the first task with status `[/]` (`:in_progress`). If found, this is the current task.
+2. **Find next todo task:** If no in-progress task, look for the first task with status `[ ]` (`:todo`). This becomes the next task to start.
+3. **All complete:** If every task is `[x]` (`:complete`), instruct the agent to output the completion promise.
+4. **No tasks:** If the collection is empty, instruct the agent to add tasks.
+
+### Status Transitions
+
+The agent is responsible for updating task statuses in `.ralph/ralph-tasks.md` directly. The prompt instructs the agent to follow this workflow:
+
+```
+[ ] todo  →  [/] in progress  →  [x] complete
+```
+
+1. Before starting work: mark the task as `[/]` in the file.
+2. After verifying the task is done: mark it as `[x]` in the file.
+3. Output `<promise>READY_FOR_NEXT_TASK</promise>` to signal task completion.
+
+Ralph does not programmatically modify task statuses between iterations. The agent owns the file.
+
+### Task Promise Detection
+
+When the loop detects `<promise>READY_FOR_NEXT_TASK</promise>` (or the value of `--task-promise`) in agent output:
+
+- The loop prints a task completion message via `Output::TaskCompletion`.
+- The next iteration's prompt will pick up the updated task file, find the next `[ ]` task, and continue.
+
+The task promise does **not** stop the loop. It is informational — the loop continues to the next iteration.
+
+### Completion Promise in Tasks Mode
+
+The completion promise (`<promise>COMPLETE</promise>` by default) is only accepted when the agent has signaled that all tasks are done. The prompt instructs the agent to only output the completion promise when every task in the file is `[x]`.
+
+### Tasks File Creation
+
+When `--tasks` is enabled and no tasks file exists:
+
+- The prompt builder includes instructions telling the agent to create the file or use `ralph --add-task`.
+- Alternatively, the user can pre-populate the file with `ralph --add-task "description"` before starting the loop.
+- `initialize_tasks_file` creates a starter file with a header and usage hint.
+
+## Prompt Integration
+
+The `Prompt` class builds task-aware prompts when `state.tasks_mode` is true.
+
+### Task-Mode Prompt Structure
+
+```
+# Ralph Wiggum Loop - Iteration N
+
+You are in an iterative development loop working through a task list.
+
+[Additional Context section, if present]
+
+## TASKS MODE: Working through task list
+
+Current tasks from .ralph/ralph-tasks.md:
+```markdown
+[full contents of ralph-tasks.md]
+```
+
+[Task instructions — one of four states]
+
+### Task Workflow
+1. Find any task marked [/] (in progress). If none, pick the first [ ] task.
+2. Mark the task as [/] in ralph-tasks.md before starting.
+3. Complete the task.
+4. Mark as [x] when verified complete.
+5. Output <promise>READY_FOR_NEXT_TASK</promise> to move to the next task.
+6. Only output <promise>COMPLETE</promise> when ALL tasks are [x].
+
+---
+
+## Your Main Goal
+
+[user's prompt text]
+
+## Critical Rules
+
+[rules about one task at a time, promise usage, honesty]
+
+## Current Iteration: N / M (min: K)
+
+Tasks Mode: ENABLED - Work on one task at a time from ralph-tasks.md
+```
+
+### Four Task Instruction States
+
+The prompt builder selects one instruction block based on the current task state:
+
+| State | Condition | Instruction |
+|-------|-----------|-------------|
+| Current task exists | `tasks.current` returns a task | Focus on completing the in-progress task. When done, mark as `[x]` and output the task promise. |
+| Next task available | No in-progress task, `tasks.next` returns a task | Mark the next task as `[/]` before starting. When done, mark as `[x]` and output the task promise. |
+| All tasks complete | `tasks.all_complete?` is true | All tasks done. Output the completion promise to finish. |
+| No tasks found | Collection is empty | Add tasks to the file or use `ralph --add-task`. |
+
+### Error State
+
+If the tasks file cannot be read (parse error, permissions, etc.), the prompt builder falls back to a short error message:
+
+```
+## TASKS MODE: Error reading tasks file
+
+Unable to read .ralph/ralph-tasks.md
+```
+
+## CLI Subcommands
+
+These subcommands are fire-and-exit — they perform their action and exit without starting the loop. See also [cli.md](./cli.md) for the full CLI specification.
+
+### `--list-tasks`
+
+Loads and displays tasks from `.ralph/ralph-tasks.md` with numbered indices and status icons.
+
+- If no tasks file exists, prints a message and exits.
+- Uses `TasksCollection#display_with_indices`.
+
+### `--add-task DESC`
+
+Appends a new `- [ ] DESC` task to the file.
+
+- Creates the file with a `# Ralph Tasks` header if it does not exist.
+- Requires a non-empty description argument.
+
+### `--remove-task N`
+
+Removes the task at 1-based index N, including its subtasks.
+
+- Requires an integer argument.
+- Validates the index is in range `1..task_count`.
+- Raises if no tasks file exists.
+
+## Consumers
+
+| Consumer | What it uses | How |
+|----------|-------------|-----|
+| `Loop#run` | `check_completion` with `task_promise` | Detects `<promise>READY_FOR_NEXT_TASK</promise>` in agent output and prints task completion message |
+| `Prompt#task_mode_prompt` | `Storage::Tasks`, `TasksCollection.parse` | Reads task file, determines current/next task, builds task-aware prompt |
+| `Prompt#build_tasks_section` | `TasksCollection#current`, `#next`, `#all_complete?` | Selects the appropriate task instruction block |
+| `CLI` | `Storage::Tasks#add_task`, `#remove_task`, `#load_tasks` | Implements `--add-task`, `--remove-task`, `--list-tasks` subcommands |
+| `Output::Status` | `Storage::Tasks#load_tasks` | Displays task progress in the `--status` dashboard |
+| `Output::TaskCompletion` | — | Prints task completion message when task promise is detected |
+| `Output::TasksFileCreated` | — | Prints confirmation when the tasks file is initialized |
+
+## Testing Strategy
+
+### Unit Tests
+
+- **Parsing:** Test `TasksCollection.parse` with:
+  - Empty string, header-only, single task, multiple tasks, subtasks, mixed statuses
+  - Lines that do not match the task pattern (ignored)
+  - Malformed status characters (treated as todo)
+- **Models:** Test `Task` status queries, mutations, `toggle_status`, `to_s`
+- **Collection:** Test `add`, `remove_at` (valid index, out of range), `current`, `next`, `all_complete?`, `empty?`
+- **Storage:** Test `load_tasks`, `save_tasks` round-trip, `add_task`, `remove_task`, `clear_tasks`, `tasks_exist?`, `initialize_tasks_file`
+
+### Integration Tests
+
+- **Loop integration:** Test that task promise detection in agent output triggers `Output::TaskCompletion` and continues the loop
+- **Prompt integration:** Test that the prompt builder includes the correct task instructions for each of the four task states
+- **CLI subcommands:** Test `--list-tasks`, `--add-task`, `--remove-task` end-to-end with a real tasks file
+- **File creation:** Test that `--tasks` mode works when no tasks file exists (agent or user creates it)