spec: PERSONA-1 — consistency audit (claim rule, mandatory speak, converse, OOB, positioning)

[JarbasAl]

🤖 Auto-generated by Claude Fable 5 (claude-fable-5) via Claude Code — NOT human-reviewed. Verify before acting. Cross-spec citations were model-verified against dev source; behavior-change sections need owner judgment.

Audit pass over persona.md. Twenty findings; nineteen addressed here, one deferred.

Contradictions resolved

• §12 vs §7.1 route 3. The conformance MUST to return None when persona_id is absent contradicted route 3, which claims in exactly that case. The obligation is now scoped to invocation under the plugin's main pipeline_id, with a parallel MUST stated for invocation under a fallback_pipeline_id. §3 and §4 restate the same split.
• §7.2 vs route 1. "MUST NOT use intent-matching to decide whether to claim" contradicted route 1, where the embedded persona commands are ordinary intents by design. The prohibition is now scoped to route 2.
• Four claim-rule formulations. §7.2 is now the single normative statement; §3, §4, §7.1 and §12 cite it.

Silent-turn and failure contracts

• §8.1 — a claimed dispatch MUST speak. A persona claim is exclusive and sits before fallback, so a handler that emitted nothing produced a silent turn with no error anywhere. Every dispatch from a claiming match now MUST emit at least one ovos.utterance.speak, including a degraded or error utterance on backend failure, refusal, or generation timeout. The timeout value is deployment-defined. Stop is exempt.
• The handler-lifecycle trio stays orchestrator-owned (PIPELINE-1 §8): a handler that swallows a failure and returns normally produces .complete, so a failing handler SHOULD speak and then propagate, letting the orchestrator emit ovos.intent.handler.error.
• §8.5 — the out-of-band interface answers on every failure mode, not only on an unsupported persona_id. Adds a deployment-defined request/generation budget and a correlation rule: the topic is a broadcast, so a caller MUST tolerate N replies (typically one success and N−1 errors), correlating by persona_id and utterance.

Corrected cross-references

• §8.3 cited "CONVERSE-1's active-handler check" — the wrong list. Rewritten against session.converse_handlers (CONVERSE-1 §2.1), stamped at dispatch (CONVERSE-1 §3.1), with the persona's pipeline_id entering it as an ordinary eligible owner via PIPELINE-1 §7.0 self-matching. No persona-specific rule is involved.
• §6 stop clear. stop-1.md on dev contains no persona_id; STOP-1 §6.2 drains active_handlers, converse_handlers and response_mode only. The clear is restated as deployment guidance ("a deployment SHOULD configure its stop plugin to clear persona_id on global stop") and names STOP-1 §6.2 as the normative home. No cross-PR dependency.

Unenforceable obligations demoted

• §5 unknown-persona summon MUST — no registry and no orchestrator role exists to enforce it. Replaced by a note describing the actual behaviour: route-2 fall-through, a session that behaves like no-persona mode.
• §9 collision WARN — nothing holds a deployment-wide view. Restated as provisioning-time tooling guidance over ovos.persona.list.

Underspecified surfaces defined

• §9 register/deregister: payload {persona_id}; duplicate register is a no-op; a deregistered identity keeps serving live sessions until dismissed but accepts no new summons. No response topic is added (scope guard) — rejection is observable only via ovos.persona.list.
• §8.5: whether an out-of-band exchange enters §8.4 history is plugin-defined and MUST be documented by the plugin.
• §11: activation/dismissal events scoped to plugin-observed transitions (self-summon, self-release); external summon/dismiss emit nothing. Advisory, best-effort, absence proves nothing.

Pipeline positioning

• §10 never mentioned common query, while COMMON-QUERY-1 §12 mandates that it precede persona. Added, and the MAY-place-earlier licence narrowed to domain-specialised personas that are not general question-answering.

Editorial

• Builds-on list said "four" and listed four; it depends on eight (adds SESSION-2, STOP-1, INTENT-2, TRANSFORM-1).
• §12 had two identical SHOULD headings; merged.
• CHANGELOG restructured into ### 1 (initial draft, rewritten — the old text described a spec that does not exist: an ovos.persona.capabilities topic, a MAY-return-None match, and conformance roles that were removed) and ### 2 (the actual changes).
• §11 keeps the answer / list.response naming asymmetry, now with a one-line note saying so deliberately.

Owner sign-off

1. RESOLVED — fallback_low restored as the final stage in the §10 example. Owner directive: persona stages are OPTIONAL; fallback_low is what ensures we always have an answer, and it stays below persona_low/persona_fallback in the pipeline. An earlier version of this PR dropped fallback_low from the §10 example and framed persona-fallback (route 3) as replacing the last-resort catch-all — that inverted the design. The example now reads ... common_query, persona, persona_fallback, fallback_low. Persona stages, including persona_fallback, are optional; a deployment without them is fully conformant. When persona_fallback is present it may shadow fallback_low in normal operation, but the always-answer guarantee is carried by OVOS-FALLBACK-1 §8.1's catch-all skill in fallback_low, not by route 3, and fallback_low SHOULD remain the final stage so the deployment still answers when no persona stage is loaded, the persona backend fails, or persona_fallback declines. §4 and §12 checked for the same claim and corrected identically.
2. Mandatory speak per claimed dispatch (§8.1). This is a new obligation on persona handlers, not a clarification: previously a handler MAY emit zero ovos.utterance.speak. It is the only way to close the silent-turn hole given exclusive consumption, but it does constrain implementations.

Deferred

• GLOSSARY entries (persona, summon, dismiss, no-persona mode, persona-fallback, persona_id) belong to the GLOSSARY PR, not this file.
• fallback.md ordering: resolved on the fallback PR (spec: OVOS-FALLBACK-1 — poll semantics, pong correlation, registry liveness #134) — §8.1 there now scopes the after-persona rule to the low-confidence catch-all tier, and its §8.2 example interleaves fallback_high/fallback_medium before persona with fallback_low last, consistent with this spec's §10.

[coderabbitai]

Warning

Review limit reached

@JarbasAl, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 21 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6b736bc4-6ccc-4812-8e9a-300d321f618d

📥 Commits

Reviewing files that changed from the base of the PR and between 1d3622b and d8bd1d9.

📒 Files selected for processing (2)

• CHANGELOG.md
• persona.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}