From 27d7c08049929344e63d7f1d4cf08f7f45ee31d5 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 03:21:27 +1000 Subject: [PATCH] docs: record the config-field trap (a field that parses is not a field that works) Three defects in one session landed the same way: a map field the file overlay dropped (xrux), a field missing from the control-plane projection (parallel_tool_calls), and per-identity forge.intake - accepted TOML that no consumer reads, and which is not even validated. The entry names the shape, gives the live example with file:line, and points at docs/architecture/configuration.md as the config authority. --- CLAUDE.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 389cf2554..222d7c954 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -161,6 +161,20 @@ structures found in legacy packages. ## Per-Package Invariants & Traps +- **Config fields (cross-cutting): a field that parses is not a field that works.** + Adding a knob to a struct the extensible surface reuses makes it *parse* + everywhere without taking effect anywhere. `Forge` is the live example: + `IdentityConfig` embeds it (`internal/config/config.go:573`), so + `[identities.forge].intake`, `.webhook_secret` and `.webhook_addr` are + accepted TOML, while every read is the root block + (`validate.go:257-268`, `defaults.go:278-279`, `bootstrap.go:1330-1344`) - so + they are silently ignored and not even validated. Three defects landed this + way in one session: a map field the file overlay dropped, a field missing from + the control-plane projection, and per-identity `forge.intake`. Before adding + or reusing a config field, name its consumer; with none, reject the + configuration rather than accept it. `docs/architecture/configuration.md` is + the authority on the config model and its reloadability criterion. + - **`internal/channels/telegram/`:** - The long-polling worker must call `dropPendingUpdates(ctx, b)` before `b.Start(ctx)` and on `/restart`.