openlanes 3.0.1 → 3.1.0

data/lib/openlanes/plans/state_machine.rb

@@ -43,7 +43,9 @@ module OpenLanes
         building:           :building_ui,
         building_ui:        :ready_for_review,
         ready_for_review:   :in_review,
-        in_review:          :approved,
+        in_review:          :verifying,
+        verifying:          :completed,
+        completed:          :approved,
         approved:           :deployed,
         rejected:           :building_ui,
         rolled_back:        :ready_for_review,
@@ -52,8 +54,8 @@ module OpenLanes
 
       # One step back along the spine, for the one move that goes backwards: a
       # person discarding an interrupted round (W9) sends the plan back to the
-      # state the work started from. Derived from {SPINE}, walking it from ⚪️:
-      # each state on that path steps back to the one before it, as far as 👀,
+      # state the work started from. Derived from {SPINE}, walking it from ⚪:
+      # each state on that path steps back to the one before it, as far as 🏁,
       # the last state an agent works in. States off the path (🔴 💩 ⏪ and
       # the birth state) have no single state behind them and step back
       # nowhere.
@@ -67,8 +69,8 @@ module OpenLanes
       # a block outranks progress, and `retroactive` is last because it is the
       # absence of documents rather than the presence of any.
       PREFERENCE = %i[
-        discarded rolled_back shit deferred blocked product_blocked
-        deployed approved rejected in_review ready_for_review building_ui building planned ready_for_planning
+        discarded rolled_back shit deferred blocked product_blocked bomb
+        deployed approved rejected completed verifying in_review ready_for_review building_ui building planned ready_for_planning
         researched new
         retroactive
       ].freeze
@@ -77,10 +79,10 @@ module OpenLanes
       # family the current name always wins, because re-deriving it would be a
       # guess dressed up as a correction.
       #
-      # ⭕️ and 🅱️ both mean "a human must decide before this moves"; *which*
+      # ⭕ and 🛑 both mean "a human must decide before this moves"; *which*
       # human is recorded nowhere but the emoji.
       #
-      # ⭐️ 🟡 🎨 look identical on disk: a `spec.md` and a `plan.md` with work
+      # ⭐ 🟡 🎨 look identical on disk: a `spec.md` and a `plan.md` with work
       # units in it. Whether nobody has started, the back end is under way, or
       # the interface is, is recorded only by the agent that renamed the folder
       # when it started. 🟢 👀 🔴 add an open pull request and are just as
@@ -91,16 +93,16 @@ module OpenLanes
       # arriving from outside lands on the weakest member its contents fit.
       # Contents that fit the family justify only its floor, never its ceiling.
       FAMILIES = [
-        %i[blocked product_blocked],
-        %i[planned building building_ui ready_for_review in_review rejected]
+        %i[blocked product_blocked bomb],
+        %i[planned building building_ui ready_for_review in_review verifying completed rejected]
       ].freeze
 
       # States the agent loop leaves alone: work that is finished (✅ 😎), work
-      # that was dropped (❌), and work waiting on a human (⭕️ 🅱️ ☢️).
+      # that was dropped (❌), and work waiting on a human (⭕ 🛑 💣 💤).
       # Everything else is fair game for a specialist.
       #
-      # ✅ Approved is here deliberately. `hansolo-reviewer` advancing a plan to
-      # it is the end of the loop, not a step in it: nothing merges, and no agent
+      # ✅ Approved is here deliberately. A plan reaching it, from 🧪 once its
+      # pull request merged, is the end of the loop, not a step in it: no agent
       # handles `approved`. Merging is the one act in this lifecycle that changes
       # a branch everyone else builds on, and an autonomous loop that does it
       # unattended has no way to be wrong quietly.
@@ -108,7 +110,7 @@ module OpenLanes
       # Moving `approved` out of this list is therefore a decision about blast
       # radius rather than about topology. If it ever moves, something has to own
       # `approved -> deployed`, and today nothing does.
