[max-sixty]

wt config update migrates [select] to [switch.picker] and [commit-generation] to [commit.generation] by moving the whole table. Any key the destination struct has no field for moved along with it, and then warned as an unknown field on every later command — at a path the user never typed, and one that wt config update, the command the warning points at, would rewrite rather than clear. The warning outlived every fix available to the user.

Given this config:

[select]
pager = "delta"
height = "50%"

[switch.picker] has a pager field and no height, so the update used to write height into [switch.picker] and leave ▲ unknown field height on every command from then on. It now drops the key and reports it:

$ wt config update --yes
▲ User config: [select] height is no longer supported and will be removed

The rewritten config loads clean. drop_unsupported_keys does the removal, and a key removal that empties a [projects."<id>"]-scoped section removes the section too, for the same reason.

Two boundaries the implementation keeps:

• A key that is merely misplaced — valid in the other config file, such as a user-only commit.generation.command written into project config — stays, and keeps its redirect warning. That is why drop_unsupported_keys is given the union of the destination's schemas across config kinds.
• This does not conflict with "never silently drop an old config key": the removal is reported, and the key had no home in either config file.

schema_property_names is factored out of schema_top_level_keys so section types can be queried the same way. It cannot see #[serde(alias)], so the destination schemas must not carry one; the docstring says so.

Both wholesale-move rules go through one migrate_section_doc, which holds the contract they share — record the rename only for a scope that got a replacement written, count a drop-only outcome as a change, emit renames before drops — so a third such rule is a table row and a migrator rather than a third copy. wt config update's help now says it removes keys as well as updating and adopting them; over an open-ended class of keys, that is the thing to know before putting --yes in a dotfiles script.

test_warning_fires_iff_update_changes now pins both halves of the invariant: what the update writes raises no deprecation warning and no unknown-field warning.

UX survey items: #8.

Reviewable files: src/config/deprecation.rs, src/config/mod.rs, tests/integration_tests/config_show.rs, and the Config Deprecation paragraph in CLAUDE.md. Generated mirrors and snapshots are regenerated.

This was written by Claude Code on behalf of max-sixty

🤖 Generated with Claude Code

https://claude.ai/code/session_01XAUYWFN9d9oh6jyoQiouHb

[worktrunk-bot]

Two notes, neither blocking — one inline on the duplicated rule bodies, one here for a file the diff doesn't touch.

wt config update's after_long_help in src/cli/config.rs (the block opening Updates deprecated settings in user and project config files / to their current equivalents) describes updating and adopting, never removing. Removal isn't new — approved-commands and list.task-timeout-ms already went that way — but it's this PR's headline behavior and now covers an open-ended class of keys rather than two named ones, and that block is the primary source for the docs page someone reads before putting wt config update --yes in a dotfiles script. One clause after "to their current equivalents" would close it, e.g. "and removes deprecated keys that have no equivalent, reporting each". Happy to push that with the regenerated mirrors and help snapshots if you want it.

On the rest: the union-across-config-kinds boundary, --yes still printing each removal plus the full diff before the write, and the args shapes that now drop (all already non-functional — command absent fails is_configured, non-string command is a serde type error, a non-string element never joined) all check out. The one way this could take a supported key — SWITCH_PICKER_KEYS or COMMIT_GENERATION_KEYS collapsing to empty — is pinned by test_select_timeout_ms_removed_alongside_rename and test_project_config_keeps_misplaced_user_only_keys.

[max-sixty]

Both folded in.

wt config update's after_long_help now reads "removes deprecated keys that have no equivalent and reports each one" — your wording, near enough. Nothing mirrored needed regenerating: the update subdoc marker that puts this block on the config page arrives in a later PR in this series, and there is no help_config_update snapshot, so test_docs_are_in_sync and test_help both come back clean.

The duplicated rule bodies are collapsed into migrate_section_doc — replied inline.

This was written by Claude Code on behalf of max-sixty

[worktrunk-bot]

One observation on scope, not a defect in the change. The two things I raised last round are both closed — migrate_section_doc holds the contract once, and the after_long_help clause is there. I confirmed the "nothing mirrored needed regenerating" claim independently: to their current equivalents appears nowhere under docs/, skills/, plugins/, or tests/snapshots/, so test_docs_are_in_sync and test_help are untouched by that edit.

The loop is still open for the configs the old migration wrote. [select] timeout-ms now drops and reports. But a user who ran wt config update on any earlier release already has [switch.picker] timeout-ms in their file — put there by the wholesale move this PR is fixing — and test_config_update_leaves_retired_keys_for_unknown_field_warnings pins that shape as permanent: has unknown field switch.picker.timeout-ms on every command, No deprecated settings found from update, file untouched. commit.generation.template-file and squash-template-file reached their paths the same way and are pinned alongside it. So the sentence the new CLAUDE.md paragraph opens with — the warning outliving every fix available to the user — is still true, for exactly the configs worktrunk wrote on the user's behalf.

I read #3949's call as deliberate: a retired key sitting at its canonical path isn't the deprecation layer's business, and that's right for a key the user typed there. What this PR makes visible is that the same key now gets opposite treatment depending on which release the user happened to run update on. Whether the relocated ones earn a row of their own is your call — it'd be one UpdateOnly rule over the three known paths, and that test would need splitting, since template-file is reachable both ways. Not blocking, and not something I'd fold into this PR; flagging it because the invariant this PR adds is what makes the divergence legible.

[worktrunk-bot]

The rewrite isn't caused by this clause. migrate_section_doc calls for_each_config_table_mut as a statement and drops its bool, so the changed the closure returns goes nowhere — what actually decides the document was rewritten is modified |= !new_kinds.is_empty() in apply_rules, and a drop-only outcome reaches it by having pushed an UnsupportedKey. No bug: moved implies a recorded scope and a pushed rename kind, and a non-empty dropped implies pushed drop kinds, so the bool and the kinds can't disagree. But this is the contract docstring a third wholesale-move rule gets written against, and the clause credits a channel that isn't wired.

Suggested change

	/// count a drop-only outcome as a change so the document is rewritten, and
	/// report a drop-only outcome as a change to the scope walk, and

[max-sixty]

Agreed on both counts, and noted as a follow-up rather than folded in.

The divergence you describe is real: a key the user typed at a retired path is left alone by design, but the same key relocated there by an earlier wt config update is worktrunk's own doing, and it reads identically in the file. So which treatment a user gets turns on which release they happened to run update on. Carrying that item out of this PR — one UpdateOnly rule over the three known relocated paths, with test_config_update_leaves_retired_keys_for_unknown_field_warnings split because template-file is reachable both ways.

Merging this as it stands; the invariant it adds is what makes that case legible in the first place.

This was written by Claude Code on behalf of max-sixty