Audit Docs Drift · script + workflow mensual

Resumen

audit_docs_drift.py es un script Python (~250 LOC) que detecta drift documental entre lo declarado en docs y la realidad del repositorio + workspace. Se introdujo en la sesión s61 (14-05-2026) como iniciativa periódica formalizada, tras detectar que el conteo de páginas wiki en CLAUDE.md §7 estaba desactualizado (227/450 declarado → 452 real).

El workflow audit-docs-drift.yml lo ejecuta automáticamente el primer domingo de cada mes a las 08:00 UTC y abre un issue GitHub si encuentra drift de severidad hard.

Motivación

Conteo wiki en CLAUDE.md §7 tenía 227/450 páginas (incorrecto). Audit real: 452 (215 Help + 129 Tech + 27 Workspace + 7 WS-Tech + 21 IA-Tech + 39 huérfanas + 14 metadocs).
4 ejemplos de drift detectados en s58 (memoria feedback_verified_closure).
Coste de corrección manual: sesiones de triaje ad hoc costosas. Solución: automatizar la detección con cron mensual.

Componentes

`scripts/audit_docs_drift.py`

6 checks implementados:

Check	Severidad	Descripción
`wiki-counts`	hard	Detecta `product:` con valor desconocido (fuera de UI_PRODUCTS ni ORPHAN_PRODUCTS). Exit 1 si falla.
`app-version-propagation`	hard	Verifica que `APP_VERSION` de `config/settings/base.py` aparece en los 6 archivos clave (README, CLAUDE.md repo, pyproject.toml, CLAUDE.md workspace, Sidebar.tsx, DesktopA.tsx).
`dead-doc-refs`	soft	Detecta referencias `Documentation/*.md` que ya no existen en el repo.
`obsolete-banners`	soft	`.md` con `OBSOLETO/DEPRECATED` sin banner explícito al inicio del fichero.
`ugly-bibask-slugs`	soft	Slugs patrón `concept--general--existe-`, `concept--general--que-`, etc. — candidatos a revisión por el Curator.
`huerfanas`	soft	Páginas con `product: supercontext` o `product: infra` — accesibles solo por URL directa, sin navegación UI.

Modos de uso:

# Auditoría completa (markdown a stdout)
python scripts/audit_docs_drift.py

# Solo un check
python scripts/audit_docs_drift.py --check wiki-counts
python scripts/audit_docs_drift.py --check app-version-propagation

# Output JSON para parsing programático
python scripts/audit_docs_drift.py --json

Constantes editables:

UI_PRODUCTS     = {"crearack", "crearack-tech", "workspace", "workspace-tech", "ia-tech"}
ORPHAN_PRODUCTS = {"supercontext", "infra"}

APP_VERSION_PROPAGATION = [
    REPO_ROOT / "README.md",
    REPO_ROOT / "CLAUDE.md",
    REPO_ROOT / "pyproject.toml",
    WORKSPACE_ROOT / "CLAUDE.md",
    WORKSPACE_ROOT / "src/components/shell/Sidebar.tsx",
    WORKSPACE_ROOT / "src/components/variants/desktop/DesktopA.tsx",
]

Si se añade una nueva wiki → añadir su product: a UI_PRODUCTS. Si se añade nuevo archivo con la versión → añadir a APP_VERSION_PROPAGATION.

`.github/workflows/audit-docs-drift.yml`

Trigger: cron: '0 8 1-7 * 0' (primer domingo de mes, 08:00 UTC / 10:00 Madrid CEST) + workflow_dispatch.
Permisos: contents: read, issues: write.
Pasos: checkout repo + workspace → Python 3.14 → ejecuta script → upload artifact (90 días) → si exit ≠ 0 → abre issue con reporte.
Secret: WORKSPACE_REPO_PAT (fallback a github.token).
Coste: ~3 min/mes de runner time.

Estado de la iniciativa s61 (14-05-2026)

Ítem	Estado
Script `audit_docs_drift.py`	✅ Mergeado PR#29
Workflow cron mensual	✅ Mergeado PR#29
`CLAUDE.md §7` corregido (452 páginas reales)	✅
ADR `decision--20260514--saneamiento-docs-periodico`	✅ Creado en workspace
Sub-iniciativa 39 páginas huérfanas (`supercontext` 38 + `infra` 1)	🔲 Pendiente — triaje caso a caso
Auditoría manual al cierre de iniciativas grandes	🔲 Pendiente — checklist 6 puntos

Criterio de cierre: permanente-operativa cuando (a) cron lleva 3 meses sin falsos positivos; (b) 39 huérfanas triadas; (c) script ejecutado en cierres de sesión que toquen docs.

Primer run local (14-05-2026)

0 hard failures, 4 soft info findings:
- dead-doc-refs:       12  (mayoría CHANGELOG histórico, aceptables)
- obsolete-banners:     2
- ugly-bibask-slugs:  ~80  candidatos Curator
- huerfanas:           39  (38 product:supercontext + 1 product:infra)

Cómo añadir un check nuevo

Definir función check_<nombre>() -> dict que devuelva {status, severity, ...}.
Añadirla al diccionario CHECKS al final del módulo.
Si es hard: devolver status: "fail" cuando detecta problema.
Actualizar este doc + TASK.md.

Véase también

[[runbook—ci—audit-docs-drift]] — instrucciones operacionales paso a paso para ejecutar y triagear el script
[[decision—20260514—saneamiento-docs-periodico]] — ADR que formaliza la iniciativa y justifica el enfoque periódico vs. reactivo