-      SETTLED = %i[approved deployed discarded blocked product_blocked deferred].freeze
+      SETTLED = %i[approved deployed discarded blocked product_blocked bomb deferred].freeze
 
       # Every state an agent that may sign `Blocked` works in. A block the
       # machine refuses is reported as a failed attempt and parks nothing, so a
@@ -127,19 +129,19 @@ module OpenLanes
         OpenLanes::Plans::STATUSES.each { |status| state status.key }
 
         event :specify, guard: :justified? do
-          transitions from: %i[retroactive blocked product_blocked deferred], to: :new
+          transitions from: %i[retroactive blocked product_blocked bomb deferred], to: :new
         end
 
         event :research, guard: :justified? do
-          transitions from: %i[new retroactive blocked product_blocked deferred], to: :researched
+          transitions from: %i[new retroactive blocked product_blocked bomb deferred], to: :researched
         end
 
         # The specification is done and the planner has not started. Entered
         # by the harness when `yoda-writer` completes; `resync` reaches it on
-        # a blank `plan.md`. Without it ⭐️ Planned required a file only the
-        # agent handling ⭐️ Planned writes, and nothing could enter it.
+        # a blank `plan.md`. Without it ⭐ Planned required a file only the
+        # agent handling ⭐ Planned writes, and nothing could enter it.
         event :ready_to_plan, guard: :justified? do
-          transitions from: %i[researched new retroactive shit blocked product_blocked deferred],
+          transitions from: %i[researched new retroactive shit blocked product_blocked bomb deferred],
             to: :ready_for_planning
         end
 
@@ -149,12 +151,12 @@ module OpenLanes
         # planned. What research buys is not enforced here; it is enforced by
         # `yoda-writer` handling `researched` and nothing else.
         event :plan, guard: :justified? do
-          transitions from: %i[ready_for_planning researched new retroactive shit blocked product_blocked deferred],
+          transitions from: %i[ready_for_planning researched new retroactive shit blocked product_blocked bomb deferred],
             to: :planned
         end
 
         event :build, guard: :justified? do
-          transitions from: %i[planned shit approved rolled_back retroactive blocked product_blocked deferred],
+          transitions from: %i[planned shit approved rolled_back retroactive blocked product_blocked bomb deferred],
             to: :building
         end
 
@@ -178,12 +180,34 @@ module OpenLanes
           transitions from: %i[ready_for_review], to: :in_review
         end
 
+        # hansolo's approval no longer ends the loop (plan 014, M1): the app is
+        # run through the pull request's `## How to test` first, by
+        # chewie-verifier, before anything may merge.
+        event :verify, guard: :justified? do
+          transitions from: %i[in_review], to: :verifying
+        end
+
+        # Every pull request is `ready-to-merge` (P1): palpatine weighs each
+        # one, and the engine merges them one at a time.
+        event :complete, guard: :justified? do
+          transitions from: %i[verifying], to: :completed
+        end
+
+        # `in_review` stays a source: a person who merges on GitHub while
+        # hansolo is still reading has approved it all the same (M4). So do
+        # 🧪 and 🏁, for a merge before the engine or palpatine has ruled,
+        # and for the `merge-manually` pull request a person merges (P3).
         event :approve, guard: :justified? do
-          transitions from: %i[in_review retroactive], to: :approved
+          transitions from: %i[in_review verifying completed retroactive], to: :approved
         end
 
+        # From 🧪 as well as 👀: a verification that fails sends the plan back
+        # to the builders exactly as a review that fails does. From 🏁 too:
+        # a pull request that no longer rebases cleanly onto `main` after
+        # its sibling merged goes back to luke and rey (P5), and a person may
+        # still reject one on GitHub while it waits for them.
         event :request_changes, guard: :justified? do
-          transitions from: %i[in_review], to: :rejected
+          transitions from: %i[in_review verifying completed], to: :rejected
         end
 
         event :slop, guard: :justified? do
