Questa cartella ospita la documentazione di secondo livello: un file HTML per ogni componente architetturale. Viene popolata progressivamente. Regola di vita: un componente non viene implementato prima che il suo HTML esista e sia approvato.
A valle di Prospettive & Giudizio v1, l'ordine di scrittura dei doc di microprogettazione è cambiato: tre doc trasversali vanno prima dei quattro classici, perché senza di essi i quattro sarebbero pattern-violators.
| # | Doc trasversale | Cosa risolve delle critiche bloccanti |
|---|---|---|
| 1 | agent_runtime.html |
reasoning loop, tool-call validation, ExecutionTrace, prompt structure |
| 2 | approval_ux.html |
batching approvazioni, pausa lettura, revoca, tutor mode |
| 3 | eval.html |
15-20 scenari YAML + harness replay + report success/cost |
| Componente | Cosa copre | Fase | Stato |
|---|---|---|---|
types.html ✓ |
Indice canonico dei tipi cross-componente. Introduce PlannedAction e TrustScore. Disciplina di versioning e drift detection. |
1 (trasversale) | approvato |
agent_runtime.html ✓ |
Reasoning loop (ReAct), prompt structure, tool-call validation, ExecutionTrace, provider failover via supra | 1 (prima) | approvato |
approval_ux.html ✓ |
Flussi approvazione CLI/Telegram, batching, pausa lettura, revoca, tutor mode | 1 (prima) | approvato |
eval.html ✓ |
Scenari YAML, harness replay, metriche success/latency/cost, CI gate | 1 (prima) | approvato |
gateway.html ✓ |
FastAPI, sessioni, webhook, cron, auth | 1 | approvato |
channel.html ✓ |
Protocol Channel, CLI, poi Telegram |
1 / 3 | approvato |
tool.html ✓ |
Protocol Tool, base set (fs, shell, web_fetch, supra adapters) |
1 | approvato |
sandbox.html ✓ |
Profili bubblewrap, hardening systemd, Docker opzionale | 1 | approvato |
policy.html ✓ |
Livelli di autonomia, approval gating, rate/cost limits, forbidden paths, cost tiering | 2 | approvato |
workspace.html ✓ |
File markdown IDENTITY / USER / MEMORY / AGENTS / SOUL | 2 | approvato |
observability.html ✓ |
Logging JSON, audit log append-only, metrics, health | 2 | approvato |
pairing.html ✓ |
DM pairing: flusso codice, firma, revoca | 3 | approvato |
memory.html ✓ |
Protocol Memory, persistenza sessioni + fatti long-term |
4 | approvato |
config.html ✓ |
Schema pydantic-settings, overrides, secrets | 1 (trasversale) | approvato |
| Estensione "Neuroni e Memoria" (vedi doc v1) | |||
rl_offline.html ✓ |
Autosviluppo senza training. 3 esperimenti trace-scoring / synth-reward / neuron self-play. Introduce TrustStore. |
5 / 7 (trasversale) | approvato |
neuron.html ✓ |
Struttura di un neurone: manifest, corpo, test di nascita, firma, journal | 6 | approvato |
synthesizer.html ✓ |
Pipeline di sintesi: fallimento → spec → bozza → analisi statica → test → approvazione umana | 5 / 6 | approvato |
synapse.html ✓ |
Grafo dei neuroni: sinapsi dichiarate/osservate, counter, decadimento, potatura | 7 | approvato |
constitution.html ✓ |
Le 4 Leggi, SOUL.md, rito di modifica, enforcement nei prompt | 2 | approvato |
| Estensione "Prospettive estese" (vedi doc v1) | |||
telos.html ✓ |
TELOS.md, funzione di allineamento, bother budget, apprendimento dai silenzi. Fondante per le famiglie proattive (A, B, D). | 4-5 | approvato |
vaglio.html ✓ |
Guardia costituzionale (binaria, deterministica) + Giudice teleologico (gradiente, LLM indipendente). Risolve il self-critic bias; coppia con telos. |
4-5 | approvato |
Ogni file HTML di microprogettazione segue lo stesso template di Architettura — Introduzione:
id;
pianificato — componente riconosciuto, documento non ancora scritto.
in stesura — documento in bozza, non usare come riferimento.
approvato — documento finale. L'implementazione può iniziare.
implementato — codice esistente in src/myclaw/<componente>/.
La microprogettazione ha senso solo contro i documenti fondamentali. Se stai leggendo un componente di questa cartella, tienili a portata: