oh-my-second-brain 0.1.7 → 0.1.8

package/adapters/README.md

@@ -82,7 +82,8 @@ In the current repository, `src/mcp/server.ts` starts a real stdio MCP server vi
 
 The MCP server currently exposes status/read/cache/retrieve/capture tools:
 `oms_graph_status`, `oms_graph_build`, `oms_list_concepts`,
-`oms_retrieve_context`, `oms_retrieve_by_axis`, `oms_lazy_load_note`,
+`oms_retrieve_context`, `oms_sync_embeddings`, `oms_get_document`, `oms_multi_get_documents`,
+`oms_retrieve_by_axis`, `oms_lazy_load_note`,
 `oms_validate_contract`, `oms_capture_prepare`, and `oms_capture_commit`.
 Capture commit is gated by path-safety, vault-confinement, and contract validation. The CLI (`oms setup`, `oms install`, `oms uninstall`, `oms doctor`) remains the real surface for lifecycle commands.
 

package/adapters/claude-code/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "oms",
-  "version": "0.1.7",
-  "description": "Oh My Second Brain convention layer for Obsidian vaults \u2014 capture, retrieve, and validate knowledge under a declared semantic convention.",
+  "version": "0.1.8",
+  "description": "Oh My Second Brain convention layer for Obsidian vaults — capture, retrieve, and validate knowledge under a declared semantic convention.",
   "author": {
     "name": "gobeumsu"
   },
@@ -19,6 +19,7 @@
     "./skills/define/",
     "./skills/capture/",
     "./skills/retrieve/",
-    "./skills/uninstall/"
+    "./skills/uninstall/",
+    "./skills/update/"
   ]
 }

package/adapters/claude-code/hooks/oms-guard.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * oms-guard — thin PreToolUse wrapper for Claude Code settings.json.
+ *
+ * Filters vault-relevant Write/Edit tool calls and delegates to
+ * `oms hook pre-tool-use --vault <vault>` only when the target path is
+ * inside a configured vault. Vault 무관 호출은 spawn 없이 즉시 통과.
+ *
+ * Configuration (env vars set by the settings.json hook definition):
+ *   OMS_VAULT        — primary vault path (e.g. /Users/…/Ataraxia)
+ *   OMS_AGENT_VAULT  — agent vault path  (e.g. /Users/…/agent)
+ *   OMS_GUARD        — set to "off" to bypass all checks
+ *
+ * Fail-open: any error (oms crash, timeout, invalid JSON) → {"continue": true}.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const WRITE_TOOLS = new Set(["Write", "write", "Edit", "edit"]);
+
+/**
+ * Resolve how to invoke the oms CLI for the hook.
+ *
+ * Prefer running the co-located dist entry via `node <dist>` so the guard is
+ * immune to the `oms` bin losing its executable bit on a bare `tsc` rebuild
+ * (which silently breaks `spawnSync("oms")` with EACCES and fails the guard
+ * open). Fall back to the `oms` bin on PATH only if dist can't be located.
+ */
+function resolveOmsCommand() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const dist = resolve(here, "../../../dist/cli/oms.js");
+    if (existsSync(dist)) return { cmd: process.execPath, prefix: [dist] };
+  } catch {
+    // fall through to PATH lookup
+  }
+  return { cmd: "oms", prefix: [] };
+}
+
+function allow() {
+  process.stdout.write(JSON.stringify({ continue: true, suppressOutput: true }) + "\n");
+}
+
+async function readStdin(timeoutMs = 5000) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        process.stdin.removeAllListeners();
+        resolve(Buffer.concat(chunks).toString("utf-8"));
+      }
+    }, timeoutMs);
+    process.stdin.on("data", (c) => chunks.push(c));
+    process.stdin.on("end", () => {
+      if (!settled) { settled = true; clearTimeout(timer); resolve(Buffer.concat(chunks).toString("utf-8")); }
+    });
+    process.stdin.on("error", () => {
+      if (!settled) { settled = true; clearTimeout(timer); resolve(""); }
+    });
+    if (process.stdin.readableEnded) {
+      if (!settled) { settled = true; clearTimeout(timer); resolve(Buffer.concat(chunks).toString("utf-8")); }
+    }
+  });
+}
+
+async function main() {
+  // Global escape hatch.
+  if (process.env.OMS_GUARD === "off") { allow(); return; }
+
+  const vaultPaths = [
+    process.env.OMS_VAULT,
+    process.env.OMS_AGENT_VAULT,
+  ].filter(Boolean);
+
+  // No vaults configured → pass through.
+  if (vaultPaths.length === 0) { allow(); return; }
+
+  let rawInput;
+  try { rawInput = await readStdin(); }
+  catch { allow(); return; }
+
+  let data;
+  try { data = JSON.parse(rawInput); }
+  catch { allow(); return; }
+
+  const toolName = data.tool_name || data.toolName || "";
+
+  // Skip non-Write/Edit tools immediately — zero spawn overhead.
+  if (!WRITE_TOOLS.has(toolName)) { allow(); return; }
+
+  const toolInput = data.tool_input || data.toolInput || {};
+  const filePath = String(toolInput.path || toolInput.file_path || "");
+  if (!filePath) { allow(); return; }
+
+  // Determine which vault this path belongs to.
+  const targetVault = vaultPaths.find(
+    (v) => filePath === v || filePath.startsWith(v + "/"),
+  );
+  if (!targetVault) { allow(); return; }
+
+  // Spawn `oms hook pre-tool-use --vault <vault>` with the raw stdin payload.
+  try {
+    const { cmd, prefix } = resolveOmsCommand();
+    const result = spawnSync(
+      cmd,
+      [...prefix, "hook", "pre-tool-use", "--vault", targetVault],
+      { input: rawInput, encoding: "utf-8", timeout: 10000 },
+    );
+    if (result.status === 0 && result.stdout && result.stdout.trim()) {
+      process.stdout.write(result.stdout);
+    } else {
+      // oms exited non-zero or produced no output → fail-open.
+      if (result.stderr) process.stderr.write("[oms-guard] " + result.stderr);
+      allow();
+    }
+  } catch {
+    // spawn failure → fail-open.
+    allow();
+  }
+}
+
+main().catch(() => allow());

