spec-and-loop 3.3.2 → 3.3.4

package/package.json

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

package/scripts/mini-ralph-cli.js

@@ -27,6 +27,17 @@
  *                              Loop exits cleanly with `blocked_handoff` when the
  *                              agent emits this tag and writes the agent's note
  *                              to <ralph-dir>/HANDOFF.md.
+ *   --auto-resolve-handoffs   Enable bounded continuation attempts for
+ *                              explicit, safe BLOCKED_HANDOFF classes
+ *   --no-auto-resolve-handoffs
+ *                              Disable auto-resolution even when enabled by env
+ *   --no-self-heal            Disable supervisor self-heal (env: RALPH_SELF_HEAL=0)
+ *   --self-heal-max-tries <n> Supervisor tries per blocker (env: RALPH_SELF_HEAL_MAX_TRIES)
+ *   --no-self-heal-downstream Disable downstream supervisor patches (env: RALPH_SELF_HEAL_DOWNSTREAM=0)
+ *   --no-self-heal-hints      Disable supervisor investigation hints (env: RALPH_SELF_HEAL_HINTS=0)
+ *   --no-self-heal-log-access Disable supervisor log-path injection (env: RALPH_SELF_HEAL_LOG_ACCESS=0)
+ *   --self-heal-verbose       Enable supervisor debug logging (env: RALPH_SELF_HEAL_VERBOSE=1)
+ *   --no-self-heal-verbose    Disable supervisor debug logging, even with --verbose
  *   --no-commit                Suppress auto-commit
  *   --model <name>             Optional model override
  *   --verbose                  Verbose output
@@ -44,6 +55,11 @@ const miniRalph = require('../lib/mini-ralph/index');
 // Argument parsing
 // ---------------------------------------------------------------------------
 
