korean-law-mcp 4.0.7 → 4.2.0

package/README.md

@@ -49,6 +49,22 @@ graph LR
 
 → STEP 1 상황진단(주택임대차보호법 자동 식별) → STEP 2 권리/구제수단(판례) → STEP 3 신청기관/기한(행정규칙+해석) → STEP 4 필요서류/양식(별표) → STEP 5 함정/주의(시효·법률구조공단). 평소 말투 그대로 → 실행 가능한 단계로 변환.
 
+### + v4.2.0 — 법령 현행성 가드 (개정 전 법령 오답 방지)
+
+`search_law` 결과에 `[현행]` / `⚠️[연혁-과거버전]` 라벨 + 시행일 표기(현행 우선 정렬), `get_law_text` 본문 헤더에 조회기준일 vs 시행일 비교 라벨(시행 예정·efYd 과거 조회 경고)과 **구 법령명**("(구 법령명: 화재예방, 소방시설 설치ㆍ유지 및 안전관리에 관한 법률…)") 표기. LLM이 분법·개정된 법령을 학습데이터 속 옛 버전과 혼동하지 않도록 도구 출력 단계에서 차단.
+
+### + v4.1.0 — 판례 검색 구조화 + 상세 증거 자동 연결
+
+판례 검색을 공통 구조화 core(`searchPrecedentsStructured`)로 통합. 긴 자연어/개념형 질의를 compact query로 보정하고, 사건번호→제목→본문검색 순으로 폴백. 상위 판례를 `get_precedent_text`에 자동 연결(기본 2건/최대 5건)해 근거 본문을 함께 제공하며, `search_decisions(domain="precedent", options.includeText=true)`로 opt-in. 다건 상세조회 합산 시 뒷 판례가 잘리던 문제도 건당 본문 예산 배분으로 해결. (외부 PR #46 + 후속 최적화)
+
+### + v4.0.9 — 법제처 API `Referer` 헤더 자동 주입
+
+법제처 OPEN API가 **`Referer` 헤더 없는 요청을 OC 키 유효 여부와 무관하게 거부**("사용자 정보 검증 실패")하는 문제 대응. `law.go.kr` 계열 호스트 호출 시 기본 `Referer`를 자동 주입한다(`LAW_REFERER`로 override). IP/도메인 등록 문제로 오인되기 쉬운 증상의 실제 근본 원인이었음 — IP 등록을 했는데도 모든 검색이 실패하던 케이스를 해결. (외부 PR #45)
+
+### + v4.0.8 — 법제처 빈/HTML 응답 자동 재시도
+
+법제처 OPEN API가 간헐적으로 200 상태에 **빈 본문이나 HTML 점검 페이지**를 반환하던 문제 대응. 이 경우 XML 파서가 `missing root element`로 터지며 "됐다 안 됐다" 증상이 발생했음. `fetchWithRetry`가 빈/HTML 응답을 일시 장애로 간주해 자동 재시도(exponential backoff)하고, 재시도 소진 후에도 빈 응답이면 `search_law`가 `missing root element` 대신 명확한 안내 메시지를 반환하도록 수정. (IP 등록·OC 키와 무관한 외부 응답 불안정 이슈)
+
 ### + v4.0.7 — 국세청 판례 본문 fallback
 
 법제처 JSON API에 본문이 비어 오는 판례를 국세청 `taxlaw.nts.go.kr`에서 HTML로 자동 보강. JSON 실패·파싱 실패·본문 누락 세 경우 모두 fallback으로 진입하며 안전하게 회수됨. 사내망/SSL inspection 환경용 `LAW_EXTERNAL_HTTPS_PROXY`(선택)·`LAW_EXTERNAL_TLS_REJECT_UNAUTHORIZED`(진단용) 지원 — 자세한 설정은 아래 "국세청 판례 서버 TLS/프록시 설정" 섹션 참조. (외부 PR #44)

package/build/lib/api-client.d.ts

@@ -20,6 +20,12 @@ export declare class LawApiClient {
     private getResponseType;
     /** 응답 본문이 HTML 에러 페이지인지 확인 */
     private checkHtmlError;
+    /**
+     * 빈 응답 감지 — 법제처가 간헐 장애 시 200으로 빈 본문을 반환하는 케이스.
+     * 그대로 XML 파서에 넘기면 "missing root element"로 터지므로 명확한 메시지로 전환.
+     * (fetchWithRetry가 빈/HTML 응답을 재시도하지만, 재시도 소진 후에도 빈 응답이면 여기서 처리)
+     */
+    private checkEmptyResponse;
     /**
      * 법령 검색
      * @param display 결과 개수 (기본값 법제처 API default, 짧은 법령명("상법" 등) 정확 매칭 찾으려면 큰 값 권장)

package/build/lib/api-client.js

@@ -55,6 +55,16 @@ export class LawApiClient {
             throw new Error(`${context} - API가 HTML 에러 페이지를 반환했습니다. 파라미터를 확인해주세요.${hint}`);
         }
     }
+    /**
+     * 빈 응답 감지 — 법제처가 간헐 장애 시 200으로 빈 본문을 반환하는 케이스.
+     * 그대로 XML 파서에 넘기면 "missing root element"로 터지므로 명확한 메시지로 전환.
+     * (fetchWithRetry가 빈/HTML 응답을 재시도하지만, 재시도 소진 후에도 빈 응답이면 여기서 처리)
+     */
+    checkEmptyResponse(text, context) {
+        if (!text || !text.trim()) {
+            throw new Error(`${context} - 법제처 API가 빈 응답을 반환했습니다. 일시적 장애일 수 있으니 잠시 후 다시 시도하세요.`);
+        }
+    }
     /**
      * 법령 검색
      * @param display 결과 개수 (기본값 법제처 API default, 짧은 법령명("상법" 등) 정확 매칭 찾으려면 큰 값 권장)
@@ -74,7 +84,10 @@ export class LawApiClient {
         const url = `${LAW_API_BASE}/lawSearch.do?${params.toString()}`;
         const response = await fetchWithRetry(url);
         await this.throwIfError(response, "searchLaw");
-        return await response.text();
+        const text = await response.text();
+        this.checkEmptyResponse(text, "법령 검색");
+        this.checkHtmlError(text, "법령 검색 결과를 받지 못했습니다");
+        return text;
     }
     /**
      * 현행법령 조회

package/build/lib/article-warnings.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 특정 조문 조회 시 전략적 주의(위험신호) 경고 주입
+ *
+ * 민법 제107~110조(의사표시의 하자)는 무효·취소를 주장하는 측에 입증책임이 있는 항변이다.
+ * 계약서·차용증 등 객관적 서면이 명백한 사건에서 이 조문을 1순위 항변으로 삼으면
+ * 법원 인용률이 낮으므로, 조회 시 변호사 상담을 권고하는 경고를 함께 노출한다.
+ *
+ * 주의: 107~110조는 거의 모든 법(형법/상법 등)에 존재하므로 반드시 법령명이 "민법"일 때만 적용한다.
+ */
+/**
+ * 법령명·조문 정보로 전략 경고를 반환. 해당 없으면 null.
+ *
+ * @param lawName 법령명 (정확히 "민법"일 때만 적용 — "민법 시행령" 등 제외)
+ * @param joNum 조문번호 문자열 (예: "108")
+ * @param joBranch 조문가지번호 (제107조의2 등 가지조문은 제외하기 위해 "0"/"" 만 허용)
+ */
+export declare function getStrategyWarning(lawName: string, joNum: string, joBranch: string): string | null;

package/build/lib/article-warnings.js

@@ -0,0 +1,30 @@
+/**
+ * 특정 조문 조회 시 전략적 주의(위험신호) 경고 주입
+ *
+ * 민법 제107~110조(의사표시의 하자)는 무효·취소를 주장하는 측에 입증책임이 있는 항변이다.
+ * 계약서·차용증 등 객관적 서면이 명백한 사건에서 이 조문을 1순위 항변으로 삼으면
+ * 법원 인용률이 낮으므로, 조회 시 변호사 상담을 권고하는 경고를 함께 노출한다.
+ *
+ * 주의: 107~110조는 거의 모든 법(형법/상법 등)에 존재하므로 반드시 법령명이 "민법"일 때만 적용한다.
+ */
+// 절충 톤: 입증책임·인용률 관점의 정성적 경고 (단정적 패소확률 수치는 미포함)
+const 의사표시하자경고 = {
+    "107": "⚠️ [위험신호] 민법 제107조(진의 아닌 의사표시)는 의사표시 하자 항변으로, 비진의 표시는 원칙적으로 유효하고 상대방의 악의·과실을 입증해야 무효가 되므로 인용률이 낮은 조문입니다. 객관적 증거 없이 이 항변에 의존할 경우 패소 위험이 매우 큽니다. 반드시 변호사 상담을 받으세요.",
+    "108": "⚠️ [위험신호] 민법 제108조(통정한 허위의 의사표시)는 의사표시 하자 항변으로, 상대방과 짜고 한 허위표시(통정)를 주장하는 측이 입증해야 하므로 인용률이 낮은 조문입니다. 객관적 증거 없이 이 항변에 의존할 경우 패소 위험이 매우 큽니다. 반드시 변호사 상담을 받으세요.",
+    "109": "⚠️ [위험신호] 민법 제109조(착오로 인한 의사표시)는 의사표시 하자 항변으로, 법률행위의 중요부분 착오이면서 본인에게 중대한 과실이 없음을 입증해야 취소할 수 있어 인용률이 낮은 조문입니다. 객관적 증거 없이 이 항변에 의존할 경우 패소 위험이 매우 큽니다. 반드시 변호사 상담을 받으세요.",
+    "110": "⚠️ [위험신호] 민법 제110조(사기, 강박에 의한 의사표시)는 의사표시 하자 항변으로, 기망 또는 강박 행위와 그로 인한 의사표시의 인과관계를 주장하는 측이 입증해야 하므로 인용률이 낮은 조문입니다. 객관적 증거 없이 이 항변에 의존할 경우 패소 위험이 큽니다. 다만 납득할 만한 증거가 있으면 결과가 달라질 수 있습니다. 반드시 변호사 상담을 받으세요."
+};
+/**
+ * 법령명·조문 정보로 전략 경고를 반환. 해당 없으면 null.
+ *
+ * @param lawName 법령명 (정확히 "민법"일 때만 적용 — "민법 시행령" 등 제외)
+ * @param joNum 조문번호 문자열 (예: "108")
+ * @param joBranch 조문가지번호 (제107조의2 등 가지조문은 제외하기 위해 "0"/"" 만 허용)
+ */
+export function getStrategyWarning(lawName, joNum, joBranch) {
+    if (lawName.trim() !== "민법")
+        return null;
+    if (joBranch && joBranch !== "0")
+        return null;
+    return 의사표시하자경고[joNum] ?? null;
+}

package/build/lib/fetch-with-retry.js

@@ -17,10 +17,36 @@ const DEFAULT_TIMEOUT = 30000;
 const DEFAULT_RETRIES = 3;
 const DEFAULT_RETRY_DELAY = 1000;
 const DEFAULT_RETRY_ON = [429, 503, 504];
+/**
+ * 법제처 API가 200으로 빈 본문/HTML(점검·과부하 페이지)을 반환하는 간헐 장애 감지.
+ * 정상 응답은 XML(`<`) 또는 JSON(`{`/`[`)으로 시작하므로 빈 본문과 HTML 페이지만 걸러낸다.
+ */
+function detectBadBody(text) {
+    const t = text.trim();
+    if (!t)
+        return "empty";
+    if (/^<!doctype html/i.test(t) || /^<html[\s>]/i.test(t))
+        return "html";
+    return null;
+}
 // 법제처 OPEN API가 Node 기본 UA(undici)를 봇으로 분류해 거부하므로
 // 일반 브라우저 UA로 호출. LAW_USER_AGENT 환경변수로 override 가능.
 const DEFAULT_USER_AGENT = process.env.LAW_USER_AGENT ||
     "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+// 법제처 OPEN API는 Referer 헤더가 없으면 OC 키가 유효해도
+// "사용자 정보 검증에 실패하였습니다 (정확한 서버장비의 IP주소 및 도메인주소를 등록해 주세요)"
+// XML을 반환한다. 메시지는 IP/도메인 등록 문제로 오인되기 쉬우나 실제 원인은 Referer 누락이다.
+// (브라우저 UA만으로는 통과하지 못하고 Referer가 결정적). LAW_REFERER 환경변수로 override 가능.
+const DEFAULT_REFERER = process.env.LAW_REFERER || "https://www.law.go.kr/";
+// Referer를 붙일 법제처 계열 호스트 판별 (그 외 호스트엔 주입하지 않음).
+function isLawGoKrHost(targetUrl) {
+    try {
+        return /(^|\.)law\.go\.kr$/i.test(new URL(targetUrl).hostname);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Fetch with automatic retry and timeout
  */
@@ -33,6 +59,8 @@ export async function fetchWithRetry(url, options = {}) {
         const headers = new Headers(fetchOptions.headers);
         if (!headers.has("user-agent"))
             headers.set("user-agent", DEFAULT_USER_AGENT);
+        if (!headers.has("referer") && isLawGoKrHost(url))
+            headers.set("referer", DEFAULT_REFERER);
         try {
             const response = await fetch(url, {
                 ...fetchOptions,
@@ -42,6 +70,23 @@ export async function fetchWithRetry(url, options = {}) {
             clearTimeout(timeoutId);
             // Success or non-retryable error
             if (response.ok || !retryOn.includes(response.status)) {
+                // 200인데 빈 본문/HTML(법제처 점검·과부하 페이지)이면 일시 장애로 보고 재시도.
+                // 이를 막지 않으면 XML 파서가 "missing root element"로 터진다.
+                if (response.ok && attempt < retries) {
+                    let bodyText = null;
+                    try {
+                        bodyText = await response.clone().text();
+                    }
+                    catch { /* clone 실패 시 정상 처리 */ }
+                    if (bodyText !== null) {
+                        const bad = detectBadBody(bodyText);
+                        if (bad) {
+                            lastError = new Error(`법제처 API 비정상 응답(${bad === "empty" ? "빈 본문" : "HTML 페이지"}) - ${maskSensitiveUrl(url)}`);
+                            await sleep(getRetryDelay(response, retryDelay, attempt));
+                            continue;
+                        }
+                    }
+                }
                 return response;
             }
             // Retryable error - check if we have retries left

package/build/tool-registry.js

@@ -634,7 +634,7 @@ export const allTools = [
     // === 통합 도구 (v3) ===
     {
         name: "search_decisions",
-        description: "[통합검색] 18개 도메인(판례·해석례·헌재·행심·조세심판·관세·국세청·공정위·개인정보위·노동위·권익위·소청심사·학칙·공사공단·공공기관·조약·영문법령) 통합 검색. domain으로 선택. 세무 관련 국세청 직접 회신 해석은 domain='nts'.",
+        description: "[통합검색] 18개 도메인(판례·해석례·헌재·행심·조세심판·관세·국세청·공정위·개인정보위·노동위·권익위·소청심사·학칙·공사공단·공공기관·조약·영문법령) 통합 검색. domain으로 선택. 판례 본문까지 필요하면 domain='precedent', options.includeText=true, options.detailLimit=N. 세무 관련 국세청 직접 회신 해석은 domain='nts'.",
         schema: SearchDecisionsSchema,
         handler: searchDecisions
     },

package/build/tools/article-with-precedents.js

@@ -3,7 +3,8 @@
  */
 import { z } from "zod";
 import { getLawText } from "./law-text.js";
-import { searchPrecedents } from "./precedents.js";
+import { renderPrecedentSearchResult } from "./precedents.js";
+import { searchPrecedentsStructured } from "./precedent-search-core.js";
 import { truncateResponse } from "../lib/schemas.js";
 import { formatToolError } from "../lib/errors.js";
 export const GetArticleWithPrecedentsSchema = z.object({
@@ -39,14 +40,16 @@ export async function getArticleWithPrecedents(apiClient, input) {
         // 3. 관련 판례 검색
         const precedentQuery = `${lawName} ${input.jo}`;
         try {
-            const precedentResult = await searchPrecedents(apiClient, {
+            const precedentResult = await searchPrecedentsStructured(apiClient, {
                 query: precedentQuery,
                 display: 5,
                 page: 1,
                 apiKey: input.apiKey
+            }, {
+                fallbackPolicy: "none",
             });
-            if (!precedentResult.isError) {
-                const precedentText = precedentResult.content[0].text;
+            if (precedentResult.hits.length > 0) {
+                const precedentText = renderPrecedentSearchResult(precedentResult);
                 // 판례 결과가 있으면 추가
                 if (precedentText && !precedentText.includes("검색 결과가 없습니다")) {
                     resultText += `\n${"=".repeat(60)}\n`;

package/build/tools/chains.js

@@ -12,7 +12,7 @@ import { runScenario, detectScenario, formatSections, formatSuggestedActions } f
 import { analyzeDocument } from "./document-analysis.js";
 import { getThreeTier } from "./three-tier.js";
 import { getBatchArticles } from "./batch-articles.js";
-import { getPrecedentText, searchPrecedents } from "./precedents.js";
+import { renderPrecedentSearchResult, searchPrecedents } from "./precedents.js";
 import { searchInterpretations } from "./interpretations.js";
 import { searchAdminAppeals } from "./admin-appeals.js";
 import { compareOldNew } from "./comparison.js";
@@ -24,12 +24,43 @@ import { searchAiLaw, searchAiLawStructured } from "./life-law.js";
 import { getLawText } from "./law-text.js";
 import { searchTaxTribunalDecisions } from "./tax-tribunal-decisions.js";
 import { searchNlrcDecisions, searchPipcDecisions } from "./committee-decisions.js";
-import { fetchSearchDetailChain, fetchCombinedSearchDetailChain } from "./search-detail-chain.js";
-import { buildCompactLegalQueries } from "./compact-query-planner.js";
+import { fetchSearchDetailChain } from "./search-detail-chain.js";
+import { searchPrecedentsStructured, } from "./precedent-search-core.js";
+import { fetchPrecedentEvidence, validatePrecedentSearchResult } from "./precedent-evidence.js";
 // ========================================
 // Helpers
 // ========================================
-const PRECEDENT_RETRY_LIMIT = 5;
+const PRECEDENT_FALLBACK_LIMIT = 5;
+function emptyStructuredPrecedentResult(args) {
+    return {
+        originalArgs: args,
+        totalCount: 0,
+        page: args.page || 1,
+        hits: [],
+        attempts: [],
+        fallbackUsed: false,
+    };
+}
+function errorCallResult(error, toolName) {
+    const response = formatToolError(error, toolName);
+    return {
+        text: response.content?.[0]?.text || (error instanceof Error ? error.message : String(error)),
+        isError: true,
+    };
+}
+async function safeSearchPrecedentsStructured(apiClient, args, context = {}) {
+    try {
+        return {
+            result: await searchPrecedentsStructured(apiClient, args, context),
+        };
+    }
+    catch (error) {
+        return {
+            result: emptyStructuredPrecedentResult(args),
+            error: errorCallResult(error, "search_precedents"),
+        };
+    }
+}
 async function callTool(
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 handler, apiClient, input) {
@@ -142,93 +173,60 @@ function selectLawTextSource(laws, query) {
     }
     return { reliableLaws, textLaw: laws[0], lowConfidence: laws.length > 0 };
 }
-function normalizeRelevanceText(text) {
-    return text
-        .toLowerCase()
-        .replace(/\s+/g, "")
-        .replace(/[^\p{L}\p{N}]+/gu, "");
-}
-function candidateRelevanceTerms(candidate) {
-    return Array.from(new Set([candidate.query, candidate.semanticAnchor]
-        .filter((term) => typeof term === "string" && normalizeRelevanceText(term).length >= 2)));
-}
-function textContainsCandidateTerm(text, candidate) {
-    const haystack = normalizeRelevanceText(text);
-    return candidateRelevanceTerms(candidate)
-        .some(term => haystack.includes(normalizeRelevanceText(term)));
-}
-function extractPrecedentCaseLines(searchText) {
-    return searchText
-        .split("\n")
-        .filter(line => /^\[\d+\]\s+/.test(line.trim()));
-}
-function extractFirstPrecedentId(searchText) {
-    for (const line of searchText.split("\n")) {
-        const match = line.trim().match(/^\[(\d+)\]\s+/);
-        if (match?.[1])
-            return match[1];
-    }
-    return undefined;
-}
-async function validateRetryPrecedentResult(apiClient, candidate, result, apiKey) {
-    const caseLines = extractPrecedentCaseLines(result.text);
-    if (caseLines.some(line => textContainsCandidateTerm(line, candidate))) {
-        return true;
-    }
-    if (candidate.search !== 2 && !candidate.requiresResultValidation) {
-        return false;
+async function searchPrecedentsForChain(apiClient, input, context = {}, detailLimit = 2) {
+    const args = {
+        query: input.query,
+        display: input.display,
+        page: 1,
+        apiKey: input.apiKey,
+    };
+    const { result: search, error } = await safeSearchPrecedentsStructured(apiClient, args, {
+        ...context,
+        maxFallbackAttempts: context.maxFallbackAttempts ?? PRECEDENT_FALLBACK_LIMIT,
+        validateResult: validation => validatePrecedentSearchResult(apiClient, validation, { apiKey: input.apiKey }),
+    });
+    if (error) {
+        return {
+            structuredResult: search,
+            searchResult: error,
+            detailResult: null,
+        };
     }
-    const id = extractFirstPrecedentId(result.text);
-    if (!id)
-        return false;
-    const detail = await callTool(getPrecedentText, apiClient, {
-        id,
-        full: candidate.search === 2,
-        apiKey,
+    const searchResult = {
+        text: renderPrecedentSearchResult(search),
+        isError: search.hits.length === 0,
+    };
+    const evidence = await fetchPrecedentEvidence(apiClient, search, {
+        apiKey: input.apiKey,
+        detailLimit,
+        full: false,
     });
-    if (isSearchFailure(detail) || !detail.text.trim())
-        return false;
-    return textContainsCandidateTerm(detail.text, candidate);
-}
-function formatRetryCandidate(candidate) {
-    return candidate.search === 2 ? `"${candidate.query}"(본문검색)` : `"${candidate.query}"`;
+    return {
+        structuredResult: search,
+        searchResult,
+        detailResult: evidence ? { text: evidence.text, isError: evidence.isError } : null,
+    };
 }
-async function retryPrecedentsIfNeeded(apiClient, input, precedentResult, aiLawResult) {
-    if (!isSearchFailure(precedentResult))
-        return precedentResult;
-    const route = routeQuery(input.query);
-    const candidates = buildCompactLegalQueries({
-        originalQuery: input.query,
-        aiLawArticles: aiLawResult?.aiLawArticles,
-        aiLawText: aiLawResult?.text,
-        route,
-        failedSearchText: precedentResult.text,
-        max: PRECEDENT_RETRY_LIMIT,
+function combineStructuredPrecedentResults(results) {
+    const nonEmpty = results.filter(result => result.hits.length > 0);
+    if (nonEmpty.length === 0)
+        return null;
+    const seen = new Set();
+    const hits = nonEmpty.flatMap(result => result.hits)
+        .filter(hit => {
+        if (seen.has(hit.id))
+            return false;
+        seen.add(hit.id);
+        return true;
     });
-    if (candidates.length === 0)
-        return precedentResult;
-    for (const candidate of candidates) {
-        const retried = await callTool(searchPrecedents, apiClient, {
-            query: candidate.query,
-            search: candidate.search,
-            display: 5,
-            apiKey: input.apiKey,
-        });
-        if (!isSearchFailure(retried) && retried.text.trim() && await validateRetryPrecedentResult(apiClient, candidate, retried, input.apiKey)) {
-            return {
-                text: `판례 1차 검색 실패 후 재검색어 "${candidate.query}"로 조회했습니다.\n\n${retried.text}`,
-                isError: false,
-            };
-        }
-    }
     return {
-        text: [
-            precedentResult.text,
-            "",
-            `재검색 시도(최대 ${PRECEDENT_RETRY_LIMIT}회): ${candidates.map(formatRetryCandidate).join(", ")}`,
-            "모든 재검색에서 판례 검색 결과가 없습니다.",
-        ].join("\n"),
-        isError: true,
+        originalArgs: nonEmpty[0].originalArgs,
+        totalCount: hits.length,
+        page: 1,
+        hits,
+        attempts: results.flatMap(result => result.attempts),
+        fallbackUsed: results.some(result => result.fallbackUsed),
+        successfulAttempt: nonEmpty[0].successfulAttempt,
     };
 }
 function wrapResult(text) {
@@ -366,9 +364,9 @@ export const chainDisputePrepSchema = z.object({
 export async function chainDisputePrep(apiClient, input) {
     try {
         const parts = [`═══ 쟁송 대비: ${input.query} ═══`];
-        // Step 1: 판례 + 행정심판 (병렬)
+        // Step 1: 판례 + 행정심판 (병렬). 판례는 구조화 hit 기반 상세조회까지 같은 경로에서 처리한다.
+        const precedentPromise = searchPrecedentsForChain(apiClient, { query: input.query, display: 8, apiKey: input.apiKey }, { route: routeQuery(input.query) });
         const parallel = [
-            callTool(searchPrecedents, apiClient, { query: input.query, display: 8, apiKey: input.apiKey }),
             callTool(searchAdminAppeals, apiClient, { query: input.query, display: 8, apiKey: input.apiKey }),
         ];
         // Step 2: 도메인별 전문 결정례 추가
@@ -382,24 +380,26 @@ export async function chainDisputePrep(apiClient, input) {
         else if (domain === "privacy") {
             parallel.push(callTool(searchPipcDecisions, apiClient, { query: input.query, display: 5, apiKey: input.apiKey }));
         }
-        const results = await Promise.all(parallel);
-        parts.push(secOrSkip("대법원 판례", results[0]));
-        parts.push(secOrSkip("행정심판례", results[1]));
-        const [precDetail, appealDetail] = await Promise.all([
-            fetchSearchDetailChain(apiClient, "search_precedents", results[0], { apiKey: input.apiKey }),
-            fetchSearchDetailChain(apiClient, "search_admin_appeals", results[1], { apiKey: input.apiKey }),
+        const [precedentBundle, results] = await Promise.all([
+            precedentPromise,
+            Promise.all(parallel),
         ]);
-        if (precDetail)
-            parts.push(secOrSkip("대법원 판례 상세", precDetail));
+        parts.push(secOrSkip("대법원 판례", precedentBundle.searchResult));
+        parts.push(secOrSkip("행정심판례", results[0]));
+        const [appealDetail] = await Promise.all([
+            fetchSearchDetailChain(apiClient, "search_admin_appeals", results[0], { apiKey: input.apiKey }),
+        ]);
+        if (precedentBundle.detailResult)
+            parts.push(secOrSkip("대법원 판례 상세", precedentBundle.detailResult));
         if (appealDetail)
             parts.push(secOrSkip("행정심판례 상세", appealDetail));
-        if (results[2]) {
+        if (results[1]) {
             const domainNames = {
                 tax: "조세심판원 결정",
                 labor: "중앙노동위 결정",
                 privacy: "개인정보위 결정",
             };
-            parts.push(secOrSkip(domainNames[domain] || "전문 결정례", results[2]));
+            parts.push(secOrSkip(domainNames[domain] || "전문 결정례", results[1]));
             const domainSearchTools = {
                 tax: "search_tax_tribunal_decisions",
                 labor: "search_nlrc_decisions",
@@ -407,7 +407,7 @@ export async function chainDisputePrep(apiClient, input) {
             };
             const domainSearchTool = domainSearchTools[domain];
             if (domainSearchTool) {
-                const domainDetail = await fetchSearchDetailChain(apiClient, domainSearchTool, results[2], { apiKey: input.apiKey });
+                const domainDetail = await fetchSearchDetailChain(apiClient, domainSearchTool, results[1], { apiKey: input.apiKey });
                 if (domainDetail)
                     parts.push(secOrSkip(`${domainNames[domain] || "전문 결정례"} 상세`, domainDetail));
             }
@@ -555,7 +555,7 @@ export const chainFullResearchSchema = z.object({
 export async function chainFullResearch(apiClient, input) {
     try {
         const parts = [`═══ 종합 리서치: ${input.query} ═══`];
-        // Step 1: AI 검색 + 법령 검색 + 판례/해석 모두 병렬
+        // Step 1: AI 검색 + 법령 검색 + 해석례를 병렬 실행하고, 판례는 AI 구조화 신호를 받은 뒤 공통 core로 검색한다.
         // findLaws를 안전하게 래핑 (throw 시 Promise.all 전체 reject 방지)
         const safeFindLaws = async () => {
             try {
@@ -565,14 +565,17 @@ export async function chainFullResearch(apiClient, input) {
                 return [];
             }
         };
-        const [aiResult, rawLawsResult, precResult, interpResult] = await Promise.all([
+        const [aiResult, rawLawsResult, interpResult] = await Promise.all([
             callAiLaw(apiClient, { query: input.query, search: "0", display: 10, page: 1, apiKey: input.apiKey }),
             safeFindLaws(),
-            callTool(searchPrecedents, apiClient, { query: input.query, display: 5, apiKey: input.apiKey }),
             callTool(searchInterpretations, apiClient, { query: input.query, display: 5, apiKey: input.apiKey }),
         ]);
         const { reliableLaws: lawsResult, textLaw, lowConfidence } = selectLawTextSource(rawLawsResult, input.query);
-        const finalPrecResult = await retryPrecedentsIfNeeded(apiClient, input, precResult, aiResult);
+        const precedentBundle = await searchPrecedentsForChain(apiClient, { query: input.query, display: 5, apiKey: input.apiKey }, {
+            aiLawArticles: aiResult.aiLawArticles,
+            route: routeQuery(input.query),
+            maxFallbackAttempts: PRECEDENT_FALLBACK_LIMIT,
+        });
         parts.push(secOrSkip("AI 법령검색 결과", aiResult));
         // 법령 본문 (첫 번째 결과)
         if (textLaw) {
@@ -580,14 +583,13 @@ export async function chainFullResearch(apiClient, input) {
             const confidenceSuffix = lowConfidence ? " (관련도 낮음)" : "";
             parts.push(secOrSkip(`${textLaw.lawName} 본문${confidenceSuffix}`, lawText));
         }
-        parts.push(secOrSkip("관련 판례", finalPrecResult));
+        parts.push(secOrSkip("관련 판례", precedentBundle.searchResult));
         parts.push(secOrSkip("법령 해석례", interpResult));
-        const [precDetail, interpDetail] = await Promise.all([
-            fetchSearchDetailChain(apiClient, "search_precedents", finalPrecResult, { apiKey: input.apiKey }),
+        const [interpDetail] = await Promise.all([
             fetchSearchDetailChain(apiClient, "search_interpretations", interpResult, { apiKey: input.apiKey }),
         ]);
-        if (precDetail)
-            parts.push(secOrSkip("관련 판례 상세", precDetail));
+        if (precedentBundle.detailResult)
+            parts.push(secOrSkip("관련 판례 상세", precedentBundle.detailResult));
         if (interpDetail)
             parts.push(secOrSkip("법령 해석례 상세", interpDetail));
         // 키워드 확장
@@ -700,35 +702,58 @@ export async function chainDocumentReview(apiClient, input) {
         }
         // 중복 제거 후 최대 5개 힌트로 제한
         const uniqueHints = [...new Set(searchHints)].slice(0, 5);
-        const searchPromises = [];
-        for (const hint of uniqueHints) {
-            searchPromises.push(callTool(searchPrecedents, apiClient, { query: hint, display: 3, apiKey: input.apiKey }));
-        }
-        // AI 법령 검색도 상위 3개 힌트로 병렬 실행
+        const precedentSearches = await Promise.all(uniqueHints.map(hint => safeSearchPrecedentsStructured(apiClient, {
+            query: hint,
+            display: 3,
+            page: 1,
+            apiKey: input.apiKey,
+        }, {
+            documentHints: [hint],
+            maxFallbackAttempts: 3,
+            validateResult: validation => validatePrecedentSearchResult(apiClient, validation, { apiKey: input.apiKey }),
+        })));
+        const precedentResults = precedentSearches.map(search => search.result);
+        // AI 법령 검색은 상위 3개 힌트로 병렬 실행
         const lawHints = uniqueHints.slice(0, 3);
-        for (const hint of lawHints) {
-            searchPromises.push(callTool(searchAiLaw, apiClient, { query: hint, display: 3, apiKey: input.apiKey }));
-        }
-        const searchResults = await Promise.all(searchPromises);
+        const lawResults = await Promise.all(lawHints.map(hint => callTool(searchAiLaw, apiClient, { query: hint, display: 3, apiKey: input.apiKey })));
         // 판례 결과 합산
         const precTexts = [];
         for (let i = 0; i < uniqueHints.length; i++) {
-            const r = searchResults[i];
-            if (!r.isError && r.text.trim()) {
-                precTexts.push(`[${uniqueHints[i]}]\n${r.text}`);
+            const r = precedentResults[i];
+            if (r.hits.length > 0) {
+                precTexts.push(`[${uniqueHints[i]}]\n${renderPrecedentSearchResult(r)}`);
             }
         }
         if (precTexts.length > 0) {
             parts.push(sec("관련 판례", precTexts.join("\n\n")));
         }
-        const precedentDetail = await fetchCombinedSearchDetailChain(apiClient, "search_precedents", searchResults.slice(0, uniqueHints.length), { apiKey: input.apiKey });
-        if (precedentDetail) {
-            parts.push(secOrSkip("관련 판례 상세", precedentDetail));
+        const precedentErrors = precedentSearches
+            .map((search, index) => search.error ? `[${uniqueHints[index]}]\n${search.error.text}` : "")
+            .filter(text => text.trim());
+        if (precedentErrors.length > 0) {
+            parts.push(secOrSkip("판례 검색 실패", {
+                text: precedentErrors.join("\n\n"),
+                isError: true,
+            }));
+        }
+        const combinedPrecedents = combineStructuredPrecedentResults(precedentResults);
+        if (combinedPrecedents) {
+            const precedentEvidence = await fetchPrecedentEvidence(apiClient, combinedPrecedents, {
+                apiKey: input.apiKey,
+                detailLimit: 2,
+                full: false,
+            });
+            if (precedentEvidence) {
+                parts.push(secOrSkip("관련 판례 상세", {
+                    text: precedentEvidence.text,
+                    isError: precedentEvidence.isError,
+                }));
+            }
         }
         // 법령 결과 합산
         const lawTexts = [];
         for (let i = 0; i < lawHints.length; i++) {
-            const r = searchResults[uniqueHints.length + i];
+            const r = lawResults[i];
             if (!r.isError && r.text.trim()) {
                 lawTexts.push(`[${lawHints[i]}]\n${r.text}`);
             }

package/build/tools/compact-query-planner.d.ts

@@ -1,7 +1,7 @@
 import type { AiLawArticleSignal } from "./life-law.js";
-export type CompactQuerySource = "ai_law_article_title" | "ai_law_law_article_title" | "search_retry_hint" | "router";
+export type CompactQuerySource = "case_number" | "original_query" | "original_keyword" | "document_hint" | "ai_law_article_title" | "ai_law_law_article_title" | "router";
 export type PrecedentSearchScope = 1 | 2;
-export type CompactQueryVariantKind = "raw" | "terminal_function_word_removed" | "terminal_function_word_spaced" | "law_title" | "retry_hint" | "router";
+export type CompactQueryVariantKind = "case_number" | "original_query" | "original_keyword" | "document_hint" | "raw" | "terminal_function_word_removed" | "terminal_function_word_spaced" | "law_title" | "router";
 export interface CompactQueryCandidate {
     query: string;
     source: CompactQuerySource;
@@ -9,6 +9,7 @@ export interface CompactQueryCandidate {
     reason: string;
     search: PrecedentSearchScope;
     semanticAnchor?: string;
+    validationTermGroups?: string[][];
     variantKind: CompactQueryVariantKind;
     requiresResultValidation: boolean;
 }
@@ -20,10 +21,11 @@ interface RouteLike {
 }
 export interface CompactQueryInput {
     originalQuery: string;
+    includeOriginal?: boolean;
+    caseNumber?: string;
+    documentHints?: string[];
     aiLawArticles?: AiLawArticleSignal[];
-    aiLawText?: string;
     route?: RouteLike;
-    failedSearchText?: string;
     max?: number;
 }
 export declare function buildCompactLegalQueries(input: CompactQueryInput): CompactQueryCandidate[];