@wooojin/forgen 0.2.0 → 0.3.0

package/dist/engine/solution-matcher.js

@@ -1,9 +1,10 @@
+import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { ME_SOLUTIONS, PACKS_DIR } from '../core/paths.js';
-import { extractTags, expandCompoundTags, expandQueryBigrams } from './solution-format.js';
+import { ME_SOLUTIONS, META_LEARNING_DIR, PACKS_DIR } from '../core/paths.js';
+import { maskBlockedTokens } from './phrase-blocklist.js';
+import { expandCompoundTags, expandQueryBigrams, extractTags } from './solution-format.js';
 import { getOrBuildIndex } from './solution-index.js';
 import { defaultNormalizer } from './term-normalizer.js';
-import { maskBlockedTokens } from './phrase-blocklist.js';
 // ── Synonym expansion (delegates to term-normalizer) ──
 //
 // The old `SYNONYM_MAP` + `expandTagsWithSynonyms` pair had two problems:
@@ -31,12 +32,106 @@ export function expandTagsWithSynonyms(tags) {
     return defaultNormalizer.normalizeTerms(tags);
 }
 // ── TF-IDF weighting for common tags ──
+// ── Character bigram similarity (Dice coefficient) ──
+/**
+ * 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 function bigramSimilarity(a, b) {
+    const na = a.toLowerCase().replace(/\s+/g, '');
+    const nb = b.toLowerCase().replace(/\s+/g, '');
+    if (na.length < 2 || nb.length < 2)
+        return 0;
+    if (na === nb)
+        return 1.0;
+    const bigramsA = new Map();
+    for (let i = 0; i < na.length - 1; i++) {
+        const bg = na.slice(i, i + 2);
+        bigramsA.set(bg, (bigramsA.get(bg) ?? 0) + 1);
+    }
+    const bigramsB = new Map();
+    for (let i = 0; i < nb.length - 1; i++) {
+        const bg = nb.slice(i, i + 2);
+        bigramsB.set(bg, (bigramsB.get(bg) ?? 0) + 1);
+    }
+    let intersectionSize = 0;
+    for (const [bg, countA] of bigramsA) {
+        const countB = bigramsB.get(bg) ?? 0;
+        intersectionSize += Math.min(countA, countB);
+    }
+    const totalA = na.length - 1;
+    const totalB = nb.length - 1;
+    return (2 * intersectionSize) / (totalA + totalB);
+}
+// ── BM25-like scoring ──
+/**
+ * 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 function bm25Score(queryTags, docTags, avgDocLength) {
+    const k1 = 1.2;
+    const b = 0.75;
+    const docLen = docTags.length;
+    if (docLen === 0 || queryTags.length === 0 || avgDocLength === 0)
+        return 0;
+    let score = 0;
+    for (const qt of queryTags) {
+        // Term frequency in document
+        const tf = docTags.filter((dt) => dt === qt || (dt.length > 3 && qt.length > 3 && (dt.includes(qt) || qt.includes(dt)))).length;
+        if (tf === 0)
+            continue;
+        // BM25 TF saturation
+        const numerator = tf * (k1 + 1);
+        const denominator = tf + k1 * (1 - b + b * (docLen / avgDocLength));
+        score += numerator / denominator;
+    }
+    // Normalize by query length
+    return score / queryTags.length;
+}
 /** High-frequency tags that should be weighted lower */
 const COMMON_TAGS = new Set([
-    'typescript', 'ts', 'javascript', 'js', 'fix', 'update', 'add', 'change',
-    'file', 'code', 'function', 'import', 'export', 'error', 'type', 'string',
-    'number', 'object', 'array', 'return', 'const', 'class', 'module',
-    '코드', '파일', '함수', '수정', '추가', '변경', '에러', '타입',
+    'typescript',
+    'ts',
+    'javascript',
+    'js',
+    'fix',
+    'update',
+    'add',
+    'change',
+    'file',
+    'code',
+    'function',
+    'import',
+    'export',
+    'error',
+    'type',
+    'string',
+    'number',
+    'object',
+    'array',
+    'return',
+    'const',
+    'class',
+    'module',
+    '코드',
+    '파일',
+    '함수',
+    '수정',
+    '추가',
+    '변경',
+    '에러',
+    '타입',
 ]);
 /** Apply IDF-like weight: common tags get reduced weight */
 export function tagWeight(tag) {
@@ -47,7 +142,7 @@ export function calculateRelevance(promptOrTags, keywordsOrTags, confidence, opt
         // 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)))));
+        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.
@@ -57,35 +152,86 @@ export function calculateRelevance(promptOrTags, keywordsOrTags, confidence, opt
     // the hot path pre-compute the expansion once per query and pass it via
     // `options.normalizedPromptTags`, so this function no longer repeats the
     // work per solution.
-    const expandedPromptTags = options?.normalizedPromptTags
-        ?? defaultNormalizer.normalizeTerms(promptOrTags);
+    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 (so
     // `api-key` matches `api`/`key` queries via the split parts), but the
     // Jaccard union denominator below still uses the RAW `keywordsOrTags`
     // for normalization stability.
     const matchTags = options?.solutionTagsExpanded ?? keywordsOrTags;
-    const intersection = matchTags.filter(t => expandedPromptTags.includes(t));
+    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))));
+    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);
-    // 완화된 임계값: 가중 점수 0.5 이상이면 후보
-    if (weightedMatched < 0.5)
+    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 ──
+    //
+    // When the TF-IDF intersection score is below the match threshold (0.5),
+    // compute a character-bigram Dice coefficient between the query tags and
+    // the solution tags. If the best bigram similarity is high enough, blend
+    // it in at 20% weight (TF-IDF 80%, bigram 20%) to rescue fuzzy matches
+    // that the exact/substring intersection missed (e.g., typos, slight
+    // morphological variants).
+    //
+    // When TF-IDF score is already above threshold, the bigram boost is NOT
+    // applied — this preserves existing match quality and avoids disturbing
+    // already-good rankings. The bigram path is purely a rescue mechanism
+    // for borderline cases.
+    if (weightedMatched < 0.5) {
+        // Compute best bigram similarity across all (promptTag, solutionTag) pairs
+        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;
+                }
+                // Track solution tags with meaningful bigram similarity (> 0.4)
+                if (sim > 0.4 && !bigramMatchedTags.includes(st)) {
+                    bigramMatchedTags.push(st);
+                }
+            }
+        }
+        // Only rescue if the bigram signal is strong enough (> 0.4 threshold)
+        // to avoid noise from weakly similar strings
+        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: [] };
-    // Jaccard-like: weighted matched / union.
-    // Union uses RAW promptTags and RAW solutionTags — not the expanded set —
-    // so that the denominator semantics are unchanged from pre-T2 behaviour.
-    // This is intentional: expanding both sides of the Jaccard would
-    // asymmetrically inflate recall and silently shift all baseline metrics.
-    // R4-T1 explicitly preserves this: `keywordsOrTags` is the raw solution
-    // tag list, not the compound-expanded `matchTags` used above.
+    }
+    // Ensemble: TF-IDF (Jaccard) 0.5 + BM25 0.3 + bigram 0.2
     const union = new Set([...promptOrTags, ...keywordsOrTags]).size;
