@wooojin/forgen 0.4.10 → 0.4.11

package/dist/engine/extraction-session.js

@@ -0,0 +1,230 @@
+/**
+ * Session context extraction for compound knowledge.
+ *
+ * Extracted from compound-extractor.ts — reads Claude session JSONL files
+ * to extract prompts and write history correlated to a specific project.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { CLAUDE_DIR, STATE_DIR } from '../core/paths.js';
+import { createLogger } from '../core/logger.js';
+const log = createLogger('extraction-session');
+function normalizeProjectPath(cwd) {
+    const resolved = path.resolve(cwd);
+    try {
+        return typeof fs.realpathSync.native === 'function'
+            ? fs.realpathSync.native(resolved)
+            : fs.realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+function getProjectPathCandidates(cwd) {
+    const resolved = path.resolve(cwd);
+    const candidates = new Set([resolved, normalizeProjectPath(cwd)]);
+    try {
+        if (fs.lstatSync(resolved).isSymbolicLink()) {
+            candidates.add(path.resolve(path.dirname(resolved), fs.readlinkSync(resolved)));
+        }
+    }
+    catch {
+        // Ignore lstat/readlink failures
+    }
+    for (const candidate of [...candidates]) {
+        candidates.add(normalizeProjectPath(candidate));
+    }
+    return [...candidates];
+}
+function getClaudeProjectDirs(cwd) {
+    return getProjectPathCandidates(cwd)
+        .map(candidate => path.join(CLAUDE_DIR, 'projects', candidate.replace(/[:\\/]/g, '-')));
+}
+function listClaudeSessionFiles(projectDirs, maxFiles) {
+    return projectDirs
+        .flatMap(projectDir => {
+        let entries;
+        try {
+            entries = fs.readdirSync(projectDir);
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const file of entries) {
+            if (!file.endsWith('.jsonl'))
+                continue;
+            const filePath = path.join(projectDir, file);
+            try {
+                if (fs.lstatSync(filePath).isSymbolicLink())
+                    continue;
+                out.push({ filePath, mtimeMs: fs.statSync(filePath).mtimeMs });
+            }
+            catch {
+                // unreadable / vanished between readdir and stat — skip
+            }
+        }
+        return out;
+    })
+        .sort((a, b) => b.mtimeMs - a.mtimeMs)
+        .slice(0, maxFiles);
+}
+function getAllClaudeProjectDirs() {
+    const projectsRoot = path.join(CLAUDE_DIR, 'projects');
+    if (!fs.existsSync(projectsRoot))
+        return [];
+    return fs.readdirSync(projectsRoot)
+        .map(name => path.join(projectsRoot, name))
+        .filter(dir => {
+        try {
+            return fs.statSync(dir).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function collectClaudeProjectSessionContext(files, cwdCandidates, cutoffMs) {
+    const prompts = [];
+    const writes = [];
+    for (const file of files) {
+        try {
+            if (fs.lstatSync(file.filePath).isSymbolicLink())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        let lines;
+        try {
+            lines = fs.readFileSync(file.filePath, 'utf-8').split('\n').filter(Boolean);
+        }
+        catch {
+            continue;
+        }
+        for (const line of lines) {
+            let entry;
+            try {
+                entry = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const entryCandidates = typeof entry.cwd === 'string' ? getProjectPathCandidates(entry.cwd) : [];
+            if (!entryCandidates.some(candidate => cwdCandidates.has(candidate)))
+                continue;
+            const timestamp = typeof entry.timestamp === 'string' ? new Date(entry.timestamp).getTime() : Number.NaN;
+            if (cutoffMs && Number.isFinite(timestamp) && timestamp <= cutoffMs)
+                continue;
+            if (entry.type === 'user') {
+                const message = entry.message;
+                if (message?.role === 'user' && typeof message.content === 'string') {
+                    prompts.push(message.content);
+                }
+                continue;
+            }
+            if (entry.type !== 'assistant')
+                continue;
+            const message = entry.message;
+            if (message?.role !== 'assistant' || !Array.isArray(message.content))
+                continue;
+            for (const item of message.content) {
+                if (typeof item !== 'object' || item === null)
+                    continue;
+                const toolUse = item;
+                if (toolUse.type !== 'tool_use')
+                    continue;
+                if (toolUse.name !== 'Write' && toolUse.name !== 'Edit')
+                    continue;
+                const filePath = String(toolUse.input?.file_path ?? toolUse.input?.filePath ?? '');
+                const content = String(toolUse.input?.content ?? toolUse.input?.new_string ?? '');
+                if (!filePath || !content)
+                    continue;
+                writes.push({
+                    filePath: filePath.slice(-100),
+                    contentSnippet: content.slice(0, 200),
+                    fileExtension: path.extname(filePath).toLowerCase(),
+                });
+            }
+        }
+    }
+    return {
+        prompts: prompts.slice(-50),
+        writes: writes.slice(-30),
+    };
+}
+export function loadPromptHistoryFallback() {
+    const promptHistoryPath = path.join(STATE_DIR, 'prompt-history.jsonl');
+    try {
+        if (!fs.existsSync(promptHistoryPath))
+            return [];
+        const lines = fs.readFileSync(promptHistoryPath, 'utf-8').split('\n').filter(Boolean);
+        return lines.slice(-50).map(l => {
+            try {
+                return JSON.parse(l).prompt;
+            }
+            catch {
+                return '';
+            }
+        }).filter(Boolean);
+    }
+    catch (e) {
+        log.debug('prompt-history.jsonl 읽기 실패 — session context fallback 건너뜀', e);
+        return [];
+    }
+}
+/**
+ * Load Claude session prompts + writes correlated to `cwd`.
+ *
+ * Exported primarily for test assertions (the `claude-session-context`
+ * tests verify correlation logic directly).
+ */
+export function loadClaudeProjectSessionContext(cwd, lastExtractedAt) {
+    const cwdCandidates = new Set(getProjectPathCandidates(cwd));
+    const projectDirs = getClaudeProjectDirs(cwd).filter(dir => fs.existsSync(dir));
+    const cutoffMs = lastExtractedAt ? new Date(lastExtractedAt).getTime() : 0;
+    try {
+        if (projectDirs.length > 0) {
+            const primary = collectClaudeProjectSessionContext(listClaudeSessionFiles(projectDirs, 5), cwdCandidates, cutoffMs);
+            if (primary.prompts.length > 0 || primary.writes.length > 0)
+                return primary;
+        }
+        const fallbackDirs = getAllClaudeProjectDirs().filter(dir => !projectDirs.includes(dir));
+        if (fallbackDirs.length === 0)
+            return { prompts: [], writes: [] };
+        return collectClaudeProjectSessionContext(listClaudeSessionFiles(fallbackDirs, 20), cwdCandidates, cutoffMs);
+    }
+    catch (e) {
+        log.debug('Claude project session context 로드 실패 — fallback 사용', e);
+        return { prompts: [], writes: [] };
+    }
+}
+/** Extract patterns from accumulated session context (prompts + writes + diff) */
+export function extractFromSessionContext(gitDiff, cwd, lastExtractedAt) {
+    const solutions = [];
+    const claudeContext = loadClaudeProjectSessionContext(cwd, lastExtractedAt);
+    let prompts = claudeContext.prompts;
+    if (prompts.length === 0) {
+        prompts = loadPromptHistoryFallback();
+    }
+    const techDecisions = [];
+    const techTerms = ['react', 'vue', 'next', 'express', 'fastify', 'prisma', 'drizzle', 'zustand', 'redux', 'tailwind', 'styled', 'vitest', 'jest', 'playwright', 'cypress'];
+    for (const term of techTerms) {
+        const inPrompts = prompts.some(p => p.toLowerCase().includes(term));
+        const inDiff = gitDiff.toLowerCase().includes(term);
+        if (inPrompts && inDiff) {
+            techDecisions.push(term);
+        }
+    }
+    if (techDecisions.length >= 2) {
+        solutions.push({
+            name: 'tech-stack-decision',
+            type: 'decision',
+            tags: ['stack', 'technology', ...techDecisions.slice(0, 5)],
+            identifiers: techDecisions.filter(t => t.length >= 4).slice(0, 5),
+            context: 'Technology choices confirmed by both discussion and implementation',
+            content: `Active technology stack: ${techDecisions.join(', ')}. Both discussed in prompts and present in code changes.`,
+        });
+    }
+    return solutions;
+}

