← Documentation index docs › architecture/

Microdesign

This folder hosts the Level 2 documentation: one HTML file per architectural component. It is populated gradually. A rule of life: a component is not implemented before its HTML exists and has been approved.

Language note. The Level 1 foundation documents are bilingual (IT + EN). The microdesign pages below, however, are currently only in Italian. This page serves as an English-language index so you can see what exists and what each component covers before following the links into the Italian files. Translation of individual microdesign files is on demand: ping mykleos@knowcastle.com if a specific component blocks your reading.
Status: 21/21 docs written and approved. The microdesign round was followed by a coherence review in Italian (22 April 2026) with 6 blocking fixes and 7 medium fixes applied in the same session. Phase 1 of implementation is now open.

Release phases

0overall architecture
✓ done
1skeleton + CLI + sandboxed shell
now
3Telegram + pairing
4memory + failover
5+voice, tunnel, dashboard

Production order (after the phase-0 judgement)

Following Perspectives & Judgement v1, the microdesign writing order changed: three cross-cutting docs go before the four classical ones, because without them the four classics would be pattern-violators.

# Cross-cutting doc Which blocking critiques it solves
1 agent_runtime.html reasoning loop, tool-call validation, ExecutionTrace, prompt structure
2 approval_ux.html approval batching, reading pause, revoke, tutor mode
3 eval.html 15-20 YAML scenarios + replay harness + success/cost report

Planned components

Each linked document opens the Italian microdesign page. The English description below summarises what the component covers.

Component What it covers Phase Status
types.html ✓ IT Canonical index of cross-component types. Introduces PlannedAction and TrustScore. Versioning discipline and drift detection. 1 (cross-cutting) approved
agent_runtime.html ✓ IT Reasoning loop (ReAct), prompt structure, tool-call validation, ExecutionTrace, provider failover via supra. 1 (first) approved
approval_ux.html ✓ IT CLI/Telegram approval flows, batching, reading pause, revoke, tutor mode. 1 (first) approved
eval.html ✓ IT YAML scenarios, replay harness, success/latency/cost metrics, CI gate. 1 (first) approved
gateway.html ✓ IT FastAPI, sessions, webhooks, cron, auth. 1 approved
channel.html ✓ IT Channel Protocol, CLI, then Telegram. 1 / 3 approved
tool.html ✓ IT Tool Protocol, base set (fs, shell, web_fetch, supra adapters). 1 approved
sandbox.html ✓ IT Bubblewrap profiles, systemd hardening, optional Docker. 1 approved
policy.html ✓ IT Autonomy levels, approval gating, rate/cost limits, forbidden paths, cost tiering. 2 approved
workspace.html ✓ IT Markdown files IDENTITY / USER / MEMORY / AGENTS / SOUL. 2 approved
observability.html ✓ IT JSON logging, append-only audit log, metrics, health. 2 approved
pairing.html ✓ IT DM pairing: code flow, signature, revocation. 3 approved
memory.html ✓ IT Memory Protocol, session persistence + long-term facts. 4 approved
config.html ✓ IT pydantic-settings schema, overrides, secrets. 1 (cross-cutting) approved
"Neurons and Memory" extension (see doc v1)
rl_offline.html ✓ IT Self-evolution without training. 3 experiments: trace-scoring / synth-reward / neuron self-play. Introduces TrustStore. 5 / 7 (cross-cutting) approved
neuron.html ✓ IT Structure of a neuron: manifest, body, birth test, signature, journal. 6 approved
synthesizer.html ✓ IT Synthesis pipeline: failure → spec → draft → static analysis → test → human approval. 5 / 6 approved
synapse.html ✓ IT Neuron graph: declared/observed synapses, counters, decay, pruning. 7 approved
constitution.html ✓ IT The 4 Laws, SOUL.md, modification rite, prompt-level enforcement. 2 approved
"Extended Perspectives" extension (see doc v1)
telos.html ✓ IT TELOS.md, alignment function, bother budget, learning from silences. Foundational for the proactive families (A, B, D). 4-5 approved
vaglio.html ✓ IT Constitutional Guard (binary, deterministic) + teleological Judge (gradient, independent LLM). Resolves self-critic bias; pairs with telos. Vaglio = "the sieve". 4-5 approved
coerenza_v1.html ✓ IT Coherence review across all 21 components. 6 blocking fixes + 7 medium fixes applied 22 April 2026. meta approved

Writing conventions

Every microdesign HTML file follows the same template as Architecture — Introduction:

Status legend

planned — component recognised, document not yet written.
drafting — document in draft, do not use as reference.
approved — final document. Implementation may begin.
built — code exists in src/myclaw/<component>/.

Back to Level 1 (foundations)

The microdesign only makes sense against the foundation documents. If you are reading a component in this folder, keep these open too:

Keep reading

foundations · 20 min
Architecture — Introduction v1
The "what": the four layers, autonomy, the workspace, the flow of a request.
 extension · 30 min
Neurons, Synapses and Memory v1.1
The "living extension": self-synthesised neurons, Darwinian selection, three-tier memory.
 rationale · 15 min
Literature & Adaptations
The "why": the literature that informed the design choices.
 practical · 10 min
Survival Kit
The "for whom": the user side, concrete use cases, what will be possible.
 home
← Main index
All documents at once.