letsdo 0.4.0 → 0.6.1

data/lib/letsdo/doctor/checks.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Letsdo
+  class Doctor
+    # The individual environment checks behind `letsdo doctor` (TASK-71).
+    # Every check returns { status:, message:, hint: } where the hint is
+    # mandatory for FAIL/WARN so the report is always actionable. Kept in its
+    # own module so Letsdo::Doctor stays within the class-length limit.
+    module DoctorChecks
+      MINIMUM_RUBY = '3.3'
+
+      private
+
+      def checks
+        [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
+      # problem as a WARN instead of a hard failure.
+      def ruby_check
+        return result('OK', "ruby #{RUBY_VERSION} (>= #{MINIMUM_RUBY})") if ruby_supported?
+
+        result('WARN', "ruby #{RUBY_VERSION} (< #{MINIMUM_RUBY})",
+               "upgrade Ruby to #{MINIMUM_RUBY} or newer")
+      end
+
+      def ruby_supported?
+        Gem::Version.new(RUBY_VERSION) >= Gem::Version.new(MINIMUM_RUBY)
+      end
+
+      def pi_check
+        command_check('pi', @config.pi_command, 'LETSDO_PI_COMMAND')
+      end
+
+      def backlog_check
+        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)
+
+        result('FAIL', "#{label} command not found: #{command}",
+               "install #{label} or set #{env_var}")
+      end
+
+      # An absolute or relative command path is checked directly; a bare name
+      # is resolved against the PATH exposed by Letsdo::Config.
+      def command_available?(command)
+        return File.executable?(command) if command.include?(File::SEPARATOR)
+
+        @config.path.split(File::PATH_SEPARATOR).any? do |dir|
+          File.executable?(File.join(dir, command))
+        end
+      end
+
+      def root_check
+        return result('OK', "project root #{@config.root} has backlog/tasks/") if backlog_tasks?
+
+        result('FAIL', "project root #{@config.root} has no backlog/tasks/",
+               'run `backlog init` or set LETSDO_ROOT to a Backlog.md project')
+      end
+
+      def backlog_tasks?
+        File.directory?(File.join(@config.root, 'backlog', 'tasks'))
+      end
+
+      def agents_md_check
+        path = File.join(@config.root, 'AGENTS.md')
+        return result('OK', "AGENTS.md present at #{path}") if File.file?(path)
+
+        result('WARN', "no AGENTS.md at #{path}",
+               'add AGENTS.md with the project instructions for agents')
+      end
+
+      def agents_dir_check
+        dir = File.join(@config.root, 'agents')
+        prompts = File.directory?(dir) ? Dir.children(dir).length : 0
+        return result('OK', "agents/ present with #{prompts} prompt(s)") if prompts.positive?
+
+        result('WARN', "agents/ missing or empty at #{dir}",
+               'create an agent prompt with `letsdo <name> --init`')
+      end
+
+      # TUI engages only when stdout is a TTY (plus stdin/TERM, checked at
+      # launch); an INFO line tells the user which mode a run would pick.
+      def tty_check
+        return result('INFO', 'stdout is a TTY - TUI mode') if @stdout.tty?
+
+        result('INFO', 'stdout is not a TTY - plain mode')
+      end
+
+      def result(status, message, hint = nil)
+        { status: status, message: message, hint: hint }
+      end
+    end
+  end
+end

data/lib/letsdo/doctor.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'doctor/checks'
+
+module Letsdo
+  # `letsdo doctor`: one line per environment check with a status tag and an
+  # actionable hint for every FAIL/WARN (TASK-71). Exits 0 when nothing
+  # FAILs and 1 otherwise, so it can gate scripts.
+  #
+  # Every input comes from Letsdo::Config (env policy) plus the injected
+  # streams, so the command is fully testable without touching process ENV.
+  class Doctor
+    include DoctorChecks
+
+    def initialize(config:, stdout:, stdin: $stdin)
+      @config = config
+      @stdout = stdout
+      @stdin = stdin
+    end
+
+    # Prints the report and returns the process exit code: 1 when at least
+    # one check FAILed, 0 otherwise.
+    def run
+      results = checks
+      results.each { |check| print_result(check) }
+      results.any? { |check| check[:status] == 'FAIL' } ? 1 : 0
+    end
+
+    private
+
+    def print_result(check)
+      line = "[#{tag(check[:status])}] #{check[:message]}"
+      line += " - #{check[:hint]}" if check[:hint]
+      @stdout.puts(line)
+    end
+
+    # All tags render six characters wide, so the columns line up.
+    def tag(status)
+      status == 'OK' ? ' OK ' : status
+    end
+  end
+end