package/dist/engine/lifecycle/types.d.ts

@@ -39,7 +39,7 @@ export interface ViolationEntry {
     at: string;
     rule_id: string;
     session_id: string;
-    source: 'stop-guard' | 'pre-tool-guard' | 'post-tool-guard' | 'evidence-store' | 'manual';
+    source: 'stop-guard' | 'subagent-stop-guard' | 'pre-tool-guard' | 'post-tool-guard' | 'evidence-store' | 'manual';
     kind: 'block' | 'deny' | 'correction';
     message_preview?: string;
 }

package/dist/engine/meta-learning/matcher-weight-loader.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Dynamic ensemble weight loader for the solution matcher.
+ *
+ * Extracted from solution-matcher.ts — loads tuned weights from meta-learning
+ * state with a 1-minute in-process TTL cache.
+ */
+/**
+ * Load tuned matcher weights from meta-learning state.
+ * Returns undefined (use defaults) if no tuned weights exist.
+ * Cached for 1 minute to avoid re-reading per matchSolutions call.
+ */
+export declare function loadTunedMatcherWeights(): {
+    tfidf: number;
+    bm25: number;
+    bigram: number;
+} | undefined;

package/dist/engine/meta-learning/matcher-weight-loader.js

@@ -0,0 +1,45 @@
+/**
+ * Dynamic ensemble weight loader for the solution matcher.
+ *
+ * Extracted from solution-matcher.ts — loads tuned weights from meta-learning
+ * state with a 1-minute in-process TTL cache.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { META_LEARNING_DIR } from '../../core/paths.js';
+let _cachedWeights;
+let _weightsCacheTime = 0;
+const WEIGHTS_CACHE_TTL = 60_000; // 1 minute cache
+/**
+ * Load tuned matcher weights from meta-learning state.
+ * Returns undefined (use defaults) if no tuned weights exist.
+ * Cached for 1 minute to avoid re-reading per matchSolutions call.
+ */
+export function loadTunedMatcherWeights() {
+    const now = Date.now();
+    if (_cachedWeights !== undefined && now - _weightsCacheTime < WEIGHTS_CACHE_TTL) {
+        return _cachedWeights ?? undefined;
+    }
+    try {
+        const weightsPath = path.join(META_LEARNING_DIR, 'matcher-weights.json');
+        if (!fs.existsSync(weightsPath)) {
+            _cachedWeights = null;
+            _weightsCacheTime = now;
+            return undefined;
+        }
+        const data = JSON.parse(fs.readFileSync(weightsPath, 'utf-8'));
+        if (typeof data.tfidf === 'number' &&
+            typeof data.bm25 === 'number' &&
+            typeof data.bigram === 'number') {
+            _cachedWeights = { tfidf: data.tfidf, bm25: data.bm25, bigram: data.bigram };
+            _weightsCacheTime = now;
+            return _cachedWeights;
+        }
+    }
+    catch {
+        /* fail-open: use defaults */
+    }
+    _cachedWeights = null;
+    _weightsCacheTime = now;
+    return undefined;
+}

