# ADR-0001: Record Architecture Decisions

- **Status**: Accepted
- **Date**: 2026-01-01
- **Deciders**: bwrob
- **Consulted**: Maintainers
- **Informed**: Contributors and Developers

## Context & Problem Statement

As **Debug Dojo** evolves, contributors and AI coding assistants make architectural and technical choices (such as modular layer boundaries, static type checking rules, dependency management, and serialization contracts). Without a persistent record of the context, alternatives evaluated, and trade-offs accepted, future maintainers face technical drift and risk inadvertently reversing intentional design decisions.

## Decision Drivers

- **Knowledge Persistence**: Retain technical rationale alongside source code in version control.
- **Agent Alignment**: Ensure AI coding assistants understand architectural constraints before generating non-compliant code.
- **Traceability**: Pair automated tool boundaries (like **Tach**) with human-readable justifications.

## Considered Options

1. **Option 1**: Michael Nygard Architecture Decision Records (MADR) in Markdown under `docs/adr/`.
2. **Option 2**: Ephemeral discussion threads in GitHub Issues or Pull Requests.
3. **Option 3**: Unstructured notes in wiki or standalone README sections.

## Pros and Cons of the Options

The options below summarize the trade-offs considered for this decision.

### Option 1: Architecture Decision Records (MADR)

- ✅ **Good**: Version-controlled alongside source code in Git.
- ✅ **Good**: Automatically integrated into Zensical documentation site.
- ✅ **Good**: Machine-readable and easily digested by AI coding assistants.
- ✅ **Good**: Follows recognized open-source and enterprise standards.
- ❌ **Bad**: Requires discipline to draft and review during architectural shifts.

### Option 2: GitHub Issues / Pull Request Discussions

- ✅ **Good**: Low friction to create during active development.
- ❌ **Bad**: Fragmented across closed PRs, difficult to discover or audit systematically.
- ❌ **Bad**: Vulnerable to repository migration or issue closure loss.

### Option 3: Unstructured Notes in Wiki

- ❌ **Bad**: Separated from git commit history and code review gating.
- ❌ **Bad**: Frequently becomes stale and out of sync with code changes.

## Decision Outcome

Chosen option: **"Option 1: Michael Nygard Architecture Decision Records (MADR) in Markdown under `docs/adr/`"**, because storing version-controlled Markdown records directly in the repository ensures that architectural intent remains permanently coupled with codebase evolution.

### Positive Consequences

- Architectural decisions are discoverable in both git and the generated Zensical documentation site.
- AI coding assistants can reference `docs/adr/` when evaluating proposed modifications.
- Decisions undergo peer review via standard Pull Requests.

### Negative Consequences / Trade-Offs

- Maintainers must ensure new architectural paradigms are accompanied by an ADR.

## Architecture & Boundary Compliance

- **Tach Layers**: Any modification to `tach.toml` modules, layer hierarchies, or external dependencies requires an accompanying ADR reference.
- **Documentation**: All accepted ADRs must be registered in `docs/adr/index.md` and `zensical.toml`.