spec-and-loop 1.0.8 → 1.2.0

package/scripts/ralph-run.sh

@@ -1,14 +1,7 @@
 #!/bin/bash
 
-set -e
-
 VERSION="1.0.0"
 
-# Add Bun to PATH if installed
-if [[ -d "$HOME/.bun/bin" ]]; then
-    export PATH="$HOME/.bun/bin:$PATH"
-fi
-
 # Detect OS for cross-platform compatibility
 detect_os() {
     case "$(uname -s)" in
@@ -63,8 +56,8 @@ get_realpath() {
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 LOCAL_NODE_BIN="$SCRIPT_DIR/../node_modules/.bin"
-BUNDLED_RALPH_JS="$SCRIPT_DIR/../node_modules/@th0rgal/ralph-wiggum/bin/ralph.js"
-RALPH_CMD=()
+# Allow tests to inject a mock by setting MINI_RALPH_CLI_OVERRIDE in the environment
+MINI_RALPH_CLI="${MINI_RALPH_CLI_OVERRIDE:-$SCRIPT_DIR/mini-ralph-cli.js}"
 
 if [[ -d "$LOCAL_NODE_BIN" ]]; then
     case ":$PATH:" in
@@ -105,22 +98,18 @@ make_temp_dir() {
 }
 
 resolve_ralph_command() {
-    if command -v ralph >/dev/null 2>&1; then
-        RALPH_CMD=("ralph")
+    if [[ -f "$MINI_RALPH_CLI" ]] && command -v node >/dev/null 2>&1; then
         return 0
     fi
-
-    if [[ -f "$BUNDLED_RALPH_JS" ]] && command -v node >/dev/null 2>&1; then
-        RALPH_CMD=("node" "$BUNDLED_RALPH_JS")
-        return 0
-    fi
-
-    RALPH_CMD=()
     return 1
 }
 
 CHANGE_NAME=""
 MAX_ITERATIONS=""
+NO_COMMIT=false
+SHOW_STATUS=false
+ADD_CONTEXT=""
+CLEAR_CONTEXT=false
 ERROR_OCCURRED=false
 CLEANUP_IN_PROGRESS=false
 
@@ -135,12 +124,10 @@ cleanup() {
     local exit_code=$1
     log_info "Cleaning up..."
     
-    # NOTE: We do NOT kill ralph/bun processes here because:
-    # 1. Ralph runs synchronously in the foreground
+    # NOTE: We do NOT kill node processes here because:
+    # 1. The mini Ralph runtime runs synchronously in the foreground
     # 2. Ctrl+C (SIGINT) naturally propagates to child processes
-    # 3. Using pkill -f "bun" is DANGEROUS - it matches gnome-session-binary!
-    # 4. Using pkill -f "ralph" could kill other user processes
-    # The shell's process group handling ensures clean termination.
+    # 3. The shell's process group handling ensures clean termination.
     
     if [[ $exit_code -ne 0 ]]; then
         log_error "Script terminated with exit code: $exit_code"
@@ -148,7 +135,9 @@ cleanup() {
     exit $exit_code
 }
 
-trap 'cleanup $?' EXIT INT TERM QUIT
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    trap 'cleanup $?' EXIT INT TERM QUIT
+fi
 
 handle_error() {
     local exit_code=$1
@@ -171,19 +160,28 @@ USAGE:
 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
+
 EXAMPLES:
     ralph-run                                    # Auto-detect most recent change
     ralph-run --change my-feature                # Execute specific change
-    ralph-run --max-iterations 100             # Limit loop to 100 iterations
+    ralph-run --change my-feature --max-iterations 100
+    ralph-run --change my-feature --no-commit    # Run without auto-committing
     ralph-run --verbose                          # Run with debug output
+    ralph-run --status                           # Check status of the active loop
+    ralph-run --add-context "Focus on error handling in module X"
+    ralph-run --clear-context                    # Remove pending context
 
 PREREQUISITES:
     - Git repository (git init)
-    - OpenSpec artifacts created (openspec init, opsx-new, opsx-ff)
-    - ralph CLI installed (npm install -g @th0rgal/ralph-wiggum)
+    - OpenSpec artifacts created (openspec init, openspec new, openspec ff)
     - opencode CLI installed (npm install -g opencode-ai)
 
 EOF
@@ -200,10 +198,26 @@ parse_arguments() {
                 MAX_ITERATIONS="$2"
                 shift 2
                 ;;
+            --no-commit)
+                NO_COMMIT=true
+                shift
+                ;;
             --verbose|-v)
                 VERBOSE=true
                 shift
                 ;;
+            --status)
+                SHOW_STATUS=true
+                shift
+                ;;
+            --add-context)
+                ADD_CONTEXT="$2"
+                shift 2
+                ;;
+            --clear-context)
+                CLEAR_CONTEXT=true
+                shift
+                ;;
             --help|-h)
                 SHOW_HELP=true
                 shift
