@vibecodetown/mcp-server 2.1.0

package/build/tools/vibe_pm/types.js

@@ -0,0 +1,229 @@
+// adapters/mcp-ts/src/tools/vibe_pm/types.ts
+// Type definitions for vibe_pm.* MCP tools
+// Reference: docs/DEV_SPEC/MCP_TOOL_SCHEMA_SPEC.md
+import { z } from "zod";
+// ============================================================
+// vibe_pm.briefing
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const briefingInputSchema = BriefingInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const briefingOutputSchema = BriefingOutputSchema;
+// ============================================================
+// vibe_pm.get_decision
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const getDecisionInputSchema = GetDecisionInputSchema;
+const choiceSchema = z.object({
+    key: z.enum(["A", "B", "C", "U"]).describe("선택 키"),
+    label: z.string().describe("선택지 레이블"),
+    description: z.string().optional().describe("선택지 설명")
+});
+const decisionRequestSchema = z.object({
+    decision_id: z.string().describe("결재 ID (내부용)"),
+    title: z.string().describe("비즈니스 언어 제목"),
+    context: z.string().describe("컨텍스트 설명 (기술 용어 없음)"),
+    choices: z.array(choiceSchema).describe("선택 가능한 옵션들")
+});
+// Output schema is generated from JSON Schema SSOT.
+export const getDecisionOutputSchema = GetDecisionOutputSchema;
+// ============================================================
+// vibe_pm.memory_status
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const memoryStatusInputSchema = MemoryStatusInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const memoryStatusOutputSchema = MemoryStatusOutputSchema;
+// ============================================================
+// vibe_pm.memory_sync
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const memorySyncInputSchema = MemorySyncInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const memorySyncOutputSchema = MemorySyncOutputSchema;
+// ============================================================
+// vibe_pm.advisory_review
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const advisoryReviewInputSchema = AdvisoryReviewInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const advisoryReviewOutputSchema = AdvisoryReviewOutputSchema;
+// ============================================================
+// vibe_pm.activate
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const activateInputSchema = ActivateInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const activateOutputSchema = ActivateOutputSchema;
+// ============================================================
+// vibe_pm.submit_decision
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const submitDecisionInputSchema = SubmitDecisionInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const submitDecisionOutputSchema = SubmitDecisionOutputSchema;
+// ============================================================
+// vibe_pm.create_work_order
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const createWorkOrderInputSchema = CreateWorkOrderInputSchema;
+const workOrderSchema = z.object({
+    headline: z.string().describe("현재 작업 목표 (단일 항목)"),
+    scope: z.object({
+        include: z.array(z.string()).describe("포함 범위"),
+        exclude: z.array(z.string()).describe("제외 범위")
+    }).describe("작업 범위 정의"),
+    do_not_touch: z.array(z.string()).describe("건드리지 말아야 할 항목"),
+    verify_criteria: z.array(z.string()).describe("검증 기준"),
+    paste_to_agent: z.string().describe("AI 에이전트에 붙여넣을 텍스트")
+});
+// Output schema is generated from JSON Schema SSOT.
+export const createWorkOrderOutputSchema = CreateWorkOrderOutputSchema;
+// ============================================================
+// vibe_pm.inspect_code
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const inspectCodeInputSchema = InspectCodeInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const inspectCodeOutputSchema = InspectCodeOutputSchema;
+/**
+ * P11: Validate inspect_code output against schema contract
+ * @throws ZodError if validation fails
+ */
+export function validateInspectCodeOutput(output) {
+    return inspectCodeOutputSchema.parse(output);
+}
+/**
+ * P14: Select message template ID based on review result and issues
+ * Reference: docs/specs/PM_USER_MESSAGES_SSOT_v1.0.md
+ *
+ * Selection rules:
+ * - GO → GO-01 (기본) or GO-02 (다음 작업 연결 시)
+ * - FIX + VERIFY_FAIL → FIX-02
+ * - FIX (other) → FIX-01
+ * - BLOCK + RULE_VIOLATION|RISK_SPIKE → BLOCK-01
+ * - BLOCK + SCOPE_MISMATCH → BLOCK-02
+ */
+export function selectMessageTemplate(reviewResult, issues, hasNextWorkOrder = false) {
+    const issueTypes = new Set(issues.map(i => i.type));
+    switch (reviewResult) {
+        case "GO":
+            return hasNextWorkOrder ? "GO-02" : "GO-01";
+        case "FIX":
+            return issueTypes.has("VERIFY_FAIL") ? "FIX-02" : "FIX-01";
+        case "BLOCK":
+            if (issueTypes.has("RULE_VIOLATION") || issueTypes.has("RISK_SPIKE")) {
+                return "BLOCK-01";
+            }
+            return "BLOCK-02"; // SCOPE_MISMATCH or default
+        default:
+            return "GO-01";
+    }
+}
+// ============================================================
+// vibe_pm.status
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const statusInputSchema = StatusInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const statusOutputSchema = StatusOutputSchema;
+// ============================================================
+// vibe_pm.repair_plan
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const repairPlanInputSchema = RepairPlanInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const repairPlanOutputSchema = RepairPlanOutputSchema;
+// ============================================================
+// vibe_pm.scaffold (Vibe-SDS - Standard Directory Structure)
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const scaffoldInputSchema = ScaffoldInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const scaffoldOutputSchema = ScaffoldOutputSchema;
+// ============================================================
+// vibe_pm.finalize_work
+// ============================================================
+// Imported from generated SSOT
+import { BriefingInputSchema } from "../../generated/briefing_input.js";
+import { CreateWorkOrderOutputSchema } from "../../generated/create_work_order_output.js";
+import { BriefingOutputSchema } from "../../generated/briefing_output.js";
+import { DoctorOutputSchema } from "../../generated/doctor_output.js";
+import { FinalizeWorkInputSchema } from "../../generated/finalize_work_input.js";
+import { FinalizeWorkOutputSchema } from "../../generated/finalize_work_output.js";
+import { GetDecisionInputSchema } from "../../generated/get_decision_input.js";
+import { GetDecisionOutputSchema } from "../../generated/get_decision_output.js";
+import { CreateWorkOrderInputSchema } from "../../generated/create_work_order_input.js";
+import { InspectCodeInputSchema } from "../../generated/inspect_code_input.js";
+import { InspectCodeOutputSchema } from "../../generated/inspect_code_output.js";
+import { RepairPlanInputSchema } from "../../generated/repair_plan_input.js";
+import { RepairPlanOutputSchema } from "../../generated/repair_plan_output.js";
+import { RunAppInputSchema } from "../../generated/run_app_input.js";
+import { RunAppOutputSchema } from "../../generated/run_app_output.js";
+import { ScaffoldInputSchema } from "../../generated/scaffold_input.js";
+import { ScaffoldOutputSchema } from "../../generated/scaffold_output.js";
+import { StatusInputSchema } from "../../generated/status_input.js";
+import { StatusOutputSchema } from "../../generated/status_output.js";
+import { SubmitDecisionInputSchema } from "../../generated/submit_decision_input.js";
+import { SubmitDecisionOutputSchema } from "../../generated/submit_decision_output.js";
+import { UndoLastTaskInputSchema } from "../../generated/undo_last_task_input.js";
+import { UndoLastTaskOutputSchema } from "../../generated/undo_last_task_output.js";
+import { UpdateOutputSchema } from "../../generated/update_output.js";
+import { MemoryStatusInputSchema } from "../../generated/memory_status_input.js";
+import { MemoryStatusOutputSchema } from "../../generated/memory_status_output.js";
+import { MemorySyncInputSchema } from "../../generated/memory_sync_input.js";
+import { MemorySyncOutputSchema } from "../../generated/memory_sync_output.js";
+import { AdvisoryReviewInputSchema } from "../../generated/advisory_review_input.js";
+import { AdvisoryReviewOutputSchema } from "../../generated/advisory_review_output.js";
+import { ActivateInputSchema } from "../../generated/activate_input.js";
+import { ActivateOutputSchema } from "../../generated/activate_output.js";
+import { ExportOutputInputSchema } from "../../generated/export_output_input.js";
+import { ExportOutputOutputSchema } from "../../generated/export_output_output.js";
+import { SearchOssInputSchema } from "../../generated/search_oss_input.js";
+import { SearchOssOutputSchema } from "../../generated/search_oss_output.js";
+import { ZoektEvidenceInputSchema } from "../../generated/zoekt_evidence_input.js";
+import { ZoektEvidenceOutputSchema } from "../../generated/zoekt_evidence_output.js";
+export const finalizeWorkInputSchema = FinalizeWorkInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const finalizeWorkOutputSchema = FinalizeWorkOutputSchema;
+// ============================================================
+// vibe_pm.undo_last_task
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const undoLastTaskInputSchema = UndoLastTaskInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const undoLastTaskOutputSchema = UndoLastTaskOutputSchema;
+// ============================================================
+// vibe_pm.run_app
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const runAppInputSchema = RunAppInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const runAppOutputSchema = RunAppOutputSchema;
+// ============================================================
+// vibe_pm.export_output
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const exportOutputInputSchema = ExportOutputInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const exportOutputOutputSchema = ExportOutputOutputSchema;
+// ============================================================
+// vibe_pm.search_oss
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const searchOssInputSchema = SearchOssInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const searchOssOutputSchema = SearchOssOutputSchema;
+// ============================================================
+// vibe_pm.zoekt_evidence
+// ============================================================
+// Input schema is generated from JSON Schema SSOT.
+export const zoektEvidenceInputSchema = ZoektEvidenceInputSchema;
+// Output schema is generated from JSON Schema SSOT.
+export const zoektEvidenceOutputSchema = ZoektEvidenceOutputSchema;
+// ============================================================
+// vibe_pm.doctor / vibe_pm.update (Output SSOT only)
+// ============================================================
+export const doctorOutputSchema = DoctorOutputSchema;
+export const updateOutputSchema = UpdateOutputSchema;
+// All output schemas are exported in-place above