@@ -202,12 +226,21 @@ module OpenLanes
           transitions from: %i[deployed], to: :rolled_back
         end
 
+        # 💣 leaves back through the block it came from: once an answer is in,
+        # `blocked.md` says whether the question was technical or product, and
+        # the ordinary unblock path takes it from there.
         event :block, guard: :justified? do
-          transitions from: BLOCKABLE, to: :blocked
+          transitions from: BLOCKABLE + %i[bomb], to: :blocked
         end
 
         event :block_on_product, guard: :justified? do
-          transitions from: BLOCKABLE, to: :product_blocked
+          transitions from: BLOCKABLE + %i[bomb], to: :product_blocked
+        end
+
+        # Fired by the aging sweep alone, never by `resync`: a plan others
+        # depend on has sat blocked past the limit, and the run halts on it.
+        event :bomb, guard: :justified? do
+          transitions from: %i[blocked product_blocked], to: :bomb
         end
 
         event :defer, guard: :justified? do
@@ -372,21 +405,21 @@ module OpenLanes
       # The state a folder's contents justify — the answer to "well, what should
       # it be, then?". This is what `resync dirs` renames toward.
       #
-      # Invariants are *minimum* requirements, not exact matches: a ⚪️ folder
-      # that has since grown a `plan.md` still satisfies ⚪️, and is nonetheless
-      # ⭐️ now. So the furthest-justified state wins, and the caller compares it
+      # Invariants are *minimum* requirements, not exact matches: a ⚪ folder
+      # that has since grown a `plan.md` still satisfies ⚪, and is nonetheless
+      # ⭐ now. So the furthest-justified state wins, and the caller compares it
       # against the current one to decide whether anything should move.
       #
       # The exception is a {FAMILIES family}, whose members contents cannot tell
       # apart. Two rules cover it:
       #
       # - **Already inside one** — the current name wins. Re-deriving it would be
-      #   a guess dressed up as a correction, and every ⭕️ would become 🅱️.
+      #   a guess dressed up as a correction, and every ⭕ would become 🛑.
       # - **Arriving from outside** — the *weakest* member the contents fit
       #   wins, not the furthest. A 📋 folder whose `plan.md` grew work units
-      #   lands on ⭐️, not 🟡, because nobody has started. A ✅ folder found
+      #   lands on ⭐, not 🟡, because nobody has started. A ✅ folder found
       #   with an open pull request is demonstrably back in the PR phase, and
-      #   ⭐️ refuses an open pull request, so it lands on 🟡 rather than
+      #   ⭐ refuses an open pull request, so it lands on 🟡 rather than
       #   claiming 🔴.
       #
       # @return [OpenLanes::Plans::Status, nil] nil when nothing fits at all

data/lib/openlanes/plans/status.rb

@@ -57,7 +57,7 @@ module OpenLanes
     RESEARCH_CHAPTER = /^[ \t]{0,3}\#{2,3}[ \t]+Research\b/i
 
     # What proves `plan.md` holds a plan rather than the blank file
-    # `yoda-writer` leaves for `palpatine-planner`: any section heading. The
+    # `yoda-writer` leaves for `luthen-rael-planner`: any section heading. The
     # ledger notes are stripped first, so an agent's `Started` line does not
     # count as a plan.
     PLAN_HEADING = /^[ \t]{0,3}\#{1,3}[ \t]+\S/
