docs/implementation/HITL_DEDUPLICATION_IMPLEMENTATION.md

HITL Deduplication & Status Display - Implementation Complete

Issue Resolved

Problem: Duplicate HITL entries in Live/Replay view showing:

1. "Step 7.5 · awaiting-human-input" (from checkpoint_state)
2. "Step 8.0 · Human review checkpoint" (from HITL events)

Solution: Consolidate HITL entries and display decision status clearly

Implementation

File Modified

• src/data_agent_baseline/observatory/guided_trace_flow_page.py

Changes to _build_guided_replay_rows() function

1. Filter Duplicate HITL Steps (Lines ~437-439)

# Skip planner_review steps from trace.json as they're HITL steps recorded separately
# They will be consolidated from the checkpoint state and shown once
if action == "planner_review" and row.get("phase") == "planner_review":
    continue

• Removes HITL steps from trace.json to prevent duplication
• Only keeps checkpoint entry from checkpoint_state

2. Retrieve Intervention Data (Line ~455)

intervention = checkpoint_state.get("intervention") if isinstance(checkpoint_state, dict) else None

• Gets the human decision (approve, revise, cancel, etc.)

3. Display Action with Decision Status (Lines ~462-472)

base_action = checkpoint_action_map.get(checkpoint_status, "planner_review")
if intervention and isinstance(intervention, dict):
    decision = str(intervention.get("decision") or "").lower()
    if decision:
        # Show decision in the action field for clarity
        display_action = f"{base_action} • {decision}"
    else:
        display_action = base_action
else:
    display_action = base_action

• Combines action with decision: "approve • approve"

4. Enhanced Story Label with Status (Lines ~478-483)

status_label = {
    "waiting": "awaiting-human-input",
    "approved": "human-review · approved",
    "revised": "human-review · revised",
    "cancelled": "human-review · cancelled",
    "auto_approved_timeout": "human-review · auto-approved",
    "expired": "human-review · expired",
}.get(checkpoint_status, "human-review-checkpoint")

• Story label shows status: "human-review · approved"

5. Updated Checkpoint Row (Line ~487)

checkpoint_row = {
    ...
    "story_label": status_label,  # "human-review · approved"
    "action": display_action,      # "approve • approve"
    ...
}

6. Removed Duplicate Event Merging (Deleted Lines ~494-500)

• Removed: build_hitl_replay_rows() call
• Removed: Event-based HITL row merging
• Reason: Now using single checkpoint entry from checkpoint_state

Result

Before (Duplicate Entries)

Step 7.5 · awaiting-human-input    [Status: completed, Action: approve]
Step 8.0 · Human review checkpoint [Status: completed, Action: planner_review]

After (Single Consolidated Entry)

Step 7.5 · human-review · approved [Status: completed, Action: approve • approve]

Visual Improvements

Story Label Evolution

• Waiting: "awaiting-human-input"
• Approved: "human-review · approved" (with decision status)
• Revised: "human-review · revised"
• Cancelled: "human-review · cancelled"
• Auto-Approved: "human-review · auto-approved"

Action Field Enhancement

Now displays decision pair:

• "approve • approve" (base_action • decision)
• "revise • revise"
• "cancel • cancel"
• "auto_approved_timeout • timeout_auto_approve"

Key Benefits

✅ No duplicate entries in Live/Replay
✅ Clear decision status visible
✅ Single consolidated checkpoint view
✅ Maintains full audit trail in trace.json
✅ Cleaner UI with status indicators

Data Flow

1. HITL steps recorded in trace.json (for audit)
2. Checkpoint state contains resolved decision
3. Gallery filters out trace.json HITL steps
4. Displays single consolidated entry with status
5. User sees: "Step X · human-review · approved"