letsdo 0.3.0 → 0.6.1

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

data/lib/letsdo/session_recorder/jsonl_writer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module Letsdo
+  class SessionRecorder
+    # Writes the optional JSON Lines metrics stream for a session recorder:
+    # a session_start line on construction, one run_finished line per closed
+    # run and a session_stop line at the end. With a nil IO the writer is a
+    # no-op, so callers need no nil checks.
+    class JsonlWriter
+      # @param io [IO, nil] append-only target; nil disables the writer
+      # @param name [String] agent name
+      # @param handle [String] assignee handle
+      # @param wall_clock [Proc] -> ISO8601 UTC timestamp string
+      def initialize(io, name:, handle:, wall_clock:)
+        @io = io
+        @name = name
+        @handle = handle
+        @wall_clock = wall_clock
+        session_start if enabled?
+      end
+
+      # @return [Boolean] whether an output target is configured
+      def enabled?
+        !@io.nil?
+      end
+
+      # Writes the opening session_start line (no-op when disabled).
+      #
+      # @return [void]
+      def session_start
+        write(session_start_payload)
+      end
+
+      # @param run [SessionRecorder::Run] a closed run record
+      # @return [void]
+      def run_finished(run)
+        write(
+          'event' => 'run_finished', 'task' => run.task_id, 'exit' => run.exit_code,
+          'outcome' => run.outcome.to_s, 'elapsed_s' => run.elapsed_s,
+          'ts' => @wall_clock.call
+        )
+      end
+
+      # @param summary [SessionRecorder::Summary] the final aggregate
+      # @return [void]
+      def session_stop(summary)
+        write(
+          'event' => 'session_stop', 'agent' => @name, 'handle' => @handle,
+          'ts' => @wall_clock.call, 'done' => summary.done, 'failed' => summary.failed,
+          'interrupted' => summary.interrupted, 'left' => summary.left,
+          'session_s' => summary.session_s, 'runs_s' => summary.active_s
+        )
+      end
+
+      private
+
+      def session_start_payload
+        { 'event' => 'session_start', 'agent' => @name, 'handle' => @handle,
+          'ts' => @wall_clock.call }
+      end
+
+      def write(payload)
+        return unless enabled?
+
+        @io.puts(JSON.generate(payload))
+        @io.flush if @io.respond_to?(:flush)
+      end
+    end
+  end
+end