@@ -143,7 +143,7 @@ module OpenLanes
     STATUSES = [
       Status.new(
         key:       :new,
-        emoji:     "⚪️",
+        emoji:     "⚪",
         label:     "New",
         requires:  %w[spec.md],
         note:      "a specification exists; it has not been planned yet",
@@ -173,7 +173,7 @@ module OpenLanes
       ),
       Status.new(
         key:       :planned,
-        emoji:     "⭐️",
+        emoji:     "⭐",
         label:     "Planned",
         requires:  %w[spec.md plan.md],
         note:      "specified and planned; nobody has started building",
@@ -193,7 +193,7 @@ module OpenLanes
       # written by opening a pull request, which happens once, when the last
       # implementer advances the plan to Ready for Review. Requiring the file to
       # *enter* Building would mean nothing could ever justify entering it, and
-      # `palpatine-planner` finishing `plan.md` would loop forever between itself
+      # `luthen-rael-planner` finishing `plan.md` would loop forever between itself
       # and a state it can never actually reach. Ready for Review is where the
       # file becomes a real requirement, once something has had the chance to
       # write it.
@@ -240,6 +240,28 @@ module OpenLanes
         note:      "a reviewer has picked it up and has not ruled yet",
         invariant: open_pull_request("In Review")
       ),
+      Status.new(
+        key:       :verifying,
+        emoji:     "🧪",
+        label:     "Verifying",
+        requires:  %w[spec.md plan.md pull-requests.md],
+        note:      "the review approved it; chewie runs the app through How to test before anything merges",
+        invariant: open_pull_request("Verifying")
+      ),
+      # Completed is not done. `ready-to-merge` is a pull request's state
+      # (P2), and once every pull request of the plan carries it the plan is
+      # 🏁: palpatine rules on each, the engine merges the `auto` ones one at
+      # a time and rebases the rest onto `main`, and `merge-manually` ones
+      # wait for a person. At least one is still open, or the plan would be
+      # ✅ (P3).
+      Status.new(
+        key:       :completed,
+        emoji:     "🏁",
+        label:     "Completed",
+        requires:  %w[spec.md plan.md pull-requests.md],
+        note:      "every pull request is `ready-to-merge`; palpatine weighs each, and they merge one at a time",
+        invariant: open_pull_request("Completed")
+      ),
       Status.new(
         key:       :rejected,
         emoji:     "🔴",
@@ -287,7 +309,7 @@ module OpenLanes
       ),
       Status.new(
         key:       :blocked,
-        emoji:     "⭕️",
+        emoji:     "⭕",
         label:     "Technical Block",
         requires:  %w[blocked.md],
         note:      "cannot proceed; `blocked.md` names what an engineer or the CTO must decide",
@@ -295,15 +317,28 @@ module OpenLanes
       ),
       Status.new(
         key:       :product_blocked,
-        emoji:     "🅱️",
+        emoji:     "🛑",
         label:     "Product Block",
         requires:  %w[blocked.md],
         note:      "cannot proceed; `blocked.md` names what a product manager must decide",
         invariant: open_block("Product Block")
       ),
+      # 💣 is entered only by the aging sweep's `bomb` event, never by what a
+      # folder holds: its contents are a ⭕'s, and a check that read the clock
+      # would rename folders as days pass with nobody firing anything. Its
+      # check is a block's, open question and all: a weaker one would let
+      # `resync` carry a drained ⭕ sideways into 💣 instead of out.
+      Status.new(
+        key:       :bomb,
+        emoji:     "💣",
+        label:     "Bomb",
+        requires:  %w[blocked.md],
+        note:      "blocked too long while other plans depend on it; the run halts until a human answers",
+        invariant: open_block("Bomb")
+      ),
       Status.new(
         key:       :deferred,
-        emoji:     "☢️",
+        emoji:     "💤",
         label:     "Deferred",
         requires:  %w[delayed.md],
         note:      "could proceed and chose not to yet; `delayed.md` must name the trigger",
@@ -314,7 +349,7 @@ module OpenLanes
       ),
       Status.new(
         key:       :retroactive,
-        emoji:     "🕰️",
+        emoji:     "⏪",
         label:     "Retroactive",
         requires:  [],
         note:      "the feature is live, but has neither a specification nor a plan",
@@ -334,12 +369,26 @@ module OpenLanes
       )
     ].freeze
 
