@lythos/skill-deck 0.9.25 → 0.9.27

package/README.md

@@ -9,7 +9,7 @@
 This package exposes a **CLI**. Invoke via:
 
 ```bash
-bunx @lythos/skill-deck@0.9.25 <command> [options]
+bunx @lythos/skill-deck@0.9.27 <command> [options]
 ```
 
 No installation required. `bunx` auto-downloads the package.
@@ -55,14 +55,14 @@ 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.25 link` |
-| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.25 validate` |
-| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.25 add owner/repo` |
-| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.25 refresh` |
-| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.25 refresh tdd` |
-| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.25 remove tdd` |
-| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.25 prune` |
-| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.25 link --deck ./my-deck.toml --workdir /path/to/project` |
+| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.27 link` |
+| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.27 validate` |
+| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.27 add owner/repo` |
+| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.27 refresh` |
+| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.27 refresh tdd` |
+| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.27 remove tdd` |
+| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.27 prune` |
+| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.27 link --deck ./my-deck.toml --workdir /path/to/project` |
 
 ### Commands
 
@@ -119,7 +119,7 @@ path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/
-bunx @lythos/skill-deck@0.9.25 link
+bunx @lythos/skill-deck@0.9.27 link
 ```
 
 ### Key Concepts
@@ -148,7 +148,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.25 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.27 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.25",
+  "version": "0.9.27",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
   "keywords": [
     "ai-agent",

package/src/add.ts

@@ -24,6 +24,8 @@ import {
   executeFetchPlan,
   parseLocator,
   formatLocator,
+  getRepoHeadRef,
+  hashSkillMd,
   type Locator,
 } from '@lythos/cold-pool'
 import { findDeckToml, expandHome } from './link.js'
@@ -148,12 +150,6 @@ export async function addSkill(
     return
   }
 
-  if (fetchPlan.alreadyExists) {
-    console.error(`❌ Already exists in cold pool: ${fetchPlan.targetDir}`)
-    console.error(`   To update: rm -rf ${fetchPlan.targetDir} and re-run`)
-    process.exit(1)
-  }
-
   if (!existsSync(coldPoolPath)) {
     console.log(`📁 Creating cold pool: ${coldPoolPath}`)
     mkdirSync(coldPoolPath, { recursive: true })
@@ -161,6 +157,13 @@ export async function addSkill(
   // git clone needs the parent of the target dir (e.g. host/owner/) to exist
   mkdirSync(dirname(fetchPlan.targetDir), { recursive: true })
 
+  // Note: if cold pool already has the repo (fetchPlan.alreadyExists),
+  // executeFetchPlan returns status: 'already-present' and skips clone.
+  // We still want to write deck.toml + link this skill — critical for
+  // monorepo case (second `deck add` from same repo, e.g. anthropics/skills/pdf
+  // then anthropics/skills/docx). Used to early-exit here, which broke
+  // the monorepo workflow and triggered post-compaction agent CPTSD
+  // (see: 2026-05-07 morning skill-deck.toml overwrite incident).
   const fetchResult = executeFetchPlan(fetchPlan, {
     log: (msg) => console.log(msg),
   })
@@ -171,6 +174,13 @@ export async function addSkill(
     process.exit(1)
   }
 
+  if (fetchResult.status === 'already-present') {
+    console.log(`✓ Repo already in cold pool — skipped clone.`)
+    console.log(`   To check for upstream updates without pulling:`)
+    console.log(`     bunx @lythos/skill-deck refresh ${parsed.host}/${parsed.owner}/${parsed.repo}`)
+    console.log(`   (per ADR-20260507110332805, refresh defaults to discover-only)`)
+  }
+
   const skillDir = findSkillDir(fetchPlan.targetDir, parsed.skill)
   if (!skillDir) {
     console.error(`❌ No SKILL.md found in downloaded repo`)
@@ -244,4 +254,18 @@ export async function addSkill(
   console.log('🔗 Running deck link...')
   const { linkDeck } = await import('./link.js')
   linkDeck(deckPath, workdir)
+
+  // ── Metadata recording (content-level only; deck refs reconciled by link) ─
+
+  try {
+    const headRef = await getRepoHeadRef(fetchPlan.targetDir)
+    const skillSubpath = parsed.skill || ''
+    const skillMdPath = join(skillDir, 'SKILL.md')
+    const contentSha256 = hashSkillMd(skillMdPath)
+
+    pool.metadata.recordRepoRef(parsed.host, parsed.owner, parsed.repo, headRef)
+    pool.metadata.recordSkillHash(parsed.host, parsed.owner, parsed.repo, skillSubpath, contentSha256, null, headRef)
+  } catch (e: any) {
+    console.warn(`⚠️  Metadata recording skipped: ${e.message}`)
+  }
 }

package/src/link.test.ts

@@ -263,68 +263,4 @@ describe('linkDeck reconciler', () => {
     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

@@ -525,6 +525,18 @@ if (!parsed.success) {
 const LOCK_PATH = resolve(PROJECT_DIR, "skill-deck.lock");
 writeFileSync(LOCK_PATH, JSON.stringify(parsed.data, null, 2) + "\n");
 
+// ── Metadata reconcile ──────────────────────────────────────
+
+try {
+  const pool = new ColdPool(COLD_POOL);
+  const declaredSkills = parsedEntries
+    .filter(e => e.type !== 'transient')
+    .map(e => ({ locator: e.path, alias: e.alias }));
+  pool.metadata.reconcileDeckReferences(DECK_PATH, declaredSkills);
+} catch (e: any) {
+  console.warn(`⚠️  Metadata reconcile skipped: ${e.message}`);
+}
+
 // ── 报告 ────────────────────────────────────────────────────
 
 console.log("");

package/src/remove.ts

@@ -11,6 +11,9 @@ import { existsSync, readFileSync, writeFileSync, rmSync } from "node:fs";
 import { resolve, dirname, join } from "node:path";
 import { findDeckToml, expandHome } from "./link.js";
 import { parseDeck } from "./parse-deck.js";
+import { ColdPool } from "@lythos/cold-pool";
+import { homedir } from "node:os";
+import { join } from "node:path";
 
 export function removeSkill(target: string, cliDeckPath?: string, cliWorkdir?: string): void {
   const cliDeck = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
@@ -87,5 +90,19 @@ export function removeSkill(target: string, cliDeckPath?: string, cliWorkdir?: s
     console.log(`  ⚠️  Symlink not found: ${symlinkPath}`);
   }
 
+  // ── Metadata cleanup ────────────────────────────────────────
+
+  try {
+    const deck = parseToml(deckRaw) as any;
+    const coldPoolRaw = deck.deck?.cold_pool || '~/.agents/skill-repos';
+    const coldPoolPath = coldPoolRaw.startsWith('~/')
+      ? join(homedir(), coldPoolRaw.slice(2))
+      : resolve(PROJECT_DIR, coldPoolRaw);
+    const pool = new ColdPool(coldPoolPath);
+    pool.metadata.removeReference(match.path, DECK_PATH);
+  } catch (e: any) {
+    console.warn(`⚠️  Metadata cleanup skipped: ${e.message}`);
+  }
+
   console.log(`\n💡 Cold pool untouched. Run 'bunx @lythos/skill-deck prune' to GC unreferenced repos.`);
 }

package/src/validate.test.ts

@@ -9,7 +9,7 @@ import { describe, it, expect, afterEach } from 'bun:test'
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
-import { spawnSync } from 'node:child_process'
+import { buildDeckValidation } from './validate.ts'
 
 let cleanup: string[] = []
 
@@ -33,44 +33,20 @@ function placeSkill(coldPool: string, relPath: string): string {
   return skillDir
 }
 
-function runValidate(deckPath: string, workdir: string) {
-  return spawnSync('bun', [join(import.meta.dir, 'cli.ts'), 'validate', '--deck', deckPath, '--workdir', workdir], {
-    cwd: workdir,
-    encoding: 'utf-8',
-  })
-}
-
 describe('validateDeck', () => {
-  it('C1: valid deck passes validation', () => {
-    const projectDir = makeTmp()
-    const coldPoolRel = 'cold-pool'
-    const coldPool = join(projectDir, coldPoolRel)
-
-    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)
-
-    const result = runValidate(deckPath, projectDir)
-
-    expect(result.status).toBe(0)
-    expect(result.stdout).toContain('Validation passed')
-  })
-
-  it('C2: missing [deck] section errors', () => {
+  it('C2: missing [deck] section errors', async () => {
     const projectDir = makeTmp()
     const deckContent = `[tool.skills.foo]\npath = "github.com/owner/repo/skill"\n`
     const deckPath = join(projectDir, 'skill-deck.toml')
     writeFileSync(deckPath, deckContent)
 
-    const result = runValidate(deckPath, projectDir)
+    const report = await buildDeckValidation(deckPath, projectDir)
 
-    expect(result.status).toBe(1)
-    expect(result.stderr).toContain('[deck] section is required')
+    expect(report.status).toBe('invalid')
+    expect(report.errors.some(e => e.includes('[deck] section is required'))).toBe(true)
   })
 
-  it('C3: invalid max_cards errors', () => {
+  it('C3: invalid max_cards errors', async () => {
     const projectDir = makeTmp()
     const coldPoolRel = 'cold-pool'
     const coldPool = join(projectDir, coldPoolRel)
@@ -80,13 +56,13 @@ describe('validateDeck', () => {
     const deckPath = join(projectDir, 'skill-deck.toml')
     writeFileSync(deckPath, deckContent)
 
-    const result = runValidate(deckPath, projectDir)
+    const report = await buildDeckValidation(deckPath, projectDir)
 
-    expect(result.status).toBe(1)
-    expect(result.stderr).toContain('deck.max_cards must be a positive integer')
+    expect(report.status).toBe('invalid')
+    expect(report.errors.some(e => e.includes('deck.max_cards must be a positive integer'))).toBe(true)
   })
 
-  it('C4: skill not found in cold pool errors', () => {
+  it('C4: skill not found in cold pool errors', async () => {
     const projectDir = makeTmp()
     const coldPoolRel = 'cold-pool'
     const coldPool = join(projectDir, coldPoolRel)
@@ -97,13 +73,13 @@ describe('validateDeck', () => {
     const deckPath = join(projectDir, 'skill-deck.toml')
     writeFileSync(deckPath, deckContent)
 
-    const result = runValidate(deckPath, projectDir)
+    const report = await buildDeckValidation(deckPath, projectDir)
 
-    expect(result.status).toBe(1)
-    expect(result.stderr).toContain('Skill not found')
+    expect(report.status).toBe('invalid')
+    expect(report.errors.some(e => e.includes('Skill not found'))).toBe(true)
   })
 
-  it('C5: budget exceeded errors', () => {
+  it('C5: budget exceeded errors', async () => {
     const projectDir = makeTmp()
     const coldPoolRel = 'cold-pool'
     const coldPool = join(projectDir, coldPoolRel)
@@ -114,47 +90,31 @@ describe('validateDeck', () => {
     const deckPath = join(projectDir, 'skill-deck.toml')
     writeFileSync(deckPath, deckContent)
 
-    const result = runValidate(deckPath, projectDir)
+    const report = await buildDeckValidation(deckPath, projectDir)
 
-    expect(result.status).toBe(1)
-    expect(result.stderr).toContain('Budget exceeded')
+    expect(report.status).toBe('invalid')
+    expect(report.errors.some(e => e.includes('Budget exceeded'))).toBe(true)
   })
 
-  it('C6: toml parse error exits', () => {
+  it('C6: toml parse error exits', async () => {
     const projectDir = makeTmp()
     const deckPath = join(projectDir, 'skill-deck.toml')
     writeFileSync(deckPath, '[invalid toml\n')
 
-    const result = runValidate(deckPath, projectDir)
-
-    expect(result.status).toBe(1)
-    expect(result.stderr).toContain('TOML parse error')
-  })
-
-  it('C7: deprecated string-array format warns', () => {
-    const projectDir = makeTmp()
-    const coldPoolRel = 'cold-pool'
-    const coldPool = join(projectDir, coldPoolRel)
-    placeSkill(coldPool, 'github.com/owner/repo/skill')
-
-    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool]\nskills = ["github.com/owner/repo/skill"]\n`
-    const deckPath = join(projectDir, 'skill-deck.toml')
-    writeFileSync(deckPath, deckContent)
-
-    const result = runValidate(deckPath, projectDir)
+    const report = await buildDeckValidation(deckPath, projectDir)
 