package/dist/engine/precision-guards.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Query-side specificity guards for the solution matcher (R4-T3).
+ *
+ * Extracted from solution-matcher.ts — orchestration-layer precision rules
+ * applied AFTER calculateRelevance returns. These fix false positives from
+ * ambiguous single-tag matches without regressing legitimate results.
+ *
+ * Rule A: single-token query AND single-tag match → reject.
+ * Rule B: all matched tags came via synonym expansion (none literal in prompt)
+ *         AND match is single-tag → reject.
+ *
+ * Returns true = reject the candidate, false = keep it.
+ */
+export declare function shouldRejectByR4T3Rules(promptTags: readonly string[], matchedTags: readonly string[]): boolean;

package/dist/engine/precision-guards.js

@@ -0,0 +1,39 @@
+/**
+ * Query-side specificity guards for the solution matcher (R4-T3).
+ *
+ * Extracted from solution-matcher.ts — orchestration-layer precision rules
+ * applied AFTER calculateRelevance returns. These fix false positives from
+ * ambiguous single-tag matches without regressing legitimate results.
+ *
+ * Rule A: single-token query AND single-tag match → reject.
+ * Rule B: all matched tags came via synonym expansion (none literal in prompt)
+ *         AND match is single-tag → reject.
+ *
+ * Returns true = reject the candidate, false = keep it.
+ */
+export function shouldRejectByR4T3Rules(promptTags, matchedTags) {
+    // Rule A
+    if (promptTags.length === 1 && matchedTags.length === 1) {
+        return true;
+    }
+    // Rule B
+    if (matchedTags.length === 1) {
+        const tag = matchedTags[0];
+        const literalHit = promptTags.includes(tag) ||
+            promptTags.some((pt) => {
+                if (pt.length <= 3 || tag.length <= 3)
+                    return false;
+                if (pt.includes(tag) || tag.includes(pt))
+                    return true;
+                // Morphological stem: shared prefix of length ≥ 4
+                let i = 0;
+                const limit = Math.min(pt.length, tag.length);
+                while (i < limit && pt[i] === tag[i])
+                    i++;
+                return i >= 4;
+            });
+        if (!literalHit)
+            return true;
+    }
+    return false;
+}