-    # Emoji => status, folded so ⚪ and ⚪️ both resolve.
-    STATUS_BY_EMOJI = STATUSES.each_with_object({}) { |s, h| h[fold_emoji(s.emoji)] ||= s }.freeze
-
     # Symbol => status.
     STATUS_BY_KEY = STATUSES.to_h { |s| [s.key, s] }.freeze
 
+    # The emoji each state wore before every one became a single code point
+    # (decision N2). Folders, ledgers and snapshots written before then still
+    # carry them, and a plan named with one must keep its state until
+    # `resync dirs` renames it. Read only, never written. `⚪️ ⭐️ ⭕️` fold onto
+    # their successors anyway; the rest are different characters altogether,
+    # and `🅱` appears both with and without its variation selector.
+    LEGACY_EMOJI = {
+      "⚪️" => :new, "⭐️" => :planned, "⭕️" => :blocked, "🅱️" => :product_blocked, "🅱" => :product_blocked,
+      "☢️" => :deferred, "🕰️" => :retroactive
+    }.freeze
+
+    # Emoji => status, folded so ⚪ and ⚪️ both resolve, and so does every
+    # {LEGACY_EMOJI} spelling.
+    STATUS_BY_EMOJI = STATUSES.each_with_object({}) { |s, h| h[fold_emoji(s.emoji)] ||= s }
+                              .merge(LEGACY_EMOJI.to_h { |e, key| [fold_emoji(e), STATUS_BY_KEY.fetch(key)] }) { |_, now, _| now }
+                              .freeze
+
     # @param emoji [String, nil]
     # @return [OpenLanes::Plans::Status, nil]
     def self.status_for_emoji(emoji) = STATUS_BY_EMOJI[fold_emoji(emoji)]

data/lib/openlanes/plans/subject.rb

@@ -122,10 +122,14 @@ module OpenLanes
           raise Error, "cannot rename #{@feature.dirname} — #{File.basename(target)} already exists"
         end
 
+        from = @feature.status
         @reads = {}
         @pull_requests = nil
         @feature = Feature.parse(target) or raise Error, "#{File.basename(target)} is not a plan folder"
         PlanState.for(target).state!(status.key)
+        # Every transition passes through here, whoever fires it, so this is
+        # the one line in the log that says a plan changed state.
+        UI.log("moved: #{from} → #{status}", plan: @feature.ordinal.to_s)
         @feature
       end
     end

data/lib/openlanes/plans/tree.rb

@@ -3,20 +3,71 @@
 module OpenLanes
   module Plans
     # A project's `.plans` directory: the folders in it, decoded and ordered.
+    #
+    # Finished, deferred and discarded plans live one level down, in the
+    # subfolders {INACTIVE_DIRS} names (decision N3), so the top level holds
+    # only the plans somebody may still work on. A tree reads the top level
+    # by default; `all: true` reads the subfolders too. Plan numbers span
+    # both, since a number is never reused.
     class Tree
+      # Where a plan in an inactive state lives, keyed by status key. The one
+      # table `resync dirs` moves folders by and every reader skips by.
+      INACTIVE_DIRS = {
+        approved:  "archive",
+        deployed:  "archive",
+        deferred:  "deferred",
+        discarded: "abandoned"
+      }.freeze
+
+      # The subfolders themselves, in the order `list-plans --all` shows them.
+      SUBFOLDERS = INACTIVE_DIRS.values.uniq.freeze
+
+      # @param status [OpenLanes::Plans::Status]
+      # @return [String, nil] the subfolder a plan in this state belongs in, nil for the top level
+      def self.subfolder_for(status) = INACTIVE_DIRS[status.key]
+
+      # The plan folder a repository-relative path is inside, looking through
+      # an inactive subfolder: `.plans/archive/003.00━━✅━━❯[…]━━x/spec.md`
+      # names the plan `003.00━━✅━━❯[…]━━x`, not a plan called `archive`.
+      #
+      # @param path [String] e.g. a path from a pull request's diff
+      # @return [String, nil] the folder's name, nil when the path is in no plan
+      def self.plan_folder(path)
+        parts = path.to_s.split("/")
+        index = parts.index(OpenLanes::PLANS_DIR) or return nil
+        parts = parts.drop(index + 1)
+        parts = parts.drop(1) if SUBFOLDERS.include?(parts.first)
+        parts.length >= 2 ? parts.first : nil # a file directly under .plans belongs to no plan
+      end
+
       # @param dir [String] the `.plans` directory
