spec-and-loop 3.0.3 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-and-loop",
-  "version": "3.0.3",
+  "version": "3.3.0",
   "description": "OpenSpec + Ralph Loop integration for iterative development with opencode",
   "main": "index.js",
   "bin": {

package/scripts/mini-ralph-cli.js

@@ -22,6 +22,11 @@
  *   --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)
+ *   --blocked-handoff-promise <s>
+ *                              Blocked-handoff promise string (default: BLOCKED_HANDOFF).
+ *                              Loop exits cleanly with `blocked_handoff` when the
+ *                              agent emits this tag and writes the agent's note
+ *                              to <ralph-dir>/HANDOFF.md.
  *   --no-commit                Suppress auto-commit
  *   --model <name>             Optional model override
  *   --verbose                  Verbose output
@@ -53,6 +58,7 @@ function parseArgs(argv) {
     stallThreshold: 3,
     completionPromise: 'COMPLETE',
     taskPromise: 'READY_FOR_NEXT_TASK',
+    blockedHandoffPromise: 'BLOCKED_HANDOFF',
     noCommit: false,
     model: '',
     verbose: false,
@@ -101,6 +107,9 @@ function parseArgs(argv) {
       case '--task-promise':
         opts.taskPromise = args[++i];
         break;
+      case '--blocked-handoff-promise':
+        opts.blockedHandoffPromise = args[++i];
+        break;
       case '--no-commit':
         opts.noCommit = true;
         break;
@@ -154,6 +163,8 @@ Options:
   --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
+  --blocked-handoff-promise <s>
+                             Blocked-handoff promise string (default: BLOCKED_HANDOFF)
   --no-commit                Suppress auto-commit
   --model <name>             Model override
   --verbose                  Verbose output
@@ -212,6 +223,7 @@ async function main() {
     stallThreshold: opts.stallThreshold,
     completionPromise: opts.completionPromise,
     taskPromise: opts.taskPromise,
+    blockedHandoffPromise: opts.blockedHandoffPromise,
     noCommit: opts.noCommit,
     model: opts.model,
     verbose: opts.verbose,

package/scripts/ralph-run.sh

@@ -333,69 +333,58 @@ validate_dependencies() {
     log_verbose "All dependencies validated"
 }
 
+should_auto_fix_artifacts() {
+    case "${RALPH_RUN_AUTO_FIX_ARTIFACTS:-}" in
+        1|true|TRUE|yes|YES)
+            return 0
+            ;;
+        0|false|FALSE|no|NO)
+            return 1
+            ;;
+    esac
+
+    [[ -t 0 ]]
+}
+
 ensure_artifacts_present() {
     local change_dir="$1"
     local change_name="$2"
 
-    local required_files=(
-        "proposal.md"
-        "tasks.md"
-        "design.md"
-    )
-
-    local missing=()
-    for file in "${required_files[@]}"; do
-        if [[ ! -f "$change_dir/$file" ]]; then
-            missing+=("$file")
-        fi
-    done
+    local status_json
+    status_json=$(openspec status --change "$change_name" --json 2>/dev/null)
+    if [[ $? -ne 0 ]]; then
+        log_error "Failed to query openspec status for change: $change_name"
+        exit 1
+    fi
 
-    if [[ ${#missing[@]} -eq 0 ]]; then
+    local blocked
+    blocked=$(echo "$status_json" | jq -r '.artifacts[] | select(.status == "blocked") | .id' 2>/dev/null)
+    if [[ -z "$blocked" ]]; then
         return 0
     fi
 
-    log_info "Missing artifacts: ${missing[*]}"
+    log_info "Blocked artifacts detected: $blocked"
+    if ! should_auto_fix_artifacts; then
+        log_error "OpenSpec artifacts are blocked and this is a non-interactive run."
+        log_error 'Run `ralph-run init` or complete the artifacts manually, then rerun.'
+        log_error "Set RALPH_RUN_AUTO_FIX_ARTIFACTS=true to opt into opencode artifact repair in automation."
+        exit 1
+    fi
+
     log_info "Invoking opencode to complete missing artifacts..."
 
     opencode run "/opsx-ff $change_name" || true
 
-    for file in "${required_files[@]}"; do
-        if [[ ! -f "$change_dir/$file" ]]; then
-            log_error "Required artifact still not found after /opsx-ff: $file"
-            exit 1
-        fi
-    done
+    status_json=$(openspec status --change "$change_name" --json 2>/dev/null)
+    blocked=$(echo "$status_json" | jq -r '.artifacts[] | select(.status == "blocked") | .id' 2>/dev/null)
+    if [[ -n "$blocked" ]]; then
+        log_error "Artifacts still blocked after /opsx-ff: $blocked"
+        exit 1
+    fi
 
     log_info "All missing artifacts generated"
 }
 
-validate_openspec_artifacts() {
-    local change_dir="$1"
-    
-    log_verbose "Validating OpenSpec artifacts..."
-    
-    local required_files=(
-        "proposal.md"
-        "tasks.md"
-        "design.md"
-    )
-    
-    for file in "${required_files[@]}"; do
-        if [[ ! -f "$change_dir/$file" ]]; then
-            log_error "Required artifact not found: $file"
-            exit 1
-        fi
-        log_verbose "Found artifact: $file"
-    done
-    
-    if [[ ! -d "$change_dir/specs" ]]; then
-        log_error "Required directory not found: specs/"
-        exit 1
-    fi
-    log_verbose "Found directory: specs/"
-    
-    log_info "All OpenSpec artifacts validated"
-}
 
 setup_ralph_directory() {
     local change_dir="$1"
@@ -682,15 +671,21 @@ validate_script_state() {
     
     log_verbose "Validating script state..."
     
-    local required_dirs=(
-        ".ralph"
-    )
-    
-    for dir in "${required_dirs[@]}"; do
-        if [[ ! -d "$change_dir/$dir" ]]; then
-            log_verbose "Required directory not found: $dir (will be created)"
-        fi
-    done
+    if [[ ! -d "$change_dir/.ralph" ]]; then
+        log_verbose "Required directory not found: .ralph (will be created)"
+    fi
+
+    if [[ ! -d "$change_dir/specs" ]]; then
+        log_error "Required directory not found: specs"
+        return 1
+    fi
+
+    local first_spec=""
+    first_spec=$(find "$change_dir/specs" -name "spec.md" -type f -print -quit 2>/dev/null || true)
+    if [[ -z "$first_spec" ]]; then
+        log_error "No spec.md files found under specs"
+        return 1
+    fi
     
     local required_files=(
         "tasks.md"
@@ -810,111 +805,7 @@ sync_tasks_to_ralph() {
     log_verbose "Symlink configured: $ralph_tasks_file -> $abs_tasks_file"
 }
 
-create_prompt_template() {
-    local change_dir="$1"
-    local template_file="$2"
-    
-    log_verbose "Creating custom prompt template..."
-    
-    local abs_change_dir
-    abs_change_dir=$(get_realpath "$change_dir")
-    
-    cat > "$template_file" << 'EOF'
-# Ralph Wiggum Task Execution - Iteration {{iteration}} / {{max_iterations}}
-
-Change directory: {{change_dir}}
-
-## OpenSpec Artifacts
-
-{{_openspec_manifest}}
-
-## Fresh Task Context
-
-{{task_context}}
-
-## Instructions
-
-Before implementing, read the OpenSpec artifacts listed above that are relevant to the current task.
-
-Follow this loop contract EXACTLY. Do not skip steps. Do not batch. Do not output a promise until every step is done.
-
-1. Work on the task shown in `## Fresh Task Context` above. Before editing any marker, open `tasks.md` at `{{change_dir}}/tasks.md` and verify that same task is still `- [ ] ` or `- [/] ` on disk (it may have been closed by a prior iteration if you are resuming).
-2. Edit `tasks.md` in place to change that line's marker to `- [/] ` (in-progress). You MUST use your file edit tool to modify the file on disk — a shell `cp`, `sed`, or print-to-stdout does not count. Verify by re-reading the file.
-3. Implement the smallest change that fully satisfies the task's Done-when conditions. Run the task's verification command if one is specified.
-4. On success, edit `tasks.md` again in place to change that line's marker from `- [/] ` to `- [x] `. Verify by re-reading the file and confirming the `[x]` is present on that exact line.
-5. ONLY after step 4 writes `[x]` to disk, output `<promise>{{task_promise}}</promise>` on its own line.
-6. If and only if EVERY task line in `tasks.md` is `- [x] `, output `<promise>{{completion_promise}}</promise>` instead.
 
-Hard rules:
-- If you do not actually modify `tasks.md` on disk in this iteration, DO NOT output any promise tag. Output a short failure note instead and stop.
-- Never output `<promise>{{task_promise}}</promise>` while the task you just worked on is still `- [ ]` on disk. That causes the same task to repeat forever.
-- Promise tags must be on their own line, literal, unquoted, and not described in prose.
-- If an approach fails twice, try a different one.
-- If the task is already satisfied by prior work (e.g. target file already exists with the right content), you STILL must flip the checkbox to `[x]` in `tasks.md` before emitting the promise.
-
-## Commit Contract
-
-{{commit_contract}}
-EOF
-    
-    # Determine repo root for AGENTS.md probe
-    local repo_root
-    repo_root=$(git rev-parse --show-toplevel 2>/dev/null) || repo_root=""
-    
-    # Build the manifest body
-    local manifest_body
-    manifest_body="Read these as needed (source of truth for this change):"$'\n'$'\n'
-    manifest_body+="- $abs_change_dir/proposal.md"$'\n'
-    manifest_body+="- $abs_change_dir/design.md"$'\n'
-    
-    # Pre-expand specs/*/spec.md into concrete paths
-    if [[ -d "$abs_change_dir/specs" ]]; then
-        while IFS= read -r spec_path; do
-            [[ -n "$spec_path" ]] && manifest_body+="- $spec_path"$'\n'
-        done < <(find "$abs_change_dir/specs" -name spec.md -type f 2>/dev/null | sort)
-    fi
-    
-    # Optionally append AGENTS.md reference
-    local agents_line
-    agents_line=$(probe_agents_md "$repo_root")
-    if [[ -n "$agents_line" ]]; then
-        manifest_body+=$'\n'"$agents_line"
-    fi
-
-    # Append Ralph best practices guide if project is ralphified
-    if check_ralphified; then
-        local bp_manifest_path="$abs_change_dir/../../OPENSPEC-RALPH-BP.md"
-        if [[ ! -f "$bp_manifest_path" ]]; then
-            bp_manifest_path="$repo_root/openspec/OPENSPEC-RALPH-BP.md"
-        fi
-        if [[ -f "$bp_manifest_path" ]]; then
-            manifest_body+=$'\n'"- $bp_manifest_path    (Ralph best practices guide)"
-        fi
-    fi
-    
-    # Substitute {{_openspec_manifest}} using awk with a manifest temp file
-    # (awk -v cannot handle multi-line values; use getline from a file instead)
-    local _manifest_file
-    _manifest_file=$(mktemp 2>/dev/null || mktemp -t ralph-manifest)
-    printf '%s' "$manifest_body" > "$_manifest_file"
-    local _tmpfile
-    _tmpfile=$(mktemp 2>/dev/null || mktemp -t ralph-template)
-    awk -v mf="$_manifest_file" '
-        {
-            if ($0 == "{{_openspec_manifest}}") {
-                while ((getline line < mf) > 0) { print line }
-                close(mf)
-            } else { print }
-        }
-    ' "$template_file" > "$_tmpfile" && mv "$_tmpfile" "$template_file"
-    rm -f "$_manifest_file"
-    
-    # Substitute {{change_dir}}
-    _tmpfile=$(mktemp 2>/dev/null || mktemp -t ralph-template)
-    sed "s|{{change_dir}}|$abs_change_dir|g" "$template_file" > "$_tmpfile" && mv "$_tmpfile" "$template_file"
-    
-    log_verbose "Prompt template created: $template_file"
-}
 
 probe_agents_md() {
     local repo_root="$1"
@@ -1064,14 +955,11 @@ execute_ralph_loop() {
         return 1
     fi
     
-    local template_file="$ralph_dir/prompt-template.md"
-    
     # Clean up old output directories and setup new one
     cleanup_old_output
     local output_dir=$(setup_output_capture "$ralph_dir")
     
     sync_tasks_to_ralph "$change_dir" "$ralph_dir"
-    create_prompt_template "$change_dir" "$template_file"
     
     # Output files
     local stdout_log="$output_dir/ralph-stdout.log"
@@ -1080,13 +968,38 @@ execute_ralph_loop() {
     log_info "Invoking internal mini Ralph runtime..."
     log_info "Capturing output to: $output_dir"
     
+    local ralph_prompt_text="/opsx-apply $CHANGE_NAME
+
+You are operating inside an automated loop. Follow these constraints EXACTLY:
+
+1. Implement exactly ONE pending task from the task list /opsx-apply shows you.
+2. After marking the task checkbox [x] on disk, output <promise>READY_FOR_NEXT_TASK</promise> on its own line.
+3. If and only if EVERY task checkbox is [x], output <promise>COMPLETE</promise> instead.
+4. Do not ask questions or wait for input. If you cannot make progress on the current task because an external decision is required (revert protected drift outside the change scope, file an out-of-scope refactor, escalate to a human reviewer, etc.), STOP and emit a structured handoff in this exact form:
+
+   ## Blocker Note
+   <one paragraph describing what is blocked>
+
+   ## Why
+   <one paragraph: which task spec clause / invariant fired, and what evidence (file paths, hashes, test names) supports the diagnosis>
+
+   ## Suggested Next Step
+   <one or two bullets the human can execute to unblock>
+
+   <promise>BLOCKED_HANDOFF</promise>
+
+   The runner will save this note to .ralph/HANDOFF.md and exit cleanly with reason=blocked_handoff. Do NOT keep retrying the same task; emit the handoff and stop. Do NOT emit BLOCKED_HANDOFF for transient errors that a retry could fix (network blips, tool-not-found that is fixable by an absolute path, etc.) — those are normal failures the loop will retry on its own.
+5. If the task is already satisfied by prior work, still flip the checkbox to [x] before emitting the promise.
+
+Do not create git commits yourself. The Ralph runner manages automatic task commits when auto-commit is enabled."
+
     # Build the mini-ralph-cli arguments
     local mini_ralph_args=(
-        "--prompt-template" "$template_file"
         "--ralph-dir" "$ralph_dir"
         "--tasks-file" "$change_dir/tasks.md"
         "--tasks"
         "--max-iterations" "$max_iterations"
+        "--prompt-text" "$ralph_prompt_text"
     )
 
     if [[ "$no_commit" == true ]]; then
@@ -1101,12 +1014,53 @@ execute_ralph_loop() {
         mini_ralph_args+=("--quiet")
     fi
 
-    # Run the internal mini Ralph CLI and capture output
-    {
-        node "$MINI_RALPH_CLI" "${mini_ralph_args[@]}"
-    } > >(tee "$stdout_log") 2> >(tee "$stderr_log")
-    local node_exit_code=$?
-    wait
+    # Run the internal mini Ralph CLI and capture output.
+    #
+    # Avoid Bash process substitution here. macOS ships Bash 3.2, and under
+    # Bats' captured `run` wrapper a bare `wait` after `> >(tee ...)` can hang
+    # after the node child has already exited. Explicit FIFOs give us concrete
+    # tee PIDs to wait on and work consistently on macOS and Linux.
+    local stdout_pipe="$output_dir/ralph-stdout.pipe"
+    local stderr_pipe="$output_dir/ralph-stderr.pipe"
+    local node_exit_code=0
+    local tee_stdout_pid=""
+    local tee_stderr_pid=""
+    local had_errexit=false
+    case $- in
+        *e*)
+            had_errexit=true
+            set +e
+            ;;
+    esac
+
+    if mkfifo "$stdout_pipe" "$stderr_pipe" 2>/dev/null; then
+        tee "$stdout_log" < "$stdout_pipe" &
+        tee_stdout_pid=$!
+        tee "$stderr_log" < "$stderr_pipe" >&2 &
+        tee_stderr_pid=$!
+
+        node "$MINI_RALPH_CLI" "${mini_ralph_args[@]}" > "$stdout_pipe" 2> "$stderr_pipe"
+        node_exit_code=$?
+
+        wait "$tee_stdout_pid" 2>/dev/null || true
+        wait "$tee_stderr_pid" 2>/dev/null || true
+        rm -f "$stdout_pipe" "$stderr_pipe"
+    else
+        log_verbose "mkfifo unavailable; capturing output without live tee"
+        node "$MINI_RALPH_CLI" "${mini_ralph_args[@]}" > "$stdout_log" 2> "$stderr_log"
+        node_exit_code=$?
+        if [[ -s "$stdout_log" ]]; then
+            cat "$stdout_log"
+        fi
+        if [[ -s "$stderr_log" ]]; then
+            cat "$stderr_log" >&2
+        fi
+    fi
+
+    if [[ "$had_errexit" == true ]]; then
+        set -e
+    fi
+
     return $node_exit_code
 }
 
@@ -1285,6 +1239,7 @@ check_ralphified() {
 
 show_ralphify_warning() {
     local change_name="$1"
+    local preset_choice="${RALPH_RUN_RALPHIFY_CHOICE:-}"
 
     cat >&2 << 'WARNING_BOX'
 ┌─────────────────────────────────────────────────────────────────────┐
@@ -1299,16 +1254,29 @@ show_ralphify_warning() {
 └─────────────────────────────────────────────────────────────────────┘
 WARNING_BOX
 
+    if [[ -z "$preset_choice" && ! -t 0 ]]; then
+        log_info "Non-interactive environment detected. Continuing without Ralph Wiggum configuration."
+        log_info 'Run `ralph-run init` to configure Ralph Wiggum best practices before the next interactive run.'
+        return 0
+    fi
+
     while true; do
-        echo "" >&2
-        echo "Choose an option:" >&2
-        echo "  [A] Run ralphify init and redo the proposal, then continue" >&2
-        echo "  [C] Continue without init" >&2
-        echo "  [Q] Quit" >&2
-        printf "Enter choice: " >&2
-        if ! read -r choice; then
-            log_info "Non-interactive environment detected. Continuing without Ralph Wiggum configuration."
-            return 0
+        local choice=""
+        if [[ -n "$preset_choice" ]]; then
+            choice="$preset_choice"
+            preset_choice=""
+            log_info "Using RALPH_RUN_RALPHIFY_CHOICE=$choice"
+        else
+            echo "" >&2
+            echo "Choose an option:" >&2
+            echo "  [A] Run ralphify init and redo the proposal, then continue" >&2
+            echo "  [C] Continue without init" >&2
+            echo "  [Q] Quit" >&2
+            printf "Enter choice: " >&2
+            if ! read -r choice; then
+                log_info "Non-interactive environment detected. Continuing without Ralph Wiggum configuration."
+                return 0
+            fi
         fi
 
         case "$choice" in
@@ -1474,7 +1442,6 @@ main() {
 
     ensure_artifacts_present "$change_dir" "$CHANGE_NAME"
 
-    validate_openspec_artifacts "$change_dir"
     validate_script_state "$change_dir"
     local ralph_dir=$(setup_ralph_directory "$change_dir")