spec-and-loop 1.0.8 → 1.2.0

package/README.md

@@ -4,53 +4,56 @@ 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)
 
-**[🚀 Quick Start Guide](./QUICKSTART.md)** - Get up and running in 5 minutes!
+**Version:** spec-and-loop 2.0.0 + OpenSpec 1.2.0
+
+**[Quick Start Guide](./QUICKSTART.md)** - Get up and running in 5 minutes!
 
 ## Why This Exists
 
-OpenSpec provides excellent structure for planning (proposal → specs → design → tasks) but leaves execution manual. Ralph Wiggum's iterative development loop (execute → commit → repeat) is powerful but requires PRD format instead of OpenSpec specs.
+OpenSpec provides excellent structure for planning (proposal → specs → design → tasks) but leaves execution manual. This package provides an iterative development loop — execute → commit → repeat — driven by an internal mini Ralph implementation that works with OpenCode and eliminates the need for any external Ralph runtime.
+
+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
-# Install OpenSpec and OpenCode (recommended)
-npm install -g @fission-ai/openspec@latest opencode-ai
+npm install -g @fission-ai/openspec@1.2.0 opencode-ai
 ```
 
-Alternative OpenCode install methods (if you prefer):
+Alternative OpenCode install methods:
 
 ```bash
-# npm (recommended)
-npm install -g opencode-ai
-
 # Install script (general use)
 curl -fsSL https://opencode.ai/install | bash
 
 # Homebrew (macOS / Linux)
 brew install anomalyco/tap/opencode
-
-# Windows: use WSL and install via one of the Linux methods above
 ```
 
-**[🚀 Get Started in 5 Minutes](./QUICKSTART.md)**
+**[Get Started in 5 Minutes](./QUICKSTART.md)**
 
 ```bash
 # 1. Initialize OpenSpec in your project
 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
@@ -58,13 +61,13 @@ ralph-run --change add-user-auth
 
 For detailed step-by-step instructions, see [QUICKSTART.md](./QUICKSTART.md).
 
-<!-- Duplicate Quick Start removed; see QUICKSTART.md for full instructions -->
-
 ## 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
+**[Testing Guide](./TESTING.md)** - Detailed instructions for running tests
 
 ### Quick Test Commands
 
@@ -93,98 +96,24 @@ npm run lint
 
 All tests are run automatically via GitHub Actions on every push and pull request.
 
-### CI/CD Workflow
-
-The CI/CD pipeline is defined in `.github/workflows/test.yml` and performs the following steps:
-
-1. **Checkout Code**: Pulls the latest code from the repository
-2. **Setup Node.js**: Installs Node.js version 24 with npm caching
-3. **Install System Dependencies**:
-   - Linux: `apt-get install bats-core jq shellcheck`
-   - macOS: `brew install bats-core jq shellcheck`
-4. **Install npm Dependencies**: Runs `npm ci` to install dependencies
-5. **Install Global CLIs**: Installs openspec, ralph, and opencode globally
-6. **Run Shellcheck Linting**: Checks bash scripts for errors and best practices
-7. **Run Unit Tests**: Executes bash and JavaScript unit tests
-8. **Run Integration Tests**: Validates full workflow end-to-end
-9. **Upload Artifacts**: Uploads test logs and coverage reports
-
-### Triggering CI/CD
-
-The workflow runs automatically on:
-- Push to `main` or `develop` branches
-- Pull requests to `main` or `develop` branches
-- Manual trigger via GitHub Actions UI
-
-To manually trigger:
-1. Go to Actions tab in GitHub
-2. Select "Test Suite" workflow
-3. Click "Run workflow"
-4. Select branch and test suite (all/unit/integration)
-
-### Troubleshooting CI/CD
-
-**Tests Failing on One Platform**
-
-If tests pass on Linux but fail on macOS (or vice versa):
-- Check for platform-specific command differences (GNU vs BSD tools)
-- Review platform-specific tests in `test-symlink-linux.bats`, `test-symlink-macos.bats`, etc.
-- Verify stat, md5sum/md5, and other commands use correct flags
-
-**Coverage Below Threshold**
-
-If coverage drops below 80%:
-- Review coverage reports uploaded as artifacts
-- Identify which functions lost coverage
-- Add tests to cover the missing code paths
-
-**Linting Failures**
-
-If shellcheck finds issues:
-- Review the warnings in the CI logs
-- Fix the issues locally: `npm run lint`
-- Commit the fixes
-
-**Timeout Issues**
-
-If tests timeout:
-- Integration tests may take longer than expected
-- Check for infinite loops or hanging processes
-- Review test fixture setup/teardown
-
-**Artifact Access**
-
-Download test logs and coverage reports:
-1. Go to the failed workflow run
-2. Scroll to "Artifacts" section
-3. Download relevant artifacts (test logs, coverage reports)
-4. Analyze locally to identify issues
-
-### Test Coverage
-
-Critical functions have >80% test coverage. View detailed coverage reports:
-```bash
-npm run test:coverage
-open coverage/index.html
-```
-
 ## 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
