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:

| 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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 '*