feat(fix): publish the Doctor catalog as a manifest tools can read

[volen-silo]

Stacked on #382 — based on fix/overstated-fix-applicability, so this diff is just the one commit. Draft until #382 lands; it will be rebased onto main after that.

What

The skill that drives this CLI states, in prose, which entries exist, how many there are, which the CLI carries out, which platform each applies on, and what each exit code means. Every one of those is a copy of something the binary already knows, and a copy can go stale with nothing comparing the two.

rocm fix --json now publishes that as one machine-readable manifest — every entry, what the CLI does with each on each platform, and the meaning of every exit code — rendered from the compiled catalog on every call rather than stored beside it.

Non-obvious decisions

Per platform, not per entry. An entry applies on Linux as print-only and on Windows as auto. A manifest that flattened that would reintroduce the exact defect #382 exists to remove, one level up.

Exit codes became named constants. They lived only in a module comment. A published number whose meaning is maintained separately from the code that returns it is the same drift this change exists to end, so apply and the manifest now read the same constants — and a test asserts the published codes are the ones apply actually returns.

The checked-in file is a guard, not the contract. cargo xtask catalog regenerates doctor-catalog.json; --check verifies it, in prek and in the clippy CI job, following the existing xtask manifest pattern. Its value is that a catalog change appears in the PR diff, in the form a consumer reads, which makes deciding whether to raise contract_version deliberate rather than something noticed later. The failure message says so explicitly.

doc_url is optional and mostly empty. Six of 23 entries carry a URL today; those are filled from URLs already in the recipe. An invented one would send a reader somewhere wrong with an air of authority. Because the file is checked in, the seventeen blanks are visible and countable — a to-do list rather than a silent gap. Filling them later is an addition, which keeps contract_version at 1.

--json with a fix id is refused, not ignored. "Apply this fix, as JSON" has no answer, and a caller that asked for machine-readable output and silently got something else has no way to notice. The refusal also emits nothing parseable, so a caller cannot mistake it for a catalog.

Verification

• cargo test --workspace --all-targets --exclude e2e-cucumber — clean; rocm-core 380 passed
• cargo clippy --locked --workspace --all-targets, cargo fmt --all --check, full prek run — clean, including the new hook
• cargo xtask e2e -- -n diagnose — 23 scenarios, 18 passed

The 5 failures are pre-existing on this host and were measured, not assumed. I ran the same command on the base commit: 16/21 with exactly the same five failure names. This dev host is WSL2 inside a container — no GPU, no /dev/dxg — and CI's own WSL2 lane passes them.

Every new assertion was mutation-checked.

• Flattening the manifest's per-platform class fails the_manifest_repeats_the_catalog_rather_than_reinterpreting_it, and only that.
• Publishing a wrong number for unknown_id fails the_published_exit_codes_are_the_ones_apply_returns.
• Reclassifying an entry in the published file makes xtask catalog --check exit 1 with the contract-version message.

One of those checks initially appeared to prove the guard was broken — the entry I mutated was already auto on that platform, so my "mutation" changed nothing. Worth recording because the guard was fine and the test was not.

Scope

This is the producer and its drift guard. The other half — the skill declaring a minimum contract_version and stopping below it — needs the skill and the binary in one CI job, which is parked on the skill move, so the Epic's "stops rather than guess against an older tool" scenario stays unclaimed here rather than looking covered.

Risk

Low. Additive: a new flag, a new xtask subcommand, a generated file, and a field defaulted to None. The only change to existing behaviour is apply returning named constants in place of the same literals.