agentilda 2.0.3 → 2.0.4

data/lib/agentilda/lifecycle/resync.rb

@@ -0,0 +1,428 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Lifecycle
+    # Reconciling what is recorded with what is true.
+    #
+    # Both resyncs are dry-run by default and both refuse to act where they are
+    # not certain, because both write to things other people join on: folder
+    # names, and pull request titles.
+    module Resync
+      # `resync dirs` — makes every folder's name say what the folder is.
+      #
+      # Two things can be wrong with a name, and both are repaired here:
+      #
+      # - **The emoji is wrong** — the contents justify a different state. A
+      #   folder whose status already holds is left alone, which is what stops
+      #   ⭕️ Blocked and 🅱️ Product Blocked — deliberately identical invariants,
+      #   distinguished only by the name — from collapsing into one.
+      # - **The spelling is not canonical** — a folder written `018-⚪️--foo`
+      #   before the `NNN.MM` padding rule or the ` → ` separator, or
+      #   `18.1-⚪️--foo` by hand. Unpadded numbers read fine and sort wrong —
+      #   `018.09` < `018.1` < `018.10` puts a single mixed-width folder in the
+      #   middle of the range. Both are renamed, to `018.00-⚪️ → foo` and
+      #   `018.01-⚪️ → foo`.
+      #
+      # The repairs are applied in that order reversed, as **up to two renames
+      # per folder**: first the spelling, under the status the folder already
+      # claims — which is how a `--`-era folder migrates to the ` → ` form —
+      # and only then the status its contents justify. Both renames aim at
+      # {Feature.plan_dirname}, so they cannot disagree about the final name;
+      # splitting them keeps each auditable on its own, instead of one report
+      # line where a spelling migration also appears to have opinions about
+      # the state of the work.
+      class Dirs
+        # A proposed rename.
+        #
+        # @!attribute [r] dirname
+        #   @return [String] the folder as it stands
+        # @!attribute [r] from
+        #   @return [Symbol] the state it claims
+        # @!attribute [r] to
+        #   @return [Symbol] the state its contents justify
+        # @!attribute [r] source
+        #   @return [String] absolute path now
+        # @!attribute [r] target
+        #   @return [String] absolute path after
+        # @!attribute [r] reason
+        #   @return [String] why the current name is wrong
+        Change = Data.define(:dirname, :from, :to, :source, :target, :reason) do
+          # @return [String] a single auditable line — `⇒` rather than `→`,
+          #   which the folder names themselves now contain
+          def to_s = "#{dirname} ⇒ #{File.basename(target)}  (#{reason})"
+        end
+
+        # The state a folder's contents justify, or the one it claims when
+        # nothing fits. What a rename moves toward, and what the dispatcher
+        # reads on a dry run, which renames nothing, so the preview still
+        # names the agents a real run would start.
+        #
+        # @param subject [Agentilda::Plans::Subject]
+        # @return [Agentilda::Plans::Status]
+        def self.target(subject) = subject.best_fit || subject.status
+
+        # @param tree [Agentilda::Plans::Tree]
+        # @param except [Array<String>] ordinals to leave alone however wrong
+        #   their names are: the dispatcher passes the plans an agent is
+        #   working in right now
+        def initialize(tree:, except: [])
+          @tree = tree
+          @except = except.map(&:to_s)
+        end
+
+        # @return [Agentilda::Plans::Tree]
+        attr_reader :tree
+
+        # What would change, without changing anything. A folder can appear
+        # twice: its spelling migration first, then its status correction.
+        #
+        # @return [Array<Agentilda::Lifecycle::Resync::Dirs::Change>]
+        def plan
+          tree.subjects.flat_map do |subject|
+            @except.include?(subject.feature.ordinal.to_s) ? [] : changes_for(subject)
+          end
+        end
+
+        # @param commit [Boolean] actually rename
+        # @return [Array<Agentilda::Lifecycle::Resync::Dirs::Change>] what was proposed
+        def call(commit: false)
+          changes = plan
+          return changes unless commit
+
+          UI.stepping(changes, "Renaming") { |change| rename(change) }
+          tree.reload
+          changes
+        end
+
+        private
+
+        # A folder moves when the name it has is not the name it should have.
+        # {target} says what that name is; this says how to get there, as up
+        # to two renames applied in order. The status rename starts from where
+        # the spelling rename left the folder, not from where it stands now,
+        # so committing the steps sequentially never renames a path that has
+        # already moved out from under it.
+        #
+        # @param subject [Agentilda::Plans::Subject]
+        # @return [Array<Agentilda::Lifecycle::Resync::Dirs::Change>] empty when the name
+        #   is already right
+        def changes_for(subject)
+          feature = subject.feature
+          fit = self.class.target(subject)
+          steps = []
+
+          spelled = feature.dirname_as(subject.status)
+          if spelled != feature.dirname
+            steps << step(feature,
+              from:   subject.status,
+              to:     subject.status,
+              source: feature.path,
+              reason: spelling_reason(feature))
+          end
+
+          if fit.key != subject.status.key
+            source = steps.empty? ? feature.path : steps.last.target
+            steps << step(feature,
+              from:   subject.status,
+              to:     fit,
+              source:,
+              reason: subject.violation || "contents now justify #{fit.label}")
+          end
+
+          steps
+        end
+
+        # @param feature [Agentilda::Plans::Feature]
+        # @param from [Agentilda::Plans::Status]
+        # @param to [Agentilda::Plans::Status]
+        # @param source [String] absolute path the rename starts from
+        # @param reason [String]
+        # @return [Agentilda::Lifecycle::Resync::Dirs::Change]
+        def step(feature, from:, to:, source:, reason:)
+          Change.new(
+            dirname: File.basename(source),
+            from:    from.key,
+            to:      to.key,
+            source:,
+            target:  File.join(File.dirname(feature.path), feature.dirname_as(to)),
+            reason:
+          )
+        end
+
+        # @param feature [Agentilda::Plans::Feature]
+        # @return [String] why the spelling is wrong, status aside
+        def spelling_reason(feature)
+          return "#{feature.dirname_ordinal} is not padded to #{feature.ordinal}" unless feature.padded?
+
+          "name is not in canonical NNN.MM-<emoji> → <slug> form"
+        end
+
+        # A rename that finds its target occupied has not happened, and saying
+        # nothing about it would leave the folder misnamed with a report
+        # claiming otherwise. Two folders can want the same canonical name —
+        # `018-⚪️--foo` and `018.00-⚪️ → foo` are the same plan written twice.
+        #
+        # @param change [Agentilda::Lifecycle::Resync::Dirs::Change]
+        # @return [void]
+        # @raise [Agentilda::Error] when the target name is already taken
+        def rename(change)
+          return if Agentilda.move_directory(change.source, change.target)
+
+          raise Error, "cannot rename #{change.dirname} — #{File.basename(change.target)} already exists"
+        end
+      end
+
+      # `resync prs` — puts an `[NNN.MM]` prefix on every pull request title that
+      # lacks one, and `[DEV.00]` on the ones that implement no plan.
+      #
+      # The resolution order is the branch name first, then the diff, and only
+      # when the diff touches exactly one plan. Anything else is reported for a
+      # human and never edited: `pull-requests.md` is generated from these
+      # titles, and a wrong number files work under a plan that did not do it,
+      # leaving the plan that did looking untouched.
+      class Prs
+        # The marker this tool used to write, now replaced. A title wearing it is
+        # rewritten in place: the assertion it makes — "this belongs to no
+        # specification" — is still true and still somebody's deliberate call,
+        # so it is restamped rather than re-resolved.
+        STALE = /\A\[#{Regexp.escape(Agentilda::STALE_NO_PLAN_PREFIX)}\]\s*/
+
+        # Titles that already carry a prefix — a plan number, the no-plan marker,
+        # or the legacy `[XXX]`.
+        PREFIXED = /\A\[(?:\d{3}(?:\.\d{2})?|#{Agentilda::NO_PLAN_PREFIX}|XXX)\](?:\([A-Z]\))?\s/
+
+        # Finds a plan number in a branch name: `kig/018.01-verify`, `002-slug`.
+        BRANCH_PATTERN = %r{(?:\A|[/\-_])(\d{3}(?:\.\d{2})?)(?:\z|[-_])}
+
+        # A proposed retitle.
+        #
+        # @!attribute [r] number
+        #   @return [Integer] the pull request
+        # @!attribute [r] title
+        #   @return [String] as it stands
+        # @!attribute [r] new_title
+        #   @return [String, nil] nil when nothing may safely be done
+        # @!attribute [r] ordinal
+        #   @return [Agentilda::Plans::Ordinal, nil]
+        # @!attribute [r] reason
+        #   @return [String] how it was resolved, or why it was not
+        # @!attribute [r] ambiguous
+        #   @return [Boolean] a human must decide; never edited
+        # @!attribute [r] assumed
+        #   @return [Boolean] "no plan" was inferred, not asserted by the author
+        Change = Data.define(:number, :title, :new_title, :ordinal, :reason, :ambiguous, :assumed, :adopted) do
+          # @return [Boolean]
+          def ambiguous? = ambiguous
+
+          # @return [Boolean]
+          def assumed? = assumed
+
+          # @return [Boolean] whether a plan folder was minted for this one
+          def adopted? = adopted
+
+          # @return [Boolean] safe to apply without a human looking
+          def applicable? = !ambiguous && !new_title.nil?
+        end
+
+        # @param tree [Agentilda::Plans::Tree]
+        # @param github [Agentilda::Vcs::GitHub]
+        # @param adopt [Boolean] give a plan folder to every pull request that
+        #   resolves to none, rather than flagging it and moving on
+        # @param root [String, nil] repository root, for reading branches
+        def initialize(tree:, github: Vcs::GitHub.new, adopt: true, root: nil)
+          @tree = tree
+          @github = github
+          @adopt = adopt
+          @root = root
+        end
+
+        # @return [Boolean]
+        def adopt? = @adopt
+
+        # @return [Agentilda::Plans::Tree]
+        attr_reader :tree
+
+        # @return [Agentilda::Vcs::GitHub]
+        attr_reader :github
+
+        # What would change, without changing anything.
+        #
+        # @return [Array<Agentilda::Lifecycle::Resync::Prs::Change>]
+        def plan
+          restamps + resolve(candidates).then { |changes| adopt? ? with_adoptions(changes) : changes }
+        end
+
+        # @return [Array<Agentilda::Lifecycle::Resync::Prs::Change>]
+        def restamps = stale.map { |pull| restamped(pull) }
+
+        # @param commit [Boolean] actually retitle, and mint the folders
+        # @return [Array<Agentilda::Lifecycle::Resync::Prs::Change>] what was proposed
+        def call(commit: false)
+          changes = resolve(candidates)
+          return restamps + (adopt? ? with_adoptions(changes) : changes) unless commit
+
+          changes = with_adoptions(changes, create: true) if adopt?
+          changes = restamps + changes
+          applicable = changes.select(&:applicable?)
+          UI.stepping(applicable, "Retitling") { |c| github.retitle(number: c.number, title: c.new_title) }
+          changes
+        end
+
+        # @return [Array<Agentilda::Lifecycle::Adoption>] the adopter, memoized
+        def adoption = @adoption ||= Adoption.new(tree:, github:, root: @root)
+
+        private
+
+        # @return [Array<Hash>] pull requests with no prefix yet
+        def candidates
+          github.pulls.reject { |pr| pr[:title].to_s.match?(PREFIXED) || pr[:title].to_s.match?(STALE) }
+        end
+
+        # @return [Array<Hash>] pull requests still wearing the old marker
+        def stale = github.pulls.select { |pr| pr[:title].to_s.match?(STALE) }
+
+        # @param pull [Hash]
+        # @return [Agentilda::Lifecycle::Resync::Prs::Change]
+        def restamped(pull)
+          Change.new(number: pull[:number],
+            title: pull[:title],
+            ordinal: nil,
+            ambiguous: false,
+            new_title: pull[:title].sub(STALE, "[#{Agentilda::NO_PLAN_PREFIX}] "),
+            reason: "the no-plan marker is now [#{Agentilda::NO_PLAN_PREFIX}]",
+            assumed: false,
+            adopted: false)
+        end
+
+        # @param pulls [Array<Hash>]
+        # @return [Array<Agentilda::Lifecycle::Resync::Prs::Change>]
+        def resolve(pulls) = pulls.map { |pr| change_for(pr) }
+
+        # Replace every flagged change with one that points at a plan folder the
+        # pull request now owns. The unresolvable ones were unresolvable because
+        # no plan described them — so the answer is a plan, not a shrug.
+        #
+        # @param changes [Array<Agentilda::Lifecycle::Resync::Prs::Change>]
+        # @param create [Boolean] mint the folders, rather than only saying so
+        # @return [Array<Agentilda::Lifecycle::Resync::Prs::Change>]
+        def with_adoptions(changes, create: false)
+          orphans = changes.select(&:ambiguous?)
+          return changes if orphans.empty?
+
+          pulls = orphans.map { |c| pull_by_number.fetch(c.number) }
+          adoptees = create ? adoption.call(pulls) : adoption.plan(pulls)
+          by_number = adoptees.to_h { |a| [a.pull[:number], a] }
+
+          changes.map { |c| c.ambiguous? && by_number[c.number] ? adopted(c, by_number[c.number]) : c }
+        end
+
+        # @return [Hash{Integer => Hash}]
+        def pull_by_number = @pull_by_number ||= candidates.to_h { |pr| [pr[:number], pr] }
+
+        # @param change [Agentilda::Lifecycle::Resync::Prs::Change]
+        # @param adoptee [Agentilda::Lifecycle::Adoption::Adoptee]
+        # @return [Agentilda::Lifecycle::Resync::Prs::Change]
+        def adopted(change, adoptee)
+          change.with(
+            ordinal:   adoptee.ordinal,
+            new_title: "#{adoptee.ordinal.to_prefix} #{change.title}",
+            reason:    "#{change.reason} — adopted into #{adoptee.dirname}",
+            ambiguous: false,
+            adopted:   true
+          )
+        end
+
+        # @param pull [Hash]
+        # @return [Agentilda::Lifecycle::Resync::Prs::Change]
+        def change_for(pull)
+          from_branch(pull) || from_files(pull) || no_plan(pull)
+        end
+
+        # 1. The branch name — the one moment the author certainly knew.
+        #
+        # @param pull [Hash]
+        # @return [Agentilda::Lifecycle::Resync::Prs::Change, nil]
+        def from_branch(pull)
+          match = BRANCH_PATTERN.match(pull[:branch].to_s) or return nil
+          ordinal = Plans::Ordinal.parse(match[1])
+
+          unless tree.include?(ordinal)
+            return flag(pull, "branch names #{ordinal}, which has no folder in #{File.basename(tree.dir)}")
+          end
+
+          resolved(pull, ordinal, "branch #{pull[:branch]}")
+        end
+
+        # 2. The diff, and only when it touches exactly one plan.
+        #
+        # @param pull [Hash]
+        # @return [Agentilda::Lifecycle::Resync::Prs::Change, nil]
+        def from_files(pull)
+          touched = Array(pull[:files]).filter_map { |path| ordinal_for_path(path) }.uniq
+          case touched.size
+          when 1 then resolved(pull, touched.first, "diff touches only #{touched.first}")
+          when 0 then nil
+          else flag(pull, "diff touches #{touched.join(", ")} and none is obviously primary")
+          end
+        end
+
+        # @param path [String] a path from the diff
+        # @return [Agentilda::Plans::Ordinal, nil]
+        def ordinal_for_path(path)
+          parts = path.to_s.split("/")
+          index = parts.index(Agentilda::PLANS_DIR) or return nil
+          folder = parts[index + 1] or return nil
+          return nil if parts.length <= index + 2 # a file directly under .plans belongs to no plan
+
+          ordinal = Plans::Ordinal.from_dirname(folder)
+          ordinal if ordinal && tree.include?(ordinal)
+        end
+
+        # @param pull [Hash]
+        # @param ordinal [Agentilda::Plans::Ordinal]
+        # @param why [String]
+        # @return [Agentilda::Lifecycle::Resync::Prs::Change]
+        def resolved(pull, ordinal, why)
+          Change.new(number: pull[:number],
+            title: pull[:title],
+            ordinal:,
+            reason: why,
+            new_title: "#{ordinal.to_prefix} #{pull[:title]}",
+            ambiguous: false,
+            assumed: false,
+            adopted: false)
+        end
+
+        # Nothing resolved, so this is developer work — but that is an assertion
+        # about intent, so it is marked as assumed rather than stated as fact.
+        #
+        # @param pull [Hash]
+        # @return [Agentilda::Lifecycle::Resync::Prs::Change]
+        def no_plan(pull)
+          Change.new(number: pull[:number],
+            title: pull[:title],
+            ordinal: nil,
+            new_title: "[#{Agentilda::NO_PLAN_PREFIX}] #{pull[:title]}",
+            reason: "no plan resolved from the branch or the diff",
+            ambiguous: false,
+            assumed: true,
+            adopted: false)
+        end
+
+        # @param pull [Hash]
+        # @param why [String]
+        # @return [Agentilda::Lifecycle::Resync::Prs::Change]
+        def flag(pull, why)
+          Change.new(number: pull[:number],
+            title: pull[:title],
+            new_title: nil,
+            ordinal: nil,
+            reason: why,
+            ambiguous: true,
+            assumed: false,
+            adopted: false)
+        end
+      end
+    end
+  end
+end

data/lib/agentilda/lifecycle/unblocker.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Lifecycle
+    # 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::Plans::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::Plans::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::Plans::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::Plans::Subject]
+      # @return [Array<Question>]
+      def self.questions(subject)
+        answered = subject.block_answers
+
+        subject.read("blocked.md").to_s.lines.grep(Plans::OPEN_BLOCK).map do |line|
+          number = line[Plans::OPEN_BLOCK, 1].to_i
+          Question.new(number:, heading: line.strip.sub(/\A\#+[ \t]*/, ""), answered: answered.include?(number))
+        end
+      end
+
+      # @param tree [Agentilda::Plans::Tree]
+      # @param agent [Agentilda::Agents::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::Plans::Tree]
+      attr_reader :tree
+
+      # @return [Agentilda::Agents::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::Plans::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),
+          file:   ->(_) { "blocked.md" },
+          root:) do |subject, progress|
+          # After ctrl-c the plans not yet started stay as they are, blocked.md
+          # untouched, so the next run picks them up from the beginning.
+          next [false, "not started: interrupted by ctrl-c"] if Execution::Control.interrupted?
+
+          invoke(subject, progress)
+        end
+
+        settle
+        subjects.zip(results).map { |subject, result| outcome(subject, result, before) }
+      end
+
+      private
+
+      # @param subject [Agentilda::Plans::Subject]
+      # @param progress [Agentilda::UI::Line] a dashboard row carries the
+      #   executor handle its kill and extend keys act on; a plain line does not
+      # @return [Array(Boolean, String)]
+      def invoke(subject, progress)
+        handle = progress.handle if progress.is_a?(Presentation::Dashboard::Tracker)
+        @executor.call(agent, subject, root:, handle:, &progress)
+      rescue StandardError => 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::Plans::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::Plans::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::Plans::Subject]
+      # @return [String]
+      def label(subject) = "#{subject.feature.ordinal} → #{agent.name}"
+
+      # @param subject [Agentilda::Plans::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
+end

data/lib/agentilda/lifecycle.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # Operations that change which plans exist or what they are called:
+  # minting a folder, drafting its brief, adopting an orphan pull request,
+  # reconciling names with contents, and draining answered questions.
+  module Lifecycle
+    module_function
+
+    # @param dir [String] the `.plans` directory
+    # @param options [Hash] passed to {Creator#create}
+    # @return [Dry::Monads::Result] Success(path) or Failure(message)
+    def create(dir:, **) = Creator.new(dir:).create(**)
+
+    # @param tree [Agentilda::Plans::Tree]
+    # @return [Agentilda::Lifecycle::Resync::Dirs]
+    def resync_dirs(tree:, **) = Resync::Dirs.new(tree:, **)
+
+    # @return [Agentilda::Lifecycle::Resync::Prs]
+    def resync_prs(**) = Resync::Prs.new(**)
+
+    # @return [Agentilda::Lifecycle::Brief]
+    def brief(**) = Brief.new(**)
+
+    # @return [Agentilda::Lifecycle::Unblocker]
+    def unblocker(**) = Unblocker.new(**)
+  end
+end

data/lib/agentilda/linear/api.rb

@@ -6,7 +6,7 @@ require "uri"
 
 module Agentilda
   module Linear
-    # Linear's GraphQL API, wrapped as thinly as {Agentilda::GitHub} wraps
+    # Linear's GraphQL API, wrapped as thinly as {Agentilda::Vcs::GitHub} wraps
     # `gh`, and for the same reason: it is a seam. Every example in the suite
     # injects a transport here, so nothing in the tests reaches Linear.
     #