Generate config.example.toml from the config structs and fail docs:check on drift #1260

Closed
opened 2026-10-27 13:39:40 +00:00 by sam · 0 comments
Owner

config.example.toml is hand-maintained and silently drifts from
internal/config. Nothing fails when the file and the struct disagree.

Concrete drift found while diagnosing PR #859:

  • config.example.toml:441 documents a gate including
    ["golangci-lint","run"]; the running config's archie-core gate is
    vet/build/test only. The example is the only place that guidance
    exists, so it was never applied.
  • config.example.toml:450 documents review_enabled = true; absent from
    the running config.

Neither is the example file's fault on its own, but a generated file plus a
drift check makes a missing or under-specified key visible instead of
leaving it to whoever last hand-edited the TOML.

Inputs already exist: config.Repo and friends carry toml/json/yaml struct
tags, and the field comments are already written as operator-facing prose
(e.g. ReviewEnabled at internal/config/config.go:98-104). tools/docsgen is
the existing generator home, and task check already runs docs:check, so
there is a gate to hang a drift failure on.

Scope: generate config.example.toml (or a checked companion) from the
config structs, and fail docs:check when the committed file does not match
what the structs would produce. Not in scope: changing what any key means.

Close reason

Closed


Imported from beads archie-core-c8sk · GitHub #944 · type feature · priority P2 · created 2026-09-18 · closed 2026-10-03

config.example.toml is hand-maintained and silently drifts from internal/config. Nothing fails when the file and the struct disagree. Concrete drift found while diagnosing PR #859: - config.example.toml:441 documents a gate including ["golangci-lint","run"]; the running config's archie-core gate is vet/build/test only. The example is the only place that guidance exists, so it was never applied. - config.example.toml:450 documents review_enabled = true; absent from the running config. Neither is the example file's fault on its own, but a generated file plus a drift check makes a missing or under-specified key visible instead of leaving it to whoever last hand-edited the TOML. Inputs already exist: config.Repo and friends carry toml/json/yaml struct tags, and the field comments are already written as operator-facing prose (e.g. ReviewEnabled at internal/config/config.go:98-104). tools/docsgen is the existing generator home, and `task check` already runs docs:check, so there is a gate to hang a drift failure on. Scope: generate config.example.toml (or a checked companion) from the config structs, and fail docs:check when the committed file does not match what the structs would produce. Not in scope: changing what any key means. ### Close reason Closed --- _Imported from beads `archie-core-c8sk` · GitHub #944 · type feature · priority P2 · created 2026-09-18 · closed 2026-10-03_
sam added the mediumfeature labels 2026-10-27 13:39:40 +00:00
sam self-assigned this 2026-10-27 13:39:40 +00:00
sam closed this issue 2026-10-27 13:39:40 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sam/archie#1260