package/dist/engine/ranking-pipeline.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared ranking core for solution matching.
+ *
+ * Extracted from solution-matcher.ts — the ranking pipeline used by both
+ * production (matchSolutions) and the bootstrap evaluator
+ * (evaluateSolutionMatcher). Single source of truth for ranking behaviour.
+ */
+/**
+ * Narrow input shape for the shared ranking pipeline. `matchSolutions` and the
+ * bootstrap evaluator both reduce to this contract — `LoadedSolution` is
+ * structurally compatible (it has more fields), and `EvalSolution` mirrors it
+ * exactly. Keeping the input narrow prevents the evaluator from leaking onto
+ * prod types and vice versa.
+ */
+export interface RankableSolution {
+    name: string;
+    tags: string[];
+    identifiers?: string[];
+    confidence: number;
+}
+/**
+ * Intermediate ranked candidate. Generic over the source solution type so the
+ * caller can get back the exact object they passed in.
+ */
+export interface RankedCandidate<T extends RankableSolution = RankableSolution> {
+    solution: T;
+    relevance: number;
+    matchedTags: string[];
+    matchedIdentifiers: string[];
+}
+/**
+ * Shared ranking core: tag-based relevance + identifier boost + top-5 sort.
+ *
+ * Contract:
+ *   - identifier boost requires `id.length >= 4` and substring presence in
+ *     the prompt (case-insensitive).
+ *   - candidates with zero matched tags AND zero matched identifiers are dropped.
+ *   - top-5 by `relevance` descending.
+ *   - duplicate names are NOT deduplicated.
+ */
+export declare function rankCandidates<T extends RankableSolution>(promptTags: string[], promptLower: string, solutions: readonly T[], ensembleWeights?: {
+    tfidf: number;
+    bm25: number;
+    bigram: number;
+}): RankedCandidate<T>[];

package/dist/engine/ranking-pipeline.js

@@ -0,0 +1,66 @@
+/**
+ * Shared ranking core for solution matching.
+ *
+ * Extracted from solution-matcher.ts — the ranking pipeline used by both
+ * production (matchSolutions) and the bootstrap evaluator
+ * (evaluateSolutionMatcher). Single source of truth for ranking behaviour.
+ */
+import { maskBlockedTokens } from './phrase-blocklist.js';
+import { calculateRelevance } from './relevance-scorer.js';
+import { expandCompoundTags, expandQueryBigrams } from './solution-format.js';
+import { shouldRejectByR4T3Rules } from './precision-guards.js';
+import { defaultNormalizer } from './term-normalizer.js';
+/**
+ * Shared ranking core: tag-based relevance + identifier boost + top-5 sort.
+ *
+ * Contract:
+ *   - identifier boost requires `id.length >= 4` and substring presence in
+ *     the prompt (case-insensitive).
+ *   - candidates with zero matched tags AND zero matched identifiers are dropped.
+ *   - top-5 by `relevance` descending.
+ *   - duplicate names are NOT deduplicated.
+ */
+export function rankCandidates(promptTags, promptLower, solutions, ensembleWeights) {
+    // R4-T2: mask blocked tokens before expansion/normalization
+    const maskedPromptTags = maskBlockedTokens(promptLower, promptTags);
+    if (maskedPromptTags.length === 0)
+        return [];
+    // R4-T1: expand prompt tags with adjacent-token bigrams
+    const promptTagsWithBigrams = expandQueryBigrams(maskedPromptTags);
+    const normalizedPromptTags = defaultNormalizer.normalizeTerms(promptTagsWithBigrams);
+    return solutions
+        .map((sol) => {
+        const solTagsExpanded = expandCompoundTags(sol.tags);
+        const result = calculateRelevance(maskedPromptTags, sol.tags, sol.confidence, {
+            normalizedPromptTags,
+            solutionTagsExpanded: solTagsExpanded,
+            ensembleWeights,
+        });
+        let identifierBoost = 0;
+        const matchedIdentifiers = [];
+        for (const id of sol.identifiers ?? []) {
+            if (id.length >= 4 && promptLower.includes(id.toLowerCase())) {
+                identifierBoost += 0.15;
+                matchedIdentifiers.push(id);
+            }
+        }
+        // R4-T3: orchestration-layer specificity guards
+        let tagRelevance = result.relevance;
+        let tagMatches = result.matchedTags;
+        if (matchedIdentifiers.length === 0 &&
+            tagMatches.length > 0 &&
+            shouldRejectByR4T3Rules(maskedPromptTags, tagMatches)) {
+            tagRelevance = 0;
+            tagMatches = [];
+        }
+        return {
+            solution: sol,
+            relevance: tagRelevance + identifierBoost,
+            matchedTags: tagMatches,
+            matchedIdentifiers,
+        };
+    })
+        .filter((c) => c.matchedTags.length + c.matchedIdentifiers.length >= 1)
+        .sort((a, b) => b.relevance - a.relevance)
+        .slice(0, 5);
+}

