spec-and-loop 2.0.0 → 2.0.1

package/QUICKSTART.md

@@ -1,5 +1,7 @@
 # Quick Start Guide
 
+> **Version Compatibility:** OpenSpec 1.2.0 | spec-and-loop 2.0.0
+
 Get up and running with **spec-and-loop** in 5 minutes!
 
 ## Prerequisites
@@ -7,8 +9,8 @@ Get up and running with **spec-and-loop** in 5 minutes!
 Install these tools (one-time setup):
 
 ```bash
-# 1. Install openspec (OpenSpec CLI)
-npm install -g @fission-ai/openspec@latest
+# 1. Install openspec (OpenSpec CLI) - pinned to version 1.2.0
+npm install -g @fission-ai/openspec@1.2.0
 
 # 2. Install opencode (agentic coding assistant)
 npm install -g opencode-ai
@@ -24,7 +26,8 @@ brew install jq
 git init
 ```
 
-> **Note:** No external `ralph` CLI needed — `spec-and-loop` includes its own internal
+> **Note:** This guide is for OpenSpec 1.2.0 and spec-and-loop 2.0.0.
+> No external `ralph` CLI needed — `spec-and-loop` includes its own internal
 > mini Ralph loop engine. Just install `opencode` and you're ready to go. The
 > runtime prompt is self-contained and does not depend on editor-specific slash
 > commands or local-only skills.
@@ -32,7 +35,7 @@ git init
 ## Installation
 
 ```bash
-npm install -g spec-and-loop
+npm install -g spec-and-loop@2.0.0
 ```
 
 ## Quick Demo (5 Minutes)
@@ -47,10 +50,13 @@ git init
 openspec init
 
 # 3. Create a new change
-openspec new add-hello-world
+openspec new change add-hello-world
 
-# 4. Fast-forward through artifact creation
-openspec ff
+# 4. Review and complete the OpenSpec artifacts
+#    (openspec/changes/add-hello-world/proposal.md)
+#    (openspec/changes/add-hello-world/design.md)
+#    (openspec/changes/add-hello-world/specs/*/spec.md)
+#    (openspec/changes/add-hello-world/tasks.md)
 
 # 5. Run the ralph loop (executes tasks with opencode)
 ralph-run --change add-hello-world
@@ -101,12 +107,27 @@ ralph-run --status
 ### OpenSpec Commands
 
 ```bash
-openspec init                  # Initialize in current directory
-openspec new <name>             # Start a new change
-openspec continue <name>         # Continue working on change
-openspec ff <name>              # Fast-forward artifact creation
-openspec apply <name>           # Apply change (implementation)
-openspec archive <name>          # Archive completed change
+# Core workflow
+openspec init                  # Initialize OpenSpec in current directory
+openspec new change <name>      # Create a new change directory
+openspec show <item-name>      # Show a change or spec in detail
+openspec archive <change-name> # Archive a completed change
+
+# Information and status
+openspec list                  # List all active changes (use --specs to list specs)
+openspec status --change <name> # Display artifact completion status for a change
+openspec validate <item-name> # Validate changes and specs
+
+# View and manage
+openspec view                  # Display interactive dashboard of specs and changes
+openspec update                # Update OpenSpec instruction files
+openspec config                # View and modify global OpenSpec configuration
+
+# Advanced
+openspec spec                  # Manage and view OpenSpec specifications
+openspec instructions         # Output enriched instructions for creating artifacts
+openspec templates             # Show resolved template paths for artifacts
+openspec schemas               # List available workflow schemas
 ```
 
 ### Ralph Loop Commands
@@ -133,7 +154,7 @@ git init
 openspec init
 
 # 2. Create a feature
-openspec new user-authentication
+openspec new change user-authentication
 
 # 3. Go through the workflow
 # - Create proposal: Why add auth?
@@ -141,77 +162,257 @@ openspec new user-authentication
 # - Create design: Use JWT, store hashed passwords
 # - Create tasks: 15 checkboxes for implementation
 
-# 4. Fast-forward to create all artifacts
-openspec ff user-authentication
-
-# 5. Execute the implementation
+# 4. Execute the implementation
 ralph-run --change user-authentication
 
-# 6. Watch the magic happen!
+# 5. Watch the magic happen!
 # [INFO] Found 15 tasks to execute
 # [INFO] Executing task 1/15: Create User model
 # [INFO] Executing task 2/15: Implement password hashing
 # ...
 