data/lib/letsdo/duration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # Shared rendering of a duration in seconds as "4m 12s" / "12s" / "0s".
+  #
+  # The stop summary (TASK-69) and the opt-in per-task elapsed write-back
+  # (TASK-70) both use this one formatter, so the number a session reports
+  # and the number written into the task record can never drift apart.
+  module Duration
+    module_function
+
+    # @param seconds [Numeric] duration in seconds (negative values clamp to 0)
+    # @return [String] human-readable duration, e.g. "4m 12s"
+    def format(seconds)
+      total = [seconds.to_f, 0.0].max.round
+      minutes, secs = total.divmod(60)
+      return '0s' if minutes.zero? && secs.zero?
+      return "#{secs}s" if minutes.zero?
+
+      "#{minutes}m #{secs}s"
+    end
+  end
+end

data/lib/letsdo/errors.rb

@@ -9,4 +9,11 @@ module Letsdo
   # cleanly. Not a StandardError — nothing rescues it accidentally.
   class Stopped < StandardError
   end
+
+  # Raised when the AI backend process cannot be started (missing or
+  # non-executable binary). This is a configuration error, not a loop
+  # problem: the CLI catches it, prints a clear message and exits 2 instead
+  # of dying with a Ruby backtrace.
+  class BackendUnavailableError < Error
+  end
 end

data/lib/letsdo/metrics/fanout.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Letsdo
+  module Metrics
+    # A small fan-out facade that forwards the loop-driver events to a
+    # list of observers.  Used in TUI mode so the session recorder and
+    # the header metrics facade both receive the same callbacks from
+    # Letsdo::AgentLoop.
+    #
+    # Each observer must respond to provider_result, run_started and
+    # run_finished (the same interface Tui::Metrics and SessionRecorder
+    # implement).  The exit code is forwarded to every observer so the
+    # session recorder can classify outcomes; Tui::Metrics ignores it.
+    class Fanout
+      # @param observers [Array<Object>] each must implement the three
+      #        callback methods (provider_result, run_started, run_finished)
+      def initialize(*observers)
+        @observers = observers
+      end
+
+      # Forwards the provider open-task count to every observer.
+      #
+      # @param count [Integer, nil] number of open tasks; nil = the
+      #        backlog state is unreadable
+      # @return [void]
+      def provider_result(count)
+        @observers.each { |observer| observer.provider_result(count) }
+      end
+
+      # Forwards a run-started event (task label) to every observer.
+      #
+      # @param task [String] task label
+      # @return [void]
+      def run_started(task)
+        @observers.each { |observer| observer.run_started(task) }
+      end
+
+      # Forwards a run-finished event (exit code) to every observer.
+      #
+      # @param exit_code [Integer, nil] the run exit code
+      # @return [void]
+      def run_finished(exit_code = nil)
+        @observers.each { |observer| observer.run_finished(exit_code) }
+      end
+    end
+  end
+end

data/lib/letsdo/prompt_store.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'fileutils'
+require 'yaml'
 
 module Letsdo
   # Access to agent prompts: the agents/<name>.md directory in the project
@@ -40,7 +41,22 @@ module Letsdo
       path = agent_path(name)
       return nil unless File.file?(path)
 
-      File.read(path)
+      content = File.read(path)
+      self.class.strip_front_matter(content)
+    end
+
+    # Parsed launch configuration for an agent.
+    #
+    # Returns a hash with symbolised keys. An empty hash when the file
+    # is missing or has no YAML front matter.
+    #
+    # @param name [String] agent name
+    # @return [Hash{Symbol => Object}]
+    def config(name)
+      path = agent_path(name)
+      return {} unless File.file?(path)
+
+      self.class.parse_front_matter(File.read(path))
     end
 
     # Absolute path of an agent's prompt file, whether or not it exists.
@@ -69,6 +85,37 @@ module Letsdo
       true
     end
 
