@wooojin/forgen 0.2.1 → 0.3.1

package/dist/engine/meta-learning/extraction-tuner.js

@@ -0,0 +1,99 @@
+/**
+ * Forgen Meta-Learning — Extraction Tuner (Feature 5)
+ *
+ * Tracks which solution types (pattern, solution, decision, etc.) have the
+ * best reflected/injected ratio and biases future extraction toward those types.
+ *
+ * Uses Laplace smoothing (pseudo-count +1) to prevent zero weights
+ * for underrepresented types.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ME_SOLUTIONS, META_LEARNING_DIR } from '../../core/paths.js';
+import { atomicWriteJSON } from '../../hooks/shared/atomic-write.js';
+import { parseFrontmatterOnly } from '../solution-format.js';
+const BIAS_PATH = path.join(META_LEARNING_DIR, 'extraction-bias.json');
+const ALL_TYPES = [
+    'pattern',
+    'solution',
+    'decision',
+    'troubleshoot',
+    'anti-pattern',
+    'convention',
+];
+function computeTypeEffectiveness() {
+    const stats = {};
+    for (const t of ALL_TYPES) {
+        stats[t] = { injected: 0, reflected: 0, ratio: 0 };
+    }
+    let totalSolutions = 0;
+    const typesWithData = new Set();
+    try {
+        if (!fs.existsSync(ME_SOLUTIONS))
+            return { stats, totalSolutions: 0, typeCount: 0 };
+        const files = fs.readdirSync(ME_SOLUTIONS).filter((f) => f.endsWith('.md'));
+        for (const file of files) {
+            try {
+                const content = fs.readFileSync(path.join(ME_SOLUTIONS, file), 'utf-8');
+                const fm = parseFrontmatterOnly(content);
+                if (!fm || fm.status === 'retired')
+                    continue;
+                totalSolutions++;
+                const type = fm.type;
+                if (!stats[type])
+                    stats[type] = { injected: 0, reflected: 0, ratio: 0 };
+                stats[type].injected += fm.evidence.injected;
+                stats[type].reflected += fm.evidence.reflected;
+                if (fm.evidence.injected > 0)
+                    typesWithData.add(type);
+            }
+            catch { }
+        }
+    }
+    catch {
+        /* empty */
+    }
+    // Compute ratios
+    for (const type of Object.keys(stats)) {
+        stats[type].ratio = stats[type].injected > 0 ? stats[type].reflected / stats[type].injected : 0;
+    }
+    return { stats, totalSolutions, typeCount: typesWithData.size };
+}
+/**
+ * Compute extraction bias based on type effectiveness.
+ * Returns null if cold-start conditions are not met.
+ */
+export function computeExtractionBias(config) {
+    const { stats, totalSolutions, typeCount } = computeTypeEffectiveness();
+    // Cold-start check
+    if (totalSolutions < config.coldStart.minSolutionsForExtraction || typeCount < 3) {
+        return null;
+    }
+    // Laplace-smoothed weights: ratio + 1 pseudo-count per type
+    const rawWeights = {};
+    let sum = 0;
+    for (const type of ALL_TYPES) {
+        const w = stats[type].ratio + 1 / ALL_TYPES.length; // Laplace smoothing
+        rawWeights[type] = w;
+        sum += w;
+    }
+    // Normalize to sum = 1.0, cap individual type at 0.5
+    const typeWeights = {};
+    for (const type of ALL_TYPES) {
+        typeWeights[type] = Math.min(0.5, Math.round((rawWeights[type] / sum) * 1000) / 1000);
+    }
+    // Re-normalize after capping
+    const cappedSum = Object.values(typeWeights).reduce((s, v) => s + v, 0);
+    if (cappedSum > 0) {
+        for (const type of ALL_TYPES) {
+            typeWeights[type] = Math.round((typeWeights[type] / cappedSum) * 1000) / 1000;
+        }
+    }
+    const result = {
+        typeWeights,
+        updatedAt: new Date().toISOString(),
+        sampleSize: totalSolutions,
+    };
+    atomicWriteJSON(BIAS_PATH, result, { pretty: true });
+    return result;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Forgen Meta-Learning — Matcher Weight Tuner (Feature 2)
+ *
+ * Analyzes which scoring component (TF-IDF, BM25, Bigram) best discriminates
+ * reflected vs. non-reflected solutions and adjusts ensemble weights.
+ *
+ * Algorithm:
+ *   1. Load all non-retired solutions with evidence.injected > 0
+ *   2. Partition into "effective" (reflected/injected > median) vs "ineffective"
+ *   3. For each component: compute discrimination ratio (effective_mean / ineffective_mean)
+ *   4. Shift weights toward the component with highest discrimination
+ *   5. Apply guardrails: clamp [floor, ceiling], max delta per cycle, normalize to 1.0
+ *
+ * Cold-start: requires 10+ solutions with injected > 0, 3+ with reflected > 0.
+ */
+import type { MatcherWeights, MetaLearningConfig } from './types.js';
+/**
+ * Tune matcher ensemble weights based on solution effectiveness data.
+ * Returns null if cold-start conditions are not met.
+ */
+export declare function tuneMatcherWeights(config: MetaLearningConfig): MatcherWeights | null;

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

@@ -0,0 +1,151 @@
+/**
+ * Forgen Meta-Learning — Matcher Weight Tuner (Feature 2)
+ *
+ * Analyzes which scoring component (TF-IDF, BM25, Bigram) best discriminates
+ * reflected vs. non-reflected solutions and adjusts ensemble weights.
+ *
+ * Algorithm:
+ *   1. Load all non-retired solutions with evidence.injected > 0
+ *   2. Partition into "effective" (reflected/injected > median) vs "ineffective"
+ *   3. For each component: compute discrimination ratio (effective_mean / ineffective_mean)
+ *   4. Shift weights toward the component with highest discrimination
+ *   5. Apply guardrails: clamp [floor, ceiling], max delta per cycle, normalize to 1.0
+ *
+ * Cold-start: requires 10+ solutions with injected > 0, 3+ with reflected > 0.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ME_SOLUTIONS, META_LEARNING_DIR } from '../../core/paths.js';
+import { atomicWriteJSON, safeReadJSON } from '../../hooks/shared/atomic-write.js';
+import { parseFrontmatterOnly } from '../solution-format.js';
+import { DEFAULT_MATCHER_WEIGHTS } from './types.js';
+const WEIGHTS_PATH = path.join(META_LEARNING_DIR, 'matcher-weights.json');
+function loadSolutionEffectivenessData() {
+    try {
+        if (!fs.existsSync(ME_SOLUTIONS))
+            return [];
+        const files = fs.readdirSync(ME_SOLUTIONS).filter((f) => f.endsWith('.md'));
+        const data = [];
+        for (const file of files) {
+            try {
+                const content = fs.readFileSync(path.join(ME_SOLUTIONS, file), 'utf-8');
+                const fm = parseFrontmatterOnly(content);
+                if (!fm || fm.status === 'retired')
+                    continue;
+                if (!fm.evidence || fm.evidence.injected <= 0)
+                    continue;
+                data.push({
+                    name: fm.name,
+                    injected: fm.evidence.injected,
+                    reflected: fm.evidence.reflected,
+                    ratio: fm.evidence.reflected / fm.evidence.injected,
+                    tags: fm.tags ?? [],
+                });
+            }
+            catch { }
+        }
+        return data;
+    }
+    catch {
+        return [];
+    }
+}
+function loadCurrentWeights() {
+    return safeReadJSON(WEIGHTS_PATH, null);
+}
+function saveWeights(weights) {
+    atomicWriteJSON(WEIGHTS_PATH, weights, { pretty: true });
+}
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+function clampWeight(value, floor, ceiling) {
+    return Math.max(floor, Math.min(ceiling, value));
+}
+function normalizeWeights(w) {
+    const sum = w.tfidf + w.bm25 + w.bigram;
+    if (sum <= 0)
+        return { ...DEFAULT_MATCHER_WEIGHTS };
+    return {
+        tfidf: Math.round((w.tfidf / sum) * 1000) / 1000,
+        bm25: Math.round((w.bm25 / sum) * 1000) / 1000,
+        bigram: Math.round((w.bigram / sum) * 1000) / 1000,
+    };
+}
+/**
+ * Tune matcher ensemble weights based on solution effectiveness data.
+ * Returns null if cold-start conditions are not met.
+ */
+export function tuneMatcherWeights(config) {
+    const data = loadSolutionEffectivenessData();
+    // Cold-start check
+    const injectedCount = data.length;
+    const reflectedCount = data.filter((d) => d.reflected > 0).length;
+    if (injectedCount < config.coldStart.minSolutionsForMatcher || reflectedCount < 3) {
+        return null;
+    }
+    // Partition by median effectiveness ratio
+    const ratios = data.map((d) => d.ratio);
+    const medianRatio = median(ratios);
+    const effective = data.filter((d) => d.ratio > medianRatio);
+    const ineffective = data.filter((d) => d.ratio <= medianRatio);
+    if (effective.length === 0 || ineffective.length === 0)
+        return null;
+    // Compute discrimination signals per component.
+    // We use tag count as a proxy for component contribution:
+    //   - TF-IDF benefits from more exact tag matches
+    //   - BM25 benefits from longer documents (more tags)
+    //   - Bigram benefits from partial/fuzzy matches (shorter tags)
+    //
+    // Since we can't replay the exact scoring without the original queries,
+    // we use statistical proxies from the solution characteristics.
+    const avgTagsEffective = effective.reduce((s, d) => s + d.tags.length, 0) / effective.length;
+    const avgTagsIneffective = ineffective.reduce((s, d) => s + d.tags.length, 0) / ineffective.length;
+    // Discrimination signals:
+    //   - If effective solutions have more tags → BM25 (length normalization) discriminates well
+    //   - If effective solutions have fewer tags → TF-IDF (exact match) discriminates well
+    //   - Bigram gets a boost proportional to how many effective solutions have short tags
+    const tagRatio = avgTagsEffective / Math.max(avgTagsIneffective, 1);
+    const shortTagEffective = effective.filter((d) => d.tags.some((t) => t.length <= 5)).length / effective.length;
+    // Raw discrimination scores (higher = more discriminating)
+    const tfidfSignal = tagRatio < 1 ? 1.2 : 1.0; // exact match helps when effective have fewer tags
+    const bm25Signal = tagRatio > 1 ? 1.2 : 1.0; // length normalization helps when effective have more tags
+    const bigramSignal = shortTagEffective > 0.5 ? 1.15 : 0.95; // fuzzy match helps with short tags
+    // Load current weights or defaults
+    const current = loadCurrentWeights();
+    const currentW = current
+        ? { tfidf: current.tfidf, bm25: current.bm25, bigram: current.bigram }
+        : { ...DEFAULT_MATCHER_WEIGHTS };
+    // Compute target weights from discrimination signals
+    const signalSum = tfidfSignal + bm25Signal + bigramSignal;
+    const targetW = {
+        tfidf: tfidfSignal / signalSum,
+        bm25: bm25Signal / signalSum,
+        bigram: bigramSignal / signalSum,
+    };
+    // Apply max delta per cycle guardrail
+    const { maxWeightDelta, weightFloor, weightCeiling } = config.guardrails;
+    const newW = {
+        tfidf: clampWeight(currentW.tfidf +
+            Math.max(-maxWeightDelta, Math.min(maxWeightDelta, targetW.tfidf - currentW.tfidf)), weightFloor, weightCeiling),
+        bm25: clampWeight(currentW.bm25 +
+            Math.max(-maxWeightDelta, Math.min(maxWeightDelta, targetW.bm25 - currentW.bm25)), weightFloor, weightCeiling),
+        bigram: clampWeight(currentW.bigram +
+            Math.max(-maxWeightDelta, Math.min(maxWeightDelta, targetW.bigram - currentW.bigram)), weightFloor, weightCeiling),
+    };
+    // Normalize to sum = 1.0
+    const normalized = normalizeWeights(newW);
+    const result = {
+        ...normalized,
+        updatedAt: new Date().toISOString(),
+        sampleSize: data.length,
+        version: (current?.version ?? 0) + 1,
+        defaults: { ...DEFAULT_MATCHER_WEIGHTS },
+    };
+    saveWeights(result);
+    return result;
+}

package/dist/engine/meta-learning/runner.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Forgen Meta-Learning — Runner (Orchestrator)
+ *
+ * Coordinates execution of all meta-learning features at session end.
+ * Called from auto-compound-runner.ts as Step 5.
+ *
+ * Design:
+ *   - Each feature is independently gated by config + cold-start check
+ *   - Failures in one feature do not block others (fail-open per feature)
+ *   - Session quality scoring always runs first (feeds other features)
+ */
+import { type MetaLearningConfig, type MetaLearningResult } from './types.js';
+export declare function loadMetaLearningConfig(): MetaLearningConfig;
+export declare function runMetaLearning(sessionId: string, cwd: string): MetaLearningResult;

package/dist/engine/meta-learning/runner.js

@@ -0,0 +1,90 @@
+/**
+ * Forgen Meta-Learning — Runner (Orchestrator)
+ *
+ * Coordinates execution of all meta-learning features at session end.
+ * Called from auto-compound-runner.ts as Step 5.
+ *
+ * Design:
+ *   - Each feature is independently gated by config + cold-start check
+ *   - Failures in one feature do not block others (fail-open per feature)
+ *   - Session quality scoring always runs first (feeds other features)
+ */
+import * as path from 'node:path';
+import { safeReadJSON } from '../../hooks/shared/atomic-write.js';
+import { computeAdaptiveThresholds } from './adaptive-thresholds.js';
+import { computeExtractionBias } from './extraction-tuner.js';
+import { tuneMatcherWeights } from './matcher-weight-tuner.js';
+import { checkScopePromotions, updateProjectUsageMap } from './scope-promoter.js';
+import { saveSessionQuality, scoreSession } from './session-quality-scorer.js';
+import { DEFAULT_CONFIG } from './types.js';
+export function loadMetaLearningConfig() {
+    const hookConfigPath = path.join(process.env.HOME ?? process.env.USERPROFILE ?? '', '.forgen', 'hook-config.json');
+    const hookConfig = safeReadJSON(hookConfigPath, {});
+    const metaSection = hookConfig?.['meta-learning'];
+    if (!metaSection)
+        return DEFAULT_CONFIG;
+    return {
+        enabled: metaSection.enabled ?? DEFAULT_CONFIG.enabled,
+        features: { ...DEFAULT_CONFIG.features, ...metaSection.features },
+        coldStart: { ...DEFAULT_CONFIG.coldStart, ...metaSection.coldStart },
+        guardrails: { ...DEFAULT_CONFIG.guardrails, ...metaSection.guardrails },
+    };
+}
+export function runMetaLearning(sessionId, cwd) {
+    const config = loadMetaLearningConfig();
+    if (!config.enabled) {
+        return { skipped: true, reason: 'meta-learning disabled in config' };
+    }
+    const result = {};
+    // Feature 1: Session Quality Scorer (always first — feeds other features)
+    if (config.features.sessionQualityScorer) {
+        try {
+            const score = scoreSession(sessionId);
+            if (score) {
+                saveSessionQuality(score);
+                result.qualityScore = score;
+            }
+        }
+        catch (e) {
+            process.stderr.write(`[forgen-meta] quality scorer: ${e instanceof Error ? e.message : String(e)}\n`);
+        }
+    }
+    // Feature 2: Matcher Weight Tuning
+    if (config.features.matcherWeightTuning) {
+        try {
+            result.matcherWeights = tuneMatcherWeights(config);
+        }
+        catch (e) {
+            process.stderr.write(`[forgen-meta] matcher tuning: ${e instanceof Error ? e.message : String(e)}\n`);
+        }
+    }
+    // Feature 3: Scope Auto-Promotion
+    if (config.features.scopeAutoPromotion) {
+        try {
+            updateProjectUsageMap(sessionId, cwd, config);
+            result.scopePromotions = checkScopePromotions(config);
+        }
+        catch (e) {
+            process.stderr.write(`[forgen-meta] scope promotion: ${e instanceof Error ? e.message : String(e)}\n`);
+        }
+    }
+    // Feature 4: Adaptive Thresholds
+    if (config.features.adaptiveThresholds) {
+        try {
+            result.thresholds = computeAdaptiveThresholds(config);
+        }
+        catch (e) {
+            process.stderr.write(`[forgen-meta] adaptive thresholds: ${e instanceof Error ? e.message : String(e)}\n`);
+        }
+    }
+    // Feature 5: Extraction Tuning
+    if (config.features.extractionTuning) {
+        try {
+            result.extractionBias = computeExtractionBias(config);
+        }
+        catch (e) {
+            process.stderr.write(`[forgen-meta] extraction tuning: ${e instanceof Error ? e.message : String(e)}\n`);
+        }
+    }
+    return result;
+}

package/dist/engine/meta-learning/scope-promoter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Forgen Meta-Learning — Scope Promoter (Feature 3)
+ *
+ * Tracks cross-project solution usage and auto-promotes solutions
+ * from scope:'me' to scope:'universal' when used in 3+ distinct projects.
+ *
+ * Data flow:
+ *   1. At session end: read injection-cache for injected solutions + session cwd
+ *   2. Record (solution, project) pair in project-usage-map.json
+ *   3. Check if any solution has 3+ distinct projects → mutate frontmatter
+ */
+import type { MetaLearningConfig } from './types.js';
+/**
+ * Record which project (cwd) each injected solution was used in.
+ */
+export declare function updateProjectUsageMap(sessionId: string, cwd: string, _config: MetaLearningConfig): void;
+/**
+ * Check for solutions that should be promoted to universal scope.
+ * Returns names of promoted solutions.
+ */
+export declare function checkScopePromotions(config: MetaLearningConfig): string[];

package/dist/engine/meta-learning/scope-promoter.js

@@ -0,0 +1,84 @@
+/**
+ * Forgen Meta-Learning — Scope Promoter (Feature 3)
+ *
+ * Tracks cross-project solution usage and auto-promotes solutions
+ * from scope:'me' to scope:'universal' when used in 3+ distinct projects.
+ *
+ * Data flow:
+ *   1. At session end: read injection-cache for injected solutions + session cwd
+ *   2. Record (solution, project) pair in project-usage-map.json
+ *   3. Check if any solution has 3+ distinct projects → mutate frontmatter
+ */
+import * as path from 'node:path';
+import { META_LEARNING_DIR, STATE_DIR } from '../../core/paths.js';
+import { atomicWriteJSON, safeReadJSON } from '../../hooks/shared/atomic-write.js';
+import { mutateSolutionByName } from '../solution-writer.js';
+const USAGE_MAP_PATH = path.join(META_LEARNING_DIR, 'project-usage-map.json');
+function sanitizeId(id) {
+    return id.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+function loadUsageMap() {
+    return safeReadJSON(USAGE_MAP_PATH, { solutions: {} });
+}
+function saveUsageMap(map) {
+    atomicWriteJSON(USAGE_MAP_PATH, map, { pretty: true });
+}
+function loadInjectedSolutions(sessionId) {
+    // Try solution-cache (primary) and injection-cache (fallback)
+    for (const prefix of ['solution-cache', 'injection-cache']) {
+        const cachePath = path.join(STATE_DIR, `${prefix}-${sanitizeId(sessionId)}.json`);
+        const data = safeReadJSON(cachePath, {});
+        if (data.injected && data.injected.length > 0)
+            return data.injected;
+    }
+    return [];
+}
+/**
+ * Record which project (cwd) each injected solution was used in.
+ */
+export function updateProjectUsageMap(sessionId, cwd, _config) {
+    const injected = loadInjectedSolutions(sessionId);
+    if (injected.length === 0)
+        return;
+    // Normalize cwd to project root name for privacy
+    const projectKey = path.basename(cwd);
+    const map = loadUsageMap();
+    let changed = false;
+    for (const name of injected) {
+        if (!map.solutions[name]) {
+            map.solutions[name] = { projects: [projectKey], updatedAt: new Date().toISOString() };
+            changed = true;
+        }
+        else if (!map.solutions[name].projects.includes(projectKey)) {
+            map.solutions[name].projects.push(projectKey);
+            map.solutions[name].updatedAt = new Date().toISOString();
+            changed = true;
+        }
+    }
+    if (changed)
+        saveUsageMap(map);
+}
+/**
+ * Check for solutions that should be promoted to universal scope.
+ * Returns names of promoted solutions.
+ */
+export function checkScopePromotions(config) {
+    const map = loadUsageMap();
+    const minProjects = config.coldStart.minProjectsForScope;
+    const promoted = [];
+    for (const [name, entry] of Object.entries(map.solutions)) {
+        if (entry.projects.length < minProjects)
+            continue;
+        const success = mutateSolutionByName(name, (sol) => {
+            if (sol.frontmatter.scope === 'universal')
+                return false; // already promoted
+            if (sol.frontmatter.scope !== 'me')
+                return false; // only promote from 'me'
+            sol.frontmatter.scope = 'universal';
+            return true;
+        });
+        if (success)
+            promoted.push(name);
+    }
+    return promoted;
+}

package/dist/engine/meta-learning/session-quality-scorer.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Forgen Meta-Learning — Session Quality Scorer (Feature 1)
+ *
+ * Joins existing data sources to compute a per-session quality score.
+ * This score feeds other meta-learning features (matcher tuning, thresholds).
+ *
+ * Data sources:
+ *   - injection-cache-{sessionId}.json → injected solutions
+ *   - modified-files-{sessionId}.json  → drift state
+ *   - implicit-feedback.jsonl          → revert/drift events
+ *   - me/behavior/*.json              → correction evidence
+ *   - state/sessions/{sessionId}.json  → session metadata
+ */
+import type { SessionQualityScore } from './types.js';
+interface InjectionCacheData {
+    injected: string[];
+    totalInjectedChars: number;
+    updatedAt: string;
+    /** Tag snapshot per solution (backfill feature) */
+    tags?: Record<string, string[]>;
+}
+interface DriftState {
+    sessionId: string;
+    totalEdits: number;
+    totalReverts: number;
+    ewmaEditRate: number;
+    ewmaRevertRate: number;
+    lastWarningAt: number | null;
+    lastCriticalAt: number | null;
+    hardCapReached: boolean;
+}
+interface ImplicitFeedbackEntry {
+    type: string;
+    sessionId?: string;
+    at: string;
+    [key: string]: unknown;
+}
+export declare function loadInjectionCache(sessionId: string): InjectionCacheData | null;
+export declare function loadDriftState(sessionId: string): DriftState | null;
+export declare function loadImplicitFeedback(sessionId: string): ImplicitFeedbackEntry[];
+export declare function loadSessionCorrections(sessionId: string): number;
+/**
+ * Compute overall session quality score (0-100, higher = better).
+ *
+ * Formula:
+ *   100
+ *   - (correctionRate × 15)        // each correction/prompt penalizes 15pts
+ *   - (driftScore × 0.3)           // drift 0-100 maps to 0-30 penalty
+ *   - (revertCount × 5)            // each revert penalizes 5pts
+ *   + (solutionEffectiveness × 20) // good solution usage boosts 0-20pts
+ */
+export declare function computeOverallScore(correctionRate: number, driftScore: number, revertCount: number, solutionEffectiveness: number): number;
+/**
+ * Score a session's quality by joining all available data sources.
+ * Returns null if insufficient data (no session state found).
+ */
+export declare function scoreSession(sessionId: string): SessionQualityScore | null;
+export declare function saveSessionQuality(score: SessionQualityScore, baseDir?: string): void;
+export declare function loadSessionQuality(sessionId: string, baseDir?: string): SessionQualityScore | null;
+export declare function loadRecentQualityScores(limit?: number, baseDir?: string): SessionQualityScore[];
+export {};