@jmtrin/kevin-core 1.3.0 → 1.5.0

package/dist/mif.js

@@ -0,0 +1,112 @@
+// K15-008 — MIF codec (plan §4.4)
+// Envelope {id, content, type, timestamp, source, metadata} + vendor extensions preserved + PII redaction + content-hash dedup (import side)
+import { fingerprint as computeFingerprint } from "./fingerprint.js";
+const SECRET_PATTERNS = [
+    /\b(API_KEY|SECRET|PASSWORD|TOKEN)\b\s*[=:]\s*\S+/gi,
+    /\bBearer\s+\S+/gi,
+    /\b(access_?token|auth_?token|api_?token)\b\s*[=:]\s*\S+/gi,
+    /\btoken\s*[=:]\s*\S+/gi,
+    /\baws_secret_access_key\b\s*[=:]\s*\S+/gi,
+    /\bghp_[A-Za-z0-9_]+/g,
+    /\bsk-[A-Za-z0-9_\-]+/g,
+    /\bgithub_pat_[A-Za-z0-9_]+/g,
+];
+function redactSecrets(text) {
+    let out = text;
+    for (const pat of SECRET_PATTERNS) {
+        out = out.replace(pat, (m) => {
+            const eq = m.indexOf("=");
+            const colon = m.indexOf(":");
+            const sep = eq !== -1 ? "=" : colon !== -1 ? ":" : " ";
+            const prefix = m.slice(0, m.indexOf(sep) + 1);
+            return `${prefix}<redacted>`;
+        });
+    }
+    // fallback: if pattern didn't match sep, replace whole token
+    return out;
+}
+function toIso(ts) {
+    try {
+        const iso = ts.includes("T") ? ts : `${ts.replace(" ", "T")}Z`;
+        return new Date(iso).toISOString();
+    }
+    catch {
+        return new Date().toISOString();
+    }
+}
+export function toMif(rows, opts) {
+    const memories = rows.map((r) => {
+        const originalContent = r.content;
+        let content = originalContent;
+        if (opts.redactPii) {
+            content = redactSecrets(content);
+        }
+        const meta = {
+            scope: String(r.scope ?? "project"),
+            fingerprint: String(r.fingerprint ?? computeFingerprint(originalContent)),
+            confidence: String(r.confidence ?? ""),
+            evidence_count: String(r.evidenceCount ?? 0),
+        };
+        const base = {
+            id: r.id,
+            content,
+            type: r.type,
+            timestamp: toIso(r.createdAt ?? new Date().toISOString()),
+            source: "opencode-kevin",
+            metadata: meta,
+        };
+        // preserve unknown fields from original row that are not part of standard mapping
+        // standard keys: id, content, type, createdAt, scope, fingerprint, confidence, evidenceCount, etc.
+        // unknown vendor extensions stored under `mif_vendor` in metadata if present
+        const mifVendor = r.mif_vendor;
+        if (mifVendor && typeof mifVendor === "object") {
+            for (const [k, v] of Object.entries(mifVendor)) {
+                if (!(k in base))
+                    base[k] = v;
+            }
+        }
+        // also check if row has extra top-level keys beyond Memory standard (for codec-level preservation)
+        const extraKeys = Object.keys(r).filter((k) => !["id", "content", "type", "scope", "createdAt", "updatedAt", "fingerprint", "confidence", "evidenceCount", "recurrenceCount", "projectId", "repoId", "layer", "status", "metadata", "origin", "sourceTool", "sourceSession", "relevanceScore", "truthPenalty"].includes(k));
+        for (const k of extraKeys) {
+            if (k === "mif_vendor")
+                continue;
+            if (!(k in base))
+                base[k] = r[k];
+        }
+        return base;
+    });
+    return { format: "mif", version: 1, memories };
+}
+export function fromMif(env) {
+    if (!env || env.format !== "mif" || env.version !== 1 || !Array.isArray(env.memories)) {
+        throw new Error("invalid MIF envelope: expected {format:'mif', version:1, memories:[]}");
+    }
+    const candidates = [];
+    const preserved = new Set();
+    for (const m of env.memories) {
+        const known = new Set(["id", "content", "type", "timestamp", "source", "metadata", "format", "version"]);
+        const unknown = {};
+        for (const k of Object.keys(m)) {
+            if (!known.has(k)) {
+                unknown[k] = m[k];
+                preserved.add(k);
+            }
+        }
+        // also collect vendorExtensions top-level unknown?
+        candidates.push({
+            id: String(m.id),
+            content: String(m.content),
+            type: String(m.type),
+            timestamp: String(m.timestamp),
+            source: String(m.source ?? "opencode-kevin"),
+            metadata: { ...(m.metadata ?? {}) },
+            unknownFields: unknown,
+        });
+    }
+    // top-level vendorExtensions unknown
+    if (env.vendorExtensions) {
+        for (const k of Object.keys(env.vendorExtensions))
+            preserved.add(k);
+    }
+    return { candidates, unknownFieldsPreserved: [...preserved] };
+}

