letsdo 0.3.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f15aee491b4d0954c628e52566908e6b7ea35428c347a79822f5781198ea4be9
-  data.tar.gz: 71b47328ea44b224cb250e4bb8d0e58c052ddd054cd950fa1b058c85933f6a91
+  metadata.gz: dc2229c2f963fc9b534a3905752c851b9ffcbf1fad90fb39d3d5620529099ef0
+  data.tar.gz: 31d93968cd32489e09d0f96edeb63fdc8346fb87bcb596ab40a536821163163e
 SHA512:
-  metadata.gz: eab4462fe5a7bec0981c9b2a803a02063d1714cc049f51f5add4053f80c302b917491465dda6d90aa66a59fb668b33a5d2166ea95589d317e1958a3756564f1c
-  data.tar.gz: 5f1b243e5bce00874965683d68bebf22c2c9cec992e6f8ab1e825db3a0796781a47bf51be934b5c8c5409c7ad1cf85a83d8a872c807b8d4e5a6023c888f8ca73
+  metadata.gz: e5b56197ecfd3dfd010f46d6ba21c5731652aa2a47e4b5a3a7b19079793df6394a652def8920bd4b4444044e31538c473197f1f998f3201ccdd6c4a4b4206e10
+  data.tar.gz: 16df1906f7d721e4229c15eb9902c6840b7782b986bbe9cc3caffcfe6b150025531428cf173f46980d27df51d77362d63e6c3e29b86af3a9348331d88c81f2ec

data/CHANGELOG.md

