@lythos/skill-deck 0.9.36 → 0.9.37

package/README.md

@@ -9,7 +9,7 @@
 This package exposes a **CLI**. Invoke via:
 
 ```bash
-bunx @lythos/skill-deck@0.9.36 <command> [options]
+bunx @lythos/skill-deck@0.9.37 <command> [options]
 ```
 
 No installation required. `bunx` auto-downloads the package.
@@ -55,17 +55,17 @@ prompt = "Search for latest info, then generate professional document with diagr
 
 | Situation | Command |
 |-----------|---------|
-| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.36 link` |
-| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.36 validate` |
-| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.36 add owner/repo` |
-| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.36 refresh` |
-| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.36 refresh tdd` |
-| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.36 remove tdd` |
-| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.36 prune` |
-| Switch skill from snapshot to sync mode | `bunx @lythos/skill-deck@0.9.36 sync tdd` |
-| Switch skill from sync to snapshot mode | `bunx @lythos/skill-deck@0.9.36 freeze tdd` |
-| Check cold pool for drift vs lock file | `bunx @lythos/skill-deck@0.9.36 reconcile` |
-| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.36 link --deck ./my-deck.toml --workdir /path/to/project` |
+| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.37 link` |
+| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.37 validate` |
+| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.37 add owner/repo` |
+| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.37 refresh` |
+| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.37 refresh tdd` |
+| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.37 remove tdd` |
+| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.37 prune` |
+| Switch skill from snapshot to sync mode | `bunx @lythos/skill-deck@0.9.37 sync tdd` |
+| Switch skill from sync to snapshot mode | `bunx @lythos/skill-deck@0.9.37 freeze tdd` |
+| Check cold pool for drift vs lock file | `bunx @lythos/skill-deck@0.9.37 reconcile` |
+| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.37 link --deck ./my-deck.toml --workdir /path/to/project` |
 
 ### Commands
 
