agentilda 1.0.3

data/lib/agentilda/cli/unblock/unblock.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda unblock NNN…` — hand a stopped plan to the agent that
+    # drains its `blocked.md`.
+    #
+    # Deliberately not part of `run`. ⭕️ and 🅱️ are {StateMachine::SETTLED}, so
+    # the loop never offers a blocked plan to anybody, and that is the property
+    # that makes the state mean anything: the plan waits for a human, and no
+    # agent quietly decides otherwise. Answers arriving is not a fact the tool
+    # can observe, so a human typing this command *is* the signal, and there is
+    # nothing else that could produce it.
+    class Unblock < Base
+      # The agent that knows the shape of `blocked.md`.
+      DEFAULT_AGENT = "lando-broker"
+
+      # What each token turned out to be, for whoever has to fix it.
+      PROBLEMS = {
+        missing: "no plan of that number",
+        not_blocked: "no blocked.md, so there is nothing to drain"
+      }.freeze
+
+      desc "Fold answered blocks into a plan's documents and retire blocked.md"
+
+      argument :plans, type: :array, required: true,
+        desc: "Which plans to drain: NNN or NNN.MM, e.g. 003 005.01"
+
+      option :commit, type: :boolean, default: false,
+        desc: "Actually invoke the agent (default: dry run, prints the questions still open)"
+      option :agent, default: DEFAULT_AGENT, desc: "Hand the folder to a different agent"
+      option :root, desc: "Repository root the agent works in (default: the .plans parent)"
+
+      example [
+        "003                # what 003 is still waiting on",
+        "003 --commit       # fold in whatever has been answered",
+        "003,005 --commit   # both"
+      ]
+
+      # @param plans [Array<String>]
+      # @param options [Hash]
+      # @return [void]
+      def call(plans:, **options)
+        tree = tree_for(options)
+        quiet?(options)
+        unblocker = Unblocker.new(tree:, agent: agent_for(options), root: options[:root],
+          commit: commit?(options), executor: Executor.new(root: options[:root] || File.dirname(tree.dir),
+            dry_run: !commit?(options)))
+
+        targets = unblocker.resolve(plans)
+        refused(targets, tree, options)
+        subjects = targets.select(&:drainable?).map(&:subject)
+        exit(worst(targets, [])) if subjects.empty?
+
+        credentials_warning if commit?(options) && !quiet?(options)
+        preflight(subjects, unblocker, options)
+
+        outcomes = unblocker.call(subjects)
+        outcomes.each { |outcome| report(outcome, options) }
+        footer(outcomes, options) unless quiet?(options)
+        exit(worst(targets, outcomes))
+      end
+
+      private
+
+      # @param options [Hash]
+      # @return [Agentilda::Agent]
+      def agent_for(options)
+        name = options.fetch(:agent, DEFAULT_AGENT)
+        agents = Agentilda::Agents.new
+        agents.find(name) or
+          refuse("No agent called #{name}.\n\nKnown: #{agents.all.map(&:name).join(", ")}", 65)
+      end
+
+      # A number that names no folder, or a folder that was never stopped, is
+      # refused rather than skipped. Whoever typed this believes an answer has
+      # arrived; running against a folder nobody blocked and saying nothing is
+      # how you come back later to a plan nobody touched and no record of why.
+      #
+      # Every bad token is reported, not just the first, because stopping at
+      # the first one hides the rest of the answer.
+      #
+      # @param targets [Array<Agentilda::Unblocker::Target>]
+      # @param tree [Agentilda::Tree]
+      # @param options [Hash]
+      # @return [void]
+      def refused(targets, tree, options)
+        problems = targets.reject(&:drainable?)
+        return if problems.empty?
+
+        problems.each do |target|
+          state = target.subject ? target.subject.status.key : "unknown"
+          puts "#{target.token}\t#{state}\t0 open\t#{PROBLEMS.fetch(target.problem)}"
+        end
+        return if quiet?(options)
+
+        error("#{problems.size} of the plans named cannot be drained:\n\n" +
+              problems.map { |t| "  #{t.token} — #{PROBLEMS.fetch(t.problem)}" }.join("\n") +
+              "\n\nThe tree holds: #{tree.ordinals.join(", ")}")
+      end
+
+      # What each folder is waiting on, said BEFORE the agent is invoked.
+      #
+      # This is the half that was missing. `--commit` hands the folder to an
+      # agent that can take a quarter of an hour, and until it came back the
+      # terminal showed nothing at all — a run that had found nothing to do and
+      # a run still working looked exactly alike.
+      #
+      # @param subjects [Array<Agentilda::Subject>]
+      # @param unblocker [Agentilda::Unblocker]
+      # @param options [Hash]
+      # @return [void]
+      def preflight(subjects, unblocker, options)
+        return if quiet?(options)
+
+        subjects.each do |subject|
+          questions = Unblocker.questions(subject)
+          answered = questions.count(&:answered)
+          say("#{paint(subject.feature.ordinal.to_s, :bright_black)} #{subject.status.emoji} " \
+              "#{subject.feature.title} — #{summary(questions.size, answered)}")
+          detail(subject, questions)
+        end
+      end
+
+      # @param open [Integer]
+      # @param answered [Integer]
+      # @return [String]
+      def summary(open, answered)
+        return "nothing open" if open.zero?
+
+        "#{open} open, #{answered.zero? ? "none answered yet" : "#{answered} with an answer waiting"}"
+      end
+
+      # @param subject [Agentilda::Subject]
+      # @param questions [Array<Agentilda::Unblocker::Question>]
+      # @return [void]
+      def detail(subject, questions)
+        if subject.unreadable_block?
+          say("  #{paint("blocked.md names no `## B<n>` question, so nothing here can be drained", :red)}",
+            bullet: " ")
+          say("  #{paint("Number each open question `## B1`, `## B2`, and each answer `## A1`, `## A2`.", :yellow)}",
+            bullet: " ")
+        elsif questions.empty?
+          say("  #{paint("nothing left open", :green)}", bullet: " ")
+        else
+          questions.each { |question| say("  #{paint(question.to_s, :yellow)}", bullet: " ") }
+        end
+      end
+
+      # One plan, after the fact: the deliverable line on STDOUT, and what
+      # changed on STDERR.
+      #
+      # @param outcome [Agentilda::Unblocker::Outcome]
+      # @param options [Hash]
+      # @return [void]
+      def report(outcome, options)
+        moved = movement(outcome, commit?(options))
+        puts "#{outcome.ordinal}\t#{outcome.ok ? outcome.subject.status.key : "failed"}\t" \
+             "#{outcome.after.size} open\t#{moved}\t#{outcome.note}"
+        # A dry run changed nothing, so the preflight above it is still the
+        # whole truth. Printing the same three lines again reads as a second
+        # pass that found the same thing, which is not what happened.
+        return if quiet?(options) || !commit?(options)
+
+        say("#{paint(outcome.ordinal.to_s, :bright_black)} #{outcome.subject.status.emoji} " \
+            "#{outcome.subject.feature.title} — #{paint(moved, outcome.ok ? :green : :red)}")
+        detail(outcome.subject, outcome.after)
+      end
+
+      # What the file says happened, rather than what the agent claims. The
+      # questions are counted off disk on both sides of the run.
+      #
+      # @param outcome [Agentilda::Unblocker::Outcome]
+      # @param commit [Boolean]
+      # @return [String]
+      def movement(outcome, commit)
+        return "failed" unless outcome.ok
+        return "not attempted" unless commit
+        return "blocked.md retired" if outcome.cleared?
+        return "nothing folded" if outcome.folded.empty?
+
+        "folded #{outcome.folded.map { |n| "B#{n}" }.join(", ")}"
+      end
+
+      # @param outcomes [Array<Agentilda::Unblocker::Outcome>]
+      # @param options [Hash]
+      # @return [void]
+      def footer(outcomes, options)
+        failed = outcomes.reject(&:ok)
+
+        unless commit?(options)
+          warn("Dry run: no agent was invoked, and #{outcomes.size} " \
+               "plan#{"s" unless outcomes.size == 1} #{(outcomes.size == 1) ? "is" : "are"} unchanged.\n" \
+               "Re-run with --commit to fold in whatever has been answered.")
+          return
+        end
+
+        return error(failed.map { |o| "#{o.ordinal}: #{o.note}" }.join("\n")) unless failed.empty?
+
+        cleared = outcomes.count(&:cleared?)
+        folded = outcomes.sum { |o| o.folded.size }
+        waiting = outcomes.sum { |o| o.after.size }
+        success("#{folded} question#{"s" unless folded == 1} folded in · " \
+                "#{cleared} plan#{"s" unless cleared == 1} out of the block · " \
+                "#{waiting} still waiting on a human." +
+                (folded.zero? ? "\n\nNothing moved. An answer has to be written into blocked.md as its own " \
+                                "`## A<n>` section, answering the `## B<n>` of the same number, before " \
+                                "there is anything to fold." : ""))
+      end
+
+      # The most serious thing that happened, as an exit status. A tree that
+      # was partly drained still exits non-zero when part of it could not be.
+      #
+      # @param targets [Array<Agentilda::Unblocker::Target>]
+      # @param outcomes [Array<Agentilda::Unblocker::Outcome>]
+      # @return [Integer]
+      def worst(targets, outcomes)
+        problems = targets.map(&:problem)
+        return 66 if problems.include?(:missing)
+        return 65 if problems.include?(:not_blocked)
+        return 1 unless outcomes.all?(&:ok)
+
+        0
+      end
+    end
+  end
+end