+    # Strips an optional YAML front matter block delimited by `---` at
+    # the very start of a prompt file. Returns the remaining content.
+    #
+    # @param content [String] full file content
+    # @return [String] content without front matter
+    def self.strip_front_matter(content)
+      content.sub(/\A---\n.+?\n---\n?/m, '')
+    end
+
+    FRONT_MATTER = /\A---\n?\n(.+?)\n?\n---\n?\n/m
+
+    # Parses an optional YAML front matter block delimited by `---` at
+    # the very start of a prompt file. Returns the keys symbolised;
+    # returns an empty hash when there is no front matter or it is
+    # invalid.
+    #
+    # @param content [String] full file content
+    # @return [Hash{Symbol => Object}]
+    def self.parse_front_matter(content)
+      match = content.match(FRONT_MATTER)
+      return {} unless match
+
+      symbolize_keys(YAML.safe_load(match[1], permitted_classes: []))
+    rescue StandardError
+      {}
+    end
+
+    def self.symbolize_keys(parsed)
+      parsed.is_a?(Hash) ? parsed.transform_keys(&:to_sym) : {}
+    end
+
     private
 
     def agents_dir

data/lib/letsdo/providers/backlog.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'shellwords'
+require_relative 'task'
+
+module Letsdo
+  module Providers
+    # Task provider for Letsdo::Loop backed by the real backlog CLI:
+    #
+    #   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
+    # when the backlog state is unreadable — the CLI is not on PATH, failed,
+    # 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
+      # Keys of the normalized Letsdo::Providers::Task shape. The backlog CLI
+      # emits more (reporter, parentTaskId, createdAt, updatedAt); the adapter
+      # projects onto these and ignores the rest so a growing CLI schema
+      # cannot crash the loop. Beyond the identity fields, the shape keeps
+      # what deterministic selection needs: ordinal (the stable tie-break) and
+      # type/labels/milestone (optional capability routing).
+      TASK_FIELDS = %w[id title status priority assignees ordinal type labels milestone].freeze
+
+      # Sort ranks for the deterministic batch order. Known priorities are
+      # compared case-insensitively; anything else (nil or a new label) ranks
+      # last instead of crashing the comparator.
+      PRIORITY_RANKS = { 'high' => 0, 'medium' => 1, 'low' => 2 }.freeze
+      UNKNOWN_RANK = PRIORITY_RANKS.size
+
+      # @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
+      #        the process environment; injected in tests to control the
+      #        fake backlog scenarios)
+      def initialize(handle:, command: 'backlog', cwd: nil, env: nil)
+        @handle = handle
+        @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.
+      #
+      # @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']
+        return nil unless tasks.is_a?(Array)
+
+        sort(select_by_assignee(tasks.map { |raw| normalize(raw) }))
+      rescue Errno::ENOENT, JSON::ParserError, TypeError
+        nil
+      end
+
+      private
+
+      # Deterministic run order: In Progress first (resume before starting),
+      # then priority High > Medium > Low, then ordinal ascending, then id
+      # ascending. The CLI's --sort priority does not put In Progress first
+      # and cannot express the full tie-break, so the adapter sorts the batch
+      # itself. The original index is the final tie-break, so equal keys keep
+      # the provider's (deterministic) order.
+      def sort(tasks)
+        tasks.each_with_index.sort_by do |task, index|
+          [in_progress_rank(task), priority_rank(task.priority),
+           ordinal_rank(task.ordinal), id_rank(task.id), index]
+        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
+
+      def priority_rank(priority)
+        PRIORITY_RANKS[priority.to_s.downcase] || UNKNOWN_RANK
+      end
+
+      # Unknown/nil ordinals sort last (their id still orders them).
+      def ordinal_rank(ordinal)
+        value = Integer(ordinal, exception: false)
+        value.nil? ? [1, 0] : [0, value]
+      end
+
+      # An absent id (malformed task) sorts after identified ones.
+      def id_rank(id)
+        [id.to_s.empty? ? 1 : 0, id.to_s]
+      end
+
+      # Projects one raw CLI task onto the normalized shape. Unknown keys are
+      # ignored (the CLI schema grows over time); a non-Hash entry means the
+      # payload is not the expected schema and raises TypeError, which #call
+      # turns into nil.
+      def normalize(raw)
+        raise TypeError, "task is not an object: #{raw.class}" unless raw.is_a?(Hash)
+
+        Task.new(**TASK_FIELDS.to_h { |field| [field.to_sym, raw[field]] })
+      end
+
+      # [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',
+          '--exclude-status', 'Done',
+          '--ready',
+          '--sort', 'priority',
+          '--json'
+        ]
+      end
+    end
+  end
+end

