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 — l’interfaccia è in spagnolo, quindi questi sono i nomi che vedrai davvero: Vault (le tue note, ciascuna con il suo colore: ricerca BM25, filtri, intervallo di date di creazione e paginazione), Vigencia (validità — cosa è scaduto o sta per scadere, con un pulsante di riconvalida), Agentes (agenti — scrivi e versiona l’AGENTS.md / CLAUDE.md che i tuoi agenti leggono all’avvio), Grafo (grafo — come si relazionano le note e come si propaga il rosso), Revisión (revisione — link rotti, note scadute, contraddizioni), Guard e Veracidad (veracità).

Puoi anche collegare un repository GitHub e navigarlo dal visualizzatore: albero dei file classico, o mappa a grafo colorata per fiducia che mostra quali parti del codice hanno conoscenza verificata alle spalle.

Tutto l’operativo vive nel menu kebab — senza terminale: Connessioni MCP (emettere e revocare token con nome per app, con scadenza e modalità sola lettura), Cestino, Audit MCP (quale token ha chiamato quale strumento, quando, da quale IP — scaricabile e potabile), Radici delle prove, Esporta (backup), Istruzioni per gli agenti 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.

Prove che vengono ricontrollate

La prova di una nota non è una sensazione: è un riferimento che COGO può andare a verificare di nuovo. Oltre ai percorsi locali, due schemi la rendono duratura:

evidence:
  - kind: command_output
    ref: github://acme/api@main/internal/db.go:88   # ancorata allo SHA del blob
  - kind: direct_log
    ref: artifact://9f2a…                           # indirizzata per contenuto, immutabile

I riferimenti a GitHub sono ancorati allo SHA del blob. Questo restituisce i denti al motore del colore su un’istanza ospitata (che non ha una copia di lavoro del tuo codice) e abilita la freschezza ancorata a git: la nota resta verde finché il file citato non cambia, e passa al giallo appena cambia. Cita un commit fisso e la prova diventa immutabile.

Gli artefatti (stash) sono conservati sotto lo SHA-256 del loro contenuto, su disco o su Cloudflare R2. Poiché la chiave è l’hash, verify lo ricalcola invece di fidarsi di una citazione che marcisce. Uno scanner di segreti gira prima di salvare qualsiasi cosa e si rifiuta per impostazione predefinita: una credenziale trapelata non viene mai immortalata.

Più agenti, un solo vault

Con MCP su HTTP e un token, agenti su macchine diverse condividono lo stesso vault:

• recall è il cursore che trasforma il vault da archivio a canale. Chiamalo senza argomenti e ottieni la memoria portante (il mandato, le decisioni verdi) più un cursore; restituisci quel cursore come since e ottieni solo ciò che è cambiato.
• lease prende un diritto a tempo su una risorsa prima di un lavoro rischioso e non idempotente — una migrazione, un deploy, una modifica di massa — così due agenti non lo eseguono insieme.
• Ogni nota registra chi l’ha catturata, e il visualizzatore filtra per agente.
• Il log di audit registra quale strumento ha chiamato ogni token, quando e da quale IP. Si può scaricare e potare, voce per voce o tutto insieme.

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