@lythos/skill-deck 0.7.2 → 0.9.1

package/src/cli.ts

@@ -2,38 +2,53 @@
 import { linkDeck } from './link.js'
 import { validateDeck } from './validate.js'
 import { addSkill } from './add.js'
+import { refreshDeck } from './refresh.js'
 import { updateDeck } from './update.js'
+import { migrateSchema } from './migrate-schema.js'
+import { removeSkill } from './remove.js'
+import { pruneDeck } from './prune.js'
 import { formatHelp } from './help.js'
 
+const args = process.argv.slice(2)
+const command = args[0]
+
+const deckFlagIdx = args.indexOf('--deck')
+const workdirFlagIdx = args.indexOf('--workdir')
+const viaFlagIdx = args.indexOf('--via')
+const asFlagIdx = args.indexOf('--as')
+const typeFlagIdx = args.indexOf('--type')
+
+const deckPath = deckFlagIdx >= 0 ? args[deckFlagIdx + 1] : undefined
+const workdir = workdirFlagIdx >= 0 ? args[workdirFlagIdx + 1] : undefined
+const via = viaFlagIdx >= 0 ? args[viaFlagIdx + 1] : undefined
+const as = asFlagIdx >= 0 ? args[asFlagIdx + 1] : undefined
+const type = typeFlagIdx >= 0 ? args[typeFlagIdx + 1] : undefined
+const noBackup = args.includes('--no-backup')
+const yes = args.includes('--yes')
+
 const HELP_CONFIG = {
   binName: 'lythoskill-deck',
   description: 'Declarative skill deck governance — cold pool, working set, deny-by-default',
   commands: [
     { name: 'link', description: 'Sync working set with skill-deck.toml' },
     { name: 'add', description: 'Download skill to cold pool and add to deck', args: '<locator>' },
-    { name: 'update', description: 'Pull latest versions of declared skills from upstream' },
+    { name: 'refresh', description: 'Pull latest versions of declared skills from upstream', args: '[<fq|alias>]' },
     { name: 'validate', description: 'Validate deck configuration', args: '[deck.toml]' },
+    { name: 'remove', description: 'Remove a skill from deck.toml and working set', args: '<fq|alias>' },
+    { name: 'prune', description: 'GC cold pool repos no longer referenced by any deck', args: '[--yes]' },
+    { name: 'migrate-schema', description: 'Convert string-array deck.toml to alias-as-key dict', args: '[--dry-run]' },
   ],
   options: [
     { flag: '--deck <path>', description: 'Specify skill-deck.toml path (default: find upward from cwd)' },
     { flag: '--workdir <dir>', description: 'Specify working directory (default: cwd)' },
     { flag: '--no-backup', description: 'Skip tar backup when removing non-symlink entries' },
     { flag: '--via <backend>', description: 'Download backend: git (default) | skills.sh' },
+    { flag: '--as <alias>', description: 'Explicit alias for the skill (default: basename of path)' },
+    { flag: '--type <type>', description: 'Target section: innate | tool | combo (default: tool)' },
+    { flag: '--yes', description: 'Skip interactive confirmation (for prune)' },
   ],
 }
 
-const args = process.argv.slice(2)
-const command = args[0]
-
-const deckFlagIdx = args.indexOf('--deck')
-const workdirFlagIdx = args.indexOf('--workdir')
-const viaFlagIdx = args.indexOf('--via')
-
-const deckPath = deckFlagIdx >= 0 ? args[deckFlagIdx + 1] : undefined
-const workdir = workdirFlagIdx >= 0 ? args[workdirFlagIdx + 1] : undefined
-const via = viaFlagIdx >= 0 ? args[viaFlagIdx + 1] : undefined
-const noBackup = args.includes('--no-backup')
-
 switch (command) {
   case '--help':
   case '-h':
@@ -48,15 +63,49 @@ switch (command) {
       console.error('❌ Missing locator. Usage: deck add <github.com/owner/repo[/skill]>')
       process.exit(1)
     }
-    await addSkill(locator, { via, deck: deckPath, workdir })
+    await addSkill(locator, { via, deck: deckPath, workdir, as, type })
+    break
+  }
+  case 'refresh': {
+    const refreshTarget = args[1] && !args[1].startsWith('-') ? args[1] : undefined
+    refreshDeck(deckPath, workdir, refreshTarget)
     break
   }
