Architecture Decision Records¶
This directory contains Architecture Decision Records (ADRs) for the Assay project.
Index¶
| ADR | Title | Status | Priority |
|---|---|---|---|
| ADR-001 | Sandbox Design | Accepted | - |
| ADR-002 | Trace Replay | Accepted | - |
| ADR-003 | Gate Semantics | Accepted | - |
| ADR-004 | Judge Metrics | Accepted | - |
| ADR-005 | Relative Thresholds | Accepted | - |
| ADR-006 | Evidence Contract | Accepted | - |
| ADR-007 | Deterministic Provenance | Accepted | - |
| ADR-008 | Evidence Streaming Architecture | Proposed | Backlog |
| ADR-009 | WORM Storage for Evidence Retention | Deferred | Q3+ |
| ADR-010 | Evidence Store Ingest API | Deferred | Q3+ |
| ADR-011 | MCP Tool Signing with Sigstore | Proposed | P1 |
| ADR-012 | Transparency Log Integration | Proposed | P3 |
| ADR-013 | EU AI Act Compliance Pack | Accepted | P2 |
| ADR-014 | GitHub Action v2 Design | Implemented | ✅ |
| ADR-015 | BYOS Storage Strategy | Accepted | P1 |
| ADR-021 | Local Pack Discovery and Pack Resolution Order | Accepted | P2 |
| ADR-022 | SOC2 Baseline Pack (AICPA Trust Service Criteria) | Accepted | P2 |
| ADR-023 | CICD Starter Pack (Adoption Floor) | Accepted | P1 |
| ADR-024 | Sim Engine Hardening (Limits + Time Budget) | Superseded | P2 |
| ADR-025 | Evidence-as-a-Product | Accepted | P1/P2 |
| ADR-026 | Protocol Adapters | Accepted | P1 |
| ADR-027 | Tool Taxonomy and Class-Based Route Policies | Accepted | P1 |
| ADR-028 | Coverage Report (Tool & Route Completeness) | Accepted | P1 |
| ADR-029 | Session & State Window Contract (MCP Governance) | Accepted | P1 |
| ADR-030 | Coverage + Wrap DX Polish | Accepted | P2 |
| ADR-031 | Coverage v1.1 DX Polish | Accepted | P2 |
| ADR-032 | MCP Policy Enforcement, Obligations, and Evidence v2 | Accepted | P1 |
| ADR-020 | Dependency Governance | Accepted | - |
Q2 2026 Priorities¶
Strategy: BYOS-first (Bring Your Own Storage) per ADR-015. Focus on CLI features, defer managed infrastructure until PMF.
| Priority | ADR | Status | Notes |
|---|---|---|---|
| ✅ | ADR-014 | Implemented | Marketplace |
| P1 | ADR-015 | Accepted | push/pull/list shipped on main; store-status, richer config ergonomics, and fuller provider docs remain open |
| P1 | ADR-011 | Proposed | x-assay-sig + local-key signing in OSS; Sigstore keyless deferred to enterprise |
| P1 | ADR-023 | Accepted | OSS starter adoption floor (implemented) |
| P2 | ADR-021 | Accepted | Local pack discovery + safe resolution order (implemented) |
| P2 | ADR-022 | Accepted | SOC2 baseline OSS pack (implemented) |
| P1/P2 | ADR-025 | Accepted | I1/I2/I3 slices merged on main; formal accept complete |
| P1 | ADR-026 | Accepted | ACP + A2A + UCP adapter slices and E0-E4 stabilization are merged on main |
| P1 | ADR-027 | Accepted | Implemented on main via PRs #560, #561, and #572 (taxonomy + class-aware tool matching + closure) |
| P1 | ADR-028 | Accepted | Implemented on main via PRs #563, #565, #567, and #572 (coverage contract + generator + wrap emission + closure) |
| P1 | ADR-029 | Accepted | Implemented on main via PRs #569, #574, and #576 (session/state contract + informational export + closure) |
| P2 | ADR-030 | Accepted | Implemented on main via PRs #578, #580, and #582 (coverage markdown/file input + wrap export log consistency + closure) |
| P2 | ADR-031 | Accepted | Implemented on main via PRs #585, #587, and #588 (--out-md, --routes-top, and closure docs/gates) |
| P1 | ADR-032 | Accepted | Wave24-Wave42 merged on main; see overview + plan for capability grouping and historical rollout |
| P2 | ADR-013 | Accepted | Article 12 mapping, --pack flag |
| P3 | ADR-012 | Proposed | Builds on ADR-011 |
| Deferred | ADR-009 | Deferred | Managed WORM → Q3+ if demand |
| Deferred | ADR-010 | Deferred | Managed API → Q3+ if demand |
ADR-032 Companion Docs¶
The ADR-032 line has supporting architecture documents with separate roles:
- ADR-032 Implementation Overview — current-state maintainer map
- ADR-032 Building Block View — structural decomposition
- ADR-032 Quality Scenarios — explicit quality attributes
- ADR-032 Structurizr Workspace — bounded architecture-as-code model
- ADR-032 Obsidian View Layer Recommendations — internal view-layer guidance
- ADR-032 Execution Plan — historical rollout log
- ADR-032 Documentation Maturity Gap Analysis — current-state gap analysis
Repo-wide Architecture & Roadmap¶
- Assay Architecture & Roadmap Gap Analysis — current-state truth sync across roadmap, ADRs, RFCs, and delivery gaps
Template¶
New ADRs should follow this structure:
# ADR-XXX: Title
## Status
Proposed | Accepted | Deprecated | Superseded
## Context
What is the issue that we're seeing that is motivating this decision?
## Decision
What is the change that we're proposing and/or doing?
## Consequences
What becomes easier or more difficult to do because of this change?