letsdo 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f15aee491b4d0954c628e52566908e6b7ea35428c347a79822f5781198ea4be9
-  data.tar.gz: 71b47328ea44b224cb250e4bb8d0e58c052ddd054cd950fa1b058c85933f6a91
+  metadata.gz: e0f497c054914f1f05f37a7e19a752435fd3d87d21338fc72abcec3ae739216e
+  data.tar.gz: c4950e70e6b3b05d02e13e3d439f97446246a502a8531675ccc523025c8d96c0
 SHA512:
-  metadata.gz: eab4462fe5a7bec0981c9b2a803a02063d1714cc049f51f5add4053f80c302b917491465dda6d90aa66a59fb668b33a5d2166ea95589d317e1958a3756564f1c
-  data.tar.gz: 5f1b243e5bce00874965683d68bebf22c2c9cec992e6f8ab1e825db3a0796781a47bf51be934b5c8c5409c7ad1cf85a83d8a872c807b8d4e5a6023c888f8ca73
+  metadata.gz: eca1e0f4c85e2040309987c34a2959e7eac3109bdc264b1b2db8164a7c77e9d02f56e610c9687a7cd79245a52a1ceb43e8b6a649caeb771cbdc4a32305a408e9
+  data.tar.gz: 6ce1d5f33a6e94242ed719da018f138b33cd98846e395d1e910bec6ab480bb45a70824fbc7cfee2b7bee033faee4a14329a51bb4eff7b3075b2c42873bc4524d

data/CHANGELOG.md

@@ -0,0 +1,179 @@
+# 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.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

