ADR-087: HITL Approval Workflow for UI Changes

Document: ADR-087-hitl-approval-workflow-ui-changes
Version: 1.0.0
Purpose: Define human approval gates for AI-generated UI changes
Audience: Product managers, developers, compliance officers
Date Created: 2026-01-19
Status: ACCEPTED
Related ADRs:
  - ADR-084-moe-ui-agent-architecture (agent pipeline)
  - ADR-086-ag-ui-event-protocol-integration (event streaming)
Related Documents:
  - agents/moe-ui-hitl-orchestrator.md
  - skills/moe-ui-hitl-approval-flow/SKILL.md
  - commands/ui-approve.md

---

Context and Problem Statement

AI agents generating UI changes can make mistakes or misinterpret requirements. Without human oversight:

• Incorrect navigation structures could ship to production
• Design system violations might damage brand consistency
• Destructive changes (deleting pages) could occur without review
• Compliance requirements (accessibility) might be missed

Why now: As AI-generated UI becomes more autonomous, governance becomes critical. Enterprise customers require audit trails and approval workflows for significant changes.

If we don't decide: AI changes go directly to production with no human checkpoint, creating risk for enterprise deployments.

---

Decision Drivers

Mandatory Requirements (Must-Have)

• Block destructive/high-risk changes until approved
• Audit trail for all approval decisions
• Configurable approval thresholds per organization
• Timeout handling (auto-deny on expiration)

Important Goals (Should-Have)

• Risk-based classification (not all changes need approval)
• Fast-path for low-risk changes
• Clear UI for reviewing pending changes
• Integration with existing approval systems (Slack, email)

Nice-to-Have

• ML-based risk prediction
• Delegation to other users
• Batch approval for related changes

---

Considered Options

Option 1: Risk-Based HITL Gates (SELECTED)

Description: Classify changes by risk level, requiring human approval only for medium+ risk changes. Low-risk changes auto-approve.

Risk Matrix:

Change Type	Risk Level	Approval Required
Component styling	Low	Auto-approve
New component addition	Low	Auto-approve
Navigation restructuring	Medium	Yes
Design token changes	High	Yes
Page/route deletion	Critical	Yes + confirmation
Bulk file modification	High	Yes
Production deployment	Critical	Yes + timeout

Approval Flow:

┌─────────────────┐
│  Change Event   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Risk Assessment │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
   Low    Medium+
    │         │
    ▼         ▼
┌───────┐ ┌─────────────┐
│ Auto  │ │   Queue     │
│Approve│ │ for Review  │
└───────┘ └──────┬──────┘
                 │
                 ▼
         ┌───────────────┐
         │  HITL Review  │
         │   Interface   │
         └───────┬───────┘
                 │
          ┌──────┴──────┐
          │             │
       Approve       Deny
          │             │
          ▼             ▼
     ┌─────────┐  ┌─────────┐
     │ Execute │  │ Rollback│
     │ Change  │  │ /Cancel │
     └─────────┘  └─────────┘

Pros:

• Balances safety with velocity
• Low-risk changes don't slow development
• Configurable per organization
• Clear audit trail

Cons:

• Risk classification may miss edge cases
• Requires ML/heuristic model for classification
• Approval UI adds development work

Effort: Medium

Option 2: Approve All Changes (REJECTED)

Description: Every AI-generated change requires human approval.

Pros:

• Maximum safety
• Simple implementation
• No risk classification needed

Cons:

• Severe velocity impact
• Approval fatigue
• Defeats purpose of AI assistance
• Doesn't scale

Effort: Low

Option 3: No Approval (REJECTED)

Description: All changes apply automatically with rollback option.

Pros:

• Maximum velocity
• No approval delays
• Simplest UX

Cons:

• High risk for enterprise
• No compliance audit trail
• Mistakes ship to production
• Customer trust issues

Effort: Low

---

Decision Outcome

Chosen Option: Option 1 - Risk-Based HITL Gates

Rationale: Enterprise deployments require governance, but excessive approval gates kill productivity. Risk-based classification provides the right balance—trivial changes auto-approve while significant changes get human review. This matches how enterprises approve code changes (PR reviews for major changes, auto-merge for trivial).

---

Consequences

Positive Consequences

