Vault Sync Skill

Vault Sync Skill

Project-instruction file resolution: CLAUDE.md and AGENTS.md (Codex CLI) are transparent aliases — see skills/_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, self-bootstraps deps via pnpm install --silent on first run, execs the Node validator. Session-end and other callers use this entry point.
• package.json — Declares zod (^3.24.0, matching projects-baseline) and yaml (^2.5.0) as deps. pnpm-lock.yaml is committed; node_modules/ is gitignored.
• tests/validator.bats — 16 BATS cases covering clean vaults, broken frontmatter, missing required fields, dangling links, no-vault skipping, README-style files, nested directories, and archive/obsidian exclusion.
• 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.

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) — actionable error printed to stderr; (b) infrastructure error (missing node, missing validator.mjs, cannot bootstrap deps). In both cases no JSON is emitted to stdout.

JSON output shape (stdout):

{
  "status": "ok|invalid|skipped",
  "vault_dir": "...",