package/dist/engine/relevance-scorer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Tag-based relevance scoring for solution matching.
+ *
+ * Extracted from solution-matcher.ts — the core scoring logic that computes
+ * relevance between a prompt's tags and a solution's tags using a TF-IDF +
+ * BM25 + bigram ensemble.
+ */
+/**
+ * Optional hints for the v3 `calculateRelevance` path. Used by hot-path
+ * callers (matchSolutions, searchSolutions) to avoid re-normalizing the
+ * same query tags on every solution.
+ */
+export interface CalculateRelevanceOptions {
+    /**
+     * Pre-normalized prompt tags (produced by `defaultNormalizer.normalizeTerms`).
+     * If provided, skips the per-call expansion. Callers loop-running against
+     * many solutions should compute this once outside the loop and pass it in.
+     */
+    normalizedPromptTags?: string[];
+    /**
+     * R4-T1: solution tags expanded with compound-split alternatives
+     * (`expandCompoundTags`). When supplied, the intersection/partial-match
+     * step uses this set INSTEAD of `solutionTags`, but the Jaccard union
+     * denominator still uses `solutionTags` (raw) so the score normalization
+     * stays semantically stable. Caller responsibility to pass the matching
+     * pair — `solutionTagsExpanded` MUST be a superset of `solutionTags`.
+     */
+    solutionTagsExpanded?: string[];
+    /** Average document (solution) tag count for BM25 normalization. Defaults to 6. */
+    avgDocLength?: number;
+    /** Meta-learning: dynamic ensemble weights (sum must equal 1.0). Defaults to {tfidf:0.5, bm25:0.3, bigram:0.2}. */
+    ensembleWeights?: {
+        tfidf: number;
+        bm25: number;
+        bigram: number;
+    };
+}
+export declare function calculateRelevance(promptTags: string[], solutionTags: string[], confidence: number, options?: CalculateRelevanceOptions): {
+    relevance: number;
+    matchedTags: string[];
+};
+/** @deprecated */
+export declare function calculateRelevance(prompt: string, keywords: string[]): number;

package/dist/engine/relevance-scorer.js

