--- type: RFI asset_id: RFI-XX-IntelliBanks-BlindajeGobernanzaSync-v01 version: v01 status: Abierto owner: Victor Heredia sherpa_owner: Jay responsable_implementacion: Alex (backend/app) + Equipo WORX (gobernanza) + Ops intellbank: IB-XX-Maestro fecha_creacion: 2026-07-02 fecha_ultima_actualizacion: 2026-07-02 prioridad: CRÍTICA proposito: Blindar IntelliBanks (app + sync + gobernanza) para que la integridad del vault compartido no dependa de la configuración de ningún usuario individual — de 6 a 100+ usuarios simultáneos sin caos. relacionado: RFI-XX-IntelliBanks-ManejoRutasDotfolders-v01, RFI-XX-IntelliBanks-NavInternaDashboards-v01 --- # RFI — Blindaje de Gobernanza + Sincronización de IntelliBanks **Request for Implementation · Estratégico** **Tripleta:** Owner: Victor Heredia · Sherpa: Jay · Implementan: Alex (backend/app) + Equipo WORX (gobernanza) + Ops **Prioridad:** 🔴 CRÍTICA · **Fecha:** 2026-07-02 --- ## 1. Resumen ejecutivo Con 6 usuarios ya nos "hacemos bolas" cada rato: un **solo** usuario mal configurado ensució el vault compartido de todo el equipo (archivos en ubicaciones incorrectas, duplicados en raíz, carpetas ocultas subidas). Con 100 usuarios simultáneos esto es un **caos garantizado**. La causa de fondo **no es un usuario** — es que **el sistema confía en el cliente**. Hoy la integridad del vault depende de que cada quien tenga la versión correcta del app, conecte la carpeta correcta y tenga su SherpaX bien configurado. Eso no escala. Se solicita rediseñar IntelliBanks bajo un principio **Zero-Trust del cliente**: la gobernanza se **enforcea en el servidor** y en el **agente de escritura**, nunca se asume. Es un problema de **harness engineering + gobernanza**, y su solución es un **binomio**: las reglas de WORX y las reglas de sincronización de IntelliBanks compartiendo **una sola fuente de verdad, enforceada en varias capas**. --- ## 2. Disparador — el incidente (2-jul-2026) Aparecieron en el vault compartido archivos fuera de norma (fuera de cualquier `IB-`), duplicados en raíz y mirrors de carpetas ocultas (`archivo.claude/`, `archivo.obsidian/`). Diagnóstico de Alex (chat 2-jul): > "Corrieron una sincronización con la versión anterior de la aplicación y se subieron archivos que no estaban en el último update." > "TODOS los archivos que se han estado subiendo en ubicaciones incorrectas vienen de **1 solo usuario**." > Tres motivos posibles: **(1)** corrieron una versión vieja del app, **(2)** instalaron el app y conectaron una carpeta de IntelliBanks **respaldada**, **(3)** el **SherpaX de su Cowork no está correctamente configurado** y pone archivos en ubicación incorrecta. **Lectura clave:** los tres motivos son fallas de **cliente**. Que cualquiera de ellos pueda corromper el vault de todos = **falta de enforcement central**. --- ## 3. Diagnóstico de causa raíz (sistémico) | Síntoma | Causa próxima (cliente) | Causa raíz (sistema) | |---|---|---| | Archivos fuera de `IB-` | SherpaX mal configurado escribe mal | El backend **acepta** cualquier ruta sin validar | | Duplicados en raíz / rutas aplanadas | App vieja o carpeta respaldada conectada | No hay **versión mínima** ni **flujo de import** controlado | | Dotfolders (`.obsidian`) subidos | Cliente sincroniza todo | No hay **lista de exclusión** central | | Un usuario contamina a todos | — | Sync bidireccional **sin cuarentena ni validación por escritura** | **Conclusión:** mientras el servidor acepte a ciegas lo que manda el cliente, cualquier usuario (hoy 6, mañana 100) puede romper el vault. La limpieza manual es un parche infinito. --- ## 4. Principio rector — Zero-Trust del cliente > **La integridad del vault NO puede depender de la configuración de ningún usuario.** > El cliente propone; el **servidor dispone**. Toda escritura se valida contra la gobernanza antes de aceptarse. Lo que no cumple se **rechaza o se pone en cuarentena** — nunca contamina el espacio canónico compartido. --- ## 5. Arquitectura de blindaje (defensa en profundidad) ### Capa 0 — Gobernanza-as-Code (el binomio WORX ↔ IntelliBanks) 🔑 Una **sola fuente de verdad** de reglas, legible por máquina y por agente, que alimenta a TODAS las capas: - Regla dura: **todo archivo vive bajo un `IB-*`**; la raíz solo tiene carpetas `IB-*` + metadata de la app. - Convención de naming BMF (`TIPO-ENTIDAD-Proyecto-Nombre-vNN`) y mapa de ubicaciones válidas por IntelliBank. - Exclusiones: dotfolders (`.obsidian/`, `.claude/`, `.git/`), basura (`.fuse_hidden`, `.DS_Store`), y prohibición de mirrors `archivo.*`. - Formato sugerido: un `governance.json`/`.yaml` canónico versionado en `IB-XX-Maestro`, del que derivan tanto el validador del backend como el prompt/skill del SherpaX. **Cambias la regla en un lugar, se enforcea en todos.** ### Capa 1 — Enforcement server-side (keystone) 🔑 El backend valida **cada escritura** contra la Capa 0 antes de persistir: - Rechaza (o **cuarentena** en `IB-XX-Maestro/_Quarantine//`) cualquier archivo fuera de `IB-`, con naming inválido, o en dotfolder. - **Nunca** coloca archivos en la raíz; reconstruye la ruta completa o cuarentena. - Deduplicación por hash: no crear segunda copia de un `skill_id`/hash existente. - **Atribución automática**: cada violación queda etiquetada con el usuario origen (como Alex rastreó a mano). ### Capa 2 — Versionado + rollback El app "supuestamente guarda versiones" — hay que **verificarlo, exponerlo y aprovecharlo**: - Confirmar que cada archivo mantiene historial de versiones recuperable. - **Rollback de sync**: poder revertir un evento de sincronización completo (ej. el sync malo del cliente viejo) a un punto anterior, sin pérdida. - Snapshots periódicos del estado canónico del vault (punto de recuperación del equipo). ### Capa 3 — Integridad del cliente - **Gating de versión mínima**: el backend **rechaza clientes por debajo de la versión requerida** (mata la causa #1). - **Flujo de import de respaldo controlado**: conectar una carpeta respaldada NO debe disparar sync crudo; debe pasar por un **import validado** (diff + validación de gobernanza + confirmación) (mata la causa #2). ### Capa 4 — Gobernanza write-time en el SherpaX / Cowork - El SherpaX de cada usuario carga el ruleset de la Capa 0 y **nunca** escribe fuera de `IB-` ni con naming inválido (mata la causa #3). - Materializar el **"Skill/GPT de reglas de IntelliBanks"** que propone Victor: un skill canónico que (a) el SherpaX consulta al escribir, (b) el usuario puede interrogar ("¿dónde va este archivo?"), (c) referencia la misma Capa 0. ### Capa 5 — Observabilidad + atribución - **Health/Governance check por usuario y central** (extender el skill `intellibanks-healthcheck` con auditoría de gobernanza): detecta cualquier cosa fuera de `IB-`, la atribuye y alerta. - Tablero de salud del vault del equipo: violaciones abiertas, por usuario, tendencia. --- ## 6. El "Skill/GPT de gobernanza" (respuesta a la propuesta de Victor) **Sí, es la pieza correcta — pero con un matiz:** no debe ser solo un skill "que sepa las reglas". Debe ser la **materialización de la Capa 0** que sirve a tres consumidores: 1. **Write-time (SherpaX):** el agente lo carga para colocar todo bien desde el origen. 2. **Sync-time (backend):** el validador del servidor lee las **mismas** reglas para rechazar/cuarentenar. 3. **Consulta humana:** cualquiera pregunta y obtiene la regla/ubicación. Si las reglas viven en 3 lugares distintos, divergen y vuelve el caos. **Una fuente, tres consumidores.** Ese es el binomio. --- ## 7. Criterios de aceptación (probar a escala, no con 6) - [ ] Un cliente con **versión vieja** no puede escribir en el vault compartido (rechazado por gating). - [ ] Conectar una **carpeta respaldada** pasa por import validado, no por sync crudo. - [ ] Un SherpaX mal configurado que intente escribir fuera de `IB-` es **rechazado/cuarentenado** en el servidor. - [ ] La **raíz** del vault compartido se mantiene solo con `IB-*` aunque N usuarios sincronicen a la vez. - [ ] Toda violación queda **atribuida** a su usuario automáticamente. - [ ] Un sync malo se puede **revertir** (rollback) sin pérdida. - [ ] Simulación con ≥20 clientes concurrentes (incluyendo 1 "malo") **no** contamina el espacio canónico. --- ## 8. Fases y responsables | Fase | Qué | Quién | |---|---|---| | 0 | **Gobernanza-as-Code**: escribir el ruleset canónico (`governance.json` + skill) | Equipo WORX (Jay/Victor) | | 1 | **Enforcement server-side** + cuarentena + atribución | Alex (backend) | | 2 | **Versionado/rollback** verificado y expuesto | Alex (backend) | | 3 | **Gating de versión** + flujo de import de respaldo | Alex (app) | | 4 | **SherpaX write-time governance** (skill de reglas) | Equipo WORX | | 5 | **Observabilidad/atribución** (health+governance check) | Ops (extiende `intellibanks-healthcheck`) | **Orden recomendado:** Fase 0 primero (la fuente de verdad) → Fase 1 (el keystone que corta el sangrado) → resto en paralelo. --- ## 9. Nota de enfoque Esto es **harness engineering + gobernanza**, no un fix puntual. Requiere inversión de tiempo dedicada (Victor sugiere correr el proceso con Fable). El entregable no es "limpiar otra vez" sino un **sistema que no se puede romper por un usuario**. Los RFI previos (`ManejoRutasDotfolders`, `NavInternaDashboards`) quedan como **sub-casos** que este blindaje resuelve de raíz. --- ## 10. Acción inmediata (mientras se implementa) El vault local de Victor quedó **limpio y completo** (2,379 archivos reales, raíz solo `IB-*`, validado contra respaldos 30-jun y 1-jul: nada real perdido). Para que este estado limpio sea la **verdad de la nube del equipo**, Alex debe **resetear/reemplazar la nube desde este estado** (no confiar en el auto-sync bidireccional, que volvería a jalar basura). Snapshot de respaldo: `outputs/Intellibanks-SNAPSHOT-*`. --- ## 11. Anexo A — Política de alcance de sincronización (decisión 3-jul-2026) Modelo **híbrido por tipo** (parte de la gobernanza-as-code, Capa 0). Define qué vive y se sincroniza en Intellibanks vs qué vive fuera. El sync parcial es **intencional**, no un bug — lo que se corrige es que la frontera sea **explícita y enforceada**, no silenciosa. | Categoría | Extensiones | ¿Sincroniza en Intellibanks? | Home canónico | |---|---|---|---| | Documentos de conocimiento | `.md` `.html` `.docx` `.pdf` `.pptx` `.xlsx` | ✅ Sí (ya funciona) | Intellibanks | | Datos | `.csv` | ✅ Sí (**agregar a allowlist**) | Intellibanks | | Motores / análisis clave | `.py` | ✅ Sí (**agregar a allowlist**) | Intellibanks | | Skills / plugins | `.skill` `.plugin` `plugin.json` `team-settings.json` | ❌ No | Plugin Marketplace WORX | | Código pesado / proyectos | repos de código | ❌ No | git | | Config regenerable | `.json` de estado (`rally_progress`, etc.) | ❌ No | local / regenerable | **Ask concreto a Alex:** agregar **`.csv` y `.py`** al *allowlist de sincronización* del app. El resto (skills/plugins) se distribuye por el marketplace; el código serio por git. **Nota técnica:** `SKILL.md` (markdown) ya sincroniza como documento; lo que no baja es el empaquetado `.skill`/`.plugin` y los `plugin.json` — responsabilidad del marketplace, no del vault. Cuando el app enforce el allowlist, un tipo fuera de política se **rechaza/cuarentena** (Capa 1), no se pierde en silencio. --- *Generado con el diagnóstico de Alex (2-jul) y la visión de escala de Victor. Alcance de sync definido 3-jul. Owner: Victor Heredia · Sherpa: Jay.*