-    expect(result.status).toBe(0)
-    expect(result.stderr).toContain('deprecated')
+    expect(report.status).toBe('invalid')
+    expect(report.errors.some(e => e.includes('TOML parse error'))).toBe(true)
   })
 
-  it('C8: invalid transient expires errors', () => {
+  it('C8: invalid transient expires errors', async () => {
     const projectDir = makeTmp()
     const deckPath = join(projectDir, 'skill-deck.toml')
     writeFileSync(deckPath, `[deck]\nmax_cards = 10\n\n[transient.foo]\npath = "./nonexistent"\nexpires = "not-a-date"\n`)
 
-    const result = runValidate(deckPath, projectDir)
+    const report = await buildDeckValidation(deckPath, projectDir)
 
-    expect(result.status).toBe(1)
-    expect(result.stderr).toContain('invalid expires')
+    expect(report.status).toBe('invalid')
+    expect(report.errors.some(e => e.includes('invalid expires'))).toBe(true)
   })
 })

package/src/validate.ts

@@ -16,9 +16,13 @@ import { resolve } from "node:path";
 import {
   buildValidationPlan,
   executeValidationPlan,
+  ColdPool,
+  hashSkillMd,
+  parseLocator,
   type ValidationReport,
 } from "@lythos/cold-pool";
 import { findDeckToml, expandHome, findSource } from "./link.js";
