claude@clouddev1
9f15f386d5
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]).
69 lines
2.7 KiB
Markdown
69 lines
2.7 KiB
Markdown
# 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.
|