E5 — Arquitectura cognitiva: cómo se implementa la experiencia
Este documento se escribió DESPUÉS de congelar la experiencia (E2/E3) y deriva la arquitectura de ella — no al revés. Todo aquí es[SUGERENCIA] salvo lo marcado [REQUISITO].
1. Lo que la experiencia exige del sistema
De E2/E3 se derivan siete capacidades, y cada una señala a quién debe pertenecer:
El lema [REQUISITO]: el modelo interpreta y propone; el código valida y autoriza. La versión actual violó la primera mitad (código interpretando significado); la tentación clásica viola la segunda (modelo con autoridad). Ninguna de las dos.
2. La topología: un director, contratos que gobiernan, workflows que ejecutan
2.1 El TurnIntent — el contrato clave nuevo
El director emite exactamente UN intent tipado por turno (más su narración). Vocabulario inicial:responder con salida útil; (3) la pregunta propuesta pasa por el gobernador: si el libro de hechos marca el campo como dicho|recordado, veto + telemetría (así el re-preguntar se vuelve estructuralmente imposible, no solo desaconsejado); (4) la autoridad de gasto sigue EXACTAMENTE en la maquinaria actual de quotes — el director solo puede proponer una decisión, nunca resolverla.
(5) Referencias estructuradas obligatorias [REQUISITO]. El TurnIntent lleva, junto a la narración, las referencias que la sostienen: los ids de las filas del tablero, las métricas y las evidencias sobre las que el turno afirma algo. La capa de gobierno resuelve cada referencia contra el estado validado del turno; una referencia que no resuelve invalida la narración (reparación acotada → degradación a la variante sin cifras), nunca se muestra. Corolario duro: narración, tablero y acciones se derivan de los MISMOS objetos. El director no puede emitir prosa factual — un conteo, una organización, una fecha, un monto, un costo — que no esté anclada a un objeto que el tablero también muestra. Esto es lo que hace estructuralmente imposible la divergencia texto⇄tablero (E7-17) y la cifra inventada, sin depender de que el modelo se porte bien.
2.2 El mapa de cobertura cliente-seguro — la pieza que mata la narración de catálogo
[REQUISITO] El director NUNCA recibe elCapabilityBundle crudo (hoy: 12 KB con capability_id, cadence, limitations, expected_cost_usd — la materia prima del reporte de inventario). El servidor proyecta:
list_connections entrega next_action de operador — eso desaparece de este contexto).
2.3 El libro de hechos (known-facts ledger)
Compilado por el servidor cada turno (extiende el Commercial Context Compiler existente): cada campo del encargo con valor + procedencia + turno de origen (dicho@t1 | perfil | inferido@t2 | faltante). Usos: (a) el eco del encuadre lo lee; (b) el gobernador veta preguntas sobre lo sabido; (c) los conflictos (perfil≠mensaje) se detectan aquí y generan la única pregunta legítima de tipo conflicto; (d) E7 lo usa como oráculo de “re-preguntó lo sabido”.
3. Veredicto sobre cada candidato de la lista
4. El turno, de punta a punta (reemplaza las escaleras de regex)
- El preflight regex actual (
classifyChatRoute/classifyIntent) deja de decidir el destino del turno. Puede sobrevivir como hint barato en la entrada del director y como guardia de producto (p. ej. bloquear la superficie comercial para pedidos no comerciales), pero la ruta la decide el director con el turno completo. Muere la asimetría “leads está en una escalera y no en la otra”. synthesisOnlymuere. El director siempre tiene su cinturón corto; la seguridad viene de que las herramientas están proyectadas y la autoridad es del código — no de amordazar al modelo.- El presupuesto por turno se conserva (deadline, max steps) y se instrumenta por intent.
5. Las preguntas explícitas del equipo
5.1 ¿Un “Market Intelligence Skill”? — Sí: uno, y es el manual del director
Un solo skill (= system prompt + referencias cargables) que ES el manual de operación del trabajo comercial: identidad y voz (E2 §voz), el modelo del encargo, cómo razonar cobertura sobre el mapa, la política de preguntas (su lado modelo), los contratos de cada estado (E3), y las reglas de honestidad evidencial. Con progressive disclosure por etapa, no por fuente: el núcleo es corto; las secciones de investigación web, monitores y contactos se cargan cuando la sesión entra a esa etapa (server-side, por estado de la sesión — no por decisión del modelo). Advertencia frontal [REQUISITO]: un skill NO arregla identidad por sí solo — la versión actual ya era “commercial intelligence assistant” y narró catálogo igual, porque el resto del sistema lo contradecía. El skill solo funciona acoplado al TurnIntent, al mapa proyectado y al gobernador. Prohibido resolver defectos de comportamiento “agregando un párrafo al skill”: cada regla nueva de comportamiento nace como eval (E7) o como validación de la capa de gobierno.5.2 ¿Skills separados para web research / monitores / contactos? — No
Son etapas del mismo trabajo con políticas propias, no trabajos distintos. Separarlos en skills con triggers propios fragmenta la identidad (¿quién contesta cuando el usuario mezcla “búscame clientes y avísame si sale algo nuevo”?) y reintroduce el riesgo de under-triggering que ya sufrieron (rutas clasificadas sin dueño). Cada etapa aporta: una sección del manual (cargada por estado), sus checkpoints tipados (ya congelados) y su maquinaria determinística (ya construida). La frontera dura no es el skill: es el checkpoint.5.3 ¿Referencias por capability? — Sí, como DATOS que viajan con el catálogo
Cada capability puede llevarnotas_estrategia redactadas cliente-seguro (ejemplo para compras públicas: “la fase importa: convocatoria abierta = urgencia por fecha de cierre; adjudicada = el ángulo es el ganador y sus subcontratistas; el monto publicado ≠ monto final”). El servidor las inyecta en el mapa de cobertura SOLO cuando esa capability está en juego. Así el conocimiento por señal escala como datos versionados, no como prompts ni código. Es la respuesta correcta a “¿cómo sabe el director vender bien cada tipo de señal?” sin explotar el prompt.
Dónde viven [REQUISITO] (corregido tras revisar el warehouse — ver 09-revision-warehouse.md §3): el contrato del catálogo (Market Intelligence 1.0) está congelado con additionalProperties: false en ambos niveles y verificado byte-a-byte contra un manifest hasheado. notas_estrategia NO modifica ese contrato — ni ahora ni como paso intermedio. Fase 1 (la única en alcance): las notas viven en un sidecar versionado dentro de la capa de proyección de Driftless, un archivo de datos keyed por (capability_id, catalog_version) con su propia versión de sidecar; el proyector lo hace join contra el bundle después de validarlo, y si una clave no existe la nota simplemente no viaja (ausencia nunca es error). Dueño: producto; cero coordinación cross-repo; cero riesgo para el bundle-check. Fase 2 (opcional, fuera de alcance): graduarlas al catálogo en un contrato v1.1 con su bump de manifest y transferir la autoría a quien opera el warehouse.
5.4 ¿Metadata/manifests por fuente en lugar de skills por fuente? — Sí, rotundo y ya es así
La arquitectura actual acertó por completo aquí y no se toca: las fuentes viven como source packs + manifests + recipes en el warehouse (repo aparte), invisibles tras el gateway de 3 funciones. Una fuente jamás será un skill, un prompt, una rama de código en Driftless ni un concepto de UI. Añadir la fuente 22 no toca ni al director, ni al shell, ni a este doc-set — ese es el test de escala del §4.0 del workbench doc, que confirmamos como invariante.6. El modelo que ejecuta al director [SUGERENCIA con tradeoff]
Hoy: DeepSeek v4-flash primario (thinking off por defecto), gpt-5.6-luna como fallback, sin json_schema en el primario. Riesgo a nombrar sin rodeos: el director ES el producto, y los turnos donde se juega (encuadre, estrategia, steering, cierre honesto) son pocos por sesión (~3–6) pero de juicio denso. Optimizar esos turnos por costo de inferencia es optimizar lo barato a costa de lo caro (churn de usuarios).
Recomendación: (a) thinking encendido para intents encuadre|steering|proponer_decision|cierre (acotado; el cache salt por workspace ya existe); (b) correr E7 contra ambos tiers y decidir con datos — si flash no pasa E7-01/02/09, el director sube de tier y la narración mecánica (títulos, resúmenes de refresco) se queda en el barato; (c) exigir json_schema (structured outputs) para TurnIntent en el tier que lo soporte — la validación fail-closed ya existe, pero el modo prompted del primario pagará más reparaciones. El costo real del producto está en la investigación pagada y en el churn, no en estos ~6 turnos.
7. Qué NO construir (anti-arquitectura)
- Sociedad de agentes (investigador + crítico + redactor conversando): coste/latencia sin evidencia de mejora para ESTE trabajo; la verificación adversarial que sí importa (evidencia, contradicciones) ya es determinística.
- Skills por fuente o por proveedor (§5.4).
- Memoria vectorial del workspace para el director: el contexto necesario es pequeño y estructurado (perfil + libro de hechos + tablero); los embeddings solo introducen autoridad difusa.
- Generative UI abierta: el registry de artifacts/acciones allowlisted se mantiene (todo payload validado — A1 ya lo garantiza).
- Un segundo dueño del estado (CopilotKit u otro runtime paralelo al Work Session): la decisión previa del equipo era correcta; assistant-ui como primitivas de interacción con External Store, el servidor como única autoridad.
- Prompt-engineering como sistema de control: el prompt del director es corto y estable; el control vive en contratos, gobernador, gates y evals. (El síntoma a vigilar: si un PR “arregla” comportamiento editando solo el skill, exigir el eval que lo pruebe.)