scai 0.1.143 → 0.1.144

package/dist/agents/MainAgent.js

@@ -1,70 +1,20 @@
 import { builtInModules } from "../pipeline/registry/moduleRegistry.js";
 import { logInputOutput } from "../utils/promptLogHelper.js";
-import { planResolverStep } from "./planResolverStep.js";
 import { infoPlanGen } from "./infoPlanGenStep.js";
 import { understandIntentStep } from "./understandIntentStep.js";
-import { structuralAnalysisStep } from "./structuralAnalysisStep.js";
 import { contextReviewStep } from "./contextReviewStep.js";
 import { planTargetFilesStep } from "./planTargetFilesStep.js";
-import { validationAnalysisStep } from "./validationAnalysisStep.js";
-import { semanticAnalysisStep } from "./semanticAnalysisStep.js";
 import { selectRelevantSourcesStep } from "./selectRelevantSourcesStep.js";
 import { transformPlanGenStep } from "./transformPlanGenStep.js";
 import { finalPlanGenStep } from "./finalPlanGenStep.js";
-import { Spinner } from "../lib/spinner.js";
 import { getDbForRepo } from "../db/client.js";
 import { writeFileStep } from "./writeFileStep.js";
 import { resolveExecutionModeStep } from "./resolveExecutionModeStep.js";
-import { preFileSearchCheckStep } from "./preFileSearchCheckStep.js";
+import { fileCheckStep } from "./fileCheckStep.js";
+import { analysisPlanGenStep } from "./analysisPlanGenStep.js";
+import chalk from "chalk";
+import { readinessGateStep } from "./readinessGateStep.js";
 /* ───────────────────────── helpers ───────────────────────── */
