scai 0.1.172 → 0.1.174

package/dist/agents/MainAgent.js

@@ -16,6 +16,7 @@ import { validateChangesStep } from './validateChangesStep.js';
 import { reasonNextTaskStep } from './reasonNextTaskStep.js';
 import { collaboratorStep } from './collaboratorStep.js';
 import { integrateFeedbackStep } from './integrateFeedbackStep.js';
+import { researchPlanGenStep } from "./researchPlanGenStep.js";
 import { selectRelevantSourcesStep } from "./selectRelevantSourcesStep.js";
 import { iterationFileSelector } from "./iterationFileSelector.js";
 import { finalAnswerModule } from "../pipeline/modules/finalAnswerModule.js";
@@ -26,8 +27,10 @@ import { NUM_TOPFILES, RELATED_FILES_LIMIT } from "../constants.js";
 import { structuralPreloadStep } from "./structuralPreloadStep.js";
 import { extractFileReferences } from "../utils/extractFileReferences.js";
 import { PREFILTER_STOP_WORDS } from "../fileRules/stopWords.js";
+import { MAX_WELL_KNOWN_REPO_FILES, WELL_KNOWN_REPO_FILE_BASENAMES } from "../fileRules/wellKnownRepoFiles.js";
 import chalk from "chalk";
 import path from "path";