-    const tagScore = weightedMatched / Math.max(union, 1);
+    const tfidfScore = weightedMatched / Math.max(union, 1);
+    // BM25 component: average doc length defaults to 6 tags (typical solution)
+    const avgDocLen = options?.avgDocLength ?? 6;
+    const bm25 = bm25Score(promptOrTags, keywordsOrTags, avgDocLen);
+    // Bigram component (mild boost for partial string matches)
+    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: tagScore * (confidence ?? 1),
+        relevance: ensembleScore * (confidence ?? 1),
         matchedTags: [...intersection, ...partialMatches],
     };
 }
@@ -161,8 +307,8 @@ export function shouldRejectByR4T3Rules(promptTags, matchedTags) {
     // Rule B
     if (matchedTags.length === 1) {
         const tag = matchedTags[0];
-        const literalHit = promptTags.includes(tag)
-            || promptTags.some(pt => {
+        const literalHit = promptTags.includes(tag) ||
+            promptTags.some((pt) => {
                 if (pt.length <= 3 || tag.length <= 3)
                     return false;
                 if (pt.includes(tag) || tag.includes(pt))
@@ -197,7 +343,7 @@ export function shouldRejectByR4T3Rules(promptTags, matchedTags) {
  *     `matchSolutions` behaviour (both scopes could rank). Callers that want
  *     first-wins scope precedence must dedupe on their side.
  */
-function rankCandidates(promptTags, promptLower, solutions) {
+function rankCandidates(promptTags, promptLower, solutions, ensembleWeights) {
     // T2: normalize prompt tags ONCE per query (not once per solution).
     // Pre-T2 this expansion happened inside calculateRelevance and was
     // repeated N times for N solutions — the plan's primary hot-path win.
@@ -232,7 +378,7 @@ function rankCandidates(promptTags, promptLower, solutions) {
     const promptTagsWithBigrams = expandQueryBigrams(maskedPromptTags);
     const normalizedPromptTags = defaultNormalizer.normalizeTerms(promptTagsWithBigrams);
     return solutions
-        .map(sol => {
+        .map((sol) => {
         // R4-T1: solution-side compound-tag expansion. `api-key` becomes
         // {api-key, api, key} so a query token `api` (from "api keys") hits
         // it directly. Computed per solution because each sol.tags is
@@ -245,7 +391,11 @@ function rankCandidates(promptTags, promptLower, solutions) {
         // step (intersection/partialMatches) already uses the masked set
         // via `normalizedPromptTags` — the union must match for score
         // semantics to stay consistent.
-        const result = calculateRelevance(maskedPromptTags, sol.tags, sol.confidence, { normalizedPromptTags, solutionTagsExpanded: solTagsExpanded });
+        const result = calculateRelevance(maskedPromptTags, sol.tags, sol.confidence, {
+            normalizedPromptTags,
+            solutionTagsExpanded: solTagsExpanded,
+            ensembleWeights,
+        });
         // Compute identifier boost FIRST — independent of tag scoring so
         // R4-T3's tag-evidence precision rules below cannot silently drop
         // a candidate that has strong identifier-level evidence.
@@ -272,9 +422,9 @@ function rankCandidates(promptTags, promptLower, solutions) {
         // the `matchedTags.length + matchedIdentifiers.length >= 1` filter.
         let tagRelevance = result.relevance;
         let tagMatches = result.matchedTags;
-        if (matchedIdentifiers.length === 0
-            && tagMatches.length > 0
-            && shouldRejectByR4T3Rules(maskedPromptTags, tagMatches)) {
+        if (matchedIdentifiers.length === 0 &&
+            tagMatches.length > 0 &&
+            shouldRejectByR4T3Rules(maskedPromptTags, tagMatches)) {
             tagRelevance = 0;
             tagMatches = [];
         }
@@ -285,7 +435,7 @@ function rankCandidates(promptTags, promptLower, solutions) {
             matchedIdentifiers,
         };
     })
-        .filter(c => c.matchedTags.length + c.matchedIdentifiers.length >= 1)
+        .filter((c) => c.matchedTags.length + c.matchedIdentifiers.length >= 1)
         .sort((a, b) => b.relevance - a.relevance)
         .slice(0, 5);
 }
@@ -562,7 +712,7 @@ function computeBucketMetrics(queries, solutions) {
  */
 export function evaluateQuery(query, solutions) {
     const promptTags = extractTags(query);
-    return rankCandidates(promptTags, query.toLowerCase(), solutions).map(c => ({
+    return rankCandidates(promptTags, query.toLowerCase(), solutions).map((c) => ({
         name: c.solution.name,
         relevance: c.relevance,
         matchedTags: c.matchedTags,
@@ -588,13 +738,16 @@ export function evaluateSolutionMatcher(fixture) {
     // doesn't drown a small paraphrase bucket but also a single-query bucket
     // doesn't dominate.
     const recallAt5 = combinedTotal > 0
-        ? (positiveM.recallAt5 * positiveM.total + paraphraseM.recallAt5 * paraphraseM.total) / combinedTotal
+        ? (positiveM.recallAt5 * positiveM.total + paraphraseM.recallAt5 * paraphraseM.total) /
+            combinedTotal
         : 0;
     const mrrAt5 = combinedTotal > 0
-        ? (positiveM.mrrAt5 * positiveM.total + paraphraseM.mrrAt5 * paraphraseM.total) / combinedTotal
+        ? (positiveM.mrrAt5 * positiveM.total + paraphraseM.mrrAt5 * paraphraseM.total) /
+            combinedTotal
         : 0;
     const noResultRate = combinedTotal > 0
-        ? (positiveM.noResultRate * positiveM.total + paraphraseM.noResultRate * paraphraseM.total) / combinedTotal
+        ? (positiveM.noResultRate * positiveM.total + paraphraseM.noResultRate * paraphraseM.total) /
+            combinedTotal
         : 0;
     let negAnyResult = 0;
     for (const q of fixture.negative) {
@@ -620,27 +773,64 @@ export function evaluateSolutionMatcher(fixture) {
         },
     };
 }
+// ── Meta-learning: dynamic ensemble weights ──
+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.
+ */
+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;
+}
 export function matchSolutions(prompt, scope, cwd) {
     // Build solution dirs for index cache
-    const dirs = [
-        { dir: ME_SOLUTIONS, scope: 'me' },
-    ];
+    const dirs = [{ dir: ME_SOLUTIONS, scope: 'me' }];
     if (scope.team) {
         dirs.push({ dir: path.join(PACKS_DIR, scope.team.name, 'solutions'), scope: 'team' });
     }
     dirs.push({ dir: path.join(cwd, '.compound', 'solutions'), scope: 'project' });
     // Use cached index (rebuilt only when dirs change)
     const index = getOrBuildIndex(dirs);
-    const allSolutions = index.entries.map(e => ({ ...e }));
+    const allSolutions = index.entries.map((e) => ({ ...e }));
     const promptTags = extractTags(prompt);
     const promptLower = prompt.toLowerCase();
+    // Meta-learning: load tuned weights if available
+    const tunedWeights = loadTunedMatcherWeights();
     // Delegate to shared ranking core. `rankCandidates` is generic so each
     // ranked candidate carries the original `LoadedSolution` reference — no
     // name-based re-lookup, so two scopes sharing a name (e.g. me/foo and
     // project/foo) can both appear in the result without a Map last-wins
     // scope-precedence bug.
-    const ranked = rankCandidates(promptTags, promptLower, allSolutions);
-    return ranked.map(c => ({
+    const ranked = rankCandidates(promptTags, promptLower, allSolutions, tunedWeights);
+    return ranked.map((c) => ({
         name: c.solution.name,
         path: c.solution.filePath,
         scope: c.solution.scope,

package/dist/fgx.js

@@ -3,14 +3,17 @@
  * fgx — forgen --dangerously-skip-permissions 의 단축 명령
  * 모든 인자를 그대로 전달하되, --dangerously-skip-permissions 를 자동 주입
  */
+import { resolveLaunchContext } from './services/session.js';
+import { prepareHarness, isFirstRun } from './core/harness.js';
+import { spawnClaude } from './core/spawn.js';
 const args = process.argv.slice(2);
 // 이미 포함되어 있으면 중복 추가하지 않음
-if (!args.includes('--dangerously-skip-permissions')) {
-    args.unshift('--dangerously-skip-permissions');
+const launchContext = resolveLaunchContext(args);
+const runtime = launchContext.runtime;
+const launchArgs = [...launchContext.args];
+if (!launchArgs.includes('--dangerously-skip-permissions')) {
+    launchArgs.unshift('--dangerously-skip-permissions');
 }
-// cli.ts 의 main 로직을 재사용
-import { prepareHarness, isFirstRun } from './core/harness.js';
-import { spawnClaude } from './core/spawn.js';
 async function main() {
     // Security warning — fgx bypasses all Claude Code permission checks
     console.warn('\n  ⚠  fgx: ALL permission checks are disabled (--dangerously-skip-permissions)');
@@ -23,7 +26,7 @@ async function main() {
         console.log('  Creating ~/.forgen/ directory and default philosophy.');
         console.log('  Run `forgen onboarding` afterwards to complete personalization.\n');
     }
-    const context = await prepareHarness(process.cwd());
+    const context = await prepareHarness(process.cwd(), { runtime });
     if (firstRun) {
         console.log('  [Done] Initial setup complete.\n');
     }
@@ -33,8 +36,9 @@ async function main() {
         console.log(`[forgen] Trust: ${v1.session.effective_trust_policy}`);
     }
     console.log('[forgen] Mode: dangerously-skip-permissions');
-    console.log('[forgen] Starting Claude Code...\n');
-    await spawnClaude(args, context);
+    const runtimeLabel = runtime === 'codex' ? 'Codex' : 'Claude';
+    console.log(`[forgen] Starting ${runtimeLabel}...\n`);
+    await spawnClaude(launchArgs, context, runtime);
 }
 main().catch((err) => {
     console.error('[forgen] Error:', err instanceof Error ? err.message : err);

package/dist/hooks/context-guard.d.ts

@@ -19,6 +19,21 @@ export declare function shouldWarn(contextPercent: {
     charsThreshold?: number;
     cooldownMs?: number;
 }): boolean;
+/** auto-compact 트리거 여부 판정 (순수 함수) */
+export declare function shouldAutoCompact(state: {
+    totalChars: number;
+    lastAutoCompactAt: number;
+}, thresholds?: {
+    charsThreshold?: number;
+    cooldownMs?: number;
+}): boolean;
+/** auto-compact 지시 메시지 생성 (순수 함수) */
+export declare function buildAutoCompactMessage(totalChars: number): string;
 /** 경고 메시지 생성 (순수 함수) */
 export declare function buildContextWarningMessage(promptCount: number, totalChars: number): string;
 export declare function main(): Promise<void>;
+/**
+ * forge-loop 활성 시 미완료 스토리가 있으면 Stop을 차단하고 지속 메시지 주입.
+ * OMC의 persistent-mode.cjs 패턴 참고.
+ */
+export declare function checkForgeLoopActive(): string | null;