@lythos/skill-deck 0.9.17 → 0.9.19

package/README.md

@@ -9,7 +9,7 @@
 This package exposes a **CLI**. Invoke via:
 
 ```bash
-bunx @lythos/skill-deck@0.9.17 <command> [options]
+bunx @lythos/skill-deck@0.9.19 <command> [options]
 ```
 
 No installation required. `bunx` auto-downloads the package.
@@ -53,14 +53,14 @@ expires = "2026-05-01"    # ISO date; warns at ≤14 days
 
 | Situation | Command |
 |-----------|---------|
-| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.17 link` |
-| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.17 validate` |
-| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.17 add owner/repo` |
-| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.17 refresh` |
-| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.17 refresh tdd` |
-| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.17 remove tdd` |
-| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.17 prune` |
-| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.17 link --deck ./my-deck.toml --workdir /path/to/project` |
+| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.19 link` |
+| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.19 validate` |
+| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.19 add owner/repo` |
+| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.19 refresh` |
+| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.19 refresh tdd` |
+| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.19 remove tdd` |
+| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.19 prune` |
+| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.19 link --deck ./my-deck.toml --workdir /path/to/project` |
 
 ### Commands
 
@@ -117,7 +117,7 @@ path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/
-bunx @lythos/skill-deck@0.9.17 link
+bunx @lythos/skill-deck@0.9.19 link
 ```
 
 ### Key Concepts
@@ -146,7 +146,7 @@ Different agents look for skills in different directories. `skill-deck.toml` con
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| `❌ Skill not found: <name>` | Skill declared in deck but not in cold pool | `bunx @lythos/skill-deck@0.9.17 add github.com/owner/repo/skill` or clone manually into cold pool |
+| `❌ Skill not found: <name>` | Skill declared in deck but not in cold pool | `bunx @lythos/skill-deck@0.9.19 add github.com/owner/repo/skill` or clone manually into cold pool |
 | `link` skips entries with warnings | Real files/directories exist in working set (not symlinks) | Delete the real directories in `working_set` and re-run `link`. Never create directories manually there |
 | `refresh` reports "Not a git repository" | Skill was copied (not cloned) into cold pool | Re-clone with `git clone` or use `deck add` which clones by default |
 | `deck update` prints deprecation warning | `update` was renamed to `refresh` in v0.8+ | Use `deck refresh` instead |

package/package.json

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

package/src/add.ts

@@ -75,7 +75,8 @@ function resolvePath(p: string): string {
   return resolve(p)
 }
 
-export async function addSkill(locator: string, options: { deck?: string; workdir?: string; alias?: string; type?: string }) {
+export async function addSkill(locator: string, options: { deck?: string; workdir?: string; alias?: string; type?: string; dryRun?: boolean }) {
+  const dryRun = options.dryRun || false
   const workdir = options.workdir ? resolvePath(options.workdir) : process.cwd()
   const deckPath = options.deck
     ? resolvePath(options.deck)
@@ -99,6 +100,37 @@ export async function addSkill(locator: string, options: { deck?: string; workdi
 
   const targetDir = join(coldPool, parsed.host, parsed.owner, parsed.repo)
 
+  if (dryRun) {
+    const skillName = parsed.skill ? basename(parsed.skill) : parsed.repo
+    const alias = options.alias || skillName
+    const skillType = (options.type || 'tool').toLowerCase()
+    const fqPath = parsed.skill
+      ? `${parsed.host}/${parsed.owner}/${parsed.repo}/${parsed.skill}`
+      : `${parsed.host}/${parsed.owner}/${parsed.repo}`
+
+    console.log(`🔎 Dry-run: deck add ${locator}`)
+    console.log(`   Cold pool:  ${coldPool}`)
+    console.log(`   Deck:       ${deckPath}`)
+    console.log()
+    console.log(`📂 Repo status: ${existsSync(join(targetDir, '.git')) ? 'already cloned' : existsSync(targetDir) ? 'dir exists (partial clone?)' : 'not in cold pool'}`)
+    if (!existsSync(join(targetDir, '.git'))) {
+      console.log(`📦 Would clone: https://${parsed.host}/${parsed.owner}/${parsed.repo}.git --depth 1`)
+    }
+    if (parsed.skill) {
+      const skillMd = join(targetDir, parsed.skill, 'SKILL.md')
+      if (existsSync(targetDir) && existsSync(skillMd)) {
+        console.log(`📄 Skill path:  valid — ${skillMd}`)
+      } else if (existsSync(targetDir)) {
+        console.log(`⚠️  Skill path:  NOT FOUND — check repo layout`)
+      }
+    }
+    console.log(`\n📝 Would add to skill-deck.toml:`)
+    console.log(`   [${skillType}.skills.${alias}]`)
+    console.log(`   path = "${fqPath}"`)
+    console.log(`\n💡 Remove --dry-run to execute.`)
+    return
+  }
+
   if (existsSync(targetDir)) {
     console.error(`❌ Already exists in cold pool: ${targetDir}`)
     console.error(`   To update: rm -rf ${targetDir} and re-run`)

package/src/cli.ts

@@ -23,6 +23,7 @@ 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')
+const dryRun = args.includes('--dry-run')
 
 const HELP_CONFIG = {
   binName: 'lythoskill-deck',
@@ -43,6 +44,7 @@ const HELP_CONFIG = {
 
     { 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: '--dry-run', description: 'Show plan without executing (add, prune)' },
     { flag: '--yes', description: 'Skip interactive confirmation (for prune)' },
   ],
 }
@@ -61,7 +63,7 @@ switch (command) {
       console.error('❌ Missing locator. Usage: deck add <github.com/owner/repo[/skill]>')
       process.exit(1)
     }
-    await addSkill(locator, { deck: deckPath, workdir, alias, type })
+    await addSkill(locator, { deck: deckPath, workdir, alias, type, dryRun })
     break
   }
   case 'refresh': {

package/src/link.ts

@@ -79,13 +79,14 @@ 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
+  // 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 };
     }
