openlanes 3.0.1 → 3.1.0

data/lib/openlanes/plans/choices.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Plans
+    # A question for a person, read as D3 shapes it: a short context paragraph,
+    # then lettered options `a)`, `b)`, `c)`, one of them recommended. The page
+    # draws a button per option, and `openlanes unblock` would offer the same
+    # ones, so both read them here rather than each guessing from the prose.
+    #
+    # Agents are told to write only that shape, but files written before D3,
+    # and agents that drift, use others. {.parse} reads them forgivingly:
+    #
+    # - lettered: `a)`, `(a)` or `a.` at the start of a line, or `a)` and
+    #   `(a)` inline, the way agents actually run a whole choice into one
+    #   paragraph; bullet-prefixed or bold-wrapped (`- **a)**`) alike
+    # - numbered: `1.`, `1)` or `Option 1:` at the start of a line
+    # - the W30 mark, `answers: yes, no`, which reads as `a) yes` `b) no`
+    #
+    # It is pure: text in, a value out, no file and no network. Whether the
+    # text really asks the reader to choose is a judgement the parser cannot
+    # make about a numbered list of steps already done, which is why the
+    # snapshot can ask {Live::ChoiceJudge} as well.
+    #
+    # @example
+    #   choices = Plans::Choices.parse("Rebase or merge?\n\na) Rebase (Recommended)\nb) Merge")
+    #   choices.context                 # => "Rebase or merge?"
+    #   choices.options.map(&:answer)   # => ["a) Rebase", "b) Merge"]
+    #   choices.recommended.letter      # => "a"
+    class Choices < Data.define(:context, :options)
+      # The text the person's choice sends back to the agent, beside how the
+      # option is shown. A yes/no option answers with the bare word, as W30
+      # promised agents ("branch on the word"); every other answers with its
+      # letter and label, so the agent can match either.
+      #
+      # @!attribute letter [String] "a", "b", …
+      # @!attribute label [String] what the button says, the marker stripped
+      # @!attribute recommended [Boolean]
+      # @!attribute answer [String] what choosing it sends
+      Option = Data.define(:letter, :label, :recommended, :answer) do
+        # @return [Hash] the page's `QuestionOption`
+        def to_h = { letter:, label:, recommended:, answer: }
+      end
+
+      # How an agent marked a yes/no question before D3 (W30), on its own line.
+      # Still read, and still what the prompt shows for a plain yes/no.
+      YES_NO_MARK = "answers: yes, no"
+
+      # {YES_NO_MARK}, read forgivingly: brackets, case and spacing vary.
+      YES_NO = /answers:\s*\[?\s*yes\s*,\s*no\s*\]?/i
+
+      # A letter's marker. At the start of a line (after a bullet or bold) it
+      # may be `a)`, `(a)` or `a.`, either case; inline only the parenthesised
+      # lowercase forms count, because `e.g.` and `I.` are prose.
+      LETTER_LINE = /^[ \t]*(?:[-*+][ \t]+)?(?:\*\*)?(?:\(([a-z])\)|([a-z])[).])(?:\*\*)?[ \t]+/i
+      LETTER_INLINE = /(?<=[\s:])(?:\*\*)?(?:\(([a-z])\)|([a-z])\))(?:\*\*)?[ \t]+/
+
+      # A number's marker, line start only: `1.`, `1)`, `Option 1:`.
+      NUMBER_LINE = /^[ \t]*(?:[-*+][ \t]+)?(?:\*\*)?(?:option[ \t]+(\d{1,2})[:.)]|(\d{1,2})[.)])(?:\*\*)?[ \t]+/i
+
+      # A numbered list is also how agents report steps already done, so one
+      # counts as a choice only after something that asks.
+      ASKS = /\?|\b(?:choose|chose|pick|prefer|option|which|decide)\b/i
+
+      # The recommendation, in the ways it gets written: bracketed anywhere
+      # (`(Recommended)`, `[recommended]`), or bare as the option's first or
+      # last word ("Recommended. Rebase first"). A bare "recommended" mid-label
+      # is prose ("the recommended layout") and stays where it is.
+      RECOMMENDED = /
+        [[:blank:]]*(?:\*\*|_)?[(\[][[:blank:]]*recommended[[:blank:]]*[)\]](?:\*\*|_)?[[:blank:]]*[.:,;]?
+        | \A(?:\*\*|_)?recommended(?:\*\*|_)?[[:blank:]]*[.:,;—–-][[:blank:]]*
+        | [[:blank:]]*[—–-][[:blank:]]*(?:\*\*|_)?recommended(?:\*\*|_)?\.?\z
+      /ix
+
+      # The option the page's text box already is. D3 makes it the last
+      # choice of every question, so an agent that writes it out gets no
+      # second, dead button.
+      SOMETHING_ELSE = /\A(?:type|write|say)\s+something\s+(?:else\s+)?instead\b|\Asomething\s+else\b|\Aother\b/i
+
+      # A label that runs into a new paragraph is not a label: the list ended
+      # and prose followed it, so the options are not the end of the text.
+      PARAGRAPH = /\n[ \t]*\n/
+
+      class << self
+        # @param text [String, nil] a question's body, Markdown
+        # @return [OpenLanes::Plans::Choices, nil] nil when the text offers
+        #   fewer than two options, or its options are not where it ends
+        def parse(text)
+          text = text.to_s.strip
+          return nil if text.empty?
+
+          marked(text) || lettered(text) || numbered(text)
+        end
+
+        # A yes/no question about +context+.
+        #
+        # @param context [String]
+        # @return [OpenLanes::Plans::Choices]
+        def yes_no(context)
+          new(context: context.to_s.strip,
+            options: [Option.new(letter: "a", label: "yes", recommended: false, answer: "yes"),
+                      Option.new(letter: "b", label: "no", recommended: false, answer: "no")])
+        end
+
+        # The D3 shape, written out: the context, a blank line, then one
+        # lettered line per label with the recommended one marked. {.parse}
+        # reads it back into the same labels, which is how a rewritten
+        # question proves it kept its shape.
+        #
+        # @param context [String]
+        # @param labels [Array<String>] one line each
+        # @param recommended [Integer] the index of the recommended label
+        # @return [String] Markdown, ending in a newline
+        def write(context:, labels:, recommended:)
+          lines = labels.each_with_index.map do |label, i|
+            "#{("a".ord + i).chr}) #{label}#{" (Recommended)" if i == recommended}"
+          end
+          "#{context.to_s.strip}\n\n#{lines.join("\n")}\n"
+        end
+
+        private
+
+        # The W30 mark, on a line of its own.
+        def marked(text)
+          line = /^[ \t]*#{YES_NO.source}[ \t]*$\n?/i
+          return nil unless text.match?(line)
+
+          yes_no(text.gsub(line, ""))
+        end
+
+        # A line's marker also matches inline from its letter on, so the
+        # inline match inside one (the `a)` of `- a)`) is dropped: kept, it
+        # would leave the bullet behind at the end of the context.
+        def lettered(text)
+          lines = scan(text, LETTER_LINE) { |m| (m[1] || m[2]).downcase.ord - "a".ord }
+          inline = scan(text, LETTER_INLINE) { |m| (m[1] || m[2]).ord - "a".ord }
+                   .reject { |start, _, _| lines.any? { |from, to, _| (from...to).cover?(start) } }
+          run(text, (lines + inline).sort_by(&:first))
+        end
+
+        def numbered(text)
+          markers = scan(text, NUMBER_LINE) { |m| (m[1] || m[2]).to_i - 1 }
+          choices = run(text, markers)
+          choices if choices&.context&.match?(ASKS)
+        end
+
+        # Every marker in +text+ as `[start, finish, index]`, index 0 for `a`
+        # or `1`.
+        def scan(text, pattern)
+          found = []
+          text.scan(pattern) do
+            match = Regexp.last_match
+            found << [match.begin(0), match.end(0), yield(match)]
+          end
+          found
+        end
+
+        # The last run of markers that counts 0, 1, 2… up to the end of the
+        # text. The last, because a context may itself mention "a) or b)"
+        # before the real options; and to the end, because a list followed by
+        # more prose was something other than a choice.
+        def run(text, markers)
+          markers.each_index.reverse_each do |first|
+            next unless markers[first].last.zero?
+
+            picked = sequence(markers.drop(first))
+            next if picked.size < 2
+
+            choices = build(text, picked)
+            return choices if choices
+          end
+          nil
+        end
+
+        # From a marker for index 0, the next marker for 1, then 2, skipping
+        # anything out of order (an `(e)` quoted inside a label).
+        def sequence(markers)
+          markers.each_with_object([]) do |marker, picked|
+            picked << marker if marker.last == picked.size
+          end
+        end
+
+        def build(text, picked)
+          labels = picked.each_with_index.map do |(_, finish, _), i|
+            text[finish...(picked[i + 1]&.first || text.size)].strip
+          end
+          return nil if labels.any? { it.empty? || it.match?(PARAGRAPH) }
+
+          options = labels.each_with_index.map { |label, i| option(label, i) }
+          options.pop if options.last&.label&.match?(SOMETHING_ELSE)
+          return nil if options.size < 2
+
+          new(context: text[0...picked.first.first].strip, options: only_one_recommended(options))
+        end
+
+        def option(raw, index)
+          recommended = raw.match?(RECOMMENDED)
+          label = unbold(raw.sub(RECOMMENDED, " ").strip).strip
+          letter = ("a".ord + index).chr
+          Option.new(letter:, label:, recommended:, answer: "#{letter}) #{label}")
+        end
+
+        # A bold marker leaves its partner behind: `**a) Rebase**` becomes
+        # `Rebase**`. An odd count of `**` means one of them lost its pair.
+        def unbold(label)
+          label = label.sub('**', "") if label.scan("**").size.odd?
+          label = label[2...-2].strip if label.start_with?("**") && label.end_with?("**") && label.size > 4
+          label
+        end
+
+        # D3 says exactly one; an agent that recommends two has recommended
+        # the first, and the page shows one tag rather than several.
+        def only_one_recommended(options)
+          first = options.index(&:recommended)
+          options.each_with_index.map { |o, i| o.recommended && i != first ? o.with(recommended: false) : o }
+        end
+      end
+
+      # @return [OpenLanes::Plans::Choices::Option, nil]
+      def recommended = options.find(&:recommended)
+
+      # @return [Boolean] whether the options are yes and no
+      def yes_no? = options.map(&:label) == %w[yes no]
+
+      # @return [Array<Hash>] the page's `QuestionOption[]`
+      def to_a = options.map(&:to_h)
+    end
+  end
+end