-  case 'update':
-    updateDeck(deckPath, workdir)
+  case 'update': {
+    const updateTarget = args[1] && !args[1].startsWith('-') ? args[1] : undefined
+    updateDeck(deckPath, workdir, updateTarget)
     break
+  }
   case 'validate':
     validateDeck(deckPath, workdir)
     break
+  case 'remove': {
+    const removeTarget = args[1] && !args[1].startsWith('-') ? args[1] : undefined
+    if (!removeTarget) {
+      console.error('❌ Missing target. Usage: deck remove <fq|alias>')
+      process.exit(1)
+    }
+    removeSkill(removeTarget, deckPath, workdir)
+    break
+  }
+  case 'prune': {
+    await pruneDeck(deckPath, workdir, yes)
+    break
+  }
+  case 'migrate-schema': {
+    const dryRun = args.includes('--dry-run')
+    const targetPath = deckPath || 'skill-deck.toml'
+    const result = migrateSchema(targetPath, dryRun)
+    if (result.diff) {
+      console.log(result.message)
+      console.log('---')
+      console.log(result.diff)
+    } else {
+      console.log(result.message)
+    }
+    if (!result.migrated) process.exit(0)
+    break
+  }
   default:
     console.error(formatHelp(HELP_CONFIG))
     process.exit(1)

package/src/link.test.ts

