agentilda 1.0.3

data/lib/agentilda/adoption.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # Gives a plan folder to every pull request that has no plan to point at.
+  #
+  # `resync prs` can resolve most pull requests from their branch or their
+  # diff. What it cannot resolve it used to flag for a human — "diff touches
+  # 021.00, 022.00, 024.00 and none is obviously primary" — and stop. That is
+  # honest but not useful: the work exists, it is unspecified, and leaving it
+  # unnumbered means it never appears in the index at all.
+  #
+  # So an orphan is adopted instead. It gets a retroactive plan of its own,
+  # numbered in the gap after the furthest plan it can see, holding the pull
+  # request that produced it.
+  #
+  # == Why the numbering is allocated serially
+  #
+  # The obvious parallel design — every worker reads the highest number and
+  # adds `.01` — is deterministic but not unique, and the collision is the
+  # common case rather than the rare one. Fifteen open pull requests branched
+  # off the same main all see the same highest number and all compute the same
+  # slot. Determinism is not the property that matters here; distinctness is.
+  #
+  # So the pipeline is **gather in parallel, allocate serially, apply in
+  # parallel**. The allocation is pure arithmetic over an array that is
+  # already in memory, so the serial section costs microseconds; the two
+  # expensive phases — reading each branch and writing each folder — keep the
+  # whole fan-out. And because the slots are handed out before any worker
+  # starts, no worker can want a number another worker holds: no locks, no
+  # retries, and the same input produces the same numbers every run.
+  class Adoption
+    # One pull request and the plan it is being given.
+    #
+    # @!attribute [r] pull
+    #   @return [Hash] as returned by {GitHub#pulls}
+    # @!attribute [r] ordinal
+    #   @return [Agentilda::Ordinal] the slot it was allocated
+    # @!attribute [r] major
+    #   @return [Integer] the furthest plan its branch or diff could see
+    # @!attribute [r] path
+    #   @return [String, nil] the folder, once created
+    Adoptee = Data.define(:pull, :ordinal, :major, :path) do
+      # @return [String] the folder name this pull request earns
+      def dirname = Agentilda.plan_dirname(ordinal, STATUS_BY_KEY.fetch(:retroactive), slug)
+
+      # The PR title, stripped of any prefix, as the folder's tail.
+      #
+      # @return [String]
+      def slug = Creator.slugify(pull[:title].to_s.sub(/\A\[[^\]]+\](?:\([A-Z]\))?\s*/, ""))
+
+      # @return [String] a single auditable line
+      def to_s = "##{pull[:number]} → #{dirname}"
+    end
+
+    # @param tree [Agentilda::Tree]
+    # @param github [Agentilda::GitHub]
+    # @param root [String] repository root, for reading branches
+    # @param jobs [Integer] workers for the two parallel phases
+    def initialize(tree:, github: GitHub.new, root: nil, jobs: UI.default_jobs)
+      @tree = tree
+      @github = github
+      @root = root || File.dirname(tree.dir)
+      @jobs = jobs
+    end
+
+    # @return [Agentilda::Tree]
+    attr_reader :tree
+
+    # @return [Agentilda::GitHub]
+    attr_reader :github
+
+    # @return [String]
+    attr_reader :root
+
+    # @return [Integer]
+    attr_reader :jobs
+
+    # Work out what each orphan would be given, without creating anything.
+    #
+    # @param pulls [Array<Hash>] the orphans, from {Resync::Prs}
+    # @return [Array<Agentilda::Adoption::Adoptee>] in pull request order
+    def plan(pulls)
+      allocate(gather(pulls))
+    end
+
+    # Adopt every orphan: create its folder and record its pull request.
+    #
+    # @param pulls [Array<Hash>]
+    # @return [Array<Agentilda::Adoption::Adoptee>] with `path` filled in
+    def call(pulls)
+      adoptees = plan(pulls)
+      return adoptees if adoptees.empty?
+
+      created = Parallel.map(adoptees, in_threads: jobs) { |adoptee| adopt(adoptee) }
+      tree.reload
+      created
+    end
+
+    private
+
+    # Phase one, in parallel: ask each pull request's branch how far the
+    # sequence had got when the work started. Branches are not all rebased
+    # onto the same main, so this is per-branch rather than tree-wide, and it
+    # is a network-free `ls-tree` per pull request.
+    #
+    # @param pulls [Array<Hash>]
+    # @return [Array<Array(Hash, Integer)>] each pull with its major
+    def gather(pulls)
+      ordered = pulls.sort_by { |pull| pull[:number].to_i }
+
+      Parallel.map(ordered, in_threads: jobs) { |pull| [pull, major_for(pull)] }
+    end
+
+    # The furthest whole plan this pull request can see: on its own branch
+    # first, then whatever it touched, then the tree we are standing in. A
+    # pull request whose branch is long gone still has a diff.
+    #
+    # @param pull [Hash]
+    # @return [Integer]
+    def major_for(pull)
+      candidates = Agentilda.plans_on_ref(root, pull[:branch].to_s)
+      candidates = touched(pull) if candidates.empty?
+      candidates = tree.subjects.map { |s| s.feature.ordinal } if candidates.empty?
+
+      candidates.map(&:major).max.to_i
+    end
+
+    # @param pull [Hash]
+    # @return [Array<Agentilda::Ordinal>]
+    def touched(pull)
+      Array(pull[:files]).filter_map { |path|
+        parts = path.to_s.split("/")
+        index = parts.index(Agentilda::PLANS_DIR)
+        index && parts[index + 1] && Ordinal.from_dirname(parts[index + 1])
+      }.uniq
+    end
+
+    # Phase two, serial and deliberately so. Minors are handed out per major,
+    # continuing past every slot the tree already holds, in ascending pull
+    # request order — so the numbers follow the order the work was opened in,
+    # and two pull requests cannot be given the same one.
+    #
+    # @param gathered [Array<Array(Hash, Integer)>]
+    # @return [Array<Agentilda::Adoption::Adoptee>]
+    def allocate(gathered)
+      taken = Hash.new { |h, major| h[major] = minors_taken(major) }
+
+      gathered.filter_map do |pull, major|
+        minor = ((taken[major].max || 0) + 1)
+        next if minor > Ordinal::MAX_MINOR
+
+        taken[major] << minor
+        Adoptee.new(pull:, major:, ordinal: Ordinal.new(major:, minor:), path: nil)
+      end
+    end
+
+    # @param major [Integer]
+    # @return [Array<Integer>] minors already used under this major
+    def minors_taken(major)
+      tree.subjects.map { |s| s.feature.ordinal }.select { |o| o.major == major }.map(&:minor)
+    end
+
+    # Phase three, in parallel: each worker owns a number nobody else can
+    # want, so it can create its folder without coordinating with anyone.
+    #
+    # @param adoptee [Agentilda::Adoption::Adoptee]
+    # @return [Agentilda::Adoption::Adoptee]
+    def adopt(adoptee)
+      path = File.join(tree.dir, adoptee.dirname)
+      return adoptee if File.exist?(path)
+
+      FileUtils.mkdir_p(path)
+      File.write(File.join(path, PullRequests::FILENAME),
+        PullRequests.render([pull_request_for(adoptee)]))
+
+      adoptee.with(path:)
+    end
+
+    # The body is what a specification would be written from, so it is worth
+    # a second request. A failure here costs the description, not the folder.
+    #
+    # @param adoptee [Agentilda::Adoption::Adoptee]
+    # @return [Hash]
+    def pull_request_for(adoptee)
+      pull = adoptee.pull
+      github.pull_request(pull[:number].to_s)
+    rescue Agentilda::Error
+      {number: pull[:number], title: pull[:title], url: pull[:url],
+       state: pull[:state] || "Unknown", body: ""}
+    end
+  end
+end