package/dist/migrations/013_v14_bridge.sql

@@ -0,0 +1,46 @@
+-- =============================================================
+-- Kevin v1.4.0 "Bridge" — migration 013
+-- Adds: channel column on kevin_injections, 5 MCP metric seeds,
+--       expands hook CHECK to include pull_mcp (D14-04).
+-- =============================================================
+
+ALTER TABLE kevin_injections ADD COLUMN channel TEXT NOT NULL DEFAULT 'plugin';
+
+-- SQLite cannot ALTER a CHECK constraint, so rebuild to widen hook.
+CREATE TABLE IF NOT EXISTS kevin_injections_new (
+  id              TEXT PRIMARY KEY,
+  memory_id       TEXT NOT NULL,
+  fingerprint     TEXT NOT NULL,
+  session_id      TEXT NOT NULL,
+  hook            TEXT NOT NULL CHECK (hook IN ('pre_prompt','compacting','pull_mcp')),
+  tokens          INTEGER NOT NULL,
+  injected_at     TEXT NOT NULL DEFAULT (datetime('now')),
+  outcome         TEXT NOT NULL DEFAULT 'unmeasured'
+                  CHECK (outcome IN ('unmeasured','effective','ineffective','inconclusive')),
+  injected_at_ms  INTEGER,
+  channel         TEXT NOT NULL DEFAULT 'plugin'
+);
+
+INSERT INTO kevin_injections_new
+  (id, memory_id, fingerprint, session_id, hook, tokens, injected_at, outcome, injected_at_ms, channel)
+SELECT
+  id, memory_id, fingerprint, session_id, hook, tokens, injected_at, outcome, injected_at_ms, channel
+FROM kevin_injections;
+
+DROP TABLE kevin_injections;
+ALTER TABLE kevin_injections_new RENAME TO kevin_injections;
+
+CREATE INDEX IF NOT EXISTS idx_injections_fp       ON kevin_injections(fingerprint);
+CREATE INDEX IF NOT EXISTS idx_injections_session  ON kevin_injections(session_id);
+CREATE INDEX IF NOT EXISTS idx_injections_outcome  ON kevin_injections(outcome);
+CREATE INDEX IF NOT EXISTS idx_injections_channel  ON kevin_injections(channel);
+CREATE INDEX IF NOT EXISTS idx_tool_calls_ts_ms        ON tool_calls(ts_ms);
+CREATE INDEX IF NOT EXISTS idx_injections_injected_ms  ON kevin_injections(injected_at_ms);
+
+INSERT OR IGNORE INTO kevin_metrics (key, value) VALUES ('mcp_requests_total', 0);
+INSERT OR IGNORE INTO kevin_metrics (key, value) VALUES ('mcp_reads_served', 0);
+INSERT OR IGNORE INTO kevin_metrics (key, value) VALUES ('mcp_writes_accepted', 0);
+INSERT OR IGNORE INTO kevin_metrics (key, value) VALUES ('mcp_writes_refused', 0);
+INSERT OR IGNORE INTO kevin_metrics (key, value) VALUES ('mcp_errors_total', 0);
+
+INSERT INTO schema_version (version) VALUES ('013');

