docs: add architecture decision records

README.md

@@ -65,9 +65,10 @@ pip install agent-lightning        # RL training governance
 - **[Tutorials](docs/tutorials/)** — Step-by-step guides for policy, identity, integrations, compliance, SRE, and sandboxing
 - **[Azure Deployment](docs/deployment/README.md)** — AKS, Azure AI Foundry, Container Apps, OpenClaw sidecar
 - **[NVIDIA OpenShell Integration](docs/integrations/openshell.md)** — Combine sandbox isolation with governance intelligence
-- **[OWASP Compliance](docs/OWASP-COMPLIANCE.md)** — Full ASI-01 through ASI-10 mapping
-- **[Architecture](docs/ARCHITECTURE.md)** — System design, security model, trust scoring
-- **[NIST RFI Mapping](docs/nist-rfi-mapping.md)** — Mapping to NIST AI Agent Security RFI (2026-00206)
+- **[OWASP Compliance](docs/OWASP-COMPLIANCE.md)** — Full ASI-01 through ASI-10 mapping
+- **[Architecture](docs/ARCHITECTURE.md)** — System design, security model, trust scoring
+- **[Architecture Decisions](docs/adr/README.md)** — ADR log for key identity, runtime, and policy choices
+- **[NIST RFI Mapping](docs/nist-rfi-mapping.md)** — Mapping to NIST AI Agent Security RFI (2026-00206)
 
 Still have questions? File a [GitHub issue](https://github.com/microsoft/agent-governance-toolkit/issues) or see our [Community page](COMMUNITY.md).
 

docs/adr/0000-template.md

@@ -0,0 +1,16 @@
+# ADR 0000: Short Decision Title
+
+- Status: proposed
+- Date: YYYY-MM-DD
+
+## Context
+
+Describe the problem, constraint, or tradeoff that requires a decision.
+
+## Decision
+
+Describe the decision in one clear paragraph.
+
+## Consequences
+
+Describe the expected benefits, tradeoffs, and follow-up impact.

docs/adr/0001-use-ed25519-for-agent-identity.md

@@ -0,0 +1,30 @@
+# ADR 0001: Use Ed25519 for agent identity
+
+- Status: accepted
+- Date: 2026-03-26
+
+## Context
+
+AgentMesh treats identity as the first layer of trust. The repository README,
+architecture docs, tutorial 02, JSON schemas, and service API docs all describe
+`did:mesh:*` identities backed by Ed25519 keys, short-lived credentials,
+sponsor signatures, and cross-language SDKs. The same identity primitive must
+work in Python, Node.js, and .NET-facing documentation, and it must support
+repeated signing and verification during registration, delegation, and trust
+handshakes. A heavier RSA-based default would increase key, signature, and
+document size for flows that are already optimized for compact manifests,
+ephemeral credentials, and low-latency verification.
+
+## Decision
+
+Standardize agent identity on Ed25519 for agent DIDs, signatures, and
+verification keys. Keep interoperability through JWK export, DID documents, and
+SPIFFE/SVID integration instead of making RSA the default identity primitive.
+
+## Consequences
+
+Identity payloads stay compact, signing remains fast enough for frequent
+handshake and rotation flows, and the repository can document one consistent
+identity story across SDKs and protocol bridges. The tradeoff is that legacy
+RSA-only PKI environments need an adapter boundary rather than first-class,
+native parity in the core identity model.

docs/adr/0002-use-four-execution-rings-for-runtime-privilege.md

@@ -0,0 +1,29 @@
+# ADR 0002: Use four execution rings instead of RBAC for runtime privilege
+
+- Status: accepted
+- Date: 2026-03-26
+
+## Context
+
+The runtime needs to decide what an agent may do while code is executing, not
+just what role it belongs to. Repository docs describe a four-ring model with a
+default sandbox tier, trust-score thresholds, rate limits, reversible versus
+non-reversible actions, and temporary elevation for exceptional cases. RBAC
+still exists elsewhere in the repository for human-facing administration,
+compliance mappings, and IATP scopes, but static roles alone do not model
+runtime risk, reversibility, or trust decay. The runtime needs a smaller,
+predictable privilege lattice that maps directly to blast radius.
+
+## Decision
+
+Use four execution rings as the primary runtime privilege model. Preserve RBAC
+and scoped capabilities as complementary controls, but do not make them the
+main mechanism for sandboxing live agent execution.
+
+## Consequences
+
+The runtime can express graduated access, safe defaults for unknown agents, and
+clear escalation rules without inventing many agent-specific roles. That makes
+policy explanations and breach detection simpler. The tradeoff is that rings are
+coarser than full role modeling, so detailed authorization still has to be
+handled by capability policies, scopes, and approval workflows layered on top.

docs/adr/0003-keep-iatp-handshake-within-200ms.md

@@ -0,0 +1,29 @@
+# ADR 0003: Keep the IATP trust handshake within a 200ms SLA
+
+- Status: accepted
+- Date: 2026-03-26
+
+## Context
+
+IATP trust handshakes sit directly in the path of agent-to-agent communication.
+The protocol spec requires capability discovery and local policy validation
+before work starts, and repository examples show handshakes happening before
+delegation or collaboration is accepted. AgentMesh planning docs, release
+notes, and examples already treat `<200ms` as the target for this step. If the
+handshake becomes materially slower, every cross-agent interaction pays the
+penalty and the trust layer stops feeling safe to use in interactive flows.
+
+## Decision
+
+Set a 200ms service-level target for the trust handshake so identity checks,
+manifest validation, and local policy decisions remain a lightweight gate in
+front of real work instead of becoming the dominant latency cost.
+
+## Consequences
+
+This target keeps trust verification compatible with chatty multi-agent systems
+and forces the protocol to prefer compact manifests, bounded checks, and local
+decision making. It also creates a clear performance budget for future changes.
+The tradeoff is that expensive remote lookups and heavyweight negotiation must
+stay out of the critical path or be handled through caching and asynchronous
+follow-up signals.

docs/adr/0004-keep-policy-evaluation-deterministic.md

@@ -0,0 +1,28 @@
+# ADR 0004: Keep policy evaluation deterministic and out of LLM control loops
+
+- Status: accepted
+- Date: 2026-03-26
+
+## Context
+
+The toolkit's core claim is that it governs what agents do before execution.
+Repository docs describe deterministic action interception, declarative policy
+rules, and sub-millisecond policy evaluation. The comparison docs also note
+that LLM-based guard systems introduce tens to hundreds of milliseconds of
+latency and probabilistic behavior. For a control plane that must be testable,
+auditable, and safe under failure, inline policy decisions cannot depend on
+model mood, prompt quality, or external inference availability.
+
+## Decision
+
+Keep enforcement-time policy evaluation deterministic by using declarative
+YAML/JSON rules and supported policy backends such as Rego and Cedar. Do not
+place an LLM in the allow-or-deny decision loop for runtime governance.
+
+## Consequences
+
+Policy outcomes remain reproducible, explainable, and cheap enough to run
+before every action. That supports reliable tests, audit trails, and strict
+failure handling. The tradeoff is that nuanced open-text reasoning has to happen
+outside the enforcement path, for example when humans draft policies or review
+shadow-mode findings, rather than inside the final policy decision itself.

docs/adr/README.md

@@ -0,0 +1,21 @@
+# Architecture Decision Records
+
+This directory tracks durable architecture decisions for the Agent Governance
+Toolkit using a lightweight MADR-style structure.
+
+Each ADR captures:
+
+- the context that made the decision necessary
+- the decision that was taken
+- the practical consequences for maintainers and contributors
+
+## ADR Index
+
+- [ADR 0001: Use Ed25519 for agent identity](0001-use-ed25519-for-agent-identity.md)
+- [ADR 0002: Use four execution rings instead of RBAC for runtime privilege](0002-use-four-execution-rings-for-runtime-privilege.md)
+- [ADR 0003: Keep the IATP trust handshake within a 200ms SLA](0003-keep-iatp-handshake-within-200ms.md)
+- [ADR 0004: Keep policy evaluation deterministic and out of LLM control loops](0004-keep-policy-evaluation-deterministic.md)
+
+## Template
+
+- [ADR 0000: Template](0000-template.md)