feat(structure): migrate Ralph files to .ralph/ subfolder (#109)

* 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>

tests/helpers/test_helper.bash

@@ -1,6 +1,12 @@
 #!/usr/bin/env bash
 # Test Helper Utilities for Ralph Test Suite
 
+# Helper: Fail with message (for use in assertions)
+fail() {
+    echo "$1"
+    return 1
+}
+
 # Simple assertion functions (replacing bats-assert)
 assert_success() {
     if [ "$status" -ne 0 ]; then
@@ -43,18 +49,20 @@ setup() {
     export TEST_TEMP_DIR="$(mktemp -d "${BATS_TEST_TMPDIR}/test.XXXXXX")"
     cd "$TEST_TEMP_DIR"
 
-    # Set up test environment variables
-    export PROMPT_FILE="PROMPT.md"
-    export LOG_DIR="logs"
-    export DOCS_DIR="docs/generated"
-    export STATUS_FILE="status.json"
-    export PROGRESS_FILE="progress.json"
-    export CALL_COUNT_FILE=".call_count"
-    export TIMESTAMP_FILE=".last_reset"
-    export EXIT_SIGNALS_FILE=".exit_signals"
+    # Set up test environment variables with .ralph/ subfolder structure
+    export RALPH_DIR=".ralph"
+    export PROMPT_FILE="$RALPH_DIR/PROMPT.md"
+    export LOG_DIR="$RALPH_DIR/logs"
+    export DOCS_DIR="$RALPH_DIR/docs/generated"
+    export STATUS_FILE="$RALPH_DIR/status.json"
+    export PROGRESS_FILE="$RALPH_DIR/progress.json"
+    export CALL_COUNT_FILE="$RALPH_DIR/.call_count"
+    export TIMESTAMP_FILE="$RALPH_DIR/.last_reset"
+    export EXIT_SIGNALS_FILE="$RALPH_DIR/.exit_signals"
+    export RESPONSE_ANALYSIS_FILE="$RALPH_DIR/.response_analysis"
 
     # Create necessary directories
-    mkdir -p "$LOG_DIR" "$DOCS_DIR"
+    mkdir -p "$LOG_DIR" "$DOCS_DIR" "$RALPH_DIR"
 
     # Initialize files
     echo "0" > "$CALL_COUNT_FILE"
@@ -77,6 +85,7 @@ strip_colors() {
 
 # Helper: Create a mock PROMPT.md file
 create_mock_prompt() {
+    mkdir -p "$RALPH_DIR"
     cat > "$PROMPT_FILE" << 'EOF'
 # Test Prompt
 This is a test prompt for Ralph.
@@ -90,19 +99,21 @@ EOF
 create_mock_fix_plan() {
     local total=${1:-5}
     local completed=${2:-0}
+    local fix_plan_file="$RALPH_DIR/@fix_plan.md"
 
-    cat > "@fix_plan.md" << EOF
+    mkdir -p "$RALPH_DIR"
+    cat > "$fix_plan_file" << EOF
 # Fix Plan
 
 ## High Priority
 EOF
 
     for ((i=1; i<=completed; i++)); do
-        echo "- [x] Completed task $i" >> "@fix_plan.md"
+        echo "- [x] Completed task $i" >> "$fix_plan_file"
     done
 
     for ((i=completed+1; i<=total; i++)); do
-        echo "- [ ] Pending task $i" >> "@fix_plan.md"
+        echo "- [ ] Pending task $i" >> "$fix_plan_file"
     done
 }