统一 Hermes Pet 与 ClawPet 的宠物身份、素材和动画语义

[XMethues]

Problem Statement

ClawPet currently maintains its own current-pet selection, Petdex catalog/cache, asset resolution, and hook-derived animation vocabulary alongside Hermes' official Pet feature. A user can therefore select or disable a pet in Hermes without ClawChat reliably presenting the same current pet, while the same Petdex assets and activity semantics are interpreted twice. The duplicated ownership also makes generated or newly installed Hermes pets invisible to ClawPet until ClawPet independently discovers and caches them.

The user wants Hermes Pet and ClawPet to feel like one pet across Hermes and ClawChat without making ClawPet more complex. Hermes must remain authoritative for pet identity, installation, assets, and enablement; ClawPet must retain its differentiated shared growth, personality, speech, gameplay scenes, skins, and private Liveware experience.

Solution

Use Hermes as the single source of truth for the current pet, pet enablement, installed pets, Petdex gallery, thumbnails, and pet assets. The private ClawPet Liveware page will continue to talk only to the local ClawPet server; that server will become a thin, Pet-only bridge to Hermes' official Pet RPC instead of maintaining a second pet-management model.

Keep Hermes hooks as the source of real-time activity and growth signals. Produce animation states with Hermes' official animation vocabulary and priority semantics, while independently converting the same hook stream into ClawPet growth events and richer scene narration. ClawPet continues to own shared growth, per-pet personality, speech, gameplay scenes, skins, and surface-specific presentation scale.

The Liveware experience has three explicit states:

1. Pet missing — invalid ClawPet configuration; show the complete Hermes Pet gallery and allow the owner to adopt a pet through the Pet RPC bridge.
2. Pet disabled — hide the growth scene and show the selected pet with enable and replace actions.
3. Pet enabled — show the normal growth scene and expose pet replacement from settings.

Upgrade the product save from v2 to v3 with one targeted migration that removes the duplicated pet.current value while preserving shared growth, per-pet personalities, gameplay scene selection, skin selection, and skin overrides.

User Stories

