3.1 M1 — Motor

Núcleo de decisión contable de Intelia. Consume hechos con procedencia clara, contexto de cliente, memoria operativa, histórico de decisiones, políticas contables y snapshots del ERP. Produce un Internal Plan: una intención contable semántica, no ejecutable directamente contra Holded.

El Motor no sabe qué endpoint de Holded se llama. No sabe qué campo concreto acepta decimales o qué objeto debe crearse antes de otro. Sí sabe que una factura de proveedor debe reconocerse como gasto, que requiere una cuenta contable, tratamiento fiscal, posible proyecto/coste, contrapartida, fecha de devengo, y que ciertas anomalías bloquean automatización.

La decisión del Motor se apoya en tres roles LLM:

• LLM de interpretación documental: entiende documento, proveedor, concepto, importes, fechas, impuestos y señales textuales.
• LLM de decisión contable: propone cuenta, tratamiento fiscal, imputación, regla contextual y confianza.
• LLM crítico/validador: busca inconsistencias, riesgos, excepciones y razones para no automatizar.

Además, M1 incluye validación determinística previa y posterior: los LLMs no sustituyen invariantes (sumas, moneda, fechas, coherencia fiscal, compatibilidad con snapshots, límites de confianza, duplicados, restricciones de política).

Detalle completo en m1-motor.md

3.2 I1 — Integrador Holded

El mundo Holded. Recibe un Internal Plan y produce un ExecutionPlan Holded declarativo. Esta traducción no se implementa como una fase agnóstica de providers universales: la hace un agente LLM especializado en Holded con:

• guías textuales de Holded (markdown editable, sin semántica fiscal);
• wrapper de herramientas Holded (read estado, leer chart, leer locks);
• snapshots relevantes del SoR;
• Plan Store de patrones calcificados (cache + reglas promovidas);
• capacidad de explicar por qué una operación se traduce de una forma concreta.

El agente genera, no ejecuta. La ejecución pertenece a un executor determinístico y aburrido. Este executor solo interpreta un ExecutionPlan ya validado, invoca operaciones permitidas, registra resultados, hace idempotencia y devuelve outcome.

I1 contiene también validación final: antes de escribir, revisa que el plan sea compatible con el estado actual del ERP; después de escribir, verifica que el SoR quedó como se esperaba o que existe una desviación trazable.

Detalle completo en i1-integrator-holded.md

3.3 T3 — Calcification Engine

T3 convierte repetición aprobada en velocidad. Cuando el sistema produce el mismo plan, o uno suficientemente equivalente, para inputs similares, y el contable aprueba durante un periodo de sombra, T3 promueve el patrón a regla calcificada.

La calcificación no es una cache. Es una promoción gobernada. Requiere:

• equivalencia de inputs;
• estabilidad de output;
• aprobación humana;
• ausencia de ediciones relevantes;
• periodo de sombra contra el agente nuevo;
• métrica de drift;
• nivel correcto de regla (semántica, traducción, UX o señal).

Una regla atraviesa cinco estados de lifecycle:

candidate → shadow → active → quarantined → retired

Una vez active, la regla permite responder instantáneamente sin coste LLM para esa parte del pipeline. Pero nunca borra trazabilidad: cada aplicación de regla conserva versión, motivo, matching y posibilidad de invalidación.

Detalle completo en t3-calcification.md

3.4 T4 — Reverse Sync

T4 observa el SoR después de que Intelia escribe o propone. Su objetivo es aprender de la realidad operacional:

• el contable editó un asiento;
• añadió un comentario en Holded;
• cambió una cuenta;
• movió un documento;
• ajustó IVA;
• rechazó una automatización;
• corrigió proveedor / proyecto / coste;
• dejó una pista textual.

T4 no interpreta todo como verdad automática. Captura delta, lo atribuye, lo clasifica, lo contrasta con el plan original y produce señales estructuradas (Learning Signals). Algunas señales invalidan una regla calcificada. Otras recalibran histórico de proveedor. Otras son ruido o edición no semántica.

Sin T4, Intelia vuelve a depender de dashboards propios para saber si acertó. Con T4, Holded se convierte en interfaz de trabajo de alta confianza y fuente de feedback.

Detalle completo en t4-reverse-sync.md

3.5 S1 — UX Híbrido

La UX V3 tiene dos superficies:

• Intelia Dashboard "Planes Pendientes" para baja confianza, onboarding, excepciones, edición asistida, aprobación explícita y explicación.
• Holded para alta confianza y trabajo diario de contables maduros, con trazabilidad hacia Intelia mediante comentario, tag estructural o enlace al plan.

