letsdo 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 203275d9cd697301e22719a2b0aefa7226109be30e7b6092854f18589b9cb871
-  data.tar.gz: e667e3dd817fc6e2948e1e59b57a034e007dc4be73997ce37a12e4a44b8c4670
+  metadata.gz: dc2229c2f963fc9b534a3905752c851b9ffcbf1fad90fb39d3d5620529099ef0
+  data.tar.gz: 31d93968cd32489e09d0f96edeb63fdc8346fb87bcb596ab40a536821163163e
 SHA512:
-  metadata.gz: 388f387315f4e806ee61721dda7a71ba771d086ba1bc6a4d8a0e849a8dcb31f16120f1c9a3c7b38784215d43d407e1a9bf77ae33029e6e76482c3d2fedb65579
-  data.tar.gz: 0fef5205aa7e9f97b61a1f2fe28cb8a785fef771326921dbc1718d0387270fe1b23d1aa69b05a3ed5cc936a8c4163f0b3346dbb5510692d67738b7efeb10144c
+  metadata.gz: e5b56197ecfd3dfd010f46d6ba21c5731652aa2a47e4b5a3a7b19079793df6394a652def8920bd4b4444044e31538c473197f1f998f3201ccdd6c4a4b4206e10
+  data.tar.gz: 16df1906f7d721e4229c15eb9902c6840b7782b986bbe9cc3caffcfe6b150025531428cf173f46980d27df51d77362d63e6c3e29b86af3a9348331d88c81f2ec

data/CHANGELOG.md

@@ -5,6 +5,35 @@ 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

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,7 +54,7 @@ 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
@@ -94,7 +95,8 @@ generation, any repeatable task flow you can express as assignee + prompt.
   `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> --ready --sort priority`.
+  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`.
 
@@ -149,7 +151,7 @@ letsdo developer --init        # writes agents/developer.md, never runs the agen
 # 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
+# run the agent: it works through all open tasks assigned to developer
 letsdo developer
 ```
 
@@ -221,7 +223,7 @@ All knobs are environment variables:
 | `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. Also the handle injected into the agent's prompt identity. |
+| `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. |
@@ -336,9 +338,10 @@ 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: 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
+- `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).
@@ -399,7 +402,7 @@ Ruby 3.3 and 4.0 (satisfies `required_ruby_version: ">= 3.3"`).
 | [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

@@ -31,7 +31,9 @@
 #   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")

data/docs/config.md

@@ -18,8 +18,10 @@ LETSDO_ROOT  (default: the current working directory)
 - `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.
+- The agent's assignee is `<name>` by default — the agent works on tasks
+  assigned to that name. The tracker stores bare names; `@<name>` is
+  prose-only notation (`letsdo doctor` warns about legacy `@`-prefixed
+  data).
 
 ## Environment variables
 
@@ -29,7 +31,7 @@ LETSDO_ROOT  (default: the current working directory)
 | `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. |
+| `AGENT_ASSIGNEE_HANDLE` | `<name>` | The agent's backlog assignee (used verbatim when set; the bare name is canonical, a legacy `@`-prefixed value still matches but `letsdo doctor` warns). 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. |
@@ -54,9 +56,12 @@ LETSDO_ROOT  (default: the current working directory)
 - `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.
+  one rule: assignee = `<name>` (the bare name). The resolved value is both
+  the assignee the loop matches backlog tasks by and the assignee letsdo
+  injects into the agent's prompt identity. The match tolerates the legacy
+  `@` prefix, whitespace and case, so old data keeps working — but the
+  canonical stored value is the bare name, and deviations trigger a
+  once-per-run warning plus a `letsdo doctor` WARN.
 - 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

data/docs/prompts.md

@@ -1,8 +1,9 @@
 # letsdo — prompt-authoring guide
 
 An agent in letsdo is exactly one file: `agents/<name>.md`. The file is the
