agentilda 1.0.3

data/lib/agentilda/cli/linear/subcommands/projects.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda linear …`
+    module Linear
+      # `linear projects` — what the team already has.
+      class Projects < Team
+        desc "List the Linear projects a team owns, and which plans they already cover"
+
+        example [
+          "TAX        # every project the team owns, matched against .plans"
+        ]
+
+        # @param team [String]
+        # @param options [Hash]
+        # @return [void]
+        def call(team:, **options)
+          tree = tree_for(options)
+          _api, survey = survey_for(team, tree)
+
+          survey.projects.each { |project| puts row(project) }
+          return if quiet?(options)
+
+          survey.projects.each do |project|
+            say("#{paint(project["name"], :cyan)}\n    #{paint(project["url"].to_s, :bright_black)}")
+          end
+          report_descriptions(survey)
+        rescue Agentilda::Error => e
+          refuse(e.message, 69)
+        end
+
+        private
+
+        # @param project [Hash]
+        # @return [String]
+        def row(project)
+          [project["name"], project.dig("status", "name") || "-", project["url"]].join("\t")
+        end
+
+        # @param survey [Agentilda::Linear::Survey]
+        # @return [void]
+        def report_descriptions(survey)
+          return if survey.undescribed.empty?
+
+          warn("#{survey.undescribed.size} of these say nothing about themselves:\n\n" \
+               "#{survey.undescribed.map { |p| "  #{p["name"]}" }.join("\n")}\n\n" \
+               "A name is three or four words and half of them are the company's. If you " \
+               "want anything here to reason about which project a plan belongs to, that " \
+               "reasoning has to have a sentence to read.")
+        end
+      end
+    end
+  end
+end

data/lib/agentilda/cli/list_plans/list_plans.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda list-plans` — backs /plan-status.
+    class ListPlans < Base
+      desc "Print every plan, its state, and its pull requests"
+
+      example ["", "-D .plans", "| less -R"]
+
+      # @param options [Hash]
+      # @return [void]
+      def call(**options)
+        reporter = Reporter.new(tree: tree_for(options))
+        $stdout.write(reporter.render)
+
+        exit 1 unless reporter.inconsistent.empty?
+      end
+    end
+  end
+end

