Documentación de COGO

COGO es tres caras sobre una misma lógica: un visor web para todos, un servidor MCP para tus agentes y una CLI para usuarios avanzados — todo el mismo binario Go.

Cara	Para quién	Cómo
Visor web	todos	cogo serve -http :8080 → navegador (Vault · Frescura · Pack · Grafo · Revisión · Guard · Veracidad)
MCP	tu agente (Claude, Codex, Cursor, Gemini…)	cogo serve (stdio) o /mcp por HTTP — herramientas: pack search open capture verify archive restore remove guard xray
CLI	usuarios avanzados	cogo add · pack · search · stale · verify · lint · agents

Cómo se calcula el color

confianza = min( evidencia , frescura , dependencia más débil , contradicción )

Una nota es verde solo cuando nada la empuja hacia abajo: evidencia observada, un check que pasó, fresca, todas sus dependencias en verde y sin contradicciones. Cada color lleva su color_reason, así que siempre puedes auditar por qué terminó como terminó.

• La evidencia pone el techo: lo observado (un log, un comando, un test, un archivo) puede llegar a verde; lo reportado o inferido topa en amarillo; sin evidencia es rojo.
• La frescura decae por tipo: un comando dura 30 días; una decisión de arquitectura, 180.
• Editar una nota cambia el color — de eso se trata. El visor recalcula el color en vivo mientras escribes: agrega evidencia observada y se pone más verde; cambia la afirmación y se reinicia a “necesita re-verificación”; presiona verify (“lo comprobé”) y pasa a verde.

Anatomía de una nota

---
id: fisherboy-redis-hostname
type: bug                 # decision|bug|runbook|architecture|constraint|command|mistake
project: fisherboy
evidence:
  - kind: direct_log      # observada → puede llegar a verde
    ref: "log de la api 2026-06-27T14:03Z: connect OK a redis:6379"
check:
  test: "leer el env efectivo del worker; probar conectividad a fisherboy-redis:6379"
  status: not_run         # passed | failed | not_run
last_verified: 2026-06-27
depends_on: [fisherboy-redis-topology]
# ---- calculado por COGO · no editar ----
confidence: yellow
color_reason: "evidencia observada pero el check no ha pasado"
---

## Claim
El worker probablemente falla porque no puede resolver el hostname interno de Redis.

El vault de Markdown es la única fuente de verdad: portable, diffeable, y sobrevive a la herramienta. Todo lo demás es un cliente delgado o una caché reconstruible.

El visor web

Las pestañas: Vault (tus notas, cada una con su color), Frescura (qué está por vencer, con un botón de revalidar), Pack (arma las notas de un tema en un bloque de contexto coloreado para pegar a una IA), Grafo (cómo se relacionan las notas), Revisión (enlaces rotos, notas vencidas, contradicciones), Guard y Veracidad.

Todo lo operativo vive en el menú kebab del visor — sin necesidad de terminal: Conexiones MCP (emitir/revocar tokens con nombre por app, con vencimiento y un modo de solo lectura), Papelera (restaurar o borrar para siempre), Auditoría MCP (quién llamó qué herramienta, cuándo, desde qué IP), Raíces de evidencia (contra qué carpeta se resuelve la evidencia de cada proyecto), Exportar (backup) (todo el vault como un zip, sin secretos), Instrucciones para agentes (genera el AGENTS.md/CLAUDE.md que le enseña el protocolo a tu agente) y Ajustes · Modelo de IA.

Guard, paso a paso

Guard responde una sola pregunta: “¿este turno del modelo me está empujando?”