-agent's whole identity — role, rules, workflow. The assignee handle is
-derived from the name (`agents/developer.md` ⇄ `@developer`), so the agent
+agent's whole identity — role, rules, workflow. The assignee is
+derived from the name (`agents/developer.md` ⇄ assignee `developer`; in
+prose you write `@developer`), so the agent
 automatically works on the tasks already assigned to it. Adding a file
 creates an agent; no code, no schemas, no setup.
 
@@ -21,9 +22,9 @@ worked examples from this repository's own agents.
 - The prompt is read on every run from `<LETSDO_ROOT>/agents/<name>.md` and
   handed to pi as the agent's system prompt (`pi --mode json`).
 - Before the prompt is handed over, letsdo prepends the agent's identity —
-  its name and backlog assignee handle (`Config#assignee_handle`, default
-  `@<name>`) — to it. The injection always happens, whatever the template
-  contains, so a template never has to state the name or handle.
+  its name and backlog assignee (`Config#assignee_handle`, default
+  `<name>`, the canonical bare name) — to it. The injection always happens, whatever the template
+  contains, so a template never has to state the name or assignee.
 - When the file is missing, the agent runs on the built-in default prompt
   (process-only instructions); letsdo announces where it looked and how to
   create a prompt (`letsdo <name> --init`).
@@ -68,9 +69,9 @@ an environment variable (see the [configuration reference](config.md)).
 
 A robust agent prompt has these parts:
 
-1. **Identity.** The agent's identity — its name and backlog assignee
-   handle — is injected by letsdo at the top of every prompt, so the
-   template does not have to state it. A hardcoded handle is a bad idea:
+1. **Identity.** The agent's identity — its name and backlog assignee —
+   is injected by letsdo at the top of every prompt, so the
+   template does not have to state it. A hardcoded assignee is a bad idea:
    it drifts from `AGENT_ASSIGNEE_HANDLE` and the backlog assignment. You
    can still describe the role in prose; keep the name in the prompt
    matching the file name.
@@ -143,7 +144,7 @@ A robust agent prompt has these parts:
   (task notes, comments) as it goes.
 - **Untestable acceptance criteria.** "Works well" cannot be verified.
   Prefer testable, objective criteria ("`rake test` green, 0 failures",
-  "the created task is assigned to @developer").
+  "the created task is assigned to developer").
 - **Missing identity/role.** Without a role the agent cannot tell what it
   owns. letsdo injects the name and handle, but the role and rules are the
   template's job.
@@ -204,6 +205,6 @@ Before writing `agents/<name>.md`, check:
 - [ ] Deliverables: concrete artifacts, paths, acceptance criteria.
 - [ ] Style/language conventions for tracked artifacts.
 - [ ] Prohibitions (unassigned work, several tasks per run, ...).
-- [ ] Prompt matches the file name (`<name>.md` ⇄ `@<name>`).
+- [ ] Prompt matches the file name (`<name>.md` ⇄ assignee `<name>`).
 - [ ] (Optional) Front-matter `model:` is set only when you want a
       per-agent model — a global `--model` flag overrides it.

data/docs/task-selection.md

@@ -43,9 +43,13 @@ record; scopes B and C remain out of scope.
 End-to-end, one `letsdo <name>` session:
 
 1. `Letsdo::Providers::Backlog` runs
-   `backlog task list --assignee <handle> --exclude-status Done --ready
+   `backlog task list --exclude-status Done --ready
    --sort priority --json` (`lib/letsdo/providers/backlog.rb`,
-   `#command_line`). `--ready` drops tasks whose dependencies are not all
+   `#command_line`) — the CLI line carries no `--assignee` (backlog CLI
+   matches it by exact string, which made notation drift invisible) — and
+   matches the agent's assignee on the returned tasks in Ruby
+   (`#normalized` comparison of the stored values against the resolved
+   handle). `--ready` drops tasks whose dependencies are not all
    done; `--sort priority` orders by priority then ordinal as a first pass.
 2. The adapter projects each raw task onto `TASK_FIELDS =
    %w[id title status priority assignees ordinal type labels milestone]` and
@@ -65,7 +69,7 @@ End-to-end, one `letsdo <name>` session:
    prepends the injected identity and hands the prompt to pi. The prompt is
    what chooses the task: `agents/analyst.md` and `agents/developer.md`
    instruct the agent to run