package/build/tools/vibe_pm/undo_last_task.js

@@ -0,0 +1,163 @@
+// adapters/mcp-ts/src/tools/vibe_pm/undo_last_task.ts
+// vibe_pm.undo_last_task - Time machine rollback via git revert
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+/**
+ * vibe_pm.undo_last_task - Rollback recent commits via git revert
+ *
+ * Steps:
+ * 1. git log --oneline -n {steps} to get recent commits
+ * 2. For each commit, git revert --no-edit
+ * 3. Add [ROLLBACK] entry to DEV_LOG
+ * 4. Return result
+ */
+export async function undoLastTask(input) {
+    const basePath = process.cwd();
+    const steps = input.steps ?? 1;
+    const reason = input.reason ?? "사용자 요청으로 롤백";
+    // Step 1: Get recent commits
+    let commits;
+    try {
+        commits = await getRecentCommits(basePath, steps);
+    }
+    catch (err) {
+        return {
+            success: false,
+            reverted_tasks: [],
+            current_commit: "unknown",
+            message: `Git 로그를 가져올 수 없습니다: ${err instanceof Error ? err.message : String(err)}`
+        };
+    }
+    if (commits.length === 0) {
+        return {
+            success: false,
+            reverted_tasks: [],
+            current_commit: await getCurrentCommit(basePath),
+            message: "되돌릴 커밋이 없습니다"
+        };
+    }
+    // Step 2: Revert each commit
+    const revertedTasks = [];
+    const revertErrors = [];
+    for (const commit of commits) {
+        try {
+            await execAsync(`git revert --no-edit ${commit.hash}`, { cwd: basePath });
+            revertedTasks.push({
+                commit_hash: commit.shortHash,
+                task_summary: commit.subject,
+                timestamp: commit.timestamp
+            });
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            revertErrors.push(`${commit.shortHash}: ${errMsg}`);
+            // If revert fails due to conflicts, abort and stop
+            if (errMsg.includes("conflict") || errMsg.includes("CONFLICT")) {
+                try {
+                    await execAsync("git revert --abort", { cwd: basePath });
+                }
+                catch {
+                    // Ignore abort errors
+                }
+                break;
+            }
+        }
+    }
+    // Step 3: Add DEV_LOG entry
+    if (revertedTasks.length > 0) {
+        try {
+            await addRollbackLog(basePath, revertedTasks, reason);
+        }
+        catch {
+            // Logging is optional
+        }
+    }
+    // Step 4: Get current commit
+    const currentCommit = await getCurrentCommit(basePath);
+    // Determine result message
+    let message;
+    if (revertedTasks.length === steps) {
+        message = `${revertedTasks.length}개 작업을 성공적으로 롤백했습니다`;
+    }
+    else if (revertedTasks.length > 0) {
+        message = `${revertedTasks.length}/${steps}개 작업을 롤백했습니다. 일부 실패: ${revertErrors.join("; ")}`;
+    }
+    else {
+        message = `롤백 실패: ${revertErrors.join("; ")}`;
+    }
+    return {
+        success: revertedTasks.length > 0,
+        reverted_tasks: revertedTasks,
+        current_commit: currentCommit,
+        message
+    };
+}
+/**
+ * Get recent commits from git log
+ */
+async function getRecentCommits(basePath, count) {
+    const { stdout } = await execAsync(`git log --oneline -n ${count} --format="%H|%h|%s|%ci"`, { cwd: basePath });
+    const commits = [];
+    const lines = stdout.trim().split("\n").filter(Boolean);
+    for (const line of lines) {
+        const [hash, shortHash, subject, timestamp] = line.split("|");
+        if (hash && shortHash && subject) {
+            commits.push({
+                hash,
+                shortHash,
+                subject,
+                timestamp: timestamp ?? new Date().toISOString()
+            });
+        }
+    }
+    return commits;
+}
+/**
+ * Get current HEAD commit hash
+ */
+async function getCurrentCommit(basePath) {
+    try {
+        const { stdout } = await execAsync("git rev-parse --short HEAD", { cwd: basePath });
+        return stdout.trim();
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Add rollback entry to DEV_LOG
+ */
+async function addRollbackLog(basePath, revertedTasks, reason) {
+    const today = new Date();
+    const dateStr = today.toISOString().split("T")[0];
+    const time = today.toISOString().split("T")[1]?.slice(0, 5) ?? "";
+    const devLogDir = path.join(basePath, "docs", "dev_logs");
+    const devLogPath = path.join(devLogDir, `${dateStr}.md`);
+    // Ensure directory exists
+    if (!fs.existsSync(devLogDir)) {
+        fs.mkdirSync(devLogDir, { recursive: true });
+    }
+    // Create rollback entry
+    const taskList = revertedTasks
+        .map((t) => `- \`${t.commit_hash}\`: ${t.task_summary}`)
+        .join("\n");
+    const entry = `## ${time} - [ROLLBACK] 작업 취소
+
+**이유:** ${reason}
+
+**취소된 작업:**
+${taskList}
+
+---
+`;
+    if (fs.existsSync(devLogPath)) {
+        fs.appendFileSync(devLogPath, `\n${entry}`);
+    }
+    else {
+        const header = `# DEV LOG - ${dateStr}\n\n`;
+        fs.writeFileSync(devLogPath, header + entry);
+    }
+}

package/build/tools/vibe_pm/update.js

@@ -0,0 +1,146 @@
+// adapters/mcp-ts/src/tools/vibe_pm/update.ts
+// vibe_pm.update - Manual engine update
+import { UpdateInputSchema } from "../../generated/update_input.js";
+import { ensureEngines, checkUpdates, clearCache, getEngineHealth } from "../../bootstrap/installer.js";
+import { ENGINE_SPECS } from "../../bootstrap/registry.js";
+// ============================================================
+// Input/Output Types
+// ============================================================
+export { UpdateInputSchema };
+// ============================================================
+// Update Implementation
+// ============================================================
+/**
+ * vibe_pm.update - Manual engine update
+ *
+ * PM-friendly description:
+ * 엔진 바이너리를 최신 버전으로 업데이트합니다.
+ */
+export async function update(input) {
+    const force = input.force ?? false;
+    const targetEngines = input.engines ?? Object.keys(ENGINE_SPECS);
+    const results = [];
+    try {
+        // Step 1: Check what needs updating
+        const updateStatus = await checkUpdates();
+        // Step 2: Filter engines to update
+        const enginesToUpdate = [];
+        for (const name of targetEngines) {
+            if (!(name in ENGINE_SPECS)) {
+                results.push({
+                    name,
+                    action: "failed",
+                    from_version: null,
+                    to_version: "unknown",
+                    message: `알 수 없는 엔진: ${name}`
+                });
+                continue;
+            }
+            const engineName = name;
+            const status = updateStatus[engineName];
+            if (force || status.needsUpdate) {
+                enginesToUpdate.push(engineName);
+            }
+            else {
+                results.push({
+                    name: engineName,
+                    action: "skipped",
+                    from_version: status.current,
+                    to_version: status.required,
+                    message: "이미 최신 버전입니다"
+                });
+            }
+        }
+        // Step 3: Clear cache if force mode
+        if (force) {
+            for (const name of enginesToUpdate) {
+                await clearCache(name);
+            }
+        }
+        // Step 4: Update engines
+        if (enginesToUpdate.length > 0) {
+            // Run ensureEngines which will update anything that needs updating
+            await ensureEngines();
+            // Check results
+            const newHealth = await getEngineHealth();
+            for (const name of enginesToUpdate) {
+                const health = newHealth.find((h) => h.name === name);
+                const oldStatus = updateStatus[name];
+                if (health?.status === "ok") {
+                    results.push({
+                        name,
+                        action: "updated",
+                        from_version: oldStatus.current,
+                        to_version: health.version,
+                        message: force ? "강제 재설치 완료" : "업데이트 완료"
+                    });
+                }
+                else {
+                    results.push({
+                        name,
+                        action: "failed",
+                        from_version: oldStatus.current,
+                        to_version: oldStatus.required,
+                        message: `업데이트 실패: ${health?.status ?? "unknown"}`
+                    });
+                }
+            }
+        }
+        // Step 5: Generate summary
+        const updated = results.filter((r) => r.action === "updated").length;
+        const skipped = results.filter((r) => r.action === "skipped").length;
+        const failed = results.filter((r) => r.action === "failed").length;
+        let status;
+        let summary;
+        let nextAction;
+        if (failed > 0 && updated === 0) {
+            status = "ERROR";
+            summary = `업데이트 실패: ${failed}개 엔진`;
+            nextAction = {
+                type: "RETRY",
+                message: "force: true 옵션으로 다시 시도하거나, 네트워크 연결을 확인하세요."
+            };
+        }
+        else if (failed > 0) {
+            status = "PARTIAL";
+            summary = `부분 성공: ${updated}개 업데이트, ${failed}개 실패`;
+            nextAction = {
+                type: "RETRY",
+                message: "실패한 엔진은 force: true 옵션으로 다시 시도하세요."
+            };
+        }
+        else if (updated > 0) {
+            status = "OK";
+            summary = `${updated}개 엔진 업데이트 완료`;
+            nextAction = {
+                type: "NONE",
+                message: "모든 엔진이 최신 버전입니다."
+            };
+        }
+        else {
+            status = "OK";
+            summary = "모든 엔진이 이미 최신 버전입니다";
+            nextAction = {
+                type: "NONE",
+                message: "업데이트할 항목이 없습니다."
+            };
+        }
+        return {
+            status,
+            summary,
+            results,
+            next_action: nextAction
+        };
+    }
+    catch (e) {
+        return {
+            status: "ERROR",
+            summary: e instanceof Error ? e.message : "알 수 없는 오류",
+            results,
+            next_action: {
+                type: "CONTACT_SUPPORT",
+                message: "업데이트 중 오류가 발생했습니다. 네트워크 연결을 확인하고 다시 시도하세요."
+            }
+        };
+    }
+}

package/build/tools/vibe_pm/zoekt_evidence.js

@@ -0,0 +1,96 @@
+// adapters/mcp-ts/src/tools/vibe_pm/zoekt_evidence.ts
+// vibe_pm.zoekt_evidence - Collect pattern evidence across local roots (zoekt/rg/python_scan)
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { runEngine } from "../../engine.js";
+import { safeJsonParse } from "../../cli.js";
+import { validateToolInput } from "../../security/input-validator.js";
+import { resolveProjectId, resolveRunId } from "./context.js";
+function toCsv(values) {
+    return values
+        .map((v) => (typeof v === "string" ? v.trim() : ""))
+        .filter(Boolean)
+        .join(",");
+}
+function toInt(v) {
+    if (typeof v === "number" && Number.isFinite(v))
+        return Math.trunc(v);
+    if (typeof v === "string") {
+        const n = Number(v);
+        if (Number.isFinite(n))
+            return Math.trunc(n);
+    }
+    return undefined;
+}
+export async function zoektEvidence(input) {
+    const basePath = process.cwd();
+    validateToolInput({ project_id: input.project_id, run_id: input.run_id });
+    const resolvedRun = resolveRunId(input.run_id ?? input.project_id, basePath);
+    const run_id = resolvedRun.run_id;
+    const project_id = resolveProjectId(run_id, basePath);
+    const roots = Array.isArray(input.roots) ? input.roots.map((r) => String(r).trim()).filter(Boolean) : [];
+    const queries = Array.isArray(input.queries) ? input.queries.map((q) => String(q).trim()).filter(Boolean) : [];
+    if (roots.length === 0)
+        throw new McpError(ErrorCode.InvalidParams, "[VALIDATION] roots is required");
+    if (queries.length === 0)
+        throw new McpError(ErrorCode.InvalidParams, "[VALIDATION] queries is required");
+    const cmd = ["zoekt-evidence", run_id, "--roots", toCsv(roots), "--queries", toCsv(queries)];
+    const samplePaths = toInt(input?.sample_paths);
+    if (samplePaths !== undefined)
+        cmd.push("--sample-paths", String(samplePaths));
+    const maxFileBytes = toInt(input?.max_file_bytes);
+    if (maxFileBytes !== undefined)
+        cmd.push("--max-file-bytes", String(maxFileBytes));
+    const writeEvidence = input?.write_evidence !== false;
+    if (!writeEvidence)
+        cmd.push("--no-write-evidence");
+    const res = await runEngine("vibecoding-helper", cmd, { timeoutMs: 300_000 });
+    if (res.code !== 0) {
+        throw new Error(`zoekt-evidence failed: ${res.stderr || res.stdout || `exit_code=${res.code}`}`);
+    }
+    const parsed = safeJsonParse(res.stdout);
+    if (!parsed.ok) {
+        throw new Error(`zoekt-evidence invalid_json: ${parsed.error}`);
+    }
+    const doc = parsed.value;
+    const engineRaw = typeof doc?.engine === "string" ? doc.engine : "";
+    const engine = engineRaw === "zoekt" || engineRaw === "rg" || engineRaw === "python_scan" ? engineRaw : "python_scan";
+    const warnings = [];
+    if (Array.isArray(doc?.warnings)) {
+        for (const w of doc.warnings) {
+            if (typeof w === "string" && w.trim())
+                warnings.push(w.trim());
+        }
+    }
+    const queriesOut = [];
+    const rawQueries = Array.isArray(doc?.queries) ? doc.queries : [];
+    for (const q of rawQueries) {
+        const obj = q;
+        const qq = typeof obj?.q === "string" ? obj.q.trim() : "";
+        if (!qq)
+            continue;
+        queriesOut.push({
+            q: qq,
+            repos_scanned: typeof obj?.repos_scanned === "number" ? obj.repos_scanned : 0,
+            match_count: typeof obj?.match_count === "number" ? obj.match_count : 0,
+            sample_paths: Array.isArray(obj?.sample_paths)
+                ? obj.sample_paths.map((x) => String(x)).filter(Boolean)
+                : []
+        });
+    }
+    const evidencePath = typeof doc?.evidence_path === "string" && doc.evidence_path.trim() ? String(doc.evidence_path).trim() : undefined;
+    const out = {
+        success: true,
+        project_id,
+        run_id,
+        engine,
+        queries: queriesOut,
+        warnings,
+        next_action: {
+            tool: "vibe_pm.export_output",
+            reason: "Use this evidence to validate patterns/OSS choices, then export."
+        }
+    };
+    if (evidencePath)
+        out.evidence_path = evidencePath;
+    return out;
+}