/health

name: health
description: Run condition-based vault health diagnostics. 8 categories — schema compliance, orphan detection, link health, description quality, three-space boundaries, processing throughput, stale notes, MOC coherence. 3 modes — quick (schema+orphans+links), full (all 8), three-space (boundary violations only). Returns actionable FAIL/WARN/PASS report with specific fixes ranked by impact. Triggers on "/health", "check vault health", "maintenance report", "what needs fixing".
version: "1.0"
generated_from: "arscontexta-v1.6"
context: fork
model: opus
allowed-tools: Read, Grep, Glob, Bash, mcp__qmd__vector_search
argument-hint: "[optional: 'quick', 'full', or 'three-space']"

Runtime Configuration (Step 0 — before any processing)

Read these files to configure domain-specific behavior:

1. **`ops/derivation-manifest.md`** — vocabulary mapping, folder names, platform hints

• Use `vocabulary.notes` for the notes folder name
• Use `vocabulary.inbox` for the inbox folder name
• Use `vocabulary.note` for the note type name in output
• Use `vocabulary.topic_map` for MOC/topic map references
• Use `vocabulary.topic_maps` for plural form

2. **`ops/config.yaml`** — processing depth, thresholds

3. **Three-space reference** — `${CLAUDE_PLUGIN_ROOT}/reference/three-spaces.md` for boundary rules (load only for full and three-space modes)

4. **Templates** — read template files to understand required schema fields for validation

If these files don't exist (pre-init invocation or standalone use), use universal defaults:

• notes folder: `notes/`
• inbox folder: `inbox/`
• topic map: topic maps in notes/

---

EXECUTE NOW

**Target: $ARGUMENTS**

Parse the invocation mode immediately:

| Input | Mode | Categories Run | |-------|------|---------------| | empty or `quick` | Quick | 1 (Schema), 2 (Orphans), 3 (Links) | | `full` | Full | All 8 categories | | `three-space` | Three-Space | 5 (Three-Space Boundaries) only |

**Execute these steps:**

1. **Detect mode** from arguments 2. **Scan the vault** — inventory all note files, {vocabulary.topic_map} files, inbox items, ops files 3. **Run each applicable diagnostic category** in order (1-8) 4. **Classify each result** as PASS, WARN, or FAIL using the thresholds below 5. **Surface condition-based maintenance signals** (check against threshold table) 6. **Generate the health report** with specific file paths, counts, and recommended actions 7. **Write report to** `ops/health/YYYY-MM-DD-report.md`

**START NOW.** Reference below explains each diagnostic category in detail.

Platform Adaptation

Checks adapt to what the platform supports:

• If semantic search (qmd) is not configured, skip semantic-dependent checks and note their absence
• If hooks are not available, note that validation is convention-only (no automated enforcement)
• If self/ directory does not exist (disabled by config), skip self-space checks but verify ops/ absorbs self-space content correctly

**Report what CAN be checked, not what the platform lacks.**

---

The 8 Diagnostic Categories

Category 1: Schema Compliance (quick, full)

**What it checks:** Every {vocabulary.note} in {vocabulary.notes}/ and self/memory/ (if self/ is enabled) has valid YAML frontmatter with required fields.

**How to check:**

# Find all note files (exclude topic maps)
for f in {vocabulary.notes}/*.md; do
  [[ -f "$f" ]] || continue
  # Check: YAML frontmatter exists
  head -1 "$f" | grep -q '^---$' || echo "FAIL: $f — no YAML frontmatter"
  # Check: description field present
  rg -q '^description:' "$f" || echo "WARN: $f — missing description field"
  # Check: topics field present and links to at least one topic map
  rg -q '^topics:' "$f" || echo "WARN: $f — missing topics field"
done

**Additional checks:**

• Domain-specific enum fields have valid values (check against template `_schema` blocks if templates exist)
• `description` field is non-empty (not just present)
• `topics` field contains at least one wiki link

**If `validate-kernel.sh` exists** in `${CLAUDE_PLUGIN_ROOT}/reference/`, run it and include results.

**Thresholds:**

| Condition | Level | |-----------|-------| | Any note missing YAML frontmatter | FAIL | | Any note missing `description` field | WARN | | Any note missing `topics` field | WARN | | Any invalid enum value | WARN | | All notes pass all checks | PASS |

**Output format:**

[1] Schema Compliance ............ WARN
    2 notes missing description:
      - notes/example-note.md
      - notes/another-note.md
    1 note missing topics:
      - notes/orphaned-claim.md
    12/15 notes fully compliant

Category 2: Orphan Detection (quick, full)

**What it checks:** Every {vocabulary.note} has at least one incoming wiki link from another file.

**How to check:**

# For each note file, check if ANY other file links to it
for f in {vocabulary.notes}/*.md; do
  [[ -f "$f" ]] || continue
  basename=$(basename "$f" .md)
  # Search for [[basename]] in all other files
  count=$(rg -l "\[\[$basename\]\]" --glob '*.md' | grep -v "$f" | wc -l | tr -d ' ')
  if [[ "$count" -eq 0 ]]; then
    echo "WARN: $f — no incoming links (orphan)"
  fi
done

**Nuance:** Orphans are not automatically failures. A note created today that hasn't been through /{vocabulary.cmd_reflect} yet is expected to be orphaned temporarily. Check file age:

| Condition | Level | |-----------|-------| | Orphan note created < 24 hours ago | INFO (expected — awaiting reflect phase) | | Orphan note created 1-7 days ago | WARN | | Orphan note older than 7 days | FAIL (persistent orphan needs attention) | | No orphans detected | PASS |

**Output format:**

[2] Orphan Detection ............. WARN
    3 orphan notes detected:
      - notes/new-claim.md (created 2h ago — awaiting reflect) [INFO]
      - notes/old-observation.md (created 5d ago) [WARN]
      - notes/forgotten-insight.md (created 14d ago) [FAIL]
    Recommendation: run /reflect on forg