Vision: make plugin command resolution explainable when names are ambiguous

[Q00]

Context

Issue #2 says ourocode should resolve installed plugins and commands through the Ouroboros plugin registry, lockfile, or a stable CLI/MCP surface before dispatching UserLevel plugin workflows. That is the right technical boundary, but product quality depends on one more layer: users need to understand why a plugin command was selected, especially when names, aliases, or natural-language prompts are ambiguous.

As the installed plugin ecosystem grows, direct command and natural-language routing will encounter collisions:

• two plugins expose similar command names such as debug, inspect, or test
• a plugin command alias overlaps with a core ooo workflow term
• natural language mentions a skill name but not the owning plugin
• an installed plugin was updated and renamed a command or alias
• a user types superpowers tdd, but the authoritative command is test-driven-development

In those cases, ourocode should not silently guess. It should make command resolution explainable, reviewable, and easy to correct.

Vision

Make plugin command resolution feel deterministic even when user language is loose.

ourocode should turn a prompt into a visible resolution decision before dispatch:

Use Superpowers TDD for this refactor.

should become an explicit, inspectable match:

plugin: superpowers
command: test-driven-development
matched by: alias "tdd"
confidence: exact alias match
next step: dispatch through Ouroboros plugin firewall

When multiple matches are possible, ourocode should ask the user to choose rather than executing the most likely one. When no safe match exists, it should explain what was missing and show the closest available commands.

Product Direction

Build an explainable resolution layer on top of the authoritative plugin capability source:

1. Resolve direct ooo <plugin> <command> ... prompts deterministically when plugin and command are exact matches.
2. Resolve aliases only when the capability contract declares them.
3. Treat natural-language resolution as a ranked candidate set, not a hidden boolean route.
4. Show the chosen plugin, command, matched token or alias, and confidence before dispatch for workflow-producing or higher-risk commands.
5. Ask for clarification when multiple installed plugins or commands match the same user phrase.
6. Keep core ooo workflow terms higher priority than plugin aliases unless the user explicitly names the plugin.
7. Record the resolution decision in session/journal state so later artifacts can explain which plugin command produced them.

Why This Matters

Natural-language dispatch is only useful if users trust what will run. A capability registry answers what can run; explainable resolution answers what ourocode decided to run and why.

This prevents subtle failures:

• a generic command name routes to the wrong plugin
• an alias shadows a built-in workflow command
• command suggestions disagree with actual dispatch behavior
• plugin updates change routing without visible explanation
• audit logs show only the final command, not the reason it was selected

A clear resolution model keeps ourocode thin and safe: it still relies on Ouroboros for plugin capability truth and firewall enforcement, while owning the user-facing decision of how prompt text maps to a plugin command.

Acceptance Criteria

• Direct plugin command prompts resolve exactly when plugin and command names are unambiguous.
• Declared aliases such as tdd can resolve to canonical commands such as test-driven-development.
• Ambiguous natural-language prompts produce a clarification state with candidate plugins and commands instead of dispatching.
• Plugin aliases cannot silently override core ooo workflow terms unless the prompt explicitly names the plugin.
• The UI can display the selected plugin, canonical command, matched token or alias, and resolution confidence before dispatch.
• The resolution decision is recorded in session or journal state for auditability.
• Tests cover exact match, alias match, core command conflict, multi-plugin ambiguity, no-match fallback, and post-update command rename behavior.

Non-goals

• Defining the full plugin capability contract. See Vision: define an authoritative plugin capability contract for ourocode #9.
• Implementing plugin dispatch execution. See Support natural-language dispatch for installed Ouroboros UserLevel plugins #2.
• Building the capability registry or cache. See Establish a plugin capability registry for natural-language dispatch #8 and Vision: keep plugin capability resolution fresh across session changes #18.
• Designing the full preflight and side-effect preview. See Vision: make plugin resolution an explicit preflight step #16 and Vision: preview plugin side effects before workflow execution #21.
• Auto-installing, auto-trusting, or auto-updating plugins.

Related

• Builds on Support natural-language dispatch for installed Ouroboros UserLevel plugins #2, especially proposed scope item 2.
• Complements Vision: define an authoritative plugin capability contract for ourocode #9 by focusing on the user-facing resolution decision rather than the capability schema itself.
• Complements Vision: make plugin resolution an explicit preflight step #16 by making the preflight step explain why a command was selected.
• Complements Vision: keep plugin capability resolution fresh across session changes #18 by requiring resolution decisions to react safely when capability metadata changes.