data/lib/agentilda/cli/resync/subcommands/dirs.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda resync …`
+    module Resync
+      # `resync dirs` — reconcile folder names with folder contents.
+      class Dirs < Base
+        desc "Rename plan folders so the name matches the contents and the NNN.MM form"
+
+        option :commit, type: :boolean, default: false,
+          desc: "Actually rename the folders (default: dry run)"
+
+        example [
+          "                # show what would be renamed",
+          "--commit        # do it"
+        ]
+
+        # @param options [Hash]
+        # @return [void]
+        def call(**options)
+          changes = Agentilda::Resync::Dirs.new(tree: tree_for(options))
+            .call(commit: commit?(options))
+
+          if changes.empty?
+            success("Every folder is already named NNN.MM-<emoji>-<slug> and the emoji matches.") unless quiet?(options)
+            return
+          end
+
+          changes.each do |change|
+            puts "#{change.dirname}\t#{File.basename(change.target)}\t#{change.reason}"
+            next if quiet?(options)
+
+            say("#{paint(change.dirname, :bright_black)} → #{File.basename(change.target)}")
+            say("  #{paint(change.reason, :yellow)}", bullet: " ")
+          end
+
+          return if quiet?(options)
+
+          if commit?(options)
+            success("Renamed #{changes.size} folder#{"s" unless changes.size == 1}.")
+          else
+            dry_run_footer(changes.size, "rename#{"s" unless changes.size == 1}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agentilda/cli/resync/subcommands/prs.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda resync …`
+    module Resync
+      # `resync prs` — put an [NNN.MM] prefix on every pull request title.
+      class Prs < Base
+        desc "Add missing [NNN.MM] prefixes to pull request titles"
+
+        option :commit, type: :boolean, default: false,
+          desc: "Actually retitle the pull requests (default: dry run)"
+        option :state, default: "all", values: %w[open closed merged all],
+          desc: "Which pull requests to consider"
+        option :adopt, type: :boolean, default: true,
+          desc: "Mint a retroactive plan folder for every pull request that resolves to none. --no-adopt flags them for a human instead"
+
+        example [
+          "                # show what would be retitled, and what would be adopted",
+          "--state open    # only open pull requests",
+          "--no-adopt      # never create a folder; flag the unresolvable ones",
+          "--commit        # do it"
+        ]
+
+        # @param options [Hash]
+        # @return [void]
+        def call(**options)
+          github = GitHub.new
+          tree = tree_for(options)
+          changes = Agentilda::Resync::Prs.new(tree:, github:,
+            adopt: options.fetch(:adopt, true), root: File.dirname(tree.dir))
+            .call(commit: commit?(options))
+
+          if changes.empty?
+            success("Every pull request title already carries a prefix.") unless quiet?(options)
+            return
+          end
+
+          changes.each do |change|
+            puts "#{change.number}\t#{change.new_title || "-"}\t#{change.reason}"
+          end
+
+          return if quiet?(options)
+
+          report_pr_changes(changes, options)
+        rescue Agentilda::Error => e
+          refuse(e.message, 69)
+        end
+
+        private
+
+        # @param changes [Array]
+        # @param options [Hash]
+        # @return [void]
+        def report_pr_changes(changes, options)
+          applicable, flagged = changes.partition(&:applicable?)
+          assumed = applicable.select(&:assumed?)
+
+          applicable.each do |c|
+            note = if c.adopted?
+              paint("   (new plan)", :magenta)
+            elsif c.assumed?
+              paint("   (assumed)", :yellow)
+            end
+            say("##{c.number}  #{c.new_title}#{note}")
+          end
+
+          report_adoptions(applicable.select(&:adopted?), options)
+
+          flagged.each { |c| say("##{c.number}  #{paint("SKIPPED", :red)} — #{c.reason}", bullet: "!") }
+
+          if commit?(options)
+            success("Retitled #{applicable.size} pull request#{"s" unless applicable.size == 1}.")
+          else
+            dry_run_footer(applicable.size, "retitle#{"s" unless applicable.size == 1}")
+          end
+
+          return if assumed.empty?
+
+          warn("#{assumed.size} title#{"s" unless assumed.size == 1} would get " \
+               "[#{Agentilda::NO_PLAN_PREFIX}] because no plan resolved.\n\n" \
+               "That is an assertion about intent, and it is yours to make: check each one\n" \
+               "before committing. A pull request that writes a plan's spec belongs to that\n" \
+               "plan however its branch was named.")
+        end
+
+        # Creating folders is a bigger act than editing a title, so it is
+        # reported separately rather than buried in the retitle list.
+        #
+        # @param adopted [Array]
+        # @param options [Hash]
+        # @return [void]
+        def report_adoptions(adopted, options)
+          return if adopted.empty?
+
+          verb = commit?(options) ? "Created" : "Would create"
+          info("#{verb} #{adopted.size} plan folder#{"s" unless adopted.size == 1} for pull " \
+               "requests that resolved to no plan:\n\n" \
+               "#{adopted.map { |c| "  #{c.ordinal}  ##{c.number}  #{c.title}" }.join("\n")}\n\n" \
+               "Each holds its pull request and nothing else. Run `agentilda run --commit`\n" \
+               "to have the specification written from what the pull request actually did.")
+        end
+      end
+    end
+  end
+end