@@ -57,7 +57,11 @@ generation, any repeatable task flow you can express as assignee + prompt.
   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 +72,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 +89,13 @@ 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 --assignee <handle> --ready --sort priority`.
+  Configurable via
   `LETSDO_BACKLOG_COMMAND`.
 
 Tests and the build use only Ruby's bundled default gems (Minitest, Rake) —
@@ -105,9 +115,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,7 +138,16 @@ 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
+# 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 +170,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 +218,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 handle. The one rule: handle = name. Also the handle 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 +336,12 @@ 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 a
+  handle via `backlog task list --assignee <handle> --exclude-status Done
+  --ready --sort priority --json`, 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 +356,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 +387,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
 

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)
@@ -32,6 +34,9 @@
 #   AGENT_ASSIGNEE_HANDLE   the agent's backlog assignee handle (default "@<name>")
 #   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.
 #

data/docs/config.md

@@ -0,0 +1,171 @@
+# letsdo — configuration reference
+
+Configuration comes from two places: environment variables (everything in
+this reference) and an optional YAML front-matter block at the top of an
+agent's prompt file, `agents/<name>.md` — see
+[Per-agent configuration](#per-agent-configuration-yaml-front-matter).
+Nothing else is configured in files.
+
+## Project layout
+
+```
+LETSDO_ROOT  (default: the current working directory)
+├── backlog/            # the Backlog.md tasks — the task provider reads them
+├── agents/<name>.md    # one prompt file per agent
+└── bin/letsdo          # the executable (or the installed letsdo command)
+```
+
+- `LETSDO_ROOT` — project root: `agents/` lives there, and the `backlog`
+  CLI resolves `backlog/` there. Default: the folder letsdo was started
+  from.
+- The agent's assignee handle is `@<name>` by default — the agent works on
+  tasks assigned to that handle.
+
+## Environment variables
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `LETSDO_ROOT` | current directory | Project root where `agents/` lives (and where the `backlog` CLI finds `backlog/`). |
+| `LETSDO_PI_FLAGS` | unset (no flags) | Extra pi flags, split on whitespace, e.g. `--model anthropic/claude-sonnet-4-5`. A `--model` here overrides the agent's front-matter `model:` (see [Per-agent configuration](#per-agent-configuration-yaml-front-matter)). |
+| `AGENT_PI_FLAGS` | unset | Fallback for `LETSDO_PI_FLAGS` when it is blank (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 (used verbatim when set). Also injected as the agent's identity in its prompt. |
+| `LETSDO_WAIT_SECONDS` | `10` | Retry interval (seconds) when there are no open tasks. |
+| `AGENT_WAIT_SECONDS` | `10` (via fallback) | Fallback for `LETSDO_WAIT_SECONDS` when it is blank (`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_DEBUG` | unset | Set to `1` to trace loop and runner decisions (`[letsdo] loop: ...`) on stderr. |
+| `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 session stop. Off by default: no task file is modified and no extra backlog subprocess runs. |
+
+### Precedence rules
+
+- `LETSDO_PI_FLAGS` → `AGENT_PI_FLAGS`: the flags are read from
+  `LETSDO_PI_FLAGS`; when it is blank/absent, `AGENT_PI_FLAGS` is used. A
+  blank result means no flags.
+- `LETSDO_WAIT_SECONDS` → `AGENT_WAIT_SECONDS`: same pattern, falling back
+  to the default `10`. A non-numeric value also falls back to `10`.
+- `LETSDO_RETRY_BASE` → `LETSDO_WAIT_SECONDS`: when
+  `LETSDO_RETRY_BASE` is blank or non-numeric, the backoff base falls back
+  to the effective `LETSDO_WAIT_SECONDS` value.
+- `LETSDO_MAX_RETRIES`: an invalid (non-integer) value falls back to `3`.
+- `LETSDO_RETRY_CAP`: an invalid (non-numeric) value falls back to `300`.
+- `AGENT_ASSIGNEE_HANDLE`: used as-is when set and non-blank; otherwise the
+  one rule: handle = `@<name>`. The resolved value is both the assignee the
+  loop queries the backlog for and the handle letsdo injects into the
+  agent's prompt identity.
+- Agent `model` → `LETSDO_PI_FLAGS`/`AGENT_PI_FLAGS`: a `--model` in the
+  flags wins; the agent's front-matter `model:` is used only when the flags
+  carry no `--model`. See
+  [Per-agent configuration](#per-agent-configuration-yaml-front-matter).
+
+### Examples
+
+```sh
+# Point letsdo at a project from anywhere
+export LETSDO_ROOT=/srv/projects/acme-backlog
+
+# Choose the pi model
+export LETSDO_PI_FLAGS="--model anthropic/claude-sonnet-4-5"
+
+# Less chatty backlog polling
+export LETSDO_WAIT_SECONDS=30
+export LETSDO_DEBUG=1        # trace loop decisions when diagnosing
+
+# Non-standard installations
+export LETSDO_PI_COMMAND=/opt/pi/bin/pi
+export LETSDO_BACKLOG_COMMAND=~/.local/bin/backlog
+```
+
+## Per-agent configuration (YAML front matter)
+
+A prompt file may start with a YAML front-matter block that carries launch
+settings for that one agent. The block is optional: a file without it
+behaves exactly as before.
+
+```markdown
+---
+model: anthropic/claude-sonnet-4-5
+---
+
+# Developer agent (developer)
+You are a developer agent named developer.
+...
+```
+
+Rules:
+
+- The block must be the *very first* thing in `agents/<name>.md`: a `---`
+  line, the YAML keys, a closing `---` line. The rest of the file stays the
+  prompt.
+- The front matter is stripped before the file is handed to the agent, so it
+  never appears in the system prompt.
+- `model` is the only key consumed today:
+  - `model: <name>` is passed to pi as `--model <name>` for that agent.
+  - Absent → no `--model` is added and pi uses its own default model.
+  - A missing file, no front matter, or invalid YAML is treated the same as
+    absent: the block is ignored and the run continues.
+- Precedence: a `--model` coming from `LETSDO_PI_FLAGS`/`AGENT_PI_FLAGS`
+  wins over the file's `model:`. If you set a global `--model`, every agent
+  uses it and the front matter is ignored — leave `--model` out of the
+  global flags to select the model per agent.
+- The block is extensible: unknown keys (e.g. `tags:`) are parsed and
+  ignored, so new parameters can be added later without breaking existing
+  prompt files.
+
+Read by `Letsdo::PromptStore#config` (`lib/letsdo/prompt_store.rb`), passed
+to the backend by `Letsdo::Agent#run` (`lib/letsdo/agent.rb`) and applied in
+`Letsdo::Backends::Pi#initialize` (`lib/letsdo/backends/pi.rb`).
+
+## TERM and TUI selection
+
+The interactive TUI is engaged only when **all** of these hold:
+
+1. stdout is a TTY, and
+2. stdin is a TTY, and
+3. `TERM` is not `dumb`.
+
+Otherwise letsdo prints the plain line-stream output — byte-identical to
+the pre-TUI behavior, with no escape codes. Set `TERM=dumb` (or pipe stdout
+through something) to force the plain mode explicitly, e.g. in scripts or
+CI.
+
+## Where each variable is read
+
+- `LETSDO_ROOT` — `Letsdo::CLI#initialize` (`lib/letsdo/cli.rb`).
+- `LETSDO_PI_FLAGS` / `AGENT_PI_FLAGS` — `Letsdo::CLI#parse_pi_flags`
+  (`lib/letsdo/cli.rb`).
+- `LETSDO_PI_COMMAND` — `Letsdo::CLI#pi_command` (`lib/letsdo/cli.rb`),
+  default `PiRunner::COMMAND` (`lib/letsdo/pi_runner.rb`).
+- `AGENT_ASSIGNEE_HANDLE` — `Letsdo::CLI#assignee_handle`
+  (`lib/letsdo/cli.rb`).
+- `LETSDO_WAIT_SECONDS` / `AGENT_WAIT_SECONDS` — `Letsdo::CLI#wait_seconds`
+  (`lib/letsdo/cli.rb`).
+- `LETSDO_BACKLOG_COMMAND` — `Letsdo::CLI#backlog_command`
+  (`lib/letsdo/cli.rb`).
+- `LETSDO_PROVIDER` — `Letsdo::Config#provider` and
+  `Letsdo::CLI::Builder#resolve_provider!` (unknown values fail fast with
+  `letsdo: unknown task provider: <name>`, exit code 1).
+- `LETSDO_BACKEND` — `Letsdo::Config#backend` and
+  `Letsdo::CLI::Builder#resolve_backend!` (unknown values fail fast with
+  `letsdo: unknown AI backend: <name>`, exit code 1).
+- `LETSDO_DEBUG` — `Letsdo::AgentLoop#initialize` (`lib/letsdo/agent_loop.rb`)
+  and `Letsdo::PiRunner#initialize` (`lib/letsdo/pi_runner.rb`); enabled when
+  the value is exactly `"1"`.
+- `LETSDO_TASK_TIME_COMMENT` — `Letsdo::Config#task_time_comment?`
+  (`lib/letsdo/config.rb`); enabled only when the value is exactly `"1"`.
+  Consumed by `Letsdo::CLI::Builder#finish_session`, which runs
+  `Letsdo::TaskTimeWriteback` at stop.
+- `TERM` — `Letsdo::CLI#tui?` (`lib/letsdo/cli.rb`).
+
+## External Requirements (not configurable)
+
+- The **pi CLI** is a runtime requirement of letsdo — an external binary,
+  not a rubygem dependency. `LETSDO_PI_COMMAND` only replaces the command
+  name. See the [usage guide](usage.md) prerequisites.
+- Test-only environment variables (`FAKE_PI_*`, `FAKE_BACKLOG_*`) belong to
+  the test fixtures (`test/fixtures/`) and are not part of the runtime
+  configuration.