From a6794d178a73207100cb64dec8fdac8aad3bcf5e Mon Sep 17 00:00:00 2001 From: Brummel Date: Sun, 31 May 2026 14:35:57 +0200 Subject: [PATCH] feat(glossary): add optional paths.glossary standing-reading slot MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pins canonical nomenclature per project so terminology does not drift and LLM-driven work reuses the established term instead of coining a synonym each session. The glossary rides the existing standing-reading mechanism — one optional path slot, no new delivery path. Single-sourcing, to avoid cross-doc drift: - `paths.glossary` row in profile-schema.md owns the "set => standing reading for every role; unset => no-op" semantics; agent-template.md and pipeline.md each carry one referencing sentence, not a restatement. - glossary-convention.md owns the format (flat per-term blocks: canonical heading + Avoid line + <=2-sentence definition) and the boss record-reality-never-invent write-rule; boss/SKILL.md only points to it. - glossary.md dogfoods the format on the plugin's own vocabulary (cycle, milestone, iteration, drift, hard-gate). Write authority: user any time; boss autonomously but only to record terms already in consistent use or to settle a drift it just resolved — never to coin. All other roles are read-only consumers. No executable surface; this repo has no test runner, so each task closed on a grep presence-assertion against the file it touched. All eight gates green (T1 3>=3, T2 5, T3 2, T4 1, T5 1, T6 1, T7 2, final sweep present). Implements docs/specs/2026-05-31-glossary-integration-design.md. Co-Authored-By: Claude Opus 4.8 (1M context) --- boss/SKILL.md | 7 +++++ docs/agent-template.md | 4 +++ docs/glossary-convention.md | 59 +++++++++++++++++++++++++++++++++++ docs/glossary.md | 35 +++++++++++++++++++++ docs/pipeline.md | 4 +++ docs/profile-schema.md | 5 +++ templates/project-profile.yml | 2 ++ 7 files changed, 116 insertions(+) create mode 100644 docs/glossary-convention.md create mode 100644 docs/glossary.md diff --git a/boss/SKILL.md b/boss/SKILL.md index e7e07ca..2a61e19 100644 --- a/boss/SKILL.md +++ b/boss/SKILL.md @@ -125,6 +125,11 @@ For each dispatched skill's result, decide: fieldtest green and stays a deliberate manual act (see `../docs/pipeline.md` § Milestone-close gate). +If a term-drift is resolved during the loop — two names collapsed to +one, or a settled term not yet listed — record it in the project +glossary per `../docs/glossary-convention.md`: record reality, never +invent. This is the only glossary write authority outside the user. + ### Step 5 — On done-state: Notify Run the procedure named in "Done-state notifications" below. @@ -286,6 +291,8 @@ actionable ask, not a wrap-up summary. authority over skills, feature acceptance, RED-first for bugs. - **Queue:** the URL configured under `git.issue_tracker.url` in the profile; CLI command at `git.issue_tracker.list_cmd`. +- **Glossary write-rule:** `../docs/glossary-convention.md` — + record-reality discipline for the only autonomous glossary writer. - **Downstream skills dispatched:** `../brainstorm`, `../planner`, `../implement`, `../audit`, `../fieldtest`, `../debug`, `../docwriter`. diff --git a/docs/agent-template.md b/docs/agent-template.md index 9dda309..052e51f 100644 --- a/docs/agent-template.md +++ b/docs/agent-template.md @@ -124,6 +124,10 @@ and passes the resolved list to the agent via the carrier. The agent's body says, prosaically: "Read everything in the standing reading list before doing anything else." +A set `paths.glossary` is implicitly part of `always`, so every role +reads the project glossary without a per-role entry (see +`profile-schema.md` § `paths`). + The agent file itself does not hardcode file paths. ### Carrier contract diff --git a/docs/glossary-convention.md b/docs/glossary-convention.md new file mode 100644 index 0000000..9163ef8 --- /dev/null +++ b/docs/glossary-convention.md @@ -0,0 +1,59 @@ +# Glossary convention + +A project's glossary pins canonical 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. This file owns the format, the reading obligation, and the +write discipline; an individual project's glossary is an instance of +this convention. + +## Where it lives + +A project opts in by setting `paths.glossary` in its +`.claude/dev-cycle-profile.yml` (see `profile-schema.md` § `paths`). +When the slot is set, the file it names is standing reading for every +role — no separate `standing_reading.always` entry is required. When +the slot is unset, the whole feature is a documented no-op. + +## Format + +The glossary is a flat list of per-term blocks (not a table), so an +appended entry produces a clean line-wise diff. Each block has exactly +three fields: + +1. a level-3 heading naming the **canonical term** to use; +2. an **Avoid:** line listing known synonyms that must NOT be used; +3. a definition of at most two sentences. + +``` +### canonical-term +**Avoid:** synonym-one, synonym-two +A definition of at most two sentences. +``` + +A term with no known synonyms still carries an `**Avoid:** —` line so +every block has the same three-field shape. + +## Reading obligation + +Every skill and agent reads the glossary as part of its standing +reading and, when producing prose or naming a concept, uses the +canonical term and avoids the listed synonyms. If a concept is not +listed, reuse the closest existing term — do not silently coin a new +one. + +## 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. diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..3c87e91 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,35 @@ +# 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 `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). diff --git a/docs/pipeline.md b/docs/pipeline.md index 52b0d64..ad5a0c4 100644 --- a/docs/pipeline.md +++ b/docs/pipeline.md @@ -176,3 +176,7 @@ a different gate set (e.g. `planner` without a `brainstorm` gate, for trivial bug-fix iterations) configures it there. See `profile-schema.md` for the syntax. + +If the profile sets `paths.glossary`, that file is standing reading +for every role — the canonical-nomenclature source every skill and +agent consults (see `glossary-convention.md`). Unset, it is a no-op. diff --git a/docs/profile-schema.md b/docs/profile-schema.md index 6b67ef8..9ddf3fd 100644 --- a/docs/profile-schema.md +++ b/docs/profile-schema.md @@ -11,6 +11,7 @@ lowercase snake_case. Lists are YAML sequences. |---------------------|--------|------------------------|-------------| | `spec_dir` | string | `docs/specs` | Where the brainstorm skill writes specs. | | `plan_dir` | string | `docs/plans` | Where the planner skill writes plans. | +| `glossary` | string | (unset) | Canonical-nomenclature file (optional). If set, it is standing reading for every role — no separate `standing_reading.always` entry is needed; unset is a documented no-op. See `glossary-convention.md`. | | `design_ledger` | string | `design/INDEX.md` | Canonical specification index (optional — projects without a design ledger can omit). | | `design_contracts` | string | `design/contracts` | Directory of prose-authoritative contracts (optional). | | `design_models` | string | `design/models` | Directory of onboarding whitepapers (optional). | @@ -151,6 +152,10 @@ Entries may be shell commands as well as file paths — they are read as opaque strings the agent should fetch / execute, e.g. `"git log -10 --format=full"`. +A set `paths.glossary` is implicitly appended to every role's +`always` list — it does not need its own entry here. The slot's +authoritative semantics live at the `paths` row above. + ## `git` | Key | Type | Default | Description | diff --git a/templates/project-profile.yml b/templates/project-profile.yml index 9faf319..38ad208 100644 --- a/templates/project-profile.yml +++ b/templates/project-profile.yml @@ -7,6 +7,8 @@ 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 # design_contracts: design/contracts # optional # design_models: design/models # optional