-# 7. Add context mid-run if needed (from another terminal)
+# 6. Add context mid-run if needed (from another terminal)
 ralph-run --add-context "Prefer bcrypt over argon2 for password hashing"
 
-# 8. Check status
+# 7. Check status
 ralph-run --status
 
-# 9. Verify the implementation
+# 8. Verify the implementation
 git log --oneline      # 15 commits, one per task
 git diff HEAD~15        # See full implementation
 ```
 
 ## Troubleshooting
 
-### "openspec CLI not found" or "opencode CLI not found"
+### "openspec: command not found"
+
+**Problem:** OpenSpec CLI is not installed or not in PATH
+
+**Solution:**
+```bash
+# Install with pinned version (recommended)
+npm install -g @fission-ai/openspec@1.2.0
+
+# Verify installation
+openspec --version
+
+# If command still not found, add npm global bin to PATH
+export PATH="$PATH:$(npm root -g)/.bin"
+```
+
+### "opencode: command not found"
 
+**Problem:** opencode CLI is not installed or not in PATH
+
+**Solution:**
 ```bash
-npm install -g @fission-ai/openspec@latest opencode-ai
+# Install opencode
+npm install -g opencode-ai
+
+# Verify installation
+opencode --version
+
+# If command still not found, add npm global bin to PATH
+export PATH="$PATH:$(npm root -g)/.bin"
 ```
 
 ### "jq CLI not found"
 
+**Problem:** jq (JSON processor) is not installed
+
+**Solution:**
 ```bash
 # Ubuntu/Debian
 sudo apt install jq
 
 # macOS
 brew install jq
+
+# Verify installation
+jq --version
 ```
 
 ### "Not a git repository"
 
+**Problem:** You're not in a git repository
+
+**Solution:**
 ```bash
+# Initialize git in current directory
 git init
+
+# Verify
+git status
 ```
 
 ### "command not found: ralph-run"
 
-**Problem:** npm bin directory not in PATH
+**Problem:** spec-and-loop npm bin directory not in PATH
 
 **Solution:**
 ```bash
-# Add to ~/.bashrc or ~/.zshrc
-export PATH="$PATH:$(npm root -g)/.bin"
+# Add npm global bin directory to PATH
+echo 'export PATH="$PATH:$(npm root -g)/.bin"' >> ~/.bashrc
+# Or for zsh:
+echo 'export PATH="$PATH:$(npm root -g)/.bin"' >> ~/.zshrc
 
 # Reload shell
 source ~/.bashrc
+# or
+source ~/.zshrc
+
+# Verify
+ralph-run --help
+```
+
+### "Internal mini Ralph runtime not found"
+
+**Problem:** spec-and-loop installation is incomplete or node is missing
+
+**Solution:**
+```bash
+# Ensure spec-and-loop is properly installed
+npm uninstall -g spec-and-loop
+npm install -g spec-and-loop
+
+# Ensure Node.js is installed (version 24.0.0 or higher)
+node --version
+
+# If node is not installed, install from https://nodejs.org
+```
+
+### "OpenSpec changes directory not found"
+
+**Problem:** OpenSpec has not been initialized or no changes exist
+
+**Solution:**
+```bash
+# Initialize OpenSpec
+openspec init
+
+# Create a new change
+openspec new change my-feature
+
+# Verify directory exists
+ls -la openspec/changes/
+```
+
+### "No changes found with tasks.md"
+
+**Problem:** No OpenSpec changes with tasks files exist
+
+**Solution:**
+```bash
+# List available changes
+openspec list
+
+# Create a new change if needed
+openspec new change my-new-feature
+
+# Ensure tasks.md exists in your change directory
+ls -la openspec/changes/my-new-feature/tasks.md
 ```
 
 ### "No tasks to execute"
 
-**Problem:** All tasks already complete (or tasks.md has no unchecked items)
+**Problem:** All tasks in tasks.md are already marked complete
+
+**Solution:**
+```bash
+# Check tasks.md for incomplete tasks
+grep "^\- \[ \]" openspec/changes/my-new-feature/tasks.md
+
+# If no incomplete tasks, create a new change
+openspec new change another-feature
+
+# Or uncheck a task by editing tasks.md manually:
+# Change: - [x] This task is done
+# To:     - [ ] This task needs work
+```
+
+### "Required artifact not found"
+
+**Problem:** OpenSpec artifacts (proposal.md, design.md, tasks.md) are missing
 
 **Solution:**
 ```bash