La transición no es binaria por cliente. Puede variar por proveedor, tipo de documento, regla, periodo, importe, confianza, antigüedad y estabilidad. Un cliente puede tener 90% auto-contabilizado en alquileres y 0% en gastos raros de importación.

Detalle completo en s1-ux-hybrid.md

3.6 TX — Signals + Temporal

TX es la capa transversal de orquestación, señales e historia operacional. Temporal no es el cerebro contable; es el mecanismo para ejecutar procesos durables, idempotentes, observables y recuperables.

TX coordina ingestión, ejecución de M1, generación y validación de ExecutionPlan, revisión humana cuando aplica, escritura en Holded, reverse sync, calcificación, reintentos, compensaciones y timeouts.

La señalización es first-class: cada decisión, validación, intervención humana, edición externa y aplicación de regla produce eventos consultables. V3 aprende porque conserva estructura, no porque guarde logs sueltos.

Detalle completo en tx-signals-temporal.md

4.1 Fact Bundle (input al Motor)

No es un modelo monolítico de "documento enriquecido". Es un paquete con secciones por owner:

Cada hecho debe poder decir: quién lo originó, cuándo, con qué confianza, desde qué documento o snapshot, y si es autoritativo, inferido o auxiliar.

4.2 Internal Plan (output del Motor)

Intención contable semántica, auditable y no ejecutable directamente. Incluye:

• clasificación del documento o evento;
• decisión contable propuesta (cuenta o familia de cuenta);
• tratamiento fiscal;
• imputaciones internas;
• excepciones;
• nivel de confianza;
• razones y evidencias;
• requisitos de revisión humana;
• validaciones pasadas y fallidas;
• constraints que el integrador debe respetar.

No incluye endpoints, IDs de operación Holded, secuencia exacta de API calls, workaround de contacto, payload final ni nombres de campos propios del ERP.

4.3 ExecutionPlan Holded (output del Integrador)

Declarativo pero específico de Holded. Describe qué operaciones se deben hacer en Holded y bajo qué precondiciones.

Debe incluir:

• objetivo de negocio;
• precondiciones observadas en Holded;
• operaciones permitidas y ordenadas;
• estrategia de idempotencia;
• expected state final;
• comentario / tag / enlace de trazabilidad;
• validaciones antes y después;
• fallback de bloqueo, no fallback silencioso;
• explicación de traducción.

No es una lista libre de comandos inventados por el agente. Debe ajustarse a una gramática pequeña y versionada que el executor determinístico entienda.

4.4 Execution Outcome (output del Executor)

El Outcome cierra el ciclo de escritura. Contiene:

• qué se intentó;
• qué se ejecutó;
• IDs del SoR;
• estado final observado;
• desviaciones;
• validaciones finales;
• señal para UX;
• señal para T3;
• señal para T4.

El Outcome es más importante que la respuesta de la API. Es la base para auditoría, aprendizaje e idempotencia.

4.5 Learning Signal (output de T4 y de S1)

Toda corrección humana o edición externa se convierte en señal estructurada cuando es posible:

• tipo de señal;
• nivel afectado (semántico / traducción / UX);
• entidad afectada;
• delta frente al plan original;
• confianza de interpretación;
• severidad;
• recomendación: ignorar, revisar, invalidar, recalibrar, promover.

La Learning Signal no aplica cambios por sí sola. Los aplican componentes propietarios: Motor, Plan Store, T3, configuración de cliente o guía operativa.

5.1 Visualización del flujo

5.2 Detalle paso a paso

