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:
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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user