-# Check tasks.md
-grep "^\- \[ \]" openspec/changes/my-feature/tasks.md
+# Check what artifacts exist in your change directory
+ls -la openspec/changes/my-new-feature/
+
+# Create missing artifacts manually or use openspec new change
+openspec new change my-new-feature
+
+# Or manually create the required files:
+# - openspec/changes/my-new-feature/proposal.md
+# - openspec/changes/my-new-feature/design.md
+# - openspec/changes/my-new-feature/specs/spec-name/spec.md
+# - openspec/changes/my-new-feature/tasks.md
+```
+
+### "Required directory not found: specs/"
+
+**Problem:** The specs directory is missing from your change
+
+**Solution:**
+```bash
+# Create the specs directory
+mkdir -p openspec/changes/my-new-feature/specs
+
+# Create at least one spec file
+mkdir -p openspec/changes/my-new-feature/specs/main-feature
+echo "# Main Feature Spec" > openspec/changes/my-new-feature/specs/main-feature/spec.md
+
+# Verify
+ls -la openspec/changes/my-new-feature/specs/
+```
+
+### "opencode CLI not found"
+
+**Problem:** opencode is not installed globally
+
+**Solution:**
+```bash
+# Install opencode
+npm install -g opencode-ai
+
+# Verify installation
+opencode --version
+
+# Add to PATH if needed
+export PATH="$PATH:$(npm root -g)/.bin"
+```
+
+### "Node.js version too old"
+
+**Problem:** Node.js version is below the required version (24.0.0+)
+
+**Solution:**
+```bash
+# Check current Node.js version
+node --version
+
+# If version is below 24.0.0, upgrade Node.js:
+# Using nvm (recommended):
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install 24
+nvm use 24
+
+# Or install from https://nodejs.org
+```
+
+### "npm: command not found"
+
+**Problem:** npm is not installed or not in PATH
+
+**Solution:**
+```bash
+# npm comes with Node.js. Install Node.js from https://nodejs.org
+
+# After installing Node.js, verify:
+npm --version
+node --version
 
-# Or create a new change
-openspec new another-feature
+# If still not found, restart your terminal or add to PATH
 ```
 
 ## Features at a Glance

package/README.md

@@ -4,7 +4,9 @@ OpenSpec + Ralph Loop integration for iterative development with opencode.
 
 ![CI Status](https://img.shields.io/github/actions/workflow/status/ncheaz/spec-and-loop/test.yml)
 ![Coverage](https://img.shields.io/badge/coverage-0%25-red)
-[![npm version](https://badge.fury.io/js/spec-and-loop.svg)](https://badge.fury.io/js/spec-and-loop)
+[![npm version](https://badge.fury.io/js/spec-and-loop.svg)](https://badge.fury.io/js/spec-and-loop.svg)
+
+**Version:** spec-and-loop 2.0.0 + OpenSpec 1.2.0
 
 **[Quick Start Guide](./QUICKSTART.md)** - Get up and running in 5 minutes!
 
@@ -14,16 +16,18 @@ OpenSpec provides excellent structure for planning (proposal → specs → desig
 
 The runtime prompt is self-contained: it does not depend on Cursor-only slash commands or editor-local skills.
 
+**Version Requirements:** This documentation applies to OpenSpec 1.2.0 and spec-and-loop 2.0.0.
+
 ## Installation
 
 ```bash
-npm install -g spec-and-loop
+npm install -g spec-and-loop@2.0.0
 ```
 
 **Prerequisites:** You need OpenSpec and the OpenCode AI agent installed:
 
 ```bash
