vemora 0.1.0-alpha.8

package/dist/commands/knowledge.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runKnowledgeList = runKnowledgeList;
+exports.runKnowledgeForget = runKnowledgeForget;
+const chalk_1 = __importDefault(require("chalk"));
+const config_1 = require("../core/config");
+const knowledge_1 = require("../storage/knowledge");
+async function runKnowledgeList(rootDir, options = {}) {
+    (0, config_1.loadConfig)(rootDir);
+    const storage = new knowledge_1.KnowledgeStorage(rootDir);
+    let entries = storage.load();
+    if (entries.length === 0) {
+        console.log(chalk_1.default.gray('No knowledge entries found. Use `vemora remember "<text>"` to add one.'));
+        return;
+    }
+    // Filter
+    if (options.category) {
+        entries = entries.filter((e) => e.category === options.category);
+    }
+    if (options.file) {
+        entries = entries.filter((e) => e.relatedFiles?.some((f) => f.includes(options.file)));
+    }
+    if (options.symbol) {
+        entries = entries.filter((e) => e.relatedSymbols?.includes(options.symbol));
+    }
+    if (entries.length === 0) {
+        console.log(chalk_1.default.gray("No entries match the given filters."));
+        return;
+    }
+    // Group by category
+    const order = [
+        "gotcha",
+        "pattern",
+        "decision",
+        "glossary",
+    ];
+    const grouped = new Map();
+    for (const cat of order)
+        grouped.set(cat, []);
+    for (const e of entries) {
+        grouped.get(e.category)?.push(e) ?? grouped.set(e.category, [e]);
+    }
+    const categoryColor = {
+        gotcha: chalk_1.default.red,
+        pattern: chalk_1.default.cyan,
+        decision: chalk_1.default.yellow,
+        glossary: chalk_1.default.gray,
+    };
+    for (const [cat, group] of grouped) {
+        if (group.length === 0)
+            continue;
+        const colorFn = categoryColor[cat] ?? chalk_1.default.white;
+        console.log();
+        console.log(colorFn(chalk_1.default.bold(`▸ ${cat.toUpperCase()}`)));
+        for (const e of group) {
+            const shortId = e.id.slice(0, 8);
+            const conf = e.confidence === "high"
+                ? chalk_1.default.green("●")
+                : e.confidence === "medium"
+                    ? chalk_1.default.yellow("●")
+                    : chalk_1.default.gray("●");
+            console.log(`  ${conf} ${chalk_1.default.bold(e.title)}  ${chalk_1.default.gray(`[${shortId}]`)}`);
+            if (e.body !== e.title) {
+                const preview = e.body.length > 120 ? `${e.body.slice(0, 120)}…` : e.body;
+                console.log(`    ${chalk_1.default.gray(preview)}`);
+            }
+            if (e.relatedFiles?.length) {
+                console.log(`    ${chalk_1.default.gray("files:")} ${e.relatedFiles.join(", ")}`);
+            }
+            if (e.relatedSymbols?.length) {
+                console.log(`    ${chalk_1.default.gray("symbols:")} ${e.relatedSymbols.join(", ")}`);
+            }
+            if (e.supersedes) {
+                console.log(`    ${chalk_1.default.gray(`supersedes: ${e.supersedes.slice(0, 8)}`)}`);
+            }
+        }
+    }
+    console.log();
+    console.log(chalk_1.default.gray(`Total: ${entries.length} entr${entries.length === 1 ? "y" : "ies"}`));
+}
+// ─── Forget ───────────────────────────────────────────────────────────────────
+async function runKnowledgeForget(rootDir, id) {
+    (0, config_1.loadConfig)(rootDir);
+    const storage = new knowledge_1.KnowledgeStorage(rootDir);
+    // Support short ID prefix (first 8 chars)
+    const entries = storage.load();
+    const match = entries.find((e) => e.id === id || e.id.startsWith(id));
+    if (!match) {
+        console.error(chalk_1.default.red(`Error: no entry found with ID starting with "${id}".`));
+        process.exit(1);
+    }
+    storage.remove(match.id);
+    console.log(chalk_1.default.green(`✔ Removed entry [${match.id.slice(0, 8)}] "${match.title}".`));
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/commands/knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.js","sourceRoot":"","sources":["../../src/commands/knowledge.ts"],"names":[],"mappings":"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"}

package/dist/commands/plan.d.ts

@@ -0,0 +1,16 @@
+export interface PlanOptions {
+    /** Number of chunks to retrieve per step when falling back to search (default: 5) */
+    topK?: number;
+    /** Force keyword/BM25 search, skip embeddings */
+    keyword?: boolean;
+    /** Max tokens per step context (default: 4000) */
+    budget?: number;
+    /** Print retrieved context for each step */
+    showContext?: boolean;
+    /** Show the plan and ask for confirmation before executing */
+    confirm?: boolean;
+    /** After all steps, call the planner again to synthesize a final answer */
+    synthesize?: boolean;
+}
+export declare function runPlan(rootDir: string, task: string, options?: PlanOptions): Promise<void>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/commands/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/commands/plan.ts"],"names":[],"mappings":"AAiCA,MAAM,WAAW,WAAW;IAC1B,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAmaD,wBAAsB,OAAO,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAsYf"}

package/dist/commands/plan.js

@@ -0,0 +1,535 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPlan = runPlan;
+const chalk_1 = __importDefault(require("chalk"));
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const ora_1 = __importDefault(require("ora"));
+const readline_1 = __importDefault(require("readline"));
+const util_1 = require("util");
+const config_1 = require("../core/config");
+const factory_1 = require("../embeddings/factory");
+const factory_2 = require("../llm/factory");
+const bm25_1 = require("../search/bm25");
+const vector_1 = require("../search/vector");
+const cache_1 = require("../storage/cache");
+const knowledge_1 = require("../storage/knowledge");
+const repository_1 = require("../storage/repository");
+const summaries_1 = require("../storage/summaries");
+const tokenizer_1 = require("../utils/tokenizer");
+const context_1 = require("./context");
+const execAsync = (0, util_1.promisify)(child_process_1.exec);
+// ─── Prompts ──────────────────────────────────────────────────────────────────
+const PLANNER_SYSTEM_PROMPT = `You are an expert software architect.
+Decompose a complex codebase task into a concrete step-by-step plan for a smaller model to execute.
+
+Available step actions:
+  read    — pull code into context with no LLM call (free; use to share files across steps)
+  analyze — executor answers a question in prose (default)
+  write   — executor produces a unified diff (use for code changes)
+  test    — run a shell command and capture its output (use to verify changes)
+
+Guidelines:
+- Each step must be atomic and focused on a single concern.
+- Prefer "files" and "symbols" over "query" — direct retrieval is faster and cheaper.
+- Use "dependsOn" when a step needs the output of a prior step.
+- Use action:"read" to share a file's content with later write/analyze steps.
+- Use action:"write" for code changes; the executor will produce a unified diff.
+- Use action:"test" with a "command" field to verify changes.
+- If unsure of exact file paths, use "query" as fallback.
+- Keep steps ≤ 7 unless truly necessary.
+
+Return ONLY valid JSON — no markdown fences, no explanation:
+{
+  "goal": "<one-line summary>",
+  "steps": [
+    {
+      "id": 1,
+      "action": "read|analyze|write|test",
+      "goal": "<what this step determines or produces>",
+      "instruction": "<precise instruction for the executor>",
+      "files": ["src/path/to/file.ts"],
+      "symbols": ["SymbolName"],
+      "query": "<fallback search query>",
+      "dependsOn": [],
+      "command": "<shell command, only for action:test>"
+    }
+  ]
+}`;
+const EXECUTOR_ANALYZE_PROMPT = "You are an expert software engineer. " +
+    "Answer the specific question using ONLY the provided code context. " +
+    "Be concise and technical. Reference file paths and symbol names when relevant.\n" +
+    "If context is insufficient, start your response with INSUFFICIENT: and describe what is missing.";
+const EXECUTOR_WRITE_PROMPT = "You are an expert software engineer. " +
+    "Produce the code changes requested as a unified diff.\n\n" +
+    "Rules:\n" +
+    "- Output ONLY the diff, no explanation before or after.\n" +
+    "- Use standard unified diff format: --- a/path and +++ b/path headers.\n" +
+    "- Include 3 lines of context around each change.\n" +
+    "- If context is insufficient to produce a correct diff, start with INSUFFICIENT: and describe what is missing.";
+const SYNTHESIZER_SYSTEM_PROMPT = "You are an expert software engineer. " +
+    "Synthesize the results from multiple analysis steps into a single, coherent, well-structured answer. " +
+    "Avoid repeating information. Be concise and precise.";
+const REPLAN_SYSTEM_PROMPT = "You are an expert software architect. " +
+    "One or more steps in a plan failed because the executor had insufficient context. " +
+    "Provide 1-3 additional steps to recover the missing information.\n\n" +
+    "Return ONLY valid JSON — no markdown fences:\n" +
+    '{ "steps": [{ "id": <next_id>, "action": "read|analyze", "goal": "...", "instruction": "...", "files": [], "symbols": [], "query": "...", "dependsOn": [<failed_step_id>] }] }';
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/** Topological sort into waves — each wave can run in parallel. */
+function buildExecutionWaves(steps) {
+    const waves = [];
+    const resolved = new Set();
+    let remaining = [...steps];
+    while (remaining.length > 0) {
+        const wave = remaining.filter((s) => (s.dependsOn ?? []).every((id) => resolved.has(id)));
+        if (wave.length === 0)
+            break; // circular dependency guard
+        for (const s of wave)
+            resolved.add(s.id);
+        remaining = remaining.filter((s) => !wave.some((w) => w.id === s.id));
+        waves.push(wave);
+    }
+    return waves;
+}
+/** Cache key for context deduplication within a session. */
+function contextCacheKey(step) {
+    return JSON.stringify({
+        f: [...(step.files ?? [])].sort(),
+        s: [...(step.symbols ?? [])].sort(),
+        q: step.query,
+    });
+}
+/** Prompt the user for y/n confirmation. */
+async function askConfirm(question) {
+    return new Promise((resolve) => {
+        const rl = readline_1.default.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        rl.question(question, (answer) => {
+            rl.close();
+            const a = answer.trim().toLowerCase();
+            resolve(a === "y" || a === "yes" || a === "");
+        });
+    });
+}
+/** Display the plan in a human-readable table before execution. */
+function displayPlan(plan, steps) {
+    const actionColor = {
+        read: chalk_1.default.blue,
+        analyze: chalk_1.default.gray,
+        write: chalk_1.default.green,
+        test: chalk_1.default.magenta,
+    };
+    console.log(chalk_1.default.bold(`\nGoal: ${plan.goal}\n`));
+    for (const step of steps) {
+        const action = step.action ?? "analyze";
+        const badge = (actionColor[action] ?? chalk_1.default.gray)(`[${action}]`);
+        const targets = (step.files?.length ?? 0) + (step.symbols?.length ?? 0) > 0
+            ? chalk_1.default.gray(`  →  ${[...(step.files ?? []), ...(step.symbols ?? [])].join(", ")}`)
+            : step.query
+                ? chalk_1.default.gray(`  →  search: "${step.query}"`)
+                : "";
+        const deps = step.dependsOn?.length
+            ? chalk_1.default.gray(`  (depends on: ${step.dependsOn.join(", ")})`)
+            : "";
+        console.log(`  ${chalk_1.default.bold.yellow(String(step.id).padStart(2))}  ${badge}  ${chalk_1.default.bold(step.goal)}${targets}${deps}`);
+        if (action === "test" && step.command) {
+            console.log(chalk_1.default.gray(`       $ ${step.command}`));
+        }
+    }
+    console.log();
+}
+/** Build the cheap planner context from summaries + symbol list (no raw code). */
+function buildPlannerContext(projectName, projectOverview, fileSummaries, symbols) {
+    const lines = [`# Project: ${projectName}\n`];
+    if (projectOverview) {
+        lines.push("## Overview\n", projectOverview, "");
+    }
+    const fileEntries = Object.entries(fileSummaries);
+    if (fileEntries.length > 0) {
+        lines.push(`## Files (${fileEntries.length})\n`);
+        for (const [file, entry] of fileEntries) {
+            lines.push(`${file} — ${entry.summary}`);
+        }
+        lines.push("");
+    }
+    const symbolEntries = Object.entries(symbols);
+    if (symbolEntries.length > 0) {
+        lines.push(`## Symbols (${symbolEntries.length})\n`);
+        for (const [name, entry] of symbolEntries) {
+            lines.push(`${name} (${entry.type}) — ${entry.file}:${entry.startLine}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/** Retrieve and format code context for an executor step, with session-level caching. */
+async function retrieveStepContext(step, config, data, cacheStorage, rootDir, topK, budget, forceKeyword, contextCache) {
+    const cacheKey = contextCacheKey(step);
+    const cached = contextCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const { chunks, symbols, depGraph, callGraph, fileSummaries, projectOverview, knowledgeEntries } = data;
+    let results = [];
+    const hasTargets = (step.files?.length ?? 0) + (step.symbols?.length ?? 0) > 0;
+    if (hasTargets) {
+        const fileSet = new Set(step.files ?? []);
+        const symbolSet = new Set(step.symbols ?? []);
+        const targeted = chunks.filter((c) => (fileSet.size > 0 && fileSet.has(c.file)) ||
+            (symbolSet.size > 0 && c.symbol !== undefined && symbolSet.has(c.symbol)));
+        results = targeted.map((chunk) => ({
+            chunk,
+            score: 1,
+            symbol: chunk.symbol ? symbols[chunk.symbol] : undefined,
+        }));
+    }
+    if (results.length === 0) {
+        if (forceKeyword) {
+            results = (0, bm25_1.computeBM25Scores)(step.query, chunks, symbols, topK);
+        }
+        else {
+            try {
+                const cache = cacheStorage.load();
+                const cachedCount = cache
+                    ? (cache.chunkIds?.length ?? Object.keys(cache.embeddings ?? {}).length)
+                    : 0;
+                if (!cache || cachedCount === 0) {
+                    results = (0, bm25_1.computeBM25Scores)(step.query, chunks, symbols, topK);
+                }
+                else {
+                    const provider = (0, factory_1.createEmbeddingProvider)(config.embedding);
+                    const [queryEmbedding] = await provider.embed([step.query]);
+                    results = (0, vector_1.vectorSearch)(queryEmbedding, chunks, cache, symbols, topK);
+                    if (results.length === 0) {
+                        results = (0, bm25_1.computeBM25Scores)(step.query, chunks, symbols, topK);
+                    }
+                }
+            }
+            catch {
+                results = (0, bm25_1.computeBM25Scores)(step.query, chunks, symbols, topK);
+            }
+        }
+    }
+    results = (0, tokenizer_1.applyTokenBudget)(results, budget);
+    const contextFormat = config.display?.format === "terse" ? "terse" : "plain";
+    const contextStr = (0, context_1.generateContextString)(config, results, depGraph, callGraph, fileSummaries, projectOverview, { query: step.query, format: contextFormat }, rootDir, chunks, knowledgeEntries);
+    contextCache.set(cacheKey, contextStr);
+    return contextStr;
+}
+/** Execute a single step, returning its answer and whether context was insufficient. */
+async function executeStep(step, config, data, cacheStorage, rootDir, executorConfig, executor, topK, budget, forceKeyword, stepResults, contextCache, showContext) {
+    const action = step.action ?? "analyze";
+    // ── action: test — run shell command, no LLM ──────────────────────────────
+    if (action === "test") {
+        if (!step.command) {
+            return { stepId: step.id, answer: "No command specified for test step.", insufficient: false };
+        }
+        try {
+            const { stdout, stderr } = await execAsync(step.command, {
+                cwd: rootDir,
+                timeout: 60_000,
+            });
+            const answer = `$ ${step.command}\n\n` +
+                (stdout ? `stdout:\n${stdout}` : "") +
+                (stderr ? `\nstderr:\n${stderr}` : "");
+            return { stepId: step.id, answer, insufficient: false };
+        }
+        catch (err) {
+            const e = err;
+            const answer = `$ ${step.command} — FAILED\n\n` +
+                (e.stdout ? `stdout:\n${e.stdout}\n` : "") +
+                (e.stderr ? `stderr:\n${e.stderr}\n` : "") +
+                (e.message ? `error: ${e.message}` : "");
+            return { stepId: step.id, answer, insufficient: false };
+        }
+    }
+    // ── retrieve context (shared cache) ──────────────────────────────────────
+    const contextStr = await retrieveStepContext(step, config, data, cacheStorage, rootDir, topK, budget, forceKeyword, contextCache);
+    if (showContext) {
+        console.log(chalk_1.default.gray("  ── context ──────────────────────────────────"));
+        console.log(chalk_1.default.gray(contextStr));
+        console.log(chalk_1.default.gray("  ─────────────────────────────────────────────\n"));
+    }
+    // ── action: read — return context as-is, no LLM call ─────────────────────
+    if (action === "read") {
+        return { stepId: step.id, answer: contextStr, insufficient: false };
+    }
+    // ── inject dependsOn results ──────────────────────────────────────────────
+    let dependencySection = "";
+    if (step.dependsOn?.length) {
+        const parts = [];
+        for (const depId of step.dependsOn) {
+            const depResult = stepResults.get(depId);
+            if (depResult)
+                parts.push(`### Step ${depId}\n${depResult}`);
+        }
+        if (parts.length > 0) {
+            dependencySection = `\n\n## Prior step results\n${parts.join("\n\n")}`;
+        }
+    }
+    // ── action: analyze | write — call executor LLM ───────────────────────────
+    const systemPrompt = action === "write" ? EXECUTOR_WRITE_PROMPT : EXECUTOR_ANALYZE_PROMPT;
+    const response = await executor.chat([
+        { role: "system", content: `${systemPrompt}\n\n${contextStr}` },
+        {
+            role: "user",
+            content: `Goal: ${step.goal}\n\nInstruction: ${step.instruction}${dependencySection}`,
+        },
+    ], {
+        model: executorConfig.model,
+        temperature: action === "write" ? 0.1 : 0.3,
+    });
+    const answer = response.content;
+    const insufficient = answer.trimStart().startsWith("INSUFFICIENT:");
+    return { stepId: step.id, answer, insufficient };
+}
+// ─── Main command ─────────────────────────────────────────────────────────────
+async function runPlan(rootDir, task, options = {}) {
+    const config = (0, config_1.loadConfig)(rootDir);
+    if (!config.summarization) {
+        console.error(chalk_1.default.red('No executor LLM configured. Add a "summarization" block to .vemora/config.json.'));
+        process.exit(1);
+    }
+    // config.summarization is guaranteed non-undefined here (checked above)
+    const executorConfig = config.summarization;
+    const plannerConfig = config.planner ?? executorConfig;
+    const topK = options.topK ?? 5;
+    const budget = options.budget ?? 4000;
+    const forceKeyword = options.keyword || config.embedding.provider === "none";
+    // ── Load index data once ───────────────────────────────────────────────────
+    const repo = new repository_1.RepositoryStorage(rootDir);
+    const cacheStorage = new cache_1.EmbeddingCacheStorage(config.projectId);
+    const summaryStorage = new summaries_1.SummaryStorage(rootDir);
+    const chunks = repo.loadChunks();
+    if (chunks.length === 0) {
+        console.error(chalk_1.default.red("No index found. Run `vemora index` first."));
+        process.exit(1);
+    }
+    const data = {
+        chunks,
+        symbols: repo.loadSymbols(),
+        depGraph: repo.loadDeps(),
+        callGraph: repo.loadCallGraph(),
+        fileSummaries: summaryStorage.hasFileSummaries()
+            ? summaryStorage.loadFileSummaries()
+            : {},
+        projectOverview: summaryStorage.loadProjectSummary()?.overview ?? null,
+        knowledgeEntries: new knowledge_1.KnowledgeStorage(rootDir).load(),
+    };
+    const planner = (0, factory_2.createLLMProvider)(plannerConfig);
+    const executor = (0, factory_2.createLLMProvider)(executorConfig);
+    const sameLLM = plannerConfig.provider === executorConfig.provider &&
+        plannerConfig.model === executorConfig.model;
+    console.log(chalk_1.default.bold.cyan("\n[vemora plan]"));
+    console.log(chalk_1.default.gray(`  Planner:  ${planner.name} · ${plannerConfig.model}${sameLLM ? " (also executor)" : ""}`));
+    if (!sameLLM) {
+        console.log(chalk_1.default.gray(`  Executor: ${executor.name} · ${executorConfig.model}`));
+    }
+    const hasSummaries = data.projectOverview !== null || Object.keys(data.fileSummaries).length > 0;
+    if (!hasSummaries) {
+        console.log(chalk_1.default.yellow("  Tip: run `vemora summarize` for cheaper planning (summaries replace raw code)."));
+    }
+    console.log();
+    // ── Phase 1: build planner context (summaries + symbols, no raw code) ──────
+    const plannerSpinner = (0, ora_1.default)("Planning...").start();
+    const plannerContext = hasSummaries
+        ? buildPlannerContext(config.projectName, data.projectOverview, data.fileSummaries, data.symbols)
+        : (0, context_1.generateContextString)(config, (0, tokenizer_1.applyTokenBudget)((0, bm25_1.computeBM25Scores)(task, chunks, data.symbols, topK), budget), data.depGraph, data.callGraph, data.fileSummaries, data.projectOverview, { query: task, format: "terse" }, rootDir, chunks, data.knowledgeEntries);
+    // ── Phase 2: call planner ──────────────────────────────────────────────────
+    // definite assignment: process.exit(1) in catch guarantees assignment
+    let plan;
+    try {
+        const plannerResponse = await planner.chat([
+            {
+                role: "system",
+                content: `${PLANNER_SYSTEM_PROMPT}\n\n${plannerContext}`,
+            },
+            {
+                role: "user",
+                content: `Decompose this task into concrete steps:\n\n${task}`,
+            },
+        ], { model: plannerConfig.model, temperature: 0.2 });
+        const raw = plannerResponse.content.trim();
+        const jsonStr = raw.startsWith("```")
+            ? raw.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "")
+            : raw;
+        plan = JSON.parse(jsonStr);
+        if (!Array.isArray(plan.steps) || plan.steps.length === 0) {
+            throw new Error("Plan has no steps");
+        }
+        plannerSpinner.succeed(`Plan ready — ${plan.steps.length} step${plan.steps.length !== 1 ? "s" : ""}`);
+    }
+    catch (err) {
+        plannerSpinner.fail(`Planning failed: ${err.message}`);
+        process.exit(1);
+    }
+    // ── Phase 3: display plan + optional confirmation ──────────────────────────
+    displayPlan(plan, plan.steps);
+    if (options.confirm) {
+        const ok = await askConfirm(chalk_1.default.bold("Proceed with this plan? [Y/n] "));
+        if (!ok) {
+            console.log(chalk_1.default.gray("Aborted."));
+            return;
+        }
+        console.log();
+    }
+    // ── Phase 4: execute in topological waves (parallel within each wave) ──────
+    const waves = buildExecutionWaves(plan.steps);
+    const stepResults = new Map();
+    const contextCache = new Map();
+    let nextId = Math.max(...plan.steps.map((s) => s.id)) + 1;
+    for (const wave of waves) {
+        const isParallel = wave.length > 1;
+        if (isParallel) {
+            console.log(chalk_1.default.gray(`── parallel wave (${wave.length} steps: ${wave.map((s) => s.id).join(", ")}) ──`));
+        }
+        const waveSpinners = wave.map((step) => {
+            const action = step.action ?? "analyze";
+            const badge = { read: "📖", analyze: "🔍", write: "✏️", test: "🧪" }[action] ?? "•";
+            const label = `${badge} [${step.id}] ${step.goal}`;
+            return isParallel ? (0, ora_1.default)(`  ${label}`).start() : null;
+        });
+        if (!isParallel) {
+            const step = wave[0];
+            const action = step.action ?? "analyze";
+            const badge = { read: chalk_1.default.blue, analyze: chalk_1.default.gray, write: chalk_1.default.green, test: chalk_1.default.magenta }[action] ?? chalk_1.default.gray;
+            const targets = (step.files?.length ?? 0) + (step.symbols?.length ?? 0) > 0
+                ? chalk_1.default.gray(` [${[...(step.files ?? []), ...(step.symbols ?? [])].join(", ")}]`)
+                : "";
+            console.log(`${chalk_1.default.bold.yellow(`[${step.id}/${plan.steps.length}]`)} ${badge(`[${action}]`)} ${chalk_1.default.bold(step.goal)}${targets}`);
+        }
+        const waveResults = await Promise.all(wave.map((step, i) => executeStep(step, config, data, cacheStorage, rootDir, executorConfig, executor, topK, budget, forceKeyword, stepResults, contextCache, options.showContext ?? false).then((result) => {
+            waveSpinners[i]?.succeed(`  [${step.id}] ${step.goal}`);
+            return result;
+        }).catch((err) => {
+            waveSpinners[i]?.fail(`  [${step.id}] ${step.goal}`);
+            return { stepId: step.id, answer: `Error: ${err.message}`, insufficient: false };
+        })));
+        for (const result of waveResults) {
+            stepResults.set(result.stepId, result.answer);
+            if (!isParallel) {
+                const indented = result.answer.replace(/\n/g, "\n  ");
+                console.log(`  ${indented}\n`);
+            }
+        }
+        if (isParallel) {
+            for (const result of waveResults) {
+                const step = wave.find((s) => s.id === result.stepId);
+                console.log(chalk_1.default.bold.yellow(`\n  [${step.id}] ${step.goal}`));
+                console.log(`  ${result.answer.replace(/\n/g, "\n  ")}\n`);
+            }
+        }
+        // ── Adaptive re-planning: handle INSUFFICIENT steps ────────────────────
+        const insufficientSteps = waveResults.filter((r) => r.insufficient);
+        if (insufficientSteps.length > 0) {
+            const replanSpinner = (0, ora_1.default)(`  Re-planning for ${insufficientSteps.length} insufficient step(s)...`).start();
+            const failedSummary = insufficientSteps
+                .map((r) => {
+                const step = wave.find((s) => s.id === r.stepId);
+                return `Step ${r.stepId} (${step.goal}):\n${r.answer}`;
+            })
+                .join("\n\n");
+            try {
+                const replanResponse = await planner.chat([
+                    {
+                        role: "system",
+                        content: `${REPLAN_SYSTEM_PROMPT}\n\n${plannerContext}`,
+                    },
+                    {
+                        role: "user",
+                        content: `The following steps reported insufficient context:\n\n${failedSummary}\n\n` +
+                            `Next available step ID: ${nextId}. ` +
+                            `Provide remediation steps to gather the missing information.`,
+                    },
+                ], { model: plannerConfig.model, temperature: 0.2 });
+                const raw = replanResponse.content.trim();
+                const jsonStr = raw.startsWith("```")
+                    ? raw.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "")
+                    : raw;
+                const replan = JSON.parse(jsonStr);
+                if (Array.isArray(replan.steps) && replan.steps.length > 0) {
+                    // Reassign IDs to avoid collisions
+                    const remediationSteps = replan.steps.map((s, i) => ({
+                        ...s,
+                        id: nextId + i,
+                    }));
+                    nextId += remediationSteps.length;
+                    replanSpinner.succeed(`  Re-plan: ${remediationSteps.length} remediation step(s) added`);
+                    // Execute remediation steps immediately (as a new wave)
+                    const remediationWaves = buildExecutionWaves(remediationSteps);
+                    for (const remWave of remediationWaves) {
+                        const remResults = await Promise.all(remWave.map((step) => executeStep(step, config, data, cacheStorage, rootDir, executorConfig, executor, topK, budget, forceKeyword, stepResults, contextCache, options.showContext ?? false)));
+                        for (const r of remResults) {
+                            stepResults.set(r.stepId, r.answer);
+                            const step = remWave.find((s) => s.id === r.stepId);
+                            console.log(chalk_1.default.bold.yellow(`\n  [${step.id}ᴿ] ${step.goal}`));
+                            console.log(`  ${r.answer.replace(/\n/g, "\n  ")}\n`);
+                        }
+                    }
+                }
+                else {
+                    replanSpinner.warn("  Re-plan returned no steps.");
+                }
+            }
+            catch {
+                replanSpinner.warn("  Re-planning failed — continuing.");
+            }
+        }
+    }
+    // ── Phase 5: optional synthesis ────────────────────────────────────────────
+    let synthesisText = "";
+    if (options.synthesize && stepResults.size > 0) {
+        const synthSpinner = (0, ora_1.default)("Synthesizing final answer...").start();
+        const stepSummaries = plan.steps
+            .map((s) => {
+            const result = stepResults.get(s.id);
+            return result ? `### Step ${s.id}: ${s.goal}\n${result}` : null;
+        })
+            .filter(Boolean)
+            .join("\n\n");
+        try {
+            const response = await planner.chat([
+                { role: "system", content: SYNTHESIZER_SYSTEM_PROMPT },
+                {
+                    role: "user",
+                    content: `Original task: ${task}\n\n## Step results\n\n${stepSummaries}\n\nSynthesize a final, complete answer.`,
+                },
+            ], { model: plannerConfig.model, temperature: 0.3 });
+            synthesisText = response.content;
+            synthSpinner.succeed("Synthesis complete");
+            console.log(chalk_1.default.bold.cyan("\n── Final answer ────────────────────────────────\n"));
+            console.log(synthesisText);
+            console.log(chalk_1.default.gray("\n────────────────────────────────────────────────"));
+        }
+        catch (err) {
+            synthSpinner.fail(`Synthesis error: ${err.message}`);
+        }
+    }
+    // ── Phase 6: offer to save synthesis as knowledge entry ───────────────────
+    if (synthesisText && options.synthesize) {
+        const save = await askConfirm(chalk_1.default.bold("\nSave synthesis as a knowledge entry? [y/N] "));
+        if (save) {
+            const knowledge = new knowledge_1.KnowledgeStorage(rootDir);
+            const entries = knowledge.load();
+            entries.push({
+                id: (0, crypto_1.randomUUID)(),
+                category: "pattern",
+                title: plan.goal,
+                body: synthesisText,
+                createdAt: new Date().toISOString(),
+                createdBy: `llm:${plannerConfig.model}`,
+                confidence: "medium",
+            });
+            knowledge.save(entries);
+            console.log(chalk_1.default.green("  Saved."));
+        }
+    }
+    console.log(chalk_1.default.gray(`\nPlan complete: ${stepResults.size} step(s) executed` +
+        (options.synthesize ? " + synthesis" : "")));
+}
+//# sourceMappingURL=plan.js.map