spec-and-loop 2.1.0 → 2.1.2

package/lib/mini-ralph/state.js

@@ -12,6 +12,7 @@ const fs = require('fs');
 const path = require('path');
 
 const STATE_FILE = 'ralph-loop.state.json';
+const LOCK_FILE = 'ralph-loop.lock.json';
 
 /**
  * Return the absolute path to the state file.
@@ -23,6 +24,16 @@ function statePath(ralphDir) {
   return path.join(ralphDir, STATE_FILE);
 }
 
+/**
+ * Return the absolute path to the per-change run lock file.
+ *
+ * @param {string} ralphDir
+ * @returns {string}
+ */
+function lockPath(ralphDir) {
+  return path.join(ralphDir, LOCK_FILE);
+}
+
 /**
  * Initialize the state file with the provided data.
  * Creates ralphDir if it does not exist.
@@ -75,6 +86,90 @@ function remove(ralphDir) {
   }
 }
 
+/**
+ * Acquire the per-change loop lock.
+ *
+ * If a prior lock exists and still points to a live process, this throws a
+ * descriptive error. If the prior lock is stale or unreadable, it is replaced.
+ *
+ * @param {string} ralphDir
+ * @param {object} metadata
+ * @returns {object}
+ */
+function acquireRunLock(ralphDir, metadata = {}) {
+  _ensureDir(ralphDir);
+
+  const file = lockPath(ralphDir);
+  const lock = Object.assign({}, metadata, {
+    pid: process.pid,
+    acquiredAt: new Date().toISOString(),
+    token: _createLockToken(),
+  });
+
+  while (true) {
+    try {
+      const fd = fs.openSync(file, 'wx');
+      fs.writeFileSync(fd, JSON.stringify(lock, null, 2), 'utf8');
+      fs.closeSync(fd);
+      return lock;
+    } catch (err) {
+      if (err.code !== 'EEXIST') {
+        throw err;
+      }
+
+      const existingLock = readRunLock(ralphDir);
+      if (_isLiveLock(existingLock)) {
+        const liveError = new Error(
+          `another loop is already active for this change (pid ${existingLock.pid})`
+        );
+        liveError.code = 'RALPH_ACTIVE_LOOP_LOCK';
+        liveError.lock = existingLock;
+        throw liveError;
+      }
+
+      _removeLockIfPresent(file);
+    }
+  }
+}
+
+/**
+ * Read the current run lock. Returns null when the lock is absent or invalid.
+ *
+ * @param {string} ralphDir
+ * @returns {object|null}
+ */
+function readRunLock(ralphDir) {
+  const file = lockPath(ralphDir);
+  if (!fs.existsSync(file)) return null;
+
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Release the current run lock when it still belongs to the provided owner.
+ *
+ * @param {string} ralphDir
+ * @param {object|null} lock
+ */
+function releaseRunLock(ralphDir, lock) {
+  const file = lockPath(ralphDir);
+  if (!fs.existsSync(file)) return;
+
+  if (!lock || !lock.token) {
+    _removeLockIfPresent(file);
+    return;
+  }
+
+  const existingLock = readRunLock(ralphDir);
+  if (!existingLock || existingLock.token === lock.token) {
+    _removeLockIfPresent(file);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -90,4 +185,46 @@ function _write(ralphDir, data) {
   fs.writeFileSync(statePath(ralphDir), JSON.stringify(data, null, 2), 'utf8');
 }
 
-module.exports = { init, read, update, remove, statePath };
+function _createLockToken() {
+  return `${process.pid}:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+}
+
+function _isLiveLock(lock) {
+  if (!lock || typeof lock.pid !== 'number' || lock.pid <= 0) {
+    return false;
+  }
+
+  try {
+    process.kill(lock.pid, 0);
+    return true;
+  } catch (err) {
+    if (err && err.code === 'EPERM') {
+      return true;
+    }
+    return false;
+  }
+}
+
+function _removeLockIfPresent(file) {
+  try {
+    if (fs.existsSync(file)) {
+      fs.unlinkSync(file);
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      throw err;
+    }
+  }
+}
+
+module.exports = {
+  init,
+  read,
+  update,
+  remove,
+  statePath,
+  lockPath,
+  acquireRunLock,
+  readRunLock,
+  releaseRunLock,
+};

package/lib/mini-ralph/status.js

@@ -40,6 +40,11 @@ function render(ralphDir, tasksFile) {
   lines.push(`Status:        ${active}`);
   lines.push(`Iteration:     ${loopState.iteration || '?'} / ${loopState.maxIterations || '?'}`);
 
+  const lifecycle = loopState.active
+    ? 'running'
+    : (loopState.completedAt ? 'completed' : 'stopped (incomplete)');
+  lines.push(`Lifecycle:     ${lifecycle}`);
+
   if (loopState.startedAt) {
     const elapsed = _elapsed(loopState.startedAt);
     lines.push(`Started:       ${loopState.startedAt}  (${elapsed} ago)`);
@@ -47,6 +52,17 @@ function render(ralphDir, tasksFile) {
 
   if (loopState.completedAt) {
     lines.push(`Completed:     ${loopState.completedAt}`);
+  } else if (loopState.stoppedAt) {
+    lines.push(`Stopped:       ${loopState.stoppedAt}`);
+  }
+
+  if (loopState.exitReason) {
+    lines.push(`Exit reason:   ${loopState.exitReason}`);
+  }
+
+  const latestCommitAnomaly = _latestCommitAnomaly(history.recent(ralphDir, 20));
+  if (latestCommitAnomaly) {
+    lines.push(`Commit issue:  ${latestCommitAnomaly.commitAnomaly}`);
   }
 
   lines.push(`Tasks mode:    ${loopState.tasksMode ? 'yes' : 'no'}`);
@@ -95,15 +111,18 @@ function render(ralphDir, tasksFile) {
       const durationSec = entry.duration ? `${(entry.duration / 1000).toFixed(1)}s` : '?';
       const completed = entry.completionDetected ? ' [COMPLETE]' : (entry.taskDetected ? ' [TASK]' : '');
       const toolSummary = _formatToolUsage(entry.toolUsage);
-      lines.push(`  Iteration ${entry.iteration}: ${durationSec}${completed}${toolSummary ? `  tools: ${toolSummary}` : ''}`);
+      const failureSummary = _formatHistoryFailure(entry);
+      const commitSuffix = entry.commitAnomaly ? `  commit: ${entry.commitAnomaly}` : '';
+      lines.push(`  Iteration ${entry.iteration}: ${durationSec}${completed}${toolSummary ? `  tools: ${toolSummary}` : ''}${failureSummary ? `  failure: ${failureSummary}` : ''}${commitSuffix}`);
     }
     lines.push('-'.repeat(50));
   }
 
   // Error history
+  const recentErrors = errors.readEntries(ralphDir, 5);
   const errorCount = errors.count(ralphDir);
   if (errorCount > 0) {
-    const latestError = errors.latest(ralphDir);
+    const latestError = recentErrors.length > 0 ? recentErrors[recentErrors.length - 1] : errors.latest(ralphDir);
     const preview = _formatErrorPreview(latestError);
     lines.push('');
     lines.push('--- Error History ---');
@@ -113,7 +132,7 @@ function render(ralphDir, tasksFile) {
   }
 
   // Struggle indicators
-  const struggles = _detectStruggles(recentHistory);
+  const struggles = _detectStruggles(recentHistory, recentErrors);
   if (struggles.length > 0) {
     lines.push('');
     lines.push('--- Struggle Indicators ---');
@@ -189,13 +208,33 @@ function _formatToolUsage(toolUsage) {
   return toolUsage.map((t) => `${t.tool}(${t.count})`).join(', ');
 }
 
+function _isFailedHistoryEntry(entry) {
+  if (!entry || typeof entry !== 'object') return false;
+  if (entry.signal) return true;
+  if (entry.failureStage) return true;
+  return entry.exitCode !== 0;
+}
+
+function _formatHistoryFailure(entry) {
+  if (!entry || typeof entry !== 'object') return '';
+
+  if (entry.signal) return `signal ${entry.signal}`;
+  if (entry.failureStage) return `stage ${entry.failureStage}`;
+
+  if (entry.exitCode !== null && entry.exitCode !== undefined && entry.exitCode !== 0) {
+    return `exit code ${entry.exitCode}`;
+  }
+
+  return '';
+}
+
 /**
  * Detect struggle indicators from recent history.
  *
  * @param {Array<object>} recentHistory
  * @returns {Array<string>} Warning messages
  */
-function _detectStruggles(recentHistory) {
+function _detectStruggles(recentHistory, errorEntries = []) {
   const warnings = [];
   if (recentHistory.length < 2) return warnings;
 
@@ -210,22 +249,94 @@ function _detectStruggles(recentHistory) {
     );
   }
 
-  // Repeated errors: multiple non-zero exit codes
-  const errorCount = recentHistory.filter((e) => e.exitCode !== 0).length;
-  if (errorCount >= 2) {
+  const repeatedError = _detectRepeatedError(recentHistory, errorEntries);
+  if (repeatedError) {
     warnings.push(
-      `OpenCode exited with errors in ${errorCount} of the last ${recentHistory.length} iterations.`
+      `Repeated error detected in ${repeatedError.count} of the last ${recentHistory.length} iterations: ${repeatedError.preview}`
     );
   }
 
   return warnings;
 }
 
+function _detectRepeatedError(recentHistory, errorEntries) {
+  if (!Array.isArray(errorEntries) || errorEntries.length < 2) {
+    return null;
+  }
+
+  const recentFailedIterations = new Set(
+    recentHistory
+      .filter((entry) => _isFailedHistoryEntry(entry))
+      .map((entry) => entry.iteration)
+  );
+
+  if (recentFailedIterations.size < 2) {
+    return null;
+  }
+
+  const signatureCounts = new Map();
+
+  for (const entry of errorEntries) {
+    if (!entry || !recentFailedIterations.has(entry.iteration)) {
+      continue;
+    }
+
+    const preview = _formatErrorPreview(entry);
+    const signature = _normalizeErrorSignature(preview);
+    if (!signature) {
+      continue;
+    }
+
+    const existing = signatureCounts.get(signature) || { count: 0, preview };
+    existing.count += 1;
+    if (!existing.preview && preview) {
+      existing.preview = preview;
+    }
+    signatureCounts.set(signature, existing);
+  }
+
+  let bestMatch = null;
+  for (const candidate of signatureCounts.values()) {
+    if (!bestMatch || candidate.count > bestMatch.count) {
+      bestMatch = candidate;
+    }
+  }
+
+  if (!bestMatch || bestMatch.count < 2) {
+    return null;
+  }
+
+  return bestMatch;
+}
+
+function _normalizeErrorSignature(text) {
+  if (!text) return '';
+
+  return text
+    .toLowerCase()
+    .replace(/\b0x[0-9a-f]+\b/g, '<hex>')
+    .replace(/[A-Z]:\\[^\s]+/g, '<path>')
+    .replace(/(?:\/[^\s:]+)+/g, '<path>')
+    .replace(/:\d+:\d+/g, ':<n>:<n>')
+    .replace(/\b\d+\b/g, '<n>')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
 function _formatErrorPreview(entry) {
   if (!entry) return '';
 
   const source = entry.stderr || entry.stdout || _fallbackErrorPreview(entry);
-  return source.substring(0, 200).trim();
+  const metadata = [];
+
+  if (entry.signal) metadata.push(`signal ${entry.signal}`);
+  if (entry.failureStage) metadata.push(`stage ${entry.failureStage}`);
+
+  const preview = metadata.length > 0
+    ? `${metadata.join(' | ')} | ${source}`
+    : source;
+
+  return preview.substring(0, 200).trim();
 }
 
 function _fallbackErrorPreview(entry) {
@@ -235,4 +346,25 @@ function _fallbackErrorPreview(entry) {
   return parts.join(' | ');
 }
 
-module.exports = { render, _elapsed, _detectStruggles, _formatToolUsage, _formatErrorPreview };
+function _latestCommitAnomaly(recentHistory) {
+  if (!Array.isArray(recentHistory) || recentHistory.length === 0) return null;
+
+  for (let idx = recentHistory.length - 1; idx >= 0; idx--) {
+    if (recentHistory[idx] && recentHistory[idx].commitAnomaly) {
+      return recentHistory[idx];
+    }
+  }
+
+  return null;
+}
+
+module.exports = {
+  render,
+  _elapsed,
+  _detectStruggles,
+  _formatToolUsage,
+  _formatErrorPreview,
+  _latestCommitAnomaly,
+  _formatHistoryFailure,
+  _isFailedHistoryEntry,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-and-loop",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "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.0",
+    "spec-and-loop": "^2.1.1"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.0",
+    "@types/jest": "^30.0.0",
     "bats": "^1.13.0",
-    "jest": "^29.7.0"
+    "jest": "^30.0.0"
   },
   "jest": {
     "testEnvironment": "node",

package/scripts/ralph-run.sh

@@ -181,7 +181,7 @@ EXAMPLES:
 
 PREREQUISITES:
     - Git repository (git init)
-    - OpenSpec artifacts created (openspec init, openspec new, openspec ff)
+    - OpenSpec artifacts created (openspec init, openspec new change, then complete the generated artifacts)
     - opencode CLI installed (npm install -g opencode-ai)
 
 EOF
@@ -757,6 +757,10 @@ Include full context from openspec artifacts in {{change_dir}}:
 - Read {{change_dir}}/design.md for the technical design approach
 - Read {{change_dir}}/specs/*/spec.md for the detailed specifications
 
+## Invocation-Time PRD Snapshot
+
+{{base_prompt}}
+
 ## Task List
 
 {{tasks}}
@@ -780,8 +784,7 @@ Include full context from openspec artifacts in {{change_dir}}:
 3. **Complete** task:
    - Verify that the implementation meets the requirements
    - When the task is successfully completed, mark it as [x] in the tasks file
-   - Create a git commit using the required format below
-   - Output: `<promise>{{task_promise}}</promise>`
+    - Output: `<promise>{{task_promise}}</promise>`
 
 4. **Continue** to the next task:
    - The loop will continue with the next iteration
@@ -800,41 +803,9 @@ Include full context from openspec artifacts in {{change_dir}}:
 - If stuck, try a different approach
 - Check your work before claiming completion
 
-## CRITICAL: Git Commit Format (MANDATORY)
-
-When making git commits, you MUST use this EXACT format:
-
-```
-Ralph iteration <N>: <brief description of work completed>
-
-Tasks completed:
-- [x] <task.number> <task description text>
-- [x] <task.number> <task description text>
-...
-```
-
-**Requirements:**
-1. Use iteration number from Ralph's state (e.g., "Ralph iteration 7")
-2. Include a BRIEF description summarizing what was done
-3. List ALL completed tasks with their numbers and full descriptions
-4. Use the EXACT format: "- [x] <task.number> <task description>"
-5. Read the "## Completed Tasks for Git Commit" section from the PRD for the task list
-
-**FORBIDDEN:**
-- DO NOT use generic messages like "work in progress" or "iteration N"
-- DO NOT skip task numbers
-- DO NOT truncate task descriptions
-- DO NOT create commits without task information
-
-**Example:**
-```
-Ralph iteration 7: Implement unit tests for response processing
-
-Tasks completed:
-- [x] 11.6 Write unit test for personality state management
-- [x] 11.7 Write unit test for personality validation
-- [x] 11.8 Write unit test for system prompt validation
-```
+## Commit Contract
+
+{{commit_contract}}
 
 {{context}}
 EOF

package/scripts/setup.js

@@ -32,16 +32,17 @@ function runSetup() {
   console.log('Usage:');
   console.log('  cd /path/to/your/project');
   console.log('  openspec init                    # Initialize OpenSpec');
-  console.log('  openspec new <name>             # Create a new change');
-  console.log('  openspec ff <name>              # Fast-forward artifacts');
+  console.log('  openspec new change <name>      # Create a new change');
   console.log('  ralph-run --change <name>       # Run ralph loop');
   console.log('  ralph-run                       # Auto-detect change');
+  console.log('  ralph-run --status              # Show loop status');
   console.log('');
   console.log('Prerequisites:');
-  console.log('  - openspec CLI: npm install -g openspec');
+  console.log('  - openspec CLI: npm install -g @fission-ai/openspec');
   console.log('  - opencode CLI: npm install -g opencode-ai');
   console.log('  - jq CLI: apt install jq / brew install jq');
   console.log('  - git: git init');
+  console.log('  - supported OS: Linux or macOS');
 }
 
 if (require.main === module) {