From 3e5765be4e86be1cdb494f1e12fca5cc7d988a9a Mon Sep 17 00:00:00 2001 From: Brummel Date: Sun, 31 May 2026 14:05:45 +0200 Subject: [PATCH] spec: glossary integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Optional paths.glossary slot: when set, the file is standing reading for every role (no separate standing_reading.always entry). Adds a docs/glossary-convention.md single-sourcing the three-field format, the standing-reading obligation, and the boss record-reality write-rule; plus a dogfooded docs/glossary.md over the plugin's own vocabulary. Guidance, not enforcement — no synonym check. Grounding-check PASS: the one new semantic (paths.glossary auto- promotion into standing reading) is carried as deliverable wiring, not assumed to pre-exist. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../2026-05-31-glossary-integration-design.md | 252 ++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 docs/specs/2026-05-31-glossary-integration-design.md diff --git a/docs/specs/2026-05-31-glossary-integration-design.md b/docs/specs/2026-05-31-glossary-integration-design.md new file mode 100644 index 0000000..c5cd260 --- /dev/null +++ b/docs/specs/2026-05-31-glossary-integration-design.md @@ -0,0 +1,252 @@ +# Glossary Integration — Design Spec + +**Date:** 2026-05-31 +**Status:** Draft — awaiting user spec review +**Authors:** orchestrator + Claude + +## Goal + +Give consuming projects a single, canonical place that pins +nomenclature so terminology does not drift over time, and so that +LLM-driven work reuses the established term for a concept instead of +coining a fresh synonym each session. The glossary is **guidance, +not enforcement**: it becomes standing reading for every skill and +agent, but no tool scans artefacts for forbidden synonyms. + +The plugin stays mechanics-only. This cycle adds: + +1. an optional profile slot `paths.glossary`, +2. a convention doc that owns the glossary format and the write + discipline, +3. standing-reading wiring so a set `paths.glossary` is read by + every role automatically, +4. a boss write-rule (record reality, never invent), +5. a dogfooded `docs/glossary.md` in this repo proving the format + on the plugin's own vocabulary. + +## Architecture + +The glossary rides the **existing standing-reading mechanism** +rather than introducing a new delivery path. One optional path slot +carries the whole feature: + +- `paths.glossary` (optional). **If set, the file it points to is + automatically standing reading for every agent** — no separate + `standing_reading.always` entry is required. If unset, the whole + feature is a documented no-op, exactly matching the plugin's + existing "missing optional slot = silent skip" contract. + +Semantics ("set ⇒ standing reading for all roles") live in +`docs/profile-schema.md` next to the slot, so the wiring is +single-sourced and a project cannot set the path yet forget to make +it read. + +The format and the write discipline live in a new +`docs/glossary-convention.md`, following the established +`docs/`-doc pattern (`pipeline.md`, `profile-schema.md`). Skills and +`boss` cross-reference it rather than restating it. + +## Concrete code shapes + +### 1. The delivered `docs/glossary.md` (dogfood — primary artefact) + +This is the actual file the feature produces, shown on the plugin's +own vocabulary. Per-term blocks (not a table) so boss-appended +entries produce clean line-wise diffs. + +```markdown +# Glossary + +Canonical nomenclature for this project. Use the **canonical term**; +never use a term under **Avoid**. If you need a concept that is not +listed here, reuse the closest existing term — do not silently coin +a new one. New entries are added only to record nomenclature already +in consistent use; see `docs/glossary-convention.md`. + +--- + +### cycle +**Avoid:** release, epic, round, sprint +One round in the pipeline graph (design → plan → execute → review → +close). Not the top-level container — that is a *milestone*. + +### milestone +**Avoid:** epic, phase, big-ticket +A tracker container spanning potentially many cycles; closes only +when its promised work is complete and functional. A cycle close is +never a milestone close. + +### iteration +**Avoid:** sprint, story, step +The default sub-unit of a cycle; one pass through the inner loop. A +project may rename it via `vocabulary.subcycle`. + +### drift +**Avoid:** divergence, rot, skew +Accumulated mismatch between the codebase and its design ledger. +Surfaced by the architect agent at audit, not by any synonym check. + +### hard-gate +**Avoid:** checkpoint, barrier, blocker +A pipeline point that forbids downstream work until an artefact +exists and is approved (e.g. an approved spec before any plan). +``` + +### 2. The profile slot (worked author example) + +What a consuming project writes — one line opts the whole project +in: + +```yaml +# /.claude/dev-cycle-profile.yml +paths: + spec_dir: docs/specs + plan_dir: docs/plans + glossary: docs/glossary.md # optional — if set, every agent reads + # it as standing reading + code_roots: [src] +``` + +### 3. The boss write-rule (lives in `docs/glossary-convention.md`) + +`boss/SKILL.md` carries only a cross-reference pointer; the rule +text itself is single-sourced here: + +```markdown +## Extending the glossary (user + boss only) + +The user may edit the glossary at any time. In a `/boss` session the +orchestrator may extend it autonomously — but only to **record +reality, never to invent**: + +- A term already used consistently across shipped artefacts but not + yet listed → add it, with its known synonyms under **Avoid**. +- A drift the orchestrator just resolved (two terms for one concept) + → record the winner as the canonical entry, the loser under + **Avoid**. + +The orchestrator never coins a brand-new term into the glossary: a +term earns its entry by already being in consistent use. All other +skills and agents are read-only consumers of the glossary. +``` + +### Implementation shape (secondary — before → after) + +**`templates/project-profile.yml`**, `paths:` block: + +```yaml +# before +paths: + spec_dir: docs/specs + plan_dir: docs/plans + # design_ledger: design/INDEX.md # optional + code_roots: [src] + +# after +paths: + spec_dir: docs/specs + plan_dir: docs/plans + # glossary: docs/glossary.md # optional — if set, read as + # standing reading by every role + # design_ledger: design/INDEX.md # optional + code_roots: [src] +``` + +**`docs/profile-schema.md`**, `paths` section: add a `glossary` +entry documenting the slot AND the "set ⇒ standing reading for all +roles" semantics, and a no-op-when-unset note. + +**`docs/agent-template.md`** and **`docs/pipeline.md`**: where +standing reading is described, add one sentence: a set +`paths.glossary` is part of every role's standing reading. + +**`boss/SKILL.md`**: add a short pointer (in the process/loop and a +cross-reference entry) to `docs/glossary-convention.md` for the +record-reality write-rule. No rule text duplicated. + +## Components + +- **`docs/glossary.md`** (new) — dogfooded glossary for the plugin's + own vocabulary; the lived proof of the format. +- **`docs/glossary-convention.md`** (new) — single source for the + format (three fields: canonical term, Avoid synonyms, ≤2-sentence + definition), the standing-reading obligation, and the boss + record-reality write-rule. +- **`paths.glossary` slot** — in `templates/project-profile.yml` + (commented) and `docs/profile-schema.md` (documented). +- **Standing-reading wiring** — one sentence each in + `docs/agent-template.md` and `docs/pipeline.md`. +- **`boss/SKILL.md`** — cross-reference pointer to the convention. + +## Data flow + +Author/consume: + +1. A project sets `paths.glossary: docs/glossary.md` and writes the + file using the convention's three-field block format. +2. Every dispatched skill/agent, per the standing-reading contract, + reads the glossary alongside `CLAUDE.md` and the git-log entries. +3. When producing prose or naming a concept, the role uses the + canonical term and avoids the listed synonyms. + +Extend (boss): + +1. In `/boss`, when the orchestrator observes a term already in + consistent use but unlisted, or has just resolved a two-term + drift, it appends/edits one block per the convention. +2. The edit is an ordinary working-tree change committed under the + only-orchestrator-commits rule; no separate gate. + +Unset: + +- No `paths.glossary` ⇒ standing reading omits it, the convention + doc is inert reference, boss has nothing to extend. Documented + no-op. + +## Error handling + +- **Slot set but file missing:** a role that cannot read the + glossary treats it as it treats any missing standing-reading + source — notes the gap, proceeds; this is a profile error for the + project to fix, not a plugin failure. +- **Boss tempted to invent:** guarded by the convention's + red-flag/rationalisation framing ("a term earns its entry by + already being in use"); mirrors the existing boss anti-invention + discipline. +- **Convention vs. glossary drift:** the convention owns format and + rule; `docs/glossary.md` is an instance. The dogfood file is + expected to conform and serves as the conformance example. + +## Testing strategy + +This is a docs/profile cycle with no executable surface; the plugin +has no test runner (`commands.test` is empty for this repo). The +acceptance evidence is therefore the concrete artefacts above plus +two manual conformance checks: + +1. **Dogfood conformance:** every block in `docs/glossary.md` has + exactly the three fields the convention mandates (canonical term + heading, **Avoid:** line, ≤2-sentence definition). +2. **No-op proof:** the wording added to `profile-schema.md`, + `agent-template.md`, and `pipeline.md` states the unset-slot case + so a profile without `glossary` provably skips the feature. + +No fenced block in this spec targets a configured `spec_validation` +parser (this repo declares none); the parse-every-block gate is a +documented no-op here. + +## Acceptance criteria + +- `paths.glossary` documented in `docs/profile-schema.md` (slot + + "set ⇒ standing reading" semantics + unset no-op) and present + commented in `templates/project-profile.yml`. +- `docs/glossary-convention.md` exists and owns: the three-field + format, the standing-reading obligation, and the boss + record-reality write-rule (with the never-invent guard). +- `docs/agent-template.md` and `docs/pipeline.md` each state that a + set `paths.glossary` is standing reading for every role. +- `boss/SKILL.md` cross-references the convention for the write-rule + without duplicating its text. +- `docs/glossary.md` exists, dogfoods the plugin vocabulary, and + every entry conforms to the three-field format. +- With no `paths.glossary` set, the feature is a provable no-op.