Config Key Sanitation

Tools that drop recognition of old config keys create silent mystery debt. Old projects keep the key; future versions stop warning; people copy unexplained lines into new files. CLIs are the primary consumer, but any artifact that reads layered user/project/global config shares the failure mode.

Normative standard (OpenShellOrg / SOS): Config Key Sanitation Protocol.

Parent framework: Software Product Essentials (primary type consumer: CLI).

The failure mode

A familiar sequence:

  1. Tool warns: unknown or deprecated user config some-old-key.

  2. Maintainers remove the key from the accepted set.

  3. Later releases stop looking for it and stop warning.

The key remains in .npmrc, gitconfig, or an app settings file. Nobody alerts. A careful human researches; everyone else inherits folklore. Agents get asked to explain keys that the tool itself no longer acknowledges.

The sanitation pattern

Treat key history as a first-class artifact:

Status Runtime duty

active

Accept and document

deprecated

Accept and always warn (successor + timeline)

expired

Ignore value but always detect and say expired after version X

unknown

Warn (typo / foreign tool / catalog gap)

Ship machine-readable key indexes with every release. Never delete catalog rows — change status.

Product checklist (Dev-Centr)

For owned CLIs and toolchain wrappers:

  • Key index checked into the repo and shipped with the package

  • Startup or first-load scan of user/project/global config sources

  • Alerts distinguish deprecated vs expired vs unknown

  • Opt-out is itself a catalogued key

  • Prefer a shared library for classify → match → alert

Reference implementation: openshellorg/config-key-sanitation (wired into OpenShellOrg CLI bridges such as prohelp-cli).

Relationship to Toolchain Management

Toolchain Management owns pin / health / repair for engines. Config Key Sanitation owns explainability for settings keys those engines read. They compose: a healthy toolchain that silently ignores mystery config is still a docs failure.

Related