@wooojin/forgen 0.3.0 → 0.3.2

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

@@ -60,14 +60,20 @@ 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 */
 export declare function parseSolutionV3(content: string): SolutionV3 | null;
 /** Serialize a SolutionV3 to a markdown string with YAML frontmatter */
 export declare function serializeSolutionV3(solution: SolutionV3): string;
-/** Check if content is in V3 format (YAML frontmatter) */
-export declare function isV3Format(content: string): boolean;
 /** Check if content is in V1 format (# Title + > Type: pattern) */
 export declare function isV1Format(content: string): boolean;
 /** 한국어 일반 조사/어미 — strip 대상 (긴 것부터 매칭)

package/dist/engine/solution-format.js

@@ -35,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;
+        errors.push(`type: must be one of ${VALID_TYPES.join('|')}`);
     if (o.scope !== 'me' && o.scope !== 'team' && o.scope !== 'project' && o.scope !== 'universal')
-        return false;
+        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');
+    }
+    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 true;
+    return errors;
 }
 // ── Parsing ──
 /** Parse YAML frontmatter from solution file content */
@@ -147,10 +162,6 @@ export function serializeSolutionV3(solution) {
     return `---\n${yamlStr}---\n\n## Context\n${solution.context}\n\n## Content\n${solution.content}\n`;
 }
 // ── Format Detection ──
-/** Check if content is in V3 format (YAML frontmatter) */
-export function isV3Format(content) {
-    return content.trimStart().startsWith('---');
-}
 /** Check if content is in V1 format (# Title + > Type: pattern) */
 export function isV1Format(content) {
     const lines = content.split('\n');

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

@@ -41,6 +41,14 @@ export interface SolutionMatch {
     tags: string[];
     identifiers: string[];
     matchedTags: string[];
+    /**
+     * Identifier substrings (function/file names) that appeared literally in the
+     * prompt. Added 2026-04-21 so solution-injector can enforce a precision gate
+     * distinguishing "user typed a specific identifier" (strong signal, survives
+     * 1-tag overlap) from "only 1 tag happens to overlap" (often noise — common
+     * nouns like 'type', 'file', 'forgen' trigger rare-tag BM25 boost).
+     */
+    matchedIdentifiers: string[];
 }
 /**
  * Optional hints for the v3 `calculateRelevance` path. Used by hot-path

package/dist/engine/solution-matcher.js

@@ -810,6 +810,31 @@ function loadTunedMatcherWeights() {
     _weightsCacheTime = now;
     return undefined;
 }
+/**
+ * Cold-start exploration bonus for candidate solutions.
+ *
+ * Phase 4 evolution: newly proposed solutions enter at `status: candidate`.
+ * Without a nudge they compete head-to-head with mature verified/champion
+ * entries and almost always lose the first few rounds — not because
+ * they're worse, but because matchers favor solutions with richer tag
+ * histories. A small confidence multiplier lets candidates surface often
+ * enough to accumulate reflected/sessions evidence, after which the
+ * lifecycle loop decides their fate.
+ *
+ * The 1.3× factor is a starting point (Q1 in docs/design-solution-evolution.md).
+ * Bonus deactivation happens implicitly when compound-lifecycle.ts::
+ * runLifecycleCheck promotes the candidate to `verified` based on accumulated
+ * reflected/sessions evidence. There is no inject-count-based auto promotion
+ * (removed 2026-04-20 — see feedback_core_loop_invariant).
+ */
+const CANDIDATE_EXPLORATION_MULTIPLIER = 1.3;
+function applyCandidateExplorationBonus(entries) {
+    return entries.map((e) => {
+        if (e.status !== 'candidate')
+            return e;
+        return { ...e, confidence: Math.min(1, e.confidence * CANDIDATE_EXPLORATION_MULTIPLIER) };
+    });
+}
 export function matchSolutions(prompt, scope, cwd) {
     // Build solution dirs for index cache
     const dirs = [{ dir: ME_SOLUTIONS, scope: 'me' }];
@@ -819,7 +844,7 @@ export function matchSolutions(prompt, scope, cwd) {
     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 = applyCandidateExplorationBonus(index.entries.map((e) => ({ ...e })));
     const promptTags = extractTags(prompt);
     const promptLower = prompt.toLowerCase();
     // Meta-learning: load tuned weights if available
@@ -842,5 +867,6 @@ export function matchSolutions(prompt, scope, cwd) {
         tags: c.solution.tags,
         identifiers: c.solution.identifiers,
         matchedTags: [...c.matchedTags, ...c.matchedIdentifiers],
+        matchedIdentifiers: c.matchedIdentifiers,
     }));
 }

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

