feat(plugin): add UserLevel plugin dispatch adapter and route (PR 4/5)

[shaun0927]

Summary

PR 4 of the five-PR plan under SSOT #25 (see PR #3 / docs/userlevel-plugin-dispatch.md).

Wires the UserLevel plugin layer into the runtime dispatch contract so ooo <plugin> <command> input can be routed through the existing guarded external command runner — without bypassing trust, risk class, or shell-injection protection.

Stacking

Requires PR #30 (PR 2) and PR #31 (PR 3) to be merged first. This branch is stacked on top of feat/plugin-user-level-resolver; until the base PRs merge, this diff includes their commits.

What ships

Ourocode.Runtime.UserLevelPluginInvocation

Implements the runtime Adapter behaviour. Reads :capabilities from the dispatch context, runs the Resolver, evaluates trust state and risk class, and either invokes via :external_command_runner or returns a structured :blocked result. Argv is always a list — Dispatcher.guarded_external_command_runner stays the shell-injection authority.

Blocked reasons surfaced:

• :trust_missing
• :ambiguous_match
• :unknown_plugin_or_command
• :destructive_action_requires_approval
• :not_user_level_plugin_input
• {:external_command_failed, reason}

Destructive risk_class commands require explicit context.destructive_action_approved? = true. Default fails closed.

Ourocode.Plugin.UserLevel.PreflightView

JSON-safe projection of a PreflightResult shaped like the existing Ourocode.Command.CapabilityPreflight.Projection. Lets any UI render UserLevel plugin preflight using the same shape as the slash command preflight (trust, side_effects, candidates, match_explanation).

Ourocode.Plugin.UserLevel.Entry

Router refinement helper. Takes a parsed TaskRequest and a capability snapshot; when the input targets a known UserLevel plugin, swaps the routing_decision to :user_level_plugin and attaches plugin_id. Keeps Ourocode.Runtime.Router itself transport- and registry-agnostic.

Ourocode.Runtime.Dispatcher.RouteResolution

• Adds :user_level_plugin to @supported_routes
• Adds adapter_keys/1 clauses (plugin-id-scoped + generic fallback)
• Reuses existing validate_adapter_route guard to reject decisions that incorrectly carry adapter_route

Ourocode.TaskRequest

routing_decision type extended with :user_level_plugin kind/execution_route and optional :plugin_id field.

What is intentionally NOT in this PR

• Registry supervision wiring in ApplicationServices. Until the live TUI integration ships, callers pass capability snapshots directly via context. PR 5 wires the registry into the runtime supervision tree alongside the artifact watcher.
• /plugins refresh slash command. Ships with PR 5 once the registry is supervised.
• Continuation/auto-run policy and artifact detection. PR 5.

Closes

• Closes Vision: use Superpowers as the golden path for plugin-native workflows #15 — Superpowers vertical slice (fixture-driven E2E in the adapter tests)
• Closes Vision: make plugin workflow failures recoverable inside ourocode #17 — failures recoverable (minimal: structured :blocked reasons with remediation; full recovery deferred per docs/userlevel-plugin-dispatch.md)
• Closes Vision: make plugin trust understandable at the moment of use #20 — trust understandable at the moment of use (trust state + remediation surfaced in PreflightView)
• Closes Vision: preview plugin side effects before workflow execution #21 — preview plugin side effects before execution (side_effects projection)

Testing

• 4 ExUnit modules (async: true) covering:
  • Adapter happy path (Superpowers fixture, mock runner)
  • Trust blocked / unknown command blocked / destructive blocked + explicit approval
  • Shell-injection argv passthrough (argv stays a list of binaries)
  • Runner contract errors (:external_command_runner_not_configured, :invalid_external_command_runner)
  • PreflightView projection across :unique_match, :ambiguous, :not_applicable, missing trust
  • Entry.refine/2 rewrites only when applicable
  • Dispatcher RouteResolution validation + adapter_keys/1 for :user_level_plugin
• Local Elixir toolchain unavailable in authoring environment; CI is the source of truth. Reviewers please confirm mix test (and especially the new files under test/ourocode/plugin/user_level/ and test/ourocode/runtime/) is green before approving.

🤖 Generated with Claude Code