openlanes 3.0.0 → 3.1.0

data/lib/openlanes/presentation/api_docs.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module OpenLanes
+  module Presentation
+    # The OpenAPI documents plans carry, one `openapi.yaml` per plan folder,
+    # gathered so a person can find and render them.
+    #
+    # This is a smoke check, not a validator: a file is a problem when it is
+    # not YAML, or lacks the two top-level keys every OpenAPI document has.
+    # A real validator would pull in a JSON Schema stack for a check whose
+    # job is to catch the file an agent half-wrote, which these two do.
+    class ApiDocs
+      # The name an agent writes its contract under, in its plan's folder.
+      FILE = "openapi.yaml"
+
+      # Keys whose absence means the file is not an OpenAPI document at all.
+      REQUIRED_KEYS = %w[openapi paths].freeze
+
+      # One document that passed the check.
+      #
+      # @!attribute path [String] absolute path to the file
+      # @!attribute title [String, nil] `info.title`, when it has one
+      # @!attribute version [String] the `openapi:` value, such as "3.1.0"
+      Found = Data.define(:path, :title, :version)
+
+      # One document that did not.
+      #
+      # @!attribute path [String] absolute path to the file
+      # @!attribute reason [String] what is wrong, in a sentence
+      Problem = Data.define(:path, :reason)
+
+      # Everything one look at a tree found.
+      #
+      # @!attribute found [Array<Found>]
+      # @!attribute problems [Array<Problem>]
+      Result = Data.define(:found, :problems) do
+        # @return [Boolean] true when no file failed the check
+        def ok? = problems.empty?
+      end
+
+      # @param tree [OpenLanes::Plans::Tree]
+      # @return [Result] files ordered by path, so plan order
+      def call(tree)
+        found = []
+        problems = []
+        Dir.glob(File.join(tree.dir, "*", FILE)).each do |path|
+          outcome = inspect_file(path)
+          (outcome.is_a?(Problem) ? problems : found) << outcome
+        end
+        Result.new(found:, problems:)
+      end
+
+      private
+
+      # @param path [String]
+      # @return [Found, Problem]
+      def inspect_file(path)
+        document = YAML.safe_load_file(path, permitted_classes: Frontmatter::PERMITTED_CLASSES, aliases: true)
+        return Problem.new(path:, reason: "is not a YAML mapping") unless document.is_a?(Hash)
+
+        missing = REQUIRED_KEYS.reject { document.key?(it) }
+        unless missing.empty?
+          return Problem.new(path:, reason: "has no top-level #{missing.map { "#{it}:" }.join(" or ")}")
+        end
+
+        Found.new(path:, title: document.dig("info", "title"), version: document["openapi"].to_s)
+      rescue Psych::Exception => e
+        # The parser's own message carries the line and column, which is
+        # what a person needs to find the bad indent.
+        Problem.new(path:, reason: "does not parse as YAML: #{e.message}")
+      end
+    end
+  end
+end

data/lib/openlanes/presentation/documentation.rb

@@ -19,6 +19,7 @@ module OpenLanes
         [
           header,
           numbering,
+          places,
           starting,
           status_table,
           blocking,
@@ -26,6 +27,7 @@ module OpenLanes
           diagram,
           files_section,
           pull_requests,
+          review_labels,
           footer
         ].join("\n")
       end
@@ -58,7 +60,7 @@ module OpenLanes
           | :---- | :---- | :---------------------- |
           | **spec** | #{status(:new).emoji} #{status(:new).label} | `spec.md` |
           | **plan** | #{status(:planned).emoji} #{status(:planned).label} | `plan.md` |
-          | **build** | #{status(:building).emoji} → #{status(:ready_for_review).emoji} → #{status(:in_review).emoji} → #{status(:approved).emoji} | `pull-requests.md` |
+          | **build** | #{status(:building).emoji} → #{status(:ready_for_review).emoji} → #{status(:in_review).emoji} → #{status(:verifying).emoji} → #{status(:completed).emoji} → #{status(:approved).emoji} | `pull-requests.md` |
 
           Those files are not paperwork. They are what the tool checks: a folder may not
           claim a phase whose file is missing, and `openlanes resync dirs` renames
@@ -79,18 +81,33 @@ module OpenLanes
           The shape is always `NNN.MM`:
 
           ```
-          #{OpenLanes::PLANS_DIR}/000.00-#{status(:new).emoji}-initial-spec
-          #{OpenLanes::PLANS_DIR}/001.00-#{status(:approved).emoji}-dev-foundation
-          #{OpenLanes::PLANS_DIR}/001.01-#{status(:approved).emoji}-schedule-k1-backfill   <- shipped between 001 and 002,
-          #{OpenLanes::PLANS_DIR}/002.00-#{status(:planned).emoji}-tenancy-households        specified afterwards
+          #{OpenLanes::PLANS_DIR}/#{name("000.00", :new, "initial-spec")}
+          #{OpenLanes::PLANS_DIR}/#{name("001.00", :building, "dev-foundation")}
+          #{OpenLanes::PLANS_DIR}/#{name("001.01", :retroactive, "schedule-k1-backfill")}   <- shipped between 001 and 002,
+          #{OpenLanes::PLANS_DIR}/#{name("002.00", :planned, "tenancy-households")}        specified afterwards
           ```
 
+          A folder name holds no space, so it needs no quoting in a shell, and every
+          state emoji is a single code point, so it measures the same in every terminal.
+          Older spellings (`NNN.MM-<emoji> → <slug>`, `NNN-<emoji>--<slug>`) and the
+          emoji they used are still read; `openlanes resync dirs` renames them.
+
           - **`NNN` counts from `000`.** The first plan of a project is `000.00`; after
             that it is the highest major plus one, zero-padded to three digits.
           - **`MM` is `00` for an ordinary plan** — one specified before it was built.
           - **`MM` from `01` to `99` marks a retroactive plan**: work that shipped with no
             specification, documented after the fact. `openlanes create --after 001`
             takes the next free slot in the gap after 001.
+          - **A number is taken if any branch holds it.** "Highest" counts the primary
+            checkout's `#{OpenLanes::PLANS_DIR}` (archived plans included) and `#{OpenLanes::PLANS_DIR}` on every local
+            branch and every `origin/*` branch, read without a fetch, so a plan on an
+            unmerged branch keeps its number.
+          - **Plans are created only in the primary checkout, on its default branch**
+            (origin's HEAD, else `main`). In a linked worktree, or on any other branch,
+            `openlanes create`, the page's new plan and `resync prs` adoption refuse and
+            say why. The same holds for an opening `spec.md` and for `depends_on:`;
+            every other file in a plan folder may be written from a worktree. Numbers are handed out under a lock in the shared git directory,
+            so two creates at once cannot take the same one.
 
           `001.01` is a **sibling of 001 that arrived later, not a part of 001**. The dot
           reads as containment in almost every other numbering scheme, and here it does
@@ -120,6 +137,53 @@ module OpenLanes
         MARKDOWN
       end
 
+      # Where a plan lives, derived from {Plans::Tree::INACTIVE_DIRS}.
+      #
+      # @return [String]
+      def places
+        rows = OpenLanes::Plans::Tree::INACTIVE_DIRS.group_by { |_, dir| dir }.map do |dir, pairs|
+          states = pairs.map { |key, _| "#{status(key).emoji} #{status(key).label}" }.join(", ")
+          "| `#{OpenLanes::PLANS_DIR}/#{dir}/` | #{states} |"
+        end
+        dated = name("001.00", :approved, "dev-foundation", archived_on: Date.new(2026, 9, 1))
+
+        <<~MARKDOWN
+          ## Where a plan lives
+
+          The top of `#{OpenLanes::PLANS_DIR}` holds only plans somebody may still work on.
+          A plan in one of these states moves into a subfolder, and its name gains the
+          date it got there:
+
+          | Folder | States |
+          | --- | --- |
+          #{rows.join("\n")}
+
+          ```
+          #{OpenLanes::PLANS_DIR}/#{OpenLanes::Plans::Tree.subfolder_for(status(:approved))}/#{dated}
+          ```
+
+          `openlanes resync dirs` does the moving, with `git mv`, and moves a plan back
+          to the top, undated, once its state is open again. The date is the folder's
+          last rename in git, else `state.json`'s `updated_at`, else today. Numbers span
+          the subfolders: a number in `archive/` is never handed out again.
+          `openlanes list-plans` shows the open plans; `--all` adds the rest.
+
+          While an agent works in a plan, its lock (pid, host, start time) sits in the
+          runtime state directory outside the repository (a legacy
+          `#{OpenLanes::Plans::Lock::FILENAME}` in the folder is still read), and `list-plans`
+          shows 🔑. The folder is never renamed while it is locked. `resync dirs` clears a
+          lock whose process is gone from this machine, and only reports one from another.
+
+        MARKDOWN
+      end
+
+      # @param ordinal [String]
+      # @param key [Symbol]
+      # @param slug [String]
+      # @param archived_on [Date, nil]
+      # @return [String] a folder name, spelled the one way {Plans.plan_dirname} spells it
+      def name(ordinal, key, slug, archived_on: nil) = OpenLanes::Plans.plan_dirname(ordinal, status(key), slug, archived_on:)
+
       # @return [String]
       def starting
         headings = OpenLanes::Lifecycle::Brief::HEADINGS.map { |h| "- `## #{h}`" }.join("\n")
@@ -320,15 +384,22 @@ module OpenLanes
           | :--- | :---------- |
           | `spec.md` | the specification; written first |
           | `plan.md` | the execution plan; written from the spec |
-          | `implementation-plan.md` | the contract between the two halves of building |
+          | `contract.md` | the contract between the two halves of building |
+          | `openapi.yaml` | the HTTP surface, when the plan has one |
           #{known.reject { |r| r.start_with?("| `spec.md`", "| `plan.md`") }.join("\n")}
 
-          `implementation-plan.md` is the one file no state requires. `luke-backend`
-          writes it before it writes code, and `rey-frontend` builds from it a round
-          later: the interfaces the back end landed, their shapes and their errors,
-          which files each half owns, which units may run concurrently, and the one
-          test that proves the halves are joined rather than merely both present. No
-          state requires it because a plan with no back-end work never needs one.
+          `contract.md` is the one file no state requires. `luke-backend` writes it
+          before it writes code, and `rey-frontend` builds from it a round later: the
+          interfaces the back end landed, their shapes and their errors, which files
+          each half owns, which units may run concurrently, and the one test that
+          proves the halves are joined rather than merely both present. No state
+          requires it because a plan with no back-end work never needs one. When
+          `plan.md` says the plan has an HTTP surface, `openapi.yaml` sits beside it,
+          linked from it, and `openlanes api docs` lists every one in the project.
+
+          The units themselves live in `plan.md`, under `## Backend` and
+          `## Frontend`. `rey-frontend` is started only when `## Frontend` holds a
+          unit heading.
 
           Nothing else belongs there. A folder holding notes, diagrams or scratch files
           is a folder nobody can audit at a glance.
@@ -345,6 +416,28 @@ module OpenLanes
           .join(", ")
       end
 
+      # Derived from {Plans::ReviewLabel::ALL}, the only place a label is named.
+      #
+      # @return [String]
+      def review_labels
+        rows = OpenLanes::Plans::ReviewLabel::ALL.map do |l|
+          "| `#{l.name}` | `#{l.colour}` | #{l.passing? ? "yes" : "no"} | #{l.meaning} |"
+        end
+
+        <<~MARKDOWN
+          ## Review labels
+
+          A pull request carries one of these at a time, set through `openlanes review <pr> <label>`.
+          A new label replaces the previous one, except that `#{OpenLanes::Plans::ReviewLabel::VULNERABILITY}`
+          sits beside `#{OpenLanes::Plans::ReviewLabel::REJECTED}`. No passing verdict is given while CI is red.
+          The engine creates or recolours every one of them on the repository when a run starts.
+
+          | Label | Colour | Passing | Meaning |
+          | --- | --- | --- | --- |
+          #{rows.join("\n")}
+        MARKDOWN
+      end
+
       # @return [String]
       def pull_requests
         <<~MARKDOWN

data/lib/openlanes/presentation/pr_changes.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Presentation
+    # What `resync prs` did, or would do, to pull request titles: one tab-
+    # separated row per change for STDOUT, and the retitles, the new plan
+    # folders, the skipped pull requests and the assumed-prefix warning for
+    # a person on STDERR.
+    class PrChanges
+      include UI
+
+      # @param changes [Array<OpenLanes::Lifecycle::Resync::Prs::Change>]
+      # @param dry_run [Boolean] whether nothing was actually changed
+      def initialize(changes, dry_run:)
+        @changes = changes
+        @dry_run = dry_run
+      end
+
+      # @return [Array<String>] the deliverable rows: number, new title, reason
+      def lines = @changes.map { |change| "#{change.number}\t#{change.new_title || "-"}\t#{change.reason}" }
+
+      # Draws the report on STDERR.
+      #
+      # @return [void]
+      def report
+        applicable, flagged = @changes.partition(&:applicable?)
+        assumed = applicable.select(&:assumed?)
+
+        applicable.each { |change| say("##{change.number}  #{change.new_title}#{note(change)}") }
+        adoptions(applicable.select(&:adopted?))
+        flagged.each { |change| say("##{change.number}  #{paint("SKIPPED", :red)} — #{change.reason}", bullet: "!") }
+        footer(applicable.size)
+        assumptions(assumed)
+      end
+
+      private
+
+      # @param change [OpenLanes::Lifecycle::Resync::Prs::Change]
+      # @return [String, nil]
+      def note(change)
+        if change.adopted?
+          paint("   (new plan)", :magenta)
+        elsif change.assumed?
+          paint("   (assumed)", :yellow)
+        end
+      end
+
+      # Creating folders is a bigger act than editing a title, so it is
+      # reported separately rather than buried in the retitle list.
+      #
+      # @param adopted [Array<OpenLanes::Lifecycle::Resync::Prs::Change>]
+      # @return [void]
+      def adoptions(adopted)
+        return if adopted.empty?
+
+        verb = @dry_run ? "Would create" : "Created"
+        info("#{verb} #{adopted.size} plan folder#{"s" unless adopted.size == 1} for pull " \
+             "requests that resolved to no plan:\n\n" \
+             "#{adopted.map { |c| "  #{c.ordinal}  ##{c.number}  #{c.title}" }.join("\n")}\n\n" \
+             "Each holds its pull request and nothing else. Run `openlanes run`\n" \
+             "to have the specification written from what the pull request actually did.")
+      end
+
+      # @param count [Integer] titles retitled, or that would be
+      # @return [void]
+      def footer(count)
+        if @dry_run
+          return if count.zero?
+
+          warn("#{count} retitle#{"s" unless count == 1} pending — nothing was changed.\n" \
+               "Re-run without --dry-run to apply.")
+        else
+          success("Retitled #{count} pull request#{"s" unless count == 1}.")
+        end
+      end
+
+      # @param assumed [Array<OpenLanes::Lifecycle::Resync::Prs::Change>]
+      # @return [void]
+      def assumptions(assumed)
+        return if assumed.empty?
+
+        warn("#{assumed.size} title#{"s" unless assumed.size == 1} would get " \
+             "[#{OpenLanes::NO_PLAN_PREFIX}] because no plan resolved.\n\n" \
+             "That is an assertion about intent, and it is yours to make: check each one\n" \
+             "before committing. A pull request that writes a plan's spec belongs to that\n" \
+             "plan however its branch was named.")
+      end
+    end
+  end
+end

data/lib/openlanes/presentation/reporter.rb

@@ -24,8 +24,11 @@ module OpenLanes
       STATE_WIDTH = Plans::PullRequests::STATES.map { |_, label| UI.display_width(label) }.max
 
       # @param tree [OpenLanes::Plans::Tree]
-      def initialize(tree:)
+      # @param waiting_on [Hash{String => Array<Integer>}] plan number to the
+      #   pull requests open and awaiting a human, from the board snapshot
+      def initialize(tree:, waiting_on: {})
         @tree = tree
+        @waiting_on = waiting_on.transform_keys(&:to_s)
       end
 
       # @return [OpenLanes::Plans::Tree]
@@ -54,7 +57,7 @@ module OpenLanes
       def label_width = @label_width ||= tree.subjects.map { |s| UI.display_width(s.status.label) }.max.to_i + 4
 
       # @return [Integer] widest feature name
-      def title_width = @title_width ||= tree.subjects.map { |s| UI.display_width(s.feature.title) }.max.to_i + 2
+      def title_width = @title_width ||= tree.subjects.map { |s| UI.display_width(title_for(s)) }.max.to_i + 2
 
       # The one place the table's shape is written down. The heading, the plan
       # rows, the continuation lines and the violations all come through here, so
@@ -67,7 +70,7 @@ module OpenLanes
       #
       # @return [String]
       def row(flag, ordinal, emoji, label, title, tail)
-        format("%s %s  %s %s  %s %s", flag, ordinal, emoji, label, title, tail)
+        format("%s %s  %s  %s  %s %s", flag, ordinal, emoji, label, title, tail)
       end
 
       # Cell at which the pull requests start, so a plan's second and third pull
@@ -102,6 +105,25 @@ module OpenLanes
         [UI.paint(text, :bold), UI.paint(rule, :bright_yellow)].join("\n")
       end
 
+      # A plan an agent is working on wears 🔑 before its name (a lock held by
+      # another machine adds where and since when), and a plan
+      # moved aside carries the date it was moved. In the title cell rather
+      # than columns of their own, so the pull requests stay where every other
+      # row puts them.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [String]
+      def title_for(subject)
+        feature = subject.feature
+        title = feature.archived_on ? "#{feature.title} [#{feature.archived_on.strftime("%F")}]" : feature.title
+        lock = Plans::Lock.read(feature.path)
+        return title unless lock
+
+        # A lock from another machine is never cleared, so say whose it is.
+        note = lock.foreign? ? " (held on #{lock.host} since #{lock.started_at.utc.iso8601})" : ""
+        "🔑 #{title}#{note}"
+      end
+
       # One line per plan, plus a continuation line for each extra pull request
       # so that every URL is visible and clickable rather than truncated.
       #
@@ -116,13 +138,40 @@ module OpenLanes
           UI.paint(UI.fit(feature.ordinal.to_s, ORDINAL_WIDTH), :bold),
           UI.fit(feature.status.emoji, EMOJI_WIDTH),
           UI.paint(UI.fit(feature.status.label, label_width), :yellow),
-          UI.paint(UI.fit(feature.title, title_width), :blue, :bold),
-          prs.empty? ? UI.paint("[none yet]", :bright_red) : link(prs.first)
+          UI.paint(UI.fit(title_for(subject), title_width), :blue, :bold),
+          [prs.empty? ? UI.paint("[none yet]", :bright_red) : link(prs.first), *blocks_note(feature.ordinal)].join("  ")
         )
 
         rest = prs.drop(1).map { |pr| (" " * pr_column) + link(pr) }
 
-        [first, *rest, *violation_line(subject)]
+        [first, *rest, *waiting_lines(subject), *violation_line(subject), *dependency_lines(subject)]
+      end
+
+      # What this plan holds up, said in the row's tail so the one line that
+      # answers "why is 050 not moving" is on the plan that causes it.
+      #
+      # @param ordinal [OpenLanes::Plans::Ordinal]
+      # @return [Array<String>]
+      def blocks_note(ordinal)
+        blocked = tree.dependencies.blocks_of(ordinal)
+        blocked.empty? ? [] : [UI.paint("blocks #{blocked.join(", ")}", :cyan)]
+      end
+
+      # Dependency trouble under the plan's row. Every answer comes from
+      # {Plans::Dependencies}; nothing about the graph is computed here.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Array<String>]
+      def dependency_lines(subject)
+        ordinal = subject.feature.ordinal
+        deps = tree.dependencies
+        notes = Plans::Spec.for(subject).problems.grep(/\Adepends_on/).map { |p| [p, :red] }
+        deps.unknown(ordinal).each { |o| notes << ["depends_on: #{o} is not a plan in this tree", :red] }
+        deps.closed(ordinal).each { |o| notes << ["depends_on: #{o} is already done, so the entry is ignored", :yellow] }
+        cycle = deps.cycle_of(ordinal)
+        notes << ["cycle: #{cycle.join(" → ")}", :red] if cycle
+
+        notes.map { |text, colour| (" " * title_column) + UI.paint("↳ #{text}", colour) }
       end
 
       # The URL is left bare rather than wrapped in an OSC 8 hyperlink: the table
@@ -152,6 +201,16 @@ module OpenLanes
         end
       end
 
+      # One line per pull request a human has yet to act on, under the plan.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Array<String>]
+      def waiting_lines(subject)
+        Array(@waiting_on[subject.feature.ordinal.to_s]).map do |number|
+          (" " * title_column) + UI.paint("↳ waiting on you: PR ##{number}", :bright_yellow)
+        end
+      end
+
       # @param subject [OpenLanes::Plans::Subject]
       # @return [Array<String>]
       def violation_line(subject)
@@ -162,7 +221,7 @@ module OpenLanes
 
       # @return [String]
       def footer
-        counts = totals.map { |key, n| "#{Plans::STATUS_BY_KEY.fetch(key).emoji} #{n}" }.join("   ")
+        counts = totals.map { |key, n| "#{Plans::STATUS_BY_KEY.fetch(key).emoji}  #{n}" }.join("   ")
         lines = ["  #{tree.subjects.size} #{tree.subjects.size == 1 ? "plan" : "plans"}   #{counts}"]
 
         unless inconsistent.empty?

data/lib/openlanes/presentation.rb

@@ -15,9 +15,28 @@ module OpenLanes
 
     # @param tree [OpenLanes::Plans::Tree]
     # @return [OpenLanes::Presentation::Reporter]
-    def reporter(tree:) = Reporter.new(tree:)
+    def reporter(tree:) = Reporter.new(tree:, waiting_on: waiting_on(tree))
+
+    # What the engine's watch last saw a person owe, read only while that
+    # engine is up: once it stops, nobody is watching, and a pull request
+    # merged since would still be listed as waiting.
+    #
+    # @param tree [OpenLanes::Plans::Tree]
+    # @return [Hash{String => Array<Integer>}]
+    def waiting_on(tree)
+      state = Engine.state_file(tree).load
+      state.running? ? state.waiting_on : {}
+    end
+
+    # @param changes [Array<OpenLanes::Lifecycle::Resync::Prs::Change>]
+    # @param dry_run [Boolean]
+    # @return [OpenLanes::Presentation::PrChanges]
+    def pr_changes(changes, dry_run:) = PrChanges.new(changes, dry_run:)
 
     # @return [OpenLanes::Presentation::Viewer]
     def viewer = Viewer.new
+
+    # @return [OpenLanes::Presentation::ApiDocs] the openapi.yaml files plans carry
+    def api_docs = ApiDocs.new
   end
 end

data/lib/openlanes/setup/check.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Setup
+    # One question asked of the machine, and its answer.
+    #
+    # @!attribute name   [String] what was checked, as the report labels it
+    # @!attribute ok     [Boolean]
+    # @!attribute detail [String] what was found
+    # @!attribute fix    [String, nil] the command that turns a ✗ into a ✓
+    Check = Data.define(:name, :ok, :detail, :fix) do
+      # @return [Boolean]
+      def ok? = ok == true
+    end
+  end
+end