feat: add agent reviewer (--review) and bump to v0.4.4

- Add LLM-powered diff review step that runs after lint/build/test pass
  but before commit, catching security issues, logic errors, and pattern
  violations that automated checks miss
- New src/loop/reviewer.ts module using existing tryCallLLM infrastructure
  (Anthropic/OpenAI/OpenRouter) with structured JSON findings output
- Errors block commit and feed back via lastValidationFeedback; warnings
  are logged but non-blocking; gracefully skips if no diff or no API key
- Wire --review CLI flag on run command and export public API types
- Close 14 delivered issues (#212, #224, #225, #226, #227, #228, #229,
  #231, #232, #233, #237, #239, #240, #241)
- Bump version to 0.4.4

Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019ce2d4-0f5f-742e-9721-3181f57267df

Author: rubenmarcus

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-starter",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "Ralph Wiggum made easy. One command to run autonomous AI coding loops with auto-commit, PRs, and Docker sandbox.",
   "main": "dist/index.js",
   "bin": {

src/cli.ts

@@ -132,6 +132,7 @@ program
     '--no-visual-check',
     'Disable visual comparison validation (auto-enabled when Figma screenshots exist)'
   )
+  .option('--review', 'Run LLM-powered diff review before commit (catches security/logic issues)')
   // Swarm mode options
   .option('--swarm', 'Run with multiple agents in parallel (swarm mode)')
   .option(

src/commands/run.ts

@@ -312,6 +312,8 @@ export interface RunCommandOptions {
   strategy?: 'race' | 'consensus' | 'pipeline';
   // Amp options
   ampMode?: 'smart' | 'rush' | 'deep';
+  // Agent reviewer
+  review?: boolean;
 }
 
 export async function runCommand(
@@ -1434,6 +1436,7 @@ Focus on one task at a time. After completing a task, update IMPLEMENTATION_PLAN
     visualValidation,
     figmaScreenshotPaths,
     ampMode: options.ampMode,
+    review: options.review,
   };
 
   // Swarm mode: run with multiple agents in parallel

src/index.ts

@@ -45,6 +45,8 @@ export { CostTracker, resolveModelPricing } from './loop/cost-tracker.js';
 export type { IterationUpdate, LoopOptions, LoopResult } from './loop/executor.js';
 export { runLoop } from './loop/executor.js';
 export { appendProjectMemory, readProjectMemory } from './loop/memory.js';
+export type { ReviewFinding, ReviewResult, ReviewSeverity } from './loop/reviewer.js';
+export { runReview } from './loop/reviewer.js';
 export type { SwarmAgentResult, SwarmConfig, SwarmResult, SwarmStrategy } from './loop/swarm.js';
 export { runSwarm } from './loop/swarm.js';
 export { detectValidationCommands, runAllValidations, runValidation } from './loop/validation.js';

src/loop/executor.ts

@@ -38,6 +38,7 @@ import { estimateLoop, formatEstimateDetailed } from './estimator.js';
 import { appendProjectMemory, formatMemoryPrompt, readProjectMemory } from './memory.js';
 import { checkFileBasedCompletion, createProgressTracker, type ProgressEntry } from './progress.js';
 import { RateLimiter } from './rate-limiter.js';
+import { formatReviewAsValidation, formatReviewFeedback, runReview } from './reviewer.js';
 import { analyzeResponse, hasExitSignal } from './semantic-analyzer.js';
 import { detectClaudeSkills, formatSkillsForPrompt } from './skills.js';
 import { detectStepFromOutput } from './step-detector.js';
@@ -269,6 +270,12 @@ export type LoopOptions = {
   env?: Record<string, string>;
   /** Amp agent mode: smart, rush, deep */
   ampMode?: import('./agents.js').AmpMode;
+  /** Run LLM-powered diff review after validation passes (before commit) */
+  review?: boolean;
+  /** Product name shown in logs/UI (default: 'Ralph-Starter'). Set to white-label when embedding. */
+  productName?: string;
+  /** Dot-directory for memory/iteration-log/activity (default: '.ralph'). */
+  dotDir?: string;
 };
 
 export type LoopResult = {
@@ -401,13 +408,14 @@ function appendIterationLog(
   iteration: number,
   summary: string,
   validationPassed: boolean,
-  hasChanges: boolean
+  hasChanges: boolean,
+  dotDir = '.ralph'
 ): void {
   try {
-    const ralphDir = join(cwd, '.ralph');
-    if (!existsSync(ralphDir)) mkdirSync(ralphDir, { recursive: true });
+    const stateDir = join(cwd, dotDir);
+    if (!existsSync(stateDir)) mkdirSync(stateDir, { recursive: true });
 
-    const logPath = join(ralphDir, 'iteration-log.md');
+    const logPath = join(stateDir, 'iteration-log.md');
     const entry = `## Iteration ${iteration}
 - Status: ${validationPassed ? 'validation passed' : 'validation failed'}
 - Changes: ${hasChanges ? 'yes' : 'no files changed'}
@@ -423,9 +431,13 @@ function appendIterationLog(
  * Read the last N iteration summaries from .ralph/iteration-log.md.
  * Used by context-builder to give the agent memory of previous iterations.
  */
-export function readIterationLog(cwd: string, maxEntries = 3): string | undefined {
+export function readIterationLog(
+  cwd: string,
+  maxEntries = 3,
+  dotDir = '.ralph'
+): string | undefined {
   try {
-    const logPath = join(cwd, '.ralph', 'iteration-log.md');
+    const logPath = join(cwd, dotDir, 'iteration-log.md');
     if (!existsSync(logPath)) return undefined;
 
     const content = readFileSync(logPath, 'utf-8');
@@ -503,6 +515,9 @@ export async function runLoop(options: LoopOptions): Promise<LoopResult> {
         isSpinning: false,
       }
     : ora();
+  const productName = options.productName || 'Ralph-Starter';
+  const dotDir = options.dotDir || '.ralph';
+
   let maxIterations = options.maxIterations || 50;
   const commits: string[] = [];
   const startTime = Date.now();
@@ -523,7 +538,7 @@ export async function runLoop(options: LoopOptions): Promise<LoopResult> {
 
   // Initialize progress tracker
   const progressTracker = options.trackProgress
-    ? createProgressTracker(options.cwd, options.task)
+    ? createProgressTracker(options.cwd, options.task, dotDir)
     : null;
 
   // Initialize cost tracker
@@ -560,10 +575,10 @@ export async function runLoop(options: LoopOptions): Promise<LoopResult> {
   }
 
   // Inject project memory from previous runs (if available)
-  const projectMemory = readProjectMemory(options.cwd);
+  const projectMemory = readProjectMemory(options.cwd, dotDir);
   if (projectMemory) {
-    taskWithSkills = `${taskWithSkills}\n\n${formatMemoryPrompt(projectMemory)}`;
-    log(chalk.dim('  Project memory loaded from .ralph/memory.md'));
+    taskWithSkills = `${taskWithSkills}\n\n${formatMemoryPrompt(projectMemory, dotDir)}`;
+    log(chalk.dim(`  Project memory loaded from ${dotDir}/memory.md`));
   }
 
   // Build abbreviated spec summary for context builder (iterations 2+)
@@ -585,7 +600,7 @@ export async function runLoop(options: LoopOptions): Promise<LoopResult> {
 
   // Show startup summary box
   const startupLines: string[] = [];
-  startupLines.push(chalk.cyan.bold('  Ralph-Starter'));
+  startupLines.push(chalk.cyan.bold(`  ${productName}`));
   startupLines.push(`  Agent:       ${chalk.white(options.agent.name)}`);
   startupLines.push(`  Max loops:   ${chalk.white(String(maxIterations))}`);
   if (validationCommands.length > 0) {
@@ -871,7 +886,7 @@ export async function runLoop(options: LoopOptions): Promise<LoopResult> {
 
     // Build iteration-specific task with smart context windowing
     // Read iteration log for inter-iteration memory (iterations 2+)
-    const iterationLog = i > 1 ? readIterationLog(options.cwd) : undefined;
+    const iterationLog = i > 1 ? readIterationLog(options.cwd, 3, dotDir) : undefined;
 
     const builtContext = buildIterationContext({
       fullTask: options.task,
@@ -1496,6 +1511,70 @@ export async function runLoop(options: LoopOptions): Promise<LoopResult> {
       }
     }
 
+    // --- Agent reviewer: LLM-powered diff review before commit ---
+    if (options.review && hasChanges && i > 1) {
+      spinner.start(chalk.yellow(`Loop ${i}: Running agent review...`));
+      try {
+        const reviewResult = await runReview(options.cwd);
+        if (reviewResult && !reviewResult.passed) {
+          const reviewValidation = formatReviewAsValidation(reviewResult);
+          validationResults.push(reviewValidation);
+          const feedback = formatReviewFeedback(reviewResult);
+          spinner.fail(
+            chalk.red(
+              `Loop ${i}: Agent review found ${reviewResult.findings.filter((f) => f.severity === 'error').length} error(s)`
+            )
+          );
+          for (const f of reviewResult.findings) {
+            const icon = f.severity === 'error' ? '❌' : f.severity === 'warning' ? '⚠️' : 'ℹ️';
+            log(chalk.dim(`  ${icon} ${f.message}`));
+          }
+
+          const tripped = circuitBreaker.recordFailure('agent-review');
+          if (tripped) {
+            finalIteration = i;
+            exitReason = 'circuit_breaker';
+            break;
+          }
+
+          lastValidationFeedback = feedback;
+
+          if (progressTracker && progressEntry) {
+            progressEntry.status = 'validation_failed';
+            progressEntry.summary = 'Agent review failed';
+            progressEntry.validationResults = validationResults;
+            progressEntry.duration = Date.now() - iterationStart;
+            await progressTracker.appendEntry(progressEntry);
+          }
+
+          continue;
+        }
+        if (reviewResult) {
+          const warnFindings = reviewResult.findings.filter((f) => f.severity === 'warning');
+          const infoFindings = reviewResult.findings.filter((f) => f.severity === 'info');
+          const suffix =
+            warnFindings.length > 0 || infoFindings.length > 0
+              ? ` (${warnFindings.length} warning(s), ${infoFindings.length} info)`
+              : '';
+          spinner.succeed(chalk.green(`Loop ${i}: Agent review passed${suffix}`));
+          for (const f of [...warnFindings, ...infoFindings]) {
+            const icon = f.severity === 'warning' ? '⚠️' : 'ℹ️';
+            log(chalk.dim(`  ${icon} ${f.message}`));
+          }
+          circuitBreaker.recordSuccess();
+          lastValidationFeedback = '';
+        } else {
+          spinner.info(chalk.dim(`Loop ${i}: Agent review skipped (no diff or no LLM key)`));
+        }
+      } catch (err) {
+        spinner.warn(
+          chalk.yellow(
+            `Loop ${i}: Agent review skipped (${err instanceof Error ? err.message : 'unknown error'})`
+          )
+        );
+      }
+    }
+
     // Auto-commit if enabled and there are changes
     let committed = false;
     let commitMsg = '';
@@ -1547,7 +1626,7 @@ export async function runLoop(options: LoopOptions): Promise<LoopResult> {
     // Write iteration summary for inter-iteration memory
     const iterSummary = summarizeChanges(result.output);
     const iterValidationPassed = validationResults.every((r) => r.success);
-    appendIterationLog(options.cwd, i, iterSummary, iterValidationPassed, hasChanges);
+    appendIterationLog(options.cwd, i, iterSummary, iterValidationPassed, hasChanges, dotDir);
 
     if (status === 'done') {
       const completionReason = completionResult.reason || 'Task marked as complete by agent';
@@ -1686,7 +1765,7 @@ export async function runLoop(options: LoopOptions): Promise<LoopResult> {
   if (costTracker) {
     memorySummary.push(`Cost: ${formatCost(costTracker.getStats().totalCost.totalCost)}`);
   }
-  appendProjectMemory(options.cwd, memorySummary.join('\n'));
+  appendProjectMemory(options.cwd, memorySummary.join('\n'), dotDir);
 
   return {
     success: exitReason === 'completed' || exitReason === 'file_signal',

src/loop/memory.ts

@@ -15,9 +15,9 @@ const MAX_MEMORY_BYTES = 8 * 1024; // 8KB max — keeps context window usage rea
  * Read the project memory file.
  * Returns undefined if no memory exists yet.
  */
-export function readProjectMemory(cwd: string): string | undefined {
+export function readProjectMemory(cwd: string, dotDir = '.ralph'): string | undefined {
   try {
-    const memoryPath = join(cwd, '.ralph', MEMORY_FILE);
+    const memoryPath = join(cwd, dotDir, MEMORY_FILE);
     if (!existsSync(memoryPath)) return undefined;
 
     const content = readFileSync(memoryPath, 'utf-8').trim();
@@ -45,12 +45,12 @@ export function readProjectMemory(cwd: string): string | undefined {
 /**
  * Append an entry to the project memory file.
  */
-export function appendProjectMemory(cwd: string, entry: string): void {
+export function appendProjectMemory(cwd: string, entry: string, dotDir = '.ralph'): void {
   try {
-    const ralphDir = join(cwd, '.ralph');
-    if (!existsSync(ralphDir)) mkdirSync(ralphDir, { recursive: true });
+    const stateDir = join(cwd, dotDir);
+    if (!existsSync(stateDir)) mkdirSync(stateDir, { recursive: true });
 
-    const memoryPath = join(ralphDir, MEMORY_FILE);
+    const memoryPath = join(stateDir, MEMORY_FILE);
     const timestamp = new Date().toISOString().split('T')[0];
     const formatted = `## ${timestamp}\n${entry.trim()}\n\n`;
 
@@ -63,13 +63,13 @@ export function appendProjectMemory(cwd: string, entry: string): void {
 /**
  * Format memory content as a prompt section for injection into agent context.
  */
-export function formatMemoryPrompt(memory: string): string {
+export function formatMemoryPrompt(memory: string, dotDir = '.ralph'): string {
   return `## Project Memory (from previous runs)
-The following notes were saved from previous ralph-starter runs on this project.
+The following notes were saved from previous runs on this project.
 Use them to understand project conventions and avoid repeating mistakes.
 
 ${memory}
 
-If you discover new project conventions or important patterns, append them to \`.ralph/memory.md\`.
+If you discover new project conventions or important patterns, append them to \`${dotDir}/memory.md\`.
 `;
 }

src/loop/progress.ts

@@ -21,7 +21,7 @@ export interface ProgressTracker {
   clear(): Promise<void>;
 }
 
-const ACTIVITY_FILE = '.ralph/activity.md';
+const DEFAULT_ACTIVITY_DIR = '.ralph';
 
 /**
  * Format a progress entry as markdown
@@ -128,8 +128,12 @@ function getFileHeader(task: string): string {
 /**
  * Create a progress tracker for a directory
  */
-export function createProgressTracker(cwd: string, task: string): ProgressTracker {
-  const filePath = path.join(cwd, ACTIVITY_FILE);
+export function createProgressTracker(
+  cwd: string,
+  task: string,
+  dotDir = DEFAULT_ACTIVITY_DIR
+): ProgressTracker {
+  const filePath = path.join(cwd, dotDir, 'activity.md');
   const dirPath = path.dirname(filePath);
   let initialized = false;