• Safety: High-risk changes blocked until reviewed
• Velocity: Low-risk changes don't need approval
• Audit Trail: All decisions logged with timestamps
• Compliance: Meets enterprise governance requirements
• Configurable: Organizations can tune thresholds

Negative Consequences

• Latency: Medium+ risk changes wait for approval
• Complexity: Risk classification model needed
• UX Work: Approval interface required
• Edge Cases: Some changes may be misclassified

Risk Mitigation

Risk	Mitigation
Misclassified high-risk as low	Conservative defaults; log all auto-approves for audit
Approval timeout delays	Configurable timeouts; escalation to backup approvers
Approval fatigue	Batch similar changes; clear risk explanations
Missing approvers	Delegation; auto-escalation; Slack/email notifications

---

Implementation Details

Risk Classification

Heuristic Rules:

def classify_risk(change: UIChange) -> RiskLevel:
    # Critical: Always require approval
    if change.type in ['page_deletion', 'route_deletion', 'production_deploy']:
        return RiskLevel.CRITICAL

    # High: Significant impact
    if change.type in ['design_token_change', 'bulk_modification']:
        return RiskLevel.HIGH
    if change.files_affected > 10:
        return RiskLevel.HIGH

    # Medium: User-visible changes
    if change.type in ['navigation_change', 'layout_change']:
        return RiskLevel.MEDIUM
    if change.affects_user_flow:
        return RiskLevel.MEDIUM

    # Low: Styling, additions
    if change.type in ['style_change', 'component_addition']:
        return RiskLevel.LOW

    # Default to medium if uncertain
    return RiskLevel.MEDIUM

Action Guards

Configurable guards that trigger approval:

Guard	Default	Description
file_write	ON	Any file modification
design_system_change	ON	Design token changes
navigation_restructure	ON	IA changes
bulk_modification	ON	>5 files affected
destructive_action	ON	Deletions
skill_activation	OFF	New skill activation
new_file_creation	OFF	Creating files

Approval Interface

PENDING APPROVALS
═══════════════════════════════════════════════════════════════

ID: req_abc123
───────────────────────────────────────────────────────────────
Type:      Navigation Restructuring
Risk:      ⚠️ MEDIUM
Timeout:   4:32 remaining
Rationale: Flatten 4-level navigation to 2-level

Impact:
├─ Files affected: 8
├─ Components: Header, Sidebar, NavMenu
├─ User flow: Settings section reorganized
└─ Reversible: Yes

Options:
[1] ✓ Approve  - Apply navigation changes
[2] ✗ Deny     - Keep current structure
[3] ⚙ Modify   - Adjust scope

Timeout Behavior

Risk Level	Default Timeout	On Timeout
Low	N/A (auto-approve)	N/A
Medium	5 minutes	Auto-deny
High	15 minutes	Auto-deny
Critical	No timeout	Requires explicit action

Affected Components

Component	Change Type	Impact
agents/moe-ui-hitl-orchestrator.md	Add	Approval coordination
skills/moe-ui-hitl-approval-flow/SKILL.md	Add	Workflow patterns
commands/ui-approve.md	Add	CLI interface
services/approval-queue/	Add	Backend service
packages/ui/ApprovalDialog/	Add	Frontend component

---

Validation and Compliance

Success Criteria

• Risk classification accuracy > 90%
• Approval latency < 30 seconds (P50)
• Zero critical changes bypassing approval
• Audit logs retained for 90 days
• Slack/email notifications working
• Timeout handling correct

Testing Requirements

• Unit tests for risk classification
• Integration tests for approval flow
• E2E tests for UI interface
• Load tests for concurrent approvals

---

Links

Internal Documentation

• agents/moe-ui-hitl-orchestrator.md
• skills/moe-ui-hitl-approval-flow/SKILL.md
• commands/ui-approve.md

External References

• GitHub Code Review Workflows
• NIST AI Risk Management Framework

Code Locations

• agents/moe-ui-hitl-orchestrator.md - Orchestrator agent
• services/approval-queue/ - Backend queue service
• packages/ui/ApprovalDialog/ - Frontend component

---

Changelog

Version	Date	Author	Changes
1.0.0	2026-01-19	CODITECT	Initial version

---

Compliance: CODITECT-STANDARD-ADR v1.0.0