feat(glossary): add optional paths.glossary standing-reading slot
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) <noreply@anthropic.com>
This commit is contained in:
@@ -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`.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user