From 58aa74290161ce248e393567a49d549af4caeff0 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Fri, 26 Jun 2026 21:59:22 +0300 Subject: [PATCH] chore: update planning-convention to 1.1.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Applies the 1.1.0 CHANGELOG delta (UPDATE from 1.0.0): the glossary artifact on the architecture/ axis. - Add planning/_templates/glossary.md (verbatim canonical copy, §1). - Merge the `### Glossary` prose and the two-axis mention into planning/README.md (§2). - Add a glossary pointer to architecture/README.md so the ubiquitous-language page is discoverable from the truth-home index. - Resync planning/index.py verbatim (no validator change in 1.1.0; only the noqa comment text, which fixes a stale cross-repo reference). - Record planning/.convention-version → 1.1.0. architecture/glossary.md itself is authored lazily (APPLY §5 skipped on UPDATE) — it lands with the first change that needs a term. just check-planning → planning: OK; just lint-ci passes. Co-Authored-By: Claude Opus 4.8 (1M context) --- architecture/README.md | 7 +++++++ planning/.convention-version | 2 +- planning/README.md | 25 +++++++++++++++++++++++-- planning/_templates/glossary.md | 15 +++++++++++++++ planning/index.py | 2 +- 5 files changed, 47 insertions(+), 4 deletions(-) create mode 100644 planning/_templates/glossary.md diff --git a/architecture/README.md b/architecture/README.md index 90bd737..5c1c631 100644 --- a/architecture/README.md +++ b/architecture/README.md @@ -19,6 +19,13 @@ These files carry **no frontmatter** — they are prose, dated by git. - [transaction.md](transaction.md) — `Transaction`, the session context manager. - [settings.md](settings.md) — `get_retries_number`, the env-driven retry count. +## Glossary + +[`glossary.md`](glossary.md) holds the project's ubiquitous language — the domain +terms code, specs, and these capability files share. Living prose, no +frontmatter, authored lazily: it appears when the first term is worth pinning +down. + ## Promotion rule Shipping a change hand-edits the affected capability file(s) here to match the diff --git a/planning/.convention-version b/planning/.convention-version index 3eefcb9..9084fa2 100644 --- a/planning/.convention-version +++ b/planning/.convention-version @@ -1 +1 @@ -1.0.0 +1.1.0 diff --git a/planning/README.md b/planning/README.md index 2fdd7ac..18b114a 100644 --- a/planning/README.md +++ b/planning/README.md @@ -49,8 +49,9 @@ realized result, and run `just check-planning` before pushing. ### Two axes, never mixed -- **`architecture/` (repo root) — the present.** One file per capability, - living prose, updated in the same PR that ships the change. The truth home. +- **`architecture/` (repo root) — the present.** One file per capability, plus + a single `glossary.md` (the ubiquitous language); living prose, updated in the + same PR that ships the change. The truth home. - **`planning/changes/` — the past-and-pending.** One folder per change, kept in place after ship. @@ -60,6 +61,26 @@ code** — the edit rides in the same diff and is reviewed with it, never applie as a separate post-merge step. That hand-edit is what keeps `architecture/` true; the bundle stays in `changes/` as the *why*. +### Glossary + +`architecture/glossary.md` is the project's **ubiquitous language** — one page +defining the domain terms that code, specs, and capability pages all share. Like +the capability files beside it, it is living prose with **no frontmatter**, dated +by git, and authored lazily: it appears when the first term is worth pinning down. + +Each entry is a term, a one-or-two-sentence definition of what it *is* (not what +it does), and an optional `_Avoid_:` line naming the synonyms to reject: + +```md +**Timer**: +A scheduled future delivery, identified by a timer id. +_Avoid_: job, task, alarm +``` + +Keep it a glossary, not a spec — no implementation detail. A change that +introduces or sharpens a term updates `glossary.md` in the same PR, the same way +a behavior change promotes into a capability file. + ### Change bundles A change is a folder `changes/YYYY-MM-DD.NN-/`: diff --git a/planning/_templates/glossary.md b/planning/_templates/glossary.md new file mode 100644 index 0000000..82385c3 --- /dev/null +++ b/planning/_templates/glossary.md @@ -0,0 +1,15 @@ +# Glossary + +The project's ubiquitous language — the domain terms that code, specs, and +capability pages share. Living prose, no frontmatter, dated by git. Each entry is +a term, what it *is* (not what it does), and the synonyms to avoid. No +implementation detail; this is a glossary, not a spec. + +**Term**: +A one-or-two-sentence definition of what it is. +_Avoid_: rejected-synonym, another-one + +**Another term**: +Define what it is, tightly. Group related terms under `##` subheadings when +natural clusters emerge; a flat list is fine when they don't. +_Avoid_: … diff --git a/planning/index.py b/planning/index.py index a1632e1..f10f5e0 100644 --- a/planning/index.py +++ b/planning/index.py @@ -1,4 +1,4 @@ -# ruff: noqa: INP001, D212 # planning/ is not a Python package; D212/D213 conflict differs from faststream-outbox +# ruff: noqa: INP001, D212 # planning/ is not a Python package; the module docstring uses the D213 (second-line summary) style, so D212 is suppressed """ Generate the planning index from frontmatter.