-   `backlog task list --assignee @<name> --exclude-status Done --sort priority --plain`
+   `backlog task list --assignee <name> --exclude-status Done --sort priority --plain`
    and take the first task, with the "already In Progress first" and "if
    blocked, take the blocker" exceptions.
 6. Retry state lives in `Letsdo::RetryPolicy` and is keyed on the **batch
@@ -81,8 +85,9 @@ batch is only a run counter. The order letsdo read does not govern the work.
 A deterministic selector needs these inputs, in this order:
 
 1. **Eligibility**
-   - assignee contains the agent's handle (`Config#assignee_handle`, default
-     `@<name>`); other agents' and `@human` tasks are never auto-run.
+   - assignee contains the agent's assignee (`Config#assignee_handle`,
+     default `<name>`, the canonical bare name); other agents' and `human`
+     tasks are never auto-run.
    - `status != Done`.
    - not in retry cooldown and not given up for this session
      (`RetryPolicy#cooldown?` / `#gave_up?`).
@@ -149,7 +154,7 @@ A deterministic selector needs these inputs, in this order:
   current batch drains. Acceptable for short runs; note it if runs get long.
 - **Race conditions.** Unassigned tasks are a coordination gap: two agents can
   pick the same task. The design's answer is assignment by a human
-  (`@developer`, `@analyst`, `@human`), not a lock. A lock/claim mechanism
+  (`developer`, `analyst`, `human`), not a lock. A lock/claim mechanism
   would require shared mutable state and belongs to scope C, not here.
 - **Retry interaction.** Any selector must compose with `RetryPolicy`: a task
   in cooldown or given up must not be re-offered, and the outcome must be

data/docs/usage.md

@@ -24,7 +24,8 @@ orchestrator loop semantics, and how to run several agents at once.
   (see the [configuration reference](config.md)).
 - The **Backlog.md CLI** (`backlog`) on `PATH` — the task provider reads the
   runnable open tasks assigned to an agent via
-  `backlog task list --assignee <handle> --ready --sort priority`. Override
+  `backlog task list --exclude-status Done --ready --sort priority` (the
+  assignee is matched on the returned tasks; the CLI line stays bare). Override
   with `LETSDO_BACKLOG_COMMAND`.
 
 Tests and the gem build use only Ruby's bundled default gems (Minitest,
@@ -84,7 +85,7 @@ letsdo developer --init           # writes agents/developer.md, never runs the a
 # Option 2: write agents/developer.md by hand
 # (see the prompt-authoring guide for what a good prompt contains)
 
-# Run the agent: it works through all open tasks assigned to @developer
+# Run the agent: it works through all open tasks assigned to developer
 letsdo developer
 ```
 
@@ -207,9 +208,9 @@ is what keeps CI and pipes deterministic.
 
 `letsdo <name>` runs an orchestrator loop:
 
-1. **Query** — fetch all open tasks assigned to `@<name>` via the backlog
-   CLI (the assignee handle comes from `AGENT_ASSIGNEE_HANDLE`, default
-   `@<name>`).
+1. **Query** — fetch all open tasks assigned to `<name>` via the backlog
+   CLI (the assignee comes from `AGENT_ASSIGNEE_HANDLE`, default `<name>`
+   — the canonical bare name; `@<name>` is prose notation only).
 2. **Run** — take the next task and run the agent on it. **One run = one
    task**; the agent must not pick up more than one task per run.
 3. **Repeat** — when a run finishes, query again.
@@ -234,11 +235,11 @@ queued task run.
 ## Running several agents
 
 Agents run as separate processes, each with its own loop and its own
-assignee handle:
+assignee:
 
 ```sh
