agentilda 2.0.3 → 2.0.4

data/lib/agentilda/plans/index.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "erb"
+
+module Agentilda
+  module Plans
+    # `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::Plans::Tree]
+      # @param project [String, nil] the heading; defaults to the repository name
+      def initialize(tree:, project: nil)
+        @tree = tree
+        @project = project
+      end
+
+      # @return [Agentilda::Plans::Tree]
+      attr_reader :tree
+
+      # @return [String] the project's name, titleized from its directory
+      def project = @project ||= Agentilda::Plans.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::Plans::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::Plans::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::Plans::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::Plans::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::Plans::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
+end

data/lib/agentilda/plans/ledger.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Agentilda
+  module Plans
+    # The dated notes an agent leaves in the document it owns.
+    #
+    # This is the only place in the codebase that knows the syntax. The
+    # dispatcher reads it to learn whether an agent finished and who it named
+    # next; the state file records it; the screen paints it. An agent writes
+    # one entry when it starts and one when it stops, in a GitHub NOTE alert,
+    # one entry per line:
+    #
+    #   > [!NOTE]
+    #   >
+    #   > [2026-09-04 11:29:20 AM PDT] [ agent: leah-researcher   status: Started, round 1 ]
+    #   > [2026-09-04 11:44:03 AM PDT] [ agent: leah-researcher   status: Completed, round 1 ]
+    #   > [2026-09-04 11:44:04 AM PDT] [ next: yoda-writer ]
+    #
+    # The verbs are a closed set. A line that looks like an entry but does not
+    # parse is reported as a {Problem}, never dropped, because an agent that
+    # wrote "Done" has said nothing the harness can act on and silence would
+    # read as a stall.
+    module Ledger
+      # Everything an agent may claim. `Completed` is the only verb a `next:`
+      # line may follow.
+      STATUSES = ["Started", "Completed", "Almost completed", "Interrupted", "Blocked"].freeze
+
+      # Local time with the zone spelled out, so an entry written on one
+      # machine reads correctly on another.
+      TIME_FORMAT = "%Y-%m-%d %I:%M:%S %p %Z"
+
+      # An entry. `**` around the status is how the harness marks the one line
+      # it writes itself, the Interrupted that precedes a signature.
+      ENTRY = /\A>\s*\[(?<at>[^\]]+)\]\s*\[\s*agent:\s*(?<agent>[\w-]+)\s+status:\s*(?<bold>\*\*)?
+        (?<status>#{STATUSES.map { |s| Regexp.escape(s) }.join("|")}),\s*round\s*(?<round>\d+)
+        (?:\s*\((?<note>[^)]*)\))?\s*(?:\*\*)?\s*\]\s*\z/x
+
+      # The handoff line.
+      NEXT = /\A>\s*\[(?<at>[^\]]+)\]\s*\[\s*next:\s*(?<next>[\w-]+)\s*\]\s*\z/
+
+      # A line that is trying to be one of the two above. Anything matching
+      # this and neither of those is a {Problem}.
+      ATTEMPT = /\A>\s*\[[^\]]+\]\s*\[/
+
+      # The whole alert block, for {.stripped}.
+      BLOCK = /^[ \t]*>[ \t]*\[!NOTE\][ \t]*\n(?:[ \t]*>.*\n?)*/
+
+      # @!attribute [r] at
+      #   @return [Time]
+      # @!attribute [r] agent
+      #   @return [String] the definition's name, `leah-researcher`
+      # @!attribute [r] status
+      #   @return [String] one of {STATUSES}
+      # @!attribute [r] round
+      #   @return [Integer]
+      # @!attribute [r] note
+      #   @return [String, nil] the parenthesised tail, `rejected 1/2`
+      # @!attribute [r] file
+      #   @return [String] the document it was read from
+      # @!attribute [r] line
+      #   @return [Integer] 1-based
+      # @!attribute [r] bold
+      #   @return [Boolean] written `**bold**`, which only the harness does
+      Entry = Data.define(:at, :agent, :status, :round, :note, :file, :line, :bold) do
+        def initialize(note: nil, bold: false, **rest) = super
+
+        # @return [Boolean]
+        def completed? = status == "Completed"
+
+        # @return [Boolean] whether the agent gets another round
+        def retry? = ["Almost completed", "Interrupted"].include?(status)
+
+        # @return [Boolean]
+        def blocked? = status == "Blocked"
+      end
+
+      # @!attribute [r] next
+      #   @return [String] the agent named
+      Handoff = Data.define(:at, :next, :file, :line)
+
+      # @!attribute [r] text
+      #   @return [String] the line as written
+      Problem = Data.define(:file, :line, :text)
+
+      # What one read of a plan folder yielded.
+      Reading = Data.define(:entries, :handoffs, :problems) do
+        # @return [Agentilda::Plans::Ledger::Reading]
+        def self.empty = new(entries: [], handoffs: [], problems: [])
+
+        # @param other [Agentilda::Plans::Ledger::Reading]
+        # @return [Agentilda::Plans::Ledger::Reading]
+        def +(other)
+          self.class.new(entries: entries + other.entries,
+            handoffs: handoffs + other.handoffs,
+            problems: problems + other.problems)
+        end
+      end
+
+      class << self
+        # @param text [String] a whole document
+        # @param file [String] its name, carried on every entry
+        # @return [Agentilda::Plans::Ledger::Reading]
+        def parse(text, file:)
+          entries = []
+          handoffs = []
+          problems = []
+          text.to_s.each_line.with_index(1) do |raw, line|
+            stripped = raw.chomp
+            if (m = ENTRY.match(stripped))
+              entries << Entry.new(at: parse_time(m[:at]),
+                agent: m[:agent],
+                status: m[:status],
+                round: m[:round].to_i,
+                note: m[:note]&.strip,
+                file:,
+                line:,
+                bold: !m[:bold].nil?)
+            elsif (m = NEXT.match(stripped))
+              handoffs << Handoff.new(at: parse_time(m[:at]), next: m[:next], file:, line:)
+            elsif ATTEMPT.match?(stripped)
+              problems << Problem.new(file:, line:, text: stripped.strip)
+            end
+          end
+          Reading.new(entries:, handoffs:, problems:)
+        end
+
+        # Every document an agent may sign, in the order its definition lists
+        # them. A missing file is not a problem; an agent that has not reached
+        # `pull-requests.md` yet has not written it.
+        #
+        # @param dir [String] the plan folder
+        # @param files [Array<String>]
+        # @return [Agentilda::Plans::Ledger::Reading]
+        def read(dir, files)
+          files.each_with_index.reduce(Reading.empty) do |reading, (name, _index)|
+            path = File.join(dir, name)
+            next reading unless File.file?(path)
+
+            found = parse(File.read(path, encoding: "UTF-8"), file: name)
+            reading + Reading.new(entries: found.entries.map { |e| e.with(file: name) },
+              handoffs: found.handoffs,
+              problems: found.problems)
+          end
+        end
+
+        # @param time [Time]
+        # @return [String]
+        def timestamp(time = Time.now) = time.strftime(TIME_FORMAT)
+
+        # Agents write what `date` prints, and `Time.strptime` cannot read a
+        # zone abbreviation back into an offset. The abbreviation is dropped
+        # and the time read as local, which is right on the machine that wrote
+        # it and off by a zone anywhere else, which the tick tolerates: entries
+        # are compared with each other, never with the wall clock.
+        #
+        # @param text [String]
+        # @return [Time]
+        def parse_time(text)
+          Time.strptime(text.to_s.strip.sub(/\s+[A-Z]{2,5}\z/, ""), "%Y-%m-%d %I:%M:%S %p")
+        rescue ArgumentError
+          Time.at(0)
+        end
+
+        # @param entry [Agentilda::Plans::Ledger::Entry]
+        # @return [String] one quoted line, no newline
+        def render(entry)
+          tail = entry.note ? " (#{entry.note})" : ""
+          body = "#{entry.status}, round #{entry.round}#{tail}"
+          body = "**#{body}**" if entry.bold
+          "> [#{timestamp(entry.at)}] [ agent: #{entry.agent}   status: #{body} ]"
+        end
+
+        # @param handoff [Agentilda::Plans::Ledger::Handoff]
+        # @return [String]
+        def render_handoff(handoff) = "> [#{timestamp(handoff.at)}] [ next: #{handoff.next} ]"
+
+        # @param lines [Array<String>] already quoted
+        # @return [String] a NOTE alert, newline-terminated
+        def block(*lines) = (["> [!NOTE]", ">"] + lines.flatten).join("\n") + "\n"
+
+        # Append one block. Separated from what is there by a blank line so the
+        # alert renders as its own block rather than merging into a paragraph.
+        #
+        # @param path [String]
+        # @param lines [Array<String>]
+        # @return [void]
+        def append(path, *lines)
+          existing = File.file?(path) ? File.read(path, encoding: "UTF-8") : ""
+          glue = if existing.empty?
+                   ""
+                 elsif existing.end_with?("\n\n")
+                   ""
+                 elsif existing.end_with?("\n")
+                   "\n"
+                 else
+                   "\n\n"
+                 end
+          File.write(path, existing + glue + block(*lines))
+        end
+
+        # The entry that tells the harness where this agent stands: the latest
+        # by clock, then by the order its documents are listed, then by line.
+        #
+        # @param reading [Agentilda::Plans::Ledger::Reading]
+        # @param agent [String]
+        # @return [Agentilda::Plans::Ledger::Entry, nil]
+        def last_for(reading, agent)
+          files = reading.entries.map(&:file).uniq
+          reading.entries.select { |e| e.agent == agent }
+                 .max_by { |e| [e.at, files.index(e.file), e.line] }
+        end
+
+        # The `next:` that belongs to an entry: same file, a later line, and no
+        # other entry between the two. A handoff written under somebody else's
+        # entry is not this agent's handoff.
+        #
+        # @param reading [Agentilda::Plans::Ledger::Reading]
+        # @param entry [Agentilda::Plans::Ledger::Entry]
+        # @return [Agentilda::Plans::Ledger::Handoff, nil]
+        def handoff_after(reading, entry)
+          candidates = reading.handoffs.select { |h| h.file == entry.file && h.line > entry.line }
+          handoff = candidates.min_by(&:line) or return nil
+          between = reading.entries.any? { |e| e.file == entry.file && e.line > entry.line && e.line < handoff.line }
+          between ? nil : handoff
+        end
+
+        # @param text [String]
+        # @return [String] the document without its ledger blocks
+        def stripped(text) = text.to_s.gsub(BLOCK, "")
+      end
+    end
+  end
+end

data/lib/agentilda/plans/mailbox.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Plans
+    # The one channel two agents on the same plan have to each other.
+    #
+    # `luke-backend` and `rey-frontend` build one plan in one worktree at the
+    # same time, but each is its own `claude -p` process. Claude Code can
+    # message between local sessions, and the prompts used to say so, but a
+    # session is named after its directory plus a random suffix, so a pair had
+    # to guess its partner from a list of every session on the machine by start
+    # time. It worked once, by luck. With ten plans running there would have
+    # been ten `agentilda-xx` entries and nothing to tell them apart.
+    #
+    # So the mailbox is a file in the plan folder, append-only, one numbered
+    # entry per message, readable by `agentilda mail read` during the round and
+    # by a person after it. The harness names the file and the partner in each
+    # agent's prompt, so nobody guesses.
+    class Mailbox
+      FILENAME = "mailbox.md"
+
+      # Between the fields of a heading. Neither a name nor a timestamp
+      # contains it, which is what makes the heading parseable.
+      SEPARATOR = " · "
+
+      # `## 3 · 2026-09-06 10:30:53 -0700 · rey-frontend → luke-backend`
+      HEADING = /\A\#\# (\d+) · (.+?) · (\S+) → (\S+)\s*\z/
+
+      TIME_FORMAT = "%Y-%m-%d %H:%M:%S %z"
+
+      # One entry.
+      #
+      # @!attribute [r] number
+      #   @return [Integer] 1-based, in order of writing
+      # @!attribute [r] at
+      #   @return [String] when, as {TIME_FORMAT} writes it
+      # @!attribute [r] from
+      #   @return [String] the agent that wrote it
+      # @!attribute [r] to
+      #   @return [String] the agent it is for
+      # @!attribute [r] body
+      #   @return [String]
+      Message = Data.define(:number, :at, :from, :to, :body) do
+        # @return [String] as it stands in the file
+        def to_s = "## #{number}#{SEPARATOR}#{at}#{SEPARATOR}#{from} → #{to}\n\n#{body.strip}\n"
+      end
+
+      # @param dir [String] the plan folder
+      def initialize(dir:)
+        @dir = dir
+      end
+
+      # @return [String] the plan folder
+      attr_reader :dir
+
+      # @return [String]
+      def path = File.join(dir, FILENAME)
+
+      # @return [Boolean]
+      def exist? = File.file?(path)
+
+      # Every message, in the order it was written.
+      #
+      # @return [Array<Agentilda::Plans::Mailbox::Message>]
+      def messages
+        return [] unless exist?
+
+        parse(File.read(path, encoding: "UTF-8"))
+      end
+
+      # What is waiting for one agent.
+      #
+      # @param name [String] the reader
+      # @param after [Integer] a number the reader has already seen; only
+      #   messages above it are returned
+      # @return [Array<Agentilda::Plans::Mailbox::Message>]
+      def for(name, after: 0)
+        messages.select { |m| m.to == name && m.number > after }
+      end
+
+      # Append one message and give it the next number.
+      #
+      # The append takes a lock on the file. Two agents finishing a unit in the
+      # same second would otherwise read the same last number and both write
+      # the one after it.
+      #
+      # @param from [String]
+      # @param to [String]
+      # @param body [String]
+      # @param at [Time]
+      # @return [Agentilda::Plans::Mailbox::Message] as written
+      # @raise [Agentilda::Error] on an empty body, which would be a heading
+      #   with nothing under it for the reader to act on, or on a sender or
+      #   recipient that is blank or holds whitespace: {HEADING} could not
+      #   parse such an entry back, so it would be written and never read
+      def append(from:, to:, body:, at: Time.now)
+        text = body.to_s.strip
+        raise Error, "a message needs a body" if text.empty?
+        raise Error, "a message needs --from and --to, each one agent name" unless name?(from) && name?(to)
+
+        File.open(path, File::RDWR | File::CREAT | File::APPEND, 0o644) do |f|
+          f.flock(File::LOCK_EX)
+          f.rewind
+          existing = f.read
+          number = (parse(existing).last&.number || 0) + 1
+          message = Message.new(number:, at: at.strftime(TIME_FORMAT), from:, to:, body: text)
+          f.write(existing.empty? ? "# Mailbox\n\n#{message}" : "\n#{message}")
+          message
+        end
+      end
+
+      private
+
+      # @param value [Object]
+      # @return [Boolean] one token, as {HEADING} expects a name to be
+      def name?(value) = value.to_s.match?(/\A\S+\z/)
+
+      # Only a line shaped exactly like {HEADING} starts a message, so a body
+      # may hold headings of its own, code, anything.
+      #
+      # @param text [String]
+      # @return [Array<Agentilda::Plans::Mailbox::Message>]
+      def parse(text)
+        messages = []
+        current = nil
+        body = []
+
+        text.to_s.each_line(chomp: true) do |line|
+          if (heading = HEADING.match(line))
+            messages << current.with(body: body.join("\n").strip) if current
+            current = Message.new(number: heading[1].to_i, at: heading[2], from: heading[3], to: heading[4], body: "")
+            body = []
+          elsif current
+            body << line
+          end
+        end
+
+        messages << current.with(body: body.join("\n").strip) if current
+        messages
+      end
+    end
+  end
+end

data/lib/agentilda/plans/ordinal.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Plans
+    # A plan's number, and therefore its identity. Set once when the folder is
+    # created and never changed: branch names, pull request titles and every
+    # `pull-requests.md` join on it, and renumbering breaks all of them silently.
+    #
+    # Always rendered `NNN.MM`. `002.00` is an ordinary plan, specified before it
+    # was built. `002.01` is retroactive — work that shipped between 002 and 003
+    # and was documented afterwards. The decimal marks a **sibling**, not
+    # containment: 002.01 is not part of 002.
+    #
+    # `000` is where the sequence starts, so the first plan of a project is
+    # `000.00`. It also absorbs the older meaning — work that predates the plan
+    # discipline — since either way it sorts first, which is where it belongs.
+    #
+    # @!attribute [r] major
+    #   @return [Integer] 0..999
+    # @!attribute [r] minor
+    #   @return [Integer] 0..99; zero for an ordinary plan
+    class Ordinal < Data.define(:major, :minor)
+      include Comparable
+
+      # The canonical form, plus the bare `NNN` that trees written before this
+      # rule still use and must remain readable.
+      PATTERN = /\A(\d{1,3})(?:\.(\d{1,2}))?\z/
+
+      # The most retroactive slots a single gap can hold.
+      MAX_MINOR = 99
+
+      # @param text [String, nil] e.g. "3", "003", "003.00", "018.01"
+      # @return [Agentilda::Plans::Ordinal, nil] nil when it is not a plan number
+      def self.parse(text)
+        m = PATTERN.match(text.to_s.strip)
+        m && new(major: m[1].to_i, minor: m[2].to_i)
+      end
+
+      # Pull the number off the front of a folder name.
+      #
+      # @param dirname [String] e.g. "018.01-✅--verify-against-filed-returns"
+      # @return [Agentilda::Plans::Ordinal, nil]
+      def self.from_dirname(dirname) = parse(dirname.to_s[/\A[\d.]+/])
+
+      # The next ordinary plan after everything in +existing+.
+      #
+      # The first plan in an empty tree is `000.00`, not `001.00`: the sequence
+      # counts from zero so that the very first specification — usually the
+      # project's own — sorts above everything and needs no gap reserved for it.
+      #
+      # @param existing [Array<Agentilda::Plans::Ordinal>]
+      # @return [Agentilda::Plans::Ordinal]
+      def self.next_major(existing)
+        return new(major: 0, minor: 0) if existing.empty?
+
+        new(major: existing.map(&:major).max + 1, minor: 0)
+      end
+
+      # The next retroactive slot in the gap after +major+.
+      #
+      # @param existing [Array<Agentilda::Plans::Ordinal>]
+      # @param major [Integer] the plan the work landed after
+      # @return [Agentilda::Plans::Ordinal]
+      # @raise [Agentilda::Error] when the gap is full
+      def self.next_minor(existing, major:)
+        taken = existing.select { |o| o.major == major }.map(&:minor).max || 0
+        if taken >= MAX_MINOR
+          raise Error, "all #{MAX_MINOR} retroactive slots after #{format("%03d", major)} are taken"
+        end
+
+        new(major:, minor: taken + 1)
+      end
+
+      # @return [Boolean] whether this plan was documented after the fact
+      def retroactive? = minor.positive?
+
+      # @return [String] the canonical `NNN.MM`
+      def to_s = format("%03d.%02d", major, minor)
+
+      # @return [String] what a pull request title carries
+      def to_prefix = "[#{self}]"
+
+      # @param other [Object]
+      # @return [Integer, nil]
+      def <=>(other)
+        return nil unless other.is_a?(self.class)
+
+        [major, minor] <=> [other.major, other.minor]
+      end
+    end
+  end
+end