HealthSAFE

Claude Code plugin that generates individualized knowledge systems from conversation. You describe how you think and work, have a conversation and get a complete second brain as markdown files you own.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

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

```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 forg

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.