docs: add architecture decision records

[rinadavidyuk826-sudo]

Summary

• add a docs/adr/ directory with a lightweight MADR-style template and index
• document four architecture decisions already reflected in the repository docs: Ed25519 identity, four execution rings, the 200ms IATP handshake target, and deterministic policy evaluation
• link the ADR index from the repository README so contributors can discover the decisions from the main docs entrypoints

Validation

• git diff --check upstream/main...HEAD

Closes #403.

[github-actions]

Welcome to the Agent Governance Toolkit! Thanks for your first pull request.
Please ensure tests pass, code follows style (ruff check), and you have signed the CLA.
See our Contributing Guide.

[github-actions]

🤖 AI Agent: security-scanner — 1. **Prompt Injection Defense Bypass**

This pull request adds documentation in the form of Architecture Decision Records (ADRs) to the repository. While the changes are primarily documentation-focused, the ADRs themselves describe critical design decisions that directly impact the security and functionality of the toolkit. Below is a security analysis of the proposed changes:

---

1. Prompt Injection Defense Bypass

• Risk: None identified. The changes are documentation-only and do not introduce or modify code that could be exploited for prompt injection attacks.
• Rating: 🔵 LOW

---

2. Policy Engine Circumvention

• Risk: The ADRs describe key design decisions that ensure the integrity of the policy engine. Specifically:
  • ADR 0004 mandates deterministic policy evaluation and explicitly excludes LLMs from the enforcement path. This is a strong safeguard against policy circumvention through probabilistic or non-deterministic behavior.
  • ADR 0002 establishes a four-ring execution model that simplifies privilege management and reduces the risk of policy circumvention by limiting the complexity of runtime privilege escalation.
• Rating: 🔵 LOW (no vulnerabilities introduced; the ADRs reinforce security principles).

---

3. Trust Chain Weaknesses

• Risk: None identified in the documentation itself. However:
  • ADR 0001 specifies the use of Ed25519 for agent identity, which is a strong cryptographic choice. The decision to avoid RSA as the default primitive is justified by performance and size considerations, and the ADR explicitly mentions maintaining interoperability with SPIFFE/SVID and JWK standards.
  • The documentation does not introduce any new trust chain weaknesses but highlights the importance of adhering to these standards.
• Rating: 🔵 LOW

---

4. Credential Exposure

• Risk: None identified. The changes are documentation-only and do not involve handling or exposing credentials.
• Rating: 🔵 LOW

---

5. Sandbox Escape

• Risk: None identified. However:
  • ADR 0002 describes a four-ring execution model that is designed to enhance sandboxing by providing a predictable privilege lattice. This decision reinforces sandbox isolation by ensuring that runtime privileges are tightly controlled.
• Rating: 🔵 LOW

---

6. Deserialization Attacks

• Risk: None identified. The changes are documentation-only and do not involve deserialization mechanisms.
• Rating: 🔵 LOW

---

7. Race Conditions

• Risk: None identified. The ADRs do not introduce or modify code that could lead to race conditions. However:
  • ADR 0003 sets a 200ms SLA for trust handshakes, which indirectly emphasizes the importance of avoiding race conditions in trust evaluation. This is a positive design decision.
• Rating: 🔵 LOW

---

8. Supply Chain

• Risk: None identified. The changes are documentation-only and do not introduce new dependencies or modify existing ones.
• Rating: 🔵 LOW

---

Overall Assessment

The proposed changes are documentation-focused and do not introduce any new code or dependencies. The ADRs themselves reinforce strong security principles, such as deterministic policy evaluation, compact and efficient cryptographic primitives, and a clear privilege model. These decisions align with best practices for secure AI agent governance.

Recommendations

1. No changes required: The ADRs are well-written and reflect sound architectural decisions that enhance the security and reliability of the toolkit.
2. Future Consideration: Ensure that the implementation of these ADRs in the codebase adheres to the principles described. Regular audits and tests should verify compliance with these decisions.

Final Rating: 🔵 LOW (No security vulnerabilities introduced)

[github-actions]

🤖 AI Agent: code-reviewer

Review of Pull Request: docs: add architecture decision records

This PR introduces a new docs/adr/ directory to document key architectural decisions using a lightweight MADR-style format. It includes four ADRs that reflect existing design choices in the repository and links the ADR index from the main README. Below is a detailed review:

---

🔴 CRITICAL

No critical security issues were identified in this PR. However, the following areas should be carefully monitored in future changes:

1. Ed25519 for Agent Identity (ADR 0001):

   • The decision to use Ed25519 for agent identity is sound, as it provides strong cryptographic guarantees with compact key sizes and fast signing/verification. However, ensure that:
     • Key generation and storage are implemented securely.
     • The library used for Ed25519 operations is well-maintained and free of known vulnerabilities.
     • The SPIFFE/SVID integration is reviewed for potential attack vectors, such as key compromise or impersonation.

2. Four Execution Rings (ADR 0002):

   • The four-ring privilege model is a good design choice for runtime governance. However, ensure that:
     • The sandboxing mechanism for the default ring is robust against escape vectors.
     • Temporary elevation mechanisms are carefully audited to prevent privilege escalation attacks.

3. Deterministic Policy Evaluation (ADR 0004):

   • Keeping policy evaluation deterministic is critical for security and auditability. However, ensure that:
     • The policy backends (e.g., Rego, Cedar) are configured securely and do not allow untrusted inputs to inject malicious rules.
     • YAML/JSON policy definitions are validated against a strict schema to prevent injection attacks.

---

🟡 WARNING

1. Backward Compatibility:
   • While this PR does not introduce breaking changes to the codebase, the decisions documented in the ADRs (e.g., Ed25519 for identity, deterministic policy evaluation) could affect future API design. Ensure that any changes to these areas are carefully reviewed for backward compatibility.

---

💡 SUGGESTIONS

1. ADR Template Improvements:

   • Consider adding a "Security Implications" section to the ADR template to explicitly document potential security risks and mitigations for each decision. This will help contributors evaluate the security impact of architectural choices.

2. Linking ADRs to Code:

   • It would be helpful to link each ADR to the relevant parts of the codebase where the decision is implemented. For example:
     • ADR 0001 (Ed25519) could link to the modules handling identity generation and verification.
     • ADR 0004 (Policy Evaluation) could link to the policy engine implementation.

3. Versioning ADRs:

   • Introduce a versioning mechanism for ADRs to track changes over time. For example, if ADR 0001 is updated in the future, it could be versioned as ADR 0001.1.

4. Automated Validation:

   • Consider adding a CI check to validate the ADR directory structure and ensure that all ADRs are listed in the index. This will help maintain consistency as the repository evolves.

5. Additional ADRs:

   • Future ADRs could document other critical areas, such as:
     • Cryptographic operations beyond Ed25519 (e.g., key rotation, encryption).
     • Thread safety and concurrency models for agent execution.
     • OWASP Agentic Top 10 compliance strategies.

---

Summary

This PR is a well-structured addition to the repository's documentation, providing clear and concise records of key architectural decisions. While no critical issues were found, the suggestions above can further enhance the value and security of the ADRs. Ensure that future changes to the areas covered by these ADRs are carefully reviewed for security, backward compatibility, and compliance with the documented decisions.

Approval Status: ✅ Approved with suggestions.

[imran-siddique]

ADRs documenting key architecture decisions — great governance practice. LGTM.

[imran-siddique]

Rebased in a new PR to resolve merge conflict with #451. Thank you @rinadavidyuk826-sudo!