Description

When running ralphex against a markdown file that is a reference spec rather than an
executable task plan, Ralphex enters the task execution loop, burns iterations, and
eventually fails with TASK_FAILED.

Example:

ralphex --task-model=haiku --review-model=codex docs/
plans/04_flowsave_pr3_operational_addendum.md

The file is a valid markdown spec, but it contains no executable task sections.

Steps to reproduce

1. Create a markdown plan/spec file with headings and prose, but no task sections:

   Operational Addendum

   API Contract

   Details...

   Error Model

   Details...

2. Run Ralphex against it:

   ralphex docs/plans/operational-addendum.md

3. Ralphex starts the task execution phase.

4. The task model reports that the file has no ## Tasks, no ### Task N, and no unchecked -
   [ ] items.

5. Ralphex retries the task iteration.

6. The run eventually fails with:

   task failed, retrying...
   error: runner: task phase: task execution failed after retry (FAILED signal received)

Root cause analysis

From the observed behavior:

• Ralphex validates that a plan file exists.
• It then enters the task loop and delegates task discovery to the model prompt.
• If the file has no executable task sections, the model can only report that it has
  nothing to do.
• That gets treated as task execution failure instead of invalid input.
• The retry path makes the failure noisier and more expensive than necessary.

This is a plan validation problem, not a task execution problem.

Expected behavior

Ralphex should fail fast before starting the model loop when the provided file has no
executable tasks.

A clear non-retryable error would be enough:

Invalid plan: no executable task sections found.

Expected:

Tasks

Task 1: Title

• Acceptance criterion
• Verification step

This file appears to be a reference spec. Add task sections or pass a different plan file.

Suggested fix

Add a preflight validation step before task execution:

• Parse the plan file.
• Confirm at least one executable task section exists.
• Confirm task sections contain unchecked actionable - [ ] items, or treat the plan as
  already complete if all task checkboxes are checked.
• If no task sections exist, exit with a non-retryable invalid-plan error.
• Do not enter the task loop or retry.

Optional follow-up: add an explicit --generate-tasks mode if converting specs into
executable plans is intended behavior.

Environment

• ralphex v0.27.2-9fd2f40-20260416T233117
• macOS
• zsh
• Plan file was a markdown operational spec with no task checklist sections.