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
2. Use vocabulary.notes for the notes folder name
3. Use vocabulary.inbox for the inbox folder name
4. Use vocabulary.note for the note type name in output
5. Use vocabulary.topic_map for MOC/topic map references
6. Use vocabulary.topic_maps for plural form

1. ops/config.yaml — processing depth, thresholds

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

1. 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 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:

| Condition | Level | |-----------|-------| | Any dangling link (target does not exist) | FAIL | | All links resolve | PASS |

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:

| Check | Threshold | |-------|-----------| | Description length | 50-200 chars ideal. < 30 chars = too terse. > 250 chars = too verbose | | Restatement detection | If description uses >70% of the same words as the title = restatement | | Information added | Description should mention mechanism, scope, or implication not in title |

Thresholds:

| Condition | Level | |-----------|-------| | Description is a clear restatement of the title | WARN | | Description is < 30 characters | WARN | | Description is missing entirely | WARN (also caught by Category 1) | | Description adds genuine new information | PASS |

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