@@ -0,0 +1,81 @@
+/**
+ * Tag-based relevance scoring for solution matching.
+ *
+ * Extracted from solution-matcher.ts — the core scoring logic that computes
+ * relevance between a prompt's tags and a solution's tags using a TF-IDF +
+ * BM25 + bigram ensemble.
+ */
+import { bigramSimilarity, bm25Score, tagWeight } from './scoring-algorithms.js';
+import { extractTags } from './solution-format.js';
+import { defaultNormalizer } from './term-normalizer.js';
+export function calculateRelevance(promptOrTags, keywordsOrTags, confidence, options) {
+    if (typeof promptOrTags === 'string') {
+        // Legacy mode: substring matching for backwards compatibility.
+        // Not a hot path — only hit by the (old) solution-matcher.test.ts cases.
+        const promptTags = extractTags(promptOrTags);
+        const intersection = keywordsOrTags.filter((kw) => promptTags.some((pt) => pt === kw || (pt.length > 3 && kw.length > 3 && (pt.startsWith(kw) || kw.startsWith(pt)))));
+        return Math.min(1, intersection.length / Math.max(promptTags.length * 0.5, 1));
+    }
+    // v3 mode: tag matching with synonym expansion + TF-IDF weighting.
+    const expandedPromptTags = options?.normalizedPromptTags ?? defaultNormalizer.normalizeTerms(promptOrTags);
+    // R4-T1: when the caller supplies a compound-expanded solution tag set,
+    // intersection and partial matching run against the expanded set.
+    const matchTags = options?.solutionTagsExpanded ?? keywordsOrTags;
+    const intersection = matchTags.filter((t) => expandedPromptTags.includes(t));
+    // partial/substring matches for longer tags (>3 chars)
+    const partialMatches = matchTags.filter((t) => t.length > 3 &&
+        !intersection.includes(t) &&
+        expandedPromptTags.some((pt) => pt.length > 3 && (pt.includes(t) || t.includes(pt))));
+    // Apply TF-IDF weighting: common tags count less
+    const weightedMatched = intersection.reduce((sum, t) => sum + tagWeight(t), 0) +
+        partialMatches.reduce((sum, t) => sum + tagWeight(t) * 0.5, 0);
+    // Bigram similarity boost for borderline cases
+    if (weightedMatched < 0.5) {
+        let bestBigramScore = 0;
+        const bigramMatchedTags = [];
+        for (const st of matchTags) {
+            for (const pt of expandedPromptTags) {
+                const sim = bigramSimilarity(pt, st);
+                if (sim > bestBigramScore) {
+                    bestBigramScore = sim;
+                }
+                if (sim > 0.4 && !bigramMatchedTags.includes(st)) {
+                    bigramMatchedTags.push(st);
+                }
+            }
+        }
+        if (bestBigramScore > 0.4) {
+            const union = new Set([...promptOrTags, ...keywordsOrTags]).size;
+            const tfidfScore = weightedMatched / Math.max(union, 1);
+            const blendedScore = tfidfScore * 0.8 + bestBigramScore * 0.2;
+            return {
+                relevance: blendedScore * (confidence ?? 1),
+                matchedTags: [
+                    ...intersection,
+                    ...partialMatches,
+                    ...bigramMatchedTags.filter((t) => !intersection.includes(t) && !partialMatches.includes(t)),
+                ],
+            };
+        }
+        return { relevance: 0, matchedTags: [] };
+    }
+    // Ensemble: TF-IDF (Jaccard) 0.5 + BM25 0.3 + bigram 0.2
+    const union = new Set([...promptOrTags, ...keywordsOrTags]).size;
+    const tfidfScore = weightedMatched / Math.max(union, 1);
+    const avgDocLen = options?.avgDocLength ?? 6;
+    const bm25 = bm25Score(promptOrTags, keywordsOrTags, avgDocLen);
+    let bigramBoost = 0;
+    for (const st of matchTags) {
+        for (const pt of expandedPromptTags) {
+            const sim = bigramSimilarity(pt, st);
+            if (sim > bigramBoost)
+                bigramBoost = sim;
+        }
+    }
+    const w = options?.ensembleWeights ?? { tfidf: 0.5, bm25: 0.3, bigram: 0.2 };
+    const ensembleScore = tfidfScore * w.tfidf + bm25 * w.bm25 + bigramBoost * w.bigram;
+    return {
+        relevance: ensembleScore * (confidence ?? 1),
+        matchedTags: [...intersection, ...partialMatches],
+    };
+}

package/dist/engine/scoring-algorithms.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Stateless scoring primitives for the solution matcher.
+ *
+ * Extracted from solution-matcher.ts — these are pure functions with no
+ * filesystem or module-level state dependencies.
+ */
+/** High-frequency tags that should be weighted lower */
+export declare const COMMON_TAGS: Set<string>;
+/** Apply IDF-like weight: common tags get reduced weight */
+export declare function tagWeight(tag: string): number;
+/**
+ * Compute the Dice coefficient between two strings using character bigrams.
+ *
+ * Dice = 2 * |intersection| / (|A| + |B|)
+ *
+ * Both strings are lowercased and whitespace-stripped before bigram generation.
+ * Returns 0 for empty strings or single-character strings (no bigrams possible).
+ * Returns 1.0 for identical non-trivial strings.
+ *
+ * This is used as a lightweight fuzzy matching signal for borderline cases
+ * where the TF-IDF tag intersection produces a low score but the query and
+ * solution tags are character-similar (e.g., "database" vs "데이터베이스"
+ * won't match, but "database" vs "databse" will get a high score).
+ */
+export declare function bigramSimilarity(a: string, b: string): number;
+/**
+ * Simplified BM25 score for a single query-document pair.
+ * Uses tag overlap with term frequency normalization.
+ * k1=1.2, b=0.75 (standard BM25 parameters).
+ */
+export declare function bm25Score(queryTags: string[], docTags: string[], avgDocLength: number): number;