@@ -0,0 +1,320 @@
+#!/usr/bin/env bun
+/**
+ * link.test.ts — unit tests for link.ts pure functions
+ *
+ * Run: bun test packages/lythoskill-deck/src/link.test.ts
+ *
+ * Co-located with src per ADR-20260503180000000 (curator-mind framework selection)
+ * and the existing precedent in packages/lythoskill-curator/src/cli.test.ts.
+ *
+ * Tests use real fs in mkdtempSync sandboxes — no mocks. Each it() owns its own
+ * tmpdir and afterEach cleans up to avoid cross-test state leakage.
+ */
+
+import { describe, it, expect, afterEach } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, lstatSync, readlinkSync, readdirSync, existsSync, symlinkSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { tmpdir, homedir } from 'node:os'
+import { createHash } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+
+import { findDeckToml, expandHome, findSource, linkDeck } from './link.ts'
+
+let cleanup: string[] = []
+
+afterEach(() => {
+  for (const dir of cleanup) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+  cleanup = []
+})
+
+function makeTmp(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'deck-link-'))
+  cleanup.push(dir)
+  return dir
+}
+
+function placeSkill(coldPool: string, relPath: string): string {
+  const skillDir = join(coldPool, relPath)
+  mkdirSync(skillDir, { recursive: true })
+  writeFileSync(join(skillDir, 'SKILL.md'), '---\nname: fixture\n---\n')
+  return skillDir
+}
+
+describe('findDeckToml', () => {
+  it('returns absolute path when skill-deck.toml is present', () => {
+    const dir = makeTmp()
+    const tomlPath = join(dir, 'skill-deck.toml')
+    writeFileSync(tomlPath, '[[skills]]\n')
+    expect(findDeckToml(dir)).toBe(tomlPath)
+  })
+
+  it('returns null when skill-deck.toml is absent', () => {
+    const dir = makeTmp()
+    expect(findDeckToml(dir)).toBeNull()
+  })
+})
+
+describe('expandHome', () => {
+  it('expands ~/<path> to homedir-anchored absolute path', () => {
+    expect(expandHome('~/foo/bar', '/anywhere')).toBe(join(homedir(), 'foo/bar'))
+  })
+
+  it('resolves relative paths against base', () => {
+    expect(expandHome('foo/bar', '/some/base')).toBe(resolve('/some/base', 'foo/bar'))
+  })
+})
+
+describe('findSource', () => {
+  it('resolves fully-qualified host.tld/owner/repo/skill via cold-pool skills/ subdir', () => {
+    const coldPool = makeTmp()
+    const projectDir = makeTmp()
+    const expected = placeSkill(coldPool, 'github.com/lythos-labs/lythoskill/skills/lythoskill-deck')
+    const result = findSource('github.com/lythos-labs/lythoskill/lythoskill-deck', coldPool, projectDir)
+    expect(result.path).toBe(expected)
+  })
+
+  it('resolves a direct cold-pool hit when name matches a top-level dir with SKILL.md', () => {
+    const coldPool = makeTmp()
+    const projectDir = makeTmp()
+    const expected = placeSkill(coldPool, 'my-skill')
+    const result = findSource('my-skill', coldPool, projectDir)
+    expect(result.path).toBe(expected)
+  })
+
+  it('resolves a monorepo layout (repo/skill → coldPool/repo/skills/skill)', () => {
+    const coldPool = makeTmp()
+    const projectDir = makeTmp()
+    const expected = placeSkill(coldPool, 'mono-repo/skills/inner-skill')
+    const result = findSource('mono-repo/inner-skill', coldPool, projectDir)
+    expect(result.path).toBe(expected)
+  })
+
+  it('falls back to projectDir/skills/<name> for project-local skills', () => {
+    const coldPool = makeTmp()
+    const projectDir = makeTmp()
+    const expected = placeSkill(projectDir, 'skills/local-skill')
+    const result = findSource('local-skill', coldPool, projectDir)
+    expect(result.path).toBe(expected)
+  })
+
+  it('returns {path: null} when no strategy resolves the name', () => {
+    const coldPool = makeTmp()
+    const projectDir = makeTmp()
+    const result = findSource('nonexistent-skill', coldPool, projectDir)
+    expect(result.path).toBeNull()
+    expect(result.error).toBeUndefined()
+  })
+})
+
+describe('linkDeck reconciler', () => {
+  it('B1.tracer: empty deck creates working set and lock with zero skills', () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+    mkdirSync(coldPool, { recursive: true })
+
+    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    linkDeck(deckPath, projectDir, true)
+
+    const workingSet = join(projectDir, '.claude', 'skills')
+    expect(existsSync(workingSet)).toBe(true)
+    expect(lstatSync(workingSet).isDirectory()).toBe(true)
+
+    const lockPath = join(projectDir, 'skill-deck.lock')
+    expect(existsSync(lockPath)).toBe(true)
+
+    const lock = JSON.parse(readFileSync(lockPath, 'utf-8'))
+    expect(lock.version).toBe('1.0.0')
+    expect(lock.skills).toEqual([])
+    expect(lock.constraints.total_cards).toBe(0)
+    expect(lock.constraints.max_cards).toBe(10)
+    expect(lock.constraints.within_budget).toBe(true)
+    expect(lock.working_set).toBe('.claude/skills')
+    expect(lock.cold_pool).toBe(coldPoolRel)
+
+    const expectedHash = createHash('sha256').update(deckContent).digest('hex')
+    expect(lock.deck_source.content_hash).toBe(expectedHash)
+    expect(lock.deck_source.path).toBe('skill-deck.toml')
+  })
+
+  it('B2: declared skill with existing cold pool creates correct symlink', () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+
+    const skillDir = placeSkill(coldPool, 'github.com/owner/repo/skill')
+    writeFileSync(
+      join(skillDir, 'SKILL.md'),
+      '---\nname: test-skill\ndeck_niche: testing\ndeck_managed_dirs: ["docs/"]\n---\n'
+    )
+
+    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.my-alias]\npath = "github.com/owner/repo/skill"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    linkDeck(deckPath, projectDir, true)
+
+    const workingSet = join(projectDir, '.claude', 'skills')
+    const symlinkPath = join(workingSet, 'my-alias')
+
+    expect(existsSync(symlinkPath)).toBe(true)
+    expect(lstatSync(symlinkPath).isSymbolicLink()).toBe(true)
+
+    const target = readlinkSync(symlinkPath)
+    expect(target).toBe(skillDir)
+
+    const lock = JSON.parse(readFileSync(join(projectDir, 'skill-deck.lock'), 'utf-8'))
+    expect(lock.skills).toHaveLength(1)
+
+    const skill = lock.skills[0]
+    expect(skill.name).toBe('github.com/owner/repo/skill')
+    expect(skill.alias).toBe('my-alias')
+    expect(skill.type).toBe('tool')
+    expect(skill.source).toBe(join('github.com', 'owner', 'repo', 'skill'))
+    expect(skill.dest).toBe(join('.claude', 'skills', 'my-alias'))
+    expect(skill.content_hash).toMatch(/^[a-f0-9]{64}$/)
+    expect(skill.deck_niche).toBe('testing')
+    expect(skill.deck_managed_dirs).toEqual(['docs/'])
+    expect(skill.linked_at).toBeDefined()
+  })
+
+  it('B2.b: idempotent re-run preserves symlink state', async () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+
+    const skillDir = placeSkill(coldPool, 'github.com/owner/repo/skill')
+
+    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.my-alias]\npath = "github.com/owner/repo/skill"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    linkDeck(deckPath, projectDir, true)
+
+    const lock1 = JSON.parse(readFileSync(join(projectDir, 'skill-deck.lock'), 'utf-8'))
+    const symlinkPath = join(projectDir, '.claude', 'skills', 'my-alias')
+    const target1 = readlinkSync(symlinkPath)
+
+    await new Promise(r => setTimeout(r, 50))
+
+    linkDeck(deckPath, projectDir, true)
+
+    const lock2 = JSON.parse(readFileSync(join(projectDir, 'skill-deck.lock'), 'utf-8'))
+    const target2 = readlinkSync(symlinkPath)
+
+    const entries = readdirSync(join(projectDir, '.claude', 'skills'))
+      .filter(e => !e.startsWith('.') && !e.startsWith('_'))
+    expect(entries).toHaveLength(1)
+    expect(target2).toBe(target1)
+    expect(target2).toBe(skillDir)
+
+    expect(lock2.generated_at).not.toBe(lock1.generated_at)
+
+    expect(lock2.skills).toHaveLength(1)
+    expect(lock2.skills[0].alias).toBe(lock1.skills[0].alias)
+    expect(lock2.skills[0].source).toBe(lock1.skills[0].source)
+    expect(lock2.skills[0].dest).toBe(lock1.skills[0].dest)
+  })
+
+  it('B3: deny-by-default removes undeclared symlinks from working set', () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+
+    const skillADir = placeSkill(coldPool, 'github.com/owner/repo/skill-a')
+    const skillBDir = placeSkill(coldPool, 'github.com/owner/repo/skill-b')
+
+    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.skill-a]\npath = "github.com/owner/repo/skill-a"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    // Pre-populate working set with both skill-a (declared) and skill-b (undeclared)
+    const workingSet = join(projectDir, '.claude', 'skills')
+    mkdirSync(workingSet, { recursive: true })
+    symlinkSync(skillADir, join(workingSet, 'skill-a'))
+    symlinkSync(skillBDir, join(workingSet, 'skill-b'))
+
+    linkDeck(deckPath, projectDir, true)
+
+    // skill-a should remain
+    expect(existsSync(join(workingSet, 'skill-a'))).toBe(true)
+    expect(lstatSync(join(workingSet, 'skill-a')).isSymbolicLink()).toBe(true)
+
+    // skill-b should be removed
+    expect(existsSync(join(workingSet, 'skill-b'))).toBe(false)
+
+    const lock = JSON.parse(readFileSync(join(projectDir, 'skill-deck.lock'), 'utf-8'))
+    expect(lock.skills).toHaveLength(1)
+    expect(lock.skills[0].alias).toBe('skill-a')
+  })
+
+  it('B4: same-type alias collision exits with fatal error', () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+    placeSkill(coldPool, 'github.com/owner-a/repo/foo')
+    placeSkill(coldPool, 'github.com/owner-b/repo/foo')
+
+    // Legacy string-array format: two skills with same basename
+    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool]\nskills = ["github.com/owner-a/repo/foo", "github.com/owner-b/repo/foo"]\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    const result = spawnSync('bun', [join(import.meta.dir, 'link.ts'), deckPath, projectDir, 'true'], {
+      cwd: projectDir,
+      encoding: 'utf-8',
+    })
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('Alias collision')
+  })
+
+  it('B4.b: cross-type alias collision exits with fatal error', () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+    placeSkill(coldPool, 'github.com/owner-a/repo/foo')
+    placeSkill(coldPool, 'github.com/owner-b/repo/foo')
+
+    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[innate.skills.foo]\npath = "github.com/owner-a/repo/foo"\n\n[tool.skills.foo]\npath = "github.com/owner-b/repo/foo"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    const result = spawnSync('bun', [join(import.meta.dir, 'link.ts'), deckPath, projectDir, 'true'], {
+      cwd: projectDir,
+      encoding: 'utf-8',
+    })
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('Alias collision')
+  })
+
+  it('B5: max_cards exceeded exits before modifying working set', () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+    placeSkill(coldPool, 'github.com/owner/repo/skill-a')
+    placeSkill(coldPool, 'github.com/owner/repo/skill-b')
+    placeSkill(coldPool, 'github.com/owner/repo/skill-c')
+
+    const deckContent = `[deck]\nmax_cards = 2\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.skill-a]\npath = "github.com/owner/repo/skill-a"\n\n[tool.skills.skill-b]\npath = "github.com/owner/repo/skill-b"\n\n[tool.skills.skill-c]\npath = "github.com/owner/repo/skill-c"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    const result = spawnSync('bun', [join(import.meta.dir, 'link.ts'), deckPath, projectDir, 'true'], {
+      cwd: projectDir,
+      encoding: 'utf-8',
+    })
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('Budget exceeded')
+
+    // Working set should not be created (fail-fast before mkdir)
+    expect(existsSync(join(projectDir, '.claude', 'skills'))).toBe(false)
+  })
+})

package/src/link.ts

@@ -14,13 +14,14 @@ import {
   existsSync, mkdirSync, readFileSync, readdirSync,
   symlinkSync, lstatSync, rmSync, statSync, writeFileSync,
 } from "node:fs";
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { resolve, dirname, join, basename, relative } from "node:path";
 import { homedir } from "node:os";
 import {
   SkillDeckLockSchema,
   type SkillDeckLock, type LinkedSkill, type ConstraintReport,
 } from "./schema.js";
+import { parseDeck } from "./parse-deck.js";
 
 // ── 路径工具 ────────────────────────────────────────────────
 
@@ -173,44 +174,47 @@ if (!existsSync(DECK_PATH)) {
 const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : dirname(DECK_PATH);
 const deckRaw = readFileSync(DECK_PATH, "utf-8");
 const deckHash = hashContent(deckRaw);
-const deck = parseToml(deckRaw) as any;
 
-const WORKING_SET_RAW = deck.deck?.working_set || ".claude/skills";
-const COLD_POOL_RAW = deck.deck?.cold_pool || "~/.agents/skill-repos";
+const { entries: parsedEntries, deprecated: isDeprecated, errors: parseErrors } = parseDeck(deckRaw);
+if (isDeprecated) {
+  console.warn("⚠️  Deprecation: string-array skill entries are deprecated. Run `deck migrate-schema` to upgrade.");
+}
+
+const parsedToml = parseToml(deckRaw) as any;
+const WORKING_SET_RAW = parsedToml.deck?.working_set || ".claude/skills";
+const COLD_POOL_RAW = parsedToml.deck?.cold_pool || "~/.agents/skill-repos";
 const WORKING_SET = expandHome(WORKING_SET_RAW, PROJECT_DIR);
 const COLD_POOL = expandHome(COLD_POOL_RAW, PROJECT_DIR);
-const MAX_CARDS = Number(deck.deck?.max_cards || 10);
+const MAX_CARDS = Number(parsedToml.deck?.max_cards || 10);
 
 // ── 收集声明 ────────────────────────────────────────────────
 
 interface DeclaredSkill {
-  name: string;
+  name: string;        // original path/name (for lock.source backward-compat)
+  alias: string;       // working-set flat symlink name
   type: "innate" | "tool" | "combo" | "transient";
   sourcePath: string;
   expires?: string;
 }
 
 const declared: DeclaredSkill[] = [];
-const errors: string[] = [];
-
-for (const section of ["innate", "tool", "combo"] as const) {
-  for (const name of (deck[section]?.skills || [])) {
-    if (!name || typeof name !== "string") continue;
-    const result = findSource(name, COLD_POOL, PROJECT_DIR);
-    if (result.error) {
-      errors.push(result.error);
-      continue;
-    }
-    if (!result.path) {
-      errors.push(`Skill not found: ${name}`);
-      continue;
-    }
-    declared.push({ name, type: section, sourcePath: result.path });
+const errors: string[] = [...parseErrors];
+
+for (const entry of parsedEntries) {
+  const result = findSource(entry.path, COLD_POOL, PROJECT_DIR);
+  if (result.error) {
+    errors.push(result.error);
+    continue;
+  }
+  if (!result.path) {
+    errors.push(`Skill not found: ${entry.path}`);
+    continue;
   }
+  declared.push({ name: entry.path, alias: entry.alias, type: entry.type, sourcePath: result.path });
 }
 
-// transient: sub-tables with path field
-for (const [key, value] of Object.entries(deck.transient || {})) {
+// transient: sub-tables with path field (kept backward-compat; future ADR may unify)
+for (const [key, value] of Object.entries(parsedToml.transient || {})) {
   const t = value as any;
   if (!t?.path) continue;
   const src = resolve(PROJECT_DIR, t.path);
@@ -218,7 +222,22 @@ for (const [key, value] of Object.entries(deck.transient || {})) {
     errors.push(`Transient path does not exist: ${key} → ${src}`);
     continue;
   }
-  declared.push({ name: key, type: "transient", sourcePath: src, expires: t.expires });
+  declared.push({ name: key, alias: key, type: "transient", sourcePath: src, expires: t.expires });
+}
+
+// ── 跨 type alias collision 检测 ──────────────────────────────
+const aliasToTypes = new Map<string, string[]>();
+for (const d of declared) {
+  const types = aliasToTypes.get(d.alias) || [];
+  types.push(d.type);
+  aliasToTypes.set(d.alias, types);
+}
+for (const [alias, types] of aliasToTypes) {
+  if (types.length > 1) {
+    errors.push(
+      `Alias collision: "${alias}" appears in [${types.join('], [')}]. Use --as to specify different aliases.`
+    );
+  }
 }
 
 if (errors.length > 0) {
@@ -242,6 +261,12 @@ if (errors.length > 0) {
   }
   // 继续执行已找到的 skill，不因个别缺失中断全部
 
+  // fatal errors: alias collision must block
+  const fatalErrors = errors.filter(e => e.includes('Alias collision'));
+  if (fatalErrors.length > 0) {
+    process.exit(1);
+  }
+
   // 引导：如果 cold pool 为空，给出更明确的指引
   const hasSkills = existsSync(COLD_POOL) && readdirSync(COLD_POOL).filter(e => !e.startsWith('.')).length > 0;
   if (!hasSkills) {
@@ -328,7 +353,7 @@ if (nonSymlinks.length > 0) {
       ...nonSymlinks.map(e => relative(PROJECT_DIR, join(WORKING_SET, e))),
     ];
     try {
-      execSync("tar " + tarArgs.map(a => a.includes(" ") ? `"${a}"` : a).join(" "), {
+      execFileSync("tar", tarArgs, {
         cwd: PROJECT_DIR,
         stdio: "pipe",
       });
@@ -348,7 +373,7 @@ if (nonSymlinks.length > 0) {
 }
 
 // 清理未声明的 symlink
-const declaredNames = new Set(declared.map(d => d.name.split("/")[0]));
+const declaredNames = new Set(declared.map(d => d.alias));
 try {
   for (const entry of readdirSync(WORKING_SET)) {
     if (entry.startsWith("_") || entry.startsWith(".")) continue;
@@ -368,7 +393,7 @@ try {
 const linkedSkills: LinkedSkill[] = [];
 
 for (const item of declared) {
-  const dest = join(WORKING_SET, item.name);
+  const dest = join(WORKING_SET, item.alias);
 
   // 幂等：已存在则删除重建（lstat 不跟随 symlink，能处理断链/自引用 symlink）
   try {
@@ -380,7 +405,7 @@ for (const item of declared) {
     mkdirSync(dirname(dest), { recursive: true });
     symlinkSync(item.sourcePath, dest);
   } catch (err: any) {
-    console.error(`❌ Link failed: ${item.name}: ${err.message}`);
+    console.error(`❌ Link failed: ${item.alias}: ${err.message}`);
     continue;
   }
 
@@ -405,6 +430,7 @@ for (const item of declared) {
 
   linkedSkills.push({
     name: item.name,
+    alias: item.alias,
     deck_niche: niche,
     type: item.type,
     source: sourceRel,
@@ -415,7 +441,7 @@ for (const item of declared) {
     deck_managed_dirs: managedDirs,
   });
 
-  console.log(`  🔗 ${item.name}`);
+  console.log(`  🔗 ${item.alias}`);
 }
 
 // ── Transient 过期检查 ──────────────────────────────────────

package/src/migrate-schema.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env bun
+import { parse as parseToml, stringify } from "@iarna/toml";
+import { readFileSync, writeFileSync, renameSync } from "node:fs";
+import { parseDeck } from "./parse-deck.js";
+
+export interface MigrateResult {
+  migrated: boolean;
+  message: string;
+  diff?: string;
+}
+
+export function migrateSchema(deckPath: string, dryRun: boolean): MigrateResult {
+  const raw = readFileSync(deckPath, "utf-8");
+  const { deprecated } = parseDeck(raw);
+
+  if (!deprecated) {
+    return {
+      migrated: false,
+      message: "No migration needed: deck.toml already uses alias-as-key dict schema.",
+    };
+  }
+
+  const parsed = parseToml(raw) as any;
+
+  for (const section of ["innate", "tool", "combo"] as const) {
+    const skills = parsed[section]?.skills;
+    if (!Array.isArray(skills)) continue;
+
+    delete parsed[section].skills;
+    const entries: Record<string, { path: string }> = {};
+    for (const name of skills) {
+      if (!name || typeof name !== "string") continue;
+      const alias = name.split("/").pop() || name;
+      entries[alias] = { path: name };
+    }
+    parsed[section] = { skills: entries };
+  }
+
+  const newToml = stringify(parsed);
+
+  if (dryRun) {
+    return {
+      migrated: true,
+      message: `Dry run — would migrate ${deckPath} to alias-as-key dict schema:`,
+      diff: newToml,
+    };
+  }
+
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  const backupPath = `${deckPath}.bak.${ts}`;
+  renameSync(deckPath, backupPath);
+  writeFileSync(deckPath, newToml);
+
+  return {
+    migrated: true,
+    message: `Migrated ${deckPath} → alias-as-key dict schema. Backup: ${backupPath}`,
+  };
+}