package/adapters/claude-code/hooks/oms-post-guard.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * oms-post-guard — thin PostToolUse wrapper for Claude Code settings.json.
+ *
+ * Filters vault-relevant Write/Edit completions and delegates to
+ * `oms hook post-tool-use --vault <vault>` for frontmatter audit and
+ * graph cache debounce. Vault 무관 호출은 spawn 없이 즉시 통과.
+ *
+ * Configuration (env vars set by the settings.json hook definition):
+ *   OMS_VAULT        — primary vault path
+ *   OMS_AGENT_VAULT  — agent vault path
+ *
+ * Fail-open: any error → silent return (PostToolUse hooks are advisory).
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const WRITE_TOOLS = new Set(["Write", "write", "Edit", "edit"]);
+
+/**
+ * Resolve how to invoke the oms CLI. Prefer `node <dist>` over the `oms` bin so
+ * the hook survives a bare `tsc` rebuild stripping the bin's executable bit
+ * (which makes spawnSync("oms") fail with EACCES). Fall back to PATH `oms`.
+ */
+function resolveOmsCommand() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const dist = resolve(here, "../../../dist/cli/oms.js");
+    if (existsSync(dist)) return { cmd: process.execPath, prefix: [dist] };
+  } catch {
+    // fall through to PATH lookup
+  }
+  return { cmd: "oms", prefix: [] };
+}
+
+async function readStdin(timeoutMs = 5000) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        process.stdin.removeAllListeners();
+        resolve(Buffer.concat(chunks).toString("utf-8"));
+      }
+    }, timeoutMs);
+    process.stdin.on("data", (c) => chunks.push(c));
+    process.stdin.on("end", () => {
+      if (!settled) { settled = true; clearTimeout(timer); resolve(Buffer.concat(chunks).toString("utf-8")); }
+    });
+    process.stdin.on("error", () => {
+      if (!settled) { settled = true; clearTimeout(timer); resolve(""); }
+    });
+    if (process.stdin.readableEnded) {
+      if (!settled) { settled = true; clearTimeout(timer); resolve(Buffer.concat(chunks).toString("utf-8")); }
+    }
+  });
+}
+
+async function main() {
+  const vaultPaths = [
+    process.env.OMS_VAULT,
+    process.env.OMS_AGENT_VAULT,
+  ].filter(Boolean);
+
+  if (vaultPaths.length === 0) return;
+
+  let rawInput;
+  try { rawInput = await readStdin(); }
+  catch { return; }
+
+  let data;
+  try { data = JSON.parse(rawInput); }
+  catch { return; }
+
+  const toolName = data.tool_name || data.toolName || "";
+  if (!WRITE_TOOLS.has(toolName)) return;
+
+  const toolInput = data.tool_input || data.toolInput || {};
+  const filePath = String(toolInput.path || toolInput.file_path || "");
+  if (!filePath) return;
+
+  const targetVault = vaultPaths.find(
+    (v) => filePath === v || filePath.startsWith(v + "/"),
+  );
+  if (!targetVault) return;
+
+  try {
+    const { cmd, prefix } = resolveOmsCommand();
+    const result = spawnSync(
+      cmd,
+      [...prefix, "hook", "post-tool-use", "--vault", targetVault],
+      { input: rawInput, encoding: "utf-8", timeout: 30000 },
+    );
+    // Forward any additionalContext output from the post-tool-use hook.
+    if (result.status === 0 && result.stdout && result.stdout.trim()) {
+      process.stdout.write(result.stdout);
+    }
+    if (result.stderr) process.stderr.write("[oms-post-guard] " + result.stderr);
+  } catch {
+    // Fail silently — post-tool-use is advisory.
+  }
+}
+
+main().catch(() => {});

