CreaRack-SL

Audit Docs Drift · script + workflow mensual

Vista limpiaEditar
Funcionalidadactiveverificado 2026-05-14#ia-tech#automatismos#ci#github-actions#docs#audit#drift

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:

CheckSeveridadDescripción
wiki-countshardDetecta product: con valor desconocido (fuera de UI_PRODUCTS ni ORPHAN_PRODUCTS). Exit 1 si falla.
app-version-propagationhardVerifica 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-refssoftDetecta referencias Documentation/*.md que ya no existen en el repo.
obsolete-bannerssoft.md con OBSOLETO/DEPRECATED sin banner explícito al inicio del fichero.
ugly-bibask-slugssoftSlugs patrón concept--general--existe-*, concept--general--que-*, etc. — candidatos a revisión por el Curator.
huerfanassoftPá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)

ÍtemEstado
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

  1. Definir función check_<nombre>() -> dict que devuelva {status, severity, ...}.
  2. Añadirla al diccionario CHECKS al final del módulo.
  3. Si es hard: devolver status: "fail" cuando detecta problema.
  4. 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

Referenciado desde

Inicio
Yo