feat(commands): add versioned semantic catalog contract

[andrexibiza]

What does this PR do?

Implements PR 1 — the versioned semantic catalog contract under #96692 without creating a second executable slash-command registry.

hermes_cli.commands.COMMAND_REGISTRY remains the canonical owner of core names, aliases, descriptions, availability, busy policy, execution keys, and Desktop projection metadata. This slice projects that owner into one immutable, JSON-safe semantic object with canonical command identity, alias-preserving resolution, deterministic catalog revision, and fail-closed collision validation. It changes no production dispatch path and grants no new execution authority.

Invariant

Entered names and aliases may locate a command, but they do not own its meaning. Every later projection must carry one canonical semantic identity and the revision of the immutable catalog that defined it.

Related Issue

Part of #96692 — Unified slash-command registry and execution contract across every Hermes surface.

This PR does not close #96692; it is the first production-code primitive in that ordered migration.

Prior work / provenance

• test(commands): characterize unified command-plane baseline #97102 is PR 0 and owns the current-topology inventory plus executable characterization baseline. This PR consumes that finding rather than duplicating it.
• fix(desktop): drive slash commands from the registry #96791 by OutThisLife is merged current ownership for registry-backed Desktop metadata and catalog projection. This PR preserves that ownership by deriving Desktop metadata through command_desktop_meta().
• feat(commands): establish unified versioned command catalog #96705 is historical stable-ID/revision design provenance only; fix(desktop): drive slash commands from the registry #96791 materially changed the landing topology after that branch was created.
• feat(plugins): register_command(override=True) to shadow a built-in command #50054 remains the explicit override-authority interlock. This PR fails closed instead of inventing last-writer-wins or import-order precedence.
• [Architecture] Hermes Authority Execution Layer — the twelve issues are one defect, and the architecture that fixes it #95028 / feat(authority): manifest schema + compiler + conformance harness #95101 remain the later Authority Policy ABI interlock. This PR does not reconstruct authorization, confirmation, mutation, busy-state, retry, or idempotency policy.
• feat(commands): establish canonical gateway command bindings #97114, feat(commands): establish desktop client command bindings #97124, feat(commands): establish Ink TUI client command bindings #97129, and feat(commands): establish classic CLI command bindings #97138 own path-disjoint gateway, Desktop, Ink TUI, and Classic CLI binding seams.

Exact submitted object

• Construction parent: 00bbfc690060d1323ddb2f065297c7425cb71c26
• Head: 51e9e866d42723870613b22c3c443f2569b0a894
• Tree: 3d08d4acf6b8aa308805423412676d0cef51d6ef
• Shape: 1 commit, 2 added files, +317 / -0
• Production call-site rewrites: 0
• Existing command execution/routing/help/completion behavior: unchanged

Current-main reconciliation

Live main at this reconciliation is 3f36c87e1ebdfbf7d14a88229dc9be222c12ea89, 169 commits beyond the construction parent. The complete main-only interval remains path-disjoint from both submitted paths (hermes_cli/command_catalog.py, tests/hermes_cli/test_command_catalog.py). GitHub's live PR object reports mergeable=true, rebaseable=true, mergeable_state=clean; no churn-only restack is required by the current landing edge.

Changes Made

• Added hermes_cli/command_catalog.py (206 lines): immutable CommandSpec / CommandCatalog, schema version 2, deterministic SHA-256 revision, canonical core IDs, alias-preserving resolution, explicit future-contribution normalization, and fail-closed duplicate-ID/token collision validation.
• Added tests/hermes_cli/test_command_catalog.py (111 lines): deterministic serialization/revision, alias identity, one projection per canonical registry entry, JSON safety, preservation of busy/execution/argument-mode/Desktop metadata, revision change on valid contribution, and refusal of missing identity / duplicate IDs / name-alias collisions.
• Both files remain below the repository 2,000-line ceiling.

Deliberate scope boundary

This PR does not replace commands.catalog, add a new transport, add normalized invocation/result types, perform context-scoped runtime discovery, define override authority, migrate any client/platform surface, or delete compatibility paths. Those are later slices after this identity/generation boundary is accepted.

Verification

Current exact-head hosted acceptance for 51e9e866d42723870613b22c3c443f2569b0a894:

• CI 33196230005 — SUCCESS
• Docker 33196229237 — SUCCESS
• Nix 33196229259 — SUCCESS

There is exactly one surviving submitted commit, so the every-commit execution gate is satisfied for the current object. No producer-authored review or independent acceptance is claimed.

Checklist

Code

• I've read the Contributing Guide
• Commit follows the repository's conventional-commit shape
• Existing related PRs were checked; the submitted two-file surface is path-disjoint from the listed sibling carriers
• PR contains only the semantic-catalog primitive and its focused tests
• Exact-head CI is green
• Tests for the new contract are included

Documentation & Housekeeping

• No user-facing documentation change is required because no operator/runtime behavior changes
• No config keys changed
• No tool schema changed
• No file exceeds the 2,000-line ceiling

Acceptance state

• Materialization: target present — feat(commands): add versioned semantic catalog contract #97143
• Integrity: exact-head green — CI/Docker/Nix all succeeded on the one submitted commit
• Governance: independent acceptance not yet claimed
• Integration: open + clean/mergeable; the 169-commit current-main landing interval is path-disjoint from the submitted files
• Operation: not claimed — no production path consumes this catalog yet
• Lineage: active — no superseding landing object is claimed for this PR 1 slice

The old b9642e… failed-CI state is superseded by the current one-commit object above and must not be used as the acceptance state for this PR.

[andrexibiza]

Exact-object completion receipt after the branch rewrite and hosted rerun:

• current submitted object: 51e9e866d42723870613b22c3c443f2569b0a894, one surviving commit, tree 3d08d4acf6b8aa308805423412676d0cef51d6ef;
• exact-head CI 33196230005 ✅, Docker 33196229237 ✅, Nix 33196229259 ✅;
• current main@a792d0794feaf4a28b65e123916061bf3f5b2f85 is three commits beyond construction parent 00bbfc690060d1323ddb2f065297c7425cb71c26, and that main-only interval does not touch either submitted path;
• GitHub currently reports the PR open, non-draft, and mergeable;
• no producer-authored code review or independent acceptance is claimed here.

I also repaired the PR body so the superseded b9642e… failed-CI object is no longer presented as current state. For this one-commit submitted object, the every-commit execution gate is now satisfied; the remaining gate is independent acceptance/landing, not implementation or hosted execution.