data/lib/agentilda/agent.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # One specialist, loaded from `~/.agents/agents/<name>.md`.
+  #
+  # The definition files are the single source of truth for who does what: the
+  # frontmatter says which plan states this agent handles and what it may write,
+  # and the body is the prompt. Nothing about a specialty is duplicated in Ruby.
+  #
+  # @!attribute [r] name
+  #   @return [String]
+  # @!attribute [r] description
+  #   @return [String]
+  # @!attribute [r] handles
+  #   @return [Array<Symbol>] plan states this agent is offered work from
+  # @!attribute [r] advances_to
+  #   @return [Symbol, nil] the state it is expected to reach; nil = read-only
+  # @!attribute [r] model
+  #   @return [String, nil]
+  # @!attribute [r] allowed_tools
+  #   @return [Array<String>]
+  # @!attribute [r] may
+  #   @return [Array<String>] commands lifted from {Executor::FORBIDDEN_COMMANDS}
+  #     for this agent alone. Nothing in {Executor::UNGRANTABLE} can be lifted.
+  # @!attribute [r] timeout
+  #   @return [Integer, nil] seconds before this agent is abandoned; nil
+  #     defers to the executor's run-wide default
+  Agent = Data.define(:name, :description, :handles, :advances_to, :model,
+    :allowed_tools, :may, :network, :timeout, :prompt, :path) do
+    # @return [Boolean] whether this agent changes anything on disk
+    def read_only? = advances_to.nil?
+
+    # @param status [Agentilda::Status]
+    # @return [Boolean]
+    def handles?(status) = handles.include?(status.key)
+  end
+
+  # Loads and indexes the agent definitions.
+  class Agents
+    # Where definitions live, unless told otherwise.
+    DEFAULT_DIR = File.expand_path("../../agents", __dir__)
+
+    # @param dir [String]
+    # @param roster [Array<Agentilda::Agent>, nil] a pre-selected list, used
+    #   by {#only} and {#without} to derive a narrower roster; nil (the
+    #   default) loads every definition in `dir`
+    def initialize(dir: DEFAULT_DIR, roster: nil)
+      @dir = File.expand_path(dir)
+      @all = roster
+    end
+
+    # @return [String]
+    attr_reader :dir
+
+    # @return [Array<Agentilda::Agent>] in name order
+    def all
+      @all ||= Dir.glob(File.join(dir, "*.md")).sort.filter_map { |path| parse(path) }
+    end
+
+    # @param name [String]
+    # @return [Agentilda::Agent, nil]
+    def find(name) = all.find { |a| a.name == name.to_s }
+
+    # A roster holding only the agents named — what `run --agent` hands the
+    # loop, so a restriction typed at the command line restricts assignments
+    # and not merely chaining.
+    #
+    # @param names [Array<String>]
+    # @return [Agentilda::Agents]
+    def only(*names)
+      wanted = names.flatten.map(&:to_s)
+      self.class.new(dir:, roster: all.select { |a| wanted.include?(a.name) })
+    end
+
+    # A roster without the agents named — what `run --skip` hands the loop.
+    # A plan sitting in a skipped agent's state is simply never assigned, the
+    # same way a state no agent handles is stepped around.
+    #
+    # @param names [Array<String>]
+    # @return [Agentilda::Agents]
+    def without(*names)
+      unwanted = names.flatten.map(&:to_s)
+      self.class.new(dir:, roster: all.reject { |a| unwanted.include?(a.name) })
+    end
+
+    # Every agent the query could mean. An exact name wins outright; failing
+    # that the query matches as a prefix, and failing that anywhere in the
+    # name, so `leah` finds leah-researcher and `review` finds
+    # hansolo-reviewer. A directory or a trailing `.md` is stripped first,
+    # because tab completion hands those in.
+    #
+    # @param query [String]
+    # @return [Array<Agentilda::Agent>]
+    def match(query)
+      wanted = File.basename(query.to_s, ".md")
+      exact = all.select { |a| a.name == wanted }
+      return exact unless exact.empty?
+
+      prefixed = all.select { |a| a.name.start_with?(wanted) }
+      return prefixed unless prefixed.empty?
+
+      all.select { |a| a.name.include?(wanted) }
+    end
+
+    # Every agent that will act on a plan in this state, in definition order.
+    # A read-only agent is never offered work by the loop — it has nothing to
+    # advance, so including it would make every round look productive.
+    #
+    # @param status [Agentilda::Status]
+    # @return [Array<Agentilda::Agent>]
+    def for_status(status) = all.select { |a| a.handles?(status) && !a.read_only? }
+
+    private
+
+    # @param path [String]
+    # @return [Agentilda::Agent, nil]
+    def parse(path)
+      meta, body = Frontmatter.split(File.read(path, encoding: "UTF-8"))
+      return nil if meta["name"].to_s.empty?
+
+      Agent.new(
+        name: meta["name"].to_s,
+        description: meta["description"].to_s,
+        handles: Array(meta["handles"]).map { |s| s.to_s.to_sym },
+        advances_to: meta["advances_to"]&.to_s&.then { |s| s.empty? ? nil : s.to_sym },
+        model: meta["model"],
+        allowed_tools: Array(meta["allowed_tools"]).map(&:to_s),
+        may: Array(meta["may"]).map { |c| c.to_s.strip.squeeze(" ") },
+        network: meta["network"] == true,
+        timeout: meta["timeout"].to_i.then { |s| s.positive? ? s : nil },
+        prompt: body.strip,
+        path: path
+      )
+    end
+  end
+end