data/lib/letsdo/providers/task.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Letsdo
+  module Providers
+    # Immutable value object representing a normalized task.
+    #
+    # Adapters map tracker-specific JSON onto this shape. Business logic
+    # consumes only this interface, not the raw tracker schema.
+    #
+    # The constructor is strict on purpose: adapters project the tracker
+    # payload onto these keywords instead of forwarding it, so extra tracker
+    # fields never reach here and a wrong key is caught as a programming
+    # error instead of silently ignored.
+    #
+    # Besides the identity/routing fields, the shape carries the fields a
+    # deterministic selector needs: +ordinal+ (the stable tie-break), and
+    # +type+/+labels+/+milestone+ for optional capability routing.
+    class Task
+      attr_reader :id, :title, :status, :priority, :assignees,
+                  :ordinal, :type, :labels, :milestone
+
+      # rubocop:disable Metrics/ParameterLists -- the keywords are the
+      # normalized shape's explicit contract; adapters project tracker
+      # payloads onto exactly these and the strict list rejects a typo.
+      def initialize(id:, title: nil, status: nil, priority: nil, assignees: [],
+                     ordinal: nil, type: nil, labels: [], milestone: nil)
+        @id = id
+        @title = title
+        @status = status
+        @priority = priority
+        @assignees = Array(assignees)
+        @ordinal = ordinal
+        @type = type
+        @labels = Array(labels)
+        @milestone = milestone
+        freeze
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def to_s
+        identifier = id.to_s
+        return identifier unless identifier.empty?
+
+        title.to_s
+      end
+    end
+  end
+end

data/lib/letsdo/retry_policy.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # Pure policy object for per-task retry, exponential backoff and give-up.
+  #
+  # Letsdo::Loop stays generic and untouched; this object is wired at the
+  # AgentLoop level. The loop filters attempt batches through #cooldown? and
+  # records outcomes with #record_failure / #record_success.
+  #
+  # State is per-task (keyed by task id) and in-memory only: a fresh letsdo
+  # session starts with zero failures, so a broken task yields instead of
+  # hammering, and a temporarily-failing task is retried next session.
+  #
+  # The clock is injectable (monotonic, as in Tui::Metrics) for
+  # deterministic tests.
+  class RetryPolicy
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_CAP = 300.0
+    DEFAULT_BASE = 10.0
+
+    # Tunables exposed for the reconciliation logic (give-up checks).
+    attr_reader :max_retries
+
+    # @param base [Float] base backoff seconds; default wait_seconds (10.0)
+    # @param cap [Float] maximum backoff seconds (default 300)
+    # @param max_retries [Integer] give-up after N consecutive failures
+    # @param clock [Proc] callable → monotonic epoch seconds
+    def initialize(base: nil, cap: nil, max_retries: nil, clock: nil)
+      @base = base || DEFAULT_BASE
+      @cap = cap || DEFAULT_CAP
+      @max_retries = max_retries || DEFAULT_MAX_RETRIES
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @state = {}
+    end
+
+    # Consecutive failures recorded for task_key (0 when none).
+    def failures(task_key)
+      info = @state[task_key]
+      info ? info[:failures] : 0
+    end
+
+    # Records a failed run: bumps the failure count and (re)arms the cooldown
+    # deadline for exponential backoff.
+    def record_failure(task_key)
+      info = (@state[task_key] ||= { failures: 0, cool_until: 0 })
+      info[:failures] += 1
+      info[:cool_until] = cooldown_deadline(info[:failures])
+      info
+    end
+
+    # Records a successful run: clears the per-task retry state.
+    def record_success(task_key)
+      @state.delete(task_key)
+    end
+
+    # Clears all per-task retry state (fresh session).
+    def reset
+      @state.clear
+    end
+
+    # Whether the task is cooling down and must be excluded from attempt
+    # batches. Tasks skipped by cooldown are NOT re-recorded as failed.
+    def cooldown?(task_key, now = nil)
+      info = @state[task_key]
+      return false unless info
+
+      cool_until(info) > current_time(now)
+    end
+
+    # Whether the task has hit the give-up limit: it must not be attempted
+    # again for the rest of the session.
+    def gave_up?(task_key)
+      failures(task_key) >= @max_retries
+    end
+
+    # Earliest cooldown deadline across all tasks (for a bounded wait); nil
+    # when nothing is cooling down.
+    def earliest_cooldown(now = nil)
+      current = current_time(now)
+      deadlines = @state.values.map { |info| info[:cool_until] }.select { |d| d > current }
+      deadlines.empty? ? nil : deadlines.min
+    end
+
+    private
+
+    def current_time(now)
+      now.nil? ? @clock.call : now
+    end
+
+    def cooldown_deadline(failure_count)
+      @clock.call + [@base * (2**(failure_count - 1)), @cap].min
+    end
+
+    def cool_until(info)
+      info[:cool_until]
+    end
+  end
+end