[AskTinNguyen]

Summary

Implements a minimal Ralph loop (~200 lines) with hook-based enforcement, achieving a 5x reduction from the original 4,244-line loop.sh.

Key changes:

• simplified-loop.sh: Core iteration loop with signal handling, timeout, atomic checkpoints
• lib/minimal.sh: Essential utilities (logging, atomic write, story management)
• hooks/pre-tool.sh: PreToolUse validation (Edit requires Read, blocks git push/merge/force)
• hooks/post-tool.sh: PostToolUse test failure detection (Jest/pytest/Go/Mocha/RSpec/Bats)
• hooks/on-stop.sh: Stop hook for completion state and cleanup
• hooks/pre-prompt.sh: UserPromptSubmit hook for session management

Design principles:

• All enforcement delegated to Claude Code hooks (not inline validation)
• Hooks ALWAYS exit 0 (never break Claude Code)
• Atomic file operations for race-condition safety
• Comprehensive test failure patterns for 7+ frameworks

Test plan

• 23 unit tests passing (./tests/simplified-loop.test.sh)
• Tests cover: hook validation, test failure detection, file operations
• Security fixes for path traversal, log injection, sed escaping

Line count comparison

Component	Original	Simplified	Reduction
Core loop	4,244	204	95%
Total (with hooks)	4,244+	805	81%

---

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

• This PR is safe to merge with minimal risk - implements critical security fixes and comprehensive test coverage
• Score reflects thorough security hardening (path traversal prevention, log injection fixes, sed escaping), robust error handling, comprehensive test coverage (23 passing tests), and proper platform compatibility. The hook-based architecture is well-designed with proper exit code handling to avoid breaking Claude Code.
• No files require special attention - all core files have been security-reviewed and tested

Important Files Changed

Filename	Overview
.agents/ralph/simplified-loop.sh	Core loop implementation with proper error handling, signal management, and security validation (PRD number validation prevents path traversal)
.agents/ralph/lib/minimal.sh	Utility functions with proper sed escaping for security; includes platform detection for macOS/Linux compatibility in mark_story_complete
.agents/ralph/hooks/pre-tool.sh	PreToolUse validation hook with log injection prevention and git command blocking; uses fixed-string grep for security
.agents/ralph/hooks/post-tool.sh	PostToolUse hook with comprehensive test failure detection for 7+ frameworks (Jest, pytest, Go, Mocha, RSpec, Bats, npm); includes rollback and failure logging
tests/simplified-loop.test.sh	Comprehensive test suite with 23 unit tests covering hooks, utilities, and test failure detection patterns

Sequence Diagram

sequenceDiagram
    participant User
    participant SimplifiedLoop
    participant PrePromptHook
    participant PreToolHook
    participant ClaudeAgent
    participant PostToolHook
    participant StopHook
    participant GitRepo

    User->>SimplifiedLoop: Start build
    SimplifiedLoop->>SimplifiedLoop: Validate PRD
    SimplifiedLoop->>SimplifiedLoop: Select story
    SimplifiedLoop->>GitRepo: Save checkpoint
    
    SimplifiedLoop->>PrePromptHook: UserPromptSubmit
    PrePromptHook->>PrePromptHook: Clear session log
    PrePromptHook-->>SimplifiedLoop: Success
    
    SimplifiedLoop->>ClaudeAgent: Execute agent
    
    ClaudeAgent->>PreToolHook: Read file
    PreToolHook-->>ClaudeAgent: Allow
    
    ClaudeAgent->>PreToolHook: Edit file
    PreToolHook->>PreToolHook: Check session log
    PreToolHook-->>ClaudeAgent: Allow or Block
    
    ClaudeAgent->>PreToolHook: Git push
    PreToolHook-->>ClaudeAgent: Block
    
    ClaudeAgent->>PostToolHook: After tool use
    PostToolHook->>PostToolHook: Check test failures
    PostToolHook->>GitRepo: Rollback if failed
    PostToolHook-->>ClaudeAgent: Success
    
    ClaudeAgent->>StopHook: Session ends
    StopHook->>StopHook: Cleanup files
    StopHook-->>SimplifiedLoop: Complete
    
    SimplifiedLoop->>GitRepo: Commit changes
    SimplifiedLoop->>SimplifiedLoop: Mark story done
    SimplifiedLoop-->>User: Build complete

Loading

[AskTinNguyen]

Code Review & Testing Complete ✅

Test Results

All 33 tests passing:

Tests: 33 | Passed: 33 | Failed: 0

Security Improvements Applied

Following comprehensive code review, these security enhancements were implemented:

Finding	Fix	Commit
sed regex injection	Strict US-NNN validation	1a1f743
git command bypass	Enhanced detection patterns	1a1f743
log injection (ANSI escapes)	Control character stripping	1a1f743
TOCTOU race condition	Cross-platform file locking	ef0c192
regex injection in on-stop	grep -F fixed strings	1a1f743
MAX_ITERATIONS unbounded	Upper bound validation (100)	1a1f743

Cross-Platform Support

• Linux: Uses flock for file locking
• macOS: Uses shlock or PID-based fallback
• All platforms: Atomic file operations via temp+mv

Demo (dry-run)

$ .agents/ralph/simplified-loop.sh --dry-run --prd=1
[23:47:34] Starting simplified loop (PRD-1, max 25 iterations)
[23:47:34] Acquired exclusive lock for agent execution
[23:47:34] === Iteration 1/25 ===
[23:47:34] ✓ All stories complete!

---

🤖 Reviewed and tested with Claude Code