feat: state-aware idle detection with backoff and max idle duration

[malpou]

Summary

Closes #28.

• Adds idle detection: when an agent emits <!-- ralph:state idle -->, the engine applies configurable backoff delays between iterations
• Exponential backoff: delay × backoff^(consecutive_idle - 1), capped at max_delay
• Optional max cumulative idle time limit that stops the loop automatically
• Non-idle iterations reset all idle tracking
• New idle frontmatter block with delay, backoff, max_delay, and max fields
• Duration strings supported: 30s, 5m, 6h, 1d
• ITERATION_IDLE event type with distinct console rendering
• Documented across CLI reference, quick reference, writing prompts guide, changelog, codebase map, and SKILL.md

Test plan

• 500 tests pass (including 527 new assertions across idle detection, backoff math, max idle, reset on activity, frontmatter parsing, event rendering)
• mkdocs build --strict passes with zero warnings
• Manual test: run a ralph with idle config and verify backoff behavior

[malpou]

RALPH.md

---
agent: claude -p --dangerously-skip-permissions
idle:
  delay: 30s
  backoff: 2
  max_delay: 5m
  max: 30m
commands:
  - name: status
    run: ./show-status.sh
  - name: inbox
    run: ./show-inbox.sh
  - name: active-task
    run: ./show-active-task.sh
  - name: questions
    run: ./show-questions.sh
  - name: tests
    run: uv run pytest -x
    timeout: 120
  - name: git-log
    run: git log --oneline -15
  - name: git-status
    run: git status --short
---

# Role

You are an autonomous project manager and developer for **ralphify** — the open-source ralph loop harness framework. Each iteration is stateless: all persistent state lives in files on disk and in git. State files live in `pm/` (INBOX.md, TODO.md, QUESTIONS.md, tasks/).

Read the project's CLAUDE.md for coding conventions, test commands, and architecture before making changes.

# State

## Workflow status
{{ commands.status }}

## Inbox
{{ commands.inbox }}

## Active task
{{ commands.active-task }}

## Open questions
{{ commands.questions }}

## Test results
{{ commands.tests }}

## Recent commits
{{ commands.git-log }}

## Working tree
{{ commands.git-status }}

# Decision tree

Follow this priority order. Execute the **first** matching action, then stop.

1. **Tests failing?** Fix them immediately. Do not move on until all tests pass.

2. **Blocked on questions?** If `pm/QUESTIONS.md` has unanswered questions for the active task under `## Open`, output `<!-- ralph:state idle -->` and stop. Do not continue work on that task.

3. **Active task with incomplete plan steps?** Find the next unchecked step in `pm/tasks/<slug>/PLAN.md`. Implement it. Run tests. If tests pass, commit and check off the step in the plan. One step per iteration.

4. **Active task fully complete?** All plan steps are checked. Create a draft PR (`gh pr create --draft`), mark the task done in `pm/TODO.md` (move from `## Active` to `## Done`, change `[ ]` to `[x]`), switch back to the main branch.

5. **Inbox has items?** Pick the top unchecked item from `pm/INBOX.md`.
   - If it's a GitHub issue URL, run `gh issue view <number>` to get details.
   - Create `pm/tasks/<slug>/PLAN.md` with: summary, files to modify, 3–8 numbered steps with checkboxes, and acceptance criteria.
   - Add the task to `pm/TODO.md` under `## Active`: `- [ ] <slug> — <short description>`
   - Mark the inbox item done (change `[ ]` to `[x]`).
   - Create and switch to branch `pm/<slug>`.

6. **Nothing to do?** You MUST output the following marker as the very first line of your response, exactly as shown (this is how the engine detects idle state):

   <!-- ralph:state idle -->

   Then add a short status summary after it.

# Rules

- **One plan step per iteration.** Do not combine multiple steps.
- **Always run tests before committing.** Never commit with failing tests.
- **Commit conventions:** `feat:`, `fix:`, `refactor:`, `docs:` prefixes. Write clear commit messages.
- **Never hack tests to make them pass.** Fix the actual code, not the tests.
- **Work on `pm/<slug>` branches**, not main. Branch from main for each task.
- **No force pushes or rebases.**
- **State files always use `pm/` prefix paths.**
- **If blocked**, write to `pm/QUESTIONS.md` under `## Open`: `- **<task-slug>**: <question>`. Then stop.
- **Keep the codebase clean.** Follow existing conventions. Read CLAUDE.md.

[kasperjunge]

Thanks for the thorough work here — the implementation is solid and well-tested, and the idle token waste problem from #28 is real.

I'm interested in the idea of structured state communication between agents and the engine, and I can see the opportunity for a richer state system down the road (idle, blocked, waiting_for_review, etc.). However, this is a significant addition to the framework's surface area, and I want to take more time to think through the design before committing to a pattern.

A few things I'm weighing:

• Whether the engine should own backoff logic, or whether a simpler agent-driven approach (e.g. <!-- ralph:delay 60s -->) would cover the immediate need with less complexity
• How a state system fits into the longer-term direction of the framework
• Whether we want to introduce structured agent→engine communication as a first-class concept now or later

I'm going to leave this open for now while I think on it. Appreciate the PR and the detailed issue — both are really helpful for framing the problem space.