A version-pinned sync mechanism between vault skills and mounted SKILL.md wrappers eliminates drift within 1 sync cycle and prevents recurrence via reactive hooks

Hypothesis

A version-pinned sync mechanism between vault skills and mounted SKILL.md wrappers eliminates drift within 1 sync cycle and prevents recurrence via reactive hooks

Changelog

Date	Summary
2026-04-06	Audited: added Changelog, domain tag ai-agents, stamped last_audited
2026-04-02	Initial creation

---

Hypothesis

A version-pinned sync mechanism between vault skills (~/vault/skills/*.md) and mounted Claude Code wrappers (~/.claude/skills/{name}/SKILL.md) will eliminate version drift within 1 sync cycle. A reactive PostToolUse hook will detect future vault skill edits and prevent drift from recurring.

Method

Built into context-curator project (~/Documents/context-curator):

1. Manifest extension (src/manifests/build-manifest.py): Added vault_version, vault_hash, mounted_version, mounted_vault_hash to skill items. Added sync_status section with categories: synced, version_drift, content_drift, unmounted, orphan_mounted.

2. Sync engine (src/sync/skill_sync.py): CLI tool with --check (detect only), --dry-run, --force, --one NAME modes. Generates mounted SKILL.md wrappers from vault skill metadata (version, hash, trigger → description, inferred tools).

3. PostToolUse hook (Layer 5 in peon-curator.sh): Detects writes to ~/vault/skills/*.md, appends skill name to dirty file. ~0.1ms overhead for non-skill writes.

4. SessionStart nudge: Checks dirty file at session start, injects systemMessage listing stale skills with sync command.

5. Config: Added skill_sync section to curator-config.json.

Hermes Agent analysis: Crawled nousresearch/hermes-agent (24,675 lines). Key self-improvement patterns: (a) turn-counting nudge → background agent fork for skill review, (b) MD5 manifest for bundled-to-user sync, (c) system prompt instructs “patch skills immediately when outdated”, (d) 90+ regex security scanner + LLM audit. We adopted (a) as SessionStart nudge, (b) as version+hash tracking, and skipped (c) background forks and (d) security scanning.

Results

Pre-sync state:

• 26 vault skills, 23 mounted (3 unmounted, 1 orphan)
• 0 mounted SKILL.md files had version: field
• 12 description mismatches between mounted and vault

Post-sync state:

• 27 vault skills (bloomnet-refresh promoted), 27 mounted
• All 27 have version: and vault-hash: matching vault source
• skill_sync.py --check exits 0

First sync actions:

• 24 wrappers regenerated (version drift → synced)
• 3 wrappers created (unmounted → mounted)
• 1 skill promoted to vault (orphan → vault source of truth)
• Dirty file cleared

Findings

Hermes Agent-inspired patterns (version manifest, SessionStart nudge) translate well to vault-first architectures. 24/27 skills had version drift (mounted had no version field), revealing that drift was pervasive before detection existed. Background agent forks and security scanning from Hermes were skipped as over-engineering for vault’s scale.

Next Steps

• Register PostToolUse hook in ~/.claude/settings.json (currently in source, not installed)
• Add daily cron: vault-bootstrap sync-skills --check
• Monitor drift rate over next 10 sessions
• Consider auto-sync on SessionStart if nudge proves insufficient