-      def initialize(dir:)
+      # @param all [Boolean] also read the inactive subfolders
+      def initialize(dir:, all: false)
         @dir = File.expand_path(dir)
+        @all = all
       end
 
       # @return [String] absolute path to the `.plans` directory
       attr_reader :dir
 
+      # @return [Boolean] whether the inactive subfolders are read too
+      def all? = @all
+
+      # The same `.plans`, inactive subfolders included.
+      #
+      # @return [OpenLanes::Plans::Tree]
+      def everything = all? ? self : (@everything ||= Tree.new(dir:, all: true))
+
       # @return [Boolean]
       def exist? = File.directory?(dir)
 
-      # @return [Array<OpenLanes::Plans::Feature>] ordered by number
-      def features = @features ||= directories.filter_map { |p| Feature.parse(p) }.sort
+      # Open plans first, then each subfolder in {SUBFOLDERS} order; by
+      # number within each group.
+      #
+      # @return [Array<OpenLanes::Plans::Feature>]
+      def features
+        @features ||= directories.filter_map { |p| Feature.parse(p) }.sort_by { |f| [group(f), f] }
+      end
 
       # @return [Array<OpenLanes::Plans::Subject>] ordered by number
       def subjects = @subjects ||= features.map { |f| Subject.new(f) }
@@ -24,6 +75,12 @@ module OpenLanes
       # @return [Array<OpenLanes::Plans::Ordinal>]
       def ordinals = features.map(&:ordinal)
 
+      # Every number in use, the inactive subfolders included: what a new
+      # plan's number must stay clear of.
+      #
+      # @return [Array<OpenLanes::Plans::Ordinal>]
+      def taken = everything.ordinals
+
       # Directories that carry no plan number. Reported, never processed.
       #
       # @return [Array<String>]
@@ -36,11 +93,13 @@ module OpenLanes
       # make every one of those joins ambiguous, and nothing downstream can tell
       # which folder a `[002.00]` pull request belongs to.
       #
+      # An archived plan still holds its number, so the subfolders count.
+      #
       # @return [Hash{OpenLanes::Plans::Ordinal => Array<String>}] number => dirnames
       def duplicates
-        features.group_by(&:ordinal)
-                .select { |_, group| group.size > 1 }
-                .transform_values { |group| group.map(&:dirname) }
+        everything.features.group_by(&:ordinal)
+                  .select { |_, group| group.size > 1 }
+                  .transform_values { |group| group.map(&:dirname) }
       end
 
       # @param ordinal [OpenLanes::Plans::Ordinal, String]
@@ -53,23 +112,55 @@ module OpenLanes
       # @return [Boolean] whether a plan with this number exists on disk
       def include?(ordinal) = !find(ordinal).nil?
 
+      # Built from {#everything}, not from the open plans alone. A shipped
+      # plan is moved into `archive/`, and read from the top level only, the
+      # prerequisite a dependent waits for would vanish the moment it was
+      # done: unknown, never done, and its dependent held forever.
+      #
+      # @return [OpenLanes::Plans::Dependencies] who waits for whom, read from
+      #   every `depends_on:` in this tree, the inactive subfolders included
+      def dependencies = @dependencies ||= Dependencies.new(everything)
+
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [Array<String>] every plan that waits for this one; derived, never stored
+      def blocks_of(ordinal) = dependencies.blocks_of(ordinal)
+
       # Forget everything read from disk, so a caller that has just renamed
       # folders sees the new state.
       #
       # @return [self]
       def reload
