docs: appendix — divergence catalogue and gaps reconciled with the refactored specs

appendix/divergences.md

@@ -49,6 +49,7 @@ that need no change:
 | PIPELINE-1 | `mycroft.skill.handler.start` / `.complete` / `.error` | `ovos.intent.handler.start` / `.complete` / `.error` | Renamed into the `ovos.intent.*` namespace for uniformity. Breaks every existing handler-lifecycle observer; the migration cost is real. |
 | PIPELINE-1 | `recognizer_loop:utterance` | `ovos.utterance.handle` | See §5.4 entry. Migration touches `ovos-dinkum-listener`, `ovos-simple-listener`, `ovos-audio`, and `ovos-core/intent_services/service.py`. |
 | PIPELINE-1 | `complete_intent_failure` | `ovos.intent.unmatched` | Follows `ovos.intent.*` namespace; pairs with `ovos.intent.matched`. |
+| COMMON-QUERY-1 | `<skill_id>:common_query` | `<skill_id>.common_query.request` | The full-answer request is a plugin-emitted addressed message, not a dispatch; MSG-1 §2.1.1 reserves the colon for dispatch-shaped topics, so it moves to the dotted form and pairs with `<skill_id>.common_query.response`. The one colon topic kept is the dispatch `<pipeline_id>:common_query`. |
 
 ### 5.2.1 Topics to remove from ovos-core
 
@@ -177,6 +178,25 @@ defined by any spec** and should be removed or replaced:
   is real — every audio-input service and intent-service
   handler is affected. A transitional deployment MAY
   subscribe to both names during migration.
+- **Stop does not escalate on a silent stoppability poll**
+  (STOP-1 §4.1). The reference implementation escalates to a
+  global stop when no handler answers the stoppability ping
+  round. STOP-1 instead prescribes the recency fallback: with
+  no positive pong responder and non-empty `active_handlers`,
+  the plugin targets the highest-`activated_at` entry — a slow
+  responder (e.g. a satellite whose round-trip exceeds the
+  ping window) gets a targeted stop rather than triggering a
+  session-wide one.
+- **Transformer priority is ascending** (TRANSFORM-1 §4).
+  The reference implementation sorts transformer chains
+  descending (`reverse=True`), where the lowest number runs
+  *last* and — because each transformer's output overwrites
+  its predecessor's — effectively "wins". That is the exact
+  inverse of the spec's ascending convention (lower = earlier,
+  default 50); an inverse-convention priority assignment MUST
+  be renumbered, since run unrenumbered the chain executes
+  backwards. The TRANSFORM-1 notes in
+  [rationale.md](rationale.md) record why ascending was chosen.
 
 ### 5.5 New topics with no direct precedent
 
@@ -228,7 +248,7 @@ defined by any spec** and should be removed or replaced:
 
 - The session object's internal shape is owned by
   OVOS-SESSION-1; the field set is the closed set defined
-  there plus whatever future specs claim via SESSION-1 §2.1.
+  there plus whatever future specs claim via SESSION-1 §2.2.
   The "extra" fields current OVOS Session carries
   (`persona_id`, `system_unit`, `time_format`, `date_format`,
   …) ride through as non-normative pass-through and may be

appendix/gaps.md

@@ -3,24 +3,15 @@
 
 ## 7. Known gaps
 
-- **Per-plugin behavioural specs.** OVOS-PIPELINE-1 defines
-  the plugin contract (the `match` shape, the orchestrator's
-  iteration semantics) but explicitly defers what each
-  non-trivial plugin type actually *does*. `converse` (OVOS-CONVERSE-1),
-  `stop` (OVOS-STOP-1), and `common_query` (OVOS-COMMON-QUERY-1)
-  have their own specs. Remaining candidates: `fallback`, `ocp`,
-  `persona`. Each defines its own internal behaviour and its
-  own bus emissions beyond the universal lifecycle PIPELINE-1
-  prescribes.
 - **Session preference fields not claimed by a spec.**
   SESSION-1 defines the wire shape and OVOS-SESSION-2 defines