-   # Install via npm
    npm install -g opencode-ai
    ```
 
@@ -206,27 +135,40 @@ 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
 
-- `ralph-run --change <name>` - Run the ralph loop for a specific change
-- `ralph-run` - Auto-detect most recent change and run
+```
+ralph-run [OPTIONS]
+
+OPTIONS:
+    --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 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:
@@ -235,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
@@ -253,47 +197,61 @@ ralph-run --change my-feature
 
 **What happens:**
 
-1. **Validation**: Checks for required OpenSpec artifacts
-2. **PRD Generation**: Converts proposal + specs + design → PRD format (for internal use)
-3. **Task Execution**: For each incomplete task:
-   - Generates context-rich prompt (task + specs + design + git history + errors)
-   - Runs `opencode` with the prompt
-   - Creates git commit with task description
+1. **Validation**: Checks for required OpenSpec artifacts and git repository
+2. **PRD Generation**: Converts proposal + specs + design → PRD format for internal use
+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, errors cleared
+5. **Cleanup**: Automatically removes old output directories (older than 7 days)
+6. **Completion**: All tasks done
 
 ### Step 3: Monitor Progress
 
 ```bash
+# Check loop status
+ralph-run --status
+
 # Check remaining tasks
 grep "^- \[ \]" openspec/changes/my-feature/tasks.md
 
 # View git commits
 git log --oneline
 
-# See errors (if any failed)
-cat openspec/changes/my-feature/.ralph/errors.md
+# Inject context into next iteration
+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:
 # [INFO] Found 15 tasks to execute
 # [INFO] Executing task 1/15: Create User model with password field
-# ✓ Complete
 # [INFO] Executing task 2/15: Implement password hashing
-# ✓ Complete
 # ...
 
-# 3. Verify implementation
+# 5. Verify implementation
 git log --oneline  # 15 commits, one per task
 git diff HEAD~15   # See full implementation
 ```
@@ -305,21 +263,33 @@ git diff HEAD~15   # See full implementation
 | **Structured Planning** | OpenSpec workflow: proposal → specs → design → tasks |
 | **Agentic Execution** | opencode executes tasks with full context |
 | **Iterative Loop** | Each task builds on previous commits |
-| **Error Propagation** | Failures inform subsequent tasks |
+| **Iteration Feedback** | Recent failures and no-progress iterations inform the next pass |
 | **Granular History** | One git commit per task |
-| **Auto-Resume** | Interrupted? Run again—picks up where left off |
-| **Context Injection** | Inject custom instructions during execution |
-
-For detailed feature descriptions, see below.
+| **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
 
-### Ralph Wiggum + Agentic Coding
+*Features available in spec-and-loop 2.0.0 with OpenSpec 1.2.0*
+
+### Mini Ralph Loop Engine
 