data/lib/agentilda/cli/version/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module CLI
+    # `agentilda version`
+    class Version < Dry::CLI::Command
+      desc "Print the version and exit"
+
+      # @return [void]
+      def call(**) = puts("agentilda #{Agentilda::VERSION}")
+    end
+  end
+end

data/lib/agentilda/cli.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "dry/cli/autocomplete/command"
+
+# One file per command, `subcommands/` under the prefixed ones. Base carries
+# the shared flags and plumbing, so it loads first; the rest only meet each
+# other here, at registration.
+require_relative "cli/base"
+require_relative "cli/create/create"
+require_relative "cli/index/index"
+require_relative "cli/list_plans/list_plans"
+require_relative "cli/resync/subcommands/dirs"
+require_relative "cli/resync/subcommands/prs"
+require_relative "cli/linear/linear"
+require_relative "cli/linear/subcommands/projects"
+require_relative "cli/linear/subcommands/import"
+require_relative "cli/docs/docs"
+require_relative "cli/run/run"
+require_relative "cli/unblock/unblock"
+require_relative "cli/version/version"
+require_relative "cli/states/states"
+require_relative "cli/agents/subcommands/list"
+require_relative "cli/agents/subcommands/describe"
+
+module Agentilda
+  # The command line. Every command is a thin shell over one library class:
+  # it parses flags, calls one object, and prints the result.
+  #
+  # Two conventions hold throughout:
+  #
+  #   * The deliverable goes to STDOUT, progress and boxes go to STDERR, so
+  #     every command composes in a pipe.
+  #   * Anything that writes to disk or to GitHub is DRY RUN by default and
+  #     needs `--commit`. Folder names and pull request titles are joined on by
+  #     branches, `pull-requests.md` and merged history; changing one silently
+  #     is how a plan ends up filed under work it did not do.
+  module CLI
+    extend Dry::CLI::Registry
+
+    register "create", Create, aliases: %w[new c]
+    # Renamed from `status`, which read as "is the tool OK?" rather than "what
+    # plans are there?". The old spellings stay registered: other repos, agent
+    # prompts and scripts call this by name.
+    register "list-plans", ListPlans, aliases: %w[status st]
+    register "run", Run
+    register "unblock", Unblock
+    register "docs", Docs
+    register "states", States, aliases: %w[diagram]
+    register "index", Index, aliases: %w[idx]
+    register "version", Version, aliases: %w[--version -v]
+
+    register "agents" do |prefix|
+      prefix.register "list", Agents::List, aliases: %w[ls]
+      prefix.register "describe", Agents::Describe, aliases: %w[show]
+    end
+
+    # `describe <name>` without the `agents` in front of it. The bare verb is
+    # how people ask for this out loud, and a near miss that prints usage is a
+    # worse answer than the thing they wanted.
+    register "describe", Agents::Describe
+
+    register "resync" do |prefix|
+      prefix.register "dirs", Resync::Dirs
+      prefix.register "prs", Resync::Prs
+    end
+
+    register "linear" do |prefix|
+      prefix.register "import", Linear::Import
+      prefix.register "projects", Linear::Projects
+    end
+
+    register "completion", ::Dry::CLI::Autocomplete::Command[::Agentilda::CLI]
+  end
+end