-  the lifecycle and state-ownership model; what remains
-  deferred is the full set of session preferences OVOS
-  carries (`persona_id`, `time_format`, `date_format`,
-  `system_unit`, `tts_preferences`, `location`, …) — these
-  need to be claimed under SESSION-1 §2.1's field registry by
-  their respective owning specs (a preferences spec,
-  OCP / persona / locale specs as appropriate).
+  the lifecycle and state-ownership model; `persona_id` is
+  claimed by OVOS-PERSONA-1. What remains deferred is the rest
+  of the session preferences OVOS carries (`time_format`,
+  `date_format`, `system_unit`, `tts_preferences`, `location`,
+  …) — these need to be claimed under SESSION-1 §2.2's field
+  registry by their respective owning specs (a preferences
+  spec, OCP / locale specs as appropriate).
 - **Text normalization of ASR output.** The basis for slot
   value typing (INTENT-1 §5.3). Deferred to its own
   specification.
@@ -66,18 +57,19 @@
   spec-level way to know whether a remote participant is
   reachable. Deferred to a separate observability specification
   if needed.
-- **Audio transmission over the bus.** BRIDGE-1 §4.2.1 describes
-  two audio-stack placements — local (satellite runs STT and its
-  own audio-output layer) and hub-side (hub runs the full audio
-  stack, satellite transmits raw audio inbound and receives final
-  audio outbound). STT placement and audio-output placement are
-  symmetric and independent: each can live on the satellite or the
-  hub, giving four possible combinations. The hub-side model
-  requires transmitting audio as bus Message payloads (e.g.
-  base64-encoded PCM or compressed frames). The bus surface for
-  any audio transmission — topic names, payload shape, session
-  fields for codec and audio preferences — is not defined by any
-  current specification. Deferred to OVOS-AUDIO-1.
+- **Outbound audio over the bus is specified; inbound is not.**
+  BRIDGE-1 §4.2.1 describes two audio-stack placements — local
+  (satellite runs STT and its own audio-output layer) and
+  hub-side (hub runs the full audio stack). On the output side
+  the bus surface is defined by OVOS-AUDIO-1:
+  `ovos.utterance.speak.b64` → `ovos.audio.speech` for
+  remote-client TTS delivery, and base64 `audio` payloads on
+  `ovos.audio.queue` / `ovos.audio.play_sound` for sound
+  effects. What remains undefined is the *inbound* leg of the
+  hub-side model — transmitting raw captured audio from the
+  satellite to a hub-side STT as bus Message payloads (topic
+  names, payload shape, session fields for codec and audio
+  preferences).
 - **Session-scoped pipeline plugin registration.** BRIDGE-1 §4.4
   and INTENT-4 §11 cover session-scoped intent registration for
   satellite-side skills. A satellite that implements a pipeline

appendix/rationale.md

@@ -85,7 +85,7 @@ the normative sections.
   on `session.session_id`. Multi-turn conversation, intent
   context, cross-skill state, and similar concerns are
   deferred to other specifications.
-- **Topic naming conventions** (MSG-1 v2 §2.1.2). The
+- **Topic naming conventions** (MSG-1 §2.1). The
   conventions other specs in the family follow are
   codified as SHOULD-rules: dot-separated hierarchy
   with `:` reserved for component-pair shapes; stable

appendix/reference.md

@@ -8,7 +8,7 @@ tables that don't fit cleanly in any single normative spec.
 
 ### 6.1 Topic-name conventions across the family
 
-The naming conventions of OVOS-MSG-1 v2 §2.1.2 — dot-separated
+The naming conventions of OVOS-MSG-1 §2.1 — dot-separated
 hierarchy, stable root, verb-tense pattern for the trailing
 segment, request/terminal pairs sharing a root verb,
 `.response` suffix, per-instance
@@ -38,7 +38,7 @@ accidentally parse responses from another.
 ### 6.2 Session-field cheat-sheet
 
 Every spec in the family that claims a `session` field does
-so via the OVOS-SESSION-1 §2.1 registry mechanism. The full
+so via the OVOS-SESSION-1 §2.2 registry mechanism. The full
 set spans four specs; this table consolidates them. All
 fields follow the canonical SHOULD-omit /
 `[]`-equivalent-to-omission wire-weight rule of