-npm install -g @fission-ai/openspec@latest opencode-ai
+npm install -g @fission-ai/openspec@1.2.0 opencode-ai
 ```
 
 Alternative OpenCode install methods:
@@ -43,10 +47,13 @@ brew install anomalyco/tap/opencode
 openspec init
 
 # 2. Create a new change
-openspec new add-user-auth
+openspec new change add-user-auth
 
-# 3. Fast-forward through artifact creation
-openspec ff add-user-auth
+# 3. Review and complete the OpenSpec artifacts
+#    (openspec/changes/add-user-auth/proposal.md)
+#    (openspec/changes/add-user-auth/design.md)
+#    (openspec/changes/add-user-auth/specs/*/spec.md)
+#    (openspec/changes/add-user-auth/tasks.md)
 
 # 4. Run the ralph loop (executes tasks with opencode)
 ralph-run --change add-user-auth
@@ -56,6 +63,8 @@ For detailed step-by-step instructions, see [QUICKSTART.md](./QUICKSTART.md).
 
 ## Testing
 
+*Testing suite for spec-and-loop 2.0.0*
+
 Spec-and-loop includes a comprehensive test suite to ensure reliability and cross-platform compatibility.
 
 **[Testing Guide](./TESTING.md)** - Detailed instructions for running tests
@@ -89,17 +98,19 @@ All tests are run automatically via GitHub Actions on every push and pull reques
 
 ## Prerequisites
 
+*Required for spec-and-loop 2.0.0 with OpenSpec 1.2.0*
+
 Before using spec-and-loop, ensure you have:
 
-1. **Node.js** - For package installation
-   ```bash
-   node --version  # Should be >=24
-   ```
+ 1. **Node.js** - For package installation (requires >=24.0.0)
+    ```bash
+    node --version  # Should be >=24.0.0
+    ```
 
-2. **openspec** - OpenSpec CLI for specification workflow
-   ```bash
-   npm install -g @fission-ai/openspec@latest
-   ```
+ 2. **openspec** - OpenSpec CLI for specification workflow (requires 1.2.0)
+    ```bash
+    npm install -g @fission-ai/openspec@1.2.0
+    ```
 
 3. **opencode** - Agentic coding assistant
    ```bash
@@ -124,14 +135,13 @@ For complete installation instructions, see [QUICKSTART.md](./QUICKSTART.md).
 
 ## Commands
 
+*Documentation applies to OpenSpec 1.2.0 and spec-and-loop 2.0.0*
+
 ### OpenSpec Commands
 
 - `openspec init` - Initialize OpenSpec in current directory
-- `openspec new <name>` - Start a new change
-- `openspec ff <name>` - Fast-forward artifact creation
-- `openspec continue <name>` - Continue working on change
-- `openspec apply <name>` - Apply change (implementation)
-- `openspec archive <name>` - Archive a completed change
+- `openspec new change <name>` - Create a new change with artifact templates
+- `openspec --help` - View all available commands and their syntax
 
 ### Ralph Loop Commands
 
@@ -139,24 +149,26 @@ For complete installation instructions, see [QUICKSTART.md](./QUICKSTART.md).
 ralph-run [OPTIONS]
 
 OPTIONS:
-    --change <name>          OpenSpec change to execute (default: auto-detect)
-    --max-iterations <n>     Maximum iterations (default: 50)
-    --no-commit              Suppress automatic git commits
-    --verbose, -v            Enable verbose output
+    --change <name>          Specify the OpenSpec change to execute (default: auto-detect)
+    --max-iterations <n>     Maximum iterations for Ralph loop (default: 50)
+    --no-commit              Suppress automatic git commits during the loop
+    --verbose, -v            Enable verbose mode for debugging
+    --help, -h               Show this help message
 
 OBSERVABILITY AND CONTROL:
-    --status                 Print loop status dashboard and exit
-    --add-context <text>     Add context to inject into the next iteration
-    --clear-context          Clear any pending context
+    --status                 Print the current loop status dashboard and exit
+    --add-context <text>     Add pending context to inject into the next iteration and exit
+    --clear-context          Clear any pending context and exit
 ```
 
 ## How It Works
 
+*Workflow for OpenSpec 1.2.0 + spec-and-loop 2.0.0*
+
 ### Step 1: Create Spec with OpenSpec
 
 ```bash
-openspec new my-feature
-openspec ff my-feature
+openspec new change my-feature
 ```
 
 This creates:
@@ -165,6 +177,8 @@ This creates:
 - **design.md**: Technical decisions and architecture
 - **tasks.md**: Implementation tasks as checkboxes
 
+After creating the change, manually complete the OpenSpec artifacts by filling in proposal.md, design.md, specs/*/spec.md, and tasks.md.
+
 **Example tasks.md:**
 ```markdown
 ## Implementation
