ralph.rb 1.2.4355354345 → 2.0.0

data/specs/iteration.md

@@ -1,173 +0,0 @@
-# Iteration Class Specification
-
-## Purpose
-
-The `Iteration` class is responsible for executing a single AI agent iteration and collecting metrics. It handles the low-level execution details while delegating business logic decisions to the caller.
-
-## Location
-
-`lib/ralph/iteration.rb`
-
-## Dependencies
-
-```ruby
-require_relative "types"
-require_relative "helpers"
-require_relative "state"
-```
-
-## Class Interface
-
-### Constructor
-
-```ruby
-def initialize(loop)
-```
-
-**Parameters:**
-- `loop` - `Ralph::Loop` instance. Provides access to:
-  - `loop.config` - `Ralph::Config` instance with all execution options (model, stream_output, verbose_tools, allow_all_permissions, disable_plugins, completion_promise, etc.)
-  - `loop.agent_config` - `Ralph::Agents::Base` instance providing command, build_args, build_env, etc. (see [agents.md](./agents.md))
-
-### Main Method
-
-```ruby
-def call(prompt, iteration_start:)
-```
-
-**Parameters:**
-- `prompt` - String containing the prompt to send to the agent
-- `iteration_start` - Integer timestamp (ms) when the iteration started
-
-**Returns:**
-- `IterationResult` struct with execution data
-
-## Result Type
-
-```ruby
-IterationResult = Struct.new(
-  :duration_ms,        # Integer - execution duration in milliseconds
-  :exit_code,          # Integer - agent process exit code
-  :stdout_text,        # String - agent stdout output
-  :stderr_text,        # String - agent stderr output
-  :tool_counts,        # Hash<String, Integer> - tool usage counts
-  :files_modified,     # Array<String> - list of files changed during iteration
-  :completion_detected, # Boolean - whether completion promise was found
-  :errors,             # Array<String> - extracted errors from output
-  :success             # Boolean - overall success (no crashes, exit_code == 0)
-)
-```
-
-## Internal Responsibilities
-
-### 1. Agent Execution
-- Build agent command using `agent_config.build_args` and `agent_config.build_env`
-- Execute agent (streaming or buffered based on options)
-- Capture stdout, stderr, exit code, and tool usage data
-- Handle agent process lifecycle
-
-### 2. Metrics Collection
-- Calculate execution duration from `iteration_start`
-- Extract tool counts from agent output using `agent_config.parse_tool_output`
-- Capture file snapshots before/after execution using `State.capture_file_snapshot`
-- Detect files modified via `State.modified_files_since_snapshot`
-
-### 3. Data Extraction
-- Combine stdout/stderr for analysis
-- Detect completion promise using `::Ralph::Helpers.check_completion`
-- Extract errors from combined output using `::Ralph::Helpers.extract_errors`
-- Determine overall success status
-
-### 4. Result Packaging
-- Assemble all collected data into `IterationResult`
-- Return structured result to caller
-
-## External Dependencies (Provided by Caller)
-
-The class expects the caller to handle:
-- **Prompt Building** - Creating the prompt text using `PromptBuilder`
-- **Output Display** - Showing iteration summaries, warnings, etc.
-- **History Management** - Recording iteration data in `RalphHistory`
-- **State Updates** - Managing loop state, iteration counters
-- **Completion Decisions** - Determining whether to continue or break loop
-- **Error Handling** - Deciding how to respond to iteration errors
-- **Post-Processing** - Auto-committing changes, consuming context
-
-## Error Handling
-
-The `Iteration` class handles:
-- Process execution errors (captures in result)
-- Stream processing errors (captures in result)
-- File operation errors for snapshots (gracefully degrades)
-- Agent process cleanup if errors occur
-
-It does NOT:
-- Display error messages (caller responsibility)
-- Modify loop state (caller responsibility)
-- Make retry decisions (caller responsibility)
-
-## Usage Example
-
-```ruby
-# In Loop class (Loop exposes attr_reader :config, :agent_config)
-iteration = Iteration.new(self)
-
-result = iteration.call(full_prompt, iteration_start: start_time)
-
-# Caller processes result
-Output::IterationSummary.call(
-  iteration: @state.iteration,
-  elapsed_ms: result.duration_ms,
-  tool_counts: result.tool_counts,
-  exit_code: result.exit_code,
-  completion_detected: result.completion_detected
-)
-
-# Caller updates history
-record_iteration_in_history(result)
-
-# Caller decides what to do next
-if result.completion_detected && @state.iteration >= @min_iterations
-  # Handle completion
-end
-```
-
-## Implementation Notes
-
-### Thread Safety
-The class holds a reference to the parent `Loop` instance and mutable streaming state. It is not intended for concurrent use across multiple loops.
-
-### Performance Considerations
-- File snapshot operations should be efficient (git-based)
-- Stream processing should handle large outputs without memory issues
-- Tool counting should be done efficiently via line-by-line processing
-
-### Extensibility
-New config values are automatically available to `Iteration` via `@loop.config` without constructor changes.
-The `IterationResult` struct can be extended with additional fields as needed.
-
-## Testing Strategy
-
-### Unit Tests
-- Mock `Open3` to test agent execution logic
-- Mock `State` methods to test file snapshot logic
-- Test completion detection with various output formats
-- Test error extraction from different types of output
-- Test tool counting with different agent output formats
-
-### Integration Tests
-- Test with actual agent binaries (if available in test environment)
-- Test file snapshot operations with git repositories
-- Test streaming vs buffered output modes
-- Test error scenarios (agent crashes, git operations fail)
-
-## Migration Path
-
-1. Create the new `Iteration` class with this interface
-2. Update `Loop` class to use `Iteration` for agent execution
-3. Move iteration-related private methods from `Loop` to `Iteration`
-4. Update `Loop` to process `IterationResult` instead of handling execution directly
-5. Remove redundant code from `Loop` class
-6. Add tests for the new `Iteration` class
-
-This refactoring will improve separation of concerns, testability, and maintainability of the iteration execution logic.

data/specs/output.md

@@ -1,104 +0,0 @@
-# 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

@@ -1,246 +0,0 @@
-# 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