Problem
When a new settings key reuses a word with established meaning (e.g. model vs default_model), nothing flags that its semantics contradict sibling keys. The model-name invariant is now documented in docs/configuration.md (2026-08-09), but there is no mechanical check that documented settings keys stay consistent with the Settings struct fields, so the F-002-class drift can recur silently.
Proposed Solution
A lint (extending scripts/lint-domain-glossary.py or a new script, run from just ci) that cross-references the settings keys documented in docs/configuration.md with the Settings struct fields and flags undocumented keys, renamed keys, or vocabulary conflicts.
Alternatives Considered
A vocabulary table in docs/configuration.md without enforcement.
Additional Context
Recorded in ~/.local/share/cake/DESIRES.md (2026-08-09). The F-001 fix initially went the wrong direction (raw provider id instead of [[models]] name); the invariant is in docs/configuration.md Models section.
Problem
When a new settings key reuses a word with established meaning (e.g.
modelvsdefault_model), nothing flags that its semantics contradict sibling keys. Themodel-name invariant is now documented indocs/configuration.md(2026-08-09), but there is no mechanical check that documented settings keys stay consistent with theSettingsstruct fields, so the F-002-class drift can recur silently.Proposed Solution
A lint (extending
scripts/lint-domain-glossary.pyor a new script, run fromjust ci) that cross-references the settings keys documented indocs/configuration.mdwith theSettingsstruct fields and flags undocumented keys, renamed keys, or vocabulary conflicts.Alternatives Considered
A vocabulary table in
docs/configuration.mdwithout enforcement.Additional Context
Recorded in
~/.local/share/cake/DESIRES.md(2026-08-09). The F-001 fix initially went the wrong direction (raw provider id instead of[[models]]name); the invariant is indocs/configuration.mdModels section.