data/lib/agentilda/brief.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # A new plan's opening brief: four questions, and a best-effort first pass
+  # at answering them from what the project already has on disk.
+  #
+  # This is for work that does not exist yet. A plan created `--after` a
+  # shipped pull request already has its facts — {CLI::Create} hands those to
+  # `yoda-writer`, which reconstructs a specification from a diff, not this.
+  # Guessing at a diff and guessing at a feature nobody has built are
+  # different jobs, and conflating them is how a retroactive spec ends up
+  # full of hedges about something that already, provably, happened.
+  #
+  # The four headings are the brief `leah-researcher` and `yoda-writer` both
+  # read *before* their own chapters: what research needs to settle is a
+  # question about the gaps in `## What already exists`, so a scaffold
+  # missing that heading forces both of them to first reconstruct a boundary
+  # this class already had for free — it just created the folder.
+  class Brief
+    # The half-agent's name. It has no `agents/*.md` of its own on purpose —
+    # a roster entry would put it in `Runner`'s routing, and this pass runs
+    # only inside `create`. The name exists so the UI can show it the same
+    # way it shows `leah-researcher` and `yoda-writer` on their spinner lines.
+    AGENT_NAME = "anakin-briefster"
+
+    HEADINGS = [
+      "What we are trying to achieve",
+      "Why it matters",
+      "What already exists",
+      "What research needs to settle"
+    ].freeze
+
+    # Read whole into the drafting prompt, in order, so the model sees the
+    # project's own account of itself before it sees the topic.
+    CONTEXT_FILES = %w[CLAUDE.md AGENTS.md README.md].freeze
+
+    # Relative to the repository root. Not every project keeps one — a
+    # missing backlog is silently skipped, not an error.
+    BACKLOG_FILE = File.join(Agentilda::PLANS_DIR, "BACKLOG.md")
+
+    # Long enough for a handful of Read/Grep/Glob calls over a local
+    # checkout; short enough that a hung `claude` does not stall `create`
+    # past the point where the scaffold is already there to open by hand.
+    TIMEOUT = 60
+
+    # The fastest model, and the draft is disposable: the prompt prefers an
+    # honest blank over a clever inference, so there is no reasoning premium
+    # worth paying a larger model for inside a 60-second budget.
+    BRIEF_MODEL = "haiku"
+
+    # Read-only, and no `Bash` — this pass surveys what the repository
+    # already says about itself, it does not go looking further. That is
+    # `leah-researcher`'s job, and denying her tools here is what keeps the
+    # two from quietly doing the same work twice.
+    ALLOWED_TOOLS = %w[Read Grep Glob Edit].freeze
+    DENIED_TOOLS = %w[WebFetch WebSearch Bash].freeze
+
+    # @param path [String] the new plan folder, absolute
+    # @param title [String] the feature's proper name, e.g. "Tax Rule DSL"
+    # @param root [String] repository root, for project context and `--add-dir`
+    # @param command [TTY::Command]
+    # @param timeout [Integer] seconds before the drafting attempt is abandoned
+    # @param dry_run [Boolean] plan the invocation, do not run it
+    # @param seed [String, nil] what the author already wrote about the
+    #   feature (`create --from`); opens spec.md and outranks the repo survey
+    def initialize(
+      path:,
+      title:,
+      root:,
+      command: TTY::Command.new(printer: :null),
+      timeout: TIMEOUT,
+      dry_run: false,
+      seed: nil
+    )
+      @path = path
+      @title = title
+      @root = File.expand_path(root)
+      @command = command
+      @timeout = timeout
+      @dry_run = dry_run
+      @seed = seed.to_s.strip.then { |s| s.empty? ? nil : s }
+    end
+
+    # @return [String]
+    attr_reader :path, :title, :root
+
+    # @return [String, nil]
+    attr_reader :seed
+
+    # @return [String] absolute path to the spec, whether or not it exists yet
+    def spec_path = File.join(path, "spec.md")
+
+    # The title and four empty headings — and, when `create --from` supplied
+    # one, the author's own prose between them, so the file already says
+    # something even if the drafting attempt never returns.
+    #
+    # @return [String]
+    def scaffold
+      opening = seed ? "#{seed}\n\n" : ""
+      "# #{title}\n\n#{opening}" + HEADINGS.map { |h| "## #{h}\n\n" }.join("\n")
+    end
+
+    # @return [String] where it was written
+    def write_scaffold!
+      File.write(spec_path, scaffold)
+      spec_path
+    end
+
+    # Make a best-effort attempt at the four headings, in place, by shelling
+    # out to `claude` the same way {Executor} does for a specialist agent.
+    # A failure here is not this method's to hide: the scaffold {#write_scaffold!}
+    # already wrote stands on its own, so the caller reports the failure and
+    # moves on rather than treating it as fatal to `create`.
+    #
+    # @return [Array(Boolean, String)] ok, and a one-line note
+    def attempt!
+      return [true, "dry run — would draft from project context"] if @dry_run
+
+      begin
+        @command.run(*invocation, timeout: @timeout)
+      rescue TTY::Command::TimeoutExceeded
+        return [false, "timed out after #{@timeout}s"]
+      rescue TTY::Command::ExitError => e
+        return [false, "claude #{Executor.failure_reason(e)}"]
+      end
+
+      [true, "drafted"]
+    end
+
+    # Exposed so a spec can assert the boundary without running anything.
+    #
+    # @return [Array<String>]
+    def invocation
+      ["claude",
+        "-p", prompt, "--add-dir", root,
+        "--model", BRIEF_MODEL,
+        "--allowedTools", ALLOWED_TOOLS.join(","),
+        "--disallowedTools", DENIED_TOOLS.join(",")]
+    end
+
+    private
+
+    # @return [String]
+    def prompt
+      <<~PROMPT
+        #{author_statement}A new plan folder was just created for a feature that does not exist
+        yet: "#{title}".
+
+        #{spec_path} holds a title and four empty headings:
+
+        #{HEADINGS.map { |h| "  * #{h}" }.join("\n")}
+
+        Make a best-effort first pass at each, drawn only from what THIS
+        project already has on disk under #{root} — its own docs, its own
+        conventions, code already built, and anything already downloaded or
+        gathered that bears on "#{title}". Read/Grep/Glob freely to look for
+        it; do not invent facts and do not research the web. Where the
+        repository gives you nothing to go on, leave that heading's body as
+        a short, honest one-line note saying so, e.g. "_Nothing in the repo
+        speaks to this yet — needs research._" A human completes this
+        afterward, and a confident-sounding guess costs them more to unwind
+        than an honest blank.
+
+        `## What already exists` matters most: name specific files, modules
+        or prior work you found, not just that "some code exists" — that is
+        exactly the context a researcher picking this up next cannot see for
+        themselves without being told where to look.
+
+        #{context}
+        #{backlog}
+        Edit #{spec_path} in place. Keep the title#{", the author's opening prose" if seed} and the four `##`
+        headings exactly as they are, in order; add prose under them; write
+        nothing outside them; touch no other file.
+      PROMPT
+    end
+
+    # The author's own words lead the prompt, ahead of even the feature's
+    # announcement, because they outrank everything this pass could survey:
+    # where the seed and the repository disagree, the seed is the intent and
+    # the repository is merely the past.
+    #
+    # @return [String] empty without a seed
+    def author_statement
+      return "" unless seed
+
+      <<~STATEMENT
+        The author has already written the following about this feature. It
+        is the primary source: where it answers one of the headings, draw
+        from it first, and use the repository survey below only to supplement
+        it — never to contradict it.
+
+        #{seed}
+
+      STATEMENT
+    end
+
+    # AGENTS.md is commonly a symlink to CLAUDE.md; realpath-deduping keeps
+    # the shared content from being inlined twice into every drafting prompt.
+    #
+    # @return [String]
+    def context
+      seen = []
+      found = CONTEXT_FILES.filter_map { |name|
+        file = File.join(root, name)
+        next unless File.file?(file)
+
+        real = File.realpath(file)
+        next if seen.include?(real)
+
+        seen << real
+        "### #{name}\n\n#{File.read(file, encoding: "UTF-8")}"
+      }
+      return "" if found.empty?
+
+      "## Project context\n\n#{found.join("\n\n")}\n"
+    end
+
+    # A relevant line in the project's own backlog is worth more than
+    # anything this pass could infer on its own — it is the one place "why
+    # now" might already be written down.
+    #
+    # @return [String]
+    def backlog
+      file = File.join(root, BACKLOG_FILE)
+      return "" unless File.file?(file)
+
+      "## #{BACKLOG_FILE}\n\n" \
+        "If this backlog mentions \"#{title}\", treat that entry as " \
+        "authoritative for `## Why it matters` — it is the project's own " \
+        "statement of intent.\n\n" \
+        "#{File.read(file, encoding: "UTF-8")}\n"
+    end
+  end
+end

