- Create CONTRIBUTING.md with 8 sections covering the full contributor
journey: Getting Started, Development Workflow, Code Style, Testing,
PR Process, Code Review, Quality Standards, and Community Guidelines
- Include workflow diagram, quality gates table, and test commands reference
- Update README.md to reference CONTRIBUTING.md, consolidating duplicate
contributor information into the dedicated guide
Add TESTING.md with complete documentation for the Ralph test suite:
- Quick start commands for running tests
- Test organization and directory structure
- BATS syntax guide with examples from the codebase
- Test helper API documentation (assertions, mocks, fixtures)
- Coverage requirements and kcov limitations
- CI/CD integration with GitHub Actions pipeline
- Troubleshooting guide for common issues
- Appendices with quick reference and patterns
Covers all 276 tests across 11 test files.
Reverted changes to issues not created by frankbria:
- #44, #54, #64, #65 removed from phase assignments
- Restored original issue titles on GitHub
- Removed phase labels from community issues
- Updated open issue counts (40 → 36)
- Update test counts (75 -> 276) and all test file details
- Convert from Week-based to Phase-based structure (Phases 1-6)
- Add all GitHub issues organized by phase and priority
- Update version history with v0.9.0-v0.9.8 changes
- Add summary statistics and open issues by priority
- Collapse closed issues into expandable section
- Add version history entries for v0.9.3 through v0.9.8
- Add Session Continuity feature to features list
- Add new Session Continuity configuration section
- Add --reset-session flag to command reference
- Add new test file references (session, import, setup, installation)
- Add detailed docblocks for detect_response_format, parse_conversion_response,
and check_claude_version functions
- Declare global PARSED_* variables near top of script with documentation
- Fix bug where convert_prd was called with subdirectory path after cd
(now uses basename since file is copied to project root)
All 276 tests pass.
- Convert CLAUDE_ALLOWED_TOOLS to bash array for proper quoting
- Use array expansion "${CLAUDE_ALLOWED_TOOLS[@]}" in CLI invocation
- Default empty version components to 0 (handles "2.1" style versions)
- Add stderr_file cleanup in JSON error path
- Add type validation for PARSED_FILES_CREATED before array iteration
- Check for empty file names in JSON array iteration
- Fix stale test counts in README.md (165 → 276, 8 → 11 test files)
- 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)