+    return { path: null };
   }
 
   // 1. 直接路径
@@ -216,8 +217,32 @@ for (const entry of parsedEntries) {
     continue;
   }
   if (!result.path) {
-    errors.push(`Skill not found: ${entry.path}`);
-    continue;
+    // For localhost skills, create a placeholder so the user can fill it in
+    if (entry.path.startsWith('localhost/')) {
+      const skill = entry.path.slice('localhost/'.length)
+      const localPath = join(COLD_POOL, skill)
+      if (!existsSync(join(localPath, 'SKILL.md'))) {
+        const now = new Date().toISOString().slice(0, 10)
+        const placeholder = [
+          '---', `name: ${skill}`, 'description: TODO — add description', 'type: standard', '---',
+          '', `# ${skill}`,
+          '', '> ⚠️ Placeholder — declared in skill-deck.toml but not yet implemented.',
+          '', '## TODO',
+          '- [ ] Define what this skill does',
+          '- [ ] Add usage instructions',
+          '- [ ] Run `deck link` to activate',
+          '', `Created: ${now}`, '',
+        ].join('\n')
+        mkdirSync(localPath, { recursive: true })
+        writeFileSync(join(localPath, 'SKILL.md'), placeholder)
+        console.log(`📝 Created placeholder: localhost/${skill} → ${localPath}/SKILL.md`)
+        result.path = localPath
+      }
+    }
+    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 });
 }

package/src/prune.test.ts

@@ -6,9 +6,10 @@
  */
 
 import { describe, it, expect, afterEach, spyOn } from 'bun:test'
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync } from 'node:fs'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
+import { formatSize } from './prune.ts'
 
 let cleanup: string[] = []
 
@@ -38,6 +39,18 @@ function placeSkillInRepo(repoDir: string, skillName: string): string {
   return skillDir
 }
 