-letsdo developer &   # works on @developer tasks
-letsdo analyst   &   # works on @analyst tasks
+letsdo developer &   # works on developer tasks
+letsdo analyst   &   # works on analyst tasks
 ```
 
 They coordinate through the shared backlog — nothing else in common. Any

data/lib/letsdo/agent.rb

@@ -22,16 +22,17 @@ module Letsdo
     #        vocabulary.
     # @param streamer [OutputStreamer] where to print output (by default
     #        the real stdout/stderr)
-    # @param handle [String, nil] the agent's backlog assignee handle
-    #        (Config#assignee_handle). Defaults to @<name>; the launcher
-    #        passes the resolved handle so the injected identity always
-    #        matches the handle the backlog tasks are assigned to.
+    # @param handle [String, nil] the agent's backlog assignee
+    #        (Config#assignee_handle). Defaults to the bare <name>
+    #        (TASK-96); the launcher passes the resolved assignee so the
+    #        injected identity always matches what the backlog tasks are
+    #        assigned to.
     def initialize(name:, root:, backend_factory:, streamer: nil, handle: nil)
       @name = name
       @root = root
       @backend_factory = backend_factory
       @streamer = streamer || OutputStreamer.new
-      @handle = handle || "@#{name}"
+      @handle = handle || name.to_s
     end
 
     # The backend of the last/current run -- lets the orchestrator

data/lib/letsdo/agent_identity.rb

@@ -3,27 +3,31 @@
 module Letsdo
   # The identity preamble letsdo injects into every agent's system prompt on
   # launch (TASK-85). The launcher already knows the agent name and its
-  # backlog assignee handle; the prompt template may not. Injecting the two
-  # facts unconditionally keeps every agent aware of who it is and which
-  # tasks are its own — independent of the template content, for the
-  # built-in default prompt and for every custom agents/<name>.md alike.
+  # backlog assignee; the prompt template may not. Injecting the two facts
+  # unconditionally keeps every agent aware of who it is and which tasks
+  # are its own — independent of the template content, for the built-in
+  # default prompt and for every custom agents/<name>.md alike.
   #
-  # The handle is Config#assignee_handle, so the identity an agent reads
-  # matches the handle its backlog tasks are assigned to.
+  # The assignee is Config#assignee_handle — the bare name (TASK-96); the
+  # '@' prefix is prose notation only, so the identity an agent reads both
+  # presents and instructs the bare tracker value.
   module AgentIdentity
     # The identity block prepended to a prompt. It ends with a blank line so
     # the original prompt keeps its own heading structure.
     #
     # @param name [String] agent name (also the backlog assignee name)
-    # @param handle [String] backlog assignee handle (Config#assignee_handle)
+    # @param handle [String] backlog assignee (Config#assignee_handle:
+    #        the bare name)
     # @return [String]
     def self.preamble(name:, handle:)
       <<~TEXT
         # Your identity
 
-        You are the agent `#{name}`. Your backlog assignee handle is `#{handle}`:
-        the tasks assigned to `#{handle}` are yours to work. Identify yourself
-        as this agent and use this handle in every tracked artifact you write.
+        You are the agent `#{name}`. Your backlog assignee is `#{handle}`:
+        the tasks assigned to `#{handle}` are yours to work. Identify
+        yourself as this agent and store `#{handle}` — the bare name, the
+        '@' prefix ('@#{handle}') is prose notation only — as the assignee
+        in every tracked artifact you write.
 
       TEXT
     end
@@ -33,7 +37,7 @@ module Letsdo
     #
     # @param prompt [String] the agent's system prompt (file or default)
     # @param name [String] agent name
-    # @param handle [String] backlog assignee handle
+    # @param handle [String] backlog assignee (bare name)
     # @return [String] prompt with the identity block at the very top
     def self.inject(prompt, name:, handle:)
       "#{preamble(name: name, handle: handle)}#{prompt}"

