KB vs Graph Fase 1 · schema Astro + migración D1-0024 + backfill 449 páginas (s61)

Descripción

Fase 1 de la iniciativa Knowledge Base vs Knowledge Graph (Sprint 61). Introduce los tres campos arquitectónicos del ADR decision—20260514—knowledge-base-vs-graph sin activar todavía crons nuevos. Las fases siguientes añadirán el drift check automático con Haiku y la evolución del agente Lint bulk.

Piezas implementadas

1. Schema Astro (src/content.config.ts · commit 068b32f)

Tres campos nuevos añadidos a la colección wiki, todos opcionales (retrocompatibles con los ~449 .md existentes):

kind: z.enum(['knowledge_base', 'knowledge_graph']).optional(),
lifecycle: z
  .string()
  .regex(/^(evergreen|refresh-\d+d|ephemeral-\d+d)$/)
  .optional(),
verification_pending: z.boolean().optional(),

• kind: diferencia documentación intencional de nodos auto-generados por bib_ask.
• lifecycle: política de caducidad declarativa. Cuatro valores usados en producción: evergreen, refresh-90d, refresh-30d, ephemeral-90d.
• verification_pending: tripwire que Ingest activará (Fases 2+) cuando los sources[] de una página sean tocados por un PR.

2. Migración D1 0024 (migrations/0024_kind_lifecycle_drift.sql · commit 75a37b8)

Añade a bib_wiki_pages:

Índices nuevos:

• idx_wiki_pages_kind en bib_wiki_pages(kind).
• idx_wiki_pages_verification_pending parcial WHERE verification_pending = 1.

Crea tabla nueva bib_drift_checks — ver [[entity—biblioteca—table—bib-drift-checks]].

Footgun D1: ALTER TABLE ADD COLUMN ... CHECK en SQLite solo valida filas nuevas/actualizadas. Las filas preexistentes no se re-verifican. Los defaults garantizan valores válidos en rows anteriores.

3. Script de backfill (scripts/migrate_kind_lifecycle.py · commit a7d9ec7)

Script Python idempotente (318 LOC) que asigna kind y lifecycle a los frontmatters YAML de las páginas .md en src/content/wiki/. Características clave:

• Dry-run por defecto; requiere --apply para escribir.
• Parseo manual conservador: no usa PyYAML/ruamel (evita reordenamiento alfabético y diff falso). Inserta solo las 2 líneas nuevas en la posición correcta.
• Preserva line endings: detecta CRLF vs LF por archivo.
• Idempotente: re-run con 449 páginas ya migradas = 0 cambios.
• Skips 14 metadocs sin frontmatter (catalog.md, index.md, log.md, etc.).

# Dry-run (default):
python scripts/migrate_kind_lifecycle.py

# Aplicar cambios:
python scripts/migrate_kind_lifecycle.py --apply

# Con detalle por archivo:
python scripts/migrate_kind_lifecycle.py --apply --verbose

Distribución resultante (post-backfill)

By kind:
  knowledge_base   421  (documentación intencional)
  knowledge_graph   28  (concept--general--* auto-archivados de bib_ask)

By lifecycle:
  refresh-90d     317  (concepts, features, entities, ia-tech)
  evergreen        67  (decision--, incident--, ia-tech--roles--)
  refresh-30d      37  (workspace--, entity--*--endpoint--, ia-tech--automatismos--)
  ephemeral-90d    28  (concept--general--* del knowledge_graph)

Test plan ejecutado

• pnpm astro sync OK con los 449 .md migrados (regex valida los 4 patrones de lifecycle reales).
• Migration 0024 validada en sqlite3 en memoria: 3 columnas nuevas + tabla bib_drift_checks + 5 índices sin errores.
• Backfill idempotente verificado: segundo run = 0 cambios.

Fases siguientes (s61)

• Fase 2: Cron drift check — Haiku revisa páginas con verification_pending = 1 y escribe en bib_drift_checks.
• Fase 3: Lint bulk — detecta páginas con lifecycle expirado y las marca como stale.
• Fase 4: Evolución Ingest — el agente activa verification_pending automáticamente en PRs que tocan sources[].

Véase también

• [[decision—20260514—knowledge-base-vs-graph]]
• [[entity—biblioteca—table—bib-drift-checks]]
• [[concept—biblioteca—supercontexto]]