Epic: migrate OVOS repos onto ovos-spec-tools

[JarbasAl]

Epic — migrate OVOS repos onto ovos-spec-tools

Tracking epic for migrating the OVOS ecosystem onto ovos-spec-tools, the conformant reference implementation of the OVOS specifications. This is the concrete work behind the "all existing OVOS repos compliant" criterion of the adoption issue #5.

Why

The same machinery has been reimplemented and drifting across the ecosystem — template expansion duplicated in ~7 repos, the language-matching boilerplate (standardize_lang_tag + closest-match + distance < 10) in ~12, ad-hoc resource loaders in ~3, and the bus Message envelope re-implemented in ovos-bus-client alongside a separate FakeMessage in ovos-utils. ovos-spec-tools is the single conformant implementation each repo depends on.

Strategy

• Each repo migrates directly onto ovos-spec-tools — no transitive routing through ovos-utils.
• Waves by dependency order, so a repo lands before its dependents.
• Conformance, not just refactor. The specs are prescriptive; migration may change behaviour (e.g. a malformed template now raises instead of silently degrading). Each such change is deliberate and tested.
• Full normalised BCP-47 tag everywhere, no macro flag. Engines reconcile at match time via closest_lang.

Per-repo recipe

1. Add the ovos-spec-tools dependency.
2. Replace the local implementation with a call to ovos-spec-tools; delete the dead copy.
3. Preserve the repo's public API as a thin wrapper (deprecation warning pointing at the spec-tools import).
4. Run the repo's tests; reconcile divergences against the spec.
5. For a repo shipping locale/, add ovos-spec-lint to CI.
6. One PR per repo.

Progress

Wave 1 — foundation

• ovos-spec-tools — released to PyPI; alphas through 0.5.0a1
• ovos-utils — template expansion → feat: migrate ovos-utils onto ovos-spec-tools ovos-utils#373
• ovos-spec-tools — lang_matches / iter_locale_dirs → feat: lang_matches and iter_locale_dirs — pin the cross-component lang policy ovos-spec-tools#4
• ovos-spec-tools — LocaleResources.find → feat: LocaleResources.find — public resource lookup by (name, ext, lang) ovos-spec-tools#6
• ovos-spec-tools — keyword_form / vocabulary_keywords / utterance_contains / strip_samples → feat: keyword_form / vocabulary_keywords + utterance_contains / strip_samples ovos-spec-tools#8
• ovos-spec-tools — LocaleResources.voc_list / .voc_match / .remove_voc → feat: LocaleResources.voc_list / .voc_match / .remove_voc ovos-spec-tools#10
• ovos-spec-tools — OVOS-MSG-1 Message envelope → feat: OVOS-MSG-1 Message envelope ovos-spec-tools#12

Wave 1.5 — bus Message primitive consolidation

The Message class moves to ovos-spec-tools as the single source of truth; ovos-bus-client and ovos-utils.fakebus re-export it.

• ovos-spec-tools — Message envelope landed
• ovos-bus-client — re-export + publish attachment → feat: Message subclasses ovos_spec_tools.Message — no API break ovos-bus-client#215
• ovos-utils — fakebus re-export + publish attachment → feat: fakebus Message subclasses ovos_spec_tools.Message — no API break ovos-utils#375

Wave 2 — core libraries

• ovos-bus-client — standardize_lang migration → refactor: migrate language matching to ovos-spec-tools ovos-bus-client#213 (merged in 2.0.0a1)
• ovos-workshop — resource loading + dialog rendering → refactor: route OVOSSkill resource loading through ovos-spec-tools (back-compat) ovos-workshop#413
• ovos-core — language matching (intent services) → refactor: migrate language matching to ovos-spec-tools ovos-core#763
• ovos-plugin-manager — language matching (utils/config.py)

Wave 3 — pipeline plugins

• nebulento → feat: migrate to ovos-spec-tools nebulento#27
• padacioso → feat: migrate to ovos-spec-tools padacioso#55
• palavreado → feat: migrate to ovos-spec-tools palavreado#25
• linha-fina → feat: migrate to ovos-spec-tools TigreGotico/linha-fina#13
• jurebes → feat: migrate to ovos-spec-tools TigreGotico/jurebes#11
• ovos-padatious-pipeline-plugin → refactor: migrate to ovos-spec-tools ovos-padatious-pipeline-plugin#70
• ovos-adapt-pipeline-plugin → fix: bucket engines by full BCP-47 tag, migrate to ovos-spec-tools ovos-adapt-pipeline-plugin#42
• ovos-ocp-pipeline-plugin → feat: migrate to ovos-spec-tools ovos-ocp-pipeline-plugin#130

Wave 4 — leaf consumers

• ovos-lang-parser
• ovos-option-matcher-fuzzy-plugin
• ovos-solver-YesNo-plugin
• skills shipping a locale/ folder

Forthcoming spec adoption

As the in-flight specs leave Draft, the per-repo recipe extends to adopting their topic names and conformance points. The topic-name catalogue belongs in ovos-pydantic-models, not in ovos-spec-tools; tracked separately.

Specs with pending implementation impact (open PRs — see issue #5):

• OVOS-CONVERSE-1 (PR OVOS-CONVERSE-1: Active Handlers and Interactive Response #25) — skill_id replaces owner_id; converse.ping/.pong topic rename; session_id removed from response data payload
• OVOS-STOP-1 (PR OVOS-STOP-1 v1 — stop pipeline plugin specification #33, merged) — ovos.stop.ping/.pong capability-discovery convention; skill_id in conformance
• OVOS-TRANSFORM-1 (PR OVOS-TRANSFORM-1: Transformer Plugins Specification #20) — skill_id in Match; per-type transformer ordering via session fields; blacklisted_*_transformers session keys
• OVOS-PIPELINE-1 (PR OVOS-PIPELINE-1 — utterance lifecycle and pipeline (draft) #11, merged) — ovos.utterance.handle replaces recognizer_loop:utterance; ovos.intent.handler.* replaces mycroft.skill.handler.*; ovos.intent.unmatched replaces complete_intent_failure
• OVOS-INTENT-4 §11 (PR INTENT-4 §11: session-scoped intent registration #45) — session-scoped intent registration; context.session.session_id as registration key
• OVOS-BRIDGE-1 (PR OVOS-BRIDGE-1: Bus Bridge and Opaque Relay Specification #43) — bridge conformance; session_id routing; site_id ownership
• OVOS-AUDIO-IN-1 (PR OVOS-AUDIO-IN-1: Audio Input Service Specification #51) — ovos.utterance.handle emission contract; audio-transformer chain before STT
• OVOS-USER-ID-1 (PR USER-ID-1 v1: user identity resolution specification #54, issue USER-ID-1: user identity resolution and authentication level specification #53) — session.user_id, session.auth_level, and four per-signal fields (voice_id, face_id, name_id, passphrase_id, default_user_id) in SESSION-1 field registry; recognition plugin and bridge conformance obligations; skill auth_level gating