+import fs from "fs";
 /* ───────────────────────── registry ───────────────────────── */
 const MODULE_REGISTRY = Object.fromEntries(Object.entries(builtInModules).map(([name, mod]) => [name, mod]));
 function resolveModuleForAction(action) {
@@ -66,9 +69,14 @@ export class MainAgent {
             this.runCount = 0;
             await this.runBoot();
             await this.runScope();
-            await this.runInitialRetrieval();
-            await this.runGrounding();
-            await this.runWorkLoop();
+            await this.runSearch();
+            await this.runVerify();
+            await this.runResearch();
+            const canProceedToExecution = this.isResearchGateSatisfied();
+            if (canProceedToExecution) {
+                await this.runPlan();
+                await this.runWorkLoop();
+            }
             await this.runFinalize();
         }
         finally {
@@ -100,12 +108,16 @@ export class MainAgent {
         await routingDecisionStep.run(this.context);
         const routing = this.context.analysis?.routingDecision;
         if (routing) {
-            this.logLine("TASK", "Routing decision", undefined, `${routing.decision} | search=${routing.allowSearch} | transform=${routing.allowTransform} | scopeLocked=${routing.scopeLocked}`);
+            this.logLine("TASK", "Routing decision", undefined, `${routing.decision} | search=${routing.allowSearch} | research=${routing.allowResearch} | transform=${routing.allowTransform} | scopeLocked=${routing.scopeLocked}`);
         }
         this.logLine("TASK", "Scope classification complete");
     }
-    /* ───────────── initial retrieval ───────────── */
-    async runInitialRetrieval() {
+    /* ───────────── search ───────────── */
+    /**
+     * Seeds initial candidate files using semantic retrieval + deterministic prefilter.
+     * Example: query mentions "MainAgent" -> relatedFiles are narrowed before grounding.
+     */
+    async runSearch() {
         const { rawUserQuery, retrievalQuery } = this.resolveInitialRetrievalQueries();
         const t = this.startTimer();
         try {
@@ -114,20 +126,29 @@ export class MainAgent {
             const seededContext = await buildLightContext(promptArgs);
             const mergedRelatedCount = this.mergeSeededInitialContext(rawUserQuery, seededContext);
             const prefilter = this.applyDeterministicPreGroundingPrefilter(retrievalQuery);
-            this.logLine("ANALYSIS", "initialRetrieval", t(), `${results.length} result(s), ${mergedRelatedCount} candidate file(s), prefilter ${prefilter.before} -> ${prefilter.after}`);
+            const repoDefaults = this.injectWellKnownRepoFiles(prefilter.after);
+            this.logLine("ANALYSIS", "initialRetrieval", t(), `${results.length} result(s), ${mergedRelatedCount} candidate file(s), prefilter ${prefilter.before} -> ${prefilter.after}, defaults +${repoDefaults.added} (${repoDefaults.reason})`);
         }
         catch (err) {
             this.logLine("ANALYSIS", "initialRetrieval", t(), `failed: ${String(err)}`);
         }
     }
-    /* ───────────── grounding ───────────── */
-    async runGrounding() {
+    /* ───────────── verify ───────────── */
+    /**
+     * Wave-based verify loop (evidence -> readiness -> optional info acquisition).
+     * Example: if readiness stays not-ready, run an info plan and try another wave.
+     */
+    async runVerify() {
         let ready = false;
         const maxGroundingWaves = this.getGroundingWaveBudget();
         let groundingWave = 0;
+        let stagnantWaves = 0;
+        const MAX_STAGNANT_WAVES = 2;
         while (groundingWave < maxGroundingWaves) {
             groundingWave++;
+            this.pruneMissingVerifyPaths();
             this.logLine("ANALYSIS", "groundingWave", undefined, `wave ${groundingWave}/${maxGroundingWaves}`);
+            const beforeFocus = this.captureVerifyFocusSnapshot();
             // ---------------- EVIDENCE PIPELINE ----------------
             // -------- STRUCTURAL PRELOAD --------
             const t0 = this.startTimer();
@@ -151,57 +172,276 @@ export class MainAgent {
                 break;
             }
             // ---------------- INFORMATION ACQUISITION ----------------
-            if (this.canExecutePhase("planning") &&
+            const canRouteSearchExpansion = this.canExecuteRoute("search-expand");
+            if (!canRouteSearchExpansion) {
+                this.logLine("PLAN", "infoPlanGen", undefined, "skipped (routing disallows search expansion)", { highlight: false });
+            }
+            else if (this.canExecutePhase("planning") &&
                 this.canExecuteScope("planning")) {
                 const t = this.startTimer();
                 await infoPlanGenStep.run(this.context);
                 const infoPlan = this.context.analysis?.planSuggestion?.plan ?? { steps: [] };
-                // If we are about to execute a new info acquisition wave,
-                // wipe previous search results.
-                if (infoPlan.steps.length > 0 && this.context.initContext && this.context.analysis?.focus) {
-                    this.context.initContext.relatedFiles = [];
-                    this.context.analysis.focus.candidateFiles = [];
-                }
                 for (const step of infoPlan.steps) {
                     const stepIO = { query: this.query };
                     await this.executeStep(step, stepIO);
                 }
                 this.logLine("PLAN", "infoPlanGen", t(), undefined, { highlight: false });
             }
+            const afterFocus = this.captureVerifyFocusSnapshot();
+            const hasFocusGrowth = this.logVerifyFocusDelta(beforeFocus, afterFocus);
+            stagnantWaves = hasFocusGrowth ? 0 : stagnantWaves + 1;
+            if (this.shouldStopVerifyForSaturation(stagnantWaves, MAX_STAGNANT_WAVES))
+                break;
             this.logLine("HASINFO", "Not ready — looping back to evidence collection", undefined, undefined, { highlight: false });
         }
-        const selectedFiles = this.context.analysis?.focus?.selectedFiles ?? [];
-        if (selectedFiles.length > 0) {
-            this.context.analysis.readiness.decision = "ready";
-            this.logLine("ANALYSIS", "readinessOverrideFromSelectedFiles", undefined, `${selectedFiles.length} selected file(s) available after grounding`);
+        // Grounding is the phase boundary that decides whether execution may start.
+        if (!this.isWorkLoopReady())
+            return;
+        this.ensureTaskForWorkLoop();
+        this.recalibrateRoutingAfterVerify();
+        // Research gate is evaluated after runResearch() in run().
+    }
+    /* ───────────── research ───────────── */
+    /**
+     * Seeds explicit research task steps for complex repo-wide lanes.
+     * Example: enqueue research-impact-map, research-symbol-trace, and research-risk-check.
+     */
+    async runResearch() {
+        var _a, _b;
+        if (!this.canExecuteRoute("research")) {
+            this.logLine("RESEARCH", "taskStepSeed", undefined, "skipped (route disallows research)");
+            return;
         }
+        if (!this.context.task)
+            return;
+        (_a = this.context.task).taskSteps || (_a.taskSteps = []);
+        await researchPlanGenStep.run(this.context);
+        const generatedSteps = (this.context.analysis?.planSuggestion?.plan?.steps ?? [])
+            .filter(step => typeof step.action === "string" && step.action.startsWith("research-"))
+            .map(step => {
+            const action = step.action;
+            const defaultFilePath = action === "research-impact-map"
+                ? "__research__/impact-map"
+                : action === "research-symbol-trace"
+                    ? "__research__/symbol-trace"
+                    : action === "research-risk-check"
+                        ? "__research__/risk-check"
+                        : "__research__/architecture-synthesis";
+            return {
+                action,
+                filePath: step.targetFile || defaultFilePath,
+                notes: step.description || `Run ${step.action}`,
+            };
+        });
+        const fallbackResearchSteps = [
+            {
+                action: "research-impact-map",
+                filePath: "__research__/impact-map",
+                notes: "Map cross-file impact before code changes.",
+            },
+            {
+                action: "research-symbol-trace",
+                filePath: "__research__/symbol-trace",
+                notes: "Trace key symbols across related files.",
+            },
+            {
+                action: "research-risk-check",
+                filePath: "__research__/risk-check",
+                notes: "Record risks, assumptions, and constraints before edits.",
+            },
+            {
+                action: "research-architecture-synthesis",
+                filePath: "__research__/architecture-synthesis",
+                notes: "Synthesize architecture summary, shared patterns, hotspots, and coupling points.",
+            },
+        ];
+        const researchSteps = generatedSteps.length > 0 ? generatedSteps : fallbackResearchSteps;
+        let seededCount = 0;
+        for (const step of researchSteps) {
+            const exists = this.context.task.taskSteps.some(s => s.filePath === step.filePath && s.action === step.action);
+            if (exists)
+                continue;
+            this.context.task.taskSteps.push({
+                taskId: this.context.task.id,
+                filePath: step.filePath,
+                action: step.action,
+                status: "pending",
+                notes: step.notes,
+                result: { phase: "research", seededBy: "runResearch" },
+            });
+            seededCount++;
+        }
+        const plannedResearchSteps = this.context.task.taskSteps
+            .filter(s => typeof s.action === "string" && s.action.startsWith("research-"))
+            .map(s => ({
+            action: s.action,
+            filePath: s.filePath,
+            status: s.status,
+            notes: s.notes,
+        }));
+        logInputOutput("runResearch", "output", {
+            source: generatedSteps.length > 0 ? "generated" : "fallback",
+            seededCount,
+            totalResearchSteps: plannedResearchSteps.length,
+            steps: plannedResearchSteps,
+        });
+        (_b = this.context).analysis || (_b.analysis = {});
+        this.context.analysis.planSuggestion = undefined;
+        this.logLine("RESEARCH", "taskStepSeed", undefined, `${seededCount} research step(s) added (${generatedSteps.length > 0 ? "generated" : "fallback"})`);
     }
+    /* ───────────── plan ───────────── */
     /**
-     * Resolves grounding wave budget from current routing metadata.
-     * Example: scope=repo-wide + decision=needs-info => 4 waves.
+     * Seeds ordered execution task steps from selected files + research/verify artifacts.
+     * Example: prioritize files that are both selected and research-touched.
      */
-    getGroundingWaveBudget() {
+    async runPlan() {
+        var _a, _b;
+        if (!this.context.task)
+            return;
+        if (!this.canExecutePhase("planning") || !this.canExecuteScope("planning"))
+            return;
+        (_a = this.context).analysis || (_a.analysis = {});
+        (_b = this.context.task).taskSteps || (_b.taskSteps = []);
+        const existingExecutionPaths = new Set(this.context.task.taskSteps
+            .filter(step => !!step.filePath &&
+            !step.filePath.startsWith("__research__/"))
+            .map(step => step.filePath));
+        const selectedFiles = this.context.analysis.focus?.selectedFiles ?? [];
+        const touchedFromResearch = this.context.analysis.researchArtifacts?.touchedFiles ?? [];
+        const route = this.context.analysis.routingDecision;
+        const useFocusedSelectedPlanOnly = this.context.analysis.readiness?.decision === "ready" &&
+            (route?.decision === "has-info") &&
+            (route?.scopeLocked ?? false) &&
+            (route?.allowSearch === false) &&
+            selectedFiles.length > 0;
+        const verifyMinConfidence = this.getVerifyConfidenceThresholdForPlan();
+        const verifyEntries = Object.entries(this.context.analysis.verify?.byFile ?? {});
+        const verifyRelevantFiles = verifyEntries
+            .filter(([_, verify]) => verify?.isRelevant &&
+            (verify.fileConfidence ?? 0) >= verifyMinConfidence)
+            .map(([filePath]) => filePath);
+        const verifySkippedLowConfidenceCount = verifyEntries.filter(([_, verify]) => !!verify?.isRelevant &&
+            (verify.fileConfidence ?? 0) < verifyMinConfidence).length;
+        const rankPath = (filePath) => {
+            const inSelected = selectedFiles.includes(filePath);
+            const inResearchTouched = touchedFromResearch.includes(filePath);
+            const inVerify = verifyRelevantFiles.includes(filePath);
+            if (inSelected && inResearchTouched)
+                return 0;
+            if (inSelected)
+                return 1;
+            if (inResearchTouched)
+                return 2;
+            if (inVerify)
+                return 3;
+            return 4;
+        };
+        const plannedPathsSource = useFocusedSelectedPlanOnly
+            ? Array.from(new Set(selectedFiles))
+            : Array.from(new Set([
+                ...selectedFiles,
+                ...touchedFromResearch,
+                ...verifyRelevantFiles,
+            ]));
+        const plannedPaths = plannedPathsSource
+            .filter(filePath => !!filePath && !filePath.startsWith("__research__/") && fs.existsSync(filePath))
+            .sort((a, b) => rankPath(a) - rankPath(b))
+            .slice(0, 16);
+        let seededCount = 0;
+        const seeded = [];
+        for (const filePath of plannedPaths) {
+            if (existingExecutionPaths.has(filePath))
+                continue;
+            const rank = rankPath(filePath);
+            const notes = rank === 0
+                ? "Plan priority: selected + research-touched"
+                : rank === 1
+                    ? "Plan priority: selected file"
+                    : rank === 2
+                        ? "Plan priority: research-touched file"
+                        : "Plan priority: verify-relevant file";
+            this.context.task.taskSteps.push({
+                taskId: this.context.task.id,
+                filePath,
+                status: "pending",
+                notes,
+                result: {
+                    phase: "plan",
+                    seededBy: "runPlan",
+                    priorityRank: rank,
+                },
+            });
+            seeded.push({ filePath, rank, notes });
+            seededCount++;
+        }
+        logInputOutput("runPlan", "output", {
+            seededCount,
+            totalPlannedPaths: plannedPaths.length,
+            selectedFileCount: selectedFiles.length,
+            researchTouchedCount: touchedFromResearch.length,
+            verifyRelevantCount: verifyRelevantFiles.length,
+            focusedSelectedOnly: useFocusedSelectedPlanOnly,
+            verifyMinConfidence,
+            verifySkippedLowConfidenceCount,
+            seeded,
+        });
+        this.logLine("PLAN", "taskStepSeed", undefined, `${seededCount} execution step(s) planned`);
+    }
+    /**
+     * Sets minimum verify confidence before a file can be plan-seeded from verify-only signal.
+     * Example: single-file lanes require higher confidence than repo-wide lanes.
+     */
+    getVerifyConfidenceThresholdForPlan() {
         const scope = this.context.analysis?.scopeType ?? "repo-wide";
-        const decision = this.context.analysis?.routingDecision?.decision ?? "has-info";
-        const allowSearch = this.context.analysis?.routingDecision?.allowSearch ?? true;
-        let budget = 2;
-        if (!allowSearch || scope === "none")
-            budget = 1;
-        else if (scope === "single-file" && decision === "has-info")
-            budget = 2;
-        else if (scope === "multi-file")
-            budget = 3;
-        else if (scope === "repo-wide" && decision === "needs-info")
-            budget = 4;
-        this.logLine("ANALYSIS", "groundingBudget", undefined, `scope=${scope}, decision=${decision}, search=${allowSearch}, maxWaves=${budget}`);
-        return budget;
+        if (scope === "single-file")
+            return 0.45;
+        if (scope === "multi-file")
+            return 0.35;
+        return 0.3;
+    }
+    /**
+     * Re-routes after verify when evidence converges on selected files with high confidence.
+     * Example: selected files strongly verified => disable expansion/research and lock focused execution.
+     */
+    recalibrateRoutingAfterVerify() {
+        var _a;
+        (_a = this.context).analysis || (_a.analysis = {});
+        const routing = this.context.analysis.routingDecision;
+        if (!routing)
+            return;
+        const selectedFiles = this.context.analysis.focus?.selectedFiles ?? [];
+        if (selectedFiles.length === 0)
+            return;
+        const readinessConfidence = this.context.analysis.readiness?.confidence ?? 0;
+        const intentConfidence = this.context.analysis.intent?.confidence ?? 0;
+        const minFileConfidence = 0.28;
+        const strongSelected = selectedFiles.filter(filePath => {
+            const verify = this.context.analysis?.verify?.byFile?.[filePath];
+            return verify?.isRelevant === true && (verify.fileConfidence ?? 0) >= minFileConfidence;
+        });
+        const convergedSingle = selectedFiles.length === 1 &&
+            strongSelected.length === 1 &&
+            readinessConfidence >= 0.9 &&
+            intentConfidence >= 0.8;
+        const convergedMulti = selectedFiles.length >= 2 &&
+            strongSelected.length >= 2 &&
+            readinessConfidence >= 0.9 &&
+            intentConfidence >= 0.75;
+        if (!convergedSingle && !convergedMulti)
+            return;
+        routing.decision = "has-info";
+        routing.allowSearch = false;
+        routing.allowResearch = false;
+        routing.scopeLocked = true;
+        routing.rationale = `${routing.rationale}; postVerify=focused-selection(${strongSelected.length})`;
+        this.logLine("TASK", "Routing recalibrated", undefined, `focused=${selectedFiles.length} selected, strong=${strongSelected.length}`);
     }
     /* ───────────── work loop ───────────── */
     async runWorkLoop() {
-        if (!this.isWorkLoopReady())
+        if (this.context.task.status !== "active")
             return;
         this.ensureTaskForWorkLoop();
-        const MAX_TASK_STEPS = 5;
+        const MAX_TASK_STEPS = this.getTaskStepBudget();
         let stepCount = 0;
         while (stepCount < MAX_TASK_STEPS &&
             this.context.task.status === "active") {
@@ -232,7 +472,17 @@ export class MainAgent {
         }
         this.logLine("TASK", "Max task step limit reached — stopping work loop", undefined, undefined, { highlight: false });
     }
+    /* ───────────── finalize ───────────── */
+    async runFinalize() {
+        await finalAnswerModule.run({ query: this.query, context: this.context });
+        persistTaskData(this.context, this.taskId, getDbForRepo(), this.logLine.bind(this));
+        this.logLine("TASK", "Finalize complete", undefined, undefined, { highlight: false });
+    }
     /* ───────────── step iterations ───────────── */
+    /**
+     * Iterates one task step until it completes, needs feedback, or asks for redo.
+     * Example: validation failure sets nextAction=redo-step and re-runs iteration.
+     */
     async runStepIterations(taskStep) {
         const MAX_ITERATIONS = 5;
         let loopCount = 0;
@@ -261,9 +511,17 @@ export class MainAgent {
         return "continue";
     }
     /* ───────────── work iteration ───────────── */
+    /**
+     * Executes one analyze/transform/validate pass for the current task step.
+     * Example: generate analysis plan, run one transform step, then validate.
+     */
     async runWorkIteration(taskStep) {
         if (!this.context.analysis)
             this.context.analysis = {};
+        if (taskStep.action?.startsWith("research-")) {
+            await this.executeResearchTaskStep(taskStep);
+            return;
+        }
         if (this.canExecutePhase("analysis") && this.canExecuteScope("analysis")) {
             const tAnalysis = this.startTimer();
             await analysisPlanGenStep.run(this.context);
@@ -309,6 +567,375 @@ export class MainAgent {
         await integrateFeedbackStep.run(this.context);
         this.logLine("FEEDBACK", "integrateFeedbackStep", tIntegrate());
     }
+    /**
+     * Executes deterministic research steps and marks them complete.
+     * Example: research-impact-map summarizes affected files and seeds understanding notes.
+     */
+    async executeResearchTaskStep(taskStep) {
+        var _a, _b;
+        const selectedFiles = this.context.analysis?.focus?.selectedFiles ?? [];
+        const candidateFiles = this.context.analysis?.focus?.candidateFiles ?? [];
+        const fileAnalysis = this.context.analysis?.fileAnalysis ?? {};
+        const researchTerms = this.buildResearchTerms();
+        const researchPaths = this.collectResearchPaths(24);
+        const corpus = this.loadResearchCorpus(researchPaths, 12, 12000);
+        const understanding = (_b = ((_a = this.context).analysis || (_a.analysis = {}))).understanding || (_b.understanding = {
+            assumptions: [],
+            constraints: [],
+            risks: [],
+            sharedPatterns: [],
+            hotspots: [],
+            couplingPoints: [],
+        });
+        const addUnique = (arr, value) => {
+            if (!arr)
+                return;
+            if (!arr.includes(value))
+                arr.push(value);
+        };
+        let summary = "";
+        let collectedData = {
+            selectedFiles: selectedFiles.slice(0, 12),
+            selectedFileCount: selectedFiles.length,
+            candidateFileCount: candidateFiles.length,
+            researchTerms,
+            corpusFilesRead: corpus.length,
+            corpusPaths: corpus.map(f => f.path).slice(0, 12),
+        };
+        switch (taskStep.action) {
+            case "research-impact-map": {
+                const touched = selectedFiles.length;
+                const impactRows = corpus
+                    .map(file => {
+                    const termHits = this.computeTermHits(file.content, researchTerms);
+                    const termHitTotal = Object.values(termHits).reduce((acc, n) => acc + n, 0);
+                    const importCount = this.countRegex(file.content, /\bimport\b|\brequire\s*\(/g);
+                    const exportCount = this.countRegex(file.content, /\bexport\b|module\.exports/g);
+                    const score = termHitTotal * 3 + importCount * 2 + exportCount;
+                    return {
+                        filePath: file.path,
+                        score,
+                        termHits,
+                        importCount,
+                        exportCount,
+                        lineCount: file.lineCount,
+                    };
+                })
+                    .sort((a, b) => b.score - a.score)
+                    .slice(0, 8);
+                summary = `Impact map across ${touched} selected file(s).`;
+                addUnique(understanding.constraints, `Refactor impact spans ${touched} file(s).`);
+                collectedData = {
+                    ...collectedData,
+                    touchedFiles: selectedFiles.slice(0, 20),
+                    impactSignals: [
+                        `selected=${selectedFiles.length}`,
+                        `candidates=${candidateFiles.length}`,
+                    ],
+                    impactMap: impactRows,
+                };
+                break;
+            }
+            case "research-symbol-trace": {
+                const structuralSymbols = Object.values(fileAnalysis)
+                    .flatMap(fa => fa.structural?.functions?.map(fn => fn.name).filter(Boolean) ?? [])
+                    .slice(0, 24);
+                const fallbackSymbols = corpus
+                    .flatMap(file => Array.from(file.content.matchAll(/\b(function|class|const|let|var)\s+([A-Za-z_]\w*)/g)).map(m => m[2]))
+                    .filter(Boolean);
+                const symbolPool = Array.from(new Set([...structuralSymbols, ...fallbackSymbols])).slice(0, 18);
+                const traceRows = symbolPool
+                    .map(symbol => {
+                    const escaped = symbol.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+                    const re = new RegExp(`\\b${escaped}\\b`, "g");
+                    const files = corpus
+                        .map(file => ({ filePath: file.path, count: this.countRegex(file.content, re) }))
+                        .filter(item => item.count > 0);
+                    return {
+                        symbol,
+                        occurrenceCount: files.reduce((acc, f) => acc + f.count, 0),
+                        files: files.slice(0, 8),
+                    };
+                })
+                    .filter(row => row.occurrenceCount > 0)
+                    .sort((a, b) => b.occurrenceCount - a.occurrenceCount)
+                    .slice(0, 10);
+                summary = traceRows.length
+                    ? `Traced ${traceRows.length} symbol(s) from corpus.`
+                    : "No structural symbols found; symbol trace used filename-level anchors.";
+                addUnique(understanding.assumptions, "Symbol trace coverage is partial and based on current selected files.");
+                collectedData = {
+                    ...collectedData,
+                    tracedSymbols: traceRows.map(s => s.symbol),
+                    symbolTrace: traceRows,
+                    analyzedFileCount: Object.values(fileAnalysis).filter(fa => fa?.semanticAnalyzed).length,
+                };
+                break;
+            }
+            case "research-risk-check": {
+                const riskPatterns = [
+                    { id: "empty-catch", description: "Empty catch blocks", pattern: /catch\s*\(\s*[^)]*\)\s*\{\s*\}/g },
+                    { id: "console-error", description: "Console error logging", pattern: /\bconsole\.error\s*\(/g },
+                    { id: "forced-exit", description: "Process exit usage", pattern: /\bprocess\.exit\s*\(/g },
+                    { id: "throws-string", description: "Throwing non-Error values", pattern: /\bthrow\s+['"`]/g },
+                ];
+                const riskRows = riskPatterns
+                    .map(risk => {
+                    const perFile = corpus
+                        .map(file => ({ filePath: file.path, count: this.countRegex(file.content, risk.pattern) }))
+                        .filter(hit => hit.count > 0);
+                    return {
+                        id: risk.id,
+                        description: risk.description,
+                        totalHits: perFile.reduce((acc, hit) => acc + hit.count, 0),
+                        files: perFile.slice(0, 8),
+                    };
+                })
+                    .filter(risk => risk.totalHits > 0);
+                summary = "Recorded baseline risks/assumptions/constraints before transformation.";
+                addUnique(understanding.risks, "Cross-file regressions are possible without full symbol coverage.");
+                addUnique(understanding.risks, "Validation should run after each transform step.");
+                for (const risk of riskRows) {
+                    addUnique(understanding.risks, `${risk.description}: ${risk.totalHits} hit(s)`);
+                }
+                collectedData = {
+                    ...collectedData,
+                    risks: understanding.risks?.slice(0, 12) ?? [],
+                    assumptions: understanding.assumptions?.slice(0, 12) ?? [],
+                    constraints: understanding.constraints?.slice(0, 12) ?? [],
+                    riskSignals: riskRows,
+                };
+                break;
+            }
+            case "research-architecture-synthesis": {
+                const analyzedPaths = Object.entries(fileAnalysis)
+                    .filter(([_, fa]) => fa?.semanticAnalyzed)
+                    .map(([filePath]) => filePath);
+                const architectureFiles = (analyzedPaths.length > 0 ? analyzedPaths : corpus.map(file => file.path)).slice(0, 8);
+                understanding.problemStatement =
+                    `Summarize repository architecture and identify weak coupling points across ${selectedFiles.length} scoped file(s).`;
+                for (const p of architectureFiles) {
+                    const base = path.basename(p);
+                    if (base.toLowerCase().includes("registry")) {
+                        addUnique(understanding.hotspots, `${base}: central registry point with broad module fan-in.`);
+                        addUnique(understanding.couplingPoints, `${base}: centralized module registration coupling.`);
+                    }
+                    if (base.toLowerCase().includes("module")) {
+                        addUnique(understanding.sharedPatterns, `${base}: module-oriented pipeline pattern.`);
+                    }
+                }
+                addUnique(understanding.sharedPatterns, "Pipeline modules follow a shared Module/ModuleIO contract.");
+                addUnique(understanding.couplingPoints, "Shared config/model utilities create cross-module coupling.");
+                addUnique(understanding.hotspots, "Core orchestration and registry layers are high-impact change zones.");
+                summary = `Architecture synthesis completed from ${architectureFiles.length} analyzed file(s).`;
+                const priorResearch = (this.context.task?.taskSteps ?? [])
+                    .filter(step => step.action?.startsWith("research-") && step.status === "completed")
+                    .map(step => ({
+                    action: step.action,
+                    summary: step.result?.research?.summary,
+                }));
+                collectedData = {
+                    ...collectedData,
+                    architectureInputFiles: architectureFiles,
+                    priorResearchSummaries: priorResearch,
+                    problemStatement: understanding.problemStatement ?? "",
+                    sharedPatterns: understanding.sharedPatterns?.slice(0, 12) ?? [],
+                    hotspots: understanding.hotspots?.slice(0, 12) ?? [],
+                    couplingPoints: understanding.couplingPoints?.slice(0, 12) ?? [],
+                };
+                break;
+            }
+            default: {
+                summary = `Unknown research action: ${taskStep.action}`;
+                collectedData = {
+                    ...collectedData,
+                    warning: "No handler for research action",
+                };
+                break;
+            }
+        }
+        const completedAt = new Date().toISOString();
+        const researchEntry = {
+            action: taskStep.action,
+            summary,
+            collectedData,
+            selectedFileCount: selectedFiles.length,
+            completedAt,
+        };
+        taskStep.result || (taskStep.result = {});
+        taskStep.result.research = researchEntry;
+        taskStep.result.stepReasoning = {
+            nextAction: "complete",
+            rationale: `Research step completed: ${summary}`,
+            confidence: 0.95,
+        };
+        taskStep.status = "completed";
+        this.persistResearchArtifact(researchEntry);
+        logInputOutput("runResearchStep", "output", {
+            research: researchEntry,
+            stepReasoning: taskStep.result.stepReasoning,
+            status: taskStep.status,
+        });
+    }
+    /**
+     * Persists normalized research outputs into analysis.researchArtifacts.
+     * Example: latestByAction["research-risk-check"] stores current risk findings.
+     */
+    persistResearchArtifact(entry) {
+        var _a, _b;
+        (_a = this.context).analysis || (_a.analysis = {});
+        const store = (_b = this.context.analysis).researchArtifacts || (_b.researchArtifacts = {
+            latestByAction: {},
+            history: [],
+            touchedFiles: [],
+            lastUpdatedAt: entry.completedAt,
+        });
+        store.latestByAction || (store.latestByAction = {});
+        store.history || (store.history = []);
+        store.touchedFiles || (store.touchedFiles = []);
+        store.latestByAction[entry.action] = entry;
+        store.history.push(entry);
+        const data = entry.collectedData ?? {};
+        const touched = this.extractPathsFromResearchData(data);
+        const merged = new Set([...(store.touchedFiles ?? []), ...touched]);
+        store.touchedFiles = Array.from(merged);
+        store.lastUpdatedAt = entry.completedAt;
+    }
+    /**
+     * Extracts file paths from heterogeneous research payloads.
+     * Example: impactMap rows and architectureInputFiles are both merged into touchedFiles.
+     */
+    extractPathsFromResearchData(data) {
+        const paths = new Set();
+        const addPath = (value) => {
+            if (typeof value === "string" && value.trim().length > 0) {
+                paths.add(value);
+            }
+        };
+        const addPathArray = (value) => {
+            if (!Array.isArray(value))
+                return;
+            for (const item of value) {
+                addPath(item);
+            }
+        };
+        addPathArray(data.corpusPaths);
+        addPathArray(data.touchedFiles);
+        addPathArray(data.architectureInputFiles);
+        if (Array.isArray(data.impactMap)) {
+            for (const row of data.impactMap) {
+                addPath(row.filePath);
+            }
+        }
+        if (Array.isArray(data.symbolTrace)) {
+            for (const row of data.symbolTrace) {
+                const files = row.files;
+                if (!Array.isArray(files))
+                    continue;
+                for (const fileRow of files) {
+                    addPath(fileRow.filePath);
+                }
+            }
+        }
+        if (Array.isArray(data.riskSignals)) {
+            for (const row of data.riskSignals) {
+                const files = row.files;
+                if (!Array.isArray(files))
+                    continue;
+                for (const fileRow of files) {
+                    addPath(fileRow.filePath);
+                }
+            }
+        }
+        return Array.from(paths);
+    }
+    /**
+     * Builds lightweight query terms for deterministic research scanning.
+     * Example: "error handling test suite" -> ["error","handling","test","suite"].
+     */
+    buildResearchTerms() {
+        const query = this.context.analysis?.intent?.normalizedQuery ??
+            this.context.initContext?.userQuery ??
+            this.query;
+        const stopWords = new Set([
+            "the", "and", "for", "with", "from", "this", "that", "what", "how",
+            "is", "are", "was", "were", "can", "could", "should", "would", "into",
+            "about", "across", "repo", "codebase", "please",
+        ]);
+        return Array.from(new Set(query
+            .toLowerCase()
+            .split(/[^a-z0-9_]+/g)
+            .filter(token => token.length >= 3 && !stopWords.has(token)))).slice(0, 10);
+    }
+    /**
+     * Collects research candidate paths from selected, candidate, related, and working files.
+     * Example: selected files are prioritized before broader related file pool.
+     */
+    collectResearchPaths(maxPaths) {
+        const focus = this.context.analysis?.focus;
+        const workingPaths = (this.context.workingFiles ?? []).map(file => file.path);
+        const related = this.context.initContext?.relatedFiles ?? [];
+        const combined = [
+            ...(focus?.selectedFiles ?? []),
+            ...(focus?.candidateFiles ?? []),
+            ...workingPaths,
+            ...related,
+        ];
+        const unique = Array.from(new Set(combined));
+        return unique
+            .filter(filePath => !filePath.startsWith("__research__/") && fs.existsSync(filePath))
+            .slice(0, maxPaths);
+    }
+    /**
+     * Reads a bounded corpus from candidate paths.
+     * Example: read first 12 files, max 12k chars per file, skipping binary payloads.
+     */
+    loadResearchCorpus(filePaths, maxFiles, maxCharsPerFile) {
+        const corpus = [];
+        for (const filePath of filePaths.slice(0, maxFiles)) {
+            try {
+                const raw = fs.readFileSync(filePath, "utf-8");
+                if (raw.includes("\u0000"))
+                    continue;
+                const content = raw.slice(0, maxCharsPerFile);
+                corpus.push({
+                    path: filePath,
+                    content,
+                    lineCount: content.split("\n").length,
+                    charCount: content.length,
+                });
+            }
+            catch {
+                // Ignore unreadable files and continue.
+            }
+        }
+        return corpus;
+    }
+    /**
+     * Counts regex matches safely.
+     * Example: countRegex(code, /import/g) -> number of import occurrences.
+     */
+    countRegex(content, pattern) {
+        const source = pattern.source;
+        const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
+        const re = new RegExp(source, flags);
+        return Array.from(content.matchAll(re)).length;
+    }
+    /**
+     * Computes per-term match counts for a file body.
+     * Example: terms ["error","test"] -> { error: 4, test: 2 }.
+     */
+    computeTermHits(content, terms) {
+        const hits = {};
+        for (const term of terms) {
+            const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            const count = this.countRegex(content, new RegExp(`\\b${escaped}\\b`, "gi"));
+            if (count > 0) {
+                hits[term] = count;
+            }
+        }
+        return hits;
+    }
     /* ───────────── step executor ───────────── */
     /**
      * Executes a single step using its corresponding module.
@@ -344,13 +971,7 @@ export class MainAgent {
             throw err;
         }
     }
-    /* ───────────── finalize ───────────── */
-    async runFinalize() {
-        await finalAnswerModule.run({ query: this.query, context: this.context });
-        persistTaskData(this.context, this.taskId, getDbForRepo(), this.logLine.bind(this));
-        this.logLine("TASK", "Finalize complete", undefined, undefined, { highlight: false });
-    }
-    /* ───────────── extracted from runInitialRetrieval ───────────── */
+    /* ───────────── extracted from runSearch ───────────── */
     resolveInitialRetrievalQueries() {
         const rawUserQuery = this.context.initContext?.userQuery ?? this.query;
         const retrievalQuery = this.context.analysis?.intent?.normalizedQuery?.trim() || rawUserQuery;
@@ -391,6 +1012,8 @@ export class MainAgent {
         };
     }
     mergeSeededInitialContext(rawUserQuery, seededContext) {
+        // Merge retrieval seed into initContext without losing previously discovered files.
+        // Example: keep old relatedFiles and append newly seeded files from buildLightContext.
         const existingInit = this.context.initContext ?? { userQuery: rawUserQuery };
         const seededInit = seededContext.initContext;
         const mergedRelatedFiles = Array.from(new Set([
@@ -419,6 +1042,8 @@ export class MainAgent {
         return mergedRelatedFiles.length;
     }
     applyDeterministicPreGroundingPrefilter(retrievalQuery) {
+        // Rank and cap retrieval candidates before grounding to reduce noisy evidence passes.
+        // Example: explicit filename anchors are always kept even if BM25 score is low.
         const init = this.context.initContext;
         if (!init?.relatedFiles?.length)
             return { before: 0, after: 0 };
@@ -458,6 +1083,184 @@ export class MainAgent {
         });
         return { before, after: init.relatedFiles.length };
     }
+    injectWellKnownRepoFiles(currentCount) {
+        // Add high-signal repo root files when scope is broad or retrieval is sparse.
+        // Example: on repo-wide queries, include package.json/README if present.
+        const init = this.context.initContext;
+        if (!init)
+            return { added: 0, reason: "none" };
+        const scope = this.context.analysis?.scopeType ?? "repo-wide";
+        const shouldInjectByScope = scope === "repo-wide";
+        const shouldInjectByFallback = currentCount < 3;
+        if (!shouldInjectByScope && !shouldInjectByFallback) {
+            return { added: 0, reason: "none" };
+        }
+        const reason = shouldInjectByScope ? "scope" : "fallback";
+        const candidates = WELL_KNOWN_REPO_FILE_BASENAMES
+            .map(fileName => path.join(process.cwd(), fileName))
+            .filter(filePath => fs.existsSync(filePath))
+            .slice(0, MAX_WELL_KNOWN_REPO_FILES);
+        if (candidates.length === 0)
+            return { added: 0, reason };
+        const existing = new Set(init.relatedFiles ?? []);
+        let added = 0;
+        for (const filePath of candidates) {
+            if (existing.has(filePath))
+                continue;
+            existing.add(filePath);
+            added++;
+        }
+        init.relatedFiles = Array.from(existing);
+        return { added, reason };
+    }
+    /**
+     * Captures focus sizes before/after a verify wave for growth tracking.
+     * Example: selected=3,candidate=7 before wave; selected=4,candidate=9 after wave.
+     */
+    captureVerifyFocusSnapshot() {
+        return {
+            selected: this.context.analysis?.focus?.selectedFiles?.length ?? 0,
+            candidate: this.context.analysis?.focus?.candidateFiles?.length ?? 0,
+        };
+    }
+    /**
+     * Logs selected/candidate deltas for a verify wave and returns whether focus grew.
+     * Example: selected 3->4 (+1), candidate 7->9 (+2) => growth=true.
+     */
+    logVerifyFocusDelta(before, after) {
+        const selectedDelta = after.selected - before.selected;
+        const candidateDelta = after.candidate - before.candidate;
+        this.logLine("ANALYSIS", "groundingDelta", undefined, `selected ${before.selected}->${after.selected} (${selectedDelta >= 0 ? "+" : ""}${selectedDelta}), candidate ${before.candidate}->${after.candidate} (${candidateDelta >= 0 ? "+" : ""}${candidateDelta})`);
+        return selectedDelta > 0 || candidateDelta > 0;
+    }
+    /**
+     * Stops verify loop when focus has not grown for too many consecutive waves.
+     * Example: 2 stagnant waves in a row => stop early to avoid useless loops.
+     */
+    shouldStopVerifyForSaturation(stagnantWaves, maxStagnantWaves) {
+        if (stagnantWaves < maxStagnantWaves)
+            return false;
+        this.logLine("ANALYSIS", "groundingSaturated", undefined, `No focus growth for ${stagnantWaves} consecutive wave(s); stopping early`);
+        return true;
+    }
+    /**
+     * Drops missing files from retrieval/focus sets to avoid verifier ENOENT noise.
+     * Example: if DB points to deleted explainModule.ts, remove it before evidence pass.
+     */
+    pruneMissingVerifyPaths() {
+        const init = this.context.initContext;
+        const focus = this.context.analysis?.focus;
+        if (!init && !focus)
+            return;
+        const existsOrResearch = (filePath) => {
+            if (filePath.startsWith("__research__/"))
+                return true;
+            return fs.existsSync(filePath);
+        };
+        let removedRelated = 0;
+        let removedSelected = 0;
+        let removedCandidate = 0;
+        if (init?.relatedFiles?.length) {
+            const before = init.relatedFiles.length;
+            init.relatedFiles = init.relatedFiles.filter(existsOrResearch);
+            removedRelated = before - init.relatedFiles.length;
+            if (removedRelated > 0 && init.relatedFileScores) {
+                init.relatedFileScores = Object.fromEntries(Object.entries(init.relatedFileScores).filter(([filePath]) => init.relatedFiles?.includes(filePath)));
+            }
+        }
+        if (focus?.selectedFiles?.length) {
+            const before = focus.selectedFiles.length;
+            focus.selectedFiles = focus.selectedFiles.filter(existsOrResearch);
+            removedSelected = before - focus.selectedFiles.length;
+        }
+        if (focus?.candidateFiles?.length) {
+            const before = focus.candidateFiles.length;
+            focus.candidateFiles = focus.candidateFiles.filter(existsOrResearch);
+            removedCandidate = before - focus.candidateFiles.length;
+        }
+        if (removedRelated + removedSelected + removedCandidate > 0) {
+            this.logLine("ANALYSIS", "verifyPruneMissing", undefined, `removed related=${removedRelated}, selected=${removedSelected}, candidate=${removedCandidate}`);
+        }
+    }
+    /**
+     * Route-aware grounding budget.
+     * Example: repo-wide + needs-info => allow up to 4 verification waves.
+     */
+    getGroundingWaveBudget() {
+        const scope = this.context.analysis?.scopeType ?? "repo-wide";
+        const decision = this.context.analysis?.routingDecision?.decision ?? "has-info";
+        const allowSearch = this.context.analysis?.routingDecision?.allowSearch ?? true;
+        let budget = 2;
+        if (!allowSearch || scope === "none")
+            budget = 1;
+        else if (scope === "single-file" && decision === "has-info")
+            budget = 2;
+        else if (scope === "multi-file")
+            budget = 3;
+        else if (scope === "repo-wide" && decision === "needs-info")
+            budget = 4;
+        this.logLine("ANALYSIS", "groundingBudget", undefined, `scope=${scope}, decision=${decision}, search=${allowSearch}, maxWaves=${budget}`);
+        return budget;
+    }
+    /**
+     * Dynamic task-step cap by route complexity.
+     * Example: research-required lanes get 10 steps instead of 5.
+     */
+    getTaskStepBudget() {
+        const scope = this.context.analysis?.scopeType ?? "repo-wide";
+        if (this.canExecuteRoute("research"))
+            return 10;
+        if (scope === "multi-file")
+            return 7;
+        if (scope === "single-file")
+            return 5;
+        return 6;
+    }
+    /**
+     * Blocks execution if repo-wide complex tasks lack minimum research signal.
+     * Example: require at least two analyzed files plus one understanding signal.
+     */
+    isResearchGateSatisfied() {
+        if (!this.canExecuteRoute("research"))
+            return true;
+        const scope = this.context.analysis?.scopeType ?? "repo-wide";
+        const researchPlanCount = this.context.task?.taskSteps?.filter(s => typeof s.action === "string" && s.action.startsWith("research-")).length ?? 0;
+        const pendingResearchCount = this.context.task?.taskSteps?.filter(s => typeof s.action === "string" &&
+            s.action.startsWith("research-") &&
+            s.status !== "completed").length ?? 0;
+        const requiredResearchSteps = scope === "repo-wide"
+            ? 4
+            : scope === "multi-file"
+                ? 3
+                : 1;
+        const hasResearchPlan = researchPlanCount >= requiredResearchSteps;
+        if (!hasResearchPlan) {
+            this.context.task.status = "deferred";
+            this.context.task.reason =
+                `Research phase required before execution ` +
+                    `(scope=${scope}, researchSteps=${researchPlanCount}, required=${requiredResearchSteps})`;
+            this.persistTaskDataForRun();
+            this.logLine("TASK", "Research gate blocked work loop", undefined, this.context.task.reason, { highlight: true });
+            return false;
+        }
+        if (pendingResearchCount > 0) {
+            this.logLine("TASK", "Research gate queued", undefined, `researchSteps=${researchPlanCount}, pendingResearch=${pendingResearchCount}`);
+            return true;
+        }
+        const understanding = this.context.analysis?.understanding;
+        const understandingSignals = (understanding?.assumptions?.length ?? 0) +
+            (understanding?.constraints?.length ?? 0) +
+            (understanding?.risks?.length ?? 0);
+        if (understandingSignals > 0) {
+            this.logLine("TASK", "Research gate passed", undefined, `researchSteps=${researchPlanCount}, understandingSignals=${understandingSignals}`);
+            return true;
+        }
+        this.context.task.status = "deferred";
+        this.context.task.reason = `Research completed but produced insufficient understanding signals (${understandingSignals}).`;
+        this.persistTaskDataForRun();
+        this.logLine("TASK", "Research gate blocked work loop", undefined, this.context.task.reason, { highlight: true });
+        return false;
+    }
     /* ───────────── extracted from runWorkLoop ───────────── */
     isWorkLoopReady() {
         const readinessDecision = this.context.analysis?.readiness?.decision;
@@ -495,28 +1298,43 @@ export class MainAgent {
         taskStep.stepIndex = stepCount;
         taskStep.status = "pending";
         persistTaskStepInsert(taskStep, getDbForRepo());
-        this.logLine("NEW STEP", `Processing taskStep ${stepCount}`, undefined, taskStep.filePath, { highlight: true });
+        const displayPath = this.formatTaskStepDisplayPath(taskStep.filePath);
+        this.logLine("NEW STEP", `Processing taskStep ${stepCount}`, undefined, displayPath, { highlight: true });
         taskStep.startTime = Date.now();
         persistTaskStepStart(taskStep, getDbForRepo());
     }
     finishTaskStep(taskStep, stepCount, stepAction) {
+        const displayPath = this.formatTaskStepDisplayPath(taskStep.filePath);
         taskStep.endTime = Date.now();
         if (stepAction === "complete") {
             taskStep.status = "completed";
             persistTaskStepCompletion(taskStep, getDbForRepo());
-            this.logLine("STEP-DONE", `Completed taskStep ${stepCount}`, undefined, taskStep.filePath, { highlight: false });
+            this.logLine("STEP-DONE", `Completed taskStep ${stepCount}`, undefined, displayPath, { highlight: false });
             return;
         }
         taskStep.status = "pending";
         persistTaskStepCompletion(taskStep, getDbForRepo());
-        this.logLine("STEP", `Pending taskStep ${stepCount}`, undefined, taskStep.filePath);
+        this.logLine("STEP", `Pending taskStep ${stepCount}`, undefined, displayPath);
+    }
+    /**
+     * Normalizes internal pseudo-paths for user-facing step logs.
+     * Example: "__research__/symbol-trace" -> "research/symbol-trace".
+     */
+    formatTaskStepDisplayPath(filePath) {
+        return filePath.startsWith("__research__/")
+            ? filePath.replace("__research__/", "research/")
+            : filePath;
     }
     /* ───────────── execution gates ───────────── */
     /**
-     * Determines whether a phase can be executed based on execution mode and constraints.
-     *
-     * @param phase - The phase to check execution for.
-     * @returns True if the phase can be executed, false otherwise.
+     * Gate model:
+     * 1) Phase + scope gates decide coarse permissions (what broad work is allowed).
+     * 2) Route gate decides finer sub-decisions within those allowed areas (what to do next).
+     */
+    /**
+     * Gate 1: Is this kind of work allowed at all?
+     * Plain meaning: checks capability rules (e.g. read-only vs file-writing).
+     * Example: for docs-only mode, analysis/planning are blocked, and writes are limited.
      */
     canExecutePhase(phase) {
         const constraints = this.context.executionControl?.constraints;
@@ -536,10 +1354,9 @@ export class MainAgent {
     }
     /* ───────────── scope gates ───────────── */
     /**
-     * Determines whether a phase can be executed based on the current scope.
-     *
-     * @param phase - The phase to check execution for.
-     * @returns True if the phase can be executed, false otherwise.
+     * Gate 2: Is this work allowed for the current scope size?
+     * Plain meaning: checks scope rules (none/single/multi/repo-wide).
+     * Example: if scope is "analysis", only analysis/planning run and transform/write are blocked.
      */
     canExecuteScope(phase) {
         const scope = this.context.analysis?.scopeType ?? "repo-wide";
@@ -553,6 +1370,24 @@ export class MainAgent {
         }
         return allowed;
     }
+    /**
+     * Gate 3: Does this request path want this action right now?
+     * Plain meaning: checks route-specific intent from routingDecision.
+     * Example: search expansion is skipped when routing says allowSearch=false.
+     */
+    canExecuteRoute(action) {
+        const routing = this.context.analysis?.routingDecision;
+        switch (action) {
+            case "search-expand":
+                return routing?.allowSearch ?? true;
+            case "transform":
+                return routing?.allowTransform ?? true;
+            case "research":
+                return routing?.allowResearch ?? false;
+            default:
+                return true;
+        }
+    }
     /* ----------------------------------- */
     /* ------------- helpers ------------- */
     /* ----------------------------------- */