kiri-mcp-server 0.9.9 → 0.10.0

package/dist/src/server/handlers.js

@@ -1,8 +1,11 @@
+import fs from "node:fs";
 import path from "node:path";
 import { checkFTSSchemaExists } from "../indexer/schema.js";
 import { generateEmbedding, structuralSimilarity } from "../shared/embedding.js";
 import { encode as encodeGPT, tokenizeText } from "../shared/tokenizer.js";
 import { getRepoPathCandidates, normalizeRepoPath } from "../shared/utils/path.js";
+import { expandAbbreviations } from "./abbreviations.js";
+import { getBoostProfile, } from "./boost-profiles.js";
 import { coerceProfileName, loadScoringProfile } from "./scoring.js";
 // Configuration file patterns (v0.8.0+: consolidated to avoid duplication)
 // Comprehensive list covering multiple languages and tools
@@ -225,6 +228,9 @@ const MAX_DEPENDENCY_SEEDS_QUERY_LIMIT = 100; // SQL injection防御用の上限
 const NEARBY_LIMIT = 6;
 const FALLBACK_SNIPPET_WINDOW = 40; // Reduced from 120 to optimize token usage
 const MAX_RERANK_LIMIT = 50;
+// Issue #68: Path/Large File Penalty configuration (環境変数で上書き可能)
+const PATH_MISS_DELTA = parseFloat(process.env.KIRI_PATH_MISS_DELTA || "-0.5");
+const LARGE_FILE_DELTA = parseFloat(process.env.KIRI_LARGE_FILE_DELTA || "-0.8");
 const MAX_WHY_TAGS = 10;
 // 項目3: whyタグの優先度マップ（低い数値ほど高優先度）
 // All actual tag prefixes used in the codebase
@@ -513,6 +519,8 @@ function ensureCandidate(map, filePath) {
             ext: null,
             embedding: null,
             semanticSimilarity: null,
+            pathMatchHits: 0, // Issue #68: Track path match count
+            penalties: [], // Issue #68: Penalty log for telemetry
         };
         map.set(filePath, candidate);
     }
@@ -677,6 +685,22 @@ function splitQueryWords(query) {
     const words = query.split(/[\s/\-_]+/).filter((w) => w.length > 2);
     return words.length > 0 ? words : [query]; // 全て除外された場合は元のクエリを使用
 }
+/**
+ * パス固有のマルチプライヤーを取得（最長プレフィックスマッチ）
+ * 配列の順序に依存せず、常に最長一致のプレフィックスを選択
+ * @param filePath - ファイルパス
+ * @param profileConfig - ブーストプロファイル設定
+ * @returns パス固有のマルチプライヤー（マッチなしの場合は1.0）
+ */
+function getPathMultiplier(filePath, profileConfig) {
+    let bestMatch = { prefix: "", multiplier: 1.0 };
+    for (const { prefix, multiplier } of profileConfig.pathMultipliers) {
+        if (filePath.startsWith(prefix) && prefix.length > bestMatch.prefix.length) {
+            bestMatch = { prefix, multiplier };
+        }
+    }
+    return bestMatch.multiplier;
+}
 /**
  * files_search専用のファイルタイプブースト適用（v0.7.0+: 設定可能な乗算的ペナルティ）
  * context_bundleと同じ乗算的ペナルティロジックを使用
@@ -686,7 +710,7 @@ function splitQueryWords(query) {
  * @param weights - スコアリングウェイト設定（乗算的ペナルティに使用）
  * @returns ブースト適用後のスコア
  */
