/vault-sync

name: vault-sync
description: Detect and repair drift between an OKF knowledge vault and the code it describes. Use after merging significant changes (schema, routes, workflows, agent config), when a staleness review is due, or when the user asks to sync, refresh, or update the knowledge vault or Obsidian vault.
user-invocable: true
allowed-tools: Read, Grep, Glob, Bash

Vault Sync Skill

> **📋 TEMPLATE**: This skill uses `{{TICKET_PREFIX}}` and `{{MAIN_BRANCH}}` as placeholders, and > assumes a vault created from `knowledge-vault/templates/starter-bundle`.

Purpose

Keep an OKF knowledge vault honest as the code evolves. The vault is a map of the system; this skill detects drift between map and territory, regenerates **only** the affected concepts, and records the sync.

When This Skill Applies

Invoke this skill when:

• A significant change merged — schema, public interfaces, CI workflows, agent or skill config
• A staleness review is due (the `stale-concepts` Base is the queue)
• The user asks to sync, refresh, or update the knowledge vault
• A concept is suspected of being wrong

Key Files

| Path | Role | | --- | --- | | `<vault>/_meta/vault-config.json` | Machine-readable constitution — types, tags, frontmatter contract | | `<vault>/_meta/CONVENTIONS.md` | The human-readable rules | | `<vault>/_meta/manifest.json` | ID registry, reverse index, and `baseline_sha` drift watermark | | `<vault>/_meta/templates/` | Per-type skeletons | | `<vault>/log.md` | Dated changelog | | `knowledge-vault/scripts/validate-vault.mjs` | The gate |

Procedure

1. Detect drift

Read the baseline and diff it to HEAD across the watch-list — **the source paths your concepts claim to describe**. Configure this list for your project; the example below is illustrative.

BASELINE=$(node -e "console.log(require('./<vault>/_meta/manifest.json').baseline_sha)")
git diff --name-only "$BASELINE"..HEAD -- \
  'src/**' 'lib/**' 'config/**' '.github/workflows/**' 'docs/**'

A concept is **stale** if and only if a changed path matches its `resource` or an entry in its `sources`. Check the manifest first (it is the reverse index); grep concept frontmatter as backup.

This is file-level truth. Do not substitute a time-based heuristic — "older than N days" flags everything and teaches people to ignore the flag.

2. Detect inventory changes

Re-enumerate your source globs and diff against the manifest.

• **New source, no concept** → create one. **Add the manifest entry first**, so the ID exists in

the registry before anything links to it.

• **Deleted source** → set the concept's `status: deprecated`. **Do not delete the file.** Inbound

links must be cleaned first, in a follow-up change; the backlinks pane or the validator's orphan report shows them.

3. Regenerate

For a handful of concepts, update inline. For larger sets, fan out generation agents batched by area. **Every generation prompt must carry exactly four things:**

1. The type template from `_meta/templates/` 2. A **golden example** — a real, already-accepted concept of the same type 3. The hard rules from `_meta/CONVENTIONS.md`, inline 4. The manifest **ID registry** — links may target only IDs listed there

Every touched concept gets `timestamp:` = today and `verified_against:` = the current short SHA.

**Re-derive facts from the source files. Never patch prose without re-reading the code it describes.** Editing a concept to match a changed interface without opening the file is how a vault becomes fiction.

4. Validate

node knowledge-vault/scripts/validate-vault.mjs --vault <vault>

Must exit 0. Markdown lint must pass. Neither is optional.

5. Record

Prepend a dated entry to `log.md`: what changed, why (ticket), and the source SHA. Then bump `baseline_sha` and `generated` in the manifest.

Ship on a `{{TICKET_PREFIX}}-XXX-vault-sync-<topic>` branch with a `docs(vault): …` commit to `{{MAIN_BRANCH}}`. The pull request should name the code changes that triggered the sync.

Invariants (do not relax)

• Concept-to-concept links never leave the bundle; out-of-bundle links only under `## Citations`
• Relative markdown links only — no wikilinks, no leading-slash paths, no repo-host URLs for repo files
• **Link only to IDs in the manifest.** If a concept does not exist, name it in prose and report it

as a suggestion — never invent a link

• One concept per file; H2 sections exactly match the type template, in order
• Stub types cite their source-of-truth doc; they never restate it
• **A citation is not re-verification.** Only re-deriving a concept from source bumps its

`timestamp` and `verified_against`

Anti-Patterns (Do NOT use)

Bumping timestamps on a docs-only pass   (that is laundering, not verification)
Deleting a concept when its source dies  (deprecate; clean inbound links first)
Regenerating the whole vault on drift    (regenerate only what the diff implicates)
Patching prose without reading the code  (the one habit that makes a vault untrustworthy)
Skipping the validator because "it is just docs"  (drift is invisible without the gate)

Authoritative References

• `knowledge-vault/docs/GUIDE.md` -- the method and why each rule exists
• `knowledge-vault/docs/ADOPTION-PLAYBOOK.md` -- running your first build
• `knowledge-vault/docs/BUILD-PROMPT.md` -- the multi-agent build prompt

Routes To

• `safe-workflow` — branch, commit, and PR conventions
• `linear-sop` — recording the sync against a ticket
• `pattern-discovery` — find existing concepts before writing new ones