package/adapters/claude-code/skills/compile/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: oms-compile
+description: Stateless per-concept compile worker — synthesizes a concept wiki page from source materials with SHA-incremental skip, provenance weighting, and cascade backlinks.
+---
+
+# Skill: oms-compile (Claude Code)
+
+Synthesize a concept wiki page from source materials using the OMS compile engine.
+
+## Invocation
+
+```
+/oms-compile
+```
+
+## What this skill does
+
+Conceptually shells out to:
+
+```bash
+oms compile <concept>
+```
+
+Thin pointer to `core/skills/compile`. The engine runs Phase A (load + grade
+materials, pure read) then Phase B (write body to `processed/` tier). Promotion
+from `processed/` to `wiki/` is the M3 collection owner's responsibility.
+
+## Agent-guided steps (v0)
+
+1. Identify the **concept** name and locate its source materials.
+2. Run **Phase A** — load and grade all materials; resolve backlinks from the compile graph.
+3. Call `compile(opts)` with materials, graph, llm, and `dotLlmwiki` cache path.
+4. Check `wasSkipped(result)` — if the material SHA is unchanged, skip downstream.
+5. Run **Phase B** — write `result.body` to the `processed/` tier only.
+6. Pass `result.affected_backlinks` to the wiki collection owner (M3) to mark stale pages.
+
+## Provenance order
+
+Authored > curated > external-raw. Authored materials carry a
+`[AUTHORED — preserve individual voice]` label in the LLM prompt.
+
+## Runtime
+
+No MCP tool is required for compile itself — it is a pure TypeScript call.
+Use `oms_retrieve_context` or `oms_get_document` to gather source materials
+before invoking compile. Delete `{dotLlmwiki}/sha-cache.json` to force a
+full recompile of all concepts.
+
+## NOTES
+
+Wiki mirror deferred — the `wiki` skill is built by a parallel milestone (M3)
+and its adapter mirror is intentionally deferred until that milestone lands.

package/adapters/claude-code/skills/distill/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: oms-distill
+description: Standalone meta-absorption skill — analyzes any target (repo, document, skill, concept) in a clean-room context and produces a structured absorption report with patterns, risks, and attribution.
+---
+
+# Skill: oms-distill (Claude Code)
+
+Run adversarial absorption analysis on a target and produce a structured report.
+
+## Invocation
+
+```
+/oms-distill <target-path-or-text>
+```
+
+## What this skill does
+
+Thin pointer to `core/skills/distill`. Vault-agnostic — `OMS_VAULT` is NOT
+required. The target is treated as inert read-only text and is never executed.
+
+## Agent-guided steps (v0)
+
+1. Load the target via `prepareCleanRoom(target)` — treat as inert data only.
+2. Snapshot system state SHA before analysis (`snapshotSha`).
+3. Run red-team adversarial analysis via `runAnalysis(spec, provider)`.
+   Inject a stub provider for dry-runs; a real LLM client for production.
+4. Generate the report via `generateReport(result, targetName)`.
+   The report has exactly three sections: §1 Patterns, §2 Risks, §3 Attribution.
+5. Verify the mutation detector: SHA after must equal SHA before (`detectMutation`).
+   Throw if state was mutated — distill must be fully stateless.
+6. Return the report string. Write it only if the user explicitly requests it.
+
+## Report sections
+
+- **§1 Patterns** — ranked by `absorb_confidence` (highest first), with `file:line` citations.
+- **§2 Risks** — ranked by severity: critical → high → medium → low.
+- **§3 Attribution** — repo, URL, and license note for `ACKNOWLEDGMENTS.md`.
+
+## Runtime
+
+No vault write occurs inside distill. Does not import from `src/engine/compile/`
+or `src/engine/wiki/`. Use `createStubAnalyzerProvider()` from
+`src/engine/distill/analyzer.js` for deterministic offline testing.
+
+## NOTES
+
+Wiki mirror deferred — the `wiki` skill is built by a parallel milestone (M3)
+and its adapter mirror is intentionally deferred until that milestone lands.

