wiggum-cli 0.14.0 → 0.15.0

package/src/templates/prompts/PROMPT_review_auto.md.tmpl

@@ -95,7 +95,7 @@ fi
 ```
 
 **Handle review feedback:**
-- If Claude outputs "APPROVED" -> Proceed to Step 5 (rebase and merge)
+- If Claude outputs "APPROVED" -> Done. The PR is ready for manual merge by the user.
 - If Claude lists issues:
   1. Address each issue with code fixes
   2. Commit: `git -C {{appDir}} add -A && git -C {{appDir}} commit -m "fix($FEATURE): address review feedback"`
@@ -103,47 +103,14 @@ fi
   4. Re-run the Claude review command above
 - Max 3 review iterations before requiring manual intervention
 
-### Step 5: Rebase Before Merge (for Parallel Execution)
-Before merging, ensure branch is up-to-date with main:
-```bash
-cd {{appDir}} && git fetch origin main
-cd {{appDir}} && git rebase origin/main
-```
-
-If rebase has conflicts:
-1. Resolve conflicts in affected files
-2. `git add .` the resolved files
-3. `git rebase --continue`
-4. Re-run tests: `{{testCommand}} && {{buildCommand}}`
-
-Push rebased branch:
-```bash
-cd {{appDir}} && git push --force-with-lease origin feat/$FEATURE
-```
-
-### Step 6: Merge PR
-When Claude review is approved and branch is rebased:
-```bash
-cd {{appDir}} && gh pr merge --squash --delete-branch
-```
-
-### Step 7: Post-Merge Cleanup
-1. If using worktree, remove it:
-   ```bash
-   # Only if this feature used a worktree ({{appDir}}-$FEATURE directory exists)
-   git -C {{appDir}} worktree remove "../{{appDir}}-$FEATURE" 2>/dev/null || true
-   ```
-2. Checkout main and pull:
-   ```bash
-   git -C {{appDir}} checkout main && git -C {{appDir}} pull
-   ```
-
-Note: Spec status updates are handled in the Spec Verification phase before PR creation.
+### Step 5: Final Summary
+After review is complete (approved or max iterations reached):
+1. Post a summary comment on the PR with the review outcome
+2. Do NOT merge — the user will review and merge manually
 
 ## Rules
-- Do NOT merge without Claude Code approval
-- Address ALL review comments before merging
-- Use squash merge to keep history clean
+- Do NOT merge the PR — auto mode only reviews, the user merges
+- Address ALL review comments before marking as approved
 - If gh CLI fails, check authentication: `gh auth status`
 - Keep review conversation focused and professional
 
@@ -152,7 +119,6 @@ Note: Spec status updates are handled in the Spec Verification phase before PR c
 - **gh auth error** -> Run: `gh auth login`
 - **PR already exists** -> Use: `gh pr view` to see status
 - **Claude Code CLI not installed** -> Install: `npm install -g @anthropic-ai/claude-code`
-- **Rebase conflicts** -> Resolve carefully, re-run all tests after
 
 ## Learning Capture
 If the review revealed patterns worth remembering, append to @.ralph/LEARNINGS.md:

package/src/templates/prompts/PROMPT_review_merge.md.tmpl

@@ -0,0 +1,163 @@
+## Context
+Study @.ralph/AGENTS.md for commands and patterns.
+Study @.ralph/specs/$FEATURE.md for feature specification.
+Study @.ralph/specs/$FEATURE-implementation-plan.md for completed tasks.
+
+## Learnings
+Read @.ralph/LEARNINGS.md for patterns from previous features.
+Capture any review feedback patterns for future iterations.
+
+## Task
+All implementation and E2E tasks are complete. Create PR, review, and merge.
+
+### Step 1: Verify Ready State
+1. Check all tasks are complete in implementation plan (no `- [ ]` items)
+2. Verify tests pass: `cd {{appDir}} && {{testCommand}}`
+3. Verify build succeeds: `cd {{appDir}} && {{buildCommand}}`
+
+If any fail, fix before proceeding.
+
+### Step 2: Check Git Status
+```bash
+cd {{appDir}} && git status
+cd {{appDir}} && git log --oneline -5
+```
+
+Ensure:
+- On branch `feat/$FEATURE`
+- All changes are committed
+- Branch is pushed to remote
+
+If uncommitted changes exist:
+```bash
+git -C {{appDir}} add -A && git -C {{appDir}} commit -m "chore($FEATURE): final cleanup"
+git -C {{appDir}} push origin feat/$FEATURE
+```
+
+### Step 3: Create PR
+Check if PR already exists:
+```bash
+cd {{appDir}} && gh pr list --head feat/$FEATURE
+```
+
+If no PR exists, create one:
+```bash
+cd {{appDir}} && gh pr create --base main --head feat/$FEATURE \
+  --title "feat($FEATURE): [read description from spec]" \
+  --body "$(cat <<'EOF'
+## Summary
+[Read from spec Purpose section]
+
+## Changes
+[Read from implementation plan - list completed phases]
+
+## Testing
+- [x] Unit/integration tests: 97 passing
+- [x] E2E tests: All scenarios passed via Playwright MCP
+- [x] Build succeeds
+
+## E2E Test Results
+[Copy from implementation plan Phase 9]
+
+Generated with Claude Code
+EOF
+)"
+```
+
+### Step 4: Request Claude Code Review
+
+Run automated code review using Claude Code CLI:
+
+```bash
+# Check if Claude Code CLI is installed
+if ! command -v claude &> /dev/null; then
+    echo "WARNING: Claude Code CLI not installed. Manual review needed."
+    cd {{appDir}} && gh pr comment --body "Manual review requested - Claude Code CLI not available. Install: https://docs.anthropic.com/en/docs/claude-code/overview"
+else
+    echo "Running Claude Code review..."
+
+    cd {{appDir}} && claude -p "You are reviewing a PR for the $FEATURE feature.
+
+Review the git diff against main and check:
+- Code quality and patterns consistency
+- Test coverage adequacy
+- Potential bugs or edge cases
+- Security concerns (injection, XSS, etc.)
+- Performance implications
+- Error handling completeness
+
+Run: git diff main
+
+Respond with:
+- APPROVED if everything looks good
+- Or list specific issues with file:line references that need to be fixed"
+fi
+```
+
+**Handle review feedback:**
+- If Claude outputs "APPROVED" -> Proceed to Step 5 (rebase and merge)
+- If Claude lists issues:
+  1. Address each issue with code fixes
+  2. Commit: `git -C {{appDir}} add -A && git -C {{appDir}} commit -m "fix($FEATURE): address review feedback"`
+  3. Push: `git -C {{appDir}} push origin feat/$FEATURE`
+  4. Re-run the Claude review command above
+- Max 3 review iterations before requiring manual intervention
+
+### Step 5: Rebase Before Merge (for Parallel Execution)
+Before merging, ensure branch is up-to-date with main:
+```bash
+cd {{appDir}} && git fetch origin main
+cd {{appDir}} && git rebase origin/main
+```
+
+If rebase has conflicts:
+1. Resolve conflicts in affected files
+2. `git add .` the resolved files
+3. `git rebase --continue`
+4. Re-run tests: `{{testCommand}} && {{buildCommand}}`
+
+Push rebased branch:
+```bash
+cd {{appDir}} && git push --force-with-lease origin feat/$FEATURE
+```
+
+### Step 6: Merge PR
+When Claude review is approved and branch is rebased:
+```bash
+cd {{appDir}} && gh pr merge --squash --delete-branch
+```
+
+### Step 7: Post-Merge Cleanup
+1. If using worktree, remove it:
+   ```bash
+   # Only if this feature used a worktree ({{appDir}}-$FEATURE directory exists)
+   git -C {{appDir}} worktree remove "../{{appDir}}-$FEATURE" 2>/dev/null || true
+   ```
+2. Checkout main and pull:
+   ```bash
+   git -C {{appDir}} checkout main && git -C {{appDir}} pull
+   ```
+
+Note: Spec status updates are handled in the Spec Verification phase before PR creation.
+
+## Rules
+- Do NOT merge without Claude Code approval
+- Address ALL review comments before merging
+- Use squash merge to keep history clean
+- If gh CLI fails, check authentication: `gh auth status`
+- Keep review conversation focused and professional
+
+## Troubleshooting
+- **gh: command not found** -> Install GitHub CLI: `brew install gh`
+- **gh auth error** -> Run: `gh auth login`
+- **PR already exists** -> Use: `gh pr view` to see status
+- **Claude Code CLI not installed** -> Install: `npm install -g @anthropic-ai/claude-code`
+- **Rebase conflicts** -> Resolve carefully, re-run all tests after
+
+## Learning Capture
+If the review revealed patterns worth remembering, append to @.ralph/LEARNINGS.md:
+- Code quality feedback -> Add under "## Anti-Patterns" or "## Patterns"
+- Common review issues -> Add under "## Anti-Patterns"
+- Good practices identified -> Add under "## Patterns"
+
+Format: `- [YYYY-MM-DD] [$FEATURE] Brief description`

package/src/templates/scripts/feature-loop-actions.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Tests for the action request JSON embedded in feature-loop.sh.tmpl
+ *
+ * The shell template contains a JSON payload written by write_action_request().
+ * These tests validate that the JSON structure matches the ActionRequest schema
+ * expected by the TUI and action-inbox helpers.
+ *
+ * Note: Full bash integration tests are out of scope. This focuses on the
+ * JSON schema validation by reading the template file directly.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_PATH = join(__dirname, 'feature-loop.sh.tmpl');
+
+/**
+ * Extract the JSON block written by write_action_request() from the template.
+ * The JSON lives between `cat > "$action_file" << 'EOF'` and `EOF`.
+ */
+function extractActionRequestJson(): unknown {
+  const content = readFileSync(TEMPLATE_PATH, 'utf-8');
+
+  // Match the heredoc block: cat > ... << 'EOF' ... EOF
+  const match = content.match(/cat\s*>\s*"\$action_file"\s*<<\s*'EOF'\s*\n([\s\S]*?)\nEOF/);
+  if (!match?.[1]) {
+    throw new Error('Could not find action request JSON in feature-loop.sh.tmpl');
+  }
+
+  return JSON.parse(match[1]);
+}
+
+describe('feature-loop.sh.tmpl — action request JSON schema', () => {
+  it('parses the embedded JSON without errors', () => {
+    const parsed = extractActionRequestJson();
+    expect(parsed).toBeDefined();
+  });
+
+  it('has a non-empty string id field', () => {
+    const parsed = extractActionRequestJson() as Record<string, unknown>;
+    expect(typeof parsed.id).toBe('string');
+    expect((parsed.id as string).length).toBeGreaterThan(0);
+  });
+
+  it('has a non-empty string prompt field', () => {
+    const parsed = extractActionRequestJson() as Record<string, unknown>;
+    expect(typeof parsed.prompt).toBe('string');
+    expect((parsed.prompt as string).length).toBeGreaterThan(0);
+  });
+
+  it('has a choices array with at least one entry', () => {
+    const parsed = extractActionRequestJson() as Record<string, unknown>;
+    expect(Array.isArray(parsed.choices)).toBe(true);
+    expect((parsed.choices as unknown[]).length).toBeGreaterThan(0);
+  });
+
+  it('each choice has a non-empty string id and label', () => {
+    const parsed = extractActionRequestJson() as Record<string, unknown>;
+    const choices = parsed.choices as Array<Record<string, unknown>>;
+
+    for (const choice of choices) {
+      expect(typeof choice.id).toBe('string');
+      expect((choice.id as string).length).toBeGreaterThan(0);
+      expect(typeof choice.label).toBe('string');
+      expect((choice.label as string).length).toBeGreaterThan(0);
+    }
+  });
+
+  it('has a non-empty string default field', () => {
+    const parsed = extractActionRequestJson() as Record<string, unknown>;
+    expect(typeof parsed.default).toBe('string');
+    expect((parsed.default as string).length).toBeGreaterThan(0);
+  });
+
+  it('default value matches one of the choice ids', () => {
+    const parsed = extractActionRequestJson() as Record<string, unknown>;
+    const choices = parsed.choices as Array<Record<string, unknown>>;
+    const choiceIds = choices.map((c) => c.id as string);
+    expect(choiceIds).toContain(parsed.default as string);
+  });
+
+  it('all required ActionRequest fields are present', () => {
+    const parsed = extractActionRequestJson() as Record<string, unknown>;
+    expect(parsed).toHaveProperty('id');
+    expect(parsed).toHaveProperty('prompt');
+    expect(parsed).toHaveProperty('choices');
+    expect(parsed).toHaveProperty('default');
+  });
+});

package/src/templates/scripts/feature-loop.sh.tmpl

@@ -6,8 +6,8 @@
 # Options:
 #   --worktree           Use git worktree for isolation (enables parallel execution)
 #   --resume             Resume an interrupted loop (reuses existing branch/worktree)
-#   --model MODEL        Claude model to use (e.g., opus, sonnet, claude-sonnet-4-5-20250514)
-#   --review-mode MODE   Review mode: 'manual' (stop at PR) or 'auto' (review + merge). Default: 'manual'
+#   --model MODEL        Claude model to use (e.g., opus, sonnet, claude-sonnet-4-5-20250929)
+#   --review-mode MODE   Review mode: 'manual' (stop at PR), 'auto' (review, no merge), or 'merge' (review + merge). Default: 'manual'
 
 set -e
 set -o pipefail
@@ -91,8 +91,8 @@ if [ -z "$REVIEW_MODE" ]; then
 fi
 
 # Validate review mode
-if [ "$REVIEW_MODE" != "manual" ] && [ "$REVIEW_MODE" != "auto" ]; then
-    echo "ERROR: Invalid review mode: '$REVIEW_MODE'. Allowed values are 'manual' or 'auto'." >&2
+if [ "$REVIEW_MODE" != "manual" ] && [ "$REVIEW_MODE" != "auto" ] && [ "$REVIEW_MODE" != "merge" ]; then
+    echo "ERROR: Invalid review mode: '$REVIEW_MODE'. Allowed values are 'manual', 'auto', or 'merge'." >&2
     exit 1
 fi
 
@@ -138,6 +138,68 @@ parse_and_accumulate_tokens() {
     echo "${new_input}|${new_output}" > "$TOKENS_FILE"
 }
 
+# Action inbox: write request file if not already present
+write_action_request() {
+    local action_file="/tmp/ralph-loop-${FEATURE}.action.json"
+    if [ -f "$action_file" ]; then
+        echo "WARNING: Action request file already exists, skipping write: $action_file" >&2
+        return 0
+    fi
+    cat > "$action_file" << 'EOF'
+{
+  "id": "post_pr_choice",
+  "prompt": "Loop complete. What would you like to do?",
+  "choices": [
+    {"id": "done", "label": "Done — end loop"},
+    {"id": "merge_local", "label": "Merge back to main locally"},
+    {"id": "keep_branch", "label": "Keep branch as-is"},
+    {"id": "discard", "label": "Discard this work"}
+  ],
+  "default": "done"
+}
+EOF
+    echo "Action request written: $action_file"
+}
+
+# Action inbox: poll for reply file, fallback to default after 15 minutes
+poll_action_reply() {
+    local action_file="/tmp/ralph-loop-${FEATURE}.action.json"
+    local reply_file="/tmp/ralph-loop-${FEATURE}.action.reply.json"
+    local default_choice="keep_branch"
+    local timeout=900  # 15 minutes in seconds
+    local elapsed=0
+
+    # Read default from action file if present
+    if [ -f "$action_file" ]; then
+        local parsed_default
+        parsed_default=$(node -e "try { const d=require('fs').readFileSync(process.argv[1],'utf8'); console.log(JSON.parse(d).default||'keep_branch'); } catch(e) { console.log('keep_branch'); }" "$action_file" 2>/dev/null || echo "keep_branch")
+        if [ -n "$parsed_default" ]; then
+            default_choice="$parsed_default"
+        fi
+    fi
+
+    while [ $elapsed -lt $timeout ]; do
+        if [ -f "$reply_file" ]; then
+            local choice
+            choice=$(node -e "try { const d=require('fs').readFileSync(process.argv[1],'utf8'); console.log(JSON.parse(d).choice||''); } catch(e) { console.log(''); }" "$reply_file" 2>/dev/null || echo "")
+            if [ -n "$choice" ]; then
+                echo "User selected: $choice" >&2
+                # Cleanup both files
+                rm -f "$action_file" "$reply_file" 2>/dev/null || true
+                echo "$choice"
+                return 0
+            fi
+        fi
+        sleep 1
+        elapsed=$((elapsed + 1))
+    done
+
+    # Timeout: use default
+    echo "Action reply timeout after ${timeout}s, using default: $default_choice" >&2
+    rm -f "$action_file" "$reply_file" 2>/dev/null || true
+    echo "$default_choice"
+}
+
 # Initialize tokens
 init_tokens
 
@@ -343,18 +405,106 @@ echo "======================== PR & REVIEW PHASE ========================"
 write_phase_start "pr_review"
 export FEATURE APP_DIR SPEC_DIR PROMPTS_DIR
 PR_STATUS="success"
+MAX_REVIEW_ATTEMPTS=3
+
 if [ "$REVIEW_MODE" = "manual" ]; then
     if ! cat "$PROMPTS_DIR/PROMPT_review_manual.md" | envsubst | $CLAUDE_CMD_OPUS 2>&1 | tee "$CLAUDE_OUTPUT"; then
         PR_STATUS="failed"
     fi
-else
-    if ! cat "$PROMPTS_DIR/PROMPT_review_auto.md" | envsubst | $CLAUDE_CMD_OPUS 2>&1 | tee "$CLAUDE_OUTPUT"; then
+    parse_and_accumulate_tokens "$CLAUDE_OUTPUT"
+
+elif [ "$REVIEW_MODE" = "merge" ]; then
+    # Merge mode: create PR, iterate review+fixes until approved, then merge
+    REVIEW_ATTEMPT=0
+    REVIEW_APPROVED=false
+    while [ $REVIEW_ATTEMPT -lt $MAX_REVIEW_ATTEMPTS ]; do
+        REVIEW_ATTEMPT=$((REVIEW_ATTEMPT + 1))
+        echo "--- Review attempt $REVIEW_ATTEMPT of $MAX_REVIEW_ATTEMPTS ---"
+        cat "$PROMPTS_DIR/PROMPT_review_merge.md" | envsubst | $CLAUDE_CMD_OPUS 2>&1 | tee "$CLAUDE_OUTPUT" || true
+        parse_and_accumulate_tokens "$CLAUDE_OUTPUT"
+
+        # Check if output contains APPROVED
+        if grep -qi "APPROVED" "$CLAUDE_OUTPUT" 2>/dev/null; then
+            echo "Review approved!"
+            REVIEW_APPROVED=true
+            break
+        fi
+
+        if [ $REVIEW_ATTEMPT -lt $MAX_REVIEW_ATTEMPTS ]; then
+            echo "Review found issues. Running fix iteration..."
+            echo "Fix the issues found in the code review above. Run git diff main to see the current changes, then:
+1. Fix each issue referenced in the review
+2. Run tests: npm test
+3. Commit and push the fixes
+Do NOT propose completion options or ask interactive questions. Just fix, test, commit, push." | $CLAUDE_CMD_IMPL 2>&1 | tee "$CLAUDE_OUTPUT" || true
+            parse_and_accumulate_tokens "$CLAUDE_OUTPUT"
+        fi
+    done
+    if [ "$REVIEW_APPROVED" != true ]; then
+        echo "Review not approved after $MAX_REVIEW_ATTEMPTS attempts."
         PR_STATUS="failed"
     fi
+
+else
+    # Auto mode: create PR, iterate review+fixes until approved (no merge)
+    REVIEW_ATTEMPT=0
+    REVIEW_APPROVED=false
+    while [ $REVIEW_ATTEMPT -lt $MAX_REVIEW_ATTEMPTS ]; do
+        REVIEW_ATTEMPT=$((REVIEW_ATTEMPT + 1))
+        echo "--- Review attempt $REVIEW_ATTEMPT of $MAX_REVIEW_ATTEMPTS ---"
+        cat "$PROMPTS_DIR/PROMPT_review_auto.md" | envsubst | $CLAUDE_CMD_OPUS 2>&1 | tee "$CLAUDE_OUTPUT" || true
+        parse_and_accumulate_tokens "$CLAUDE_OUTPUT"
+
+        # Check if output contains APPROVED
+        if grep -qi "APPROVED" "$CLAUDE_OUTPUT" 2>/dev/null; then
+            echo "Review approved!"
+            REVIEW_APPROVED=true
+            break
+        fi
+
+        if [ $REVIEW_ATTEMPT -lt $MAX_REVIEW_ATTEMPTS ]; then
+            echo "Review found issues. Running fix iteration..."
+            echo "Fix the issues found in the code review above. Run git diff main to see the current changes, then:
+1. Fix each issue referenced in the review
+2. Run tests: npm test
+3. Commit and push the fixes
+Do NOT propose completion options or ask interactive questions. Just fix, test, commit, push." | $CLAUDE_CMD_IMPL 2>&1 | tee "$CLAUDE_OUTPUT" || true
+            parse_and_accumulate_tokens "$CLAUDE_OUTPUT"
+        fi
+    done
+    if [ "$REVIEW_APPROVED" != true ]; then
+        echo "Review not approved after $MAX_REVIEW_ATTEMPTS attempts. PR ready for manual review."
+    fi
 fi
-parse_and_accumulate_tokens "$CLAUDE_OUTPUT"
 write_phase_end "pr_review" "$PR_STATUS"
 
+# Phase 7.5: Post-completion action request
+echo "======================== ACTION REQUEST PHASE ========================"
+write_action_request
+CHOSEN_ACTION=$(poll_action_reply)
+echo "User chose: $CHOSEN_ACTION"
+
+# Dispatch based on user choice
+case "$CHOSEN_ACTION" in
+    done)
+        echo "Loop complete. Exiting."
+        ;;
+    merge_local)
+        echo "Merging back to main locally..."
+        git checkout main 2>/dev/null || git checkout master
+        git merge --squash "$BRANCH" && git commit -m "feat($FEATURE): squash merge from $BRANCH"
+        echo "Merged. You can delete the branch with: git branch -D $BRANCH"
+        ;;
+    discard)
+        echo "Discarding work on branch $BRANCH..."
+        git checkout main 2>/dev/null || git checkout master
+        git branch -D "$BRANCH" 2>/dev/null || echo "Branch $BRANCH not found locally."
+        ;;
+    keep_branch|*)
+        echo "Keeping branch $BRANCH as-is."
+        ;;
+esac
+
 # Persist final status for TUI summaries
 if ! echo "$ITERATION|$MAX_ITERATIONS|$(date +%s)|done" > "$FINAL_STATUS_FILE"; then
     echo "WARNING: Failed to write final status file: $FINAL_STATUS_FILE" >&2