From b0902cc699b725e258c74abb5190795ebacbfcfc Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 03:39:23 +1000 Subject: [PATCH] docs(skills): fold the config-wiring trap into the ledger The rule belongs in CLAUDE.md, the inventory belongs in the config skill. The skill already carried a decoded-but-unwired ledger and defines its status terms exactly, so the entry now points at it instead of duplicating it, and the ledger gains the live instance from 2026-09-22 (per-identity forge intake) plus the three shapes an unwired field can take - not-consumed, not-projected, and deliberately-not-projected, the last being UpdateCheckCommand/UpdateInstallCommand read from base by design. --- .../skills/archie-config-and-flags/SKILL.md | 24 ++++++++++++++++++- CLAUDE.md | 22 ++++++++--------- 2 files changed, 33 insertions(+), 13 deletions(-) diff --git a/.agents/skills/archie-config-and-flags/SKILL.md b/.agents/skills/archie-config-and-flags/SKILL.md index 0873e49b8..5dce85191 100644 --- a/.agents/skills/archie-config-and-flags/SKILL.md +++ b/.agents/skills/archie-config-and-flags/SKILL.md @@ -9,7 +9,8 @@ Treat configuration as a dataflow, not as a struct inventory. Prove every claimed setting has an input, normalization path, composition seam, and runtime consumer. -Current evidence date: **2026-09-18**. +Current evidence date: **2026-09-18** for the matrix below. Entries added later +carry their own date inline. Use these status terms exactly: @@ -131,6 +132,27 @@ Do not expose these helper flags as daemon settings. | `tools.mcp_servers` | `internal/app/archied` registers daemon-side MCP providers. Empty transport becomes `stdio`; only `stdio` accepted. `url` decoded but unused. | partially-wired | | `indexing.index_dir`, `indexing.db_path` | `finalize` derives paths under `work_dir`; no entrypoint constructs `internal/indexing.Manager` (the exported `NewManager` exists but has no production caller). | decoded-but-unwired | | `extra` / unknown `conf.d` values | Test/library-only `Loader.Dir` stores untyped data; no core production consumer. | decoded-but-unwired | +| `[identities.forge].intake`, `.webhook_secret`, `.webhook_addr` | 2026-09-22: these parse because `IdentityConfig` embeds `Forge` (`internal/config/config.go:573`), while every read is the root `[forge]` block (`validate.go`, `defaults.go`, `bootstrap.go`). Wiring them is the intake migration, tracked as `archie-core-1786637497036-275-8838629e`. | partially-wired | + +**Three shapes of an unwired field.** All three read as working from the file +alone, and only the first two are defects - so establish which shape you are +looking at before reporting one: + +1. **not-consumed.** Decoded and normalized, but no production consumer uses the + effective value (`memory.provider` and `indexing.*` above; per-identity intake + was this shape until 2026-09-22, when the configuration was made to reject it + rather than accept it). +2. **not-projected.** A read exists, but at a layer that does not own the + effective copy, so editing the wrong layer does nothing. Direction matters as + much as presence: for most `[chat.*]` keys the stored resource outranks the + file, so writing a new file value is a no-op once a resource exists. A file + key in that position is a **seed**, not the contract. +3. **deliberately-not-projected.** File-only by design and therefore + indistinguishable from a dropped field to an auditor unless the projection + says so in a comment. `runtimeChatConfigFrom` reads + `Telegram.UpdateCheckCommand`/`UpdateInstallCommand` from `base` rather than + from the stored resource, on purpose. Check for that comment before filing a + defect. The default `agent.command = "archie-agent"` is not verified subprocess operation. `SubprocessRunner` expects one JSON invocation on stdin and one JSON diff --git a/CLAUDE.md b/CLAUDE.md index 222d7c954..5255e6be1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -162,18 +162,16 @@ 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. + A knob added to a struct the extensible surface reuses *parses* everywhere + without taking effect anywhere, and a knob read from the wrong layer is just + as invisible: a file key is only a seed once a stored resource outranks it. + Before adding or reusing a config field, name its consumer, and reject the + configuration when there is none - which is what this repo now does for + per-identity `forge.intake`. Two documents carry the detail: + `.agents/skills/archie-config-and-flags` holds the wiring matrix, the + decoded-but-unwired ledger and the three shapes an unwired field can take; + `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