data/lib/openlanes/plans/dependencies.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Plans
+    # Who waits for whom, read from every plan's `depends_on:` and nothing
+    # else. Only the forward edge is written down; `blocks` is derived here
+    # every time and never stored, so dropping a dependency cannot leave a
+    # stale reverse entry behind in the plan it used to name (N6).
+    #
+    # Every answer is an array of canonical `NNN.MM` strings, sorted. Asking
+    # about a plan the tree does not hold answers empty rather than raising.
+    #
+    # Plans joined by an unfinished edge, in either direction, form a group,
+    # and a group works on one plan at a time (#95): the first in topological
+    # order that may start, so two plans that will meet in a common dependent
+    # are never built against each other's moving code. Separate groups run
+    # side by side. An edge to a finished plan joins nothing, so the
+    # dependents of a shipped plan part ways.
+    class Dependencies
+      # The states in which a dependency is done. Everything else, blocked and
+      # deferred included, keeps the dependent waiting.
+      DONE = %i[approved deployed].freeze
+
+      # The states before the build. Work in them is documents only, so a plan
+      # here gives up its group's turn to one whose code is already under way.
+      BEFORE_BUILD = %i[retroactive new researched ready_for_planning planned].freeze
+
+      # @param tree [OpenLanes::Plans::Tree]
+      # @param status_of [#call, nil] the state to judge a plan by, when it is
+      #   not the folder's name. A dry run renames nothing, so without this a
+      #   prerequisite whose contents already say ✅ would still hold its
+      #   dependents back, while a real run would have reconciled it and let
+      #   them start.
+      def initialize(tree, status_of: nil)
+        @tree = tree
+        @status_of = status_of || :status.to_proc
+      end
+
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [Array<String>, nil] the declared list, nil when the key is absent
+      def depends_on(ordinal) = declared[key(ordinal)]
+
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [Array<String>] every plan whose `depends_on` names this one
+      def blocks_of(ordinal) = reverse.fetch(key(ordinal), [])
+
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [Array<String>] declared entries that are not done, unknown ones included
+      def waiting_on(ordinal) = edges(ordinal).reject { done?(it) }
+
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [Array<String>] declared entries with no folder in the tree
+      def unknown(ordinal) = edges(ordinal).reject { states.key?(it) }
+
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [Array<String>] declared entries naming a done plan, which the gate ignores
+      def closed(ordinal) = edges(ordinal).select { done?(it) }
+
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [Array<String>, nil] a shortest cycle through this plan,
+      #   starting and ending with it, or nil when it is on none
+      def cycle_of(ordinal)
+        wanted = key(ordinal)
+        return nil unless looped?(wanted)
+
+        (@rings ||= {})[wanted] ||= ring_from(wanted)
+      end
+
+      # One shortest cycle per tangle of plans that wait on each other, each
+      # starting and ending at the tangle's lowest ordinal. A tangle can hold
+      # more cycles than this; {#cycle_of} names one through any plan in it.
+      #
+      # @return [Array<Array<String>>]
+      def cycles = @cycles ||= components.select { looped?(it.first) }.map { cycle_of(it.first) }.sort
+
+      # Unfinished plans joined by an unfinished edge, in either direction.
+      #
+      # @return [Array<Array<String>>] each group sorted, groups by first ordinal
+      def groups
+        @groups ||= begin
+          # Union-find, walked in a loop rather than recursively, so a long
+          # chain of plans cannot raise SystemStackError inside a tick.
+          root = unfinished.to_h { [it, it] }
+          find = lambda do |x|
+            x = root[x] = root[root[x]] until root[x] == x
+            x
+          end
+          unfinished.each do |from|
+            open_edges.fetch(from).each { |to| root[find.call(from)] = find.call(to) if root.key?(to) }
+          end
+          unfinished.group_by { find.call(it) }.values.map(&:sort).sort
+        end
+      end
+
+      # Each group in topological order, prerequisites first, ties by
+      # ordinal. Plans on a cycle cannot be ordered and come last.
+      #
+      # @return [Array<Array<String>>] parallel to {#groups}
+      def order = @order ||= groups.map { sorted(it) }
+
+      # The plan whose turn it is in this plan's group, or nil when no plan
+      # in it may start: the first in {#order} that may, preferring one whose
+      # build is already under way, so work already done is never stranded.
+      #
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [String, nil]
+      def head(ordinal)
+        wanted = key(ordinal)
+        line = order.find { it.include?(wanted) } or return nil
+        (@heads ||= {}).fetch(line.first) do
+          ready = line.select { startable?(it) }
+          @heads[line.first] = ready.find { !BEFORE_BUILD.include?(states[it]) } || ready.first
+        end
+      end
+
+      # Why the engine must not start this plan, or nil when it may. A cycle
+      # outranks a plain wait, since waiting on a cycle never ends. An entry
+      # naming no plan is said apart from a real wait: a typo such as
+      # "099.00" holds the plan forever, and "waiting on 099.00" in the held
+      # report read like a wait that would end on its own. A plan free of
+      # all three still waits while another plan holds its group's turn.
+      #
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [String, nil] e.g. "waiting on 034.00", "unknown plan 099.00",
+      #   "cycle: 034.00 → 050.00 → 034.00" or "queued behind 034.00"
+      def reason(ordinal)
+        own = own_reason(ordinal) and return own
+
+        first = head(ordinal)
+        "queued behind #{first}" if first && first != key(ordinal)
+      end
+
+      private
+
+      # {#reason} without the group's turn: what this plan's own edges say.
+      #
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [String, nil]
+      def own_reason(ordinal)
+        cycle = cycle_of(ordinal)
+        return "cycle: #{cycle.join(" → ")}" if cycle
+
+        missing = unknown(ordinal)
+        open = waiting_on(ordinal) - missing
+        parts = []
+        parts << "unknown plan #{missing.join(", ")}" unless missing.empty?
+        parts << "waiting on #{open.join(", ")}" unless open.empty?
+        parts.join("; ") unless parts.empty?
+      end
+
+      # @return [Boolean] whether this plan could take its group's turn:
+      #   neither parked nor done, and free of its own reasons to wait
+      def startable?(ordinal) = !StateMachine::SETTLED.include?(states[ordinal]) && own_reason(ordinal).nil?
+
+      # @return [Array<String>] plans in the tree that are not done
+      def unfinished = @unfinished ||= declared.keys.reject { done?(it) }.sort
+
+      # Kahn's algorithm over the group's open edges, taking the lowest
+      # ordinal whenever several plans are free. The free list stays sorted
+      # by binary insertion, so a group of thousands sorts in a blink.
+      #
+      # @param group [Array<String>]
+      # @return [Array<String>]
+      def sorted(group)
+        members = group.to_set
+        pending = group.to_h { |plan| [plan, open_edges.fetch(plan).count { members.include?(it) }] }
+        free = pending.select { |_, n| n.zero? }.keys.sort
+        out = []
+        until free.empty?
+          plan = free.shift
+          out << plan
+          pending.delete(plan)
+          blocks_of(plan).each do |waiter|
+            next unless pending.key?(waiter) && (pending[waiter] -= 1).zero?
+
+            free.insert(free.bsearch_index { it >= waiter } || free.size, waiter)
+          end
+        end
+        out + pending.keys.sort
+      end
+
+      # @return [String]
+      def key(ordinal) = (ordinal.is_a?(Ordinal) ? ordinal : Ordinal.parse(ordinal)).to_s
+
+      # @return [Array<String>]
+      def edges(ordinal) = depends_on(ordinal) || []
+
+      # @return [Boolean]
+      def done?(ordinal) = DONE.include?(states[ordinal])
+
+      # @return [Hash{String => Symbol}] ordinal => status key
+      def states = @states ||= @tree.subjects.to_h { [it.feature.ordinal.to_s, @status_of.call(it).key] }
+
+      # @return [Hash{String => Array<String>, nil}]
+      def declared
+        @declared ||= @tree.subjects.to_h { [it.feature.ordinal.to_s, Spec.for(it).depends_on] }
+      end
+
+      # @return [Hash{String => Array<String>}]
+      def reverse
+        @reverse ||= declared.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(from, tos), out|
+          Array(tos).each { out[it] << from }
+        end.transform_values(&:sort)
+      end
+
+      # The edges that can still hold anything up: entries not yet done that
+      # name a plan in the tree. A dependency on a ✅ plan is already met, so
+      # it closes no cycle; two plans that once named each other stop being
+      # deadlocked the moment one of them ships.
+      #
+      # @return [Hash{String => Array<String>}]
+      def open_edges = @open_edges ||= declared.keys.to_h { [it, waiting_on(it).select { declared.key?(it) }] }
+
+      # @return [Boolean] whether this plan sits on a cycle of open edges
+      def looped?(ordinal)
+        group = group_of[ordinal] or return false
+        group.size > 1 || open_edges.fetch(ordinal).include?(ordinal)
+      end
+
+      # @return [Hash{String => Array<String>}] ordinal => its strongly connected component
+      def group_of = @group_of ||= components.each_with_object({}) { |g, out| g.each { out[it] = g } }
+
+      # Tarjan's strongly connected components over {#open_edges}, so each
+      # plan is visited once. Enumerating every path instead revisited shared
+      # subgraphs on each one: 28 plans each waiting on the two before took
+      # 2.6 seconds and two million visits, and the dispatcher asks on every
+      # tick. The walk keeps its own stack of frames rather than recursing,
+      # so a chain of a few thousand plans cannot raise SystemStackError
+      # inside a dispatcher tick.
+      #
+      # @return [Array<Array<String>>] each component sorted
+      def components
+        @components ||= begin
+          index = {}
+          low = {}
+          stack = []
+          on_stack = {}
+          out = []
+          open_edges.keys.sort.each do |root|
+            next if index.key?(root)
+
+            frames = [[root, 0]]
+            index[root] = low[root] = index.size
+            stack << root
+            on_stack[root] = true
+            until frames.empty?
+              v, i = frames.last
+              w = open_edges.fetch(v)[i]
+              if w
+                frames.last[1] += 1
+                if !index.key?(w)
+                  index[w] = low[w] = index.size
+                  stack << w
+                  on_stack[w] = true
+                  frames << [w, 0]
+                elsif on_stack[w]
+                  low[v] = [low[v], index[w]].min
+                end
+                next
+              end
+
+              frames.pop
+              parent = frames.last&.first
+              low[parent] = [low[parent], low[v]].min if parent
+              next unless low[v] == index[v]
+
+              group = []
+              group << stack.pop.tap { on_stack.delete(it) } until group.last == v
+              out << group.sort
+            end
+          end
+          out
+        end
+      end
+
+      # Breadth-first from +start+ back to itself inside its component, so
+      # the cycle named is a shortest one and the walk is linear.
+      #
+      # @param start [String]
+      # @return [Array<String>]
+      def ring_from(start)
+        group = group_of.fetch(start)
+        parent = { start => nil }
+        queue = [start]
+        until queue.empty?
+          node = queue.shift
+          open_edges.fetch(node).sort.each do |nxt|
+            next unless group.include?(nxt)
+
+            if nxt == start
+              path = [node]
+              path.unshift(parent[path.first]) while parent[path.first]
+              return path + [start]
+            end
+            next if parent.key?(nxt)
+
+            parent[nxt] = node
+            queue << nxt
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/plans/feature.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "date"
+
 module OpenLanes
   module Plans
     # Lowercase in the middle of a title, capitalised at the front.
