From 489949c663133de116bac387bc8b127d169fa058 Mon Sep 17 00:00:00 2001 From: Han Ngo Date: Sat, 18 Jul 2026 22:14:46 +0700 Subject: [PATCH] docs(glossary): land the plain-words glossary (ID-293 first slice) ID-293's five terms (gate ~1016 files, ledger ~780, lane ~647, mega ~532, harness ~319) are semantic-everywhere: each is a code identifier, config key, module dir, and file name, so a full rename is its own migration project, NOT a doc sweep (the row and the inventory both classify them that way, verdict "glossary / own project"). The honest, safe first slice is the glossary itself, which ID-293's own parked note names as the precondition ("unpark after ... the glossary lands"): a reader-facing map from each surviving jargon term to its everyday word, so onboarding gets the plain-words benefit without the destabilising 1000-file churn. Linked from the CONTRIBUTING Plain words rule. The five semantic renames are deferred to dedicated migration PRs (reported). Docs-only (inert). 718/718 meta. --- CONTRIBUTING.md | 5 +++ docs/glossary.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+) create mode 100644 docs/glossary.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8abbd35b..11fc4ec0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -77,6 +77,11 @@ Precedent renames: edge -> profile, surface/spoke/sources -> app, hub -> board (2026-07-16, sync module), leg -> stage / Specify-Execute-Observe-Govern -> Shape-Build-Watch-Check (2026-07-18, ADR-0034 amendment; Learn kept). +The still-coined terms that are too semantic-everywhere to rename yet (gate, +lane, ledger, mega, harness) have their plain-word equivalents in +[docs/glossary.md](docs/glossary.md), so a reader always has the everyday word +even before the rename migration (ID-293) runs. + ## Source The "rejection-first" framing of this document is adapted from [obra/superpowers v5.0.7 `AGENTS.md`](https://github.com/obra/superpowers/blob/main/AGENTS.md). Same source we adopted in v1.3 for `commands/kit-health.md` (see ADR-008). Specific rejection criteria here are the kit's own from `docs/PHILOSOPHY.md`, not lifted verbatim. diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 00000000..1c174ee9 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,81 @@ +# Glossary: the kit's words in plain English + +The kit tries to speak the simplest everyday word that fits (see the +[Plain words rule](../CONTRIBUTING.md#plain-words-rule-2026-07-16)). Some coined +or jargon terms still survive in code, config, and file names because renaming +them touches hundreds to a thousand+ files each, a migration project per term, +not a doc sweep. This page is the bridge: it maps each surviving jargon term to +the everyday word so a new reader never has to learn a coined concept to +understand the docs. + +Source of the ranked list: `docs/research/2026-07-16-plain-words-inventory.md`. + +## Semantic-everywhere terms (ID-293, rename deferred) + +These are the load-bearing coined words. Each appears in 300-1000+ files (code +identifiers, config keys, module and file names, test assertions), so a full +rename is its own migration project (ID-293) and is deliberately NOT done here. +Read the plain word; the jargon is what the code still calls it. + +| Jargon (in code) | Plain word | What it means | +|---|---|---| +| gate | a check / quality check | A checkpoint at a phase boundary that must pass before the work proceeds (e.g. the ship-gate refuses a push that has no proof of done). "Quality gate" is quasi-standard, so this one may stay. | +| lane | risk level | How much ceremony a task gets, sized to its risk: `tiny` / `normal` / `full`. A one-line typo fix is a low risk level; an auth change is a high one. | +| ledger | a log / an append-only history | The append-only record of what the run did (gates run, tokens spent, overrides). Never edited in place, only appended, so it is an audit trail. | +| mega / mega-goal | a roadmap (multi-goal program) | One destination decomposed into several dependent sub-goals shipped one PR at a time. `bin/mega` drives the reconcile/report/review of such a program. | +| harness | the kit | The whole machinery of this repo (hooks, commands, gates, agents). "The harness" and "the kit" mean the same thing; prefer "kit". | + +## Reader-facing jargon (plain word in prose; code name kept) + +Lower-blast-radius terms. The code keeps the name; when you write operator-facing +prose, prefer the plain word. + +| Jargon | Plain word | +|---|---| +| dispatch | hand work to a worker / send | +| orchestrate | coordinate (run sub-goals together) | +| lens | a review angle | +| verifier | a read-only checker | +| mirror | copy / sync the board out | +| promote | approve a staged item onto the board | +| scaffold | generate the starting skeleton | +| registry | a lookup table / manifest | +| spec-drift | the code no longer matches its spec | +| quiz-gate | the understanding-check nudge | +| over-suggest | the advisor's extra-suggestions mode | +| tombstone | a removed-item marker | +| surface | an operator-facing entry point (the sync-target sense is already "app") | + +## Terms kept because they are already standard + +These are industry words a user already knows; they earn their keep and are NOT +renamed: `git`, `PR`, `branch`, `commit`, `kanban`, `backlog`, `retro`, +`triage`, `cron`, `worktree`, `snapshot`, `debt`, `intake`, `adopt`, `manifest`, +`contract`, `proof-of-done`, `V-model`, `fan-out`, `wavefront`, `spanner`, +`descent`, `staging`. + +## Already renamed (for reference) + +The plain-words pass already landed these (old name kept as a legacy alias for +one release where it was a config key or command): + +| Old | New | +|---|---| +| edge | profile | +| surface / spoke / sources (sync target) | app | +| hub | board | +| leg | stage | +| Specify / Execute / Observe / Govern | Shape / Build / Watch / Check (Learn kept) | +| verif-counts | verify-counts | +| SDD (first use) | spec-driven development (SDD) | + +## Why the big five are not renamed here + +`gate` (~1016 files), `ledger` (~780), `lane` (~647), `mega` (~532), and +`harness` (~319) are semantic-everywhere: the name is a code identifier, a +config key, a module directory, and a file name, not just prose. Renaming any +one of them is a dedicated migration project with its own PR, legacy-alias +window, and full-suite run (ID-293). This glossary is the deliberate first slice: +it delivers the onboarding benefit (a reader always has the plain word) without +the destabilising code churn, and it is the precondition ID-293's own backlog +note names ("unpark after the glossary lands").