- Fix check_claude_version() to use numeric semantic version comparison
- Fix detect_response_format() to read first non-whitespace character
- Wire PARSED_RESULT into success message output
- Wire PARSED_FILES_CREATED into file verification logic
- Add --allowedTools flag to CLI invocation using CLAUDE_ALLOWED_TOOLS
- Separate stderr to avoid corrupting JSON output file
- Clean up stderr file on completion and error
- Update README.md version badges to v0.9.8 and 276 tests
- Update roadmap section with current test coverage breakdown
- 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 SC2155: separate declare from assign in get_session_id(),
log_session_transition(), init_session_tracking()
- Use jq for safe JSON generation in reset_session() and init_session_tracking()
instead of heredocs (prevents special character issues)
- Add corruption tolerance to log_session_transition() with JSON validation
and fallback to empty array on parse failures
- Add generate_session_id() to create unique session IDs (ralph-<epoch>-<random>)
- Add update_session_last_used() helper called on each loop iteration
- init_session_tracking() now generates unique session_id and sets last_used
- Add session files to .gitignore (.ralph_session, .ralph_session_history,
.claude_session_id)
All 265 tests pass.
- Add init_session_tracking() call in main() before loop starts
- Use literal escape codes for color in --reset-session output
- Remove conditional in reset_session() to always create file
- Remove unused old_session_id variable
- Remove duplicate SESSION_EXPIRATION_SECONDS (keep in response_analyzer.sh)
- Add clarifying comments for RALPH_SESSION_FILE vs CLAUDE_SESSION_FILE
All 265 tests pass.
- 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)
README.md:
- Update test count: 98 → 145 tests (accurate count from all 7 test files)
- Change coverage badge to informational (kcov subprocess limitation)
- Add CI/CD integration mention
- Add coverage note with link to bats-core#15
- Add --reset-circuit and --circuit-status to command reference
- Simplify formatting (remove emoji prefixes)
CLAUDE.md:
- Add version/test status line at top
- Add CI/CD Pipeline section documenting all 3 workflows
- Add Test Suite table with all 7 test files
- Add Running Tests section with npm/bats commands
- Document CLI parsing tests (27 new tests)
- Update Feature Completion Checklist with CI/CD requirement
- Add coverage note explaining kcov limitations
kcov cannot trace subprocess executions due to LD_PRELOAD limitations.
When bats runs tests, it spawns new bash processes that kcov cannot
instrument. This is a known, unsolved issue in bats-core (issue #15).
Changes:
- Set COVERAGE_THRESHOLD to 0 (disabled enforcement)
- Added detailed comment explaining the limitation
- Coverage job remains for informational purposes
- Test pass rate (100%) serves as the quality gate
References:
- https://github.com/bats-core/bats-core/issues/15
kcov spawns a subprocess that doesn't inherit the npm PATH, so
the 'bats' command wasn't found. Use the full path to the bats
binary in node_modules/.bin/ to fix coverage measurement.
Previous approach tried to download pre-built binaries that don't exist.
Now builds kcov from source with all required dependencies:
- cmake, g++ for compilation
- binutils-dev, libcurl4-openssl-dev, libdw-dev, libiberty-dev
- zlib1g-dev, libssl-dev
Also added better debugging output when coverage files not found.
Refs #10
kcov is not available in Ubuntu's default repositories. Update the
workflow to:
- Install kcov build dependencies
- Try downloading pre-built binary first
- Fall back to building from source if pre-built not available
- Add graceful handling for coverage measurement failures
Refs #10
Add coverage job to CI pipeline using kcov:
- Install kcov on Ubuntu runner
- Run BATS tests under kcov to collect coverage for ralph_loop.sh and lib/
- Generate HTML and JSON coverage reports
- Configurable threshold via COVERAGE_THRESHOLD env var (default: 70%)
- Set threshold to 0 to disable enforcement
- Upload coverage artifacts for inspection
- Optional Codecov integration
Coverage is measured separately from test execution to keep the
test job fast and isolate coverage concerns.
Refs #10
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
Replace two heredocs that write analysis results with jq construction
to prevent JSON injection via work_summary or other string fields.
Fixed locations:
- Line 205-235: JSON parsing path analysis result
- Line 351-381: Text parsing path analysis result
Both now use jq with --arg for strings and --argjson for numeric/boolean
fields, ensuring proper escaping of special characters.
Fixes three security issues identified in Phase 1.1 code review:
1. JSON injection in parse_json_response() (response_analyzer.sh:113-132)
- Replace heredoc with jq construction using --arg for strings
- Use --argjson for numeric/boolean fields
- Ensures proper escaping of quotes, newlines, backslashes
2. Input validation for --allowed-tools flag (ralph_loop.sh:903-905)
- Add VALID_TOOL_PATTERNS whitelist
- Add validate_allowed_tools() function
- Validate against whitelist in argument parsing
- Allow Bash(...) patterns with any content
3. Shell injection in build_claude_command() (ralph_loop.sh:439-444)
- Convert from string concatenation to command array
- Use global CLAUDE_CMD_ARGS array
- Execute with "${CLAUDE_CMD_ARGS[@]}" instead of bash -c
- No manual escaping needed - array handles metacharacters
All 98 tests passing.
Closes#48, #50
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)
Update all base directory documentation to accurately reflect current codebase state:
- IMPLEMENTATION_PLAN.md: Correct CI/CD status (operational), update test counts (75 actual),
clarify week completion status (1-2 + partial 5 complete)
- IMPLEMENTATION_STATUS.md: Add verification dates, detailed test breakdowns, updated remaining
work estimates, recent improvements section
- STATUS.md: Update from 35 to 75 tests, add integration test details, include lib/ modules
- PHASE1_COMPLETION.md & PHASE2_COMPLETION.md: Add historical milestone notes
Key corrections:
- CI/CD pipeline IS operational (.github/workflows/test.yml)
- install.sh DOES copy lib/ directory (verified lines 78, 91, 148)
- 75 tests accurately reported (15 rate + 20 exit + 20 loop + 20 edge)
- Week 5 partially complete (edge cases done, features not implemented)
- Weeks 3-4 and 6 not started (accurate status vs. optimistic claims)
All documentation now synchronized with codebase as of 2025-12-31.
Add -u flag to GNU date command in get_iso_timestamp() to match
the macOS implementation and function documentation. Both platforms
now consistently return UTC timestamps in YYYY-MM-DDTHH:MM:SS+00:00
format.
Before: date -Iseconds (returned local time on Linux)
After: date -u -Iseconds (returns UTC on Linux)
Add cross-platform date utility library to handle differences between
GNU date (Linux) and BSD date (macOS). Fixes issues with:
- ISO 8601 timestamp formatting (-Iseconds flag)
- Date arithmetic operations (-d vs -v flags)
Changes:
- Created lib/date_utils.sh with get_iso_timestamp() and get_next_hour_time()
- Updated ralph_loop.sh to use date utilities (2 instances)
- Updated lib/circuit_breaker.sh to use date utilities (4 instances)
- Updated lib/response_analyzer.sh to use date utilities (1 instance)
All date operations now work consistently across both platforms without
modification. The utility automatically detects the OS and uses the
appropriate date command syntax.
Tested on Linux with GNU date - all syntax checks and integration tests pass.
Updated both documentation files to reflect recent enhancements and fixes:
CLAUDE.md Changes:
- Added comprehensive Core Architecture section detailing main scripts and lib/ components
- Documented lib/circuit_breaker.sh and lib/response_analyzer.sh modular architecture
- Added detailed Exit Conditions and Thresholds section with circuit breaker thresholds
- Documented advanced two-stage error detection process to eliminate false positives
- Documented multi-line error matching for accurate stuck loop detection
- Added Recent Improvements section highlighting v0.9.0 circuit breaker enhancements
- Updated Global Installation section to include lib/ directory and ralph-import command
- Test coverage details: 13 error detection + 9 stuck loop tests
README.md Changes:
- Updated "What's Working Now" section with circuit breaker enhancements
- Added "Recent Improvements" section highlighting v0.9.0 updates
- Updated test count from 75 to 97 tests (75 core + 13 error detection + 9 stuck loop)
- Enhanced circuit breaker description with two-stage filtering details
- Added circuit breaker thresholds to Exit Thresholds section
- Updated test commands to include error detection and stuck loop test scripts
- Updated current test status with specialized test file counts
Key improvements documented:
- Multi-line error matching fix for detect_stuck_loop function
- JSON field false positive elimination (e.g., "is_error": false)
- Two-stage error filtering for accurate error detection
- Installation fix for lib/ directory components
- 22 new tests added for circuit breaker functionality
These updates ensure documentation accurately reflects the current state of the
codebase following PR #6 (circuit-breaker false positives fix) and PR #4
(installation lib/ directory fix).
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