@@ -185,12 +199,16 @@ ralph-run --change my-feature
 
 1. **Validation**: Checks for required OpenSpec artifacts and git repository
 2. **PRD Generation**: Converts proposal + specs + design → PRD format for internal use
-3. **Task Execution**: For each incomplete task:
+3. **Setup**: Creates .ralph directory, syncs tasks symlink, and sets up output capture
+4. **Task Execution**: For each incomplete task:
    - Generates context-rich prompt (full OpenSpec artifacts + a fresh task snapshot + recent loop signals)
    - Runs `opencode` with the prompt via the internal mini Ralph engine
+   - Captures output to temp directory for review and debugging
+   - Logs any errors to `.ralph/errors.md` with timestamps
    - Creates git commit with task description (unless `--no-commit`)
    - Marks task complete in tasks.md
-4. **Completion**: All tasks done
+5. **Cleanup**: Automatically removes old output directories (older than 7 days)
+6. **Completion**: All tasks done
 
 ### Step 3: Monitor Progress
 
@@ -210,12 +228,21 @@ ralph-run --add-context "Prefer async/await over callbacks"
 
 ## Example Workflow
 
+*Example workflow for OpenSpec 1.2.0 and spec-and-loop 2.0.0*
+
 ```bash
-# 1. Plan feature with OpenSpec
-openspec new user-auth
-openspec ff user-auth
+# 1. Initialize OpenSpec in your project
+cd my-web-app
+git init
+openspec init
 
-# 2. Execute with Ralph
+# 2. Create a new change
+openspec new change user-auth
+
+# 3. Complete OpenSpec artifacts manually or use opencode skills
+#    (review and fill in proposal.md, design.md, specs/*/spec.md, tasks.md)
+
+# 4. Execute with Ralph
 ralph-run --change user-auth
 
 # Output:
@@ -224,7 +251,7 @@ ralph-run --change user-auth
 # [INFO] Executing task 2/15: Implement password hashing
 # ...
 
-# 3. Verify implementation
+# 5. Verify implementation
 git log --oneline  # 15 commits, one per task
 git diff HEAD~15   # See full implementation
 ```
@@ -241,10 +268,15 @@ git diff HEAD~15   # See full implementation
 | **Auto-Resume** | Interrupted? Run again — picks up where left off |
 | **Context Injection** | `--add-context` injects guidance into the next iteration |
 | **Loop Status** | `--status` shows active state, history, and struggle indicators |
+| **Error Tracking** | Automatic error logging and archiving for debugging |
+| **Output Capture** | Loop output captured to temp directories for review |
+| **Cross-Platform** | Full support for Linux and macOS with portable operations |
 | **No External Ralph** | Self-contained mini Ralph engine — no external `ralph` CLI needed |
 
 ## Features
 
+*Features available in spec-and-loop 2.0.0 with OpenSpec 1.2.0*
+
 ### Mini Ralph Loop Engine
 
 `spec-and-loop` includes a first-party mini Ralph implementation (`lib/mini-ralph/`) that
@@ -272,11 +304,17 @@ this repository's OpenSpec-first workflow (multi-agent rotation, plugin toggles,
 - **Auto-resume**: Interrupted? Run again — picks up where left off
 - **Context injection**: `--add-context` / `--clear-context` via each change's `.ralph/ralph-context.md`
 - **Error recovery**: Recent loop signals help guide subsequent tasks
+- **Error tracking**: Automatic error logging to `.ralph/errors.md` with timestamps and archiving
 - **Task synchronization**: `tasks.md` and the per-change `.ralph/ralph-tasks.md` symlink stay in sync
+- **Output capture**: Loop output captured to temp directories for review and debugging
+- **Cross-platform**: Portable operations for Linux and macOS (stat, md5sum, realpath)
+- **Cleanup**: Automatic cleanup of old output directories (older than 7 days)
 - **Idempotent**: Run multiple times safely
 
 ## Advanced Usage
 
+*Advanced features for spec-and-loop 2.0.0*
+
 ### Context Injection
 
 Inject custom instructions into the next iteration:
