docs: Add ADRs

.github/workflows/release.yml

@@ -61,4 +61,4 @@ jobs:
       - name: Create GitHub Release
         uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2.5.0
         with:
-          generate_release_notes: true
+          generate_release_notes: true

AGENTS.md

@@ -6,6 +6,35 @@
 - We strive to achieve excellent stability by enforcing invariants in the code:
   - `assert!` and `.expect()` for simple cases
   - `invariants.rs` otherwise, to skip the coverage of unreachable code
+- We maintain the architecture decision records (ADRs)
+  - AI agent is responsible for creating new ADR when such decision was made during agentic coding session
+
+# Architecture Decision Records (ADRs)
+
+- **Location**: `docs/adr/`
+- **Naming**: `ADR-XXXX-short-title-in-kebab-case.md` (`XXXX` is a sequential number).
+- **Template**:
+
+  ```markdown
+  # ADR-XXXX: Title of the Decision
+
+  - **Status**: Proposed | Accepted | Deprecated | Superseded by [ADR-YYYY](ADR-YYYY-...)
+  - **Date**: YYYY-MM-DD
+
+  ## Context
+
+  Describe the issue, problem, or driving force.
+
+  ## Decision
+
+  Clearly state the decision that was made.
+
+  ## Consequences
+
+  - **Positive**: Benefits, alignment with goals.
+  - **Negative**: Drawbacks, trade-offs, future challenges.
+  - **Considered Alternatives**: Describe rejected options and why.
+  ```
 
 # Plotnik Query Language
 

docs/adr/ADR-0001-query-parser.md

@@ -0,0 +1,21 @@
+# ADR-0001: Hand-written Parser with Rowan
+
+- **Status**: Accepted
+- **Date**: 2025-12-08 (retrospective)
+
+## Context
+
+We need a resilient parser with excellent, user-friendly diagnostics and fine-grained error recovery. Parser generators like `chumsky` were considered but offer insufficient control.
+
+## Decision
+
+We implemented a hand-written recursive descent parser.
+
+- **Lexer**: `logos` for zero-copy tokenization.
+- **CST**: `rowan` to build a lossless Concrete Syntax Tree, preserving all source text and trivia.
+- **AST**: A typed AST wrapper provides a clean API for semantic analysis.
+
+## Consequences
+
+- **Positive**: Full control over error recovery, enabling high-quality diagnostics. The lossless CST is ideal for accurate error reporting and future tooling (e.g., formatters).
+- **Negative**: Higher initial development effort and complexity compared to parser generators.

docs/adr/ADR-0002-diagnostics-system.md

@@ -0,0 +1,21 @@
+# ADR-0002: Prioritized Diagnostics System
+
+- **Status**: Accepted
+- **Date**: 2025-12-08 (retrospective)
+
+## Context
+
+A single syntax error can cause many cascading downstream errors, overwhelming the user. Our goal is to present only the most relevant, actionable feedback.
+
+## Decision
+
+We implemented a diagnostics system with priority-based suppression.
+
+- **Priority**: A central `DiagnosticKind` enum defines all possible diagnostics, ordered by priority.
+- **Suppression**: When multiple diagnostics overlap, a filtering process suppresses lower-priority ones, effectively hiding noise and showing the likely root cause.
+- **Formatting**: The `annotate-snippets` crate renders rich, user-friendly error messages with source context.
+
+## Consequences
+
+- **Positive**: Provides high-quality, actionable feedback by eliminating distracting cascading errors. The system is decoupled and independently testable.
+- **Negative**: The suppression logic adds complexity and requires careful maintenance and tuning to remain effective.

docs/adr/README.md

@@ -0,0 +1,52 @@
+# The Plotnik ADR System
+
+An ADR system documents important architectural decisions, their context, and their consequences. This helps maintain architectural consistency and provides valuable context for current and future contributors.
+
+## 1. Location
+
+As hinted at in your `AGENTS.md`, the best place for these is `docs/adr/`.
+
+## 2. Naming Convention
+
+Files should be named `ADR-XXXX-short-title-in-kebab-case.md`, where `XXXX` is a sequential number (e.g., `0001`, `0002`).
+
+## 3. ADR Template
+
+Create a file named `ADR-0000-template.md` in the `docs/adr/` directory with the following content. This makes it easy for anyone to start a new record.
+
+```markdown
+# ADR-XXXX: Title of the Decision
+
+- **Status**: Proposed | Accepted | Deprecated | Superseded by [ADR-YYYY](ADR-YYYY-...)
+- **Date**: YYYY-MM-DD
+
+## Context
+
+Describe the issue, problem, or driving force that led to this decision. What are the constraints and requirements? What is the scope of this decision? This section should be understandable to someone without deep project knowledge.
+
+## Decision
+
+Clearly and concisely state the decision that was made. This is the "what," not the "why."
+
+## Consequences
+
+This is the most critical section. Describe the results, outcomes, and trade-offs of the decision.
+
+### Positive Consequences
+
+- What benefits does this decision provide?
+- How does it align with the project's goals (e.g., resilience, user experience, performance)?
+
+### Negative Consequences
+
+- What are the drawbacks or costs?
+- What trade-offs were made?
+- What future challenges might this decision introduce?
+
+### Considered Alternatives
+
+- **Alternative 1:** A brief description of a rejected option.
+  - _Pros_: Why was it considered?
+  - _Cons_: Why was it rejected?
+- **Alternative 2:** ...
+```