agentilda 1.0.3

data/lib/agentilda/unblocker.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # Draining a plan's `blocked.md`, and saying what happened.
+  #
+  # `unblock` is the one command a human runs *because* they know something the
+  # tool cannot observe: an answer has arrived. So it owes them an account of
+  # what it did with it. Four things can happen to a plan named on the command
+  # line, and only one of them is the interesting one:
+  #
+  #   * the number names no folder,
+  #   * the folder is not blocked and there is nothing to drain,
+  #   * the folder is blocked, and some, none or all of its questions fold in,
+  #   * `blocked.md` is there but numbers nothing `## B<n>`, so no program can
+  #     read it at all.
+  #
+  # Each is reported differently, because each needs a different thing done
+  # next. This object works out which one happened; {CLI::Unblock} prints it.
+  class Unblocker
+    # One open question, as `blocked.md` writes it.
+    #
+    # @!attribute [r] number
+    #   @return [Integer] the `n` in `## B<n>`
+    # @!attribute [r] heading
+    #   @return [String] the heading text, hashes stripped
+    # @!attribute [r] answered
+    #   @return [Boolean] whether an `## A<n>` of the same number is waiting
+    Question = Data.define(:number, :heading, :answered) do
+      # @return [String]
+      def to_s = answered ? "#{heading}  ← answer waiting" : heading
+    end
+
+    # One token from the command line, once the tree has had a look at it.
+    #
+    # @!attribute [r] token
+    #   @return [String] what the user typed
+    # @!attribute [r] subject
+    #   @return [Agentilda::Subject, nil]
+    # @!attribute [r] problem
+    #   @return [Symbol, nil] :missing, :not_blocked, or nil when it is drainable
+    Target = Data.define(:token, :subject, :problem) do
+      # @return [Boolean]
+      def drainable? = problem.nil?
+    end
+
+    # What became of one plan.
+    #
+    # @!attribute [r] subject
+    #   @return [Agentilda::Subject] as the folder stands *now*
+    # @!attribute [r] ok
+    #   @return [Boolean] whether the agent ran without failing
+    # @!attribute [r] note
+    #   @return [String] one line about how it went
+    # @!attribute [r] before
+    #   @return [Array<Question>] open before the agent ran
+    # @!attribute [r] after
+    #   @return [Array<Question>] open now
+    Outcome = Data.define(:subject, :ok, :note, :before, :after) do
+      # @return [Agentilda::Ordinal]
+      def ordinal = subject.feature.ordinal
+
+      # @return [Array<Integer>] the questions this run actually disposed of
+      def folded = before.map(&:number) - after.map(&:number)
+
+      # @return [Boolean] `blocked.md` is gone, so the plan is out of the block
+      def cleared? = !subject.file?("blocked.md")
+
+      # @return [Boolean] a `blocked.md` no program can read
+      def unreadable? = subject.unreadable_block?
+
+      # @return [Array<Question>] still open, with an answer sitting unfolded
+      def waiting = after.select(&:answered)
+    end
+
+    # The questions a folder still names, in the order the file names them.
+    #
+    # @param subject [Agentilda::Subject]
+    # @return [Array<Question>]
+    def self.questions(subject)
+      answered = subject.block_answers
+
+      subject.read("blocked.md").to_s.lines.grep(OPEN_BLOCK).map do |line|
+        number = line[OPEN_BLOCK, 1].to_i
+        Question.new(number:, heading: line.strip.sub(/\A\#+[ \t]*/, ""), answered: answered.include?(number))
+      end
+    end
+
+    # @param tree [Agentilda::Tree]
+    # @param agent [Agentilda::Agent]
+    # @param executor [#call] receives (agent, subject, root:) and yields each
+    #   phrase describing what the agent is doing
+    # @param root [String] the repository the agent works in
+    # @param commit [Boolean] false plans the invocation and changes nothing
+    def initialize(tree:, agent:, executor:, root: nil, commit: false)
+      @tree = tree
+      @agent = agent
+      @executor = executor
+      @root = root || File.dirname(tree.dir)
+      @commit = commit
+    end
+
+    # @return [Agentilda::Tree]
+    attr_reader :tree
+
+    # @return [Agentilda::Agent]
+    attr_reader :agent
+
+    # @return [String]
+    attr_reader :root
+
+    # @return [Boolean]
+    def commit? = @commit
+
+    # Work out what each number on the command line refers to.
+    #
+    # Nothing is rejected here and nothing exits: a token that names no folder
+    # is as much a thing the user needs told about as a folder that drained, and
+    # stopping at the first bad one hides the rest of the report.
+    #
+    # The gate is `blocked.md` itself, not the folder's emoji. ⭕️ is *derived*
+    # from the file, so gating on the emoji made the tool circular: a
+    # `blocked.md` whose questions are not numbered `## B<n>` never earns the
+    # emoji, so `unblock` refused it, so the file could never drain and the
+    # folder could never leave 🟡.
+    #
+    # @param tokens [Array<String>] `NNN`, `NNN.MM`, or several comma separated
+    # @return [Array<Target>]
+    def resolve(tokens)
+      tokens.flat_map { |token| token.to_s.split(",") }.map(&:strip).reject(&:empty?).map do |token|
+        subject = tree.find(token)
+        next Target.new(token:, subject: nil, problem: :missing) if subject.nil?
+        next Target.new(token:, subject:, problem: :not_blocked) unless subject.file?("blocked.md")
+
+        Target.new(token:, subject:, problem: nil)
+      end
+    end
+
+    # Hand each folder to the agent, one at a time, and read the file back.
+    #
+    # What the agent claims it did is not evidence. The questions are counted
+    # off disk before and after, so "folded B3" means the heading is gone from
+    # `blocked.md`, not that an agent said so.
+    #
+    # @param subjects [Array<Agentilda::Subject>]
+    # @return [Array<Outcome>]
+    def call(subjects)
+      return [] if subjects.empty?
+
+      before = subjects.map { |subject| [subject.feature.ordinal.to_s, self.class.questions(subject)] }.to_h
+      results = UI.concurrently(subjects, headline(subjects), jobs: 1, label: method(:label),
+        fields: method(:log_fields)) do |subject, progress|
+        invoke(subject, &progress)
+      end
+
+      settle
+      subjects.zip(results).map { |subject, result| outcome(subject, result, before) }
+    end
+
+    private
+
+    # @param subject [Agentilda::Subject]
+    # @yieldparam phrase [String] what the agent is doing, as it changes
+    # @return [Array(Boolean, String)]
+    def invoke(subject, &on_activity)
+      @executor.call(agent, subject, root:, &on_activity)
+    rescue => e
+      [false, "#{e.class}: #{e.message.lines.first.to_s.strip}"]
+    end
+
+    # The same pass the run loop makes after every round, for the same reason:
+    # a drained folder is only *named* differently once something reads the
+    # file the agent just deleted.
+    #
+    # @return [void]
+    def settle
+      Resync::Dirs.new(tree:).call(commit: true) if commit?
+      tree.reload
+    end
+
+    # @param subject [Agentilda::Subject] as it was before the run
+    # @param result [Array, Exception]
+    # @param before [Hash{String => Array<Question>}]
+    # @return [Outcome]
+    def outcome(subject, result, before)
+      ok, note = result.is_a?(Exception) ? [false, result.message.lines.first.to_s.strip] : result
+      current = tree.find(subject.feature.ordinal) || subject
+
+      Outcome.new(subject: current, ok: !!ok, note: note.to_s,
+        before: before.fetch(subject.feature.ordinal.to_s, []), after: self.class.questions(current))
+    end
+
+    # @param subjects [Array<Agentilda::Subject>]
+    # @return [String]
+    def headline(subjects)
+      "#{commit? ? "handing" : "would hand"} #{subjects.size} plan#{"s" unless subjects.size == 1} " \
+      "to #{agent.name} in #{root}"
+    end
+
+    # @param subject [Agentilda::Subject]
+    # @return [String]
+    def label(subject) = "#{subject.feature.ordinal} → #{agent.name}"
+
+    # @param subject [Agentilda::Subject]
+    # @return [Hash] the columns this plan's log lines carry
+    def log_fields(subject) = {plan: subject.feature.ordinal.to_s, status: subject.status.to_s, agent: agent.name}
+  end
+end

data/lib/agentilda/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Alone in its own file, requiring nothing, so the gemspec can read the version
+# without loading the library — and therefore without the library's own
+# dependencies having to be installed before the gemspec can be evaluated.
+#
+# © 2026 Konstantin Gredeskoul
+module Agentilda
+  VERSION = "1.0.3"
+end

data/lib/agentilda/viewer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # Hands Markdown files to a renderer outside this process: the system
+  # viewer via `open`, or mdfried in the terminal.
+  #
+  # Both paths shell out, so the class takes its two effects as lambdas and
+  # the specs assert on the commands instead of launching viewers on the box
+  # running the suite.
+  class Viewer
+    # What to run when mdfried is asked for but not installed. Homebrew is the
+    # one package manager the toolchain already assumes (see the Brewfile
+    # convention), so there is no fallback chain to get wrong.
+    INSTALL = "brew install mdfried >/dev/null"
+
+    # How to notice mdfried is missing without depending on `which`, which
+    # differs across shells; `command -v` is POSIX.
+    DETECT = "command -v mdfried >/dev/null"
+
+    # @param launch [#call] runs a command, returns truthy on success
+    # @param pipe [#call] runs a command, yielding its stdin as an IO
+    def initialize(launch: ->(*cmd) { system(*cmd) },
+      pipe: ->(cmd, &block) { IO.popen(cmd, "w", &block) })
+      @launch = launch
+      @pipe = pipe
+    end
+
+    # Opens each file in whatever the system has configured for Markdown.
+    #
+    # @param paths [Array<String>]
+    # @return [void]
+    def open(paths)
+      Array(paths).each { |path| @launch.call("open", path) }
+    end
+
+    # Streams each file's content into mdfried, installing it first when it
+    # is missing.
+    #
+    # @param paths [Array<String>]
+    # @return [void]
+    # @raise [Agentilda::Error] when mdfried is absent and brew cannot fix that
+    def mdfried(paths)
+      ensure_mdfried!
+      Array(paths).each do |path|
+        @pipe.call("mdfried") { |io| io.write(File.read(path)) }
+      end
+    end
+
+    private
+
+    # @return [void]
+    # @raise [Agentilda::Error]
+    def ensure_mdfried!
+      return if @launch.call(DETECT)
+
+      @launch.call(INSTALL) or
+        raise Error, "mdfried is not installed, and `brew install mdfried` failed"
+    end
+  end
+end

data/lib/agentilda/worktree.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # A git worktree per plan, so agents working on different plans cannot
+  # collide at all.
+  #
+  # A lock coordinates a shared tree; a worktree removes the sharing. That
+  # matters more than it sounds for an agent loop: two agents editing one
+  # checkout produce no git conflict — same branch, same files — so the last
+  # writer simply wins and the loser's work vanishes with nothing anywhere to
+  # say it happened.
+  #
+  # The branch carries the plan number (`<user>/NNN.MM-slug`), which is not
+  # decoration: it is the first thing `resync prs` reads when deciding which
+  # plan a pull request implements. Naming branches this way means the number
+  # carries itself from worktree creation through to a merged pull request with
+  # nobody having to remember it.
+  class Worktree
+    # `bin/setup-worktree`, which copies in the ignored-but-required files a new
+    # checkout does not get. Shelling out rather than reimplementing the rules
+    # here keeps one answer to "what does a worktree need", and keeps that answer
+    # usable from a shell on a machine that has never run `bundle install`.
+    SEEDER = File.expand_path("../../bin/setup-worktree", __dir__)
+
+    # One plan's isolated checkout.
+    #
+    # @!attribute [r] ordinal
+    #   @return [Agentilda::Ordinal]
+    # @!attribute [r] branch
+    #   @return [String]
+    # @!attribute [r] path
+    #   @return [String] absolute
+    # @!attribute [r] created
+    #   @return [Boolean] false when an existing worktree was reused
+    Checkout = Data.define(:ordinal, :branch, :path, :created) do
+      # @return [Boolean] whether the agent left anything behind
+      def dirty? = !`git -C #{path.shellescape} status --porcelain 2>/dev/null`.strip.empty?
+
+      # @return [String] the plans directory inside this checkout
+      def plans_dir = File.join(path, Agentilda::PLANS_DIR)
+
+      # @return [Boolean] whether this round made it, rather than reusing one
+      def created? = created
+    end
+
+    # @param root [String] the main repository
+    # @param dir [String, nil] where worktrees go; defaults to a sibling
+    # @param user [String] branch namespace
+    def initialize(root:, dir: nil, user: ENV["USER"] || "agent")
+      @root = File.expand_path(root)
+      @user = user
+      @dir = File.expand_path(dir || default_dir)
+    end
+
+    # @return [String] the main repository
+    attr_reader :root
+
+    # @return [String] where worktrees are kept
+    attr_reader :dir
+
+    # @return [Boolean] whether root is a git repository at all
+    def repository? = system("git", "-C", root, "rev-parse", "--git-dir", out: File::NULL, err: File::NULL)
+
+    # Get, or create, the isolated checkout for one plan.
+    #
+    # The checkout is seeded before it is handed back, on both paths. `git
+    # worktree add` brings every TRACKED file and nothing else, so an agent
+    # given a bare one cannot run the suite it was told to keep green: a Rails
+    # project dies on `MissingKeyError` because `config/credentials/*.key` is
+    # gitignored. The agent then reports a broken checkout as a broken plan,
+    # which is the worst failure this loop has, because the diagnosis points
+    # at the code rather than at the tree.
+    #
+    # A reused worktree is seeded too. {#seed} only ever adds a missing file,
+    # so running it again costs one fast subprocess and repairs the worktrees
+    # that were created before any of this existed.
+    #
+    # @param feature [Agentilda::Feature]
+    # @return [Agentilda::Worktree::Checkout]
+    # @raise [Agentilda::Error] when git refuses
+    def checkout_for(feature)
+      branch = branch_for(feature)
+      path = File.join(dir, "#{feature.ordinal}-#{feature.slug}")
+
+      if File.directory?(path)
+        seed(path)
+        return Checkout.new(ordinal: feature.ordinal, branch:, path:, created: false)
+      end
+
+      # git keeps a registration for a worktree whose directory was deleted by
+      # hand, marks it `prunable`, and then refuses to create a new one at that
+      # path. Anybody who has ever `rm -rf`d a worktree meets this, and the
+      # error says only "already exists" about a directory that does not.
+      forget_stale
+
+      FileUtils.mkdir_p(dir)
+      add(branch, path)
+      seed(path)
+      Checkout.new(ordinal: feature.ordinal, branch:, path:, created: true)
+    end
+
+    # Copy in the files git ignores and a new checkout therefore lacks: `.env`
+    # and friends, and credential keys.
+    #
+    # Never fatal. A repository with no ignored files is perfectly normal, and
+    # a plan is not worth abandoning over a seeding step, so this reports and
+    # carries on. It runs `--quiet`, which prints nothing on success and leaves
+    # a real failure on STDERR where the loop's other progress goes.
+    #
+    # @param path [String] the worktree to seed
+    # @return [Boolean] whether the seeder ran and succeeded
+    # `$stderr` rather than `Kernel#warn`, matching {Agentilda::UI}, which
+    # writes its progress to `$stderr` too. Style/StderrPuts prefers warn so the
+    # output can be silenced, but warn reaches file descriptor 2 through
+    # `Warning.warn` and ignores a reassigned `$stderr` entirely:
+    #
+    #   $stderr = StringIO.new; warn "x"; $stderr.string  # => ""
+    #
+    # So anything capturing this loop's output, the suite included, would never
+    # see a seeding failure. Being silenceable is worth less than being seen.
+    # rubocop: disable Style/StderrPuts
+    def seed(path)
+      unless File.executable?(SEEDER)
+        $stderr.puts "worktree: #{SEEDER} is missing, so #{path} has no .env or credential keys"
+        return false
+      end
+
+      return true if system(SEEDER, "--quiet", path, out: File::NULL)
+
+      $stderr.puts "worktree: could not seed #{path}; its suite may fail on a missing key"
+      false
+    end
+
+    # rubocop: enable Style/StderrPuts
+
+    # @param feature [Agentilda::Feature]
+    # @return [String] e.g. "kig/002.00-tenancy-households"
+    def branch_for(feature) = "#{@user}/#{feature.ordinal}-#{feature.slug}"
+
+    # Every worktree this class manages, as git sees them.
+    #
+    # @return [Array<String>] absolute paths
+    def list
+      # Compare canonical paths. git reports resolved ones, and on macOS the
+      # temp and home trees run through symlinks (/var -> /private/var), so a
+      # raw string compare matches nothing and prune silently does nothing.
+      mine = canonical(dir)
+
+      `git -C #{root.shellescape} worktree list --porcelain 2>/dev/null`
+        .lines(chomp: true)
+        .filter_map { |l| l.delete_prefix("worktree ") if l.start_with?("worktree ") }
+        .select { |p| canonical(p).start_with?(mine) }
+    end
+
+    # @param path [String]
+    # @return [String] the symlink-resolved path, or the input when it is gone
+    def canonical(path)
+      File.realpath(path)
+    rescue Errno::ENOENT
+      path
+    end
+
+    # Remove worktrees the agents left untouched.
+    #
+    # An agent that ran and changed nothing has produced a checkout that is
+    # pure cost: it looks like work in progress and is not. Dirty ones are
+    # always kept — that is the output.
+    #
+    # @return [Array<String>] paths removed
+    def prune
+      list.select { |path| clean?(path) }.each { |path| remove(path) }
+    end
+
+    # @param path [String]
+    # @return [void]
+    def remove(path)
+      system("git", "-C", root, "worktree", "remove", "--force", path, out: File::NULL, err: File::NULL)
+    end
+
+    private
+
+    # Sibling of the repository, not inside it: a worktree under the repo shows
+    # up in its own `git status` and in every glob anybody writes.
+    #
+    # @return [String]
+    def default_dir = "#{@root}.worktrees"
+
+    # Drop registrations whose directory is gone.
+    #
+    # @return [void]
+    def forget_stale
+      system("git", "-C", root, "worktree", "prune", out: File::NULL, err: File::NULL)
+    end
+
+    # @param path [String]
+    # @return [Boolean]
+    def clean?(path) = `git -C #{path.shellescape} status --porcelain 2>/dev/null`.strip.empty?
+
+    # @param branch [String]
+    # @param path [String]
+    # @return [void]
+    def add(branch, path)
+      exists = system("git", "-C", root, "show-ref", "--verify", "--quiet", "refs/heads/#{branch}")
+      args = exists ? ["worktree", "add", path, branch] : ["worktree", "add", "-b", branch, path]
+
+      return if system("git", "-C", root, *args, out: File::NULL, err: File::NULL)
+
+      raise Error, "could not create a worktree for #{branch} at #{path}"
+    end
+  end
+end

data/lib/agentilda.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require_relative "dry/cli/banner"
+require "dry/monads"
+require "dry/inflector"
+require "pastel"
+require "unicode/display_width"
+require "strings"
+require "tty/box"
+require "tty/command"
+require "tty/screen"
+require "tty/progressbar"
+require "tty/spinner"
+require "concurrent/array"
+require "concurrent/hash"
+require "etc"
+require "fileutils"
+require "tempfile"
+require "tmpdir"
+require "shellwords"
+require "parallel"
+
+# Spec → Plan → Build.
+#
+# Three phases, each with a file that proves it happened, and a guarded state
+# machine that refuses to let a plan folder claim a phase it has not reached.
+#
+#   spec   ⚪️ New          spec.md
+#   plan   ⭐️ Ready        plan.md
+#   build  🟡 → ✅         pull-requests.md
+#
+# The conventions are not documented anywhere else by hand: the status
+# vocabulary, the numbering rules and the transition table live here and are
+# emitted by `agentilda docs`. Three hand-maintained copies of that table
+# have already drifted apart, which is why there is now exactly one.
+#
+require_relative "agentilda/version"
+
+# © 2026 Konstantin Gredeskoul
+module Agentilda
+  # The folder every project keeps its plans in.
+  PLANS_DIR = ".plans"
+
+  # Prefix for a pull request that deliberately implements no plan —
+  # dependency bumps, CI work, hotfixes, developer tooling.
+  #
+  # Lower case, and not a number, so it cannot be mistaken for one. It used to
+  # be `DEV.00`, which read as a plan number and sorted among them.
+  NO_PLAN_PREFIX = "dev"
+
+  # What it used to be. Titles still wearing it are rewritten rather than
+  # skipped as already-prefixed.
+  STALE_NO_PLAN_PREFIX = "DEV.00"
+
+  # Prefix for a pull request that implements *something* nothing could name.
+  # Unlike `dev` this asserts nothing; it marks a question left open.
+  NONE_PREFIX = "none"
+
+  # @return [Dry::Inflector] shared inflector
+  def self.inflector = @inflector ||= Dry::Inflector.new
+
+  # Move a directory, preferring `git mv` so its history follows it.
+  #
+  # Both the state machine and `resync dirs` move plan folders, and a folder
+  # that loses its history because one of them used `FileUtils` is a folder
+  # nobody can `git log`.
+  #
+  # @param source [String] absolute
+  # @param target [String] absolute
+  # @return [Boolean] false when the target was already occupied
+  def self.move_directory(source, target)
+    return false if File.exist?(target)
+
+    parent = File.dirname(source)
+    tracked = system("git", "-C", parent, "ls-files", "--error-unmatch", source,
+      out: File::NULL, err: File::NULL)
+    moved = tracked && system("git", "-C", parent, "mv", source, target,
+      out: File::NULL, err: File::NULL)
+    FileUtils.mv(source, target) unless moved
+    true
+  end
+
+  # Plan numbers visible in `.plans` on a git ref, without checking it out.
+  #
+  # A pull request's branch is the only place that knows how far the sequence
+  # had got when the work started, and branches are not all rebased onto the
+  # same main. Reading the ref directly costs one `ls-tree` and no worktree.
+  #
+  # @param root [String] repository root
+  # @param ref [String] a branch name; `origin/` is tried first
+  # @return [Array<Agentilda::Ordinal>] possibly empty
+  def self.plans_on_ref(root, ref)
+    ["origin/#{ref}", ref].each do |candidate|
+      out = `git -C #{root.shellescape} ls-tree -d --name-only #{candidate.shellescape} #{PLANS_DIR}/ 2>/dev/null`
+      next if out.to_s.strip.empty?
+
+      return out.lines.filter_map { |line| Ordinal.from_dirname(File.basename(line.strip)) }
+    end
+    []
+  end
+
+  # The agent that writes a specification for work that already shipped.
+  # Named here rather than in the CLI so the definition file stays the single
+  # source of truth about who does what.
+  RETROACTIVE_WRITER = "yoda-writer"
+
+  class Error < StandardError; end
+end
+
+# Each component is required only once it exists, so the suite loads — and
+# stays a useful red/green signal — while the rest is being built. Drop the
+# `File.exist?` guard once every file below is in place.
+%w[
+  ui
+  config
+  ordinal
+  status
+  progress_log
+  state_machine
+  dev_work
+  frontmatter
+  markdown
+  pull_request
+  description
+  feature
+  github
+  tree
+  creator
+  brief
+  adoption
+  resolver
+  resync
+  reporter
+  tally
+  index
+  linear
+  agent
+  transcript
+  roster
+  viewer
+  worktree
+  publisher
+  control
+  keyboard
+  executor
+  runner
+  unblocker
+  documentation
+  diagram
+  cli
+].each do |component|
+  path = File.join(__dir__, "agentilda", "#{component}.rb")
+  require path if File.exist?(path)
+end