data/lib/agentilda/cli/agents/subcommands/describe.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda agents …` — the specialist roster.
+    module Agents
+      # `agentilda agents describe [NAME]`
+      class Describe < Dry::CLI::Command
+        include UI
+
+        desc "Open one specialist's definition in a Markdown viewer"
+
+        argument :name, required: false,
+          desc: "Which specialist, full name or a fragment, e.g. leah (default: every one)"
+
+        option :mdfried, type: :boolean, default: false, aliases: ["-m"],
+          desc: "Render in the terminal through mdfried instead of the system viewer"
+
+        example [
+          "leah               # leah-researcher, in the system Markdown viewer",
+          "luke-backend -m    # the same, rendered in this terminal by mdfried",
+          "                       # every agent, one viewer window each"
+        ]
+
+        # The registry instantiates commands bare, so both collaborators
+        # default to the real thing; the suite hands in its own to keep
+        # viewers from opening on the box running it.
+        #
+        # @param agents [Agentilda::Agents]
+        # @param viewer [Agentilda::Viewer]
+        def initialize(agents: Agentilda::Agents.new, viewer: Viewer.new)
+          super()
+          @agents = agents
+          @viewer = viewer
+        end
+
+        # @param name [String, nil]
+        # @param mdfried [Boolean]
+        # @return [void]
+        def call(name: nil, mdfried: false, **_options)
+          agents = @agents
+          found = name ? agents.match(name) : agents.all
+
+          if found.empty?
+            known = agents.all.map(&:name).join(", ")
+            raise Error, name ? "No agent matches #{name}. Known: #{known}" : "No agent definitions in #{agents.dir}"
+          end
+
+          # A fragment that fits several agents is a question, not an order:
+          # opening all of them would bury the one that was meant.
+          raise Error, "#{name} could be any of #{found.map(&:name).join(", ")} — say which" if name && found.size > 1
+
+          paths = found.map(&:path)
+          mdfried ? @viewer.mdfried(paths) : @viewer.open(paths)
+        rescue Agentilda::Error => e
+          error(e.message)
+          exit 65
+        end
+      end
+    end
+  end
+end

data/lib/agentilda/cli/agents/subcommands/list.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda agents …` — the specialist roster.
+    module Agents
+      # `agentilda agents list`
+      class List < Dry::CLI::Command
+        include UI
+
+        desc "List every specialist, what it handles, and what it advances to"
+
+        example ["", "| less -R"]
+
+        # @return [void]
+        def call(**) = $stdout.write(Roster.new.list)
+      end
+    end
+  end
+end