diff --git a/README.md b/README.md index f4aacfb..ee8c6d0 100644 --- a/README.md +++ b/README.md @@ -36,28 +36,55 @@ Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code t ### Recent Improvements +**v0.9.8 - Modern CLI for PRD Import** +- Modernized `ralph_import.sh` to use Claude Code CLI JSON output format +- JSON output format support with `--output-format json` for structured responses +- Enhanced error handling with structured JSON error messages +- Improved file verification with JSON-derived status information +- Backward compatibility with older CLI versions (automatic text fallback) +- Added 11 new tests for modern CLI features +- Test count: 276 (up from 265) + +**v0.9.7 - Session Lifecycle Management** +- Complete session lifecycle management with automatic reset triggers +- Session auto-reset on: circuit breaker open, manual interrupt, project completion +- Added `--reset-session` CLI flag for manual session reset +- Session history tracking (last 50 transitions) for debugging +- Added 26 new tests for session continuity features + +**v0.9.6 - JSON Output & Session Management** +- Extended `parse_json_response()` to support Claude Code CLI JSON format +- Added session management functions: `store_session_id()`, `get_last_session_id()`, `should_resume_session()` +- Cross-platform epoch time utilities in date_utils.sh +- Added 16 new tests covering Claude CLI format and session management + +**v0.9.5 - PRD Import Tests** +- Added 22 comprehensive tests for `ralph_import.sh` PRD conversion script +- Tests cover: file format support, output file creation, project naming, error handling + +**v0.9.4 - Project Setup Tests** +- Added 36 comprehensive tests for `setup.sh` project initialization script +- Tests cover: directory creation, template copying, git initialization + +**v0.9.3 - Installation Tests** +- Added 14 comprehensive tests for `install.sh` global installation script +- Tests cover: directory creation, command installation, dependency detection + **v0.9.2 - Prompt File Fix** - Fixed critical bug: replaced non-existent `--prompt-file` CLI flag with `-p` flag - Modern CLI mode now correctly passes prompt content via `-p "$(cat file)"` - Added error handling for missing prompt files in `build_claude_command()` -- Added 6 new TDD tests for `build_claude_command` function -- Maintains shell injection safety through array-based command building **v0.9.1 - Modern CLI Commands (Phase 1.1)** - JSON output format support with `--output-format json` (default) - Session continuity using `--continue` flag for cross-loop context - Tool permissions via `--allowed-tools` flag -- Loop context injection with `build_loop_context()` function -- Backward-compatible: automatic fallback to text parsing -- 70 new tests: JSON parsing (20) + CLI modern (23) + CLI parsing (27) - CI/CD pipeline with kcov coverage reporting **v0.9.0 - Circuit Breaker Enhancements** - Fixed multi-line error matching in stuck loop detection - Eliminated JSON field false positives (e.g., `"is_error": false`) - Added two-stage error filtering for accurate detection -- Comprehensive test suite: 22 new tests for error detection -- Fixed installation to include lib/ directory components ### In Progress - Expanding test coverage @@ -74,6 +101,7 @@ Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code t - **Autonomous Development Loop** - Continuously executes Claude Code with your project requirements - **Intelligent Exit Detection** - Automatically stops when project objectives are complete +- **Session Continuity** - Preserves context across loop iterations with automatic session management - **Rate Limiting** - Built-in API call management with hourly limits and countdown timers - **5-Hour API Limit Handling** - Detects Claude's 5-hour usage limit and offers wait/exit options - **Live Monitoring** - Real-time dashboard showing loop status, progress, and logs @@ -297,6 +325,33 @@ ralph --verbose ralph --monitor --verbose --timeout 30 ``` +### Session Continuity + +Ralph maintains session context across loop iterations for improved coherence: + +```bash +# Sessions are enabled by default with --continue flag +ralph --monitor # Uses session continuity + +# Start fresh without session context +ralph --no-continue # Isolated iterations + +# Reset session manually (clears context) +ralph --reset-session # Clears current session + +# Check session status +cat .ralph_session # View current session file +cat .ralph_session_history # View session transition history +``` + +**Session Auto-Reset Triggers:** +- Circuit breaker opens (stagnation detected) +- Manual interrupt (Ctrl+C / SIGINT) +- Project completion (graceful exit) +- Manual circuit breaker reset (`--reset-circuit`) + +Sessions are persisted to `.ralph_session` with a 24-hour expiration. The last 50 session transitions are logged to `.ralph_session_history` for debugging. + ### Exit Thresholds Modify these variables in `~/.ralph/ralph_loop.sh`: @@ -381,7 +436,11 @@ bats tests/unit/test_exit_detection.bats bats tests/unit/test_json_parsing.bats bats tests/unit/test_cli_modern.bats bats tests/unit/test_cli_parsing.bats +bats tests/unit/test_session_continuity.bats bats tests/integration/test_loop_execution.bats +bats tests/integration/test_prd_import.bats +bats tests/integration/test_project_setup.bats +bats tests/integration/test_installation.bats # Run error detection and circuit breaker tests ./tests/test_error_detection.sh @@ -582,6 +641,7 @@ ralph [OPTIONS] --no-continue Disable session continuity (start fresh each loop) --reset-circuit Reset the circuit breaker --circuit-status Show circuit breaker status + --reset-session Reset session state manually ``` ### Project Commands (Per Project) @@ -593,6 +653,7 @@ ralph --status # Check current loop status ralph --verbose # Enable detailed progress updates ralph --timeout 30 # Set 30-minute execution timeout ralph --calls 50 # Limit to 50 API calls per hour +ralph --reset-session # Reset session state manually ralph-monitor # Manual monitoring dashboard ```