fix(config): report declared restart semantics in config-reference.md - #816
Merged
Conversation
The reference table printed "hot" for all 70 operational rows. Its source, GetMigratableSettings(), assigns Class via classificationFor(key), which does not carry the per-entry withMutability(...) overrides the registry audit set by reading each setting's consuming code — so the column reported the pre-audit default rather than the declared value. operationalRow now resolves Mutability from the registry def via DefFor(key), falling back to the projected value for generated provider keys that have no def. The lookup is confined to the documentation generator, leaving GetMigratableSettings()'s observable output untouched; making classificationFor() itself consult the registry stays Phase E work per Ruling 15. The regenerated table reads 66 static / 4 hot. Also amends §1 of the config model redesign design to the measured reality. The spec was written assuming operational settings are runtime-editable with restart-required as the declared exception; Phase A measured roughly 89 Static to 11 Hot. That does not invalidate the design or change Phases C-E, whose mechanism already restarts at each step, but it does retire the informal claim that moving a setting to the database lets admins edit it live — true for about eleven settings, not the rest. The honest benefit is one source of truth, one delivery path, and a reproducible per-environment template. The new guardrail was watched to fail: reverting declaredMutability to the projected value makes it report 0 static rows and name declaredMutability in the failure message. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FanMDLkRXPQEGY73Z4EsSL
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FanMDLkRXPQEGY73Z4EsSL
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Two things, both following from the Phase A registry consolidation in #812.
1.
config-reference.mdreported every operational setting as hot-reloadableThe table printed
hotfor all 70 operational rows — not "mostly hot",literally every one.
GenerateReferenceMarkdownreadsGetMigratableSettings(), which assignsClassviaclassificationFor(key). That path does not carry the per-entrywithMutability(...)overrides the Phase A audit set by reading each setting'sconsuming code, so
operationalRowwas rendering the pre-audit default ratherthan the declared value.
operationalRownow resolvesMutabilityfrom the registry viaDefFor(key),falling back to the projected value for generated provider keys that have no
def. The regenerated table reads 66 static / 4 hot.
The lookup is deliberately confined to the documentation generator.
GetMigratableSettings()'s observable output is untouched — makingclassificationFor()itself consult the registry stays Phase E work perRuling 15, because it would also change seeded-vs-explicit classification and
the origin backfill that derives from the same set.
2. Spec §1 amended to the measured reality
docs/superpowers/specs/2026-08-22-config-model-redesign-design.md§1 waswritten assuming operational settings are runtime-editable with
restart-required as the declared exception. Phase A measured the opposite:
roughly 89 Static to 11 Hot.
The amendment states that plainly, records the traced case
(
features.saml_enabled—NewServicebuilds the SAML manager only when theboot flag is true, so flipping the row at runtime changes nothing until a
restart), and is explicit about scope:
the point of promoting
Mutability.step.
lets admins edit it live. True for ~11 settings, not the rest. The honest
benefit is one source of truth, one delivery path, and a reproducible
per-environment template.
Guardrail, watched to fail
Per the rule #812 established — a guardrail nobody has watched fail is not
evidence. Reverting
declaredMutabilityto the projected value produces:Restored, it passes.
Noted, not fixed here
The reference lists 70 rows against ~100 operational settings, because the
generator reads the same
OmitWhenEmpty-filtered projection that #810 reports.Called out in the amendment; #810 owns the fix.
Gates
make lint— 0 issuesmake build-server— cleanmake test-unit— 2744 passed, 0 failed (2743 + the new guardrail)reference_gen.go