Files

T

claude@clouddev1 9f15f386d5 docs(adr): design the DSL→SQL teaching echo (ADR-0038) + dependencies

Realises ADR-0030 §10 (the DSL→SQL teaching bridge) as a /runda'd design
set, before implementation:

- ADR-0037 (new): execution-time mode side-channel — SubmissionMode
  {Simple, Advanced, AdvancedOneShot} threaded Action→worker, output-only;
  redeems ADR-0033 Amendment 3's deferred follow-up. Replay stays silent.
- ADR-0038 (new): the teaching echo + full catalogue (Buckets A/B/C),
  the copy-paste round-trip contract, the three-category framework, and
  the Value→SQL-literal renderer. DDL + show-data centric (overlapping
  DML is SQL-first, so already SQL). Build-order deps recorded.
- ADR-0035 Amendment 2: standard-first dialect stance + ALTER COLUMN
  SET/DROP NOT NULL, SET/DROP DEFAULT, ISO SET DATA TYPE gap-fill.
- ADR-0033 Amendment 4: reclassifies the `update … --all-rows`
  non-fall-back as a bug; it now falls back to the DSL Update and echoes
  (keyed on adjacent `--`; spaced arithmetic preserved).
- ADR-0039 (new): EXPLAIN over advanced SQL — decision recorded, build
  deferred; supersedes ADR-0030 §13 OOS-2.
- ADR-0000: out-of-scope discipline (deferred vs rejected). README index
  updated for all of the above.

Reconcile CLAUDE.md: simple-mode column ops are implemented, not pending
(requirements.md C2/B2 already [x]).

2026-05-27 20:44:38 +00:00

2.7 KiB

Raw Blame History

ADR-0000: Record architecture decisions

Status

Accepted

Context

The RDBMS Playground project will accumulate design decisions as it grows. We want those decisions to be traceable, reviewable, and easy to challenge later when context has changed.

Decision

Record significant architecture and product decisions as Architecture Decision Records (ADRs) in docs/adr/, using the Michael Nygard format (Status, Context, Decision, Consequences). Files are numbered sequentially with a four-digit prefix and a kebab-case slug, e.g. 0001-language-and-tui-framework.md.

Each ADR captures one decision. Superseding a decision means adding a new ADR that references the old one and marking the old one as "Superseded by ADR-NNNN".

ADRs document decisions, not speculation. An idea under discussion belongs in conversation, an issue, or a design note — not an ADR. An ADR is written once a decision has actually been made.

Index discipline

docs/adr/README.md contains the canonical index of all ADRs. Whenever an ADR is added, renamed, or has its status changed (e.g. "Superseded by ADR-NNNN"), the index MUST be updated in the same change. An ADR change without a corresponding index update is incomplete.

The index lists ADRs in numerical order. Each entry shows the number, title, and — where relevant — status annotations such as "Superseded by ADR-NNNN" or "Deprecated".

Out-of-scope discipline

ADRs (and the plans they spawn) lean heavily on "out of scope" language. The phrase carries two very different meanings, and conflating them misleads a later reader:

Deferred — out of scope for this plan / phase / step, but a reasonable thing to do later. A sequencing decision, effectively a tracked TODO. Where possible, point at where it will be picked up.
Rejected — considered and deliberately not done, on principle. Durable. State the reason.

When writing an out-of-scope item, say which kind it is — e.g. OOS (deferred) / OOS (rejected: <reason>), or the equivalent in prose — so a future reader can tell a standing decision from a not-yet. A bare "out of scope" is ambiguous and tends to read, wrongly, as permanent. (Motivating example: ADR-0030 §13 OOS-2 was a deferred scope exclusion that read as a permanent rejection until ADR-0039 lifted it.)

Consequences

New significant decisions require an ADR before or alongside the implementation that depends on them.
Old decisions remain visible even after they are superseded.
Reviewers can audit the rationale chain by reading docs/adr/ in order.
The index in README.md stays trustworthy because keeping it current is part of every ADR change, not an afterthought.

2.7 KiB Raw Blame History