1. Ingestión y extracción. El documento entra por email, upload, sincronización o ERP. El pipeline produce hechos extraídos y evidencias.
2. Construcción del Fact Bundle. TX agrega memoria, snapshot ERP, human_context y runtime. Conserva owner y frescura por sección.
3. Consulta T3 semántica. Antes de invocar el Motor completo, busca regla calcificada semántica aplicable por proveedor, tipo de documento, concepto, importe, cliente, periodo y condiciones.
4. Decisión M1. Si no hay regla semántica suficiente, el Motor ejecuta sus tres roles LLM y validaciones para producir un Internal Plan.
5. Validación M1. Reglas determinísticas y LLM crítico deciden si el plan es auto-contabilizable, requiere revisión o debe bloquearse.
6. Consulta T3 de traducción Holded. El integrador busca si existe una traducción calcificada para Internal Plans equivalentes.
7. Plan Generator Holded. Si no hay traducción calcificada suficiente, el agente Holded (con 3 roles internos: Planner + Tool Mapper + Critic) genera un ExecutionPlan específico.
8. Validación I1. El integrador comprueba precondiciones, estado actual del SoR, permisos, campos obligatorios, idempotencia y expected state.
9. Routing UX. Según madurez, confianza y reglas, el plan pasa a Pending Plans o se ejecuta automáticamente.
10. Aprobación o edición humana. En Pending Plans, el contable puede aprobar, editar, rechazar o comentar. La edición produce señal inmediata.
11. Ejecución determinística. El executor aplica el plan en Holded sin razonar. Si algo se desvía, bloquea o escala.
12. Validación final. Se lee Holded y se verifica que el estado final coincide con el expected state.
13. Trazabilidad en Holded. El asiento/factura/documento queda con comentario, tag o link hacia Intelia Plan ID.
14. Outcome y señales. TX emite eventos para auditoría, UX, T3 y T4.
15. Reverse Sync. T4 sigue observando Holded durante una ventana posterior y captura ediciones o comentarios.
16. Aprendizaje. T3 decide promoción, invalidación o recalibración con intervención humana cuando toca.

Detalle importante: la aprobación humana puede ocurrir antes de escribir en Holded o después, dentro de Holded. V3 no fuerza una única superficie de control.

Mes 0: modo aprendizaje visible

En un cliente nuevo, casi todo pasa por Pending Plans. El sistema debe maximizar explicación y captura de correcciones:

• mostrar Facts por owner;
• explicar decisión semántica;
• explicar traducción Holded;
• permitir editar antes de escribir;
• pedir motivo cuando la edición contradice una propuesta de alta confianza;
• registrar patrones para T3;
• mantener auto-ejecución desactivada salvo casos triviales.

El objetivo no es eficiencia inmediata. Es generar dataset del cliente y detectar diferencias de práctica contable.

Mes 1-3: automatización por islas

Empiezan a calcificarse patrones: proveedor recurrente, gasto simple, factura con estructura estable, misma cuenta y tratamiento fiscal, mismo flujo Holded, ausencia de ediciones.

La automatización se activa por isla, con shadow mode y comparación contra agente. Pending Plans se reduce para zonas estables, pero sigue siendo la interfaz de excepciones.

Mes 3-12: Holded como superficie principal para alta confianza

Cuando una isla alcanza estabilidad, Intelia puede escribir directamente en Holded. El contable trabaja en Holded y T4 observa:

• si no edita, se refuerza la regla;
• si edita, se genera señal;
• si comenta, se interpreta;
• si cambia patrón, se abre revisión.

La UX de Intelia se vuelve más de auditoría, cola de excepciones y explicación que de operación diaria.

Mes 12+: automatización mayoritaria y aprendizaje cruzado

Clientes maduros deberían tener 80-95% de documentos recurrentes auto-contabilizados, pero no por magia generalista. Lo logran por acumulación de reglas por cliente, proveedor, sector y tipo de documento.

El cross-bootstrap permite que un cliente nuevo de un sector arranque con reglas candidatas de otros clientes. Pero esas reglas no entran como verdad. Entran como:

• sugerencias calcificadas heredadas;
• menor umbral para shadow;
• explicación de precedentes;
• nunca auto-promoción sin validación local.

7.1 Plan Generator: agente único con 3 roles internos, no multi-agente

El Plan Generator de Holded se implementa conceptualmente como un agente único con tres roles internos, no como tres agentes independientes desde el principio:

• Planner: traduce Internal Plan a intención Holded.
• Tool Mapper: selecciona operaciones y datos concretos de Holded.
• Critic: verifica precondiciones, idempotencia y expected state.

Separarlo físicamente en sub-agentes demasiado pronto aumentaría latencia y superficie de coordinación. Mantener roles internos permite prompts y evaluaciones diferenciadas sin multiplicar infraestructura. Si en producción aparecen errores sistemáticos de tool mapping o crítica débil, entonces sí merece extraerlos.

El executor debe permanecer completamente fuera del agente. Si el agente puede escribir, se rompe la frontera más valiosa de V3.

7.2 T3: lifecycle asíncrono Temporal, no lookup con side effects

T3 es un sistema asíncrono gobernado por Temporal. El lookup de reglas activas sí es sincrónico y barato, pero la promoción, shadow comparison, invalidación, análisis de drift y revisión ops viven en workflows durables:

• una promoción puede tardar días;
• necesita ventanas de observación;
• depende de señales posteriores de T4;
• puede requerir aprobación humana;
• debe ser auditable.

T3 no debería ser una tabla rules con un contador. Eso produciría calcificación prematura. V3 necesita lifecycle explícito: candidate → shadow → active → quarantined → retired.

7.3 T4: feedback imperfecto clasificado, no conversación explícita

T4 trata Holded como una fuente de feedback imperfecta, no como conversación. Una edición en Holded puede significar:

• Intelia se equivocó;
• el contable aplicó criterio específico;
• el cliente pidió algo excepcional;
• el contable corrigió un dato externo;
• hubo una limitación de Holded;
• alguien tocó por accidente;
• una regla fiscal cambió;
• la propuesta era correcta pero incompleta.

Por eso T4 no debe auto-aplicar todo. Debe producir señales clasificadas con confianza. Las señales de alto impacto deben entrar en cola de revisión ops antes de modificar reglas activas.

Los comentarios de Holded son especialmente peligrosos: tienen mucha semántica y poca estructura. Se interpretan con LLM, pero la salida debe quedar tipada y revisable.

9.1 Menos agnosticismo, más verdad operacional

V3 acepta acoplamiento explícito a Holded en I1. Eso reduce elegancia arquitectónica pero aumenta capacidad de entrega. El riesgo es que Holded contamine el Motor. La mitigación es contrato Internal Plan estricto y revisión de las 5 reglas de oro en cada PR relevante.

9.2 Más LLM donde hay ambigüedad, menos LLM donde hay ejecución

El LLM decide y genera planes. No ejecuta. Esto asume que el coste y variabilidad del LLM son aceptables antes de calcificar. T3 reduce coste con el tiempo. El executor determinístico reduce riesgo de acciones irreversibles.

9.3 Aprendizaje con gate humano

La calcificación gobernada será más lenta que auto-learning. Es intencional. En contabilidad, una regla equivocada aplicada mil veces no es una mejora de producto; es deuda operativa y riesgo de confianza.

9.4 Holded como UX madura

Usar Holded como superficie principal evita obligar al contable a duplicar trabajo en Intelia. Pero también reduce control visual sobre la experiencia. T4 y trazabilidad estructural (link + tag + comment) son el precio para que esta decisión sea viable.

9.5 Plan Store dentro del integrador

Esto protege niveles, pero puede duplicar mecánicas de reglas entre Motor (M1.RuleStore) e integrador (I1.PlanStore). La mitigación es T3 común como framework de ciclo de vida, con stores propietarios por nivel.

9.6 Latencia vs coste vs control

Auto es mejor UX a largo plazo; dashboard es mejor señal de aprendizaje. No hay versión perfecta — hay calibración constante del umbral de confianza.

10.1 El Internal Plan se convierte en esperanto encubierto

Si el Internal Plan empieza a incluir primitivas ejecutables genéricas, V3 recrea el target V2. Mitigación: el Internal Plan debe describir intención y constraints, no operaciones. Cualquier campo que parezca POST_X o ENSURE_Y debe justificarse o moverse al integrador.

10.2 El integrador empieza a decidir semántica

El agente Holded puede sentirse tentado a corregir cuentas o tratamiento fiscal porque ve datos del ERP. Mitigación: guías Holded sin semántica, prompts con frontera explícita, validación que detecte cambios semánticos no autorizados, y tests de contrato.

10.3 T3 calcifica correlaciones falsas

Un proveedor puede parecer estable hasta que cambia el concepto. Mitigación: scopes estrechos, periodo de sombra, invalidación por T4, explicación de matching y umbrales conservadores al principio.

10.4 T4 genera demasiadas señales ruidosas

Si todo cambio en Holded se interpreta como aprendizaje, ops se satura. Mitigación: clasificación por severidad, ventanas de observación, deduplicación, sampling y colas separadas de "acción requerida" vs "telemetría".

10.5 La UX queda partida

Si algunas acciones se revisan en Intelia y otras en Holded sin trazabilidad clara, el contable pierde confianza. Mitigación: cada objeto escrito en Holded debe tener enlace/tag a Intelia, y Pending Plans debe mostrar qué pasó después.

10.6 Temporal se convierte en dominio

Temporal debe orquestar, no decidir. Mitigación: workflows finos en persistencia de estado operacional, actividades con servicios de dominio, señales tipadas y prohibición de lógica contable sustantiva en workflows.