Alla chiusura della microprogettazione, i 19 doc esistenti in
docs/architecture/ sono stati letti uno a uno e confrontati
incrociatamente per stanare incongruenze prima che il codice le pietrifichi.
Questo doc è il referto, non una nuova decisione di design.
Il perimetro della review: i 17 doc della lista canonica di
Prospettive & Giudizio §8
più i 2 doc di estensione (types.html, rl_offline.html).
Totale: 19 HTML.
Il metodo: per ogni doc estrai (i) Protocol/classi, (ii) tipi cross-componente citati, (iii) eccezioni, (iv) decisioni chiave, (v) link uscenti, (vi) callout "DECISIONE DA CONFERMARE". Poi confronta tutti-con-tutti cercando cinque forme di frizione:
| Categoria | Criterio | Severità |
|---|---|---|
| Incongruenza forte | Stesso concetto definito in modo conflittuale in due o più doc. Blocca l'implementazione. | alta |
| Gap | Tipo o concetto citato ma non definito in nessun doc, oppure link rotto a doc atteso. | media |
| Ridondanza | Stesso meccanismo spiegato in più posti senza fonte canonica dichiarata. | bassa |
| Tensione accettata | Già esplicitata in uno dei doc come trade-off vissuto. Non riaprire. | ok |
| Coerenza forte | Cross-reference che funziona: la stessa idea riemerge invariata in più doc. | ok |
Prima dei referti puntuali, una vista d'insieme. I quattro tipi cross-componente più attraversati sono stati tracciati contro i doc che li nominano. Ogni cella è colorata secondo lo stato di coerenza tra i doc coinvolti.
Sei casi. Per ciascuno: descrizione, doc coinvolti, rimedio proposto. La severità è alta per tutti: vanno risolti prima di iniziare l'implementazione dei componenti coinvolti.
ExecutionTrace frammentato altaagent_runtime.html · eval.html · memory.html · observability.html · types.htmlagent_runtime la dichiara "fonte unica di verità". observability
la serializza come JSONL append-only. memory dice che "vive dentro
ExecutionTrace del turno" per la working memory, e che a fine turno
promuove step a episodi. eval riusa l'oggetto per il replay.
Nessuno dei cinque doc definisce chi crea, chi chiude (marca
immutabile), chi persiste, e in quale ordine.
types.html come fonte canonica dello schema e agent_runtime.html come fonte canonica del ciclo di vita. Aggiungere un diagramma di stato (open → steps_appended → closed → persisted → promoted) a agent_runtime.html. Gli altri doc si limitano a citare.gateway.html §4.1 · approval_ux.html §8gateway.html riga 500 fissa timeout_at = now + APPROVAL_TIMEOUT
con commento "default 15 min". approval_ux.html §8 definisce
invece una tabella per-canale: CLI 30s, Telegram DM 2 min, canale di casa 5 min,
voce 15 s. Sono numeri incompatibili.
approval_ux è il default corretto (è stata disegnata pensando al canale). Correggere il commento di gateway.html: timeout_at viene calcolato dal Channel, non dal Gateway, tramite un metodo default_approval_timeout() sul Protocol Channel. Il Gateway riceve un timedelta, non hardcoda 15 min.PlannedAction vs ApprovalRequestDraft: due nomi per una cosa sola? altatypes.html §4.1 · constitution.html §9 · gateway.html §4.1 · policy.htmltypes.html definisce PlannedAction come input di
Policy.check(). constitution.html la usa nello stesso
senso. Ma gateway.html §4.1 introduce ApprovalRequestDraft
come output della Policy, che il Gateway converte in
ApprovalRequest. Dai doc non è chiaro se sia lo stesso oggetto
rinominato, un super-tipo, o una seconda entità.
types.html: (a) PlannedAction è l'input, ApprovalRequestDraft = PlannedAction + decision_hint dal Policy; (b) sono la stessa classe con un campo opzionale policy_decision. Opzione (a) è più pulita ma richiede un nuovo tipo; opzione (b) è più snella. Default conservativo: (a).synapse.html · neuron.html §6 · rl_offline.html · policy.htmlsynapse.html definisce "utility = gap_pre − gap_post" per-sinapsi.
neuron.html registra gli esiti nel journal per-neurone.
rl_offline.html introduce TrustStore come aggregatore.
Ma policy.html non ne cita nessuno: una Policy che non guarda la
fitness è una Policy cieca rispetto alla selezione darwiniana.
policy.html, aggiungere una sotto-sezione "input di fiducia" dove si documenta che Policy.check() riceve lo TrustScore corrente del neurone (se è un neurone) e può usarlo per alzare o abbassare la soglia di approvazione. Formula aggregata documentata in rl_offline.html.gateway.html · channel.html · memory.htmlgateway.html "crea e gestisce sessioni". channel.html
non menziona sessioni: un messaggio entra come InboundMessage(sender,
channel, body), il mapping a session_id è invisibile.
memory.html non dice se episodic è indicizzata per-sender o
per-session. Quando un utente apre un nuovo turno, come la memoria episodic
viene richiamata?
gateway.html, aggiungere una sotto-sezione "chiave di binding": session_id = hash(sender, channel, window) dove window è chiuso per idle timeout (§8 del gateway). In memory.html, specificare che episodic è indicizzata per sender (non per session), semantic è globale, working muore con la session.observability.html · gateway.html · neuron.html §6 · synapse.htmlobservability.html dichiara il journal append-only JSONL come
componente centrale. Ma gateway.html descrive la persistenza di
ExecutionTrace a fine turno; neuron.html §6 tiene un
co_activations.sqlite per-neurone; synapse.html ha un
grafo con contatori. Quattro journal, nessuno dichiarato "ombrello".
observability.html, aggiungere un capitolo "sorgenti di verità" con questa gerarchia: (1) audit.jsonl append-only è la sorgente ombrello di eventi; (2) traces/*.json è il rollup immutabile per-turno; (3) il journal per-neurone e il grafo sinaptico sono derivati che possono essere ricostruiti da (1) + (2) in caso di perdita. Chi scrive cosa → tabella.Tipi o concetti citati nei doc ma non definiti in nessun posto. Severità media: si possono tollerare per qualche settimana, ma ogni implementazione che li incontra deve stoppare e chiedere.
FactProposal / MemoryFact non ha schemamemory.html §6 · Atteso in: types.htmlmemory.html descrive la reflection che produce "proposte di fatto" soggette ad approvazione umana. Il tipo Python di queste proposte non esiste. È str? un dict? un oggetto con confidence?
types.html: FactProposal(text, category, confidence, source_trace_ids, proposed_at). MemoryFact = FactProposal + approved_at + approver.memory.html §7 · synapse.htmlmemory.html cita "decay · days_since_last_access" senza il valore. synapse.html ha Ebbinghaus/ACT-R come ispirazione ma non fissa la costante. Sono due decadimenti indipendenti o derivano dalla stessa base?
synapse.html fissare una tabella di costanti (Ebbinghaus k=0.05/die per episodic, forse molto più lento per semantic). memory.html cita la tabella di synapse.html come fonte.policy_denied non specificatoagent_runtime.html §4 · policy.htmlagent_runtime documenta "2 retry massimi su validation error". policy.html non cita retry: che succede quando un'azione viene negata due volte di fila? Autoban del neurone? Escalation a utente?
policy.html: dopo 2 policy_denied consecutivi sullo stesso tool, escalation a "richiesta chiarimento" verso l'utente. Non autoban (il neurone può avere un uso legittimo in altro contesto).agent_runtime.html §3 · memory.htmlLa sintesi via LLM "oltre 20 turni" è citata ma non è chiaro se avviene (a) all'ingresso del 21° turno prima del prompt, (b) a fine del 20° turno come preprocessing asincrono, (c) on-demand quando il context overflow si profila.
agent_runtime.html §3 esplicitamente.neuron.html §7Estinto → .audit/neurons_extinct/. Il file è recuperabile manualmente? Se sì, come; se no, è delete logico e basta dirlo.
neuron.html: estinzione è delete logico con retention 90 giorni. Resurrezione richiede comando esplicito dell'utente (neuron resurrect <id>) e rigenera una nuova firma (il vecchio journal è preservato come read-only).agent_runtime.html §6 · config.html §4 · constitution.htmlI cap 2€ soft / 5€ hard sono in agent_runtime. config.html li rende configurabili. constitution.html non dice se un override di config possa violare una Legge (es. Legge di omeostasi). Fatto di policy non banale.
constitution.html: i budget sono parametri, non Leggi. Il cap hard è però limitato dall'alto da un "cap costituzionale" (es. 20€/die) hardcoded che la config NON può superare. Documentarlo come nota nell'articolo che introduce la Legge 0.neuron.html §6 · synapse.htmlEntrambi registrano co-attivazioni. Uno è la sorgente, l'altro è un rollup? Oppure sono due sorgenti indipendenti che possono divergere?
synapse.html dichiara la sua natura derivata.Tre meccanismi sono descritti in più posti senza una fonte canonica nominata. Severità bassa: il lettore può assemblare, ma è fragile.
agent_runtime.html §4 (gate nel loop) · approval_ux.html §3 (macchina a stati) · gateway.html §4.1 (build_approval_request)approval_ux.html è la fonte canonica della macchina a stati e dei tempi. Gli altri due doc citano + linkano. Rimuovere duplicazioni descrittive lasciando solo "come il loop/gateway si aggancia alla macchina a stati".observability.html §4 · gateway.html §8 · config.htmlobservability.html è canonico. config.html definisce solo le env var (LOG_LEVEL, LOG_FORMAT). gateway.html rimuove la menzione in §8 e linka observability.agent_runtime.html §3 (7 blocchi) · memory.html §8 (si concentra su ②④⑤)agent_runtime.html canonica. memory.html cita per numero senza ripetere la tabella.Quattro frizioni sono scelte consapevoli documentate. Le elenco per evitare che un futuro passaggio di refactoring le tratti come bug.
| Tensione | Dove è motivata | Stato |
|---|---|---|
| Supervised mode rischia automation bias | approval_ux.html §1 · §7 (tutor mode) | accettata |
| Antropomorfizzazione del vocabolario ("neurone", "sinapsi") | constitution.html §6 · approval_ux.html §1 | accettata |
| Reflection non produce apprendimento autonomo (serve approvazione) | memory.html §6 | accettata |
| Gateway è un processo unico, non microservizi | gateway.html §2 | accettata |
Tre cross-reference funzionano e vanno protette: se in fase di implementazione si è tentati di erodere uno di questi pattern per comodità, fermarsi.
ExecutionTrace come backbone semanticoNonostante il §3.1, il concetto (una singola struttura immutabile post-chiusura, append-only durante l'esecuzione, consumata da audit/replay/eval/memory) è la spina dorsale del progetto ed è la cosa più preziosa. I doc sono allineati sul cosa è; il rimedio §3.1 tocca solo il ciclo di vita.
constitution.html §3 dichiara la Legge 0 ("perimetro fisico e legale"). policy.html, sandbox.html, approval_ux.html ne discendono senza mai provare a negoziarla. Coerenza perfetta.
<untrusted> come boundary unicaagent_runtime.html §3 e constitution.html §7 adottano lo stesso tag per wrappare contenuti esterni non fidati. Nessun doc propone un pattern alternativo. Da riusare identico in tool.html (web_fetch) e channel.html (inbound).
Una tabella, con priorità, doc da editare, stima di effort. Da eseguire prima di iniziare la fase 1 di implementazione.
| # | Fix | Severità | Doc da toccare | Effort |
|---|---|---|---|---|
| 1 | Diagramma di stato ExecutionTrace (§3.1) | alta | agent_runtime.html + nota in types.html | M |
| 2 | Sposta approval_timeout su Channel, rimuovi hardcode 15 min (§3.2) | alta | gateway.html, channel.html | S |
| 3 | Unifica PlannedAction / ApprovalRequestDraft (§3.3) | alta | types.html, gateway.html, policy.html | M |
| 4 | Policy.check() legge TrustScore (§3.4) | alta | policy.html, rl_offline.html | S |
| 5 | Binding sender → session → memory end-to-end (§3.5) | alta | gateway.html, memory.html, channel.html | M |
| 6 | Gerarchia sorgenti-di-verità del journal (§3.6) | alta | observability.html, neuron.html, synapse.html | M |
| 7 | Schema FactProposal / MemoryFact (§4.1) | media | types.html, memory.html | S |
| 8 | Costanti di decadimento (§4.2) | media | synapse.html, memory.html | S |
| 9 | Retry su policy_denied (§4.3) | media | policy.html | S |
| 10 | Timing della compressione context (§4.4) | media | agent_runtime.html | XS |
| 11 | Retention/resurrezione neurone estinto (§4.5) | media | neuron.html | S |
| 12 | Cap costituzionale sul budget (§4.6) | media | constitution.html | XS |
| 13 | Chiarire journal derivato (§4.7) | media | synapse.html | XS |
| 14 | Canonizzare fonti (§5.1-5.3) | bassa | vari | M |
Effort: XS = 1 paragrafo, S = 1 sezione breve, M = sezione con figura o tabella.
Totale effort: ~3 M + 6 S + 3 XS + 2 M (ridondanze) ≈ 1 giornata di lavoro di editing.
myclaw — Review di coerenza v1.0 — 2026-04-22
Scritto dopo la chiusura della microprogettazione. Non aggiunge design: segnala.