Sync Cascade · Propagación automática de drift entre docs vinculadas

Contexto y problema

Sesión 79 · 22-05-2026 · Edu verbalizó queja recurrente al cerrar los cherry-picks de Understand-Anything.

El equipo Esferic Labs cambia procesos con frecuencia (rotación herramientas, asignación responsabilidades, decisiones técnicas). Cada cambio debería propagarse a múltiples páginas wiki:

• Onboardings individuales (onboarding-edu, onboarding-dani, onboarding-txell).
• Procesos compartidos (team-processes, claude-method-sync).
• Documentos generales (sección equipo de CLAUDE.md en cada repo).
• Onboarding genérico (onboarding-template).

El patrón observado: el cambio se aplica en 1-2 docs (el que tocó la decisión) y los espejos quedan desincronizados hasta que alguien los lee semanas después por casualidad. Esto se ha repetido al menos 5 veces en las últimas 4 sesiones (s75-s78 auditorías masivas onboardings).

Lo que ya tenemos (no cubre el caso)

Brecha: drift transversal entre docs.

Propuesta: Sync Cascade

Sistema declarativo + reactivo que detecta cuando un doc-fuente cambia y notifica/actualiza los doc-espejo declarados.

Arquitectura

PR mergea cambio en wiki page → workflow detecta paths modificados
                                          ↓
                            Para cada path modificado:
                                          ↓
                Query D1: ¿qué páginas declaran mirrors: [<path>]?
                                          ↓
                Para cada espejo encontrado:
                          ┌───────────────┴───────────────┐
                          ↓                               ↓
              Fase 2 (MVP): marcar             Fase 3 (avanzado): Haiku
              verification_pending=true        lee diff fuente + escribe
              + entrada en Pulse               PR draft con cambios espejo

Schema extensions

Nuevo campo frontmatter mirrors (array de slugs):

---
title: Onboarding · Edu (CEO/Dev)
slug: workspace--onboarding--onboarding-edu
mirrors:
  - workspace--onboarding--onboarding-dani
  - workspace--onboarding--onboarding-txell
  - workspace--processes--team-processes
  - workspace--onboarding--onboarding-template
mirror_reason: "Cambios en herramientas/accesos del staff deben sincronizarse en los 3 onboardings + processes + template"
---

Semántica direccional: si A.mirrors = [B, C], un cambio en A propaga a B y C. NO bidireccional (los espejos pueden tener sus propios mirrors: independientes).

Detección de cascada circular: limit depth 2 (A→B→C OK, A→B→C→D ya no). Evita loops y limita ruido.

Plan de implementación (multi-fase)

Fase 0 · Diseño + schema (estimado 30 min)

• Decidir formato campo mirrors: (array de slugs, validación regex).
• Añadir validación al schema Astro de la wiki (src/content/config.ts): mirrors: z.array(z.string()).optional().
• Definir reglas de cascada: depth max 2, no self-reference, validación de slug existence en lint bulk.

Fase 1 · Detector post-merge (estimado 1h)

