onto-mcp 0.3.0

package/dist/core-runtime/learning/shared/llm-tool-loop.js

@@ -0,0 +1,393 @@
+/**
+ * LLM tool-calling loop — Phase 3-2 of host runtime decoupling.
+ *
+ * # What this module is
+ *
+ * A multi-turn driver that lets an LLM iteratively call onto-defined tools
+ * (`read_file`, `list_directory`, `search_content`) before producing its
+ * final answer. The driver speaks both Anthropic Messages API and OpenAI
+ * Chat Completions API tool-calling protocols, normalizing them under a
+ * single TS interface.
+ *
+ * # Why it exists
+ *
+ * The single-turn `callLlm()` in llm-caller.ts forces all context into the
+ * initial prompt (Tier 2 inline-content mode). For function-calling-capable
+ * models, it's far more token-efficient to expose a small read-only API and
+ * let the model fetch what it needs (Tier 1 tool-native mode). This driver
+ * implements that loop while keeping the tool definitions, boundary
+ * enforcement, and provider transport in three separate seats.
+ *
+ * # How it relates
+ *
+ * - `onto-tools.ts` owns the tool definitions and boundary-checked execution.
+ * - This module owns provider-format adaptation and the tool-result feedback
+ *   loop. It does NOT enforce boundaries — those live in the tool itself, so
+ *   any future executor that calls a tool gets the same guarantees.
+ * - `inline-http-review-unit-executor.ts` is the caller: it picks tool_mode
+ *   (native | inline | auto) and either invokes this driver (native/auto) or
+ *   calls single-turn `callLlm()` for inline mode.
+ *
+ * # Provider-format differences (the part that matters)
+ *
+ * Anthropic Messages API:
+ *   request.tools = [{ name, description, input_schema }]
+ *   response.content = [{ type: "tool_use", id, name, input }, ...]
+ *   tool result is fed back as a user message:
+ *     { role: "user", content: [{ type: "tool_result", tool_use_id, content }] }
+ *
+ * OpenAI Chat Completions:
+ *   request.tools = [{ type: "function", function: { name, description, parameters } }]
+ *   response.message.tool_calls = [{ id, type: "function", function: { name, arguments } }]
+ *   tool result is fed back as a tool message:
+ *     { role: "tool", tool_call_id, content }
+ *   arguments are stringified JSON; we parse before dispatching.
+ *
+ * Both providers signal "no more tool calls, here is the final answer" by
+ * returning normal text content / message.content with no tool_calls. The
+ * loop terminates when that happens (or when MAX_ITERATIONS is reached as
+ * a runaway-safety brake).
+ */
+import { BoundaryViolationError, findToolByName, } from "../../cli/onto-tools.js";
+import { DEFAULT_GROK_BASE_URL, DEFAULT_LMSTUDIO_BASE_URL, } from "../../llm/model-switcher.js";
+const MAX_ITERATIONS = 12;
+const MAX_TOKENS_PER_TURN = 4096;
+/**
+ * Model-call observability — mirrors `emitModelCallLog` in llm-caller.ts.
+ * Duplicated here to avoid a cyclic import (llm-caller imports nothing from
+ * this loop module, and this loop module is the companion seat for the
+ * `callLlmWithTools` entry point). Review Recovery PR-1 (R5) extends the
+ * `[model-call]` prefix coverage to both tool-native and inline paths.
+ */
+function emitModelCallLog(line) {
+    process.stderr.write(`[model-call] ${line}\n`);
+}
+/**
+ * Run a tool-calling conversation until the model produces a final text
+ * answer or the iteration cap is reached.
+ *
+ * Mock provider hook: when ONTO_LLM_MOCK=1, this routes to a deterministic
+ * mock that exercises the loop wiring (see callMockToolLoop). Real provider
+ * calls are gated behind that env var so unit tests never need credentials.
+ */
+export async function callLlmWithTools(systemPrompt, userPrompt, tools, config, toolCtx) {
+    if (process.env.ONTO_LLM_MOCK === "1") {
+        return callMockToolLoop(systemPrompt, userPrompt, tools, config, toolCtx);
+    }
+    if (config.provider === "anthropic") {
+        return runAnthropicToolLoop(systemPrompt, userPrompt, tools, config, toolCtx);
+    }
+    return runOpenAIToolLoop(systemPrompt, userPrompt, tools, config, toolCtx);
+}
+async function runAnthropicToolLoop(systemPrompt, userPrompt, tools, config, toolCtx) {
+    const { default: Anthropic } = await import("@anthropic-ai/sdk");
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        throw new Error("callLlmWithTools(anthropic) requires ANTHROPIC_API_KEY");
+    }
+    const client = new Anthropic({ apiKey });
+    const anthropicTools = tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.input_schema,
+    }));
+    const messages = [
+        { role: "user", content: userPrompt },
+    ];
+    let totalIn = 0;
+    let totalOut = 0;
+    let toolCallCount = 0;
+    const cap = config.max_iterations ?? MAX_ITERATIONS;
+    let truncated = false;
+    let finalText = "";
+    for (let iteration = 0; iteration < cap; iteration++) {
+        emitModelCallLog(`anthropic tool-loop call: model="${config.model_id}" iteration=${iteration + 1}/${cap} max_tokens=${config.max_tokens ?? MAX_TOKENS_PER_TURN} tool_count=${anthropicTools.length}`);
+        let response;
+        try {
+            response = await client.messages.create({
+                model: config.model_id,
+                max_tokens: config.max_tokens ?? MAX_TOKENS_PER_TURN,
+                system: systemPrompt,
+                tools: anthropicTools,
+                messages: messages,
+            });
+        }
+        catch (err) {
+            const e = err;
+            emitModelCallLog(`anthropic tool-loop call FAILED: model="${config.model_id}" iteration=${iteration + 1} status=${e.status ?? "?"} type=${e.error?.type ?? e.name ?? "?"} message="${e.error?.message ?? e.message ?? String(err)}" request_id=${e.request_id ?? "?"}`);
+            throw err;
+        }
+        totalIn += response.usage.input_tokens;
+        totalOut += response.usage.output_tokens;
+        emitModelCallLog(`anthropic tool-loop response: model_id=${response.model ?? config.model_id} iteration=${iteration + 1} stop_reason=${response.stop_reason ?? "?"} input_tokens=${response.usage.input_tokens} output_tokens=${response.usage.output_tokens}`);
+        const blocks = response.content;
+        const assistantBlocks = [];
+        const toolUses = [];
+        for (const block of blocks) {
+            assistantBlocks.push(block);
+            if (block.type === "tool_use") {
+                toolUses.push({ id: block.id, name: block.name, input: block.input });
+            }
+        }
+        messages.push({ role: "assistant", content: assistantBlocks });
+        if (response.stop_reason !== "tool_use" || toolUses.length === 0) {
+            finalText = blocks
+                .filter((b) => b.type === "text")
+                .map((b) => b.text)
+                .join("\n");
+            return {
+                text: finalText.trim(),
+                iterations: iteration + 1,
+                tool_calls: toolCallCount,
+                input_tokens: totalIn,
+                output_tokens: totalOut,
+                model_id: config.model_id,
+                truncated_by_iteration_cap: false,
+            };
+        }
+        const resultBlocks = [];
+        for (const use of toolUses) {
+            toolCallCount++;
+            const result = await executeOneTool(tools, use.name, use.input, toolCtx);
+            resultBlocks.push({
+                type: "tool_result",
+                tool_use_id: use.id,
+                content: result.text,
+                ...(result.isError ? { is_error: true } : {}),
+            });
+        }
+        messages.push({ role: "user", content: resultBlocks });
+    }
+    truncated = true;
+    return {
+        text: finalText.trim(),
+        iterations: cap,
+        tool_calls: toolCallCount,
+        input_tokens: totalIn,
+        output_tokens: totalOut,
+        model_id: config.model_id,
+        truncated_by_iteration_cap: truncated,
+    };
+}
+async function runOpenAIToolLoop(systemPrompt, userPrompt, tools, config, toolCtx) {
+    const { default: OpenAI } = await import("openai");
+    const baseURL = config.base_url ??
+        (config.provider === "grok"
+            ? DEFAULT_GROK_BASE_URL
+            : config.provider === "lmstudio"
+                ? process.env.LMSTUDIO_BASE_URL ?? DEFAULT_LMSTUDIO_BASE_URL
+                : undefined);
+    const apiKey = config.provider === "grok"
+        ? process.env.XAI_API_KEY ?? process.env.GROK_API_KEY
+        : config.provider === "lmstudio"
+            ? "lmstudio-local"
+            : process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+        throw new Error(config.provider === "grok"
+            ? "callLlmWithTools(grok) requires XAI_API_KEY or GROK_API_KEY"
+            : "callLlmWithTools(openai) requires OPENAI_API_KEY");
+    }
+    const client = new OpenAI({ apiKey, baseURL });
+    const openaiTools = tools.map((t) => ({
+        type: "function",
+        function: {
+            name: t.name,
+            description: t.description,
+            parameters: t.input_schema,
+        },
+    }));
+    const messages = [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: userPrompt },
+    ];
+    let totalIn = 0;
+    let totalOut = 0;
+    let toolCallCount = 0;
+    const cap = config.max_iterations ?? MAX_ITERATIONS;
+    let finalText = "";
+    for (let iteration = 0; iteration < cap; iteration++) {
+        emitModelCallLog(`${config.provider} tool-loop call: model="${config.model_id}" iteration=${iteration + 1}/${cap} max_tokens=${config.max_tokens ?? MAX_TOKENS_PER_TURN} tool_count=${openaiTools.length}${baseURL ? ` base_url=${baseURL}` : ""}`);
+        let response;
+        try {
+            response = await client.chat.completions.create({
+                model: config.model_id,
+                max_tokens: config.max_tokens ?? MAX_TOKENS_PER_TURN,
+                messages: messages,
+                tools: openaiTools,
+            });
+        }
+        catch (err) {
+            const e = err;
+            emitModelCallLog(`${config.provider} tool-loop call FAILED: model="${config.model_id}" iteration=${iteration + 1} status=${e.status ?? "?"} type=${e.error?.type ?? e.name ?? "?"} message="${e.error?.message ?? e.message ?? String(err)}" request_id=${e.request_id ?? "?"}`);
+            throw err;
+        }
+        totalIn += response.usage?.prompt_tokens ?? 0;
+        totalOut += response.usage?.completion_tokens ?? 0;
+        emitModelCallLog(`${config.provider} tool-loop response: model_id=${response.model ?? config.model_id} iteration=${iteration + 1} finish_reason=${response.choices[0]?.finish_reason ?? "?"} input_tokens=${response.usage?.prompt_tokens ?? 0} output_tokens=${response.usage?.completion_tokens ?? 0}`);
+        const choice = response.choices[0];
+        if (!choice) {
+            throw new Error("OpenAI tool loop: response had no choices");
+        }
+        const message = choice.message;
+        // OpenAI SDK types tool_calls as a union of function calls and custom
+        // calls (tool-use API). onto only emits function tools, so we narrow
+        // here and silently skip any custom calls the LLM might invent — they
+        // would have nowhere to dispatch.
+        const rawCalls = message.tool_calls ?? [];
+        const toolCalls = rawCalls.filter((c) => c.type === "function");
+        // Push assistant turn (with or without tool_calls).
+        const assistantMsg = {
+            role: "assistant",
+            content: message.content ?? null,
+        };
+        if (toolCalls.length > 0) {
+            assistantMsg.tool_calls = toolCalls.map((c) => ({
+                id: c.id,
+                type: "function",
+                function: { name: c.function.name, arguments: c.function.arguments },
+            }));
+        }
+        messages.push(assistantMsg);
+        if (toolCalls.length === 0 || choice.finish_reason !== "tool_calls") {
+            finalText = message.content ?? "";
+            return {
+                text: finalText.trim(),
+                iterations: iteration + 1,
+                tool_calls: toolCallCount,
+                input_tokens: totalIn,
+                output_tokens: totalOut,
+                model_id: config.model_id,
+                truncated_by_iteration_cap: false,
+            };
+        }
+        for (const call of toolCalls) {
+            toolCallCount++;
+            let parsedArgs;
+            try {
+                parsedArgs = JSON.parse(call.function.arguments);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                messages.push({
+                    role: "tool",
+                    tool_call_id: call.id,
+                    content: `error: arguments JSON parse failed — ${msg}`,
+                });
+                continue;
+            }
+            const result = await executeOneTool(tools, call.function.name, parsedArgs, toolCtx);
+            messages.push({
+                role: "tool",
+                tool_call_id: call.id,
+                content: result.text,
+            });
+        }
+    }
+    return {
+        text: finalText.trim(),
+        iterations: cap,
+        tool_calls: toolCallCount,
+        input_tokens: totalIn,
+        output_tokens: totalOut,
+        model_id: config.model_id,
+        truncated_by_iteration_cap: true,
+    };
+}
+// ---------------------------------------------------------------------------
+// Shared tool dispatch
+// ---------------------------------------------------------------------------
+async function executeOneTool(tools, name, input, ctx) {
+    const tool = tools.find((t) => t.name === name) ?? findToolByName(name);
+    if (!tool) {
+        return {
+            text: `error: tool "${name}" is not registered. Available: ${tools.map((t) => t.name).join(", ")}`,
+            isError: true,
+        };
+    }
+    try {
+        const text = await tool.execute(input, ctx);
+        return { text, isError: false };
+    }
+    catch (err) {
+        if (err instanceof BoundaryViolationError) {
+            return { text: `boundary_violation: ${err.message}`, isError: true };
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        return { text: `tool_error: ${msg}`, isError: true };
+    }
+}
+// ---------------------------------------------------------------------------
+// Mock provider — exercises loop without credentials
+// ---------------------------------------------------------------------------
+/**
+ * Deterministic mock for ONTO_LLM_MOCK=1. The mock reads the system prompt
+ * and emits a small scripted sequence:
+ *   - turn 1: call list_directory on projectRoot
+ *   - turn 2: call read_file on the first .md it sees in the listing
+ *   - turn 3: produce a final markdown answer
+ *
+ * This proves that translation + dispatch + tool-result wiring all work end
+ * to end without a real LLM. Real loops will not follow this script — they
+ * use whatever the LLM decides.
+ */
+async function callMockToolLoop(_systemPrompt, _userPrompt, tools, config, toolCtx) {
+    let toolCalls = 0;
+    // Step 1: list_directory(projectRoot) — exercise the dispatch path.
+    const listTool = tools.find((t) => t.name === "list_directory");
+    let firstMdName;
+    if (listTool) {
+        toolCalls++;
+        try {
+            const listing = await listTool.execute({ path: toolCtx.projectRoot }, toolCtx);
+            const match = listing.match(/\[F\] ([^\s]+\.md)/);
+            if (match)
+                firstMdName = match[1];
+        }
+        catch {
+            // Mock tolerates failure — just don't follow up with read_file.
+        }
+    }
+    // Step 2: read_file on first .md if we found one.
+    const readTool = tools.find((t) => t.name === "read_file");
+    if (readTool && firstMdName) {
+        toolCalls++;
+        try {
+            await readTool.execute({ path: firstMdName, start_line: 1, end_line: 20 }, toolCtx);
+        }
+        catch {
+            // Same tolerance as above.
+        }
+    }
+    // Step 3: deterministic final answer.
+    const text = [
+        "# Mock Lens Output (callLlmWithTools mock)",
+        "",
+        "## Structural Inspection",
+        "- Mock tool-loop exercised list_directory and read_file successfully.",
+        "",
+        "## Findings",
+        "(none — mock executor)",
+        "",
+        "## Newly Learned",
+        "(none — mock executor)",
+        "",
+        "## Applied Learnings",
+        "(none — mock executor)",
+        "",
+        "## Domain Constraints Used",
+        "[]",
+        "",
+        "## Domain Context Assumptions",
+        '- "Mock tool-loop returned this output via ONTO_LLM_MOCK=1."',
+        "",
+    ].join("\n");
+    return {
+        text,
+        iterations: 1,
+        tool_calls: toolCalls,
+        input_tokens: 1,
+        output_tokens: text.length / 4,
+        model_id: config.model_id,
+        truncated_by_iteration_cap: false,
+    };
+}

package/dist/core-runtime/learning/shared/mode.js

@@ -0,0 +1,25 @@
+/**
+ * ExtractMode enum + validator — Phase 2.
+ *
+ * Single validator shared by write path (session start) and read path
+ * (Step 2.5, prompt materialization). R4-IA2, R5-IA-R5-1 해소.
+ */
+const VALID_MODES = ["disabled", "shadow", "active"];
+/**
+ * Validate raw env/config value into ExtractMode.
+ * Invalid value → fail-fast (throw). Silent degradation 금지.
+ */
+export function validateExtractMode(raw) {
+    const value = raw ?? "disabled";
+    if (!VALID_MODES.includes(value)) {
+        throw new Error(`Invalid ONTO_LEARNING_EXTRACT_MODE: "${value}". Valid: ${VALID_MODES.join(", ")}`);
+    }
+    return value;
+}
+/**
+ * Read persisted extract mode from session metadata.
+ * Same validator — no raw cast (R5-IA-R5-1).
+ */
+export function readExtractMode(sessionMetadata) {
+    return validateExtractMode(sessionMetadata.learning_extract_mode);
+}

package/dist/core-runtime/learning/shared/paths.js

@@ -0,0 +1,84 @@
+/**
+ * Learning file path resolution — shared by loader (consumption) and extractor (accumulation).
+ *
+ * C3 해소: 단일 resolveWritePaths(). Dual-write 금지.
+ * CONS-4: resolveRawPaths() 내부 헬퍼로 경로 라우팅 단일화.
+ * Phase 0 dual-read: canonical (bare) ID 우선, onto_ fallback.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+// ---------------------------------------------------------------------------
+// Internal: ID canonicalization (Phase 0 dual-read)
+// ---------------------------------------------------------------------------
+/** Strip "onto_" prefix to yield canonical bare form. Idempotent. */
+function canonicalizeAgentId(agentId) {
+    return agentId.startsWith("onto_") ? agentId.slice(5) : agentId;
+}
+function resolveRawPaths(agentId, projectRoot) {
+    const userDir = path.join(os.homedir(), ".onto", "learnings");
+    const projectDir = path.join(projectRoot, ".onto", "learnings");
+    const userPath = path.join(userDir, `${agentId}.md`);
+    const projectPath = path.join(projectDir, `${agentId}.md`);
+    const projectDirExists = fs.existsSync(projectDir);
+    return { userDir, projectDir, userPath, projectPath, projectDirExists };
+}
+/**
+ * Resolve a single file path with dual-read fallback:
+ * canonical (bare ID) first, then onto_ legacy.
+ * Returns the first existing path, or the canonical path if neither exists.
+ */
+function resolveWithFallback(dir, agentId) {
+    const canonicalId = canonicalizeAgentId(agentId);
+    const canonicalPath = path.join(dir, `${canonicalId}.md`);
+    if (fs.existsSync(canonicalPath))
+        return canonicalPath;
+    const legacyPath = path.join(dir, `onto_${canonicalId}.md`);
+    if (fs.existsSync(legacyPath))
+        return legacyPath;
+    return canonicalPath; // canonical preferred even when neither exists
+}
+/**
+ * Resolve existing learning file paths for a single agent.
+ * Returns null for paths that don't exist.
+ * Phase 0: tries canonical (bare) ID first, then onto_ fallback.
+ */
+export function resolveLearningFilePaths(agentId, projectRoot) {
+    const raw = resolveRawPaths(agentId, projectRoot);
+    const userResolved = resolveWithFallback(raw.userDir, agentId);
+    const projectResolved = raw.projectDirExists
+        ? resolveWithFallback(raw.projectDir, agentId)
+        : null;
+    return {
+        user_path: fs.existsSync(userResolved) ? userResolved : null,
+        project_path: projectResolved && fs.existsSync(projectResolved) ? projectResolved : null,
+    };
+}
+/**
+ * Resolve the single write target for learning accumulation.
+ *
+ * Product Locality Principle (§2.2): always write to product scope.
+ * If `{project}/.onto/learnings/` does not exist, create it.
+ * read_paths: both user and project (A-10 dedup). Dual-write 금지.
+ * Phase 0: write always uses canonical (bare) ID. Read checks both bare + onto_ fallback.
+ */
+export function resolveWritePaths(agentId, projectRoot) {
+    const canonicalId = canonicalizeAgentId(agentId);
+    const raw = resolveRawPaths(canonicalId, projectRoot);
+    // Read paths: collect all existing files (canonical + legacy) for dedup
+    const readPaths = [];
+    const userResolved = resolveWithFallback(raw.userDir, agentId);
+    if (fs.existsSync(userResolved))
+        readPaths.push(userResolved);
+    if (raw.projectDirExists) {
+        const projectResolved = resolveWithFallback(raw.projectDir, agentId);
+        if (fs.existsSync(projectResolved))
+            readPaths.push(projectResolved);
+    }
+    // Write path: always product scope (Product Locality Principle §2.2).
+    // Create the directory if it doesn't exist yet.
+    if (!raw.projectDirExists) {
+        fs.mkdirSync(raw.projectDir, { recursive: true });
+    }
+    return { write_path: raw.projectPath, write_scope: "product", read_paths: readPaths };
+}

package/dist/core-runtime/learning/shared/paths.test.js

@@ -0,0 +1,79 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveLearningFilePaths, resolveWritePaths } from "./paths.js";
+describe("paths — Phase 0 dual-read (W-A-01)", () => {
+    let tmpProject;
+    let tmpHome;
+    let originalHome;
+    beforeEach(() => {
+        tmpProject = fs.mkdtempSync(path.join(os.tmpdir(), "onto-paths-test-"));
+        tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "onto-home-test-"));
+        originalHome = process.env.HOME;
+        process.env.HOME = tmpHome;
+        fs.mkdirSync(path.join(tmpHome, ".onto", "learnings"), { recursive: true });
+        fs.mkdirSync(path.join(tmpProject, ".onto", "learnings"), { recursive: true });
+    });
+    afterEach(() => {
+        if (originalHome !== undefined)
+            process.env.HOME = originalHome;
+        fs.rmSync(tmpProject, { recursive: true, force: true });
+        fs.rmSync(tmpHome, { recursive: true, force: true });
+    });
+    describe("resolveLearningFilePaths — read fallback", () => {
+        it("prefers canonical (bare) path when both exist", () => {
+            fs.writeFileSync(path.join(tmpHome, ".onto", "learnings", "logic.md"), "canonical");
+            fs.writeFileSync(path.join(tmpHome, ".onto", "learnings", "onto_logic.md"), "legacy");
+            const result = resolveLearningFilePaths("logic", tmpProject);
+            expect(result.user_path).toMatch(/logic\.md$/);
+            expect(result.user_path).not.toMatch(/onto_logic\.md$/);
+        });
+        it("falls back to onto_ legacy when canonical absent", () => {
+            fs.writeFileSync(path.join(tmpHome, ".onto", "learnings", "onto_axiology.md"), "legacy");
+            const result = resolveLearningFilePaths("axiology", tmpProject);
+            expect(result.user_path).toMatch(/onto_axiology\.md$/);
+        });
+        it("returns null when neither exists", () => {
+            const result = resolveLearningFilePaths("structure", tmpProject);
+            expect(result.user_path).toBeNull();
+            expect(result.project_path).toBeNull();
+        });
+        it("accepts onto_ prefixed input and resolves to bare canonical first", () => {
+            fs.writeFileSync(path.join(tmpHome, ".onto", "learnings", "semantics.md"), "canonical");
+            const result = resolveLearningFilePaths("onto_semantics", tmpProject);
+            expect(result.user_path).toMatch(/semantics\.md$/);
+            expect(result.user_path).not.toMatch(/onto_semantics\.md$/);
+        });
+    });
+    describe("resolveWritePaths — always canonical write", () => {
+        it("writes to bare canonical filename even with onto_ prefixed input", () => {
+            const result = resolveWritePaths("onto_evolution", tmpProject);
+            expect(result.write_path).toMatch(/evolution\.md$/);
+            expect(result.write_path).not.toMatch(/onto_evolution\.md$/);
+        });
+        it("write_scope is product per Product Locality Principle", () => {
+            const result = resolveWritePaths("coverage", tmpProject);
+            expect(result.write_scope).toBe("product");
+        });
+        it("read_paths includes both canonical and legacy when present", () => {
+            fs.writeFileSync(path.join(tmpHome, ".onto", "learnings", "pragmatics.md"), "user-canonical");
+            fs.writeFileSync(path.join(tmpProject, ".onto", "learnings", "onto_pragmatics.md"), "project-legacy");
+            const result = resolveWritePaths("pragmatics", tmpProject);
+            expect(result.read_paths.length).toBeGreaterThanOrEqual(2);
+            expect(result.read_paths.some(p => p.endsWith("pragmatics.md"))).toBe(true);
+            expect(result.read_paths.some(p => p.endsWith("onto_pragmatics.md"))).toBe(true);
+        });
+        it("creates project learnings dir if missing", () => {
+            const freshProject = fs.mkdtempSync(path.join(os.tmpdir(), "onto-fresh-"));
+            try {
+                const result = resolveWritePaths("structure", freshProject);
+                expect(fs.existsSync(path.join(freshProject, ".onto", "learnings"))).toBe(true);
+                expect(result.write_scope).toBe("product");
+            }
+            finally {
+                fs.rmSync(freshProject, { recursive: true, force: true });
+            }
+        });
+    });
+});

