source-control: `melodic.worktreeroot` is a publisher-named key the org-agnosticism rule prohibits, and neither #2610 nor #3136 rules on it

[kyle-sexton]

Context

melodic.worktreeroot and the org-agnosticism rule were each decided deliberately, in separate passes, and nothing has reconciled them. This issue exists to force that decision rather than leave a shipped key sitting in unacknowledged tension with a stated rule.

The two sides

#2610 chose the key on purpose, with the namespace verified. It rejected worktree.* because Git owns it (worktree.guessRemote, worktree.useRelativePaths) and is extending includeIf into worktree semantics in 2.56, cited prior art for vendor sections (ghq.root, git-town.* ~45 keys, wt.basedir), and concluded "melodic.* collides with nothing." The motivating evidence was strong: 292 linked worktrees across ten conventions and zero in the configured worktree_root, precisely because the convention lived where only this plugin could read it. A git config key is readable by git config --get from any tool, agent, or human — that was the whole point, and this issue does not reopen it.

docs/PLUGIN-PHILOSOPHY.md § "Design boundary" says the opposite about naming. A plugin "must work outside the repository and organization that produced it. Publisher metadata may identify its source; runtime behavior must not depend on publisher names, organization-specific environment variables, repository names, absolute machine paths, or an undocumented consumer layout."

melodic.worktreeroot is runtime behavior keyed on a publisher name. A consumer outside this org who adopts source-control must write melodic.* into their own repositories' git config to use the documented per-repo override — which is the dependency the boundary rule prohibits.

Why now

#3136 already asks the fleet to "decide the conformance gap deliberately" for publisher-prefixed tokens, and measured 48 shipped skill-content files containing melodic-software while the validator exits 0. That issue's scope is scripts/ and plugins/ content; a git config key is a different and arguably worse instance of the same rule, because it is not a string in our own prose — it is a name we ask other people's repositories to adopt.

Neither #2610 nor #3136 rules on it. Confirmed by search: no open or closed issue proposes renaming this key.

Ask

Pick one, explicitly, and record the reasoning where the next reader will find it.

1. Rename to a neutral section (e.g. worktreeroot.path, wtroot.*, or a fleet-neutral vendor section that is not the org name), with a deprecation window that reads the old key and warns. Costs a migration on every machine that has already set it.
2. Keep melodic.* and narrow the rule — amend § "Design boundary" to state that a git config vendor section is exempt publisher metadata rather than prohibited runtime dependence, citing source-control: the worktree convention lives where only this plugin can read it, so nothing else on the machine can honor it #2610's namespace-collision reasoning as why a vendor section is the correct git-native idiom.

Option 2 looks stronger on the evidence: ghq.root and git-town.* are exactly this pattern, and Git's own convention is that third-party keys live under a vendor section. But the rule as written does not currently permit it, so it needs the amendment rather than silence.

Out of scope: the machine-global worktree_root plugin option (a pluginConfigs key, not publisher-prefixed) and the MELODIC_* environment-variable class already tracked in #3136.

Evidence

• Key present in the current shipped plugin: source-control 0.55.13 scripts/worktree-create.sh — resolution ladder rung 2, and the same-drive guard's stated remedy at L113-L122.
• Rule text: docs/PLUGIN-PHILOSOPHY.md § "Design boundary".
• Encountered live: a C: repo against a D:/worktrees machine-global root hits the same-drive refusal, whose only per-repo remedy is git config melodic.worktreeroot <same-drive-root>.

Related

No issue closed by this. Context: #2610 (introduced the key), #3136 (org-agnosticism enforcement consolidation), #2806 and #2764 (the same-drive guard that surfaces the key to users).