Architecture Decision Records

This directory holds the durable record of architecture decisions that should not be re-litigated from scratch every time the same question comes up.

Use ADRs for decisions that are:

• structural rather than incidental
• likely to be questioned again
• expensive to reverse
• cross-cutting across runtime, product, and extensions

Relationship to the other docs:

• ../architecture.md: what the system is now
• ../roadmap.md: where the system is going
• ../whitepaper.md: why this category should exist
• adr-*.md: why a specific architecture choice was made instead of an alternative

Current ADRs:

• adr-0001-agent-native-ontology-runtime.md
• adr-0002-capability-vs-channel-boundary.md
• adr-0003-machine-first-contract.md
• adr-0004-canonicalitem-bidirectional-boundary.md
• adr-0005-reactive-semantics-over-imperative-orchestration.md
• adr-0006-runtime-loadable-ontology-over-python-registered-logic.md
• adr-0007-python-as-host-and-extension-interface.md
• adr-0008-connector-recipe-ingest-boundary.md
• adr-0009-relationship-authoring-and-wiki-link-layer.md — Accepted (2026-06-22)
• adr-0010-durable-agent-work-outside-reactive-bus.md
• adr-0011-obsidian-ontology-human-sovereign-mirror.md
• adr-0012-agent-dispatch-via-dsl-primitive-agents-as-graph-nodes.md — Proposed (open)
• adr-0013-vault-registry-from-manifest.md — Proposed (2026-06-29)
• adr-0014-manual-effect-scope-cascade-deferral.md — Accepted (2026-06-29)
• ADR-0015 (dual-entry implicit scoping / effect_scope()) — referenced from ADR-0014; file pending
• adr-0015-binary-aliases-as-node-field.md — Accepted (2026-07-06)
• adr-0016-inbox-jsonl-file-vs-rpc.md — Accepted (2026-07-06)
• adr-0017-worker-sync-streaming-via-daemon-threads.md — Accepted (2026-07-06)
• adr-0018-engine-keeps-minimal-substrate.md — Accepted (2026-07-09; revised same day — see file header. Decoupled from specific paths; migration softened to per-case diagnostic.)