openlanes 3.0.0

data/lib/openlanes/plans/index.rb

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

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "time"
+
+module OpenLanes
+  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 [OpenLanes::Plans::Ledger::Reading]
+        def self.empty = new(entries: [], handoffs: [], problems: [])
+
+        # @param other [OpenLanes::Plans::Ledger::Reading]
+        # @return [OpenLanes::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 [OpenLanes::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, then the signatures in `state.json`. A missing file is not a
+        # problem; an agent that has not reached `pull-requests.md` yet has not
+        # written it. `state.json` comes last, so on a tie in time a signature
+        # made through `openlanes state sign` outranks a line in prose.
+        #
+        # @param dir [String] the plan folder
+        # @param files [Array<String>]
+        # @return [OpenLanes::Plans::Ledger::Reading]
+        def read(dir, files)
+          markdown(dir, files) + signed(dir)
+        end
+
+        # A `state.json` that will not parse is reported like an unreadable
+        # line, not raised: one bad file must not stop the loop for every plan.
+        #
+        # @param dir [String]
+        # @return [OpenLanes::Plans::Ledger::Reading]
+        def signed(dir)
+          PlanState.for(dir).ledger
+        rescue Error => e
+          Reading.new(entries: [], handoffs: [], problems: [Problem.new(file: PlanState::FILENAME, line: 1, text: e.message)])
+        end
+
+        # @param dir [String]
+        # @param files [Array<String>]
+        # @return [OpenLanes::Plans::Ledger::Reading]
+        def markdown(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 [OpenLanes::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 [OpenLanes::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 [OpenLanes::Plans::Ledger::Reading]
+        # @param agent [String]
+        # @return [OpenLanes::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 [OpenLanes::Plans::Ledger::Reading]
+        # @param entry [OpenLanes::Plans::Ledger::Entry]
+        # @return [OpenLanes::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/openlanes/plans/mailbox.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  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 `openlanes-xx` entries and nothing to tell them apart.
+    #
+    # So the mailbox lives in the plan folder, append-only, one numbered entry
+    # per message, readable by `openlanes mail read` during the round and by a
+    # person after it. The harness names the partner in each agent's prompt,
+    # so nobody guesses.
+    #
+    # Messages are kept in the plan's `state.json` ({PlanState}), next to the
+    # stages and signatures a restart reads. Plans from before that kept them
+    # in `mailbox.md`; those are still read, and numbering carries on from
+    # them, but nothing writes there any more.
+    class Mailbox
+      # Where messages used to be written, and are still read from.
+      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] where new messages are written
+      def path = state.path
+
+      # @return [String] where messages from before `state.json` are read
+      def legacy_path = File.join(dir, FILENAME)
+
+      # @return [Boolean] whether any message has been written
+      def exist? = !messages.empty?
+
+      # Every message, in the order it was written.
+      #
+      # @return [Array<OpenLanes::Plans::Mailbox::Message>]
+      def messages
+        (legacy + state.messages.map { |m| from_state(m) }).sort_by(&:number)
+      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<OpenLanes::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.
+      #
+      # {PlanState} takes a lock around the read and the write, so two agents
+      # finishing a unit in the same second cannot both take the same number.
+      #
+      # @param from [String]
+      # @param to [String]
+      # @param body [String]
+      # @param at [Time]
+      # @param command [String, nil] the page command that sent it; the same
+      #   id to the same reader appends nothing the second time
+      # @return [OpenLanes::Plans::Mailbox::Message] as written, or as first
+      #   written under +command+
+      # @raise [OpenLanes::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
+      def append(from:, to:, body:, at: Time.now, command: nil)
+        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)
+
+        from_state(state.message!(from:, to:, body: text, at:, after: legacy.map(&:number).max.to_i, command:))
+      end
+
+      private
+
+      # @return [OpenLanes::Plans::PlanState]
+      def state = PlanState.for(dir)
+
+      # @return [Array<OpenLanes::Plans::Mailbox::Message>] what mailbox.md holds
+      def legacy
+        return [] unless File.file?(legacy_path)
+
+        parse(File.read(legacy_path, encoding: "UTF-8"))
+      end
+
+      # @param message [Hash] as {PlanState} stores it
+      # @return [OpenLanes::Plans::Mailbox::Message]
+      def from_state(message)
+        at = begin
+          Time.iso8601(message["at"].to_s).strftime(TIME_FORMAT)
+        rescue ArgumentError
+          message["at"].to_s
+        end
+        Message.new(number: message["number"], at:, from: message["from"], to: message["to"], body: message["body"])
+      end
+
+      # @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<OpenLanes::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