+import { join } from "node:path";
 import { parseDeck } from "./parse-deck.js";
 
 export interface ValidateOptions {
@@ -37,6 +41,10 @@ export interface DeckValidationReport {
     alias: string;
     localStatus: 'found' | 'missing' | 'parse-error';
     remote?: ValidationReport;
+    drift?: {
+      recordedSha256: string;
+      currentSha256: string;
+    };
   }>;
   budget: { declared: number; max_cards: number; within_budget: boolean };
 }
@@ -125,6 +133,8 @@ export async function buildDeckValidation(
     }
 
     let remote: ValidationReport | undefined;
+    let drift: { recordedSha256: string; currentSha256: string } | undefined;
+
     if (options.remote) {
       const plan = buildValidationPlan(entry.path);
       remote = await executeValidationPlan(plan);
@@ -135,12 +145,34 @@ export async function buildDeckValidation(
       errors.push(`Skill not found in cold pool: ${entry.path} (${entry.type})`);
     }
 
+    // ── Metadata drift check ──────────────────────────────────
+    if (localStatus === 'found' && result.path) {
+      try {
+        const pool = new ColdPool(COLD_POOL);
+        const locator = parseLocator(entry.path);
+        if (locator) {
+          const skillSubpath = locator.skill || '';
+          const recorded = pool.metadata.getSkillHash(locator.host, locator.owner, locator.repo, skillSubpath);
+          if (recorded) {
+            const current = hashSkillMd(join(result.path, 'SKILL.md'));
+            if (recorded !== current) {
+              drift = { recordedSha256: recorded, currentSha256: current };
+              warnings.push(`Content drift: ${entry.alias} — SKILL.md changed since last deck add/link`);
+            }
+          }
+        }
+      } catch {
+        // Drift check is best-effort
+      }
+    }
+
     entryReports.push({
       locator: entry.path,
       type: entry.type,
       alias: entry.alias,
       localStatus,
       remote,
+      drift,
     });
   }
 
@@ -198,6 +230,12 @@ function renderText(report: DeckValidationReport): void {
         console.log(`     ${tag} (confidence: ${fix.confidence.toFixed(2)}) — ${fix.message}`)
       }
     }
+    if (entry.drift) {
+      console.log(`🔀 ${entry.alias} — content drift detected`)
+      console.log(`     recorded: ${entry.drift.recordedSha256.slice(0, 16)}...`)
+      console.log(`     current:  ${entry.drift.currentSha256.slice(0, 16)}...`)
+      console.log(`     Run \`deck add ${entry.locator}\` to re-record metadata`)
+    }
   }
 
   if (report.errors.length > 0) {