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:

Columna	Tipo	Default	Constraint
`kind`	TEXT NOT NULL	`'knowledge_base'`	`CHECK (kind IN ('knowledge_base','knowledge_graph'))`
`lifecycle`	TEXT	NULL	— (validación en Astro + bib_ingest.py)
`verification_pending`	INTEGER NOT NULL	`0`	`CHECK (verification_pending IN (0, 1))`

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