onto-mcp 0.3.0

package/CLAUDE.md

@@ -0,0 +1,39 @@
+# CLAUDE.md
+
+## Authority 위계
+
+| 순위 | 역할 | 위치 |
+|---|---|---|
+| 1 | 개념 SSOT | .onto/authority/core-lexicon.yaml |
+| 2 | 개발 원칙: OaC | .onto/principles/ontology-as-code-guideline.md |
+| 2 | 개발 원칙: LLM-Native | .onto/principles/llm-native-development-guideline.md |
+| 2 | 개발 원칙: 비전문가 소통 | .onto/principles/non-specialist-communication-guideline.md |
+| 2 | 개발 원칙: product 우선 | .onto/principles/product-locality-principle.md |
+| 3 | 제품 방향 | .onto/principles/productization-charter.md |
+| 4 | 인터페이스 명세 | .onto/principles/llm-runtime-interface-principles.md |
+| 4 | 이름 규칙 | .onto/principles/ontology-as-code-naming-charter.md |
+| 5 | 기능별 계약 | .onto/processes/{feature}/*.md (계약 파일) |
+| 6 | 타입·구현 | src/core-runtime/ |
+| 7 | 기능 프로세스 | .onto/processes/review/*.md, .onto/roles/*.md |
+| 8 | 개발 기록 | development-records/ |
+
+.onto/authority/ 구성: 개념 SSOT + runtime lens registry (core-lens-registry.yaml)
+.onto/principles/ 구성: rank 2~4 개발 규범 문서 7개 (배포 제외)
+위계 밖: development-records/ (이력/참조)
+
+## current runtime 구조
+
+```
+src/core-runtime/
+├── cli/                    ← review bounded step entrypoints
+├── discovery/              ← settings, onto home, lens registry
+├── llm/                    ← provider switcher + LLM call wrappers
+├── review/                 ← review artifact types, materializers, deliberation, route policy
+├── logger.ts               ← 공용 로거
+```
+
+- **review**: 현재 제품화 대상. context-isolated lenses, controlled deliberation, synthesize, ReviewRecord를 소유한다.
+- **llm**: API key / OAuth / local provider selection을 단순화한 runtime boundary다.
+- **development-records/archive/**: retired CLI/process/learning/govern/evolve material을 격리 보관한다.
+
+동일 순위 충돌 해소: 같은 순위 파일은 규범 내용이 중복되지 않는다. 중복 발견 시, 원칙의 성격에 부합하는 파일이 canonical이며, 나머지는 참조만 한다. 예외: 동일 개념이 서로 다른 소비 목적(구조 규칙 vs 설계 가이드)으로 필요한 경우, 각 파일의 고유 범위를 확정하고 상호 참조를 명기하여 이중 존재를 허용한다.

package/README.md

@@ -0,0 +1,287 @@
+# Onto MCP
+
+`onto-mcp` is the TypeScript product core for ontology-as-code review. The
+public interface is MCP-native; repository-local npm scripts remain development
+harnesses for verification and debugging.
+
+```text
+.onto contracts and domain documents
+        -> TS review runtime
+        -> core API facade
+        -> MCP tools
+        -> provider adapters
+```
+
+## Current Product Slice
+
+The active implementation target is `review`.
+
+Across `review`, `reconstruct`, and future `evolve`, targets are not assumed to
+be code. Runtime contracts classify the material form with
+`target_material_kind` (`code`, `spreadsheet`, `document`, `database`, `mixed`,
+or `unknown`) before choosing observation, validation, or adapter behavior. The
+cross-process goal contract lives at
+`.onto/processes/shared/target-material-kind-contract.md`.
+
+`review` performs:
+
+1. invocation interpretation and binding
+2. execution preparation artifacts
+3. isolated parallel lens execution
+4. issue ledger and issue stance closure artifacts
+5. controlled lens deliberation
+6. conservative synthesis
+7. `ReviewRecord` assembly
+8. concise human-readable final output
+
+`reconstruct` now has a current design contract under
+`.onto/processes/reconstruct/`, material-aware runtime helpers, and a bounded
+happy-path runner. The runner classifies target material, writes source
+observations, accepts pluggable LLM-owned directive authors and confirmation
+providers, validates evidence refs, computes deterministic metrics, and writes
+`final-output.md`, `reconstruct-run-manifest.yaml`, and the primary
+`reconstruct-record.yaml`. Code is the first fixture; the runner path is shared
+with spreadsheet/document/database material through source profiles and
+material-specific observers. The current public run path is an explicit mock
+semantic/confirmation happy path; domain context selection, failure
+classification, and revision proposal are recorded as deferred scope.
+`evolve` has a future material-kind adapter contract at
+`.onto/processes/evolve/material-kind-adapter-contract.md`, but no active
+runtime or MCP tool. `learn` and `govern` remain separate design slices.
+
+## Public Interface
+
+Install from npm:
+
+```bash
+npm install -g onto-mcp
+```
+
+Start the MCP server:
+
+```bash
+onto mcp
+```
+
+For project-local installs, add `onto-mcp` to the project and run the local
+binary:
+
+```bash
+npm install --save-dev onto-mcp
+npm exec -- onto mcp
+```
+
+Available MCP tools:
+
+| Tool | Purpose |
+|---|---|
+| `onto.review` | Run the full review path and return artifact refs plus summary |
+| `onto.prepare_review` | Prepare a review session and prompt packets |
+| `onto.review_status` | Read structured status and artifact refs |
+| `onto.review_result` | Read `review-record.yaml` and final output |
+| `onto.list_lenses` | List canonical lens sets |
+| `onto.list_domains` | List available domain ids |
+| `onto.list_source_profiles` | List reconstruct source profiles |
+| `onto.observe_source` | Materialize reconstruct material profile, inventory, source observations, and initial record |
+| `onto.validate_reconstruct_directive` | Validate LLM-authored reconstruct directive files |
+| `onto.reconstruct` | Run the material-aware reconstruct happy path with explicit mock semantic/confirmation realization |
+| `onto.reconstruct_status` | Read reconstruct session status and artifact refs |
+| `onto.reconstruct_result` | Read `reconstruct-record.yaml`, run manifest, and final output |
+
+MCP results include `llmPresentation` prompts. The runtime supplies bounded
+facts; the host LLM should use those prompts to explain the opening brief and
+final result to the user without inventing settings or findings.
+
+Minimal reconstruct MCP call shape:
+
+```json
+{
+  "name": "onto.reconstruct",
+  "arguments": {
+    "projectRoot": "/path/to/project",
+    "targetRefs": ["src/example.ts"],
+    "intent": "Create a bounded reconstruct Seed from this target.",
+    "sessionRoot": ".onto/reconstruct/example-run",
+    "semanticAuthorRealization": "mock",
+    "confirmationProviderRealization": "mock"
+  }
+}
+```
+
+`semanticAuthorRealization` and `confirmationProviderRealization` are required
+so completed reconstruct runs are explicit about their current mock semantics.
+Today this proves the material-aware happy path, artifact gates, and MCP
+surface. It does not claim live host-LLM semantic authorship or live
+user-mediated confirmation.
+
+Repository-local development harness:
+
+```bash
+npm run review:invoke -- <target> "<intent>"
+```
+
+`review:invoke` prints a structured start preview before execution begins:
+
+- review target and filesystem boundary
+- request intent
+- selected domain and selection mode
+- review mode and lens ids
+- execution mode, seats, deliberation mode, concurrency
+- model auth/provider/model/effort/service tier
+- settings locations and MCP/dev-harness override points
+
+During execution, the runner prints numbered progress markers for the bounded
+review stages. At completion, it prints a structured result overview:
+
+- outcome status and deliberation status
+- target/domain/review mode
+- planned, participating, and degraded lens counts
+- comprehensive `Final Review Result` explanation from synthesize
+- issue count plus severity/timing/closure classification
+- top problem definitions from `problem-framing.yaml`
+- primary artifact paths
+
+For MCP clients, prefer the `llmPresentation.openingBrief` and
+`llmPresentation.finalResult` prompt/input pairs over CLI stdout when presenting
+start and finish explanations.
+
+Runtime hardening is available as a development verification harness:
+
+```bash
+npm run test:review:hardening
+```
+
+It runs large and repeated mock reviews, validates primary artifact consistency,
+checks `Tools: required` native-tool boundaries, verifies provider preflight
+fail-loud behavior, and removes temporary fixtures unless
+`ONTO_REVIEW_HARDENING_KEEP_TMP=1` is set.
+
+## Settings
+
+Runtime settings live in JSON:
+
+| Path | Role |
+|---|---|
+| `{project}/.onto/settings.json` | project-local settings |
+| `~/.onto/settings.json` | user defaults |
+
+Project settings override user defaults for scalar keys.
+
+Minimal Codex OAuth profile:
+
+```json
+{
+  "llm": {
+    "auth": "oauth",
+    "provider": "openai",
+    "model": "gpt-5.5",
+    "effort": "medium",
+    "service_tier": "fast"
+  },
+  "review": {
+    "execution": {
+      "mode": "main-workers",
+      "teamlead": {
+        "seat": "main",
+        "llm": "inherit"
+      },
+      "lens": {
+        "seat": "worker",
+        "llm": "inherit"
+      },
+      "synthesize": {
+        "seat": "worker",
+        "llm": {
+          "effort": "xhigh"
+        }
+      },
+      "deliberation": "controlled-lens-deliberation"
+    }
+  },
+  "review_mode": "full"
+}
+```
+
+LLM switcher axes:
+
+| auth | provider | Runtime path |
+|---|---|---|
+| `oauth` | `openai` | Codex worker |
+| `api_key` | `openai` | OpenAI API |
+| `api_key` | `anthropic` | Anthropic API |
+| `api_key` | `grok` | xAI/Grok OpenAI-style API |
+| `local` | `lmstudio` | LM Studio OpenAI-style endpoint |
+
+Unsupported settings stop during profile resolution.
+
+## Review Artifacts
+
+A review session writes artifacts under `.onto/review/<session-id>/`.
+
+Primary outputs:
+
+| Artifact | Purpose |
+|---|---|
+| `execution-plan.yaml` | bounded runtime plan |
+| `issue-ledger.yaml` | normalized issue list |
+| `issue-stance-matrix.yaml` | every participating lens stance per issue |
+| `deliberation.md` | teamlead-controlled deliberation result |
+| `problem-framing.yaml` | end-of-review problem classification |
+| `review-run-manifest.yaml` | packet/output refs and hashes |
+| `review-record.yaml` | primary structured review artifact |
+| `final-output.md` | principal-facing report with `Final Review Result` explanation |
+
+## Reconstruct Artifacts
+
+A reconstruct session writes artifacts under `.onto/reconstruct/<session-id>/`.
+
+Implemented happy-path outputs:
+
+| Artifact | Owner | Purpose |
+|---|---|---|
+| `target-material-profile.yaml` | runtime | detected `target_material_kind`, support status, and selected source profiles |
+| `source-inventory.yaml` | runtime | material-specific inventory units and scan boundary |
+| `source-observations.yaml` | runtime | structural observations with stable evidence ids |
+| `source-observation-directive.yaml` | mock/host author | selected observations for evidence use |
+| `source-observation-directive-validation.yaml` | runtime | validation of selected observation refs |
+| `seed-candidate.yaml` | mock/host author | evidence-backed Seed candidate |
+| `seed-candidate-validation.yaml` | runtime | Seed claim and evidence-ref validation |
+| `seed-confirmation.yaml` | mock/host/user mediated | accepted, rejected, or partial Seed confirmation |
+| `competency-questions.yaml` | mock/host author | questions linked to confirmed claims |
+| `reconstruct-metrics.yaml` | runtime | deterministic counts, unresolved count, and pass rate |
+| `stop-decision.yaml` | mock/host author | stop, continue, or ask-user decision based on metrics |
+| `final-output.md` | mock/host author | user-facing result grounded in artifacts |
+| `reconstruct-run-manifest.yaml` | runtime | step refs, `performed_by` provenance, execution profile, and happy-path scope |
+| `reconstruct-record.yaml` | runtime | primary structured reconstruct artifact |
+
+Current deferred reconstruct artifacts are recorded in
+`reconstruct-run-manifest.yaml` under `happy_path_scope.deferred_artifacts`:
+`domain_context_selection`, `failure_classification`, and `revision_proposal`.
+Those require additional host/user semantic decisions and are outside the
+current mock happy path.
+
+## Repository Map
+
+| Path | Role |
+|---|---|
+| `.onto/authority/` | canonical ontology data and runtime registries |
+| `.onto/processes/shared/` | cross-process target and runtime contracts |
+| `.onto/processes/review/` | review contracts |
+| `.onto/processes/reconstruct/` | reconstruct contracts and source profiles |
+| `.onto/domains/` | bundled domain documents |
+| `src/core-runtime/` | TypeScript runtime |
+| `src/core-api/` | library facade used by MCP |
+| `src/mcp/` | MCP tool surface |
+| `development-records/` | development records and archived material |
+| `IMPLEMENTATION_MAP.html` | visual architecture and roadmap map |
+
+## Verification
+
+```bash
+npm run check:ts-core
+npm run build:ts-core
+npm run test:mcp:review
+npm run test:review:hardening
+npm run test:e2e
+git diff --check
+```

package/bin/onto

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+// Public binary entry point for onto-mcp.
+// Uses tsx for TypeScript execution in development.
+// For production, compile first: npm run build
+//
+// Product Locality Principle (.onto/principles/product-locality-principle.md):
+// If a project-local installation exists, delegate execution to it.
+// --global flag bypasses delegation.
+
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ontoRoot = path.resolve(__dirname, "..");
+
+// ---------------------------------------------------------------------------
+// Project-local delegation (§2.1)
+// ---------------------------------------------------------------------------
+
+function findProjectRoot(startDir) {
+  let dir = startDir;
+  while (true) {
+    if (
+      fs.existsSync(path.join(dir, ".onto", "settings.json")) ||
+      fs.existsSync(path.join(dir, ".git")) ||
+      fs.existsSync(path.join(dir, "package.json"))
+    ) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return startDir;
+    dir = parent;
+  }
+}
+
+function tryDelegateToLocal(argv) {
+  if (argv.includes("--global")) return false;
+
+  const projectRoot = findProjectRoot(process.cwd());
+  const localBin = path.join(projectRoot, "node_modules", "onto-mcp", "bin", "onto");
+
+  // Don't delegate to ourselves
+  if (!fs.existsSync(localBin)) return false;
+  const resolvedLocal = fs.realpathSync(localBin);
+  const resolvedSelf = fs.realpathSync(fileURLToPath(import.meta.url));
+  if (resolvedLocal === resolvedSelf) return false;
+
+  // CON-2: Force ONTO_HOME to the local installation to prevent resource mismatch (§3 #5)
+  const localOntoRoot = path.resolve(path.dirname(localBin), "..");
+  try {
+    execSync(`"${process.execPath}" "${localBin}" ${argv.map(a => `"${a}"`).join(" ")}`, {
+      stdio: "inherit",
+      cwd: process.cwd(),
+      env: { ...process.env, ONTO_HOME: localOntoRoot },
+    });
+  } catch (error) {
+    process.exit(error && typeof error === "object" && "status" in error ? Number(error.status) || 1 : 1);
+  }
+  process.exit(0);
+}
+
+const userArgs = process.argv.slice(2);
+
+if (!tryDelegateToLocal(userArgs)) {
+  // ---------------------------------------------------------------------------
+  // No local installation — run from this (global/development) binary
+  // ---------------------------------------------------------------------------
+
+  const distEntry = path.join(ontoRoot, "dist", "cli.js");
+  const srcEntry = path.join(ontoRoot, "src", "cli.ts");
+
+  if (fs.existsSync(distEntry)) {
+    // Production: use compiled JS
+    await import(distEntry);
+  } else {
+    // Development: use tsx
+    const tsxBin = path.join(ontoRoot, "node_modules", ".bin", "tsx");
+    const args = [srcEntry, ...userArgs];
+    try {
+      execSync(`"${tsxBin}" ${args.map(a => `"${a}"`).join(" ")}`, {
+        stdio: "inherit",
+        cwd: process.cwd(),
+        env: { ...process.env, ONTO_HOME: ontoRoot },
+      });
+    } catch (error) {
+      process.exit(error && typeof error === "object" && "status" in error ? Number(error.status) || 1 : 1);
+    }
+  }
+}

package/dist/cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { readOntoVersion } from "./core-runtime/release-channel/release-channel.js";
+/**
+ * Public binary surface for the MCP-native product.
+ *
+ * Product tools are exposed through MCP (`onto mcp`). Review and other
+ * runtime flows are no longer public `onto <activity>` CLI commands. The
+ * `npm run review:*` scripts remain internal development harnesses.
+ */
+function loadOntoEnvFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return;
+    let contents;
+    try {
+        contents = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return;
+    }
+    for (const rawLine of contents.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (!key || process.env[key] !== undefined)
+            continue;
+        process.env[key] = line.slice(eq + 1);
+    }
+}
+function printHelp() {
+    console.log([
+        "Usage: onto mcp",
+        "",
+        "Active interface:",
+        "  mcp            Start the MCP stdio tool server",
+        "",
+        "Available MCP tools:",
+        "  onto.review",
+        "  onto.prepare_review",
+        "  onto.review_status",
+        "  onto.review_result",
+        "  onto.list_lenses",
+        "  onto.list_domains",
+        "  onto.list_source_profiles",
+        "  onto.observe_source",
+        "  onto.validate_reconstruct_directive",
+        "  onto.reconstruct",
+        "  onto.reconstruct_status",
+        "  onto.reconstruct_result",
+        "",
+        "Development harness:",
+        "  npm run review:invoke -- <target> \"<intent>\"",
+        "",
+        "Options:",
+        "  --version, -v  Show version",
+        "  --help, -h     Show this help",
+    ].join("\n"));
+}
+function unsupportedCommandMessage(subcommand) {
+    return [
+        `[onto] Unsupported public CLI subcommand: ${subcommand}`,
+        "Active public command: onto mcp",
+        "Development harness: npm run review:invoke -- <target> \"<intent>\"",
+    ].join("\n");
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const subcommand = argv[0];
+    loadOntoEnvFile(path.join(os.homedir(), ".onto", ".env"));
+    loadOntoEnvFile(path.join(process.cwd(), ".onto", ".env"));
+    switch (subcommand) {
+        case "mcp": {
+            const { startMcpServer } = await import("./mcp/server.js");
+            return startMcpServer();
+        }
+        case "--version":
+        case "-v": {
+            const version = await readOntoVersion();
+            console.log(`onto-mcp ${version}`);
+            return 0;
+        }
+        case "--help":
+        case "-h":
+        case undefined:
+            printHelp();
+            return 0;
+        default:
+            console.error(unsupportedCommandMessage(subcommand));
+            return 1;
+    }
+}
+main().then((exitCode) => process.exit(exitCode), (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});