agentilda 1.0.3

data/lib/agentilda/feature.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # Lowercase in the middle of a title, capitalised at the front.
+  SMALL_WORDS = %w[a an and as at but by for from in into nor of on or per the to via vs with].freeze
+
+  # Slug words that are really acronyms and should shout.
+  ACRONYMS = %w[
+    abac ai api aws cdn ci cd cli cms cors cpu crm css csv db dns dsl e2e ec2 etl gcp gdpr gpu gui
+    html http https iam id ide jwt json k8s llm ml mcp mvp npm oauth orm otp pdf pii poc pr prs qa
+    rbac rds rest rls rpc rss s3 saas sdk seo sns spa sql sqs sre ssh sso ssl ssr tls tui ts tsx ui
+    ux uuid vpc vpn xml yaml
+  ].freeze
+
+  # Words with a house spelling that neither capitalize nor upcase gets right.
+  SPECIAL_CASE = {
+    "github" => "GitHub", "gitlab" => "GitLab", "graphql" => "GraphQL", "ios" => "iOS",
+    "javascript" => "JavaScript", "macos" => "macOS", "nodejs" => "Node.js", "oauth" => "OAuth",
+    "openai" => "OpenAI", "postgres" => "PostgreSQL", "postgresql" => "PostgreSQL",
+    "typescript" => "TypeScript", "uuidv7" => "UUIDv7", "websocket" => "WebSocket"
+  }.freeze
+
+  # Turn a kebab slug into a proper name: `law-as-data` → "Law as Data".
+  #
+  # @param slug [String]
+  # @return [String]
+  def self.titleize(slug)
+    words = slug.to_s.split(/[-_\s.]+/).reject(&:empty?)
+    return "" if words.empty?
+
+    words.each_with_index.map { |word, i|
+      lower = word.downcase
+      if SPECIAL_CASE.key?(lower)
+        SPECIAL_CASE[lower]
+      elsif ACRONYMS.include?(lower)
+        lower.upcase
+      elsif i.positive? && SMALL_WORDS.include?(lower)
+        lower
+      elsif lower.match?(/\A\d+\z/)
+        lower
+      else
+        lower.sub(/\A./, &:upcase)
+      end
+    }.join(" ")
+  end
+
+  # The one place a plan folder's name is spelled out: `NNN.MM-<emoji>--<slug>`.
+  #
+  # The double dash after the emoji is deliberate: an emoji renders two cells
+  # wide and visually swallows a single dash beside it, so `🔎-refactor` reads
+  # as if the emoji and the slug were touching. Everything that mints or
+  # renames a folder goes through here; {Feature.parse} accepts the older
+  # single-dash spelling too, and `resync dirs` normalises it on contact.
+  #
+  # @param ordinal [Agentilda::Ordinal, String]
+  # @param status [Agentilda::Status]
+  # @param slug [String]
+  # @return [String]
+  def self.plan_dirname(ordinal, status, slug) = "#{ordinal}-#{status.emoji}--#{slug}"
+
+  # One `NNN.MM-<emoji>--<slug>` folder, decoded.
+  #
+  # @!attribute [r] ordinal
+  #   @return [Agentilda::Ordinal]
+  # @!attribute [r] status
+  #   @return [Agentilda::Status]
+  # @!attribute [r] slug
+  #   @return [String]
+  # @!attribute [r] dirname
+  #   @return [String] exactly as it is on disk
+  # @!attribute [r] path
+  #   @return [String] absolute
+  Feature = Data.define(:ordinal, :status, :slug, :dirname, :path) do
+    include Comparable
+
+    # Decode a folder name, or return nil when it is not a plan folder.
+    #
+    # @param path [String] absolute path to a candidate directory
+    # @return [Agentilda::Feature, nil]
+    def self.parse(path)
+      dirname = File.basename(path)
+      ordinal = Ordinal.from_dirname(dirname) or return nil
+
+      rest = dirname.sub(/\A[\d.]+[-_]/, "")
+      head, tail = rest.split(/[-_]/, 2)
+
+      # A leading segment with no ASCII word character is the status emoji.
+      # The slug strips any further separators: the canonical spelling puts
+      # two dashes after the emoji, and folders from before that rule put one.
+      status = (Agentilda.status_for_emoji(head) if tail && !head.to_s.empty? && !head.match?(/[A-Za-z0-9]/))
+      slug = status ? tail.sub(/\A[-_]+/, "") : rest
+
+      new(ordinal:, status: status || STATUS_BY_KEY.fetch(:new), slug:, dirname:, path:)
+    end
+
+    # @return [String] proper name, e.g. "Law as Data"
+    def title = Agentilda.titleize(slug)
+
+    # The folder name this feature would carry in a given state — the slug
+    # never moves, and the number is always rendered canonically, so this is
+    # also what repairs a folder written `018-⚪️--foo` before the `NNN.MM` rule.
+    #
+    # @param status [Agentilda::Status]
+    # @return [String]
+    def dirname_as(status) = Agentilda.plan_dirname(ordinal, status, slug)
+
+    # The number exactly as the folder writes it, which is not always the
+    # canonical rendering: `018-⚪️--foo` yields "018" where {#ordinal} renders
+    # "018.00".
+    #
+    # @return [String]
+    def dirname_ordinal = dirname.to_s[/\A[\d.]+/].to_s
+
+    # @return [Boolean] whether the number is written in full `NNN.MM` form
+    def padded? = dirname_ordinal == ordinal.to_s
+
+    # Whether the folder is already named the way this tool would name it —
+    # number padded, emoji matching the state it claims, slug unchanged.
+    #
+    # @return [Boolean]
+    def canonical? = dirname == dirname_as(status)
+
+    # @param other [Object]
+    # @return [Integer, nil]
+    def <=>(other) = other.is_a?(self.class) ? [ordinal, dirname] <=> [other.ordinal, other.dirname] : nil
+  end
+
+  # A plan folder as the state machine sees it: which files exist, what they
+  # say, and which pull requests they record.
+  #
+  # It exists because the invariants ask the same questions repeatedly and
+  # {Feature} is a frozen `Data` with nowhere to memoize the answers.
+  class Subject
+    # @param feature [Agentilda::Feature]
+    def initialize(feature)
+      @feature = feature
+      @reads = {}
+    end
+
+    # @return [Agentilda::Feature]
+    attr_reader :feature
+
+    # @return [Agentilda::Status] the status the folder name claims
+    def status = feature.status
+
+    # @param name [String] a bare filename
+    # @return [Boolean]
+    def file?(name) = File.file?(File.join(feature.path, name))
+
+    # @param name [String]
+    # @return [String, nil] contents, or nil when absent
+    def read(name)
+      @reads.fetch(name) do
+        @reads[name] = file?(name) ? File.read(File.join(feature.path, name), encoding: "UTF-8") : nil
+      end
+    end
+
+    # @return [Array<Agentilda::PullRequest>]
+    def pull_requests = @pull_requests ||= PullRequests.new(dir: feature.path).all
+
+    # The specification's own Goal section, verbatim and at most two
+    # paragraphs. Anything that paraphrases the spec is a second copy that
+    # drifts; quoting it is not — which is why the pull request body and the
+    # index both read it from here rather than each writing their own.
+    #
+    # @return [Array<String>] paragraphs, empty when there is no Goal to read
+    def goal
+      body = read("spec.md").to_s
+      section = body[/^\#{"#"}{2,3}\s*Goals?\b[^\n]*\n+(.*?)(?=\n\#{"#"}{1,3}\s|\z)/mi, 1]
+
+      paragraphs(section) || paragraphs(body.sub(/\A\s*\#{"#"}[^\n]*\n/, "")) || []
+    end
+
+    # Specifications written before the template existed have no Goal section,
+    # and they are exactly the ones an index most needs to describe. So the
+    # opening prose stands in — skipping headings, quotes, lists and tables,
+    # which describe the document rather than the work.
+    #
+    # @param text [String, nil]
+    # @return [Array<String>, nil] nil when there is no prose to be had
+    def paragraphs(text)
+      found = text.to_s.strip.split(/\n{2,}/)
+        .map(&:strip)
+        .reject { |p| p.empty? || p.match?(/\A[\#>|\-*\d`_=]/) }
+        .first(2)
+
+      found.empty? ? nil : found
+    end
+
+    # The questions `blocked.md` still names, by number.
+    #
+    # Empty means one of two very different things, and a caller that treats
+    # them alike is how a folder with thirty kilobytes of open questions gets
+    # reported as "nothing left open": either there is no `blocked.md` at all,
+    # or there is one whose questions are not written as `## B<n>` and are
+    # therefore invisible to every part of this tool. Ask {#file?} which.
+    #
+    # @return [Array<Integer>]
+    def open_blocks = Agentilda.block_numbers(read("blocked.md"), OPEN_BLOCK)
+
+    # The answers waiting in `blocked.md`, by number. `## A1` settles `## B1`.
+    #
+    # Waiting, not folded. An `## A<n>` heading is not the same as a settled
+    # question: one may say in its own body that it is a draft pending a
+    # conversation. `lando-broker` makes that call; this only counts headings.
+    #
+    # @return [Array<Integer>]
+    def block_answers = Agentilda.block_numbers(read("blocked.md"), ANSWER_BLOCK)
+
+    # A `blocked.md` this tool cannot read: the file is there, and not one
+    # question in it is written as `## B<n>`. Nothing can drain it and nothing
+    # currently says so, which is the whole reason this exists.
+    #
+    # @return [Boolean]
+    def unreadable_block? = file?("blocked.md") && open_blocks.empty?
+
+    # @return [String, nil] why the folder's name is not justified
+    def violation = status.violation(self)
+
+    # @return [Boolean] whether the name matches the contents
+    def consistent? = violation.nil?
+
+    # @return [Agentilda::StateMachine] positioned at the current state
+    def machine = StateMachine.new(self)
+
+    # @return [Array<Symbol>] states reachable right now, guards applied
+    def allowed = machine.allowed
+
+    # @return [Agentilda::Status, nil] the state these contents justify
+    def best_fit = machine.best_fit
+
+    # Move the folder into +status+ — the side effect a transition *is*.
+    #
+    # The {Feature} is a frozen `Data` holding the old name, so it is replaced
+    # rather than mutated, and the memoized reads go with it.
+    #
+    # @param status [Agentilda::Status]
+    # @return [Agentilda::Feature] the feature under its new name
+    # @raise [Agentilda::Error] when the target name is already taken
+    def rename_to(status)
+      return @feature if status.key == @feature.status.key
+
+      target = File.join(File.dirname(@feature.path), @feature.dirname_as(status))
+      unless Agentilda.move_directory(@feature.path, target)
+        raise Error, "cannot rename #{@feature.dirname} — #{File.basename(target)} already exists"
+      end
+
+      @reads = {}
+      @pull_requests = nil
+      @feature = Feature.parse(target) or raise Error, "#{File.basename(target)} is not a plan folder"
+    end
+  end
+end

data/lib/agentilda/frontmatter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "date"
+require "yaml"
+
+module Agentilda
+  # Splits a markdown file into its YAML frontmatter and its body.
+  #
+  # The agent definitions and `create --from` both read frontmatter, and both
+  # used to call `YAML.safe_load` on their own. Its defaults refuse to build a
+  # `Date`, so an ordinary `date: 2026-08-31` raised Psych::DisallowedClass and
+  # `create` reported a missing `title:` on a file whose title was right there.
+  # One parser, one list of permitted classes, so that cannot happen twice.
+  module Frontmatter
+    # Frontmatter, then body.
+    PATTERN = /\A---\s*\n(.*?)\n---\s*\n(.*)\z/m
+
+    # Dates and timestamps are ordinary frontmatter, so they load. Nothing else
+    # does: the point of `safe_load` is that a seed file cannot name a class.
+    PERMITTED_CLASSES = [Date, Time].freeze
+
+    class << self
+      # @param content [String] a whole markdown file
+      # @return [Array(Hash, String)] the frontmatter and the body. A file with
+      #   no frontmatter is all body, and frontmatter that is not a mapping —
+      #   a bare list, a lone string — reads as no keys rather than raising.
+      # @raise [Psych::Exception] when the frontmatter is not valid YAML
+      def split(content)
+        match = PATTERN.match(content) or return [{}, content]
+
+        meta = YAML.safe_load(match[1], permitted_classes: PERMITTED_CLASSES)
+        [meta.is_a?(Hash) ? meta : {}, match[2]]
+      end
+    end
+  end
+end

data/lib/agentilda/github.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Agentilda
+  # The `gh` CLI, wrapped thinly.
+  #
+  # It is a seam rather than a convenience: every example in the suite injects
+  # a double here, so nothing in the tests reaches the network or a real
+  # repository.
+  class GitHub
+    # Fields asked of `gh pr list`.
+    FIELDS = %w[number title url headRefName files state isDraft mergedAt].freeze
+
+    # @param command [TTY::Command] runner, injectable for tests
+    # @param limit [Integer] how many pull requests to fetch
+    def initialize(command: TTY::Command.new(printer: :null), limit: 200)
+      @command = command
+      @limit = limit
+    end
+
+    # Every pull request, normalised into plain hashes.
+    #
+    # @param state [String] "open", "closed", "merged" or "all"
+    # @return [Array<Hash>] `{number:, title:, url:, branch:, files:}`
+    def pulls(state: "all")
+      out = UI.spinning("Fetching pull requests from GitHub") {
+        @command.run("gh", "pr", "list", "--state", state, "--limit", @limit.to_s,
+          "--json", FIELDS.join(",")).out
+      }
+
+      # `gh` can exit 0 having printed NOTHING — most often when it cannot reach
+      # the credential store, as in a non-interactive shell that has no keyring
+      # access, or when GH_TOKEN is set to something invalid and shadows a
+      # working login. Left alone this parses as a JSON error and reports as
+      # "bad output", sending you to look at the wrong thing entirely.
+      raise Error, no_output_message if out.to_s.strip.empty?
+
+      JSON.parse(out).map do |pr|
+        {
+          number: pr["number"],
+          title: pr["title"].to_s,
+          url: pr["url"],
+          branch: pr["headRefName"].to_s,
+          files: Array(pr["files"]).map { |f| f["path"] }.compact,
+          state: self.class.state_label(pr),
+          open: pr["mergedAt"].nil? && pr["state"].to_s.upcase == "OPEN"
+        }
+      end
+    rescue TTY::Command::ExitError, JSON::ParserError => e
+      raise Error, "could not list pull requests via `gh`: #{e.message.lines.first.to_s.strip}"
+    end
+
+    # @return [String] the diagnosis for a silent `gh`
+    def no_output_message
+      <<~MESSAGE.strip
+        `gh` produced no output and did not report an error.
+
+        That is almost always authentication rather than an empty repository:
+
+          - Check `gh auth status`. An invalid GH_TOKEN in the environment
+            shadows a working keyring login and fails without saying so.
+
+          - A non-interactive shell may have no access to the system keyring
+            even when an interactive one does.
+
+        Verify with: gh pr list --state all --limit 1
+      MESSAGE
+    end
+
+    # Fields asked of `gh pr view`, which unlike `pr list` can be told about
+    # one pull request in another repository.
+    VIEW_FIELDS = %w[number title url state isDraft mergedAt body].freeze
+
+    # A reference to one pull request: a bare number, a `#`-prefixed number,
+    # or a full URL to a GitHub pull request or a GitLab merge request.
+    REF = %r{\A(?:\#?\d+|https?://\S+?/(?:pull|merge_requests)/\d+/?)\z}
+
+    # Split and validate a `--prs` value before any of it reaches the network,
+    # so a typo fails in a hundredth of a second with the offending token named
+    # rather than after four round trips with a `gh` diagnostic.
+    #
+    # @param text [String] e.g. "12,15,18" or "https://…/pull/12, #15"
+    # @return [Array<String>] references, in the order given, de-duplicated
+    # @raise [Agentilda::Error] on anything that is not a reference
+    def self.parse_refs(text)
+      refs = text.to_s.split(",").map(&:strip).reject(&:empty?)
+      raise Error, "no pull requests given" if refs.empty?
+
+      bad = refs.reject { |r| r.match?(REF) }
+      unless bad.empty?
+        raise Error, "not a pull request number or URL: #{bad.join(", ")}"
+      end
+
+      refs.uniq
+    end
+
+    # One pull request, by number or URL.
+    #
+    # @param ref [String] "12", "#12" or "https://github.com/o/r/pull/12"
+    # @return [Hash] `{number:, title:, url:, state:, body:}`
+    # @raise [Agentilda::Error]
+    def pull_request(ref)
+      out = @command.run("gh", "pr", "view", ref.to_s, "--json", VIEW_FIELDS.join(",")).out
+      raise Error, no_output_message if out.to_s.strip.empty?
+
+      pr = JSON.parse(out)
+      {
+        number: pr["number"],
+        title: pr["title"].to_s,
+        url: pr["url"].to_s,
+        state: self.class.state_label(pr),
+        body: pr["body"].to_s
+      }
+    rescue TTY::Command::ExitError, JSON::ParserError => e
+      raise Error, "could not read pull request #{ref}: #{e.message.lines.first.to_s.strip}"
+    end
+
+    # Several pull requests, in the order asked for.
+    #
+    # @param refs [Array<String>]
+    # @return [Array<Hash>]
+    def pull_requests(refs)
+      UI.stepping(refs, "Fetching pull requests") { |ref| ref }
+      refs.map { |ref| pull_request(ref) }
+    end
+
+    # `gh` speaks in enums; `pull-requests.md` speaks in the words the state
+    # machine parses. Translate once, here, rather than at each call site.
+    #
+    # @param pr [Hash] a decoded `gh pr view` payload
+    # @return [String] one of the labels in {PullRequests::STATES}
+    def self.state_label(pr)
+      return "Merged 🟣" if pr["mergedAt"]
+      return "WIP 🟡" if pr["isDraft"]
+
+      case pr["state"].to_s.upcase
+      when "OPEN" then "Open 🟡"
+      when "CLOSED" then "Closed 🔴"
+      else "Unknown"
+      end
+    end
+
+    # Change a pull request's title.
+    #
+    # @param number [Integer]
+    # @param title [String]
+    # @return [void]
+    def retitle(number:, title:)
+      @command.run("gh", "pr", "edit", number.to_s, "--title", title)
+    rescue TTY::Command::ExitError => e
+      raise Error, "could not retitle ##{number}: #{e.message.lines.first.to_s.strip}"
+    end
+
+    # @return [Boolean] whether `gh` is installed and authenticated
+    def available?
+      @command.run!("gh", "auth", "status").success?
+    end
+  end
+end

data/lib/agentilda/index.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "erb"
+
+module Agentilda
+  # `agentilda index` — the project's plans as one browsable page.
+  #
+  # {Reporter} answers "what is the state of things" in a terminal, in columns,
+  # for someone standing at a prompt. This answers "what is this project, and
+  # where is everything" for someone arriving at the repository on the web: the
+  # goal of each plan in its own words, every pull request as a link, and every
+  # document in the folder one click away.
+  #
+  # It is generated for the same reason the conventions document is. A
+  # hand-written index of twenty plans cannot survive a rename, and renaming is
+  # exactly what `resync dirs` exists to do — the first hand-made INDEX.md this
+  # replaced had all 82 of its links pointing at folder names that had been
+  # padded to `NNN.MM` underneath it.
+  class Index
+    # The file this writes, relative to the `.plans` directory.
+    FILENAME = "INDEX.md"
+
+    # Documents that get a proper name rather than their filename.
+    ARTIFACT_NAMES = {
+      "spec.md" => "Spec",
+      "plan.md" => "Plan",
+      "pull-requests.md" => "Pull Requests",
+      "linear.md" => "Linear",
+      "blocked.md" => "Blocked",
+      "delayed.md" => "Deferred",
+      "rewrite.md" => "Rewrite",
+      "deployed.md" => "Deployed",
+      "rollback.md" => "Rollback",
+      "discarded.md" => "Discarded"
+    }.freeze
+
+    # @param tree [Agentilda::Tree]
+    # @param project [String, nil] the heading; defaults to the repository name
+    def initialize(tree:, project: nil)
+      @tree = tree
+      @project = project
+    end
+
+    # @return [Agentilda::Tree]
+    attr_reader :tree
+
+    # @return [String] the project's name, titleized from its directory
+    def project = @project ||= Agentilda.titleize(File.basename(File.dirname(tree.dir)))
+
+    # @return [String] the whole document
+    def render
+      [heading, *tree.subjects.map { |subject| section(subject) }].join("\n") + footer
+    end
+
+    # Write it next to the plans it describes.
+    #
+    # @param path [String, nil] override the destination
+    # @return [String] where it was written
+    def write(path = nil)
+      path ||= File.join(tree.dir, FILENAME)
+      File.write(path, render)
+      path
+    end
+
+    private
+
+    # @return [String]
+    def heading
+      <<~MARKDOWN
+        # Project #{project}
+
+        > [!IMPORTANT]
+        > **This file is auto generated.** To regenerate it, run `agentilda index`.
+        > Editing it by hand lasts until the next `resync dirs` renames a folder.
+
+        ## Current specifications and their status
+
+      MARKDOWN
+    end
+
+    # One plan: a heading that carries its number and state, then a table.
+    #
+    # Raw HTML rather than a markdown table because the cells are not one-liners
+    # — a goal is a paragraph or two and a plan may have a dozen pull requests,
+    # neither of which a pipe-delimited row can hold.
+    #
+    # @param subject [Agentilda::Subject]
+    # @return [String]
+    def section(subject)
+      feature = subject.feature
+
+      <<~MARKDOWN
+        ## #{feature.ordinal} — #{feature.status.emoji} #{escape(feature.title)}
+
+        <table>
+          <thead>
+            <tr>
+              <th align="left">Status</th>
+              <th align="left">Pull Requests</th>
+              <th align="left">What it is</th>
+              <th align="left">Artifacts</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td valign="top">#{status_cell(subject)}</td>
+              <td valign="top">#{pulls_cell(subject)}</td>
+              <td valign="top">#{goal_cell(subject)}</td>
+              <td valign="top">#{artifacts_cell(feature)}</td>
+            </tr>
+          </tbody>
+        </table>
+
+      MARKDOWN
+    end
+
+    # The emoji and the words, kept on one line — a status that wraps mid-label
+    # makes the column look like two states rather than one.
+    #
+    # @param subject [Agentilda::Subject]
+    # @return [String]
+    def status_cell(subject)
+      cell = "#{subject.status.emoji}&nbsp;#{escape(subject.status.label)}"
+      return cell if subject.consistent?
+
+      "#{cell}<br><sub>⚠️ #{escape(subject.violation)}</sub>"
+    end
+
+    # @param subject [Agentilda::Subject]
+    # @return [String]
+    def pulls_cell(subject)
+      prs = subject.pull_requests
+      return "<em>—</em>" if prs.empty?
+
+      items = prs.map { |pr|
+        "<li>#{link(pr.url, pr.label)} #{escape(pr.state)}</li>"
+      }
+      "<ul>#{items.join}</ul>"
+    end
+
+    # @param subject [Agentilda::Subject]
+    # @return [String]
+    def goal_cell(subject)
+      paragraphs = subject.goal
+      return "<em>No specification yet.</em>" if paragraphs.empty?
+
+      paragraphs.map { |p| "<p>#{inline(p)}</p>" }.join
+    end
+
+    # Markdown inside a raw HTML block is not parsed — GitHub stops parsing
+    # markdown the moment it sees a block-level tag — so a goal quoted verbatim
+    # would show its own `**` and backticks. Only the three that carry meaning
+    # are translated; single-underscore emphasis is deliberately left alone,
+    # because `deleted_at` is more common in these documents than italics.
+    #
+    # @param text [String] markdown, unescaped
+    # @return [String] HTML
+    def inline(text)
+      escape(text)
+        .gsub(/\[([^\]]+)\]\((https?:[^)\s]+)\)/) { %(<a href="#{$2}">#{$1}</a>) }
+        .gsub(/\*\*([^*]+)\*\*/) { "<strong>#{$1}</strong>" }
+        .gsub(/`([^`]+)`/) { "<code>#{$1}</code>" }
+        .tr("\n", " ")
+    end
+
+    # Every document in the folder, linked. The folder name is percent-encoded
+    # because it contains an emoji, and a raw one in an href is a broken link
+    # on GitHub.
+    #
+    # @param feature [Agentilda::Feature]
+    # @return [String]
+    def artifacts_cell(feature)
+      files = Dir.children(feature.path).select { |f| File.file?(File.join(feature.path, f)) }
+      return "<em>empty</em>" if files.empty?
+
+      # The documents that carry the lifecycle come first, in lifecycle order;
+      # whatever else the folder holds follows alphabetically.
+      known = ARTIFACT_NAMES.keys
+      files = files.sort_by { |f| [known.index(f) || known.size, f] }
+
+      items = files.map { |file|
+        href = "#{ERB::Util.url_encode(feature.dirname)}/#{ERB::Util.url_encode(file)}"
+        "<li>#{link(href, ARTIFACT_NAMES.fetch(file, file))}</li>"
+      }
+      "<ul>#{items.join}</ul>"
+    end
+
+    # @return [String]
+    def footer
+      counts = tree.subjects.each_with_object(Hash.new(0)) { |s, h| h[s.status] += 1 }
+        .map { |status, n| "#{status.emoji} #{n}" }.join(" &nbsp; ")
+
+      "\n---\n\n#{tree.subjects.size} #{(tree.subjects.size == 1) ? "plan" : "plans"} &nbsp; #{counts}\n"
+    end
+
+    # @param href [String]
+    # @param text [String]
+    # @return [String]
+    def link(href, text) = %(<a href="#{escape(href)}">#{escape(text)}</a>)
+
+    # @param text [String]
+    # @return [String]
+    def escape(text) = CGI.escapeHTML(text.to_s)
+  end
+end