feat: add HITL approval for drafted directives

[rlippmann]

Summary

Add a host-local HITL approval gate to the LiteLLM DirectiveDrafter example.

A CanonicalDirective produced by DirectiveDrafter is now treated as a proposed state transition rather than immediately applied. The example displays the drafted directive, requires explicit approval, and only calls engine.step(...) after approval.

Rejected drafts are discarded locally:

• no compiler mutation;
• no downstream LiteLLM request;
• no persistent state change.

NoDirective and UnknownDirective behavior remains unchanged.

Why

A valid CanonicalDirective only means the drafter produced a compiler-compatible proposal. It does not prove that the user intended or approved the resulting state transition.

The reference example should demonstrate the full authority boundary:

user input
  -> DirectiveDrafter
  -> CanonicalDirective proposal
  -> human approval
  -> engine mutation

This prevents the example from implying that model-generated directives should automatically become authoritative state.

The HITL step is intentionally host-owned:

• no compiler state changes;
• no checkpoint continuation;
• no pending workflow;
• no changes to DirectiveDrafter or core.

Example metadata

• Enforcement point: Human approval before authoritative state mutation
• Domain: Context Compiler directive drafting and state transitions
• Technology/runtime: Python LiteLLM prompt-construction example
• 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 approval gate occurs only after DirectiveDrafter produces a CanonicalDirective.

Behavior:

• Approved CanonicalDirective → engine.step(...)
• Rejected CanonicalDirective → local rejection response, no mutation
• NoDirective → existing normal flow
• UnknownDirective → existing normal flow

Validation:

• uv run pytest python/tests/test_litellm_with_directive_drafter.py
• ./scripts/validate_python.sh

Results:

• focused tests passed (19 passed)
• full Python validation passed (206 passed, 6 skipped)