onto-mcp 0.3.2 → 0.4.1

package/dist/core-runtime/learning/loader.js

@@ -1,388 +0,0 @@
-/**
- * Learning consumption loader — Phase 1.5.
- *
- * Phase 1: C-1 (path), C-2 (parse), C-3a/C-3b (applicability filter), C-4 (sort+cap)
- * Phase 1.5: C-3c (cross-domain rule), C-5a (tier), C-5b (token budget)
- * Common: C-6 (render), C-6b (manifest), C-7 (summary)
- *
- * Design reference: .onto/temp/phase-1.5-design-draft.md
- * Reviews: 20260407-4b64681d (R1), 20260407-bc36fb51 (R2)
- */
-import fs from "node:fs";
-import { ITEM_LINE_RE, APPLICABILITY_RE, ROLE_RE, IMPACT_RE, } from "./shared/patterns.js";
-import { resolveLearningFilePaths } from "./shared/paths.js";
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-const MAX_ITEMS_PER_AGENT = 30; // Phase 1 fallback cap
-const TOKEN_BUDGET_PER_AGENT = 4000; // Phase 1.5 token budget (T2+ only)
-const T1_TOKEN_WARN_RATIO = 0.5; // Warn if T1 tokens exceed 50% of budget
-// ---------------------------------------------------------------------------
-// C-2: Best-effort line parser (patterns from shared/patterns.ts)
-// ---------------------------------------------------------------------------
-function parseLearningLine(line, sourceScope, agentId, orderIndex) {
-    const typeMatch = line.match(ITEM_LINE_RE);
-    if (!typeMatch)
-        return null;
-    const type = typeMatch[1];
-    const applicability = [];
-    const appRegex = new RegExp(APPLICABILITY_RE.source, "g");
-    let appMatch;
-    while ((appMatch = appRegex.exec(line)) !== null) {
-        applicability.push(appMatch[1]);
-    }
-    const roleMatch = line.match(ROLE_RE);
-    // [insight] → null (under-classified, Phase 3 promote will re-classify)
-    let role = null;
-    if (roleMatch && roleMatch[1] !== "insight") {
-        role = roleMatch[1];
-    }
-    const impactMatch = line.match(IMPACT_RE);
-    const impact = impactMatch?.[1] === "high" ? "high" : "normal";
-    return { type, applicability, role, impact, raw_line: line, source_scope: sourceScope, agent_id: agentId, order_index: orderIndex, cross_domain: false };
-}
-function parseLearningFile(filePath, sourceScope, agentId, startIndex) {
-    const content = fs.readFileSync(filePath, "utf8");
-    const lines = content.split("\n");
-    const items = [];
-    const warnings = [];
-    let skipped = 0;
-    let orderIndex = startIndex;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i].trim();
-        if (!line || line.startsWith("#") || line.startsWith("<!--"))
-            continue;
-        if (!/^[-*+]\s+\[/.test(line))
-            continue;
-        const item = parseLearningLine(line, sourceScope, agentId, orderIndex);
-        if (item) {
-            items.push(item);
-            orderIndex++;
-        }
-        else {
-            skipped++;
-            warnings.push(`[learn-loader] skip: ${filePath}:${i + 1} — parse failed`);
-        }
-    }
-    return { items, skipped, warnings };
-}
-// ---------------------------------------------------------------------------
-// C-3a / C-3b: Applicability filter (methodology + current domain)
-// ---------------------------------------------------------------------------
-function filterByApplicability(items, sessionDomain) {
-    const isNoDomain = !sessionDomain || sessionDomain === "none" || sessionDomain === "@-";
-    return items.filter((item) => {
-        if (item.applicability.includes("methodology"))
-            return true;
-        if (!isNoDomain && item.applicability.includes(`domain/${sessionDomain}`))
-            return true;
-        return false;
-    });
-}
-function applyCrossDomainFilter(existingItems, allParsedItems, sessionDomain) {
-    const isNoDomain = !sessionDomain || sessionDomain === "none" || sessionDomain === "@-";
-    if (isNoDomain) {
-        return { items: [...existingItems], stats: { included: 0, excluded: 0 } };
-    }
-    // Build new array — never mutate input (fail-close snapshot integrity)
-    const result = [...existingItems];
-    const existingSet = new Set(existingItems);
-    let included = 0;
-    let excluded = 0;
-    for (const item of allParsedItems) {
-        if (existingSet.has(item))
-            continue; // already included by C-3a/C-3b
-        if (item.applicability.includes("methodology"))
-            continue; // not domain-only
-        const hasDomain = item.applicability.some((a) => a.startsWith("domain/"));
-        if (!hasDomain)
-            continue;
-        if (item.applicability.includes(`domain/${sessionDomain}`))
-            continue;
-        // This is a cross-domain item
-        if (item.role === "guardrail" || item.impact === "high") {
-            result.push({ ...item, cross_domain: true });
-            included++;
-        }
-        else {
-            excluded++;
-        }
-    }
-    return { items: result, stats: { included, excluded } };
-}
-// ---------------------------------------------------------------------------
-// C-5a: Tier assignment + sort (Phase 1.5, supersedes C-4)
-//
-// Tier assignment: first matching from T1 down.
-// Intra-tier sort: current-domain first, then newest first.
-// ---------------------------------------------------------------------------
-function assignTier(item) {
-    if (item.role === "guardrail")
-        return 1;
-    if (item.impact === "high")
-        return 2;
-    if (item.role === "foundation")
-        return 3;
-    return 4; // convention, under-classified, or unknown role
-}
-function assignTierAndSort(items) {
-    const tiered = items.map((item) => ({
-        ...item,
-        tier: assignTier(item),
-    }));
-    tiered.sort((a, b) => {
-        // 1. tier ascending (T1 first)
-        if (a.tier !== b.tier)
-            return a.tier - b.tier;
-        // 2. current-domain first within tier
-        const aCross = a.cross_domain ? 1 : 0;
-        const bCross = b.cross_domain ? 1 : 0;
-        if (aCross !== bCross)
-            return aCross - bCross;
-        // 3. newest first
-        return b.order_index - a.order_index;
-    });
-    return tiered;
-}
-// ---------------------------------------------------------------------------
-// C-5b: Token budget (Phase 1.5)
-//
-// T1 items are exempt (always included).
-// T2+ items fill budget in tier order until exhausted.
-// Last item that crosses budget is included (over-budget allowed).
-// ---------------------------------------------------------------------------
-function estimateTokens(text) {
-    let tokens = 0;
-    for (const char of text) {
-        // Non-ASCII (CJK, Korean, etc.): ~1 token per character
-        // ASCII/Latin: ~4 characters per token
-        tokens += char.charCodeAt(0) > 0x7F ? 1 : 0.25;
-    }
-    return Math.ceil(tokens);
-}
-function applyTokenBudget(items) {
-    const kept = [];
-    let budgetUsed = 0;
-    let budgetExhausted = false;
-    let truncatedCount = 0;
-    let t1Tokens = 0;
-    for (const item of items) {
-        const tokens = estimateTokens(item.raw_line);
-        if (item.tier === 1) {
-            // T1: always included, budget exempt
-            kept.push(item);
-            t1Tokens += tokens;
-            continue;
-        }
-        if (budgetExhausted) {
-            truncatedCount++;
-            continue;
-        }
-        kept.push(item);
-        budgetUsed += tokens;
-        // Allow last item to exceed budget (over-budget)
-        if (budgetUsed >= TOKEN_BUDGET_PER_AGENT) {
-            budgetExhausted = true;
-        }
-    }
-    return { items: kept, tokens_used: budgetUsed + t1Tokens, budget_truncated_count: truncatedCount, t1_tokens: t1Tokens };
-}
-// ---------------------------------------------------------------------------
-// C-4: Phase 1 fallback (sort + cap 30)
-// ---------------------------------------------------------------------------
-function prioritySortAndCap(items) {
-    const sorted = [...items].sort((a, b) => {
-        const ag = a.role === "guardrail" ? 1 : 0;
-        const bg = b.role === "guardrail" ? 1 : 0;
-        if (ag !== bg)
-            return bg - ag;
-        const ah = a.impact === "high" ? 1 : 0;
-        const bh = b.impact === "high" ? 1 : 0;
-        if (ah !== bh)
-            return bh - ah;
-        const af = a.role === "foundation" ? 1 : 0;
-        const bf = b.role === "foundation" ? 1 : 0;
-        if (af !== bf)
-            return bf - af;
-        return b.order_index - a.order_index;
-    });
-    const capped = sorted.slice(0, MAX_ITEMS_PER_AGENT);
-    return capped.map((item) => ({ ...item, tier: assignTier(item) }));
-}
-// ---------------------------------------------------------------------------
-// C-7: Distribution helpers
-// ---------------------------------------------------------------------------
-function computeRoleDistribution(items) {
-    const dist = { guardrail: 0, foundation: 0, convention: 0, unclassified: 0 };
-    for (const item of items) {
-        const key = item.role ?? "unclassified";
-        dist[key] = (dist[key] ?? 0) + 1;
-    }
-    return dist;
-}
-function computeTierDistribution(items) {
-    const dist = { "1": 0, "2": 0, "3": 0, "4": 0 };
-    for (const item of items) {
-        dist[String(item.tier)] = (dist[String(item.tier)] ?? 0) + 1;
-    }
-    return dist;
-}
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Load, filter, tier, and budget-truncate learnings for a single agent.
- * Phase 1.5 pipeline: C-3a/C-3b → C-3c → C-5a → C-5b
- * Fail-close: falls back to Phase 1 (C-4) on any error.
- */
-export function loadLearningsForAgent(agentId, projectRoot, sessionDomain) {
-    const paths = resolveLearningFilePaths(agentId, projectRoot);
-    const allParsedItems = [];
-    let totalSkipped = 0;
-    const warnings = [];
-    const filePaths = [];
-    // C-1/C-2: Load and parse — promoted (global/user) learnings only.
-    // Project-level learnings (seed, unpromoted) are excluded from consumption
-    // to prevent drift. They serve as input for creation and promotion only.
-    // See .onto/principles/product-locality-principle.md §2.2.
-    for (const [scope, filePath] of [["methodology", paths.user_path]]) {
-        if (!filePath)
-            continue;
-        filePaths.push(filePath);
-        try {
-            const r = parseLearningFile(filePath, scope, agentId, allParsedItems.length);
-            allParsedItems.push(...r.items);
-            totalSkipped += r.skipped;
-            warnings.push(...r.warnings);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            warnings.push(`[learn-loader] warn: ${agentId} ${scope} file read failed: ${message}`);
-        }
-    }
-    const totalParsed = allParsedItems.length;
-    // C-3a/C-3b: applicability filter
-    let items = filterByApplicability(allParsedItems, sessionDomain);
-    // Phase 1.5 disabled by env var → use Phase 1 fallback
-    if (process.env.ONTO_LEARNING_TIER_DISABLED === "1") {
-        const fallback = prioritySortAndCap(items);
-        const tokensUsed = fallback.reduce((s, i) => s + estimateTokens(i.raw_line), 0);
-        return { agent_id: agentId, items: fallback, total_parsed: totalParsed, skipped_count: totalSkipped, file_paths: filePaths, warnings, degraded: false, cross_domain_included: 0, cross_domain_excluded: 0, budget_truncated_count: 0, tokens_used: tokensUsed };
-    }
-    // IAR-1: Snapshot pre-C-3c items for fail-close fallback
-    const phase1Items = [...items];
-    let crossStats = { included: 0, excluded: 0 };
-    try {
-        // C-3c: cross-domain rule-based inclusion
-        if (process.env.ONTO_LEARNING_CROSS_DOMAIN_DISABLED !== "1") {
-            const result = applyCrossDomainFilter(items, allParsedItems, sessionDomain);
-            items = result.items;
-            crossStats = result.stats;
-        }
-        // C-5a: tier assignment + sort
-        const tiered = assignTierAndSort(items);
-        // C-5b: token budget
-        const budgetResult = applyTokenBudget(tiered);
-        // T1 token warning
-        if (budgetResult.t1_tokens > TOKEN_BUDGET_PER_AGENT * T1_TOKEN_WARN_RATIO) {
-            warnings.push(`[learn-loader] warn: ${agentId} T1 tokens (${budgetResult.t1_tokens}) exceed ${T1_TOKEN_WARN_RATIO * 100}% of budget (${TOKEN_BUDGET_PER_AGENT})`);
-        }
-        return { agent_id: agentId, items: budgetResult.items, total_parsed: totalParsed, skipped_count: totalSkipped, file_paths: filePaths, warnings, degraded: false, cross_domain_included: crossStats.included, cross_domain_excluded: crossStats.excluded, budget_truncated_count: budgetResult.budget_truncated_count, tokens_used: budgetResult.tokens_used };
-    }
-    catch (error) {
-        // Fail-close: use pre-C-3c snapshot with Phase 1 fallback
-        const message = error instanceof Error ? error.message : String(error);
-        warnings.push(`[learn-loader] Phase 1.5 degraded: ${message}, falling back to Phase 1`);
-        const fallback = prioritySortAndCap(phase1Items);
-        const tokensUsed = fallback.reduce((s, i) => s + estimateTokens(i.raw_line), 0);
-        return { agent_id: agentId, items: fallback, total_parsed: totalParsed, skipped_count: totalSkipped, file_paths: filePaths, warnings, degraded: true, cross_domain_included: 0, cross_domain_excluded: 0, budget_truncated_count: 0, tokens_used: tokensUsed };
-    }
-}
-/**
- * Load learnings for all agents in a session. Returns per-agent results + manifest.
- */
-export function loadLearningsForSession(agentIds, projectRoot, sessionDomain) {
-    const results = [];
-    const allPaths = [];
-    let anyDegraded = false;
-    let degradationReason = null;
-    for (const agentId of agentIds) {
-        const result = loadLearningsForAgent(agentId, projectRoot, sessionDomain);
-        results.push(result);
-        allPaths.push(...result.file_paths);
-        if (result.degraded) {
-            anyDegraded = true;
-            degradationReason = result.warnings.find((w) => w.includes("degraded")) ?? "unknown";
-        }
-    }
-    // Compute cross-domain stats from results
-    const manifest = {
-        session_domain: sessionDomain ?? "none",
-        agents_loaded: results.length,
-        total_items_loaded: results.reduce((sum, r) => sum + r.items.length, 0),
-        total_items_parsed: results.reduce((sum, r) => sum + r.total_parsed, 0),
-        total_items_skipped: results.reduce((sum, r) => sum + r.skipped_count, 0),
-        per_agent: results.map((r) => ({
-            agent_id: r.agent_id,
-            loaded: r.items.length,
-            parsed: r.total_parsed,
-            skipped: r.skipped_count,
-            truncated: Math.max(0, r.total_parsed - r.items.length),
-            role_distribution: computeRoleDistribution(r.items),
-            tier_distribution: computeTierDistribution(r.items),
-            cross_domain_included: r.cross_domain_included,
-            cross_domain_excluded: r.cross_domain_excluded,
-            tokens_used: r.tokens_used,
-            tokens_budget: TOKEN_BUDGET_PER_AGENT,
-            budget_truncated_count: r.budget_truncated_count,
-        })),
-        learning_file_paths: [...new Set(allPaths)],
-        degraded: anyDegraded,
-        degradation_reason: degradationReason,
-    };
-    return { results, manifest };
-}
-/**
- * C-6: Render learning section for insertion into a lens prompt packet.
- */
-export function renderLearningSection(items) {
-    if (items.length === 0)
-        return "";
-    const lines = [
-        "",
-        "## Prior Learnings",
-        `Items: ${items.length} (priority: T1-guardrail > T2-high-impact > T3-foundation > T4-other)`,
-        "Use these learnings as prior knowledge during your review. Report which learnings you applied in your output.",
-        "",
-    ];
-    for (const item of items) {
-        lines.push(item.raw_line);
-    }
-    return lines.join("\n");
-}
-/**
- * C-7: Format loading summary for console output.
- */
-export function formatLoadingSummary(manifest) {
-    const lines = [
-        `[learn-loader] domain=${manifest.session_domain}, agents=${manifest.agents_loaded}, ` +
-            `loaded=${manifest.total_items_loaded}, parsed=${manifest.total_items_parsed}, ` +
-            `skipped=${manifest.total_items_skipped}` +
-            (manifest.degraded ? ` (degraded: Phase 1 fallback)` : ""),
-    ];
-    for (const agent of manifest.per_agent) {
-        const tierParts = Object.entries(agent.tier_distribution)
-            .filter(([, count]) => count > 0)
-            .map(([tier, count]) => `T${tier}:${count}`)
-            .join(" ");
-        const crossPart = agent.cross_domain_included > 0 ? ` cross:${agent.cross_domain_included}` : "";
-        const tokenPart = ` tok:${agent.tokens_used}/${agent.tokens_budget}`;
-        lines.push(`  ${agent.agent_id}: ${agent.loaded}/${agent.parsed}` +
-            (agent.truncated > 0 ? ` (truncated ${agent.truncated})` : "") +
-            (agent.loaded === 0 ? " (filtered to zero)" : "") +
-            (tierParts ? ` [${tierParts}]` : "") +
-            crossPart +
-            tokenPart);
-    }
-    return lines.join("\n");
-}

