Title here
Summary here
Architecture Decision Records
This directory contains the Architecture Decision Records (ADRs) for this project.
Format
Each ADR follows this structure:
# NNNN: Title
**Status**: Proposed | Accepted | Superseded | Deprecated
**Date**: YYYY-MM-DD
## Context — What is the issue motivating this decision?
## Candidates — Options considered with trade-offs
## Decision — What we chose and why
## Consequences — What becomes easier/harder
## Constitution Compliance — Mapping to project principlesNumbering Convention
ADRs are numbered sequentially: 001, 002, etc.
Numbers are never reused. If a decision is reversed, the original ADR is marked “Superseded” and a new ADR is created with a reference.
Index
| ADR | Title | Status |
|---|---|---|
| 001 | Hexagonal Architecture | Accepted |
| 002 | Error Taxonomy with Exit Codes | Accepted |
| 003 | YAML State Machine for Workflow Definition | Accepted |
| 004 | Domain Operation Registry with Infrastructure Coexistence | Accepted |
| 005 | Atomic File Writes for State Persistence | Accepted |
| 006 | XDG-Compliant Path Resolution | Accepted |
| 007 | Agent Prompt XOR Constraint | Accepted |
| 008 | OpenAI-Compatible Provider: HTTP Adapter Integration | Accepted |
| 009 | Breaking: Removal of Custom Provider in v0.4.0 | Accepted |
| 010 | Paired JSONL Audit Trail with Atomic Append | Accepted |
| 011 | Application-Layer Secret Masking for Audit Events | Accepted |
| 012 | Runtime Shell Detection with $SHELL Environment Variable | Accepted |
| 013 | Context-Aware Input Ports | Accepted |
| 014 | Shebang Execution for Script Files | Accepted |
Creating a New ADR
- Find the next number:
ls docs/ADR/ | grep -oP '^\d+' | sort -n | tail -1+ 1 - Copy the template:
cp docs/ADR/.template.md docs/ADR/NNNN-short-name.md - Fill in all sections
- Update this index
- Submit for review
Pre-Merge Checklist
Before merging any new or modified ADR:
- Cross-references: All
[ADR-NNNN]links resolve to existing files - Supersession: If changing a prior decision, both ADRs have
Supersedes/Superseded bymetadata - Constitution: Compliance section maps to current constitution version
- Candidates: At least 2 alternatives documented with trade-offs