package/dist/perf.d.ts

@@ -1,5 +1,5 @@
 import type { Store } from "./Store.js";
-export type PerfScope = "tool.execute.before" | "tool.execute.after" | "chat.message" | "chat.system.transform" | "session.compacting" | "event" | "session.idle" | "dispose";
+export type PerfScope = "tool.execute.before" | "tool.execute.after" | "chat.message" | "chat.system.transform" | "session.compacting" | "event" | "session.idle" | "dispose" | "mcp.read" | "mcp.write";
 export interface Budget {
     readonly scope: PerfScope;
     readonly p95Ms: number;

package/dist/perf.js

@@ -7,6 +7,8 @@ export const BUDGETS = [
     { scope: "event", p95Ms: 5, maxMs: 25 },
     { scope: "session.idle", p95Ms: 150, maxMs: 600 },
     { scope: "dispose", p95Ms: 50, maxMs: 250 },
+    { scope: "mcp.read", p95Ms: 25, maxMs: 100 },
+    { scope: "mcp.write", p95Ms: 50, maxMs: 250 },
 ];
 function clampCapacity(raw) {
     if (raw === null || raw === undefined || raw === "")

package/dist/skills-emit.d.ts

@@ -0,0 +1,38 @@
+import { type KevinEnv } from "./env.js";
+export interface TopicBundle {
+    topic: string;
+    content: string;
+    /** optional precomputed summary; derived from content if omitted */
+    summary?: string;
+}
+export interface SkillEmitInput {
+    projectRoot: string;
+    canonicalDir: string;
+    mirrors: Array<"claude" | "cursor">;
+    topics: TopicBundle[];
+    repoId: string;
+    /** injectable for tests; defaults to ~/.opencode-kevin/skills-manifest.json */
+    manifestPath?: string;
+    env?: KevinEnv;
+    metrics?: {
+        incr: (key: string, by?: number) => void;
+    };
+}
+export interface EmitReport {
+    written: string[];
+    skipped_external: string[];
+    noop: string[];
+    removed_orphan_manifest: string[];
+    external_edits: string[];
+}
+declare function sha256Hex(s: string): string;
+declare function escaped(text: string): string;
+declare function buildSkillMd(repoId: string, bundles: TopicBundle[]): string;
+export declare function emitSkillBundle(input: SkillEmitInput): EmitReport;
+export declare function refreshSkillBundle(input: SkillEmitInput): EmitReport;
+export declare const _internal: {
+    buildSkillMd: typeof buildSkillMd;
+    sha256Hex: typeof sha256Hex;
+    escaped: typeof escaped;
+};
+export {};

package/dist/skills-emit.js

@@ -0,0 +1,421 @@
+// K15-003 — Skill bundle emitter (plan §4.1)
+// Writes <projectRoot>/<canonicalDir>/kevin-knowledge/SKILL.md + references/<topic>.md
+// Every emitted byte passes through escape helpers (C-09, K15-004).
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { escapeForFence, escapeForMarkerBlock } from "./escape.js";
+import { firstSentence } from "./Curator.js";
+import { resolveEnv } from "./env.js";
+import { KEVIN_VERSION } from "./index.js";
+function sha256Hex(s) {
+    return createHash("sha256").update(s, "utf8").digest("hex");
+}
+function escaped(text) {
+    // C-09 funnel: every byte through escape helpers. Apply both fence + marker (orthogonal).
+    return escapeForMarkerBlock(escapeForFence(text));
+}
+function atomicWrite(target, content) {
+    mkdirSync(dirname(target), { recursive: true });
+    const tmp = `${target}.tmp.${process.pid}.${randomBytes(4).toString("hex")}`;
+    writeFileSync(tmp, content, "utf8");
+    try {
+        renameSync(tmp, target);
+    }
+    catch (e) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw e;
+    }
+}
+function buildSkillMd(repoId, bundles) {
+    const header = [
+        "---",
+        "name: kevin-knowledge",
+        "description: >-",
+        "  Project knowledge curated by opencode-kevin: conventions, decisions and verified",
+        "  fixes for this repository. Load when working in this repo and unsure about local",
+        "  rules, past failures or team decisions.",
+        "metadata:",
+        `  generator: opencode-kevin/${KEVIN_VERSION}`,
+        `  repo_id: ${escaped(repoId)}`,
+        "---",
+        "",
+    ].join("\n");
+    let body;
+    if (bundles.length === 0) {
+        body = "No knowledge yet — Kevin has not curated any memories for this repository.\n\nSee `references/` when topics appear.\n";
+    }
+    else {
+        // index ≤80 lines: one per topic + header
+        const indexLines = [];
+        indexLines.push("# Kevin Knowledge");
+        indexLines.push("");
+        indexLines.push("Topics curated for this repository:");
+        indexLines.push("");
+        for (const b of bundles) {
+            const rawSummary = b.summary ?? firstSentence(b.content.split("\n").find((l) => l.trim().startsWith("-"))?.replace(/^-+\s*/, "") ?? b.content.slice(0, 120));
+            const summary = escaped(rawSummary.trim().slice(0, 140));
+            // relative link from SKILL.md to references/<topic>.md
+            indexLines.push(`- **${escaped(b.topic)}**: ${summary} — [references/${escaped(b.topic)}.md](references/${escaped(b.topic)}.md)`);
+        }
+        const MAX_INDEX = 78;
+        if (indexLines.length > MAX_INDEX) {
+            // cap at 78: truncate excess topics, reserve footer lines
+            indexLines.splice(MAX_INDEX);
+        }
+        indexLines.push("");
+        indexLines.push("See `references/` for detailed topic files.");
+        indexLines.push("");
+        body = indexLines.join("\n");
+    }
+    const full = header + body;
+    // enforce <150 lines total; if exceeds, truncate body tail via paragraph truncation
+    const lines = full.split("\n");
+    if (lines.length >= 150) {
+        const headerLines = header.split("\n").length;
+        const allowedBody = 149 - headerLines;
+        const bodyLines = body.split("\n");
+        const truncatedBody = bodyLines.slice(0, Math.max(0, allowedBody)).join("\n");
+        const truncated = header + truncatedBody;
+        return truncated.endsWith("\n") ? truncated : truncated + "\n";
+    }
+    return full;
+}
+function buildToWrite(input) {
+    const canonicalRaw = (input.canonicalDir && input.canonicalDir.trim() !== "") ? input.canonicalDir.trim() : ".agents/skills";
+    // H-01: validate canonicalDir is relative and does not escape projectRoot
+    if (isAbsolute(canonicalRaw) || canonicalRaw.includes("..")) {
+        throw new Error(`unsafe canonicalDir: ${canonicalRaw}`);
+    }
+    const base = resolve(join(input.projectRoot, canonicalRaw, "kevin-knowledge"));
+    const projectRootResolved = resolve(input.projectRoot);
+    if (base !== projectRootResolved && !base.startsWith(projectRootResolved + "/") && !base.startsWith(projectRootResolved + "\\")) {
+        throw new Error(`canonicalDir escapes projectRoot: ${canonicalRaw}`);
+    }
+    const skillPath = join(base, "SKILL.md");
+    const refsDir = join(base, "references");
+    const bundles = [...input.topics].sort((a, b) => a.topic.localeCompare(b.topic));
+    const skillContent = buildSkillMd(input.repoId, bundles);
+    const referenceContents = new Map();
+    for (const b of bundles) {
+        let body = b.content;
+        if (body.length > 4000)
+            body = body.slice(0, 4000);
+        const esc = escaped(body);
+        referenceContents.set(b.topic, esc + (esc.endsWith("\n") ? "" : "\n"));
+    }
+    const toWrite = [];
+    toWrite.push({ path: skillPath, content: skillContent });
+    for (const [topic, content] of referenceContents) {
+        // C-01 sanitize topic by replacing [/\\:]/g with "-", replacing ".." and validating
+        let safe = topic.replace(/[/\\:]/g, "-").replace(/\.\./g, "-");
+        if (safe.includes("/") || safe.includes("\\") || safe.includes("..")) {
+            throw new Error(`unsafe topic: ${topic}`);
+        }
+        if (safe.trim() === "") {
+            throw new Error(`unsafe topic: ${topic}`);
+        }
+        toWrite.push({ path: join(refsDir, `${safe}.md`), content });
+    }
+    return { base, skillPath, refsDir, toWrite, referenceContents, skillContent, bundles };
+}
+export function emitSkillBundle(input) {
+    const { base, toWrite } = buildToWrite(input);
+    const manifestPath = input.manifestPath ?? join(resolveEnv(input.env).dataRoot, "skills-manifest.json");
+    let manifest = {};
+    let manifestExists = false;
+    let manifestCorrupt = false;
+    if (existsSync(manifestPath)) {
+        try {
+            manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+            manifestExists = true;
+        }
+        catch {
+            manifestCorrupt = true;
+            try {
+                input.metrics?.incr("skills_manifest_corrupt_total", 1);
+            }
+            catch { }
+            try {
+                const corrupt = readFileSync(manifestPath, "utf8");
+                writeFileSync(`${manifestPath}.corrupt.${Date.now()}`, corrupt, "utf8");
+            }
+            catch { }
+            manifest = {};
+            manifestExists = false;
+        }
+    }
+    const written = [];
+    const skipped_external = [];
+    const noop = [];
+    const external_edits = [];
+    const removed_orphan_manifest = [];
+    for (const w of toWrite) {
+        const freshHash = sha256Hex(w.content);
+        const manifestHash = manifest[w.path];
+        const diskExists = existsSync(w.path);
+        let diskHash = null;
+        if (diskExists) {
+            try {
+                diskHash = sha256Hex(readFileSync(w.path, "utf8"));
+            }
+            catch {
+                diskHash = null;
+            }
+        }
+        if (!diskExists) {
+            atomicWrite(w.path, w.content);
+            written.push(w.path);
+            manifest[w.path] = freshHash;
+            continue;
+        }
+        if (manifestCorrupt) {
+            if (diskHash !== null && freshHash === diskHash) {
+                noop.push(w.path);
+                manifest[w.path] = freshHash;
+            }
+            else {
+                atomicWrite(w.path, w.content);
+                written.push(w.path);
+                manifest[w.path] = freshHash;
+            }
+            continue;
+        }
+        if (manifestExists) {
+            if (manifestHash === undefined) {
+                skipped_external.push(w.path);
+                external_edits.push(w.path);
+                continue;
+            }
+            if (diskHash !== manifestHash) {
+                skipped_external.push(w.path);
+                external_edits.push(w.path);
+                continue;
+            }
+        }
+        if (diskHash !== null && freshHash === diskHash) {
+            noop.push(w.path);
+            manifest[w.path] = freshHash;
+        }
+        else {
+            atomicWrite(w.path, w.content);
+            written.push(w.path);
+            manifest[w.path] = freshHash;
+        }
+    }
+    // orphan manifest cleanup: entries under base not in current toWrite
+    for (const key of Object.keys({ ...manifest })) {
+        if (key.startsWith(base) && !toWrite.some((w) => w.path === key)) {
+            removed_orphan_manifest.push(key);
+            delete manifest[key];
+            try {
+                unlinkSync(key);
+            }
+            catch { }
+            for (const mirror of input.mirrors) {
+                const mirrorBase = mirror === "claude"
+                    ? join(input.projectRoot, ".claude", "skills", "kevin-knowledge")
+                    : join(input.projectRoot, ".cursor", "skills", "kevin-knowledge");
+                const rel = key.slice(base.length);
+                const mirrorPath = join(mirrorBase, rel);
+                try {
+                    unlinkSync(mirrorPath);
+                }
+                catch { }
+            }
+        }
+    }
+    // mirror handling — follow canonical state
+    for (const mirror of input.mirrors) {
+        const mirrorBase = mirror === "claude"
+            ? join(input.projectRoot, ".claude", "skills", "kevin-knowledge")
+            : join(input.projectRoot, ".cursor", "skills", "kevin-knowledge");
+        for (const w of toWrite) {
+            const rel = w.path.slice(base.length);
+            const mirrorPath = join(mirrorBase, rel);
+            const wasWritten = written.includes(w.path);
+            const wasNoop = noop.includes(w.path);
+            const wasSkipped = skipped_external.includes(w.path);
+            if (wasSkipped)
+                continue;
+            if (wasWritten) {
+                atomicWrite(mirrorPath, w.content);
+            }
+            else if (wasNoop) {
+                if (!existsSync(mirrorPath)) {
+                    atomicWrite(mirrorPath, w.content);
+                }
+            }
+        }
+    }
+    try {
+        // manifest already built; write LAST
+        mkdirSync(dirname(manifestPath), { recursive: true });
+        atomicWrite(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+    }
+    catch { }
+    try {
+        input.metrics?.incr("skills_emitted_total", 1);
+    }
+    catch { }
+    return { written, skipped_external, noop, removed_orphan_manifest, external_edits };
+}
+export function refreshSkillBundle(input) {
+    const { base, refsDir, toWrite, referenceContents } = buildToWrite(input);
+    const manifestPath = input.manifestPath ?? join(resolveEnv(input.env).dataRoot, "skills-manifest.json");
+    let manifest = {};
+    let manifestExists = false;
+    let manifestCorrupt = false;
+    if (existsSync(manifestPath)) {
+        try {
+            manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+            manifestExists = true;
+        }
+        catch {
+            manifestCorrupt = true;
+            try {
+                input.metrics?.incr("skills_manifest_corrupt_total", 1);
+            }
+            catch { }
+            try {
+                const corrupt = readFileSync(manifestPath, "utf8");
+                writeFileSync(`${manifestPath}.corrupt.${Date.now()}`, corrupt, "utf8");
+            }
+            catch { }
+            manifest = {};
+            manifestExists = false;
+        }
+    }
+    const written = [];
+    const skipped_external = [];
+    const noop = [];
+    const external_edits = [];
+    const removed_orphan_manifest = [];
+    // three-state per managed path
+    for (const w of toWrite) {
+        const freshHash = sha256Hex(w.content);
+        const manifestHash = manifest[w.path];
+        const diskExists = existsSync(w.path);
+        let diskHash = null;
+        if (diskExists) {
+            try {
+                diskHash = sha256Hex(readFileSync(w.path, "utf8"));
+            }
+            catch {
+                diskHash = null;
+            }
+        }
+        if (!diskExists) {
+            // deleted-file reconciliation: manifest entry without disk file → rewrite (STALE)
+            atomicWrite(w.path, w.content);
+            written.push(w.path);
+            manifest[w.path] = freshHash;
+            continue;
+        }
+        // disk exists
+        if (manifestHash === undefined) {
+            if (manifestExists && !manifestCorrupt) {
+                // missing manifest + existing file = EXTERNAL domain → skip
+                skipped_external.push(w.path);
+                external_edits.push(w.path);
+                continue;
+            }
+            // if manifest corrupt or missing (bootstrap), treat as stale: allow write below
+            if (!manifestExists && !manifestCorrupt) {
+                // no manifest yet - bootstrap case: if we are in refresh with no manifest but file exists,
+                // original behavior was EXTERNAL. Keep external for refresh when not corrupt.
+                // But for corrupt we already handled; for bootstrap we should still consider external.
+                // To preserve original spec for refresh: when manifest missing, existing file is EXTERNAL
+                if (!manifestCorrupt) {
+                    skipped_external.push(w.path);
+                    external_edits.push(w.path);
+                    continue;
+                }
+            }
+        }
+        if (manifestExists && diskHash !== manifestHash) {
+            // EXTERNAL_EDIT: disk ≠ manifest → skip
+            skipped_external.push(w.path);
+            external_edits.push(w.path);
+            continue;
+        }
+        // disk == manifest (or manifest corrupt/missing and we allowed)
+        if (diskHash !== null && freshHash === diskHash) {
+            noop.push(w.path);
+            manifest[w.path] = freshHash;
+        }
+        else {
+            // STALE: disk == manifest but inputs changed → rewrite
+            // Also for corrupt bootstrap, rewrite
+            atomicWrite(w.path, w.content);
+            written.push(w.path);
+            manifest[w.path] = freshHash;
+        }
+    }
+    // orphan manifest cleanup: entries under base not in current toWrite
+    for (const key of Object.keys({ ...manifest })) {
+        if (key.startsWith(base) && !toWrite.some((w) => w.path === key)) {
+            removed_orphan_manifest.push(key);
+            delete manifest[key];
+            try {
+                unlinkSync(key);
+            }
+            catch { }
+            for (const mirror of input.mirrors) {
+                const mirrorBase = mirror === "claude"
+                    ? join(input.projectRoot, ".claude", "skills", "kevin-knowledge")
+                    : join(input.projectRoot, ".cursor", "skills", "kevin-knowledge");
+                const rel = key.slice(base.length);
+                const mirrorPath = join(mirrorBase, rel);
+                try {
+                    unlinkSync(mirrorPath);
+                }
+                catch { }
+            }
+        }
+    }
+    // mirror handling — follow canonical state
+    for (const mirror of input.mirrors) {
+        const mirrorBase = mirror === "claude"
+            ? join(input.projectRoot, ".claude", "skills", "kevin-knowledge")
+            : join(input.projectRoot, ".cursor", "skills", "kevin-knowledge");
+        for (const w of toWrite) {
+            const rel = w.path.slice(base.length);
+            const mirrorPath = join(mirrorBase, rel);
+            const wasWritten = written.includes(w.path);
+            const wasNoop = noop.includes(w.path);
+            const wasSkipped = skipped_external.includes(w.path);
+            if (wasSkipped)
+                continue;
+            if (wasWritten) {
+                // canonical changed → mirror must match (discard external edits on mirror)
+                atomicWrite(mirrorPath, w.content);
+            }
+            else if (wasNoop) {
+                // canonical unchanged → don't touch mirror (preserve if externally edited, per spec)
+                // but if mirror missing, create it (stale projection)
+                if (!existsSync(mirrorPath)) {
+                    atomicWrite(mirrorPath, w.content);
+                }
+            }
+        }
+    }
+    // manifest written LAST
+    try {
+        mkdirSync(dirname(manifestPath), { recursive: true });
+        atomicWrite(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+    }
+    catch { }
+    if (written.length > 0) {
+        try {
+            input.metrics?.incr("skills_emitted_total", 1);
+        }
+        catch { }
+    }
+    return { written, skipped_external, noop, removed_orphan_manifest, external_edits };
+}
+// Utility for tests: expose header builder and escaping
+export const _internal = { buildSkillMd, sha256Hex, escaped };

package/dist/skills-validate.d.ts

@@ -0,0 +1,7 @@
+export interface SkillValidateResult {
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export declare function validateSkill(content: string, dirname?: string): SkillValidateResult;
+export declare function validateSkillFile(filePath: string, content: string): SkillValidateResult;