initial commit

docs/adr/0000-adr-template.md

@@ -0,0 +1,58 @@
+# 0000. ADR process and template
+
+## Status
+
+Accepted
+
+## Context
+
+We are about to make several architecture decisions about how the Qdrant
+vector store is structured and used (ingestion, CRUD, and agent retrieval).
+`docs/adr/README.md` currently has no convention for recording these
+decisions. We need a lightweight, consistent format so future contributors
+can understand *why* the system is built the way it is, not just *what* it
+does.
+
+## Decision
+
+We will record architecturally significant decisions as Architecture Decision
+Records (ADRs) under `docs/adr/`, using this convention:
+
+- **Filename**: `NNNN-short-title.md`, zero-padded, monotonically increasing
+  (`0000`, `0001`, `0002`, ...). The number is permanent once assigned.
+- **Sections**, in this order:
+  1. Title (`# NNNN. Title`)
+  2. Status — one of `Proposed`, `Accepted`, `Superseded by NNNN`
+  3. Context — the problem, constraints, and forces at play
+  4. Decision — what we're doing, stated directly
+  5. Consequences — `Positive` and `Negative` subsections
+  6. Alternatives Considered — options we rejected and why
+- **Immutability**: once an ADR is `Accepted`, it is not edited to reflect a
+  changed decision. A changed decision gets a *new* ADR that sets the old
+  one's status to `Superseded by NNNN` and links back to it. Small
+  clarifications/typo fixes are fine to edit in place.
+- **Scope**: only decisions with real architectural weight (data model,
+  external system boundaries, protocols, cross-cutting concerns) get an ADR.
+  Routine implementation choices do not.
+
+## Consequences
+
+### Positive
+- Future contributors (and agents) can trace *why* the Qdrant schema, CRUD
+  API, and retrieval pipeline look the way they do without re-deriving it
+  from code.
+- Decisions that turn out wrong are corrected via a visible trail
+  (superseding ADRs) instead of silently rewritten history.
+
+### Negative
+- Adds minor overhead — anyone making a significant architectural change must
+  also write or update an ADR.
+
+## Alternatives Considered
+
+- **No formal record, rely on commit messages/PR descriptions**: rejected —
+  these are hard to discover later and don't survive squash-merges or
+  history rewrites.
+- **Full MADR template (with explicit "Decision Drivers" and scored option
+  comparison tables)**: rejected as too heavyweight for this project's current
+  size; we can adopt more structure later if needed via a new ADR.