data/lib/letsdo/agent_loop/assignee_hints.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # Assignee mismatch reporting for AgentLoop (TASK-96).
+  #
+  # The provider matches the configured assignee after normalization
+  # (leading '@', whitespace, case), so legacy-stored values keep the loop
+  # running — but every exact-match consumer (backlog --assignee, the
+  # agent's own queries) misses them. This concern surfaces that deviation
+  # as a once-per-run stderr hint instead of letting it pass silently.
+  module AgentLoopAssigneeHints
+    private
+
+    # Warns once per run about assignees that matched only after
+    # normalization. Providers without #assignee_variants (plain lambdas
+    # in tests) are silently skipped.
+    def report_assignee_variants
+      variants = provider_assignee_variants
+      return if @variants_hinted || variants.empty?
+
+      @variants_hinted = true
+      quoted = variants.map { |value| "'#{value}'" }.join(', ')
+      @stderr.puts("letsdo: warning: tasks store assignee(s) #{quoted} instead of the handle " \
+                   "'#{@handle}' - matched after normalization; store '#{@handle}' on the tasks " \
+                   '(or set AGENT_ASSIGNEE_HANDLE) so exact-match filters find them')
+    end
+
+    def provider_assignee_variants
+      return [] unless @task_provider.respond_to?(:assignee_variants)
+
+      @task_provider.assignee_variants.to_a
+    end
+  end
+end

data/lib/letsdo/agent_loop/tasks.rb

@@ -15,6 +15,7 @@ module Letsdo
         tasks = @task_provider.call
         return provider_unavailable if tasks.nil?
 
+        report_assignee_variants
         reconcile_attempts(tasks)
         filtered = reject_cooled_down(tasks)
         @metrics&.provider_result(filtered.length)
@@ -31,7 +32,9 @@ module Letsdo
 
       debug("provider: #{tasks.length} open task(s)")
       @stderr.puts("letsdo: #{@name} has #{tasks.length} open task(s)")
-      report_backoff(raw - tasks.length) if raw && raw > tasks.length
+      return unless raw && raw > tasks.length
+
+      @stderr.puts("letsdo: #{raw - tasks.length} open task(s) in retry backoff")
     end
 
     def report_empty(raw)
@@ -45,12 +48,6 @@ module Letsdo
       end
     end
 
-    def report_backoff(skipped)
-      return unless skipped.positive?
-
-      @stderr.puts("letsdo: #{skipped} open task(s) in retry backoff")
-    end
-
     def provider_unavailable
       debug('provider: backlog unavailable')
       @stderr.puts(unavailable_message)

data/lib/letsdo/agent_loop.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 require_relative 'agent_loop/tasks'
+require_relative 'agent_loop/assignee_hints'
 
 module Letsdo
   # The orchestrator loop wired to the real environment for `letsdo <name>`.
   class AgentLoop
     include AgentLoopTasks
+    include AgentLoopAssigneeHints
 
     STOP = :letsdo_stop
     PAUSE_POLL_SECONDS = 0.05
@@ -73,6 +75,7 @@ module Letsdo
       @loop = build_loop
       install_signal_handlers
       @unavailable_hinted = false
+      @variants_hinted = false
     end
 
     def build_retry_policy(opts)

data/lib/letsdo/cli/builder_assembly.rb

@@ -108,8 +108,11 @@ module Letsdo
         handle = opts[:handle] || assignee_handle(name)
         agent = opts[:agent] || agent_for(name, streamer)
         provider = opts[:provider] || provider_for(handle)
+        # The provider object itself (not a wrapping lambda) reaches the loop
+        # so the once-per-run assignee mismatch hint can read its
+        # #assignee_variants (TASK-96).
         AgentLoop.new(name: name, handle: handle, agent: agent,
-                      task_provider: -> { provider.call },
+                      task_provider: provider,
                       wait_seconds: wait_seconds, sleeper: @sleeper, stderr: opts[:stderr],
                       metrics: opts[:metrics], pause_gate: opts[:pause_gate],
                       watcher: backlog_watcher, **retry_options)

data/lib/letsdo/config.rb

@@ -38,11 +38,22 @@ module Letsdo
       Shellwords.split(value)
     end
 
-    # The agent's backlog assignee handle. Default: @<name> (handle = name);
-    # a blank override also falls back to the derived handle.
+    # The agent's backlog assignee name. Default: the bare agent name —
+    # the tracker stores bare names ('developer'); the '@' prefix is
+    # prompt-only notation (TASK-96). AGENT_ASSIGNEE_HANDLE overrides for
+    # legacy setups (used verbatim; a @-prefixed value still matches after
+    # normalization in the provider, but `letsdo doctor` warns about it);
+    # a blank override also falls back to the derived bare name.
     def assignee_handle(name)