@@ -45,22 +47,36 @@ module OpenLanes
       }.join(" ")
     end
 
-    # The one place a plan folder's name is spelled out: `NNN.MM-<emoji> → <slug>`.
+    # The heavy rule between the parts of a folder name. No space anywhere, so
+    # a name needs no quoting in a shell, and nothing an emoji can swallow.
+    RULE = "━━"
+
+    # What points from the state to the slug.
+    POINTER = "❯"
+
+    # The one place a plan folder's name is spelled out (decision N1):
+    # `NNN.MM━━<emoji>━━❯<slug>`, or `NNN.MM━━<emoji>━━❯[YYYY-MM-DD]━━<slug>`
+    # once the plan has been moved into an inactive subfolder (N3).
     #
-    # The spaced arrow after the emoji is deliberate: an emoji renders two cells
-    # wide and visually swallows a bare dash beside it, so `🔎-refactor` reads
-    # as if the emoji and the slug were touching. Everything that mints or
-    # renames a folder goes through here; {Feature.parse} accepts the older
-    # `--` and single-dash spellings too, and `resync dirs` migrates them on
-    # contact.
+    # The earlier `NNN.MM-<emoji> → <slug>` put a space in every name, and the
+    # `--` before it let a two-cell emoji swallow the dash beside it.
+    # Everything that mints or renames a folder goes through here; {Feature.parse}
+    # still reads every older spelling, and `resync dirs` migrates them.
     #
     # @param ordinal [OpenLanes::Plans::Ordinal, String]
     # @param status [OpenLanes::Plans::Status]
     # @param slug [String]
