Human-in-the-Loop

HatiData V2 provides structured checkpoints where autonomous agent progression pauses for human review. Gates, review queues, and recovery workflows give managers and reviewers clear decision points without blocking the entire pipeline.

Gates: Structured Checkpoints

A gate is a named checkpoint in the agent lifecycle. Each gate has predicates — conditions that must be satisfied for the gate to pass.

Gate Types

Gate	Name	Auto-Approvable?	Purpose
G0	UX Review	No (always manual)	Wireframe sign-off before build
G1	Proposal Approval	No (always manual)	Client accepts proposal + triggers M1 payment
G2	Architecture Review	Conditionally	Architecture sign-off before parallel build
G3	Build Quality	Conditionally	QA + security pass before staging
G4	Pre-Launch Review	No (always manual)	Client UAT + preview approval
G5	Go-Live	No (always manual)	Final sign-off + M3 payment trigger

Gate Predicates

Each gate evaluates a set of predicates against a fact bag — a collection of current project state values:

{
  "gate_id": "g3",
  "predicates": [
    {
      "key": "test_results.passed_pct",
      "operator": "gte",
      "value": 95,
      "description": "At least 95% of tests must pass"
    },
    {
      "key": "security_findings.critical",
      "operator": "eq",
      "value": 0,
      "description": "No critical security findings"
    },
    {
      "key": "build_verification.compile_status",
      "operator": "eq",
      "value": "pass",
      "description": "Build must compile successfully"
    }
  ],
  "auto_approvable": true,
  "client_sign_off_required": false,
  "approval_role": "pm"
}

Predicate Operators

Operator	Meaning	Example
eq	Equals	security_findings.critical eq 0
ne	Not equals	status ne "blocked"
gt	Greater than	confidence gt 0.8
gte	Greater than or equal	tests_passing gte 95
lt	Less than	cost_usd lt 500
lte	Less than or equal	latency_ms lte 2000
contains	String contains	deploy_target contains "staging"
regex	Regex match	`agent_type regex "^(qa

Gate Evaluation Results

The gate evaluator returns one of three outcomes:

Result	Meaning	Next Action
AutoApproved	All predicates passed + gate is auto-approvable	Phase advances automatically
PendingManual	Predicates passed but gate requires human sign-off	ReviewRequest created
Failed	One or more predicates failed	Blocked — fix required

// AutoApproved example
{
  "result": "AutoApproved",
  "gate_id": "g3",
  "passed_conditions": ["test_results", "security_findings", "build_verification"],
  "failed_conditions": []
}

// PendingManual example
{
  "result": "PendingManual",
  "gate_id": "g1",
  "approval_role": "client",
  "client_sign_off": true,
  "passed_conditions": ["proposal_generated", "pricing_valid"],
  "action_url": "/portal/{project_id}/gate/g1"
}

// Failed example
{
  "result": "Failed",
  "gate_id": "g3",
  "failed_conditions": [
    {
      "key": "security_findings.critical",
      "expected": "0",
      "actual": "2",
      "message": "2 critical security vulnerabilities must be resolved"
    }
  ]
}

Review Queue

When human review is needed, a ReviewRequest is created and surfaced in the dashboard:

ReviewRequest Structure

Field	Description
id	Unique review request ID
entity_type	What needs review: gate, artifact, release_decision, recovery
entity_id	The specific entity to review
project_id	Which project
reason	Why human review is needed
urgency	low, medium, high, critical
assigned_to	Role (pm, client, admin) or specific email
status	pending, approved, rejected, deferred
created_at	When the request was created
reviewed_at	When it was acted on (null if pending)
reviewer_notes	Free-text notes from the reviewer

API Endpoints

Method	Path	Description
GET	/v2/reviews	List pending reviews (filterable by project, role, urgency)
GET	/v2/reviews/:id	Get review detail with context
POST	/v2/reviews/:id/approve	Approve with optional notes
POST	/v2/reviews/:id/reject	Reject with mandatory reason
POST	/v2/reviews/:id/defer	Defer with new deadline

Reviewer Guide

For Project Managers:

1. Check the Review Queue in the Admin Portal (Command Centre)
2. Click a pending review to see the evidence summary
3. For gate reviews: check all predicates, review the evidence bundle
4. Approve or reject with notes — the pipeline resumes or blocks accordingly

For Clients:

1. Gate notifications appear as banners in the portal dashboard
2. Click "Review Gate" to see the evidence checklist
3. G1 (Proposal) and G4 (Preview) require explicit client sign-off
4. Approval triggers the next phase + associated milestone payment

Recovery Workflows

When an agent fails and reaches L4 (Human Gate), the system creates a ReviewRequest for the recovery:

Recovery Levels and Human Involvement

Level	Human Required?	What the Reviewer Sees
L1 Retry	No	(Automatic — same model retries)
L2 Escalation	No	(Automatic — stronger model selected)
L3 Repair	No	(Automatic — RepairAgent dispatched)
L4 Human	Yes	Full ExplainBundle + failure chain + suggested actions
Blocked	Yes	Missing dependency or policy denial — manual intervention required

Recovery Actions via API

POST /v2/recovery/:attempt_id
{
  "action": "retry",
  "override_reason": "Reviewed the failure — transient issue, safe to retry"
}

Available actions:

Action	Effect
retry	Create new attempt with same configuration
retry_with_model	Create new attempt with specified model override
escalate	Bump to next recovery level
repair	Dispatch RepairAgent with custom evidence
approve	Override the failure — mark as acceptable
block	Permanently block the task — requires human resolution

The Recovery Chain

Every recovery action is recorded in the recovery_actions table, forming an audit trail:

SELECT
    ra.failure_kind,
    ra.action_type,
    ra.status,
    ra.created_at
FROM hd_runtime.recovery_actions ra
WHERE ra.task_attempt_id = :attempt_id
ORDER BY ra.created_at;

Example chain:

L1 Retry      → failed (timeout)
L2 Escalation → failed (schema validation)
L3 Repair     → failed (RepairAgent couldn't fix)
L4 Human      → pending (waiting for PM review)

Notifications

Gate evaluations and review requests generate notifications:

Event	Notification	Recipient
Gate ready for review	"G2 Architecture Review is ready"	PM
Gate requires client sign-off	"Review your proposal — G1 pending"	Client
L4 recovery needs human	"Agent blocked — manual intervention needed"	PM/Admin
Gate approved	"G3 Build Quality approved — build continues"	Client + PM
Gate rejected	"G1 Proposal rejected — changes requested"	PM

Next Steps

• Tasks & Attempts — Recovery levels and the attempt lifecycle
• Lineage & Explainability — Audit trail for gate decisions
• Entity Relationship Model — How gates fit in the entity hierarchy