validate_vault
Validate every document in the ontology vault to get a whole-vault health view, surfacing per-document and per-code issues before writes.
Instructions
R+ (cycle 46) — validate every doc in the vault, return per-doc + per-code aggregate. Replaces the K-round-trip pattern of list_concepts then per-doc get_concept (whose warnings: [...] is per-file). 8 issue codes — unclosed-frontmatter, parse-zero-keys, malformed-frontmatter-line, malformed-quoted-scalar, missing-kind, empty-kind, unknown-kind, missing-uid, invalid-uid, invalid-merged-uids, non-canonical-merged-uids, missing-expected-field, non-canonical-graph-array, dangling-graph-reference, duplicate-slug, duplicate-uid, definition-missing, boundary-missing, epistemic-exclusion, uncertainty-missing, slug-outside-kind-folder, folder-only-evidence, dependency-unwitnessed, dependency-unjudged, starter-example-node, kind-under-sources. Returns { scanned, problems: [{slug, issues: [{code, severity, message}]}], problemsPagination, summary: { problemFiles, errorFiles, warningFiles, byCode: { code: { severity, count, files } } } }. problems is one page, files with errors first and then by slug: offset (default 0) and limit (default 100, max 500) choose it, a page left at the default limit stops sooner when its text would pass 128 KiB, and problemsPagination.nextOffset resumes it, so follow pages until hasMore is false before calling the vault clean. summary always counts the whole vault; each byCode entry names at most 20 files and says how many more in filesOmitted. Also returns pathDrift: frontmatter path: / elements: source paths that no longer exist on disk (vault→code drift), resolved against repoRoot (default: the active resolved repository root from connection_info). Ontology-slug references are never flagged. Fix via patch_concept or remove the stale entry. Also returns evidenceDrift: one Git walk dates every cited path and every concept document, and each concept is current (cited code unchanged since the document), stale (a cited file changed after the document — read it before trusting the recorded meaning), missing (cited path gone) or unknown (nothing cited, no commit in the window, or only a folder-level path moved — listed under folderOnly, because a folder changes on almost any commit). checked: false names why nothing was dated; it never means nothing moved. side effect 0. Use when an agent needs the whole-vault health view: first-contact before writes, before / after a batch write, or surfacing issues to the user.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Problem files per page. Defaults 100. | |
| offset | No | Zero-based index of the first problem file to return, in the order errors first and then slug. Resume with `problemsPagination.nextOffset`. Defaults 0. | |
| repoRoot | No | Repository root that frontmatter source paths resolve against, for the pathDrift check. Defaults to the active resolved repository root from connection_info. Pass this if the vault lives apart from the code repo. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scanned | Yes | Number of vault markdown files scanned. | |
| summary | Yes | ||
| problems | Yes | ||
| pathDrift | Yes | Vault→code path drift: frontmatter source paths missing on disk, resolved against repoRoot. | |
| problemsHint | No | Present when the vault has more than one page: which files this page shows and the call for the next one. | |
| evidenceDrift | No | Whether each concept still stands on the code it cites, dated by one Git walk: current / stale / missing / unknown per concept, with the stale and missing rows named (bounded to 50 each). | |
| summaryFreshness | Yes | ||
| problemsPagination | No | The page `problems` holds: `total` problem files, and `nextOffset` for the next page until `hasMore` is false. |