Decision log¶
Architectural decisions for Ariadne, recorded as ADRs (Architecture Decision Records) in the MADR format. One file per decision. This is the single place to point to when someone asks "why did you choose X instead of Y?", each record names the alternatives that were considered, why they lost, and what the choice costs us.
Why we keep these¶
Decisions get made constantly and then disappear into chat logs and commit messages. An ADR is a small, dated, immutable record of one decision and its rejected alternatives, kept in source control next to the code so it stays in sync. When the context changes, we don't edit the old record, we supersede it with a new one.
When to write one¶
Write an ADR when a choice is architecturally significant and contestable: a
store, a framework, a connector, a security posture, a deferral. Skip it for
reversible implementation details. A good trigger is "a reviewer could
reasonably ask why we didn't do it the other way." Each design choice should
still carry its # research(YYYY-MM): provenance at the code/roadmap level; the
ADR is where the comparison lives.
The records¶
| # | Decision | Status |
|---|---|---|
| 0001 | Orchestrate on the Claude Agent SDK | Accepted |
| 0002 | Use official MCP connectors over hand-rolled wrappers | Accepted |
| 0003 | Expose Postgres via postgres-mcp Restricted Mode |
Accepted |
| 0004 | Keep Postgres (not Redis) for the relational store | Accepted |
| 0005 | Defer subagent fan-out pending a design pass | Deferred |
| 0006 | Dataset-agnostic pipeline (canonical schema + adapters) | Accepted |
| 0007 | Hybrid retrieval, full-text first (in-Postgres) | Accepted |
| 0008 | Multimodal via agentic-to-text, not native multimodal embeddings | Accepted |
| 0009 | Distribute as an MCP server, wrapped in a Claude Code plugin | Accepted |
| 0010 | Observability via OpenTelemetry (GenAI conventions) | Accepted |
| 0011 | LLM-rubric scoring of analytic standards (ICD-203) | Accepted |
| 0012 | Cloud vs. air-gapped deployment fork (single seam) | Accepted |
| 0013 | User-selectable model profiles (curated allowlist) | Accepted |
| 0014 | pgvector for the semantic-leg vector store | Accepted |
| 0015 | Subagent fan-out — design specified, implementation gated | Accepted |
| 0016 | Entity resolution across stores — tiered, ingestion-first | Accepted |
| 0017 | Results presentation — self-contained interactive workup report | Accepted |
| 0018 | Multimodal connector slate — text/audio/relational shipped, video deferred | Accepted |
| 0019 | Retrieval-side evaluation — context utilization, not precision@k | Accepted |
| 0020 | Adaptive & self-improving Ariadne — bounded, audited, propose→ratify→freeze | Accepted |
| 0021 | Run-output organization — immutable per-run dirs + reproducibility manifest | Accepted |
| 0022 | Citation-recall coverage hardening — P-Cite repair loop + abbreviation-robust segmentation | Accepted |
| 0023 | Measure the P-Cite repair loop's citation-coverage gain (Δcoverage) | Accepted |
| 0024 | Trajectory eval grades observations, not just actions | Accepted |
| 0025 | Apply a ratified mapping — it self-registers as a dataset | Accepted |
| 0026 | LLM-backed schema mapper — forced tool-use + validator-terminated retry | Accepted |
| 0027 | Declarative user ontology — a lightweight TOML vocabulary the mapper maps into | Accepted |
| 0028 | Runtime dataset activation over MCP — connect_dataset + a dynamically-registered tool |
Accepted |
| 0029 | Distil analytic skills from eval-certified trajectories — ariadne distil (B2) |
Accepted |
| 0030 | Reflexion over the eval harness — ariadne reflect, grounded and gold-free (B3) |
Accepted |
| 0031 | Net-effect ratification comparator — ariadne compare, measure don't read |
Accepted |
| 0032 | Deepening a skill from new experience — distil --into, bounded and compare-gated |
Accepted |
| 0033 | Verifying the air-gapped posture — a network-egress guard (egress_guard + autouse CI gate) |
Accepted |
| 0034 | Automated net-effect ratification — ariadne ratify, produce the paired runs |
Accepted |
| 0035 | Self-consistency sampling for the analytic-rubric judge — median + judge-disagreement | Accepted |
Template¶
New records follow the MADR shape: Context → Decision drivers → Considered options (with pros/cons) → Decision → Consequences, plus a one-line status and the sources behind the call. Copy an existing record and keep it to a single decision.