@@ -0,0 +1,232 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.6.1] - 2026-09-18
+
+### Fixed
+
+- Assignee identity is now the bare agent name (`developer`), not an
+  `@`-prefixed handle. The backlog CLI matches `--assignee` by exact
+  string, so the legacy default made letsdo's own view of the queue
+  diverge from every exact-match consumer. Canonical tracker value is the
+  bare name; `@` stays prose-only notation (TASK-96).
+  - `Providers::Backlog` no longer passes `--assignee` on the CLI line and
+    matches the resolved assignee against stored task assignees in Ruby,
+    tolerating the legacy `@` prefix, surrounding whitespace and case; the
+    matched-not-exact values are exposed as `assignee_variants`.
+  - `AgentLoop` prints a once-per-run stderr hint when a batch matched only
+    after normalization, pointing at the tasks to reassign.
+  - `letsdo doctor` gained an assignee check: WARN on a legacy
+    `@`-prefixed `AGENT_ASSIGNEE_HANDLE` override and on `@`-prefixed
+    assignees stored on open tasks (with the reassignment command).
+  - `AGENT_ASSIGNEE_HANDLE` still works verbatim as an escape hatch.
+- Own backlog data migrated: no open task is stored with an `@`-prefixed
+  assignee anymore.
+
+### Changed
+
+- Docs flipped to bare assignees: AGENTS.md team rules (`-a developer`),
+  agent templates (`agents/developer.md`, `agents/analyst.md`), README,
+  docs/config.md, docs/usage.md, docs/prompts.md, docs/task-selection.md.
+  The TUI header keeps `@name` as display-only notation.
+
+## [0.6.0] - 2026-09-17
+
+### Added
+
+- Deterministic task selection: `Providers::Backlog` now requests
+  `--ready --sort priority` from the backlog CLI and re-sorts the normalized
+  batch in the adapter — In Progress first, then priority
+  High > Medium > Low, then ordinal ascending, then id ascending — so the
+  batch letsdo hands to the loop is the authoritative runnable order and the
+  common divergence between what letsdo reads and what the agent picks
+  disappears. Blocked tasks (unfinished dependencies) are never offered, and
+  the normalized `Task` carries the fields selection needs (`ordinal`,
+  `type`, `labels`, `milestone`) while a growing backlog JSON schema still
+  cannot crash the adapter (TASK-95).
+- `docs/task-selection.md` — how letsdo picks the next task today, the
+  missing-data table, and the recommendation roadmap (TASK-86).
+
+### Changed
+
+- Documentation for per-agent model configuration: `docs/config.md`,
+  `docs/prompts.md` and the README now cover the YAML front-matter agent
+  config block (`model:` and friends) and its interaction with
+  `LETSDO_PI_COMMAND` (TASK-89).
+
+## [0.5.0] - 2026-09-13
+
+### Added
+
+- `letsdo doctor` — an environment self-check that prints one line per
+  check with a status tag (`[ OK ]` / `[WARN]` / `[FAIL]` / `[INFO]`) and an
+  actionable hint for every FAIL/WARN, exiting 0 when nothing FAILs and 1
+  otherwise. It checks the Ruby version (`>= 3.3`), the `pi` and `backlog`
+  commands (honoring `LETSDO_PI_COMMAND` / `LETSDO_BACKLOG_COMMAND`),
+  `backlog/tasks/` under `LETSDO_ROOT`, `AGENTS.md`, a non-empty `agents/`,
+  and whether stdout is a TTY. `doctor` is a reserved agent name: it always
+  runs the self-check and never launches an agent (TASK-71).
+- Agent prompts now carry the agent's own identity: on every
+  `letsdo <name>` launch, letsdo prepends an identity block (agent name +
+  backlog assignee handle) to the system prompt, whether the prompt comes
+  from `agents/<name>.md` or the built-in default. The handle is
+  `Config#assignee_handle` (default `@<name>`, overridable with
+  `AGENT_ASSIGNEE_HANDLE`), so the identity an agent reads matches the
+  handle its backlog tasks are assigned to (TASK-85).
+- Plain mode now supports the TUI control keys when stdin is a terminal:
+  `p` pauses/resumes the running agent (SIGSTOP/SIGCONT) and `q` stops it
+  cleanly (exit 0), while the output stays a plain byte stream. With a
+  piped or `/dev/null` stdin the reader is never started, so stopping stays
+  signal-only (`SIGINT`/`SIGTERM`/`SIGHUP`) (TASK-75).
+- Inside tmux, a TUI session now labels its window with the agent name
+  (`letsdo developer` → window `developer`) instead of the process name
+  tmux's automatic-rename derives (`ruby`), so side-by-side agent panes are
+  distinguishable. automatic-rename is disabled for the session and
+  restored, together with the previous window label, on every exit path
+  (quit, stop signal, crash). Outside tmux nothing extra is written and the
+  tmux binary is never invoked (TASK-90).
+
+### Changed
+
+- When the backlog cannot be read, the loop's first "backlog unavailable"
+  message of a run now points at `letsdo doctor`; later retries keep the
+  short line, so a long outage does not repeat the hint forever (TASK-93).
+
+## [0.4.0] - 2026-09-08
+
+### Changed
+
+- `Letsdo::CLI::Builder` extracted from `CLI` — all component assembly
+  (agent, provider, loop, TUI setup) now lives in Builder; `CLI` keeps only
+  argv parsing and delegates to Builder. The former `CLILaunch` module is
+  deleted. New `test/cli_builder_test.rb` covers Builder assembly and TUI
+  detection. Zero behavioral change.
+- The gemspec now has a user-facing description (what letsdo does and why)
+  instead of an internal class inventory; `required_ruby_version` is
+  narrowed from `>= 3.0` to `>= 3.3` to match what CI actually tests
+  (Ruby 3.0–3.2 are end-of-life); `bug_tracker_uri` and `documentation_uri`
+  metadata are added; and `spec.files` ships `CHANGELOG.md` and the gemspec
+  itself alongside the code, README and LICENSE.
+
+### Fixed
+
+- The documented Ruby 4.0.x install workaround now leads with fixing the
+  environment (`gem install rbs -v '>= 4.0.0'`), with `--no-document` as a
+  fallback — the rbs upgrade actually makes the plain `gem install letsdo`
+  post-install RDoc hook succeed instead of just skipping it. The CI
+  "Verify install" step now installs the built gem without `--no-document`,
+  repairs a broken rdoc/rbs pair when `require "rdoc"` fails, runs on Ruby
+  4.0 as well as 3.3, and checks `letsdo --version` — so the exact plain
+  install path a user runs (including the RDoc hook) is guarded against the
+  rdoc/rbs conflict crashing it again.
+
+## [0.3.0] - 2026-09-07
+
+### Added
+
+- `Letsdo::Watcher` — OS file-change watching of the backlog folder via
+  inotify (Linux, through Fiddle with no external gem) with a self-pipe
+  polling fallback; the orchestrator loop now wakes on a backlog change
+  instead of waiting out the full `LETSDO_WAIT_SECONDS` interval. The wake
+  replaces the idle-phase wait only — the startup check and the re-check
+  after each finished task stay immediate provider queries.
+
+### Fixed
+
+- An explicitly injected control/stop sleeper is honored over the watcher
+  idle path, so a CLI test that injects a sleeper completes normally even
+  with the loop watcher enabled — `rake test` no longer hangs in an infinite
+  idle wait.
+- `Letsdo::Capture` runs its child in its own process group and terminates
+  the whole group when the capture is interrupted, so a stopped capture can
+  no longer leave an orphaned grandchild holding the stdout/stderr pipes.
+- Quitting the TUI no longer leaves the terminal in raw mode: raw-mode entry
+  moved to the main thread, so the saved termios (echo + canonical line
+  editing) is restored on every quit path — the shell in a tmux pane stays
+  usable.
+- A tool-only agent run after a text run no longer writes a spurious blank
+  line on stdout (`OutputStreamer#finish` resets its last-char state).
+- `require "letsdo"` no longer eagerly loads `tty-cursor` (or any tty-* gem),
+  so `rake test` runs on a clean Ruby without the gem installed; the TUI
+  still loads its gems lazily on the interactive path.
+- Documented a Ruby 4.0.x install note: the post-install RDoc hook can crash
+  on a mismatched rdoc/rbs pair — install with `--no-document`.
+
+## [0.2.0] - 2026-09-04
+
+### Added
+
+- `letsdo <name> --init` (and the flag-first form `letsdo --init <name>`)
+  creates `agents/<name>.md` with the starter default prompt
+  (`Letsdo::DefaultPrompt::TEXT`) so the prompt can be customized — the
+  agent is never started. An already existing file or an unsafe name
+  (contains `/` or `\`, or is `.`/`..`) is refused with a message on
+  stderr and exit 1; nothing is ever written outside `agents/`
+  (`Letsdo::PromptStore#create_agent`).
+- Built-in default prompt (`Letsdo::DefaultPrompt::TEXT`): `letsdo <name>`
+  starts the agent even without `agents/<name>.md` — the run falls back to
+  the built-in process-only prompt, and letsdo announces once on stderr
+  the exact path checked (`<root>/agents/<name>.md`) plus the
+  `letsdo <name> --init` placement hint. `UnknownAgentError` is removed:
+  with the fallback there are no unknown agents, the base `Letsdo::Error`
+  remains the package error surface.
+- Real pause semantics for the TUI 'p' key: mid-run the pi group is
+  suspended at the kernel level (SIGSTOP via `Letsdo::PiRunner#pause`,
+  resume via SIGCONT); between runs a shared `Letsdo::Control::PauseGate`
+  holds new runs until resume. The footer flips between `p pause` and
+  `p resume`.
+- `SIGHUP` (terminal closed) stops the loop the same way as `SIGINT`/
+  `SIGTERM`.
+- Prompt stop of a paused pi: `PiRunner#terminate` now reaps the child
+  during its grace wait (WNOHANG) instead of polling the process table,
+  so a signal-killed child's zombie state can no longer stall the stop
+  for the full grace period.
+- Gemspec metadata: `homepage`, `homepage_uri`, `source_code_uri`,
+  `changelog_uri`, `allowed_push_host`.
+- `CHANGELOG.md`.
+- Default RuboCop 1.77 as a development dependency; CI fails the build
+  on style violations.
+
+### Changed
+
+- Tool result bodies (indented stdout/stderr blocks, truncation notes,
+  `✖ Error:` markers) are no longer printed to the aux output; the stream
+  shows only tool invocations (`HH:MM:SS ⚙ name: args`) and a one-line
+  completion with duration (`✓/✖ name: done/error (Ns)`).
+- `Session#quit` sets the stop flag before raising `Letsdo::Stopped`, so
+  the input thread renders no frames during teardown.
+
+### Fixed
+
+- `rake test` no longer prints `Open3.capture3` reader-thread dumps
+  (`IOError: stream closed in another thread`): `Letsdo::BacklogTasks` now
+  captures the backlog CLI output through `Letsdo::Capture`, whose reader
+  threads tolerate the pipes being closed when a stop (TUI quit, signal)
+  interrupts an in-flight backlog call and whose cleanup reaps the child
+  even then.
+- CLI tests no longer collide on a shared `/tmp` “tasks already served”
+  marker after Minitest reseeds `Kernel.srand` per test class.
+
+## [0.1.0] - 2026-09-04
+
+### Added
+
+- Initial release of letsdo — a local agent worker for Backlog.md/markdown tasks.
+- OOP structure: `Letsdo::PromptStore` (agents/), `Letsdo::OutputStreamer` and
+  `Letsdo::PiRunner` (pi --mode json), `Letsdo::Agent` (one run), `Letsdo::Loop`
+  (orchestrator loop), `Letsdo::CLI`.
+- Interactive TUI (header metrics, scrollable stream) in TTY mode; plain
+  line-stream mode for pipes/CI/tests.
+- Minitest tests; CI (GitHub Actions) builds the gem and runs tests on every push.
+- Local executable `letsdo`.
+
+[Unreleased]: https://github.com/sergio-fry/letsdo/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/sergio-fry/letsdo/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/sergio-fry/letsdo/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/sergio-fry/letsdo/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/sergio-fry/letsdo/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/sergio-fry/letsdo/releases/tag/v0.1.0

data/README.md

@@ -32,8 +32,9 @@ platform — the backlog folder is the single source of truth.
   already have everything letsdo needs. The tasks are the instructions;
   letsdo only executes them.
 - **Zero-config team.** A new agent is a new file: `agents/<name>.md`
-  with the agent's instructions. The assignee handle is derived from the
-  name (`@developer` ↔ `developer`), so the agent automatically works on
+  with the agent's instructions. The assignee is derived from the
+  name (`developer` the agent ↔ `developer` the assignee; `@developer`
+  is prose notation only), so the agent automatically works on
   the tasks already assigned to it. No code, no schemas, no setup.
 - **One task per run — honest work.** Each run picks up exactly one open
   task and completes it before the next. No context-switching, no runaway
@@ -53,11 +54,15 @@ generation, any repeatable task flow you can express as assignee + prompt.
 ## Features
 
 - **One-command agent run** — `letsdo <name>` starts the loop: all open
-  tasks assigned to `@<name>` are done one after another (one agent run =
+  tasks assigned to `<name>` are done one after another (one agent run =
   one task), then the loop waits for new ones until stopped with
   `SIGINT/SIGTERM` (clean exit, code 0).
 - **Agents as prompt files** — `agents/<name>.md` is the whole identity of
-  an agent: role, rules, workflow. Add a file, get an agent.
+  an agent: role, rules, workflow. Add a file, get an agent. letsdo injects
+  the agent's name and backlog assignee handle into the prompt on every
+  launch, so the template only needs role and rules. An optional YAML
+  front-matter block in the same file sets per-agent launch settings —
+  today `model:` selects the pi model for that agent.
 - **Built-in default prompt** — an agent starts even without a prompt file:
   it runs on the built-in default prompt (process-only instructions), and
   letsdo announces once where the prompt was looked for and how to create
@@ -68,6 +73,11 @@ generation, any repeatable task flow you can express as assignee + prompt.
 - **Orchestrator loop** — retries every 10 s (configurable) when there are
   no open tasks, pauses when the backlog is unreadable instead of crashing,
   and stops instantly on `Ctrl+C`.
+- **Pause/quit in plain mode** — when stdin is still a terminal (e.g.
+  `letsdo developer > run.log`), `p` pauses/resumes the running agent and
+  `q` stops it cleanly, exactly like the TUI keys; the byte stream itself
+  stays plain. With a piped stdin the control keys are unavailable and
+  stopping stays signal-only (`Ctrl+C`/`SIGTERM`/`SIGHUP`).
 - **Streaming output** — agent text streams to stdout as it is generated;
   service and tool lines go to stderr with a shared `HH:MM:SS` prefix:
   tool start (`⚙ name: args`) and completion with duration
@@ -80,12 +90,14 @@ generation, any repeatable task flow you can express as assignee + prompt.
 
 ## Requirements
 
-- Ruby **>= 3.0**.
+- Ruby **>= 3.3**.
 - The [pi](https://github.com/earendil-works/pi) agent CLI on
   `PATH` — this is the AI backend that runs the agent (`pi --mode json`).
   The command is configurable via `LETSDO_PI_COMMAND`.
 - The Backlog.md CLI (`backlog`) on `PATH` — the task provider reads open
-  tasks via `backlog task list --assignee <handle>`. Configurable via
+  tasks via `backlog task list --exclude-status Done --ready --sort
+  priority --json` and matches the agent's assignee on them.
+  Configurable via
   `LETSDO_BACKLOG_COMMAND`.
 
 Tests and the build use only Ruby's bundled default gems (Minitest, Rake) —
@@ -105,9 +117,10 @@ gem install letsdo-0.3.0.gem
 > **Ruby 4.0.x note.** Some Ruby 4.0.x builds ship default gems out of sync —
 > rdoc 8.0.0 declares `rbs >= 4.0.0` while rbs 3.x is bundled — so the
 > post-install RDoc hook can raise `Gem::ConflictError` even though the gem
-> files are already installed. Install without documentation to skip the
-> hook (`gem install letsdo-0.3.0.gem --no-document`), or install a matching
-> rbs first (`gem install rbs -v '>= 4.0.0'`).
+> files are already installed. Fix the environment by installing a matching
+> rbs first (`gem install rbs -v '>= 4.0.0'`); if that is not possible,
+> install the gem without documentation to skip the hook
+> (`gem install letsdo-0.3.0.gem --no-document`).
 
 or run it straight from the checkout without installing:
 
@@ -127,9 +140,18 @@ cd your-backlog-project
 # create an agent prompt (once)
 letsdo developer --init        # writes agents/developer.md, never runs the agent
 
-# or write agents/developer.md by hand — the file is the agent's instructions
-
-# run the agent: it works through all open tasks assigned to @developer
+# or write agents/developer.md by hand — the file is the agent's instructions.
+# It can start with an optional YAML front-matter block that sets per-agent
+# launch settings — today, the pi model:
+#
+#   ---
+#   model: anthropic/claude-sonnet-4-5
+#   ---
+#
+# Without model:, pi's own default model is used. A --model in
+# LETSDO_PI_FLAGS overrides the file.
+
+# run the agent: it works through all open tasks assigned to developer
 letsdo developer
 ```
 
@@ -150,12 +172,34 @@ The agent still runs — on the built-in default prompt. The notification is
 printed once per process. The looked-up path is exactly
 `<LETSDO_ROOT>/agents/<name>.md`.
 
+Not sure what is broken in the environment? Run the self-check:
+
+```
+$ letsdo doctor
+[ OK ] ruby 4.0.2 (>= 3.3)
+[ OK ] pi command found: pi
+[ OK ] backlog command found: backlog
+[ OK ] project root /home/user/backlog-project has backlog/tasks/
+[ OK ] AGENTS.md present at /home/user/backlog-project/AGENTS.md
+[ OK ] agents/ present with 1 prompt(s)
+[INFO] stdout is not a TTY - plain mode
+```
+
+One line per check with a status tag (`[ OK ]`, `[WARN]`, `[FAIL]`,
+`[INFO]`); every FAIL and WARN carries an actionable hint. It exits 1 when a
+check FAILs (0 otherwise, warnings included), so it can gate scripts.
+`doctor` is a reserved agent name — it always runs the self-check and never
+launches an agent. When the loop cannot read the backlog, its first
+`backlog unavailable` message of a run points at `letsdo doctor`, so the
+cause is one command away.
+
 For the full walkthrough — install, session anatomy (plain and TUI), the
 loop/waiting model, exit codes — see the [usage guide](docs/usage.md).
 
 CLI reference:
 
 ```
+letsdo doctor              # environment self-check, exit 0 unless a check FAILs
 letsdo <name>              # run the <name> agent in the loop (exit 0 on stop)
 letsdo <name> --init       # create agents/<name>.md, never run the agent (exit 0)
 letsdo --init <name>       # same as above (flag-first form)
@@ -176,19 +220,100 @@ All knobs are environment variables:
 | Variable | Default | Purpose |
 | --- | --- | --- |
 | `LETSDO_ROOT` | current folder | Project root where `agents/` lives (and where the `backlog` CLI finds `backlog/`). |
-| `LETSDO_PI_FLAGS` | — | Extra pi flags, e.g. `--model anthropic/claude-sonnet-4-5` (split on whitespace). |
+| `LETSDO_PI_FLAGS` | — | Extra pi flags, e.g. `--model anthropic/claude-sonnet-4-5` (split on whitespace). A `--model` here overrides the agent's front-matter `model:`. |
 | `AGENT_PI_FLAGS` | — | Fallback for `LETSDO_PI_FLAGS` (compatibility with the old `bin/agent`). |
 | `LETSDO_PI_COMMAND` | `pi` | The pi command used to run agents; overridable for tests / fake pi. |
-| `AGENT_ASSIGNEE_HANDLE` | `@<name>` | The agent's backlog assignee handle. The one rule: handle = name. |
+| `AGENT_ASSIGNEE_HANDLE` | `<name>` | The agent's backlog assignee. The one rule: assignee = name, stored bare (`@` is prose-only notation). Also the assignee injected into the agent's prompt identity. |
 | `LETSDO_WAIT_SECONDS` | 10 | Retry interval when there are no open tasks. |
 | `AGENT_WAIT_SECONDS` | — | Fallback for `LETSDO_WAIT_SECONDS` (`bin/agent-loop` compatibility). |
+| `LETSDO_MAX_RETRIES` | 3 | Max consecutive failed runs of the same task before giving up for the session. |
+| `LETSDO_RETRY_BASE` | = `LETSDO_WAIT_SECONDS` | Base backoff seconds; doubles per failure, capped by `LETSDO_RETRY_CAP`. |
+| `LETSDO_RETRY_CAP` | 300 | Maximum backoff seconds between attempts. |
 | `LETSDO_BACKLOG_COMMAND` | `backlog` | The Backlog.md CLI command used as the task provider. |
+| `LETSDO_PROVIDER` | `backlog` | Task provider name used by the loop (currently only `backlog`). |
+| `LETSDO_BACKEND` | `pi` | AI backend that runs each agent (only `pi` today; `LETSDO_PI_COMMAND`/`LETSDO_PI_FLAGS` keep working as before). |
+| `LETSDO_METRICS_FILE` | — | Append session metrics as JSON Lines (`session_start`, one `run_finished` per task, `session_stop`) to this path. Unset disables the file. |
+| `LETSDO_TASK_TIME_COMMENT` | unset (off) | Set to `1` to append a `letsdo: completed in <time>` comment to each completed task's backlog record at stop (see the stop summary below). Off by default: no task file is modified and no extra backlog subprocess runs. |
 | `LETSDO_DEBUG` | — | Set to `1` to trace loop decisions on stderr. |
 
+On stop, letsdo prints a session summary to stderr — done / failed /
+interrupted counts, open tasks left, total session time, time inside runs,
+the derived waiting time, the average done-run duration, and up to ten
+per-task lines (`TASK-42 done in 2m 10s`):
+
+```
+letsdo: session: 3 done, 1 failed, 0 interrupted, 4 left open, 12m 30s (8m 10s in runs, 4m 20s waiting, avg 2m 43s)
+letsdo:   TASK-12 done in 3m 5s
+letsdo:   TASK-13 failed in 1m 2s
+```
+
+The same summary prints in TUI mode after the terminal is restored, so a
+TUI session leaves the identical record on stderr. With
+`LETSDO_METRICS_FILE` set, the recorder also appends one JSON object per
+event — `session_start`, `run_finished` (`{task, exit, outcome,
+ elapsed_s, ts}`) and `session_stop` — flushing each line as it is written.
+An unwritable path only warns on stderr; the run continues without the
+file. `waiting` is a derived approximation (session time minus run time):
+it also covers polling and backlog reads, not only idle waiting.
+
+### Per-task elapsed in the task record (opt-in)
+
+With `LETSDO_TASK_TIME_COMMENT=1`, letsdo writes the elapsed time back into
+the task record at stop. The write-back is batched after every agent run
+has ended (so it cannot race the agent's own closing edit), re-queries the
+provider once, and comments only exit-0 runs whose task is **no longer
+open** — a task still open after its run is skipped, because calling it
+completed would be wrong. The comment is authored as `@letsdo`:
+
+```
+letsdo: completed in 4m 12s
+```
+
+It runs the configured `LETSDO_BACKLOG_COMMAND` in the project root
+(`backlog task edit <id> --comment '...' --comment-author @letsdo`). A
+missing or renamed task, or a failing command, warns once per task
+(`letsdo: cannot write task time comment for TASK-12: ...`) and the summary
+reports `N comments not written`; the stop path and the exit code are
+unaffected. The flag is off by default, so a normal session never touches
+task files and never spawns an extra backlog process.
+
 The comprehensive reference — every variable with defaults, precedences,
 examples and where each one is read — lives in the
 [configuration reference](docs/config.md).
 
+## Failure handling
+
+When an agent run fails, the loop avoids hammering the same task and
+instead backs off, then gives up for the session:
+
+- **Non-zero exit** (including a task killed by a signal, exit 128+):
+  counts as a failure of that task.
+- **Exit 0 but the task is still open** on the next provider poll:
+  also counts as a failure — the agent ended without closing the task.
+- **Task gone from the provider** after a run: counts as success and
+  clears the task's retry state.
+
+Failing tasks are retried with exponential backoff: after the *n*
+failure the task is skipped from the attempt batches until
+`now >= now + min(LETSDO_RETRY_BASE * 2^(n-1), LETSDO_RETRY_CAP)`
+seconds have elapsed (default: 10s, 20s, 40s, capped at 300s).
+
+After `LETSDO_MAX_RETRIES` (default 3) consecutive failures the loop
+stops attempting that task for the rest of the session, logs
+`letsdo: giving up on <TASK> after N failed runs — task stays open,
+next session will retry it` to stderr, and keeps processing other
+open tasks. A fresh `letsdo` session starts with no failure state,
+so a temporarily-failing task is retried next session.
+
+**Backend missing**: when the AI backend binary cannot be started
+(`LETSDO_PI_COMMAND` points at a nonexistent or non-executable file),
+letsdo prints a clear message and exits with code 2 — no Ruby
+backtrace.
+
+The loop's stop semantics are unchanged: `SIGINT`/`SIGTERM` during a
+backoff cooldown exits promptly with code 0, and a started run is
+always terminated (TERM then KILL after a grace period) and reaped.
+
 ## How it works
 
 ```
@@ -213,10 +338,13 @@ bin/letsdo ──► Letsdo::CLI ──► Letsdo::Agent ──► Letsdo::PiRun
   code (including 128+signal).
 - `Letsdo::OutputStreamer` — routes agent text to stdout and service/tool
   lines to stderr with `HH:MM:SS` prefixes and durations.
-- `Letsdo::BacklogTasks` — the task provider: open tasks for a handle via
-  `backlog task list --assignee <handle> --exclude-status Done --json`;
-  `nil` when the backlog is unreadable (the loop pauses instead of running
-  the agent).
+- `Letsdo::BacklogTasks` — the task provider: runnable open tasks for the
+  assignee via `backlog task list --exclude-status Done --ready --sort
+  priority --json` with the assignee matched in Ruby (tolerating the
+  legacy `@` notation), returned in the authoritative run order
+  (In Progress first, then priority High > Medium > Low, then ordinal, then
+  id); `nil` when the backlog is unreadable (the loop pauses instead of
+  running the agent).
 - `Letsdo::Loop` / `Letsdo::AgentLoop` — the orchestrator: tasks → one run
   each → wait → repeat; stopped from outside via `SIGINT/SIGTERM` (the
   running pi child is terminated, exit 0).
@@ -231,9 +359,14 @@ common. This repository itself is run by letsdo: `agents/developer.md` and
 - [Usage guide](docs/usage.md) — install, first run, loop semantics,
   the interactive TUI and its keys, exit codes.
 - [Prompt-authoring guide](docs/prompts.md) — what makes a good agent
-  prompt: must-haves, anti-patterns, worked examples.
-- [Configuration reference](docs/config.md) — every environment variable,
-  its default, precedence and where it is read.
+  prompt: must-haves, anti-patterns, per-agent front-matter config, worked
+  examples.
+- [Configuration reference](docs/config.md) — every environment variable
+  and the per-agent YAML front-matter block, their defaults, precedence and
+  where they are read.
+- [Task selection](docs/task-selection.md) — how the next task is chosen,
+  the selection criteria and the deterministic-ordering behavior of the
+  provider batch.
 
 ## Development
 
@@ -257,7 +390,7 @@ gem build letsdo.gemspec
 
 Cleanliness is enforced by the CI workflow
 (`.github/workflows/ci.yml`): gem build + `rake test` on every push,
-Ruby 3.3 (satisfies `required_ruby_version: ">= 3.0"`).
+Ruby 3.3 and 4.0 (satisfies `required_ruby_version: ">= 3.3"`).
 
 ## Alternatives
 
@@ -269,7 +402,7 @@ Ruby 3.3 (satisfies `required_ruby_version: ">= 3.0"`).
 | [aider](https://github.com/Aider-AI/aider) | Pair-programming CLI | Local AI pair for code changes | Focused on interactive coding pairs, not executing a tracked backlog |
 
 What none of them do out of the box: take an existing markdown backlog,
-derive the team from the assignee handles, and execute the tasks one per
+derive the team from the assignees, and execute the tasks one per
 run with an observable loop. That is letsdo's niche — a thin convention
 layer instead of a framework. If your project is tracked in Backlog.md
 format and you want a local, observable, multi-agent worker on top of it,

data/bin/letsdo

@@ -16,6 +16,8 @@
 # so the prompt can be customized before the first run).
 #
 # Usage:
+#   ./bin/letsdo doctor       # environment self-check, exit 0 unless a check FAILs;
+#                             #   'doctor' is reserved -- it never runs an agent
 #   ./bin/letsdo <name>       # run the <name> agent in the loop (exit 0 on stop)
 #   ./bin/letsdo <name> --init # create agents/<name>.md with the starter
 #                               #   default prompt, never run the agent (exit 0)
@@ -29,9 +31,14 @@
 #   LETSDO_ROOT             project root with agents/ (default — current folder)
 #   LETSDO_PI_FLAGS         extra pi flags (e.g. "--model anthropic/claude-sonnet-4-5")
 #   AGENT_PI_FLAGS          the same, for bin/agent compatibility if LETSDO_PI_FLAGS is unset
-#   AGENT_ASSIGNEE_HANDLE   the agent's backlog assignee handle (default "@<name>")
+#   AGENT_ASSIGNEE_HANDLE   the agent's backlog assignee (default <name>,
+#                           the bare name; a legacy '@<name>' value is warned
+#                           about by `letsdo doctor`)
 #   LETSDO_WAIT_SECONDS     retry interval when no tasks are open (default 10)
 #   LETSDO_BACKLOG_COMMAND  the backlog CLI command (default "backlog")
+#   LETSDO_PROVIDER         task provider name (default "backlog")
+#   LETSDO_BACKEND          AI backend that runs each agent (default "pi";
+#                           unknown values fail fast with exit code 1)
 #
 # A new agent = a new agents/<name>.md file, no code changes needed.
 #