@yuaone/core 0.1.0

package/dist/execution-engine.js

@@ -0,0 +1,1555 @@
+/**
+ * @module execution-engine
+ * @description Top-level Execution Engine — StateMachine(brain) ↔ AgentLoop(hands) 오케스트레이터.
+ *
+ * 모든 하위 시스템을 연결하여 사용자 목표를 end-to-end로 실행한다:
+ * - **StateMachine** — phase 전이 (analyze → plan → implement → verify → done)
+ * - **AgentLoop** — LLM ↔ Tool 반복 실행 (implement/fix phase)
+ * - **HierarchicalPlanner** — 3-level 계획 수립 (plan phase)
+ * - **SelfReflection** — 6-dimension 심층 검증 (verify phase)
+ * - **CodebaseContext** — 코드베이스 인덱싱/검색 (analyze phase)
+ *
+ * @example
+ * ```typescript
+ * const engine = new ExecutionEngine({
+ *   byokConfig: { provider: "anthropic", apiKey: "sk-..." },
+ *   projectPath: "/my/project",
+ *   toolExecutor: myExecutor,
+ *   maxIterations: 100,
+ *   totalTokenBudget: 500_000,
+ * });
+ *
+ * engine.on("phase:enter", (phase) => console.log(`Phase: ${phase}`));
+ * engine.on("monologue", (entry) => console.log(entry.thought));
+ *
+ * const result = await engine.execute("Add error handling to all API routes");
+ * console.log(result.success, result.summary);
+ * ```
+ */
+import { EventEmitter } from "node:events";
+import { readFile } from "node:fs/promises";
+import { BYOKClient } from "./llm-client.js";
+import { AgentLoop } from "./agent-loop.js";
+import { AgentLogger } from "./agent-logger.js";
+import { AgentStateMachine, } from "./state-machine.js";
+import { CodebaseContext } from "./codebase-context.js";
+import { VectorIndex } from "./vector-index.js";
+import { LanguageSupport } from "./language-support.js";
+import { HierarchicalPlanner, } from "./hierarchical-planner.js";
+import { SelfReflection, } from "./self-reflection.js";
+import { PlanGraphManager } from "./kernel.js";
+import { MCPClient } from "./mcp-client.js";
+import { PerfOptimizer } from "./perf-optimizer.js";
+import { SandboxManager } from "./sandbox-tiers.js";
+import { DebateOrchestrator } from "./debate-orchestrator.js";
+import { SecurityScanner } from "./security-scanner.js";
+import { DocIntelligence } from "./doc-intelligence.js";
+import { IntentInferenceEngine } from "./intent-inference.js";
+import { SpeculativeExecutor } from "./speculative-executor.js";
+// ─── Defaults ────────────────────────────────────────────────────
+const ENGINE_DEFAULTS = {
+    maxIterations: 100,
+    totalTokenBudget: 500_000,
+    maxFixAttempts: 3,
+    enableCodebaseIndex: true,
+    enableHierarchicalPlanning: true,
+    enableDeepVerify: true,
+    enableMonologue: true,
+    enableLearning: true,
+    skipDesignForSimple: true,
+    enableParallel: true,
+    enableParallelExecution: true,
+    maxParallelAgents: 3,
+};
+// ─── ExecutionEngine ─────────────────────────────────────────────
+/**
+ * ExecutionEngine — YUAN 에이전트의 최상위 오케스트레이터.
+ *
+ * StateMachine이 phase 전이를 결정하고,
+ * ExecutionEngine이 각 phase에서 적절한 하위 시스템을 호출한다.
+ *
+ * - **analyze**: CodebaseContext로 프로젝트 구조 파악
+ * - **design**: LLM으로 접근법 제안
+ * - **plan**: HierarchicalPlanner로 3-level 계획 수립
+ * - **implement**: AgentLoop로 LLM ↔ Tool 반복 실행
+ * - **verify**: SelfReflection.deepVerify로 6-dimension 검증
+ * - **fix**: AgentLoop로 에러 수정
+ * - **replan**: HierarchicalPlanner.replan으로 재계획
+ */
+export class ExecutionEngine extends EventEmitter {
+    config;
+    llmClient;
+    reflection;
+    codebaseContext;
+    vectorIndex;
+    stateMachine;
+    abortController;
+    changedFiles;
+    originalFiles;
+    lastTermination;
+    lastVerifyResult;
+    hierarchicalPlan;
+    planGraph;
+    sessionId;
+    _logger;
+    sessionPersistence;
+    /** DAG 기반 병렬 실행 결과 캐시 (stepIndex → StepResult) */
+    parallelStepResults;
+    /** DAG 기반 병렬 실행이 완료되었는지 */
+    parallelExecutionDone;
+    /** MCP server configurations (stored from constructor config) */
+    mcpServerConfigs;
+    /** MCP Client — external tool bridge (null if disabled) */
+    mcpClient = null;
+    /** MCP tool definitions discovered at runtime */
+    mcpToolDefinitions = [];
+    /** Performance optimizer (null if disabled) */
+    perfOptimizer = null;
+    /** Sandbox manager for tool call validation (null if disabled) */
+    sandboxManager = null;
+    constructor(config) {
+        super();
+        this.config = {
+            byokConfig: config.byokConfig,
+            projectPath: config.projectPath,
+            toolExecutor: config.toolExecutor,
+            maxIterations: config.maxIterations ?? ENGINE_DEFAULTS.maxIterations,
+            totalTokenBudget: config.totalTokenBudget ?? ENGINE_DEFAULTS.totalTokenBudget,
+            maxFixAttempts: config.maxFixAttempts ?? ENGINE_DEFAULTS.maxFixAttempts,
+            enableCodebaseIndex: config.enableCodebaseIndex ?? ENGINE_DEFAULTS.enableCodebaseIndex,
+            enableHierarchicalPlanning: config.enableHierarchicalPlanning ?? ENGINE_DEFAULTS.enableHierarchicalPlanning,
+            enableDeepVerify: config.enableDeepVerify ?? ENGINE_DEFAULTS.enableDeepVerify,
+            enableMonologue: config.enableMonologue ?? ENGINE_DEFAULTS.enableMonologue,
+            enableLearning: config.enableLearning ?? ENGINE_DEFAULTS.enableLearning,
+            skipDesignForSimple: config.skipDesignForSimple ?? ENGINE_DEFAULTS.skipDesignForSimple,
+            enableParallel: config.enableParallel ?? ENGINE_DEFAULTS.enableParallel,
+            enableParallelExecution: config.enableParallelExecution ?? ENGINE_DEFAULTS.enableParallelExecution,
+            maxParallelAgents: config.maxParallelAgents ?? ENGINE_DEFAULTS.maxParallelAgents,
+            enableVectorSearch: config.enableVectorSearch ?? false,
+            enableDebate: config.enableDebate ?? false,
+            enableSecurityScan: config.enableSecurityScan ?? false,
+            enableDocGeneration: config.enableDocGeneration ?? false,
+            enableIntentInference: config.enableIntentInference ?? true,
+            enableSpeculative: config.enableSpeculative ?? false,
+            speculativeMaxApproaches: config.speculativeMaxApproaches ?? 3,
+            governorConfig: config.governorConfig,
+            contextConfig: config.contextConfig,
+            approvalConfig: config.approvalConfig,
+            approvalHandler: config.approvalHandler,
+            autoFixConfig: config.autoFixConfig,
+        };
+        this.llmClient = new BYOKClient(this.config.byokConfig);
+        this.sessionId = config.sessionId ?? `engine-${Date.now().toString(36)}`;
+        this.sessionPersistence = config.sessionPersistence ?? null;
+        this.reflection = new SelfReflection(this.sessionId, {
+            enableDeepVerify: this.config.enableDeepVerify,
+            enableMonologue: this.config.enableMonologue,
+            enableLearning: this.config.enableLearning,
+        });
+        // Initialize structured logger
+        this._logger = config.logger ?? new AgentLogger({
+            sessionId: this.sessionId,
+            level: "info",
+            outputs: [{ type: "memory" }],
+            ...config.loggerConfig,
+        });
+        this.codebaseContext = null;
+        this.vectorIndex = null;
+        this.stateMachine = null;
+        this.planGraph = null;
+        this.abortController = new AbortController();
+        this.changedFiles = new Set();
+        this.originalFiles = new Map();
+        this.lastTermination = { reason: "USER_CANCELLED" };
+        this.parallelStepResults = new Map();
+        this.parallelExecutionDone = false;
+        // Store MCP server configs for use in execute()
+        this.mcpServerConfigs = config.mcpServerConfigs ?? [];
+        // Initialize PerfOptimizer if enabled
+        if (config.enablePerfTracking) {
+            this.perfOptimizer = new PerfOptimizer();
+        }
+        // Initialize SandboxManager if enabled
+        if (config.enableSandbox) {
+            this.sandboxManager = new SandboxManager({
+                projectPath: this.config.projectPath,
+                defaultTier: config.sandboxTier,
+            });
+        }
+        // Wire reflection monologue events to engine events
+        this.reflection.on("monologue:entry", (entry) => {
+            this.emit("monologue", entry);
+        });
+    }
+    // ─── Logger Access ─────────────────────────────────────────────
+    /** 실행 로거 — 실행 후 로그 조회에 사용 */
+    get logger() {
+        return this._logger;
+    }
+    /** 현재 PlanGraphManager 인스턴스 (계획 진행 상태 조회용) */
+    get currentPlanGraph() {
+        return this.planGraph;
+    }
+    /**
+     * 현재 계획의 진행 상황을 반환한다.
+     * PlanGraphManager가 없으면 null을 반환한다.
+     *
+     * @returns 진행 상황 객체 또는 null
+     */
+    getPlanProgress() {
+        if (!this.planGraph)
+            return null;
+        const progress = this.planGraph.getProgress();
+        const graphState = this.planGraph.getState();
+        return {
+            completed: progress.completed,
+            total: progress.total,
+            percent: progress.percent,
+            running: [...graphState.runningNodes],
+            failed: [...graphState.failedNodes],
+        };
+    }
+    // ─── Main Entry ────────────────────────────────────────────────
+    /**
+     * 사용자 목표를 end-to-end로 실행한다.
+     *
+     * 내부적으로 StateMachine을 생성하고, 각 phase에 대한 콜백을 연결하여
+     * idle → analyze → plan → implement → verify → done까지 자동 진행한다.
+     *
+     * @param goal - 사용자의 실행 목표
+     * @returns 실행 결과 (성공 여부, 변경 파일, 토큰 사용량 등)
+     */
+    async execute(goal) {
+        const startTime = Date.now();
+        this.abortController = new AbortController();
+        this.changedFiles.clear();
+        this.originalFiles.clear();
+        this.lastVerifyResult = undefined;
+        this.hierarchicalPlan = undefined;
+        this.planGraph = null;
+        this.parallelStepResults = new Map();
+        this.parallelExecutionDone = false;
+        this.emit("engine:start", goal);
+        this._logger.logInput(goal);
+        this.reflection.think("start", `Goal received: "${goal}"`);
+        try {
+            // 0. Intent inference pre-processing (refine ambiguous goals)
+            if (this.config.enableIntentInference) {
+                try {
+                    const intentEngine = new IntentInferenceEngine({
+                        byokConfig: this.config.byokConfig,
+                        projectPath: this.config.projectPath,
+                        maxContextTokens: 4000,
+                    });
+                    const intentResult = await intentEngine.infer(goal);
+                    this.emit("intent:inferred", intentResult);
+                    if (intentResult.isAmbiguous) {
+                        this._logger.info("system", `Intent inference: ambiguous input refined — "${goal}" → "${intentResult.refinedGoal}" (category: ${intentResult.category}, confidence: ${intentResult.confidence.toFixed(2)})`);
+                        this.reflection.think("analyze", `Intent inference refined ambiguous goal: "${goal}" → "${intentResult.refinedGoal}" [${intentResult.category}, confidence=${intentResult.confidence.toFixed(2)}]`);
+                        goal = intentResult.refinedGoal;
+                    }
+                    else {
+                        this._logger.info("system", `Intent inference: input is clear (category: ${intentResult.category}, confidence: ${intentResult.confidence.toFixed(2)})`);
+                    }
+                }
+                catch (intentErr) {
+                    this._logger.warn("system", `Intent inference failed (continuing with original goal): ${intentErr instanceof Error ? intentErr.message : String(intentErr)}`);
+                }
+            }
+            // 1. Build codebase index (if enabled and not already built)
+            if (this.config.enableCodebaseIndex && !this.codebaseContext) {
+                const languageSupport = new LanguageSupport();
+                this.codebaseContext = new CodebaseContext(this.config.projectPath, languageSupport);
+                this._logger.info("system", "Building codebase index", { projectPath: this.config.projectPath });
+                this.reflection.think("analyze", "Building codebase index...");
+                await this.codebaseContext.buildIndex();
+                const stats = this.codebaseContext.getStats();
+                this._logger.info("system", `Codebase indexed: ${stats.totalFiles} files, ${stats.totalSymbols} symbols`);
+                this.reflection.think("analyze", `Index built: ${stats.totalFiles} files, ${stats.totalSymbols} symbols`);
+            }
+            // 1b. Conditional VectorIndex initialization (requires pgvector)
+            if (this.config.enableVectorSearch && !this.vectorIndex) {
+                // VectorIndex requires a real SQLExecutor and EmbeddingProvider.
+                // When no DB is available, create a no-op stub so the engine
+                // doesn't crash — vector search simply returns empty results.
+                const noopSqlExecutor = {
+                    query: async () => ({ rows: [] }),
+                };
+                const noopEmbeddingProvider = {
+                    embed: async (texts) => texts.map(() => []),
+                    dimension: 1536,
+                };
+                this.vectorIndex = new VectorIndex({
+                    projectId: this.config.projectPath,
+                    sqlExecutor: noopSqlExecutor,
+                    embeddingProvider: noopEmbeddingProvider,
+                });
+                this._logger.info("system", "VectorIndex initialized (no-op stub — supply real DB for pgvector search)");
+            }
+            // 1c. MCP Client initialization (optional — connect to external MCP servers)
+            if (this.mcpServerConfigs.length > 0) {
+                try {
+                    this.mcpClient = new MCPClient({
+                        servers: this.mcpServerConfigs.map((s) => ({
+                            name: s.name,
+                            transport: "stdio",
+                            command: s.command,
+                            args: s.args ?? [],
+                        })),
+                    });
+                    await this.mcpClient.connectAll();
+                    this.mcpToolDefinitions = this.mcpClient.toToolDefinitions();
+                    this._logger.info("system", `MCP: discovered ${this.mcpToolDefinitions.length} tool(s) from ${this.mcpServerConfigs.length} server(s)`);
+                    this.reflection.think("analyze", `MCP tools available: ${this.mcpToolDefinitions.length}`);
+                }
+                catch (mcpErr) {
+                    this._logger.warn("system", `MCP connection failed (continuing without MCP tools): ${mcpErr instanceof Error ? mcpErr.message : String(mcpErr)}`);
+                    this.mcpClient = null;
+                    this.mcpToolDefinitions = [];
+                }
+            }
+            // 2. Create state machine with wired callbacks
+            const context = this.buildStateMachineContext();
+            this.stateMachine = new AgentStateMachine(context, {
+                maxFixAttempts: this.config.maxFixAttempts,
+                skipDesignForSimple: this.config.skipDesignForSimple,
+                enableParallel: this.config.enableParallel,
+            });
+            // Wire state machine events
+            this.stateMachine.on("phase:enter", (phase) => {
+                this.emit("phase:enter", phase);
+                if (this.perfOptimizer) {
+                    this.perfOptimizer.startPhase(phase);
+                }
+                // Checkpoint after each phase transition
+                this.checkpoint().catch((err) => {
+                    console.warn("[YUAN] Checkpoint failed:", err instanceof Error ? err.message : err);
+                });
+            });
+            this.stateMachine.on("phase:exit", (phase) => {
+                this.emit("phase:exit", phase);
+                if (this.perfOptimizer) {
+                    this.perfOptimizer.endPhase(phase);
+                }
+            });
+            this.stateMachine.on("verify:result", (r) => {
+                // Convert VerifyResult to a lightweight emit; deepVerify result is emitted separately
+                this.emit("verify:result", this.lastVerifyResult);
+            });
+            // 3. Run state machine
+            const finalState = await this.stateMachine.run(goal, this.abortController.signal);
+            // 4. Build result
+            const result = this.buildResult(finalState, startTime);
+            // Performance report (if tracking enabled)
+            if (this.perfOptimizer) {
+                const perfReport = this.perfOptimizer.generateReport(this.sessionId);
+                this._logger.info("system", `Perf: efficiency score ${perfReport.efficiencyScore}/100`);
+                if (perfReport.bottlenecks.length > 0) {
+                    this._logger.info("system", `Perf: ${perfReport.bottlenecks.length} bottleneck(s) detected`);
+                }
+            }
+            // Disconnect MCP servers (cleanup)
+            if (this.mcpClient) {
+                await this.mcpClient.disconnectAll().catch(() => {
+                    // Best-effort cleanup
+                });
+            }
+            this._logger.logOutput(result.summary, result.success, result.totalTokens);
+            await this._logger.flush();
+            this.emit("engine:complete", result);
+            return result;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this._logger.error("error", `Execution failed: ${error.message}`);
+            await this._logger.flush();
+            this.emit("engine:error", error);
+            return {
+                success: false,
+                termination: { reason: "ERROR", error: error.message },
+                finalPhase: this.stateMachine?.getState().phase ?? "idle",
+                changedFiles: [...this.changedFiles],
+                summary: `Execution failed: ${error.message}`,
+                totalTokens: { input: 0, output: 0 },
+                totalIterations: 0,
+                totalToolCalls: 0,
+                durationMs: Date.now() - startTime,
+                monologue: [...this.reflection.getMonologue()],
+                learnings: [...this.reflection.getAllLearnings()],
+            };
+        }
+    }
+    /**
+     * 런타임 상태를 디스크에 체크포인트로 저장한다.
+     * sessionPersistence가 없으면 아무것도 하지 않는다.
+     * 실패해도 실행을 중단하지 않는다 (경고 로그만 남김).
+     *
+     * @param stepIndex - 현재 step 인덱스 (있으면)
+     */
+    async checkpoint(stepIndex) {
+        if (!this.sessionPersistence)
+            return;
+        try {
+            await this.sessionPersistence.saveRuntimeState(this.sessionId, {
+                planGraphState: this.planGraph?.toJSON() ?? null,
+                stateMachinePhase: this.stateMachine?.getState().phase,
+                stepIndex,
+                reflectionLearnings: [...this.reflection.getAllLearnings()],
+                reflectionMonologue: [...this.reflection.getMonologue()],
+            });
+        }
+        catch (err) {
+            this._logger.warn("system", `Checkpoint save failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * 실행을 중단한다.
+     * 현재 진행 중인 AgentLoop와 StateMachine이 다음 체크포인트에서 중단된다.
+     */
+    abort() {
+        // Emergency checkpoint save before stopping
+        this.checkpoint().catch(() => {
+            // Ignore — best-effort save during abort
+        });
+        this.abortController.abort();
+    }
+    // ─── StateMachineContext Builder ────────────────────────────────
+    /**
+     * StateMachine에 주입할 콜백 컨텍스트를 생성한다.
+     * 각 콜백이 적절한 하위 시스템(AgentLoop, HierarchicalPlanner 등)을 호출한다.
+     */
+    buildStateMachineContext() {
+        return {
+            analyzeFn: this.analyzeGoal.bind(this),
+            designFn: this.designApproaches.bind(this),
+            planFn: this.createPlan.bind(this),
+            executeFn: this.executeStepWithParallel.bind(this),
+            verifyFn: this.verifyWork.bind(this),
+            fixFn: this.fixErrors.bind(this),
+            replanFn: this.replanWork.bind(this),
+            delegateFn: this.delegateToUser.bind(this),
+        };
+    }
+    // ─── Phase Callbacks ───────────────────────────────────────────
+    /**
+     * analyze phase 콜백 — CodebaseContext + LLM으로 목표를 분석한다.
+     *
+     * @param goal - 사용자 목표
+     * @param state - 현재 에이전트 상태
+     * @returns 복잡도 판정과 분석 컨텍스트
+     */
+    async analyzeGoal(goal, state) {
+        const exitAnalyze = this._logger.enterLayer("analyze", `Analyzing goal: "${goal}"`);
+        this.reflection.think("analyze", `Analyzing goal: "${goal}"`);
+        let codebaseStats = {};
+        if (this.codebaseContext) {
+            codebaseStats = this.codebaseContext.getStats();
+            // Semantic search for relevant symbols
+            const relevant = this.codebaseContext.searchSymbols(goal, 10);
+            if (relevant.length > 0) {
+                const symbolNames = relevant.map((r) => `${r.symbol.name} (${r.symbol.kind}) in ${r.symbol.file}`);
+                this.reflection.think("analyze", `Found ${relevant.length} relevant symbols: ${symbolNames.slice(0, 5).join(", ")}`);
+            }
+        }
+        const analysisPrompt = this.buildAnalysisPrompt(goal, codebaseStats);
+        const response = await this.llmClient.chat([
+            { role: "system", content: analysisPrompt },
+            { role: "user", content: goal },
+        ]);
+        const content = response.content ?? "";
+        // Parse complexity from LLM response
+        let complexity = "moderate";
+        const complexityMatch = content.match(/\b(trivial|simple|moderate|complex|massive)\b/i);
+        if (complexityMatch) {
+            complexity = complexityMatch[1].toLowerCase();
+        }
+        this._logger.logDecision("Goal complexity assessment", ["trivial", "simple", "moderate", "complex", "massive"], complexity, `LLM analysis determined complexity based on goal and codebase context`);
+        this.reflection.think("analyze", `Analysis complete — complexity: ${complexity}`);
+        exitAnalyze();
+        return { complexity, context: content };
+    }
+    /**
+     * design phase 콜백 — LLM에게 구현 접근법 제안을 요청한다.
+     *
+     * @param goal - 사용자 목표
+     * @param context - analyze phase에서 수집한 컨텍스트
+     * @returns 제안된 접근법 목록
+     */
+    async designApproaches(goal, context) {
+        const exitDesign = this._logger.enterLayer("design", "Generating approach options");
+        this.reflection.think("design", "Generating approach options...");
+        const prompt = `You are a senior architect. Based on the analysis, propose 2-3 implementation approaches.
+
+## Analysis Context
+${context}
+
+## Goal
+${goal}
+
+## Output Format
+Respond with ONLY a JSON array (no markdown fences):
+[
+  {
+    "id": 1,
+    "name": "approach name",
+    "description": "what this approach does",
+    "pros": ["advantage 1"],
+    "cons": ["disadvantage 1"],
+    "estimatedComplexity": "low",
+    "recommended": true
+  }
+]
+
+Complexity: "low" | "medium" | "high"
+Exactly one approach should have recommended=true.`;
+        const response = await this.llmClient.chat([
+            { role: "system", content: prompt },
+            { role: "user", content: goal },
+        ]);
+        const content = response.content ?? "[]";
+        try {
+            const jsonStr = this.extractJson(content);
+            const parsed = JSON.parse(jsonStr);
+            if (Array.isArray(parsed) && parsed.length > 0) {
+                const recommended = parsed.find((a) => a.recommended);
+                this._logger.logDecision("Select implementation approach", parsed.map((a) => a.name), recommended?.name ?? parsed[0].name, `LLM recommended approach based on goal analysis`);
+                this.reflection.think("design", `Generated ${parsed.length} approaches. Recommended: ${recommended?.name ?? "none"}`);
+                exitDesign();
+                return parsed;
+            }
+        }
+        catch {
+            // Parse failure — fall through
+        }
+        // Default: single direct approach
+        const defaultApproach = {
+            id: 1,
+            name: "direct",
+            description: "Direct implementation based on analysis",
+            pros: ["Simple", "Fast"],
+            cons: ["May miss edge cases"],
+            estimatedComplexity: "medium",
+            recommended: true,
+        };
+        this._logger.logReasoning("LLM response could not be parsed, falling back to default direct approach");
+        this.reflection.think("design", "Using default direct approach");
+        exitDesign();
+        return [defaultApproach];
+    }
+    /**
+     * plan phase 콜백 — HierarchicalPlanner로 3-level 실행 계획을 수립한다.
+     *
+     * @param goal - 사용자 목표
+     * @param approach - 선택된 접근법
+     * @returns 실행 계획 (ExecutionPlan 형식)
+     */
+    async createPlan(goal, approach) {
+        const exitPlan = this._logger.enterLayer("plan", `Creating plan with approach: "${approach.name}"`);
+        this.reflection.think("plan", `Creating plan with approach: "${approach.name}"`);
+        if (this.config.enableHierarchicalPlanning) {
+            const planner = new HierarchicalPlanner({
+                projectPath: this.config.projectPath,
+            });
+            const hPlan = await planner.createHierarchicalPlan(goal, this.llmClient);
+            this.hierarchicalPlan = hPlan;
+            this._logger.info("system", `Hierarchical plan: ${hPlan.tactical.length} tasks, ${hPlan.totalEstimatedIterations} iterations, ${hPlan.parallelizableGroups.length} parallel groups`);
+            this.reflection.think("plan", `Hierarchical plan created: ${hPlan.tactical.length} tactical tasks, ` +
+                `${hPlan.totalEstimatedIterations} estimated iterations, ` +
+                `${hPlan.parallelizableGroups.length} parallel groups`);
+            const executionPlan = planner.toExecutionPlan(hPlan);
+            // Initialize PlanGraphManager for step progress tracking
+            this.planGraph = PlanGraphManager.fromExecutionPlan(this.sessionId, executionPlan);
+            this._logger.info("system", `PlanGraph initialized: ${executionPlan.steps.length} nodes, ${this.planGraph.getState().parallelGroups.length} parallel groups`);
+            this.reflection.think("plan", `PlanGraph initialized with ${executionPlan.steps.length} nodes`);
+            exitPlan();
+            return executionPlan;
+        }
+        // Fallback: single-step plan
+        this._logger.logReasoning("Hierarchical planning disabled, using single-step fallback");
+        this.reflection.think("plan", "Using single-step fallback plan");
+        const fallbackPlan = {
+            goal,
+            steps: [
+                {
+                    id: "step-1",
+                    goal: `${approach.description}: ${goal}`,
+                    targetFiles: [],
+                    readFiles: [],
+                    tools: ["file_read", "file_write", "file_edit", "grep", "glob"],
+                    estimatedIterations: 10,
+                    dependsOn: [],
+                },
+            ],
+            estimatedTokens: 50_000,
+        };
+        // Initialize PlanGraphManager for fallback plan too
+        this.planGraph = PlanGraphManager.fromExecutionPlan(this.sessionId, fallbackPlan);
+        this._logger.info("system", `PlanGraph initialized (fallback): 1 node`);
+        exitPlan();
+        return fallbackPlan;
+    }
+    /**
+     * 병렬 실행 가능 여부에 따라 DAG 기반 병렬 실행 또는 단일 step 실행을 선택한다.
+     *
+     * StateMachine의 `handleParallel` phase에서 호출될 때:
+     * - 첫 호출 시 DAG 기반 병렬 실행을 수행하고 모든 결과를 캐시한다.
+     * - 이후 호출은 캐시에서 결과를 반환한다.
+     *
+     * StateMachine의 `handleImplement` phase에서 호출될 때:
+     * - 기존 순차 실행을 그대로 사용한다.
+     *
+     * @param plan - 실행 계획
+     * @param stepIndex - 실행할 step 인덱스
+     * @param state - 현재 에이전트 상태
+     * @returns step 실행 결과
+     */
+    async executeStepWithParallel(plan, stepIndex, state) {
+        // Parallel DAG execution: if enabled and PlanGraph exists and plan has multiple steps
+        const shouldRunParallel = this.config.enableParallelExecution &&
+            this.planGraph !== null &&
+            plan.steps.length > 1;
+        if (!shouldRunParallel) {
+            // Sequential fallback
+            return this.executeStep(plan, stepIndex, state);
+        }
+        // If DAG execution already ran, return cached result
+        if (this.parallelExecutionDone) {
+            const cached = this.parallelStepResults.get(stepIndex);
+            if (cached)
+                return cached;
+            // No cached result means this step was not reached by DAG (failed deps, etc.)
+            return {
+                stepIndex,
+                phase: "implement",
+                success: false,
+                output: `Step ${stepIndex} was not executed (blocked by dependency failure or skipped)`,
+                changedFiles: [],
+                tokensUsed: 0,
+                durationMs: 0,
+            };
+        }
+        // First call triggers full DAG execution for ALL steps
+        await this.executeStepsWithDAG(plan, state);
+        this.parallelExecutionDone = true;
+        // Return this step's result from cache
+        const result = this.parallelStepResults.get(stepIndex);
+        if (result)
+            return result;
+        return {
+            stepIndex,
+            phase: "implement",
+            success: false,
+            output: `Step ${stepIndex} was not executed during DAG execution`,
+            changedFiles: [],
+            tokensUsed: 0,
+            durationMs: 0,
+        };
+    }
+    /**
+     * PlanGraph DAG 기반 병렬 step 실행.
+     *
+     * PlanGraphManager의 의존성 그래프를 따라:
+     * 1. 의존성이 모두 완료된 ready 노드를 가져온다.
+     * 2. maxParallelAgents만큼 동시에 실행한다.
+     * 3. 완료되면 의존 노드를 ready로 전환하고 반복한다.
+     * 4. 모든 노드가 종료 상태가 될 때까지 반복한다.
+     *
+     * @param plan - 실행 계획
+     * @param state - 현재 에이전트 상태
+     */
+    async executeStepsWithDAG(plan, state) {
+        if (!this.planGraph)
+            return;
+        const maxConcurrent = this.config.maxParallelAgents;
+        this._logger.info("system", `DAG parallel execution started: ${plan.steps.length} steps, max ${maxConcurrent} concurrent`);
+        this.reflection.think("implement", `Starting DAG-based parallel execution: ${plan.steps.length} steps, max ${maxConcurrent} concurrent`);
+        while (true) {
+            // Check abort
+            if (this.abortController.signal.aborted) {
+                this._logger.info("system", "DAG parallel execution aborted");
+                break;
+            }
+            // Get nodes that are ready (all dependencies completed)
+            const readyNodes = this.planGraph.getReadyNodes();
+            if (readyNodes.length === 0) {
+                // Check if all done or stuck
+                if (this.planGraph.isComplete()) {
+                    this._logger.info("system", "DAG parallel execution: all nodes complete");
+                    break;
+                }
+                // If there are running nodes, wait for them to finish
+                const graphState = this.planGraph.getState();
+                if (graphState.runningNodes.length > 0) {
+                    await new Promise(resolve => setTimeout(resolve, 100));
+                    continue;
+                }
+                // No ready, no running = deadlock (all remaining nodes are blocked/failed)
+                this._logger.warn("system", "DAG parallel execution: deadlock — no ready or running nodes, but graph not complete");
+                break;
+            }
+            // Take up to maxConcurrent ready nodes
+            const batch = readyNodes.slice(0, maxConcurrent);
+            this._logger.info("system", `DAG batch: executing ${batch.length} steps in parallel [${batch.map(n => n.id).join(", ")}]`);
+            this.reflection.think("implement", `Parallel batch: ${batch.map(n => `"${n.goal}" (${n.id})`).join(", ")}`);
+            // Execute batch in parallel using Promise.allSettled
+            await Promise.allSettled(batch.map(async (node) => {
+                const stepIndex = plan.steps.findIndex(s => s.id === node.id);
+                if (stepIndex === -1) {
+                    this._logger.warn("system", `DAG: node "${node.id}" not found in plan steps`);
+                    return;
+                }
+                try {
+                    // executeStep already handles markRunning/markCompleted/markFailed
+                    const stepResult = await this.executeStep(plan, stepIndex, state);
+                    // Cache the result
+                    this.parallelStepResults.set(stepIndex, stepResult);
+                    // Update state tracking
+                    state.currentStepIndex = Math.max(state.currentStepIndex, stepIndex + 1);
+                }
+                catch (err) {
+                    // executeStep should not throw (it handles errors internally),
+                    // but just in case, cache a failure result
+                    const errorMessage = err instanceof Error ? err.message : String(err);
+                    this._logger.error("error", `DAG: unexpected error executing step ${stepIndex}: ${errorMessage}`);
+                    this.parallelStepResults.set(stepIndex, {
+                        stepIndex,
+                        phase: "implement",
+                        success: false,
+                        output: `Unexpected error: ${errorMessage}`,
+                        changedFiles: [],
+                        tokensUsed: 0,
+                        durationMs: 0,
+                    });
+                }
+            }));
+            // Checkpoint after each parallel batch
+            await this.checkpoint(state.currentStepIndex);
+            // Log progress
+            const progress = this.planGraph.getProgress();
+            this._logger.info("system", `DAG progress: ${progress.completed}/${progress.total} (${progress.percent}%)`);
+        }
+        // Final summary
+        const progress = this.planGraph.getProgress();
+        const graphState = this.planGraph.getState();
+        this._logger.info("system", `DAG parallel execution complete: ${progress.completed}/${progress.total} succeeded, ${graphState.failedNodes.length} failed, ${graphState.skippedNodes.length} skipped`);
+        this.reflection.think("implement", `DAG execution complete: ${progress.completed}/${progress.total} steps, ${graphState.failedNodes.length} failed`);
+    }
+    /**
+     * implement phase 콜백 — AgentLoop로 개별 step을 실행한다.
+     *
+     * @param plan - 실행 계획
+     * @param stepIndex - 실행할 step 인덱스
+     * @param state - 현재 에이전트 상태
+     * @returns step 실행 결과
+     */
+    async executeStep(plan, stepIndex, state) {
+        const step = plan.steps[stepIndex];
+        if (!step) {
+            this._logger.warn("error", `Step ${stepIndex} not found in plan`);
+            return {
+                stepIndex,
+                phase: "implement",
+                success: false,
+                output: `Step ${stepIndex} not found in plan`,
+                changedFiles: [],
+                tokensUsed: 0,
+                durationMs: 0,
+            };
+        }
+        const exitImplement = this._logger.enterLayer("implement", `Step ${stepIndex + 1}/${plan.steps.length}: "${step.goal}"`);
+        this.reflection.think("implement", `Executing step ${stepIndex + 1}/${plan.steps.length}: "${step.goal}"`);
+        // Mark step as running in PlanGraph
+        const stepId = step.id;
+        if (this.planGraph) {
+            try {
+                this.planGraph.markRunning(stepId);
+                this._logger.info("system", `PlanGraph: node "${stepId}" → running`);
+            }
+            catch (pgErr) {
+                // Node may not be in ready state (e.g., if called out of order)
+                this._logger.warn("system", `PlanGraph: failed to mark "${stepId}" running: ${pgErr instanceof Error ? pgErr.message : String(pgErr)}`);
+            }
+        }
+        // Snapshot target files before modification
+        await this.snapshotFiles(step.targetFiles);
+        // ─── Speculative Execution (opt-in) ─────────────────────────
+        if (this.config.enableSpeculative) {
+            try {
+                this._logger.info("system", `Speculative execution enabled for step ${stepIndex + 1}`);
+                this.reflection.think("implement", `Using speculative execution for step ${stepIndex + 1}`);
+                const specExecutor = new SpeculativeExecutor({
+                    maxApproaches: this.config.speculativeMaxApproaches,
+                    approachTimeout: 120_000,
+                    minQualityThreshold: 60,
+                    byokConfig: this.config.byokConfig,
+                    projectPath: this.config.projectPath,
+                });
+                // Forward speculative events
+                const specEvents = [
+                    "speculative:start",
+                    "speculative:approach:start",
+                    "speculative:approach:complete",
+                    "speculative:evaluation",
+                    "speculative:complete",
+                ];
+                for (const eventName of specEvents) {
+                    specExecutor.on(eventName, (...args) => {
+                        this.emit(eventName, ...args);
+                    });
+                }
+                // Build codebase context summary for speculative executor
+                let codebaseContextSummary = "";
+                if (this.codebaseContext) {
+                    const stats = this.codebaseContext.getStats();
+                    codebaseContextSummary = `Project: ${stats.totalFiles} files, ${stats.totalSymbols} symbols. Path: ${this.config.projectPath}`;
+                }
+                const specResult = await specExecutor.execute(step.goal, this.config.toolExecutor, codebaseContextSummary);
+                if (specResult.winner) {
+                    this._logger.info("system", `Speculative execution winner: "${specResult.winner.approach.strategy}" (quality: ${specResult.winner.qualityScore}, tokens: ${specResult.winner.tokensUsed})`);
+                    this.reflection.think("implement", `Speculative winner: ${specResult.winner.approach.strategy} — ${specResult.selectionReason}`);
+                    // Apply winner's file changes
+                    for (const [filePath] of specResult.winner.changes) {
+                        this.changedFiles.add(filePath);
+                    }
+                    // Update PlanGraph
+                    if (this.planGraph) {
+                        try {
+                            this.planGraph.markCompleted(stepId, `Speculative execution (${specResult.winner.approach.strategy}): quality ${specResult.winner.qualityScore}`, [...specResult.winner.changes.keys()], { input: specResult.totalTokensUsed, output: 0 });
+                            this._logger.info("system", `PlanGraph: node "${stepId}" → completed (speculative)`);
+                        }
+                        catch (pgErr) {
+                            this._logger.warn("system", `PlanGraph: failed to update "${stepId}": ${pgErr instanceof Error ? pgErr.message : String(pgErr)}`);
+                        }
+                    }
+                    // Checkpoint and return
+                    await this.checkpoint(stepIndex);
+                    exitImplement();
+                    return {
+                        stepIndex,
+                        phase: "implement",
+                        success: specResult.winner.success,
+                        output: `Speculative execution (${specResult.winner.approach.strategy}): ${specResult.selectionReason}`,
+                        changedFiles: [...specResult.winner.changes.keys()],
+                        tokensUsed: specResult.totalTokensUsed,
+                        durationMs: specResult.winner.durationMs,
+                    };
+                }
+                // No winner — fall through to normal AgentLoop execution
+                this._logger.info("system", "Speculative execution: no winner found, falling back to normal execution");
+                this.reflection.think("implement", "Speculative execution produced no winner — falling back to AgentLoop");
+                if (specResult.learnings.length > 0) {
+                    this.reflection.think("implement", `Speculative learnings: ${specResult.learnings.join("; ")}`);
+                }
+            }
+            catch (specErr) {
+                this._logger.warn("system", `Speculative execution failed (falling back to normal): ${specErr instanceof Error ? specErr.message : String(specErr)}`);
+            }
+        }
+        // ─── Normal AgentLoop Execution ─────────────────────────────
+        // Build step-specific system prompt
+        const systemPrompt = this.buildStepPrompt(plan, step, stepIndex);
+        // Create and run AgentLoop for this step
+        const loop = this.createAgentLoop(systemPrompt);
+        this.wireAgentLoopEvents(loop);
+        const startMs = Date.now();
+        const termination = await loop.run(step.goal);
+        const durationMs = Date.now() - startMs;
+        // Track last termination
+        this.lastTermination = termination;
+        // Collect changed files from loop
+        const loopUsage = loop.getTokenUsage();
+        const stepChangedFiles = [];
+        // Extract changed files from agent events (tracked via tool results)
+        // The changedFiles set is updated via wireAgentLoopEvents
+        for (const file of this.changedFiles) {
+            if (step.targetFiles.includes(file) || step.targetFiles.length === 0) {
+                stepChangedFiles.push(file);
+            }
+        }
+        const success = termination.reason === "GOAL_ACHIEVED";
+        // Update PlanGraph with step outcome
+        if (this.planGraph) {
+            try {
+                if (success) {
+                    this.planGraph.markCompleted(stepId, termination.reason === "GOAL_ACHIEVED"
+                        ? termination.summary
+                        : "completed", stepChangedFiles, { input: loopUsage.input, output: loopUsage.output });
+                    this._logger.info("system", `PlanGraph: node "${stepId}" → completed`);
+                }
+                else {
+                    const errorMsg = termination.reason === "ERROR"
+                        ? termination.error
+                        : `Step failed: ${termination.reason}`;
+                    this.planGraph.markFailed(stepId, errorMsg);
+                    this._logger.info("system", `PlanGraph: node "${stepId}" → failed`);
+                }
+            }
+            catch (pgErr) {
+                this._logger.warn("system", `PlanGraph: failed to update "${stepId}": ${pgErr instanceof Error ? pgErr.message : String(pgErr)}`);
+            }
+            // Log plan progress after each step
+            const progress = this.planGraph.getProgress();
+            this._logger.info("system", `PlanGraph progress: ${progress.completed}/${progress.total} (${progress.percent}%)`);
+        }
+        this._logger.logDecision(`Step ${stepIndex + 1} outcome`, ["succeeded", "failed"], success ? "succeeded" : "failed", `AgentLoop terminated with reason: ${termination.reason}`);
+        this.reflection.think("implement", `Step ${stepIndex + 1} ${success ? "succeeded" : "failed"}: ${termination.reason === "GOAL_ACHIEVED"
+            ? termination.summary
+            : termination.reason}`);
+        // Checkpoint after step completes (success or failure)
+        await this.checkpoint(stepIndex);
+        exitImplement();
+        return {
+            stepIndex,
+            phase: "implement",
+            success,
+            output: termination.reason === "GOAL_ACHIEVED"
+                ? termination.summary
+                : termination.reason === "ERROR"
+                    ? termination.error
+                    : `Terminated: ${termination.reason}`,
+            changedFiles: stepChangedFiles,
+            tokensUsed: loopUsage.input + loopUsage.output,
+            durationMs,
+        };
+    }
+    /**
+     * verify phase 콜백 — SelfReflection.deepVerify로 6-dimension 검증을 수행한다.
+     *
+     * @param state - 현재 에이전트 상태
+     * @returns 검증 결과 (StateMachine VerifyResult 형식)
+     */
+    async verifyWork(state) {
+        const exitVerify = this._logger.enterLayer("verify", "Starting deep verification");
+        this.reflection.think("verify", "Starting deep verification...");
+        if (!this.config.enableDeepVerify || this.changedFiles.size === 0) {
+            this._logger.logReasoning("Deep verify skipped", ["run deep verify", "skip deep verify"], "skip deep verify", undefined, "Deep verify disabled or no changed files");
+            this.reflection.think("verify", "Deep verify skipped (disabled or no changed files)");
+            exitVerify();
+            return {
+                verdict: "pass",
+                checks: {
+                    buildSuccess: true,
+                    typesSafe: true,
+                    testsPass: true,
+                    noRegressions: true,
+                    followsPatterns: true,
+                    securityClean: true,
+                },
+                issues: [],
+                suggestions: [],
+                confidence: 1.0,
+            };
+        }
+        // Collect current file contents
+        const changedFileContents = new Map();
+        for (const filePath of this.changedFiles) {
+            try {
+                const content = await readFile(filePath, "utf-8");
+                changedFileContents.set(filePath, content);
+            }
+            catch {
+                // File may have been deleted
+                changedFileContents.set(filePath, "");
+            }
+        }
+        // Gather project patterns from codebase context
+        const patterns = [];
+        if (this.codebaseContext) {
+            const stats = this.codebaseContext.getStats();
+            if (stats.totalFiles > 0) {
+                patterns.push(`Project has ${stats.totalFiles} files`);
+            }
+        }
+        // Run deep verification
+        const deepResult = await this.reflection.deepVerify(state.goal, changedFileContents, this.originalFiles, patterns, async (prompt) => {
+            const response = await this.llmClient.chat([
+                { role: "user", content: prompt },
+            ]);
+            return response.content ?? "";
+        });
+        this.lastVerifyResult = deepResult;
+        // Cross-check with PlanGraph completion status
+        if (this.planGraph) {
+            const pgComplete = this.planGraph.isComplete();
+            const progress = this.planGraph.getProgress();
+            this._logger.info("system", `PlanGraph completion check: complete=${pgComplete}, ${progress.completed}/${progress.total} nodes`);
+            if (!pgComplete && deepResult.verdict === "pass") {
+                this.reflection.think("verify", `Warning: Deep verify passed but PlanGraph shows ${progress.total - progress.completed} incomplete nodes`);
+            }
+        }
+        this._logger.logDecision("Verification verdict", ["pass", "warn", "fail"], deepResult.verdict, `Score: ${deepResult.overallScore}, confidence: ${deepResult.confidence}`);
+        this.reflection.think("verify", `Deep verification: ${deepResult.verdict} (score: ${deepResult.overallScore}, confidence: ${deepResult.confidence})`);
+        // ─── Debate Orchestrator (optional) ───────────────────────
+        if (this.config.enableDebate && this.changedFiles.size > 0) {
+            try {
+                this._logger.info("system", "Running multi-agent debate verification...");
+                this.reflection.think("verify", "Starting debate orchestrator for code review...");
+                const debateOrchestrator = DebateOrchestrator.create({
+                    projectPath: this.config.projectPath,
+                    byokConfig: this.config.byokConfig,
+                    toolExecutor: this.config.toolExecutor,
+                });
+                // Forward debate events
+                const debateEvents = [
+                    "debate:start",
+                    "debate:round:start",
+                    "debate:round:end",
+                    "debate:coder",
+                    "debate:reviewer",
+                    "debate:revision",
+                    "debate:verifier",
+                    "debate:pass",
+                    "debate:fail",
+                    "debate:token_usage",
+                    "debate:abort",
+                ];
+                for (const eventName of debateEvents) {
+                    debateOrchestrator.on(eventName, (...args) => {
+                        this.emit(eventName, ...args);
+                    });
+                }
+                const changedFilesSummary = [...this.changedFiles]
+                    .map((f) => {
+                    const content = changedFileContents.get(f) ?? "";
+                    return `## ${f}\n${content.slice(0, 2000)}`;
+                })
+                    .join("\n\n");
+                const debateResult = await debateOrchestrator.debate(state.goal, changedFilesSummary);
+                this._logger.info("system", `Debate result: score=${debateResult.finalScore}, success=${debateResult.success}, rounds=${debateResult.rounds.length}`);
+                this.reflection.think("verify", `Debate: ${debateResult.success ? "PASSED" : "FAILED"} (score: ${debateResult.finalScore}, ${debateResult.rounds.length} round(s))`);
+                // If debate fails and deep verify passed, downgrade to "concern"
+                if (!debateResult.success && deepResult.verdict === "pass") {
+                    deepResult.verdict = "concern";
+                    const reviewerIssues = debateResult.rounds
+                        .flatMap((r) => r.issues)
+                        .filter((i) => i.severity === "critical" || i.severity === "major");
+                    deepResult.suggestedFixes.push(...reviewerIssues.map((i) => ({
+                        dimension: "correctness",
+                        severity: i.severity === "critical" ? "critical" : "high",
+                        description: `[debate] ${i.description}`,
+                        file: i.file,
+                        autoFixable: false,
+                    })));
+                    this.reflection.think("verify", `Debate downgraded verdict to "concern" due to ${reviewerIssues.length} critical/major issue(s)`);
+                }
+            }
+            catch (debateErr) {
+                this._logger.warn("system", `Debate orchestrator failed (continuing): ${debateErr instanceof Error ? debateErr.message : String(debateErr)}`);
+            }
+        }
+        // ─── Security Scanner (optional) ──────────────────────────
+        if (this.config.enableSecurityScan && this.changedFiles.size > 0) {
+            try {
+                this._logger.info("system", "Running security scan on changed files...");
+                this.reflection.think("verify", "Running security scanner...");
+                const scanner = new SecurityScanner({
+                    projectPath: this.config.projectPath,
+                });
+                const changedFileList = [...this.changedFiles];
+                const scanResult = await scanner.scan(changedFileList);
+                this._logger.info("system", `Security scan: passed=${scanResult.passed}, findings=${scanResult.summary.total} (critical=${scanResult.summary.critical}, high=${scanResult.summary.high})`);
+                this.reflection.think("verify", `Security scan: ${scanResult.passed ? "PASSED" : "FAILED"} — ${scanResult.summary.total} finding(s) (${scanResult.summary.critical} critical, ${scanResult.summary.high} high)`);
+                // If critical findings found, add them to suggestedFixes and downgrade verdict
+                if (scanResult.summary.critical > 0 || scanResult.summary.high > 0) {
+                    const securityFindings = scanResult.findings
+                        .filter((f) => f.severity === "critical" || f.severity === "high");
+                    deepResult.suggestedFixes.push(...securityFindings.map((f) => ({
+                        dimension: "security",
+                        severity: f.severity === "critical" ? "critical" : "high",
+                        description: `[security] ${f.rule} in ${f.file}:${f.line} — ${f.message}`,
+                        file: f.file,
+                        autoFixable: false,
+                    })));
+                    if (scanResult.summary.critical > 0 && deepResult.verdict !== "fail") {
+                        deepResult.verdict = "fail";
+                        this.reflection.think("verify", `Security scanner escalated verdict to "fail" due to ${scanResult.summary.critical} critical finding(s)`);
+                    }
+                    else if (deepResult.verdict === "pass") {
+                        deepResult.verdict = "concern";
+                        this.reflection.think("verify", `Security scanner downgraded verdict to "concern" due to high-severity findings`);
+                    }
+                }
+            }
+            catch (scanErr) {
+                this._logger.warn("system", `Security scan failed (continuing): ${scanErr instanceof Error ? scanErr.message : String(scanErr)}`);
+            }
+        }
+        // ─── Doc Intelligence (optional) ──────────────────────────
+        if (this.config.enableDocGeneration && this.changedFiles.size > 0) {
+            try {
+                this._logger.info("system", "Running documentation intelligence...");
+                this.reflection.think("verify", "Analyzing documentation coverage...");
+                const docIntel = new DocIntelligence({
+                    projectPath: this.config.projectPath,
+                });
+                const docCoverage = docIntel.analyzeCoverage(changedFileContents);
+                this._logger.info("system", `Doc coverage: ${docCoverage.coveragePercent}% (grade: ${docCoverage.grade}), ${docCoverage.missing.length} undocumented symbol(s)`);
+                this.reflection.think("verify", `Documentation: ${docCoverage.coveragePercent}% coverage (grade ${docCoverage.grade}), ${docCoverage.missing.length} missing`);
+                // If coverage is below D grade, add as suggestedFix (non-blocking)
+                if (docCoverage.grade === "D" || docCoverage.grade === "F") {
+                    const missingSymbols = docCoverage.missing
+                        .slice(0, 10)
+                        .map((m) => `${m.symbolName} (${m.symbolType}) in ${m.filePath}:${m.line}`);
+                    deepResult.suggestedFixes.push({
+                        dimension: "quality",
+                        severity: "low",
+                        description: `Documentation coverage is ${docCoverage.grade} (${docCoverage.coveragePercent}%). Missing JSDoc for: ${missingSymbols.join(", ")}`,
+                        autoFixable: false,
+                    });
+                    this.reflection.think("verify", `Low doc coverage (${docCoverage.grade}) — added suggestion for ${missingSymbols.length} symbol(s)`);
+                }
+            }
+            catch (docErr) {
+                this._logger.warn("system", `Doc intelligence failed (continuing): ${docErr instanceof Error ? docErr.message : String(docErr)}`);
+            }
+        }
+        exitVerify();
+        // Map DeepVerifyResult → VerifyResult
+        return this.mapVerifyResult(deepResult);
+    }
+    /**
+     * fix phase 콜백 — AgentLoop로 에러를 수정한다.
+     *
+     * @param errors - 수정할 에러 목록
+     * @param state - 현재 에이전트 상태
+     * @returns 수정 시도 결과
+     */
+    async fixErrors(errors, state) {
+        const exitFix = this._logger.enterLayer("fix", `Fixing ${errors.length} error(s)`);
+        const errorDescriptions = errors
+            .map((e, i) => `${i + 1}. [${e.phase}] ${e.error}${e.suggestedFix ? ` (suggested: ${e.suggestedFix})` : ""}`)
+            .join("\n");
+        this._logger.info("error", `Errors to fix: ${errors.length}`, {
+            errors: errors.map((e) => ({ phase: e.phase, error: e.error })),
+        });
+        this.reflection.think("fix", `Attempting to fix ${errors.length} error(s):\n${errorDescriptions}`);
+        const fixPrompt = `You are fixing errors found during verification. Address each issue:
+
+## Errors to Fix
+${errorDescriptions}
+
+## Changed Files
+${[...this.changedFiles].join(", ")}
+
+## Instructions
+- Fix each error by reading the affected file and making corrections
+- Run relevant build/lint checks after each fix
+- Be precise — only change what's needed to fix the issue
+- If an error seems unfixable, explain why`;
+        const loop = this.createAgentLoop(fixPrompt);
+        this.wireAgentLoopEvents(loop);
+        const startMs = Date.now();
+        const termination = await loop.run(`Fix the following errors:\n${errorDescriptions}`);
+        const durationMs = Date.now() - startMs;
+        this.lastTermination = termination;
+        const loopUsage = loop.getTokenUsage();
+        const success = termination.reason === "GOAL_ACHIEVED";
+        this._logger.logDecision("Fix attempt result", ["succeeded", "failed"], success ? "succeeded" : "failed", `Fix loop terminated with reason: ${termination.reason}`);
+        this.reflection.think("fix", `Fix attempt ${success ? "succeeded" : "failed"}: ${termination.reason}`);
+        exitFix();
+        return {
+            stepIndex: state.currentStepIndex,
+            phase: "fix",
+            success,
+            output: termination.reason === "GOAL_ACHIEVED"
+                ? termination.summary
+                : `Fix attempt ended: ${termination.reason}`,
+            changedFiles: [...this.changedFiles],
+            tokensUsed: loopUsage.input + loopUsage.output,
+            durationMs,
+        };
+    }
+    /**
+     * replan phase 콜백 — HierarchicalPlanner.replan으로 재계획을 수립한다.
+     *
+     * @param state - 현재 에이전트 상태
+     * @returns 새로운 실행 계획
+     */
+    async replanWork(state) {
+        const exitReplan = this._logger.enterLayer("replan", `Re-planning due to ${state.errors.length} error(s)`);
+        this.reflection.think("replan", `Re-planning due to ${state.errors.length} error(s)`);
+        if (this.config.enableHierarchicalPlanning && this.hierarchicalPlan) {
+            const planner = new HierarchicalPlanner({
+                projectPath: this.config.projectPath,
+            });
+            const errorDescriptions = state.errors
+                .map((e) => e.error)
+                .join("; ");
+            const affectedTaskIds = state.errors
+                .map((e) => state.plan?.steps[e.stepIndex]?.id)
+                .filter((id) => !!id);
+            const replanResult = await planner.replan(this.hierarchicalPlan, {
+                type: "error",
+                description: errorDescriptions,
+                affectedTaskIds,
+                severity: "major",
+            }, this.llmClient);
+            this._logger.logDecision("Replan strategy", ["retry", "simplify", "restructure", "abort"], replanResult.strategy, replanResult.reason);
+            this.reflection.think("replan", `Re-plan strategy: ${replanResult.strategy} — ${replanResult.reason}`);
+            // Convert modified tasks back to ExecutionPlan
+            const newSteps = replanResult.modifiedTasks.map((task) => ({
+                id: task.id,
+                goal: task.description,
+                targetFiles: task.targetFiles,
+                readFiles: task.readFiles,
+                tools: task.toolStrategy,
+                estimatedIterations: task.estimatedIterations,
+                dependsOn: task.dependsOn,
+            }));
+            const newPlan = {
+                goal: state.goal,
+                steps: newSteps,
+                estimatedTokens: newSteps.length * 10_000,
+            };
+            // Re-initialize PlanGraph for the new plan
+            this.planGraph = PlanGraphManager.fromExecutionPlan(this.sessionId, newPlan);
+            this._logger.info("system", `PlanGraph re-initialized (replan): ${newSteps.length} nodes`);
+            // Checkpoint after replan completes (save new plan state)
+            await this.checkpoint(state.currentStepIndex);
+            exitReplan();
+            return newPlan;
+        }
+        // Fallback: single retry step
+        this._logger.logReasoning("Hierarchical replanning unavailable, using single-step fallback");
+        this.reflection.think("replan", "Using fallback single-step replan");
+        const fallbackReplan = {
+            goal: state.goal,
+            steps: [
+                {
+                    id: "replan-step-1",
+                    goal: `Retry: ${state.goal} (previous errors: ${state.errors.map((e) => e.error).join("; ")})`,
+                    targetFiles: [],
+                    readFiles: [],
+                    tools: ["file_read", "file_write", "file_edit", "grep", "glob"],
+                    estimatedIterations: 10,
+                    dependsOn: [],
+                },
+            ],
+            estimatedTokens: 50_000,
+        };
+        // Re-initialize PlanGraph for fallback replan
+        this.planGraph = PlanGraphManager.fromExecutionPlan(this.sessionId, fallbackReplan);
+        this._logger.info("system", `PlanGraph re-initialized (fallback replan): 1 node`);
+        // Checkpoint after fallback replan completes
+        await this.checkpoint(state.currentStepIndex);
+        exitReplan();
+        return fallbackReplan;
+    }
+    /**
+     * delegate phase 콜백 — 사용자에게 질문을 전달하고 응답을 대기한다.
+     *
+     * 현재 구현에서는 기본 응답을 반환한다.
+     * 실제 환경에서는 이벤트를 emit하고 외부 응답을 대기해야 한다.
+     *
+     * @param question - 사용자에게 전달할 질문
+     * @returns 사용자 응답
+     */
+    async delegateToUser(question) {
+        this.reflection.think("delegate", `Delegating to user: "${question}"`);
+        // Emit event for external handling
+        this.emit("engine:delegate", question);
+        // In a real implementation, this would wait for user input.
+        // For now, return a default that selects the recommended approach.
+        return "1";
+    }
+    // ─── Helpers ───────────────────────────────────────────────────
+    /**
+     * 변경 전 파일 내용을 스냅샷으로 저장한다.
+     * 이미 스냅샷이 있는 파일은 건너뛴다 (최초 원본만 보존).
+     *
+     * @param files - 스냅샷할 파일 경로 목록
+     */
+    async snapshotFiles(files) {
+        for (const file of files) {
+            if (this.originalFiles.has(file))
+                continue;
+            try {
+                const content = await readFile(file, "utf-8");
+                this.originalFiles.set(file, content);
+            }
+            catch {
+                // File doesn't exist yet — no snapshot needed
+            }
+        }
+    }
+    /**
+     * 개별 step 실행을 위한 AgentLoop 인스턴스를 생성한다.
+     *
+     * @param systemPrompt - step별 시스템 프롬프트
+     * @returns 새 AgentLoop 인스턴스
+     */
+    createAgentLoop(systemPrompt) {
+        // Merge base tool definitions with MCP tool definitions
+        const tools = [
+            ...this.config.toolExecutor.definitions,
+            ...this.mcpToolDefinitions,
+        ];
+        // Wrap tool executor to add sandbox validation and MCP tool routing
+        const baseExecutor = this.config.toolExecutor;
+        const sandboxMgr = this.sandboxManager;
+        const mcpCli = this.mcpClient;
+        const mcpToolDefs = this.mcpToolDefinitions;
+        const wrappedExecutor = {
+            definitions: tools,
+            execute: async (call, abortSignal) => {
+                // Parse arguments to object if needed
+                let args;
+                try {
+                    args = typeof call.arguments === "string"
+                        ? JSON.parse(call.arguments)
+                        : call.arguments;
+                }
+                catch {
+                    return {
+                        tool_call_id: call.id,
+                        name: call.name,
+                        output: `[Error] Invalid JSON in tool arguments: ${String(call.arguments).slice(0, 200)}`,
+                        success: false,
+                        durationMs: 0,
+                    };
+                }
+                // Sandbox pre-validation
+                if (sandboxMgr) {
+                    const validation = sandboxMgr.validateToolCall(call.name, args);
+                    if (!validation.allowed) {
+                        return {
+                            tool_call_id: call.id,
+                            name: call.name,
+                            output: `[Sandbox blocked] ${validation.violations.join("; ")}`,
+                            success: false,
+                            durationMs: 0,
+                        };
+                    }
+                }
+                // Route MCP tool calls to MCPClient (check MCP registry, not string pattern)
+                if (mcpCli && mcpToolDefs.some((t) => t.name === call.name)) {
+                    return mcpCli.callToolAsYuan(call.name, args, call.id);
+                }
+                // Default: use base executor
+                return baseExecutor.execute(call, abortSignal);
+            },
+        };
+        return new AgentLoop({
+            config: {
+                byok: this.config.byokConfig,
+                loop: {
+                    model: "coding",
+                    maxIterations: this.config.maxIterations,
+                    maxTokensPerIteration: 16_384,
+                    totalTokenBudget: this.config.totalTokenBudget,
+                    tools,
+                    systemPrompt,
+                    projectPath: this.config.projectPath,
+                },
+            },
+            toolExecutor: wrappedExecutor,
+            governorConfig: this.config.governorConfig ?? { planTier: "PRO" },
+            contextConfig: this.config.contextConfig,
+            approvalConfig: this.config.approvalConfig,
+            approvalHandler: this.config.approvalHandler,
+            autoFixConfig: this.config.autoFixConfig,
+        });
+    }
+    /**
+     * AgentLoop 이벤트를 ExecutionEngine 이벤트로 전파한다.
+     *
+     * @param loop - 이벤트를 연결할 AgentLoop 인스턴스
+     */
+    wireAgentLoopEvents(loop) {
+        loop.on("event", (event) => {
+            switch (event.kind) {
+                case "agent:text_delta":
+                    this.emit("text_delta", event.text);
+                    break;
+                case "agent:thinking":
+                    this.emit("thinking", event.content);
+                    break;
+                case "agent:tool_call": {
+                    const toolName = event.tool;
+                    const toolInput = (event.input ?? {});
+                    // Sandbox pre-validation: block disallowed tool calls
+                    if (this.sandboxManager) {
+                        const validation = this.sandboxManager.validateToolCall(toolName, toolInput);
+                        if (!validation.allowed) {
+                            this._logger.warn("system", `Sandbox blocked tool "${toolName}": ${validation.violations.join("; ")}`);
+                            // The event is still emitted for observability, but the
+                            // AgentLoop's toolExecutor wrapper handles the actual blocking.
+                            // We emit a synthetic tool_result error to signal the block.
+                        }
+                    }
+                    this._logger.logToolCall(toolName, toolInput);
+                    this.emit("tool:call", toolName, toolInput);
+                    break;
+                }
+                case "agent:tool_result":
+                    this._logger.logToolResult(event.tool, event.output, event.durationMs ?? 0, event.success ?? true);
+                    this.emit("tool:result", event.tool, event.output);
+                    if (this.perfOptimizer) {
+                        this.perfOptimizer.recordToolCall(event.tool, event.input ?? {}, event.durationMs ?? 0);
+                    }
+                    break;
+                case "agent:file_change":
+                    // Track changed files
+                    if (typeof event.path === "string") {
+                        this.changedFiles.add(event.path);
+                    }
+                    break;
+            }
+        });
+    }
+    /**
+     * analyze phase용 분석 프롬프트를 생성한다.
+     *
+     * @param goal - 사용자 목표
+     * @param codebaseStats - CodebaseContext 통계
+     * @returns 시스템 프롬프트
+     */
+    buildAnalysisPrompt(goal, codebaseStats) {
+        const statsStr = Object.keys(codebaseStats).length > 0
+            ? `\n## Codebase Statistics\n${JSON.stringify(codebaseStats, null, 2)}`
+            : "";
+        return `You are a code analysis expert. Analyze the user's request and the project context.
+${statsStr}
+
+## Instructions
+1. Determine the complexity of the request: trivial, simple, moderate, complex, or massive
+2. Identify relevant files and patterns
+3. Note any risks or dependencies
+4. Provide a brief analysis summary
+
+Start your response with the complexity level (e.g., "Complexity: moderate")
+Then provide your analysis.`;
+    }
+    /**
+     * 개별 step 실행을 위한 시스템 프롬프트를 생성한다.
+     *
+     * @param plan - 전체 실행 계획
+     * @param step - 현재 step
+     * @param stepIndex - step 인덱스
+     * @returns 시스템 프롬프트
+     */
+    buildStepPrompt(plan, step, stepIndex) {
+        const sections = [];
+        sections.push(`You are an expert coding agent executing step ${stepIndex + 1} of ${plan.steps.length}.`);
+        sections.push("");
+        sections.push(`## Overall Goal`);
+        sections.push(plan.goal);
+        sections.push("");
+        sections.push(`## Current Step`);
+        sections.push(step.goal);
+        sections.push("");
+        if (step.targetFiles.length > 0) {
+            sections.push(`## Target Files`);
+            sections.push(step.targetFiles.join(", "));
+            sections.push("");
+        }
+        if (step.readFiles.length > 0) {
+            sections.push(`## Reference Files (read only)`);
+            sections.push(step.readFiles.join(", "));
+            sections.push("");
+        }
+        sections.push(`## Instructions`);
+        sections.push(`- Focus on this step's goal only`);
+        sections.push(`- Read relevant files before making changes`);
+        sections.push(`- Make precise, minimal changes`);
+        sections.push(`- Verify your changes compile/work`);
+        sections.push(`- When done, provide a summary of what you changed`);
+        return sections.join("\n");
+    }
+    /**
+     * DeepVerifyResult를 StateMachine의 VerifyResult 형식으로 변환한다.
+     *
+     * @param deep - 6-dimension 심층 검증 결과
+     * @returns StateMachine VerifyResult
+     */
+    mapVerifyResult(deep) {
+        const d = deep.dimensions;
+        return {
+            verdict: deep.verdict,
+            checks: {
+                buildSuccess: d.correctness.status !== "fail",
+                typesSafe: d.correctness.status !== "fail",
+                testsPass: d.completeness.status !== "fail",
+                noRegressions: d.consistency.status !== "fail",
+                followsPatterns: d.quality.status !== "fail",
+                securityClean: d.security.status !== "fail",
+            },
+            issues: [
+                ...d.correctness.issues,
+                ...d.completeness.issues,
+                ...d.consistency.issues,
+                ...d.quality.issues,
+                ...d.security.issues,
+                ...d.performance.issues,
+            ],
+            suggestions: deep.suggestedFixes.map((f) => `[${f.dimension}/${f.severity}] ${f.description}`),
+            confidence: deep.confidence,
+        };
+    }
+    /**
+     * StateMachine 최종 상태에서 ExecutionResult를 생성한다.
+     *
+     * @param smState - StateMachine 최종 상태
+     * @param startTime - 실행 시작 시각 (epoch ms)
+     * @returns 실행 결과
+     */
+    buildResult(smState, startTime) {
+        const hasErrors = smState.errors.length > 0;
+        const lastReflection = smState.reflections[smState.reflections.length - 1];
+        const passed = !hasErrors ||
+            (lastReflection && lastReflection.verdict === "pass");
+        // Build summary from step results
+        const summaryParts = [];
+        for (const sr of smState.stepResults) {
+            if (sr.phase === "implement" || sr.phase === "fix") {
+                summaryParts.push(`[${sr.phase}] ${sr.output}`);
+            }
+        }
+        const summary = summaryParts.length > 0
+            ? summaryParts.join("\n")
+            : `Execution completed in phase: ${smState.phase}`;
+        return {
+            success: !!passed,
+            termination: this.lastTermination,
+            finalPhase: smState.phase,
+            changedFiles: [...this.changedFiles],
+            summary,
+            totalTokens: {
+                input: smState.tokenUsage.input,
+                output: smState.tokenUsage.output,
+            },
+            totalIterations: smState.iterationCount,
+            totalToolCalls: smState.toolCalls,
+            durationMs: Date.now() - startTime,
+            verifyResult: this.lastVerifyResult,
+            monologue: [...this.reflection.getMonologue()],
+            learnings: [...this.reflection.getAllLearnings()],
+            plan: this.hierarchicalPlan,
+        };
+    }
+    /**
+     * JSON 문자열에서 JSON 블록을 추출한다.
+     * markdown 코드 펜스 또는 순수 JSON을 처리한다.
+     *
+     * @param content - 원본 문자열
+     * @returns 추출된 JSON 문자열
+     */
+    extractJson(content) {
+        // Strip markdown code fences
+        const fenced = content.match(/```(?:json)?\s*([\s\S]*?)```/);
+        if (fenced) {
+            return fenced[1].trim();
+        }
+        // Find first JSON array or object
+        const arrayMatch = content.match(/\[[\s\S]*\]/);
+        if (arrayMatch) {
+            return arrayMatch[0];
+        }
+        const objectMatch = content.match(/\{[\s\S]*\}/);
+        if (objectMatch) {
+            return objectMatch[0];
+        }
+        return content.trim();
+    }
+}
+//# sourceMappingURL=execution-engine.js.map