wiggum-cli 0.15.0 → 0.17.0

package/dist/utils/github.d.ts

@@ -0,0 +1,32 @@
+export declare function isGhInstalled(): Promise<boolean>;
+export declare function _resetGhCache(): void;
+export interface GitHubIssueDetail {
+    title: string;
+    body: string;
+    labels: string[];
+}
+export declare function fetchGitHubIssue(owner: string, repo: string, number: number): Promise<GitHubIssueDetail | null>;
+export interface GitHubIssueListItem {
+    number: number;
+    title: string;
+    state: 'open' | 'closed';
+    labels: string[];
+    createdAt: string;
+}
+export interface ListIssuesResult {
+    issues: GitHubIssueListItem[];
+    error?: string;
+}
+export declare function listRepoIssues(owner: string, repo: string, search?: string, limit?: number): Promise<ListIssuesResult>;
+export declare function detectGitHubRemote(projectRoot: string): Promise<GitHubRepo | null>;
+export interface ParsedGitHubIssue {
+    owner: string;
+    repo: string;
+    number: number;
+}
+export declare function isGitHubIssueUrl(input: string): ParsedGitHubIssue | null;
+export interface GitHubRepo {
+    owner: string;
+    repo: string;
+}
+export declare function parseGitHubRemote(remoteUrl: string): GitHubRepo | null;

package/dist/utils/github.js