@@ -0,0 +1,74 @@
+export type Outcome = 'accept' | 'correct' | 'error' | 'unknown';
+export type Attribution = 'explicit' | 'window' | 'session_end' | 'default';
+/**
+ * One inject → outcome event. Written append-only to
+ * ~/.forgen/state/outcomes/{session_id}.jsonl. The pending state (inject
+ * happened, outcome not yet decided) is stored separately in
+ * ~/.forgen/state/outcome-pending-{session_id}.json.
+ */
+export interface OutcomeEvent {
+    ts: number;
+    session_id: string;
+    solution: string;
+    match_score: number;
+    injected_chars: number;
+    outcome: Outcome;
+    outcome_lag_ms: number;
+    attribution: Attribution;
+}
+/**
+ * Record that solutions were injected. Called from solution-injector right
+ * after `approveWithContext` is emitted. Fails silently — outcome tracking
+ * must never block the user's workflow.
+ */
+export declare function appendPending(sessionId: string, injections: Array<{
+    solution: string;
+    match_score: number;
+    injected_chars: number;
+}>): void;
+/**
+ * Flush pending injections as `accept` events. Called when a new user
+ * prompt arrives without any intervening correction/error, signaling that
+ * the previous injections were silently accepted. "Silence = consent."
+ *
+ * If `excludeSolutions` is provided, those solutions are NOT flushed (e.g.
+ * because an earlier step already attributed them as `correct` or `error`).
+ */
+export declare function flushAccept(sessionId: string, excludeSolutions?: Set<string>): number;
+/**
+ * Attribute a correction to the most recent pending injection(s). Called
+ * from the correction-record MCP tool. Removes attributed entries from
+ * pending so subsequent `flushAccept` does not double-count them.
+ *
+ * Strategy: all currently-pending solutions in this session are marked as
+ * `correct`. This is conservative (the correction may target only one of
+ * them), but without semantic attribution we err on the side of the user's
+ * feedback signal being louder than acceptance.
+ */
+export declare function attributeCorrection(sessionId: string): string[];
+/**
+ * Attribute a tool error to pending solutions in this session. Called from
+ * post-tool-failure hook. Unlike corrections, errors do not clear pending
+ * — an error is a weaker signal and the next user prompt can still produce
+ * a correct/accept decision.
+ *
+ * Only the top-K most-relevant, recent, above-threshold pending solutions
+ * are attributed (see gates above). Below-threshold or stale pending
+ * entries are left untouched — they will resolve via accept/unknown later.
+ *
+ * To avoid flooding the log with duplicate errors for the same pending
+ * batch, we cap at one `error` event per (session, solution) pair per
+ * pending-cycle by tracking a `error_flagged` set in the pending state.
+ */
+export declare function attributeError(sessionId: string): string[];
+/**
+ * At session end, any still-pending entries are logged as `unknown` (we
+ * can't tell if the user was happy or just stopped). Pending file is
+ * removed.
+ */
+export declare function finalizeSession(sessionId: string): number;
+/**
+ * Read all outcome events across all sessions. Used by fitness
+ * calculation. Returns events sorted by timestamp ascending.
+ */
+export declare function readAllOutcomes(): OutcomeEvent[];