v0.9.2: Complete default skill-pack routing metadata and opt-in live smoke docs

[Hmbown]

Context

PR #4695 shipped the default end-user skill pack (bundled v5) for v0.9.1 with safe install/migration behavior and provider-free discovery coverage. Its stated non-blocking follow-ups should remain explicit after the v0.9.1 release instead of disappearing into the merged PR history.

Scope

• Add a provider-free routing-evaluation fixture matrix for the bundled end-user skills and explicit-only power skills.
• Define and validate locale-aware routing metadata for every shipped locale, including deterministic fallback behavior.
• Unify the model-invocable metadata consumed by prompt and tool surfaces where the current invocation: and aliases-for: fields are documentation-only.
• Document opt-in live smoke commands for Kimi K3 plus one second model/provider, with isolated configuration, credential boundaries, expected receipts, and no automatic live execution.
• Add a regression test for a corrupt/non-numeric bundled-skill version marker so install/upgrade repairs safely instead of silently becoming a permanent no-op.

Acceptance

• Provider-free fixtures prove positive routing, negative routing, alias behavior, and explicit-only non-activation for the full bundled catalog.
• All shipped locales have source-backed routing metadata or a documented deterministic fallback, with parity tests.
• Runtime behavior for invocation: and aliases-for: is explicit and tested; inert metadata is either wired or removed.
• Corrupt version-marker recovery preserves user-edited skill bodies and advances the repaired marker.
• Live-smoke documentation is opt-in, copy-pasteable, and never reads ambient credentials without explicit configuration.
• Focused skill tests, locale parity, locked TUI tests, cargo fmt --all -- --check, and git diff --check pass.

Boundaries

This is a v0.9.2 follow-up to #4695/#4691. It does not block v0.9.1, run a live provider request, overwrite user-edited skills, or broaden the shipped skill catalog.

[Hmbown]

Live parity audit (2026-07-25) found a concrete catalog gap that belongs in this issue rather than a duplicate.

GrokBuild currently bundles five user skills under crates/codegen/xai-grok-shell/skills/: check-work, code-review, create-skill, help, and imagine. Codewhale's v6 first-party catalog has partial conceptual equivalents for the first three (verify, review, skill-creator), but no explicit compatibility/alias/provenance decision and no direct help or image-tool workflow equivalent. The right v0.9.2 work is not a blind copy: add a provider-free fixture that inventories each Grok skill and records import / canonical alias / intentionally out of scope, then ship the smallest non-duplicative result with Apache-2.0 attribution where source text is reused.

Please extend acceptance with:

• a source-backed parity table for those five GrokBuild skills;
• deliberate aliases or migration notes where Codewhale already has the behavior;
• help routing grounded in Codewhale's installed docs and current config, without injecting a giant manual into context;
• an imagine decision based on whether Codewhale actually exposes image generation/edit tools—do not advertise missing tools;
• no Codewhale repository-maintenance/release-operator helpers in the end-user starter pack;
• prompt-budget and collision tests proving the extra routing metadata does not reintroduce context poisoning.

Separate plugin-delivery work is now tracked in #4836. Current installed-home evidence: 33 bundled skill assets in source, 34 user skill directories after restoring the current first-party fleet-manager, and zero installed Codewhale plugin bundles.

[Hmbown]

Additional live defect found while reconciling the starter-pack inventory: ~/.codewhale/skills/.system-installed-version was a directory containing .cleanroom-protected, not the expected version text file. install_system_skills() treats that as an unreadable/missing marker, but because the skill directories already exist it can leave the invalid marker unrepaired and future bundle upgrades ambiguous. I repaired this user's marker recoverably to the file contents 6; the displaced directory is in ~/.Trash/codewhale-helper-skills-20260725-1558/codewhale-system-installed-version-directory.

This is a real fixture for the issue's existing corrupt/non-numeric marker acceptance: add directory-marker coverage, repair atomically, preserve modified/user-owned skill bodies, and advance the marker without touching the real home.

[Hmbown]

Landed-main reconciliation on c4e460e758d841d4cefbf805b49de316fc6f5281:

Completed acceptance slices:

• fix(skills): repair invalid bundled-skill version markers #4876 / fix(skills): repair invalid system install markers #4891: corrupt, unreadable, or directory-shaped system version markers are repaired without overwriting user-edited skill bodies; focused marker tests landed.
• feat(skills): make invocation and alias routing explicit #4879: invocation: and aliases-for: are parsed into native/reviewed-plugin snapshots; aliases resolve through load_skill; explicit-only skills stay out of ambient model context while remaining explicitly loadable.

Still open:

• the full provider-free positive/negative/alias/explicit-only fixture matrix across the bundled catalog;
• locale-aware routing metadata or a documented deterministic fallback, with parity coverage;
• remaining help-routing and GrokBuild starter-pack parity decisions, including the plugin-delivery boundary tracked with v0.9.2: Ship a real starter plugin pack and safe install registry #4836;
• copy-pasteable opt-in live-smoke documentation for Kimi K3 plus a second provider, with isolated config and no ambient-credential reads.

Keeping this open and agent-ready; the merged slices should not be reimplemented.

[Hmbown]

Landed-main reconciliation on 37a2efd02. Every remaining acceptance slice from the 2026-07-26 note is now on main. Closing with receipts.

Taking the 07-26 "still open" list item by item, by symbol rather than by commit message:

1. Provider-free positive/negative/alias/explicit-only fixture matrix — landed