@@ -322,8 +360,33 @@ ralph-run --verbose --change my-feature
 cat openspec/changes/my-feature/.ralph/PRD.md
 ```
 
+### Review Loop Output
+
+```bash
+# Find the latest output directory path
+cat openspec/changes/my-feature/.ralph/.output_dir
+
+# View stdout and stderr logs
+cat openspec/changes/my-feature/.ralph/.output_dir/ralph-stdout.log
+cat openspec/changes/my-feature/.ralph/.output_dir/ralph-stderr.log
+```
+
+Output is captured to temporary directories for debugging. Old output directories are automatically cleaned up after 7 days.
+
+### View Error Logs
+
+```bash
+# View recent errors
+cat openspec/changes/my-feature/.ralph/errors.md
+
+# Archived errors are saved with timestamps
+ls openspec/changes/my-feature/.ralph/errors_*.md
+```
+
 ## Architecture
 
+*Architecture for spec-and-loop 2.0.0 with OpenSpec 1.2.0*
+
 This package integrates:
 - **OpenSpec**: Structured specification workflow
 - **opencode**: Agentic coding assistant for task execution
@@ -357,16 +420,41 @@ openspec/changes/<name>/
 │   └── api/
 │       └── spec.md
 └── .ralph/              # Internal loop state (auto-generated, per change)
-    ├── PRD.md
-    ├── ralph-tasks.md
-    ├── ralph-context.md
-    ├── ralph-history.json
-    ├── ralph-loop.state.json
-    └── prompt-template.md
+    ├── PRD.md                    # Generated product requirements document
+    ├── prompt-template.md       # Template used for generating prompts
+    ├── ralph-history.json       # Iteration history and state
+    ├── ralph-loop.state.json    # Current loop state and iteration count
+    ├── ralph-tasks.md           # Symlink to ../tasks.md (syncs task state)
+    ├── .output_dir              # Path to latest output capture directory
+    ├── ralph-context.md         # (Optional) Pending context for next iteration
+    ├── errors.md                # (Optional) Error logs with timestamps
+    ├── errors_*.md              # (Optional) Archived error logs
+    └── *.md                     # (Optional) Research artifacts created during task execution
 ```
 
+**Note:** Files marked as (Optional) are created only when needed:
+- `ralph-context.md`: Created when you use `--add-context`
+- `errors.md` and `errors_*.md`: Created when errors occur during loop execution
+- Additional `*.md` files: Research artifacts created by opencode during task execution (e.g., verification outputs, analysis documents)
+
+### Cross-Platform Support
+
+*Cross-platform support verified for spec-and-loop 2.0.0*
+
+`spec-and-loop` is designed to work seamlessly on both Linux and macOS. The script includes portable implementations for:
+
+- **File modification times**: Uses `stat -f %m` on macOS and `stat -c %Y` on Linux
+- **MD5 hashing**: Supports both `md5sum` (Linux) and `md5 -q` (macOS)
+- **Path resolution**: Falls back from `realpath` to `readlink -f` to manual path construction
+- **Temp directories**: Uses `TMPDIR` environment variable or `/tmp` as fallback
+- **Cleanup**: Portable `find` and `rm` operations for old output directories
+
+All features work identically on both platforms without requiring platform-specific configuration.
+
 ## Troubleshooting
 