-function applyFileTypeBoost(path, baseScore, profile = "default", weights) {
+function applyFileTypeBoost(path, baseScore, profileConfig, _weights) {
     // Blacklisted directories that are almost always irrelevant for code context
     const blacklistedDirs = [
         ".cursor/",
@@ -699,58 +723,39 @@ function applyFileTypeBoost(path, baseScore, profile = "default", weights) {
     ];
     for (const dir of blacklistedDirs) {
         if (path.startsWith(dir)) {
-            // FIX: boost_profile="docs" の場合は docs/ ブラックリストをスキップ
-            if (profile === "docs" && dir === "docs/") {
+            // ✅ Decoupled: Check denylist overrides from profile config
+            if (profileConfig.denylistOverrides.includes(dir)) {
                 continue;
             }
             return -100; // Effectively remove it
         }
     }
-    if (profile === "none") {
-        return baseScore;
-    }
-    // Extract file extension for type detection
+    const fileName = path.split("/").pop() ?? "";
     const ext = path.includes(".") ? path.substring(path.lastIndexOf(".")) : null;
-    // ✅ UNIFIED LOGIC: Use same multiplicative penalties as context_bundle
-    if (profile === "docs") {
-        // Boost documentation files
-        if (path.endsWith(".md") || path.endsWith(".yaml") || path.endsWith(".yml")) {
-            return baseScore * 1.5; // 50% boost (same as context_bundle)
-        }
-        // Penalty for implementation files in docs mode
-        if (path.startsWith("src/") &&
-            (path.endsWith(".ts") || path.endsWith(".js") || path.endsWith(".tsx"))) {
-            return baseScore * 0.5; // 50% penalty
-        }
-        return baseScore;
-    }
-    // Default profile: Use configurable multiplicative penalties
     let multiplier = 1.0;
-    const fileName = path.split("/").pop() ?? "";
-    // ✅ Step 1: Config files get strongest penalty (95% reduction)
+    // ✅ Step 1: Config files
     if (isConfigFile(path, fileName)) {
-        multiplier *= weights.configPenaltyMultiplier; // 0.05 = 95% reduction
+        multiplier *= profileConfig.fileTypeMultipliers.config;
         return baseScore * multiplier;
     }
-    // ✅ Step 2: Documentation files get moderate penalty (50% reduction)
+    // ✅ Step 2: Documentation files
     const docExtensions = [".md", ".yaml", ".yml", ".mdc"];
     if (docExtensions.some((docExt) => path.endsWith(docExt))) {
-        multiplier *= weights.docPenaltyMultiplier; // 0.5 = 50% reduction
+        multiplier *= profileConfig.fileTypeMultipliers.doc;
         return baseScore * multiplier;
     }
-    // ✅ Step 3: Implementation file boosts
-    if (path.startsWith("src/app/")) {
-        multiplier *= weights.implBoostMultiplier * 1.4; // Extra boost for app files
-    }
-    else if (path.startsWith("src/components/")) {
-        multiplier *= weights.implBoostMultiplier * 1.3;
-    }
-    else if (path.startsWith("src/lib/")) {
-        multiplier *= weights.implBoostMultiplier * 1.2;
+    // ✅ Step 3: Implementation files with path-specific boosts
+    const implMultiplier = profileConfig.fileTypeMultipliers.impl;
+    // ✅ Use longest-prefix-match logic (order-independent)
+    const pathBoost = getPathMultiplier(path, profileConfig);
+    if (pathBoost !== 1.0) {
+        multiplier *= implMultiplier * pathBoost;
+        return baseScore * multiplier;
     }
-    else if (path.startsWith("src/")) {
+    // Fallback for other src/ files
+    if (path.startsWith("src/")) {
         if (ext === ".ts" || ext === ".tsx" || ext === ".js") {
-            multiplier *= weights.implBoostMultiplier; // Base impl boost
+            multiplier *= implMultiplier;
         }
     }
     // Test files: additive penalty (keep strong for files_search)
@@ -767,29 +772,92 @@ function applyPathBasedScoring(candidate, lowerPath, weights, extractedTerms) {
     if (!extractedTerms || weights.pathMatch <= 0) {
         return;
     }
+    // hasAddedScore gates additive boosts; pathMatchHits/reasons still track every hit for penalties/debugging.
+    let hasAddedScore = false;
     // フレーズがパスに完全一致する場合（最高の重み）
     for (const phrase of extractedTerms.phrases) {
         if (lowerPath.includes(phrase)) {
-            candidate.score += weights.pathMatch * 1.5; // 1.5倍のブースト
+            if (!hasAddedScore) {
+                candidate.score += weights.pathMatch * 1.5; // 1.5倍のブースト
+                hasAddedScore = true;
+            }
             candidate.reasons.add(`path-phrase:${phrase}`);
-            return; // 最初のマッチのみ適用
+            candidate.pathMatchHits++; // Issue #68: Track path match for penalty calculation
         }
     }
     // パスセグメントがマッチする場合（中程度の重み）
     const pathParts = lowerPath.split("/");
     for (const segment of extractedTerms.pathSegments) {
         if (pathParts.includes(segment)) {
-            candidate.score += weights.pathMatch;
+            if (!hasAddedScore) {
+                candidate.score += weights.pathMatch;
+                hasAddedScore = true;
+            }
             candidate.reasons.add(`path-segment:${segment}`);
-            return; // 最初のマッチのみ適用
+            candidate.pathMatchHits++; // Issue #68: Track path match for penalty calculation
         }
     }
     // 通常のキーワードがパスに含まれる場合（低い重み）
+    const matchedKeywords = new Set();
     for (const keyword of extractedTerms.keywords) {
         if (lowerPath.includes(keyword)) {
-            candidate.score += weights.pathMatch * 0.5; // 0.5倍のブースト
+            if (!hasAddedScore) {
+                candidate.score += weights.pathMatch * 0.5; // 0.5倍のブースト
+                hasAddedScore = true;
+            }
             candidate.reasons.add(`path-keyword:${keyword}`);
-            return; // 最初のマッチのみ適用
+            candidate.pathMatchHits++; // Issue #68: Track path match for penalty calculation
+            matchedKeywords.add(keyword); // Track for abbreviation expansion
+        }
+    }
+    // ADR 003: Abbreviation expansion for keywords with zero exact matches
+    // Avoid double-counting by only expanding keywords that didn't match exactly
+    // Skip abbreviation expansion for files that will be heavily penalized (test/config/lock files)
+    const fileName = lowerPath.split("/").pop() ?? "";
+    const testPatterns = [".spec.ts", ".spec.js", ".test.ts", ".test.js", ".spec.tsx", ".test.tsx"];
+    const lockFiles = [
+        "package-lock.json",
+        "pnpm-lock.yaml",
+        "yarn.lock",
+        "bun.lockb",
+        "gemfile.lock",
+        "cargo.lock",
+        "poetry.lock",
+    ];
+    const configPatterns = [
+        "tsconfig.json",
+        "vite.config",
+        "vitest.config",
+        "eslint.config",
+        "prettier.config",
+        "package.json",
+        ".env",
+        "dockerfile",
+    ];
+    const shouldSkipAbbreviation = testPatterns.some((pattern) => lowerPath.endsWith(pattern)) ||
+        lockFiles.some((lock) => fileName === lock) ||
+        configPatterns.some((cfg) => fileName.includes(cfg));
+    if (!shouldSkipAbbreviation) {
+        for (const keyword of extractedTerms.keywords) {
+            if (matchedKeywords.has(keyword)) {
+                continue; // Skip keywords that already matched exactly
+            }
+            const expandedTerms = expandAbbreviations(keyword);
+            // Try each expanded variant (except the original keyword itself)
+            for (const term of expandedTerms) {
+                if (term === keyword)
+                    continue; // Skip original to avoid duplicate check
+                if (lowerPath.includes(term)) {
+                    // Lower weight (0.4x) for abbreviation-expanded matches
+                    if (!hasAddedScore) {
+                        candidate.score += weights.pathMatch * 0.4;
+                        hasAddedScore = true;
+                    }
+                    candidate.reasons.add(`abbr-path:${keyword}→${term}`);
+                    candidate.pathMatchHits++; // Count for penalty calculation
+                    break; // Only count first match per keyword to avoid over-boosting
+                }
+            }
         }
     }
 }
@@ -799,7 +867,7 @@ function applyPathBasedScoring(candidate, lowerPath, weights, extractedTerms) {
  * @param profile - boost_profile設定（"docs"の場合はdocs/ディレクトリのブラックリストをスキップ）
  * @returns true if penalty was applied and processing should stop
  */
-function applyAdditiveFilePenalties(candidate, path, lowerPath, fileName, profile) {
+function applyAdditiveFilePenalties(candidate, path, lowerPath, fileName, profileConfig) {
     // Blacklisted directories - effectively remove
     const blacklistedDirs = [
         ".cursor/",
@@ -825,10 +893,9 @@ function applyAdditiveFilePenalties(candidate, path, lowerPath, fileName, profil
     ];
     for (const dir of blacklistedDirs) {
         if (path.startsWith(dir)) {
-            // ✅ FIX (v0.9.0): boost_profile="docs"の場合はdocs/ブラックリストをスキップ
-            // これによりドキュメント検索が正しく機能する
-            if (profile === "docs" && dir === "docs/") {
-                continue; // このブラックリストエントリをスキップ
+            // ✅ Decoupled: Check denylist overrides from profile config
+            if (profileConfig.denylistOverrides.includes(dir)) {
+                continue; // Skip this blacklisted directory
             }
             candidate.score = -100;
             candidate.reasons.add("penalty:blacklisted-dir");
@@ -857,7 +924,7 @@ function applyAdditiveFilePenalties(candidate, path, lowerPath, fileName, profil
         candidate.reasons.add("penalty:lock-file");
         return true;
     }
-    // Configuration files - strong penalty
+    // Configuration files - penalty handling depends on profile
     const configPatterns = [
         ".config.js",
         ".config.ts",
@@ -878,6 +945,12 @@ function applyAdditiveFilePenalties(candidate, path, lowerPath, fileName, profil
         fileName === "Dockerfile" ||
         fileName === "docker-compose.yml" ||
         fileName === "docker-compose.yaml") {
+        // ✅ Use explicit flag instead of magic number (0.3) to determine behavior
+        // This decouples profile detection from multiplier values
+        if (profileConfig.skipConfigAdditivePenalty) {
+            return false; // Continue to multiplicative penalty only
+        }
+        // For other profiles, apply strong additive penalty
         candidate.score -= 1.5;
         candidate.reasons.add("penalty:config-file");
         return true;
@@ -895,54 +968,50 @@ function applyAdditiveFilePenalties(candidate, path, lowerPath, fileName, profil
  * profile="docs": ドキュメントファイルをブースト
  * profile="default": ドキュメントファイルにペナルティ、実装ファイルをブースト
  */
-function applyFileTypeMultipliers(candidate, path, ext, profile, weights) {
-    if (profile === "none") {
-        return;
+function applyFileTypeMultipliers(candidate, path, ext, profileConfig, _weights) {
+    const fileName = path.split("/").pop() ?? "";
+    // ✅ Step 1: Config files
+    if (isConfigFile(path, fileName)) {
+        candidate.scoreMultiplier *= profileConfig.fileTypeMultipliers.config;
+        candidate.reasons.add("penalty:config-file");
+        return; // Don't apply impl boosts to config files
     }
-    // ✅ CRITICAL SAFETY: profile="docs" mode boosts docs, skips penalties
-    if (profile === "docs") {
-        const docExtensions = [".md", ".yaml", ".yml", ".mdc"];
-        if (docExtensions.some((docExt) => path.endsWith(docExt))) {
-            candidate.scoreMultiplier *= 1.5; // 50% boost for docs
+    // ✅ Step 2: Documentation files
+    const docExtensions = [".md", ".yaml", ".yml", ".mdc"];
+    if (docExtensions.some((docExt) => path.endsWith(docExt))) {
+        const docMultiplier = profileConfig.fileTypeMultipliers.doc;
+        candidate.scoreMultiplier *= docMultiplier;
+        if (docMultiplier > 1.0) {
             candidate.reasons.add("boost:doc-file");
         }
-        // No penalty for implementation files in "docs" mode
-        return;
-    }
-    // DEFAULT PROFILE: Use MULTIPLICATIVE penalties for config/docs, MULTIPLICATIVE boosts for impl files
-    if (profile === "default") {
-        const fileName = path.split("/").pop() ?? "";
-        // ✅ Step 1: Config files get strongest penalty (95% reduction)
-        if (isConfigFile(path, fileName)) {
-            candidate.scoreMultiplier *= weights.configPenaltyMultiplier; // 0.05 = 95% reduction
-            candidate.reasons.add("penalty:config-file");
-            return; // Don't apply impl boosts to config files
-        }
-        // ✅ Step 2: Documentation files get moderate penalty (50% reduction)
-        const docExtensions = [".md", ".yaml", ".yml", ".mdc"];
-        if (docExtensions.some((docExt) => path.endsWith(docExt))) {
-            candidate.scoreMultiplier *= weights.docPenaltyMultiplier; // 0.5 = 50% reduction
+        else if (docMultiplier < 1.0) {
             candidate.reasons.add("penalty:doc-file");
-            return; // Don't apply impl boosts to docs
         }
-        // ✅ Step 3: Implementation files get multiplicative boost
+        return; // Don't apply impl boosts to docs
+    }
+    // ✅ Step 3: Implementation files with path-specific boosts
+    const implMultiplier = profileConfig.fileTypeMultipliers.impl;
+    // ✅ Use longest-prefix-match logic (order-independent)
+    const pathBoost = getPathMultiplier(path, profileConfig);
+    if (pathBoost !== 1.0) {
+        candidate.scoreMultiplier *= implMultiplier * pathBoost;
+        // Add specific reason based on matched path
         if (path.startsWith("src/app/")) {
-            candidate.scoreMultiplier *= weights.implBoostMultiplier * 1.4; // Extra boost for app files
             candidate.reasons.add("boost:app-file");
         }
         else if (path.startsWith("src/components/")) {
-            candidate.scoreMultiplier *= weights.implBoostMultiplier * 1.3;
             candidate.reasons.add("boost:component-file");
         }
         else if (path.startsWith("src/lib/")) {
-            candidate.scoreMultiplier *= weights.implBoostMultiplier * 1.2;
             candidate.reasons.add("boost:lib-file");
         }
-        else if (path.startsWith("src/")) {
-            if (ext === ".ts" || ext === ".tsx" || ext === ".js") {
-                candidate.scoreMultiplier *= weights.implBoostMultiplier;
-                candidate.reasons.add("boost:impl-file");
-            }
+        return;
+    }
+    // Fallback for other src/ files
+    if (path.startsWith("src/")) {
+        if (ext === ".ts" || ext === ".tsx" || ext === ".js") {
+            candidate.scoreMultiplier *= implMultiplier;
+            candidate.reasons.add("boost:impl-file");
         }
     }
 }
@@ -958,22 +1027,19 @@ function applyFileTypeMultipliers(candidate, path, ext, profile, weights) {
  * 2. profile="docs" skips documentation penalties (allows doc-focused queries)
  * 3. Blacklist/test/lock/config files keep additive penalties (already very strong)
  */
-function applyBoostProfile(candidate, row, profile, weights, extractedTerms) {
-    if (profile === "none") {
-        return;
-    }
+function applyBoostProfile(candidate, row, profileConfig, weights, extractedTerms) {
     const { path, ext } = row;
     const lowerPath = path.toLowerCase();
     const fileName = path.split("/").pop() ?? "";
     // Step 1: パスベースのスコアリング（加算的ブースト）
     applyPathBasedScoring(candidate, lowerPath, weights, extractedTerms);
     // Step 2: 加算的ペナルティ（ブラックリスト、テスト、lock、設定、マイグレーション）
-    const shouldStop = applyAdditiveFilePenalties(candidate, path, lowerPath, fileName, profile);
+    const shouldStop = applyAdditiveFilePenalties(candidate, path, lowerPath, fileName, profileConfig);
     if (shouldStop) {
         return; // ペナルティが適用された場合は処理終了
     }
     // Step 3: ファイルタイプ別の乗算的ペナルティ/ブースト
-    applyFileTypeMultipliers(candidate, path, ext, profile, weights);
+    applyFileTypeMultipliers(candidate, path, ext, profileConfig, weights);
 }
 export async function filesSearch(context, params) {
     const { db, repoId } = context;
@@ -1058,6 +1124,7 @@ export async function filesSearch(context, params) {
     }
     const rows = await db.all(sql, values);
     const boostProfile = params.boost_profile ?? "default";
+    const profileConfig = getBoostProfile(boostProfile);
     // ✅ v0.7.0+: Load configurable scoring weights for unified boosting logic
     // Note: filesSearch doesn't have a separate profile parameter, uses default weights
     const weights = loadScoringProfile(null);
@@ -1077,7 +1144,9 @@ export async function filesSearch(context, params) {
             matchLine = findFirstMatchLine(row.content ?? "", query);
         }
         const baseScore = row.score ?? 1.0; // FTS時はBM25スコア、ILIKE時は1.0
-        const boostedScore = applyFileTypeBoost(row.path, baseScore, boostProfile, weights);
+        const boostedScore = boostProfile === "none"
+            ? baseScore
+            : applyFileTypeBoost(row.path, baseScore, profileConfig, weights);
         const result = {
             path: row.path,
             matchLine,
@@ -1177,6 +1246,265 @@ export async function snippetsGet(context, params) {
         symbolKind,
     };
 }
+// ============================================================================
+// Issue #68: Path/Large File Penalty Helper Functions
+// ============================================================================
+/**
+ * 環境変数からペナルティ機能フラグを読み取る
+ */
+function readPenaltyFlags() {
+    return {
+        pathPenalty: process.env.KIRI_PATH_PENALTY === "1",
+        largeFilePenalty: process.env.KIRI_LARGE_FILE_PENALTY === "1",
+    };
+}
+/**
+ * クエリ統計を計算（単語数と平均単語長）
+ */
+function computeQueryStats(goal) {
+    const words = goal
+        .trim()
+        .split(/\s+/)
+        .filter((w) => w.length > 0);
+    const totalLength = words.reduce((sum, w) => sum + w.length, 0);
+    return {
+        wordCount: words.length,
+        avgWordLength: words.length > 0 ? totalLength / words.length : 0,
+    };
+}
+/**
+ * Path Miss Penaltyをcandidateに適用（レガシー: Binary penalty）
+ * 条件: wordCount >= 2 AND avgWordLength >= 4 AND pathMatchHits === 0
+ *
+ * @deprecated Use applyGraduatedPenalty() instead (ADR 002)
+ */
+function applyPathMissPenalty(candidate, queryStats) {
+    if (queryStats.wordCount >= 2 && queryStats.avgWordLength >= 4 && candidate.pathMatchHits === 0) {
+        candidate.score += PATH_MISS_DELTA; // -0.5
+        recordPenaltyEvent(candidate, "path-miss", PATH_MISS_DELTA, {
+            wordCount: queryStats.wordCount,
+            avgWordLength: queryStats.avgWordLength,
+            pathMatchHits: candidate.pathMatchHits,
+        });
+    }
+}
+/**
+ * 段階的ペナルティをcandidateに適用（Issue #68: Graduated Penalty）
+ * ADR 002: Graduated Penalty System
+ *
+ * @param candidate Candidate to apply penalty to
+ * @param queryStats Query statistics for eligibility check
+ * @param config Graduated penalty configuration
+ */
+function applyGraduatedPenalty(candidate, queryStats, config) {
+    const penalty = computeGraduatedPenalty(candidate.pathMatchHits, queryStats, config);
+    if (penalty !== 0) {
+        candidate.score += penalty;
+        recordPenaltyEvent(candidate, "path-miss", penalty, {
+            wordCount: queryStats.wordCount,
+            avgWordLength: queryStats.avgWordLength,
+            pathMatchHits: candidate.pathMatchHits,
+            tier: candidate.pathMatchHits === 0
+                ? "tier0"
+                : candidate.pathMatchHits === 1
+                    ? "tier1"
+                    : candidate.pathMatchHits === 2
+                        ? "tier2"
+                        : "no-penalty",
+        });
+    }
+}
+/**
+ * Large File Penaltyをcandidateに適用
+ * 条件: totalLines > 500 AND matchLine > 120
+ * TODO(Issue #68): Add "no symbol at match location" check after selectSnippet integration
+ */
+function applyLargeFilePenalty(candidate) {
+    const { totalLines, matchLine } = candidate;
+    if (totalLines !== null && totalLines > 500 && matchLine !== null && matchLine > 120) {
+        candidate.score += LARGE_FILE_DELTA; // -0.8
+        recordPenaltyEvent(candidate, "large-file", LARGE_FILE_DELTA, {
+            totalLines,
+            matchLine,
+        });
+    }
+}
+/**
+ * ペナルティイベントを記録（テレメトリ用）
+ */
+function recordPenaltyEvent(candidate, kind, delta, details) {
+    candidate.penalties.push({ kind, delta, details });
+    candidate.reasons.add(`penalty:${kind}`);
+}
+/**
+ * pathMatchHits分布を計算（Issue #68: Telemetry）
+ * LDE: 純粋関数として実装（副作用なし、イミュータブル）
+ */
+function computePathMatchDistribution(candidates) {
+    let zero = 0;
+    let one = 0;
+    let two = 0;
+    let three = 0;
+    let fourPlus = 0;
+    for (const candidate of candidates) {
+        const hits = candidate.pathMatchHits;
+        if (hits === 0)
+            zero++;
+        else if (hits === 1)
+            one++;
+        else if (hits === 2)
+            two++;
+        else if (hits === 3)
+            three++;
+        else
+            fourPlus++;
+    }
+    return {
+        zero,
+        one,
+        two,
+        three,
+        fourPlus,
+        total: candidates.length,
+    };
+}
+/**
+ * スコア統計を計算（Issue #68: Telemetry）
+ * LDE: 純粋関数として実装（副作用なし、イミュータブル）
+ */
+function computeScoreStats(candidates) {
+    if (candidates.length === 0) {
+        return { min: 0, max: 0, mean: 0, median: 0 };
+    }
+    const scores = candidates.map((c) => c.score).sort((a, b) => a - b);
+    const sum = scores.reduce((acc, s) => acc + s, 0);
+    const mean = sum / scores.length;
+    const median = scores[Math.floor(scores.length / 2)] ?? 0;
+    return {
+        min: scores[0] ?? 0,
+        max: scores[scores.length - 1] ?? 0,
+        mean,
+        median,
+    };
+}
+/**
+ * ペナルティ適用状況を計算（Issue #68: Telemetry）
+ * LDE: 純粋関数として実装（副作用なし、イミュータブル）
+ */
+function computePenaltyTelemetry(candidates) {
+    let pathMissPenalties = 0;
+    let largeFilePenalties = 0;
+    for (const candidate of candidates) {
+        for (const penalty of candidate.penalties) {
+            if (penalty.kind === "path-miss")
+                pathMissPenalties++;
+            if (penalty.kind === "large-file")
+                largeFilePenalties++;
+        }
+    }
+    return {
+        pathMissPenalties,
+        largeFilePenalties,
+        totalCandidates: candidates.length,
+        pathMatchDistribution: computePathMatchDistribution(candidates),
+        scoreStats: computeScoreStats(candidates),
+    };
+}
+/**
+ * テレメトリーをファイル出力（Issue #68: Debug）
+ * LDE: 副作用を分離（I/O操作）
+ *
+ * JSON Lines形式で /tmp/kiri-penalty-telemetry.jsonl に追記
+ */
+function logPenaltyTelemetry(telemetry, queryStats) {
+    const dist = telemetry.pathMatchDistribution;
+    const scores = telemetry.scoreStats;
+    // JSON Lines形式でテレメトリーデータを記録
+    const telemetryRecord = {
+        timestamp: new Date().toISOString(),
+        query: {
+            wordCount: queryStats.wordCount,
+            avgWordLength: queryStats.avgWordLength,
+        },
+        totalCandidates: telemetry.totalCandidates,
+        pathMissPenalties: telemetry.pathMissPenalties,
+        largeFilePenalties: telemetry.largeFilePenalties,
+        pathMatchDistribution: {
+            zero: dist.zero,
+            one: dist.one,
+            two: dist.two,
+            three: dist.three,
+            fourPlus: dist.fourPlus,
+            total: dist.total,
+            percentages: {
+                zero: ((dist.zero / dist.total) * 100).toFixed(1),
+                one: ((dist.one / dist.total) * 100).toFixed(1),
+                two: ((dist.two / dist.total) * 100).toFixed(1),
+                three: ((dist.three / dist.total) * 100).toFixed(1),
+                fourPlus: ((dist.fourPlus / dist.total) * 100).toFixed(1),
+            },
+        },
+        scoreStats: {
+            min: scores.min.toFixed(2),
+            max: scores.max.toFixed(2),
+            mean: scores.mean.toFixed(2),
+            median: scores.median.toFixed(2),
+            // 最大ペナルティ(-0.8)との比率
+            penaltyRatio: ((0.8 / scores.mean) * 100).toFixed(1) + "%",
+        },
+    };
+    const telemetryFile = "/tmp/kiri-penalty-telemetry.jsonl";
+    fs.appendFileSync(telemetryFile, JSON.stringify(telemetryRecord) + "\n");
+}
+/**
+ * 環境変数から段階的ペナルティ設定を読み込む（Issue #68: Graduated Penalty）
+ * LDE: 純粋関数（I/O分離、テスト可能）
+ */
+function readGraduatedPenaltyConfig() {
+    return {
+        enabled: process.env.KIRI_GRADUATED_PENALTY === "1",
+        minWordCount: parseFloat(process.env.KIRI_PENALTY_MIN_WORD_COUNT || "2"),
+        minAvgWordLength: parseFloat(process.env.KIRI_PENALTY_MIN_AVG_WORD_LENGTH || "4.0"),
+        tier0Delta: parseFloat(process.env.KIRI_PENALTY_TIER_0 || "-0.8"),
+        tier1Delta: parseFloat(process.env.KIRI_PENALTY_TIER_1 || "-0.4"),
+        tier2Delta: parseFloat(process.env.KIRI_PENALTY_TIER_2 || "-0.2"),
+    };
+}
+/**
+ * 段階的ペナルティ値を計算（Issue #68: Graduated Penalty）
+ * LDE: 純粋関数（副作用なし、参照透明性）
+ *
+ * ADR 002: Graduated Penalty System
+ * - Tier 0 (pathMatchHits === 0): Strong penalty (no path evidence)
+ * - Tier 1 (pathMatchHits === 1): Medium penalty (weak path evidence)
+ * - Tier 2 (pathMatchHits === 2): Light penalty (moderate path evidence)
+ * - Tier 3+ (pathMatchHits >= 3): No penalty (strong path evidence)
+ *
+ * Invariants:
+ * - Result is always <= 0 (non-positive)
+ * - More path hits → less penalty (monotonicity)
+ * - Query must meet eligibility criteria
+ *
+ * @param pathMatchHits Number of path-based scoring matches
+ * @param queryStats Query word count and average word length
+ * @param config Graduated penalty configuration
+ * @returns Penalty delta (always <= 0)
+ */
+function computeGraduatedPenalty(pathMatchHits, queryStats, config) {
+    // Early return if query doesn't meet criteria
+    if (queryStats.wordCount < config.minWordCount ||
+        queryStats.avgWordLength < config.minAvgWordLength) {
+        return 0;
+    }
+    // Graduated penalty tiers
+    if (pathMatchHits === 0)
+        return config.tier0Delta;
+    if (pathMatchHits === 1)
+        return config.tier1Delta;
+    if (pathMatchHits === 2)
+        return config.tier2Delta;
+    return 0; // pathMatchHits >= 3: no penalty
+}
 export async function contextBundle(context, params) {
     context.warningManager.startRequest();
     const { db, repoId } = context;
@@ -1224,6 +1552,9 @@ export async function contextBundle(context, params) {
     const candidates = new Map();
     const stringMatchSeeds = new Set();
     const fileCache = new Map();
+    // ✅ Cache boost profile config to avoid redundant lookups in hot path
+    const boostProfile = params.boost_profile ?? "default";
+    const profileConfig = getBoostProfile(boostProfile);
     // フレーズマッチング（高い重み: textMatch × 2）- 統合クエリでパフォーマンス改善
     if (extractedTerms.phrases.length > 0) {
         const phrasePlaceholders = extractedTerms.phrases
@@ -1242,7 +1573,6 @@ export async function contextBundle(context, params) {
         ORDER BY f.path
         LIMIT ?
       `, [repoId, ...extractedTerms.phrases, MAX_MATCHES_PER_KEYWORD * extractedTerms.phrases.length]);
-        const boostProfile = params.boost_profile ?? "default";
         for (const row of rows) {
             if (row.content === null) {
                 continue;
@@ -1261,7 +1591,9 @@ export async function contextBundle(context, params) {
                 candidate.reasons.add(`phrase:${phrase}`);
             }
             // Apply boost profile once per file
-            applyBoostProfile(candidate, row, boostProfile, weights, extractedTerms);
+            if (boostProfile !== "none") {
+                applyBoostProfile(candidate, row, profileConfig, weights, extractedTerms);
+            }
             // Use first matched phrase for preview (guaranteed to exist due to length check above)
             const { line } = buildPreview(row.content, matchedPhrases[0]);
             candidate.matchLine =
@@ -1301,7 +1633,6 @@ export async function contextBundle(context, params) {
         ORDER BY f.path
         LIMIT ?
       `, [repoId, ...extractedTerms.keywords, MAX_MATCHES_PER_KEYWORD * extractedTerms.keywords.length]);
-        const boostProfile = params.boost_profile ?? "default";
         for (const row of rows) {
             if (row.content === null) {
                 continue;
@@ -1319,7 +1650,9 @@ export async function contextBundle(context, params) {
                 candidate.reasons.add(`text:${keyword}`);
             }
             // Apply boost profile once per file
-            applyBoostProfile(candidate, row, boostProfile, weights, extractedTerms);
+            if (boostProfile !== "none") {
+                applyBoostProfile(candidate, row, profileConfig, weights, extractedTerms);
+            }
             // Use first matched keyword for preview (guaranteed to exist due to length check above)
             const { line } = buildPreview(row.content, matchedKeywords[0]);
             candidate.matchLine =
@@ -1456,6 +1789,36 @@ export async function contextBundle(context, params) {
             candidate.score *= candidate.scoreMultiplier;
         }
     }
+    // Issue #68: Apply Path-Based Penalties (after multipliers, before sorting)
+    const penaltyFlags = readPenaltyFlags();
+    const queryStats = computeQueryStats(goal); // Always compute for telemetry
+    const graduatedConfig = readGraduatedPenaltyConfig();
+    // ADR 002: Use graduated penalty system if enabled, otherwise use legacy binary penalty
+    if (graduatedConfig.enabled && penaltyFlags.pathPenalty) {
+        for (const candidate of materializedCandidates) {
+            applyGraduatedPenalty(candidate, queryStats, graduatedConfig);
+        }
+    }
+    else if (penaltyFlags.pathPenalty) {
+        // Legacy mode: Binary penalty (pathMatchHits === 0 only)
+        for (const candidate of materializedCandidates) {
+            applyPathMissPenalty(candidate, queryStats);
+        }
+    }
+    // Issue #68: Apply Large File Penalty (after multipliers, before sorting)
+    if (penaltyFlags.largeFilePenalty) {
+        for (const candidate of materializedCandidates) {
+            applyLargeFilePenalty(candidate);
+        }
+    }
+    // Issue #68: Telemetry（デバッグ用、環境変数で制御）
+    // LDE: 純粋関数（計算）と副作用（I/O）を分離
+    const enableTelemetry = process.env.KIRI_PENALTY_TELEMETRY === "1";
+    if (enableTelemetry) {
+        console.error(`[DEBUG] Telemetry enabled. Flags: pathPenalty=${penaltyFlags.pathPenalty}, largeFilePenalty=${penaltyFlags.largeFilePenalty}`);
+        const telemetry = computePenaltyTelemetry(materializedCandidates);
+        logPenaltyTelemetry(telemetry, queryStats);
+    }
     const sortedCandidates = materializedCandidates
         .filter((candidate) => candidate.score > 0) // Filter out candidates with negative or zero scores
         .sort((a, b) => {