@@ -252,12 +266,11 @@ validate_dependencies() {
     log_verbose "Validating dependencies..."
     
     if ! resolve_ralph_command; then
-        log_error "ralph CLI not found."
-        log_error "Please install open-ralph-wiggum: npm install -g @th0rgal/ralph-wiggum"
-        log_error "If spec-and-loop is globally installed, reinstalling it should also restore the bundled Ralph dependency."
+        log_error "Internal mini Ralph runtime not found: $MINI_RALPH_CLI"
+        log_error "Ensure node is installed and spec-and-loop dependencies are up to date (npm install)."
         exit 1
     fi
-    log_verbose "Found Ralph command: ${RALPH_CMD[*]}"
+    log_verbose "Found internal mini Ralph runtime: $MINI_RALPH_CLI"
     
     # Check for opencode
     if ! command -v opencode &> /dev/null; then
@@ -454,7 +467,7 @@ parse_tasks() {
         ((line_number++)) || true
         
         if [[ "$line" == "- [ ]"* ]]; then
-            local task_desc="${line#- [ ] }"
+            local task_desc="${line#- \[ \] }"
             TASKS+=("$task_desc")
             TASK_IDS+=("$line_number")
             log_verbose "Found incomplete task (line $line_number): $task_desc"
@@ -483,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"
@@ -692,7 +709,7 @@ sync_tasks_to_ralph() {
         rm "$old_ralph_tasks_file"
     fi
     
-    # Use symlink so Ralph and openspec-apply-change work on the SAME file
+    # Use a symlink so the loop runtime always works against the OpenSpec tasks file
     # Ensure parent directory for ralph_tasks_file exists
     mkdir -p "$(dirname "$ralph_tasks_file")"
 
@@ -744,6 +761,10 @@ Include full context from openspec artifacts in {{change_dir}}:
 
 {{tasks}}
 
+## Fresh Task Context
+
+{{task_context}}
+
 ## Instructions
 
 1. **Identify** current task:
@@ -751,15 +772,15 @@ Include full context from openspec artifacts in {{change_dir}}:
    - If no task is in progress, pick the first task marked as [ ] (incomplete)
    - Mark the task as [/] in the tasks file before starting work
 
-2. **Implement** task using openspec-apply-change:
-   - Use the /opsx-apply skill to implement the current task
-   - Read the relevant openspec artifacts for context (proposal.md, design.md, specs)
-   - Follow the openspec workflow to complete the task
-   - The openspec-apply-change skill will implement changes and update task status automatically
+2. **Implement** the current task directly:
+   - Read the relevant OpenSpec artifacts for context (proposal.md, design.md, specs)
+   - Make the smallest maintainable change that fully satisfies the current task
+   - Run the most relevant validation or tests for the task before claiming completion
 
 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>`
 
 4. **Continue** to the next task:
@@ -769,7 +790,9 @@ Include full context from openspec artifacts in {{change_dir}}:
 ## Critical Rules
 
 - Work on ONE task at a time from the task list
-- Use openspec-apply-change (/opsx-apply) for implementation
+- Read the full tasks file every iteration; do not rely on memory from prior iterations
+- Do not rely on editor-specific slash commands or local-only skills; follow this prompt directly
+- Treat tasks.md as the only source of truth for task state
 - ONLY output `<promise>{{task_promise}}</promise>` when the current task is complete and marked as [x]
 - ONLY output `<promise>{{completion_promise}}</promise>` when ALL tasks are [x]
 - Output promise tags DIRECTLY - do not quote them, explain them, or say you "will" output them
@@ -881,12 +904,12 @@ get_current_task_context() {
     while IFS= read -r line; do
         if [[ "$line" =~ ^-\ \[/\] ]]; then
             # Found in-progress task - extract description
-            current_task_desc="${line#- [/] }"
+            current_task_desc="${line#- \[/\] }"
             found_task=true
             break
         elif [[ "$line" =~ ^-\ \[\ \] ]] && [[ "$found_task" == "false" ]]; then
             # Found incomplete task - extract description
-            current_task_desc="${line#- [ ] }"
+            current_task_desc="${line#- \[ \] }"
             found_task=true
             break
         fi
@@ -948,14 +971,18 @@ execute_ralph_loop() {
     local change_dir="$1"
     local ralph_dir="$2"
     local max_iterations="${3:-50}"
+    local no_commit="${4:-false}"
     
-    log_info "Starting Ralph Wiggum loop with open-ralph-wiggum..."
+    log_info "Starting internal mini Ralph loop..."
     log_info "Max iterations: $max_iterations"
     log_info "Change directory: $change_dir"
+    if [[ "$no_commit" == true ]]; then
+        log_info "Auto-commit disabled (--no-commit)"
+    fi
     
     if ! resolve_ralph_command; then
-        log_error "ralph CLI not found."
-        log_error "Please install open-ralph-wiggum: npm install -g @th0rgal/ralph-wiggum"
+        log_error "Internal mini Ralph runtime not found: $MINI_RALPH_CLI"
+        log_error "Ensure node is installed and spec-and-loop dependencies are up to date (npm install)."
         return 1
     fi
     
@@ -973,51 +1000,132 @@ execute_ralph_loop() {
     prd_content=$(generate_prd "$change_dir")
     echo "$prd_content" > "$ralph_dir/PRD.md"
     
-    # Get current task context for Ralph to use in commits
-    local task_context
-    task_context=$(get_current_task_context "$change_dir")
-    
-    # Create context injection file for Ralph
-    local context_file="$ralph_dir/.context_injection"
-    if [[ -n "$task_context" ]]; then
-        log_verbose "Writing task context injection..."
-        echo "$task_context" > "$context_file"
-    fi
-    
-    # Restore Ralph state from tasks.md before running
-    restore_ralph_state_from_tasks "$change_dir/tasks.md"
-    
-    # Initialize context injections file for Ralph to read context
-    initialize_context_injections "$ralph_dir"
-    
     # Output files
     local stdout_log="$output_dir/ralph-stdout.log"
     local stderr_log="$output_dir/ralph-stderr.log"
     
-    log_info "Delegating to ralph CLI..."
+    log_info "Invoking internal mini Ralph runtime..."
     log_info "Capturing output to: $output_dir"
     
-    # Run Ralph and capture output to both console and files
+    # Build the mini-ralph-cli arguments
+    local mini_ralph_args=(
+        "--prompt-file" "$ralph_dir/PRD.md"
+        "--prompt-template" "$template_file"
+        "--ralph-dir" "$ralph_dir"
+        "--tasks-file" "$change_dir/tasks.md"
+        "--tasks"
+        "--max-iterations" "$max_iterations"
+    )
+
+    if [[ "$no_commit" == true ]]; then
+        mini_ralph_args+=("--no-commit")
+    fi
+
+    if [[ "$VERBOSE" == true ]]; then
+        mini_ralph_args+=("--verbose")
+    fi
+
+    # Run the internal mini Ralph CLI and capture output
     {
-        "${RALPH_CMD[@]}" --prompt-file "$ralph_dir/PRD.md" \
-            --agent opencode \
-            --tasks \
-            --max-iterations "$max_iterations" \
-            --prompt-template "$template_file" \
-            --verbose-tools
+        node "$MINI_RALPH_CLI" "${mini_ralph_args[@]}"
     } > >(tee "$stdout_log") 2> >(tee "$stderr_log")
     
     return $?
 }
 
 
+# ---------------------------------------------------------------------------
+# Observability and control commands
+#
+# These commands delegate to the internal mini-ralph-cli.js for status,
+# context management, and other loop controls without running the full loop.
+# ---------------------------------------------------------------------------
+
+run_observability_command() {
+    local change_name="$1"
+    local command="$2"
+    local arg="$3"
+
+    if [[ ! -f "$MINI_RALPH_CLI" ]]; then
+        log_error "Internal mini-ralph-cli.js not found: $MINI_RALPH_CLI"
+        exit 1
+    fi
+
+    if [[ ! -x "$(command -v node)" ]]; then
+        log_error "node is required but not found in PATH."
+        exit 1
+    fi
+
+    local change_dir="openspec/changes/$change_name"
+    local ralph_dir="$change_dir/.ralph"
+
+    case "$command" in
+        status)
+            local tasks_file="$change_dir/tasks.md"
+            local tasks_arg=""
+            if [[ -f "$tasks_file" ]]; then
+                tasks_arg="--tasks-file $tasks_file"
+            fi
+            # shellcheck disable=SC2086
+            node "$MINI_RALPH_CLI" --ralph-dir "$ralph_dir" --status $tasks_arg
+            ;;
+        add-context)
+            node "$MINI_RALPH_CLI" --ralph-dir "$ralph_dir" --add-context "$arg"
+            ;;
+        clear-context)
+            node "$MINI_RALPH_CLI" --ralph-dir "$ralph_dir" --clear-context
+            ;;
+        *)
+            log_error "Unknown observability command: $command"
+            exit 1
+            ;;
+    esac
+}
 
 main() {
+    set -e
     parse_arguments "$@"
     
     log_verbose "Starting ralph-run v$VERSION"
     log_verbose "Change name: ${CHANGE_NAME:-<auto-detect>}"
-    
+
+    # Resolve change name first for observability commands that need it
+    if [[ -z "$CHANGE_NAME" ]] && ( [[ "$SHOW_STATUS" == true ]] || [[ -n "$ADD_CONTEXT" ]] || [[ "$CLEAR_CONTEXT" == true ]] ); then
+        validate_git_repository
+        CHANGE_NAME=$(auto_detect_change)
+        log_verbose "Auto-detected change for observability: $CHANGE_NAME"
+    fi
+
+    # Handle observability commands (status, add-context, clear-context)
+    # These exit early without running the full loop.
+    if [[ "$SHOW_STATUS" == true ]]; then
+        if [[ -z "$CHANGE_NAME" ]]; then
+            validate_git_repository
+            CHANGE_NAME=$(auto_detect_change)
+        fi
+        run_observability_command "$CHANGE_NAME" "status"
+        exit $?
+    fi
+
+    if [[ -n "$ADD_CONTEXT" ]]; then
+        if [[ -z "$CHANGE_NAME" ]]; then
+            validate_git_repository
+            CHANGE_NAME=$(auto_detect_change)
+        fi
+        run_observability_command "$CHANGE_NAME" "add-context" "$ADD_CONTEXT"
+        exit $?
+    fi
+
+    if [[ "$CLEAR_CONTEXT" == true ]]; then
+        if [[ -z "$CHANGE_NAME" ]]; then
+            validate_git_repository
+            CHANGE_NAME=$(auto_detect_change)
+        fi
+        run_observability_command "$CHANGE_NAME" "clear-context"
+        exit $?
+    fi
+
+    # Normal loop execution path
     validate_git_repository
     validate_dependencies
     
@@ -1045,9 +1153,11 @@ main() {
     
     local max_iterations="${MAX_ITERATIONS:-50}"
     
-    execute_ralph_loop "$change_dir" "$ralph_dir" "$max_iterations"
+    execute_ralph_loop "$change_dir" "$ralph_dir" "$max_iterations" "$NO_COMMIT"
     
     log_info "ralph-run.sh initialized successfully"
 }
 
-main "$@"
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi

package/scripts/setup.js

@@ -4,40 +4,48 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
-console.log('Setting up spec-and-loop...');
+function runSetup() {
+  console.log('Setting up spec-and-loop...');
 
-// Get the installation directory
-const installDir = __dirname;
-const ralphRunScript = path.join(installDir, 'ralph-run.sh');
+  // Get the installation directory
+  const installDir = __dirname;
+  const ralphRunScript = path.join(installDir, 'ralph-run.sh');
 
-console.log(`Installation directory: ${installDir}`);
+  console.log(`Installation directory: ${installDir}`);
 
-// Make ralph-run.sh executable
-if (fs.existsSync(ralphRunScript)) {
-  try {
-    execSync(`chmod +x "${ralphRunScript}"`);
-    console.log('✓ Made ralph-run.sh executable');
-  } catch (err) {
-    console.warn(`Could not make ralph-run.sh executable: ${err.message}`);
+  // Make ralph-run.sh executable
+  if (fs.existsSync(ralphRunScript)) {
+    try {
+      execSync(`chmod +x "${ralphRunScript}"`, { stdio: 'inherit' });
+      console.log('✓ Made ralph-run.sh executable');
+    } catch (err) {
+      console.warn(`Could not make ralph-run.sh executable: ${err.message}`);
+    }
+  } else {
+    console.error(`Error: ralph-run.sh not found at ${ralphRunScript}`);
+    process.exit(1);
   }
-} else {
-  console.error(`Error: ralph-run.sh not found at ${ralphRunScript}`);
-  process.exit(1);
+
+  console.log('');
+  console.log('spec-and-loop setup complete!');
+  console.log('');
+  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('  ralph-run --change <name>       # Run ralph loop');
+  console.log('  ralph-run                       # Auto-detect change');
+  console.log('');
+  console.log('Prerequisites:');
+  console.log('  - openspec CLI: npm install -g 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');
+}
+
+if (require.main === module) {
+  runSetup();
 }
 
-console.log('');
-console.log('spec-and-loop setup complete!');
-console.log('');
-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('  ralph-run --change <name>       # Run ralph loop');
-console.log('  ralph-run                       # Auto-detect change');
-console.log('');
-console.log('Prerequisites:');
-console.log('  - openspec CLI: npm install -g 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');
+module.exports = { runSetup };