* feat(structure): migrate Ralph files to .ralph/ subfolder
BREAKING CHANGE: Ralph configuration files now live in .ralph/ subfolder
This refactoring moves all Ralph-specific files into a hidden .ralph/
directory while keeping src/ at the project root. This improves
compatibility with existing tooling and keeps the project root clean.
Changes:
- Move PROMPT.md, @fix_plan.md, @AGENT.md to .ralph/
- Move specs/, logs/, docs/generated/, examples/ to .ralph/
- Move state files (.response_analysis, .circuit_breaker_state, etc.) to .ralph/
- Keep src/ at project root (unchanged)
- Add RALPH_DIR=".ralph" configuration variable
- Add ralph-migrate command for existing projects
- Create migrate_to_ralph_folder.sh migration script
- Update all path references in scripts and tests
- Update documentation (README.md, CLAUDE.md)
New project structure:
project/
├── .ralph/ # Ralph configuration
│ ├── PROMPT.md
│ ├── @fix_plan.md
│ ├── @AGENT.md
│ ├── specs/
│ ├── logs/
│ └── docs/generated/
└── src/ # Source code (unchanged)
Migration: Run `ralph-migrate` in existing projects to upgrade.
All 310 tests pass (100% pass rate).
* chore: add .claude/settings.local.json to .gitignore
* fix: address code review feedback for .ralph/ subfolder structure
Fixes multiple path-related issues identified in code review:
Test fixes:
- Fix create_sample_prompt to use $RALPH_DIR/PROMPT.md in test_session_continuity.bats
- Fix result_file path to use $RALPH_DIR/.json_parse_result in test_json_parsing.bats
- Fix @fix_plan.md and .response_analysis paths in test_cli_modern.bats
- Update templates directory missing test to account for global fallback
Template fix:
- Fix @fix_plan.md reference in templates/PROMPT.md to use .ralph/ prefix
Script fixes:
- Fix PROMPT_FILE comparison in ralph_loop.sh to use $RALPH_DIR/PROMPT.md
- Fix examples migration logic in migrate_to_ralph_folder.sh (remove premature mkdir)
- Move templates directory check AFTER cd in setup.sh (was checking wrong location)
- Add template directory validation with fallback to global templates
All 310 tests pass.
* Update migrate_to_ralph_folder.sh
Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
* fix: address code review feedback for .ralph/ subfolder structure
Code Review Fixes:
- Fix test_json_parsing.bats: all result_file and session file paths now use $RALPH_DIR prefix
- Fix ralph_loop.sh help text: paths now show .ralph/.ralph_session, .ralph/.call_count, etc.
- Fix migrate_to_ralph_folder.sh:
- Proper error handling for date command (separate local declaration)
- Use cp -a source/. dest/ pattern to preserve dotfiles and attributes
- Remove 2>/dev/null suppression to surface copy errors
- Update create_files.sh to use .ralph/ structure for embedded scripts
- Update .gitignore with all .ralph/ state file paths
- Add old structure detection in ralph_loop.sh with helpful migration message
Version Update:
- Bump to v0.10.0 (breaking change: structural reorganization)
- Update README.md and CLAUDE.md with new version and release notes
- Add ralph-migrate documentation to Key Commands section
All 310 tests pass.
---------
Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
* feat(timeout): add cross-platform timeout support for macOS
Add portable timeout wrapper that automatically detects and uses the
appropriate timeout command based on the platform:
- Linux: Uses standard GNU `timeout` from coreutils
- macOS: Uses `gtimeout` from Homebrew coreutils
Changes:
- Add lib/timeout_utils.sh with detect_timeout_command() and
portable_timeout() functions
- Update ralph_loop.sh to source timeout_utils.sh and use
portable_timeout for Claude Code execution
- Update install.sh to check for coreutils on macOS and provide
installation instructions
- Update test mocks to include gtimeout and portable_timeout
- Update README.md with macOS coreutils installation instructions
- Update CLAUDE.md with timeout_utils.sh documentation
Users on macOS now need to install coreutils: brew install coreutils
* Update model reference in opencode-review workflow
* Update model name in opencode-review workflow
* Update model version in opencode-review workflow
* Update model version in opencode-review workflow
* Update lib/timeout_utils.sh
Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
* Update opencode-review.yml
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
* Reapply "feat(session): implement session expiration with configurable timeout (#83)"
This reverts commit 1ba55a4b9c.
* fix(session): address code review feedback
- Fix integer overflow: return -1 from get_session_file_age_hours on stat
failure instead of 0, preventing false expiration
- Handle stat failure in init_claude_session with WARN log
- Add comprehensive documentation for return values and expiration strategy
- Add 6 behavioral integration tests that verify actual functionality
- Add inline comments explaining 24-hour default rationale
Test count: 286 → 292 (100% pass rate)
* fix(test): use grep-based verification to fix CI failures
Tests that sourced ralph_loop.sh with --help flag failed in GitHub
Actions due to BATS environment differences. Changed behavioral tests
to grep-based code verification that checks implementation patterns
exist without executing the script.
* fix(test): guard main with BASH_SOURCE for safe sourcing
- Add BASH_SOURCE check to only execute main when script is run directly
- Update tests to source script without --help flag
- Convert grep-based verification tests back to functional tests
- Fixes CI failures caused by script execution during sourcing
---------
Co-authored-by: Test User <test@example.com>
- Add CLAUDE_SESSION_EXPIRY_HOURS configuration variable (default: 24)
- Add get_session_file_age_hours() helper with cross-platform stat support
- Modify init_claude_session() to check session age and remove expired sessions
- Add --session-expiry CLI flag to configure expiration (positive integers only)
- Update help text with new option and example
- Add 10 new tests for session expiration (TDD approach)
Closes#51
Test count: 276 → 286 (100% pass rate)
Co-authored-by: Test User <test@example.com>
- Add --output-format json flag for structured Claude CLI responses
- Implement detect_response_format() for JSON vs text detection
- Implement parse_conversion_response() for extracting JSON fields
- Add check_claude_version() for modern CLI feature detection
- Enhance error handling with structured JSON error messages
- Improve file verification with JSON-derived status information
- Maintain backward compatibility with automatic text fallback
- Add 11 new TDD tests for modern CLI features (tests 23-33)
- Update README.md with Modern CLI Features section
- Update CLAUDE.md with v0.9.8 release notes
Test count: 276 (up from 265)
- Fix BSD date parsing to handle milliseconds in ISO timestamps
(e.g., 2026-01-09T10:30:00.123+00:00)
- Document error_count mapping behavior when only has_errors=true is present
- Remove unused has_session_id_field variable
- Add debug logging for session persistence (controlled by VERBOSE_PROGRESS)
- Standardize session filename to .claude_session_id across all files
All 239 tests passing.
- Extend parse_json_response() to support both flat and Claude CLI formats
- Extract result, sessionId, and metadata fields
- Support metadata.files_changed, metadata.has_errors, completion_status
- Parse progress_indicators array for confidence boosting
- Add session management functions for continuity tracking:
- store_session_id(): Persist session with ISO timestamp
- get_last_session_id(): Retrieve stored session ID
- should_resume_session(): Check session validity (24-hour expiration)
- Add get_epoch_seconds() to date_utils.sh for cross-platform epoch time
- Auto-persist sessionId to .session_id file during response analysis
- Add 16 new TDD tests for Claude CLI format and session management
- Update documentation for v0.9.6 (239 tests total)
Test count: 239 (up from 223)
- Remove unused 'load mocks' (mocks.bash not needed)
- Use GIT_AUTHOR_*/GIT_COMMITTER_* env vars instead of git config --global
- Prefix git commands with 'command' to bypass shell function overrides
- Fix tautological assertions in edge case tests:
- Rename test to "succeeds when run in existing directory (idempotent)"
- Assert success ($status -eq 0) instead of always-true condition
README.md:
- Update version badge to v0.9.3
- Update test count to 165 in all locations
- Update test coverage breakdown (111 unit + 54 integration)
test_installation.bats:
- Add missing mock setup.sh in setup() function
- Fix dependency test to mock all three deps (jq, git, node/npx)
- Remove unused source_install_functions helper function
- Add test_installation.bats with full coverage of install.sh
- Tests cover directory creation, command installation, permissions
- Template and lib file copying verification
- Dependency detection with mocked failures (jq, git, node)
- PATH detection and warning system tests
- Uninstallation cleanup verification
- Idempotency testing (run twice without errors)
- End-to-end installation workflow validation
- All tests use isolated temp directories for safety
- Update CLAUDE.md with new test count (165 total)
- Fix npm test script to run tests recursively
- Version bump to v0.9.3
The build_claude_command() function was incorrectly using --prompt-file
which doesn't exist in Claude Code CLI. This fix:
- Replaces --prompt-file with -p flag plus prompt content
- Reads prompt content via $(cat "$prompt_file") before execution
- Adds error handling for missing prompt files
- Maintains shell injection safety through array-based command building
- Updates comments to reflect the correct approach
Adds 6 TDD tests verifying the fix:
- Uses -p flag instead of --prompt-file
- Reads prompt file content correctly
- Handles missing prompt file
- Includes all modern CLI flags
- Handles multiline prompt content
- Prevents shell injection
Test count: 145 -> 151 (all passing)
Address code review finding by adding dedicated test for
--allowed-tools flag validation.
Add code review report documenting:
- 0 critical issues
- 0 major issues
- 1 minor issue (addressed in this commit)
- 6 positive findings
Test count: 27 CLI parsing tests (105 total unit tests)
Refs #10
Add 26 new BATS tests validating all CLI flags in ralph_loop.sh:
- Help flag tests (2): --help, -h short flag
- Flag value tests (6): --calls, --prompt, --monitor, --verbose, --timeout
- Status flag tests (2): --status with/without status.json
- Circuit breaker tests (2): --reset-circuit, --circuit-status
- Invalid input tests (3): unknown flag, invalid timeout, invalid format
- Multiple flags tests (3): combinations, all flags, early exit
- Flag order tests (2): verify order independence
- Short flag tests (6): -c, -p, -s, -m, -v, -t equivalence
Test strategy uses --help as early-exit escape to validate parsing
without triggering main loop execution.
Closes#10
Implements Issue #28 - modernize CLI commands for better Claude integration.
Key changes:
- Add JSON output format support with --output-format flag (default: json)
- Add session continuity with --continue flag and .claude_session_id file
- Add tool permissions via --allowed-tools flag
- Add build_loop_context() for loop-aware context injection
- Add detect_output_format() and parse_json_response() for JSON parsing
- Maintain backward compatibility with text output fallback
- Add version checking with check_claude_version()
New CLI options:
- --output-format json|text: Control Claude output format
- --allowed-tools "Write,Read,Bash(git *)": Restrict tool permissions
- --no-continue: Disable session continuity
Test coverage:
- 20 new JSON parsing tests (test_json_parsing.bats)
- 23 new CLI modern tests (test_cli_modern.bats)
- All 98 tests passing (100% pass rate)
Addresses CodeRabbit outside diff range comment on lines 268-283:
CRITICAL BUG:
The detect_stuck_loop function had a multi-line string handling bug where
only the first error line was checked against historical outputs when
multiple distinct errors were present.
Problem:
grep -q "$current_errors" file.log
# When $current_errors has multiple lines, grep only matches first line
Impact:
Stuck loops with multiple recurring errors would not be detected correctly,
potentially allowing Ralph to continue running despite being genuinely stuck.
Fix:
Changed from simple grep to nested loop checking:
- For each historical output file
- For each error line in current output
- ALL error lines must appear in that file
- Only returns "stuck" if ALL files contain ALL current errors
Used grep -qF for literal fixed-string matching (not regex) to avoid
edge cases with special characters in error messages.
Test Coverage:
Added 2 new test scenarios (7 → 9 total tests):
Test 8: Multiple distinct errors where ALL repeat across history
Current: Error: Build failed + Fatal: DB lost + Exception: NPE
History: All 3 files contain all 3 errors
Expected: Stuck detected ✅
Test 9: Multiple errors where only some repeat
Current: Error: Build failed + Fatal: DB lost
History: Only first error appears consistently
Expected: Not stuck ✅
All existing tests continue to pass, validating backward compatibility.
Test results:
✓ Error detection tests: 13/13 passing
✓ Stuck loop tests: 9/9 passing (was 7/7)
✓ Total: 22/22 tests passing
This ensures detect_stuck_loop correctly handles the real-world scenario
where Ralph gets stuck on multiple simultaneous recurring errors.
Addresses CodeRabbit review comment:
- Outside diff range (lines 268-283): Multi-line error matching bug
Addresses additional CodeRabbit findings in lib/response_analyzer.sh:
CRITICAL (line 267):
- Fixed detect_stuck_loop() to use two-stage filtering
- Was using naive grep -i "error\|failed" pattern
- Now filters JSON fields before extracting errors
- Pattern aligned with analyze_response() for consistency
DEAD CODE (line 18):
- Removed unused STUCK_INDICATORS array
- Array was defined but never referenced in code
- Reduces maintenance burden per coding guidelines
TEST COVERAGE:
- Added comprehensive test suite for detect_stuck_loop()
- New file: tests/test_stuck_loop_detection.sh
- 7 test scenarios validating:
* JSON fields don't trigger false stuck detection
* Actual repeated errors are correctly detected
* Type annotations are properly excluded
* Function returns appropriate exit codes
Test results:
✓ Error detection tests: 13/13 passing
✓ Stuck loop tests: 7/7 passing
✓ Total: 20/20 tests passing
This ensures both error detection functions (analyze_response and
detect_stuck_loop) use identical filtering logic, preventing circuit
breaker false positives across all code paths.
Addresses CodeRabbit review comments:
- Outside diff range comment: line 267 (Critical)
- Outside diff range comment: line 18 (Dead code)
- Outside diff range comment: lines 254-286 (Test coverage)
Aligns error detection patterns across all implementations and improves
test coverage based on CodeRabbit's critical and major findings.
Changes:
1. CRITICAL: Align lib/response_analyzer.sh pattern with ralph_loop.sh
- Changed Stage 1 filter from '"[^"]*\(error\|failed\)"[^"]*":' to '"[^"]*error[^"]*":'
- Removed bare 'cannot' and 'unable to' from Stage 2 (prevent false positives in prose)
- Both files now use identical patterns for consistency
2. MAJOR: Improved test coverage
- Renamed test 10 from "Cannot/unable in error context" to "Error prefix with descriptive message"
- Added test 10a to validate bare "cannot/unable" DON'T trigger false positives
- Now testing 13 scenarios (was 12)
3. MINOR: Added comprehensive test strategy documentation
- Header comments explain two-stage filtering approach
- Documents pattern consistency requirement
- Lists all 13 test scenarios and their purpose
Test results:
✓ All 13 tests passing
✓ Pattern consistency validated across ralph_loop.sh and lib/response_analyzer.sh
✓ False positive scenarios properly excluded
Addresses CodeRabbit review comments:
- r2655862688 (Critical pattern inconsistency)
- r2655862689 (Major test coverage gap)
- r2655862690 (Minor misleading test name)
Fixes circuit breaker opening prematurely due to naive error pattern matching
that treated JSON field names like "is_error": false as actual errors.
Changes:
- ralph_loop.sh: Implement two-stage error detection with JSON filtering
- lib/response_analyzer.sh: Apply same filtering to error counting
- tests/test_error_detection.sh: Add comprehensive test suite (12 scenarios)
Error detection now:
- Filters out JSON field patterns before searching for errors
- Uses context-specific patterns (^Error:, ]: error, Exception, Fatal)
- Avoids type annotations (error: Error) and code identifiers
- Includes debug logging when VERBOSE_PROGRESS=true
Test coverage validates:
✓ JSON fields don't trigger false positives
✓ Real error messages are correctly detected
✓ Mixed content handled properly
✓ Code diffs and documentation excluded
This prevents the consecutive_same_error counter from incrementing on
false positives, eliminating unnecessary circuit breaker trips.