-        @features = @subjects = @skipped = nil
+        @features = @subjects = @skipped = @dependencies = nil
+        @everything&.reload
         self
       end
 
       private
 
-      # @return [Array<String>] absolute paths of every subdirectory
+      # @param feature [OpenLanes::Plans::Feature]
+      # @return [Integer] 0 for the top level, else one past the subfolder's index
+      def group(feature)
+        parent = File.basename(File.dirname(feature.path))
+        File.dirname(feature.path) == dir ? 0 : SUBFOLDERS.index(parent).to_i + 1
+      end
+
+      # @return [Array<String>] absolute paths of every plan-shaped subdirectory
       def directories
         return [] unless exist?
 
-        Dir.children(dir)
-           .map { |c| File.join(dir, c) }
+        top = children(dir).reject { |p| SUBFOLDERS.include?(File.basename(p)) }
+        return top unless all?
+
+        top + SUBFOLDERS.flat_map { |name| children(File.join(dir, name)) }
+      end
+
+      # @param parent [String]
+      # @return [Array<String>]
+      def children(parent)
+        return [] unless File.directory?(parent)
+
+        Dir.children(parent)
+           .map { |c| File.join(parent, c) }
            .select { |p| File.directory?(p) }
            .reject { |p| File.basename(p).start_with?(".") }
            .sort