1. As a Hermes owner, I want Hermes and ClawChat to show the same current pet, so that I experience one companion rather than two unrelated selections.
2. As a Hermes owner, I want changing my pet from any official Hermes surface to update ClawChat, so that I do not have to repeat the selection.
3. As a Hermes owner, I want selecting a pet from ClawChat to make it the active Hermes pet, so that the change applies consistently across surfaces.
4. As a Hermes owner, I want ClawPet to use Hermes' installed pet packages, so that one local copy of each pet is sufficient.
5. As a Hermes owner, I want generated and locally registered Hermes pets to appear in ClawChat, so that ClawPet is not limited to remote Petdex entries.
6. As a Hermes owner, I want the Liveware selector to include the complete Hermes Pet gallery, so that I have the same choices as the official Hermes interfaces.
7. As a Hermes owner, I want already installed pets to be visibly distinguished in the selector, so that I know which choices are immediately available.
8. As a Hermes owner, I want selecting an uninstalled pet to install, select, and enable it through Hermes, so that ClawPet does not create a partial private adoption.
9. As a Hermes owner, I want an installation or selection failure to leave the previous Hermes state unchanged, so that a failed adoption does not corrupt my current pet.
10. As a Hermes owner, I want ClawChat to show a pet selector when no usable current pet exists, so that I can repair the invalid configuration from Liveware.
11. As a Hermes owner, I do not want ClawPet to silently substitute a default pet when the current pet is missing, so that configuration problems remain visible and correctable.
12. As a Hermes owner, I want disabling Pet in Hermes to hide it in ClawChat, so that the Pet master switch has one meaning across surfaces.
13. As a Hermes owner, I want the disabled Liveware state to retain the selected pet identity, so that I can re-enable it without adopting again.
14. As a Hermes owner, I want to replace the current pet from the disabled Liveware state, so that disabling does not trap me on one selection.
15. As a Hermes owner, I want to replace the current pet from normal ClawPet settings, so that I can change companions without first creating an error state.
16. As a Hermes owner, I want the Liveware selector to load local pets promptly even when Petdex is slow, so that my existing pets remain usable offline or during remote failure.
17. As a Hermes owner, I want remote gallery failure to preserve the local installed-pet list, so that Petdex availability does not break ClawPet.
18. As a Hermes owner, I want pet thumbnails to come through Hermes' official Pet capability, so that ClawPet does not duplicate thumbnail fetching and caching.
19. As a Hermes owner, I want ClawChat animations to use Hermes' official states, so that the pet communicates the same activity on every surface.
20. As a Hermes owner, I want waiting for my approval to display the official waiting animation, so that blocked work is recognizable everywhere.
21. As a Hermes owner, I want active tool execution to display the official run animation, so that ClawChat agrees with Hermes about ongoing work.
22. As a Hermes owner, I want model reasoning to display the official review animation, so that thinking is not confused with tool execution.
23. As a Hermes owner, I want successful and failed completion beats to use the official animation vocabulary, so that completion feedback remains consistent.
24. As a Hermes owner, I do not want ClawPet-only subagent or unknown animation rows, so that standard Hermes pets render valid animations.
25. As a Hermes owner, I still want delegated work described through gameplay narration, so that removing a private animation state does not remove ClawPet's richer story.
26. As a Hermes owner, I want hook activity to continue advancing shared growth, so that Pet unification does not reduce ClawPet gameplay.
27. As a Hermes owner, I want switching pets to preserve shared growth, so that adoption changes the companion rather than resetting the journey.
28. As a Hermes owner, I want each pet's personality to remain associated with that pet, so that switching back restores its speech style.
29. As a Hermes owner, I want an undecided personality to continue prompting according to the existing personality policy, so that Pet unification does not remove personalization.
30. As a Hermes owner, I want gameplay scenes and skins to remain independent of the current pet, so that changing companions does not change my selected theme.
31. As a Hermes owner, I want ClawChat to keep a scene-appropriate pet size, so that Hermes' mascot scale does not shrink or distort the portrait Liveware layout.
32. As a Hermes owner, I want Hermes' scale controls to continue affecting Hermes' native mascot surfaces, so that ClawPet does not change existing official behavior.
33. As an existing ClawPet user, I want my v2 shared growth to survive the unification upgrade, so that accumulated progress is not lost.
34. As an existing ClawPet user, I want my per-pet personalities to survive the unification upgrade, so that configured speech remains available.
35. As an existing ClawPet user, I want my gameplay scene, skin, and visual overrides to survive the unification upgrade, so that the UI does not reset.
36. As an existing ClawPet user, I want the obsolete ClawPet current-pet selection removed during migration, so that stale data cannot override Hermes.
37. As a maintainer, I want ClawPet to depend on a narrow Pet RPC adapter, so that Hermes integration has one replaceable boundary.
38. As a maintainer, I want the browser to communicate only with the ClawPet server, so that the full Hermes Gateway is never exposed through Liveware.
39. As a maintainer, I want the private Liveware deployment to remain the access boundary for owner mutations, so that this feature adds no independent authentication system.
40. As a maintainer, I want Pet RPC failures normalized at the ClawPet service boundary, so that the Liveware UI can display stable, actionable errors.
41. As a maintainer, I want ClawPet to stop reading the Petdex manifest directly, so that Hermes owns remote catalog compatibility.
42. As a maintainer, I want ClawPet to stop writing Hermes Pet configuration or directories directly, so that official Pet behavior remains authoritative.
43. As a maintainer, I want one integration seam to cover Pet management, hooks, persistence, and HTTP presentation, so that tests verify behavior without coupling to internals.
44. As a maintainer, I want non-v2 legacy or damaged saves to retain the existing explicit failure policy, so that one targeted migration does not become a general migration framework.

Implementation Decisions

