feat: add HITL approval to OpenWebUI directive drafter

[rlippmann]

Summary

Add HITL approval for the OpenWebUI DirectiveDrafter reference integration.

Canonical directives produced by DirectiveDrafter are now treated as proposals rather than immediate state mutations. The OpenWebUI integration presents the proposed directive to the user and requires explicit approval before calling engine.step(...).

Pending approvals are host-owned and one-turn only:

• approved proposals are applied through the compiler;
• rejected proposals are discarded without mutation;
• unrelated follow-up messages discard the pending proposal and continue through normal processing.

NoDirective and UnknownDirective behavior remains unchanged.

Why

A drafted directive is a compiler-compatible proposal, not authoritative intent.

The integration should demonstrate the complete authority boundary:

user input
  -> DirectiveDrafter
  -> CanonicalDirective proposal
  -> human approval
  -> engine.step(...)
  -> authoritative state transition

This prevents model-generated or drafted directives from becoming compiler state without explicit user approval.

The approval workflow is intentionally host-owned:

• no compiler state is added;
• no checkpoint continuation is introduced;
• no pending clarification workflow is recreated.

Example metadata

• Enforcement point: Human approval before authoritative state mutation
• Domain: Context Compiler directive drafting and state transitions
• Technology/runtime: Python OpenWebUI integration
• Example type: reference integration
• Does this use directive drafter? should normally be no: Yes
• Does this derive state from model output? must be no for primary examples: No

Checklist

• Repository scaffolding / governance change
• One primary enforcement point
• Explicit authoritative state
• No model-derived state mutation
• Adversarial stub or equivalent test
• Observable runtime behavior change
• Domain vocabulary is natural
• Framework is secondary to the enforcement point
• Docs updated
• Tests/smoke checks added where practical

Notes

The HITL flow is intentionally limited to the immediate approval interaction.

Behavior:

• CanonicalDirective:

  • show proposed directive;
  • wait for explicit approval;
  • apply only after approval.

• y / yes:

  • applies the stored directive;
  • clears pending approval state.

• n / no:

  • discards the proposal;
  • leaves compiler state unchanged.

• Any other response:

  • discards the pending proposal;
  • continues normal processing;
  • does not make later approval responses meaningful.

Validation:

• uv run pytest python/tests/test_openwebui_pipe_with_directive_drafter.py

Result:

• 21 passed