-- **Iterative refinement**: Each task builds on previous commits with full context
-- **Error propagation**: Failures inform subsequent iterations—don't repeat mistakes
-- **Granular history**: Commit per task makes debugging and rollback easy
-- **Context awareness**: AI sees proposal, specs, design, git history, and errors
+`spec-and-loop` includes a first-party mini Ralph implementation (`lib/mini-ralph/`) that
+provides the core iterative loop without any external Ralph dependency:
+
+- **Iterative execution**: Each task builds on previous commits with full context
+- **State and history**: Loop state, iteration history, and struggle indicators stored in each change's `.ralph/`
+- **Prompt templates**: Context-aware prompts generated from OpenSpec artifacts
+- **Completion promises**: Loop exits when a completion signal is detected
+- **Task progression**: Synchronized with `tasks.md` checkboxes as the source of truth
+
+The supported subset intentionally excludes upstream features that are out of scope for
+this repository's OpenSpec-first workflow (multi-agent rotation, plugin toggles, etc.).
 
 ### OpenSpec + opencode Synergy
 
@@ -331,25 +301,49 @@ For detailed feature descriptions, see below.
 
 ### Script Features
 
-- **Auto-resume**: Interrupted? Run again—picks up where left off
-- **Context injection**: Inject custom instructions during execution
-- **Error recovery**: Errors propagate to guide subsequent tasks
-- **Bidirectional tracking**: Tasks.md and .ralph/tracking.json stay synced
+- **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 during execution:
+Inject custom instructions into the next iteration:
+
+```bash
+ralph-run --add-context "Use Redis instead of Memcached"
+
+# Check current pending context
+ralph-run --status
+
+# Clear pending context
+ralph-run --clear-context
+```
+
+### Loop Status Dashboard
 
 ```bash
-# Create injection file
-echo "Use Redis instead of Memcached" > openspec/changes/my-feature/.ralph/.context_injection
+ralph-run --status
+```
 
-# Next opencode invocation includes:
-## Injected Context
-Use Redis instead of Memcached
+Shows: active loop state, current task, prompt summary, pending context, iteration history,
+and struggle indicators if the loop appears stuck.
+
+### No-Commit Mode
+
+Run without automatic git commits (useful for reviewing changes before committing):
+
+```bash
+ralph-run --change my-feature --no-commit
 ```
 
 ### Verbose Mode