+describe('formatSize', () => {
+  it('formats bytes correctly at each boundary', () => {
+    expect(formatSize(0)).toBe('0B')
+    expect(formatSize(512)).toBe('512B')
+    expect(formatSize(1023)).toBe('1023B')
+    expect(formatSize(1024)).toBe('1.0KB')
+    expect(formatSize(1536)).toBe('1.5KB')
+    expect(formatSize(1048576)).toBe('1.0MB')
+    expect(formatSize(1073741824)).toBe('1.0GB')
+  })
+})
+
 describe('pruneDeck', () => {
   it('C15: prune with unreferenced repos deletes them when --yes is set', async () => {
     const projectDir = makeTmp()

package/src/prune.ts

@@ -19,7 +19,7 @@ interface PruneCandidate {
   size: number;
 }
 
-function formatSize(bytes: number): string {
+export function formatSize(bytes: number): string {
   if (bytes < 1024) return `${bytes}B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
   if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;

package/src/refresh-plan.test.ts

@@ -1,7 +1,7 @@
 import { describe, test, expect } from 'bun:test'
-import { mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { mkdirSync, rmSync } from 'node:fs'
 import { join } from 'node:path'
-import { resolveRefreshConfig, detectGitRoot, buildRefreshPlan } from './refresh-plan'
+import { resolveRefreshConfig, detectGitRoot, buildRefreshPlan, executeRefreshPlan, type RefreshPlan, type RefreshTarget } from './refresh-plan'
 
 const deckAliasDict = `[deck]
 max_cards = 10
@@ -54,6 +54,15 @@ describe('detectGitRoot', () => {
     expect(result.type).toBe('localhost')
   })
 
+  test('git: directory with .git directly present', () => {
+    const dir = join('/tmp', 'refresh-test-git-' + Date.now())
+    mkdirSync(join(dir, '.git'), { recursive: true })
+    const result = detectGitRoot(dir, '/tmp')
+    expect(result.type).toBe('git')
+    expect(result.gitRoot).toBe(dir)
+    rmSync(dir, { recursive: true, force: true })
+  })
+
   test('not-git: directory without .git', () => {
     const dir = join('/tmp', 'refresh-test-no-git-' + Date.now())
     mkdirSync(dir, { recursive: true })
@@ -105,6 +114,17 @@ describe('buildRefreshPlan', () => {
     expect(localhost!.path).toBe('localhost/skill-b')
   })
 
+  test('derives coldPool from deck toml when not in opts', () => {
+    const plan = buildRefreshPlan(deckAliasDict, { workdir: '/custom/work' })
+    expect(plan.workdir).toBe('/custom/work')
+    expect(plan.coldPool).toBe('/custom/work/cold-pool')
+  })
+
+  test('explicit coldPool in opts overrides deck toml', () => {
+    const plan = buildRefreshPlan(deckAliasDict, { coldPool: '/explicit/pool' })
+    expect(plan.coldPool).toBe('/explicit/pool')
+  })
+
   test('paths are resolved through config', () => {
     const plan = buildRefreshPlan(deckAliasDict, {
       deckPath: '/custom/deck.toml',
@@ -116,3 +136,139 @@ describe('buildRefreshPlan', () => {
     expect(plan.coldPool).toBe('/custom/pool')
   })
 })
+
+// ── executeRefreshPlan (IO-injected plan execution) ────────────────
+
+function makeTarget(overrides: Partial<RefreshTarget> = {}): RefreshTarget {
+  return {
+    alias: 'skill-a',
+    path: 'github.com/owner/repo/skill-a',
+    sourcePath: '/pool/github.com/owner/repo/skill-a',
+    sourceRel: 'github.com/owner/repo/skill-a',
+    type: 'git',
+    gitRoot: '/pool/github.com/owner/repo/skill-a',
+    ...overrides,
+  }
+}
+
+function makePlan(targets: RefreshTarget[]): RefreshPlan {
+  return {
+    deckPath: '/tmp/deck.toml',
+    workdir: '/tmp',
+    coldPool: '/pool',
+    targets,
+    allDeclared: targets.map(t => ({ alias: t.alias, path: t.path, type: 'tool' as const })),
+  }
+}
+
+describe('executeRefreshPlan', () => {
+  test('git up-to-date: reports correctly, does not call linkDeck', () => {
+    const plan = makePlan([makeTarget()])
+    const logs: string[] = []
+    let linkCalled = false
+
+    const results = executeRefreshPlan(plan, {
+      gitPull: () => ({ status: 'up-to-date', message: 'Already up to date.' }),
+      log: (msg) => logs.push(msg),
+      linkDeck: () => { linkCalled = true },
+    })
+
+    expect(results).toHaveLength(1)
+    expect(results[0].status).toBe('up-to-date')
+    expect(logs.some(l => l.includes('Up-to-date: 1'))).toBe(true)
+    expect(linkCalled).toBe(false)
+  })
+
+  test('git updated: triggers linkDeck', () => {
+    const plan = makePlan([makeTarget()])
+    let linkCalled = false
+
+    const results = executeRefreshPlan(plan, {
+      gitPull: () => ({ status: 'updated', message: 'Fast-forward' }),
+      log: () => {},
+      linkDeck: () => { linkCalled = true },
+    })
+
+    expect(results[0].status).toBe('updated')
+    expect(linkCalled).toBe(true)
+  })
+
+  test('git failed: reports failed, does not call linkDeck', () => {
+    const plan = makePlan([makeTarget()])
+    let linkCalled = false
+
+    const results = executeRefreshPlan(plan, {
+      gitPull: () => ({ status: 'failed', message: 'connection refused' }),
+      log: () => {},
+      linkDeck: () => { linkCalled = true },
+    })
+
+    expect(results[0].status).toBe('failed')
+    expect(linkCalled).toBe(false)
+  })
+
+  test('localhost: skipped with user-managed message', () => {
+    const plan = makePlan([makeTarget({ type: 'localhost', gitRoot: undefined })])
+
+    const results = executeRefreshPlan(plan, { log: () => {} })
+
+    expect(results[0].status).toBe('skipped')
+    expect(results[0].message).toContain('localhost')
+    expect(results[0].message).toContain('user-managed')
+  })
+
+  test('not-git: skipped with not-a-git-repository message', () => {
+    const plan = makePlan([makeTarget({ type: 'not-git', gitRoot: undefined })])
+
+    const results = executeRefreshPlan(plan, { log: () => {} })
+
+    expect(results[0].status).toBe('not-git')
+    expect(results[0].message).toContain('not a git repository')
+  })
+
+  test('missing: failed with not-found message', () => {
+    const plan = makePlan([makeTarget({ type: 'missing', gitRoot: undefined, sourcePath: '' })])
+
+    const results = executeRefreshPlan(plan, { log: () => {} })
+
+    expect(results[0].status).toBe('failed')
+    expect(results[0].message).toContain('not found')
+  })
+
+  test('multiple targets: counts each status', () => {
+    const logs: string[] = []
+    const plan = makePlan([
+      makeTarget({ alias: 'up', type: 'git', gitRoot: '/pool/a' }),
+      makeTarget({ alias: 'updated', type: 'git', gitRoot: '/pool/b' }),
+      makeTarget({ alias: 'local', type: 'localhost', gitRoot: undefined }),
+      makeTarget({ alias: 'nogit', type: 'not-git', gitRoot: undefined }),
+    ])
+
+    const results = executeRefreshPlan(plan, {
+      gitPull: (dir) => {
+        if (dir === '/pool/b') return { status: 'updated', message: 'Fast-forward' }
+        return { status: 'up-to-date', message: 'Already up to date.' }
+      },
+      log: (msg) => logs.push(msg),
+    })
+
+    expect(results).toHaveLength(4)
+    expect(logs.some(l => l.includes('Updated: 1') && l.includes('Up-to-date: 1') && l.includes('Skipped: 2'))).toBe(true)
+  })
+
+  test('single target in plan ≠ allDeclared → reports "single skill" scope', () => {
+    const plan = makePlan([makeTarget()])
+    plan.allDeclared = [
+      { alias: 'skill-a', path: 'github.com/owner/repo/skill-a', type: 'tool' },
+      { alias: 'skill-b', path: 'github.com/owner/repo/skill-b', type: 'tool' },
+    ]
+    const logs: string[] = []
+
+    executeRefreshPlan(plan, {
+      gitPull: () => ({ status: 'up-to-date', message: 'ok' }),
+      log: (msg) => logs.push(msg),
+    })
+
+    expect(logs.some(l => l.includes('single skill'))).toBe(true)
+  })
+})

package/src/refresh.test.ts

@@ -2,265 +2,22 @@
 /**
  * refresh.test.ts — unit tests for refresh.ts helpers
  *
- * Run: bun test packages/lythoskill-deck/src/refresh.test.ts
+ * Actual IO tests (git pull, linkDeck, refreshDeck end-to-end) belong in
+ * e2e/integration tests run manually. This file tests thin wrappers only.
  */
 
-import { describe, it, expect, afterEach, spyOn } from 'bun:test'
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, realpathSync, existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { tmpdir } from 'node:os'
-import { execSync } from 'node:child_process'
-import * as childProcess from 'node:child_process'
+import { describe, it, expect } from 'bun:test'
 
 import { findGitRoot } from './refresh.ts'
 
-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-refresh-'))
-  cleanup.push(dir)
-  return dir
-}
-
 describe('findGitRoot', () => {
-  it('returns the directory itself when .git is directly present', () => {
-    const dir = makeTmp()
-    execSync('git init', { cwd: dir, stdio: 'ignore' })
-    const root = findGitRoot(dir, dir)
-    expect(root).not.toBeNull()
-    expect(realpathSync(root!)).toBe(realpathSync(dir))
-  })
-
-  it('finds git root in parent directory for monorepo layout', () => {
-    const repoDir = makeTmp()
-    const skillDir = join(repoDir, 'skills', 'my-skill')
-    mkdirSync(skillDir, { recursive: true })
-    execSync('git init', { cwd: repoDir, stdio: 'ignore' })
-    const root = findGitRoot(skillDir, repoDir)
-    expect(root).not.toBeNull()
-    expect(realpathSync(root!)).toBe(realpathSync(repoDir))
-  })
-
-  it('returns null for a non-git directory', () => {
-    const dir = makeTmp()
-    expect(findGitRoot(dir, dir)).toBeNull()
-  })
-})
-
-function initGitRepo(dir: string) {
-  execSync('git init', { cwd: dir, stdio: 'ignore' })
-  execSync('git config user.email "test@test.com"', { cwd: dir, stdio: 'ignore' })
-  execSync('git config user.name "Test"', { cwd: dir, stdio: 'ignore' })
-  execSync('git commit --allow-empty -m "init"', { cwd: dir, stdio: 'ignore' })
-}
-
-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
-}
-
-function mockGitPull(status: 'up-to-date' | 'updated') {
-  const originalExecSync = childProcess.execSync
-  execSpy = spyOn(childProcess, 'execSync').mockImplementation(((cmd: string, options?: any) => {
-    if (cmd === 'git pull') {
-      return status === 'up-to-date'
-        ? 'Already up to date.\n'
-        : 'Updating abc123..def456\nFast-forward\n README.md | 1 +\n'
-    }
-    return originalExecSync(cmd, options)
-  }) as any)
-}
-
-describe('refreshDeck', () => {
-  it('C12: refresh all skills reports status for each cold pool repo', async () => {
-    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')
-    initGitRepo(skillADir)
-    initGitRepo(skillBDir)
-
-    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\n[tool.skills.skill-b]\npath = "github.com/owner/repo/skill-b"\n`
-    const deckPath = join(projectDir, 'skill-deck.toml')
-    writeFileSync(deckPath, deckContent)
-
-    mockGitPull('up-to-date')
-
-    const logs: string[] = []
-    const logSpy = spyOn(console, 'log').mockImplementation((msg: string) => {
-      logs.push(String(msg))
-    })
-
-    const { refreshDeck } = await import('./refresh.ts')
-    refreshDeck(deckPath, projectDir)
-
-    logSpy.mockRestore()
-
-    expect(logs.some(l => l.includes('skill-a'))).toBe(true)
-    expect(logs.some(l => l.includes('skill-b'))).toBe(true)
-    expect(logs.some(l => l.includes('Up-to-date: 2'))).toBe(true)
-  })
-
-  it('C13: refresh single skill by alias only processes the target', async () => {
-    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')
-    initGitRepo(skillADir)
-    initGitRepo(skillBDir)
-
-    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\n[tool.skills.skill-b]\npath = "github.com/owner/repo/skill-b"\n`
-    const deckPath = join(projectDir, 'skill-deck.toml')
-    writeFileSync(deckPath, deckContent)
-
-    mockGitPull('up-to-date')
-
-    const logs: string[] = []
-    const logSpy = spyOn(console, 'log').mockImplementation((msg: string) => {
-      logs.push(String(msg))
-    })
-
-    const { refreshDeck } = await import('./refresh.ts')
-    refreshDeck(deckPath, projectDir, 'skill-a')
-
-    logSpy.mockRestore()
-
-    expect(logs.some(l => l.includes('skill-a'))).toBe(true)
-    expect(logs.some(l => l.includes('skill-b'))).toBe(false)
-    expect(logs.some(l => l.includes('single skill'))).toBe(true)
-  })
-
-  it('C14: refresh with updated skills triggers linkDeck', async () => {
-    const projectDir = makeTmp()
-    const coldPoolRel = 'cold-pool'
-    const coldPool = join(projectDir, coldPoolRel)
-
-    const skillADir = placeSkill(coldPool, 'github.com/owner/repo/skill-a')
-    initGitRepo(skillADir)
-
-    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)
-
-    mockGitPull('updated')
-
-    const logs: string[] = []
-    const logSpy = spyOn(console, 'log').mockImplementation((msg: string) => {
-      logs.push(String(msg))
-    })
-
-    const { refreshDeck } = await import('./refresh.ts')
-    refreshDeck(deckPath, projectDir)
-
-    logSpy.mockRestore()
-
-    expect(logs.some(l => l.includes('Running deck link'))).toBe(true)
-    expect(logs.some(l => l.includes('Updated: 1'))).toBe(true)
-  })
-
-  it('C15: refresh skips localhost skills', async () => {
-    const projectDir = makeTmp()
-    const coldPoolRel = 'cold-pool'
-    const coldPool = join(projectDir, coldPoolRel)
-
-    const skillDir = placeSkill(coldPool, 'localhost/my-skill')
-    initGitRepo(skillDir)
-
-    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.local]\npath = "localhost/my-skill"\n`
-    const deckPath = join(projectDir, 'skill-deck.toml')
-    writeFileSync(deckPath, deckContent)
-
-    mockGitPull('up-to-date')
-
-    const logs: string[] = []
-    const logSpy = spyOn(console, 'log').mockImplementation((msg: string) => {
-      logs.push(String(msg))
-    })
-
-    const { refreshDeck } = await import('./refresh.ts')
-    refreshDeck(deckPath, projectDir)
-
-    logSpy.mockRestore()
-
-    expect(logs.some(l => l.includes('local'))).toBe(true)
-    expect(logs.some(l => l.includes('Skipped: 1'))).toBe(true)
-  })
-
-  it('C16: refresh reports not-git for non-git directories', async () => {
-    const projectDir = makeTmp()
-    const coldPoolRel = 'cold-pool'
-    const coldPool = join(projectDir, coldPoolRel)
-
-    placeSkill(coldPool, 'github.com/owner/repo/skill-a')
-    // NO git init
-
-    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)
-
-    const logs: string[] = []
-    const logSpy = spyOn(console, 'log').mockImplementation((msg: string) => {
-      logs.push(String(msg))
-    })
-
-    const { refreshDeck } = await import('./refresh.ts')
-    refreshDeck(deckPath, projectDir)
-
-    logSpy.mockRestore()
-
-    expect(logs.some(l => l.includes('not a git repository'))).toBe(true)
-  })
-
-  it('C17: refresh target not found exits with error', async () => {
-    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\n[tool.skills.skill-a]\npath = "github.com/owner/repo/skill-a"\n`
-    const deckPath = join(projectDir, 'skill-deck.toml')
-    writeFileSync(deckPath, deckContent)
-
-    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 { refreshDeck } = await import('./refresh.ts')
-      refreshDeck(deckPath, projectDir, 'nonexistent')
-      expect(false).toBe(true)
-    } catch (err: any) {
-      expect(exitCode).toBe(1)
-      expect(errors.some(e => e.includes('not found'))).toBe(true)
-    } finally {
-      process.exit = originalExit
-      errorSpy.mockRestore()
-    }
+  it('wraps detectGitRoot → returns gitRoot or null', () => {
+    // Thin wrapper: delegates to detectGitRoot(dir, coldPool) and returns gitRoot ?? null.
+    // detectGitRoot is tested in refresh-plan.test.ts with IO injection.
+    // This test verifies the signature and null-coalescing.
+    // null means detectGitRoot returned something without gitRoot (not-git, localhost, missing).
+    // string means detectGitRoot found a git root.
+    const result = findGitRoot('/nonexistent/path', '/pool')
+    expect(typeof result === 'string' || result === null).toBe(true)
   })
 })