@vibecodetown/mcp-server 2.1.4 → 2.2.1

package/build/tools/vibe_pm/context.js

@@ -1,12 +1,53 @@
 // adapters/mcp-ts/src/tools/vibe_pm/context.ts
 // Run context auto-discovery utilities
 import * as fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
 import * as path from "node:path";
 import { TieredCache, createCacheKey } from "../../cache/index.js";
 import { validatePath } from "../../security/path-policy.js";
 import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
 import { RunStateFileSchema } from "../../generated/run_state_file.js";
 // ============================================================
+// P2-19: Async File System Utilities
+// NOTE: Gradual migration from sync to async is in progress.
+// New code should prefer these async helpers.
+// ============================================================
+/**
+ * Check if a path exists (async)
+ */
+async function existsAsync(p) {
+    try {
+        await fsPromises.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a path is a directory (async)
+ */
+async function isDirAsync(p) {
+    try {
+        const stat = await fsPromises.stat(p);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read file content (async)
+ */
+async function readFileAsync(p) {
+    try {
+        return await fsPromises.readFile(p, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================
 // Constants
 // ============================================================
 const RUNS_DIR = "runs";
@@ -51,6 +92,8 @@ function normalizeRunState(raw) {
     const parsed = RunStateFileSchema.safeParse(raw);
     if (!parsed.success)
         return null;
+    // RunStateFileSchema uses z.any().superRefine() for union validation
+    // Type assertion is safe here because safeParse succeeded
     const value = parsed.data;
     const out = {};
     if (typeof value?.phase === "string")
@@ -241,8 +284,38 @@ export function resolveRunId(providedId, basePath = process.cwd()) {
     }
     return { run_id: generateRunId(undefined, basePath), is_new: true };
 }
+/**
+ * Find the .vibe folder in the directory tree (like Git finds .git)
+ * Priority:
+ *   1. VIBE_PROJECT_ROOT environment variable (if set and has .vibe)
+ *   2. Search upward from startPath
+ * @param startPath Starting directory (default: process.cwd())
+ * @returns Path to the directory containing .vibe, or null if not found
+ */
+export function findVibeRoot(startPath = process.cwd()) {
+    // Check VIBE_PROJECT_ROOT environment variable first
+    const envRoot = process.env.VIBE_PROJECT_ROOT;
+    if (envRoot && fs.existsSync(path.join(envRoot, ".vibe"))) {
+        return envRoot;
+    }
+    // Search upward from startPath
+    let current = path.resolve(startPath);
+    const root = path.parse(current).root;
+    while (current !== root) {
+        if (fs.existsSync(path.join(current, ".vibe"))) {
+            return current;
+        }
+        current = path.dirname(current);
+    }
+    // Check root as well
+    if (fs.existsSync(path.join(root, ".vibe"))) {
+        return root;
+    }
+    return null;
+}
 /**
  * Resolve project_id from run_id or folder name
+ * If .vibe folder exists in parent directories, uses that folder's name
  */
 export function resolveProjectId(runId, basePath = process.cwd()) {
     if (runId) {
@@ -258,6 +331,12 @@ export function resolveProjectId(runId, basePath = process.cwd()) {
         }
         return runId;
     }
+    // Find the project root by looking for .vibe folder
+    const vibeRoot = findVibeRoot(basePath);
+    if (vibeRoot) {
+        return sanitizeForId(path.basename(vibeRoot));
+    }
+    // Fallback: use current folder name
     return sanitizeForId(path.basename(basePath));
 }
 // ============================================================

package/build/tools/vibe_pm/create_work_order.js

@@ -14,6 +14,7 @@ import { ClinicBridgeFileSchema } from "../../generated/clinic_bridge_file.js";
 import { loadPromptDensity } from "./intent/prompt_density.js";
 import { runKceRetrieve, runKceStatus } from "./kce/preflight.js";
 import { updateKceDocUsage } from "./kce/doc_usage.js";
+import { getSpecContext } from "./spec_rag.js";
 /**
  * vibe_pm.create_work_order - Issue work order for implementation
  *
@@ -83,17 +84,17 @@ export async function createWorkOrder(input) {
     const headline = "프로젝트 구현";
     const dg = bridgeData?.decision_guard;
     const legacyScope = bridgeData?.scope;
-    const scopeInclude = Array.isArray(dg?.allow_paths)
+    let scopeInclude = Array.isArray(dg?.allow_paths)
         ? dg.allow_paths
         : Array.isArray(legacyScope?.include)
             ? legacyScope.include
             : [];
-    const scopeExclude = Array.isArray(dg?.deny_paths)
+    let scopeExclude = Array.isArray(dg?.deny_paths)
         ? dg.deny_paths
         : Array.isArray(legacyScope?.exclude)
             ? legacyScope.exclude
             : [];
-    const doNotTouch = Array.isArray(dg?.read_only_paths)
+    let doNotTouch = Array.isArray(dg?.read_only_paths)
         ? dg.read_only_paths
         : Array.isArray(bridgeData?.do_not_touch)
             ? bridgeData.do_not_touch
@@ -105,6 +106,27 @@ export async function createWorkOrder(input) {
         : Array.isArray(bridgeData?.verify_criteria)
             ? bridgeData.verify_criteria.filter((s) => typeof s === "string" && s.trim())
             : [];
+    // Add SSOT compliance verification criterion
+    verifyCriteria.push("변경 사항이 기존 SSOT 문서(docs/ssot/*.md)와 충돌하지 않는지 확인");
+    // Bridge protocol (seed consumption):
+    // - If work_order_seed.json exists, it must be consumed (no ignore)
+    // - confirmed_reference.json must exist when seed exists (fail-closed)
+    //
+    // Minimal structured consumption policy:
+    // - Never broaden scope beyond the clinic bridge. Only:
+    //   - Fill missing include list from seed.include (when clinic bridge include is empty)
+    //   - Union in seed.exclude / seed.do_not_touch as additional restrictions
+    const seed = loadBridgeWorkOrderSeedOrThrow({ runDir: context.runs_path });
+    if (seed) {
+        const seedInclude = sanitizePatternList(seed.scope_seed.include);
+        const seedExclude = sanitizePatternList(seed.scope_seed.exclude);
+        const seedDoNotTouch = sanitizePatternList(seed.scope_seed.do_not_touch ?? []);
+        if (scopeInclude.length === 0 && seedInclude.length > 0) {
+            scopeInclude = seedInclude;
+        }
+        scopeExclude = mergeUnique(scopeExclude, seedExclude);
+        doNotTouch = mergeUnique(doNotTouch, seedDoNotTouch);
+    }
     // Generate paste_to_agent text
     let pasteToAgent = generateWorkOrderText({
         projectName,
@@ -118,6 +140,35 @@ export async function createWorkOrder(input) {
     if (input.additional_instructions && input.additional_instructions.trim()) {
         pasteToAgent += `\n\n[추가 지시]\n- ${input.additional_instructions.trim()}\n`;
     }
+    if (seed) {
+        pasteToAgent = applyBridgeSeedToPasteToAgent(pasteToAgent, seed);
+    }
+    // Inject SPEC_CONTEXT from SSOT documents (best-effort)
+    if (promptDensityMode !== "mode_2") {
+        try {
+            const specQuery = [headline, seed?.intent?.goal, verifyCriteria.slice(0, 2).join(" ")]
+                .filter(Boolean)
+                .join(" ");
+            const specResult = await getSpecContext({
+                query: specQuery,
+                maxChars: 2500,
+                maxItems: 4,
+                basePath
+            });
+            if (specResult.context_block) {
+                // Insert SPEC_CONTEXT right after the header line
+                const headerEnd = pasteToAgent.indexOf("\n\n");
+                if (headerEnd > 0) {
+                    const header = pasteToAgent.slice(0, headerEnd);
+                    const rest = pasteToAgent.slice(headerEnd);
+                    pasteToAgent = `${header}\n\n${specResult.context_block}${rest}`;
+                }
+            }
+        }
+        catch {
+            // Best-effort: never block work order issuance when spec context is unavailable
+        }
+    }
     // Ensure versioned modules (Research/Skills/Planning) exist and link them to output
     const modules = ensureModulesForWorkOrder({ basePath, runId: run_id });
     // Append SKILLS_PACK / PLAN_STEPS into paste_to_agent (still user-friendly, no engine terms)
@@ -245,6 +296,152 @@ export async function createWorkOrder(input) {
         }
     };
 }
+export function loadBridgeWorkOrderSeedOrThrow(opts) {
+    const bridgeDir = path.join(opts.runDir, "bridge");
+    const seedPath = path.join(bridgeDir, "work_order_seed.json");
+    const confirmedPath = path.join(bridgeDir, "confirmed_reference.json");
+    if (!fs.existsSync(seedPath))
+        return null;
+    if (!fs.existsSync(confirmedPath)) {
+        throw new Error("레퍼런스 선택 확인 파일이 없어 작업 지시서를 생성할 수 없습니다. 먼저 레퍼런스를 확정해주세요.");
+    }
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(seedPath, "utf-8"));
+    }
+    catch {
+        throw new Error("work_order_seed.json을 읽을 수 없습니다. 파일 내용을 확인해주세요.");
+    }
+    if (!raw || typeof raw !== "object") {
+        throw new Error("work_order_seed.json 형식이 올바르지 않습니다.");
+    }
+    const seed = raw;
+    if (seed.schema_version !== "bridge.work_order_seed.v1") {
+        throw new Error("work_order_seed.json 버전이 올바르지 않습니다.");
+    }
+    if (typeof seed.created_at !== "string" || !seed.created_at) {
+        throw new Error("work_order_seed.json 필수 필드(created_at)가 누락되었습니다.");
+    }
+    if (typeof seed.intent?.goal !== "string" || !seed.intent.goal.trim()) {
+        throw new Error("work_order_seed.json 필수 필드(intent.goal)가 누락되었습니다.");
+    }
+    if (typeof seed.intent?.user_story !== "string" || !seed.intent.user_story.trim()) {
+        throw new Error("work_order_seed.json 필수 필드(intent.user_story)가 누락되었습니다.");
+    }
+    if (!Array.isArray(seed.intent?.acceptance) || seed.intent.acceptance.length < 3) {
+        throw new Error("work_order_seed.json 필수 필드(intent.acceptance)가 부족합니다(최소 3개).");
+    }
+    if (!Array.isArray(seed.scope_seed?.include) || seed.scope_seed.include.length < 1) {
+        throw new Error("work_order_seed.json 필수 필드(scope_seed.include)가 누락되었습니다.");
+    }
+    if (!Array.isArray(seed.scope_seed?.exclude)) {
+        throw new Error("work_order_seed.json 필수 필드(scope_seed.exclude)가 누락되었습니다.");
+    }
+    if (typeof seed.reference?.key !== "string" || !["A", "B", "C"].includes(seed.reference.key)) {
+        throw new Error("work_order_seed.json 필수 필드(reference.key)가 올바르지 않습니다.");
+    }
+    if (typeof seed.reference?.title !== "string" || !seed.reference.title.trim()) {
+        throw new Error("work_order_seed.json 필수 필드(reference.title)가 누락되었습니다.");
+    }
+    if (typeof seed.reference?.primary_link !== "string" || !seed.reference.primary_link.trim()) {
+        throw new Error("work_order_seed.json 필수 필드(reference.primary_link)가 누락되었습니다.");
+    }
+    return seed;
+}
+export function applyBridgeSeedToPasteToAgent(pasteToAgent, seed) {
+    const lines = [];
+    lines.push("[레퍼런스 기준]");
+    lines.push(`- 선택: ${seed.reference.title}`);
+    lines.push(`- 링크: ${seed.reference.primary_link}`);
+    if (Array.isArray(seed.reference.takeaways) && seed.reference.takeaways.length > 0) {
+        lines.push("- 핵심 포인트:");
+        for (const t of seed.reference.takeaways.slice(0, 10)) {
+            if (typeof t === "string" && t.trim())
+                lines.push(`  - ${t.trim()}`);
+        }
+    }
+    lines.push("");
+    lines.push("[사용자 목표]");
+    lines.push(seed.intent.goal.trim());
+    lines.push("");
+    lines.push("[사용자 관점]");
+    lines.push(seed.intent.user_story.trim());
+    lines.push("");
+    lines.push("[완료 기준]");
+    for (const a of seed.intent.acceptance) {
+        if (typeof a === "string" && a.trim())
+            lines.push(`- ${a.trim()}`);
+    }
+    if (Array.isArray(seed.intent.constraints) && seed.intent.constraints.length > 0) {
+        lines.push("");
+        lines.push("[제약]");
+        for (const c of seed.intent.constraints.slice(0, 12)) {
+            if (typeof c === "string" && c.trim())
+                lines.push(`- ${c.trim()}`);
+        }
+    }
+    if (Array.isArray(seed.intent.non_goals) && seed.intent.non_goals.length > 0) {
+        lines.push("");
+        lines.push("[하지 않을 것]");
+        for (const n of seed.intent.non_goals.slice(0, 8)) {
+            if (typeof n === "string" && n.trim())
+                lines.push(`- ${n.trim()}`);
+        }
+    }
+    lines.push("");
+    lines.push("[권장 작업 구역]");
+    for (const p of seed.scope_seed.include.slice(0, 20)) {
+        if (typeof p === "string" && p.trim())
+            lines.push(`- 포함: ${p.trim()}`);
+    }
+    for (const p of seed.scope_seed.exclude.slice(0, 20)) {
+        if (typeof p === "string" && p.trim())
+            lines.push(`- 제외: ${p.trim()}`);
+    }
+    if (Array.isArray(seed.scope_seed.do_not_touch) && seed.scope_seed.do_not_touch.length > 0) {
+        for (const p of seed.scope_seed.do_not_touch.slice(0, 20)) {
+            if (typeof p === "string" && p.trim())
+                lines.push(`- 건드리지 말 것: ${p.trim()}`);
+        }
+    }
+    const seedBlock = lines.join("\n").trimEnd();
+    // Insert seed guidance near the top of the work order so it becomes the primary grounding context.
+    // Prefer placing it right before the first "[목표]" section if present; otherwise prepend.
+    const marker = "\n\n[목표]\n";
+    const idx = pasteToAgent.indexOf(marker);
+    if (idx !== -1) {
+        const head = pasteToAgent.slice(0, idx).trimEnd();
+        const tail = pasteToAgent.slice(idx).trimStart();
+        return `${head}\n\n${seedBlock}\n\n${tail}\n`;
+    }
+    return `${seedBlock}\n\n${pasteToAgent.trimEnd()}\n`;
+}
+function sanitizePatternList(list) {
+    if (!Array.isArray(list))
+        return [];
+    return list
+        .map((p) => (typeof p === "string" ? p.trim() : ""))
+        .filter(Boolean);
+}
+function mergeUnique(base, extra) {
+    const seen = new Set();
+    const out = [];
+    for (const p of base) {
+        const v = typeof p === "string" ? p.trim() : "";
+        if (!v || seen.has(v))
+            continue;
+        seen.add(v);
+        out.push(v);
+    }
+    for (const p of extra) {
+        const v = typeof p === "string" ? p.trim() : "";
+        if (!v || seen.has(v))
+            continue;
+        seen.add(v);
+        out.push(v);
+    }
+    return out;
+}
 function formatPlanSteps(planJsonText) {
     try {
         const doc = JSON.parse(planJsonText);

package/build/tools/vibe_pm/doctor.js

@@ -2,11 +2,13 @@
 // vibe_pm.doctor - Installation health check and auto-repair
 import { DoctorInputSchema } from "../../generated/doctor_input.js";
 import { doctor as runDoctor, healthCheck, checkForUpdates } from "../../bootstrap/doctor.js";
+import { getSkillsHealth } from "../../bootstrap/skills-installer.js";
 import { CONTRACTS_BUNDLE_SHA256, CONTRACTS_SCHEMA_COUNT, CONTRACTS_VERSION } from "../../generated/contracts_bundle_info.js";
 import { getAuthGate } from "../../auth/index.js";
 import { resolveProjectId } from "./context.js";
 import { memoryStatus } from "./memory_status.js";
 import { memorySync } from "./memory_sync.js";
+import { runPythonCli, findPythonRepoRoot } from "../../engine.js";
 // ============================================================
 // Input/Output Types
 // ============================================================
@@ -26,6 +28,36 @@ function mapEngineStatus(status) {
             return "손상됨";
     }
 }
+/**
+ * Check Python CLI health
+ * Verifies that `python -m vibecoding_helper` can be executed
+ */
+async function checkPythonCli() {
+    const cwd = process.cwd();
+    const detectedRoot = findPythonRepoRoot(cwd);
+    try {
+        const result = await runPythonCli(["--help"], { timeoutMs: 10_000 });
+        if (result.code === 0) {
+            return {
+                status: "정상",
+                message: "Python CLI 정상 동작",
+                pythonpath_detected: detectedRoot
+            };
+        }
+        return {
+            status: "오류",
+            message: `Python CLI 오류: ${result.stderr?.slice(0, 100) ?? "알 수 없는 오류"}`,
+            pythonpath_detected: detectedRoot
+        };
+    }
+    catch (e) {
+        return {
+            status: "오류",
+            message: e instanceof Error ? e.message : "알 수 없는 오류",
+            pythonpath_detected: detectedRoot
+        };
+    }
+}
 // ============================================================
 // Doctor Implementation
 // ============================================================
@@ -57,6 +89,23 @@ export async function doctor(input) {
             return null;
         }
     }
+    function getSkillBundleStatus() {
+        const skillsHealth = getSkillsHealth();
+        let status = "OK";
+        if (!skillsHealth.installed || skillsHealth.summary.missing > 0 || skillsHealth.summary.corrupted > 0) {
+            status = "ERROR";
+        }
+        else if (skillsHealth.version !== skillsHealth.version) {
+            // Note: In a real scenario, compare with expected version from registry
+            status = "WARN";
+        }
+        return {
+            status,
+            version: skillsHealth.version,
+            installed: skillsHealth.summary.ok,
+            total: skillsHealth.summary.total
+        };
+    }
     try {
         // Step 1: Quick health check
         const quickCheck = await healthCheck();
@@ -68,6 +117,8 @@ export async function doctor(input) {
                 version: e.version,
                 current_version: e.currentVersion
             }));
+            // Python CLI check
+            const pythonCliStatus = await checkPythonCli();
             // Local Memory check (best-effort)
             let localMemory = await getLocalMemoryStatus();
             if (autoFix && localMemory?.status === "NEEDS_SYNC") {
@@ -91,6 +142,23 @@ export async function doctor(input) {
                     // ignore
                 }
             }
+            // Check if Python CLI has issues
+            if (pythonCliStatus.status === "오류") {
+                return {
+                    status: "NEEDS_ATTENTION",
+                    contracts,
+                    summary: "Python CLI에 문제가 있습니다.",
+                    engines,
+                    python_cli: pythonCliStatus,
+                    skills: getSkillBundleStatus(),
+                    local_memory: localMemory,
+                    actions_taken: actionsTaken.length > 0 ? actionsTaken : undefined,
+                    next_action: {
+                        type: "MANUAL_FIX",
+                        message: `Python CLI 오류: ${pythonCliStatus.message}. PYTHONPATH 설정을 확인하세요.`
+                    }
+                };
+            }
             if (localMemory && localMemory.status !== "READY") {
                 const msg = localMemory.status === "NEEDS_SYNC"
                     ? "Local Memory 갱신이 필요합니다. vibe_pm.memory_sync를 실행해 보세요."
@@ -102,6 +170,8 @@ export async function doctor(input) {
                     contracts,
                     summary: "엔진은 정상입니다. 다만 Local Memory 준비가 필요합니다.",
                     engines,
+                    python_cli: pythonCliStatus,
+                    skills: getSkillBundleStatus(),
                     local_memory: localMemory,
                     actions_taken: actionsTaken.length > 0 ? actionsTaken : undefined,
                     next_action: {
@@ -115,6 +185,8 @@ export async function doctor(input) {
                 contracts,
                 summary: "모든 엔진이 정상적으로 설치되어 있습니다.",
                 engines,
+                python_cli: pythonCliStatus,
+                skills: getSkillBundleStatus(),
                 local_memory: localMemory,
                 actions_taken: actionsTaken.length > 0 ? actionsTaken : undefined,
                 next_action: {
@@ -136,6 +208,8 @@ export async function doctor(input) {
                 version: info.version,
                 current_version: info.currentVersion
             }));
+            // Python CLI check (after auto-fix)
+            const pythonCliStatus = await checkPythonCli();
             if (doctorResult.status === "OK") {
                 actionsTaken.push("문제 자동 수정 완료");
                 // Local Memory check (best-effort)
@@ -172,6 +246,8 @@ export async function doctor(input) {
                         contracts,
                         summary: "엔진은 정상입니다. 다만 Local Memory 준비가 필요합니다.",
                         engines,
+                        python_cli: pythonCliStatus,
+                        skills: getSkillBundleStatus(),
                         actions_taken: actionsTaken,
                         local_memory: localMemory,
                         next_action: {
@@ -185,6 +261,8 @@ export async function doctor(input) {
                     contracts,
                     summary: "문제를 발견하고 자동으로 수정했습니다.",
                     engines,
+                    python_cli: pythonCliStatus,
+                    skills: getSkillBundleStatus(),
                     actions_taken: actionsTaken,
                     local_memory: localMemory,
                     next_action: {
@@ -201,6 +279,8 @@ export async function doctor(input) {
                     contracts,
                     summary: "일부 엔진 업데이트가 필요합니다.",
                     engines,
+                    python_cli: pythonCliStatus,
+                    skills: getSkillBundleStatus(),
                     actions_taken: actionsTaken,
                     local_memory: localMemory,
                     next_action: {
@@ -216,6 +296,8 @@ export async function doctor(input) {
                 contracts,
                 summary: doctorResult.error ?? "알 수 없는 오류가 발생했습니다.",
                 engines,
+                python_cli: pythonCliStatus,
+                skills: getSkillBundleStatus(),
                 actions_taken: actionsTaken,
                 local_memory: localMemory,
                 next_action: {
@@ -231,6 +313,7 @@ export async function doctor(input) {
             version: e.version,
             current_version: e.currentVersion
         }));
+        const pythonCliStatus = await checkPythonCli();
         const issueCount = engines.filter((e) => e.status !== "정상").length;
         const localMemory = await getLocalMemoryStatus();
         return {
@@ -238,6 +321,8 @@ export async function doctor(input) {
             contracts,
             summary: `${issueCount}개의 엔진에 문제가 있습니다.`,
             engines,
+            python_cli: pythonCliStatus,
+            skills: getSkillBundleStatus(),
             local_memory: localMemory,
             next_action: {
                 type: "MANUAL_FIX",
@@ -247,11 +332,21 @@ export async function doctor(input) {
     }
     catch (e) {
         const localMemory = await getLocalMemoryStatus();
+        // Try to get Python CLI status even in error state
+        let pythonCliStatus;
+        try {
+            pythonCliStatus = await checkPythonCli();
+        }
+        catch {
+            // ignore
+        }
         return {
             status: "ERROR",
             contracts,
             summary: e instanceof Error ? e.message : "알 수 없는 오류",
             engines: [],
+            python_cli: pythonCliStatus,
+            skills: getSkillBundleStatus(),
             local_memory: localMemory,
             next_action: {
                 type: "CONTACT_SUPPORT",

package/build/tools/vibe_pm/entity_gate/preflight.js

@@ -3,9 +3,10 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { z } from "zod";
-import { runEngine } from "../../../engine.js";
+import { runPythonCli } from "../../../engine.js";
 import { safeJsonParse } from "../../../cli.js";
 import { resolveRunDir } from "../context.js";
+import { classifyPythonError } from "../python_error.js";
 const EntityGateReportSchema = z.object({
     status: z.enum(["OK", "FAIL"]),
     errors: z.array(z.string()),
@@ -38,9 +39,13 @@ function kceEventsPath(run_id, basePath) {
 export async function runEntityGate(args) {
     const eventsPath = args.writeEvidence && args.run_id ? kceEventsPath(args.run_id, args.basePath) : null;
     try {
-        const { code, stdout, stderr } = await runEngine("vibecoding-helper", ["entity-gate"], { timeoutMs: 60_000 });
+        const { code, stdout, stderr } = await runPythonCli(["entity-gate"], { timeoutMs: 60_000 });
         if (code !== 0 && !stdout.trim()) {
-            throw new Error(`entity-gate failed: ${stderr || `exit_code=${code}`}`);
+            const classified = classifyPythonError(stderr ?? "", code, "Entity Gate");
+            const hint = classified.issueCode === "python_module_not_found"
+                ? " (PYTHONPATH 문제 - vibe_pm.doctor 실행 권장)"
+                : "";
+            throw new Error(`${classified.issueCode}: ${classified.summary}${hint}`);
         }
         const parsed = safeJsonParse(stdout);
         if (!parsed.ok)

package/build/tools/vibe_pm/export_output.js

@@ -2,14 +2,13 @@
 // vibe_pm.export_output - Export a feature into a chosen output format via Output Adapters
 import * as path from "node:path";
 import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
-import { runEngine } from "../../engine.js";
+import { runPythonCli } from "../../engine.js";
 import { safeJsonParse } from "../../cli.js";
 import { validateToolInput } from "../../security/input-validator.js";
 import { isPathForbidden, validatePath } from "../../security/path-policy.js";
 import { resolveProjectId, resolveRunId, resolveRunDir } from "./context.js";
-function normalizeRelPosix(p) {
-    return p.replace(/\\/g, "/").replace(/^\/+/, "");
-}
+import { classifyPythonError } from "./python_error.js";
+import { normalizeRelativePosix } from "../../path-utils.js";
 function resolveDefaultOutputDir(target) {
     const t = (target ?? "").trim();
     return t ? `export/${t}` : "export/out";
@@ -41,7 +40,7 @@ export async function exportOutput(input) {
     }
     const outputDirInput = (input.output_dir ?? "").trim() || resolveDefaultOutputDir(target);
     const outputDirAbs = validatePath(outputDirInput, basePath);
-    const outputDirRel = normalizeRelPosix(path.relative(basePath, outputDirAbs));
+    const outputDirRel = normalizeRelativePosix(path.relative(basePath, outputDirAbs));
     const forbid = isPathForbidden(outputDirRel);
     if (forbid.forbidden) {
         throw new McpError(ErrorCode.InvalidParams, "Forbidden export output_dir.", {
@@ -64,9 +63,10 @@ export async function exportOutput(input) {
     }
     if (dryRun)
         planCmd.push("--dry-run");
-    const planRes = await runEngine("vibecoding-helper", planCmd, { timeoutMs: 120_000 });
+    const planRes = await runPythonCli(planCmd, { timeoutMs: 120_000 });
     if (planRes.code !== 0) {
-        throw new Error(`export-plan failed: ${planRes.stderr || `exit_code=${planRes.code}`}`);
+        const classified = classifyPythonError(planRes.stderr ?? "", planRes.code, "export-plan");
+        throw new Error(`${classified.issueCode}: ${classified.summary}`);
     }
     const planParsed = safeJsonParse(planRes.stdout);
     if (!planParsed.ok) {
@@ -94,9 +94,10 @@ export async function exportOutput(input) {
         ];
         if (needsTemplatePin)
             genCmd.push("--template-repo", templateRepo, "--template-ref", templateRef);
-        const genRes = await runEngine("vibecoding-helper", genCmd, { timeoutMs: 300_000 });
+        const genRes = await runPythonCli(genCmd, { timeoutMs: 300_000 });
         if (genRes.code !== 0) {
-            throw new Error(`export-generate failed: ${genRes.stderr || `exit_code=${genRes.code}`}`);
+            const classified = classifyPythonError(genRes.stderr ?? "", genRes.code, "export-generate");
+            throw new Error(`${classified.issueCode}: ${classified.summary}`);
         }
         const genParsed = safeJsonParse(genRes.stdout);
         if (!genParsed.ok) {
@@ -107,10 +108,10 @@ export async function exportOutput(input) {
             for (const f of files) {
                 const p = typeof f?.path === "string" ? f.path : "";
                 if (p)
-                    createdPaths.push(normalizeRelPosix(p));
+                    createdPaths.push(normalizeRelativePosix(p));
             }
         }
-        artifactsPathRel = normalizeRelPosix(path.relative(basePath, exportArtifactsPath(runDirAbs)));
+        artifactsPathRel = normalizeRelativePosix(path.relative(basePath, exportArtifactsPath(runDirAbs)));
     }
     const out = {
         success: true,
@@ -120,8 +121,8 @@ export async function exportOutput(input) {
         output_dir: outputDirRel,
         dry_run: dryRun,
         paths: {
-            feature_output_spec_path: normalizeRelPosix(path.relative(basePath, specAbs)),
-            export_plan_path: normalizeRelPosix(path.relative(basePath, exportPlanPath(runDirAbs))),
+            feature_output_spec_path: normalizeRelativePosix(path.relative(basePath, specAbs)),
+            export_plan_path: normalizeRelativePosix(path.relative(basePath, exportPlanPath(runDirAbs))),
             export_artifacts_path: artifactsPathRel
         },
         created_paths: createdPaths,