registry: why field, and the shepherd - no orphan constants allowed

2026-08-23 06:09:06 -05:00
parent 8f3b7074aa
commit 9450ae946f
1 changed files with 23 additions and 0 deletions
@@ -12,6 +12,29 @@ Rules:
 2. All three resolve to the same registry row; changing the value changes it everywhere at once.
 3. No bare values anywhere in code — a number never appears without its technical name.
 4. Values live as registry rows (data), revisable, history logged per change.
 5. Every row carries its own **why** — the reason it was set where it's set.
 ## Finding new ones — no orphans allowed
 The failure mode: you're coding, you reach for a number, you type it
 bare, and six months later nobody knows what it serves. So:
 1. **The linter is the shepherd.** No bare numeric literals in kernel
   code (0, 1, and array indices excepted). Any magic number fails the
   build with one message: *"register it or name it."*
 2. **Registry-first workflow.** Need a new knob? Add the row first —
   three names, full sentence, why — then use it. Thirty seconds now,
   saves the archaeology later.
 3. **Tuning proposes, registry disposes.** When behavior feels wrong
   and the fix is "adjust something," that instinct is the discovery
   event: propose a row for the thing you want to adjust. If two
   different tweaks keep wanting the same knob, that's one parameter
   trying to be born.
 4. **Periodic sweep.** Grep for repeated suspicious literals; anything
   appearing twice outside tests gets named.
 New parameters are discovered by friction. The registry makes sure
 friction turns into knowledge instead of folklore.
 ## Registered parameters