@lythos/skill-deck 0.9.2 → 0.9.13

package/README.md

@@ -1,6 +1,6 @@
 # @lythos/skill-deck
 
-![Coverage](https://img.shields.io/badge/coverage-82%25-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-82%25-brightgreen) ![CI](https://img.shields.io/badge/CI-71%20unit%20%2B%2021%20CLI%20BDD-brightgreen) ![Agent BDD](https://img.shields.io/badge/Agent%20BDD-5%20local-blue) ![Intent/Plan](https://img.shields.io/badge/arch-intent%2Fplan%2Fexecute-8A2BE2)
 
 > Declarative skill deck governance. Reconcile declared skills against your cold pool via symlinks — deny-by-default, max-cards budgeting, transient expiry.
 
@@ -68,7 +68,7 @@ expires = "2026-05-01"    # ISO date; warns at ≤14 days
 |---------|------|-------------|
 | `link` | `[--deck <path>] [--workdir <dir>]` | Sync working set. Removes undeclared skills (deny-by-default). |
 | `validate` | `[deck.toml] [--workdir <dir>]` | Validate deck config without modifying files. |
-| `add` | `<locator> [--via <backend>] [--as <alias>] [--type <type>] [--deck <path>]` | Download skill to cold pool and append to skill-deck.toml. |
+| `add` | `<locator> [--alias <alias>] [--type <type>] [--deck <path>]` | Git clone skill to cold pool and append to skill-deck.toml. |
 | `refresh` | `[<fq|alias>] [--deck <path>]` | Pull latest versions of declared skills from upstream git repos. Pass a name to refresh one skill. |
 | `remove` | `<fq|alias> [--deck <path>]` | Remove skill from deck.toml and working set. Cold pool untouched. |
 | `prune` | `[--yes] [--deck <path>]` | GC cold pool repos no longer referenced. Interactive confirm (skip with `--yes`). |
@@ -79,8 +79,8 @@ expires = "2026-05-01"    # ISO date; warns at ≤14 days
 |------|-------------|---------|
 | `--deck <path>` | Path to skill-deck.toml | Find upward from cwd |
 | `--workdir <dir>` | Working directory | cwd |
-| `--via <backend>` | Download backend for `add`: `git` or `skills.sh` | `git` |
-| `--as <alias>` | Explicit alias for the skill (default: basename of path) | — |
+
+| `--alias <alias>` | Explicit alias for the skill (default: basename of path) | — |
 | `--type <type>` | Target section for `add`: `innate`, `tool`, or `combo` | `tool` |
 
 ### Safety guards
@@ -157,6 +157,30 @@ Different agents look for skills in different directories. `skill-deck.toml` con
 | `deck add` fails with 404 | Locator format wrong or repo doesn't exist | Format: `github.com/owner/repo/skill-name` (path to skill directory inside repo) |
 | `skill-deck.toml not found` | Running `link` outside project tree | Run from project root, or use `--deck ./path/to/skill-deck.toml` |
 
+## Architecture: Intent / Plan / Execute
+
+Deck commands separate pure logic from IO:
+
+```
+deck.toml  →  RefreshPlan / PrunePlan (pure)  →  execute with injectable IO
+```
+
+- **Plan**: `buildRefreshPlan()`, `buildPrunePlan()` — pure functions, unit-testable
+- **Execute**: `executeRefreshPlan(plan, io)`, `executePrunePlan(plan, io)` — IO injected (`gitPull`, `delete`, `log`)
+- **Config**: `workdir`, `coldPool`, `deckPath` all accept explicit overrides, defaults are fallback
+
+This enables testing without real git operations — inject mock `gitPull`, capture `log` output, assert expected behavior.
+
+## Test Coverage
+
+| Layer | Count | CI | Notes |
+|-------|-------|----|-------|
+| Unit tests | 71 | ✅ | Plan generation, link, add, remove, schema |
+| CLI BDD | 21 | ✅ | End-to-end via real CLI invocations in tmpdir |
+| Agent BDD | 5 | ❌ | Requires `claude -p` CLI; `.agent.test.ts` convention |
+
+Coverage is honest — no gate, no inflation. Agent BDD scenarios run locally only.
+
 ## More Documentation
 
 - **Skill layer** (agent-facing instructions):  

package/package.json

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

package/src/add.test.ts

@@ -137,7 +137,7 @@ describe('addSkill', () => {
 
     try {
       const { addSkill } = await import('./add.ts')
-      await addSkill('github.com/owner/repo-b', { workdir: projectDir, deck: deckPath, as: 'foo' })
+      await addSkill('github.com/owner/repo-b', { workdir: projectDir, deck: deckPath, alias: 'foo' })
       expect(false).toBe(true) // should not reach here
     } catch (err: any) {
       expect(exitCode).toBe(1)

package/src/add.ts

@@ -3,8 +3,8 @@
  * deck-add.ts — Skill acquisition command
  *
  * Downloads a skill to the cold pool, updates skill-deck.toml, and links.
- * Supports multiple backends (git clone, skills.sh) without locking users
- * into a single download method.
+ * Single backend: git clone. For feed-based discovery with decision tracking,
+ * use curator add instead.
  */
 
 import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, readFileSync, readdirSync } from 'node:fs'
@@ -16,7 +16,6 @@ import { parse as parseToml, stringify as stringifyToml } from '@iarna/toml'
 import { findDeckToml, expandHome } from './link.js'
 import { parseDeck } from './parse-deck.js'
 
-const CLAUDE_SKILLS_DIR = join(homedir(), '.claude', 'skills')
 
 interface ParsedLocator {
   host: string
@@ -76,7 +75,7 @@ function resolvePath(p: string): string {
   return resolve(p)
 }
 
-export async function addSkill(locator: string, options: { via?: string; deck?: string; workdir?: string; as?: string; type?: string }) {
+export async function addSkill(locator: string, options: { deck?: string; workdir?: string; alias?: string; type?: string }) {
   const workdir = options.workdir ? resolvePath(options.workdir) : process.cwd()
   const deckPath = options.deck
     ? resolvePath(options.deck)
@@ -89,8 +88,6 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
     process.exit(1)
   }
 
-  const backend = options.via || 'git'
-
   let coldPool = join(homedir(), '.agents', 'skill-repos')
   if (existsSync(deckPath)) {
     try {
@@ -117,47 +114,10 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
   const tmpRepo = join(tmpDir, 'repo')
 
   try {
-    let skillSourceDir: string
-
-    if (backend === 'skills.sh' || backend === 'vercel') {
-      const skillsShLocator = `${parsed.owner}/${parsed.repo}`
-      console.log(`📦 Downloading via skills.sh: ${skillsShLocator}`)
-
-      // Snapshot existing directories in ~/.claude/skills/
-      const beforeDirs = existsSync(CLAUDE_SKILLS_DIR)
-        ? new Set(readdirSync(CLAUDE_SKILLS_DIR, { withFileTypes: true })
-            .filter(e => e.isDirectory())
-            .map(e => e.name))
-        : new Set<string>()
-
-      execFileSync('npx', ['skills', 'add', skillsShLocator, '-g'], { cwd: tmpDir, stdio: 'inherit' })
-
-      // Detect the newly installed directory
-      const afterDirs = existsSync(CLAUDE_SKILLS_DIR)
-        ? readdirSync(CLAUDE_SKILLS_DIR, { withFileTypes: true })
-            .filter(e => e.isDirectory())
-            .map(e => e.name)
-        : []
-      const newDirs = afterDirs.filter(d => !beforeDirs.has(d))
-
-      if (newDirs.length === 0) {
-        console.error(`❌ skills.sh installed nothing new to ~/.claude/skills/`)
-        console.error(`   The skill may already be installed, or the install failed.`)
-        process.exit(1)
-      }
-      if (newDirs.length > 1) {
-        console.warn(`⚠️  Multiple new directories detected in ~/.claude/skills/`)
-        console.warn(`   Using the first one: ${newDirs[0]}`)
-      }
-      const installedName = newDirs[0]
-      skillSourceDir = join(CLAUDE_SKILLS_DIR, installedName)
-      console.log(`   Detected install: ${installedName}`)
-    } else {
-      const gitUrl = `https://${parsed.host}/${parsed.owner}/${parsed.repo}.git`
-      console.log(`📦 Cloning: ${gitUrl}`)
-      execFileSync('git', ['clone', '--depth', '1', gitUrl, tmpRepo], { stdio: 'inherit' })
-      skillSourceDir = tmpRepo
-    }
+    const gitUrl = `https://${parsed.host}/${parsed.owner}/${parsed.repo}.git`
+    console.log(`📦 Cloning: ${gitUrl}`)
+    execFileSync('git', ['clone', '--depth', '1', gitUrl, tmpRepo], { stdio: 'inherit' })
+    let skillSourceDir = tmpRepo
 
     if (!existsSync(skillSourceDir)) {
       console.error(`❌ Download failed: expected output not found at ${skillSourceDir}`)
@@ -175,7 +135,7 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
     }
 
     const skillName = parsed.skill ? basename(parsed.skill) : parsed.repo
-    const alias = options.as || skillName
+    const alias = options.alias || skillName
     const skillType = (options.type || 'tool').toLowerCase()
 
     if (!['innate', 'tool', 'combo'].includes(skillType)) {

package/src/cli.ts

@@ -14,14 +14,12 @@ 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 aliasFlagIdx = args.indexOf('--alias')
 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 alias = aliasFlagIdx >= 0 ? args[aliasFlagIdx + 1] : undefined
 const type = typeFlagIdx >= 0 ? args[typeFlagIdx + 1] : undefined
 const noBackup = args.includes('--no-backup')
 const yes = args.includes('--yes')
@@ -42,8 +40,8 @@ const HELP_CONFIG = {
     { 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: '--alias <name>', 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)' },
   ],
@@ -63,7 +61,7 @@ switch (command) {
       console.error('❌ Missing locator. Usage: deck add <github.com/owner/repo[/skill]>')
       process.exit(1)
     }
-    await addSkill(locator, { via, deck: deckPath, workdir, as, type })
+    await addSkill(locator, { deck: deckPath, workdir, alias, type })
     break
   }
   case 'refresh': {

package/src/link.ts

@@ -244,7 +244,7 @@ for (const d of declared) {
 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.`
+      `Alias collision: "${alias}" appears in [${types.join('], [')}]. Use --alias to specify different aliases.`
     );
   }
 }

package/src/prune-plan.test.ts

@@ -0,0 +1,103 @@
+import { describe, test, expect } from 'bun:test'
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolvePruneConfig, scanColdPool, calculateDirSize, buildPrunePlan } from './prune-plan'
+
+const deckToml = `[deck]
+cold_pool = "./cold-pool"
+
+[tool.skills.skill-a]
+path = "github.com/foo/bar/skill-a"
+
+[tool.skills.skill-b]
+path = "localhost/skill-b"
+`
+
+describe('resolvePruneConfig', () => {
+  test('explicit paths override defaults', () => {
+    const cfg = resolvePruneConfig({
+      deckPath: '/tmp/deck.toml',
+      workdir: '/custom/work',
+      coldPool: '/custom/pool',
+    })
+    expect(cfg.deckPath).toBe('/tmp/deck.toml')
+    expect(cfg.workdir).toBe('/custom/work')
+    expect(cfg.coldPool).toBe('/custom/pool')
+  })
+})
+
+describe('scanColdPool', () => {
+  test('empty for nonexistent directory', () => {
+    expect(scanColdPool('/tmp/nonexistent-' + Date.now())).toEqual([])
+  })
+
+  test('finds flat localhost skills in cold pool', () => {
+    const pool = join('/tmp', 'prune-test-pool-' + Date.now())
+    mkdirSync(join(pool, 'skill-b'), { recursive: true })
+    writeFileSync(join(pool, 'skill-b', 'SKILL.md'), '# test')
+
+    const repos = scanColdPool(pool)
+    expect(repos.some(r => r.endsWith('skill-b'))).toBe(true)
+
+    rmSync(pool, { recursive: true, force: true })
+  })
+})
+
+describe('calculateDirSize', () => {
+  test('calculates total size', () => {
+    const dir = join('/tmp', 'size-test-' + Date.now())
+    mkdirSync(join(dir, 'sub'), { recursive: true })
+    writeFileSync(join(dir, 'a.txt'), 'hello')
+    writeFileSync(join(dir, 'sub', 'b.txt'), 'world')
+
+    const size = calculateDirSize(dir)
+    expect(size).toBeGreaterThanOrEqual(10) // 'hello' + 'world' = 10 bytes
+    rmSync(dir, { recursive: true, force: true })
+  })
+})
+
+describe('buildPrunePlan', () => {
+  test('builds plan from deck config', () => {
+    const plan = buildPrunePlan(deckToml, { coldPool: '/tmp/test-pool' })
+    expect(plan.declared).toHaveLength(2)
+    expect(plan.declared).toContain('github.com/foo/bar/skill-a')
+  })
+
+  test('identifies unreferenced repos as candidates', () => {
+    const pool = join('/tmp', 'prune-plan-test-' + Date.now())
+    // Create a declared repo
+    mkdirSync(join(pool, 'github.com', 'foo', 'bar', 'skill-a'), { recursive: true })
+    // Create an UNREFERENCED repo (not in deck)
+    mkdirSync(join(pool, 'github.com', 'baz', 'qux'), { recursive: true })
+
+    const plan = buildPrunePlan(deckToml, { coldPool: pool })
+    const unreferenced = plan.candidates.map(c => c.repoRel)
+    expect(unreferenced).toContain('github.com/baz/qux')
+    // skill-a is declared, should NOT be a candidate
+    expect(unreferenced).not.toContain('github.com/foo/bar/skill-a')
+
+    rmSync(pool, { recursive: true, force: true })
+  })
+
+  test('empty candidates when all repos declared', () => {
+    const pool = join('/tmp', 'prune-all-declared-' + Date.now())
+    mkdirSync(join(pool, 'github.com', 'foo', 'bar', 'skill-a'), { recursive: true })
+    mkdirSync(join(pool, 'localhost', 'skill-b'), { recursive: true })
+
+    const plan = buildPrunePlan(deckToml, { coldPool: pool })
+    expect(plan.candidates).toHaveLength(0)
+
+    rmSync(pool, { recursive: true, force: true })
+  })
+
+  test('totalSize is sum of candidate sizes', () => {
+    const pool = join('/tmp', 'prune-size-test-' + Date.now())
+    mkdirSync(join(pool, 'github.com', 'unref', 'repo'), { recursive: true })
+    writeFileSync(join(pool, 'github.com', 'unref', 'repo', 'data.txt'), 'hello world')
+
+    const plan = buildPrunePlan(deckToml, { coldPool: pool })
+    expect(plan.totalSize).toBeGreaterThanOrEqual(11)
+
+    rmSync(pool, { recursive: true, force: true })
+  })
+})

package/src/prune-plan.ts

@@ -0,0 +1,188 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import { findDeckToml, expandHome } from './link'
+import { parseDeck } from './parse-deck'
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface PruneCandidate {
+  repoPath: string
+  repoRel: string                  // relative to cold pool
+  size: number                     // bytes
+}
+
+export interface PrunePlan {
+  deckPath: string
+  workdir: string
+  coldPool: string
+  candidates: PruneCandidate[]     // unreferenced repos to delete
+  declared: string[]               // declared skill names (for audit)
+  totalSize: number                // total reclaimable bytes
+}
+
+// ── Config resolution ──────────────────────────────────────────────────────
+
+export function resolvePruneConfig(opts?: {
+  deckPath?: string
+  workdir?: string
+  coldPool?: string
+}) {
+  const deckPath = opts?.deckPath
+    ? resolve(opts.deckPath)
+    : (findDeckToml(process.cwd()) || resolve('skill-deck.toml'))
+
+  const workdir = opts?.workdir
+    ? resolve(opts.workdir)
+    : join(deckPath, '..')
+
+  const coldPool = opts?.coldPool
+    ? resolve(opts.coldPool)
+    : expandHome('~/.agents/skill-repos', workdir)
+
+  return { deckPath, workdir, coldPool }
+}
+
+// ── Cold pool scanner (pure: reads, no delete) ─────────────────────────────
+
+export function scanColdPool(coldPool: string): string[] {
+  const repos: string[] = []
+  if (!existsSync(coldPool)) return repos
+
+  try {
+    for (const host of readdirSync(coldPool, { withFileTypes: true })) {
+      if (!host.isDirectory() || host.name.startsWith('.')) continue
+      const hostPath = join(coldPool, host.name)
+
+      // Flat skill: cold-pool/skill-name/SKILL.md (localhost style)
+      if (existsSync(join(hostPath, 'SKILL.md'))) {
+        repos.push(hostPath)
+        continue
+      }
+
+      // Nested: cold-pool/github.com/owner/repo/
+      for (const owner of readdirSync(hostPath, { withFileTypes: true })) {
+        if (!owner.isDirectory() || owner.name.startsWith('.')) continue
+        const ownerPath = join(hostPath, owner.name)
+        for (const repo of readdirSync(ownerPath, { withFileTypes: true })) {
+          if (!repo.isDirectory() || repo.name.startsWith('.')) continue
+          repos.push(join(ownerPath, repo.name))
+        }
+      }
+    }
+  } catch {}
+
+  return repos
+}
+
+// ── Size calculation (pure helper) ─────────────────────────────────────────
+
+export function calculateDirSize(dir: string): number {
+  let total = 0
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        total += calculateDirSize(p)
+      } else if (entry.isFile()) {
+        total += statSync(p).size
+      }
+    }
+  } catch {}
+  return total
+}
+
+// ── Plan builder (pure: no deletion, no mutation) ──────────────────────────
+
+export function buildPrunePlan(
+  deckRaw: string,
+  opts?: { deckPath?: string; workdir?: string; coldPool?: string }
+): PrunePlan {
+  const { deckPath, workdir, coldPool: configuredColdPool } = resolvePruneConfig(opts)
+
+  // Read cold_pool from deck.toml if not explicitly overridden
+  let coldPool = configuredColdPool
+  if (!opts?.coldPool) {
+    const deckMatch = deckRaw.match(/cold_pool\s*=\s*"([^"]+)"/)
+    if (deckMatch) {
+      coldPool = expandHome(deckMatch[1], workdir)
+    }
+  }
+
+  // Get declared skill paths from deck
+  const { entries: declared } = parseDeck(deckRaw)
+  const declaredPaths = new Set(declared.map(d => d.path))
+
+  // Scan cold pool for all repos
+  const allRepos = scanColdPool(coldPool)
+
+  // Find unreferenced: repos not declared in deck
+  const candidates: PruneCandidate[] = []
+  for (const repoPath of allRepos) {
+    // A repo is referenced if any declared skill path starts with its cold-pool-relative path
+    const repoRel = repoPath.slice(coldPool.length + 1) // relative to cold pool
+    const isReferenced = [...declaredPaths].some(d => d.startsWith(repoRel) || repoRel.startsWith(d))
+
+    if (!isReferenced) {
+      candidates.push({
+        repoPath,
+        repoRel,
+        size: calculateDirSize(repoPath),
+      })
+    }
+  }
+
+  const totalSize = candidates.reduce((sum, c) => sum + c.size, 0)
+
+  return {
+    deckPath,
+    workdir,
+    coldPool,
+    candidates,
+    declared: declared.map(d => d.path),
+    totalSize,
+  }
+}
+
+// ── Execution (IO layer, injectable for testing) ───────────────────────────
+
+export interface PruneResult {
+  repoRel: string
+  deleted: boolean
+  error?: string
+}
+
+export interface PruneIO {
+  delete?: (path: string) => void
+  log?: (msg: string) => void
+  formatSize?: (bytes: number) => string
+}
+
+export function executePrunePlan(plan: PrunePlan, io?: PruneIO): PruneResult[] {
+  const deleteFn = io?.delete ?? ((_path: string) => { throw new Error('delete not injected') })
+  const log = io?.log ?? (() => {})
+  const fmtSize = io?.formatSize ?? ((b: number) => b < 1024 ? `${b}B` : b < 1024 * 1024 ? `${(b / 1024).toFixed(1)}KB` : `${(b / (1024 * 1024)).toFixed(1)}MB`)
+
+  log(`\n🧹 Prune candidates — ${plan.candidates.length} repo(s), ${fmtSize(plan.totalSize)} total:\n`)
+  for (const c of plan.candidates) {
+    log(`   ${c.repoRel} (${fmtSize(c.size)})`)
+  }
+
+  const results: PruneResult[] = []
+  let deleted = 0, failed = 0
+
+  for (const c of plan.candidates) {
+    try {
+      deleteFn(c.repoPath)
+      log(`  🗑️  Deleted: ${c.repoRel}`)
+      results.push({ repoRel: c.repoRel, deleted: true })
+      deleted++
+    } catch (err: any) {
+      log(`  ❌ Failed to delete ${c.repoRel}: ${err.message}`)
+      results.push({ repoRel: c.repoRel, deleted: false, error: err.message })
+      failed++
+    }
+  }
+
+  log(`\n📦 Prune complete: ${deleted} deleted, ${failed} failed`)
+  return results
+}

package/src/prune.ts

@@ -7,12 +7,11 @@
  * Does NOT modify deck.toml or the working set.
  */
 
-import { parse as parseToml } from "@iarna/toml";
-import { existsSync, readFileSync, readdirSync, statSync, rmSync } from "node:fs";
-import { resolve, dirname, join, relative } from "node:path";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
 import { createInterface } from "node:readline";
-import { findDeckToml, expandHome, findSource } from "./link.js";
-import { parseDeck } from "./parse-deck.js";
+import { findDeckToml } from "./link.js";
+import { buildPrunePlan, executePrunePlan } from "./prune-plan.js";
 
 interface PruneCandidate {
   repoPath: string;
@@ -103,108 +102,60 @@ async function confirm(message: string): Promise<boolean> {
 }
 
 export async function pruneDeck(cliDeckPath?: string, cliWorkdir?: string, yes?: boolean): Promise<void> {
-  const cliDeck = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
-  const DECK_PATH = cliDeck
-    ? resolve(cliDeck)
-    : findDeckToml(process.cwd()) || resolve("skill-deck.toml");
+  const deckPath = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
+  const workdir = cliWorkdir
 
-  if (!existsSync(DECK_PATH)) {
-    console.error(`❌ skill-deck.toml not found in ${process.cwd()}`);
-    console.error(`\nCreate one or specify a path: bunx @lythos/skill-deck link --deck /path/to/deck.toml`);
-    process.exit(1);
-  }
-
-  const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : dirname(DECK_PATH);
-  const deckRaw = readFileSync(DECK_PATH, "utf-8");
-  const deck = parseToml(deckRaw) as any;
-
-  const COLD_POOL = expandHome(deck.deck?.cold_pool || "~/.agents/skill-repos", PROJECT_DIR);
-
-  // ── 收集声明 ────────────────────────────────────────────────
-
-  const { entries: parsedEntries } = parseDeck(deckRaw);
-  const declaredPaths = parsedEntries.map(e => e.path);
-
-  // Legacy string-array fallback
-  for (const section of ["innate", "tool", "combo"] as const) {
-    const skills = deck[section]?.skills;
-    if (Array.isArray(skills)) {
-      for (const name of skills) {
-        if (name && typeof name === "string" && !declaredPaths.includes(name)) {
-          declaredPaths.push(name);
-        }
-      }
-    }
-  }
-
-  // ── 扫描 cold pool ──────────────────────────────────────────
+  const DECK_PATH = deckPath ? resolve(deckPath) : findDeckToml(process.cwd()) || resolve('skill-deck.toml')
 
-  if (!existsSync(COLD_POOL)) {
-    console.log("📭 Cold pool does not exist. Nothing to prune.");
-    process.exit(0);
+  if (!existsSync(DECK_PATH)) {
+    console.error(`❌ skill-deck.toml not found in ${process.cwd()}`)
+    console.error(`\nCreate one or specify a path: bunx @lythos/skill-deck link --deck /path/to/deck.toml`)
+    process.exit(1)
   }
 
-  const allRepos = scanColdPoolRepos(COLD_POOL);
-  if (allRepos.length === 0) {
-    console.log("📭 Cold pool is empty. Nothing to prune.");
-    process.exit(0);
-  }
+  const deckRaw = readFileSync(DECK_PATH, 'utf-8')
 
-  // ── 求差集 ──────────────────────────────────────────────────
+  // ── Plan: pure unreferenced detection ──────────────────────────────
+  const plan = buildPrunePlan(deckRaw, {
+    deckPath: DECK_PATH,
+    workdir: workdir ? resolve(workdir) : undefined,
+  })
 
-  const candidates: PruneCandidate[] = [];
-  for (const repoPath of allRepos) {
-    if (isRepoReferenced(repoPath, declaredPaths, COLD_POOL, PROJECT_DIR)) continue;
-    const size = calculateDirSize(repoPath);
-    candidates.push({ repoPath, repoRel: relative(COLD_POOL, repoPath), size });
+  if (!existsSync(plan.coldPool)) {
+    console.log('📭 Cold pool does not exist. Nothing to prune.')
+    process.exit(0)
   }
 
-  if (candidates.length === 0) {
-    console.log("✅ All cold pool repositories are referenced. Nothing to prune.");
-    process.exit(0);
+  if (plan.candidates.length === 0 && plan.declared.length === 0) {
+    console.log('📭 Cold pool is empty. Nothing to prune.')
+    process.exit(0)
   }
 
-  // ── 报告 ────────────────────────────────────────────────────
-
-  const totalSize = candidates.reduce((sum, c) => sum + c.size, 0);
-  console.log(`\n🧹 Prune candidates — ${candidates.length} repo(s), ${formatSize(totalSize)} total:\n`);
-  for (const c of candidates) {
-    console.log(`   ${c.repoRel} (${formatSize(c.size)})`);
+  if (plan.candidates.length === 0) {
+    console.log('✅ All cold pool repositories are referenced. Nothing to prune.')
+    process.exit(0)
   }
 
-  // ── 确认 ────────────────────────────────────────────────────
-
-  let shouldDelete = false;
+  // ── Confirm ──────────────────────────────────────────────────────
+  let shouldDelete = false
   if (yes) {
-    shouldDelete = true;
-    console.log("\n⚠️  --yes flag set: deleting without confirmation.");
+    shouldDelete = true
+    console.log('\n⚠️  --yes flag set: deleting without confirmation.')
   } else {
-    shouldDelete = await confirm(`\nDelete ${candidates.length} unreferenced repo(s)?`);
+    shouldDelete = await confirm(`\nDelete ${plan.candidates.length} unreferenced repo(s)?`)
   }
 
   if (!shouldDelete) {
-    console.log("❎ Prune cancelled.");
-    process.exit(0);
+    console.log('❎ Prune cancelled.')
+    process.exit(0)
   }
 
-  // ── 执行删除 ────────────────────────────────────────────────
-
-  let deleted = 0;
-  let failed = 0;
-  for (const c of candidates) {
-    try {
-      rmSync(c.repoPath, { recursive: true, force: true });
-      console.log(`  🗑️  Deleted: ${c.repoRel}`);
-      deleted++;
-    } catch (err: any) {
-      console.error(`  ❌ Failed to delete ${c.repoRel}: ${err.message}`);
-      failed++;
-    }
-  }
+  // ── Execute with real IO ──────────────────────────────────────────
+  const results = executePrunePlan(plan, {
+    delete: (path: string) => rmSync(path, { recursive: true, force: true }),
+    log: console.log,
+    formatSize,
+  })
 
-  console.log(`\n📦 Prune complete: ${deleted} deleted, ${failed} failed`);
-
-  if (failed > 0) {
-    process.exit(1);
-  }
+  if (results.some(r => !r.deleted)) process.exit(1)
 }

package/src/refresh-plan.test.ts

@@ -0,0 +1,118 @@
+import { describe, test, expect } from 'bun:test'
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveRefreshConfig, detectGitRoot, buildRefreshPlan } from './refresh-plan'
+
+const deckAliasDict = `[deck]
+max_cards = 10
+cold_pool = "./cold-pool"
+
+[tool.skills.skill-a]
+path = "github.com/foo/bar/skill-a"
+
+[tool.skills.skill-b]
+path = "localhost/skill-b"
+`
+
+describe('resolveRefreshConfig', () => {
+  test('returns strings without throwing when no opts', () => {
+    const cfg = resolveRefreshConfig()
+    expect(typeof cfg.deckPath).toBe('string')
+    expect(typeof cfg.workdir).toBe('string')
+    expect(typeof cfg.coldPool).toBe('string')
+  })
+
+  test('resolves explicit deckPath', () => {
+    const cfg = resolveRefreshConfig({ deckPath: '/tmp/test-deck.toml' })
+    expect(cfg.deckPath).toBe('/tmp/test-deck.toml')
+  })
+
+  test('workdir falls back to deckPath dirname', () => {
+    const cfg = resolveRefreshConfig({ deckPath: '/tmp/my-deck.toml' })
+    expect(cfg.workdir).toBe('/tmp')
+  })
+
+  test('explicit workdir overrides fallback', () => {
+    const cfg = resolveRefreshConfig({ deckPath: '/tmp/my-deck.toml', workdir: '/custom/workdir' })
+    expect(cfg.workdir).toBe('/custom/workdir')
+  })
+
+  test('explicit coldPool resolved', () => {
+    const cfg = resolveRefreshConfig({ coldPool: '/custom/cold-pool' })
+    expect(cfg.coldPool).toBe('/custom/cold-pool')
+  })
+})
+
+describe('detectGitRoot', () => {
+  test('localhost skill → localhost type', () => {
+    const result = detectGitRoot('/pool/localhost/skill-a', '/pool')
+    expect(result.type).toBe('localhost')
+  })
+
+  test('localhost as root → localhost type', () => {
+    const result = detectGitRoot('/pool/localhost', '/pool')
+    expect(result.type).toBe('localhost')
+  })
+
+  test('not-git: directory without .git', () => {
+    const dir = join('/tmp', 'refresh-test-no-git-' + Date.now())
+    mkdirSync(dir, { recursive: true })
+    const result = detectGitRoot(dir, '/tmp')
+    expect(result.type).toBe('not-git')
+    rmSync(dir, { recursive: true, force: true })
+  })
+})
+
+describe('buildRefreshPlan', () => {
+  test('builds plan from alias-dict deck', () => {
+    const plan = buildRefreshPlan(deckAliasDict, { coldPool: '/tmp/test-cold-pool' })
+    expect(plan.targets).toHaveLength(2)
+    expect(plan.allDeclared).toHaveLength(2)
+  })
+
+  test('filters by alias when target specified', () => {
+    const plan = buildRefreshPlan(deckAliasDict, {
+      coldPool: '/tmp/test-cold-pool',
+      target: 'skill-a',
+    })
+    expect(plan.targets).toHaveLength(1)
+    expect(plan.targets[0].alias).toBe('skill-a')
+  })
+
+  test('filters by path when target specified', () => {
+    const plan = buildRefreshPlan(deckAliasDict, {
+      coldPool: '/tmp/test-cold-pool',
+      target: 'github.com/foo/bar/skill-a',
+    })
+    expect(plan.targets).toHaveLength(1)
+    expect(plan.targets[0].path).toBe('github.com/foo/bar/skill-a')
+  })
+
+  test('unknown target → empty plan', () => {
+    const plan = buildRefreshPlan(deckAliasDict, {
+      coldPool: '/tmp/test-cold-pool',
+      target: 'nonexistent',
+    })
+    expect(plan.targets).toHaveLength(0)
+  })
+
+  test('localhost skill is in plan as declared', () => {
+    const plan = buildRefreshPlan(deckAliasDict, { coldPool: '/tmp/test-cold-pool' })
+    const localhost = plan.targets.find(t => t.alias === 'skill-b')
+    // Without a real cold pool, source resolution may fail → 'missing'
+    // Plan structure is what matters; type depends on actual filesystem
+    expect(localhost).toBeDefined()
+    expect(localhost!.path).toBe('localhost/skill-b')
+  })
+
+  test('paths are resolved through config', () => {
+    const plan = buildRefreshPlan(deckAliasDict, {
+      deckPath: '/custom/deck.toml',
+      workdir: '/custom/work',
+      coldPool: '/custom/pool',
+    })
+    expect(plan.deckPath).toBe('/custom/deck.toml')
+    expect(plan.workdir).toBe('/custom/work')
+    expect(plan.coldPool).toBe('/custom/pool')
+  })
+})

package/src/refresh-plan.ts

@@ -0,0 +1,212 @@
+import { existsSync } from 'node:fs'
+import { resolve, dirname, relative } from 'node:path'
+import { realpathSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+import { findDeckToml, expandHome, findSource } from './link'
+import { parseDeck, type ParsedSkillEntry } from './parse-deck'
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface RefreshTarget {
+  alias: string
+  path: string                      // FQ path
+  sourcePath: string                // absolute path in cold pool
+  sourceRel: string                 // relative to cold pool
+  type: 'git' | 'localhost' | 'missing' | 'not-git'
+  gitRoot?: string                  // populated for 'git' type
+}
+
+export interface RefreshPlan {
+  deckPath: string
+  workdir: string
+  coldPool: string
+  targets: RefreshTarget[]
+  allDeclared: ParsedSkillEntry[]
+}
+
+// ── Config resolution (pure, defaults via params) ──────────────────────────
+
+export function resolveRefreshConfig(opts?: {
+  deckPath?: string
+  workdir?: string
+  coldPool?: string
+}) {
+  const deckPath = opts?.deckPath
+    ? resolve(opts.deckPath)
+    : (findDeckToml(process.cwd()) || resolve('skill-deck.toml'))
+
+  const workdir = opts?.workdir
+    ? resolve(opts.workdir)
+    : dirname(deckPath)
+
+  const coldPool = opts?.coldPool
+    ? resolve(opts.coldPool)
+    : expandHome('~/.agents/skill-repos', workdir)
+
+  return { deckPath, workdir, coldPool }
+}
+
+// ── Git detection (pure: only checks directory structure, no mutation) ─────
+
+export function detectGitRoot(skillDir: string, coldPool: string): { gitRoot?: string; type: RefreshTarget['type'] } {
+  // localhost skills are user-managed
+  const rel = relative(coldPool, skillDir)
+  if (rel.startsWith('localhost') || rel === 'localhost') {
+    return { type: 'localhost' }
+  }
+
+  // Standalone skill: .git directly in skill dir
+  if (existsSync(resolve(skillDir, '.git'))) {
+    return { gitRoot: skillDir, type: 'git' }
+  }
+
+  try {
+    const out = execSync('git rev-parse --show-toplevel', {
+      cwd: skillDir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim()
+
+    // Normalize paths (macOS /tmp → /private/tmp)
+    const resolvedRoot = realpathSync(out)
+    const resolvedDir = realpathSync(skillDir)
+    const resolvedPool = realpathSync(coldPool)
+
+    // Must be ancestor of skillDir and within coldPool
+    if (resolvedDir.startsWith(resolvedRoot + '/') &&
+        (resolvedRoot === resolvedPool || resolvedRoot.startsWith(resolvedPool + '/'))) {
+      return { gitRoot: out, type: 'git' }
+    }
+  } catch {}
+
+  return { type: 'not-git' }
+}
+
+// ── Plan builder (pure: no git pull, no mutation) ──────────────────────────
+
+export function buildRefreshPlan(
+  deckRaw: string,
+  opts?: { deckPath?: string; workdir?: string; coldPool?: string; target?: string }
+): RefreshPlan {
+  const { deckPath, workdir, coldPool: configuredColdPool } = resolveRefreshConfig(opts)
+
+  // Read cold_pool from deck.toml [deck] section if not explicitly overridden
+  let coldPool = configuredColdPool
+  if (!opts?.coldPool) {
+    const deckMatch = deckRaw.match(/cold_pool\s*=\s*"([^"]+)"/)
+    if (deckMatch) {
+      coldPool = expandHome(deckMatch[1], workdir)
+    }
+  }
+
+  const { entries: allDeclared } = parseDeck(deckRaw)
+
+  // Filter to target (by alias or path) if specified
+  let declared = allDeclared
+  if (opts?.target) {
+    const byAlias = allDeclared.find(d => d.alias === opts.target)
+    if (byAlias) {
+      declared = [byAlias]
+    } else {
+      const byPath = allDeclared.find(d => d.path === opts.target)
+      if (byPath) {
+        declared = [byPath]
+      } else {
+        declared = [] // target not found → empty plan
+      }
+    }
+  }
+
+  const targets: RefreshTarget[] = []
+
+  for (const entry of declared) {
+    const source = findSource(entry.path, coldPool, workdir)
+
+    if (source.error || !source.path) {
+      targets.push({ alias: entry.alias, path: entry.path, sourcePath: '', sourceRel: '', type: 'missing' })
+      continue
+    }
+
+    const { gitRoot, type } = detectGitRoot(source.path, coldPool)
+    const sourceRel = relative(coldPool, source.path)
+
+    targets.push({
+      alias: entry.alias,
+      path: entry.path,
+      sourcePath: source.path,
+      sourceRel,
+      type,
+      gitRoot,
+    })
+  }
+
+  return { deckPath, workdir, coldPool, targets, allDeclared }
+}
+
+// ── Execution (IO layer, injectable for testing) ───────────────────────────
+
+export interface RefreshResult {
+  alias: string
+  path: string
+  status: 'updated' | 'up-to-date' | 'skipped' | 'failed' | 'not-git'
+  message?: string
+}
+
+export interface RefreshIO {
+  gitPull?: (dir: string) => { status: 'updated' | 'up-to-date' | 'failed'; message: string }
+  log?: (msg: string) => void
+  linkDeck?: (deckPath?: string, workdir?: string) => void
+}
+
+export function executeRefreshPlan(plan: RefreshPlan, io?: RefreshIO): RefreshResult[] {
+  const gitPull = io?.gitPull ?? (() => ({ status: 'failed' as const, message: 'gitPull not injected' }))
+  const log = io?.log ?? (() => {})
+
+  const results: RefreshResult[] = []
+  let updated = 0, upToDate = 0, skipped = 0, failed = 0
+
+  for (const t of plan.targets) {
+    switch (t.type) {
+      case 'missing':
+        results.push({ alias: t.alias, path: '', status: 'failed', message: 'Skill not found in cold pool' })
+        failed++
+        break
+      case 'localhost':
+        results.push({ alias: t.alias, path: t.sourceRel, status: 'skipped', message: 'localhost skill — user-managed' })
+        skipped++
+        break
+      case 'not-git':
+        results.push({ alias: t.alias, path: t.sourceRel, status: 'not-git', message: 'skipped: not a git repository' })
+        skipped++
+        break
+      case 'git': {
+        const pullResult = gitPull(t.gitRoot!)
+        results.push({ alias: t.alias, path: t.sourceRel, status: pullResult.status, message: pullResult.message })
+        if (pullResult.status === 'updated') updated++
+        else if (pullResult.status === 'up-to-date') upToDate++
+        else failed++
+        break
+      }
+    }
+  }
+
+  // Report phase
+  const scope = plan.targets.length === plan.allDeclared.length
+    ? `${plan.allDeclared.length} skill(s)`
+    : 'single skill'
+  log(`\n📦 Skill Refresh Report — ${scope} checked`)
+  log(`   Updated: ${updated} | Up-to-date: ${upToDate} | Skipped: ${skipped} | Failed: ${failed}`)
+
+  for (const r of results) {
+    const icon = r.status === 'updated' ? '🔄' : r.status === 'up-to-date' ? '✅' :
+      r.status === 'skipped' ? '⏭️' : r.status === 'not-git' ? '📁' : '❌'
+    log(`${icon} ${r.alias}`)
+    if (r.message) log(`   ${r.message}`)
+  }
+
+  if (updated > 0) {
+    io?.linkDeck?.()
+  }
+
+  return results
+}

package/src/refresh.ts

@@ -7,12 +7,18 @@
  * Never modifies deck.toml.
  */
 
-import { parse as parseToml } from "@iarna/toml";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { execSync } from "node:child_process";
-import { resolve, dirname, join, relative } from "node:path";
-import { findDeckToml, expandHome, findSource, linkDeck } from "./link.js";
+import { resolve } from "node:path";
+import { findDeckToml, linkDeck } from "./link.js";
 import { parseDeck } from "./parse-deck.js";
+import { buildRefreshPlan, detectGitRoot, executeRefreshPlan } from "./refresh-plan.js";
+
+// Backward compat: old findGitRoot returns string|null
+export function findGitRoot(dir: string, coldPool: string): string | null {
+  const result = detectGitRoot(dir, coldPool)
+  return result.gitRoot ?? null
+}
 
 interface RefreshResult {
   name: string;
@@ -21,39 +27,6 @@ interface RefreshResult {
   message?: string;
 }
 
-export function findGitRoot(dir: string, coldPool: string): string | null {
-  // Standalone skill: .git directly in skill dir
-  if (existsSync(join(dir, ".git"))) {
-    return dir;
-  }
-
-  try {
-    const out = execSync("git rev-parse --show-toplevel", {
-      cwd: dir,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-    }).trim();
-
-    const resolvedRoot = realpathSync(out);
-    const resolvedDir = realpathSync(dir);
-    const resolvedColdPool = realpathSync(coldPool);
-
-    // Must be an ancestor of dir (standalone case handled above)
-    if (!resolvedDir.startsWith(resolvedRoot + "/")) {
-      return null;
-    }
-
-    // Must be within cold_pool — prevents finding an unrelated git repo outside
-    if (resolvedRoot === resolvedColdPool || resolvedRoot.startsWith(resolvedColdPool + "/")) {
-      return out;
-    }
-
-    return null;
-  } catch {
-    return null;
-  }
-}
-
 function gitPull(dir: string): { status: "updated" | "up-to-date" | "failed"; message: string } {
   try {
     const output = execSync("git pull", {
@@ -74,140 +47,54 @@ function gitPull(dir: string): { status: "updated" | "up-to-date" | "failed"; me
 }
 
 export function refreshDeck(cliDeckPath?: string, cliWorkdir?: string, target?: string): void {
-  const cliDeck = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
-  const DECK_PATH = cliDeck
-    ? resolve(cliDeck)
-    : findDeckToml(process.cwd()) || resolve("skill-deck.toml");
+  const deckPath = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
+  const workdir = cliWorkdir
+
+  const DECK_PATH = deckPath ? resolve(deckPath) : findDeckToml(process.cwd()) || resolve('skill-deck.toml')
 
   if (!existsSync(DECK_PATH)) {
-    console.error(`❌ skill-deck.toml not found in ${process.cwd()}`);
-    console.error(`\nCreate one or specify a path: bunx @lythos/skill-deck link --deck /path/to/deck.toml`);
-    process.exit(1);
+    console.error(`❌ skill-deck.toml not found in ${process.cwd()}`)
+    console.error(`\nCreate one or specify a path: bunx @lythos/skill-deck link --deck /path/to/deck.toml`)
+    process.exit(1)
   }
 
-  const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : dirname(DECK_PATH);
-  const deckRaw = readFileSync(DECK_PATH, "utf-8");
-  const deck = parseToml(deckRaw) as any;
-
-  const COLD_POOL = expandHome(deck.deck?.cold_pool || "~/.agents/skill-repos", PROJECT_DIR);
+  const deckRaw = readFileSync(DECK_PATH, 'utf-8')
 
-  // ── 收集声明 ────────────────────────────────────────────────
+  // ── Plan: pure target collection + type classification ─────────────
+  const plan = buildRefreshPlan(deckRaw, {
+    deckPath: DECK_PATH,
+    workdir: workdir ? resolve(workdir) : undefined,
+    coldPool: undefined, // derive from deck
+    target,
+  })
 
-  const declared: { name: string; alias: string; path: string; type: string }[] = [];
-
-  // Use parseDeck for alias-dict compatibility
-  const { entries: parsedEntries, deprecated: isDeprecated } = parseDeck(deckRaw);
+  const { entries: parsedEntries, deprecated: isDeprecated } = parseDeck(deckRaw)
   if (isDeprecated) {
-    console.warn("⚠️  Deprecation: string-array skill entries are deprecated. Run `deck migrate-schema` to upgrade.");
+    console.warn('⚠️  Deprecation: string-array skill entries are deprecated. Run `deck migrate-schema` to upgrade.')
   }
 
-  for (const entry of parsedEntries) {
-    declared.push({ name: entry.path, alias: entry.alias, path: entry.path, type: entry.type });
+  if (parsedEntries.length === 0) {
+    console.log('📭 No skills declared in deck. Nothing to refresh.')
+    process.exit(0)
   }
 
-  if (declared.length === 0) {
-    console.log("📭 No skills declared in deck. Nothing to refresh.");
-    process.exit(0);
+  if (target && plan.targets.length === 0) {
+    console.error(`❌ Skill not found in deck: ${target}`)
+    const { entries } = parseDeck(deckRaw)
+    console.error(`   Declared aliases: ${entries.map(d => d.alias).join(', ')}`)
+    process.exit(1)
   }
 
-  // ── 确定目标 ────────────────────────────────────────────────
-
-  let targets: { name: string; alias: string; path: string; type: string }[];
-
-  if (target) {
-    // Try resolve as alias first, then as FQ path
-    const byAlias = declared.find(d => d.alias === target);
-    if (byAlias) {
-      targets = [byAlias];
-    } else {
-      const byPath = declared.find(d => d.path === target);
-      if (byPath) {
-        targets = [byPath];
-      } else {
-        console.error(`❌ Skill not found in deck: ${target}`);
-        console.error(`   Declared aliases: ${declared.map(d => d.alias).join(", ")}`);
-        process.exit(1);
-      }
-    }
-  } else {
-    targets = declared;
-  }
-
-  // ── 执行刷新 ────────────────────────────────────────────────
-
-  const results: RefreshResult[] = [];
-  let updated = 0;
-  let upToDate = 0;
-  let skipped = 0;
-  let failed = 0;
-
-  for (const item of targets) {
-    const result = findSource(item.path, COLD_POOL, PROJECT_DIR);
-
-    if (result.error || !result.path) {
-      results.push({ name: item.alias, path: "", status: "failed", message: result.error || "Skill not found in cold pool" });
-      failed++;
-      continue;
-    }
-
-    const path = result.path;
-
-    // localhost skills are user-managed; skip
-    const relativePath = relative(COLD_POOL, path);
-    if (relativePath.startsWith("localhost")) {
-      results.push({ name: item.alias, path: relativePath, status: "skipped", message: "localhost skill — user-managed" });
-      skipped++;
-      continue;
-    }
-
-    const gitRoot = findGitRoot(path, COLD_POOL);
-    if (!gitRoot) {
-      results.push({ name: item.alias, path: relativePath, status: "not-git", message: "skipped: not a git repository" });
-      skipped++;
-      continue;
-    }
-
-    const pullResult = gitPull(gitRoot);
-    results.push({ name: item.alias, path: relativePath, status: pullResult.status, message: pullResult.message });
-
-    if (pullResult.status === "updated") updated++;
-    else if (pullResult.status === "up-to-date") upToDate++;
-    else failed++;
-  }
-
-  // ── 报告 ────────────────────────────────────────────────────
-
-  const scope = target ? `single skill` : `${declared.length} skill(s)`;
-  console.log(`\n📦 Skill Refresh Report — ${scope} checked`);
-  console.log(`   Updated: ${updated} | Up-to-date: ${upToDate} | Skipped: ${skipped} | Failed: ${failed}`);
-  console.log();
-
-  for (const r of results) {
-    const icon =
-      r.status === "updated" ? "🔄" :
-      r.status === "up-to-date" ? "✅" :
-      r.status === "skipped" ? "⏭️" :
-      r.status === "not-git" ? "📁" :
-      "❌";
-    console.log(`${icon} ${r.name}`);
-    if (r.message && r.status !== "up-to-date") {
-      const lines = r.message.split("\n").filter(l => l.trim());
-      for (const line of lines.slice(0, 3)) {
-        console.log(`   ${line.trim()}`);
-      }
-      if (lines.length > 3) {
-        console.log(`   ... (${lines.length - 3} more lines)`);
-      }
-    }
-  }
-
-  if (updated > 0) {
-    console.log(`\n💡 Run 'bunx @lythos/skill-deck link' to sync refreshed skills to working set.`);
-    console.log("🔗 Running deck link...");
-    linkDeck(cliDeckPath, cliWorkdir);
-  }
-
-  if (failed > 0) {
-    process.exit(1);
-  }
+  // ── Execute with real IO ────────────────────────────────────
+  const results = executeRefreshPlan(plan, {
+    gitPull,
+    log: console.log,
+    linkDeck: () => {
+      console.log(`\n💡 Run 'bunx @lythos/skill-deck link' to sync refreshed skills to working set.`)
+      console.log('🔗 Running deck link...')
+      linkDeck(cliDeckPath, cliWorkdir)
+    },
+  })
+
+  if (results.some(r => r.status === 'failed')) process.exit(1)
 }