spec-kitty / spec-kitty/spec-kitty
Glossary: add alias/banned-synonym governance (full canonical-term enforcement)
- Dominant language
- Python
- Stars
- 1.6k
- Forks
- 165
- Avg merge
- 13h 53m
- Merged PRs (30d)
- 336
Description
## Context
Follow-up from mission `docs-ia-onboarding-overhaul-01KY02JB` (WP10 — Terminology Canon Sweep & Follow-Up Issue), per spec.md **C-003**:
> Full alias/banned-synonym glossary governance (a schema change to `.kittify/glossaries/spec_kitty_core.yaml` plus population) is out of scope for this mission; a GitHub issue is filed to track it as follow-up.
## Current state
- `.kittify/glossaries/spec_kitty_core.yaml` has 104 `surface`-keyed terms, each with a `definition`, `confidence`, and `status` field. There is **no `aliases` field** and no banned-synonym list anywhere in the schema.
- `tests/architectural/test_glossary_canonical_terms.py` (added in this mission, WP09) is a narrower check: it loads the live glossary seed and flags any occurrence in `docs/**/*.md` where a *known, multi-word* term appears with the wrong **casing/spelling** (e.g. "Work Package" instead of the canonical "work package"). It does **not** detect:
- Banned synonyms for a canonical term (e.g. someone writing "ceremony" instead of "status commit", or "feature" instead of "mission" outside the already-covered 2-term denylist in `test_no_legacy_terminology.py`).
- Aliases that should resolve to a canonical term but currently have no mapping in the glossary schema at all.
## Gap
There is no schema support for:
1. Declaring known aliases for a canonical term (so a linter/check could flag "X should be written as Y").
2. Declaring banned synonyms that must never appear in active docs/code (beyond the small hardcoded 2-term list in `test_no_legacy_terminology.py`).
## Suggested follow-up work
1. Extend `.kittify/glossaries/spec_kitty_core.yaml`'s schema with an `aliases` field (and optionally a `banned_synonyms` field) per term.
2. Populate aliases/banned synonyms for at least the highest-drift terms (candidates surfaced during this mission's terminology sweep: "Mission" vs "Feature", "work package" vs "WP"/"ticket", "target branch" vs "base branch" confusion, etc. — see `docs/development/terminology-sweep-report.md` and `kitty-specs/docs-ia-onboarding-overhaul-01KY02JB/docs-audit.md` for the raw casing-violation inventory this mission left out of scope).
3. Extend `tests/architectural/test_glossary_canonical_terms.py` (or add a sibling test) to enforce alias/banned-synonym resolution the same way it currently enforces canonical casing.
4. Decide whether banned-synonym enforcement should be a hard architectural gate (like `test_no_legacy_terminology.py`) or a softer warning tier, given the volume of pre-existing drift found (~200 non-canonical-casing occurrences remained out of this mission's scope in `docs/` alone after WP10's sweep).
## References
- Mission: `docs-ia-onboarding-overhaul-01KY02JB`
- `kitty-specs/docs-ia-onboarding-overhaul-01KY02JB/spec.md` — C-003
- `tests/architectural/test_glossary_canonical_terms.py`
- `.kittify/glossaries/spec_kitty_core.yaml`
Contributor guide
Research direction
Start with .kittify/glossaries/spec_kitty_core.yaml and tests/architectural/test_glossary_canonical_terms.py, then review tests for the existing legacy terminology denylist. Define the alias and banned-synonym schema and populate the highest-drift terms cited in the issue. Done means the architectural checks enforce the selected resolution behavior, with the hard-gate versus warning decision documented and tests passing.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, yaml
- Domain
- documentation, testing
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100