@selesai/code 0.13.11 → 0.13.13

package/dist/extensions/pi-hermes-memory/src/store/skill-store.ts

@@ -1,950 +0,0 @@
-/**
- * SkillStore — procedural memory stored as Pi-native skills.
- *
- * Global skills live in ~/.selesai/agent/pi-hermes-memory/skills/<slug>/SKILL.md.
- * Project skills live in ~/.selesai/agent/<projectsMemoryDir>/<project>/skills/<slug>/SKILL.md.
- */
-
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import { scanContent } from "./content-scanner.js";
-import {
-  buildSkillId,
-  exists,
-  formatFrontmatter,
-  jaccardSimilarity,
-  parseFrontmatter,
-  parseSkillId,
-  slugify,
-  today,
-  tokenizeForSimilarity,
-} from "./skill-utils.js";
-import type { SkillDocument, SkillIndex, SkillResult, SkillScope } from "../types.js";
-import { AGENT_ROOT } from "../paths.js";
-
-interface SkillStoreOptions {
-  /** Where this extension writes global skills. Never Pi's own root. */
-  globalSkillsDir?: string;
-  /** Pi's global skills root, consulted read-only to refuse shadowed writes. */
-  piGlobalSkillsDir?: string;
-  projectSkillsDir?: string | null;
-  projectName?: string | null;
-  legacySkillsDir?: string;
-  migrationSentinelPath?: string;
-}
-
-interface SkillLocation {
-  skillId: string;
-  scope: SkillScope;
-  slug: string;
-  fileName: string;
-  path: string;
-  projectName?: string;
-}
-
-export interface LegacySkillMigrationResult {
-  migrated: number;
-  skipped: number;
-  warnings: string[];
-}
-
-const LIST_SECTIONS = new Set(["procedure", "pitfalls", "verification"]);
-
-function normalizeSectionName(section: string): string {
-  return section.replace(/^#+\s*/, "").trim();
-}
-
-function isExactSectionHeader(line: string, section: string): boolean {
-  const heading = line.trim().match(/^##\s+(.+?)\s*$/);
-  if (!heading) return false;
-  return heading[1].trim().toLowerCase() === section.trim().toLowerCase();
-}
-
-function looksLikeJsonArray(content: string): boolean {
-  const trimmed = content.trim();
-  return trimmed.startsWith("[") && trimmed.endsWith("]");
-}
-
-function looksLikeJsonObject(content: string): boolean {
-  const trimmed = content.trim();
-  return trimmed.startsWith("{") && trimmed.endsWith("}");
-}
-
-function formatPatchList(section: string, items: string[]): string {
-  const cleaned = items.map((item) => item.trim()).filter(Boolean);
-  if (cleaned.length === 0) return "";
-  const key = section.trim().toLowerCase();
-  if (key === "pitfalls") {
-    return cleaned.map((item) => `- ${item.replace(/^[-*]\s+/, "")}`).join("\n");
-  }
-  // Procedure / Verification default to ordered steps.
-  return cleaned
-    .map((item, index) => `${index + 1}. ${item.replace(/^\d+\.\s+/, "").replace(/^[-*]\s+/, "")}`)
-    .join("\n");
-}
-
-/**
- * Normalize/validate free-form patch content so LLM format drift cannot wipe
- * or splice skill sections. Coerces JSON string arrays into Markdown lists for
- * list-shaped sections and rejects empty / object / header-injecting payloads.
- */
-export function normalizeSkillPatchContent(
-  section: string,
-  rawContent: string,
-): { content: string } | { error: string } {
-  const sectionName = normalizeSectionName(section);
-  if (!sectionName) {
-    return { error: "section is required for patch." };
-  }
-
-  let content = typeof rawContent === "string" ? rawContent.trim() : "";
-  if (!content) {
-    return {
-      error: "New content is required for patch. Prefer structured fields (procedure_steps, pitfalls, verification_steps, when_to_use) over free-form content.",
-    };
-  }
-
-  if (looksLikeJsonObject(content)) {
-    return {
-      error: "Patch content looks like a JSON object. Provide Markdown section body or a string array via structured fields.",
-    };
-  }
-
-  if (looksLikeJsonArray(content)) {
-    try {
-      const parsed: unknown = JSON.parse(content);
-      if (!Array.isArray(parsed)) {
-        return { error: "Patch content looks like JSON but is not a string array." };
-      }
-      const items = parsed
-        .filter((item): item is string => typeof item === "string")
-        .map((item) => item.trim())
-        .filter(Boolean);
-      if (items.length === 0) {
-        return { error: "Patch content JSON array must contain non-empty strings." };
-      }
-      const key = sectionName.toLowerCase();
-      if (key === "when to use") {
-        content = items.join("\n\n");
-      } else if (LIST_SECTIONS.has(key)) {
-        content = formatPatchList(sectionName, items);
-      } else {
-        content = items.map((item) => `- ${item}`).join("\n");
-      }
-    } catch {
-      return {
-        error: "Patch content looks like a JSON array but could not be parsed. Use Markdown or structured string[] fields.",
-      };
-    }
-  }
-
-  // Reject payloads that would inject extra ## sections mid-body.
-  if (/^#{1,6}\s+\S/m.test(content)) {
-    return {
-      error: "Patch content must not include Markdown section headers (## ...). Patch only the body of the target section.",
-    };
-  }
-
-  if (!content.trim()) {
-    return { error: "New content is required for patch." };
-  }
-
-  return { content: content.trim() };
-}
-
-
-export class SkillStore {
-  private globalSkillsDir: string;
-  private piGlobalSkillsDir: string;
-  private projectSkillsDir: string | null;
-  private projectName: string | null;
-  private legacySkillsDir: string;
-  private migrationSentinelPath: string;
-
-  constructor(options: SkillStoreOptions = {}) {
-    const agentRoot = AGENT_ROOT;
-    this.globalSkillsDir = options.globalSkillsDir ?? path.join(agentRoot, "pi-hermes-memory", "skills");
-    this.piGlobalSkillsDir = options.piGlobalSkillsDir ?? path.join(agentRoot, "skills");
-    this.projectSkillsDir = options.projectSkillsDir ?? null;
-    this.projectName = options.projectName ?? null;
-    this.legacySkillsDir = options.legacySkillsDir ?? path.join(agentRoot, "memory", "skills");
-    this.migrationSentinelPath = options.migrationSentinelPath
-      ?? path.join(agentRoot, "pi-hermes-memory", ".skills-migrated-to-extension-storage");
-  }
-
-  getGlobalSkillsDir(): string {
-    return this.globalSkillsDir;
-  }
-
-  /**
-   * Pi's own global skills root. Read-only from here: we never create, patch,
-   * or delete inside it. It is consulted solely to refuse writes that Pi would
-   * silently shadow (see `findShadowingPiGlobalSkill`).
-   */
-  getPiGlobalSkillsDir(): string {
-    return this.piGlobalSkillsDir;
-  }
-
-  getProjectSkillsDir(): string | null {
-    return this.projectSkillsDir;
-  }
-
-  getProjectName(): string | null {
-    return this.projectName;
-  }
-
-  setProjectContext(projectName: string | null, projectSkillsDir: string | null): void {
-    this.projectName = projectName;
-    this.projectSkillsDir = projectSkillsDir;
-  }
-
-  async ensureDiscoveredRoots(): Promise<void> {
-    await fs.mkdir(this.globalSkillsDir, { recursive: true });
-    if (this.projectSkillsDir) {
-      await fs.mkdir(this.projectSkillsDir, { recursive: true });
-    }
-  }
-
-  async migrateLegacySkills(): Promise<LegacySkillMigrationResult> {
-    const result: LegacySkillMigrationResult = { migrated: 0, skipped: 0, warnings: [] };
-
-    // Always normalize flat markdown files under the global skills root,
-    // even when a previous migration sentinel already exists.
-    await this.migrateFlatMarkdownInGlobalSkillsDir(result);
-
-    if (await exists(this.migrationSentinelPath)) return result;
-
-    await fs.mkdir(path.dirname(this.migrationSentinelPath), { recursive: true });
-
-    // Only this migration's own warnings may hold back its sentinel — a
-    // permanently shadowed skill reported above must not make it retry forever.
-    const warningsBefore = result.warnings.length;
-    try {
-      await this.migrateLegacyMarkdownSkills(result);
-    } finally {
-      if (result.warnings.length === warningsBefore) {
-        await fs.writeFile(this.migrationSentinelPath, `${new Date().toISOString()}\n`, "utf-8");
-      }
-    }
-
-    return result;
-  }
-
-  private async migrateLegacyMarkdownSkills(result: LegacySkillMigrationResult): Promise<void> {
-    if (!await exists(this.legacySkillsDir)) return;
-
-    const files = (await fs.readdir(this.legacySkillsDir))
-      .filter((file) => file.endsWith(".md"))
-      .sort();
-
-    for (const file of files) {
-      const legacyPath = path.join(this.legacySkillsDir, file);
-      try {
-        const raw = await fs.readFile(legacyPath, "utf-8");
-        const parsed = parseFrontmatter(raw);
-        const fallbackSlug = slugify(path.basename(file, ".md"));
-        const slug = slugify(parsed.meta.name || fallbackSlug);
-        if (!slug) {
-          result.skipped++;
-          continue;
-        }
-
-        const targetPath = path.join(this.globalSkillsDir, slug, "SKILL.md");
-        if (await exists(targetPath)) {
-          result.skipped++;
-          continue;
-        }
-
-        const skillDoc = {
-          name: slug,
-          displayName: parsed.meta.display_name?.trim() || parsed.meta.name?.trim() || undefined,
-          description: parsed.meta.description?.trim() || `Migrated legacy skill: ${slug}`,
-          version: Number.parseInt(parsed.meta.version || "1", 10) || 1,
-          created: parsed.meta.created || today(),
-          updated: parsed.meta.updated || today(),
-          body: parsed.body || `# ${slug}\n`,
-        };
-
-        await fs.mkdir(path.dirname(targetPath), { recursive: true });
-        await this.atomicWrite(targetPath, formatFrontmatter(skillDoc));
-        result.migrated++;
-      } catch (error) {
-        result.warnings.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
-      }
-    }
-  }
-
-  private async migrateFlatMarkdownInGlobalSkillsDir(result: LegacySkillMigrationResult): Promise<void> {
-    if (!await exists(this.globalSkillsDir)) return;
-
-    const files = (await fs.readdir(this.globalSkillsDir))
-      .filter((file) => file.endsWith(".md") && file !== "SKILL.md")
-      .sort();
-
-    for (const file of files) {
-      const legacyPath = path.join(this.globalSkillsDir, file);
-      try {
-        const raw = await fs.readFile(legacyPath, "utf-8");
-        const parsed = parseFrontmatter(raw);
-        const fallbackSlug = slugify(path.basename(file, ".md"));
-        const slug = slugify(parsed.meta.name || fallbackSlug);
-        if (!slug) {
-          result.skipped++;
-          continue;
-        }
-
-        const targetPath = path.join(this.globalSkillsDir, slug, "SKILL.md");
-        if (await exists(targetPath)) {
-          await fs.rm(legacyPath, { force: true });
-          result.skipped++;
-          continue;
-        }
-
-        const skillDoc = {
-          name: slug,
-          displayName: parsed.meta.display_name?.trim() || parsed.meta.name?.trim() || undefined,
-          description: parsed.meta.description?.trim() || `Migrated legacy skill: ${slug}`,
-          version: Number.parseInt(parsed.meta.version || "1", 10) || 1,
-          created: parsed.meta.created || today(),
-          updated: parsed.meta.updated || today(),
-          body: parsed.body || `# ${slug}\n`,
-        };
-
-        await fs.mkdir(path.dirname(targetPath), { recursive: true });
-        await this.atomicWrite(targetPath, formatFrontmatter(skillDoc));
-        await fs.rm(legacyPath, { force: true });
-        result.migrated++;
-      } catch (error) {
-        result.warnings.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
-      }
-    }
-  }
-
-  /**
-   * Is `slug` already claimed by a skill in Pi's own global root?
-   *
-   * Pi keys skills by name, first-loaded wins, and `~/.selesai/agent/skills/` is
-   * auto-discovered at higher precedence than anything an extension contributes
-   * via `resources_discover`. A global skill we write under a name that also
-   * exists there is never the copy Pi loads, so the write succeeds on disk and
-   * changes nothing about the agent's behaviour — silent write-loss (#125).
-   *
-   * Callers refuse the write and name both paths instead, which makes the
-   * shadowed state impossible to create rather than merely reported after the
-   * fact. Returns the shadowing path, or null when the name is free.
-   */
-  private async findShadowingPiGlobalSkill(slug: string): Promise<string | null> {
-    if (path.resolve(this.piGlobalSkillsDir) === path.resolve(this.globalSkillsDir)) return null;
-    const candidate = path.join(this.piGlobalSkillsDir, slug, "SKILL.md");
-    return await exists(candidate) ? candidate : null;
-  }
-
-  async loadIndex(scope?: SkillScope): Promise<SkillIndex[]> {
-    const locations = await this.collectLocations(scope);
-    const skills: SkillIndex[] = [];
-
-    for (const location of locations) {
-      const doc = await this.readLocation(location);
-      if (doc) skills.push(this.toIndex(doc));
-    }
-
-    return skills.sort((a, b) => {
-      if (a.updated !== b.updated) return b.updated.localeCompare(a.updated);
-      if (a.created !== b.created) return b.created.localeCompare(a.created);
-      if (a.scope !== b.scope) return a.scope.localeCompare(b.scope);
-      return (a.displayName || a.name).localeCompare(b.displayName || b.name);
-    });
-  }
-
-  async loadSkill(skillId: string): Promise<SkillDocument | null> {
-    const location = await this.findLocationById(skillId);
-    if (!location) return null;
-    return this.readLocation(location);
-  }
-
-  async create(name: string, description: string, body: string, scope?: SkillScope): Promise<SkillResult> {
-    name = name.trim();
-    description = description.trim();
-    body = body.trim();
-
-    if (!name) return { success: false, error: "Skill name is required." };
-    if (!description) return { success: false, error: "Skill description is required." };
-    if (!body) return { success: false, error: "Skill body is required." };
-
-    const scanError = scanContent(`${name} ${description} ${body}`);
-    if (scanError) return { success: false, error: scanError };
-
-    const slug = slugify(name);
-    if (!slug) return { success: false, error: "Skill name produces empty slug." };
-
-    const resolvedScope = this.resolveScope(scope, name, description, body);
-    const root = this.getScopeRoot(resolvedScope);
-    if (!root) {
-      return { success: false, error: "Project skills require an active project." };
-    }
-
-    const skillId = buildSkillId(resolvedScope, slug, this.projectName);
-    const existing = await this.findLocationById(skillId);
-    if (existing) {
-      return {
-        success: false,
-        error: `Skill '${slug}' already exists (${skillId}). Use 'patch' or 'update' to update it.`,
-        conflictType: "duplicate",
-        similarSkillIds: [skillId],
-        suggestedAction: "patch",
-      };
-    }
-
-    if (resolvedScope === "global") {
-      const similarSkillIds = await this.findSimilarGlobalSkillIds(slug, description);
-      if (similarSkillIds.length > 0) {
-        const targetId = similarSkillIds[0];
-        return {
-          success: false,
-          error: `A similar global skill already exists (${targetId}). Enhance the existing skill with new learnings/failures using 'patch' or 'update' instead of creating a duplicate.`,
-          conflictType: "similar",
-          similarSkillIds,
-          suggestedAction: "patch",
-        };
-      }
-
-      const collidingNameSkillIds = await this.findNameCollisionGlobalSkillIds(slug, description);
-      if (collidingNameSkillIds.length > 0) {
-        const targetId = collidingNameSkillIds[0];
-        return {
-          success: false,
-          error: `A near-name global skill already exists (${targetId}) but with different intent. Use a clearer differentiated name for the new skill, or patch/update the existing skill if the intent is actually the same.`,
-          conflictType: "name-collision",
-          similarSkillIds: collidingNameSkillIds,
-          suggestedAction: "rename",
-        };
-      }
-
-      const shadowedBy = await this.findShadowingPiGlobalSkill(slug);
-      if (shadowedBy) {
-        return {
-          success: false,
-          error: `Pi already loads a global skill named '${slug}' from ${shadowedBy}. `
-            + `Pi keys skills by name and loads its own root first, so a skill written to `
-            + `${path.join(this.globalSkillsDir, slug, "SKILL.md")} would never be the copy in effect. `
-            + `Choose a different name, or edit ${shadowedBy} directly.`,
-          conflictType: "name-collision",
-          suggestedAction: "rename",
-        };
-      }
-    }
-
-    const filePath = path.join(root, slug, "SKILL.md");
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-
-    const displayName = name;
-    const storedName = slug;
-    const stamp = today();
-    await this.atomicWrite(filePath, formatFrontmatter({
-      name: storedName,
-      displayName,
-      description,
-      version: 1,
-      created: stamp,
-      updated: stamp,
-      body,
-    }));
-
-    return {
-      success: true,
-      message: `Skill '${displayName}' created as a ${resolvedScope} skill.`,
-      fileName: path.basename(filePath),
-      skillId,
-      scope: resolvedScope,
-      path: filePath,
-    };
-  }
-
-  async patch(skillId: string, section: string, newContent: string): Promise<SkillResult> {
-    const sectionName = normalizeSectionName(section);
-    if (!sectionName) return { success: false, error: "section is required for patch." };
-
-    const normalized = normalizeSkillPatchContent(sectionName, newContent);
-    if ("error" in normalized) return { success: false, error: normalized.error };
-    const content = normalized.content;
-
-    const scanError = scanContent(content);
-    if (scanError) return { success: false, error: scanError };
-
-    const doc = await this.loadSkill(skillId);
-    if (!doc) return { success: false, error: `Skill '${skillId}' not found.` };
-
-    const sectionHeader = `## ${sectionName}`;
-    const lines = doc.body.split("\n");
-    let found = false;
-    const result: string[] = [];
-
-    for (let i = 0; i < lines.length; i++) {
-      if (isExactSectionHeader(lines[i], sectionName)) {
-        result.push(sectionHeader);
-        // Preserve multi-line body as discrete lines so later headers stay exact.
-        for (const bodyLine of content.split("\n")) {
-          result.push(bodyLine);
-        }
-        found = true;
-        i++;
-        while (i < lines.length && !lines[i].trim().startsWith("## ")) i++;
-        if (i < lines.length) result.push(lines[i]);
-      } else {
-        result.push(lines[i]);
-      }
-    }
-
-    if (!found) {
-      if (result.length > 0 && result[result.length - 1] !== "") result.push("");
-      result.push(sectionHeader);
-      for (const bodyLine of content.split("\n")) {
-        result.push(bodyLine);
-      }
-    }
-
-    await this.atomicWrite(doc.path, formatFrontmatter({
-      name: doc.name,
-      displayName: doc.displayName,
-      description: doc.description,
-      version: doc.version + 1,
-      created: doc.created,
-      updated: today(),
-      body: result.join("\n").trim(),
-    }));
-
-    return {
-      success: true,
-      message: `Skill '${doc.displayName || doc.name}' section '${sectionName}' updated.`,
-      fileName: doc.fileName,
-      skillId: doc.skillId,
-      scope: doc.scope,
-      path: doc.path,
-    };
-  }
-
-  async edit(skillId: string, description: string, body: string): Promise<SkillResult> {
-    description = description.trim();
-    body = body.trim();
-
-    if (!description && !body) {
-      return { success: false, error: "At least one of description or body is required." };
-    }
-
-    const doc = await this.loadSkill(skillId);
-    if (!doc) return { success: false, error: `Skill '${skillId}' not found.` };
-
-    const newDescription = description || doc.description;
-    const newBody = body || doc.body;
-    const scanError = scanContent(`${newDescription} ${newBody}`);
-    if (scanError) return { success: false, error: scanError };
-
-    await this.atomicWrite(doc.path, formatFrontmatter({
-      name: doc.name,
-      displayName: doc.displayName,
-      description: newDescription,
-      version: doc.version + 1,
-      created: doc.created,
-      updated: today(),
-      body: newBody,
-    }));
-
-    return {
-      success: true,
-      message: `Skill '${doc.displayName || doc.name}' updated.`,
-      fileName: doc.fileName,
-      skillId: doc.skillId,
-      scope: doc.scope,
-      path: doc.path,
-    };
-  }
-
-  async move(skillId: string, targetScope: SkillScope): Promise<SkillResult> {
-    const doc = await this.loadSkill(skillId);
-    if (!doc) return { success: false, error: `Skill '${skillId}' not found.` };
-
-    const parsed = parseSkillId(skillId);
-    if (!parsed) return { success: false, error: `Skill '${skillId}' is invalid.` };
-
-    if (doc.scope === targetScope) {
-      return {
-        success: true,
-        message: `Skill '${doc.displayName || doc.name}' is already ${targetScope}.`,
-        fileName: doc.fileName,
-        skillId: doc.skillId,
-        scope: doc.scope,
-        path: doc.path,
-      };
-    }
-
-    const targetRoot = this.getScopeRoot(targetScope);
-    if (!targetRoot) {
-      return { success: false, error: "Project skills require an active project." };
-    }
-
-    const targetSkillId = buildSkillId(targetScope, parsed.slug, this.projectName);
-    const targetPath = path.join(targetRoot, parsed.slug, "SKILL.md");
-    if (await exists(targetPath)) {
-      return {
-        success: false,
-        error: `Cannot move '${doc.displayName || doc.name}' to ${targetScope}: ${targetSkillId} already exists.`,
-        conflictType: "scope-conflict",
-        similarSkillIds: [targetSkillId],
-        suggestedAction: "rename",
-      };
-    }
-
-    if (targetScope === "global") {
-      const similarSkillIds = await this.findSimilarGlobalSkillIds(parsed.slug, doc.description);
-      if (similarSkillIds.length > 0) {
-        const targetId = similarSkillIds[0];
-        return {
-          success: false,
-          error: `Cannot move '${doc.displayName || doc.name}' to global: a similar global skill already exists (${targetId}).`,
-          conflictType: "similar",
-          similarSkillIds,
-          suggestedAction: "patch",
-        };
-      }
-
-      const collidingNameSkillIds = await this.findNameCollisionGlobalSkillIds(parsed.slug, doc.description);
-      if (collidingNameSkillIds.length > 0) {
-        const targetId = collidingNameSkillIds[0];
-        return {
-          success: false,
-          error: `Cannot move '${doc.displayName || doc.name}' to global: a near-name global skill already exists (${targetId}) with different intent.`,
-          conflictType: "name-collision",
-          similarSkillIds: collidingNameSkillIds,
-          suggestedAction: "rename",
-        };
-      }
-    }
-
-    await fs.mkdir(path.dirname(targetPath), { recursive: true });
-
-    // Same-filesystem move: use rename first for atomicity and to avoid duplicate windows.
-    try {
-      await fs.rename(doc.path, targetPath);
-
-      if (path.basename(doc.path) === "SKILL.md") {
-        await this.removeEmptyParents(path.dirname(doc.path), this.getScopeRoot(doc.scope));
-      }
-
-      return {
-        success: true,
-        message: `Skill '${doc.displayName || doc.name}' moved to ${targetScope}.`,
-        fileName: path.basename(targetPath),
-        skillId: targetSkillId,
-        scope: targetScope,
-        path: targetPath,
-      };
-    } catch (renameError) {
-      const code = (renameError as NodeJS.ErrnoException)?.code;
-      if (code !== "EXDEV") {
-        return {
-          success: false,
-          error: `Move to ${targetScope} failed before copy for skill '${skillId}'. Source path: ${doc.path}. Destination path: ${targetPath}. Error: ${renameError instanceof Error ? renameError.message : String(renameError)}`,
-        };
-      }
-      // Cross-device fallback below.
-    }
-
-    // Cross-device fallback: copy then remove source.
-    await this.atomicWrite(targetPath, formatFrontmatter({
-      name: parsed.slug,
-      displayName: doc.displayName,
-      description: doc.description,
-      version: doc.version,
-      created: doc.created,
-      updated: doc.updated,
-      body: doc.body,
-    }));
-
-    try {
-      await fs.unlink(doc.path);
-      if (path.basename(doc.path) === "SKILL.md") {
-        await this.removeEmptyParents(path.dirname(doc.path), this.getScopeRoot(doc.scope));
-      }
-    } catch (error) {
-      // Best-effort rollback: remove the destination copy if source removal fails,
-      // so we do not silently leave duplicate skills across scopes.
-      let rollbackFailed = false;
-      try {
-        await fs.unlink(targetPath);
-        if (path.basename(targetPath) === "SKILL.md") {
-          await this.removeEmptyParents(path.dirname(targetPath), this.getScopeRoot(targetScope));
-        }
-      } catch {
-        rollbackFailed = true;
-      }
-
-      return {
-        success: false,
-        error: rollbackFailed
-          ? `Move to ${targetScope} failed while removing source skill '${skillId}', and rollback also failed. Source path: ${doc.path}. Destination path: ${targetPath}. Error: ${error instanceof Error ? error.message : String(error)}`
-          : `Move to ${targetScope} failed while removing source skill '${skillId}'. Rolled back destination copy. Source path: ${doc.path}. Destination path: ${targetPath}. Error: ${error instanceof Error ? error.message : String(error)}`,
-      };
-    }
-
-    return {
-      success: true,
-      message: `Skill '${doc.displayName || doc.name}' moved to ${targetScope}.`,
-      fileName: path.basename(targetPath),
-      skillId: targetSkillId,
-      scope: targetScope,
-      path: targetPath,
-    };
-  }
-
-  async delete(skillId: string): Promise<SkillResult> {
-    const doc = await this.loadSkill(skillId);
-    if (!doc) return { success: false, error: `Skill '${skillId}' not found.` };
-
-    await fs.unlink(doc.path);
-    if (path.basename(doc.path) === "SKILL.md") {
-      await this.removeEmptyParents(path.dirname(doc.path), this.getScopeRoot(doc.scope));
-    }
-
-    return {
-      success: true,
-      message: `Skill '${doc.displayName || doc.name}' deleted.`,
-      fileName: doc.fileName,
-      skillId: doc.skillId,
-      scope: doc.scope,
-      path: doc.path,
-    };
-  }
-
-  private resolveScope(scope: SkillScope | undefined, name: string, description: string, body: string): SkillScope {
-    if (scope) return scope;
-    if (!this.projectSkillsDir || !this.projectName) return "global";
-
-    const haystack = `${name}\n${description}\n${body}`.toLowerCase();
-    const projectLower = this.projectName.toLowerCase();
-
-    const strongSignals = [
-      haystack.includes(projectLower),
-      /\bthis repo\b|\bthis repository\b|\bthis project\b|\bour codebase\b|\bour app\b/.test(haystack),
-      /\bpackage\.json\b|\bpnpm-lock\.yaml\b|\byarn\.lock\b|\btsconfig\.json\b|\bdocker-compose(\.ya?ml)?\b|\b\.env(\.[a-z0-9._-]+)?\b/.test(haystack),
-      /(^|\s)(src|app|apps|packages|services|scripts|tests|docs|infra|migrations|db|api|web|frontend|backend)\/[a-z0-9._/-]+/m.test(haystack),
-      /\b(npm|pnpm|yarn|bun)\s+(run|test|build|dev|lint|deploy)\b/.test(haystack),
-    ].filter(Boolean).length;
-
-    const weakerSignals = [
-      /\bdeploy\b|\brelease\b|\bmigrate\b|\bmonorepo\b|\bworkspace\b|\bstaging\b|\bproduction\b/.test(haystack),
-      /\bteam convention\b|\bcodebase convention\b|\brepo convention\b/.test(haystack),
-    ].filter(Boolean).length;
-
-    return strongSignals >= 2 || (strongSignals >= 1 && weakerSignals >= 1) ? "project" : "global";
-  }
-
-  private getScopeRoot(scope: SkillScope): string | null {
-    return scope === "global" ? this.globalSkillsDir : this.projectSkillsDir;
-  }
-
-  private async findSimilarGlobalSkillIds(candidateSlug: string, candidateDescription: string): Promise<string[]> {
-    const NAME_SIMILARITY_THRESHOLD = 0.7;
-    const DESCRIPTION_SIMILARITY_THRESHOLD = 0.75;
-
-    const scored = await this.scoreGlobalSimilarity(candidateSlug, candidateDescription);
-
-    return scored
-      .filter((entry) => entry.nameSimilarity > NAME_SIMILARITY_THRESHOLD
-        && entry.descriptionSimilarity > DESCRIPTION_SIMILARITY_THRESHOLD)
-      .map((entry) => entry.skillId);
-  }
-
-  private async findNameCollisionGlobalSkillIds(candidateSlug: string, candidateDescription: string): Promise<string[]> {
-    const NAME_SIMILARITY_THRESHOLD = 0.7;
-    const DESCRIPTION_SIMILARITY_THRESHOLD = 0.75;
-
-    const scored = await this.scoreGlobalSimilarity(candidateSlug, candidateDescription);
-
-    return scored
-      .filter((entry) => entry.nameSimilarity > NAME_SIMILARITY_THRESHOLD
-        && entry.descriptionSimilarity <= DESCRIPTION_SIMILARITY_THRESHOLD)
-      .map((entry) => entry.skillId);
-  }
-
-  private async scoreGlobalSimilarity(
-    candidateSlug: string,
-    candidateDescription: string,
-  ): Promise<Array<{ skillId: string; nameSimilarity: number; descriptionSimilarity: number }>> {
-    const globals = await this.loadIndex("global");
-    const candidateNameTokens = tokenizeForSimilarity(candidateSlug.replace(/-/g, " "));
-    const candidateDescriptionTokens = tokenizeForSimilarity(candidateDescription);
-
-    return globals
-      .map((skill) => {
-        const nameTokens = tokenizeForSimilarity((skill.displayName || skill.name).replace(/-/g, " "));
-        const descriptionTokens = tokenizeForSimilarity(skill.description || "");
-        const nameSimilarity = jaccardSimilarity(candidateNameTokens, nameTokens);
-        const descriptionSimilarity = jaccardSimilarity(candidateDescriptionTokens, descriptionTokens);
-
-        return {
-          skillId: skill.skillId,
-          nameSimilarity,
-          descriptionSimilarity,
-        };
-      })
-      .sort((a, b) => {
-        const byName = b.nameSimilarity - a.nameSimilarity;
-        if (Math.abs(byName) > 0.0001) return byName;
-        return b.descriptionSimilarity - a.descriptionSimilarity;
-      });
-  }
-
-  private async collectLocations(scope?: SkillScope): Promise<SkillLocation[]> {
-    const locations: SkillLocation[] = [];
-    const seen = new Set<string>();
-
-    if (!scope || scope === "global") {
-      const globalLocations = await this.scanScope(this.globalSkillsDir, "global", true, this.projectName ?? undefined);
-      for (const location of globalLocations) {
-        if (seen.has(location.skillId)) continue;
-        seen.add(location.skillId);
-        locations.push(location);
-      }
-    }
-
-    if ((!scope || scope === "project") && this.projectSkillsDir && this.projectName) {
-      const projectLocations = await this.scanScope(this.projectSkillsDir, "project", false, this.projectName);
-      for (const location of projectLocations) {
-        if (seen.has(location.skillId)) continue;
-        seen.add(location.skillId);
-        locations.push(location);
-      }
-    }
-
-    return locations;
-  }
-
-  private async scanScope(
-    root: string,
-    scope: SkillScope,
-    allowRootMarkdown: boolean,
-    projectName?: string,
-  ): Promise<SkillLocation[]> {
-    if (!await exists(root)) return [];
-    const results: SkillLocation[] = [];
-
-    const walk = async (dir: string, isRoot: boolean): Promise<void> => {
-      const entries = await fs.readdir(dir, { withFileTypes: true });
-      const dirs = entries.filter((entry) => entry.isDirectory()).sort((a, b) => a.name.localeCompare(b.name));
-      const files = entries.filter((entry) => entry.isFile()).sort((a, b) => a.name.localeCompare(b.name));
-
-      for (const entry of dirs) {
-        if (entry.name.startsWith(".")) continue;
-        const childDir = path.join(dir, entry.name);
-        const skillFile = path.join(childDir, "SKILL.md");
-        if (await exists(skillFile)) {
-          results.push({
-            skillId: buildSkillId(scope, entry.name, projectName),
-            scope,
-            slug: entry.name,
-            fileName: "SKILL.md",
-            path: skillFile,
-            projectName,
-          });
-        }
-        await walk(childDir, false);
-      }
-
-      if (!isRoot || !allowRootMarkdown) return;
-
-      for (const entry of files) {
-        if (!entry.name.endsWith(".md") || entry.name === "SKILL.md") continue;
-        const slug = slugify(path.basename(entry.name, ".md"));
-        if (!slug) continue;
-        results.push({
-          skillId: buildSkillId(scope, slug, projectName),
-          scope,
-          slug,
-          fileName: entry.name,
-          path: path.join(dir, entry.name),
-          projectName,
-        });
-      }
-    };
-
-    await walk(root, true);
-    return results;
-  }
-
-  private async findLocationById(skillId: string): Promise<SkillLocation | null> {
-    const parsed = parseSkillId(skillId);
-    if (!parsed) return null;
-
-    const locations = await this.collectLocations(parsed.scope);
-    return locations.find((location) => location.skillId === skillId) ?? null;
-  }
-
-  private async readLocation(location: SkillLocation): Promise<SkillDocument | null> {
-    try {
-      const raw = await fs.readFile(location.path, "utf-8");
-      const { meta, body } = parseFrontmatter(raw);
-      const skillName = meta.name?.trim() || location.slug;
-      const displayName = meta.display_name?.trim() || undefined;
-      return {
-        skillId: location.skillId,
-        scope: location.scope,
-        fileName: location.fileName,
-        path: location.path,
-        projectName: location.projectName,
-        name: skillName,
-        displayName,
-        description: meta.description?.trim() || "",
-        version: Number.parseInt(meta.version || "1", 10) || 1,
-        created: meta.created || today(),
-        updated: meta.updated || today(),
-        body,
-      };
-    } catch {
-      return null;
-    }
-  }
-
-  private toIndex(doc: SkillDocument): SkillIndex {
-    return {
-      skillId: doc.skillId,
-      scope: doc.scope,
-      fileName: doc.fileName,
-      path: doc.path,
-      projectName: doc.projectName,
-      name: doc.name,
-      displayName: doc.displayName,
-      description: doc.description,
-      created: doc.created,
-      updated: doc.updated,
-    };
-  }
-
-  private async atomicWrite(filePath: string, content: string): Promise<void> {
-    const dir = path.dirname(filePath);
-    await fs.mkdir(dir, { recursive: true });
-
-    const tempFile = path.join(
-      dir,
-      `.${path.basename(filePath)}.tmp-${Date.now()}-${Math.random().toString(36).slice(2)}`,
-    );
-
-    await fs.writeFile(tempFile, content, "utf-8");
-    await fs.rename(tempFile, filePath);
-  }
-
-  private async removeEmptyParents(startDir: string, stopDir: string | null): Promise<void> {
-    if (!stopDir) return;
-
-    let current = startDir;
-    while (current.startsWith(stopDir) && current !== stopDir) {
-      try {
-        const entries = await fs.readdir(current);
-        if (entries.length > 0) return;
-        await fs.rmdir(current);
-        current = path.dirname(current);
-      } catch {
-        return;
-      }
-    }
-  }
-}