@@ -366,36 +360,52 @@ ralph-run --verbose --change my-feature
 cat openspec/changes/my-feature/.ralph/PRD.md
 ```
 
-### Manually Inject Context
+### 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
-echo "Consider performance implications" > openspec/changes/my-feature/.ralph/.context_injection
+# 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
-- **Ralph Loop**: Iterative development with commits per task, error tracking
+- **Mini Ralph** (`lib/mini-ralph/`): Internal iterative loop engine
 
 ### Context Propagation
 
 Each task execution includes:
-- **Task description**: What to implement
-- **Proposal summary**: Why this change matters
-- **Relevant specs**: Requirements to satisfy
-- **Design decisions**: Architectural constraints
-- **Git history**: Last 10 commits (what's already done)
-- **Previous errors**: What failed before (to avoid repeating)
+- **OpenSpec artifacts**: Proposal, design, and spec content from the generated PRD
+- **Fresh task snapshot**: Raw `tasks.md` content plus the current task and completed-task summary rendered each iteration
+- **Recent loop signals**: Compact reminders about prior failed or no-progress iterations
+- **Pending context**: Any `--add-context` injection
 
 ### Task Tracking
 
-Bidirectional synchronization:
-- **tasks.md**: Human-readable checkboxes `[ ]` → `[x]`
-- **.ralph/tracking.json**: Machine-readable state
-- **Atomic updates**: Both succeed or both fail
-- **Stable IDs**: Line numbers persist across script runs
+Synchronized tracking:
+- **tasks.md**: Human-readable checkboxes `[ ]` → `[x]` (source of truth)
+- **.ralph/ralph-tasks.md**: Symlink to `tasks.md` for the loop engine
+- **Atomic updates**: Checkboxes updated after each completed task
 
 ### File Structure
 
@@ -403,22 +413,48 @@ Bidirectional synchronization:
 openspec/changes/<name>/
 ├── proposal.md          # Your "why"
 ├── design.md            # Your "how"
-├── tasks.md             # Your "what" (checkboxes)
-└── specs/               # Your requirements
-    ├── auth/
-    │   └── spec.md
-    └── api/
-        └── spec.md
-└── .ralph/             # Internal state (auto-generated)
-    ├── PRD.md                    # Generated from artifacts
-    ├── tracking.json             # Task completion state
-    ├── errors.md                 # Failure history
-    ├── context-injections.md      # Manual injections log
-    └── .context_injection        # Pending injection
+├── tasks.md             # Your "what" (checkboxes, source of truth)
+├── specs/               # Your requirements
+│   ├── auth/
+│   │   └── spec.md
+│   └── api/
+│       └── spec.md
+└── .ralph/              # Internal loop state (auto-generated, per change)
+    ├── 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:**
@@ -440,7 +476,6 @@ export PATH="$PATH:$(npm root -g)/.bin"
 ## Resources
 
 - [OpenSpec](https://openspec.ai) - Structured specification workflow
-- [open-ralph-wiggum](https://github.com/Th0rgal/open-ralph-wiggum) - Iterative execution loop
 - [opencode](https://opencode.ai) - Agentic coding assistant
 
 ## License

package/lib/mini-ralph/context.js

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * context.js - Pending context management for mini-ralph.
+ *
+ * Manages reading, writing, adding, clearing, and consuming pending context
+ * from .ralph/ralph-context.md. Context is injected into the next iteration's
+ * prompt and then consumed (removed) so it does not carry forward indefinitely.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const CONTEXT_FILE = 'ralph-context.md';
+
+/**
+ * Return the absolute path to the context file.
+ *
+ * @param {string} ralphDir
+ * @returns {string}
+ */
+function contextPath(ralphDir) {
+  return path.join(ralphDir, CONTEXT_FILE);
+}
+
+/**
+ * Read the current pending context. Returns empty string if none.
+ *
+ * @param {string} ralphDir
+ * @returns {string}
+ */
+function read(ralphDir) {
+  const file = contextPath(ralphDir);
+  if (!fs.existsSync(file)) return '';
+  return fs.readFileSync(file, 'utf8').trim();
+}
+
+/**
+ * Append text to the pending context file.
+ *
+ * @param {string} ralphDir
+ * @param {string} text
+ */
+function add(ralphDir, text) {
+  if (!text || !text.trim()) return;
+  _ensureDir(ralphDir);
+  const file = contextPath(ralphDir);
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const separator = existing && !existing.endsWith('\n') ? '\n\n' : (existing ? '\n' : '');
+  fs.writeFileSync(file, `${existing}${separator}${text.trim()}`, 'utf8');
+}
+
+/**
+ * Clear all pending context.
+ *
+ * @param {string} ralphDir
+ */
+function clear(ralphDir) {
+  const file = contextPath(ralphDir);
+  if (fs.existsSync(file)) {
+    fs.unlinkSync(file);
+  }
+}
+
+/**
+ * Read pending context and then clear it (consume it for one iteration).
+ * Returns the context string, or null if there was nothing pending.
+ *
+ * @param {string} ralphDir
+ * @returns {string|null}
+ */
+function consume(ralphDir) {
+  const text = read(ralphDir);
+  if (!text) return null;
+  clear(ralphDir);
+  return text;
+}
+
+/**
+ * Check whether there is pending context.
+ *
+ * @param {string} ralphDir
+ * @returns {boolean}
+ */
+function hasPending(ralphDir) {
+  return !!read(ralphDir);
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function _ensureDir(ralphDir) {
+  if (!fs.existsSync(ralphDir)) {
+    fs.mkdirSync(ralphDir, { recursive: true });
+  }
+}
+
+module.exports = { read, add, clear, consume, hasPending, contextPath };