+    # @param archived_on [Date, nil] the date the plan was moved aside
     # @return [String]
-    def self.plan_dirname(ordinal, status, slug) = "#{ordinal}-#{status.emoji} → #{slug}"
+    def self.plan_dirname(ordinal, status, slug, archived_on: nil)
+      date = archived_on && "[#{archived_on.strftime("%F")}]#{RULE}"
+      "#{ordinal}#{RULE}#{status.emoji}#{RULE}#{POINTER}#{date}#{slug}"
+    end
+
+    # The current spelling, with or without the archive date.
+    CURRENT_FORM = /\A[\d.]+#{RULE}(?<emoji>[^━]+)#{RULE}#{POINTER}(?:\[(?<date>\d{4}-\d{2}-\d{2})\]#{RULE})?(?<slug>.+)\z/
 
-    # One `NNN.MM-<emoji> → <slug>` folder, decoded.
+    # One plan folder, decoded.
     #
     # @!attribute [r] ordinal
     #   @return [OpenLanes::Plans::Ordinal]
@@ -72,9 +88,14 @@ module OpenLanes
     #   @return [String] exactly as it is on disk
     # @!attribute [r] path
     #   @return [String] absolute
-    Feature = Data.define(:ordinal, :status, :slug, :dirname, :path) do
+    # @!attribute [r] archived_on
+    #   @return [Date, nil] the date in the name of a plan moved aside, else nil
+    Feature = Data.define(:ordinal, :status, :slug, :dirname, :path, :archived_on) do
       include Comparable
 