• Nuevo workflow .github/workflows/sync-cascade-detect.yml triggered on push a main con paths src/content/wiki/*.md.
• Script scripts/sync-cascade-detect.mjs:
  1. Obtener paths modificados del commit (git diff HEAD~1 HEAD --name-only).
  2. Para cada path, leer frontmatter del archivo en el HEAD anterior + actual.
  3. Query GitHub Actions API D1 (vía wrangler o MCP): SELECT slug FROM bib_wiki_pages WHERE json_extract(frontmatter, '$.mirrors') LIKE '%<modified_slug>%'.
  4. Output JSON con { modified: [...], mirrors_to_notify: [...] }.

Fase 2 · Marcado verification_pending (estimado 45 min)

• Handler MCP nuevo wiki_mark_mirror_pending(source_slug, mirror_slugs[]) que:
  1. UPDATE bib_wiki_pages SET verification_pending = true, mirror_changed_at = NOW(), mirror_source = ? para cada mirror_slug.
  2. Insert en bib_change_log con event_type = 'mirror_cascade'.
• El workflow Fase 1 llama al handler con los espejos detectados.
• Widget Pulse extends “Drift checks · 7d” con sección “Mirror cascades · 7d”: cuántas cascadas, cuántos espejos pendientes, top 5.

Fase 3 (opcional) · Haiku diff-aware PR drafts (estimado 1.5h)

• Handler MCP nuevo wiki_propose_mirror_update(source_slug, mirror_slug):
  1. Lee diff del source (HEAD~1 vs HEAD).
  2. Lee contenido actual del mirror.
  3. Llama Haiku con prompt “Propón los cambios equivalentes en este doc-espejo basándote en el diff del doc-fuente”.
  4. Output: nuevo contenido propuesto + razonamiento.
• Workflow Fase 1 (extendido): para cada mirror, llamar al handler + crear PR draft con el cambio sugerido + label sync-cascade:auto-proposed.
• Edu revisa y mergea con 1 click (o rechaza si Haiku se equivocó).

Fase 4 (opcional) · Sugerencia inverse al editar (estimado 2h, futuro lejano)

• En el editor de wiki del workspace: cuando un usuario edite un doc con mirrors:, mostrar banner “Este doc tiene 3 espejos. Si tu cambio toca proceso/decisión/asignación, considera replicar”.
• Optional: ofrecer “propaganda automática” en submit (vía Fase 3 endpoint).

Coste estimado

Coste total mínimo viable: 2h de implementación + $0/mes runtime. Coste alto valor: 3.5h + $0.5/mes.

Riesgos y mitigaciones

Criterios de éxito

A 1 mes de operativa Fase 0+1+2 (MVP):

• ≥10 docs con mirrors: declarados (al menos los 3 onboardings + team-processes + 5 docs más identificados).
• ≥80% de cambios en docs-fuente generan recordatorio en Pulse.
• ≥50% de mirror_pending se resuelven dentro de 1 semana (Edu/Dani/Txell ven el aviso y actúan).
• 0 incidentes “lo descubrí leyendo un doc 3 semanas después” reportados por Edu.

A 3 meses (con Fase 3 opcional activa):

• ≥30% de cascadas tienen PR draft auto-propuesto.
• ≥60% de PR drafts se mergean (señal de que Haiku acierta).

Docs candidatas iniciales (sugeridas para Fase 0)

Estos son los pares prioritarios identificados en s75-s78 auditorías:

Dependencias

• Sistema Bibliotecario operativo: ✅ ya tenemos bib_wiki_pages + bib_change_log + handlers MCP base.
• Pulse widget extensible: ✅ ya soporta nuevas secciones (drift-checks añadida s61 fase 5).
• GitHub Actions con D1 access: ✅ ya validado con wiki-catalog, audit-docs-drift, etc.
• Edu/Dani/Txell familiarizados con frontmatter: ✅ ya manejan kind, lifecycle, tags.

Próxima sesión · cómo arrancar

Mensaje sugerido para abrir la sesión:

“Sigamos con Sync Cascade. Lee feature--supercontext--sync-cascade y ejecuta Fase 0 (diseño schema).”

Y el plan se desarrolla naturalmente desde ahí.

Referencias

• Conversación origen: sesión 79 (22-05-2026 mañana) tras cierre cherry-picks Understand-Anything.
• ADR cherry-picks: [[decision—20260522—evaluacion-understand-anything-vs-bibliotecario]].
• ADR drift code↔doc (base lifecycle/tripwires): [[decision—20260514—knowledge-base-vs-graph]].
• Sistemas actuales relacionados: Lint bulk · Drift Check Haiku · Curator · bib_impact_query · widget Pulse.
• Memoria Edu: feedback_no_close_suggestion_strong (Edu decide cuándo arrancar, no Claude).

Estado

Planned — diseño completo, pre-implementación. No bloquea otras iniciativas. Estimación primer MVP funcional (Fases 0+1+2): ~2h sesión dedicada.

Véase también

• [[decision—20260514—knowledge-base-vs-graph]]
• [[decision—20260522—evaluacion-understand-anything-vs-bibliotecario]]