+function _envFlagDefaultEnabled(value) {
+  if (value === undefined) return true;
+  return !/^(0|false|no|off)$/i.test(String(value || '').trim());
+}
+
 function parseArgs(argv) {
   const args = argv.slice(2);
   const opts = {
@@ -59,6 +75,13 @@ function parseArgs(argv) {
     completionPromise: 'COMPLETE',
     taskPromise: 'READY_FOR_NEXT_TASK',
     blockedHandoffPromise: 'BLOCKED_HANDOFF',
+    autoResolveHandoffs: _envFlagDefaultEnabled(process.env.RALPH_AUTO_RESOLVE_HANDOFFS),
+    selfHeal: null,
+    selfHealMaxTries: null,
+    selfHealDownstream: null,
+    selfHealHints: null,
+    selfHealLogAccess: null,
+    selfHealVerbose: null,
     noCommit: false,
     model: '',
     verbose: false,
@@ -110,6 +133,33 @@ function parseArgs(argv) {
       case '--blocked-handoff-promise':
         opts.blockedHandoffPromise = args[++i];
         break;
+      case '--auto-resolve-handoffs':
+        opts.autoResolveHandoffs = true;
+        break;
+      case '--no-auto-resolve-handoffs':
+        opts.autoResolveHandoffs = false;
+        break;
+      case '--no-self-heal':
+        opts.selfHeal = false;
+        break;
+      case '--self-heal-max-tries':
+        opts.selfHealMaxTries = parseInt(args[++i], 10);
+        break;
+      case '--no-self-heal-downstream':
+        opts.selfHealDownstream = false;
+        break;
+      case '--no-self-heal-hints':
+        opts.selfHealHints = false;
+        break;
+      case '--no-self-heal-log-access':
+        opts.selfHealLogAccess = false;
+        break;
+      case '--self-heal-verbose':
+        opts.selfHealVerbose = true;
+        break;
+      case '--no-self-heal-verbose':
+        opts.selfHealVerbose = false;
+        break;
       case '--no-commit':
         opts.noCommit = true;
         break;
@@ -164,7 +214,16 @@ Options:
   --completion-promise <s>   Completion promise string
   --task-promise <s>         Task promise string
   --blocked-handoff-promise <s>
-                             Blocked-handoff promise string (default: BLOCKED_HANDOFF)
+                              Blocked-handoff promise string (default: BLOCKED_HANDOFF)
+  --auto-resolve-handoffs    Enable bounded continuation for explicit safe handoffs
+  --no-auto-resolve-handoffs Disable bounded continuation for explicit safe handoffs
+  --no-self-heal             Disable supervisor self-heal (env: RALPH_SELF_HEAL=0)
+  --self-heal-max-tries <n>  Supervisor tries per blocker (env: RALPH_SELF_HEAL_MAX_TRIES)
+  --no-self-heal-downstream  Disable downstream supervisor patches (env: RALPH_SELF_HEAL_DOWNSTREAM=0)
+  --no-self-heal-hints       Disable supervisor investigation hints (env: RALPH_SELF_HEAL_HINTS=0)
+  --no-self-heal-log-access  Disable supervisor log-path injection (env: RALPH_SELF_HEAL_LOG_ACCESS=0)
+  --self-heal-verbose        Enable supervisor debug logging (env: RALPH_SELF_HEAL_VERBOSE=1)
+  --no-self-heal-verbose     Disable supervisor debug logging, even with --verbose
   --no-commit                Suppress auto-commit
   --model <name>             Model override
   --verbose                  Verbose output
@@ -224,6 +283,13 @@ async function main() {
     completionPromise: opts.completionPromise,
     taskPromise: opts.taskPromise,
     blockedHandoffPromise: opts.blockedHandoffPromise,
+    autoResolveHandoffs: opts.autoResolveHandoffs,
+    selfHeal: opts.selfHeal,
+    selfHealMaxTries: opts.selfHealMaxTries,
+    selfHealDownstream: opts.selfHealDownstream,
+    selfHealHints: opts.selfHealHints,
+    selfHealLogAccess: opts.selfHealLogAccess,
+    selfHealVerbose: opts.selfHealVerbose,
     noCommit: opts.noCommit,
     model: opts.model,
     verbose: opts.verbose,
@@ -251,4 +317,11 @@ async function main() {
   }
 }
 
-main();
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  _envFlagDefaultEnabled,
+  _parseArgs: parseArgs,
+};

package/scripts/ralph-run.sh

@@ -129,6 +129,13 @@ resolve_ralph_command() {
 CHANGE_NAME=""
 MAX_ITERATIONS=""
 NO_COMMIT=false
+AUTO_RESOLVE_HANDOFFS=""
+SELF_HEAL=""
+SELF_HEAL_MAX_TRIES=""
+SELF_HEAL_DOWNSTREAM=""
+SELF_HEAL_HINTS=""
+SELF_HEAL_LOG_ACCESS=""
+SELF_HEAL_VERBOSE=""
 SHOW_STATUS=false
 SHOW_VERSION=false
 ADD_CONTEXT=""
@@ -137,6 +144,12 @@ SUBCOMMAND=""
 ERROR_OCCURRED=false
 CLEANUP_IN_PROGRESS=false
 
+# Tracks the per-run temp directory created by setup_output_capture so the
+# EXIT trap can remove it. Without this each invocation leaves a stale
+# `$TMPDIR/ralph-run-XXXXXX` directory behind and they accumulate quickly
+# (we observed ~1k stale dirs on a single workstation).
+RALPH_RUN_TEMP_DIR=""
+
 # Trap signals for proper cleanup
 cleanup() {
     # Prevent multiple cleanup calls
@@ -152,7 +165,16 @@ cleanup() {
     # 1. The mini Ralph runtime runs synchronously in the foreground
     # 2. Ctrl+C (SIGINT) naturally propagates to child processes
     # 3. The shell's process group handling ensures clean termination.
-    
+
+    # Remove the per-run temp directory created by setup_output_capture.
+    # Path-shape guard: only delete dirs whose name starts with `ralph-run-`
+    # so an accidental empty/aliased value cannot wipe an unrelated path.
+    if [[ -n "$RALPH_RUN_TEMP_DIR" \
+          && -d "$RALPH_RUN_TEMP_DIR" \
+          && "$(basename "$RALPH_RUN_TEMP_DIR")" == ralph-run-* ]]; then
+        rm -rf "$RALPH_RUN_TEMP_DIR" 2>/dev/null || true
+    fi
+
     if [[ $exit_code -ne 0 ]]; then
         log_error "Script terminated with exit code: $exit_code"
     fi
@@ -186,6 +208,19 @@ 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
+    --auto-resolve-handoffs  Enable bounded continuation for explicit safe handoffs
+    --no-auto-resolve-handoffs
+                             Disable bounded continuation for explicit safe handoffs
+    --no-self-heal           Disable supervisor self-heal (env: RALPH_SELF_HEAL=0)
+    --self-heal-max-tries <n>
+                             Supervisor tries per blocker (env: RALPH_SELF_HEAL_MAX_TRIES)
+    --no-self-heal-downstream
+                             Disable downstream supervisor patches (env: RALPH_SELF_HEAL_DOWNSTREAM=0)
+    --no-self-heal-hints     Disable supervisor investigation hints (env: RALPH_SELF_HEAL_HINTS=0)
+    --no-self-heal-log-access
+                             Disable supervisor log-path injection (env: RALPH_SELF_HEAL_LOG_ACCESS=0)
+    --self-heal-verbose      Enable supervisor debug logging (env: RALPH_SELF_HEAL_VERBOSE=1)
+    --no-self-heal-verbose   Disable supervisor debug logging, even with --verbose
     --verbose, -v            Enable verbose mode for debugging
     --quiet                  Suppress the per-iteration progress stream
     --version                Print the version and exit
@@ -232,6 +267,42 @@ parse_arguments() {
                 NO_COMMIT=true
                 shift
                 ;;
+            --auto-resolve-handoffs)
+                AUTO_RESOLVE_HANDOFFS=true
+                shift
+                ;;
+            --no-auto-resolve-handoffs)
+                AUTO_RESOLVE_HANDOFFS=false
+                shift
+                ;;
+            --no-self-heal)
+                SELF_HEAL=false
+                shift
+                ;;
+            --self-heal-max-tries)
+                SELF_HEAL_MAX_TRIES="$2"
+                shift 2
+                ;;
+            --no-self-heal-downstream)
+                SELF_HEAL_DOWNSTREAM=false
+                shift
+                ;;
+            --no-self-heal-hints)
+                SELF_HEAL_HINTS=false
+                shift
+                ;;
+            --no-self-heal-log-access)
+                SELF_HEAL_LOG_ACCESS=false
+                shift
+                ;;
+            --self-heal-verbose)
+                SELF_HEAL_VERBOSE=true
+                shift
+                ;;
+            --no-self-heal-verbose)
+                SELF_HEAL_VERBOSE=false
+                shift
+                ;;
             --verbose|-v)
                 VERBOSE=true
                 shift
