spec-and-loop 2.1.1 → 3.0.0

package/lib/mini-ralph/state.js

@@ -55,11 +55,27 @@ function init(ralphDir, data) {
 function read(ralphDir) {
   const file = statePath(ralphDir);
   if (!fs.existsSync(file)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
-  } catch {
-    return null;
+  // One-shot retry to paper over the vanishingly-rare race where we read the
+  // state file between `openSync('wx')` on the temp file and the rename. On
+  // POSIX `renameSync` is atomic, so the retry window is only meaningful on
+  // filesystems where it is not -- but the cost of retrying is tiny, so we
+  // do it uniformly for robustness.
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const raw = fs.readFileSync(file, 'utf8');
+      if (!raw) {
+        if (attempt === 0) continue;
+        return null;
+      }
+      return JSON.parse(raw);
+    } catch (err) {
+      if (attempt === 0 && (err.code === 'ENOENT' || err instanceof SyntaxError)) {
+        continue;
+      }
+      return null;
+    }
   }
+  return null;
 }
 
 /**
@@ -182,7 +198,43 @@ function _ensureDir(ralphDir) {
 
 function _write(ralphDir, data) {
   _ensureDir(ralphDir);
-  fs.writeFileSync(statePath(ralphDir), JSON.stringify(data, null, 2), 'utf8');
+  const target = statePath(ralphDir);
+  // Atomic write: serialize to a temp file in the same directory, then rename.
+  // A concurrent `read()` either sees the fully-written old file or the fully-
+  // written new file -- never a partially-written one. This matters because
+  // `ralph-run --status` can race with the live loop's per-iteration
+  // `state.update()` calls, and a torn read used to surface as JSON.parse
+  // errors or the dashboard reporting a stale iteration counter.
+  const tmp = `${target}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const serialized = JSON.stringify(data, null, 2);
+
+  let handle = null;
+  try {
+    handle = fs.openSync(tmp, 'wx');
+    fs.writeFileSync(handle, serialized, 'utf8');
+    fs.fsyncSync(handle);
+  } finally {
+    if (handle !== null) {
+      try {
+        fs.closeSync(handle);
+      } catch {
+        /* best-effort close */
+      }
+    }
+  }
+
+  try {
+    fs.renameSync(tmp, target);
+  } catch (err) {
+    // Clean up the temp file if rename failed, then rethrow so the caller
+    // sees the real error (disk full, permissions, etc.).
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      /* best-effort cleanup */
+    }
+    throw err;
+  }
 }
 
 function _createLockToken() {

package/lib/mini-ralph/tasks.js

@@ -157,24 +157,19 @@ function taskContext(tasksFile) {
     all.find((task) => task.status === 'in_progress') ||
     all.find((task) => task.status === 'incomplete') ||
     null;
-  const completed = all.filter((task) => task.status === 'completed');
+  const completedCount = all.filter((task) => task.status === 'completed').length;
+  const total = all.length;
 
   const sections = [];
 
   if (current) {
     sections.push('## Current Task');
     sections.push(`- ${current.fullDescription || current.description}`);
+    sections.push('');
   }
 
-  if (completed.length > 0) {
-    if (sections.length > 0) {
-      sections.push('');
-    }
-    sections.push('## Completed Tasks for Git Commit');
-    sections.push(
-      ...completed.map((task) => `- [x] ${task.fullDescription || task.description}`)
-    );
-  }
+  sections.push('## Progress');
+  sections.push(`- ${completedCount} of ${total} tasks complete`);
 
   return sections.join('\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-and-loop",
-  "version": "2.1.1",
+  "version": "3.0.0",
   "description": "OpenSpec + Ralph Loop integration for iterative development with opencode",
   "main": "index.js",
   "bin": {
@@ -17,13 +17,13 @@
     "lint": "shellcheck scripts/*.sh"
   },
   "dependencies": {
-    "@fission-ai/openspec": "1.2.0",
-    "spec-and-loop": "^2.0.0"
+    "@fission-ai/openspec": "1.3.1",
+    "spec-and-loop": "^2.1.2"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.0",
+    "@types/jest": "^30.0.0",
     "bats": "^1.13.0",
-    "jest": "^29.7.0"
+    "jest": "^30.3.0"
   },
   "jest": {
     "testEnvironment": "node",
@@ -63,6 +63,7 @@
     "bin/",
     "lib/",
     "scripts/",
+    "OPENSPEC-RALPH-BP.md",
     "README.md",
     "QUICKSTART.md"
   ],

package/scripts/mini-ralph-cli.js

@@ -19,11 +19,13 @@
  *   --tasks                    Enable tasks mode
  *   --min-iterations <n>       Minimum iterations (default: 1)
  *   --max-iterations <n>       Maximum iterations (default: 50)
+ *   --stall-threshold <n>      Halt after N consecutive no-op iterations (default: 3; 0 disables)
  *   --completion-promise <s>   Completion promise string (default: COMPLETE)
  *   --task-promise <s>         Task promise string (default: READY_FOR_NEXT_TASK)
  *   --no-commit                Suppress auto-commit
  *   --model <name>             Optional model override
  *   --verbose                  Verbose output
+ *   --quiet                    Suppress the per-iteration progress stream
  *   --status                   Print status dashboard and exit
  *   --add-context <text>       Add pending context and exit
  *   --clear-context            Clear pending context and exit
@@ -48,11 +50,13 @@ function parseArgs(argv) {
     tasksMode: false,
     minIterations: 1,
     maxIterations: 50,
+    stallThreshold: 3,
     completionPromise: 'COMPLETE',
     taskPromise: 'READY_FOR_NEXT_TASK',
     noCommit: false,
     model: '',
     verbose: false,
+    quiet: false,
     // Control commands
     status: false,
     addContext: null,
@@ -88,6 +92,9 @@ function parseArgs(argv) {
       case '--max-iterations':
         opts.maxIterations = parseInt(args[++i], 10);
         break;
+      case '--stall-threshold':
+        opts.stallThreshold = parseInt(args[++i], 10);
+        break;
       case '--completion-promise':
         opts.completionPromise = args[++i];
         break;
@@ -103,6 +110,9 @@ function parseArgs(argv) {
       case '--verbose':
         opts.verbose = true;
         break;
+      case '--quiet':
+        opts.quiet = true;
+        break;
       case '--status':
         opts.status = true;
         break;
@@ -141,11 +151,13 @@ Options:
   --tasks                    Enable tasks mode
   --min-iterations <n>       Minimum iterations (default: 1)
   --max-iterations <n>       Maximum iterations (default: 50)
+  --stall-threshold <n>      Halt after N consecutive no-op iterations (default: 3; 0 disables)
   --completion-promise <s>   Completion promise string
   --task-promise <s>         Task promise string
   --no-commit                Suppress auto-commit
   --model <name>             Model override
   --verbose                  Verbose output
+  --quiet                    Suppress the per-iteration progress stream
   --status                   Print status dashboard and exit
   --add-context <text>       Add pending context and exit
   --clear-context            Clear pending context and exit
@@ -197,11 +209,13 @@ async function main() {
     tasksMode: opts.tasksMode,
     minIterations: opts.minIterations,
     maxIterations: opts.maxIterations,
+    stallThreshold: opts.stallThreshold,
     completionPromise: opts.completionPromise,
     taskPromise: opts.taskPromise,
     noCommit: opts.noCommit,
     model: opts.model,
     verbose: opts.verbose,
+    quiet: opts.quiet,
   };
 
   try {
@@ -213,13 +227,15 @@ async function main() {
       );
     }
 
-    process.exit(result.completed ? 0 : 1);
+    process.exitCode = result.completed ? 0 : 1;
+    setTimeout(() => process.exit(result.completed ? 0 : 1), 5000).unref();
   } catch (err) {
     process.stderr.write(`[mini-ralph] error: ${err.message}\n`);
     if (opts.verbose && err.stack) {
       process.stderr.write(err.stack + '\n');
     }
-    process.exit(1);
+    process.exitCode = 1;
+    setTimeout(() => process.exit(1), 5000).unref();
   }
 }