+      # @param archived_on [Date, nil] optional, so callers that predate it still build one
+      def initialize(archived_on: nil, **) = super
+
       # Decode a folder name, or return nil when it is not a plan folder.
       #
       # @param path [String] absolute path to a candidate directory
@@ -83,29 +104,67 @@ module OpenLanes
         dirname = File.basename(path)
         ordinal = Ordinal.from_dirname(dirname) or return nil
 
+        current(dirname, ordinal, path) || legacy(dirname, ordinal, path)
+      end
+
+      # `NNN.MM━━<emoji>━━❯<slug>`, dated or not.
+      #
+      # An emoji nothing answers to reads as ⚪ New rather than falling through
+      # to {.legacy}, which cannot split this spelling and took the whole name
+      # for the slug; the next rename then wrote
+      # `001.00━━⭕━━❯001.00━━🛑━━❯slug`. A name already nested that way is
+      # read down to its innermost slug, so `resync dirs` can undo it.
+      #
+      # @return [OpenLanes::Plans::Feature, nil]
+      def self.current(dirname, ordinal, path)
+        m = CURRENT_FORM.match(dirname) or return nil
+        status = OpenLanes::Plans.status_for_emoji(m[:emoji]) || STATUS_BY_KEY.fetch(:new)
+        archived_on = m[:date] && Date.iso8601(m[:date], exception: false)
+
+        new(ordinal:, status:, slug: innermost(m[:slug], ordinal), dirname:, path:, archived_on:)
+      end
+
+      # @param slug [String]
+      # @param ordinal [OpenLanes::Plans::Ordinal]
+      # @return [String] +slug+ without any plan prefix of the same ordinal
+      def self.innermost(slug, ordinal)
+        return slug unless Ordinal.from_dirname(slug) == ordinal
+
+        parse(slug)&.slug || slug
+      end
+
+      # `NNN.MM-<emoji> → <slug>`, `NNN-<emoji>--<slug>` and `NNN-<emoji>-<slug>`.
+      #
+      # @return [OpenLanes::Plans::Feature]
+      def self.legacy(dirname, ordinal, path)
         rest = dirname.sub(/\A[\d.]+[-_]/, "")
         head, tail = rest.split(/\s*→\s*|[-_]/, 2)
 
         # A leading segment with no ASCII word character is the status emoji.
