@wooojin/forgen 0.2.1 → 0.3.1

package/dist/engine/solution-fixup.js

@@ -0,0 +1,116 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { DEFAULT_EVIDENCE } from './solution-format.js';
+import { diagnoseFromRawContent } from './solution-quarantine.js';
+import { createLogger } from '../core/logger.js';
+const log = createLogger('solution-fixup');
+/**
+ * Attempt to repair known-safe frontmatter defects.
+ *
+ * Handled defects (pre-0.3.1 schema drift, observed on 5 auto-extracted
+ * solutions from 2026-04-10):
+ *   - `extractedBy` missing → add `extractedBy: auto`
+ *   - `evidence` block missing → add `DEFAULT_EVIDENCE`
+ *
+ * All other validation errors (bad scope, non-numeric confidence, etc.)
+ * are surfaced in `remaining_errors` and the file is left untouched —
+ * those require human judgement, not a mechanical default.
+ *
+ * `dryRun: true` (default) reports what would change without writing.
+ */
+export function fixupSolutions(solutionsDir, opts = {}) {
+    const dryRun = opts.dryRun !== false;
+    const result = { scanned: 0, fixed: 0, untouched: 0, unfixable: 0, reports: [] };
+    if (!fs.existsSync(solutionsDir))
+        return result;
+    const files = fs.readdirSync(solutionsDir).filter((f) => f.endsWith('.md'));
+    for (const file of files) {
+        const filePath = path.join(solutionsDir, file);
+        result.scanned++;
+        let content;
+        try {
+            content = fs.readFileSync(filePath, 'utf-8');
+        }
+        catch {
+            result.unfixable++;
+            continue;
+        }
+        const errors = diagnoseFromRawContent(content);
+        if (errors.length === 0) {
+            result.untouched++;
+            continue;
+        }
+        const fix = tryFix(content, errors);
+        result.reports.push({
+            path: filePath,
+            changed: fix.changed,
+            added: fix.added,
+            remaining_errors: fix.remaining,
+        });
+        if (fix.changed && fix.remaining.length === 0) {
+            if (!dryRun) {
+                try {
+                    fs.writeFileSync(filePath, fix.content);
+                    log.debug(`fixed: ${filePath} (${fix.added.join(', ')})`);
+                }
+                catch (e) {
+                    log.debug(`write failed: ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
+                    result.unfixable++;
+                    continue;
+                }
+            }
+            result.fixed++;
+        }
+        else {
+            result.unfixable++;
+        }
+    }
+    return result;
+}
+function tryFix(content, initialErrors) {
+    const trimmed = content.trimStart();
+    const added = [];
+    if (!trimmed.startsWith('---')) {
+        return { changed: false, added, remaining: initialErrors, content };
+    }
+    const endIdx = trimmed.indexOf('---', 3);
+    if (endIdx === -1) {
+        return { changed: false, added, remaining: initialErrors, content };
+    }
+    const leadingWs = content.slice(0, content.length - trimmed.length);
+    const fmRaw = trimmed.slice(3, endIdx);
+    const body = trimmed.slice(endIdx + 3);
+    let fm;
+    try {
+        const parsed = yaml.load(fmRaw, { schema: yaml.JSON_SCHEMA });
+        if (parsed == null || typeof parsed !== 'object') {
+            return { changed: false, added, remaining: initialErrors, content };
+        }
+        fm = parsed;
+    }
+    catch {
+        return { changed: false, added, remaining: initialErrors, content };
+    }
+    if (fm.extractedBy !== 'auto' && fm.extractedBy !== 'manual') {
+        fm.extractedBy = 'auto';
+        added.push('extractedBy: auto');
+    }
+    if (fm.evidence == null || typeof fm.evidence !== 'object') {
+        fm.evidence = { ...DEFAULT_EVIDENCE };
+        added.push('evidence: default');
+    }
+    if (fm.supersedes === undefined) {
+        fm.supersedes = null;
+        added.push('supersedes: null');
+    }
+    const newFmRaw = yaml.dump(fm, { lineWidth: 120, noRefs: true, sortKeys: false });
+    const rebuilt = `${leadingWs}---\n${newFmRaw}---${body}`;
+    const remaining = diagnoseFromRawContent(rebuilt);
+    return {
+        changed: added.length > 0,
+        added,
+        remaining,
+        content: rebuilt,
+    };
+}

package/dist/engine/solution-format.d.ts

@@ -13,7 +13,7 @@ export interface SolutionFrontmatter {
     status: SolutionStatus;
     confidence: number;
     type: SolutionType;
-    scope: 'me' | 'team' | 'project';
+    scope: 'me' | 'team' | 'project' | 'universal';
     tags: string[];
     identifiers: string[];
     evidence: SolutionEvidence;
@@ -33,7 +33,7 @@ export interface SolutionIndexEntry {
     status: SolutionStatus;
     confidence: number;
     type: SolutionType;
-    scope: 'me' | 'team' | 'project';
+    scope: 'me' | 'team' | 'project' | 'universal';
     tags: string[];
     /**
      * Pre-expanded tag set, computed at index build time via the term normalizer.
@@ -60,6 +60,14 @@ export declare const DEFAULT_EVIDENCE: SolutionEvidence;
 export declare function slugify(text: string): string;
 /** Runtime type guard for SolutionFrontmatter */
 export declare function validateFrontmatter(fm: unknown): fm is SolutionFrontmatter;
+/**
+ * Return a list of validation errors for a parsed frontmatter object.
+ *
+ * Empty array = valid. Non-empty = each entry describes one missing/wrong
+ * field. Callers that only need a boolean should use `validateFrontmatter`.
+ * Slow path (quarantine logging) uses this to produce actionable diagnostics.
+ */
+export declare function diagnoseFrontmatter(fm: unknown): string[];
 /** Parse YAML frontmatter from solution file content */
 export declare function parseFrontmatterOnly(content: string): SolutionFrontmatter | null;
 /** Parse a full V3 solution file into its components */

package/dist/engine/solution-format.js

@@ -1,9 +1,26 @@
 import yaml from 'js-yaml';
 export const DEFAULT_EVIDENCE = {
-    injected: 0, reflected: 0, negative: 0, sessions: 0, reExtracted: 0,
+    injected: 0,
+    reflected: 0,
+    negative: 0,
+    sessions: 0,
+    reExtracted: 0,
 };
-const VALID_STATUSES = ['experiment', 'candidate', 'verified', 'mature', 'retired'];
-const VALID_TYPES = ['pattern', 'solution', 'decision', 'troubleshoot', 'anti-pattern', 'convention'];
+const VALID_STATUSES = [
+    'experiment',
+    'candidate',
+    'verified',
+    'mature',
+    'retired',
+];
+const VALID_TYPES = [
+    'pattern',
+    'solution',
+    'decision',
+    'troubleshoot',
+    'anti-pattern',
+    'convention',
+];
 // ── Helpers ──
 export function slugify(text) {
     const slug = text
@@ -18,43 +35,58 @@ export function slugify(text) {
 // ── Validation ──
 /** Runtime type guard for SolutionFrontmatter */
 export function validateFrontmatter(fm) {
-    if (fm == null || typeof fm !== 'object')
-        return false;
+    return diagnoseFrontmatter(fm).length === 0;
+}
+/**
+ * Return a list of validation errors for a parsed frontmatter object.
+ *
+ * Empty array = valid. Non-empty = each entry describes one missing/wrong
+ * field. Callers that only need a boolean should use `validateFrontmatter`.
+ * Slow path (quarantine logging) uses this to produce actionable diagnostics.
+ */
+export function diagnoseFrontmatter(fm) {
+    const errors = [];
+    if (fm == null || typeof fm !== 'object') {
+        errors.push('frontmatter is not an object');
+        return errors;
+    }
     const o = fm;
     if (typeof o.name !== 'string')
-        return false;
+        errors.push('name: must be string');
     if (typeof o.version !== 'number' || o.version <= 0)
-        return false;
+        errors.push('version: must be positive number');
     if (typeof o.status !== 'string' || !VALID_STATUSES.includes(o.status))
-        return false;
+        errors.push(`status: must be one of ${VALID_STATUSES.join('|')}`);
     if (typeof o.confidence !== 'number' || o.confidence < 0 || o.confidence > 1)
-        return false;
+        errors.push('confidence: must be number in [0,1]');
     if (typeof o.type !== 'string' || !VALID_TYPES.includes(o.type))
-        return false;
-    if (o.scope !== 'me' && o.scope !== 'team' && o.scope !== 'project')
-        return false;
+        errors.push(`type: must be one of ${VALID_TYPES.join('|')}`);
+    if (o.scope !== 'me' && o.scope !== 'team' && o.scope !== 'project' && o.scope !== 'universal')
+        errors.push('scope: must be me|team|project|universal');
     if (!Array.isArray(o.tags) || !o.tags.every((t) => typeof t === 'string'))
-        return false;
+        errors.push('tags: must be string[]');
     if (!Array.isArray(o.identifiers) || !o.identifiers.every((t) => typeof t === 'string'))
-        return false;
+        errors.push('identifiers: must be string[]');
     if (typeof o.created !== 'string')
-        return false;
+        errors.push('created: must be string');
     if (typeof o.updated !== 'string')
-        return false;
+        errors.push('updated: must be string');
     if (o.supersedes !== null && typeof o.supersedes !== 'string')
-        return false;
+        errors.push('supersedes: must be string or null');
     if (o.extractedBy !== 'auto' && o.extractedBy !== 'manual')
-        return false;
-    // evidence
-    if (o.evidence == null || typeof o.evidence !== 'object')
-        return false;
-    const ev = o.evidence;
-    const evFields = ['injected', 'reflected', 'negative', 'sessions', 'reExtracted'];
-    for (const f of evFields) {
-        if (typeof ev[f] !== 'number')
-            return false;
+        errors.push('extractedBy: missing or not auto|manual');
+    if (o.evidence == null || typeof o.evidence !== 'object') {
+        errors.push('evidence: block missing');
     }
-    return true;
+    else {
+        const ev = o.evidence;
+        const evFields = ['injected', 'reflected', 'negative', 'sessions', 'reExtracted'];
+        for (const f of evFields) {
+            if (typeof ev[f] !== 'number')
+                errors.push(`evidence.${f}: must be number`);
+        }
+    }
+    return errors;
 }
 // ── Parsing ──
 /** Parse YAML frontmatter from solution file content */
@@ -122,7 +154,11 @@ export function parseSolutionV3(content) {
 // ── Serialization ──
 /** Serialize a SolutionV3 to a markdown string with YAML frontmatter */
 export function serializeSolutionV3(solution) {
-    const yamlStr = yaml.dump(solution.frontmatter, { lineWidth: -1, quotingType: '"', schema: yaml.JSON_SCHEMA });
+    const yamlStr = yaml.dump(solution.frontmatter, {
+        lineWidth: -1,
+        quotingType: '"',
+        schema: yaml.JSON_SCHEMA,
+    });
     return `---\n${yamlStr}---\n\n## Context\n${solution.context}\n\n## Content\n${solution.content}\n`;
 }
 // ── Format Detection ──
@@ -149,34 +185,207 @@ export function isV1Format(content) {
 /** 한국어 불용어 — 태그로 의미 없는 일반 단어 */
 const KO_STOPWORDS = new Set([
     // 일반 불용어
-    '적용', '패턴', '모든', '같은', '발견', '다른', '사용', '경우', '위해',
-    '통해', '대한', '이후', '때문', '하는', '있는', '없는', '되는', '관련',
-    '해야', '하고', '있다', '없다', '한다', '이런', '그런', '저런', '매우',
-    '항상', '모두', '각각', '대해', '여러', '시작', '그것', '이것', '저것',
-    '아주', '정말', '너무', '많이', '자주', '가장', '먼저', '이미', '아직',
-    '그냥', '바로', '다시', '함께', '위한', '따라', '부분', '전체', '방법',
-    '내용', '결과', '문제', '시점', '설정', '작업', '확인', '수행', '처리',
-    '기본', '추가', '변경', '제거', '포함', '생성', '실행', '완료', '필요',
+    '적용',
+    '패턴',
+    '모든',
+    '같은',
+    '발견',
+    '다른',
+    '사용',
+    '경우',
+    '위해',
+    '통해',
+    '대한',
+    '이후',
+    '때문',
+    '하는',
+    '있는',
+    '없는',
+    '되는',
+    '관련',
+    '해야',
+    '하고',
+    '있다',
+    '없다',
+    '한다',
+    '이런',
+    '그런',
+    '저런',
+    '매우',
+    '항상',
+    '모두',
+    '각각',
+    '대해',
+    '여러',
+    '시작',
+    '그것',
+    '이것',
+    '저것',
+    '아주',
+    '정말',
+    '너무',
+    '많이',
+    '자주',
+    '가장',
+    '먼저',
+    '이미',
+    '아직',
+    '그냥',
+    '바로',
+    '다시',
+    '함께',
+    '위한',
+    '따라',
+    '부분',
+    '전체',
+    '방법',
+    '내용',
+    '결과',
+    '문제',
+    '시점',
+    '설정',
+    '작업',
+    '확인',
+    '수행',
+    '처리',
+    '기본',
+    '추가',
+    '변경',
+    '제거',
+    '포함',
+    '생성',
+    '실행',
+    '완료',
+    '필요',
     // 조사/어미/접속사 — Jaccard 분모 희석 방지
-    '에서', '으로', '에게', '에는', '에도', '까지', '부터', '보다', '처럼',
-    '만큼', '대로', '밖에', '뿐만', '이나', '이고', '이면', '이라', '인데',
-    '했는데', '됐는데', '있으면', '없으면', '하면', '되면', '하지', '되지',
-    '하며', '되며', '에서의', '으로의', '라는', '라고', '이라고', '때문에',
-    '아니라', '하지만', '그러나', '그래서', '따라서', '그리고', '그러면',
-    '만약', '비록', '하여', '않고', '않은', '않는', '해서', '해도', '해야',
+    '에서',
+    '으로',
+    '에게',
+    '에는',
+    '에도',
+    '까지',
+    '부터',
+    '보다',
+    '처럼',
+    '만큼',
+    '대로',
+    '밖에',
+    '뿐만',
+    '이나',
+    '이고',
+    '이면',
+    '이라',
+    '인데',
+    '했는데',
+    '됐는데',
+    '있으면',
+    '없으면',
+    '하면',
+    '되면',
+    '하지',
+    '되지',
+    '하며',
+    '되며',
+    '에서의',
+    '으로의',
+    '라는',
+    '라고',
+    '이라고',
+    '때문에',
+    '아니라',
+    '하지만',
+    '그러나',
+    '그래서',
+    '따라서',
+    '그리고',
+    '그러면',
+    '만약',
+    '비록',
+    '하여',
+    '않고',
+    '않은',
+    '않는',
+    '해서',
+    '해도',
+    '해야',
     // 일반 동사/형용사 어간 — 의미 없는 고빈도 단어
-    '가능', '상태', '이유', '방지', '의존', '의존성', '즉시', '원칙', '근거',
-    '수정', '제안', '기능', '구현', '구조', '단계', '목적', '상황', '조건',
-    '규칙', '동작', '활성', '비활성', '원래', '현재', '이전', '다음', '최종',
+    '가능',
+    '상태',
+    '이유',
+    '방지',
+    '의존',
+    '의존성',
+    '즉시',
+    '원칙',
+    '근거',
+    '수정',
+    '제안',
+    '기능',
+    '구현',
+    '구조',
+    '단계',
+    '목적',
+    '상황',
+    '조건',
+    '규칙',
+    '동작',
+    '활성',
+    '비활성',
+    '원래',
+    '현재',
+    '이전',
+    '다음',
+    '최종',
 ]);
 /** 영어 불용어 */
 const EN_STOPWORDS = new Set([
-    'the', 'and', 'for', 'that', 'this', 'with', 'from', 'are', 'was',
-    'were', 'been', 'have', 'has', 'had', 'not', 'but', 'all', 'can',
-    'will', 'use', 'used', 'using', 'when', 'each', 'which', 'their',
-    'also', 'into', 'more', 'some', 'than', 'other', 'should', 'would',
-    'could', 'about', 'after', 'before', 'between', 'does', 'only',
-    'across', 'just', 'detected', 'based', 'sessions', 'prompts',
+    'the',
+    'and',
+    'for',
+    'that',
+    'this',
+    'with',
+    'from',
+    'are',
+    'was',
+    'were',
+    'been',
+    'have',
+    'has',
+    'had',
+    'not',
+    'but',
+    'all',
+    'can',
+    'will',
+    'use',
+    'used',
+    'using',
+    'when',
+    'each',
+    'which',
+    'their',
+    'also',
+    'into',
+    'more',
+    'some',
+    'than',
+    'other',
+    'should',
+    'would',
+    'could',
+    'about',
+    'after',
+    'before',
+    'between',
+    'does',
+    'only',
+    'across',
+    'just',
+    'detected',
+    'based',
+    'sessions',
+    'prompts',
 ]);
 /** 한국어 일반 조사/어미 — strip 대상 (긴 것부터 매칭)
  *
@@ -189,9 +398,32 @@ const EN_STOPWORDS = new Set([
  * term-matcher의 `KO_VERBAL_SUFFIXES`에 따로 둔다.
  */
 export const KO_SUFFIXES = [
-    '했습니다', '있습니다', '합니다', '입니다', '됩니다',
-    '에서', '까지', '으로', '하는', '하고', '했다', '된다', '한다',
-    '을', '를', '이', '가', '은', '는', '의', '에', '와', '과', '도', '만', '로',
+    '했습니다',
+    '있습니다',
+    '합니다',
+    '입니다',
+    '됩니다',
+    '에서',
+    '까지',
+    '으로',
+    '하는',
+    '하고',
+    '했다',
+    '된다',
+    '한다',
+    '을',
+    '를',
+    '이',
+    '가',
+    '은',
+    '는',
+    '의',
+    '에',
+    '와',
+    '과',
+    '도',
+    '만',
+    '로',
 ];
 export function stripKoSuffix(word) {
     for (const suffix of KO_SUFFIXES) {
@@ -220,9 +452,7 @@ const MAX_TAGS = 8;
  * a fresh `ROUND3_BASELINE` measurement on every downstream PR.
  */
 export function extractTags(text) {
-    const cleaned = text
-        .toLowerCase()
-        .replace(/[^가-힣a-z0-9\s]/g, ' ');
+    const cleaned = text.toLowerCase().replace(/[^가-힣a-z0-9\s]/g, ' ');
     const words = cleaned.split(/\s+/).filter(Boolean);
     const freq = new Map();
     for (const w of words) {

package/dist/engine/solution-index.d.ts

@@ -1,7 +1,7 @@
 import type { SolutionIndexEntry } from './solution-format.js';
 export interface SolutionDirConfig {
     dir: string;
-    scope: 'me' | 'team' | 'project';
+    scope: 'me' | 'team' | 'project' | 'universal';
 }
 export interface SolutionIndex {
     entries: SolutionIndexEntry[];

package/dist/engine/solution-index.js

@@ -5,6 +5,7 @@ import { defaultNormalizer } from './term-normalizer.js';
 import { withFileLockSync } from '../hooks/shared/file-lock.js';
 import { atomicWriteText } from '../hooks/shared/atomic-write.js';
 import { createLogger } from '../core/logger.js';
+import { recordQuarantine, diagnoseFromRawContent } from './solution-quarantine.js';
 const log = createLogger('solution-index');
 /**
  * Cache keyed by an order-preserving directory signature.
@@ -155,6 +156,15 @@ function buildIndex(dirs) {
                 const fm = parseFrontmatterOnly(content);
                 if (!fm) {
                     droppedMalformed++;
+                    // Slow-path diagnosis: re-parse YAML to produce actionable errors,
+                    // then persist to ~/.forgen/state/solution-quarantine.jsonl so the
+                    // file is visible to `forgen doctor` instead of silently dead.
+                    // Best-effort: quarantine writes must never throw.
+                    try {
+                        const errors = diagnoseFromRawContent(content);
+                        recordQuarantine(filePath, errors);
+                    }
+                    catch { /* ignore */ }
                     log.debug(`dropped (malformed frontmatter): ${filePath}`);
                     continue;
                 }

package/dist/engine/solution-matcher.d.ts

@@ -32,7 +32,7 @@ export declare function tagWeight(tag: string): number;
 export interface SolutionMatch {
     name: string;
     path: string;
-    scope: 'me' | 'team' | 'project';
+    scope: 'me' | 'team' | 'project' | 'universal';
     relevance: number;
     summary: string;
     status: SolutionStatus;
@@ -65,6 +65,12 @@ export interface CalculateRelevanceOptions {
     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;