wiggum-cli 0.14.0 → 0.15.0

package/dist/tui/screens/RunScreen.js

@@ -18,6 +18,7 @@ import { execFileSync, spawn } from 'node:child_process';
 import { closeSync, existsSync, openSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { Confirm } from '../components/Confirm.js';
+import { Select } from '../components/Select.js';
 import { AppShell } from '../components/AppShell.js';
 import { RunCompletionSummary } from '../components/RunCompletionSummary.js';
 import { colors, theme } from '../theme.js';
@@ -26,6 +27,7 @@ import { buildEnhancedRunSummary } from '../utils/build-run-summary.js';
 import { writeRunSummaryFile } from '../../utils/summary-file.js';
 import { loadConfigWithDefaults } from '../../utils/config.js';
 import { logger } from '../../utils/logger.js';
+import { readActionRequest, writeActionReply, cleanupActionFiles } from '../utils/action-inbox.js';
 const POLL_INTERVAL_MS = 2500;
 const ERROR_TAIL_LINES = 12;
 function findFeatureLoopScript(projectRoot, scriptsDir) {
@@ -103,6 +105,7 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
     const [isStarting, setIsStarting] = useState(!monitorOnly);
     const [showConfirm, setShowConfirm] = useState(false);
     const [completionSummary, setCompletionSummary] = useState(null);
+    const [actionRequest, setActionRequest] = useState(null);
     const childRef = useRef(null);
     const stopRequestedRef = useRef(false);
     const isMountedRef = useRef(true);
@@ -113,6 +116,7 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
     const scriptsDirRef = useRef('.ralph/scripts');
     const maxIterationsRef = useRef(0);
     const maxE2eAttemptsRef = useRef(0);
+    const handledActionIdRef = useRef(null);
     useInput((input, key) => {
         // If showing completion summary, Enter or Esc dismisses
         if (completionSummary) {
@@ -123,6 +127,9 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
         }
         if (showConfirm)
             return;
+        // Action prompt handles its own input (Select component)
+        if (actionRequest)
+            return;
         if (key.ctrl && input === 'c') {
             setShowConfirm(true);
             return;
@@ -149,6 +156,21 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
         if (!isMountedRef.current)
             return;
         setBranch(getGitBranch(projectRoot));
+        // Check for pending action request (loop waiting for user input)
+        const request = readActionRequest(featureName);
+        if (!isMountedRef.current)
+            return;
+        if (request) {
+            // Only show if we haven't already handled this action
+            if (request.id !== handledActionIdRef.current) {
+                setActionRequest(request);
+            }
+        }
+        else {
+            // File cleaned up by shell — reset tracking so future requests work
+            handledActionIdRef.current = null;
+            setActionRequest((prev) => prev ? null : prev);
+        }
         // In monitor mode, detect completion (only fire once)
         if (monitorOnly && !nextStatus.running && !completionSentRef.current) {
             completionSentRef.current = true;
@@ -190,6 +212,10 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
             });
         }
     }, [featureName, projectRoot, monitorOnly]);
+    // Keep a stable ref to the latest refreshStatus so the spawn effect
+    // can schedule polls without re-running when refreshStatus changes.
+    const refreshStatusRef = useRef(refreshStatus);
+    useEffect(() => { refreshStatusRef.current = refreshStatus; }, [refreshStatus]);
     const stopLoop = useCallback(() => {
         stopRequestedRef.current = true;
         if (childRef.current) {
@@ -244,11 +270,11 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
                 if (cancelled)
                     return;
                 setIsStarting(false);
-                refreshStatus().catch((err) => {
+                refreshStatusRef.current().catch((err) => {
                     logger.warn(`Status refresh failed: ${err instanceof Error ? err.message : String(err)}`);
                 });
                 pollTimer = setInterval(() => {
-                    refreshStatus().catch((err) => {
+                    refreshStatusRef.current().catch((err) => {
                         logger.warn(`Status refresh failed: ${err instanceof Error ? err.message : String(err)}`);
                     });
                 }, POLL_INTERVAL_MS);
@@ -288,11 +314,15 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
                     return;
                 }
                 const reviewMode = reviewModeProp ?? config.loop.reviewMode ?? 'manual';
-                if (reviewMode !== 'manual' && reviewMode !== 'auto') {
-                    setError(`Invalid reviewMode '${reviewMode}'. Allowed values are 'manual' or 'auto'.`);
+                if (reviewMode !== 'manual' && reviewMode !== 'auto' && reviewMode !== 'merge') {
+                    setError(`Invalid reviewMode '${reviewMode}'. Allowed values are 'manual', 'auto', or 'merge'.`);
                     setIsStarting(false);
                     return;
                 }
+                // Clean up stale action files from previous runs
+                await cleanupActionFiles(featureName).catch((err) => {
+                    logger.warn(`Failed to clean up stale action files: ${err instanceof Error ? err.message : String(err)}`);
+                });
                 const logPath = getLoopLogPath(featureName);
                 const logFd = openSync(logPath, 'a');
                 let logFdClosed = false;
@@ -321,11 +351,11 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
                         child.kill('SIGINT');
                     }
                     pollTimer = setInterval(() => {
-                        refreshStatus().catch((err) => {
+                        refreshStatusRef.current().catch((err) => {
                             logger.warn(`Status refresh failed: ${err instanceof Error ? err.message : String(err)}`);
                         });
                     }, POLL_INTERVAL_MS);
-                    refreshStatus().catch((err) => {
+                    refreshStatusRef.current().catch((err) => {
                         logger.warn(`Status refresh failed: ${err instanceof Error ? err.message : String(err)}`);
                     });
                     child.on('error', (err) => {
@@ -415,7 +445,10 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
             if (pollTimer)
                 clearInterval(pollTimer);
         };
-    }, [featureName, projectRoot, refreshStatus, monitorOnly, sessionState.config]);
+        // Note: refreshStatusRef (not refreshStatus) is used inside to avoid re-spawning
+        // the child process when the callback identity changes due to actionRequest updates.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [featureName, projectRoot, monitorOnly, sessionState.config]);
     const totalTasks = tasks.tasksDone + tasks.tasksPending;
     const totalE2e = tasks.e2eDone + tasks.e2ePending;
     const totalAll = totalTasks + totalE2e;
@@ -429,11 +462,47 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
     // Tips text
     const tips = completionSummary
         ? 'Enter to return to shell'
-        : monitorOnly
-            ? 'Ctrl+C stop, Esc back'
-            : 'Ctrl+C stop, Esc background';
-    // Input element (only show Confirm when stopping)
-    const inputElement = showConfirm ? (_jsx(Confirm, { message: stopRequestedRef.current ? 'Stopping loop...' : 'Stop the feature loop?', onConfirm: handleConfirm, onCancel: () => setShowConfirm(false), initialValue: false })) : null;
+        : actionRequest
+            ? 'Select an option, Esc for default'
+            : monitorOnly
+                ? 'Ctrl+C stop, Esc back'
+                : 'Ctrl+C stop, Esc background';
+    // Action select handler — awaits write before clearing prompt
+    const handleActionSelect = useCallback(async (choiceId) => {
+        if (!actionRequest)
+            return;
+        try {
+            await writeActionReply(featureName, { id: actionRequest.id, choice: choiceId });
+            handledActionIdRef.current = actionRequest.id;
+            setActionRequest(null);
+        }
+        catch (err) {
+            logger.error(`Failed to write action reply: ${err instanceof Error ? err.message : String(err)}`);
+            setError(`Failed to send action reply. The loop may time out to the default.`);
+        }
+    }, [actionRequest, featureName]);
+    // Action cancel handler (Esc = use default) — awaits write before clearing
+    const handleActionCancel = useCallback(async () => {
+        if (!actionRequest)
+            return;
+        try {
+            await writeActionReply(featureName, { id: actionRequest.id, choice: actionRequest.default });
+            handledActionIdRef.current = actionRequest.id;
+            setActionRequest(null);
+        }
+        catch (err) {
+            logger.error(`Failed to write action reply (default): ${err instanceof Error ? err.message : String(err)}`);
+            setError(`Failed to send action reply. The loop may time out to the default.`);
+        }
+    }, [actionRequest, featureName]);
+    // Input element: completionSummary > showConfirm > actionRequest > null
+    const actionSelectOptions = actionRequest
+        ? actionRequest.choices.map((c) => ({ value: c.id, label: c.label }))
+        : null;
+    const actionInitialIndex = actionRequest
+        ? Math.max(0, actionRequest.choices.findIndex((c) => c.id === actionRequest.default))
+        : 0;
+    const inputElement = showConfirm ? (_jsx(Confirm, { message: stopRequestedRef.current ? 'Stopping loop...' : 'Stop the feature loop?', onConfirm: handleConfirm, onCancel: () => setShowConfirm(false), initialValue: false })) : !completionSummary && actionRequest && actionSelectOptions ? (_jsx(Select, { message: actionRequest.prompt, options: actionSelectOptions, onSelect: handleActionSelect, onCancel: handleActionCancel, initialIndex: actionInitialIndex })) : null;
     return (_jsx(AppShell, { header: header, tips: tips, isWorking: isRunning && !isStarting, workingStatus: `${phaseLine} \u2014 ${featureName}`, workingHint: monitorOnly ? 'esc to go back' : 'esc to background', input: inputElement, error: error, footerStatus: {
             action: 'Run Loop',
             phase: phaseLine,

package/dist/tui/utils/action-inbox.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Action inbox helpers for file-based IPC between loop processes and the TUI.
+ *
+ * The loop writes an action request file; the TUI reads it and writes a reply.
+ * Both files live in /tmp with the conventional ralph-loop-<feature> prefix.
+ */
+export interface ActionChoice {
+    id: string;
+    label: string;
+}
+export interface ActionRequest {
+    id: string;
+    prompt: string;
+    choices: ActionChoice[];
+    default: string;
+}
+export interface ActionReply {
+    id: string;
+    choice: string;
+}
+/**
+ * Return the path to the action request file for a feature.
+ */
+export declare function getActionRequestPath(feature: string): string;
+/**
+ * Return the path to the action reply file for a feature.
+ */
+export declare function getActionReplyPath(feature: string): string;
+/**
+ * Read and validate the action request file for a feature.
+ *
+ * Returns null if the file does not exist, cannot be parsed, or is missing
+ * required fields. Logs a warning on parse errors.
+ */
+export declare function readActionRequest(feature: string): ActionRequest | null;
+/**
+ * Write an action reply file atomically (write to .tmp then rename).
+ */
+export declare function writeActionReply(feature: string, reply: ActionReply): Promise<void>;
+/**
+ * Remove both action request and reply files. Only suppresses ENOENT (file not found).
+ */
+export declare function cleanupActionFiles(feature: string): Promise<void>;

package/dist/tui/utils/action-inbox.js

@@ -0,0 +1,109 @@
+/**
+ * Action inbox helpers for file-based IPC between loop processes and the TUI.
+ *
+ * The loop writes an action request file; the TUI reads it and writes a reply.
+ * Both files live in /tmp with the conventional ralph-loop-<feature> prefix.
+ */
+import { rename, unlink, writeFile } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { logger } from '../../utils/logger.js';
+const FEATURE_REGEX = /^[a-zA-Z0-9_-]+$/;
+function validateFeature(feature) {
+    if (!FEATURE_REGEX.test(feature)) {
+        throw new Error(`Invalid feature name: "${feature}". Must contain only letters, numbers, hyphens, and underscores.`);
+    }
+}
+/**
+ * Return the path to the action request file for a feature.
+ */
+export function getActionRequestPath(feature) {
+    validateFeature(feature);
+    return `/tmp/ralph-loop-${feature}.action.json`;
+}
+/**
+ * Return the path to the action reply file for a feature.
+ */
+export function getActionReplyPath(feature) {
+    validateFeature(feature);
+    return `/tmp/ralph-loop-${feature}.action.reply.json`;
+}
+/**
+ * Read and validate the action request file for a feature.
+ *
+ * Returns null if the file does not exist, cannot be parsed, or is missing
+ * required fields. Logs a warning on parse errors.
+ */
+export function readActionRequest(feature) {
+    validateFeature(feature);
+    const path = getActionRequestPath(feature);
+    if (!existsSync(path)) {
+        return null;
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch (err) {
+        logger.warn(`Failed to read action request file: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        logger.warn(`Failed to parse action request JSON: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        typeof parsed.id !== 'string' ||
+        typeof parsed.prompt !== 'string' ||
+        !Array.isArray(parsed.choices) ||
+        parsed.choices.length === 0 ||
+        typeof parsed.default !== 'string') {
+        logger.warn('Action request file is missing required fields (id, prompt, choices, default) or choices is empty');
+        return null;
+    }
+    const record = parsed;
+    const choices = record.choices;
+    for (const choice of choices) {
+        if (typeof choice !== 'object' ||
+            choice === null ||
+            typeof choice.id !== 'string' ||
+            typeof choice.label !== 'string') {
+            logger.warn('Action request choices contain invalid entries (each must have id and label)');
+            return null;
+        }
+    }
+    return {
+        id: record.id,
+        prompt: record.prompt,
+        choices: choices,
+        default: record.default,
+    };
+}
+/**
+ * Write an action reply file atomically (write to .tmp then rename).
+ */
+export async function writeActionReply(feature, reply) {
+    validateFeature(feature);
+    const replyPath = getActionReplyPath(feature);
+    const tmpPath = `${replyPath}.tmp`;
+    const json = JSON.stringify(reply);
+    await writeFile(tmpPath, json, 'utf-8');
+    await rename(tmpPath, replyPath);
+}
+/**
+ * Remove both action request and reply files. Only suppresses ENOENT (file not found).
+ */
+export async function cleanupActionFiles(feature) {
+    validateFeature(feature);
+    const requestPath = getActionRequestPath(feature);
+    const replyPath = getActionReplyPath(feature);
+    const safeUnlink = (path) => unlink(path).catch((err) => {
+        if (err.code !== 'ENOENT')
+            throw err;
+    });
+    await Promise.all([safeUnlink(requestPath), safeUnlink(replyPath)]);
+}

package/dist/tui/utils/polishGoal.d.ts

@@ -0,0 +1,37 @@
+/**
+ * polishGoal — Pure utility functions for generating a polished, imperative
+ * single-sentence Goal line in the spec completion summary.
+ *
+ * No AI calls, no side-effects. Deterministic string transformations only.
+ */
+/**
+ * selectGoalSource — Choose the best source for the goal line from a
+ * structured set of candidates, applying the spec's 3-tier fallback chain:
+ *   1. AI recap (if non-empty/non-whitespace)
+ *   2. Key decisions (if non-empty/non-whitespace after normalisation)
+ *   3. User request (fallback)
+ *
+ * For `keyDecisions`, bullet prefixes are stripped and fragments joined with `; `.
+ */
+export declare function selectGoalSource(opts: {
+    aiRecap: string;
+    keyDecisions: string | string[];
+    userRequest: string;
+}): {
+    source: 'ai' | 'decisions' | 'user';
+    text: string;
+};
+/**
+ * polishGoalSentence — Transform any goal source text into a polished,
+ * imperative, single-sentence string ending with a period.
+ *
+ * Steps applied (all deterministic):
+ *  1. Whitespace normalization
+ *  2. Strip trailing ellipses
+ *  3. Remove leading framing phrases ("I want to …", "We will …", etc.)
+ *  4. Single-sentence enforcement (take first sentence)
+ *  5. Imperative verb enforcement (prepend "Implement " if needed)
+ *  6. Capitalise first letter
+ *  7. Ensure exactly one trailing period
+ */
+export declare function polishGoalSentence(text: string): string;

package/dist/tui/utils/polishGoal.js

@@ -0,0 +1,170 @@
+/**
+ * polishGoal — Pure utility functions for generating a polished, imperative
+ * single-sentence Goal line in the spec completion summary.
+ *
+ * No AI calls, no side-effects. Deterministic string transformations only.
+ */
+/** Allowed imperative verbs that may begin a polished goal sentence. */
+const IMPERATIVE_VERBS = [
+    'Implement',
+    'Add',
+    'Improve',
+    'Fix',
+    'Refactor',
+    'Support',
+    'Enable',
+    'Create',
+    'Update',
+    'Build',
+    'Extend',
+    'Migrate',
+    'Remove',
+    'Replace',
+    'Integrate',
+    'Define',
+    'Achieve',
+    'Allow',
+    'Complete',
+    'Configure',
+    'Deploy',
+    'Design',
+    'Ensure',
+    'Generate',
+    'Handle',
+    'Introduce',
+    'Make',
+    'Optimize',
+    'Provide',
+    'Redesign',
+    'Restructure',
+    'Set',
+    'Show',
+    'Use',
+];
+const IMPERATIVE_VERB_PATTERN = new RegExp(`^(${IMPERATIVE_VERBS.join('|')})\\b`, 'i');
+/** Leading framing-phrase patterns to strip/rewrite, each returning a cleaned fragment. */
+const FRAMING_PATTERNS = [
+    [/^i want to\s*/i, ''],
+    [/^i'd like to\s*/i, ''],
+    [/^i would like to\s*/i, ''],
+    [/^we will\s*/i, ''],
+    [/^we want to\s*/i, ''],
+    [/^we need to\s*/i, ''],
+    [/^you're\s+\w+ing\s+to\s*/i, ''],
+    [/^you'd like to\s*/i, ''],
+    [/^you want to\s*/i, ''],
+    [/^you need to\s*/i, ''],
+    [/^this spec covers\s*/i, ''],
+    [/^this spec describes\s*/i, ''],
+    [/^the goal is to\s*/i, ''],
+    // Handles normalizeRecap output like "To build …" (stripped "you want" prefix)
+    [/^to\s+/i, ''],
+];
+/** Strip bullet prefixes (`-`, `*`, `1.`, `•`) from a single line. */
+function stripBulletPrefix(line) {
+    return line.replace(/^(\s*[-*•]|\s*\d+[.)]\s*)\s*/, '').trim();
+}
+/** Collapse multi-space/newline whitespace to a single space and trim. */
+function normalizeWhitespace(text) {
+    return text.replace(/[\r\n\t]+/g, ' ').replace(/\s{2,}/g, ' ').trim();
+}
+/** Return true if this part looks like an abbreviation fragment (e.g. "e.g", "i.e", "vs"). */
+function looksLikeAbbreviation(fragment) {
+    return /^(e\.g|i\.e|etc|vs|mr|mrs|dr|prof|no|vol|fig|ch|approx|est)$/i.test(fragment.trim());
+}
+/**
+ * Enforce single-sentence: split conservatively on `. ` boundaries, skipping
+ * abbreviation-like fragments, then return only the first sentence.
+ */
+function toOneSentence(text) {
+    // Split on ". " followed by an uppercase letter — conservative heuristic
+    const parts = text.split(/(?<=\b\w{3,})\. (?=[A-Z])/);
+    if (parts.length <= 1)
+        return text;
+    // Take first part only
+    const first = parts[0];
+    // Guard against abbreviations causing false splits
+    if (looksLikeAbbreviation(first))
+        return text;
+    return first;
+}
+/**
+ * selectGoalSource — Choose the best source for the goal line from a
+ * structured set of candidates, applying the spec's 3-tier fallback chain:
+ *   1. AI recap (if non-empty/non-whitespace)
+ *   2. Key decisions (if non-empty/non-whitespace after normalisation)
+ *   3. User request (fallback)
+ *
+ * For `keyDecisions`, bullet prefixes are stripped and fragments joined with `; `.
+ */
+export function selectGoalSource(opts) {
+    const { aiRecap, keyDecisions, userRequest } = opts;
+    // 1. AI recap
+    const normalizedAi = normalizeWhitespace(aiRecap);
+    if (normalizedAi.length > 0) {
+        return { source: 'ai', text: normalizedAi };
+    }
+    // 2. Key decisions
+    const decisionsArr = Array.isArray(keyDecisions)
+        ? keyDecisions
+        : keyDecisions
+            ? [keyDecisions]
+            : [];
+    const cleanedDecisions = decisionsArr
+        .map((d) => stripBulletPrefix(normalizeWhitespace(d)))
+        .filter((d) => d.length > 0);
+    if (cleanedDecisions.length > 0) {
+        const joined = cleanedDecisions.join('; ');
+        return { source: 'decisions', text: joined };
+    }
+    // 3. User request
+    return { source: 'user', text: normalizeWhitespace(userRequest) };
+}
+/**
+ * polishGoalSentence — Transform any goal source text into a polished,
+ * imperative, single-sentence string ending with a period.
+ *
+ * Steps applied (all deterministic):
+ *  1. Whitespace normalization
+ *  2. Strip trailing ellipses
+ *  3. Remove leading framing phrases ("I want to …", "We will …", etc.)
+ *  4. Single-sentence enforcement (take first sentence)
+ *  5. Imperative verb enforcement (prepend "Implement " if needed)
+ *  6. Capitalise first letter
+ *  7. Ensure exactly one trailing period
+ */
+export function polishGoalSentence(text) {
+    if (!text || text.trim().length === 0) {
+        return 'Implement the requested feature.';
+    }
+    // 1. Whitespace normalization
+    let result = normalizeWhitespace(text);
+    // 2. Strip trailing ellipses
+    result = result.replace(/\.{2,}$/, '').replace(/…$/, '').trim();
+    // 3. Remove leading framing phrases iteratively (apply first matching pattern)
+    for (const [pattern, replacement] of FRAMING_PATTERNS) {
+        if (pattern.test(result)) {
+            result = result.replace(pattern, replacement).trim();
+            break;
+        }
+    }
+    // Guard: if stripping left nothing (e.g. "I want to" with no continuation)
+    if (result.length === 0) {
+        return 'Implement the requested feature.';
+    }
+    // 4. Single-sentence enforcement
+    result = toOneSentence(result);
+    // Strip any trailing sentence-ending punctuation before we add our own
+    result = result.replace(/[.!?]+$/, '').trim();
+    // 5. Imperative verb enforcement
+    if (!IMPERATIVE_VERB_PATTERN.test(result)) {
+        // Lowercase first char before prepending to avoid "Implement The thing"
+        result = result.charAt(0).toLowerCase() + result.slice(1);
+        result = `Implement ${result}`;
+    }
+    // 6. Capitalize first letter
+    result = result.charAt(0).toUpperCase() + result.slice(1);
+    // 7. Ensure exactly one trailing period
+    result = `${result}.`;
+    return result;
+}

package/dist/utils/config.d.ts

@@ -48,7 +48,7 @@ export interface LoopConfig {
     maxE2eAttempts: number;
     defaultModel: string;
     planningModel: string;
-    reviewMode: 'manual' | 'auto';
+    reviewMode: 'manual' | 'auto' | 'merge';
 }
 /**
  * Full ralph.config.cjs structure

package/dist/utils/fuzzy-match.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns true if all characters in `query` appear in `target` in order
+ * (case-insensitive). An empty query always matches.
+ */
+export declare function fuzzyMatch(query: string, target: string): boolean;

package/dist/utils/fuzzy-match.js

@@ -0,0 +1,16 @@
+/**
+ * Returns true if all characters in `query` appear in `target` in order
+ * (case-insensitive). An empty query always matches.
+ */
+export function fuzzyMatch(query, target) {
+    if (query.length === 0)
+        return true;
+    const q = query.toLowerCase();
+    const t = target.toLowerCase();
+    let qi = 0;
+    for (let ti = 0; ti < t.length && qi < q.length; ti++) {
+        if (t[ti] === q[qi])
+            qi++;
+    }
+    return qi === q.length;
+}

package/dist/utils/spec-names.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reads top-level .md files from the given directory and returns their names
+ * without the .md extension, sorted alphabetically.
+ * Returns an empty array if the directory does not exist or is unreadable.
+ */
+export declare function listSpecNames(specsDir: string): Promise<string[]>;

package/dist/utils/spec-names.js

@@ -0,0 +1,23 @@
+import { readdir } from 'node:fs/promises';
+import { logger } from './logger.js';
+/**
+ * Reads top-level .md files from the given directory and returns their names
+ * without the .md extension, sorted alphabetically.
+ * Returns an empty array if the directory does not exist or is unreadable.
+ */
+export async function listSpecNames(specsDir) {
+    let entries;
+    try {
+        entries = await readdir(specsDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code !== 'ENOENT') {
+            logger.debug(`Failed to list spec names from ${specsDir}: ${err.message}`);
+        }
+        return [];
+    }
+    return entries
+        .filter((e) => e.isFile() && e.name.endsWith('.md'))
+        .map((e) => e.name.slice(0, -3))
+        .sort();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiggum-cli",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "AI-powered feature development loop CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -26,11 +26,16 @@
   },
   "keywords": [
     "cli",
-    "ai",
-    "development",
-    "automation",
+    "ai-agent",
+    "autonomous-coding",
+    "ralph-loop",
+    "spec-generation",
+    "claude-code",
+    "codex",
+    "ai-coding",
     "feature-loop",
     "code-generation",
+    "developer-tools",
     "tech-stack-detection"
   ],
   "repository": {

package/src/templates/config/ralph.config.cjs.tmpl

@@ -34,6 +34,6 @@ module.exports = {
     maxE2eAttempts: 5,
     defaultModel: 'sonnet',
     planningModel: 'opus',
-    reviewMode: 'manual', // 'manual' = stop at PR, 'auto' = review + auto-merge
+    reviewMode: 'manual', // 'manual' = stop at PR, 'auto' = review (no merge), 'merge' = review + auto-merge
   },
 };