-        # The slug strips any further separators: the canonical spelling puts
-        # a spaced arrow after the emoji, and folders from before that rule put
-        # two dashes, or one.
+        # The slug strips any further separators: the arrow spelling put a
+        # spaced arrow after the emoji, and folders from before that put two
+        # dashes, or one.
         status = (OpenLanes::Plans.status_for_emoji(head) if tail && !head.to_s.empty? && !head.match?(/[A-Za-z0-9]/))
         slug = status ? tail.sub(/\A[-_\s]+/, "") : rest
 
         new(ordinal:, status: status || STATUS_BY_KEY.fetch(:new), slug:, dirname:, path:)
       end
+      private_class_method :current, :legacy, :innermost
 
       # @return [String] proper name, e.g. "Law as Data"
       def title = OpenLanes::Plans.titleize(slug)
 
       # The folder name this feature would carry in a given state — the slug
-      # never moves, and the number is always rendered canonically, so this is
-      # also what repairs a folder written `018-⚪️--foo` before the `NNN.MM` rule.
+      # and any archive date never move, and the number is always rendered
+      # canonically, so this is also what repairs a folder written
+      # `018-⚪️--foo` before the `NNN.MM` rule.
       #
       # @param status [OpenLanes::Plans::Status]
+      # @param archived_on [Date, nil] defaults to the date the name carries now
       # @return [String]
-      def dirname_as(status) = OpenLanes::Plans.plan_dirname(ordinal, status, slug)
+      def dirname_as(status, archived_on: self.archived_on)
+        OpenLanes::Plans.plan_dirname(ordinal, status, slug, archived_on:)
+      end
 
       # The number exactly as the folder writes it, which is not always the
       # canonical rendering: `018-⚪️--foo` yields "018" where {#ordinal} renders