• Hermes owns the current pet, pet disabled state, installed pets, Petdex discovery, pet thumbnails, and pet assets.
• ClawPet will no longer persist a current-pet identifier or maintain a Petdex index, downloaded spritesheet cache, or fallback default pet.
• Introduce one narrow Hermes Pet client abstraction at the ClawPet service boundary. Its required capabilities are current pet information, gallery retrieval, thumbnail retrieval, pet selection/install-on-demand, and pet enable/disable.
• The Pet client must call Hermes' official Pet RPC behavior. It must not reproduce Petdex manifest parsing, pet installation, configuration writes, active-pet fallback, or asset ownership inside ClawPet.
• The private Liveware browser continues to use ClawPet's HTTP service and never connects directly to Hermes Gateway.
• ClawPet's server is a thin adapter between the existing Liveware HTTP surface and the injected Hermes Pet client. No separate authentication or pairing system is added because the ClawPet Liveware app is deployed privately.
• Preserve the existing high-level HTTP concepts where practical:
  • The presentation response identifies the current Pet condition as missing, disabled, or enabled.
  • The catalog response projects the Hermes gallery, installed markers, current selection, and enabled state.
  • The existing pet-selection command becomes a Pet RPC bridge rather than a ClawPet save mutation.
  • Add or adapt an enable/disable command that delegates to Hermes.
  • Existing pet asset delivery delegates to the official current/installed asset or thumbnail capability rather than a ClawPet cache.
• Pet missing means Hermes cannot provide a usable current pet. It is invalid for normal ClawPet presentation and must not be masked with yinyue-2 or another fallback.
• Pet disabled means Hermes retains a selected pet while its master Pet switch is off. ClawPet hides the normal pet scene but retains enough read information to offer enable and replace actions.
• Pet enabled means Hermes provides an enabled, usable current pet. ClawPet projects the existing shared growth experience around that pet.
• The Liveware UI implements its own ClawPet visual treatment for the selector, but its data and mutations come exclusively from the Hermes Pet bridge.
• Gallery loading follows the official two-phase behavior: show locally installed/generated pets first, then merge the complete remote Petdex catalog. Remote failure must not remove the usable local gallery.
• A pet adoption is successful only after Hermes confirms its official select operation. ClawPet does not persist optimistic pet identity, although the UI may show an in-flight state.
• Pet RPC errors are returned as stable service errors suitable for retry and user display. A failed operation must not change shared growth, personality, scene, skin, or a ClawPet-owned current-pet value.
• Hermes hooks remain the source of transient activity signals and growth-event input. The Pet RPC is not used as a real-time activity stream.
• Split hook interpretation into two conceptual outputs:
  • Official pet animation state for presentation.
  • Scene-neutral growth events and richer activity facts for shared growth and narration.
• Pet animation states are limited to Hermes' official vocabulary and priority semantics. subagent and unknown remain eligible as narration/fact distinctions but are not animation states.
• Delegated work continues to produce the existing scene narration and growth behavior without introducing an extra animation row.
• Animation row and frame resolution must follow Hermes' official Pet metadata/constants rather than ClawPet-specific hard-coded row ownership.
• ClawPet retains ownership of shared growth, stable growth facts, growth strategy, per-pet personality, pet speech, gameplay scenes, skins, and skin overrides.
• Switching the Hermes current pet never resets or copies shared growth, gameplay scene, skin, or growth strategy.
• Personality remains stored by Pet slug in the ClawPet product save. The currently selected Hermes slug determines which stored personality is projected.
• ClawChat's presentation scale remains scene- and viewport-specific. ClawPet neither reads nor writes Hermes' native mascot scale.
• Increment the product save schema from v2 to v3.
• The v2-to-v3 migration is a single, explicit, atomic transformation:
  • Remove the duplicated current-pet value.
  • Preserve shared growth.
  • Preserve per-pet personalities.
  • Preserve gameplay scene and skin selection.
  • Preserve skin overrides.
• The migration must complete before the runtime serves presentation or accepts commands. A failed migration must not partially replace the v2 save.
• The targeted v2 migration is the only compatibility exception. Unsupported older versions and damaged saves retain explicit startup failure rather than automatic reset or general conversion.
• Runtime startup and asset warming resolve the pet through Hermes rather than through saved ClawPet identity or private asset cache.
• The fixed private ClawPet publication identity and Gateway-owned server lifecycle remain unchanged.
• The bundled ClawPet skill and user documentation must describe Hermes as the source of pet selection and installation, while continuing to document ClawPet-owned growth, personality, scene, and skin operations.
• This implementation follows ADR-0005 and only supersedes the current-pet ownership and no-migration clauses identified there. The remaining one-runtime/one-save transaction boundary remains intact.