-let activeSpinner = null;
-/**
- * Called implicitly by MainAgent via side-effect:
- * the first spinner.start() will register itself here.
- */
-function registerSpinner(spinner) {
-    activeSpinner = spinner;
-}
-function startTimer() {
-    const start = Date.now();
-    return () => Date.now() - start;
-}
-function withSpinnerPaused(fn) {
-    if (!activeSpinner) {
-        fn();
-        return;
-    }
-    const wasRunning = typeof activeSpinner.isRunning === "function"
-        ? activeSpinner.isRunning()
-        : true;
-    if (wasRunning)
-        activeSpinner.stop();
-    try {
-        fn();
-    }
-    finally {
-        if (wasRunning)
-            activeSpinner.start();
-    }
-}
-function logLine(phase, step, ms, desc) {
-    withSpinnerPaused(() => {
-        process.stdout.write('\r\x1b[K');
-        const suffix = desc ? ` — ${desc}` : "";
-        const timing = typeof ms === "number" ? ` (${ms}ms)` : "";
-        console.log(`[AGENT] ${phase} :: ${step}${suffix}${timing}`);
-    });
-}
-function userOutput(message) {
-    withSpinnerPaused(() => {
-        console.log(`[USER OUTPUT] ${message}`);
-    });
-}
-function userPhaseOutput(phase, message) {
-    withSpinnerPaused(() => {
-        console.log(`[USER OUTPUT] [${phase}] ${message}`);
-    });
-}
 /* ───────────────────────── registry ───────────────────────── */
 const MODULE_REGISTRY = Object.fromEntries(Object.entries(builtInModules).map(([name, mod]) => [name, mod]));
 function resolveModuleForAction(action) {
@@ -72,24 +22,46 @@ function resolveModuleForAction(action) {
 }
 /* ───────────────────────── agent ───────────────────────── */
 export class MainAgent {
-    constructor(context) {
-        this.spinner = new Spinner();
+    constructor(context, ui) {
         this.runCount = 0;
         this.maxRuns = 2;
         this.context = context;
         this.query = context.initContext?.userQuery ?? "";
+        this.ui = ui;
+    }
+    /* ───────────── timers ───────────── */
+    startTimer() {
+        const start = Date.now();
+        return () => Date.now() - start;
+    }
+    /* ───────────── spinner helpers ───────────── */
+    withSpinnerPaused(fn) {
+        this.ui.pause(fn);
+    }
+    logLine(phase, step, ms, desc) {
+        this.withSpinnerPaused(() => {
+            process.stdout.write('\r\x1b[K');
+            const suffix = desc ? ` — ${desc}` : "";
+            const timing = typeof ms === "number" ? ` (${ms}ms)` : "";
+            console.log(`[AGENT] ${phase} :: ${step}${suffix}${timing}`);
+        });
+    }
+    userOutput(message) {
+        this.withSpinnerPaused(() => {
+            console.log(`[USER OUTPUT] ${message}`);
+        });
     }
     /* ───────────── step executor ───────────── */
     async executeStep(step, input) {
-        const stop = startTimer();
+        const stop = this.startTimer();
         this.context.currentStep = step;
         const mod = resolveModuleForAction(step.action);
         if (!mod) {
-            logLine("EXECUTE", step.action, stop(), "skipped (missing module)");
+            this.logLine("EXECUTE", step.action, stop(), "skipped (missing module)");
             return { query: input.query, content: input.content, data: { skipped: true } };
         }
         try {
-            this.spinner.update(`Running step: ${step.action}`);
+            this.ui.update(`Running step: ${step.action}`);
             const output = await mod.run({
                 query: step.description ?? input.query,
                 content: input.data ?? input.content,
@@ -97,15 +69,15 @@ export class MainAgent {
             });
             if (!output)
                 throw new Error(`Module "${mod.name}" returned empty output`);
-            logLine("EXECUTE", step.action, stop());
+            this.logLine("EXECUTE", step.action, stop());
             return { query: step.description ?? input.query, data: output.data };
         }
         catch (err) {
-            logLine("EXECUTE", step.action, stop(), "failed");
+            this.logLine("EXECUTE", step.action, stop(), "failed");
             throw err;
         }
     }
-    /* ───────────────────────── execution gates ───────────────────────── */
+    /* ───────────── execution gates ───────────── */
     canExecutePhase(phase) {
         const mode = this.context.executionControl?.mode ?? "transform";
         switch (phase) {
@@ -126,18 +98,17 @@ export class MainAgent {
     async run() {
         var _a, _b;
         this.runCount++;
-        const stopRun = startTimer();
-        logLine("RUN", `start #${this.runCount}`);
+        const stopRun = this.startTimer();
+        this.logLine("RUN", `start #${this.runCount}`);
         logInputOutput("GlobalContext (structured)", "input", this.context);
-        this.spinner.start();
         /* ================= BOOT ================= */
         {
-            const t1 = startTimer();
+            const t1 = this.startTimer();
             await understandIntentStep.run({ context: this.context });
-            logLine("BOOT", "understandIntent", t1());
-            const t2 = startTimer();
+            this.logLine("BOOT", "understandIntent", t1());
+            const t2 = this.startTimer();
             await resolveExecutionModeStep.run(this.context);
-            logLine("BOOT", "resolveExecutionMode", t2(), `mode=${this.context.executionControl?.mode}`);
+            this.logLine("BOOT", "resolveExecutionMode", t2(), `mode = ${this.context.executionControl?.mode} `);
             // Ensure executionControl exists first
             (_a = this.context).executionControl ?? (_a.executionControl = {
                 mode: "transform", // default mode if missing
@@ -184,16 +155,16 @@ export class MainAgent {
             const now = new Date().toISOString();
             const userQuery = this.context.initContext?.userQuery ?? "unknown query";
             const result = db.prepare(`
-                INSERT INTO tasks (initial_query, created_at, updated_at)
-                VALUES (?, ?, ?)
+                INSERT INTO tasks(initial_query, created_at, updated_at)
+VALUES(?, ?, ?)
             `).run(userQuery, now, now);
             this.taskId = result.lastInsertRowid;
-            logLine("TASK", `created task id=${this.taskId}"`);
+            this.logLine("TASK", `created task id = ${this.taskId} "`);
         }
-        /* ================= INFORMATION ACQUISITION ================= */
-        let t = startTimer();
-        await preFileSearchCheckStep(this.context);
-        logLine("PRECHECK", "preFileSearch", t());
+        // -------------------- INITIAL PRE-FILE CHECK --------------------
+        let t = this.startTimer();
+        await fileCheckStep(this.context);
+        this.logLine("PRECHECK", "preFileSearch", t());
         // -------------------- EXPLAIN MODE HANDLING --------------------
         if (this.canExecutePhase("explain")) {
             const explainMod = resolveModuleForAction("explain");
@@ -203,57 +174,83 @@ export class MainAgent {
                 query: this.query,
                 context: this.context
             });
-            logLine("MODE", "explain", undefined, "returning AI-generated explanation after preFileSearchCheck");
-            this.spinner.stop();
+            this.logLine("MODE", "explain", undefined, "returning AI-generated explanation after preFileSearchCheck");
             return explainOutput;
         }
-        // -------------------- SUMMARIZE FOLDERCAPSULES FOR PLANNING --------------------
+        // -------------------- summarize folder capsules --------------------
         logFolderCapsulesSummary(this.context);
-        /* ================= FAST-PATH CHECK ================= */
+        this.logLine("BOOT", "folderCapsulesSummary", t(), `📂 ${this.context.initContext?.folderCapsules?.length} folders summarized`);
         {
-            await planResolverStep.run(this.context);
-            const routing = this.context.analysis?.routingDecision;
-            if (routing?.decision === "final-answer" && routing.answer) {
-                logLine("ROUTING", "fastPathHit", undefined, "returning final answer early");
-                return { query: this.query, data: { finalAnswer: routing.answer, source: "planResolver" } };
-            }
+            let t = this.startTimer();
+            await readinessGateStep.run(this.context);
+            this.logLine("HASINFO", "routing", t());
         }
-        // -------------------- PLANNING --------------------
+        /* ================= INFORMATION ACQUISITION PHASE ================= */
         if (this.canExecutePhase("planning")) {
-            t = startTimer();
+            t = this.startTimer();
             await infoPlanGen.run(this.context);
-            logLine("PLAN", "infoPlanGen", t());
+            this.logLine("PLAN", "infoPlanGen", t());
             const infoPlan = this.context.analysis?.planSuggestion?.plan ?? { steps: [] };
             let stepIO = { query: this.query };
             for (const step of infoPlan.steps.filter(s => s.groups?.includes("info"))) {
                 stepIO = await this.executeStep(step, stepIO);
             }
+            // -------------------- POST-FILE DISCOVERY CHECK --------------------
+            // Only run if infoPlan actually generated steps / new files
+            const newFilesFound = infoPlan.steps.length > 0;
+            if (newFilesFound) {
+                t = this.startTimer();
+                await fileCheckStep(this.context);
+                this.logLine("PRECHECK", "postFileSearch", t());
+            }
+            else {
+                this.logLine("PRECHECK", "postFileSearch", undefined, chalk.gray("skipped (no new info search steps)"));
+            }
         }
         /* ================= ANALYSIS PHASE ================= */
-        if (this.canExecutePhase("analysis")) {
-            let t = startTimer();
+        {
+            t = this.startTimer();
             await selectRelevantSourcesStep.run({ query: this.query, context: this.context });
-            logLine("ANALYSIS", "selectRelevantSources", t());
+            this.logLine("ANALYSIS", "selectRelevantSources", t());
+        }
+        if (this.canExecutePhase("analysis")) {
+            t = this.startTimer();
+            await analysisPlanGenStep.run(this.context);
+            this.logLine("PLAN", "analysisPlanGen", t());
+            const analysisPlan = this.context.analysis?.planSuggestion?.plan?.steps ?? [];
+            let stepIO = { query: this.query };
+            for (const step of analysisPlan.filter(s => s.groups?.includes("analysis"))) {
+                stepIO = await this.executeStep(step, stepIO);
+            }
+        }
+        {
+            t = this.startTimer();
+            await planTargetFilesStep.run({ query: this.query, context: this.context });
+            this.logLine("ANALYSIS", "planTargetFiles", t());
+        }
+        /* // ── OPTIONAL DEBUGGING ──
+        debugContext(this.context, {
+            step: "After writefile ",
+            note: "Does transform exist?"
+        }); */
+        /* TO BE MOVED TO PLAN_ACTIONS
+         
+        if (this.canExecutePhase("analysis")) {
             t = startTimer();
             await structuralAnalysisStep.run({ query: this.query, context: this.context });
             logLine("ANALYSIS", "structuralAnalysis", t());
-            t = startTimer();
-            await semanticAnalysisStep.run({ query: this.query, context: this.context });
-            logLine("ANALYSIS", "semanticAnalysis", t());
-            t = startTimer();
-            await planTargetFilesStep.run({ query: this.query, context: this.context });
-            logLine("ANALYSIS", "planTargetFiles", t());
+        
             t = startTimer();
             await validationAnalysisStep.run({ query: this.query, context: this.context });
             logLine("VALIDATE", "validationAnalysis", t());
-        }
+        } */
         const review = await contextReviewStep(this.context);
-        if (review.decision === "gatherData") {
+        if (review.decision === "has") {
             if (this.runCount >= this.maxRuns) {
-                logLine("ROUTING", "gatherData", undefined, "max runs reached, proceeding anyway");
+                this.logLine("ROUTING", "gatherData", undefined, chalk.yellow("max runs reached, proceeding anyway"));
             }
             else {
-                logLine("ROUTING", "gatherData", undefined, review.reason);
+                this.logLine("ROUTING", "gatherData", undefined, chalk.yellow(review.reason));
                 this.runCount++;
                 this.resetInitContextForLoop();
                 return this.run();
@@ -261,9 +258,9 @@ export class MainAgent {
         }
         /* ================= TRANSFORM PHASE ================= */
         if (this.canExecutePhase("transform")) {
-            let t = startTimer();
+            let t = this.startTimer();
             await transformPlanGenStep.run(this.context);
-            logLine("PLAN", "transformPlanGen", t());
+            this.logLine("PLAN", "transformPlanGen", t());
             const transformSteps = (this.context.analysis?.planSuggestion?.plan?.steps ?? [])
                 .filter(s => s.groups?.includes("transform"));
             let stepIO = { query: this.query };
@@ -272,29 +269,28 @@ export class MainAgent {
             }
             /* ================= WRITE FILES ================= */
             if (this.canExecutePhase("write")) {
-                const tWrite = startTimer();
+                const tWrite = this.startTimer();
                 stepIO = await writeFileStep.run({
                     query: this.query,
                     context: this.context,
                     data: stepIO.data
                 });
-                logLine("EXECUTE", "writeFile", tWrite());
+                this.logLine("EXECUTE", "writeFile", tWrite());
             }
         }
         /* ================= FINALIZE PHASE ================= */
         {
-            const t = startTimer();
+            const t = this.startTimer();
             await finalPlanGenStep.run(this.context);
-            logLine("PLAN", "finalPlanGen", t());
+            this.logLine("PLAN", "finalPlanGen", t());
             const finalPlan = this.context.analysis?.planSuggestion?.plan ?? { steps: [] };
             let stepIO = { query: this.query };
             for (const step of finalPlan.steps.filter(s => s.groups?.includes("finalize"))) {
                 stepIO = await this.executeStep(step, stepIO);
             }
         }
-        this.spinner.stop();
-        userOutput("All input/output logs can be found at ~/.scai/input_output.log");
-        logLine("RUN", "complete", stopRun());
+        this.userOutput("All input/output logs can be found at ~/.scai/input_output.log");
+        this.logLine("RUN", "complete", stopRun());
         /*  console.log("\n[DEBUG] Final MainAgent context:");
          console.dir(this.context, { depth: null, colors: true }); */
         return { query: this.query, data: {} };
@@ -333,5 +329,4 @@ export function logFolderCapsulesSummary(context) {
         return body ? `${header}\n${body}` : header;
     }).join("\n\n"); // extra newline for readability
     logInputOutput('FolderCapsule summarized', 'output', context.analysis.folderCapsulesHuman = humanReadable);
-    logLine("BOOT", "folderCapsulesSummary", undefined, `📂 ${capsules.length} folders summarized`);
 }

package/dist/agents/analysisPlanGenStep.js

@@ -0,0 +1,118 @@
+// src/agents/analysisPlanGenStep.ts
+import { generate } from "../lib/generate.js";
+import { PLAN_ACTIONS } from "../utils/planActions.js";
+import { logInputOutput } from "../utils/promptLogHelper.js";
+import { cleanupModule } from "../pipeline/modules/cleanupModule.js";
+const MAX_STEPS = 100;
+/**
+ * ANALYSIS PLAN GENERATOR
+ * Generates analysis reasoning steps only.
+ */
+export const analysisPlanGenStep = {
+    name: "analysisPlanGen",
+    description: "Generates an analysis reasoning plan.",
+    requires: ["analysis.intent", "analysis.focus", "analysis.routingDecision"],
+    produces: ["analysis.planSuggestion"],
+    async run(context) {
+        context.analysis || (context.analysis = {});
+        // 🔁 Always overwrite previous planSuggestion for analysis phase
+        delete context.analysis.planSuggestion;
+        // --- Skip if routingDecision indicates task is already resolved ---
+        if (context.analysis.routingDecision?.decision === "has-info") {
+            context.analysis.planSuggestion = { plan: { steps: [] } };
+            logInputOutput("analysisPlanGen", "output", { steps: [] });
+            return;
+        }
+        // Restrict actions to ANALYSIS only
+        const effectiveActions = PLAN_ACTIONS.filter(a => a.groups?.includes("analysis"));
+        if (!effectiveActions.length) {
+            context.analysis.planSuggestion = { plan: { steps: [] } };
+            logInputOutput("analysisPlanGen", "output", { steps: [] });
+            return;
+        }
+        const actionsJson = JSON.stringify(effectiveActions, null, 2);
+        const intentText = context.analysis.intent?.normalizedQuery ??
+            context.initContext?.userQuery ??
+            "";
+        const intentCategory = context.analysis.intent?.intentCategory ?? "";
+        const relevantFiles = JSON.stringify(context.analysis.focus?.relevantFiles ?? [], null, 2);
+        const rationaleText = context.analysis.focus?.rationale ?? "";
+        const understandingText = context.analysis.understanding
+            ? JSON.stringify(context.analysis.understanding, null, 2)
+            : "";
+        const prompt = `
+You are an autonomous coding agent.
+Your task is to produce a structured plan describing what analysis or reasoning
+steps are required to understand the codebase well enough to safely plan transformations.
+
+Intent / task description:
+${intentText}
+
+Task category:
+${intentCategory}
+
+Allowed actions (analysis only):
+${actionsJson}
+
+Existing relevant files:
+${relevantFiles}
+
+Rationale / notes from pre-file check:
+${rationaleText}
+
+Existing understanding of the codebase:
+${understandingText}
+
+If the intent indicates that this is NOT a coding, refactoring, or inline commenting task,
+then return an empty plan object with an empty "steps" array:
+{ "steps": [] }
+
+Return a strictly valid JSON plan:
+
+{
+  "steps": [
+    {
+      "action": "analysisAction",
+      "targetFile": "optional/path.ts",
+      "description": "what this analysis step achieves",
+      "metadata": {}
+    }
+  ]
+}
+    `.trim();
+        try {
+            logInputOutput('analysis prompt', 'output', prompt);
+            const genInput = { query: intentText, content: prompt };
+            const genOutput = await generate(genInput);
+            const raw = typeof genOutput.data === "string"
+                ? genOutput.data
+                : JSON.stringify(genOutput.data ?? "{}");
+            const cleaned = await cleanupModule.run({ query: intentText, content: raw });
+            const jsonString = typeof cleaned.content === "string"
+                ? cleaned.content
+                : JSON.stringify(cleaned.content ?? "{}");
+            let plan = JSON.parse(jsonString);
+            if (!plan || !Array.isArray(plan.steps)) {
+                throw new Error("Invalid analysis plan structure");
+            }
+            if (plan.steps.length > MAX_STEPS) {
+                plan.steps = plan.steps.slice(0, MAX_STEPS);
+            }
+            plan.steps = plan.steps.map((step) => {
+                const actionDef = PLAN_ACTIONS.find(a => a.action === step.action);
+                return {
+                    ...step,
+                    groups: actionDef?.groups ?? ["analysis"],
+                    metadata: step.metadata ?? {}
+                };
+            });
+            context.analysis.planSuggestion = { plan };
+            logInputOutput("analysisPlanGen", "output", plan);
+        }
+        catch (err) {
+            console.warn("⚠️ Failed to generate analysis plan:", err);
+            context.analysis.planSuggestion = { plan: { steps: [] } };
+            logInputOutput("analysisPlanGen", "output", { steps: [] });
+        }
+    }
+};

package/dist/agents/contextReviewStep.js

@@ -49,6 +49,8 @@ Decision meanings:
 User Intent:
 ${JSON.stringify(intent, null, 2)}
 
+Plan Suggestion Status: ${planDecision}
+
 Relevant Files (paths only):
 ${JSON.stringify(focus.relevantFiles, null, 2)}
 
@@ -61,7 +63,6 @@ ${focus.rationale ?? "No rationale provided."}
 Relevant File Summaries (high-signal only):
 ${JSON.stringify(summarizedFiles, null, 2)}
 
-Plan Suggestion Status: ${planDecision}
 
 Question:
 Based on the above, is there enough information to answer the user's question directly?
@@ -74,7 +75,6 @@ Output STRICT JSON with shape:
   "missing": string[]
 }
 `.trim();
-    logInputOutput("contextReviewStep", "output", prompt);
     const ai = await generate({
         query: context.initContext?.userQuery ?? "",
         content: prompt,

package/dist/agents/{preFileSearchCheckStep.js → fileCheckStep.js}

@@ -2,7 +2,8 @@
 import { generate } from "../lib/generate.js";
 import { logInputOutput } from "../utils/promptLogHelper.js";
 import { cleanupModule } from "../pipeline/modules/cleanupModule.js";
-export async function preFileSearchCheckStep(context) {
+import path from "path";
+export async function fileCheckStep(context) {
     var _a;
     context.analysis ?? (context.analysis = {});
     (_a = context.analysis).focus ?? (_a.focus = { relevantFiles: [], missingFiles: [], rationale: "" });
@@ -13,11 +14,23 @@ export async function preFileSearchCheckStep(context) {
     // Step 2: extract file names from normalizedQuery or planSuggestion
     const extractedFiles = extractFilesFromAnalysis(context.analysis);
     // Step 3: populate focus with safe defaults
-    const relevantFiles = extractedFiles.filter(f => knownFiles.has(f));
-    const missingFiles = extractedFiles.filter(f => !knownFiles.has(f));
+    const relevantFiles = [];
+    const missingFiles = [];
+    for (const file of extractedFiles) {
+        // Try to find full path in knownFiles by matching basename
+        const matchedPath = [...knownFiles].find(f => path.basename(f) === file);
+        if (matchedPath) {
+            relevantFiles.push(matchedPath);
+        }
+        else {
+            // Store as full path if possible, here just keeping relative for now
+            missingFiles.push(file);
+        }
+    }
     context.analysis.focus.relevantFiles = relevantFiles;
     context.analysis.focus.missingFiles = missingFiles;
-    context.analysis.focus.rationale = `Pre-check: ${relevantFiles.length} files already available, ${missingFiles.length} missing.`;
+    context.analysis.focus.rationale =
+        `Pre-check: ${relevantFiles.length} files already available, ${missingFiles.length} missing.`;
     // Optional: LLM call for semantic understanding (assumptions, constraints, risks)
     const prompt = `
 You are an AI meta-agent assisting with context verification. The user intent and plan suggestion are below.
@@ -77,15 +90,25 @@ Task:
             console.warn("[preFileSearchCheckStep] Failed to parse cleanup output, using defaults", parseErr);
         }
         // Merge parsed output safely
-        context.analysis.focus.relevantFiles = Array.isArray(parsed.relevantFiles)
-            ? parsed.relevantFiles
-            : context.analysis.focus.relevantFiles;
-        context.analysis.focus.missingFiles = Array.isArray(parsed.missingFiles)
-            ? parsed.missingFiles
-            : context.analysis.focus.missingFiles;
-        context.analysis.focus.rationale = typeof parsed.rationale === "string"
-            ? parsed.rationale
-            : context.analysis.focus.rationale;
+        if (Array.isArray(parsed.relevantFiles)) {
+            const existing = new Set(context.analysis.focus.relevantFiles);
+            context.analysis.focus.relevantFiles = [
+                ...context.analysis.focus.relevantFiles,
+                ...parsed.relevantFiles.filter((f) => !existing.has(f))
+            ];
+        }
+        if (Array.isArray(parsed.missingFiles)) {
+            const existing = new Set(context.analysis.focus.missingFiles);
+            context.analysis.focus.missingFiles = [
+                ...context.analysis.focus.missingFiles,
+                ...parsed.missingFiles.filter((f) => !existing.has(f))
+            ];
+        }
+        if (typeof parsed.rationale === "string") {
+            context.analysis.focus.rationale =
+                (context.analysis.focus.rationale ?? "") +
+                    "\n[Post-check] " + parsed.rationale;
+        }
         if (parsed.understanding && typeof parsed.understanding === "object") {
             context.analysis.understanding = {
                 ...context.analysis.understanding,

package/dist/agents/finalPlanGenStep.js

@@ -14,10 +14,9 @@ export const finalPlanGenStep = {
     requires: ['analysis.intent', 'analysis.focus'],
     produces: ['analysis.planSuggestion'],
     async run(context) {
-        var _a, _b;
         context.analysis || (context.analysis = {});
-        (_a = context.analysis).planSuggestion || (_a.planSuggestion = {});
-        (_b = context.analysis.planSuggestion).plan || (_b.plan = { steps: [] });
+        // 🔁 Always overwrite any previous planSuggestion
+        delete context.analysis.planSuggestion;
         // Only allow actions in the FINALIZE group
         const effectiveActions = PLAN_ACTIONS.filter(a => a.groups?.includes('finalize'));
         const actionsJson = JSON.stringify(effectiveActions, null, 2);
@@ -62,11 +61,9 @@ Example format:
             const cleaned = await cleanupModule.run({ query: intentText, content: raw });
             let plan = null;
             if (cleaned.data && typeof cleaned.data === 'object') {
-                // ✅ cleanup succeeded
                 plan = cleaned.data;
             }
             else if (typeof cleaned.data === 'string') {
-                // ⚠️ fallback: try extracting JSON
                 const match = cleaned.data.match(/\{[\s\S]*\}/);
                 if (match) {
                     plan = JSON.parse(match[0]);
@@ -75,10 +72,9 @@ Example format:
             if (!plan || !Array.isArray(plan.steps)) {
                 throw new Error('Invalid final plan structure');
             }
-            if (!plan || !Array.isArray(plan.steps))
-                throw new Error('Invalid final plan structure');
-            if (plan.steps.length > MAX_STEPS)
+            if (plan.steps.length > MAX_STEPS) {
                 plan.steps = plan.steps.slice(0, MAX_STEPS);
+            }
             // Map groups & metadata
             plan.steps = plan.steps.map(step => {
                 const actionDef = PLAN_ACTIONS.find(a => a.action === step.action);
@@ -91,7 +87,7 @@ Example format:
                     groups: actionDef?.groups ?? ['finalize']
                 };
             });
-            // Ensure at least one finalAnswer step if plan is empty
+            // Ensure at least one finalAnswer step
             if (!plan.steps.some(s => s.action === 'finalAnswer')) {
                 plan.steps.push({
                     action: 'finalAnswer',
@@ -102,26 +98,29 @@ Example format:
                     groups: ['finalize']
                 });
             }
-            // Replace existing finalize steps in planSuggestion
-            context.analysis.planSuggestion.plan.steps = [
-                ...context.analysis.planSuggestion.plan.steps.filter(s => !s.groups?.includes('finalize')),
-                ...plan.steps
-            ];
+            // 🔁 Replace planSuggestion entirely for this phase
+            context.analysis.planSuggestion = {
+                plan
+            };
             logInputOutput('finalPlanGen', 'output', plan);
         }
         catch (err) {
             console.warn('⚠️ Failed to generate final plan:', err);
             // Fallback: always include finalAnswer
-            context.analysis.planSuggestion.plan.steps = [
-                {
-                    action: 'finalAnswer',
-                    description: 'Generate final user-facing response summarizing results.',
-                    metadata: {
-                        routingConfidence: context.analysis?.routingDecision?.confidence ?? 0
-                    },
-                    groups: ['finalize']
+            context.analysis.planSuggestion = {
+                plan: {
+                    steps: [
+                        {
+                            action: 'finalAnswer',
+                            description: 'Generate final user-facing response summarizing results.',
+                            metadata: {
+                                routingConfidence: context.analysis?.routingDecision?.confidence ?? 0
+                            },
+                            groups: ['finalize']
+                        }
+                    ]
                 }
-            ];
+            };
             logInputOutput('finalPlanGen', 'output', context.analysis.planSuggestion.plan);
         }
     }