@boopkit/cli 0.1.0

package/dist/commands/loop.js

@@ -0,0 +1,765 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPlanningPrompt = buildPlanningPrompt;
+exports.planWork = planWork;
+exports.findFallbackFeature = findFallbackFeature;
+exports.extractFeatureId = extractFeatureId;
+exports.isUsageLimitText = isUsageLimitText;
+exports.isStandaloneUsageLimitMessage = isStandaloneUsageLimitMessage;
+exports.isIssueInScope = isIssueInScope;
+exports.runLoop = runLoop;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
+function buildPlanningPrompt(workContent, flowContent, prefix) {
+    let prompt = `You are setting up work for a development project.
+
+## Work Specification
+${workContent}
+
+## Workflow Process
+${flowContent}
+
+## Instructions
+1. Read the work specification carefully
+2. Create a feature issue: \`bd create "<title>" -t feature -d "<description>"\`
+   - Derive the title from the work specification
+   - Include breadcrumbs in the description (links to the work file, relevant specs, skills, and code)
+3. Follow the workflow process to create child issues under this feature
+   (use \`--parent <feature-id>\` so they are children of the feature)
+4. Review all created issues: ensure each has breadcrumbs, then set
+   appropriate priorities and blocking deps between tasks
+
+When finished, output exactly one line:
+FEATURE_ID=<the-feature-issue-id>`;
+    if (prefix) {
+        prompt += `\n\nNaming hint: Use \`${prefix}\` as a naming hint for the feature title.`;
+    }
+    return prompt;
+}
+async function planWork(opts) {
+    const workContent = fs.readFileSync(opts.workPath, 'utf8');
+    const flowContent = fs.readFileSync(opts.flowPath, 'utf8');
+    const prompt = buildPlanningPrompt(workContent, flowContent, opts.prefix);
+    const sessionId = (0, crypto_1.randomUUID)();
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').substring(0, 19);
+    const logFile = path.join(opts.logDir, `_planning_${opts.prefix}_${timestamp}.log`);
+    const readableLogFile = path.join(opts.logDir, `_planning_${opts.prefix}_${timestamp}.readable.log`);
+    // Write readable log header
+    fs.writeFileSync(readableLogFile, `=== Planning Session ===\nSession: ${sessionId}\nStarted: ${new Date().toISOString()}\n\n`);
+    console.log(`\x1b[32m[bd-loop]\x1b[0m 📋 Starting planning phase...`);
+    console.log(`\x1b[32m[bd-loop]\x1b[0m   Work: ${opts.workPath}`);
+    console.log(`\x1b[32m[bd-loop]\x1b[0m   Flow: ${opts.flowPath}`);
+    console.log(`\x1b[32m[bd-loop]\x1b[0m   Log:  ${logFile}`);
+    const runner = opts.runClaudeFn || runClaude;
+    const result = await runner(prompt, {
+        budget: opts.budget,
+        model: opts.model,
+        skipPerms: opts.skipPerms,
+        bare: opts.bare,
+        sessionId,
+    }, logFile, readableLogFile);
+    if (result.exitCode !== 0 && result.limitHit) {
+        console.error('\x1b[31m[bd-loop]\x1b[0m Planning phase hit usage limit');
+        return { featureId: null, costUsd: null };
+    }
+    if (result.exitCode !== 0) {
+        console.error(`\x1b[31m[bd-loop]\x1b[0m Planning phase exited with code ${result.exitCode}`);
+        console.error(`\x1b[31m[bd-loop]\x1b[0m Check log: ${logFile}`);
+        return { featureId: null, costUsd: null };
+    }
+    // Read log file and parse assistant text + cost
+    let accumulated = '';
+    let costUsd = null;
+    try {
+        const logContent = fs.readFileSync(logFile, 'utf8');
+        const lines = logContent.split('\n').filter(Boolean);
+        for (const line of lines) {
+            try {
+                const msg = JSON.parse(line);
+                if (msg.type === 'assistant') {
+                    const texts = (msg.message?.content || [])
+                        .filter((c) => c.type === 'text')
+                        .map((c) => c.text);
+                    accumulated += texts.join('');
+                }
+                else if (msg.type === 'result' && typeof msg.total_cost_usd === 'number') {
+                    costUsd = msg.total_cost_usd;
+                }
+            }
+            catch (e) {
+                console.warn(`\x1b[33m[bd-loop]\x1b[0m Failed to parse planning log line: ${e.message}`);
+            }
+        }
+    }
+    catch {
+        console.error(`\x1b[31m[bd-loop]\x1b[0m Failed to read planning log: ${logFile}`);
+        return { featureId: null, costUsd: null };
+    }
+    // Primary extraction
+    const featureId = extractFeatureId(accumulated);
+    if (featureId) {
+        return { featureId, costUsd };
+    }
+    // Fallback: query bd list for recently created features
+    console.log('\x1b[33m[bd-loop]\x1b[0m No FEATURE_ID in output, trying fallback query...');
+    try {
+        const execFn = opts.execSyncFn || ((cmd, o) => (0, child_process_1.execSync)(cmd, o));
+        const raw = execFn('bd list --json --type feature 2>/dev/null', { encoding: 'utf8' });
+        const features = JSON.parse(raw);
+        const fallbackId = findFallbackFeature(features, workContent, opts.workPath);
+        if (fallbackId) {
+            console.log(`\x1b[32m[bd-loop]\x1b[0m Fallback found feature: ${fallbackId}`);
+            return { featureId: fallbackId, costUsd };
+        }
+    }
+    catch (e) {
+        console.warn(`\x1b[33m[bd-loop]\x1b[0m Fallback feature query failed: ${e.message}`);
+    }
+    console.error(`\x1b[31m[bd-loop]\x1b[0m Planning phase failed to produce a feature ID`);
+    console.error(`\x1b[31m[bd-loop]\x1b[0m Check planning log: ${logFile}`);
+    return { featureId: null, costUsd };
+}
+function findFallbackFeature(features, workContent, workPath) {
+    const fiveMinAgo = new Date(Date.now() - 5 * 60 * 1000).toISOString();
+    // Extract keywords from work file H1 heading or filename
+    const h1Match = workContent.match(/^#\s+(.+)$/m);
+    const keywords = h1Match
+        ? h1Match[1].toLowerCase().split(/\s+/).filter((w) => w.length > 3).slice(0, 3)
+        : [path.basename(workPath, path.extname(workPath)).toLowerCase()];
+    const match = features.find((f) => {
+        if (!f.created_at || f.created_at < fiveMinAgo)
+            return false;
+        const title = (f.title || '').toLowerCase();
+        return keywords.some((kw) => title.includes(kw));
+    });
+    return match?.id ?? null;
+}
+function extractFeatureId(text) {
+    const match = text.match(/FEATURE_ID=([\w.-]+)/);
+    return match ? match[1] : null;
+}
+function isUsageLimitText(text) {
+    // Normalize all whitespace (including NBSP) so provider text variants still match.
+    const normalized = text.toLowerCase().replace(/\s+/gu, ' ').trim();
+    return (normalized.includes("you've hit your limit") ||
+        normalized.includes('usage limit') ||
+        normalized.includes('rate limit') ||
+        normalized.includes('quota') ||
+        normalized.includes('credit balance is too low') ||
+        normalized.includes('credit balance too low') ||
+        /credit\s+balance\s+(?:is\s+)?too\s+low/u.test(normalized) ||
+        normalized.includes('insufficient credit') ||
+        normalized.includes('insufficient funds'));
+}
+function isStandaloneUsageLimitMessage(text) {
+    const trimmed = text.trim();
+    if (!trimmed || trimmed.includes('\n')) {
+        return false;
+    }
+    // Real provider limit responses are usually short single-line messages.
+    if (trimmed.length > 200) {
+        return false;
+    }
+    const normalized = trimmed.toLowerCase().replace(/\s+/gu, ' ');
+    return (/^credit\s+balance\s+(?:is\s+)?too\s+low\b/u.test(normalized) ||
+        /^insufficient\s+credit\b/u.test(normalized) ||
+        /^insufficient\s+funds\b/u.test(normalized) ||
+        /^you'?ve\s+hit\s+your\s+limit\b/u.test(normalized) ||
+        /^rate\s+limit\s+reached\b/u.test(normalized) ||
+        /^error:\s*usage\s+limit\s+exceeded\b/u.test(normalized) ||
+        /^quota\s+exceeded\b/u.test(normalized));
+}
+function findClaudeBinary() {
+    try {
+        return (0, child_process_1.execSync)('command -v claude', { encoding: 'utf8' }).trim();
+    }
+    catch {
+        // Check common locations
+        const candidates = [
+            path.join(process.env.HOME || '', '.nvm/versions/node'),
+            path.join(process.env.HOME || '', '.local/bin/claude'),
+            '/usr/local/bin/claude',
+        ];
+        for (const candidate of candidates) {
+            if (candidate.includes('.nvm')) {
+                // Glob for nvm versions
+                try {
+                    const result = (0, child_process_1.execSync)(`ls ${candidate}/*/bin/claude 2>/dev/null | head -1`, {
+                        encoding: 'utf8',
+                    }).trim();
+                    if (result)
+                        return result;
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        return null;
+    }
+}
+function findNextIssue(prefix, includeFeatures) {
+    const matching = getMatchingReadyIssues(prefix, includeFeatures);
+    return matching.length > 0 ? matching[0].id : null;
+}
+function getIssueParentId(id) {
+    try {
+        const raw = (0, child_process_1.execSync)(`bd show ${id} --json 2>/dev/null`, { encoding: 'utf8' });
+        const data = JSON.parse(raw);
+        const issue = data[0] || data;
+        return issue.parent || null;
+    }
+    catch {
+        return null;
+    }
+}
+function isIssueInScope(issue, prefix, getParentById) {
+    if (issue.id.startsWith(prefix)) {
+        return true;
+    }
+    const seen = new Set();
+    let ancestor = issue.parent || null;
+    while (ancestor && !seen.has(ancestor)) {
+        if (ancestor.startsWith(prefix)) {
+            return true;
+        }
+        seen.add(ancestor);
+        ancestor = getParentById(ancestor);
+    }
+    return false;
+}
+function getMatchingReadyIssues(prefix, includeFeatures) {
+    try {
+        const raw = (0, child_process_1.execSync)('bd ready --json -n 20 2>/dev/null', { encoding: 'utf8' });
+        const issues = JSON.parse(raw);
+        const typeFilter = includeFeatures
+            ? (i) => i.issue_type !== 'epic'
+            : (i) => i.issue_type !== 'epic' && i.issue_type !== 'feature';
+        const parentCache = new Map();
+        for (const issue of issues) {
+            parentCache.set(issue.id, issue.parent || null);
+        }
+        const getParentById = (id) => {
+            if (parentCache.has(id)) {
+                return parentCache.get(id) ?? null;
+            }
+            const parent = getIssueParentId(id);
+            parentCache.set(id, parent);
+            return parent;
+        };
+        return issues
+            .filter(typeFilter)
+            .filter((issue) => isIssueInScope(issue, prefix, getParentById));
+    }
+    catch {
+        return [];
+    }
+}
+function getIssueInfo(id) {
+    try {
+        const raw = (0, child_process_1.execSync)(`bd show ${id} --json 2>/dev/null`, { encoding: 'utf8' });
+        const data = JSON.parse(raw);
+        const issue = data[0] || data;
+        return {
+            id,
+            title: issue.title || 'unknown',
+            priority: issue.priority ?? '?',
+            issue_type: issue.issue_type || 'task',
+            description: issue.description || 'No description',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isIssueClosed(id) {
+    try {
+        const raw = (0, child_process_1.execSync)(`bd show ${id} --json 2>/dev/null`, { encoding: 'utf8' });
+        const data = JSON.parse(raw);
+        const status = (data[0] || data).status || 'unknown';
+        return status === 'closed';
+    }
+    catch {
+        return false;
+    }
+}
+function buildPrompt(issue) {
+    return `You are working on issue ${issue.id} in the boop project.
+
+## Issue: ${issue.title}
+Type: ${issue.issue_type} | Priority: ${issue.priority}
+
+## Description
+${issue.description}
+
+## Instructions
+1. Read AGENTS.md for project orientation
+2. Claim the issue: bd update ${issue.id} --claim
+3. Read relevant skills from skills/index.md before making changes
+4. Implement the changes following TDD-Lite: observe, implement, verify
+5. Run tests if applicable: npm test
+6. Commit your changes with a message referencing ${issue.id}
+7. Close the issue: bd close ${issue.id} --reason "<what you did>"
+8. Push: git pull --rebase && git push
+
+IMPORTANT: Complete the FULL workflow — implement, test, commit, close, and push.
+Do NOT pause for review. Work autonomously through to completion.
+
+If you discover additional issues during your work, file them with:
+  bd create "Title" -d "description" --deps discovered-from:${issue.id}`;
+}
+const RESUME_PROMPT = `Approved. Continue working on this issue. Complete the full workflow:
+- Finish any remaining implementation
+- Run tests to verify
+- Commit changes referencing the issue ID
+- Close the issue with bd close
+- Push with: git pull --rebase && git push
+
+Do NOT pause for review. Complete everything now.`;
+function runClaude(prompt, opts, logFile, readableLogFile) {
+    return new Promise((resolve) => {
+        const args = [
+            '-p',
+            '--max-budget-usd', opts.budget,
+            '--output-format', 'stream-json',
+            '--verbose',
+        ];
+        if (opts.bare)
+            args.push('--bare');
+        if (opts.skipPerms)
+            args.push('--dangerously-skip-permissions');
+        if (opts.model)
+            args.push('--model', opts.model);
+        if (opts.resume) {
+            args.push('--resume', opts.sessionId);
+        }
+        else {
+            args.push('--session-id', opts.sessionId);
+        }
+        const claudeBin = findClaudeBinary();
+        if (!claudeBin) {
+            console.error('\x1b[31m[bd-loop]\x1b[0m claude binary not found');
+            resolve({ exitCode: 1, limitHit: false });
+            return;
+        }
+        const logStream = fs.createWriteStream(logFile, { flags: 'a' });
+        const readableStream = readableLogFile
+            ? fs.createWriteStream(readableLogFile, { flags: 'a' })
+            : null;
+        const child = (0, child_process_1.spawn)(claudeBin, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        let limitHit = false;
+        child.stdin.write(prompt);
+        child.stdin.end();
+        child.stdout.on('data', (chunk) => {
+            logStream.write(chunk);
+            const lines = chunk.toString().split('\n').filter(Boolean);
+            for (const line of lines) {
+                try {
+                    const msg = JSON.parse(line);
+                    if (msg.type === 'assistant') {
+                        const texts = (msg.message?.content || [])
+                            .filter((c) => c.type === 'text')
+                            .map((c) => c.text);
+                        if (texts.length > 0) {
+                            const textBlob = texts.join('');
+                            if (isStandaloneUsageLimitMessage(textBlob)) {
+                                limitHit = true;
+                            }
+                            const first = textBlob.split('\n')[0].substring(0, 120);
+                            console.log(`\x1b[32m[bd-loop]\x1b[0m     💬 ${first}`);
+                            if (readableStream) {
+                                readableStream.write(`[text] ${textBlob}\n\n`);
+                            }
+                        }
+                        const tools = (msg.message?.content || [])
+                            .filter((c) => c.type === 'tool_use')
+                            .map((c) => `${c.name} ${JSON.stringify(c.input).substring(0, 80)}`);
+                        for (const t of tools) {
+                            console.log(`\x1b[32m[bd-loop]\x1b[0m     🔧 ${t}`);
+                            if (readableStream) {
+                                readableStream.write(`[tool] ${t}\n`);
+                            }
+                        }
+                    }
+                    else if (msg.type === 'result') {
+                        const resultText = typeof msg.result === 'string' ? msg.result : '';
+                        if ((msg.is_error || msg.subtype === 'error') && isUsageLimitText(resultText)) {
+                            limitHit = true;
+                        }
+                        const cost = msg.total_cost_usd || '?';
+                        const dur = Math.round((msg.duration_ms || 0) / 1000);
+                        const turns = msg.num_turns || '?';
+                        console.log(`\x1b[32m[bd-loop]\x1b[0m     📊 ${turns} turns, $${cost}, ${dur}s`);
+                        if (readableStream) {
+                            readableStream.write(`\n=== Result ===\nTurns: ${turns} | Cost: $${cost} | Duration: ${dur}s\n\n${resultText}\n`);
+                        }
+                    }
+                }
+                catch {
+                    if (isStandaloneUsageLimitMessage(line)) {
+                        limitHit = true;
+                    }
+                }
+            }
+        });
+        child.stderr.on('data', (chunk) => {
+            logStream.write(chunk);
+            if (isStandaloneUsageLimitMessage(chunk.toString())) {
+                limitHit = true;
+            }
+        });
+        child.on('close', (code) => {
+            logStream.end();
+            if (readableStream)
+                readableStream.end();
+            resolve({ exitCode: code ?? 1, limitHit });
+        });
+    });
+}
+async function processIssue(issue, opts) {
+    const sessionId = (0, crypto_1.randomUUID)();
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').substring(0, 19);
+    const logFile = path.join(opts.logDir, `${issue.id}_${timestamp}.log`);
+    const readableLogFile = path.join(opts.logDir, `${issue.id}_${timestamp}.readable.log`);
+    // Write readable log header
+    fs.writeFileSync(readableLogFile, `=== ${issue.id}: ${issue.title} ===\nSession: ${sessionId}\nStarted: ${new Date().toISOString()}\n\n`);
+    console.log(`\x1b[32m[bd-loop]\x1b[0m ━━━ \x1b[34m${issue.id}\x1b[0m (P${issue.priority} ${issue.issue_type}) ━━━`);
+    console.log(`\x1b[32m[bd-loop]\x1b[0m   ${issue.title}`);
+    let originalBranch;
+    if (!opts.noBranch && opts.perIssueBranch) {
+        const branchName = `fix/${issue.id}`;
+        originalBranch = (0, child_process_1.execSync)('git branch --show-current', { encoding: 'utf8' }).trim();
+        console.log(`\x1b[32m[bd-loop]\x1b[0m   Creating branch: ${branchName}`);
+        try {
+            (0, child_process_1.execSync)(`git checkout -b ${branchName} 2>/dev/null`, { encoding: 'utf8' });
+        }
+        catch {
+            try {
+                (0, child_process_1.execSync)(`git checkout ${branchName} 2>/dev/null`, { encoding: 'utf8' });
+                console.log(`\x1b[33m[bd-loop]\x1b[0m   Branch ${branchName} exists, checked out`);
+            }
+            catch {
+                console.error(`\x1b[31m[bd-loop]\x1b[0m   Failed to create/checkout branch`);
+                return { issueId: issue.id, closed: false, resumes: 0, logFile, limitHit: false };
+            }
+        }
+    }
+    // Initial run
+    const prompt = buildPrompt(issue);
+    console.log(`\x1b[32m[bd-loop]\x1b[0m   🚀 Starting Claude session (budget: $${opts.budget}, session: ${sessionId.substring(0, 8)}...)`);
+    const initialRun = await runClaude(prompt, {
+        budget: opts.budget,
+        model: opts.model,
+        skipPerms: opts.skipPerms,
+        bare: opts.bare,
+        sessionId,
+    }, logFile, readableLogFile);
+    let anyLimitHit = initialRun.limitHit;
+    if (initialRun.limitHit) {
+        console.error('\x1b[31m[bd-loop]\x1b[0m   Claude usage limit reached; stopping retries for this issue');
+    }
+    // Resume loop
+    let resumeCount = 0;
+    while (resumeCount < opts.resumeLimit && !initialRun.limitHit) {
+        if (isIssueClosed(issue.id)) {
+            console.log(`\x1b[32m[bd-loop]\x1b[0m   ✅ Issue ${issue.id} closed successfully`);
+            break;
+        }
+        resumeCount++;
+        console.log(`\x1b[33m[bd-loop]\x1b[0m   Issue not yet closed — resuming session (attempt ${resumeCount}/${opts.resumeLimit})`);
+        console.log(`\x1b[32m[bd-loop]\x1b[0m   🔄 Resuming session ${sessionId.substring(0, 8)}...`);
+        fs.appendFileSync(readableLogFile, `\n=== Resume attempt ${resumeCount} ===\nTime: ${new Date().toISOString()}\n\n`);
+        const resumeRun = await runClaude(RESUME_PROMPT, {
+            budget: opts.budget,
+            model: opts.model,
+            skipPerms: opts.skipPerms,
+            bare: opts.bare,
+            sessionId,
+            resume: true,
+        }, logFile, readableLogFile);
+        if (resumeRun.limitHit) {
+            anyLimitHit = true;
+            console.error('\x1b[31m[bd-loop]\x1b[0m   Claude usage limit reached during resume; stopping retries for this issue');
+            break;
+        }
+    }
+    const closed = isIssueClosed(issue.id);
+    if (closed) {
+        console.log(`\x1b[32m[bd-loop]\x1b[0m   ✅ Done: ${issue.id}`);
+    }
+    else {
+        console.error(`\x1b[31m[bd-loop]\x1b[0m   ⚠️  Issue ${issue.id} not closed after ${opts.resumeLimit} resume attempts`);
+        console.error(`\x1b[31m[bd-loop]\x1b[0m   Check log: ${logFile}`);
+    }
+    if (originalBranch) {
+        try {
+            (0, child_process_1.execSync)(`git checkout ${originalBranch} 2>/dev/null`);
+        }
+        catch {
+            // Best effort
+        }
+    }
+    return { issueId: issue.id, closed, resumes: resumeCount, logFile, limitHit: anyLimitHit };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function runLoop(options) {
+    let prefix = options.prefix;
+    const work = options.work;
+    const flow = options.flow;
+    // Validate: need either --prefix OR both --work and --flow
+    if (!prefix && !work && !flow) {
+        console.error('\x1b[31mERR\x1b[0m Either --prefix or both --work and --flow are required');
+        console.error('Usage: boop loop --prefix <issue-prefix> [--run] [--max N] [--budget N.NN]');
+        console.error('       boop loop --work <spec-file> --flow <workflow-file> [--run]');
+        process.exitCode = 1;
+        return;
+    }
+    // --work and --flow must be used together
+    if ((work && !flow) || (!work && flow)) {
+        console.error('\x1b[31mERR\x1b[0m --work and --flow must be used together');
+        process.exitCode = 1;
+        return;
+    }
+    // Validate that work/flow files exist
+    if (work && !fs.existsSync(work)) {
+        console.error(`\x1b[31mERR\x1b[0m --work file not found: ${work}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (flow && !fs.existsSync(flow)) {
+        console.error(`\x1b[31mERR\x1b[0m --flow file not found: ${flow}`);
+        process.exitCode = 1;
+        return;
+    }
+    const dryRun = !options.run;
+    const maxIssues = parseInt(options.max || '0', 10);
+    const budget = options.budget || '5.00';
+    const resumeLimit = parseInt(options.resumeLimit || '3', 10);
+    const pollInterval = parseInt(options.pollInterval || '60', 10);
+    const model = options.model || 'claude-opus-4-6';
+    const perIssueBranch = options.perIssueBranch || false;
+    const noBranch = options.noBranch || false;
+    let includeFeatures = options.features || false;
+    const skipPerms = options.skipPerms !== false; // default true
+    const bare = options.bare || false;
+    const poll = options.poll || false;
+    const projectDir = process.cwd();
+    const logDir = path.join(projectDir, 'labs', 'claude-runs');
+    fs.mkdirSync(logDir, { recursive: true });
+    // Planning mode dry-run
+    if (dryRun && work && flow) {
+        const workContent = fs.readFileSync(work, 'utf8');
+        const flowContent = fs.readFileSync(flow, 'utf8');
+        console.log('[bd-loop] PLANNING MODE (dry-run)');
+        console.log(`[bd-loop]   Work file: ${work}`);
+        console.log(`[bd-loop]   Flow file: ${flow}`);
+        console.log('[bd-loop]   Planning prompt that would be sent:');
+        console.log('---');
+        console.log(buildPlanningPrompt(workContent, flowContent, prefix));
+        console.log('---');
+        console.log('[bd-loop] After planning, loop would process tasks under the created feature.');
+        return;
+    }
+    // Planning phase: create feature tree before looping
+    if (work && flow) {
+        const planResult = await planWork({
+            workPath: work,
+            flowPath: flow,
+            prefix,
+            budget,
+            model,
+            skipPerms,
+            bare,
+            logDir,
+        });
+        if (!planResult.featureId) {
+            console.error('[bd-loop] Planning phase failed to produce a feature ID');
+            console.error('[bd-loop] Check logs in: ' + logDir);
+            process.exitCode = 1;
+            return;
+        }
+        // Warn if planning consumed more than half the budget
+        const budgetNum = parseFloat(budget);
+        if (planResult.costUsd != null && budgetNum > 0) {
+            const pct = (planResult.costUsd / budgetNum) * 100;
+            if (pct > 50) {
+                console.warn(`\x1b[33m[bd-loop]\x1b[0m ⚠️  Planning phase used $${planResult.costUsd.toFixed(2)} of $${budget} budget (${pct.toFixed(0)}%). ` +
+                    `Per-task phases share the same budget cap — tasks may hit the limit early.`);
+            }
+        }
+        prefix = planResult.featureId;
+        includeFeatures = true;
+        console.log(`\x1b[32m[bd-loop]\x1b[0m Planning complete. Feature: ${planResult.featureId}`);
+    }
+    console.log(`\x1b[32m[bd-loop]\x1b[0m Starting bd-loop for prefix \x1b[34m${prefix}\x1b[0m`);
+    if (dryRun) {
+        console.log('\x1b[33m[bd-loop]\x1b[0m DRY RUN — add --run to execute');
+    }
+    // Set up shared branch
+    let originalBranch;
+    let sharedBranch;
+    if (!noBranch && !perIssueBranch) {
+        sharedBranch = `work/${prefix}`;
+        console.log(`\x1b[32m[bd-loop]\x1b[0m Branch strategy: shared branch \x1b[34m${sharedBranch}\x1b[0m`);
+    }
+    if (sharedBranch && !dryRun) {
+        originalBranch = (0, child_process_1.execSync)('git branch --show-current', { encoding: 'utf8' }).trim();
+        console.log(`\x1b[32m[bd-loop]\x1b[0m   Checking out branch: ${sharedBranch}`);
+        try {
+            (0, child_process_1.execSync)(`git checkout -b ${sharedBranch} 2>/dev/null`, { encoding: 'utf8' });
+        }
+        catch {
+            try {
+                (0, child_process_1.execSync)(`git checkout ${sharedBranch}`, { encoding: 'utf8' });
+                console.log(`\x1b[33m[bd-loop]\x1b[0m   Branch ${sharedBranch} already exists, checked out`);
+            }
+            catch {
+                console.error(`\x1b[31m[bd-loop]\x1b[0m   Failed to checkout shared branch ${sharedBranch}`);
+                console.error('\x1b[31m[bd-loop]\x1b[0m   You may have uncommitted changes — try: git stash');
+                process.exitCode = 1;
+                return;
+            }
+        }
+    }
+    let totalProcessed = 0;
+    let totalClosed = 0;
+    const results = [];
+    while (true) {
+        const nextId = prefix ? findNextIssue(prefix, includeFeatures) : null;
+        if (!nextId) {
+            if (poll) {
+                console.log(`\x1b[36m[bd-loop]\x1b[0m No ready issues for prefix '${prefix}'. Polling again in ${pollInterval}s...`);
+                await sleep(pollInterval * 1000);
+                continue;
+            }
+            else {
+                console.log(`\x1b[32m[bd-loop]\x1b[0m No more ready issues for prefix '${prefix}'.`);
+                break;
+            }
+        }
+        totalProcessed++;
+        if (maxIssues > 0 && totalProcessed > maxIssues) {
+            console.log(`\x1b[32m[bd-loop]\x1b[0m Reached --max ${maxIssues} issues. Stopping.`);
+            break;
+        }
+        if (dryRun) {
+            // Show all matching issues in dry-run mode
+            try {
+                const matching = getMatchingReadyIssues(prefix || '', includeFeatures);
+                for (const m of matching) {
+                    const info = getIssueInfo(m.id);
+                    if (!info)
+                        continue;
+                    if (maxIssues > 0 && totalProcessed > maxIssues)
+                        break;
+                    console.log(`  \x1b[34m${info.id}\x1b[0m (P${info.priority} ${info.issue_type}) — ${info.title}`);
+                    console.log(`    Would run: claude -p --max-budget-usd ${budget} --session-id <uuid>`);
+                    if (sharedBranch) {
+                        console.log(`    Branch: ${sharedBranch} (shared)`);
+                    }
+                    else if (!noBranch) {
+                        console.log(`    Branch: fix/${info.id}`);
+                    }
+                    console.log(`    Resume limit: ${resumeLimit} attempts`);
+                    console.log('');
+                    if (m.id !== nextId)
+                        totalProcessed++;
+                }
+            }
+            catch {
+                // Fallback: just show the one issue
+                const info = getIssueInfo(nextId);
+                if (info) {
+                    console.log(`  \x1b[34m${info.id}\x1b[0m (P${info.priority} ${info.issue_type}) — ${info.title}`);
+                }
+            }
+            break;
+        }
+        // Process the issue
+        const issue = getIssueInfo(nextId);
+        if (!issue) {
+            console.error(`\x1b[31m[bd-loop]\x1b[0m   Failed to get issue details for ${nextId}`);
+            continue;
+        }
+        const result = await processIssue(issue, {
+            budget,
+            model,
+            skipPerms,
+            bare,
+            resumeLimit,
+            perIssueBranch,
+            noBranch,
+            logDir,
+        });
+        results.push(result);
+        if (result.closed)
+            totalClosed++;
+        if (result.limitHit) {
+            console.error('\x1b[31m[bd-loop]\x1b[0m   Credit/usage limit hit — stopping loop');
+            break;
+        }
+    }
+    // Return to original branch
+    if (sharedBranch && !dryRun && originalBranch) {
+        try {
+            (0, child_process_1.execSync)(`git checkout ${originalBranch} 2>/dev/null`);
+        }
+        catch {
+            // Best effort
+        }
+    }
+    // Summary
+    console.log('');
+    console.log('\x1b[32m[bd-loop]\x1b[0m ━━━ Summary ━━━');
+    console.log(`\x1b[32m[bd-loop]\x1b[0m   Prefix:    ${prefix}`);
+    console.log(`\x1b[32m[bd-loop]\x1b[0m   Processed: ${totalProcessed}`);
+    if (!dryRun) {
+        console.log(`\x1b[32m[bd-loop]\x1b[0m   Closed:    ${totalClosed}`);
+        if (totalProcessed > totalClosed) {
+            console.log(`\x1b[33m[bd-loop]\x1b[0m   Not closed: ${totalProcessed - totalClosed}`);
+        }
+    }
+    console.log(`\x1b[32m[bd-loop]\x1b[0m   Logs: ${logDir}/`);
+    if (options.json) {
+        console.log(JSON.stringify({ prefix, totalProcessed, totalClosed, results }, null, 2));
+    }
+}