kiri-mcp-server 0.9.9 → 0.11.0

package/dist/src/server/handlers.js

@@ -1,9 +1,15 @@
+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 { loadServerConfig } from "./config.js";
 import { coerceProfileName, loadScoringProfile } from "./scoring.js";
+import { createServerServices } from "./services/index.js";
+// Re-export extracted handlers for backward compatibility
+export { snippetsGet, } from "./handlers/snippets-get.js";
 // Configuration file patterns (v0.8.0+: consolidated to avoid duplication)
 // Comprehensive list covering multiple languages and tools
 const CONFIG_FILES = [
@@ -130,6 +136,83 @@ const CONFIG_PATTERNS = [
     ".github/workflows",
 ];
 const FTS_STATUS_CACHE_TTL_MS = 10_000;
+const METADATA_ALIAS_MAP = new Map([
+    ["tag", { key: "tags" }],
+    ["tags", { key: "tags" }],
+    ["category", { key: "category" }],
+    ["title", { key: "title" }],
+    ["service", { key: "service" }],
+]);
+const METADATA_KEY_PREFIXES = [
+    { prefix: "meta." },
+    { prefix: "metadata.", strict: true },
+    { prefix: "docmeta.", strict: true },
+    { prefix: "frontmatter.", source: "front_matter" },
+    { prefix: "fm.", source: "front_matter" },
+    { prefix: "yaml.", source: "yaml" },
+    { prefix: "json.", source: "json" },
+];
+const METADATA_MATCH_WEIGHT = 0.15;
+const METADATA_FILTER_MATCH_WEIGHT = 0.1;
+const METADATA_HINT_BONUS = 0.25;
+const INBOUND_LINK_WEIGHT = 0.2;
+/**
+ * checkTableAvailability
+ *
+ * 起動時にテーブルの存在を確認し、TableAvailabilityオブジェクトを生成する。
+ * これにより、グローバルミュータブル変数による競合状態を回避する。
+ *
+ * NOTE: スキーマ変更（テーブル追加）後はサーバーの再起動が必要です。
+ *
+ * @param db - DuckDBClient インスタンス
+ * @returns TableAvailability オブジェクト
+ * @throws データベース接続エラー等、テーブル不在以外のエラーが発生した場合
+ */
+export async function checkTableAvailability(db) {
+    const ALLOWED_TABLES = [
+        "document_metadata_kv",
+        "markdown_link",
+        "hint_expansion",
+        "hint_dictionary",
+    ];
+    const checkTable = async (tableName) => {
+        if (!ALLOWED_TABLES.includes(tableName)) {
+            throw new Error(`Invalid table name: ${tableName}`);
+        }
+        try {
+            await db.all(`SELECT 1 FROM ${tableName} LIMIT 0`);
+            return true;
+        }
+        catch (error) {
+            // テーブル不在エラーのみキャッチ
+            if (isTableMissingError(error, tableName)) {
+                return false;
+            }
+            // その他のエラー（接続エラー等）は再スロー
+            throw new Error(`Failed to check table availability for ${tableName}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    const result = {
+        hasMetadataTables: await checkTable("document_metadata_kv"),
+        hasLinkTable: await checkTable("markdown_link"),
+        hasHintLog: await checkTable("hint_expansion"),
+        hasHintDictionary: await checkTable("hint_dictionary"),
+    };
+    // 起動時警告: テーブルが存在しない場合に通知
+    if (!result.hasMetadataTables) {
+        console.warn("document_metadata_kv table is missing. Metadata filters and boosts disabled until database is upgraded.");
+    }
+    if (!result.hasLinkTable) {
+        console.warn("markdown_link table is missing. Inbound link boosting disabled until database is upgraded.");
+    }
+    if (!result.hasHintLog) {
+        console.warn("hint_expansion table is missing. Hint logging disabled. Enable the latest schema and rerun the indexer to capture hint logs.");
+    }
+    if (!result.hasHintDictionary) {
+        console.warn("hint_dictionary table is missing. Dictionary hints disabled. Run scripts/diag/build-hint-dictionary.ts after upgrading the schema.");
+    }
+    return result;
+}
 async function hasDirtyRepos(db) {
     const statusCheck = await db.all(`SELECT COUNT(*) as count FROM repo
        WHERE fts_dirty = true OR fts_status IN ('dirty', 'rebuilding')`);
@@ -214,8 +297,154 @@ function isConfigFile(path, fileName) {
         fileName.startsWith(".env") ||
         isInConfigDirectory);
 }
+function normalizeArtifactHints(hints) {
+    if (!Array.isArray(hints)) {
+        return [];
+    }
+    const normalized = [];
+    const seen = new Set();
+    for (const rawHint of hints) {
+        if (typeof rawHint !== "string") {
+            continue;
+        }
+        const trimmed = rawHint.trim();
+        if (!trimmed || seen.has(trimmed)) {
+            continue;
+        }
+        normalized.push(trimmed);
+        seen.add(trimmed);
+        if (normalized.length >= MAX_ARTIFACT_HINTS) {
+            break;
+        }
+    }
+    return normalized;
+}
+function bucketArtifactHints(hints) {
+    const buckets = {
+        pathHints: [],
+        substringHints: [],
+    };
+    for (const hint of hints) {
+        if (hint.includes("/") && SAFE_PATH_PATTERN.test(hint)) {
+            buckets.pathHints.push(hint);
+            continue;
+        }
+        const normalized = hint.trim().toLowerCase();
+        if (normalized.length >= 3) {
+            buckets.substringHints.push(normalized);
+        }
+    }
+    return buckets;
+}
+function isMissingTableError(error, table) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return /Table with name/i.test(error.message) && error.message.includes(table);
+}
+async function logHintExpansionEntry(db, tableAvailability, entry) {
+    if (!HINT_LOG_ENABLED) {
+        return;
+    }
+    if (!tableAvailability.hasHintLog) {
+        return;
+    }
+    try {
+        await db.run(`
+        INSERT INTO hint_expansion (repo_id, hint_value, expansion_kind, target_path, payload)
+        VALUES (?, ?, ?, ?, ?)
+      `, [
+            entry.repoId,
+            entry.hintValue,
+            entry.kind,
+            entry.targetPath ?? null,
+            entry.payload ? JSON.stringify(entry.payload) : null,
+        ]);
+    }
+    catch (error) {
+        if (isMissingTableError(error, "hint_expansion")) {
+            console.warn("hint_expansion table is missing in the active database. Enable the latest schema and rerun the indexer to capture hint logs.");
+            return;
+        }
+        throw error;
+    }
+}
+async function fetchDictionaryPathHints(db, tableAvailability, repoId, hints, perHintLimit) {
+    if (!HINT_DICTIONARY_ENABLED || perHintLimit <= 0 || hints.length === 0) {
+        return [];
+    }
+    if (!tableAvailability.hasHintDictionary) {
+        return [];
+    }
+    const uniqueHints = Array.from(new Set(hints));
+    const targets = [];
+    for (const hint of uniqueHints) {
+        let rows = [];
+        try {
+            rows = await db.all(`
+          SELECT target_path
+          FROM hint_dictionary
+          WHERE repo_id = ?
+            AND hint_value = ?
+          ORDER BY freq DESC, target_path
+          LIMIT ?
+        `, [repoId, hint, perHintLimit]);
+        }
+        catch (error) {
+            if (isMissingTableError(error, "hint_dictionary")) {
+                console.warn("hint_dictionary table is missing in the active database. Run scripts/diag/build-hint-dictionary.ts after upgrading the schema.");
+                return [];
+            }
+            throw error;
+        }
+        for (const row of rows) {
+            if (!row.target_path || !SAFE_PATH_PATTERN.test(row.target_path)) {
+                continue;
+            }
+            targets.push({ path: row.target_path, sourceHint: hint, origin: "dictionary" });
+        }
+    }
+    return targets;
+}
+function createHintSeedMeta(targets) {
+    const meta = new Map();
+    const deduped = [];
+    for (const target of targets) {
+        if (meta.has(target.path)) {
+            continue;
+        }
+        meta.set(target.path, { sourceHint: target.sourceHint, origin: target.origin });
+        deduped.push(target);
+    }
+    return { list: deduped, meta };
+}
+function getHintSeedMeta(seedMeta, path) {
+    return seedMeta?.get(path);
+}
+function computeHintPriorityBoost(weights) {
+    const textComponent = weights.textMatch * HINT_PRIORITY_TEXT_MULTIPLIER;
+    const pathComponent = weights.pathMatch * HINT_PRIORITY_PATH_MULTIPLIER;
+    const aggregate = textComponent + pathComponent + weights.editingPath + weights.dependency;
+    return Math.max(HINT_PRIORITY_BASE_BONUS, aggregate);
+}
+function createHintExpansionConfig(weights) {
+    return {
+        dirLimit: Math.max(0, HINT_DIR_LIMIT),
+        dirMaxFiles: Math.max(1, HINT_DIR_MAX_FILES),
+        depOutLimit: Math.max(0, HINT_DEP_OUT_LIMIT),
+        depInLimit: Math.max(0, HINT_DEP_IN_LIMIT),
+        semLimit: Math.max(0, HINT_SEM_LIMIT),
+        semDirCandidateLimit: Math.max(1, HINT_SEM_DIR_CANDIDATE_LIMIT),
+        semThreshold: Number.isFinite(HINT_SEM_THRESHOLD) ? HINT_SEM_THRESHOLD : 0.65,
+        perHintLimit: Math.max(0, HINT_PER_HINT_LIMIT),
+        dbQueryBudget: Math.max(0, HINT_DB_QUERY_BUDGET),
+        dirBoost: computeHintPriorityBoost(weights) * 0.35,
+        depBoost: weights.dependency * 0.8,
+        substringLimit: Math.max(0, HINT_SUBSTRING_LIMIT),
+        substringBoost: Math.max(0, HINT_SUBSTRING_BOOST),
+    };
+}
 const DEFAULT_SEARCH_LIMIT = 50;
-const DEFAULT_SNIPPET_WINDOW = 150;
 const DEFAULT_BUNDLE_LIMIT = 7; // Reduced from 12 to optimize token usage
 const MAX_BUNDLE_LIMIT = 20;
 const MAX_KEYWORDS = 12;
@@ -223,32 +452,76 @@ const MAX_MATCHES_PER_KEYWORD = 40;
 const MAX_DEPENDENCY_SEEDS = 8;
 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 serverConfig = loadServerConfig();
+const SUPPRESS_NON_CODE_ENABLED = serverConfig.features.suppressNonCode;
+const FINAL_RESULT_SUPPRESSION_ENABLED = serverConfig.features.suppressFinalResults;
+const CLAMP_SNIPPETS_ENABLED = serverConfig.features.clampSnippets;
+const FALLBACK_SNIPPET_WINDOW = serverConfig.features.snippetWindow;
 const MAX_RERANK_LIMIT = 50;
+const MAX_ARTIFACT_HINTS = 8;
+const SAFE_PATH_PATTERN = /^[a-zA-Z0-9_.\-/]+$/;
+const HINT_PRIORITY_TEXT_MULTIPLIER = serverConfig.hints.priority.textMultiplier;
+const HINT_PRIORITY_PATH_MULTIPLIER = serverConfig.hints.priority.pathMultiplier;
+const HINT_PRIORITY_BASE_BONUS = serverConfig.hints.priority.baseBonus;
+const HINT_DIR_LIMIT = serverConfig.hints.directory.limit;
+const HINT_DIR_MAX_FILES = serverConfig.hints.directory.maxFiles;
+const HINT_DEP_OUT_LIMIT = serverConfig.hints.dependency.outLimit;
+const HINT_DEP_IN_LIMIT = serverConfig.hints.dependency.inLimit;
+const HINT_SEM_LIMIT = serverConfig.hints.semantic.limit;
+const HINT_SEM_DIR_CANDIDATE_LIMIT = serverConfig.hints.semantic.dirCandidateLimit;
+const HINT_SEM_THRESHOLD = serverConfig.hints.semantic.threshold;
+const SUPPRESSED_PATH_PREFIXES = [".github/", ".git/", "ThirdPartyNotices", "node_modules/"];
+const SUPPRESSED_FILE_NAMES = ["thirdpartynotices.txt", "thirdpartynotices.md", "cgmanifest.json"];
+function isSuppressedPath(path) {
+    if (!SUPPRESS_NON_CODE_ENABLED) {
+        return false;
+    }
+    const normalized = path.startsWith("./") ? path.replace(/^\.\/+/u, "") : path;
+    const lower = normalized.toLowerCase();
+    if (SUPPRESSED_FILE_NAMES.some((name) => lower.endsWith(name))) {
+        return true;
+    }
+    const lowerPrefixMatches = SUPPRESSED_PATH_PREFIXES.map((prefix) => prefix.toLowerCase());
+    return lowerPrefixMatches.some((prefix) => lower.includes(prefix));
+}
+const HINT_PER_HINT_LIMIT = serverConfig.hints.perHintLimit;
+const HINT_DB_QUERY_BUDGET = serverConfig.hints.dbQueryLimit;
+const HINT_SUBSTRING_LIMIT = serverConfig.hints.substring.limit;
+const HINT_SUBSTRING_BOOST = serverConfig.hints.substring.boost;
+const HINT_LOG_ENABLED = process.env.KIRI_HINT_LOG === "1";
+const HINT_DICTIONARY_ENABLED = process.env.KIRI_HINT_DICTIONARY !== "0";
+const HINT_DICTIONARY_LIMIT = Math.max(0, Number.parseInt(process.env.KIRI_HINT_DICTIONARY_LIMIT ?? "2", 10));
+// Issue #68: Path/Large File Penalty configuration (環境変数で上書き可能)
+const PATH_MISS_DELTA = serverConfig.penalties.pathMissDelta;
+const LARGE_FILE_DELTA = serverConfig.penalties.largeFileDelta;
 const MAX_WHY_TAGS = 10;
 // 項目3: whyタグの優先度マップ（低い数値ほど高優先度）
 // All actual tag prefixes used in the codebase
 const WHY_TAG_PRIORITY = {
-    artifact: 1, // User-provided hints (editing_path, failing_tests)
+    artifact: 1, // User-provided hints (editing_path, failing_tests, hints)
+    dictionary: 1, // Dictionary-provided hints
     phrase: 2, // Multi-word literal matches (strongest signal)
     text: 3, // Single keyword matches
-    "path-phrase": 4, // Path contains multi-word phrase
-    structural: 5, // Semantic similarity
-    "path-segment": 6, // Path component matches
-    "path-keyword": 7, // Path keyword match
-    dep: 8, // Dependency relationship
-    near: 9, // Proximity to editing file
-    boost: 10, // File type boost
-    recent: 11, // Recently changed
-    symbol: 12, // Symbol match
-    penalty: 13, // Penalty explanations (keep for transparency)
-    keyword: 14, // Generic keyword (deprecated, kept for compatibility)
+    metadata: 4, // Front matter / metadata filters & boosts
+    substring: 4, // Substring hint expansion
+    "path-phrase": 5, // Path contains multi-word phrase
+    structural: 6, // Semantic similarity
+    "path-segment": 7, // Path component matches
+    "path-keyword": 8, // Path keyword match
+    dep: 9, // Dependency relationship
+    near: 10, // Proximity to editing file
+    boost: 11, // File type boost
+    recent: 12, // Recently changed
+    symbol: 13, // Symbol match
+    penalty: 14, // Penalty explanations (keep for transparency)
+    keyword: 15, // Generic keyword (deprecated, kept for compatibility)
 };
 // Reserve at least one slot for important structural tags
 const RESERVED_WHY_SLOTS = {
     dep: 1, // Dependency relationships are critical
     symbol: 1, // Symbol boundaries help understand context
     near: 1, // Proximity explains file selection
+    metadata: 1, // Preserve metadata reasons when filters/boosts are active
 };
 function parseOutputOptions(params) {
     return {
@@ -271,6 +544,9 @@ function selectWhyTags(reasons) {
         reasons = new Set(Array.from(reasons).slice(0, 1000));
     }
     const selected = new Set();
+    if (reasons.has("boost:links")) {
+        selected.add("boost:links");
+    }
     const byCategory = new Map();
     for (const reason of reasons) {
         const prefix = reason.split(":")[0] ?? "";
@@ -336,6 +612,45 @@ const STOP_WORDS = new Set([
     "need",
     "goal",
 ]);
+function prioritizeHintCandidates(rankedCandidates, hintPaths, limit) {
+    if (rankedCandidates.length === 0) {
+        return [];
+    }
+    const sanitizedLimit = Math.max(1, Math.min(limit, rankedCandidates.length));
+    const candidateByPath = new Map();
+    for (const candidate of rankedCandidates) {
+        if (!candidateByPath.has(candidate.path)) {
+            candidateByPath.set(candidate.path, candidate);
+        }
+    }
+    const final = [];
+    const seen = new Set();
+    for (const hintPath of hintPaths) {
+        if (final.length >= sanitizedLimit) {
+            break;
+        }
+        const candidate = candidateByPath.get(hintPath);
+        if (!candidate || seen.has(candidate.path)) {
+            continue;
+        }
+        final.push(candidate);
+        seen.add(candidate.path);
+    }
+    if (final.length >= sanitizedLimit) {
+        return final;
+    }
+    for (const candidate of rankedCandidates) {
+        if (final.length >= sanitizedLimit) {
+            break;
+        }
+        if (seen.has(candidate.path)) {
+            continue;
+        }
+        final.push(candidate);
+        seen.add(candidate.path);
+    }
+    return final;
+}
 function normalizeLimit(limit) {
     if (!limit || Number.isNaN(limit)) {
         return DEFAULT_SEARCH_LIMIT;
@@ -513,13 +828,358 @@ 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);
     }
     return candidate;
 }
+async function expandHintCandidatesForHints(params) {
+    const { hintPaths, config } = params;
+    if (hintPaths.length === 0 || config.perHintLimit <= 0 || config.dbQueryBudget <= 0) {
+        return;
+    }
+    const state = { remainingDbQueries: config.dbQueryBudget };
+    for (const hintPath of hintPaths) {
+        if (state.remainingDbQueries <= 0) {
+            break;
+        }
+        await expandSingleHintNeighborhood({ ...params, hintPath, state });
+    }
+}
+async function expandSingleHintNeighborhood(args) {
+    const { config } = args;
+    let remaining = config.perHintLimit;
+    if (remaining <= 0) {
+        return;
+    }
+    if (config.dirLimit > 0) {
+        const added = await addHintDirectoryNeighbors(args, Math.min(config.dirLimit, remaining));
+        remaining -= added;
+        if (remaining <= 0) {
+            return;
+        }
+    }
+    if (config.depOutLimit > 0 || config.depInLimit > 0) {
+        const added = await addHintDependencyNeighbors(args, remaining);
+        remaining -= added;
+        if (remaining <= 0) {
+            return;
+        }
+    }
+    if (config.semLimit > 0) {
+        await addHintSemanticNeighbors(args, Math.min(config.semLimit, remaining));
+    }
+}
+function useHintDbBudget(state, cost = 1) {
+    if (state.remainingDbQueries < cost) {
+        return false;
+    }
+    state.remainingDbQueries -= cost;
+    return true;
+}
+function applyHintReasonBoost(candidate, reason, scoreDelta, lang, ext) {
+    if (scoreDelta <= 0 || candidate.reasons.has(reason)) {
+        return false;
+    }
+    candidate.score += scoreDelta;
+    candidate.reasons.add(reason);
+    candidate.pathMatchHits = Math.max(candidate.pathMatchHits, 2);
+    candidate.matchLine ??= 1;
+    if (lang && !candidate.lang) {
+        candidate.lang = lang;
+    }
+    if (ext && !candidate.ext) {
+        candidate.ext = ext;
+    }
+    return true;
+}
+async function applyPathHintPromotions(args) {
+    const { hintTargets } = args;
+    if (hintTargets.length === 0) {
+        return;
+    }
+    const hintBoost = computeHintPriorityBoost(args.weights);
+    for (const target of hintTargets) {
+        const candidate = ensureCandidate(args.candidates, target.path);
+        const reasonPrefix = target.origin === "dictionary" ? "dictionary:hint" : "artifact:hint";
+        candidate.score += hintBoost;
+        candidate.reasons.add(`${reasonPrefix}:${target.path}`);
+        candidate.pathMatchHits = Math.max(candidate.pathMatchHits, 3);
+        candidate.matchLine ??= 1;
+        await logHintExpansionEntry(args.db, args.tableAvailability, {
+            repoId: args.repoId,
+            hintValue: target.sourceHint,
+            kind: target.origin === "dictionary" ? "dictionary" : "path",
+            targetPath: target.path,
+            payload: {
+                origin: target.origin,
+                source_hint: target.sourceHint,
+            },
+        });
+    }
+    await expandHintCandidatesForHints({
+        db: args.db,
+        tableAvailability: args.tableAvailability,
+        repoId: args.repoId,
+        hintPaths: hintTargets.map((target) => target.path),
+        candidates: args.candidates,
+        fileCache: args.fileCache,
+        weights: args.weights,
+        config: createHintExpansionConfig(args.weights),
+        hintSeedMeta: args.hintSeedMeta,
+    });
+}
+async function addHintSubstringMatches(db, tableAvailability, repoId, hints, candidates, limitPerHint, boost) {
+    if (limitPerHint <= 0 || boost <= 0) {
+        return;
+    }
+    for (const hint of hints) {
+        if (!SAFE_PATH_PATTERN.test(hint.replace(/[^a-zA-Z0-9_.-]/g, ""))) {
+            continue;
+        }
+        const rows = await db.all(`
+        SELECT path
+        FROM file
+        WHERE repo_id = ?
+          AND is_binary = FALSE
+          AND LOWER(path) LIKE '%' || ? || '%'
+        ORDER BY path
+        LIMIT ?
+      `, [repoId, hint, limitPerHint]);
+        for (const row of rows) {
+            const candidate = ensureCandidate(candidates, row.path);
+            const reason = `substring:hint:${hint}`;
+            if (applyHintReasonBoost(candidate, reason, boost)) {
+                await logHintExpansionEntry(db, tableAvailability, {
+                    repoId,
+                    hintValue: hint,
+                    kind: "substring",
+                    targetPath: row.path,
+                });
+            }
+        }
+    }
+}
+async function addHintDirectoryNeighbors(args, limit) {
+    if (limit <= 0) {
+        return 0;
+    }
+    const dir = path.posix.dirname(args.hintPath);
+    if (!dir || dir === "." || dir === "/") {
+        return 0;
+    }
+    if (!useHintDbBudget(args.state)) {
+        return 0;
+    }
+    const rows = await args.db.all(`
+      SELECT path, lang, ext
+      FROM file
+      WHERE repo_id = ?
+        AND is_binary = FALSE
+        AND path LIKE ?
+      ORDER BY path
+      LIMIT ?
+    `, [args.repoId, `${dir}/%`, args.config.dirMaxFiles + 1]);
+    if (rows.length === 0 || rows.length > args.config.dirMaxFiles) {
+        return 0;
+    }
+    rows.sort((a, b) => hintNeighborRank(a.path) - hintNeighborRank(b.path));
+    let added = 0;
+    for (const row of rows) {
+        if (row.path === args.hintPath) {
+            continue;
+        }
+        if (!SAFE_PATH_PATTERN.test(row.path)) {
+            continue;
+        }
+        const candidate = ensureCandidate(args.candidates, row.path);
+        const reason = `artifact:hint_dir:${args.hintPath}:${row.path}`;
+        if (applyHintReasonBoost(candidate, reason, args.config.dirBoost, row.lang, row.ext)) {
+            added += 1;
+            const seedMeta = getHintSeedMeta(args.hintSeedMeta, args.hintPath);
+            await logHintExpansionEntry(args.db, args.tableAvailability, {
+                repoId: args.repoId,
+                hintValue: seedMeta?.sourceHint ?? args.hintPath,
+                kind: "directory",
+                targetPath: row.path,
+                payload: {
+                    origin: seedMeta?.origin ?? "artifact",
+                },
+            });
+            if (added >= limit) {
+                break;
+            }
+        }
+    }
+    return added;
+}
+async function addHintDependencyNeighbors(args, perHintRemaining) {
+    if (perHintRemaining <= 0) {
+        return 0;
+    }
+    let added = 0;
+    if (args.config.depOutLimit > 0) {
+        const outLimit = Math.min(args.config.depOutLimit, perHintRemaining - added);
+        if (outLimit > 0) {
+            added += await addHintDependencyDirection(args, outLimit, "out");
+        }
+    }
+    if (perHintRemaining - added <= 0) {
+        return added;
+    }
+    if (args.config.depInLimit > 0) {
+        const inLimit = Math.min(args.config.depInLimit, perHintRemaining - added);
+        if (inLimit > 0) {
+            added += await addHintDependencyDirection(args, inLimit, "in");
+        }
+    }
+    return added;
+}
+async function addHintDependencyDirection(args, limit, direction) {
+    if (limit <= 0) {
+        return 0;
+    }
+    if (!useHintDbBudget(args.state)) {
+        return 0;
+    }
+    const fetchLimit = Math.min(limit * 4, 25);
+    if (direction === "out") {
+        const rows = await args.db.all(`
+        SELECT dst
+        FROM dependency
+        WHERE repo_id = ?
+          AND src_path = ?
+          AND dst_kind = 'path'
+        LIMIT ?
+      `, [args.repoId, args.hintPath, fetchLimit]);
+        return await applyDependencyRows(args, rows.map((row) => row.dst), limit, direction);
+    }
+    const rows = await args.db.all(`
+      SELECT src_path
+      FROM dependency
+      WHERE repo_id = ?
+        AND dst = ?
+        AND dst_kind = 'path'
+      LIMIT ?
+    `, [args.repoId, args.hintPath, fetchLimit]);
+    return await applyDependencyRows(args, rows.map((row) => row.src_path), limit, direction);
+}
+async function applyDependencyRows(args, paths, limit, direction) {
+    if (paths.length === 0) {
+        return 0;
+    }
+    const uniquePaths = Array.from(new Set(paths)).filter((p) => p && SAFE_PATH_PATTERN.test(p));
+    uniquePaths.sort((a, b) => hintNeighborRank(a) - hintNeighborRank(b));
+    let added = 0;
+    for (const dependencyPath of uniquePaths) {
+        if (dependencyPath === args.hintPath) {
+            continue;
+        }
+        const candidate = ensureCandidate(args.candidates, dependencyPath);
+        const reason = `artifact:hint_dep_${direction}:${args.hintPath}:${dependencyPath}`;
+        if (applyHintReasonBoost(candidate, reason, args.config.depBoost)) {
+            added += 1;
+            const seedMeta = getHintSeedMeta(args.hintSeedMeta, args.hintPath);
+            await logHintExpansionEntry(args.db, args.tableAvailability, {
+                repoId: args.repoId,
+                hintValue: seedMeta?.sourceHint ?? args.hintPath,
+                kind: "dependency",
+                targetPath: dependencyPath,
+                payload: {
+                    origin: seedMeta?.origin ?? "artifact",
+                    direction,
+                },
+            });
+            if (added >= limit) {
+                break;
+            }
+        }
+    }
+    return added;
+}
+async function addHintSemanticNeighbors(args, limit) {
+    if (limit <= 0) {
+        return 0;
+    }
+    const dir = path.posix.dirname(args.hintPath);
+    if (!dir || dir === "." || dir === "/") {
+        return 0;
+    }
+    if (!useHintDbBudget(args.state)) {
+        return 0;
+    }
+    const rows = await args.db.all(`
+      SELECT path
+      FROM file
+      WHERE repo_id = ?
+        AND is_binary = FALSE
+        AND path LIKE ?
+      ORDER BY path
+      LIMIT ?
+    `, [args.repoId, `${dir}/%`, args.config.semDirCandidateLimit]);
+    const candidatePaths = rows.map((row) => row.path).filter((p) => p !== args.hintPath);
+    if (candidatePaths.length === 0) {
+        return 0;
+    }
+    if (!useHintDbBudget(args.state)) {
+        return 0;
+    }
+    const embeddingMap = await fetchEmbeddingMap(args.db, args.repoId, [
+        args.hintPath,
+        ...candidatePaths,
+    ]);
+    const hintEmbedding = embeddingMap.get(args.hintPath);
+    if (!hintEmbedding) {
+        return 0;
+    }
+    let added = 0;
+    for (const candidatePath of candidatePaths) {
+        if (!SAFE_PATH_PATTERN.test(candidatePath)) {
+            continue;
+        }
+        const embedding = embeddingMap.get(candidatePath);
+        if (!embedding) {
+            continue;
+        }
+        const similarity = structuralSimilarity(hintEmbedding, embedding);
+        if (!Number.isFinite(similarity) || similarity < args.config.semThreshold) {
+            continue;
+        }
+        const candidate = ensureCandidate(args.candidates, candidatePath);
+        const reason = `artifact:hint_sem:${args.hintPath}:${candidatePath}`;
+        if (applyHintReasonBoost(candidate, reason, args.weights.structural * similarity)) {
+            added += 1;
+            if (added >= limit) {
+                break;
+            }
+        }
+    }
+    return added;
+}
+function hintNeighborRank(filePath) {
+    if (filePath.startsWith("src/") || filePath.startsWith("external/assay-kit/src/")) {
+        return 0;
+    }
+    if (isTestLikePath(filePath)) {
+        return 2;
+    }
+    if (filePath.startsWith("docs/")) {
+        return 3;
+    }
+    return 1;
+}
+function isTestLikePath(filePath) {
+    return (/(^|\/)(tests?|__tests__|fixtures)\//.test(filePath) ||
+        filePath.endsWith(".spec.ts") ||
+        filePath.endsWith(".spec.tsx") ||
+        filePath.endsWith(".test.ts") ||
+        filePath.endsWith(".test.tsx"));
+}
 function parseEmbedding(vectorJson, vectorDims) {
-    if (!vectorJson || !vectorDims || vectorDims <= 0) {
+    const dims = vectorDims === null ? null : typeof vectorDims === "bigint" ? Number(vectorDims) : vectorDims;
+    if (!vectorJson || !dims || dims <= 0) {
         return null;
     }
     try {
@@ -528,7 +1188,7 @@ function parseEmbedding(vectorJson, vectorDims) {
             return null;
         }
         const values = [];
-        for (let i = 0; i < parsed.length && i < vectorDims; i += 1) {
+        for (let i = 0; i < parsed.length && i < dims; i += 1) {
             const raw = parsed[i];
             const num = typeof raw === "number" ? raw : Number(raw);
             if (!Number.isFinite(num)) {
@@ -536,7 +1196,7 @@ function parseEmbedding(vectorJson, vectorDims) {
             }
             values.push(num);
         }
-        return values.length === vectorDims ? values : null;
+        return values.length === dims ? values : null;
     }
     catch {
         return null;
@@ -630,18 +1290,6 @@ function buildSnippetPreview(content, startLine, endLine) {
     }
     return `${snippet.slice(0, 239)}…`;
 }
-function prependLineNumbers(snippet, startLine) {
-    const lines = snippet.split(/\r?\n/);
-    if (lines.length === 0) {
-        return snippet;
-    }
-    // Calculate required width from the last line number (dynamic sizing)
-    const endLine = startLine + lines.length - 1;
-    const width = String(endLine).length;
-    return lines
-        .map((line, index) => `${String(startLine + index).padStart(width, " ")}→${line}`)
-        .join("\n");
-}
 /**
  * トークン数を推定（コンテンツベース）
  * 実際のGPTトークナイザーを使用して正確にカウント
@@ -668,14 +1316,399 @@ function estimateTokensFromContent(content, startLine, endLine) {
     }
 }
 /**
- * 複数単語クエリを単語分割してOR検索条件を構築
- * @param query - 検索クエリ文字列
- * @returns 単語配列（2文字以下を除外）
+ * 複数単語クエリを単語分割してOR検索条件を構築
+ * @param query - 検索クエリ文字列
+ * @returns 単語配列（2文字以下を除外）
+ */
+function splitQueryWords(query) {
+    // 空白、スラッシュ、ハイフン、アンダースコアで分割
+    const words = query.split(/[\s/\-_]+/).filter((w) => w.length > 2);
+    return words.length > 0 ? words : [query]; // 全て除外された場合は元のクエリを使用
+}
+function normalizeMetadataFilterKey(rawKey) {
+    if (!rawKey) {
+        return null;
+    }
+    const normalized = rawKey.toLowerCase();
+    const alias = METADATA_ALIAS_MAP.get(normalized);
+    if (alias) {
+        return { ...alias };
+    }
+    for (const entry of METADATA_KEY_PREFIXES) {
+        if (normalized.startsWith(entry.prefix)) {
+            const remainder = normalized.slice(entry.prefix.length);
+            if (!remainder) {
+                return null;
+            }
+            return {
+                key: remainder,
+                source: entry.source,
+                ...(entry.strict !== undefined && { strict: entry.strict }),
+            };
+        }
+    }
+    return null;
+}
+function normalizeFilterValues(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed ? [trimmed] : [];
+    }
+    if (Array.isArray(value)) {
+        const values = [];
+        for (const item of value) {
+            if (typeof item === "string") {
+                const trimmed = item.trim();
+                if (trimmed) {
+                    values.push(trimmed);
+                }
+            }
+        }
+        return values;
+    }
+    return [];
+}
+function normalizeMetadataFiltersParam(input) {
+    if (!input || typeof input !== "object") {
+        return [];
+    }
+    const filters = [];
+    for (const [rawKey, rawValue] of Object.entries(input)) {
+        const normalizedKey = normalizeMetadataFilterKey(rawKey);
+        if (!normalizedKey) {
+            continue;
+        }
+        const values = normalizeFilterValues(rawValue);
+        if (values.length === 0) {
+            continue;
+        }
+        const filter = {
+            key: normalizedKey.key,
+            values,
+            source: normalizedKey.source,
+        };
+        if (normalizedKey.strict !== undefined) {
+            filter.strict = normalizedKey.strict;
+        }
+        filters.push(filter);
+    }
+    return filters;
+}
+function mergeMetadataFilters(filters) {
+    const merged = new Map();
+    for (const filter of filters) {
+        if (filter.values.length === 0)
+            continue;
+        const mapKey = `${filter.source ?? "*"}::${filter.key}::${filter.strict ? "strict" : "hint"}`;
+        const existing = merged.get(mapKey);
+        if (existing) {
+            const existingSet = new Set(existing.values.map((val) => val.toLowerCase()));
+            for (const value of filter.values) {
+                if (!existingSet.has(value.toLowerCase())) {
+                    existing.values.push(value);
+                    existingSet.add(value.toLowerCase());
+                }
+            }
+        }
+        else {
+            const entry = {
+                key: filter.key,
+                source: filter.source,
+                values: [...filter.values],
+            };
+            if (filter.strict !== undefined) {
+                entry.strict = filter.strict;
+            }
+            merged.set(mapKey, entry);
+        }
+    }
+    return Array.from(merged.values());
+}
+function parseInlineMetadataFilters(query) {
+    if (!query) {
+        return { cleanedQuery: "", filters: [] };
+    }
+    const matches = [];
+    const pattern = /(\b[\w.]+):("[^"]+"|'[^']+'|[^\s]+)/g;
+    let match;
+    while ((match = pattern.exec(query)) !== null) {
+        const normalizedKey = normalizeMetadataFilterKey(match[1] ?? "");
+        if (!normalizedKey) {
+            continue;
+        }
+        let rawValue = match[2] ?? "";
+        if ((rawValue.startsWith('"') && rawValue.endsWith('"')) ||
+            (rawValue.startsWith("'") && rawValue.endsWith("'"))) {
+            rawValue = rawValue.slice(1, -1);
+        }
+        const value = rawValue.trim();
+        if (!value) {
+            continue;
+        }
+        const filter = {
+            key: normalizedKey.key,
+            source: normalizedKey.source,
+            values: [value],
+        };
+        if (normalizedKey.strict !== undefined) {
+            filter.strict = normalizedKey.strict;
+        }
+        matches.push({
+            start: match.index,
+            end: pattern.lastIndex,
+            filter,
+        });
+    }
+    if (matches.length === 0) {
+        return { cleanedQuery: query.trim(), filters: [] };
+    }
+    let cleaned = "";
+    let lastIndex = 0;
+    for (const info of matches) {
+        cleaned += query.slice(lastIndex, info.start);
+        lastIndex = info.end;
+    }
+    cleaned += query.slice(lastIndex);
+    const normalizedQuery = cleaned.replace(/\s{2,}/g, " ").trim();
+    return {
+        cleanedQuery: normalizedQuery,
+        filters: mergeMetadataFilters(matches.map((m) => m.filter)),
+    };
+}
+function buildMetadataFilterConditions(filters, alias = "f") {
+    // SQL Injection対策: aliasをリテラル型で制限し、念のため検証
+    if (!["f", "mk"].includes(alias)) {
+        throw new Error(`Invalid SQL alias: ${alias}`);
+    }
+    const clauses = [];
+    for (const filter of filters) {
+        if (!filter.key || filter.values.length === 0) {
+            continue;
+        }
+        const likeClauses = filter.values.map(() => "mk.value ILIKE ?").join(" OR ");
+        const whereParts = [`mk.repo_id = ${alias}.repo_id`, `mk.path = ${alias}.path`];
+        const params = [];
+        if (filter.source) {
+            whereParts.push("mk.source = ?");
+            params.push(filter.source);
+        }
+        whereParts.push("mk.key = ?");
+        params.push(filter.key);
+        whereParts.push(`(${likeClauses})`);
+        params.push(...filter.values.map((value) => `%${value}%`));
+        const sql = `EXISTS (SELECT 1 FROM document_metadata_kv mk WHERE ${whereParts.join(" AND ")})`;
+        clauses.push({ sql, params });
+    }
+    return clauses;
+}
+function isTableMissingError(error, table) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return error.message.includes(`Table with name ${table}`) || error.message.includes(table);
+}
+async function safeMetadataQuery(db, tableAvailability, sql, params) {
+    if (!tableAvailability.hasMetadataTables) {
+        return [];
+    }
+    try {
+        return await db.all(sql, params);
+    }
+    catch (error) {
+        if (isTableMissingError(error, "document_metadata_kv")) {
+            console.warn("Metadata tables not found; disabling metadata filters and boosts until database is upgraded.");
+            return [];
+        }
+        throw error;
+    }
+}
+async function safeLinkQuery(db, tableAvailability, sql, params) {
+    if (!tableAvailability.hasLinkTable) {
+        return [];
+    }
+    try {
+        return await db.all(sql, params);
+    }
+    catch (error) {
+        if (isTableMissingError(error, "markdown_link")) {
+            console.warn("Markdown link table not found; inbound link boosting disabled until database is upgraded.");
+            return [];
+        }
+        throw error;
+    }
+}
+async function fetchMetadataOnlyCandidates(db, tableAvailability, repoId, filters, limit) {
+    if (!tableAvailability.hasMetadataTables || filters.length === 0 || limit <= 0) {
+        return [];
+    }
+    const filterClauses = buildMetadataFilterConditions(filters);
+    const whereClauses = ["f.repo_id = ?"];
+    const params = [repoId];
+    for (const clause of filterClauses) {
+        whereClauses.push(clause.sql);
+        params.push(...clause.params);
+    }
+    const sql = `
+    SELECT f.path, f.lang, f.ext, b.content
+    FROM file f
+    JOIN blob b ON b.hash = f.blob_hash
+    WHERE ${whereClauses.join(" AND ")}
+    ORDER BY f.path
+    LIMIT ?
+  `;
+    params.push(limit);
+    try {
+        return await db.all(sql, params);
+    }
+    catch (error) {
+        if (isTableMissingError(error, "document_metadata_kv")) {
+            console.warn("Metadata tables not found; disabling metadata-only searches until database is upgraded.");
+            return [];
+        }
+        throw error;
+    }
+}
+async function fetchMetadataKeywordMatches(db, tableAvailability, repoId, keywords, filters, limit, excludePaths) {
+    if (!tableAvailability.hasMetadataTables || keywords.length === 0 || limit <= 0) {
+        return [];
+    }
+    const keywordClauses = keywords.map(() => "mk.value ILIKE ?").join(" OR ");
+    const params = [repoId, ...keywords.map((kw) => `%${kw}%`)];
+    const whereClauses = ["mk.repo_id = ?", `(${keywordClauses})`];
+    if (excludePaths.size > 0) {
+        const placeholders = Array.from(excludePaths)
+            .map(() => "?")
+            .join(", ");
+        whereClauses.push(`f.path NOT IN (${placeholders})`);
+        params.push(...excludePaths);
+    }
+    const filterClauses = buildMetadataFilterConditions(filters, "f");
+    for (const clause of filterClauses) {
+        whereClauses.push(clause.sql);
+        params.push(...clause.params);
+    }
+    params.push(limit);
+    const sql = `
+    SELECT f.path, f.lang, f.ext, b.content, COUNT(*) AS score
+    FROM document_metadata_kv mk
+    JOIN file f ON f.repo_id = mk.repo_id AND f.path = mk.path
+    JOIN blob b ON b.hash = f.blob_hash
+    WHERE ${whereClauses.join(" AND ")}
+    GROUP BY f.path, f.lang, f.ext, b.content
+    ORDER BY score DESC, f.path
+    LIMIT ?
+  `;
+    const rows = await safeMetadataQuery(db, tableAvailability, sql, params);
+    return rows.map((row) => ({ ...row, score: Number(row.score ?? 1) }));
+}
+async function loadMetadataForPaths(db, tableAvailability, repoId, paths) {
+    const result = new Map();
+    if (!tableAvailability.hasMetadataTables || paths.length === 0) {
+        return result;
+    }
+    const placeholders = paths.map(() => "?").join(", ");
+    const sql = `
+    SELECT path, key, value, source
+    FROM document_metadata_kv
+    WHERE repo_id = ? AND path IN (${placeholders})
+  `;
+    const rows = await safeMetadataQuery(db, tableAvailability, sql, [repoId, ...paths]);
+    for (const row of rows) {
+        if (!result.has(row.path)) {
+            result.set(row.path, []);
+        }
+        result.get(row.path).push({
+            key: row.key,
+            value: row.value,
+            source: row.source ?? undefined,
+        });
+    }
+    return result;
+}
+async function loadInboundLinkCounts(db, tableAvailability, repoId, paths) {
+    const counts = new Map();
+    if (!tableAvailability.hasLinkTable || paths.length === 0) {
+        return counts;
+    }
+    const placeholders = paths.map(() => "?").join(", ");
+    const sql = `
+    SELECT resolved_path AS path, COUNT(*) AS inbound
+    FROM markdown_link
+    WHERE repo_id = ? AND resolved_path IS NOT NULL AND resolved_path IN (${placeholders})
+    GROUP BY resolved_path
+  `;
+    const rows = await safeLinkQuery(db, tableAvailability, sql, [repoId, ...paths]);
+    for (const row of rows) {
+        const inboundValue = typeof row.inbound === "bigint" ? Number(row.inbound) : Number(row.inbound ?? 0);
+        counts.set(row.path, inboundValue);
+    }
+    return counts;
+}
+function computeMetadataBoost(entries, keywordSet, filterValueSet) {
+    if (!entries || entries.length === 0) {
+        return 0;
+    }
+    let boost = 0;
+    for (const entry of entries) {
+        const valueLower = entry.value.toLowerCase();
+        for (const keyword of keywordSet) {
+            if (valueLower.includes(keyword)) {
+                boost += METADATA_MATCH_WEIGHT;
+                break;
+            }
+        }
+        if (filterValueSet.has(valueLower)) {
+            boost += METADATA_FILTER_MATCH_WEIGHT;
+        }
+    }
+    return Math.min(boost, 1.5);
+}
+function computeInboundLinkBoost(count) {
+    let numericCount = count;
+    if (typeof numericCount === "bigint") {
+        numericCount = Number(numericCount);
+    }
+    if (!numericCount || numericCount <= 0) {
+        return 0;
+    }
+    return Math.min(Math.log1p(numericCount) * INBOUND_LINK_WEIGHT, 1.0);
+}
+function candidateMatchesMetadataFilters(entries, filters) {
+    if (filters.length === 0) {
+        return true;
+    }
+    if (!entries || entries.length === 0) {
+        return false;
+    }
+    return filters.every((filter) => {
+        const expectedValues = filter.values.map((value) => value.toLowerCase());
+        return entries.some((entry) => {
+            if (entry.key !== filter.key) {
+                return false;
+            }
+            if (filter.source && entry.source !== filter.source) {
+                return false;
+            }
+            const lowerValue = entry.value.toLowerCase();
+            return expectedValues.some((value) => lowerValue.includes(value));
+        });
+    });
+}
+/**
+ * パス固有のマルチプライヤーを取得（最長プレフィックスマッチ）
+ * 配列の順序に依存せず、常に最長一致のプレフィックスを選択
+ * @param filePath - ファイルパス
+ * @param profileConfig - ブーストプロファイル設定
+ * @returns パス固有のマルチプライヤー（マッチなしの場合は1.0）
  */
-function splitQueryWords(query) {
-    // 空白、スラッシュ、ハイフン、アンダースコアで分割
-    const words = query.split(/[\s/\-_]+/).filter((w) => w.length > 2);
-    return words.length > 0 ? words : [query]; // 全て除外された場合は元のクエリを使用
+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+: 設定可能な乗算的ペナルティ）
@@ -686,7 +1719,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,63 +1732,45 @@ 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
+            // v1.0.0: Use multiplicative penalty instead of absolute -100
+            return baseScore * weights.blacklistPenaltyMultiplier;
         }
     }
-    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)
+    // Test files: multiplicative penalty (v1.0.0)
     if (path.startsWith("tests/") || path.startsWith("test/")) {
-        return baseScore * 0.2; // Strong penalty for tests
+        return baseScore * weights.testPenaltyMultiplier;
     }
     return baseScore * multiplier;
 }
@@ -767,49 +1782,115 @@ 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
+                }
+            }
         }
     }
 }
 /**
- * 加算的ファイルペナルティを適用
- * ブラックリストディレクトリ、テストファイル、lockファイル、設定ファイル、マイグレーションファイルに強いペナルティ
- * @param profile - boost_profile設定（"docs"の場合はdocs/ディレクトリのブラックリストをスキップ）
- * @returns true if penalty was applied and processing should stop
+ * 乗算的ファイルペナルティを適用（v1.0.0+）
+ * ブラックリストディレクトリ、テストファイル、lockファイルに乗算ペナルティ
+ * v1.0.0: 絶対ペナルティ(-100)から乗算ペナルティ(×0.01など)に移行
+ * @param weights - スコアリングウェイト設定（乗算ペナルティ係数を含む）
+ * @param profile - boost_profile設定（denylistOverridesなど）
+ * @returns true if severe penalty was applied (caller should skip further boosts)
  */
-function applyAdditiveFilePenalties(candidate, path, lowerPath, fileName, profile) {
-    // Blacklisted directories - effectively remove
+function applyMultiplicativeFilePenalties(candidate, path, lowerPath, fileName, weights, profileConfig) {
+    // Returns true if a severe penalty was applied (should skip further boosts)
+    // Blacklisted directories - apply strong multiplicative penalty (99% reduction)
+    // v1.0.0: test/ and tests/ removed - handled by testPenaltyMultiplier instead
     const blacklistedDirs = [
         ".cursor/",
         ".devcontainer/",
         ".serena/",
         "__mocks__/",
         "docs/",
-        "test/",
-        "tests/",
         ".git/",
+        ".github/",
         "node_modules/",
         "db/migrate/",
         "db/migrations/",
@@ -825,24 +1906,30 @@ 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;
+            // v1.0.0: Use multiplicative penalty instead of absolute -100
+            candidate.scoreMultiplier *= weights.blacklistPenaltyMultiplier;
             candidate.reasons.add("penalty:blacklisted-dir");
-            return true;
+            return true; // Signal to skip further boosts - this is the strongest penalty
         }
     }
-    // Test files - strong penalty
+    if (isSuppressedPath(path)) {
+        // v1.0.0: Use multiplicative penalty instead of absolute -100
+        candidate.scoreMultiplier *= weights.blacklistPenaltyMultiplier;
+        candidate.reasons.add("penalty:suppressed");
+        return true; // Signal to skip further boosts
+    }
+    // Test files - strong multiplicative penalty (95% reduction)
     const testPatterns = [".spec.ts", ".spec.js", ".test.ts", ".test.js", ".spec.tsx", ".test.tsx"];
     if (testPatterns.some((pattern) => lowerPath.endsWith(pattern))) {
-        candidate.score -= 2.0;
+        candidate.scoreMultiplier *= weights.testPenaltyMultiplier;
         candidate.reasons.add("penalty:test-file");
-        return true;
+        return true; // Signal to skip further boosts
     }
-    // Lock files - very strong penalty
+    // Lock files - very strong multiplicative penalty (99% reduction)
     const lockFiles = [
         "package-lock.json",
         "pnpm-lock.yaml",
@@ -853,231 +1940,299 @@ function applyAdditiveFilePenalties(candidate, path, lowerPath, fileName, profil
         "poetry.lock",
     ];
     if (lockFiles.some((lockFile) => fileName === lockFile)) {
-        candidate.score -= 3.0;
+        candidate.scoreMultiplier *= weights.lockPenaltyMultiplier;
         candidate.reasons.add("penalty:lock-file");
-        return true;
-    }
-    // Configuration files - strong penalty
-    const configPatterns = [
-        ".config.js",
-        ".config.ts",
-        ".config.mjs",
-        ".config.cjs",
-        "tsconfig.json",
-        "jsconfig.json",
-        "package.json",
-        ".eslintrc",
-        ".prettierrc",
-        "jest.config",
-        "vite.config",
-        "vitest.config",
-        "webpack.config",
-        "rollup.config",
-    ];
-    if (configPatterns.some((pattern) => lowerPath.endsWith(pattern) || fileName.startsWith(".env")) ||
-        fileName === "Dockerfile" ||
-        fileName === "docker-compose.yml" ||
-        fileName === "docker-compose.yaml") {
-        candidate.score -= 1.5;
-        candidate.reasons.add("penalty:config-file");
-        return true;
-    }
-    // Migration files - strong penalty
-    if (lowerPath.includes("migrate") || lowerPath.includes("migration")) {
-        candidate.score -= 2.0;
-        candidate.reasons.add("penalty:migration-file");
-        return true;
+        return true; // Signal to skip further boosts
     }
-    return false; // No penalty applied, continue processing
+    // v1.0.0: No penalty applied, allow further boosts/penalties
+    return false;
 }
 /**
  * ファイルタイプ別の乗算的ペナルティ/ブーストを適用（v0.7.0+）
  * 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() ?? "";
+    const lowerPath = path.toLowerCase();
+    // ✅ Step 1: Low-value files (v1.0.0: syntax/perf/legal/migration)
+    // Apply configPenaltyMultiplier (strong penalty) to rarely useful file types
+    const isSyntaxGrammar = path.includes("/syntaxes/") &&
+        (lowerPath.endsWith(".tmlanguage") ||
+            lowerPath.endsWith(".tmlanguage.json") ||
+            lowerPath.endsWith(".tmtheme") ||
+            lowerPath.endsWith(".plist"));
+    const isPerfData = lowerPath.includes(".perf.data") ||
+        lowerPath.includes(".perf-data") ||
+        lowerPath.includes("-perf-data");
+    const isLegalFile = fileName.toLowerCase().includes("thirdpartynotices") ||
+        fileName.toLowerCase() === "cgmanifest.json";
+    const isMigrationFile = lowerPath.includes("migrate") || lowerPath.includes("migration");
+    if (isSyntaxGrammar || isPerfData || isLegalFile || isMigrationFile) {
+        candidate.scoreMultiplier *= weights.configPenaltyMultiplier;
+        candidate.reasons.add("penalty:low-value-file");
+        return; // Don't apply impl boosts
+    }
+    // ✅ Step 2: 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 3: 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 4: 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");
         }
     }
 }
 /**
- * contextBundle専用のブーストプロファイル適用（v0.7.0+: リファクタリング版）
+ * contextBundle専用のブーストプロファイル適用（v1.0.0: 乗算ペナルティモデル）
  * 複雑度を削減するために3つのヘルパー関数に分割：
  * 1. applyPathBasedScoring: パスベースの加算的スコアリング
- * 2. applyAdditiveFilePenalties: 強力な加算的ペナルティ
- * 3. applyFileTypeMultipliers: 乗算的ペナルティ/ブースト
+ * 2. applyMultiplicativeFilePenalties: 乗算的ペナルティ（blacklist/test/lock）
+ * 3. applyFileTypeMultipliers: 乗算的ペナルティ/ブースト（doc/config/impl）
+ *
+ * v1.0.0 CHANGES:
+ * - 絶対ペナルティ(-100)を乗算ペナルティ(×0.01など)に置き換え
+ * - すべてのペナルティが組み合わせ可能に（boost_profileとの相互作用が予測可能）
+ * - v0.9.0の特別ケース処理（if profile === "docs"）が不要に
  *
- * CRITICAL SAFETY RULES:
- * 1. Multipliers are stored in candidate.scoreMultiplier, applied AFTER all additive scoring
- * 2. profile="docs" skips documentation penalties (allows doc-focused queries)
- * 3. Blacklist/test/lock/config files keep additive penalties (already very strong)
+ * SCORING PHASES:
+ * 1. Additive phase: テキストマッチ、パスマッチ、依存関係、近接性を加算
+ * 2. Multiplicative phase: ペナルティとブーストを scoreMultiplier に蓄積
+ * 3. Final application: score *= scoreMultiplier（最終段階で一度だけ適用）
  */
-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);
-    if (shouldStop) {
-        return; // ペナルティが適用された場合は処理終了
-    }
+    // Step 2: 乗算的ペナルティ（ブラックリスト、テスト、lock）
+    // v1.0.0: Returns true if severe penalty applied (should skip further boosts)
+    const skipFurtherBoosts = applyMultiplicativeFilePenalties(candidate, path, lowerPath, fileName, weights, profileConfig);
     // Step 3: ファイルタイプ別の乗算的ペナルティ/ブースト
-    applyFileTypeMultipliers(candidate, path, ext, profile, weights);
+    // Skip if severe penalty was applied (blacklist/test/lock files shouldn't get impl boosts)
+    if (!skipFurtherBoosts) {
+        applyFileTypeMultipliers(candidate, path, ext, profileConfig, weights);
+    }
 }
 export async function filesSearch(context, params) {
     const { db, repoId } = context;
-    const { query } = params;
-    if (!query || query.trim().length === 0) {
-        throw new Error("files_search requires a non-empty query. Provide a search keyword to continue.");
+    const rawQuery = params.query ?? "";
+    const inlineMetadata = parseInlineMetadataFilters(rawQuery);
+    const paramFilters = normalizeMetadataFiltersParam(params.metadata_filters);
+    const metadataFilters = mergeMetadataFilters([...inlineMetadata.filters, ...paramFilters]);
+    const strictMetadataFilters = metadataFilters.filter((filter) => filter.strict);
+    const hintMetadataFilters = metadataFilters.filter((filter) => !filter.strict);
+    const hasStrictMetadataFilters = strictMetadataFilters.length > 0;
+    const hasHintMetadataFilters = hintMetadataFilters.length > 0;
+    const hasAnyMetadataFilters = metadataFilters.length > 0;
+    let cleanedQuery = inlineMetadata.cleanedQuery;
+    let hasTextQuery = cleanedQuery.length > 0;
+    if (!hasTextQuery && hasHintMetadataFilters) {
+        cleanedQuery = hintMetadataFilters
+            .flatMap((filter) => filter.values)
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0)
+            .join(" ");
+        cleanedQuery = cleanedQuery.trim();
+        hasTextQuery = cleanedQuery.length > 0;
+    }
+    const metadataValueSeed = metadataFilters
+        .flatMap((filter) => filter.values)
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0)
+        .join(" ");
+    if (metadataValueSeed.length > 0) {
+        cleanedQuery = `${cleanedQuery} ${metadataValueSeed}`.trim();
+        hasTextQuery = cleanedQuery.length > 0;
+    }
+    if (!hasTextQuery && !hasAnyMetadataFilters) {
+        throw new Error("files_search requires a query or metadata_filters. Provide keywords or structured filters to continue.");
     }
     const limit = normalizeLimit(params.limit);
     const ftsStatus = await getFreshFtsStatus(context);
     const hasFTS = ftsStatus.ready;
-    let sql;
-    let values;
-    if (hasFTS) {
-        // FTS拡張利用可能: fts_main_blob.match_bm25 を使用
-        const conditions = ["f.repo_id = ?"];
-        values = [repoId];
-        // 言語・拡張子フィルタ
-        if (params.lang) {
-            conditions.push("COALESCE(f.lang, '') = ?");
-            values.push(params.lang);
-        }
-        if (params.ext) {
-            conditions.push("COALESCE(f.ext, '') = ?");
-            values.push(params.ext);
-        }
-        if (params.path_prefix) {
-            conditions.push("f.path LIKE ?");
-            values.push(`${params.path_prefix}%`);
-        }
-        // FTS検索（BM25スコアリング）
-        sql = `
-      SELECT f.path, f.lang, f.ext, b.content, fts.score
-      FROM file f
-      JOIN blob b ON b.hash = f.blob_hash
-      JOIN (
-        SELECT hash, fts_main_blob.match_bm25(hash, ?) AS score
-        FROM blob
-        WHERE score IS NOT NULL
-      ) fts ON fts.hash = b.hash
-      WHERE ${conditions.join(" AND ")}
-      ORDER BY fts.score DESC
-      LIMIT ?
-    `;
-        values.unshift(query); // FTSクエリを先頭に追加
-        values.push(limit);
-    }
-    else {
-        // FTS拡張利用不可: ILIKE検索（Phase 1の単語分割ロジック）
-        const conditions = ["f.repo_id = ?", "b.content IS NOT NULL"];
-        values = [repoId];
-        const words = splitQueryWords(query);
-        if (words.length === 1) {
-            conditions.push("b.content ILIKE '%' || ? || '%'");
-            values.push(query);
+    const metadataClauses = buildMetadataFilterConditions(strictMetadataFilters);
+    const candidateRows = [];
+    if (hasTextQuery) {
+        let sql;
+        let values;
+        if (hasFTS) {
+            const conditions = ["f.repo_id = ?"];
+            values = [repoId];
+            if (params.lang) {
+                conditions.push("COALESCE(f.lang, '') = ?");
+                values.push(params.lang);
+            }
+            if (params.ext) {
+                conditions.push("COALESCE(f.ext, '') = ?");
+                values.push(params.ext);
+            }
+            if (params.path_prefix) {
+                conditions.push("f.path LIKE ?");
+                values.push(`${params.path_prefix}%`);
+            }
+            for (const clause of metadataClauses) {
+                conditions.push(clause.sql);
+                values.push(...clause.params);
+            }
+            sql = `
+        SELECT f.path, f.lang, f.ext, b.content, fts.score
+        FROM file f
+        JOIN blob b ON b.hash = f.blob_hash
+        JOIN (
+          SELECT hash, fts_main_blob.match_bm25(hash, ?) AS score
+          FROM blob
+          WHERE score IS NOT NULL
+        ) fts ON fts.hash = b.hash
+        WHERE ${conditions.join(" AND ")}
+        ORDER BY fts.score DESC
+        LIMIT ?
+      `;
+            values.unshift(cleanedQuery);
+            values.push(limit);
         }
         else {
-            const wordConditions = words.map(() => "b.content ILIKE '%' || ? || '%'");
-            conditions.push(`(${wordConditions.join(" OR ")})`);
-            values.push(...words);
-        }
-        if (params.lang) {
-            conditions.push("COALESCE(f.lang, '') = ?");
-            values.push(params.lang);
-        }
-        if (params.ext) {
-            conditions.push("COALESCE(f.ext, '') = ?");
-            values.push(params.ext);
-        }
-        if (params.path_prefix) {
-            conditions.push("f.path LIKE ?");
-            values.push(`${params.path_prefix}%`);
-        }
-        sql = `
-      SELECT f.path, f.lang, f.ext, b.content
-      FROM file f
-      JOIN blob b ON b.hash = f.blob_hash
-      WHERE ${conditions.join(" AND ")}
-      ORDER BY f.path
-      LIMIT ?
-    `;
-        values.push(limit);
-    }
-    const rows = await db.all(sql, values);
-    const boostProfile = params.boost_profile ?? "default";
-    // ✅ v0.7.0+: Load configurable scoring weights for unified boosting logic
-    // Note: filesSearch doesn't have a separate profile parameter, uses default weights
+            const conditions = ["f.repo_id = ?", "b.content IS NOT NULL"];
+            values = [repoId];
+            const words = splitQueryWords(cleanedQuery);
+            if (words.length === 1) {
+                conditions.push("b.content ILIKE '%' || ? || '%'");
+                values.push(cleanedQuery);
+            }
+            else {
+                const wordConditions = words.map(() => "b.content ILIKE '%' || ? || '%'");
+                conditions.push(`(${wordConditions.join(" OR ")})`);
+                values.push(...words);
+            }
+            if (params.lang) {
+                conditions.push("COALESCE(f.lang, '') = ?");
+                values.push(params.lang);
+            }
+            if (params.ext) {
+                conditions.push("COALESCE(f.ext, '') = ?");
+                values.push(params.ext);
+            }
+            if (params.path_prefix) {
+                conditions.push("f.path LIKE ?");
+                values.push(`${params.path_prefix}%`);
+            }
+            for (const clause of metadataClauses) {
+                conditions.push(clause.sql);
+                values.push(...clause.params);
+            }
+            sql = `
+        SELECT f.path, f.lang, f.ext, b.content
+        FROM file f
+        JOIN blob b ON b.hash = f.blob_hash
+        WHERE ${conditions.join(" AND ")}
+        ORDER BY f.path
+        LIMIT ?
+      `;
+            values.push(limit);
+        }
+        const textRows = await db.all(sql, values);
+        candidateRows.push(...textRows);
+    }
+    if (!hasTextQuery && hasAnyMetadataFilters) {
+        const metadataOnlyRows = await fetchMetadataOnlyCandidates(db, context.tableAvailability, repoId, metadataFilters, limit * 2);
+        for (const row of metadataOnlyRows) {
+            row.score = 1 + metadataFilters.length * 0.2;
+        }
+        candidateRows.push(...metadataOnlyRows);
+    }
+    if (hasTextQuery) {
+        const metadataKeywords = splitQueryWords(cleanedQuery.toLowerCase()).map((kw) => kw.toLowerCase());
+        if (metadataKeywords.length > 0) {
+            const excludePaths = new Set(candidateRows.map((row) => row.path));
+            const metadataRows = await fetchMetadataKeywordMatches(db, context.tableAvailability, repoId, metadataKeywords, metadataFilters, limit * 2, excludePaths);
+            candidateRows.push(...metadataRows);
+        }
+    }
+    if (candidateRows.length === 0) {
+        return [];
+    }
+    const rowMap = new Map();
+    for (const row of candidateRows) {
+        const base = row.score ?? (hasTextQuery ? 1.0 : 0.8);
+        const existing = rowMap.get(row.path);
+        const existingScore = existing?.score ?? (hasTextQuery ? 1.0 : 0.8);
+        if (!existing || base > existingScore) {
+            rowMap.set(row.path, { ...row, score: base });
+        }
+    }
+    const dedupedRows = Array.from(rowMap.values()).sort((a, b) => (b.score ?? 1) - (a.score ?? 1));
+    const limitedRows = dedupedRows.slice(0, limit);
+    const paths = limitedRows.map((row) => row.path);
+    const metadataMap = await loadMetadataForPaths(db, context.tableAvailability, repoId, paths);
+    const inboundCounts = await loadInboundLinkCounts(db, context.tableAvailability, repoId, paths);
+    const metadataKeywordSet = hasTextQuery
+        ? new Set(splitQueryWords(cleanedQuery.toLowerCase()).map((kw) => kw.toLowerCase()))
+        : new Set();
+    const filterValueSet = new Set(metadataFilters.flatMap((filter) => filter.values.map((value) => value.toLowerCase())));
+    const boostProfile = params.boost_profile ??
+        (hasHintMetadataFilters ? "balanced" : hasStrictMetadataFilters ? "docs" : "default");
+    const profileConfig = getBoostProfile(boostProfile);
     const weights = loadScoringProfile(null);
     const options = parseOutputOptions(params);
-    return rows
+    const previewQuery = hasTextQuery
+        ? cleanedQuery
+        : (metadataFilters[0]?.values[0] ?? rawQuery.trim());
+    return limitedRows
         .map((row) => {
         let preview;
         let matchLine;
+        const previewSource = previewQuery || row.path;
         if (options.includePreview) {
-            // Full preview generation for non-compact mode
-            const previewData = buildPreview(row.content ?? "", query);
+            const previewData = buildPreview(row.content ?? "", previewSource);
             preview = previewData.preview;
             matchLine = previewData.line;
         }
         else {
-            // Lightweight: extract only line number without preview
-            matchLine = findFirstMatchLine(row.content ?? "", query);
-        }
-        const baseScore = row.score ?? 1.0; // FTS時はBM25スコア、ILIKE時は1.0
-        const boostedScore = applyFileTypeBoost(row.path, baseScore, boostProfile, weights);
+            matchLine = findFirstMatchLine(row.content ?? "", previewSource);
+        }
+        const metadataEntries = metadataMap.get(row.path);
+        const metadataBoost = computeMetadataBoost(metadataEntries, metadataKeywordSet, filterValueSet);
+        const inboundBoost = computeInboundLinkBoost(inboundCounts.get(row.path));
+        const baseScore = (row.score ?? (hasTextQuery ? 1.0 : 0.8)) + metadataBoost + inboundBoost;
+        const boostedScore = boostProfile === "none"
+            ? baseScore
+            : applyFileTypeBoost(row.path, baseScore, profileConfig, weights);
         const result = {
             path: row.path,
             matchLine,
@@ -1090,102 +2245,310 @@ export async function filesSearch(context, params) {
         }
         return result;
     })
-        .sort((a, b) => b.score - a.score); // スコアの高い順に再ソート
+        .filter((result) => result.score > SCORE_FILTER_THRESHOLD) // v1.0.0: Filter out extremely low-scored files (multiplicative penalties)
+        .sort((a, b) => b.score - a.score);
 }
-export async function snippetsGet(context, params) {
-    const { db, repoId } = context;
-    if (!params.path) {
-        throw new Error("snippets_get requires a file path. Specify a tracked text file path to continue.");
-    }
-    const rows = await db.all(`
-      SELECT f.path, f.lang, f.ext, f.is_binary, b.content
-      FROM file f
-      JOIN blob b ON b.hash = f.blob_hash
-      WHERE f.repo_id = ? AND f.path = ?
-      LIMIT 1
-    `, [repoId, params.path]);
-    if (rows.length === 0) {
-        throw new Error("Requested snippet file was not indexed. Re-run the indexer or choose another path.");
+// snippetsGet has been extracted to ./handlers/snippets-get.ts and re-exported above
+// ============================================================================
+// Issue #68: Path/Large File Penalty Helper Functions
+// ============================================================================
+/**
+ * v1.0.0: Score filtering threshold for multiplicative penalty model
+ * Files with score < threshold are filtered out (unless they are hint paths)
+ * Default: 0.05 removes files with >95% penalty while keeping relevant files
+ * Can be overridden via KIRI_SCORE_THRESHOLD environment variable
+ */
+const SCORE_FILTER_THRESHOLD = parseFloat(process.env.KIRI_SCORE_THRESHOLD ?? "0.05");
+/**
+ * 環境変数からペナルティ機能フラグを読み取る
+ */
+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,
+        });
     }
-    const row = rows[0];
-    if (!row) {
-        throw new Error("Requested snippet file was not indexed. Re-run the indexer or choose another path.");
-    }
-    if (row.is_binary) {
-        throw new Error("Binary snippets are not supported. Choose a text file to preview its content.");
-    }
-    if (row.content === null) {
-        throw new Error("Snippet content is unavailable. Re-run the indexer to refresh DuckDB state.");
-    }
-    const lines = row.content.split(/\r?\n/);
-    const totalLines = lines.length;
-    const snippetRows = await db.all(`
-      SELECT s.snippet_id, s.start_line, s.end_line, s.symbol_id, sym.name AS symbol_name, sym.kind AS symbol_kind
-      FROM snippet s
-      LEFT JOIN symbol sym
-        ON sym.repo_id = s.repo_id
-       AND sym.path = s.path
-       AND sym.symbol_id = s.symbol_id
-      WHERE s.repo_id = ? AND s.path = ?
-      ORDER BY s.start_line
-    `, [repoId, params.path]);
-    const requestedStart = params.start_line ?? 1;
-    const requestedEnd = params.end_line ?? Math.min(totalLines, requestedStart + DEFAULT_SNIPPET_WINDOW - 1);
-    const useSymbolSnippets = snippetRows.length > 0 && params.end_line === undefined;
-    let snippetSelection = null;
-    if (useSymbolSnippets) {
-        snippetSelection =
-            snippetRows.find((snippet) => requestedStart >= snippet.start_line && requestedStart <= snippet.end_line) ?? null;
-        if (!snippetSelection) {
-            const firstSnippet = snippetRows[0];
-            if (firstSnippet && requestedStart < firstSnippet.start_line) {
-                snippetSelection = firstSnippet;
-            }
-            else {
-                snippetSelection = snippetRows[snippetRows.length - 1] ?? null;
-            }
-        }
+}
+/**
+ * 段階的ペナルティを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",
+        });
     }
-    let startLine;
-    let endLine;
-    let symbolName = null;
-    let symbolKind = null;
-    if (snippetSelection) {
-        startLine = snippetSelection.start_line;
-        endLine = snippetSelection.end_line;
-        symbolName = snippetSelection.symbol_name;
-        symbolKind = snippetSelection.symbol_kind;
+}
+/**
+ * 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,
+        });
     }
-    else {
-        startLine = Math.max(1, Math.min(totalLines, requestedStart));
-        endLine = Math.max(startLine, Math.min(totalLines, requestedEnd));
+}
+/**
+ * ペナルティイベントを記録（テレメトリ用）
+ */
+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++;
     }
-    const isCompact = params.compact === true;
-    const addLineNumbers = params.includeLineNumbers === true && !isCompact;
-    let content;
-    if (!isCompact) {
-        const snippetContent = lines.slice(startLine - 1, endLine).join("\n");
-        content = addLineNumbers ? prependLineNumbers(snippetContent, startLine) : snippetContent;
+    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 {
-        path: row.path,
-        startLine,
-        endLine,
-        ...(content !== undefined && { content }),
-        totalLines,
-        symbolName,
-        symbolKind,
+        pathMissPenalties,
+        largeFilePenalties,
+        totalCandidates: candidates.length,
+        pathMatchDistribution: computePathMatchDistribution(candidates),
+        scoreStats: computeScoreStats(candidates),
     };
 }
-export async function contextBundle(context, params) {
+/**
+ * テレメトリーをファイル出力（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
+}
+async function contextBundleImpl(context, params) {
     context.warningManager.startRequest();
     const { db, repoId } = context;
-    const goal = params.goal?.trim() ?? "";
-    if (goal.length === 0) {
+    const rawGoal = params.goal?.trim() ?? "";
+    if (rawGoal.length === 0) {
         throw new Error("context_bundle requires a non-empty goal. Describe your objective to receive context.");
     }
+    if (process.env.KIRI_TRACE_METADATA === "1") {
+        console.info(`[metadata-trace-env] goal=${rawGoal}`);
+    }
+    const inlineMetadata = parseInlineMetadataFilters(rawGoal);
+    const paramFilters = normalizeMetadataFiltersParam(params.metadata_filters);
+    const metadataFilters = mergeMetadataFilters([...inlineMetadata.filters, ...paramFilters]);
+    const strictMetadataFilters = metadataFilters.filter((filter) => filter.strict);
+    const hintMetadataFilters = metadataFilters.filter((filter) => !filter.strict);
+    const hasStrictMetadataFilters = strictMetadataFilters.length > 0;
+    const hasHintMetadataFilters = hintMetadataFilters.length > 0;
+    const hasAnyMetadataFilters = metadataFilters.length > 0;
+    const goal = inlineMetadata.cleanedQuery.length > 0 ? inlineMetadata.cleanedQuery : rawGoal;
+    if (process.env.KIRI_TRACE_METADATA === "1") {
+        console.info("[metadata-trace]", JSON.stringify({
+            rawGoal,
+            cleanedGoal: goal,
+            inlineFilters: inlineMetadata.filters,
+            paramFilters,
+            mergedFilters: metadataFilters,
+        }));
+    }
     const limit = normalizeBundleLimit(params.limit);
     const artifacts = params.artifacts ?? {};
+    const artifactHints = normalizeArtifactHints(artifacts.hints);
+    const hintBuckets = bucketArtifactHints(artifactHints);
+    const artifactPathHints = hintBuckets.pathHints;
+    const substringHints = hintBuckets.substringHints;
     const includeTokensEstimate = params.includeTokensEstimate === true;
     const isCompact = params.compact === true;
     // 項目2: トークンバジェット保護警告
@@ -1208,6 +2571,15 @@ export async function contextBundle(context, params) {
     if (artifacts.editing_path) {
         keywordSources.push(artifacts.editing_path);
     }
+    if (artifactHints.length > 0) {
+        keywordSources.push(artifactHints.join(" "));
+    }
+    if (hasAnyMetadataFilters) {
+        const filterSeed = metadataFilters
+            .map((filter) => `${filter.source ?? "meta"}:${filter.key}=${filter.values.join(",")}`)
+            .join(" ");
+        keywordSources.push(filterSeed);
+    }
     const semanticSeed = keywordSources.join(" ");
     const queryEmbedding = generateEmbedding(semanticSeed)?.values ?? null;
     const extractedTerms = extractKeywords(semanticSeed);
@@ -1224,11 +2596,17 @@ 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 ??
+        (hasHintMetadataFilters ? "balanced" : hasStrictMetadataFilters ? "docs" : "default");
+    const profileConfig = getBoostProfile(boostProfile);
     // フレーズマッチング（高い重み: textMatch × 2）- 統合クエリでパフォーマンス改善
     if (extractedTerms.phrases.length > 0) {
         const phrasePlaceholders = extractedTerms.phrases
             .map(() => "b.content ILIKE '%' || ? || '%'")
             .join(" OR ");
+        // DEBUG: Log SQL query parameters for troubleshooting
+        console.log(`[DEBUG contextBundle] Executing phrase match query with repo_id=${repoId}, phrases=${JSON.stringify(extractedTerms.phrases)}`);
         const rows = await db.all(`
         SELECT f.path, f.lang, f.ext, f.is_binary, b.content, fe.vector_json, fe.dims AS vector_dims
         FROM file f
@@ -1242,7 +2620,14 @@ 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";
+        // DEBUG: Log returned paths and verify they match expected repo_id
+        if (rows.length > 0) {
+            console.log(`[DEBUG contextBundle] Phrase match returned ${rows.length} rows. Sample paths:`, rows.slice(0, 3).map((r) => r.path));
+            // Verify repo_id of returned files
+            const pathsToCheck = rows.slice(0, 3).map((r) => r.path);
+            const verification = await db.all(`SELECT path, repo_id FROM file WHERE path IN (${pathsToCheck.map(() => "?").join(", ")}) LIMIT 3`, pathsToCheck);
+            console.log(`[DEBUG contextBundle] Repo ID verification:`, verification);
+        }
         for (const row of rows) {
             if (row.content === null) {
                 continue;
@@ -1261,7 +2646,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 +2688,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 +2705,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 =
@@ -1341,6 +2729,31 @@ export async function contextBundle(context, params) {
             }
         }
     }
+    const artifactPathTargets = artifactPathHints.map((hintPath) => ({
+        path: hintPath,
+        sourceHint: hintPath,
+        origin: "artifact",
+    }));
+    const dictionaryPathTargets = await fetchDictionaryPathHints(db, context.tableAvailability, repoId, substringHints, HINT_DICTIONARY_LIMIT);
+    const { list: resolvedPathHintTargets, meta: hintSeedMeta } = createHintSeedMeta([
+        ...artifactPathTargets,
+        ...dictionaryPathTargets,
+    ]);
+    if (resolvedPathHintTargets.length > 0) {
+        await applyPathHintPromotions({
+            db,
+            tableAvailability: context.tableAvailability,
+            repoId,
+            hintTargets: resolvedPathHintTargets,
+            candidates,
+            fileCache,
+            weights,
+            hintSeedMeta,
+        });
+    }
+    if (substringHints.length > 0) {
+        await addHintSubstringMatches(db, context.tableAvailability, repoId, substringHints, candidates, HINT_SUBSTRING_LIMIT, HINT_SUBSTRING_BOOST);
+    }
     if (artifacts.editing_path) {
         const editingCandidate = ensureCandidate(candidates, artifacts.editing_path);
         editingCandidate.score += weights.editingPath;
@@ -1348,7 +2761,6 @@ export async function contextBundle(context, params) {
         editingCandidate.matchLine ??= 1;
     }
     // SQL injection防御: ファイルパスの検証パターン
-    const SAFE_PATH_PATTERN = /^[a-zA-Z0-9_.\-/]+$/;
     const dependencySeeds = new Set();
     for (const pathSeed of stringMatchSeeds) {
         if (!SAFE_PATH_PATTERN.test(pathSeed)) {
@@ -1362,10 +2774,13 @@ export async function contextBundle(context, params) {
     }
     if (artifacts.editing_path) {
         if (!SAFE_PATH_PATTERN.test(artifacts.editing_path)) {
-            throw new Error(`Invalid editing_path format. Path must contain only alphanumeric characters, underscores, dots, hyphens, and forward slashes.`);
+            throw new Error(`Invalid editing_path format: ${artifacts.editing_path}. Use only A-Z, 0-9, _, ., -, / characters.`);
         }
         dependencySeeds.add(artifacts.editing_path);
     }
+    for (const target of resolvedPathHintTargets) {
+        dependencySeeds.add(target.path);
+    }
     if (dependencySeeds.size > 0) {
         // SQL injection防御: プレースホルダー生成前にサイズを検証
         if (dependencySeeds.size > MAX_DEPENDENCY_SEEDS_QUERY_LIMIT) {
@@ -1375,7 +2790,7 @@ export async function contextBundle(context, params) {
         // 防御的チェック: プレースホルダーが正しい形式であることを確認
         // 期待される形式: "?, ?, ..." (クエスチョンマーク、カンマ、スペースのみ)
         if (!/^(\?)(,\s*\?)*$/.test(placeholders)) {
-            throw new Error("Invalid placeholder generation detected. Operation aborted for safety.");
+            throw new Error("Invalid dependency placeholder sequence detected. Remove unsafe dependency seeds and retry the request.");
         }
         const depRows = await db.all(`
         SELECT src_path, dst_kind, dst, rel
@@ -1413,31 +2828,72 @@ export async function contextBundle(context, params) {
             }
         }
     }
-    const materializedCandidates = [];
-    for (const candidate of candidates.values()) {
-        if (!candidate.content) {
-            const cached = fileCache.get(candidate.path);
-            if (cached) {
-                candidate.content = cached.content;
-                candidate.lang = cached.lang;
-                candidate.ext = cached.ext;
-                candidate.totalLines = cached.totalLines;
-                candidate.embedding = cached.embedding;
+    const materializeCandidates = async () => {
+        const result = [];
+        for (const candidate of candidates.values()) {
+            if (isSuppressedPath(candidate.path)) {
+                continue;
             }
-            else {
-                const loaded = await loadFileContent(db, repoId, candidate.path);
-                if (!loaded) {
-                    continue;
+            if (!candidate.content) {
+                const cached = fileCache.get(candidate.path);
+                if (cached) {
+                    candidate.content = cached.content;
+                    candidate.lang = cached.lang;
+                    candidate.ext = cached.ext;
+                    candidate.totalLines = cached.totalLines;
+                    candidate.embedding = cached.embedding;
                 }
-                candidate.content = loaded.content;
-                candidate.lang = loaded.lang;
-                candidate.ext = loaded.ext;
-                candidate.totalLines = loaded.totalLines;
-                candidate.embedding = loaded.embedding;
-                fileCache.set(candidate.path, loaded);
+                else {
+                    const loaded = await loadFileContent(db, repoId, candidate.path);
+                    if (!loaded) {
+                        continue;
+                    }
+                    candidate.content = loaded.content;
+                    candidate.lang = loaded.lang;
+                    candidate.ext = loaded.ext;
+                    candidate.totalLines = loaded.totalLines;
+                    candidate.embedding = loaded.embedding;
+                    fileCache.set(candidate.path, loaded);
+                }
+            }
+            result.push(candidate);
+        }
+        return result;
+    };
+    const addMetadataFallbackCandidates = async () => {
+        if (!hasAnyMetadataFilters) {
+            return;
+        }
+        const metadataRows = await fetchMetadataOnlyCandidates(db, context.tableAvailability, repoId, metadataFilters, limit * 2);
+        if (metadataRows.length === 0) {
+            return;
+        }
+        for (const row of metadataRows) {
+            const candidate = ensureCandidate(candidates, row.path);
+            if (row.content) {
+                candidate.content = row.content;
+                candidate.totalLines = row.content.split(/\r?\n/).length;
+                fileCache.set(row.path, {
+                    content: row.content,
+                    lang: row.lang,
+                    ext: row.ext,
+                    totalLines: candidate.totalLines,
+                    embedding: candidate.embedding,
+                });
             }
+            candidate.lang ??= row.lang;
+            candidate.ext ??= row.ext;
+            candidate.matchLine ??= 1;
+            candidate.score = Math.max(candidate.score, 1 + metadataFilters.length * 0.2);
         }
-        materializedCandidates.push(candidate);
+    };
+    if (hasAnyMetadataFilters) {
+        await addMetadataFallbackCandidates();
+    }
+    let materializedCandidates = await materializeCandidates();
+    if (materializedCandidates.length === 0 && hasAnyMetadataFilters) {
+        await addMetadataFallbackCandidates();
+        materializedCandidates = await materializeCandidates();
     }
     if (materializedCandidates.length === 0) {
         // Get warnings from WarningManager (includes breaking change notification if applicable)
@@ -1448,6 +2904,72 @@ export async function contextBundle(context, params) {
             ...(warnings.length > 0 && { warnings }),
         };
     }
+    const metadataKeywordSet = new Set(extractedTerms.keywords.map((keyword) => keyword.toLowerCase()));
+    const filterValueSet = new Set(metadataFilters.flatMap((filter) => filter.values.map((value) => value.toLowerCase())));
+    let metadataEntriesMap;
+    if (hasAnyMetadataFilters || metadataKeywordSet.size > 0 || filterValueSet.size > 0) {
+        metadataEntriesMap = await loadMetadataForPaths(db, context.tableAvailability, repoId, materializedCandidates.map((candidate) => candidate.path));
+    }
+    if (hasStrictMetadataFilters) {
+        metadataEntriesMap ??= new Map();
+        for (let i = materializedCandidates.length - 1; i >= 0; i--) {
+            const candidate = materializedCandidates[i];
+            if (!candidate) {
+                continue; // Skip undefined entries
+            }
+            const entries = metadataEntriesMap.get(candidate.path);
+            const matchesFilters = candidateMatchesMetadataFilters(entries, strictMetadataFilters);
+            if (!matchesFilters) {
+                materializedCandidates.splice(i, 1);
+                continue;
+            }
+            candidate.reasons.add("metadata:filter");
+            if (process.env.KIRI_TRACE_METADATA === "1") {
+                console.info(`[metadata-trace-match] path=${candidate.path}`);
+            }
+        }
+        if (materializedCandidates.length === 0 && hasAnyMetadataFilters) {
+            await addMetadataFallbackCandidates();
+            materializedCandidates = await materializeCandidates();
+        }
+        if (materializedCandidates.length === 0) {
+            const warnings = [...context.warningManager.responseWarnings];
+            return {
+                context: [],
+                ...(includeTokensEstimate && { tokens_estimate: 0 }),
+                ...(warnings.length > 0 && { warnings }),
+            };
+        }
+    }
+    if (hasHintMetadataFilters) {
+        metadataEntriesMap ??= new Map();
+        for (const candidate of materializedCandidates) {
+            const entries = metadataEntriesMap.get(candidate.path);
+            const matchesHints = candidateMatchesMetadataFilters(entries, hintMetadataFilters);
+            if (matchesHints) {
+                candidate.score += METADATA_HINT_BONUS;
+                candidate.reasons.add("metadata:hint");
+            }
+        }
+    }
+    const inboundCounts = await loadInboundLinkCounts(db, context.tableAvailability, repoId, materializedCandidates.map((candidate) => candidate.path));
+    if (metadataEntriesMap) {
+        for (const candidate of materializedCandidates) {
+            const entries = metadataEntriesMap.get(candidate.path);
+            const metadataBoost = computeMetadataBoost(entries, metadataKeywordSet, filterValueSet);
+            if (metadataBoost > 0) {
+                candidate.score += metadataBoost;
+                candidate.reasons.add("boost:metadata");
+            }
+        }
+    }
+    for (const candidate of materializedCandidates) {
+        const linkBoost = computeInboundLinkBoost(inboundCounts.get(candidate.path));
+        if (linkBoost > 0) {
+            candidate.score += linkBoost;
+            candidate.reasons.add("boost:links");
+        }
+    }
     applyStructuralScores(materializedCandidates, queryEmbedding, weights.structural);
     // ✅ CRITICAL SAFETY: Apply multipliers AFTER all additive scoring (v0.7.0)
     // Only apply to positive scores to prevent negative score inversion
@@ -1456,18 +2978,61 @@ export async function contextBundle(context, params) {
             candidate.score *= candidate.scoreMultiplier;
         }
     }
-    const sortedCandidates = materializedCandidates
-        .filter((candidate) => candidate.score > 0) // Filter out candidates with negative or zero scores
+    // 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);
+    }
+    // v1.0.0: Filter out extremely low-scored candidates (result of multiplicative penalties)
+    // Threshold removes files with >95% penalty while keeping reasonably relevant files
+    // Hint paths are exempt from this threshold (always included if score > 0)
+    const hintPathSet = new Set(resolvedPathHintTargets.map((target) => target.path));
+    const rankedCandidates = materializedCandidates
+        .filter((candidate) => candidate.score > SCORE_FILTER_THRESHOLD ||
+        (candidate.score > 0 && hintPathSet.has(candidate.path)))
         .sort((a, b) => {
         if (b.score === a.score) {
             return a.path.localeCompare(b.path);
         }
         return b.score - a.score;
-    })
-        .slice(0, limit);
-    const maxScore = Math.max(...sortedCandidates.map((candidate) => candidate.score));
+    });
+    const prioritizedCandidates = prioritizeHintCandidates(rankedCandidates, resolvedPathHintTargets.map((target) => target.path), limit);
+    if (prioritizedCandidates.length === 0) {
+        const warnings = [...context.warningManager.responseWarnings];
+        return {
+            context: [],
+            ...(includeTokensEstimate && { tokens_estimate: 0 }),
+            ...(warnings.length > 0 && { warnings }),
+        };
+    }
+    const maxScore = Math.max(...prioritizedCandidates.map((candidate) => candidate.score));
     const results = [];
-    for (const candidate of sortedCandidates) {
+    for (const candidate of prioritizedCandidates) {
         if (!candidate.content) {
             continue;
         }
@@ -1495,6 +3060,23 @@ export async function contextBundle(context, params) {
             startLine = Math.max(1, matchLine - windowHalf);
             endLine = Math.min(totalLines === 0 ? matchLine + windowHalf : totalLines, startLine + FALLBACK_SNIPPET_WINDOW - 1);
         }
+        if (CLAMP_SNIPPETS_ENABLED) {
+            // Clamp snippet length to FALLBACK_SNIPPET_WINDOW even when symbol spans large regions
+            const maxWindow = FALLBACK_SNIPPET_WINDOW;
+            const selectedEnd = selected ? selected.end_line : endLine;
+            const selectedStart = selected ? selected.start_line : startLine;
+            if (endLine - startLine + 1 > maxWindow) {
+                const anchor = candidate.matchLine ?? startLine;
+                let clampedStart = Math.max(selectedStart, anchor - Math.floor(maxWindow / 2));
+                let clampedEnd = clampedStart + maxWindow - 1;
+                if (clampedEnd > selectedEnd) {
+                    clampedEnd = selectedEnd;
+                    clampedStart = Math.max(selectedStart, clampedEnd - maxWindow + 1);
+                }
+                startLine = clampedStart;
+                endLine = Math.max(clampedStart, clampedEnd);
+            }
+        }
         if (endLine < startLine) {
             endLine = startLine;
         }
@@ -1522,7 +3104,7 @@ export async function contextBundle(context, params) {
     let tokensEstimate;
     if (includeTokensEstimate) {
         tokensEstimate = results.reduce((acc, item) => {
-            const candidate = sortedCandidates.find((c) => c.path === item.path);
+            const candidate = prioritizedCandidates.find((c) => c.path === item.path);
             if (candidate && candidate.content) {
                 return acc + estimateTokensFromContent(candidate.content, item.range[0], item.range[1]);
             }
@@ -1533,8 +3115,13 @@ export async function contextBundle(context, params) {
     }
     // Get warnings from WarningManager (includes breaking change notification if applicable)
     const warnings = [...context.warningManager.responseWarnings];
+    const shouldFilterResults = FINAL_RESULT_SUPPRESSION_ENABLED && SUPPRESS_NON_CODE_ENABLED;
+    const sanitizedResults = shouldFilterResults
+        ? results.filter((item) => !isSuppressedPath(item.path))
+        : results;
+    const finalResults = sanitizedResults.length > 0 ? sanitizedResults : results;
     const payload = {
-        context: results,
+        context: finalResults,
         ...(warnings.length > 0 && { warnings }),
     };
     if (tokensEstimate !== undefined) {
@@ -1737,35 +3324,27 @@ export async function depsClosure(context, params) {
         edges,
     };
 }
-export async function resolveRepoId(db, repoRoot) {
+/**
+ * リポジトリのrootパスをデータベースIDに解決する。
+ *
+ * この関数は下位互換性のために保持されているが、内部的には新しいRepoResolverを使用する。
+ *
+ * @param db - DuckDBクライアント
+ * @param repoRoot - リポジトリのrootパス
+ * @param services - オプショナルなServerServices（指定がなければ新規作成される）
+ * @returns リポジトリID
+ * @throws Error リポジトリがインデックスされていない場合
+ */
+export async function resolveRepoId(db, repoRoot, services) {
+    const svc = services ?? createServerServices(db);
+    return await svc.repoResolver.resolveId(repoRoot);
+}
+export async function contextBundle(context, params) {
     try {
-        const candidates = getRepoPathCandidates(repoRoot);
-        const normalized = candidates[0];
-        const placeholders = candidates.map(() => "?").join(", ");
-        const rows = await db.all(`SELECT id, root FROM repo WHERE root IN (${placeholders}) LIMIT 1`, candidates);
-        if (rows.length === 0) {
-            const existingRows = await db.all("SELECT id, root FROM repo");
-            for (const candidate of existingRows) {
-                if (normalizeRepoPath(candidate.root) === normalized) {
-                    await db.run("UPDATE repo SET root = ? WHERE id = ?", [normalized, candidate.id]);
-                    return candidate.id;
-                }
-            }
-            throw new Error("Target repository is missing from DuckDB. Run the indexer before starting the server.");
-        }
-        const row = rows[0];
-        if (!row) {
-            throw new Error("Failed to retrieve repository record. Database returned empty result.");
-        }
-        if (row.root !== normalized) {
-            await db.run("UPDATE repo SET root = ? WHERE id = ?", [normalized, row.id]);
-        }
-        return row.id;
+        return await contextBundleImpl(context, params);
     }
     catch (error) {
-        if (error instanceof Error && error.message.includes("Table with name repo")) {
-            throw new Error("Target repository is missing from DuckDB. Run the indexer before starting the server.");
-        }
+        console.error("context_bundle error:", error);
         throw error;
     }
 }