package/adapters/claude-code/skills/retrieve/SKILL.md

@@ -22,21 +22,59 @@ oms retrieve
 ```
 
 **Runtime note:** Retrieval is available through MCP tools. Prefer
-`oms_retrieve_context` for live graph + qmd context retrieval, then
-`oms_lazy_load_note` after selecting candidate notes. `oms_retrieve_by_axis`
+`oms_retrieve_context` for live graph + semantic context retrieval, use
+`oms_sync_embeddings` when the native semantic index must be refreshed, then
+`oms_get_document` or `oms_multi_get_documents` for selected semantic evidence
+or `oms_semantic_query`/`oms_semantic_status` for qmd-compatible follow-ups,
+and `oms_lazy_load_note` for selected vault-note bodies. `oms_retrieve_by_axis`
 remains available for legacy cache-backed axis retrieval.
 
+## Typed query interface
+
+Pass `semanticSearches` to issue typed sub-queries in a single call:
+
+| type    | behaviour                                        |
+|---------|--------------------------------------------------|
+| `lex`   | BM25 keyword search (exact terms, fast)          |
+| `vec`   | SQLite-vector semantic search (meaning-based)    |
+| `hyde`  | Hypothetical-document expansion before search    |
+| `graph` | Semantic candidates confined to graph neighbors  |
+
+```
+semanticSearches: [
+  { type: "lex",   query: "transformer attention" },
+  { type: "vec",   query: "self-attention replaces recurrence" },
+  { type: "hyde",  query: "a paper about attention mechanisms" },
+  { type: "graph", query: "related concepts in my notes" }
+]
+```
+
+Use `semanticScope: "global"` (default) for vault-wide semantic search.
+Use `semanticScope: "graph"` (**gph mode**) to confine semantic candidates
+to the set already selected by the OMS graph traversal.
+
 ## Agent-guided steps (v0)
 
 1. Clarify the user's **retrieval purpose** (synthesize, audit, plan, review, etc.).
 2. Narrow by declared **folder/concept/property/wikilink axes** where possible.
 3. Match the purpose to a declared **retrieval view** (`lenses` in YAML) in `vault/.oms/concepts/*.yaml`.
 4. Call MCP `oms_retrieve_context` with the best available axes and query.
-5. Use default `qmdScope: "global"` for broad semantic search; use
-   `qmdScope: "graph"` only when qmd must stay inside the selected graph
-   candidates.
-6. For each note, return the retrieval-view fields and lazy-load body only when needed.
-7. Return results grouped by concept/folder with retrieval-view frontmatter.
+5. Choose semantic scope: `semanticScope: "global"` for broad vault-wide search;
+   `semanticScope: "graph"` (gph mode) when candidates must stay inside the
+   selected graph neighbors. Pass typed sub-queries via `semanticSearches`
+   using `lex`, `vec`, `hyde`, or `graph` types as appropriate.
+   Pass `semanticMode`, `semanticIntent`, `semanticLex`, `semanticVec`,
+   `semanticHyde`, and `semanticMinScore` for additional control.
+   Use `semanticStorage: "qmd-sqlite"` for the default qmd-compatible SQLite
+   store; set `embeddingSyncBeforeSearch: true` only when the native semantic
+   index must be refreshed before retrieval.
+6. Use `oms_sync_embeddings` for explicit update/embed sync.
+7. Use `oms_semantic_query`, `oms_semantic_status`, `oms_semantic_collections`,
+   or `oms_semantic_contexts` for qmd-compatible follow-ups on the native OMS index.
+8. Use read-only `oms_get_document` or `oms_multi_get_documents` to rehydrate
+   selected docids, paths, globs, or line ranges.
+9. For each note, return the retrieval-view fields and lazy-load body only when needed.
+10. Return results grouped by concept/folder with retrieval-view frontmatter.
 
 ## Example
 
@@ -55,6 +93,10 @@ Purpose: "Synthesize my transformer papers"
 
 ## Runtime
 
-Use MCP `oms_retrieve_context` for live graph/qmd retrieval. Use MCP
-`oms_retrieve_by_axis` only for legacy axis-first cache retrieval. Use MCP
-`oms_lazy_load_note` only after selecting candidate notes.
+Use MCP `oms_retrieve_context` for live graph/semantic retrieval. Pass typed
+sub-queries via `semanticSearches` (types: `lex`, `vec`, `hyde`, `graph`).
+Use `semanticScope: "graph"` (gph mode) to confine semantic candidates to
+graph neighbors. Use MCP `oms_sync_embeddings` for native semantic-index sync.
+Use MCP `oms_get_document` or `oms_multi_get_documents` for document rehydration.
+Use MCP `oms_retrieve_by_axis` only for legacy axis-first cache retrieval.
+Use MCP `oms_lazy_load_note` only after selecting candidate notes.

package/adapters/claude-code/skills/setup/SKILL.md

@@ -19,14 +19,17 @@ This skill is **REAL in v0** — it shells out to the fully-implemented CLI.
 Shells out to:
 
 ```bash
-oms setup [--vault <path>] [--yes] [--install-claude]
+oms setup [--vault <path>] [--yes] [--suggest-fields] [--install-claude]
 oms install [--runtime <auto|all|claude|codex|hermes>] [--vault <path>] [--dry-run] [--execute] [--yes]
 ```
 
 The CLI will:
 1. Scan your vault's existing top-level folders (does NOT impose a structure).
-2. Interactively ask the `intent` for each folder (use `--yes` to skip prompts).
-3. Write `vault/.oms/taxonomy.yaml` and copy default concept schemas.
+2. Interactively ask each folder's intent and concept binding (use `--yes` to accept defaults).
+3. Summarize observed frontmatter fields without changing notes.
+4. Optionally add selected observed fields to concept schemas with `--suggest-fields`.
+5. Ask for retrieval lenses and reject lenses that reference unknown fields.
+6. Write `vault/.oms/taxonomy.yaml` and preserve existing `vault/.oms/concepts/` files while adding missing defaults.
 
 ## Options
 
@@ -34,6 +37,7 @@ The CLI will:
 |------|-------------|
 | `--vault <path>` | Path to your Obsidian vault root (default: current directory) |
 | `--yes` | Non-interactive: accept all defaults, no prompts |
+| `--suggest-fields` | Merge observed note frontmatter fields into concept schemas without mutating notes. |
 | `--install-claude` | Legacy setup-only dry-run that prints Claude Code plugin install and MCP registration commands. |
 | `install --runtime <name>` | Install host adapter/MCP registration for `auto`, `all`, `claude`, `codex`, or `hermes`. |
 | `install --dry-run` | Preview host writes without mutating config. |
@@ -45,6 +49,9 @@ The CLI will:
 # Interactive (recommended first run):
 oms setup --vault ~/Documents/MyVault
 
+# Interactive setup with observed frontmatter field suggestions:
+oms setup --vault ~/Documents/MyVault --suggest-fields
+
 # Non-interactive (CI / scripted):
 oms setup --vault ~/Documents/MyVault --yes
 

package/adapters/claude-code/skills/update/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: oms-update
+description: Update Oh My Second Brain and refresh installed host adapters.
+---
+
+# Skill: oms-update (Claude Code)
+
+Update the globally installed Oh My Second Brain package and reconcile host adapter surfaces.
+
+## Invocation
+
+```
+/oms-update
+```
+
+## What this skill does
+
+Shells out to:
+
+```bash
+oms update [--runtime <auto|all|claude|codex|hermes>] [--vault <path>] [--dry-run] [--yes]
+```
+
+The CLI will:
+1. Check the latest `oh-my-second-brain` version on npm.
+2. Print the planned package update and adapter reconciliation commands unless `--yes` is provided.
+3. With `--yes`, run `npm install -g oh-my-second-brain@latest`.
+4. Refresh host adapter/MCP registrations for the selected runtime.
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--vault <path>` | Vault path used for MCP registration refresh. |
+| `--runtime <name>` | Refresh `auto`, `all`, `claude`, `codex`, or `hermes`. |
+| `--dry-run` | Preview update and reconciliation commands without mutating anything. |
+| `--yes` | Perform the package update and adapter reconciliation. |
+| `--execute` | Allow external host CLIs during reconciliation where available. |
+
+## Example
+
+```bash
+oms update --dry-run --runtime all --vault ~/Documents/MyVault
+oms update --yes --runtime all --vault ~/Documents/MyVault
+```

package/adapters/claude-code/skills/vault-decision-record/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: oms-vault-decision-record
+description: Records vault structural changes as ADR markdown in .oms/governance/decisions/. Update rule is SUPERSEDE-ONLY — new ADRs supersede old ones; existing ADRs are never deleted.
+---
+
+# Skill: oms-vault-decision-record (Claude Code)
+
+Record a vault structural decision as an Architecture Decision Record (ADR).
+
+## Invocation
+
+```
+/oms-vault-decision-record
+```
+
+## What this skill does
+
+Thin pointer to `core/skills/vault-decision-record`. Writes append-only ADR
+files to `vaultRoot/.oms/governance/decisions/`. History is permanent — ADRs
+are never deleted or renamed.
+
+## Agent-guided steps (v0)
+
+1. Scan `vaultRoot/.oms/governance/decisions/` for existing `ADR-NNNN-*.md` files
+   to determine the next sequential number. Create the directory if it does not exist.
+2. Slugify `title` (lowercase, hyphens, no special characters).
+3. Write `ADR-{NNNN}-{slug}.md` with the required frontmatter and three body sections:
+   **Context**, **Decision**, **Consequences**.
+4. If `supersedes` is provided, open the referenced ADR and set its `superseded_by`
+   field to the new ADR id. Never delete or rename the old file.
+5. Return `adrPath`, `adrId`, and `supersededPath` (or `null`).
+
+## Update rule — SUPERSEDE-ONLY
+
+- Never delete an existing ADR.
+- Never edit the `decision` or `consequences` body of an existing ADR.
+- To revise a decision, write a new ADR with `supersedes: ADR-{old}`.
+- `superseded_by` in the old ADR is the only mutation allowed on existing files.
+
+## Layer 1 CONTRACT guard
+
+Never read, write, or modify `core/ontology/taxonomy.yaml`,
+`core/ontology/concepts/*.yaml`, or `vaultRoot/.oms/taxonomy.yaml`.
+
+## Runtime
+
+No MCP tool required — this is a pure TypeScript call against the filesystem.
+
+## NOTES
+
+Wiki mirror deferred — the `wiki` skill is built by a parallel milestone (M3)
+and its adapter mirror is intentionally deferred until that milestone lands.

package/adapters/claude-code/skills/vault-lint/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: oms-vault-lint
+description: Checker-lane-only vault linter — enforces the Layer 1 CONTRACT (taxonomy.yaml + concepts/*.yaml) across all notes in a vault via five checks. Never mutates vault files.
+---
+
+# Skill: oms-vault-lint (Claude Code)
+
+Verify that every markdown note in a vault conforms to its declared ontology.
+
+## Invocation
+
+```
+/oms-vault-lint
+```
+
+## What this skill does
+
+Thin pointer to `core/skills/vault-lint`. Runs five CONTRACT checks
+(allowlist, required, type, enum, routing-law) across all notes. Read-only by
+default; autofix requires explicit human-gate approval.
+
+## Agent-guided steps (v0)
+
+1. Load the ontology: `await loadOntology(path.join(vaultRoot, ".oms/ontology"))`.
+2. Call `lintVault(vaultRoot, ontology)`.
+3. If `report.clean` is false, surface `report.violations` to the user.
+   **Do NOT autofix without explicit user approval.**
+4. If autofix is explicitly approved, re-call with `{ autofixEnabled: true }`.
+   (Autofix is a no-op in v0.1.0 — reserved for a future human-gate protocol.)
+
+## Five checks
+
+1. **allowlist** — no frontmatter key outside the concept's declared field list.
+2. **required** — required fields must be present and non-empty.
+3. **type** — values must match the declared `FieldType` (string / url / date / list / number / boolean).
+4. **enum** — string fields with an `enum` array must use a listed value.
+5. **routing-law** — notes in agent-writable taxonomy zones must carry `created_by`.
+
+## Runtime
+
+`lintVault` returns a `VaultLintReport`: `violations`, `scannedNotes`, `clean`.
+No MCP tool is required — this is a pure TypeScript call against the filesystem.
+
+## NOTES
+
+Wiki mirror deferred — the `wiki` skill is built by a parallel milestone (M3)
+and its adapter mirror is intentionally deferred until that milestone lands.