@@ -916,7 +987,10 @@ setup_output_capture() {
     local output_dir
     output_dir=$(make_temp_dir "ralph-run")
     log_info "Output directory: $output_dir"
-    
+
+    # Track for cleanup() so the EXIT trap can remove it.
+    RALPH_RUN_TEMP_DIR="$output_dir"
+
     # Store output directory path in Ralph directory for reference
     echo "$output_dir" > "$ralph_dir/.output_dir"
     
@@ -1006,6 +1080,38 @@ Do not create git commits yourself. The Ralph runner manages automatic task comm
         mini_ralph_args+=("--no-commit")
     fi
 
+    if [[ "$AUTO_RESOLVE_HANDOFFS" == true ]]; then
+        mini_ralph_args+=("--auto-resolve-handoffs")
+    elif [[ "$AUTO_RESOLVE_HANDOFFS" == false ]]; then
+        mini_ralph_args+=("--no-auto-resolve-handoffs")
+    fi
+
+    if [[ "$SELF_HEAL" == false ]]; then
+        mini_ralph_args+=("--no-self-heal")
+    fi
+
+    if [[ -n "$SELF_HEAL_MAX_TRIES" ]]; then
+        mini_ralph_args+=("--self-heal-max-tries" "$SELF_HEAL_MAX_TRIES")
+    fi
+
+    if [[ "$SELF_HEAL_DOWNSTREAM" == false ]]; then
+        mini_ralph_args+=("--no-self-heal-downstream")
+    fi
+
+    if [[ "$SELF_HEAL_HINTS" == false ]]; then
+        mini_ralph_args+=("--no-self-heal-hints")
+    fi
+
+    if [[ "$SELF_HEAL_LOG_ACCESS" == false ]]; then
+        mini_ralph_args+=("--no-self-heal-log-access")
+    fi
+
+    if [[ "$SELF_HEAL_VERBOSE" == true ]]; then
+        mini_ralph_args+=("--self-heal-verbose")
+    elif [[ "$SELF_HEAL_VERBOSE" == false ]]; then
+        mini_ralph_args+=("--no-self-heal-verbose")
+    fi
+
     if [[ "$VERBOSE" == true ]]; then
         mini_ralph_args+=("--verbose")
     fi
@@ -1184,6 +1290,7 @@ rules:
     - Each task has one dominant outcome and one verification cluster
     - Use surgical, scope-targeted validation commands; reserve broad gates for pre-flight baselines or final integration tasks
     - Include explicit stop-and-hand-off conditions
+    - Run the OPENSPEC-RALPH-BP "Pre-loop scope-handoff pre-scan" against tasks.md before handing it to ralph-run; remediate every finding (dangling file paths, missing sections, scope/verifier mismatches, unclassified pre-existing failures, subjective stop conditions, unflagged manual-only tasks, cross-task scope conflicts)
   design:
     - Do not leave core policy choices unresolved
     - Specify algorithms, config shapes, and failure semantics
@@ -1206,6 +1313,18 @@ Before generating any OpenSpec artifacts, you MUST:
 - Ensure tasks use the task template with objective done-when conditions
 - Ensure each task uses the narrowest verifier that proves its scope; use broad gates only with baseline classification or final integration tasks
 - Include explicit stop-and-hand-off conditions in every task
+
+Before handing `tasks.md` to `ralph-run` (whether you just authored it or just edited it), you MUST run the **Pre-loop scope-handoff pre-scan** from `openspec/OPENSPEC-RALPH-BP.md` against every pending `- [ ]` task. For each pending task, statically verify:
+
+1. Every file path in `Scope:` / `Done when:` / `Stop and hand off if:` resolves on disk (`ls`, `git ls-files`).
+2. Every referenced section/heading exists in its named document with the exact heading text (`rg "^## <heading>$" <file>`).
+3. The verifier's actual reach matches the `Scope:` statement; broaden scope or narrow the verifier when they disagree.
+4. Multi-file gates that may hit pre-existing failures enumerate them in a "Pre-existing unrelated failures" sub-section with file:line references and a "do not stop on these" clause.
+5. `Stop and hand off if:` conditions are objective (grep-able evidence, exact class/selector names) — never subjective ("looks wrong", "cannot be explained").
+6. Any task requiring human-in-browser verification, deployed-URL checks, or visual judgment is tagged `[manual]` in its title with an explicit "manual verification required — emit BLOCKED_HANDOFF with verification template" stop condition.
+7. No two pending tasks claim ownership of the same file/route/symbol; no task's `Stop and hand off if:` would trigger on the normal completion of a later task.
+
+Remediate every finding by editing `tasks.md` directly, then re-run `openspec validate <change>` before starting the loop. If you cannot remediate a finding (it requires a product/policy decision), surface it to the user instead of starting the loop.
 RALPH_AGENTS
         log_verbose "Updated $agents_file with Ralph Wiggum compliance section"
     else

package/scripts/supervisor-prompt.md

@@ -0,0 +1,134 @@
+# Supervisor Prompt
+
+You are the supervisor agent for the embedded Ralph loop.
+
+Your job is to repair `tasks.md` structure, not to edit source code. You may propose a replacement body for the current pending task and optional downstream task patches when they share the same structural cause. You may also emit read-only investigation hints for the implementer.
+
+## Required Template Variables
+
+The runner renders this template with every variable below:
+
+- `{{blocker_note}}`
+- `{{current_task_number}}`
+- `{{current_task_body}}`
+- `{{downstream_tasks}}`
+- `{{handoff_history}}`
+- `{{recent_iterations}}`
+- `{{try_index}}`
+- `{{previous_supervisor_attempts}}`
+- `{{openspec_config_rules}}`
+- `{{ralph_authoring_rules}}`
+- `{{change_proposal}}`
+- `{{change_design}}`
+- `{{run_stdout_log_path}}`
+- `{{run_stderr_log_path}}`
+
+`{{tasks_md_path}}` and `{{blocker_hash}}` are intentionally not provided.
+
+## Structured Inputs
+
+### Blocker Note
+
+{{blocker_note}}
+
+### Current Task Number
+
+{{current_task_number}}
+
+### Current Task Body
+
+{{current_task_body}}
+
+### Downstream Tasks
+
+{{downstream_tasks}}
+
+### Handoff History
+
+{{handoff_history}}
+
+### Recent Iterations
+
+{{recent_iterations}}
+
+### Supervisor Try Index
+
+{{try_index}}
+
+### Previous Supervisor Attempts
+
+{{previous_supervisor_attempts}}
+
+### OpenSpec Config Rules
+
+{{openspec_config_rules}}
+
+### Ralph Authoring Rules
+
+{{ralph_authoring_rules}}
+
+### Change Proposal
+
+{{change_proposal}}
+
+### Change Design
+
+{{change_design}}
+
+### Optional Run Log Paths
+
+stdout: `{{run_stdout_log_path}}`
+
+stderr: `{{run_stderr_log_path}}`
+
+If those paths are non-empty, you may read at most the tail 8 KiB needed to disambiguate a blocker. Treat them as read-only.
+
+## Response Contract
+
+Emit exactly one JSON object inside a fenced `supervisor-response` block.
+
+- `current_task_patch`: object or `null`
+- `downstream_patches`: array
+- `investigation_hints`: array
+- `summary`: string
+- `downstream_rationale`: string
+
+When `current_task_patch` is an object, it must contain:
+
+- `task_number`: numbered task identifier such as `2.3`
+- `new_body`: full replacement markdown for the target task body
+- `rationale`: one paragraph explaining the repair
+
+Each `downstream_patches[]` entry may contain:
+
+- `task_number`: existing numbered task to modify
+- `operation`: `modify`, `insert_before`, or `insert_after`
+- `anchor_task_number`: required for insert operations
+- `new_body`: replacement or inserted task markdown
+- `rationale`: similarity rationale for the downstream patch
+
+Each `investigation_hints[]` entry must contain:
+
+- `path`: repository-relative file path to read
+- `rationale`: read-only explanation for why the implementer should inspect it
+
+## Example Response
+
+```supervisor-response
+{
+  "current_task_patch": {
+    "task_number": "2.3",
+    "new_body": "- [ ] 2.3 **Define and document the supervisor I/O contract (request fields + response JSON shape)**\n  - Scope: `scripts/supervisor-prompt.md`, `lib/mini-ralph/supervisor.js` (parser stub only)\n  - Change: Define the template variables and parser contract.\n  - Done when:\n    - `scripts/supervisor-prompt.md` documents the required variables\n    - `lib/mini-ralph/supervisor.js` exports the parser stub\n    - focused parser coverage passes\n  - Stop and hand off if:\n    - the response shape conflicts with the OpenCode surface",
+    "rationale": "Freeze the supervisor contract before later orchestration and prompt-rendering work."
+  },
+  "downstream_patches": [],
+  "investigation_hints": [
+    {
+      "path": "lib/mini-ralph/tasks.js",
+      "rationale": "Read task parsing helpers before changing task-number validation."
+    }
+  ],
+  "summary": "Define the supervisor prompt and parser contract so later supervisor tasks can build against a stable schema.",
+  "downstream_rationale": ""
+}
+```