package/dist/core-runtime/learning/loader.test.js

@@ -1,102 +0,0 @@
-/**
- * Learning consumption loader tests (W-B-17).
- *
- * 핵심 검증: promoted(user scope) 학습만 consumer 에 노출.
- * project scope(seed/candidate/provisional) 학습은 소비되지 않음.
- * feedback_learning_core_value.md 정책과 implementation 일치 확인.
- */
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import { loadLearningsForAgent, loadLearningsForSession } from "./loader.js";
-// ─── Test fixtures ───
-const PROMOTED_LEARNING = `# logic learnings
-
-- [fact] [methodology] [guardrail] [high] 리뷰 시 모순 검출은 첫 번째 우선순위
-- [judgment] [methodology] [foundation] [normal] 구조 분해 후 의존성 분석이 효율적
-`;
-const UNPROMOTED_LEARNING = `# logic learnings (project scope)
-
-- [fact] [methodology] [guardrail] [high] 이 프로젝트에서 인증 모듈은 항상 먼저 검토해야 함
-- [judgment] [domain/se] [convention] [normal] SE 도메인의 CQ 우선순위는 보안 → 성능 → 유지보수
-`;
-let tmpDir;
-let origHome;
-beforeEach(() => {
-    tmpDir = mkdtempSync(join(tmpdir(), "loader-test-"));
-    origHome = process.env.HOME ?? "";
-    // user scope (promoted) 경로 설정
-    process.env.HOME = tmpDir;
-});
-afterEach(() => {
-    process.env.HOME = origHome;
-    rmSync(tmpDir, { recursive: true, force: true });
-});
-function setupPromotedLearning(agentId) {
-    const userDir = join(tmpDir, ".onto", "learnings");
-    mkdirSync(userDir, { recursive: true });
-    writeFileSync(join(userDir, `${agentId}.md`), PROMOTED_LEARNING, "utf-8");
-}
-function setupProjectLearning(projectRoot, agentId) {
-    const projectDir = join(projectRoot, ".onto", "learnings");
-    mkdirSync(projectDir, { recursive: true });
-    writeFileSync(join(projectDir, `${agentId}.md`), UNPROMOTED_LEARNING, "utf-8");
-}
-describe("loader consumption guard (W-B-17)", () => {
-    it("promoted(user scope) 학습만 로드한다", () => {
-        const projectRoot = join(tmpDir, "project");
-        mkdirSync(projectRoot, { recursive: true });
-        setupPromotedLearning("logic");
-        const result = loadLearningsForAgent("logic", projectRoot, "methodology");
-        expect(result.items.length).toBeGreaterThan(0);
-        // 모든 item 이 user scope
-        for (const item of result.items) {
-            expect(item.source_scope).toBe("methodology");
-        }
-    });
-    it("project scope(unpromoted) 학습은 소비하지 않는다", () => {
-        const projectRoot = join(tmpDir, "project");
-        mkdirSync(projectRoot, { recursive: true });
-        // project scope 만 존재, user scope 없음
-        setupProjectLearning(projectRoot, "logic");
-        const result = loadLearningsForAgent("logic", projectRoot, "methodology");
-        // project scope 학습이 있어도 로드되지 않음
-        expect(result.items).toHaveLength(0);
-        expect(result.total_parsed).toBe(0);
-    });
-    it("user + project 모두 존재할 때 user 만 로드한다", () => {
-        const projectRoot = join(tmpDir, "project");
-        mkdirSync(projectRoot, { recursive: true });
-        setupPromotedLearning("logic");
-        setupProjectLearning(projectRoot, "logic");
-        const result = loadLearningsForAgent("logic", projectRoot, "methodology");
-        // user scope 항목만 로드됨
-        expect(result.items.length).toBeGreaterThan(0);
-        for (const item of result.items) {
-            expect(item.source_scope).toBe("methodology");
-        }
-        // project scope 의 "인증 모듈" 항목은 포함되지 않음
-        const hasProjectItem = result.items.some(i => i.raw_line.includes("인증 모듈"));
-        expect(hasProjectItem).toBe(false);
-    });
-    it("loadLearningsForSession 도 동일한 promoted-only 정책을 따른다", () => {
-        const projectRoot = join(tmpDir, "project");
-        mkdirSync(projectRoot, { recursive: true });
-        setupPromotedLearning("logic");
-        setupProjectLearning(projectRoot, "logic");
-        const { results, manifest } = loadLearningsForSession(["logic"], projectRoot, "methodology");
-        expect(results).toHaveLength(1);
-        for (const item of results[0].items) {
-            expect(item.source_scope).toBe("methodology");
-        }
-        expect(manifest.total_items_loaded).toBeGreaterThan(0);
-    });
-    it("학습 파일이 없으면 빈 결과를 반환한다 (에러 아님)", () => {
-        const projectRoot = join(tmpDir, "project");
-        mkdirSync(projectRoot, { recursive: true });
-        const result = loadLearningsForAgent("logic", projectRoot, "methodology");
-        expect(result.items).toHaveLength(0);
-        expect(result.degraded).toBe(false);
-    });
-});