ValidateVault

ValidateVault

Validate vault markdown files against .mdschema schema files using the mdschema CLI. Reports structural violations: missing frontmatter fields, wrong field types, unexpected headings, missing required sections.

Workflow Routing

Workflow	Trigger	Section
Check	"validate vault", "check journals", "validate memory"	Check
Report	"how bad is it", "vault health", "show violations"	Report

Tool Reference

Binary: mdschema (Go, installed via brew install jackchuka/tap/mdschema).

mdschema check "glob/pattern/**/*.md" --schema path/to/.mdschema

Output: per-file list of ✗ violations with line numbers, categories ([frontmatter], [structure]), and descriptions.

Schema Locations

Schemas ship with their convention-owning module, not in the vault. The vault contains instances; modules contain the rules.

Content	Schema Location	Vault Glob
Daily journals	$VAULT/Templates/Journals/.mdschema	$VAULT/Resources/Journals/Daily/**/*.md
Weekly journals	$VAULT/Templates/Journals/.mdschema	$VAULT/Resources/Journals/Weekly/**/*.md
Memory Insights	$MODULES/forge-reflect/skills/MemoryInsights/Templates/.mdschema	$VAULT/Orchestration/Memory/Insights/*.md
Memory Imperatives	$MODULES/forge-reflect/skills/MemoryInsights/Templates/.mdschema	$VAULT/Orchestration/Memory/Imperatives/*.md
Memory Ideas	$MODULES/forge-reflect/skills/MemoryInsights/Templates/.mdschema	$VAULT/Orchestration/Memory/Ideas/*.md

Where $VAULT resolves from user.root in config.yaml (currently Vaults/Personal) relative to $HOME/Data, and $MODULES is Modules/.

---

Check

1. Resolve the vault root from config.yaml:

   FORGE_ROOT="$HOME/Data"
   VAULT="$FORGE_ROOT/$(grep 'root:' "$FORGE_ROOT/config.yaml" | awk '{print $2}')"
   MODULES="$FORGE_ROOT/Modules"
   

2. Verify mdschema is installed:

   command -v mdschema >/dev/null || { echo "mdschema not installed — brew install jackchuka/tap/mdschema"; exit 1; }
   

3. Determine scope from user request. Default to journals if unspecified.

4. Run validation against the relevant schema:

   # Daily journals
   mdschema check "$VAULT/Resources/Journals/Daily/**/*.md" \
       --schema "$VAULT/Templates/Journals/.mdschema"
   
   # Weekly journals
   mdschema check "$VAULT/Resources/Journals/Weekly/**/*.md" \
       --schema "$VAULT/Templates/Journals/.mdschema"
   
   # Memory (when requested)
   mdschema check "$VAULT/Orchestration/Memory/Insights/*.md" \
       --schema "$MODULES/forge-reflect/skills/MemoryInsights/Templates/.mdschema"
   

5. Present results to the user grouped by violation type.

---

Report

Summarize validation results as a structured report:

1. Run the Check workflow, capturing full output.

2. Count violations by category:

   • Frontmatter: missing fields, wrong types
   • Structure: missing required sections, unexpected headings, heading hierarchy

3. Present summary table:

   | Directory     | Files | Passing | Failing | Top Violation           |
   |---------------|-------|---------|---------|-------------------------|
   | Daily 2026/01 | 31    | 12      | 19      | missing "## Plan"       |
   | Daily 2026/02 | 27    | 25      | 2       | missing 'tlp' field     |
   | Weekly 2026   | 8     | 8       | 0       | —                       |
   

4. List the top 5 most common violations with counts.

5. Suggest remediation approach (batch fix vs manual).

---

Constraints

• Read-only — this skill validates, it does not fix. Remediation is a separate step.
• Skip directories that don't exist (graceful degradation).
• Skip validation entirely if mdschema is not installed — report the missing dependency.
• The journal .mdschema currently lives in the vault (Templates/Journals/). Future: migrate to forge-journals as source of truth.
• mdschema validates structure only — it cannot check semantic correctness (enum values, tag formats, date validity).