Epic: v3.0.0 — CLI input/output contract changes

[leggetter]

Why

Three issues are independently parked on "wait for the next major":

Issue	Change	Why it is breaking
#340	Errors move from stdout to stderr	Silently breaks anything parsing stdout, e.g. out=$(hookdeck ... 2>/dev/null)
#347	Remove the JSON form of gateway --config	--config '{"auth":{...}}' stops working
#352	Rename Gateway MCP product tools to gateway_	Per-tool permission grants and allowedTools config do not carry across a rename

Three is the point where "defer to the next major" stops being a decision and becomes the place things go to be forgotten, because nobody owns the question when is that major. This epic owns it.

They also belong together on their merits. All three are input/output contract changes that break automation. Shipped as one release, users read one migration guide and adjust once, rather than being surprised three times.

No target date. The value here is sequencing and the deprecation work that has to precede it; a date with no forcing function only makes this look stale.

In scope

• #340 — errors to stderr. 7 print sites in Execute(), plus ~22 acceptance assertions that read error text from stdout. No minor-release split available: errors are either on stdout or stderr.
• #347 — remove the JSON form of gateway --config. Only the removal is major (see sequencing).
• #352 — rename Gateway MCP product tools to gateway_. Platform tools (hookdeck_login, hookdeck_projects) keep their prefix and are unaffected.

Sequencing

1. Minor first — deliver what does not need a major, and warn about what does.

• Gateway --config accepts both formats (JSON when the value starts with {, dotted key=value otherwise). Additive, nothing breaks, and it closes the --config-means-two-things collision immediately rather than at 3.0.
• Deprecation notice on the JSON form of --config.
• Deprecation notice that Gateway MCP tool names will change, calling out explicitly that per-tool permission approvals and any allowedTools config will need re-granting. This is the one genuinely silent failure in the rename: a strict allowlist omits the renamed tool without saying so.

This step matters. A major that arrives without prior warning is a worse release than a later one that was signposted.

2. Major — the removals and renames.

• Errors move to stderr
• JSON form of --config removed
• Gateway MCP tools renamed
• Migration guide covering all three in one place

Explicitly out of scope

Majors attract scope. These will get suggested and should not gate 3.0, because neither is breaking and both are more useful shipped sooner:

• #341 — pkg/cmd/sources is dead code
• #343 — releases are published before the acceptance gate runs

Open question

Is CLI support for Outpost GA by then? Outpost itself is GA; it is the hookdeck outpost command group that is currently in beta, from an unmerged branch (#346, #348, #349). If 3.0 lands first, the major ships containing a beta command group. That may be fine, but it should be a decision rather than an accident of timing.

Related: #351 (top-level hookdeck mcp) would make prefixes load-bearing, which strengthens the case for #352 landing in the same release rather than after it.

Reference

SemVer classification for this CLI is in .agents/skills/hookdeck-cli-release/SKILL.md. All three items match the MAJOR row: "requires users to change scripts, configs, or habits".