Documentazione di COGO

COGO è tre volti sopra un’unica logica: un visualizzatore web per tutti, un server MCP per i tuoi agenti e una CLI per gli utenti esperti — tutti lo stesso singolo binario Go.

Volto	Per chi	Come
Visualizzatore web	tutti	cogo serve -http :8080 → browser (Vault · Freschezza · Pack · Grafo · Revisione · Guard · Veracità)
MCP	il tuo agente (Claude, Codex, Cursor, Gemini…)	cogo serve (stdio) oppure /mcp via HTTP — strumenti: pack search open capture verify archive restore remove guard xray
CLI	utenti esperti	cogo add · pack · search · stale · verify · lint · agents

Come viene calcolato il colore

confidenza = min( evidenza , freschezza , dipendenza più debole , contraddizione )

Una nota è verde solo quando niente la spinge verso il basso: evidenza osservata, un controllo superato, fresca, tutte le sue dipendenze verdi e nessuna contraddizione. Ogni colore porta con sé il suo color_reason, così puoi sempre verificare perché è finito così.

• L’evidenza fissa il tetto: osservata (un log, un comando, un test, un file) può arrivare al verde; riferita o dedotta si ferma al giallo; nessuna evidenza significa rosso.
• La freschezza decade per tipo: un comando dura 30 giorni; una decisione di architettura, 180.
• Modificare una nota cambia il colore — è proprio questo il punto. Il visualizzatore ricalcola il colore in tempo reale mentre scrivi: aggiungi evidenza osservata e diventa più verde; cambia l’affermazione e si azzera a “richiede nuova verifica”; premi verify (“l’ho controllato”) e diventa verde.

Anatomia di una nota

---
id: fisherboy-redis-hostname
type: bug                 # decision|bug|runbook|architecture|constraint|command|mistake
project: fisherboy
evidence:
  - kind: direct_log      # osservata → può arrivare al verde
    ref: "api log 2026-06-27T14:03Z: connect OK to redis:6379"
check:
  test: "leggi l'env effettivo del worker; verifica la connettività verso fisherboy-redis:6379"
  status: not_run         # passed | failed | not_run
last_verified: 2026-06-27
depends_on: [fisherboy-redis-topology]
# ---- calcolato da COGO · non modificare ----
confidence: yellow
color_reason: "evidenza osservata ma il controllo non è stato superato"
---

## Claim
Il worker probabilmente fallisce perché non riesce a risolvere l'hostname interno di Redis.

Il vault Markdown è l’unica fonte di verità: portabile, diffabile, e sopravvive allo strumento. Tutto il resto è un client sottile o una cache ricostruibile.

Il visualizzatore web

Le schede: Vault (le tue note, ciascuna con il suo colore), Freschezza (cosa sta scadendo, con un pulsante di riconvalida), Pack (assembla le note di un argomento in un blocco di contesto colorato da incollare a un’IA), Grafo (come si relazionano le note), Revisione (link rotti, note scadute, contraddizioni), Guard e Veracità.

Tutto ciò che è operativo vive nel menu kebab del visualizzatore — nessun terminale necessario: Connessioni MCP (emetti/revoca token con nome per app, con scadenza e una modalità di sola lettura), Cestino (ripristina o elimina per sempre), Audit MCP (chi ha chiamato quale strumento, quando, da quale IP), Radici delle evidenze (contro quale cartella si risolvono le evidenze di ogni progetto), Esporta (backup) (l’intero vault come zip, senza segreti), Istruzioni per gli agenti (genera l’AGENTS.md/CLAUDE.md che insegna il protocollo al tuo agente) e Impostazioni · Modello IA.

Guard, passo dopo passo

Guard risponde a una sola domanda: “questo turno del modello mi sta spingendo?”