@@ -0,0 +1,106 @@
+import { execFile as execFileCb } from 'node:child_process';
+/**
+ * Safe command execution using execFile (no shell, array-based args).
+ */
+function safeExec(cmd, args, cwd) {
+    return new Promise((resolve, reject) => {
+        execFileCb(cmd, args, { cwd, timeout: 10000 }, (error, stdout) => {
+            if (error)
+                reject(error);
+            else
+                resolve(String(stdout));
+        });
+    });
+}
+let ghInstalledCache = null;
+export async function isGhInstalled() {
+    if (ghInstalledCache !== null)
+        return ghInstalledCache;
+    try {
+        await safeExec('gh', ['--version']);
+        ghInstalledCache = true;
+    }
+    catch {
+        ghInstalledCache = false;
+    }
+    return ghInstalledCache;
+}
+export function _resetGhCache() {
+    ghInstalledCache = null;
+}
+export async function fetchGitHubIssue(owner, repo, number) {
+    try {
+        const stdout = await safeExec('gh', [
+            'issue', 'view', String(number),
+            '--repo', `${owner}/${repo}`,
+            '--json', 'title,body,labels',
+        ]);
+        const data = JSON.parse(stdout);
+        return {
+            title: data.title ?? '',
+            body: data.body ?? '',
+            labels: (data.labels ?? []).map((l) => l.name),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function listRepoIssues(owner, repo, search, limit = 20) {
+    try {
+        const args = [
+            'issue', 'list',
+            '--repo', `${owner}/${repo}`,
+            '--limit', String(limit),
+            '--json', 'number,title,state,labels,createdAt',
+            '--state', 'open',
+        ];
+        if (search) {
+            args.push('--search', search);
+        }
+        const stdout = await safeExec('gh', args);
+        const data = JSON.parse(stdout);
+        const issues = data.map((item) => ({
+            number: item.number,
+            title: item.title,
+            state: item.state.toLowerCase(),
+            labels: (item.labels ?? []).map((l) => l.name),
+            createdAt: item.createdAt ?? '',
+        }));
+        return { issues };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('auth') || msg.includes('login') || msg.includes('not logged')) {
+            return { issues: [], error: 'Run "gh auth login" to enable issue browsing' };
+        }
+        return { issues: [] };
+    }
+}
+export async function detectGitHubRemote(projectRoot) {
+    try {
+        const stdout = await safeExec('git', ['remote', 'get-url', 'origin'], projectRoot);
+        return parseGitHubRemote(stdout.trim());
+    }
+    catch {
+        return null;
+    }
+}
+const GITHUB_ISSUE_RE = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/(issues|pull)\/(\d+)\/?/;
+export function isGitHubIssueUrl(input) {
+    const match = input.match(GITHUB_ISSUE_RE);
+    if (!match)
+        return null;
+    return { owner: match[1], repo: match[2], number: parseInt(match[4], 10) };
+}
+const SSH_REMOTE_RE = /^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/;
+const HTTPS_REMOTE_RE = /^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/;
+export function parseGitHubRemote(remoteUrl) {
+    const ssh = remoteUrl.match(SSH_REMOTE_RE);
+    if (ssh)
+        return { owner: ssh[1], repo: ssh[2] };
+    const https = remoteUrl.match(HTTPS_REMOTE_RE);
+    if (https)
+        return { owner: https[1], repo: https[2] };
+    return null;
+}

package/dist/utils/spec-names.js

@@ -17,7 +17,11 @@ export async function listSpecNames(specsDir) {
         return [];
     }
     return entries
-        .filter((e) => e.isFile() && e.name.endsWith('.md'))
+        .filter((e) => e.isFile() &&
+        e.name.endsWith('.md') &&
+        !e.name.startsWith('_') &&
+        e.name !== 'README.md' &&
+        !e.name.endsWith('-implementation-plan.md'))
         .map((e) => e.name.slice(0, -3))
         .sort();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiggum-cli",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "AI-powered feature development loop CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -22,6 +22,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
+    "e2e:bridge": "tsx e2e/bridge/server.ts",
     "prepublishOnly": "npm run build && npm test"
   },
   "keywords": [
@@ -60,13 +61,20 @@
     "react": "^18.3.1",
     "zod": "^4.3.5"
   },
+  "overrides": {
+    "minimatch": ">=10.2.1"
+  },
   "devDependencies": {
     "@types/node": "^20.10.0",
     "@types/react": "^19.2.9",
+    "@types/ws": "^8.5.10",
     "@vitest/coverage-v8": "^4.0.18",
     "ink-testing-library": "^4.0.0",
+    "node-pty": "^1.0.0",
+    "tsx": "^4.7.0",
     "typescript": "^5.3.0",
-    "vitest": "^4.0.17"
+    "vitest": "^4.0.17",
+    "ws": "^8.16.0"
   },
   "engines": {
     "node": ">=18.0.0"

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

@@ -1,5 +1,5 @@
 ## Context
-Study @.ralph/AGENTS.md for commands and patterns.
+If @.ralph/guides/AGENTS.md exists, study it for commands and patterns.
 Study @.ralph/specs/$FEATURE.md for feature specification.
 Study @.ralph/specs/$FEATURE-implementation-plan.md for current tasks.
 {{#if frameworkVariant}}For detailed architecture, see @{{appDir}}/.claude/CLAUDE.md{{/if}}
@@ -18,10 +18,10 @@ Key patterns: parallel fetches, direct imports, React.cache(), lazy loading.
 - Search codebase before assuming something doesn't exist
 
 ## Task
-Pick the next incomplete task from the implementation plan.
+Work through ALL incomplete tasks in the implementation plan in a single session.
 **Skip E2E tasks** (tasks starting with `E2E:`) - those are handled in a separate phase.
-Implement it following the patterns in AGENTS.md.
-Write tests for the implementation.
+For each task: implement it, write tests, validate, commit, then move to the next task.
+Do not stop after one task — keep going until all non-E2E tasks are complete.
 
 ## Validation
 After changes, ALL must pass:
@@ -36,7 +36,8 @@ If any validation fails, fix the issue before proceeding.
 Before committing, review your changes against @.ralph/guides/SECURITY.md:
 1. **Quick scan**: Input validation, injection prevention, auth checks, data exposure
 2. **Run**: `cd {{appDir}} && {{packageManager}} audit` (check for vulnerable dependencies)
-3. **Check**: `mcp__supabase__get_advisors` with type "security" (RLS policies)
+{{#if hasSupabase}}3. **Check**: `mcp__supabase__get_advisors` with type "security" (RLS policies)
+{{/if}}
 4. **Red team**: Can auth be bypassed? Can other users' data be accessed?
 
 Flag any security issues in the implementation plan and fix before committing.
@@ -54,7 +55,7 @@ If any check fails, fix before committing.
 
 ## Completion
 When ALL validations pass:
-1. Update @.ralph/specs/$FEATURE-implementation-plan.md - mark task done with commit hash
+1. Update @.ralph/specs/$FEATURE-implementation-plan.md — change the task's `- [ ]` to `- [x]` and append the commit hash (e.g., `- [x] Task description - abc1234`). The harness tracks progress by counting checkboxes, so this step is mandatory.
 2. `git -C {{appDir}} add -A`
 3. `git -C {{appDir}} commit -m "type(scope): description"`
 4. `git -C {{appDir}} push origin feat/$FEATURE`
@@ -69,9 +70,11 @@ If this iteration revealed something useful, append to @.ralph/LEARNINGS.md:
 Format: `- [YYYY-MM-DD] [$FEATURE] Brief description`
 
 ## Rules
-- One task per iteration
+- Complete ALL remaining non-E2E tasks before ending the session
+- Commit after each task so progress is preserved if the session is interrupted
 - Tests are mandatory - no task is complete without tests
 - Search codebase before assuming something doesn't exist
-- If blocked, document in implementation plan and move to next task
-- Use Supabase MCP for database operations
-- Use PostHog MCP for analytics queries
+- If blocked on a task, document in implementation plan and move to the next task
+{{#if hasSupabase}}- Use Supabase MCP for database operations
+{{/if}}{{#if hasPosthog}}- Use PostHog MCP for analytics queries
+{{/if}}

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

@@ -1,5 +1,5 @@
 ## Context
-Study @.ralph/AGENTS.md for commands and patterns.
+If @.ralph/guides/AGENTS.md exists, study it for commands and patterns.
 Study @.ralph/specs/$FEATURE.md for feature specification.
 Study @.ralph/specs/$FEATURE-implementation-plan.md for E2E test scenarios.
 {{#if frameworkVariant}}For detailed architecture, see @{{appDir}}/.claude/CLAUDE.md{{/if}}
@@ -12,12 +12,164 @@ Pay special attention to "E2E Pitfalls" section to avoid known issues.
 Before E2E testing, verify:
 1. Build passes: `cd {{appDir}} && {{buildCommand}}`
 2. All unit tests pass: `cd {{appDir}} && {{testCommand}}`
+{{#unless isTui}}
 3. Clear cache if issues: `rm -rf {{appDir}}/.next`
+{{/unless}}
 
 If either fails, fix issues before proceeding with E2E tests.
 
+{{#if isTui}}
+## Task
+Execute automated E2E tests for the completed TUI feature using the xterm.js bridge and agent-browser.
+Run ALL scenarios in a single session — do not end between scenarios.
+
+### Step 1: Start Bridge
+Check the bridge is running:
+```bash
+curl -s http://localhost:3999/health || (cd {{projectRoot}} && npm run e2e:bridge &)
+sleep 3
+```
+
+### Step 2: Parse E2E Test Scenarios
+Read E2E test scenarios from @.ralph/specs/$FEATURE-implementation-plan.md.
+Each scenario is marked with `- [ ] E2E:` prefix and follows this format:
+
+```
+- [ ] E2E: [Scenario name]
+  - **Command:** [wiggum command, e.g., init, new auth-flow]
+  - **CWD:** [working directory, e.g., e2e/fixtures/bare-project]
+  - **Steps:**
+    1. [Action] -> [expected terminal output]
+  - **Verify:** [text that should appear in terminal]
+```
+
+### Step 3: Execute Each Scenario
+
+For each scenario:
+
+1. **Open the TUI in the bridge:**
+```bash
+agent-browser open "http://localhost:3999?cmd=<command>&cwd=<path>"
+```
+
+2. **Wait for terminal ready:**
+```bash
+agent-browser wait --text "Ready" --source title --timeout 10000
+```
+
+3. **Read terminal content:**
+```bash
+agent-browser eval "document.getElementById('terminal-mirror').textContent"
+```
+
+4. **Interact with TUI:**
+```bash
+# Click to focus terminal
+agent-browser snapshot -i
+agent-browser click @<terminal-ref>
+
+# Type text (Enter = press Enter after)
+agent-browser type @<terminal-ref> "/help"
+agent-browser key Enter
+
+# Arrow navigation
+agent-browser key ArrowDown
+agent-browser key ArrowDown
+agent-browser key Enter
+
+# Escape
+agent-browser key Escape
+```
+
+5. **Assert expected output:**
+```bash
+# Read terminal and check for expected text
+CONTENT=$(agent-browser eval "document.getElementById('terminal-mirror').textContent")
+# Verify CONTENT contains expected strings
+```
+
+6. **Reset between scenarios:**
+```bash
+agent-browser close
+```
+
+### TUI Interaction Cheatsheet
+
+| Action | Command |
+|--------|---------|
+| Open TUI | `agent-browser open "http://localhost:3999?cmd=init&cwd=/path"` |
+| Read screen | `agent-browser eval "document.getElementById('terminal-mirror').textContent"` |
+| Take snapshot | `agent-browser snapshot -i` |
+| Click element | `agent-browser click @ref` |
+| Type text | `agent-browser type @ref "text"` |
+| Press Enter | `agent-browser key Enter` |
+| Arrow down | `agent-browser key ArrowDown` |
+| Escape | `agent-browser key Escape` |
+| Screenshot | `agent-browser screenshot e2e-failure.png` |
+| Wait for text | `agent-browser wait --text "expected" --timeout 10000` |
+| Close session | `agent-browser close` |
+
+### Key Rules
+- Always wait for expected text before asserting (TUI renders async via React)
+- Use `agent-browser eval` with `terminal-mirror` for reliable text reading
+- Take screenshots on failures for debugging
+- Each scenario navigates to a fresh URL (clean state)
+- Wait 500ms after key presses before reading (Ink re-render delay)
+
+### Step 4: Report Results
+Update @.ralph/specs/$FEATURE-implementation-plan.md for each scenario:
+
+**Passed:**
+```markdown
+- [x] E2E: scenario name - PASSED
+```
+
+**Failed:**
+```markdown
+- [ ] E2E: scenario name - FAILED: [brief reason]
+  - Error: [what went wrong]
+  - Screenshot: [if captured]
+  - Fix needed: [suggested action]
+```
+
+## Error Recovery
+
+If a scenario fails:
+1. Document the failure with specific error details
+2. Take a screenshot: `agent-browser screenshot e2e-failure-<scenario>.png`
+3. Note what fix is likely needed (code bug vs test spec issue)
+4. Continue with remaining scenarios
+5. At end, summary shows total passed/failed
+
+Failures will trigger a fix iteration in the loop.
+
+## Completion
+
+When all scenarios are executed:
+1. Update implementation plan with results for each scenario
+2. Update the Implementation Summary status to `[PASSED]` if all passed
+3. **Commit the updated implementation plan:**
+   ```bash
+   git -C {{appDir}} add -A && git -C {{appDir}} commit -m "test($FEATURE): E2E tests passed via agent-browser"
+   ```
+4. **Push to remote:**
+   ```bash
+   git -C {{appDir}} push origin feat/$FEATURE
+   ```
+5. If all passed: signal ready for PR phase
+6. If any failed: failures documented, loop will retry after fix iteration
+
+## Learning Capture
+If E2E testing revealed issues worth remembering, append to @.ralph/LEARNINGS.md:
+- Flaky test patterns -> Add under "## Anti-Patterns" > "E2E Pitfalls"
+- TUI timing issues -> Add under "## Anti-Patterns"
+- Useful agent-browser techniques -> Add under "## Tool Usage"
+
+Format: `- [YYYY-MM-DD] [$FEATURE] Brief description`
+{{else}}
 ## Task
 Execute automated E2E tests for the completed feature using Playwright MCP tools.
+Run ALL scenarios in a single session — do not end between scenarios.
 
 ### Step 1: Check Dev Server
 Verify dev server is running at http://localhost:3000. If not accessible, start it:
@@ -26,7 +178,7 @@ cd {{appDir}} && {{devCommand}} &
 ```
 Wait ~10 seconds for server startup, then verify with a simple browser_navigate.
 
-### Step 1.5: Seed Test Data (if needed)
+{{#if hasSupabase}}### Step 1.5: Seed Test Data (if needed)
 
 Check if test scenarios require specific data volumes (e.g., pagination needs >10 rows).
 
@@ -49,6 +201,7 @@ query: "DELETE FROM table_name WHERE data->>'_test' = 'true';"
 ```
 
 **If seeding is impractical:** Document in implementation plan that E2E was skipped but unit tests provide coverage.
+{{/if}}
 
 ### Step 2: Parse E2E Test Scenarios
 Read E2E test scenarios from @.ralph/specs/$FEATURE-implementation-plan.md.
@@ -96,7 +249,7 @@ For each E2E test scenario:
    - Check console: `browser_console_messages` for JS errors
    - Document failure details
 
-### Step 4: Database Verification
+{{#if hasSupabase}}### Step 4: Database Verification
 For scenarios with database checks, use Supabase MCP:
 ```
 mcp__plugin_supabase_supabase__execute_sql
@@ -105,6 +258,7 @@ query: "SELECT * FROM survey_responses WHERE ..."
 ```
 
 Verify returned data matches expected state.
+{{/if}}
 
 ### Unique Test Data (for Parallel Execution)
 When creating test data, use unique identifiers to avoid conflicts with other loops:
@@ -165,11 +319,12 @@ Update @.ralph/specs/$FEATURE-implementation-plan.md for each scenario:
 2. Verify URL contains expected path/params
 ```
 
-### Database State
+{{#if hasSupabase}}### Database State
 ```
 1. mcp__plugin_supabase_supabase__execute_sql with SELECT query
 2. Verify row count, column values match expectations
 ```
+{{/if}}
 
 ## Browser State Management
 
@@ -214,8 +369,9 @@ If code changes don't appear in the browser:
 
 ### Stale Data
 - Clear browser storage: Use `browser_close` between scenarios
-- Check Supabase for stale test data from previous runs
+{{#if hasSupabase}}- Check Supabase for stale test data from previous runs
 - Delete test data: `DELETE FROM table WHERE data->>'_test' = 'true'`
+{{/if}}
 
 ## Rules
 - Always get a fresh `browser_snapshot` after actions before making assertions
@@ -232,3 +388,4 @@ If E2E testing revealed issues worth remembering, append to @.ralph/LEARNINGS.md
 - Timing issues or race conditions -> Add under "## Anti-Patterns"
 
 Format: `- [YYYY-MM-DD] [$FEATURE] Brief description`
+{{/if}}

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

@@ -1,5 +1,5 @@
 ## Context
-Study @.ralph/AGENTS.md for commands and patterns.
+If @.ralph/guides/AGENTS.md exists, study it for commands and patterns.
 Study @.ralph/specs/README.md for spec structure.
 Study @.ralph/specs/$FEATURE.md for feature specification.
 {{#if frameworkVariant}}For detailed architecture, see @{{appDir}}/.claude/CLAUDE.md{{/if}}
@@ -44,6 +44,28 @@ Study @.ralph/specs/$FEATURE.md for feature specification.
 - [ ] Task N (additional polish)
 
 ### Phase 5: E2E Testing
+{{#if isTui}}
+TUI E2E tests executed via xterm.js bridge + agent-browser.
+Fixture projects in `e2e/fixtures/`. Bridge at `http://localhost:3999`.
+
+- [ ] E2E: [Scenario name] - [brief description]
+  - **Command:** [wiggum command, e.g., init, new auth-flow]
+  - **CWD:** [working directory, e.g., e2e/fixtures/bare-project]
+  - **Steps:**
+    1. [Action] -> [expected terminal output]
+    2. [Action] -> [expected terminal output]
+  - **Verify:** [text that should appear in terminal]
+
+Example TUI E2E scenario:
+- [ ] E2E: Init in bare project - happy path
+  - **Command:** init
+  - **CWD:** e2e/fixtures/bare-project
+  - **Steps:**
+    1. Open bridge with init command -> Welcome screen renders
+    2. Arrow down to select option -> Option highlighted
+    3. Press Enter -> Next screen appears
+  - **Verify:** "initialized" text visible in terminal
+{{else}}
 Browser-based tests executed via Playwright MCP tools.
 
 - [ ] E2E: [Scenario name] - [brief description]
@@ -67,15 +89,29 @@ Example E2E scenario:
     5. Wait for "Thank You!" -> Success card displays
   - **Verify:** "successfully submitted" text visible
   - **Database check:** SELECT * FROM survey_responses WHERE survey_id = '{surveyId}'
+{{/if}}
 
 ## Done
 - [x] Completed task - [commit hash]
 - [x] E2E: Scenario name - PASSED
 ```
 
+## CRITICAL CONSTRAINT — PLANNING ONLY
+**You are in the PLANNING phase. Your ONLY job is to produce an implementation plan.**
+- Do NOT write any source code, test code, or configuration files
+- Do NOT create, modify, or touch any files outside `.ralph/specs/`
+- Do NOT run build, test, or lint commands
+- Do NOT make git commits
+- If you feel the urge to "just implement a small piece", STOP — that is a phase violation
+- The implementation phase runs AFTER this session ends, in a separate session
+- Violation of this constraint wastes tokens and breaks the harness automation
+
 ## Rules
-- Plan only in this phase, do NOT implement
-- One task = one commit-sized unit of work
+- You MUST use `- [ ]` checkbox syntax for every task in the plan
+- Do NOT use heading-based task formats (e.g., `#### Task 1:`) for individual tasks
+- The harness parses `- [ ]` lines to track progress — other formats will break automation
+- Use `### Phase N:` headings only for phase grouping, not for individual tasks
+- One task = one commit-sized unit of work (but tasks can be grouped into phases for batch implementation)
 - Every implementation task needs a corresponding test task
 - Use Supabase MCP to check existing schema
 - Use PostHog MCP to check existing analytics setup

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

@@ -1,5 +1,5 @@
 ## Context
-Study @.ralph/AGENTS.md for commands and patterns.
+If @.ralph/guides/AGENTS.md exists, study it for commands and patterns.
 Study @.ralph/specs/$FEATURE.md for feature specification.
 Study @.ralph/specs/$FEATURE-implementation-plan.md for completed tasks.
 
@@ -9,6 +9,7 @@ Capture any review feedback patterns for future iterations.
 
 ## Task
 All implementation and E2E tasks are complete. Create PR and request review.
+Complete ALL steps in a single pass — do not end the session between steps.
 
 ### Step 1: Verify Ready State
 1. Check all tasks are complete in implementation plan (no `- [ ]` items)
@@ -52,12 +53,14 @@ cd {{appDir}} && gh pr create --base main --head feat/$FEATURE \
 [Read from implementation plan - list completed phases]
 
 ## Testing
-- [x] Unit/integration tests: 97 passing
-- [x] E2E tests: All scenarios passed via Playwright MCP
+- [x] Unit/integration tests: passing
+- [x] E2E tests: All scenarios passed
 - [x] Build succeeds
 
 ## E2E Test Results
-[Copy from implementation plan Phase 9]
+[Copy from implementation plan E2E section]
+
+Closes #[Read the source issue number from the spec file metadata or context section]
 
 Generated with Claude Code
 EOF
@@ -88,14 +91,29 @@ Review the git diff against main and check:
 
 Run: git diff main
 
-Respond with:
-- APPROVED if everything looks good
-- Or list specific issues with file:line references that need to be fixed"
+Then:
+1. Post your complete review as a comment on the PR using:
+   gh pr comment --body '<your review in markdown>'
+   Format the comment with: a summary, specific issues with file:line refs (if any), and the verdict.
+2. Print your final verdict as the LAST line of stdout. Print exactly one of:
+   VERDICT: APPROVED
+   VERDICT: NOT APPROVED
+   This line is parsed by the automation — do not omit it."
 fi
 ```
 
+After the review completes, check its output:
+- If it contains "VERDICT: APPROVED", echo that line so the automation detects it:
+  ```bash
+  echo "VERDICT: APPROVED"
+  ```
+- If issues were found, echo:
+  ```bash
+  echo "VERDICT: NOT APPROVED"
+  ```
+
 **Handle review feedback:**
-- If Claude outputs "APPROVED" -> Done. The PR is ready for manual merge by the user.
+- If Claude outputs "VERDICT: 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"`
@@ -108,8 +126,15 @@ 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
 
+## IMPORTANT: Review scope
+If you discover that no implementation code exists (empty diff, no source files changed),
+do NOT implement the feature yourself. Instead, report "VERDICT: NOT APPROVED —
+no implementation found" so the harness can trigger a new implementation iteration.
+
 ## Rules
+- **NEVER approve if any tests are failing.** Output "VERDICT: NOT APPROVED — test failures" if any tests fail.
 - Do NOT merge the PR — auto mode only reviews, the user merges
+- Do NOT implement missing features — only review and fix minor issues
 - Address ALL review comments before marking as approved
 - If gh CLI fails, check authentication: `gh auth status`
 - Keep review conversation focused and professional

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

@@ -1,5 +1,5 @@
 ## Context
-Study @.ralph/AGENTS.md for commands and patterns.
+If @.ralph/guides/AGENTS.md exists, study it for commands and patterns.
 Study @.ralph/specs/$FEATURE.md for feature specification.
 Study @.ralph/specs/$FEATURE-implementation-plan.md for completed tasks.
 
@@ -9,6 +9,7 @@ Capture any review feedback patterns for future iterations.
 
 ## Task
 All implementation and E2E tasks are complete. Create PR for manual review.
+Complete ALL steps in a single pass — do not end the session between steps.
 
 ### Step 1: Verify Ready State
 1. Check all tasks are complete in implementation plan (no `- [ ]` items)
@@ -59,6 +60,8 @@ cd {{appDir}} && gh pr create --base main --head feat/$FEATURE \
 ## E2E Test Results
 [Copy from implementation plan if E2E phase exists]
 
+Closes #[Read the source issue number from the spec file metadata or context section]
+
 Generated with Claude Code
 EOF
 )"