-      handle = @env['AGENT_ASSIGNEE_HANDLE']
-      handle && !handle.strip.empty? ? handle : "@#{name}"
+      assignee_handle_override || name.to_s
+    end
+
+    # Raw AGENT_ASSIGNEE_HANDLE (nil when unset or blank) — `letsdo
+    # doctor` uses it to warn about a legacy @-prefixed override instead
+    # of it silently missing every bare-named task.
+    def assignee_handle_override
+      value = @env['AGENT_ASSIGNEE_HANDLE']
+      value && !value.strip.empty? ? value : nil
     end
 
     # Retry interval when no tasks are open. LETSDO_WAIT_SECONDS wins, then
@@ -74,6 +85,14 @@ module Letsdo
       @env.fetch('PATH', '')
     end
 
+    # Environment for CLI child processes spawned outside the builder
+    # (the doctor's handle-less provider): the process environment
+    # overlaid with the injected env, so shebang PATH resolution and test
+    # scenario variables both keep working (TASK-96).
+    def child_env
+      ENV.to_h.merge(@env)
+    end
+
     # The task provider name. Reads LETSDO_PROVIDER with default 'backlog'.
     # An empty value falls back to 'backlog'.
     def provider

data/lib/letsdo/doctor/checks.rb

@@ -12,8 +12,8 @@ module Letsdo
       private
 
       def checks
-        [ruby_check, pi_check, backlog_check, root_check,
-         agents_md_check, agents_dir_check, tty_check]
+        [ruby_check, pi_check, backlog_check, assignee_check,
+         root_check, agents_md_check, agents_dir_check, tty_check]
       end
 
       # ruby >= 3.3 is the gemspec floor: below it letsdo still reports the
@@ -37,6 +37,52 @@ module Letsdo
         command_check('backlog', @config.backlog_command, 'LETSDO_BACKLOG_COMMAND')
       end
 
+      # Assignee-name convention (TASK-96): the tracker stores bare names
+      # ('developer'); '@' is prompt-only notation. The backlog CLI matches
+      # --assignee by exact string, so a legacy @-prefixed stored assignee
+      # (or handle override) is invisible to every exact-match query.
+      # letsdo still matches such tasks after normalization, but the
+      # deviation deserves a WARN so the data gets fixed. Uses a handle-less
+      # provider (no filtering) and reads the raw assignees; an unreadable
+      # backlog is reported as INFO because backlog_check already flags the
+      # cause.
+      def assignee_check
+        override = @config.assignee_handle_override
+        return warn_at_prefixed_override(override) if at_prefixed?(override)
+
+        tasks = provider_without_handle.call
+        return result('INFO', 'assignee names not checked - backlog task list failed') if tasks.nil?
+
+        warn_legacy_assignees(tasks)
+      end
+
+      # A handle-less provider sees every open task, so the check reads the
+      # raw stored assignees (no filtering, no variants recorded).
+      def provider_without_handle
+        Letsdo::Providers::Backlog.new(handle: nil, command: @config.backlog_command,
+                                       cwd: @config.root, env: @config.child_env)
+      end
+
+      def warn_legacy_assignees(tasks)
+        legacy = tasks.flat_map(&:assignees).select { |value| at_prefixed?(value) }.uniq.sort
+        return result('OK', 'assignee names are stored bare (canonical)') if legacy.empty?
+
+        quoted = legacy.map { |value| "'#{value}'" }.join(', ')
+        result('WARN', "tasks store legacy @-prefixed assignee(s): #{quoted}",
+               'reassign them to bare names: backlog task edit <ID> -a <name>')
+      end
+
+      def warn_at_prefixed_override(override)
+        result('WARN', "AGENT_ASSIGNEE_HANDLE '#{override}' carries the legacy '@' prefix",
+               "set it to the bare name: AGENT_ASSIGNEE_HANDLE=#{override.sub(/\A@+/, '')}")
+      end
+
+      # '@developer' is prose notation; the canonical tracker value is the
+      # bare name, so any leading '@' is a legacy deviation worth a WARN.
+      def at_prefixed?(value)
+        value.to_s.strip.start_with?('@')
+      end
+
       def command_check(label, command, env_var)
         return result('OK', "#{label} command found: #{command}") if command_available?(command)
 