Testing Decisions

• Use one primary integration seam: the externally visible ClawPet service boundary.
• The harness runs the real runtime, HTTP server, and hook adapter while injecting an in-memory fake implementing the narrow Hermes Pet client.
• Drive Pet browsing, selection, enablement, and failures through HTTP rather than testing adapter internals.
• Drive activity through registered Hermes hooks and observe the resulting presentation through HTTP, ensuring official animation and ClawPet growth are verified together.
• Seed an authentic v2 save before service startup, then observe v3 behavior and persisted data through the same service boundary.
• Restart the service against the migrated save to verify durable behavior instead of inspecting implementation-only calls.
• Good tests assert user-visible state, persisted domain outcomes, and calls at the external fake boundary. They do not assert private helper calls, internal collection shapes, or exact module structure.
• Cover the three presentation states:
  • Missing returns a repairable selector experience and no default pet.
  • Disabled hides the growth scene while retaining enable/replace context.
  • Enabled returns the normal growth presentation for the Hermes current pet.
• Cover switching the current pet from both directions:
  • A Liveware selection invokes the official fake and is reflected in later presentation.
  • An externally changed fake Hermes current pet is reflected without a ClawPet save mutation.
• Cover install-on-demand success, already-installed selection, gallery remote failure with local fallback, selection failure, enable failure, and thumbnail/asset failure.
• Cover official activity priorities for waiting, running tools, reasoning, clean completion, failure, and idle.
• Prove that subagent activity can affect narration/growth but never emits a private animation state.
• Prove that pet switching preserves shared growth, personality records, strategy, scene, skin, and skin overrides.
• Prove that ClawChat presentation scale is unaffected by Hermes scale changes.
• Prove that the v2-to-v3 migration removes current-pet ownership and preserves all approved product state.
• Prove that the migration is atomic under persistence failure and that unsupported/damaged saves retain the explicit failure behavior.
• Prior art is the repository's existing isolated HTTP server tests, raw-hook adapter tests, runtime restart/persistence tests, Pet identity tests, gameplay-scene tests, personality tests, and publication adapter fakes.
• Frontend production build verification remains required, but this spec does not add a browser E2E framework. Behavioral acceptance is anchored at the existing service boundary to keep the test architecture small.

Out of Scope

• Replacing Hermes' official Pet RPC, Petdex integration, installer, renderer, or native selectors.
• Direct browser access to the full Hermes Gateway.
• A second ClawPet authentication, authorization, or pairing system.
• Public Liveware deployment.
• ClawPet-owned Petdex manifest fetching, pet installation, spritesheet caching, or thumbnail caching.
• A default or fallback pet when Hermes has no usable current pet.
• Sharing Hermes' native mascot scale with the ClawChat gameplay layout.
• New growth formulas, growth dimensions, stages, strategies, scenes, skins, or personality-generation behavior.
• Per-pet growth saves or resetting shared growth when the current pet changes.
• New ClawPet animation states beyond Hermes' official vocabulary.
• A generic migration framework or conversion of unsupported historical saves.
• Liveware UI for pet removal, rename, export, or AI pet generation unless those operations are separately specified later.
• Changes to the fixed ClawPet publication identity or Gateway-owned lifecycle.
• Adding a new browser E2E toolchain.

Further Notes

• The source domain language is defined in the root glossary, including current pet, pet missing, pet disabled, installed pet, pet asset, presentation scale, pet adoption, and pet animation state.
• ADR-0005 records Hermes ownership of the unified pet and the targeted v2-to-v3 migration. ADR-0003 remains authoritative for the rest of the one-runtime/one-save transaction boundary.
• Hermes' official Pet design treats pets as cosmetic mascots, stores them per profile, manages selection under the Hermes Pet configuration, and exposes shared gallery/select/info/thumbnail behavior to its native clients.
• ClawPet remains valuable after unification because it adds persistent shared growth, personality, speech, scene narration, skins, and the private Liveware experience rather than duplicating mascot management.