crates/tui/src/skills/catalog_matrix.rs (508 lines), driven by an authored, not generated expectation table at crates/tui/assets/skills-catalog-matrix.json. The fixture carries name, tier, invocation, aliases, in_model_catalogue, and shadowed_aliases per skill, and the suite asserts a bijection with the shipped catalog — so a change to the shipped pack cannot land without an explicit fixture update. It installs the real pack into a temp dir and discovers it exactly as a fresh user install would (installed_registry()), asserting the bundled pack parses with zero warnings.

Its module doc draws the scope line the acceptance criteria needed, and draws it in the right place:

They validate deterministic Codewhale behavior … They validate nothing about semantic routing. Whether a model picks debug for a stack trace is a live-provider question and is deliberately out of scope here.

That is the correct reading of "positive/negative routing" for a provider-free suite, and it is better than silently letting the fixture imply semantic guarantees it cannot make.

2. Locale-aware routing metadata with a documented deterministic fallback + parity coverage — landed

• crates/tui/src/skills/mod.rs:140-160 — description_for_locale resolves exact locale tag → primary subtag → canonical fallback, with optional description_zh-style locale keys (mod.rs:543).
• Fallback semantics pinned by description_for_locale_matches_exact_then_primary_then_falls_back (mod.rs:1565).
• Parity across every shipped locale, which is the part the acceptance criteria specifically asked for, and which is enumerated from Locale::shipped() rather than a hand-listed set — so adding a locale cannot skip the check:
  • every_shipped_locale_falls_back_to_canonical_english_routing_descriptions (catalog_matrix.rs:372)
  • rendered_catalogue_is_identical_across_every_shipped_locale (catalog_matrix.rs:397)

The deterministic answer chosen is "every shipped locale sees the canonical English routing description." Worth being explicit that this is the documented fallback branch of the acceptance criterion, not the source-backed per-locale metadata branch — the criterion allowed either, and this is the one that cannot drift.

3. invocation: / aliases-for: are runtime-effective, not documentation-only — landed (#4879, previously noted)

Parsed into native and reviewed-plugin snapshots; aliases resolve through load_skill; explicit-only skills stay out of ambient model context while remaining explicitly loadable. Covered by the matrix's invocation / aliases / shadowed_aliases / in_model_catalogue columns.

4. Corrupt/non-numeric version-marker recovery — landed (#4876/#4891, previously noted)

corrupt_marker_is_repaired_without_overwriting_user_skill_body (crates/tui/src/skills/system.rs:598), with write_marker_atomically (system.rs:471) behind it, plus the audit-side guards v1_marker_is_legacy_integrity_and_managed_actions, v2_marker_detects_healthy_and_drift, managed_marker_wins_over_bundled_name, and symlink_installed_from_marker_is_fail_closed (skills/audit.rs:1122-1321). The last one matters: a marker pointing at a symlink fails closed rather than following it.

5. Opt-in live-smoke documentation — landed

docs/LIVE_SMOKE.md. It meets the "never reads ambient credentials without explicit configuration" bar in a specific way worth recording: the credential is named indirectly through CW_SMOKE_CRED_VAR, which "must be the variable name the provider expects" rather than being guessed from the provider. Both runs are covered — Run A: Kimi K3 (--provider moonshot) and Run B: DeepSeek as the second provider/model — with a sealed throwaway state directory created in Step 1.

Its honesty table is the reason this closes the acceptance criterion rather than merely satisfying it:

Question	What a live run proves
Does the receipt record the provider/model I asked for?	Yes — but that does not by itself prove which network endpoint handled the request.
Is skill registry/catalog/alias behavior correct?	No — that is the provider-free suite's job.

It also classifies failures into credential/entitlement/availability/harness rather than letting a red run mean "skills are broken."

Explicitly not closed by this

The 07-26 note also listed "remaining help-routing and GrokBuild starter-pack parity decisions, including the plugin-delivery boundary tracked with #4836." Those are not in this issue's Scope or Acceptance sections, and #4836 already owns the plugin-delivery boundary. Folding them in here would mean this issue never closes on its own stated criteria. Leaving them with #4836.

Receipts

All run on origin/main = 37a2efd02e792d685bcb34ca19dea99a6b14a4f4, macOS, codewhale-tui 0.9.2.

cargo test -p codewhale-tui --bin codewhale-tui --all-features --locked
test result: ok. 9302 passed; 0 failed; 5 ignored; 0 measured; 0 filtered out; finished in 86.30s

Gates:

cargo fmt --all -- --check                    clean
git diff --check                              clean
python3 scripts/check-tui-locale-parity.py    PASS  (1227/1227 keys for every complete locale;
                                                    zh-Hant 498/1227 declared partial, #4057)

cargo clippy -p codewhale-tui --all-features --locked -- -D warnings \
  -A clippy::uninlined_format_args -A clippy::too_many_arguments \
  -A clippy::unnecessary_map_or -A clippy::collapsible_if \
  -A clippy::assertions_on_constants
Finished `dev` profile in 44.97s — no warnings, no errors

Audited against the installed dogfood build of this exact SHA: codewhale 0.9.2 (37a2efd02e79) / codewhale-tui 0.9.2 (37a2efd02e79), install receipt at backups/dogfood-installs/20260728T005915Z-37a2efd02e79.txt.

Focused:

-- skills::            193 passed; 0 failed   (2.43s)
-- catalog_matrix       16 passed; 0 failed