data/lib/agentilda/config.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Agentilda
+  # Default option overrides, read from `~/.local/config/agentilda.json`.
+  #
+  # The file is keyed by command, so it can grow without every command
+  # seeing every key:
+  #
+  #   {
+  #     "run": { "timeout": 1800, "jobs": 4 }
+  #   }
+  #
+  # Precedence is: an option passed on the command line, then this file,
+  # then the built-in default. The file supplies *defaults*, never
+  # mandates — nothing here can force `--commit`, which stays a flag a
+  # person types.
+  #
+  # An unreadable file is an error, not a shrug: a config silently ignored
+  # is how a timeout somebody set stops applying with no signal anywhere.
+  class Config
+    PATH = File.join(Dir.home, ".local", "config", "agentilda.json")
+
+    # @param command [Symbol, String] the command whose section to read
+    # @param path [String] the config file
+    # @return [Hash{Symbol => Object}] that command's overrides, {} when the
+    #   file or the section is absent
+    # @raise [Agentilda::Error] when the file exists and cannot be used
+    def self.for(command, path: PATH)
+      return {} unless File.file?(path)
+
+      data = JSON.parse(File.read(path))
+      raise Error, "#{path}: expected a JSON object keyed by command" unless data.is_a?(Hash)
+
+      section = data.fetch(command.to_s, {})
+      raise Error, "#{path}: \"#{command}\" must be a JSON object" unless section.is_a?(Hash)
+
+      section.transform_keys(&:to_sym)
+    rescue JSON::ParserError => e
+      raise Error, "#{path} is not valid JSON: #{e.message.lines.first.to_s.strip}"
+    end
+  end
+end