data/lib/letsdo/providers/backlog.rb

@@ -8,8 +8,7 @@ module Letsdo
   module Providers
     # Task provider for Letsdo::Loop backed by the real backlog CLI:
     #
-    #   backlog task list --assignee <handle> --exclude-status Done \
-    #     --ready --sort priority --json
+    #   backlog task list --exclude-status Done --ready --sort priority --json
     #
     # Returns the runnable tasks assigned to the handle in the
     # authoritative run order (an Array of Letsdo::Providers::Task), or nil
@@ -17,6 +16,15 @@ module Letsdo
     # or its output is not the expected JSON. The loop treats nil as "pause
     # and retry, do not run the agent".
     #
+    # The assignee filter is applied in Ruby, not via the CLI's --assignee:
+    # the CLI matches the assignee by exact string, so a task stored as
+    # '@developer' (legacy notation) would never reach a '--assignee
+    # developer' query and the loop would silently starve (TASK-96). The
+    # handle match here tolerates the leading '@', surrounding whitespace
+    # and case, so both notations keep working; the literal values that
+    # matched only after normalization are exposed by #assignee_variants
+    # for the doctor WARN and the once-per-run loop hint.
+    #
     # The command runs in the project root (cwd), where the backlog CLI finds
     # the backlog/ folder — the same context as a single agent run.
     class Backlog
@@ -34,7 +42,10 @@ module Letsdo
       PRIORITY_RANKS = { 'high' => 0, 'medium' => 1, 'low' => 2 }.freeze
       UNKNOWN_RANK = PRIORITY_RANKS.size
 
-      # @param handle [String] assignee handle to filter by (e.g. "@developer")
+      # @param handle [String, nil] assignee name to filter by (canonical:
+      #        'developer'; a legacy '@developer' still matches the same
+      #        tasks); nil disables the filter (doctor inspects all open
+      #        tasks)
       # @param command [String] backlog CLI command (overridable for tests)
       # @param cwd [String, nil] project root for the CLI; nil = inherit cwd
       # @param env [Hash, nil] environment for the CLI child (nil = inherit
@@ -45,6 +56,16 @@ module Letsdo
         @command = command
         @cwd = cwd
         @env = env
+        @assignee_variants = []
+      end
+
+      # Literal assignee values from the last successful batch that matched
+      # the handle only after normalization (e.g. '@developer' for the
+      # handle 'developer') — the mismatch signature the doctor check and
+      # the loop hint surface. Empty when the handle matched exactly, no
+      # handle is configured, or the last call failed.
+      def assignee_variants
+        @assignee_variants.dup
       end
 
       # Reads the runnable open tasks once, in deterministic run order.
@@ -52,12 +73,15 @@ module Letsdo
       # @return [Array<Task>, nil] runnable open tasks; nil when the backlog is
       #         unreadable; empty array when there are no open tasks
       def call
+        @assignee_variants = []
         args = @env ? [@env, *command_line] : command_line
         out, _err, status = Letsdo::Capture.new(*args, chdir: @cwd).run
         return nil unless status.success?
 
         tasks = JSON.parse(out)['tasks']
-        tasks.is_a?(Array) ? sort(tasks.map { |raw| normalize(raw) }) : nil
+        return nil unless tasks.is_a?(Array)
+
+        sort(select_by_assignee(tasks.map { |raw| normalize(raw) }))
       rescue Errno::ENOENT, JSON::ParserError, TypeError
         nil
       end
@@ -77,6 +101,37 @@ module Letsdo
         end.map(&:first)
       end
 
