DK-ADR-001: Adopt Architecture Decision Records

Context

DataKit has accumulated vision documents (docs/target-state.md, docs/vision/), concept docs (docs/concepts/), and an architecture overview (docs/architecture.md). These describe the desired state but do not capture the reasoning behind individual decisions, what alternatives were considered, or which earlier choices have been superseded.

As the project grows, contributors (human and AI) need a lightweight, version-controlled way to:

1. Record significant architectural decisions and the reasoning behind them.
2. Identify which past decisions are still active vs. deprecated or superseded.
3. Detect when proposed work conflicts with an existing decision and trigger a deliberate conversation before proceeding.

Decision

We will maintain Architecture Decision Records (ADRs) in docs/adr/, using the naming convention DK-ADR-NNN-<slug>.md.

Format

Each ADR follows this structure:

# DK-ADR-NNN: Title

| Field       | Value           |
|-------------|-----------------|
| **Status**  | Proposed | Accepted | Deprecated | Superseded by DK-ADR-XXX |
| **Date**    | YYYY-MM-DD      |
| **Authors** | name (email)    |

## Context
Why this decision is needed.

## Decision
What we decided and any key details.

## Consequences
What changes as a result — both positive and negative.

## Alternatives Considered
What other options were evaluated and why they were not chosen.

Rules

• One decision per ADR. Keep them focused.
• ADRs are immutable once accepted. To reverse or change a decision, create a new ADR that supersedes the old one and update the old ADR’s status to Superseded by DK-ADR-XXX.
• Number sequentially. Use the next available NNN (zero-padded to three digits).
• Status lifecycle: Proposed → Accepted → optionally Deprecated or Superseded by DK-ADR-XXX.

Machine instructions (CLAUDE.md integration)

The project’s CLAUDE.md references ADRs so that AI-assisted development stays aligned with recorded decisions. Specifically:

• Before proposing architectural changes, check docs/adr/ for relevant decisions.
• When work would substantially deviate from an existing ADR or vision document, ask whether a new ADR should be created before proceeding.

Consequences

• Every significant architectural choice gets a durable, reviewable record.
• Contributors can ls docs/adr/ to understand the decision history at a glance.
• Superseded decisions remain in the repo for historical context rather than being silently deleted.
• Minor implementation choices (variable names, small refactors) do not need ADRs — only decisions that affect the project’s architecture, manifest schema, deployment model, or public CLI surface.

Alternatives Considered

• Wiki / Notion pages — Not version-controlled alongside the code. Decisions drift out of sync with the implementation.
• Inline comments in vision docs — Vision docs describe target state, not decision rationale. Mixing the two makes both harder to maintain.
• No formal tracking — The current state. Leads to repeated discussions about decisions that were already made and forgotten.