data/lib/agentilda/control.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # The side channel between a keypress and a running agent.
+  #
+  # `claude -p` takes no input once it starts, so the only way to reach an
+  # agent mid-flight is a file it has been told to poll: each invocation gets
+  # a control file of its own, named in its prompt, and a keypress writes a
+  # word into every file currently registered. Like everything else about the
+  # prompt this is a request — an agent deep in a tool call reads the file at
+  # its next step, not instantly — which is why {#quit!} also arms a deadline
+  # the {Executor} checks, so "quit" is eventually a guarantee too.
+  module Control
+    # What a keypress writes into a control file. One word, one line, so an
+    # agent can act on `File.read(path).strip` and nothing subtler.
+    WRAP_UP = "WRAP_UP"
+    STOP = "STOP"
+
+    # Seconds between {#quit!} and the harness terminating whatever is still
+    # running. Long enough to write files and a handoff note; short enough
+    # that q means quit rather than "quit eventually".
+    GRACE = 60
+
+    @mutex = Mutex.new
+    @files = []
+    @quit = false
+    @deadline = nil
+
+    class << self
+      # Register a fresh control file for one invocation and hand back its
+      # path, to be named in the agent's prompt.
+      #
+      # @param dir [String] where the file lives (the trace dir — outside the
+      #   repository for the same reason traces are)
+      # @param name [String] something findable: plan ordinal and agent name
+      # @return [String]
+      def register(dir, name)
+        FileUtils.mkdir_p(dir)
+        path = File.join(dir, "control-#{name}-#{Process.pid}-#{format("%04x", rand(0x10000))}")
+        File.write(path, "")
+        @mutex.synchronize { @files << path }
+        path
+      end
+
+      # Forget a finished invocation's file. The file itself is removed so a
+      # crashed run does not leave stale STOPs for the next one to find.
+      #
+      # @param path [String]
+      # @return [void]
+      def release(path)
+        @mutex.synchronize { @files.delete(path) }
+        FileUtils.rm_f(path)
+      end
+
+      # `w`: every running agent is asked to finish the essential remainder
+      # as fast as it can. The loop itself keeps going.
+      #
+      # @return [void]
+      def wrap_up! = broadcast(WRAP_UP)
+
+      # `n`: every running agent is asked to write out what it has and end
+      # its turn. The loop keeps going — under chaining that is exactly what
+      # hands the plan to the next agent.
+      #
+      # @return [void]
+      def stop! = broadcast(STOP)
+
+      # `q`: {#stop!}, plus the loop ends after this round, plus a deadline —
+      # {GRACE} seconds from now — after which the {Executor} aborts whatever
+      # is still running rather than waiting on its goodwill.
+      #
+      # @return [void]
+      def quit!
+        stop!
+        @mutex.synchronize {
+          @quit = true
+          @deadline ||= UI.monotonic + GRACE
+        }
+      end
+
+      # @return [Boolean] whether `q` has been pressed
+      def quit? = @mutex.synchronize { @quit }
+
+      # @return [Boolean] whether the grace period after `q` has run out
+      def overdue?
+        @mutex.synchronize { !@deadline.nil? && UI.monotonic > @deadline }
+      end
+
+      # Back to rest, for the next `Runner#call` — and for the suite, where
+      # one example's q must not quit every example after it.
+      #
+      # @return [void]
+      def reset!
+        @mutex.synchronize {
+          @files.each { |f| FileUtils.rm_f(f) }
+          @files.clear
+          @quit = false
+          @deadline = nil
+        }
+      end
+
+      private
+
+      # @param word [String]
+      # @return [void]
+      def broadcast(word)
+        @mutex.synchronize { @files.dup }.each do |path|
+          File.write(path, "#{word}\n")
+        rescue SystemCallError
+          # A file whose invocation just finished is not an error to miss.
+        end
+      end
+    end
+  end
+end

