spec-and-loop 2.1.2 → 3.0.1

package/scripts/ralph-run.sh

@@ -1,6 +1,27 @@
 #!/bin/bash
 
-VERSION="1.0.0"
+resolve_version() {
+    local pkg_json="$SCRIPT_DIR/../package.json"
+    if [[ ! -f "$pkg_json" ]]; then
+        echo "Error: package.json not found at $pkg_json" >&2
+        exit 1
+    fi
+    if [[ ! -r "$pkg_json" ]]; then
+        echo "Error: package.json not readable at $pkg_json" >&2
+        exit 1
+    fi
+    local version
+    version=$(node -e "console.log(require('$pkg_json').version)" 2>/dev/null) || {
+        echo "Error: Failed to read version from $pkg_json" >&2
+        exit 1
+    }
+    if [[ -z "$version" ]]; then
+        echo "Error: Empty version read from $pkg_json" >&2
+        exit 1
+    fi
+    echo "$version"
+}
+VERSION=""
 
 # Detect OS for cross-platform compatibility
 detect_os() {
@@ -55,6 +76,7 @@ get_realpath() {
 }
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VERSION=$(resolve_version)
 LOCAL_NODE_BIN="$SCRIPT_DIR/../node_modules/.bin"
 # 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}"
@@ -108,8 +130,10 @@ CHANGE_NAME=""
 MAX_ITERATIONS=""
 NO_COMMIT=false
 SHOW_STATUS=false
+SHOW_VERSION=false
 ADD_CONTEXT=""
 CLEAR_CONTEXT=false
+SUBCOMMAND=""
 ERROR_OCCURRED=false
 CLEANUP_IN_PROGRESS=false
 
@@ -148,6 +172,7 @@ handle_error() {
     fi
 }
 VERBOSE=false
+QUIET=false
 SHOW_HELP=false
 
 usage() {
@@ -162,8 +187,13 @@ OPTIONS:
     --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
+    --quiet                  Suppress the per-iteration progress stream
+    --version                Print the version and exit
     --help, -h               Show this help message
 
+SUBCOMMANDS:
+    init                     Configure the project for Ralph-friendly artifact generation
+
 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
@@ -206,6 +236,10 @@ parse_arguments() {
                 VERBOSE=true
                 shift
                 ;;
+            --quiet)
+                QUIET=true
+                shift
+                ;;
             --status)
                 SHOW_STATUS=true
                 shift
@@ -222,6 +256,14 @@ parse_arguments() {
                 SHOW_HELP=true
                 shift
                 ;;
+            --version)
+                SHOW_VERSION=true
+                shift
+                ;;
+            init)
+                SUBCOMMAND="init"
+                shift
+                ;;
             *)
                 echo "Error: Unknown option: $1"
                 usage
@@ -421,13 +463,7 @@ generate_prd() {
     prd_content+="$OPENSPEC_DESIGN"$'\n'$'\n'
     
     # Add current task context for Ralph to use in commits
-    local task_context
-    task_context=$(get_current_task_context "$change_dir")
-    
-    if [[ -n "$task_context" ]]; then
-        prd_content+="## Current Task Context"$'\n'$'\n'
-        prd_content+="$task_context"$'\n'$'\n'
-    fi
+    # (Removed: task context is now provided via {{task_context}} template variable only)
     
     echo "$prd_content"
 }
@@ -462,17 +498,19 @@ parse_tasks() {
     TASKS=()
     TASK_IDS=()
     
-    local line_number=0
-    while IFS= read -r line; do
-        ((line_number++)) || true
-        
-        if [[ "$line" == "- [ ]"* ]]; then
-            local task_desc="${line#- \[ \] }"
-            TASKS+=("$task_desc")
-            TASK_IDS+=("$line_number")
-            log_verbose "Found incomplete task (line $line_number): $task_desc"
-        fi
-    done < "$tasks_file"
+    if [[ -f "$tasks_file" ]]; then
+        local line_number=0
+        while IFS= read -r line; do
+            ((line_number++)) || true
+            
+            if [[ "$line" == "- [ ]"* ]]; then
+                local task_desc="${line#- \[ \] }"
+                TASKS+=("$task_desc")
+                TASK_IDS+=("$line_number")
+                log_verbose "Found incomplete task (line $line_number): $task_desc"
+            fi
+        done < "$tasks_file"
+    fi
     
     log_verbose "Found ${#TASKS[@]} incomplete tasks"
 }
