@vibecodetown/mcp-server 2.2.0 → 2.2.1

package/build/tools/vibe_pm/bridge_generate_references.js

@@ -0,0 +1,258 @@
+// adapters/mcp-ts/src/tools/vibe_pm/bridge_generate_references.ts
+// vibe_pm.bridge_generate_references - Create runs/<run_id>/bridge/references.json (A/B/C)
+import * as fsSync from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { decode as decodeMsgpack } from "@msgpack/msgpack";
+import { validateToolInput } from "../../security/input-validator.js";
+import { resolveProjectId, resolveRunId, getRunContext } from "./context.js";
+import { BridgeReferencesFileSchema } from "../../generated/bridge_references_file.js";
+import { searchOss } from "./search_oss.js";
+function sanitizeStrings(values, maxItems) {
+    if (!Array.isArray(values))
+        return [];
+    return values
+        .map((v) => (typeof v === "string" ? v.trim() : ""))
+        .filter(Boolean)
+        .slice(0, maxItems);
+}
+function keyForIndex(i) {
+    return i === 0 ? "A" : i === 1 ? "B" : "C";
+}
+function toRelPath(basePath, absPath) {
+    const rel = path.relative(basePath, absPath);
+    return rel.replace(/\\\\/g, "/");
+}
+export async function bridgeGenerateReferences(input, 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 context = getRunContext(run_id, basePath);
+    const rawUserIntent = String(input.raw_user_intent ?? "").trim();
+    let keywords = sanitizeStrings(input?.keywords, 12);
+    if (!rawUserIntent)
+        throw new Error("raw_user_intent is required");
+    if (keywords.length === 0) {
+        keywords = deriveKeywordsFromContextScan({ basePath, runDirAbs: context.runs_path });
+        if (keywords.length === 0) {
+            keywords = ["reference"];
+        }
+    }
+    const constraints = sanitizeStrings(input?.constraints, 12);
+    const mustHave = sanitizeStrings(input?.must_have, 12);
+    const mustNot = sanitizeStrings(input?.must_not, 12);
+    const maxCandidates = typeof input?.max_candidates === "number" ? Math.trunc(input.max_candidates) : 3;
+    const maxK = maxCandidates >= 2 && maxCandidates <= 3 ? maxCandidates : 3;
+    const warnings = [];
+    // Candidate sources:
+    // 1) candidates_seed (explicit) - deterministic + test-friendly
+    // 2) best-effort OSS search (vibe_pm.search_oss) - may fail offline
+    // 3) fallback patterns (always available)
+    const seedCandidates = Array.isArray(input?.candidates_seed) ? input.candidates_seed : [];
+    const candidates = [];
+    if (seedCandidates.length > 0) {
+        warnings.push("OSS_SEARCH_SKIPPED: candidates_seed provided");
+        for (const c of seedCandidates.slice(0, maxK)) {
+            const obj = c;
+            const title = typeof obj?.title === "string" ? obj.title.trim() : "";
+            const kind = typeof obj?.kind === "string" ? obj.kind : "doc";
+            const primary_link = typeof obj?.primary_link === "string" ? obj.primary_link.trim() : "";
+            if (!title || !primary_link)
+                continue;
+            candidates.push({
+                title,
+                kind,
+                why_similar: typeof obj?.why_similar === "string" ? obj.why_similar : "유사 레퍼런스",
+                fit_summary: typeof obj?.fit_summary === "string" ? obj.fit_summary : "",
+                confidence: 4,
+                links: { primary: primary_link, secondary: [] },
+                evidence: { source: "manual", highlights: [] }
+            });
+        }
+    }
+    else {
+        try {
+            const oss = await searchOss({
+                project_id,
+                run_id,
+                intent: rawUserIntent.slice(0, 200),
+                keywords,
+                write_evidence: true
+            });
+            for (const c of (oss.candidates ?? []).slice(0, maxK)) {
+                const repo = typeof c?.repo === "string" ? c.repo.trim() : "";
+                const url = typeof c?.url === "string" ? c.url.trim() : "";
+                const desc = typeof c?.description === "string" ? c.description : "";
+                if (!repo || !url)
+                    continue;
+                candidates.push({
+                    title: repo,
+                    kind: "oss_repo",
+                    why_similar: desc || "유사 기능을 가진 OSS 레퍼런스",
+                    fit_summary: desc || "",
+                    confidence: 3,
+                    links: { primary: url, secondary: [] },
+                    evidence: { source: "github", highlights: [] }
+                });
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            warnings.push(`OSS_SEARCH_FAILED: ${msg}`);
+        }
+    }
+    // Ensure at least 2 candidates by adding deterministic fallbacks.
+    const fallback = [
+        {
+            title: "Minimal Bridge Protocol",
+            kind: "doc",
+            why_similar: "A/B/C 선택 → 확인 기록 → seed 생성의 최소 프로토콜",
+            fit_summary: "도입 난이도 낮음",
+            confidence: 3,
+            links: { primary: "https://example.com/bridge-protocol", secondary: [] },
+            evidence: { source: "manual", highlights: [] }
+        },
+        {
+            title: "Local Evidence Pattern (Zoekt/Ripgrep)",
+            kind: "pattern",
+            why_similar: "로컬 코드베이스 근거를 모아 구현 방향을 고정",
+            fit_summary: "증거 기반 정렬",
+            confidence: 3,
+            links: { primary: "https://example.com/zoekt", secondary: [] },
+            evidence: { source: "manual", highlights: [] }
+        },
+        {
+            title: "Template Pin Pattern",
+            kind: "pattern",
+            why_similar: "레퍼런스를 핀으로 고정하고 작업 범위를 줄이는 방식",
+            fit_summary: "합의/반복 비용 감소",
+            confidence: 3,
+            links: { primary: "https://example.com/pattern-template-pin", secondary: [] },
+            evidence: { source: "manual", highlights: [] }
+        }
+    ];
+    for (const f of fallback) {
+        if (candidates.length >= 2)
+            break;
+        candidates.push(f);
+    }
+    const picked = candidates.slice(0, maxK).map((c, i) => ({
+        key: keyForIndex(i),
+        ...c
+    }));
+    const nowIso = new Date().toISOString();
+    const referencesDoc = BridgeReferencesFileSchema.parse({
+        schema_version: "bridge.references.v1",
+        run_id,
+        project_id,
+        created_at: nowIso,
+        query: {
+            raw_user_intent: rawUserIntent,
+            keywords,
+            constraints,
+            must_have: mustHave,
+            must_not: mustNot
+        },
+        candidates: picked
+    });
+    const bridgeDir = path.join(context.runs_path, "bridge");
+    const referencesPathAbs = path.join(bridgeDir, "references.json");
+    if (input?.write_files !== false) {
+        await fs.mkdir(bridgeDir, { recursive: true });
+        await fs.writeFile(referencesPathAbs, JSON.stringify(referencesDoc, null, 2) + "\n", "utf-8");
+    }
+    const out = {
+        success: true,
+        project_id,
+        run_id,
+        references_path: toRelPath(basePath, referencesPathAbs),
+        candidates: picked.map((c) => ({ key: c.key, title: c.title, primary_link: c.links.primary })),
+        warnings,
+        next_action: {
+            tool: "vibe_pm.bridge_confirm_reference",
+            reason: "A/B/C 중 하나를 선택해 레퍼런스를 확정하세요."
+        }
+    };
+    return out;
+}
+function deriveKeywordsFromContextScan(args) {
+    const ingressDir = path.join(args.runDirAbs, "ingress");
+    const repoMapAbs = path.join(ingressDir, "repo_map.msgpack");
+    const riskFlagsAbs = path.join(ingressDir, "risk_flags.json");
+    const summaryAbs = path.join(ingressDir, "ingress_summary.json");
+    const out = [];
+    const push = (s) => {
+        const v = (s ?? "").trim();
+        if (!v)
+            return;
+        out.push(v);
+    };
+    // 1) ingress_summary.json (cheap JSON)
+    try {
+        if (fsSync.existsSync(summaryAbs)) {
+            const raw = JSON.parse(fsSync.readFileSync(summaryAbs, "utf-8"));
+            const hint = typeof raw?.high_level?.repo_kind_hint === "string" ? raw.high_level.repo_kind_hint : "";
+            hint.split(/[\s+]+/).forEach(push);
+            const reasons = Array.isArray(raw?.high_level?.clarification_reasons) ? raw.high_level.clarification_reasons : [];
+            for (const r of reasons) {
+                if (typeof r === "string" && r.trim())
+                    push(r.trim().toLowerCase());
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    // 2) risk_flags.json (cheap JSON)
+    try {
+        if (fsSync.existsSync(riskFlagsAbs)) {
+            const raw = JSON.parse(fsSync.readFileSync(riskFlagsAbs, "utf-8"));
+            const flags = raw?.flags ?? {};
+            if (flags?.monorepo_suspected)
+                push("monorepo");
+            if (flags?.entrypoint_ambiguous)
+                push("entrypoint");
+            if (flags?.has_env_files)
+                push("env");
+        }
+    }
+    catch {
+        // ignore
+    }
+    // 3) repo_map.msgpack (best-effort, still deterministic)
+    try {
+        if (fsSync.existsSync(repoMapAbs)) {
+            const decoded = decodeMsgpack(fsSync.readFileSync(repoMapAbs));
+            const summary = decoded?.summary ?? {};
+            const topDirs = Array.isArray(summary?.top_dirs) ? summary.top_dirs : [];
+            for (const d of topDirs.slice(0, 8)) {
+                if (typeof d === "string" && d.trim())
+                    push(d.trim());
+            }
+            const signals = Array.isArray(summary?.signals) ? summary.signals : [];
+            for (const s of signals.slice(0, 8)) {
+                if (typeof s === "string" && s.trim())
+                    push(s.trim());
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    // Normalize + dedupe + clamp
+    const seen = new Set();
+    const normalized = [];
+    for (const k of out) {
+        const v = k.toLowerCase().replace(/[^\w-]+/g, " ").trim().split(/\s+/)[0] ?? "";
+        if (!v)
+            continue;
+        if (seen.has(v))
+            continue;
+        seen.add(v);
+        normalized.push(v);
+        if (normalized.length >= 12)
+            break;
+    }
+    return normalized;
+}

package/build/tools/vibe_pm/briefing.js

@@ -1,13 +1,17 @@
 // adapters/mcp-ts/src/tools/vibe_pm/briefing.ts
 // vibe_pm.briefing - Project intake and structuring
+import * as fsPromises from "node:fs/promises";
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { runEngine } from "../../engine.js";
 import { safeJsonParse } from "../../cli.js";
-import { generateRunId, resolveProjectId, ensureRunsDir, getRunsDir } from "./context.js";
+import { generateRunId, resolveProjectId, ensureRunsDir, getRunsDir, getRunContext } from "./context.js";
 import { validateBriefingInput } from "../../security/input-validator.js";
 import { ensureResearchForBriefing } from "./modules/ensure.js";
 import { memorySync } from "./memory_sync.js";
 import { getAuthGate } from "../../auth/index.js";
 import { SpecHighDecisionDraftOutputSchema } from "../../generated/spec_high_decision_draft_output.js";
+import { IngressResolutionFileSchema } from "../../generated/ingress_resolution_file.js";
 import { applyPromptDensityHysteresis, computePromptDensity, loadLatestPromptDensityForProject, savePromptDensity } from "./intent/prompt_density.js";
 import { generateIntentFromBriefing, saveIntentWithMarkdown } from "./intent/index.js";
 /**
@@ -35,11 +39,31 @@ export async function briefing(input) {
     // Mode defaults to balanced
     const mode = input.mode ?? "balanced";
     // Step 1: Initialize the run
-    // Note: spec-high init doesn't support --mode flag, mode is handled at MCP layer
-    const initResult = await runEngine("spec-high", ["--root", "engines/spec_high", "init", run_id], { timeoutMs: 60_000 });
+    const initResult = await runEngine("spec-high", ["--root", "engines/spec_high", "init", run_id, "--mode", mode], { timeoutMs: 60_000 });
     if (initResult.code !== 0) {
         throw new Error(`프로젝트 초기화 실패: ${initResult.stderr || "알 수 없는 오류"}`);
     }
+    // Ingress v2 (best-effort): record ingress_resolution.json so downstream tools can gate deterministically.
+    try {
+        const ctx = getRunContext(run_id, basePath);
+        const ingressDir = path.join(ctx.runs_path, "ingress");
+        await fsPromises.mkdir(ingressDir, { recursive: true });
+        const doc = IngressResolutionFileSchema.parse({
+            schema_version: "ingress.resolution.v2",
+            run_id,
+            project_id,
+            workspace_path: path.resolve(basePath),
+            resolution: "INGRESS_RESOLVED_NEW_TASK",
+            has_vibe_state: fs.existsSync(path.join(basePath, ".vibe")),
+            context_scan_required: false,
+            context_scan_completed: false,
+            created_at: new Date().toISOString()
+        });
+        await fsPromises.writeFile(path.join(ingressDir, "ingress_resolution.json"), JSON.stringify(doc, null, 2) + "\n", "utf-8");
+    }
+    catch {
+        // ignore (best-effort)
+    }
     // Step 2: Set the project brief as input
     const inputSetResult = await runEngine("spec-high", ["--root", "engines/spec_high", "input-set", run_id, "--text", input.project_brief], { timeoutMs: 60_000 });
     if (inputSetResult.code !== 0) {

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);