data/lib/agentilda/creator.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # Mints new plan folders. Backs `/spec-create`.
+  #
+  # Every failure is a `Failure`, never an exception: creating a folder is the
+  # one place a typo becomes permanent, so the caller is made to look.
+  class Creator
+    include Dry::Monads[:result]
+
+    # The state a new plan opens in — a specification and nothing else yet.
+    DEFAULT_STATUS = :new
+
+    # The state a retroactive plan is born in: the work is live, but it has
+    # neither a specification nor a plan.
+    RETROACTIVE_STATUS = :retroactive
+
+    # @param dir [String] the `.plans` directory
+    def initialize(dir:)
+      @dir = File.expand_path(dir)
+    end
+
+    # @return [String] the `.plans` directory
+    attr_reader :dir
+
+    # Create a plan folder.
+    #
+    # @param words [Array<String>] the topic; becomes the slug
+    # @param after [String, nil] anchor for a retroactive plan, e.g. "002"
+    # @param status [String, Symbol, nil] override the default state
+    # @param prs [Array<Hash>, nil] pull requests to record, already fetched;
+    #   their presence is what makes the folder 🕰️ Retroactive rather than ⚪️
+    # @return [Dry::Monads::Result] Success(absolute path) or Failure(message)
+    def create(words:, after: nil, status: nil, prs: nil)
+      resolved = resolve_status(status, after) or
+        return Failure("unknown status: #{status}")
+
+      slug = self.class.slugify(words)
+      return Failure("the topic produced an empty slug") if slug.empty?
+
+      ordinal = after ? retroactive_ordinal(after) : Ordinal.next_major(existing)
+      return ordinal if ordinal.is_a?(Dry::Monads::Result)
+
+      build(ordinal, resolved, slug).fmap { |path| record_pull_requests(path, prs) }
+    rescue Agentilda::Error => e
+      Failure(e.message)
+    end
+
+    # @return [Array<Agentilda::Ordinal>] every number already taken
+    def existing
+      @existing ||= begin
+        return [] unless File.directory?(dir)
+
+        Dir.children(dir)
+          .select { |c| File.directory?(File.join(dir, c)) }
+          .filter_map { |c| Ordinal.from_dirname(c) }
+      end
+    end
+
+    # Turn free text into the kebab tail of a folder name.
+    #
+    # @param words [Array<String>, String]
+    # @return [String] possibly empty, which the caller must reject
+    def self.slugify(words)
+      Array(words).join(" ").downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+    end
+
+    private
+
+    # @param status [String, Symbol, nil]
+    # @param after [String, nil]
+    # @return [Agentilda::Status, nil]
+    def resolve_status(status, after)
+      return Agentilda.status(status) if status
+
+      STATUS_BY_KEY.fetch(after ? RETROACTIVE_STATUS : DEFAULT_STATUS)
+    end
+
+    # @param after [String]
+    # @return [Agentilda::Ordinal, Dry::Monads::Result]
+    def retroactive_ordinal(after)
+      anchor = Ordinal.parse(after) or return Failure("not a plan number: #{after}")
+
+      unless existing.any? { |o| o.major == anchor.major }
+        return Failure("no plan #{format("%03d", anchor.major)} to anchor against — " \
+                       "a retroactive plan names the plan its work landed after")
+      end
+
+      Ordinal.next_minor(existing, major: anchor.major)
+    end
+
+    # Write the pull requests the folder was created from, so 🕰️ Retroactive
+    # is justified the moment the folder exists — that state means "the work is
+    # live and undocumented", and it is the recorded pull requests that make
+    # the first half of that true.
+    #
+    # @param path [String] the new folder
+    # @param prs [Array<Hash>, nil]
+    # @return [String] the path, unchanged
+    def record_pull_requests(path, prs)
+      return path if prs.nil? || prs.empty?
+
+      File.write(File.join(path, PullRequests::FILENAME), PullRequests.render(prs))
+      path
+    end
+
+    # @param ordinal [Agentilda::Ordinal]
+    # @param status [Agentilda::Status]
+    # @param slug [String]
+    # @return [Dry::Monads::Result]
+    def build(ordinal, status, slug)
+      target = File.join(dir, Agentilda.plan_dirname(ordinal, status, slug))
+      return Failure("already exists: #{File.basename(target)}") if File.exist?(target)
+
+      FileUtils.mkdir_p(target)
+      @existing = nil
+      Success(target)
+    end
+  end
+end

