@lythos/skill-deck 0.9.0 → 0.9.2

package/README.md

@@ -1,5 +1,7 @@
 # @lythos/skill-deck
 
+![Coverage](https://img.shields.io/badge/coverage-82%25-brightgreen)
+
 > Declarative skill deck governance. Reconcile declared skills against your cold pool via symlinks — deny-by-default, max-cards budgeting, transient expiry.
 
 ## For AI Agents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/skill-deck",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
   "keywords": [
     "ai-agent",

package/src/COVERAGE-GAPS.md

@@ -0,0 +1,117 @@
+# Deck Package Coverage Gaps
+
+> Generated from `bun test --coverage packages/lythoskill-deck/src/*.test.ts`
+> Lines: 82.35% | Funcs: 73.81% | Date: 2026-05-04
+
+## 策略声明
+
+以下缺口是**故意保留**的。覆盖这些分支的意图已经看到，处理方式不是"为覆盖率改代码"，而是：
+
+1. **提取行为后单测** — 如果某段逻辑值得验证，把它提取为纯函数，单独写 test
+2. **直接说明不覆盖** — 如果分支是纯边界防护（`catch {}`、交互式确认、外部依赖），写明原因即可
+3. **拒绝为覆盖率改写代码** — 不为了触发分支而拆散可读性高的连续逻辑
+
+具体不追的类别：
+- `catch {}` silent ignore（fs 边界错误，测了也是 mock，无业务意义）
+- 需要 >1GB 文件才能触发的分支（formatSize GB）
+- 依赖外部 network 的分支（git clone 真实失败、skills.sh backend）
+- 交互式 CLI 分支（prune confirm()）
+- 仅为凑分支覆盖率而进行的微重构（降低可读性）
+
+---
+
+## add.ts — 62.37% lines
+
+| 行 | 代码 | 未覆盖原因 | 是否追 |
+|----|------|-----------|--------|
+| 44, 46–50 | `deckPath` resolve + `findDeckToml` 失败 | CLI 路径解析，可用 spawnSync 追但成本高 | ⬜ 低优先级 |
+| 55–59 | cold pool mkdir | 正常路径已覆盖，异常分支为 `catch {}` | ❌ 不追 |
+| 62–71 | `targetDir` exists 错误 | 需构造 cold pool 冲突，有意义但成本中等 | ⬜ 低优先级 |
+| 87–89 | `skills.sh` / `vercel` backend | 依赖外部 `npx skills` 命令，无 mock 价值 | ❌ 不追 |
+| 106–108 | auto-migrate string-array → dict | 有意义，但需 mock `git clone` 全流程 | ⬜ 低优先级 |
+| 123–124, 127–131 | alias resolve / `nameParts.length` | shorthand path 分支，有意义 | ⬜ 低优先级 |
+| 136–141 | invalid type rejection | **已覆盖** (C9) | ✅ |
+| 143–154 | git clone 成功后的 `findSkillDir` | 正常路径已覆盖 | ✅ |
+| 163–164 | `--as` alias | 正常路径已覆盖 | ✅ |
+| 172–174, 182–183 | error handling (catch) | `catch {}` 无意义 | ❌ 不追 |
+| 206, 210 | skills.sh 路径 | 外部依赖 | ❌ 不追 |
+| 221–227 | `writeFileSync` / `linkDeck` | 正常路径已覆盖 | ✅ |
+| 235–240 | catch final error | `catch {}` | ❌ 不追 |
+
+## link.ts — 60.71% lines
+
+link.ts 是 deck 包最大文件（~540 行）， uncovered 行最多。主要缺口：
+
+| 行 | 代码 | 未覆盖原因 | 是否追 |
+|----|------|-----------|--------|
+| 103–111 | `parseSkillFrontmatter` 异常（SKILL.md 不存在/解析失败） | 有意义，需构造无 SKILL.md 的 fixture | ⬜ 低优先级 |
+| 116, 119–123 | `calculateDirSize` 异常 / `readdirSync` 失败 | `catch {}` | ❌ 不追 |
+| 131–142 | backup 逻辑（nonSymlink > 100MB tar） | 需构造大文件或 mock `tar`，成本高 | ❌ 不追 |
+| 146–147 | backup 路径构造 | 同上 | ❌ 不追 |
+| 162–171 | transient 过期警告（`days <= 14` / `days <= 0`） | 有意义，需调系统时间或 mock Date | ⬜ 低优先级 |
+| 180 | managed_dirs 重叠检测 | 有意义，需构造父子目录冲突 | ⬜ 低优先级 |
+| 206–211, 218–225 | `readdirSync` / `symlinkSync` 异常 | `catch {}` | ❌ 不追 |
+| 237–239, 244–245 | 各种路径 resolve | 边界情况 | ❌ 不追 |
+| 247–261 | `findSource` 多种匹配策略 | 部分已覆盖，剩余为罕见 fallback | ⬜ 低优先级 |
+| 265–278 | budget exceeded 详细报告 | 正常路径已覆盖 | ✅ |
+| 285–287, 298–300, 307–310 | 各种 `existsSync` / `lstatSync` 边界 | `catch {}` | ❌ 不追 |
+| 326 | `content_hash` 计算 | 正常路径已覆盖 | ✅ |
+| 334–372 | lock 文件 schema 校验 | 正常路径已覆盖 | ✅ |
+| 407–408 | `readlinkSync` 异常 | `catch {}` | ❌ 不追 |
+| 454–461 | `parseDeck` fallback | 正常路径已覆盖 | ✅ |
+| 479–480, 488–490, 492–498 | `readdirSync` / `rmSync` 边界 | `catch {}` | ❌ 不追 |
+| 524–525, 537 | 各种 cleanup / 路径 | 边界 | ❌ 不追 |
+
+## parse-deck.ts — 92.45% lines
+
+| 行 | 代码 | 未覆盖原因 | 是否追 |
+|----|------|-----------|--------|
+| 47–50 | legacy string-array `continue`（空 name） | 有意义但 trivial | ⬜ 低优先级 |
+
+## prune.ts — 80.43% lines
+
+| 行 | 代码 | 未覆盖原因 | 是否追 |
+|----|------|-----------|--------|
+| 25–27 | `formatSize` GB 分支 | 需 >1GB 文件 | ❌ 不追 |
+| 74 | `calculateDirSize` catch | `catch {}` | ❌ 不追 |
+| 81–87 | `scanColdPoolRepos` catch | `catch {}` | ❌ 不追 |
+| 98–100 | empty cold pool | **已覆盖** (C17) | ✅ |
+| 118–122 | all-referenced no-op | **已覆盖** (C16) | ✅ |
+| 129–130 | failed > 0 exit(1) | 需构造删除失败（权限不足） | ❌ 不追 |
+| 167 | formatSize MB 分支 | 正常路径已覆盖 | ✅ |
+| 172–173 | 删除失败 catch | `catch {}` | ❌ 不追 |
+| 185–186 | formatSize 边界 | 正常路径已覆盖 | ✅ |
+
+## refresh.ts — 88.97% lines
+
+| 行 | 代码 | 未覆盖原因 | 是否追 |
+|----|------|-----------|--------|
+| 43, 49 | deck 不存在 / `findDeckToml` 失败 | CLI 路径解析 | ⬜ 低优先级 |
+| 70–71 | localhost skip | **已覆盖** (C15) | ✅ |
+| 83–85 | not-git | **已覆盖** (C16) | ✅ |
+| 101 | `result.error`（findSource 失败） | 有意义 | ⬜ 低优先级 |
+| 109–110 | `gitRoot` null 后的 skip | **已覆盖** (C16) | ✅ |
+| 125 | `pullResult.status === "failed"` | 需 mock `git pull` 返回错误 | ⬜ 低优先级 |
+| 148–150 | `updated` / `upToDate` / `failed` 计数 | **已覆盖** (C12-C14) | ✅ |
+| 199 | `failed > 0` exit(1) | 需构造 failed 状态 | ⬜ 低优先级 |
+
+## remove.ts — 91.53% lines
+
+| 行 | 代码 | 未覆盖原因 | 是否追 |
+|----|------|-----------|--------|
+| 22–24 | deck 不存在 error | CLI 路径解析 | ⬜ 低优先级 |
+| 44 | legacy string-array filter | **已覆盖** (C11.b) | ✅ |
+
+## schema.ts — 100.00%
+
+全部覆盖 ✅
+
+---
+
+## 如果未来要推到 90%+
+
+优先级排序：
+1. **link.ts `parseSkillFrontmatter` 异常** — 有业务意义（broken SKILL.md），中等成本
+2. **link.ts transient 过期警告** — 有业务意义，需 mock Date
+3. **add.ts auto-migrate** — 有业务意义，需 mock git clone
+4. **link.ts managed_dirs 重叠** — 有业务意义，需构造目录冲突

package/src/add.test.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env bun
+/**
+ * add.test.ts — unit tests for add.ts
+ *
+ * Run: bun test packages/lythoskill-deck/src/add.test.ts
+ */
+
+import { describe, it, expect, afterEach, spyOn, mock } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync, cpSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import * as childProcess from 'node:child_process'
+
+// Control homedir() return value for tests that need default cold_pool under tmpdir
+let mockHomeDir = '/tmp'
+mock.module('node:os', () => ({
+  homedir: () => mockHomeDir,
+}))
+
+let cleanup: string[] = []
+let execSpy: ReturnType<typeof spyOn> | null = null
+
+afterEach(() => {
+  if (execSpy) {
+    execSpy.mockRestore()
+    execSpy = null
+  }
+  for (const dir of cleanup) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+  cleanup = []
+})
+
+function makeTmp(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'deck-add-'))
+  cleanup.push(dir)
+  return dir
+}
+
+function mockGitClone(fixturePath: string) {
+  const originalExec = childProcess.execFileSync
+  execSpy = spyOn(childProcess, 'execFileSync').mockImplementation(((cmd: string, args: string[], options?: any) => {
+    if (cmd === 'git' && args[0] === 'clone') {
+      const dest = args[args.length - 1]
+      cpSync(fixturePath, dest, { recursive: true })
+      return Buffer.from('')
+    }
+    return originalExec(cmd, args, options)
+  }) as any)
+}
+
+describe('addSkill', () => {
+  it('C6: add to empty project creates deck.toml and cold pool', async () => {
+    const projectDir = makeTmp()
+    mockHomeDir = projectDir
+
+    const fixtureDir = makeTmp()
+    writeFileSync(join(fixtureDir, 'SKILL.md'), '---\nname: test-skill\n---\n')
+
+    mockGitClone(fixtureDir)
+
+    // Dynamic import so add.ts picks up the mocked homedir()
+    const { addSkill } = await import('./add.ts')
+
+    await addSkill('github.com/owner/repo', { workdir: projectDir })
+
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    expect(existsSync(deckPath)).toBe(true)
+
+    const deckContent = readFileSync(deckPath, 'utf-8')
+    expect(deckContent).toContain('[tool.skills.repo]')
+    expect(deckContent).toContain('path = "github.com/owner/repo"')
+
+    const coldPoolDir = join(projectDir, '.agents', 'skill-repos', 'github.com', 'owner', 'repo')
+    expect(existsSync(coldPoolDir)).toBe(true)
+    expect(existsSync(join(coldPoolDir, 'SKILL.md'))).toBe(true)
+  })
+
+  it('C7: add to existing deck appends entry', async () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+    mkdirSync(coldPool, { recursive: true })
+
+    // Pre-place skill-a in cold pool
+    const skillADir = join(coldPool, 'github.com', 'owner', 'repo-a')
+    mkdirSync(skillADir, { recursive: true })
+    writeFileSync(join(skillADir, 'SKILL.md'), '---\nname: skill-a\n---\n')
+
+    // Create deck.toml with skill-a
+    const deckContent = `[deck]\nmax_cards = 10\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.skill-a]\npath = "github.com/owner/repo-a"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    // Fixture for skill-b
+    const fixtureDir = makeTmp()
+    writeFileSync(join(fixtureDir, 'SKILL.md'), '---\nname: skill-b\n---\n')
+
+    mockGitClone(fixtureDir)
+
+    const { addSkill } = await import('./add.ts')
+    await addSkill('github.com/owner/repo-b', { workdir: projectDir, deck: deckPath })
+
+    const newContent = readFileSync(deckPath, 'utf-8')
+    expect(newContent).toContain('[tool.skills.skill-a]')
+    expect(newContent).toContain('path = "github.com/owner/repo-a"')
+    expect(newContent).toContain('[tool.skills.repo-b]')
+    expect(newContent).toContain('path = "github.com/owner/repo-b"')
+  })
+
+  it('C8: alias collision rejects', async () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+    mkdirSync(coldPool, { recursive: true })
+
+    const deckContent = `[deck]\nmax_cards = 10\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.foo]\npath = "github.com/owner/repo-a"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    const fixtureDir = makeTmp()
+    writeFileSync(join(fixtureDir, 'SKILL.md'), '---\nname: skill-b\n---\n')
+
+    mockGitClone(fixtureDir)
+
+    const errors: string[] = []
+    const errorSpy = spyOn(console, 'error').mockImplementation((msg: string) => {
+      errors.push(String(msg))
+    })
+
+    const originalExit = process.exit
+    let exitCode: number | undefined
+    process.exit = ((code?: number) => {
+      exitCode = code ?? 0
+      throw new Error(`EXIT:${code}`)
+    }) as typeof process.exit
+
+    try {
+      const { addSkill } = await import('./add.ts')
+      await addSkill('github.com/owner/repo-b', { workdir: projectDir, deck: deckPath, as: 'foo' })
+      expect(false).toBe(true) // should not reach here
+    } catch (err: any) {
+      expect(exitCode).toBe(1)
+      expect(errors.some(e => e.includes('Alias "foo" already exists'))).toBe(true)
+    } finally {
+      process.exit = originalExit
+      errorSpy.mockRestore()
+    }
+  })
+
+  it('C9: invalid skill type rejects', async () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+    mkdirSync(coldPool, { recursive: true })
+
+    const fixtureDir = makeTmp()
+    writeFileSync(join(fixtureDir, 'SKILL.md'), '---\nname: skill\n---\n')
+
+    const originalExec = childProcess.execFileSync
+    const execSpy = spyOn(childProcess, 'execFileSync').mockImplementation(((cmd: string, args: string[], options?: any) => {
+      if (cmd === 'git' && args[0] === 'clone') {
+        const dest = args[args.length - 1]
+        cpSync(fixtureDir, dest, { recursive: true })
+        return Buffer.from('')
+      }
+      return originalExec(cmd, args, options)
+    }) as any)
+
+    const errors: string[] = []
+    const errorSpy = spyOn(console, 'error').mockImplementation((msg: string) => {
+      errors.push(String(msg))
+    })
+
+    const originalExit = process.exit
+    let exitCode: number | undefined
+    process.exit = ((code?: number) => {
+      exitCode = code ?? 0
+      throw new Error(`EXIT:${code}`)
+    }) as typeof process.exit
+
+    try {
+      const { addSkill } = await import('./add.ts')
+      await addSkill('github.com/owner/repo', { deck: join(projectDir, 'skill-deck.toml'), workdir: projectDir, type: 'invalid' })
+      expect(false).toBe(true)
+    } catch (err: any) {
+      expect(exitCode).toBe(1)
+      expect(errors.some(e => e.includes('Invalid type'))).toBe(true)
+    } finally {
+      process.exit = originalExit
+      errorSpy.mockRestore()
+      execSpy.mockRestore()
+    }
+  })
+})

package/src/add.ts

@@ -252,7 +252,7 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
 
     console.log('🔗 Running deck link...')
     const { linkDeck } = await import('./link.js')
-    linkDeck(deckPath === join(workdir, 'skill-deck.toml') ? undefined : deckPath, workdir)
+    linkDeck(deckPath, workdir)
 
   } catch (err) {
     console.error(`❌ Failed to add skill: ${err}`)

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

@@ -79,6 +79,15 @@ export function findSource(name: string, coldPool: string, projectDir: string):
     if (existsSync(join(directPath, "SKILL.md"))) return { path: directPath };
   }
 
+  // 0.5 localhost skills: localhost/skill → cold_pool/skill
+  if (name.startsWith('localhost/')) {
+    const skill = name.slice('localhost/'.length);
+    if (skill) {
+      const localPath = join(coldPool, skill);
+      if (existsSync(join(localPath, "SKILL.md"))) return { path: localPath };
+    }
+  }
+
   // 1. 直接路径
   const direct = resolve(coldPool, name);
   if (existsSync(join(direct, "SKILL.md"))) return { path: direct };