fix(config): rank env vars and --config-set above project entries

[worktrunk-bot]

Fixes #3788.

Layer and specificity were separate steps. load_with_warnings flattened system config → user config → WORKTRUNK_* env vars → --config-set into one document, and the accessors then resolved specificity on that document, so a [projects."<id>"] entry answered for the global key of the same name whichever layer set it. WORKTRUNK_WORKTREE_PATH could therefore not override a project's worktree-path, and a global --config-set hit the same wall.

Per @max-sixty in the issue thread — "env vars should indeed take precedence over the user project config, we should fix this throughout" — the two invocation layers now cross the axes: they're typed for one run, so they outrank a project entry as well as the global key. Load applies them at both scopes (apply_invocation_layer_over_projects, the last step before finalize): whatever the layer set is dropped from every project entry, leaving the global key it also set to answer for it.

Two kinds of key are held back:

• Keys the layer restates under projects."<name>" — --config-set 'projects."github.com/owner/repo".worktree-path = …' is both the highest layer and the most specific key, so it still wins over the same layer's global key.
• Composing keys — hooks, aliases, and step.copy-ignored.exclude — whose project-scoped values append to the global ones rather than replacing them. Both already apply, so an env-set hook was never outranked, and dropping the project's copy would silently stop it running. Hook names come from HooksConfig's schema, so a new hook can't be forgotten.

Two sections have to go as a unit rather than leaf by leaf. [commit.generation]'s mutually exclusive pairs: template and template-file clear one another in merge_with and are rejected together by validate, so overriding either has to displace both at project scope — otherwise the project's partner would still win the merge. exclusive_sibling names those pairs. And [list.custom-columns], which ListConfig::merge_with extends per whole column, so a partial removal leaves the project's column replacing the global one anyway — and ListColumnConfig::template is required, so it can also strand a column that no longer deserializes. is_atomic_section names that table.

Both are enumerations, so the pass degrades as a unit behind them: the removals land on a candidate, kept only if it still deserializes and validates. That is the guarantee the env and --config-set layers already have, and without it the next required field would answer a stranded leaf with UserConfig::default() — costing the user their whole config for that invocation rather than one project entry's precedence.

The precedence table now reads:

Source of worktree-path	Loses to
--config-set 'worktree-path = …'	—
WORKTRUNK_WORKTREE_PATH	--config-set
[projects."github.com/owner/repo"] in a config file	either invocation layer
global worktree-path in a config file	all of the above

Docs

The help text had no precedence section at all — the gap that made this read as a bug — so this adds one under Environment variables, plus a pointer from User project-specific settings. That supersedes #3789, which documented the old behavior; I'll close it in favour of this.

Testing

Nine unit tests in src/config/user/tests.rs cover the table-level rule (both layers, pattern entries, restated project-scoped overrides, untouched sibling keys, composing keys, the exclusive pair, the atomic custom column, a rolled-back layer, and the no-override no-op), and test_switch_create_invocation_layers_outrank_project_worktree_path proves it end-to-end — a real process is the only thing that reads WORKTRUNK_WORKTREE_PATH off the environment. That test keeps a control showing the project entry still beats the config file's own global key, so it can't pass by project entries having stopped applying.

The reproduction from the issue now lands where it says it should:

$ WORKTRUNK_CONFIG_PATH="$tmp/wt.toml" WORKTRUNK_WORKTREE_PATH="$tmp/from-environment" \
    wt switch --create feature --no-cd --no-hooks --yes --format=json
{"action":"created","branch":"feature","path":"/tmp/tmp.jQiTAuNPFd/from-environment",…}

Local suite

cargo test --lib --bins and cargo test --test integration are green apart from test_copy_ignored_preserves_file_executable_permissions, which fails in this sandbox because its umask is 0002 (file created 0664, test expects 0644) — unrelated to this change and not reproducible on a 0022 runner. cargo fmt --check and cargo clippy --all-targets --all-features are clean.

[worktrunk-bot]

Two gaps in the new step 5, both reproduced against 392d478 with throwaway tests in src/config/user/tests.rs; details inline.

The one that matters: an invocation override of a [list.custom-columns.<Name>] key strands that column's required template inside the project entry, the merged document stops deserializing, and finalize takes its Err arm and returns UserConfig::default(). Step 5 runs after both existing probe points, so nothing rolls it back — the user loses their entire config for that invocation, not just the project entry.

Smaller: step.copy-ignored.exclude composes exactly the way hooks and aliases do, but isn't held back, so --config-set 'step.copy-ignored.exclude=[…]' — the flagship example in the --config-set docs section — silently stops a project's patterns applying.

The rest reads well: the layer-vs-specificity framing, the exclusive_sibling reasoning and its now-exhaustive pair coverage, the control assertion that keeps the end-to-end test from passing on project entries having stopped applying, and the precedence table.

[worktrunk-bot]

The docs restructure reads well — a standalone Precedence section that both the env-var and [projects] sections point at is a better home than a subsection of Environment variables, and the numbered list is easier to scan than the old table.

One thing got lost in the move: the ordered list is framed as exhaustive ("comes from the first of these that sets it"), but a project-scoped --config-set beats a global --config-set for the same key, and the replacement sentence describes scoping rather than ranking. That's the one case apply_invocation_layer_over_projects special-cases (the restated argument to drop_overridden_keys), so it's worth keeping the ranking claim the old text carried. Inline suggestion below; it changes src/cli/mod.rs, so the mirrors and the help_config_long snapshot need regenerating with it.

[worktrunk-bot]

is_atomic_section and the candidate/backstop shape land what the earlier threads asked for, and I re-derived the "only required leaf" claim rather than taking the reply for it: scanning UserProjectOverrides, ListColumnConfig::template is indeed the sole non-Option, non-default leaf reachable under a project entry — ProjectForgeConfig, CopyIgnoredConfig, CommitGenerationConfig, ListConfig's scalars and the rest are all optional or defaulted — so the enumeration is complete for today's schema. CopyIgnoredConfig::merged_with unions through StepConfig::merge_with/merge_optional, so step.copy-ignored.exclude belongs on the composing list exactly as hooks and aliases do.

One correction, inline: the Err arm's comment claims it is unreachable, and it isn't — not through a partial removal, but through a candidate that was already invalid when the pass started.

[worktrunk-bot]

The predicate reads better than the path list — is_compose_only sits next to exclusive_sibling and is_atomic_section and is asked the same question by the same walk, and deleting remove_path takes the empty-parent pruning with it, which only ever existed to make the path list behave.

One regression rode along, inline below: the !merged_table.contains_key("projects") half of the entry guard became the let Some(projects) = … else — which now sits after both overlay.clone() and merged_table.clone().

A second consequence of the same move, worth a decision rather than a fix: global.is_empty() used to be evaluated after the compose-only paths were pruned out of global, so an overlay of nothing but composing keys (--config-set 'aliases.ship = …', the case test_invocation_layer_leaves_composing_keys_alone exercises) returned before the candidate clone. A predicate can't be applied to global up front the way a path list could, so those invocations now clone the merged table and run a full deserialize_and_validate for a pass that provably removed nothing. That's likely the right trade for the simpler shape, but it isn't in the commit message, and it widens which invocations reach the Err arm below.