+*Troubleshooting guide for spec-and-loop 2.0.0 with OpenSpec 1.2.0*
+
 For common issues and solutions, see [QUICKSTART.md#troubleshooting](./QUICKSTART.md#troubleshooting).
 
 **Quick fixes:**

package/lib/mini-ralph/errors.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ERRORS_FILE = 'errors.md';
+
+function errorsPath(ralphDir) {
+  return path.join(ralphDir, ERRORS_FILE);
+}
+
+function read(ralphDir, limit) {
+  const file = errorsPath(ralphDir);
+  if (!fs.existsSync(file)) return '';
+  const content = fs.readFileSync(file, 'utf8').trim();
+  if (!content) return '';
+  const entries = content.split(/^---$/m).filter(e => e.trim());
+  if (!entries.length) return '';
+  if (limit !== undefined && limit < entries.length) {
+    return entries.slice(-limit).join('\n---\n');
+  }
+  return entries.join('\n---\n');
+}
+
+function append(ralphDir, entry) {
+  _ensureDir(ralphDir);
+  const file = errorsPath(ralphDir);
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const separator = existing && !existing.endsWith('\n') ? '\n' : '';
+  const timestamp = new Date().toISOString();
+  const text = [
+    '---',
+    `Timestamp: ${timestamp}`,
+    `Iteration: ${entry.iteration}`,
+    `Task: ${entry.task}`,
+    `Exit Code: ${entry.exitCode}`,
+    '',
+    '### stderr',
+    entry.stderr || '',
+    '',
+    '### stdout',
+    entry.stdout || '',
+    '',
+  ].join('\n');
+  fs.writeFileSync(file, `${existing}${separator}${text}`, 'utf8');
+}
+
+function clear(ralphDir) {
+  const file = errorsPath(ralphDir);
+  if (fs.existsSync(file)) {
+    fs.unlinkSync(file);
+  }
+}
+
+function archive(ralphDir) {
+  const file = errorsPath(ralphDir);
+  if (!fs.existsSync(file)) return null;
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const archiveFile = path.join(ralphDir, `errors_${timestamp}.md`);
+  fs.copyFileSync(file, archiveFile);
+  return archiveFile;
+}
+
+function _ensureDir(ralphDir) {
+  if (!fs.existsSync(ralphDir)) {
+    fs.mkdirSync(ralphDir, { recursive: true });
+  }
+}
+
+module.exports = { errorsPath, read, append, clear, archive };

package/lib/mini-ralph/index.js

@@ -18,6 +18,7 @@ const runner = require('./runner');
 const state = require('./state');
 const history = require('./history');
 const context = require('./context');
+const errors = require('./errors');
 const tasks = require('./tasks');
 const status = require('./status');
 const prompt = require('./prompt');
@@ -84,6 +85,7 @@ module.exports = {
   _state: state,
   _history: history,
   _context: context,
+  _errors: errors,
   _tasks: tasks,
   _prompt: prompt,
   _runner: runner,

package/lib/mini-ralph/invoker.js

@@ -67,6 +67,7 @@ async function invoke(opts) {
 
   return {
     stdout: result.stdout,
+    stderr: result.stderr,
     exitCode: result.exitCode,
     toolUsage: _extractToolUsage(result.stdout),
     filesChanged,

package/lib/mini-ralph/runner.js

@@ -18,6 +18,7 @@ const context = require('./context');
 const tasks = require('./tasks');
 const prompt = require('./prompt');
 const invoker = require('./invoker');
+const errors = require('./errors');
 
 const DEFAULTS = {
   minIterations: 1,
@@ -93,7 +94,8 @@ async function run(opts) {
 
     // Build the prompt for this iteration
     const renderedPrompt = await prompt.render(options, iterationCount);
-    const iterationFeedback = _buildIterationFeedback(history.recent(ralphDir, 3));
+    const errorContent = errors.read(ralphDir, 3);
+    const iterationFeedback = _buildIterationFeedback(history.recent(ralphDir, 3), errorContent);
 
     // Inject any pending context
     const pendingContext = context.consume(ralphDir);
@@ -146,6 +148,17 @@ async function run(opts) {
       completedTasks: completedTasks.map((task) => task.fullDescription || task.description),
     });
 
+    if (result.exitCode !== 0) {
+      const currentTask = _getCurrentTaskDescription(tasksBefore);
+      errors.append(ralphDir, {
+        iteration: iterationCount,
+        task: currentTask,
+        exitCode: result.exitCode,
+        stderr: result.stderr || '',
+        stdout: result.stdout || '',
+      });
+    }
+
     // Auto-commit only for successful task/completion iterations.
     if (
       !options.noCommit &&
@@ -174,6 +187,14 @@ async function run(opts) {
     }
   }
 
+  if (completed) {
+    const archivePath = errors.archive(ralphDir);
+    if (archivePath && options.verbose) {
+      process.stderr.write(`[mini-ralph] errors archived to ${archivePath}\n`);
+    }
+    errors.clear(ralphDir);
+  }
+
   // Mark loop as inactive
   state.update(ralphDir, { active: false, completedAt: new Date().toISOString() });
 
@@ -321,7 +342,7 @@ function _formatAutoCommitMessage(iteration, completedTasks) {
  * @param {Array<object>} recentHistory
  * @returns {string}
  */
-function _buildIterationFeedback(recentHistory) {
+function _buildIterationFeedback(recentHistory, errorContent) {
   if (!Array.isArray(recentHistory) || recentHistory.length === 0) {
     return '';
   }
@@ -344,7 +365,22 @@ function _buildIterationFeedback(recentHistory) {
     }
 
     if (issues.length > 0) {
-      problemLines.push(`- Iteration ${entry.iteration}: ${issues.join('; ')}.`);
+      let line = `- Iteration ${entry.iteration}: ${issues.join('; ')}.`;
+
+      if (entry.exitCode !== 0 && errorContent) {
+        const errorDetails = _extractErrorForIteration(errorContent, entry.iteration);
+        if (errorDetails) {
+          line += '\n  Error output:';
+          if (errorDetails.stderr) {
+            line += `\n  ${errorDetails.stderr}`;
+          }
+          if (errorDetails.stdout) {
+            line += `\n  stdout: ${errorDetails.stdout}`;
+          }
+        }
+      }
+
+      problemLines.push(line);
     }
   }
 
@@ -358,6 +394,39 @@ function _buildIterationFeedback(recentHistory) {
   ].join('\n');
 }
 
+function _extractErrorForIteration(errorContent, iteration) {
+  if (!errorContent) return null;
+
+  const entries = errorContent.split(/^---$/m).filter((e) => e.trim());
+
+  for (const entry of entries) {
+    if (!entry.includes(`Iteration: ${iteration}`)) continue;
+
+    let stderr = '';
+    let stdout = '';
+
+    const stderrMatch = entry.match(/### stderr\n([\s\S]*?)(?=\n### stdout|$)/);
+    const stdoutMatch = entry.match(/### stdout\n([\s\S]*?)$/);
+
+    if (stderrMatch) stderr = stderrMatch[1].trim();
+    if (stdoutMatch) stdout = stdoutMatch[1].trim();
+
+    if (stderr.length > 2000) stderr = stderr.substring(0, 2000) + '...';
+    if (stdout.length > 500) stdout = stdout.substring(0, 500) + '...';
+
+    return { stderr, stdout };
+  }
+
+  return null;
+}
+
+function _getCurrentTaskDescription(tasksBefore) {
+  if (!Array.isArray(tasksBefore) || tasksBefore.length === 0) return 'N/A';
+  const incomplete = tasksBefore.find((t) => t.status !== 'completed');
+  if (incomplete) return incomplete.fullDescription || incomplete.description || 'N/A';
+  return 'N/A';
+}
+
 function _taskIdentity(task) {
   return task.number
     ? `${task.number}|${task.fullDescription || task.description}`
@@ -412,4 +481,6 @@ module.exports = {
   _completedTaskDelta,
   _formatAutoCommitMessage,
   _buildIterationFeedback,
+  _extractErrorForIteration,
+  _getCurrentTaskDescription,
 };

package/lib/mini-ralph/status.js

@@ -12,6 +12,7 @@ const state = require('./state');
 const history = require('./history');
 const context = require('./context');
 const tasks = require('./tasks');
+const errors = require('./errors');
 
 /**
  * Render a status dashboard string for the given .ralph/ directory.
@@ -99,6 +100,19 @@ function render(ralphDir, tasksFile) {
     lines.push('-'.repeat(50));
   }
 
+  // Error history
+  const errorContent = errors.read(ralphDir, 3);
+  if (errorContent) {
+    const entries = errorContent.split(/^---$/m).filter(e => e.trim());
+    const count = entries.length;
+    const preview = entries[entries.length - 1].substring(0, 200).trim();
+    lines.push('');
+    lines.push('--- Error History ---');
+    lines.push(`  Errors: ${count}`);
+    lines.push(`  Most recent: ${preview}`);
+    lines.push('-'.repeat(50));
+  }
+
   // Struggle indicators
   const struggles = _detectStruggles(recentHistory);
   if (struggles.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-and-loop",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "OpenSpec + Ralph Loop integration for iterative development with opencode",
   "main": "index.js",
   "bin": {
@@ -17,7 +17,8 @@
     "lint": "shellcheck scripts/*.sh"
   },
   "dependencies": {
-    "@fission-ai/openspec": "1.2.0"
+    "@fission-ai/openspec": "1.2.0",
+    "spec-and-loop": "^2.0.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.0",

package/scripts/ralph-run.sh

@@ -496,6 +496,10 @@ check_tasks_modified() {
     return 1
 }
 
+# DEPRECATED: The following functions are superseded by lib/mini-ralph/errors.js.
+# Do not add new callers. These will be removed in a future cleanup.
+# See: lib/mini-ralph/errors.js for the current implementation.
+
 format_error_entry() {
     local task_id="$1"
     local task_description="$2"