package/dist/core-runtime/learning/shared/patterns.js

@@ -0,0 +1,37 @@
+/**
+ * Shared regex patterns for learning pipeline — Phase 1~3 공용.
+ *
+ * Extraction patterns (§1.4): TAG_PATTERN, SOURCE_PATTERN, GUARDRAIL_PATTERN, CONTENT_CAPTURE
+ * Consumption patterns (loader.ts): ITEM_LINE_RE, APPLICABILITY_RE, ROLE_RE, IMPACT_RE
+ */
+// ---------------------------------------------------------------------------
+// Extraction patterns (§1.4 — Phase 2 extractor, Phase 3 promote)
+// ---------------------------------------------------------------------------
+/** Full line validation — A-8, P-2, C-2 */
+export const TAG_PATTERN = /^[-*+]\s+\[(fact|judgment)\](?:\s+\[(?:methodology|domain\/[^\]]+)\])+(?:\s+\[(?:guardrail|foundation|convention)\])?\s+(.+?)\s+\(source:\s*[^,]+,\s*[^,]+,\s*\d{4}-\d{2}-\d{2}\)\s+\[impact:(high|normal)\]\s*$/u;
+/** Source metadata extraction — A-8, P-2 */
+export const SOURCE_PATTERN = /\(source:\s*([^,]+),\s*([^,]+),\s*(\d{4}-\d{2}-\d{2})\)/;
+/** Guardrail 3-element check — A-9 (role=guardrail only) */
+export const GUARDRAIL_PATTERN = /\*\*Situation\*\*:.*\*\*Result\*\*:.*\*\*Corrective action\*\*:/s;
+/** Content extraction — A-10/P-3 exact match. Boundary aligned with TAG_PATTERN (CCNS-1). */
+export const CONTENT_CAPTURE = /\[(?:fact|judgment)\](?:\s+\[[^\]]+\])+\s+(.+?)\s+\(source:\s*[^,]+,\s*[^,]+,\s*\d{4}-\d{2}-\d{2}\)/;
+// ---------------------------------------------------------------------------
+// Consumption patterns (loader.ts — Phase 1/1.5 reader)
+// ---------------------------------------------------------------------------
+/** Line-start type detection (best-effort parser) */
+export const ITEM_LINE_RE = /^[-*+]\s+\[(fact|judgment)\]\s+/;
+/** Applicability tag extraction (global — use with new RegExp or exec loop) */
+export const APPLICABILITY_RE = /\[(methodology|domain\/[^\]]+)\]/g;
+/** Role extraction (includes insight for legacy compat — loader maps to null) */
+export const ROLE_RE = /\[(guardrail|foundation|convention|insight)\]/;
+/** Impact extraction */
+export const IMPACT_RE = /\[impact:(high|normal)\]/;
+// ---------------------------------------------------------------------------
+// LLM output patterns (Phase 2 — before source metadata is added)
+// ---------------------------------------------------------------------------
+/** Raw LLM output line — §1.1 format (no source metadata yet) */
+export const RAW_LLM_LINE_RE = /^[-*+]\s+\[(fact|judgment)\](?:\s+\[(?:methodology|domain\/[^\]]+)\])+(?:\s+\[(?:guardrail|foundation|convention)\])?\s+(.+?)\s+\[impact:(high|normal)\]\s*$/u;
+/** Newly Learned section header */
+export const NEWLY_LEARNED_HEADER_RE = /^###\s+Newly\s+Learned\s*$/m;
+/** Event Markers section header */
+export const EVENT_MARKERS_HEADER_RE = /^###\s+Applied\s+Learnings\s+—\s+Event\s+Markers\s*$/m;