Salud del vault: huérfanos, tags y enlaces según markeup-audit

La skill markeup-audit —«Mide la salud del vault y prioriza las acciones de mejora»— es una de las habilidades que el sistema MarkeUP tiene escritas para Hermes Agent y para Cline. Esta página es su ficha pública: lo que sabe hacer, cuándo se usa y qué comandos ejecuta.

Cuando el vault crece, alguien tiene que mirar el conjunto: la skill propone qué arreglar primero y no toca nada por su cuenta.

El texto de la sección «Instrucciones del canon» está transcrito del fichero fuente —que se escribe sin tildes por convención de su propio gate—, así que es exactamente lo que lee el agente cuando le pides algo. La cabecera y esta entradilla sí están redactadas para leerlas.

Dato	Valor
Skill	`markeup-audit`
Responsabilidad	Mide la salud del vault y prioriza las acciones de mejora.
Versión	1.3.0
Autoría	uriszarernesto-blip · licencia MIT
Plataformas	linux · macos
Tags del canon	auditoria · salud · huerfanos · tags · markeup · obsidian
Skills relacionadas	markeup-context · markeup-wikilinks · markeup-cli
Fuente	`~/.hermes/skills/markeup/markeup-audit/SKILL.md`

Responsabilidad unica: medir y reportar la salud estructural del vault. No modifica contenido por su cuenta: propone y espera aprobacion.

Revision periodica del vault.
Antes de planificar contenido nuevo.
Cuando tools:huerfanos o validate:wikilinks dan cifras preocupantes.

Primero lee markeup-context.

El vault se sincroniza con Syncthing (Mac ↔ Android/Obsidian). Auditar mientras se escribe produce cifras no deterministas y un índice que nace desactualizado.

cd ~/markeup
find src/content/posts -name '*.md' -newermt '-10 minutes' | head

Si devuelve archivos, avísalo y pide pausar la sincronización antes de auditar o de ejecutar tools:index. No presentes cifras exactas como definitivas.
Indicio externo: pgrep -fl syncthing.

La CLI, sus flags y el prerrequisito de Python (PyYAML) son responsabilidad de markeup-cli (matriz completa en esa skill: markeup-cli/references/command-matrix.md). Aqui queda solo lo que alimenta el informe:

cd ~/markeup
export PATH="/opt/homebrew/bin:$PATH"     # fallback con PyYAML (el venv del proyecto ya lo trae)

npm run validate:frontmatter -- --json    # metricas de frontmatter (para contar)
npm run validate:seo -- --json            # gate SEO en JSON
npm run tools:auditar -- --json           # huerfanos, sin wikilinks, slugs, tags, drafts
npm run tools:huerfanos                   # huerfanos priorizados (tabla)
npm run validate:wikilinks                # Regla de Oro (exit 1 si falla)

Dos definiciones de huérfano (no confundirlas): tools:auditar cuenta todo destino de wikilink sin nota propia; validate:wikilinks descuenta los que resuelven por aliases. Sus cifras difieren (p. ej. 206 vs 188) y ambas son correctas: cita siempre de qué comando sale el número.

Si tools:* falla con ModuleNotFoundError: No module named 'yaml', el interprete resuelto es el del sistema: usa el venv (PYTHONPATH=src src/.venv/bin/python3 -m markeup_tools ...) o Homebrew. Detalle en markeup-cli.

Metrica	Formula	Objetivo	Fuente (comando)
Cobertura de wikilinks	notas con >=1 wikilink / total	> 70%	`tools:auditar`
Tasa de huerfanos	huerfanos / total wikilinks	< 15%	`validate:wikilinks` (o `tools:auditar`)
Cumplimiento frontmatter	notas con los 22 campos (4 duros) / total	100%	`validate:frontmatter`
SEO conforme	posts con title 50-75, description 140-200 y clave al frente / total	100%	`validate:seo`
Description en rango	notas con 140-200 chars / total	100%	`validate:frontmatter`
Coherencia categoria/carpeta	notas con `categories[0]` == carpeta / total	100%	`validate:frontmatter`
Tags normalizados	tags sin tildes ni `#` / total tags	100%	`validate:frontmatter` + `tools:tagfix`
Imagenes presentes	posts con imagen real / total	alto	`validate:frontmatter`
Drafts stale	`draft: true` con pubDate antiguo	0	`tools:auditar`

tools:auditar no revisa el frontmatter: solo huérfanos, notas sin wikilinks, slugs con mayúsculas, tags con # y drafts. Las métricas de frontmatter salen de validate:frontmatter (usar --json para contar).

Severidad (2 niveles, 2026-09-25): los AVISO de validate:frontmatter y validate:seo son deuda de calidad y no bloquean la publicación; solo los ERROR (campo duro ausente, categoría inválida, clave del concept fuera del title, title duplicado o provisional, rango duro 40-90 / 100-260) son fallos. Un aviso no baja el nivel de salud del vault; cuéntalos como deuda separada.

Detalle de umbrales: references/health-metrics.md.

Nivel	Criterios
EXCELENTE	> 90% notas con wikilinks, < 5% huerfanos, 0 drafts stale
BUENA	> 70% notas con wikilinks, < 15% huerfanos
REGULAR	> 50% notas con wikilinks, < 30% huerfanos
MALA	< 50% notas con wikilinks, > 30% huerfanos

Notas a crear - top 5 huerfanos prioritarios.
Notas a interconectar - slugs sin wikilinks que deberian enlazar a otros.
Tags a consolidar - tags con 1 sola aparicion que podrian unificarse.
Notas a actualizar - slugs con updatedDate muy antiguo.
Posts relacionados - notas con tags similares pero sin wikilinks entre si.

Un huerfano es prioritario cuando cumple al menos uno:

Aparece en 3+ notas distintas.
Aparece en 2+ notas de categorias diferentes.
Es un concepto central en la introduccion de varias notas.

Variantes del mismo concepto (ansiedad y ansiedad-generalizada).
Uno es subconjunto del otro (meditacion y meditacion-vipassana).
Diferencia solo de guiones/espacios.

Ruta del informe:

~/markeup/src/content/hermes/logs/sessions/auditoria-YYYY-MM-DD.md

Importante: el directorio hermes/logs/ puede no existir. Creao antes de escribir: mkdir -p src/content/hermes/logs/sessions. No falles silenciosamente si falta.

npm run tools:index      # regenera hermes/memory/vault-index.md

## [HORA] Auditoria de vault
- Notas escaneadas: N
- Huerfanos encontrados: N
- Recomendaciones generadas: N

❌ Sugerir crear una nota para cada huerfano (solo los prioritarios).
❌ Recomendar eliminar tags sin consultar al usuario.
❌ Cambiar categorias de notas existentes sin preguntar.
❌ Ejecutar tools:tagfix o renombrar sin confirmacion (son escrituras).
❌ Reportar un nivel de salud sin haber ejecutado validate:wikilinks.

Obsidian: informe completo con bloques plegables por seccion.
Telegram: solo nivel de salud + top 5 huerfanos + recuentos. Maximo ~3500 caracteres.
VS Code / Cline: informe + comandos ejecutados con su salida.
Hermes CLI: informe + log de sesion escrito.

references/health-metrics.md - formulas y umbrales detallados.
markeup-cli - los comandos que este atomo usa.
markeup-wikilinks - criterios de huerfanos y densidad.

¿Quieres saber cómo se piden estas cosas? La guía completa está en skills de Hermes Agent, con la chuleta de objetivos y los casos paso a paso.

Salud del vault

Salud del vault: huérfanos, tags y enlaces según markeup-audit

Posts que enlazan a este artículo