/vault-sync

name: vault-sync
description: >
  Use when you need to validate the Meta-Vault's Markdown frontmatter and wiki-link integrity before
  closing a session or after vault edits. Runs as a hard gate at session-end Phase 1 — blocks close if any
  `.md` file fails the Zod frontmatter schema or has dangling `[[wiki-links]]`. Supports three modes:
  `hard` (blocks on errors), `warn` (reports without blocking), `off` (skip). Reads `vault-sync.*` from
  Session Config; respects per-vault exclude globs from `CLAUDE.md`. Triggers: "vault validation failed at
  session close", "fix vault frontmatter errors", "check vault wiki-links", "why is session-end blocked by
  vault-sync". <example>Context: session-end Phase 1 quality gate, vault-sync.enabled=true,
  vault-sync.mode="hard". user: "/close" assistant: "vault-sync found 2 frontmatter errors in
  vault/40-learnings/ml-notes.md — missing required `id` field. Fixing before close."</example>
user-invocable: false
model: haiku

Vault Sync Skill

> Project-instruction file resolution: `CLAUDE.md` and `AGENTS.md` (Codex CLI) are transparent aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md). The vault-marker check below treats either file as a valid marker (when it carries `## Session Config` + `vault-sync:`); references to `CLAUDE.md` resolve via the SSOT precedence rule.

Status

STATUS: PHASE 1 IMPLEMENTED (2026-04-13). Session-End hard gate (section 3.1) operational. Phase 2 (wave-executor incremental, 3.2) and Phase 3 (evolve advisory, 3.3) not yet implemented.

Implementation

Phase 1 ships a self-contained validator that reads every `.md` file under `VAULT_DIR`, parses YAML frontmatter, validates against the canonical `vaultFrontmatterSchema`, and flags dangling wiki-links as warnings.

Files

• `validator.mjs` — Node.js ESM validator. Uses `zod` + `yaml` npm packages. Reads `VAULT_DIR` (env or default cwd), walks the tree, skipping `node_modules/`, `.git/`, `.obsidian/`. `90-archive/` is walked but never *checked* (#833): archived notes stay in the link-target register — so an inbound `[[wiki-link]]` to an archived note resolves instead of dangling — while their frontmatter is skipped and counted in `archived_skipped_count`. For each `.md`: parses frontmatter, validates against the inline Zod schema, extracts `[[wiki-links]]`, verifies each target resolves. Emits JSON report on stdout.
• `validator.sh` — Thin POSIX wrapper. Resolves `VAULT_DIR` from arg 1 or env, checks that `zod` and `yaml` resolve from the skill directory, execs the Node validator. It never installs anything: unresolvable deps exit 2 with `"reason":"setup-required"` and the one setup command, `npm ci` in the plugin root (#1070). Session-end and other callers use this entry point.
• `package.json` — Declares `zod` (`^4.6.7`, the projects-baseline major) and `yaml` (`^2.5.0`) as deps. No lockfile is committed (`skills/vault-sync/package-lock.json` is gitignored at the repo root); `node_modules/` is gitignored.
• `tests/fixtures/` — Seven fixture vaults matching each test scenario.

Schema source

The inline Zod schema is vendored from the canonical source at `projects-baseline/packages/zod-schemas/src/vault-frontmatter.ts`. The skill is intentionally self-contained (no monorepo workspace dependency), so the schema is duplicated with a header comment pointing at the SSOT. Drift is to be caught by a future smoke test that imports the canonical schema and diffs the shape — NOT YET IMPLEMENTED. Until that test exists, any change to the canonical schema must be mirrored here in the same commit.

Dependencies

`skills/vault-sync/package.json` pins `yaml ^2.5.0` / `zod ^4.6.7` — the `yaml` range intentionally NOT the root's `yaml ^2.9.0`. This is not drift to fix:

• Nothing installs this sub-package. Neither CI host runs a nested install any more — both run only the root `npm ci`, and `.husky/pre-push` links only the root `node_modules/` into its tracked-tree clone. The nested install was dropped on 2026-10-05: it pulled unlocked `zod`/`yaml` versions (this folder's lockfile is gitignored) that the root `npm audit` never saw, and the vault-sync test files ran 125 passed / 0 failed without it.
• The root `package.json` declares no `workspaces`, so `npm ci` at the root never touches this folder's deps. Node resolves `zod`/`yaml` from this folder via the root's own `dependencies` (`yaml ^2.9.0`, `zod ^4.6.7`) — measured 2026-10-05 via `import.meta.resolve('zod')` from this folder → `<root>/node_modules/zod`, re-measured 2026-10-23 after the zod 4.6.7 bump (#1782) with the same result. That is the runtime path in CI, in every worktree and for every end user, so the root dependencies must stay. A stale local `skills/vault-sync/node_modules/` from an older manual install would still win resolution; delete it if versions disagree.
• The `zod` pin tracks the projects-baseline major (`zod ^4.0.0` in `packages/zod-schemas`), not this repo's own version (`scripts/release.mjs`, `evaluateDriftSweep` comment). Its floor is `4.6.7` because every 4.x below 4.6.6 carries GHSA-mrhx-c7xc-m3w5 (#1782); the same floor sits in the root `package.json`, so both ranges resolve to one installed copy.

The root's dependency versions are NOT the SSOT for this folder — do not "fix" this pin to match the root.

How session-end invokes it

VAULT_DIR=/path/to/vault bash ~/Projects/session-orchestrator/skills/vault-sync/validator.sh

• Exit `0` — vault valid (or skipped because no vault exists / no .md files). Warnings may still be present in the JSON report.
• Exit `1` — one or more validation errors. Session-end surfaces them in the quality gate report and refuses to close.
• Exit `2` — invalid invocation or infrastructure error. Two cases: (a) `VAULT_DIR` is not set and `cwd` does not look like a Meta-Vault (no `_meta/`, no `.obsidian/`, no `CLAUDE.md` or `AGENTS.md` with `## Session Config` + `vault-sync:` block) — action