1. Declara tu mandato (una vez): tu objetivo y tus líneas rojas (“no renuncio sin otra oferta firmada”). Se guarda en el vault. Sin mandato, la manipulación y la persuasión legítima son indistinguibles — COGO entonces solo nombra técnicas, sin veredicto.
2. Pega el turno (y la conversación previa, un mensaje por línea: U: tú, M: el modelo) → una radiografía coloreada: verde — sin señales; amarillo — hay persuasión, o toca tu línea roja; rojo — hay mecánica, o hay recibos.
3. Los recibos son el superpoder: como COGO ve la transcripción, cuando el modelo niega lo que dijo (“yo nunca te dije que renuncies”) COGO encuentra el turno donde SÍ lo dijo y muestra ambas citas, lado a lado. El gaslighting deja de ser tu palabra contra la suya.
4. Cada táctica detectada llega con sus preguntas críticas y su contramedida — el motor no censura al modelo: te inocula a ti. Él muestra; tú decides.

La ontología detrás: 108 técnicas de manipulación destiladas de seis disciplinas ofensivas — persuasión (Cialdini, Kahneman), interrogatorio policial y militar (técnica Reid, Army FM 2-22.3, Scharff), negociación (Harvard, Voss), coerción y reforma del pensamiento (Lifton, Biderman), manipulación emocional (gaslighting, DARVO, FOG) y retórica/propaganda (Frankfurt, Grice, Walton) — cada una con su fuente real, cómo se ve en un chat, y su contramedida.

La regla de hierro

Ningún modelo dictamina “te están manipulando”. Los dientes son deterministas (marcadores, recibos, trayectoria); los modelos solo proponen — y cada propuesta se verifica contra el texto literal o se descarta. Con un modelo conectado aparecen dos niveles opcionales: propuestas estructurales (patrones que ningún diccionario ve) y el steelman adversarial — otro modelo argumentando deliberadamente el lado que el turno no te mostró. El marco teórico está en docs/fundamento-teorico.md.

Veracidad: ¿sólido, o humo?

El gemelo de Guard. Donde Guard pregunta “¿me está empujando?”, la pestaña Veracidad (herramienta MCP xray) pregunta “¿esta respuesta se sostiene?”. Pega la respuesta de un modelo y COGO la radiografía oración por oración, de forma determinista, sin ningún modelo: mide el compromiso (matizado o fuertemente aseverado), la evidencia (observada, reportada o ninguna) y si es falsable (una opinión disfrazada de hecho). Una afirmación fuerte y sin sustento sale en rojo; una sólida con evidencia observada, mejor. Documento de diseño: docs/motor-veracidad.md.

La CLI

cogo init                 # crear un vault
cogo add nota.md          # validar, calcular el color, guardar (stdin si no hay archivo)
cogo pack "redis"         # armar un contexto coloreado para un tema (degrada lo rojo)
cogo search "worker"      # listar: color · id · resumen (sin cuerpos)
cogo stale                # qué está vencido o por vencer
cogo verify <id>          # "lo comprobé": revalidar y recolorear
cogo lint                 # enlaces rotos, notas vencidas, contradicciones (si hay modelo)
cogo agents --claude      # generar el CLAUDE.md/AGENTS.md que le enseña el protocolo a un agente
cogo serve -http :8080    # visor web + servidor MCP por HTTP
cogo serve                # servidor MCP por stdio

Accesorios opcionales (apagados por defecto)

COGO es 100% determinista y standalone sin nada de esto. Cada accesorio se habilita por variable de entorno y nunca toca el núcleo:

Accesorio	Se habilita con	Para
Modelo de IA (OpenRouter, Ollama, DeepSeek…)	COGO_LLM_BASE_URL + COGO_LLM_MODEL (o Ajustes en la GUI)	detectar contradicciones entre notas + los niveles opcionales de Guard
Juez fuerte independiente	COGO_LLM_STRONG_BASE_URL + COGO_LLM_STRONG_MODEL	que el steelman de Guard no comparta cerebro con el proponente
Scrub de Anonimal	ANONIMAL_URL	mantener secretos/PII fuera del vault
Login de Lockatus (OIDC)	AUTH_MODE=federado	federarse con la Suite Escriba

Nota

El detalle completo vive en el repo: el manual para principiantes, la guía de despliegue completa (cada variable, backup, endurecimiento) y los documentos de diseño de los motores de veracidad y autonomía.

Ver en GitHub