1. Dichiara il tuo mandato (una volta sola): il tuo obiettivo e le tue linee rosse (“non mi dimetto senza un’altra offerta firmata”). Viene conservato nel vault. Senza un mandato, manipolazione e persuasione legittima sono indistinguibili — COGO allora si limita a nominare le tecniche, senza verdetto.
2. Incolla il turno (e la conversazione precedente, un messaggio per riga: U: tu, M: il modello) → una radiografia colorata: verde — nessun segnale; giallo — persuasione presente, o tocca la tua linea rossa; rosso — c’è meccanica, o ci sono prove.
3. Le prove sono il superpotere: poiché COGO vede la trascrizione, quando il modello nega ciò che ha detto (“non ti ho mai detto di dimetterti”) COGO trova il turno in cui l’ha detto DAVVERO e mostra entrambe le citazioni, fianco a fianco. Il gaslighting smette di essere la tua parola contro la sua.
4. Ogni tattica rilevata arriva con le sue domande critiche e la sua contromisura — il motore non censura il modello: inocula te. Lui mostra; tu decidi.

L’ontologia dietro: 108 tecniche di manipolazione distillate da sei discipline offensive — persuasione (Cialdini, Kahneman), interrogatorio di polizia e militare (tecnica Reid, Army FM 2-22.3, Scharff), negoziazione (Harvard, Voss), coercizione e riforma del pensiero (Lifton, Biderman), manipolazione emotiva (gaslighting, DARVO, FOG) e retorica/propaganda (Frankfurt, Grice, Walton) — ciascuna con la sua fonte reale, come appare in una chat, e la sua contromisura.

La regola di ferro

Nessun modello sentenzia “ti stanno manipolando”. I denti sono deterministici (marcatori, prove, traiettoria); i modelli si limitano a proporre — e ogni proposta viene verificata sul testo letterale o scartata. Con un modello collegato compaiono due livelli opzionali: proposte strutturali (pattern che nessun dizionario vede) e lo steelman avversariale — un altro modello che argomenta deliberatamente il lato che il turno non ti ha mostrato. Il quadro teorico è in docs/fundamento-teorico.md.

Veracità: solido, o fumo?

Il gemello di Guard. Dove Guard chiede “mi sta spingendo?”, la scheda Veracità (strumento MCP xray) chiede “questa risposta regge?”. Incolla la risposta di un modello e COGO la radiografa frase per frase, in modo deterministico, senza alcun modello: misura l’impegno (attenuato o fortemente asserito), l’evidenza (osservata, riferita o nessuna) e se è falsificabile (un’opinione travestita da fatto). Un’affermazione forte e senza fondamento esce in rosso; una solida con evidenza osservata, meglio. Documento di design: docs/motor-veracidad.md.

La CLI

cogo init                 # crea un vault
cogo add nota.md          # valida, calcola il colore, conserva (stdin se non c'è file)
cogo pack "redis"         # costruisce un contesto colorato per un argomento (degrada il rosso)
cogo search "worker"      # elenca: colore · id · riassunto (senza corpi)
cogo stale                # cosa è scaduto o sta per scadere
cogo verify <id>          # "l'ho controllato": riconvalida e ricolora
cogo lint                 # link rotti, note scadute, contraddizioni (se c'è un modello configurato)
cogo agents --claude      # genera il CLAUDE.md/AGENTS.md che insegna il protocollo a un agente
cogo serve -http :8080    # visualizzatore web + server MCP via HTTP
cogo serve                # server MCP via stdio

Accessori opzionali (disattivati per impostazione predefinita)

COGO è deterministico al 100% e standalone senza nulla di tutto questo. Ogni accessorio si abilita con una variabile d’ambiente e non tocca mai il nucleo:

Accessorio	Si abilita con	Per
Modello IA (OpenRouter, Ollama, DeepSeek…)	COGO_LLM_BASE_URL + COGO_LLM_MODEL (o Impostazioni nella GUI)	rilevare le contraddizioni tra note + i livelli opzionali di Guard
Giudice forte indipendente	COGO_LLM_STRONG_BASE_URL + COGO_LLM_STRONG_MODEL	perché lo steelman di Guard non condivida il cervello con il proponente
Scrub di Anonimal	ANONIMAL_URL	tenere segreti/PII fuori dal vault
Login Lockatus (OIDC)	AUTH_MODE=federado	federarsi con la Suite Escriba

Nota

Il dettaglio completo vive nel repository: il manuale per principianti, la guida di deploy completa (ogni variabile, backup, hardening) e i documenti di design dei motori di veracità e di autonomia.

Vedi su GitHub