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.
This commit is contained in:
sam committed 2026-09-22 03:39:23 +10:00
1 parent 9e5f77a257
commit b0902cc699
2 files changed
+33 -13

No files matched your search

@@ -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
+10 -12
View File
@@ -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