+      # Assignee filtering happens here, not in the CLI's --assignee: the
+      # CLI matches by exact string (TASK-96). The stored value may be the
+      # bare canonical name or the legacy '@'-prefixed one — both match.
+      # A nil handle (doctor) keeps every task and never records variants.
+      def select_by_assignee(tasks)
+        return tasks unless @handle
+
+        selected = tasks.select { |task| match_assignees(task) }
+        @assignee_variants = @assignee_variants.uniq.sort
+        selected
+      end
+
+      def match_assignees(task)
+        task.assignees.any? do |value|
+          next false if normalize_assignee(value) != normalized_handle
+
+          @assignee_variants << value unless value == @handle
+          true
+        end
+      end
+
+      def normalized_handle
+        normalize_assignee(@handle)
+      end
+
+      # '@Dev', ' dev ' and 'dev' are the same handle; only the leading '@'
+      # is stripped, so '@dev team' stays distinct from 'devteam'.
+      def normalize_assignee(value)
+        value.to_s.strip.sub(/\A@/, '').downcase
+      end
+
       def in_progress_rank(task)
         task.status.to_s.casecmp('In Progress').zero? ? 0 : 1
       end
@@ -106,13 +161,14 @@ module Letsdo
         Task.new(**TASK_FIELDS.to_h { |field| [field.to_sym, raw[field]] })
       end
 
-      # [command..., task, list, --assignee <handle>, --exclude-status Done,
-      #  --ready, --sort priority, --json]
+      # [command..., task, list, --exclude-status Done, --ready,
+      #  --sort priority, --json] — no --assignee: the filter runs in Ruby
+      # (select_by_assignee), so exact-match deviations in the stored
+      # assignees cannot starve the loop (TASK-96).
       def command_line
         [
           *Shellwords.split(@command),
           'task', 'list',
-          '--assignee', @handle,
           '--exclude-status', 'Done',
           '--ready',
           '--sort', 'priority',

data/lib/letsdo/tui/metrics.rb

@@ -29,7 +29,9 @@ module Letsdo
                             :current_task, :current_task_seconds, keyword_init: true)
 
       # @param name [String] agent name (CLI argument)
-      # @param handle [String] assignee handle (e.g. "@developer")
+      # @param handle [String] assignee (the bare tracker name, e.g.
+      #        "developer"; the header renders it with the display-only
+      #        '@' prefix)
       # @param clock [Proc] monotonic clock, callable → seconds; injected
       #        in tests
       # @param on_run_start [Proc, nil] called with the task label when a

data/lib/letsdo/tui/renderer.rb

@@ -66,11 +66,19 @@ module Letsdo
       end
 
       def self.header_line(metrics, width)
-        title = "letsdo · #{metrics.name} (#{metrics.handle})"
+        title = "letsdo · #{metrics.name} (#{display_handle(metrics)})"
         timer = "session #{Text.format_duration(metrics.session_seconds)}"
         Text.fit_line_with_right(title, timer, width)
       end
 
+      # The header keeps the historical "name (@assignee)" look: the '@'
+      # is display notation only (TASK-96) — the tracker value is the bare
+      # name, and a legacy @-prefixed handle is shown as stored.
+      def self.display_handle(metrics)
+        handle = metrics.handle.to_s
+        handle.start_with?('@') ? handle : "@#{handle}"
+      end
+
       # The state line: done/left plus either the running task with its
       # elapsed time, a waiting reason, or the PAUSED overlay.
       def self.state_line(metrics, width, paused, wait_seconds)

data/lib/letsdo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Letsdo
-  VERSION = '0.6.0'
+  VERSION = '0.6.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: letsdo
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Sergei O. Udalov
@@ -104,6 +104,7 @@ files:
 - lib/letsdo/agent.rb
 - lib/letsdo/agent_identity.rb
 - lib/letsdo/agent_loop.rb
+- lib/letsdo/agent_loop/assignee_hints.rb
 - lib/letsdo/agent_loop/tasks.rb
 - lib/letsdo/backends/backend.rb
 - lib/letsdo/backends/pi.rb
@@ -171,7 +172,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.21
 specification_version: 4
 summary: A local agent worker for Backlog.md/markdown tasks
 test_files: []