M2-6: Blocked Task Explanation Helper

[akserg]

Goal

Make blocked tasks immediately understandable to humans by clearly explaining why a task is blocked, what it depends on, and how to unblock it — without requiring users to inspect raw JSON, dependency graphs, or infer state manually.

This milestone ensures that “blocked” is never a dead-end state. Every blocked task must come with an explicit, actionable explanation.

Definition of Done (DoD)

1. Explicit Blocked Reason Identification

• When a task is in blocked state, the orchestrator determines the exact reason(s), such as:
  • unmet task dependencies
  • failed or rejected prerequisite tasks
  • missing context files
  • pending approvals
  • failed preflight validation
• Block reasons are deterministic and machine-derived, not inferred heuristically

2. Human-Readable Blocked Explanation

• A clear explanation is generated describing:
  • why the task is blocked
  • what it is waiting for
  • which task(s), approval(s), or file(s) are blocking it
• The explanation is understandable without reading JSON

3. Markdown Output for Blocked Tasks

• For blocked tasks, a Markdown summary is generated or updated, including:
  • task ID and description
  • current status (blocked)
  • blocking reasons (bullet list)
  • concrete next actions required to unblock
• This information appears in:
  • task-level Markdown (exec.md if applicable)
  • plan-level Markdown (plan.md task table or section)

4. CLI Integration

• The status command (or equivalent) surfaces blocked explanations directly
• Users can quickly see:
  • why a task is blocked
  • whether action is required from them
• No need to inspect tasks/*.json manually

5. Accurate and Up-to-Date Explanations

• Blocked explanations update automatically when:
  • dependencies are approved
  • tasks complete
  • context is added
  • validations pass
• Stale or misleading explanations are not allowed

6. Auditability

• Blocked reasons are recorded in:
  • task state
  • audit.log
• Changes to blocked status (blocked → unblocked) are auditable and timestamped

7. Dogfooding Validation

• During dogfooding on llm-orchestrator:
  • At least one task is intentionally blocked
  • The blocked explanation clearly guides the user to resolution
  • No guesswork is required to unblock the task

Success Signal

When a task is blocked, the user immediately knows why, what must happen next, and who or what is responsible, without reading JSON or reverse-engineering the orchestrator state.