task-graph-repair

Task Graph Repair

Diagnose and fix common issues: orphaned tasks, broken dependencies, stale claims, disconnected agents, and data inconsistencies.

Prerequisite: Understand task-graph-basics for tool reference.

---

Quick Start

# 1. Connect with repair capabilities
connect(name="repair-agent", tags=["repair", "admin"])
→ agent_id

# 2. Run diagnostics
list_tasks(format="markdown")        # Overview
list_tasks(blocked=true)             # Blocked tasks
list_agents(format="markdown")       # Agent status

# 3. Fix issues as discovered
# (See specific repair procedures below)

---

Diagnostic Checklist

Run these queries to identify issues:

Query	Looking For
list_tasks(blocked=true)	Tasks stuck on deps
list_tasks(status="working")	Potentially stale work
list_agents()	Disconnected/stale agents
list_marks()	Abandoned file marks
list_tasks(parent="null")	Unexpected root tasks

---

Issue: Orphaned Tasks

Symptoms: Tasks with no parent that shouldn't be root tasks.

Diagnosis:

# Find all root tasks
list_tasks(parent="null")

# Identify which are intentional vs orphaned
# Orphaned = was child, parent deleted without cascade

Repair Options:

# Option A: Re-parent to correct parent
update(agent=agent_id, task=orphan_id, parent=correct_parent_id)

# Option B: Delete if no longer needed
delete(task=orphan_id, cascade=true)

# Option C: Make intentional root
# (No action needed, just document)

---

Issue: Broken Dependencies

Symptoms: Task blocked by non-existent task, or circular dependency.

Diagnosis:

# Find blocked tasks
list_tasks(blocked=true)

# For each, check blockers exist
get(task=blocked_task_id)  # Look at blockedBy field

# Try to fetch each blocker
get(task=blocker_id)  # Will fail if deleted

Repair:

# Remove reference to deleted blocker
unblock(blocker=deleted_task_id, blocked=stuck_task_id)

# For circular deps (rare, should be rejected):
# Break the cycle by removing one edge
unblock(blocker=task_a, blocked=task_b)