@@ -128,7 +128,7 @@ path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/
-bunx @lythos/skill-deck@0.9.36 link
+bunx @lythos/skill-deck@0.9.37 link
 ```
 
 ### Key Concepts
@@ -153,11 +153,68 @@ Different agents look for skills in different directories. `skill-deck.toml` con
 
 > **If you are an agent**: verify where your platform scans for skills, then set `working_set` to that path before running `deck link`.
 
+### For OpenClaw
+
+OpenClaw loads skills from multiple locations, in priority order:
+
+| Priority | Location | Use case |
+|----------|----------|----------|
+| 1 | `<workspace>/skills` | Workspace-level override |
+| 2 | `<workspace>/.agents/skills` | **Project deck (recommended)** |
+| 3 | `~/.agents/skills` | Personal agent skills |
+| 4 | `~/.openclaw/skills` | Global managed skills |
+
+**Per-project deck** (most common):
+```toml
+[deck]
+working_set = ".agents/skills"
+```
+This matches OpenClaw's "project agent skills" path. Run `deck link` from your project root.
+
+**Global deck** (manage all OpenClaw skills centrally):
+```toml
+[deck]
+working_set = "~/.openclaw/skills"
+```
+Create this in your home directory. One global deck can syndicate to all projects via OpenClaw's fallback chain.
+
+### For Hermes
+
+Hermes keeps skills in `~/.hermes/skills/` and supports scanning additional directories via `external_dirs` in `~/.hermes/config.yaml`. This makes Hermes + deck integration clean: deck manages the working set, Hermes reads it through `external_dirs`.
+
+**Recommended: project-level deck + external_dirs**
+
+```toml
+# skill-deck.toml
+[deck]
+working_set = ".hermes/skills"
+```
+
+```yaml
+# ~/.hermes/config.yaml
+skills:
+  external_dirs:
+    - /absolute/path/to/your/project/.hermes/skills
+```
+
+Run `deck link` from your project root. Hermes picks up the syndicated skills without touching its primary `~/.hermes/skills/` directory.
+
+**Alternative: direct mode (not recommended)**
+
+You can point deck directly at `~/.hermes/skills`:
+
+```toml
+[deck]
+working_set = "~/.hermes/skills"
+```
+
+Caution: deck's deny-by-default will remove any skills not declared in your deck, including Hermes' bundled skills. Only use this if your deck explicitly declares every skill you want Hermes to see.
+
 ### Troubleshooting
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| `❌ Skill not found: <name>` | Skill declared in deck but not in cold pool | `bunx @lythos/skill-deck@0.9.36 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.37 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.36",
+  "version": "0.9.37",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
   "keywords": [
     "ai-agent",

package/src/add.ts

@@ -249,10 +249,11 @@ export async function addSkill(
       '# Skill Deck — generated by lythoskill-deck',
       '# Edit working_set for your agent platform (uncomment one):',
       '#   working_set = ".claude/skills"   # Claude Code (also read by Cursor, Copilot)',
-      '#   working_set = ".agents/skills"   # Codex CLI, OpenClaw',
+      '#   working_set = ".agents/skills"   # Codex CLI, OpenClaw (project-level)',
       '#   working_set = ".cursor/skills"   # Cursor-native',
       '#   working_set = ".github/skills"   # GitHub Copilot',
       '#   working_set = ".windsurf/skills" # Windsurf',
+      '# For OpenClaw global skills: working_set = "~/.openclaw/skills" (global deck)',
       '# After editing, run:  bunx @lythos/skill-deck@latest link',
       '',
     ].join('\n')

package/src/cli.ts

@@ -61,7 +61,7 @@ const HELP_CONFIG = {
     { name: 'prune', description: 'GC cold pool repos no longer referenced by any deck', args: '[--yes]' },
     { name: 'sync', description: 'Switch skill from snapshot (cp) to sync (symlink)', args: '<alias>' },
     { name: 'freeze', description: 'Switch skill from sync (symlink) to snapshot (cp), pinning current HEAD', args: '<alias>' },
-    { name: 'reconcile', description: 'Compare lock file (desired) vs cold pool (actual), report drift', args: '[--apply]' },
+    { name: 'reconcile', description: 'Compare lock file vs cold pool, report drift', args: '[--apply] [--yes]' },
     { name: 'migrate-schema', description: 'Convert string-array deck.toml to alias-as-key dict', args: '[--dry-run]' },
   ],
   options: [
@@ -141,7 +141,7 @@ switch (command) {
   }
   case 'reconcile': {
     const apply = args.includes('--apply')
-    reconcileDeck(deckPath, workdir, apply)
+    await reconcileDeck(deckPath, workdir, apply, yes)
     break
   }
   case 'prune': {

package/src/reconcile.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
+import { mkdtempSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { reconcileDeck } from './reconcile.js'
+
+describe('reconcileDeck', () => {
+  let projectDir: string
+  let coldPoolDir: string
+
+  beforeEach(() => {
+    projectDir = mkdtempSync(join(tmpdir(), 'deck-reconcile-'))
+    coldPoolDir = join(projectDir, 'cold-pool')
+    mkdirSync(coldPoolDir, { recursive: true })
+  })
+
+  afterEach(() => {
+    // Cleanup handled by OS temp dir lifecycle
+  })
+
+  function writeLock(skills: any[]) {
+    const lock = {
+      version: '1.0.0' as const,
+      generated_at: new Date().toISOString(),
+      deck_source: { path: join(projectDir, 'skill-deck.toml'), content_hash: 'abc' },
+      working_set: '.claude/skills',
+      cold_pool: coldPoolDir,
+      skills,
+      constraints: {
+        total_cards: skills.length,
+        max_cards: 10,
+        within_budget: skills.length <= 10,
+        transient_warnings: [],
+        dir_overlaps: [],
+      },
+    }
+    writeFileSync(join(projectDir, 'skill-deck.lock'), JSON.stringify(lock, null, 2))
+  }
+
+  function writeDeck() {
+    writeFileSync(
+      join(projectDir, 'skill-deck.toml'),
+      `[deck]\ncold_pool = "${coldPoolDir}"\nworking_set = ".claude/skills"\n\n[tool.skills.test]\npath = "github.com/owner/repo/test"\n`
+    )
+  }
+
+  it('reports no drift when lock matches cold pool', async () => {
+    writeDeck()
+    writeLock([
+      {
+        name: 'test',
+        alias: 'test',
+        deck_niche: 'test',
+        type: 'tool',
+        source: 'github.com/owner/repo/test',
+        dest: join(projectDir, '.claude/skills/test'),
+        mode: 'symlink',
+        linked_at: new Date().toISOString(),
+        deck_managed_dirs: [],
+      },
+    ])
+
+    // No cold pool repo = missing, but that's fine for this test
+    // We just verify it doesn't crash
+    await reconcileDeck(join(projectDir, 'skill-deck.toml'), projectDir, false)
+  })
+
+  it('shows plan-only mode by default', async () => {
+    writeDeck()
+    writeLock([])
+
+    await reconcileDeck(join(projectDir, 'skill-deck.toml'), projectDir, false)
+  })
+
+  it('--apply requires --yes or TTY confirmation', async () => {
+    writeDeck()
+    writeLock([])
+
+    // With --yes, apply proceeds even without TTY
+    await reconcileDeck(join(projectDir, 'skill-deck.toml'), projectDir, true, true)
+  })
+})

package/src/reconcile.ts

@@ -11,10 +11,34 @@ import { existsSync, readFileSync } from 'node:fs'
 import { resolve, dirname, join } from 'node:path'
 import { findDeckToml, expandHome } from './link.js'
 import { parse as parseToml } from '@iarna/toml'
-import { ColdPool, buildReconcilePlan, type ReconcileDesiredState } from '@lythos/cold-pool'
+import { ColdPool, buildReconcilePlan, type ReconcileDesiredState, getRepoHeadRef } from '@lythos/cold-pool'
 import { SkillDeckLockSchema } from './schema.js'
+import { addSkill } from './add.js'
+import { refreshDeck } from './refresh.js'
+import { pruneDeck } from './prune.js'
 
-export function reconcileDeck(cliDeckPath?: string, cliWorkdir?: string, apply?: boolean): void {
+function isTTY(): boolean {
+  return process.stdin.isTTY && process.stdout.isTTY
+}
+
+async function promptYesNo(question: string): Promise<boolean> {
+  if (!isTTY()) return false
+  const { createInterface } = await import('node:readline')
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  return new Promise((resolve) => {
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close()
+      resolve(answer.trim().toLowerCase() === 'y')
+    })
+  })
+}
+
+export async function reconcileDeck(
+  cliDeckPath?: string,
+  cliWorkdir?: string,
+  apply?: boolean,
+  yes?: boolean,
+): Promise<void> {
   const cliDeck = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === '--deck')
   const DECK_PATH = cliDeck
     ? resolve(cliDeck)
@@ -52,11 +76,17 @@ export function reconcileDeck(cliDeckPath?: string, cliWorkdir?: string, apply?:
   const coldPoolRaw = lockData.cold_pool || '~/.agents/skill-repos'
   const COLD_POOL = expandHome(coldPoolRaw, PROJECT_DIR)
 
+  // Build alias → skill info map for locating missing skills
+  const skillByAlias = new Map<string, { source: string; type: string; mode: string }>()
+  for (const s of lockData.skills) {
+    skillByAlias.set(s.alias, { source: s.source, type: s.type, mode: s.mode })
+  }
+
   // Build desired state from lock
   const desired: ReconcileDesiredState = {
     deckPath: DECK_PATH,
-    skills: lockData.skills.map(s => ({
-      locator: s.source, // source is relative to cold pool, in FQ format
+    skills: lockData.skills.map((s) => ({
+      locator: s.source,
       alias: s.alias,
     })),
   }
@@ -99,16 +129,110 @@ export function reconcileDeck(cliDeckPath?: string, cliWorkdir?: string, apply?:
     console.log(`      Reason: ${entry.reason}`)
   }
 
-  if (apply) {
-    console.log(`\n🏗️  --apply: convergence not yet implemented.`)
-    console.log(`   For missing: use 'deck add <locator>'`)
-    console.log(`   For behind: use 'deck refresh'`)
-    console.log(`   For extra: use 'cold-pool prune'`)
-  } else {
+  if (!apply) {
     console.log(`\n💡 Plan-first. Use --apply to converge, or handle individually:`)
     console.log(`   deck add <locator>   → restore missing`)
     console.log(`   deck refresh         → update behind`)
     console.log(`   cold-pool prune      → GC extras`)
+    pool.metadata.close()
+    return
+  }
+
+  // ── Apply convergence ────────────────────────────────────────────────
+
+  // Confirmation
+  if (!yes) {
+    const confirmed = await promptYesNo('\nApply these changes?')
+    if (!confirmed) {
+      console.log('❌ Aborted. No changes made.')
+      pool.metadata.close()
+      return
+    }
+  }
+
+  console.log(`\n🏗️  Applying convergence...`)
+
+  const failures: string[] = []
+
+  // 1. Missing → deck add
+  for (const entry of plan.missing) {
+    for (const alias of entry.aliases) {
+      const info = skillByAlias.get(alias)
+      if (!info) {
+        failures.push(`Missing skill info for alias: ${alias}`)
+        continue
+      }
+      try {
+        console.log(`   ➕ Adding ${alias}...`)
+        await addSkill(info.source, {
+          deck: DECK_PATH,
+          workdir: PROJECT_DIR,
+          alias,
+          type: info.type,
+          mode: info.mode as 'symlink' | 'snapshot',
+        })
+        console.log(`   ✅ Added ${alias}`)
+      } catch (e: any) {
+        failures.push(`Add ${alias}: ${e.message}`)
+        console.error(`   ❌ Failed to add ${alias}: ${e.message}`)
+      }
+    }
+  }
+
+  // 2. Behind → check actual HEAD vs recorded, then refresh if different
+  for (const entry of plan.behind) {
+    try {
+      const recordedRef = pool.metadata.getRepoRef(entry.host, entry.owner, entry.repo)
+      if (!recordedRef) {
+        console.log(`   ⏭️  Skipping ${entry.host}/${entry.owner}/${entry.repo} — no recorded HEAD`)
+        continue
+      }
+      const currentRef = await getRepoHeadRef(entry.repoPath)
+      if (currentRef === recordedRef) {
+        console.log(`   ✅ ${entry.host}/${entry.owner}/${entry.repo} is up to date (${currentRef.slice(0, 8)})`)
+        continue
+      }
+      console.log(`   🔄 Refreshing ${entry.host}/${entry.owner}/${entry.repo} (${recordedRef.slice(0, 8)} → ${currentRef.slice(0, 8)})...`)
+      // Refresh all aliases for this repo
+      for (const alias of entry.aliases) {
+        try {
+          refreshDeck(DECK_PATH, PROJECT_DIR, alias)
+          console.log(`   ✅ Refreshed ${alias}`)
+        } catch (e: any) {
+          failures.push(`Refresh ${alias}: ${e.message}`)
+          console.error(`   ❌ Failed to refresh ${alias}: ${e.message}`)
+        }
+      }
+    } catch (e: any) {
+      failures.push(`Behind ${entry.host}/${entry.owner}/${entry.repo}: ${e.message}`)
+      console.error(`   ❌ Failed to check/refresh ${entry.host}/${entry.owner}/${entry.repo}: ${e.message}`)
+    }
+  }
+
+  // 3. Extra → prune (global, only once)
+  if (plan.extra.length > 0) {
+    try {
+      console.log(`   🗑️  Pruning extras...`)
+      await pruneDeck(DECK_PATH, PROJECT_DIR, true)
+      console.log(`   ✅ Prune complete`)
+    } catch (e: any) {
+      failures.push(`Prune: ${e.message}`)
+      console.error(`   ❌ Prune failed: ${e.message}`)
+    }
+  }
+
+  // Summary
+  console.log(`\n📋 Convergence summary:`)
+  console.log(`   Missing resolved: ${plan.missing.length}`)
+  console.log(`   Behind resolved:  ${plan.behind.length}`)
+  console.log(`   Extra resolved:   ${plan.extra.length}`)
+  if (failures.length > 0) {
+    console.log(`   ❌ Failures: ${failures.length}`)
+    for (const f of failures) {
+      console.log(`      - ${f}`)
+    }
+  } else {
+    console.log(`   ✅ All operations successful`)
   }
 
   pool.metadata.close()