data/lib/agentilda/dev_work.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # Telling "this belongs to no specification" apart from "nobody could tell".
+  #
+  # Both end up without a plan number, and filing them under one marker loses
+  # the difference between a finished thought and an open question. A
+  # dependency bump genuinely implements no specification and never will —
+  # that is an assertion, and `[dev]` records it. A pull request that adds
+  # Schedule K-1 for four tax years plainly implements *something*; nothing
+  # here could work out what, and `[none]` records that instead, as a job left
+  # for a human rather than a verdict.
+  #
+  # The bar for `[dev]` is deliberately high. Marking real work as `[dev]`
+  # tells everyone afterwards it was never worth a plan, and nobody re-opens a
+  # question that looks settled. `[none]` is visibly unfinished, so the cost of
+  # guessing wrong in that direction is somebody spending a minute on it.
+  module DevWork
+    module_function
+
+    # Titles that say what they are: dependency bumps, release chores, CI.
+    TITLES = [
+      /\Abump\s+\S+\s+from\s+\S+\s+to\s+\S+/i,
+      /\A(?:chore|ci|build|deps|style|refactor)(?:\([^)]*\))?:/i,
+      /\Abump\s+(?:to\s+)?v?\d+\.\d+/i
+    ].freeze
+
+    # Paths that are how the project is built rather than what it does.
+    PLUMBING = %r{\A(?:\.github/|\.circleci/|\.devcontainer/|bin/|scripts/|
+                       Dockerfile|\.dockerignore|Gemfile(?:\.lock)?|justfile|Rakefile|
+                       \.rubocop\.ya?ml|\.standard\.ya?ml|\.gitignore|\.tool-versions)}x
+
+    # Files that say nothing either way, so they neither prove plumbing nor
+    # disprove it — every pull request in this tool's world touches `.plans`.
+    NEUTRAL = %r{\A(?:#{PLANS_DIR}/|CHANGELOG|README)}
+
+    # @param title [String]
+    # @param files [Array<String>] paths in the diff
+    # @return [Boolean] whether this can be *asserted* to implement no plan
+    def developer?(title, files = [])
+      return true if TITLES.any? { |pattern| title.to_s.match?(pattern) }
+
+      judged = Array(files).reject { |path| path.match?(NEUTRAL) }
+      return false if judged.empty?
+
+      judged.all? { |path| path.match?(PLUMBING) }
+    end
+
+    # @param title [String]
+    # @param files [Array<String>]
+    # @return [String] the marker to stamp on it
+    def marker(title, files = []) = developer?(title, files) ? NO_PLAN_PREFIX : NONE_PREFIX
+  end
+end