health

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:

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:

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:

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 forgotten-insight.md and old-observation.md

Category 3: Link Health (quick, full)

What it checks: Every wiki link [[target]] in every file resolves to an existing file.

How to check:

# Extract all wiki links from all markdown files
# For each unique link target, verify a file with that name exists
rg -oN '\[\[([^\]]+)\]\]' --glob '*.md' -r '$1' | sort -u | while read target; do
  # Search for file matching this name
  found=$(find . -name "$target.md" -not -path "./.git/*" 2>/dev/null | head -1)
  if [[ -z "$found" ]]; then
    echo "FAIL: dangling link [[${target}]] — no file found"
    # Show which files contain this dangling link
    rg -l "\[\[$target\]\]" --glob '*.md'
  fi
done

Thresholds:

Why FAIL not WARN: Dangling links are broken promises. Every [[link]] a reader follows that leads nowhere erodes trust in the graph. Fix these immediately.

Output format:

[3] Link Health .................. FAIL
    2 dangling links found:
      - [[nonexistent-note]] referenced in:
        - notes/some-claim.md (line 14)
        - notes/another-claim.md (line 8)
      - [[removed-topic]] referenced in:
        - notes/old-note.md (line 22)
    Recommendation: create missing notes or remove broken links

Category 4: Description Quality (full only)

What it checks: Every {vocabulary.note}'s description adds genuine information beyond the title — not just a restatement.

How to check:

For each {vocabulary.note}:

1. Read the title (filename without extension)
2. Read the description field from YAML frontmatter
3. Evaluate: does the description add scope, mechanism, or implication that the title does not cover?

Quality heuristics:

Thresholds:

This check requires judgment. Use semantic understanding, not just string matching. A description that uses different words but says the same thing as the title is still a restatement.

Output format:

[4] Description Quality