From 0c6253d74dd64c7ccefdb847b27f8e929ecd70c3 Mon Sep 17 00:00:00 2001 From: Brummel Date: Sun, 31 May 2026 14:27:14 +0200 Subject: [PATCH] plan: glossary integration Task-by-task plan for the glossary-integration spec. Seven tasks plus a final sweep: create docs/glossary-convention.md and the dogfooded docs/glossary.md, document the paths.glossary slot in profile-schema.md, add the commented slot to the project-profile template, wire one standing-reading sentence each into agent-template.md and pipeline.md, and point boss/SKILL.md at the convention's write-rule. Docs-only cycle: no test runner, so each task closes on a grep presence assertion calibrated against verified zero baselines. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/plans/2026-05-31-glossary-integration.md | 418 ++++++++++++++++++ 1 file changed, 418 insertions(+) create mode 100644 docs/plans/2026-05-31-glossary-integration.md diff --git a/docs/plans/2026-05-31-glossary-integration.md b/docs/plans/2026-05-31-glossary-integration.md new file mode 100644 index 0000000..0e215a3 --- /dev/null +++ b/docs/plans/2026-05-31-glossary-integration.md @@ -0,0 +1,418 @@ +# Glossary Integration — Implementation Plan + +> **Parent spec:** `docs/specs/2026-05-31-glossary-integration-design.md` +> +> **For agentic workers:** REQUIRED SUB-SKILL: use the +> `implement` skill to run this plan. Steps use `- [ ]` +> checkboxes for tracking. + +**Goal:** Add an optional `paths.glossary` profile slot whose file +becomes standing reading for every role, a convention doc that owns +the format and the boss write-rule, and a dogfooded `docs/glossary.md` +for the plugin's own vocabulary. + +**Architecture:** The glossary rides the existing standing-reading +mechanism — one optional path slot, no new delivery path. The +"set ⇒ standing reading for every role" semantics are single-sourced +at the `paths.glossary` row in `profile-schema.md`; `agent-template.md` +and `pipeline.md` carry one referencing sentence each. The format and +write-rule live once in `docs/glossary-convention.md`; `boss/SKILL.md` +only points to it. + +**Tech Stack:** Markdown docs, one YAML template. No executable +surface — this repo has no test runner, so each task verifies with a +`grep` presence assertion against the file it touched. + +--- + +## Note on verification & the parse gate + +This repo ships **no** `.claude/dev-cycle-profile.yml`, so +`commands.test` is empty and `spec_validation` is undeclared. Per the +planner self-review parse gate (`docs/profile-schema.md` +§ `spec_validation`), the inlined blocks here are `markdown` / `yaml` +fences with **no configured parser** — the parse-the-bytes-you-inline +gate is a documented no-op for this plan. Each task therefore closes +on a `grep` assertion whose pattern is named to match ≥1 real line in +the file just written (self-review item 8), not a test-runner result. + +--- + +## Task 1: Create `docs/glossary-convention.md` + +The single source for the glossary format, the standing-reading +obligation, and the boss record-reality write-rule. Created first so +later tasks can cross-reference it. + +**Files:** +- Create: `docs/glossary-convention.md` + +- [ ] **Step 1: Write the convention doc** + +Create `docs/glossary-convention.md` with exactly this content (the +outer fence is four backticks so the inner three-backtick format +example below survives — write only the inner content to the file): + +````markdown +# 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. +```` + +- [ ] **Step 2: Verify the three load-bearing parts are present** + +Run: `grep -c -e '## Format' -e 'record reality' -e 'standing reading' docs/glossary-convention.md` +Expected: a count of at least `3` (the format section, the +record-reality rule, and the reading obligation are all present). + +--- + +## Task 2: Create `docs/glossary.md` (dogfood) + +The plugin's own glossary, proving the format on real vocabulary. +Content is lifted verbatim from the spec's primary artefact (spec +lines 58-92). + +**Files:** +- Create: `docs/glossary.md` + +- [ ] **Step 1: Write the dogfood glossary** + +Create `docs/glossary.md` with exactly this content: + +```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 `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). +``` + +- [ ] **Step 2: Verify every entry conforms to the three-field shape** + +Run: `grep -c '^\*\*Avoid:\*\*' docs/glossary.md` +Expected: `5` (one Avoid line per term: cycle, milestone, iteration, +drift, hard-gate). + +--- + +## Task 3: Document the slot in `docs/profile-schema.md` + +Add the `glossary` row to the `paths` table (single source for the +"set ⇒ standing reading" semantics) and a referencing sentence in the +`standing_reading` section. + +**Files:** +- Modify: `docs/profile-schema.md:13` (paths table) and `:152` + (standing_reading tail) + +- [ ] **Step 1: Add the `glossary` row after the `plan_dir` row** + +Exact-string replace this anchor: + +``` +| `plan_dir` | string | `docs/plans` | Where the planner skill writes plans. | +``` + +with: + +``` +| `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`. | +``` + +- [ ] **Step 2: Add the cross-reference sentence at the end of `standing_reading`** + +Exact-string replace this anchor (end of the `standing_reading` +section, just before `## \`git\``): + +``` +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"`. + +## `git` +``` + +with: + +``` +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` +``` + +- [ ] **Step 3: Verify both edits landed** + +Run: `grep -c 'glossary' docs/profile-schema.md` +Expected: a count of `2` (the new `paths` table row line, and the one +new sentence line in the `standing_reading` section). `grep -c` counts +matching lines, so the table row counts once even though it names the +glossary twice. + +--- + +## Task 4: Add the commented slot to `templates/project-profile.yml` + +**Files:** +- Modify: `templates/project-profile.yml:9` (paths block) + +- [ ] **Step 1: Insert the commented `glossary` line after `plan_dir`** + +Exact-string replace this anchor: + +``` + spec_dir: docs/specs + plan_dir: docs/plans + # design_ledger: design/INDEX.md # optional +``` + +with: + +``` + 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 +``` + +- [ ] **Step 2: Verify the commented slot is present** + +Run: `grep -c 'glossary: docs/glossary.md' templates/project-profile.yml` +Expected: `1`. + +--- + +## Task 5: Add the standing-reading sentence to `docs/agent-template.md` + +**Files:** +- Modify: `docs/agent-template.md:125` (Standing reading list section) + +- [ ] **Step 1: Append the `paths.glossary` sentence to the standing-reading paragraph** + +Exact-string replace this anchor: + +``` +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." + +The agent file itself does not hardcode file paths. +``` + +with: + +``` +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. +``` + +- [ ] **Step 2: Verify the sentence landed** + +Run: `grep -c 'paths.glossary' docs/agent-template.md` +Expected: `1`. + +--- + +## Task 6: Add the standing-reading sentence to `docs/pipeline.md` + +`pipeline.md` does not currently mention standing reading; the +natural home is the tail of the "Pipeline configuration" section, +which already cross-references the profile. + +**Files:** +- Modify: `docs/pipeline.md:178` (end of Pipeline configuration) + +- [ ] **Step 1: Append the glossary sentence after the configuration cross-reference** + +Exact-string replace this anchor (the final line of the file): + +``` +See `profile-schema.md` for the syntax. +``` + +with: + +``` +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. +``` + +- [ ] **Step 2: Verify the sentence landed** + +Run: `grep -c 'paths.glossary' docs/pipeline.md` +Expected: `1`. + +--- + +## Task 7: Add the cross-reference pointer to `boss/SKILL.md` + +Boss gets a pointer to the convention's write-rule in two places: the +loop (Step 4) and the Cross-references list. No rule text is +duplicated. + +**Files:** +- Modify: `boss/SKILL.md` (Step 4 loop area; Cross-references section) + +- [ ] **Step 1: Add the write-rule pointer after the Step-4 decision bullets** + +Exact-string replace this anchor: + +``` + fieldtest green and stays a deliberate manual act (see + `../docs/pipeline.md` § Milestone-close gate). + +### Step 5 — On done-state: Notify +``` + +with: + +``` + 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 +``` + +- [ ] **Step 2: Add the Cross-references bullet** + +Exact-string replace this anchor: + +``` +- **Queue:** the URL configured under `git.issue_tracker.url` in + the profile; CLI command at `git.issue_tracker.list_cmd`. +- **Downstream skills dispatched:** `../brainstorm`, +``` + +with: + +``` +- **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`, +``` + +- [ ] **Step 3: Verify both pointers landed** + +Run: `grep -c 'glossary-convention.md' boss/SKILL.md` +Expected: `2`. + +--- + +## Final acceptance sweep + +- [ ] **Step 1: Confirm all spec acceptance criteria are covered** + +Run: `ls docs/glossary.md docs/glossary-convention.md && grep -l 'glossary' docs/profile-schema.md templates/project-profile.yml docs/agent-template.md docs/pipeline.md boss/SKILL.md` +Expected: both new files listed, and all five modified files reported +as containing `glossary`.