@@ -750,20 +788,9 @@ create_prompt_template() {
 
 Change directory: {{change_dir}}
 
-## OpenSpec Artifacts Context
-
-Include full context from openspec artifacts in {{change_dir}}:
-- Read {{change_dir}}/proposal.md for the overall project goal
-- Read {{change_dir}}/design.md for the technical design approach
-- Read {{change_dir}}/specs/*/spec.md for the detailed specifications
-
-## Invocation-Time PRD Snapshot
+## OpenSpec Artifacts
 
-{{base_prompt}}
-
-## Task List
-
-{{tasks}}
+{{_openspec_manifest}}
 
 ## Fresh Task Context
 
@@ -771,53 +798,97 @@ Include full context from openspec artifacts in {{change_dir}}:
 
 ## Instructions
 
-1. **Identify** current task:
-   - Find any task marked as [/] (in progress)
-   - 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** 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
-    - Output: `<promise>{{task_promise}}</promise>`
-
-4. **Continue** to the next task:
-   - The loop will continue with the next iteration
-   - Find the next incomplete task and repeat the process
-
-## Critical Rules
-
-- Work on ONE task at a time from the task list
-- 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
-- Do NOT lie or output false promises to exit the loop
-- If stuck, try a different approach
-- Check your work before claiming completion
+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}}
-
-{{context}}
 EOF
     
-    # Use a portable inplace replace: write to temp file then move into place
+    # 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"
+    if [[ -n "$repo_root" && -r "$repo_root/AGENTS.md" ]]; then
+        echo "- AGENTS.md    (project-level build/test guide)"
+    else
+        echo ""
+    fi
+}
+
 restore_ralph_state_from_tasks() {
     local tasks_file="$1"
     local ralph_loop_file=".ralph/ralph-loop.state.json"
@@ -966,11 +1037,6 @@ execute_ralph_loop() {
     sync_tasks_to_ralph "$change_dir" "$ralph_dir"
     create_prompt_template "$change_dir" "$template_file"
     
-    # Generate PRD and write to file
-    local prd_content
-    prd_content=$(generate_prd "$change_dir")
-    echo "$prd_content" > "$ralph_dir/PRD.md"
-    
     # Output files
     local stdout_log="$output_dir/ralph-stdout.log"
     local stderr_log="$output_dir/ralph-stderr.log"
@@ -980,7 +1046,6 @@ execute_ralph_loop() {
     
     # 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"
@@ -996,12 +1061,17 @@ execute_ralph_loop() {
         mini_ralph_args+=("--verbose")
     fi
 
+    if [[ "$QUIET" == true ]]; then
+        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")
-    
-    return $?
+    local node_exit_code=$?
+    wait
+    return $node_exit_code
 }
 
 
@@ -1053,10 +1123,259 @@ run_observability_command() {
     esac
 }
 
+resolve_bp_path() {
+    local repo_root="${1:-.}"
+    local bp_candidates=(
+        "$repo_root/node_modules/spec-and-loop/OPENSPEC-RALPH-BP.md"
+        "$SCRIPT_DIR/../OPENSPEC-RALPH-BP.md"
+    )
+
+    for candidate in "${bp_candidates[@]}"; do
+        local resolved
+        resolved=$(get_realpath "$candidate")
+        if [[ -n "$resolved" && -f "$resolved" ]]; then
+            printf "%s" "$resolved"
+            return 0
+        fi
+    done
+
+    return 1
+}
+
+ralphify_init() {
+    local config_file="openspec/config.yaml"
+    local agents_file="AGENTS.md"
+    local bp_local_path="openspec/OPENSPEC-RALPH-BP.md"
+
+    if ! git rev-parse --git-dir > /dev/null 2>&1; then
+        log_error "Not a git repository. Please run: git init"
+        return 1
+    fi
+
+    if [[ ! -d "openspec" ]]; then
+        log_error "openspec/ directory not found. Please run: openspec init"
+        return 1
+    fi
+
+    local repo_root
+    repo_root=$(git rev-parse --show-toplevel 2>/dev/null) || repo_root="$(pwd)"
+
+    local bp_source
+    bp_source=$(resolve_bp_path "$repo_root")
+    if [[ -z "$bp_source" ]]; then
+        log_error "OPENSPEC-RALPH-BP.md not found in node_modules or package directory"
+        log_error "Package installation may be incomplete. Run: npm install"
+        return 1
+    fi
+
+    if ! cmp -s "$bp_source" "$bp_local_path" 2>/dev/null; then
+        cp "$bp_source" "$bp_local_path"
+        log_info "Copied OPENSPEC-RALPH-BP.md to openspec/"
+    else
+        log_verbose "OPENSPEC-RALPH-BP.md already up to date in openspec/"
+    fi
+
+    if ! grep -q "Ralph Wiggum" "$config_file" 2>/dev/null; then
+        cat >> "$config_file" << 'RALPH_CONFIG'
+
+# --- Ralph Wiggum ---
+# This project uses the Ralph Wiggum method for iterative development.
+# See OPENSPEC-RALPH-BP.md for the detailed authoring guide shipped with spec-and-loop.
+context: |
+  This project follows the Ralph Wiggum method for task authoring.
+  Read openspec/OPENSPEC-RALPH-BP.md before generating OpenSpec artifacts.
+  Verify proposals against the Ralph checklist before approval.
+rules:
+  proposal:
+    - Include explicit scope, non-goals, and first-rollout boundaries
+    - Resolve all policy decisions before implementation tasks
+  tasks:
+    - Use the task template from OPENSPEC-RALPH-BP.md
+    - Each task has one dominant outcome and one verification cluster
+    - Include explicit stop-and-hand-off conditions
+  design:
+    - Do not leave core policy choices unresolved
+    - Specify algorithms, config shapes, and failure semantics
+RALPH_CONFIG
+        log_verbose "Updated $config_file with Ralph Wiggum rules"
+    else
+        log_verbose "Ralph Wiggum rules already present in $config_file"
+    fi
+
+    if ! grep -q "Ralph Wiggum Compliance" "$agents_file" 2>/dev/null; then
+        cat >> "$agents_file" << 'RALPH_AGENTS'
+
+## Ralph Wiggum Compliance
+
+This project follows the Ralph Wiggum method for iterative OpenSpec development.
+
+Before generating any OpenSpec artifacts, you MUST:
+- Read `openspec/OPENSPEC-RALPH-BP.md` (Ralph Wiggum authoring guide)
+- Verify proposals against the Ralph authoring checklist
+- Ensure tasks use the task template with objective done-when conditions
+- Include explicit stop-and-hand-off conditions in every task
+RALPH_AGENTS
+        log_verbose "Updated $agents_file with Ralph Wiggum compliance section"
+    else
+        log_verbose "Ralph Wiggum compliance section already present in $agents_file"
+    fi
+
+    log_info "Project ralphified successfully. Proposals will now follow Ralph Wiggum best practices."
+    return 0
+}
+
+check_ralphified() {
+    local config_file="openspec/config.yaml"
+    local agents_file="AGENTS.md"
+
+    if [[ ! -f "$config_file" ]]; then
+        return 1
+    fi
+
+    if [[ ! -f "$agents_file" ]]; then
+        return 1
+    fi
+
+    if ! grep -q "Ralph Wiggum" "$config_file" 2>/dev/null; then
+        return 1
+    fi
+
+    if ! grep -q "Ralph Wiggum Compliance" "$agents_file" 2>/dev/null; then
+        return 1
+    fi
+
+    return 0
+}
+
+show_ralphify_warning() {
+    local change_name="$1"
+
+    cat >&2 << 'WARNING_BOX'
+┌─────────────────────────────────────────────────────────────────────┐
+│                                                                     │
+│   WARNING: Project not configured for Ralph Wiggum best practices   │
+│                                                                     │
+│   This project has not been ralphified. Proposals and artifacts     │
+│   may not follow Ralph Wiggum conventions.                          │
+│                                                                     │
+│   It is recommended to run: ralph-run init                          │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+WARNING_BOX
+
+    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
+        fi
+
+        case "$choice" in
+            [Aa])
+                log_info "Running ralphify init..."
+                if ! ralphify_init; then
+                    log_error "ralphify init failed. Aborting."
+                    exit 1
+                fi
+
+                local change_dir="openspec/changes/$change_name"
+                local backup_dir
+                backup_dir=$(make_temp_dir "ralph-artifact-backup")
+
+                local proposal_backup=""
+                if [[ -f "$change_dir/proposal.md" ]]; then
+                    proposal_backup="$backup_dir/proposal.md"
+                    mv "$change_dir/proposal.md" "$proposal_backup"
+                    log_info "Backed up proposal.md"
+                fi
+
+                local tasks_backup=""
+                if [[ -f "$change_dir/tasks.md" ]]; then
+                    tasks_backup="$backup_dir/tasks.md"
+                    mv "$change_dir/tasks.md" "$tasks_backup"
+                    log_info "Backed up tasks.md"
+                fi
+
+                local bp_file="openspec/OPENSPEC-RALPH-BP.md"
+                if [[ ! -f "$bp_file" ]]; then
+                    bp_file="$SCRIPT_DIR/../OPENSPEC-RALPH-BP.md"
+                fi
+                local ralph_guidance=""
+                if [[ -f "$bp_file" ]]; then
+                    ralph_guidance=" When creating artifacts, read ${bp_file} and follow the Ralph Wiggum task template and authoring checklist. Ensure the proposal includes explicit scope, non-goals, first-rollout boundaries, and capabilities that map to Ralph-friendly tasks. Ensure tasks use the task template with objective done-when conditions and explicit stop-and-hand-off conditions. Do NOT restore or copy from any .bak backup files - write fresh artifacts from scratch."
+                fi
+
+                log_info "Invoking opencode to regenerate proposal and tasks with Ralph Wiggum best practices..."
+                opencode run "/opsx-continue $change_name${ralph_guidance}" || true
+                local proposal_ok=false
+                if [[ -f "$change_dir/proposal.md" ]]; then
+                    proposal_ok=true
+                    log_info "Proposal regenerated successfully"
+                else
+                    log_error "opencode did not create a new proposal.md"
+                fi
+
+                if [[ -f "$change_dir/tasks.md" ]]; then
+                    log_info "Tasks regenerated successfully"
+                else
+                    log_error "opencode did not create a new tasks.md (only proposal may have been created; tasks may require a second /opsx-continue)"
+                fi
+
+                if [[ "$proposal_ok" == true ]]; then
+                    log_info "Artifact regeneration complete"
+                else
+                    log_error "Restoring backed-up artifacts"
+                    if [[ -n "$proposal_backup" && -f "$proposal_backup" ]]; then
+                        mv "$proposal_backup" "$change_dir/proposal.md"
+                        log_info "Restored original proposal.md"
+                    fi
+                    if [[ -n "$tasks_backup" && -f "$tasks_backup" ]]; then
+                        mv "$tasks_backup" "$change_dir/tasks.md"
+                        log_info "Restored original tasks.md"
+                    fi
+                fi
+
+                log_info "Returning to loop execution..."
+                return 0
+                ;;
+            [Cc])
+                log_info "Continuing without Ralph Wiggum configuration."
+                return 0
+                ;;
+            [Qq])
+                log_info "Exiting."
+                exit 0
+                ;;
+            *)
+                echo "Invalid choice '$choice'. Please enter A, C, or Q." >&2
+                ;;
+        esac
+    done
+}
+
 main() {
     set -e
     parse_arguments "$@"
     
+    if [[ "$SHOW_VERSION" == true ]]; then
+        echo "$VERSION"
+        exit 0
+    fi
+
+    if [[ "$SUBCOMMAND" == "init" ]]; then
+        if [[ -n "$CHANGE_NAME" ]]; then
+            log_error "Cannot use --change with the init subcommand"
+            exit 1
+        fi
+        ralphify_init
+        exit $?
+    fi
+
     log_verbose "Starting ralph-run v$VERSION"
     log_verbose "Change name: ${CHANGE_NAME:-<auto-detect>}"
 
@@ -1100,6 +1419,15 @@ main() {
     validate_git_repository
     validate_dependencies
     
+    # Ralphify guard: check if project is configured for Ralph Wiggum best practices
+    if ! check_ralphified; then
+        if [[ -z "$CHANGE_NAME" ]]; then
+            CHANGE_NAME=$(auto_detect_change)
+            log_info "Auto-detected change for ralphify guard: $CHANGE_NAME"
+        fi
+        show_ralphify_warning "$CHANGE_NAME"
+    fi
+    
     if [[ -z "$CHANGE_NAME" ]]; then
         CHANGE_NAME=$(auto_detect_change)
         log_info "Auto-detected change: $CHANGE_NAME"
@@ -1113,13 +1441,8 @@ main() {
     log_info "Change directory: $change_dir"
     log_info "Ralph directory: $ralph_dir"
     
-    read_openspec_artifacts "$change_dir"
-    local prd_content=$(generate_prd "$change_dir")
-    write_prd "$ralph_dir" "$prd_content"
-    
     parse_tasks "$change_dir"
     
-    log_info "PRD generation complete"
     log_info "Found ${#TASKS[@]} tasks to execute"
     
     local max_iterations="${MAX_ITERATIONS:-50}"