data/lib/agentilda/cli/run/run.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda run` — drive the specialist agents until the tree settles.
+    class Run < Base
+      desc "Run specialist agents over the plans until nothing changes"
+
+      option :commit, type: :boolean, default: false,
+        desc: "Actually invoke the agents (default: dry run, prints the plan of work)"
+      option :rounds, desc: "Hard ceiling on loop iterations (default: 10)"
+      option :timeout, desc: "Seconds before one agent is abandoned (default: 900)"
+      option :chain, type: :boolean,
+        desc: "When an agent advances a plan, run the next agent in the same round " \
+              "(default: on; forced off by --agent)"
+      option :agent, desc: "Only run this one agent"
+      option :prompt, desc: "Extra instructions appended to the agent's prompt (only with --agent)"
+      option :skip, desc: "Never assign this agent; its plans wait, the rest of the pipeline runs. " \
+        "Comma separated for several"
+      option :model, desc: "Model for every agent this run, overriding each agent's own frontmatter " \
+        "(default: what the agent declares, else the claude CLI's default)"
+      option :max_tokens, desc: "Token budget per agent invocation, input plus output, sub-agents " \
+        "included. The agent is told the number so it can finish inside it; the meter aborts it past " \
+        "the number so the telling is true. (default: unmetered)"
+      option :plan, aliases: ["--plans"],
+        desc: "Only these plans, comma separated: NNN or NNN.MM, e.g. --plan 003,005.01. Default: the whole tree"
+      option :root, desc: "Repository root the agents work in (default: the .plans parent)"
+      option :isolation, default: "worktree", values: %w[worktree shared],
+        desc: "worktree: a checkout and branch per plan, run in parallel. shared: one tree, serial"
+      option :jobs, aliases: ["-j"],
+        desc: "Agents to run at once (default: cores - 2, capped at 12)"
+      option :dont_push_anything, type: :boolean, default: false,
+        desc: "With --commit and --isolation worktree, a finished branch is pushed and its pull request " \
+              "opened as soon as it lands, titled [NNN.MM](X). Pass this to turn that off and leave it uncommitted."
+      option :log, desc: "Append progress to this file (default: a per-project file under the system temp dir)"
+
+      example [
+        "                       # show which agent would take which plan",
+        "--commit               # run them, one worktree per plan, in parallel",
+        "--commit -j 4          # …with four at a time",
+        "--isolation shared     # one tree, serial — no git required",
+        "--commit --rounds 3    # …with a tighter ceiling",
+        "--commit --plan 005,006,007  # only the plans a batch step just created"
+      ]
+
+      # Option precedence, quietest to loudest: the built-in default, then
+      # `~/.local/config/agentilda.json` under its `"run"` key, then the flag
+      # actually typed. The config never supplies `--commit`: an agent run
+      # that writes is something a person asks for each time.
+      #
+      # @param options [Hash]
+      # @return [void]
+      def call(**options)
+        config = begin
+          Agentilda::Config.for(:run)
+        rescue Agentilda::Error => e
+          refuse(e.message, 66)
+        end
+
+        if options[:prompt] && !options[:agent]
+          refuse("--prompt only works with --agent: it speaks to one agent, and without " \
+                 "that restriction every agent in the round would hear it.", 64)
+        end
+
+        tree = tree_for(options)
+        root = options[:root] || File.dirname(tree.dir)
+        agents = Agentilda::Agents.new
+        agents = filtered(agents, options[:agent]) if options[:agent]
+        agents = skipped(agents, options[:skip], options[:agent]) if options[:skip]
+        plans = options[:plan] ? scoped(tree, options[:plan]) : nil
+        assignable!(agents, tree, plans, options[:agent]) if options[:agent]
+
+        isolation = options.fetch(:isolation, "worktree").to_sym
+        jobs = (options[:jobs] || config[:jobs] || UI.default_jobs).to_i
+        timeout = (options[:timeout] || config[:timeout] || 900).to_i
+        chain = if options[:agent]
+          false
+        elsif options.key?(:chain)
+          options[:chain]
+        else
+          config.fetch(:chain, true)
+        end
+
+        if isolation == :worktree && !Worktree.new(root:).repository?
+          refuse("#{root} is not a git repository, so plans cannot be isolated.\n\n" \
+                 "Run with --isolation shared to work in one tree, serially.", 66)
+        end
+
+        # Set before the loop starts, not after: `UI.animate?` (and therefore
+        # whether a round prints anything at all) is read the whole time the
+        # loop runs, not just when `report` prints its closing summary.
+        quiet?(options)
+        UI.log_path = options[:log] || config[:log] ||
+          File.join(Dir.tmpdir, "agentilda-#{File.basename(root)}.log")
+        info("Progress: #{UI.log_path}") unless quiet?(options)
+        credentials_warning if commit?(options) && !quiet?(options)
+
+        Control.reset!
+        keyboard = Keyboard.listen
+        UI.line("keys: h for help — w wrap up · n write out and stop · q quit") if keyboard && !quiet?(options)
+
+        runner = Runner.new(
+          tree:, agents:, isolation:, jobs:, plans:, chain:,
+          worktree: (Worktree.new(root:) if isolation == :worktree),
+          max_rounds: (options[:rounds] || config[:rounds] || 10).to_i,
+          executor: Executor.new(root:, timeout:, dry_run: !commit?(options),
+            instructions: options[:prompt], model: options[:model],
+            max_tokens: (options[:max_tokens] || config[:max_tokens])&.to_i,
+            interactive: !keyboard.nil? && commit?(options)), dry_run: !commit?(options),
+          publisher: publisher_for(root, isolation, options)
+        )
+
+        started = UI.monotonic
+        rounds = begin
+          runner.call
+        ensure
+          keyboard&.stop
+        end
+        report(runner, rounds, options, seconds: UI.monotonic - started)
+        exit(failures(rounds).empty? ? 0 : 1)
+      end
+
+      private
+
+      # @param agents [Agentilda::Agents]
+      # @param name [String]
+      # @return [Agentilda::Agents] holding only the agent named — the
+      #   restriction has to reach assignments, not just chaining, or a flag
+      #   like `--prompt` aimed at one agent leaks to the whole round
+      def filtered(agents, name)
+        agents.find(name) or
+          refuse("No agent called #{name}.\n\nKnown: #{agents.all.map(&:name).join(", ")}", 65)
+        agents.only(name)
+      end
+
+      # Each name is checked against the full roster, not the possibly
+      # already-restricted one, so `--skip` misspelled is a refusal rather
+      # than a silent no-op — the same reasoning `--plan` applies to numbers.
+      #
+      # @param agents [Agentilda::Agents]
+      # @param text [String] comma-separated agent names
+      # @param restricted [String, nil] what `--agent` asked for, if anything
+      # @return [Agentilda::Agents] without the agents named
+      def skipped(agents, text, restricted)
+        roster = Agentilda::Agents.new
+        names = text.split(",").map(&:strip).reject(&:empty?)
+        names.each do |name|
+          roster.find(name) or
+            refuse("No agent called #{name}.\n\nKnown: #{roster.all.map(&:name).join(", ")}", 65)
+          if name == restricted
+            refuse("--agent #{name} and --skip #{name} contradict each other: " \
+                   "one asks for only this agent, the other for anything but.", 64)
+          end
+        end
+        agents.without(*names)
+      end
+
+      # `--plan` names the whole point of scoping: a skill that just minted
+      # N folders hands off exactly those, not the tree. A typo'd or already-
+      # settled number silently running the whole tree instead is the failure
+      # this exists to prevent, so an unknown one is refused rather than
+      # dropped.
+      #
+      # @param tree [Agentilda::Tree]
+      # @param text [String]
+      # @return [Array<Agentilda::Ordinal>]
+      def scoped(tree, text)
+        known = tree.subjects.map { |s| s.feature.ordinal }
+        text.split(",").map(&:strip).reject(&:empty?).map { |token|
+          ordinal = Ordinal.parse(token)
+          unless ordinal && known.include?(ordinal)
+            refuse("No plan #{token} in #{tree.dir}.\n\n" \
+                   "Known: #{known.join(", ")}", 66)
+          end
+          ordinal
+        }
+      end
+
+      # `--agent` narrowing the round to nobody used to exit 0 in silence —
+      # "0 plans addressed", green box, no hint that the agent named simply
+      # does not handle any in-scope plan's state. Someone who typed both an
+      # agent and a plan meant them to meet, so a pairing that cannot happen
+      # is refused up front with the agent that would actually take each plan.
+      #
+      # @param agents [Agentilda::Agents] already narrowed to the one agent
+      # @param tree [Agentilda::Tree]
+      # @param plans [Array<Agentilda::Ordinal>, nil]
+      # @param name [String]
+      # @return [void]
+      def assignable!(agents, tree, plans, name)
+        agent = agents.find(name)
+        active = tree.subjects.select { |s|
+          (plans.nil? || plans.include?(s.feature.ordinal)) &&
+            !StateMachine::SETTLED.include?(s.status.key)
+        }
+        return if active.empty? || active.any? { |s| agent.handles?(s.status) }
+
+        roster = Agentilda::Agents.new
+        lines = active.map { |s|
+          takers = roster.for_status(s.status).map(&:name)
+          "  #{s.feature.ordinal} is #{s.status.emoji} #{s.status.label}" \
+            "#{" — #{takers.join(", ")} takes it" unless takers.empty?}"
+        }
+        handled = agent.handles.map { |k| Agentilda::STATUS_BY_KEY[k]&.then { |st| "#{st.emoji} #{st.label}" } || k }
+        refuse("#{name} handles #{handled.join(", ")}, and no plan in scope is there:\n\n" \
+               "#{lines.join("\n")}\n\nName the agent that takes these states, or drop --agent.", 65)
+      end
+
+      # @param rounds [Array]
+      # @return [Array]
+      def failures(rounds) = rounds.flat_map(&:attempts).reject(&:ok)
+
+      # The one thing this harness does that leaves the machine — pushing a
+      # branch and opening its pull request — so it takes one more thing to
+      # turn on than everything else here: `--commit` alone is not enough,
+      # isolation has to actually give each plan a branch of its own too.
+      #
+      # `nil` is how {Runner} is told to leave a finished worktree alone; it
+      # is what `--dont-push-anything` asks for, and what a shared tree gets
+      # by construction, since there is no separate branch there to push.
+      #
+      # @param root [String]
+      # @param isolation [Symbol]
+      # @param options [Hash]
+      # @return [Agentilda::Publisher, nil]
+      def publisher_for(root, isolation, options)
+        return nil if isolation != :worktree || options[:dont_push_anything]
+
+        Publisher.new(root:, dry_run: !commit?(options))
+      end
+
+      # @param runner [Agentilda::Runner]
+      # @param rounds [Array]
+      # @param options [Hash]
+      # @param seconds [Float] wall clock for the whole loop
+      # @return [void]
+      def report(runner, rounds, options, seconds: 0.0)
+        rounds.each do |round|
+          puts "round #{round.number}"
+          round.attempts.each do |a|
+            mark = if !a.ok
+              "FAIL"
+            elsif a.advanced?
+              "#{a.from} -> #{a.to}"
+            else
+              "no change"
+            end
+            puts "  #{a.ordinal}\t#{a.agent}\t#{mark}\t#{a.note}"
+          end
+        end
+
+        # What the run cost, on STDOUT with the rounds it belongs to, so a run
+        # redirected to a file keeps its bill. A dry run spent nothing and gets
+        # none of this.
+        tally = Tally.new(attempts: rounds.flat_map(&:attempts), seconds:, rounds: rounds.size)
+        puts("", tally.render) if commit?(options)
+
+        return if quiet?(options)
+
+        if Control.quit?
+          warn("Stopped from the keyboard — q. Unfinished plans keep their state; " \
+               "re-run to resume where they stand.")
+        end
+
+        advanced = rounds.sum(&:advanced)
+        blocked = runner.blocked
+        summary = ["#{rounds.size} round#{"s" unless rounds.size == 1}", "#{advanced} advanced"]
+        summary << (runner.isolated? ? "#{runner.jobs} at a time, one worktree each" : "serial, shared tree")
+        summary << "#{blocked.size} blocked" unless blocked.empty?
+        summary << "#{failures(rounds).size} failed" unless failures(rounds).empty?
+
+        if !commit?(options)
+          warn("Dry run — no agent was invoked.\n#{summary.join(" · ")}\n\nRe-run with --commit.")
+        elsif failures(rounds).empty?
+          success("#{summary.join(" · ")}#{"\n\nEvery plan is done or deliberately parked." if runner.settled?}")
+        else
+          error("#{summary.join(" · ")}\n\n#{failures(rounds).map { |f| "#{f.ordinal} #{f.agent}: #{f.note}" }.join("\n")}")
+        end
+
+        return if blocked.empty?
+
+        warn("#{blocked.size} plan#{"s" unless blocked.size == 1} need a human decision:\n" +
+             blocked.map { |b| "  #{b.feature.ordinal} #{b.status.emoji} #{b.feature.title} — see blocked.md" }.join("\n") +
+             "\n\nWrite the answers into blocked.md, then: agentilda unblock " \
+             "#{blocked.map { |b| b.feature.ordinal }.join(",")} --commit")
+      end
+    end
+  end
+end

data/lib/agentilda/cli/states/states.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda states` — the state machine, as a terminal diagram.
+    class States < Dry::CLI::Command
+      desc "Print a diagram of every state and the transitions between them"
+
+      example [""]
+
+      # @return [void]
+      def call(**) = $stdout.write(Diagram.new.render)
+    end
+  end
+end