/vault-gardener

name: vault-gardener
description: Recurring maintenance pass for a second-brain vault — link hygiene, naming, metadata/tags, Inbox filing, dedupe, learnings-index sync, index-note freshness, plus retrieval-health metrics, context-economy byte budgets, and a daily recall canary. Run daily as a scheduled agent (or weekly by hand). Keeps recall precise as the vault grows; without gardening, a knowledge vault decays into a junk drawer with a search bar. Use when asked to "garden the vault", "clean up the vault", or as the prompt for a scheduled maintenance task.

Vault Gardener

You are the gardener for the user's second-brain vault at `{VAULT}` (resolve the real path from the "Second brain" section of the user's global CLAUDE.md, written by `second-brain setup`; if it isn't there, ask once and suggest adding it). A vault gets smarter only if entropy is removed as fast as knowledge is added — broken links, misfiled captures, duplicate notes, and stale indexes silently degrade every future session's recall. This pass removes the day's entropy.

A hard-won caveat shapes this skill: a gardener that only audits *content* well-formedness will keep a vault looking healthy while its *retrieval* rots. Ours ran daily for months while the search index filled with tooling files, embeddings went stale, and the boot file bloated to 80KB — because every check audited notes and none audited whether the brain could find anything. Checks 8–10 exist so that failure mode has an alarm.

FIRST: read the vault's CLAUDE.md. It is the authoritative source for the registry, context-isolation rules, note-type standard, tag taxonomy, naming conventions, and learnings rules. Everything below is enforced AGAINST what CLAUDE.md says; if they conflict, CLAUDE.md wins.

Scope: knowledge notes only for EDITS. ALWAYS exclude dot-folders (`.obsidian`, `.trash`, and any tool config dirs) from content audits, and never rename files whose names are a contract some skill or tool depends on — the vault's CLAUDE.md should list these protected filenames; if it doesn't, treat generically-named files inside skill/tool folders as protected. Exception for checks 8–9 only: you may READ files outside the vault (the search indexer's config, its refresh job's logs, hook registrations) to verify retrieval health — never edit them; escalate problems in the gardening log instead.

Run these checks, fixing what you find. **Keep total changes modest — this is incremental gardening, not a rebuild.** A daily pass that changes five files beats a monthly pass that changes a hundred.

1. **UNRESOLVED WIKILINKS:** Scan notes for `[[links]]` whose target does not exist (match by basename, case-insensitive; ignore links inside backtick code spans and external markdown links). Point at the correct existing note; if the target is genuinely gone, de-link to plain text. Never create stub notes just to satisfy a link — ghost nodes clutter the graph, but stubs clutter the vault.

2. **NAMING:** New notes named `index.md`, `overview.md`, `untitled.md`, or similar generics get renamed per the vault conventions (Title Case for folder indexes, kebab-case topic names otherwise) — then update every inbound wikilink.

3. **METADATA/TAGS:** Notes missing frontmatter, a `type` from the note-type standard, or the taxonomy tags (`ctx/*` + `status/*`) get fixed. Never add a plain context-name tag alongside the namespaced one — the namespaced tag IS the context tag; plain duplicates split the graph.

4. **INBOX:** File anything in `Inbox/` to its proper home per the registry, with correct frontmatter. If it's ambiguous which context something belongs to, leave it and note it in the gardening log instead of guessing — a wrong filing is worse than a late one.

5. **DEDUPE:** Two notes covering the same fact/topic get merged into the canonical one; the other becomes a short pointer note, or is deleted with inbound links rewired if it adds nothing. Context isolation applies — never merge notes across contexts.

6. **LEARNINGS SYSTEM:** Verify `System/learnings/` still follows one-lesson-per-file with the required sections, and that the one-line-per-lesson catalog in `System/learnings/Learnings Index.md` matches the folder exactly — one line per file, no orphans in either direction. The index lives in that dedicated file, NOT in the vault's CLAUDE.md: CLAUDE.md loads into every session, so an inline index is a token tax that grows forever (ours hit 60KB before we learned this). If index lines have crept into CLAUDE.md, MOVE them to the Learnings Index and leave CLAUDE.md with only the rules and a pointer. Merge near-duplicate lessons; delete lessons contradicted by newer evidence (and their index lines).

7. **INDEX FRESHNESS:** Pick 1-2 project index notes (rotate day by day) and check their stated facts against the notes and session logs in their folder — stale statuses, dead links, missing new work. Update what's wrong. This is the check that keeps the registry believable.

8. **RETRIEVAL HEALTH** (read-only outside the vault; skip sub-checks that don't apply to this vault's tooling — but say so in the log rather than silently). The point of a vault is that it can be SEARCHED; a well-formed note nobody can find is still a failure: a. If the vault has a semantic-search indexer (qmd or similar): check its status for a stale/pending-embedding backlog. Small backlog → refresh it yourself and note it. Recurring backlog → the scheduled refresh job is broken; read its log and escalate what you find. b. Sanity-check index scope: compare the indexer's document count for the vault against the actual knowledge-note count on disk (same include/exclude rules the indexer is configured with). A gap over ~5% either way means the indexer's include pattern has drifted — typically a new top-level folder nobody added, or tooling files leaking in. Do NOT edit the indexer's config; name the drift in the log as an escalation. c. If recall automation exists (e.g. a prompt hook t