[Technical Debt] Verify HITL reason mapping completeness in draft generation

Summary

The determine_draft_type_from_hitl_reason() function maps HITL reasons to draft types, but it's unclear if the mapping covers all possible HITL reasons defined in the architecture.

Current State

app/llm/draft_generation.py:332-342 defines mapping for 8 HITL reasons:

mapping = {
    "information_missing": "info_request",
    "ambiguity_clarification": "info_request",
    "business_decision": "info_request",
    "policy_confirmation": "info_request",
    "high_value_approval": "order_confirmation",
    "custom_request": "info_request",
    "execution_error": "error_notification",
    "integration_failure": "error_notification"
}

Unknown: Does this cover ALL HITL reasons from architecture.md Section 6.4?

Problems

1. Incomplete mapping: If architecture defines more HITL reasons, they'll fall through to default
2. Silent failures: Unknown reasons get mapped to fallback draft type without warning
3. No validation: No way to ensure mapping stays in sync with HITL reason definitions
4. Maintenance risk: New HITL reasons added without updating draft mapping

Proposed Solution

Step 1: Audit HITL reasons

• Review docs/langgraph-rewrite/architecture.md Section 6.4
• List all defined HITL reasons
• Compare with current mapping

Step 2: Add validation

# Define canonical HITL reasons (sync with architecture)
KNOWN_HITL_REASONS = [
    "information_missing",
    "ambiguity_clarification",
    "business_decision",
    "policy_confirmation",
    "high_value_approval",
    "custom_request",
    "execution_error",
    "integration_failure",
    # Add any missing from architecture.md
]

def determine_draft_type_from_hitl_reason(
    hitl_reason: str,
    workflow_status: str
) -> str:
    # Validate known reason
    if hitl_reason not in KNOWN_HITL_REASONS:
        logger.warning(
            f"Unknown HITL reason '{hitl_reason}' - may need to update mapping. "
            f"Known reasons: {KNOWN_HITL_REASONS}"
        )
    
    # Existing mapping logic...

Step 3: Add test

def test_all_hitl_reasons_mapped():
    """Verify all known HITL reasons have draft type mapping"""
    for reason in KNOWN_HITL_REASONS:
        draft_type = determine_draft_type_from_hitl_reason(reason, "paused")
        assert draft_type in VALID_DRAFT_TYPES

Acceptance Criteria

• [ ] All HITL reasons from architecture.md Section 6.4 identified
• [ ] Mapping table verified complete or gaps documented
• [ ] KNOWN_HITL_REASONS constant added with canonical list
• [ ] Warning logged for unknown HITL reasons
• [ ] Test verifies all known reasons produce valid draft type
• [ ] Documentation notes where HITL reasons are defined (single source of truth)

Priority

Low - Likely already complete, but needs verification

Estimated Effort

1-2 hours (audit + validation code)

Related

• Agent 7 (LLM Modules)
• Agent 4 (Review Phase - HITL logic)
• app/llm/draft_generation.py
• docs/langgraph-rewrite/architecture.md Section 6.4