data/lib/openlanes/plans/verdict.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Plans
+    # The review label the reviewers' comments add up to (decisions R2, R3).
+    #
+    # Every review comment opens with an emoji that declares how much it
+    # matters. Counted across all the reviewers together, in order: any ⛔️ or
+    # 💣 rejects (and a 💣 adds {ReviewLabel::VULNERABILITY} beside the
+    # rejection); otherwise more than `max_hmm` 🤔 is
+    # {ReviewLabel::OK_NOT_PERFECT}; otherwise {ReviewLabel::APPROVED}. A clean
+    # small pull request is approved even if it earned no ✅.
+    #
+    # Pure: it reads strings and answers labels. The threshold comes in as an
+    # argument, so where it is configured ({Config#max_hmm}) is not this
+    # class's business, and nothing here reads GitHub.
+    #
+    # @!attribute [r] labels
+    #   @return [Array<ReviewLabel>] one verdict, or {ReviewLabel::REJECTED}
+    #     and {ReviewLabel::VULNERABILITY} together
+    # @!attribute [r] tally
+    #   @return [Hash{Symbol => Integer}] counted comments, by {MARKS} key
+    # @!attribute [r] ignored
+    #   @return [Array<Comment>] 💣 or 🔓 comments from a reviewer other than
+    #     {SECURITY_REVIEWER}, left out of the tally
+    Verdict = Data.define(:labels, :tally, :ignored) do
+      # @return [Boolean] whether the labels let the pull request go on
+      def passing? = labels.all?(&:passing?)
+
+      # @return [Array<String>] the label names, as `openlanes review` takes them
+      def names = labels.map(&:name)
+    end
+
+    class Verdict
+      # One review comment, and the agent that wrote it. The author has to be
+      # carried alongside the body: every reviewer comments from the same
+      # GitHub account (R2), so GitHub's author says nothing about who wrote it.
+      Comment = Data.define(:agent, :body)
+
+      # The opening emoji, by what they mean. ⛔ is matched with and without
+      # its variation selector (U+FE0F), since editors and models drop it as
+      # often as they keep it; the others tolerate a stray one too.
+      MARKS = {
+        great:    "\u2705",    # ✅ Great!
+        hmm:      "\u{1F914}", # 🤔 Hmmm...
+        must_fix: "\u26D4",    # ⛔️ Must Fix, with or without U+FE0F after it
+        flaw:     "\u{1F4A3}", # 💣 Security Flaw
+        concern:  "\u{1F513}"  # 🔓 Security Concern
+      }.freeze
+
+      # The words each emoji is written with, for a person reading the tally.
+      WORDS = {
+        great: "Great!", hmm: "Hmmm...", must_fix: "Must Fix", flaw: "Security Flaw", concern: "Security Concern"
+      }.freeze
+
+      # Marks only the security reviewer may use. From anyone else a 💣 would
+      # reject a pull request on a reviewer's say-so outside its remit, so it
+      # is dropped and reported rather than counted.
+      SECURITY_MARKS = %i[flaw concern].freeze
+
+      # The one agent whose 💣 and 🔓 count.
+      SECURITY_REVIEWER = "vader-security-reviewer"
+
+      # How many 🤔 a review may carry and still be approved.
+      DEFAULT_MAX_HMM = 5
+
+      # Markdown a comment may open with before its emoji: a heading, a
+      # quote, bold. Anything else first means the comment declares nothing.
+      LEAD = /\A[\s#>*_]*/
+
+      class << self
+        # @param comments [Array<Comment, Hash>] each with `agent:` and `body:`
+        # @param max_hmm [Integer] the most 🤔 an approval may carry
+        # @return [Verdict]
+        def call(comments, max_hmm: DEFAULT_MAX_HMM)
+          tally = MARKS.keys.to_h { [it, 0] }
+          ignored = []
+          comments.each do |raw|
+            comment = coerce(raw)
+            mark = mark_of(comment.body)
+            next if mark.nil?
+
+            if SECURITY_MARKS.include?(mark) && comment.agent.to_s != SECURITY_REVIEWER
+              ignored << comment
+              next
+            end
+            tally[mark] += 1
+          end
+          new(labels: labels_for(tally, max_hmm), tally:, ignored:)
+        end
+
+        # The mark a comment opens with.
+        #
+        # @param body [String]
+        # @return [Symbol, nil] a {MARKS} key; nil for a comment that declares
+        #   nothing, such as the "Reviewed by ..." header
+        def mark_of(body)
+          text = body.to_s.sub(LEAD, "")
+          MARKS.find { |_, emoji| text.start_with?(emoji) }&.first
+        end
+
+        private
+
+        # @return [Comment]
+        def coerce(raw)
+          return raw if raw.is_a?(Comment)
+
+          Comment.new(agent: raw[:agent] || raw["agent"], body: raw[:body] || raw["body"])
+        end
+
+        # @return [Array<ReviewLabel>]
+        def labels_for(tally, max_hmm)
+          if tally[:must_fix].positive? || tally[:flaw].positive?
+            [ReviewLabel::REJECTED, *(ReviewLabel::VULNERABILITY if tally[:flaw].positive?)]
+          elsif tally[:hmm] > max_hmm
+            [ReviewLabel::OK_NOT_PERFECT]
+          else
+            [ReviewLabel::APPROVED]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/plans.rb

@@ -35,5 +35,24 @@ module OpenLanes
     # @param project [String, nil]
     # @return [OpenLanes::Plans::Index]
     def index(tree:, project: nil) = Index.new(tree:, project:)
+
+    # The review label the reviewers' comments add up to (R3). A 💣 or 🔓
+    # from anyone but the security reviewer is left out, and said in the log,
+    # so a reviewer straying outside its remit is visible rather than silent.
+    #
+    # @param comments [Array<OpenLanes::Plans::Verdict::Comment, Hash>] each
+    #   with `agent:` and `body:`
+    # @param max_hmm [Integer] defaults to `review.max_hmm`, or
+    #   `$OPENLANES_REVIEW_MAX_HMM` over it
+    # @return [OpenLanes::Plans::Verdict]
+    def verdict(comments, max_hmm: Config.current.max_hmm)
+      Verdict.call(comments, max_hmm:).tap do |verdict|
+        verdict.ignored.each do |comment|
+          UI.log("ignored #{Verdict::MARKS[Verdict.mark_of(comment.body)]} from #{comment.agent || "an unnamed reviewer"}: " \
+                 "only #{Verdict::SECURITY_REVIEWER} may use it",
+            level: :warn)
+        end
+      end
+    end
   end
 end