openlanes 3.0.0 → 3.1.0

data/lib/openlanes/lifecycle/create_workflow.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module OpenLanes
+  module Lifecycle
+    # `openlanes create` without the command: read the seed, fetch the pull
+    # requests, mint the folder, and either reconstruct its spec from the
+    # pull requests or scaffold and draft a new one.
+    #
+    # The spinner line and the warning boxes for a writer that fell through
+    # draw on STDERR as the work happens. The folder, the success text and
+    # the `spec.md` worth opening come back for the command to print.
+    class CreateWorkflow
+      include UI
+      include Dry::Monads[:result]
+      include Dry::Monads::Do.for(:call)
+
+      # What a create made.
+      #
+      # @!attribute [r] path
+      #   @return [String] the folder, where it ended up
+      # @!attribute [r] message
+      #   @return [String] the success text: what was made and the next step
+      # @!attribute [r] spec
+      #   @return [String, nil] the scaffolded `spec.md`, for a person to open;
+      #     nil when nothing was scaffolded
+      Created = Data.define(:path, :message, :spec)
+
+      # @param dir [String] the `.plans` directory
+      # @param root [String, nil] repository root (default: the .plans parent)
+      # @param after [String, nil] mint a retroactive plan in the gap after this one
+      # @param status [String, nil] open in this state instead of the default
+      # @param prs [String, nil] pull request numbers or URLs, comma separated
+      # @param from [String, nil] a seed markdown file, already resolved
+      # @param spec [Boolean] with +prs+, write spec.md from them
+      # @param draft [Boolean] without +prs+, attempt the four headings
+      # @param lane [String, nil] written into spec.md's frontmatter
+      # @param depth [String, nil] written into spec.md's frontmatter
+      def initialize(dir:, root: nil, after: nil, status: nil, prs: nil, from: nil, spec: true, draft: true,
+        lane: nil, depth: nil)
+        @dir = dir
+        @root = root
+        @after = after
+        @status = status
+        @prs = prs
+        @from = from
+        @spec = spec
+        @draft = draft
+        @settings = { "lane" => lane, "depth" => depth }.compact
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # @param words [Array<String>] the topic; empty when +from+ names it
+      # @return [Dry::Monads::Result] Success({Created}), or Failure({Refusal})
+      #   with 64 (usage), 65 (bad data) or 66 (no seed file)
+      def call(words)
+        FileUtils.mkdir_p(@dir)
+        words, seed = yield resolve_seed(words)
+        prs = yield fetch_prs
+        path = yield mint(words, prs)
+
+        Success(created(path, prs, seed))
+      end
+
+      private
+
+      # @param message [String]
+      # @param status [Integer]
+      # @return [Dry::Monads::Result::Failure]
+      def refusal(message, status) = Failure(Refusal.new(message:, status:))
+
+      # `--from FILE` trades the words argument for a markdown file: the
+      # frontmatter's `title:` names the folder, and the body travels on to
+      # {Brief} as the author's own opening statement. Words and a file are
+      # two answers to one question — the folder's name — so holding both is
+      # refused rather than silently ranked.
+      #
+      # @param words [Array<String>]
+      # @return [Dry::Monads::Result] Success([slug words, seed body or nil])
+      def resolve_seed(words)
+        return Success([words, nil]) unless @from
+
+        unless words.empty?
+          return refusal("--from names the topic by its frontmatter title;\ndrop the words, or drop --from", 64)
+        end
+        if @prs
+          return refusal("--prs reconstructs spec.md from the pull requests, so a seed file\n" \
+                         "would be ignored; use one or the other",
+            64)
+        end
+        return refusal("Could not read the seed file:\n#{@from} does not exist", 66) unless File.file?(@from)
+
+        parse_seed(File.read(@from, encoding: "UTF-8"))
+      end
+
+      # Frontmatter that will not parse used to be reported as a missing
+      # title, which sends the author looking for a `title:` line that is
+      # sitting right there. Say which of the two actually went wrong.
+      #
+      # @param content [String]
+      # @return [Dry::Monads::Result] Success([title words, body])
+      def parse_seed(content)
+        meta, body = Frontmatter.split(content)
+        title = meta["title"].to_s
+        if title.strip.empty?
+          return refusal("The seed file needs a frontmatter title, e.g.\n---\ntitle: Tax Rule DSL\n---", 65)
+        end
+
+        Success([title.split, body.strip])
+      rescue Psych::Exception => e
+        refusal("The seed file's frontmatter is not valid YAML:\n#{e.message}", 65)
+      end
+
+      # A retroactive plan documents work that landed *somewhere* in the
+      # sequence, and only its author knows where. Guessing would put the
+      # number — the one thing that never changes — in the wrong place.
+      #
+      # @return [Dry::Monads::Result] Success(Array<Hash>) or Success(nil) without +prs+
+      def fetch_prs
+        return Success(nil) unless @prs
+
+        unless @after
+          return refusal("--prs documents work that already shipped;\n" \
+                         "name the plan it landed after with --after, e.g. --after 018",
+            64)
+        end
+
+        Success(Vcs.github.pull_requests(Vcs::GitHub.parse_refs(@prs)))
+      rescue OpenLanes::Error => e
+        refusal("Could not read the pull requests:\n#{e.message}", 65)
+      end
+
+      # @param words [Array<String>]
+      # @param prs [Array<Hash>, nil]
+      # @return [Dry::Monads::Result] Success(path)
+      def mint(words, prs)
+        Lifecycle.create(dir: @dir, words:, after: @after, status: @status, prs:)
+                 .alt_map { |message| Refusal.new(message: "Could not create the plan:\n#{message}", status: 65) }
+      end
+
+      # A plan with recorded pull requests already has its facts — hand it to
+      # the writer that reconstructs a specification from a diff. One without
+      # them does not exist yet, and reconstructing is not the job; {#brief} is.
+      #
+      # @param path [String]
+      # @param prs [Array<Hash>, nil]
+      # @param seed [String, nil]
+      # @return [Created]
+      def created(path, prs, seed)
+        from_prs = prs && !prs.empty?
+        spec = nil
+        if from_prs
+          path = synthesize(path) if @spec
+        else
+          spec = brief(path, seed)
+        end
+
+        feature = Plans::Feature.parse(path)
+        Created.new(path:,
+          spec:,
+          message: "Created #{File.basename(path)}\n\n" \
+                   "#{feature.status.emoji} #{feature.status.label} — #{feature.status.note}\n" \
+                   "#{next_step(path, feature, from_prs:)}")
+      end
+
+      # Hand the folder to the writer that already knows how to write a
+      # retroactive specification, then let `resync dirs` decide what the
+      # folder has become — ⏪ is only true while there is no `spec.md`.
+      #
+      # @param path [String]
+      # @return [String] the folder's path, which the resync may have renamed
+      def synthesize(path)
+        agent = OpenLanes::Agents.registry.find(OpenLanes::RETROACTIVE_WRITER) or return path
+
+        feature = Plans::Feature.parse(path)
+        ok, note = on_agent_row("Writing spec.md from #{UI.paint(File.basename(path).to_s, :yellow)}",
+          agent: agent.name,
+          plan:  feature.ordinal.to_s) do |line|
+          Execution.executor(root: root_of(path)).call(agent, Plans.subject(feature), &line)
+        end
+        unless ok
+          error("The folder was created, but spec.md was not written:\n#{note}\n\n" \
+                "The pull requests are recorded. Run `openlanes run` to retry.")
+        end
+
+        settle(path)
+      end
+
+      # A folder with no pull requests to reconstruct from is a feature that
+      # does not exist yet. {Brief} writes the four headings a human still has
+      # to answer and makes a best-effort pass at them from what the project
+      # already has on disk. The folder's state never moves: ⚪ New only ever
+      # claimed that a specification exists, not that it is complete.
+      #
+      # @param path [String]
+      # @param seed [String, nil] the seed body from the `--from` file
+      # @return [String, nil] the scaffolded spec.md; nil for a retroactive folder
+      def brief(path, seed)
+        feature = Plans::Feature.parse(path)
+        return if feature.status.key == :retroactive
+
+        brief = Lifecycle.brief(path:, title: feature.title, root: root_of(path), seed:)
+        brief.write_scaffold!
+        draft(brief, feature, seed) if @draft
+        # After the draft, so a drafting agent that rewrites the file cannot
+        # drop `--lane` and `--depth`.
+        brief.stamp!(@settings)
+        brief.spec_path
+      end
+
+      # @param brief [OpenLanes::Lifecycle::Brief]
+      # @param feature [OpenLanes::Plans::Feature]
+      # @param seed [String, nil]
+      # @return [void]
+      def draft(brief, feature, seed)
+        # Painted the way Runner::Task#label paints a roster agent, so the
+        # half-agent reads as one of them on the terminal.
+        label = "#{UI.paint(Brief::AGENT_NAME, :yellow, :bold)} drafting spec.md from #{seed}"
+        ok, note = on_agent_row(label, agent: Brief::AGENT_NAME, plan: feature.ordinal.to_s) { brief.attempt! }
+        return if ok
+
+        error("spec.md was scaffolded, but the drafting attempt did not finish:\n#{note}\n\n" \
+              "The four headings are there, empty. Fill them in by hand, or hand off to leah-researcher.")
+      end
+
+      # @param path [String] a plan folder
+      # @return [String] the repository root the agents work in
+      def root_of(path) = @root || File.dirname(path, 2)
+
+      # One agent writing spec.md, drawn as a spinner line.
+      #
+      # @param label [String] the spinner line's text
+      # @param agent [String]
+      # @param plan [String]
+      # @yieldparam line [OpenLanes::UI::Line]
+      # @return [Object] the block's value
+      def on_agent_row(label, agent:, plan:, &block)
+        Execution.on_interrupt do
+          UI.concurrently([plan],
+            label,
+            jobs:   1,
+            label:  ->(_) { label },
+            fields: ->(_) { { plan:, agent: } }) { |_, line| block.call(line) }.first
+        end
+      end
+
+      # @param path [String]
+      # @return [String] where the folder ended up
+      def settle(path)
+        change = Lifecycle.resync_dirs(tree: Plans.tree(File.dirname(path)))
+                          .call(commit: true)
+                          .find { |c| c.source == path }
+        change ? change.target : path
+      end
+
+      # @param path [String]
+      # @param feature [OpenLanes::Plans::Feature]
+      # @param from_prs [Boolean]
+      # @return [String]
+      def next_step(path, feature, from_prs:)
+        spec = File.join(File.basename(path), "spec.md")
+        return "Next: write #{spec}" unless feature.status.key == :new && File.file?(File.join(path, "spec.md"))
+        if from_prs
+          return "Next: read #{spec} — it was written from the pull requests, so check it against what actually shipped"
+        end
+
+        "Next: fill in the four headings in #{spec}, then hand off to leah-researcher"
+      end
+    end
+  end
+end

data/lib/openlanes/lifecycle/creator.rb

@@ -33,7 +33,7 @@ module OpenLanes
       # @param after [String, nil] anchor for a retroactive plan, e.g. "002"
       # @param status [String, Symbol, nil] override the default state
       # @param prs [Array<Hash>, nil] pull requests to record, already fetched;
-      #   their presence is what makes the folder 🕰️ Retroactive rather than ⚪️
+      #   their presence is what makes the folder ⏪ Retroactive rather than ⚪
       # @return [Dry::Monads::Result] Success(absolute path) or Failure(message)
       def create(words:, after: nil, status: nil, prs: nil)
         resolved = resolve_status(status, after) or
@@ -42,23 +42,51 @@ module OpenLanes
         slug = self.class.slugify(words)
         return Failure("the topic produced an empty slug") if slug.empty?
 
-        ordinal = after ? retroactive_ordinal(after) : Plans::Ordinal.next_major(existing)
-        return ordinal if ordinal.is_a?(Dry::Monads::Result)
+        # Read the taken numbers and make the folder under one lock, fresh
+        # each time: a number read before the lock was taken may be gone.
+        allocator.hold do
+          @existing = nil
+          ordinal = after ? retroactive_ordinal(after) : Plans::Ordinal.next_major(existing)
+          return ordinal if ordinal.is_a?(Dry::Monads::Result)
 
-        build(ordinal, resolved, slug).fmap { |path| record_pull_requests(path, prs) }
+          build(ordinal, resolved, slug).fmap { |path| record_pull_requests(path, prs) }
+        end
       rescue OpenLanes::Error => e
         Failure(e.message)
       end
 
+      # Archived, deferred and abandoned plans keep their numbers (N3), so a
+      # number that lives only in `archive/` is still taken; so is one that
+      # lives only on another branch, or two checkouts mint it twice.
+      #
       # @return [Array<OpenLanes::Plans::Ordinal>] every number already taken
-      def existing
-        @existing ||= begin
-          return [] unless File.directory?(dir)
+      def existing = @existing ||= allocator.taken
+
+      # @return [OpenLanes::Lifecycle::Allocator] where numbers may come from
+      def allocator = @allocator ||= Allocator.new(dir:)
 
-          Dir.children(dir)
-             .select { |c| File.directory?(File.join(dir, c)) }
-             .filter_map { |c| Plans::Ordinal.from_dirname(c) }
+      # How many words of an idea name its plan.
+      TOPIC_WORDS = 8
+
+      # The words a free-form idea's plan is named after: a frontmatter
+      # `title:`, else its first line, a heading's `#` marks dropped.
+      #
+      # Taking the first words of the raw text named the minesweeper trial's
+      # plan `minesweeper-minesweeper-is-played-on-a-grid`: the idea opened
+      # with `# Minesweeper` and then a paragraph starting with the same
+      # word, and the heading's `#` was dropped while its word was kept.
+      #
+      # @param idea [String] Markdown, as the page's idea dialog sends it
+      # @return [Array<String>] at most {TOPIC_WORDS} words, possibly none
+      def self.topic(idea)
+        meta, body = begin
+          Frontmatter.split(idea.to_s)
+        rescue Psych::Exception
+          [{}, idea.to_s.sub(Frontmatter::PATTERN, '\\2')]
         end
+        title = meta["title"].to_s.strip
+        line = title.empty? ? body.lines.map(&:strip).find { !it.empty? }.to_s : title
+        line.sub(/\A\#{1,6}\s+/, "").split.first(TOPIC_WORDS)
       end
 
       # Turn free text into the kebab tail of a folder name.
@@ -93,7 +121,7 @@ module OpenLanes
         Plans::Ordinal.next_minor(existing, major: anchor.major)
       end
 
-      # Write the pull requests the folder was created from, so 🕰️ Retroactive
+      # Write the pull requests the folder was created from, so ⏪ Retroactive
       # is justified the moment the folder exists — that state means "the work is
       # live and undocumented", and it is the recorded pull requests that make
       # the first half of that true.

data/lib/openlanes/lifecycle/lanes.rb

@@ -8,7 +8,7 @@ module OpenLanes
     # trusts, so research and rewriting are skipped: the harness writes the
     # blank `plan.md` yoda-writer would have left and moves the folder to 📋.
     # A plan in the `quick` lane is a short mechanical task: the harness
-    # writes a one-unit `plan.md` and moves the folder to ⭐️, where
+    # writes a one-unit `plan.md` and moves the folder to ⭐, where
     # r2d2-mechanic is the only builder that serves the lane.
     #
     # Both moves are ordinary transitions through the state machine, so the

data/lib/openlanes/lifecycle/resync.rb

@@ -14,23 +14,35 @@ module OpenLanes
       #
       # - **The emoji is wrong** — the contents justify a different state. A
       #   folder whose status already holds is left alone, which is what stops
-      #   ⭕️ Blocked and 🅱️ Product Blocked — deliberately identical invariants,
+      #   ⭕ Blocked and 🛑 Product Blocked — deliberately identical invariants,
       #   distinguished only by the name — from collapsing into one.
-      # - **The spelling is not canonical** — a folder written `018-⚪️--foo`
-      #   before the `NNN.MM` padding rule or the ` → ` separator, or
-      #   `18.1-⚪️--foo` by hand. Unpadded numbers read fine and sort wrong —
+      # - **The spelling is not canonical** — a folder written `018-⚪--foo`
+      #   before the `NNN.MM` padding rule or the `━━❯` separator, or
+      #   `18.1-⚪--foo` by hand. Unpadded numbers read fine and sort wrong —
       #   `018.09` < `018.1` < `018.10` puts a single mixed-width folder in the
-      #   middle of the range. Both are renamed, to `018.00-⚪️ → foo` and
-      #   `018.01-⚪️ → foo`.
+      #   middle of the range. Both are renamed, to `018.00━━⚪━━❯foo` and
+      #   `018.01━━⚪━━❯foo`.
       #
-      # The repairs are applied in that order reversed, as **up to two renames
-      # per folder**: first the spelling, under the status the folder already
-      # claims — which is how a `--`-era folder migrates to the ` → ` form —
-      # and only then the status its contents justify. Both renames aim at
-      # {Feature.plan_dirname}, so they cannot disagree about the final name;
-      # splitting them keeps each auditable on its own, instead of one report
-      # line where a spelling migration also appears to have opinions about
-      # the state of the work.
+      # - **The folder is in the wrong place** — a plan in an inactive state
+      #   (✅ 😎 💤 ❌) belongs in the subfolder {Plans::Tree::INACTIVE_DIRS}
+      #   names, under a name dated by {Vcs::RenameDate}; a plan in any other
+      #   state belongs at the top level, undated. Moving a plan back out is
+      #   how one is revived: the state machine renames it in place, and the
+      #   next resync brings it home (decision N3).
+      #
+      # The repairs are applied as **up to three renames per folder**: first
+      # the spelling, under the status the folder already claims — which is
+      # how an older folder migrates to the `NNN.MM━━<emoji>━━❯<slug>` form —
+      # then the status its contents justify, then the move. All of them aim
+      # at {Feature.plan_dirname}, so they cannot disagree about the final
+      # name; splitting them keeps each auditable on its own, instead of one
+      # report line where a spelling migration also appears to have opinions
+      # about the state of the work.
+      #
+      # A folder an agent holds a lock on ({Plans::Lock}) keeps its name, the
+      # same as one passed in +except+. A lock left by a process that is gone
+      # from this machine is removed by a committing run; one from another
+      # machine is reported and never touched, since its pid means nothing here.
       class Dirs
         # A proposed rename.
         #
@@ -49,7 +61,46 @@ module OpenLanes
         Change = Data.define(:dirname, :from, :to, :source, :target, :reason) do
           # @return [String] a single auditable line — `⇒` rather than `→`,
           #   which the folder names themselves now contain
-          def to_s = "#{dirname} ⇒ #{File.basename(target)}  (#{reason})"
+          def to_s = "#{dirname} ⇒ #{target_name}  (#{reason})"
+
+          # @return [String] the new name, with its subfolder when it is in one
+          def target_name
+            parent = File.basename(File.dirname(target))
+            Plans::Tree::SUBFOLDERS.include?(parent) ? "#{parent}/#{File.basename(target)}" : File.basename(target)
+          end
+        end
+
+        # A spec.md whose `how-to-verify:` key moves into its body (M10).
+        #
+        # @!attribute [r] dirname
+        #   @return [String] the plan folder, as it stands
+        # @!attribute [r] path
+        #   @return [String] the spec, absolute
+        Rewrite = Data.define(:dirname, :path) do
+          # @return [String]
+          def reason = "how-to-verify: moves into #{Plans::Spec::HOW_TO_VERIFY_HEADING}"
+
+          # @return [String]
+          def to_s = "#{dirname}/#{File.basename(path)}  (#{reason})"
+        end
+
+        # A lock file found on the way.
+        #
+        # @!attribute [r] dirname
+        #   @return [String] the plan folder it is in
+        # @!attribute [r] path
+        #   @return [String] the plan folder, absolute
+        # @!attribute [r] lock
+        #   @return [OpenLanes::Plans::Lock]
+        HeldLock = Data.define(:dirname, :path, :lock) do
+          # @return [Boolean] written on this machine by a process that is gone
+          def stale? = lock.stale?
+
+          # @return [Boolean] written on another machine, so never cleared here
+          def foreign? = !lock.local?
+
+          # @return [String]
+          def to_s = "#{dirname}: locked by pid #{lock.pid} on #{lock.host} since #{lock.started_at.utc.iso8601}"
         end
 
         # The state a folder's contents justify, or the one it claims when
@@ -78,17 +129,44 @@ module OpenLanes
         #
         # @return [Array<OpenLanes::Lifecycle::Resync::Dirs::Change>]
         def plan
-          tree.subjects.flat_map do |subject|
-            @except.include?(subject.feature.ordinal.to_s) ? [] : changes_for(subject)
+          held = held_paths
+          tree.everything.subjects.flat_map { |subject| left_alone?(subject, held) ? [] : changes_for(subject) }
+        end
+
+        # Specs that still carry `how-to-verify:` in their frontmatter.
+        #
+        # @return [Array<OpenLanes::Lifecycle::Resync::Dirs::Rewrite>]
+        def rewrites
+          held = held_paths
+          tree.everything.subjects.filter_map do |subject|
+            next if left_alone?(subject, held)
+
+            path = File.join(subject.feature.path, Plans::Spec::FILENAME)
+            next unless File.file?(path)
+
+            text = File.read(path, encoding: "UTF-8")
+            Rewrite.new(dirname: subject.feature.dirname, path:) unless Plans::Spec.migrate_how_to_verify(text).equal?(text)
+          end
+        end
+
+        # Every lock file in the tree, inactive subfolders included.
+        #
+        # @return [Array<OpenLanes::Lifecycle::Resync::Dirs::HeldLock>]
+        def locks
+          tree.everything.subjects.filter_map do |subject|
+            lock = Plans::Lock.read(subject.feature.path) or next
+            HeldLock.new(dirname: subject.feature.dirname, path: subject.feature.path, lock:)
           end
         end
 
-        # @param commit [Boolean] actually rename
+        # @param commit [Boolean] actually rename, and clear stale local locks
         # @return [Array<OpenLanes::Lifecycle::Resync::Dirs::Change>] what was proposed
         def call(commit: false)
           changes = plan
           return changes unless commit
 
+          locks.select(&:stale?).each { |held| Plans::Lock.remove(held.path) }
+          rewrites.each { |rewrite| rewrite_spec(rewrite.path) }
           UI.stepping(changes, "Renaming") { |change| rename(change) }
           tree.reload
           changes
@@ -96,6 +174,22 @@ module OpenLanes
 
         private
 
+        # @return [Array<String>] plan folders a live or foreign lock holds
+        def held_paths = locks.reject(&:stale?).map(&:path)
+
+        # @param subject [OpenLanes::Plans::Subject]
+        # @param held [Array<String>]
+        # @return [Boolean] whether an agent may be inside it right now
+        def left_alone?(subject, held)
+          @except.include?(subject.feature.ordinal.to_s) || held.include?(subject.feature.path)
+        end
+
+        # @param path [String] a spec.md
+        # @return [void]
+        def rewrite_spec(path)
+          File.write(path, Plans::Spec.migrate_how_to_verify(File.read(path, encoding: "UTF-8")))
+        end
+
         # A folder moves when the name it has is not the name it should have.
         # {target} says what that name is; this says how to get there, as up
         # to two renames applied in order. The status rename starts from where
@@ -113,40 +207,71 @@ module OpenLanes
 
           spelled = feature.dirname_as(subject.status)
           if spelled != feature.dirname
-            steps << step(feature,
-              from:   subject.status,
+            steps << step(from:   subject.status,
               to:     subject.status,
               source: feature.path,
+              target: beside(feature.path, spelled),
               reason: spelling_reason(feature))
           end
 
           if fit.key != subject.status.key
             source = steps.empty? ? feature.path : steps.last.target
-            steps << step(feature,
-              from:   subject.status,
+            steps << step(from:   subject.status,
               to:     fit,
               source:,
+              target: beside(source, feature.dirname_as(fit)),
               reason: subject.violation || "contents now justify #{fit.label}")
           end
 
+          source = steps.empty? ? feature.path : steps.last.target
+          home = home_for(feature, fit)
+          steps << step(from: fit, to: fit, source:, target: home, reason: placement_reason(feature, fit)) if home != source
+
           steps
         end
 
-        # @param feature [OpenLanes::Plans::Feature]
         # @param from [OpenLanes::Plans::Status]
         # @param to [OpenLanes::Plans::Status]
         # @param source [String] absolute path the rename starts from
+        # @param target [String] absolute path it ends at
         # @param reason [String]
         # @return [OpenLanes::Lifecycle::Resync::Dirs::Change]
-        def step(feature, from:, to:, source:, reason:)
-          Change.new(
-            dirname: File.basename(source),
-            from:    from.key,
-            to:      to.key,
-            source:,
-            target:  File.join(File.dirname(feature.path), feature.dirname_as(to)),
-            reason:
-          )
+        def step(from:, to:, source:, target:, reason:)
+          Change.new(dirname: File.basename(source), from: from.key, to: to.key, source:, target:, reason:)
+        end
+
+        # @param path [String]
+        # @param name [String]
+        # @return [String] +name+ in the same directory as +path+
+        def beside(path, name) = File.join(File.dirname(path), name)
+
+        # Where a plan in this state lives, and under which name: an inactive
+        # plan in its subfolder, dated, keeping a date it already carries
+        # there; any other plan at the top level, undated.
+        #
+        # @param feature [OpenLanes::Plans::Feature]
+        # @param status [OpenLanes::Plans::Status]
+        # @return [String] absolute
+        def home_for(feature, status)
+          subfolder = Plans::Tree.subfolder_for(status)
+          return File.join(tree.dir, feature.dirname_as(status, archived_on: nil)) unless subfolder
+
+          parent = File.join(tree.dir, subfolder)
+          date = (feature.archived_on if File.dirname(feature.path) == parent) || Vcs::RenameDate.for(feature.path)
+          File.join(parent, feature.dirname_as(status, archived_on: date))
+        end
+
+        # @param feature [OpenLanes::Plans::Feature]
+        # @param status [OpenLanes::Plans::Status]
+        # @return [String]
+        def placement_reason(feature, status)
+          subfolder = Plans::Tree.subfolder_for(status)
+          here = File.dirname(feature.path)
+          return "#{status.label} lives in #{subfolder}/" if subfolder && here != File.join(tree.dir, subfolder)
+          return "a plan moved aside carries the date it was moved" if subfolder
+          return "#{status.label} is not inactive; back to #{File.basename(tree.dir)}/" if here != tree.dir
+
+          "an open plan's name carries no date"
         end
 
         # @param feature [OpenLanes::Plans::Feature]
@@ -154,19 +279,26 @@ module OpenLanes
         def spelling_reason(feature)
           return "#{feature.dirname_ordinal} is not padded to #{feature.ordinal}" unless feature.padded?
 
-          "name is not in canonical NNN.MM-<emoji> → <slug> form"
+          "name is not in canonical NNN.MM━━<emoji>━━❯<slug> form"
         end
 
         # A rename that finds its target occupied has not happened, and saying
         # nothing about it would leave the folder misnamed with a report
         # claiming otherwise. Two folders can want the same canonical name —
-        # `018-⚪️--foo` and `018.00-⚪️ → foo` are the same plan written twice.
+        # `018-⚪--foo` and `018.00━━⚪━━❯foo` are the same plan written twice.
         #
         # @param change [OpenLanes::Lifecycle::Resync::Dirs::Change]
         # @return [void]
         # @raise [OpenLanes::Error] when the target name is already taken
         def rename(change)
-          return if OpenLanes.move_directory(change.source, change.target)
+          if OpenLanes.move_directory(change.source, change.target)
+            # Counted like any other move, so a session left in the state
+            # the plan has just been taken out of is not resumed when it
+            # comes back. A folder with no state.json has no session to lose.
+            state = Plans::PlanState.for(change.target)
+            state.state!(change.to) if change.from != change.to && state.exist?
+            return
+          end
 
           raise Error, "cannot rename #{change.dirname} — #{File.basename(change.target)} already exists"
         end
@@ -346,7 +478,7 @@ module OpenLanes
           match = BRANCH_PATTERN.match(pull[:branch].to_s) or return nil
           ordinal = Plans::Ordinal.parse(match[1])
 
-          unless tree.include?(ordinal)
+          unless tree.everything.include?(ordinal)
             return flag(pull, "branch names #{ordinal}, which has no folder in #{File.basename(tree.dir)}")
           end
 
@@ -369,13 +501,9 @@ module OpenLanes
         # @param path [String] a path from the diff
         # @return [OpenLanes::Plans::Ordinal, nil]
         def ordinal_for_path(path)
-          parts = path.to_s.split("/")
-          index = parts.index(OpenLanes::PLANS_DIR) or return nil
-          folder = parts[index + 1] or return nil
-          return nil if parts.length <= index + 2 # a file directly under .plans belongs to no plan
-
+          folder = Plans::Tree.plan_folder(path) or return nil
           ordinal = Plans::Ordinal.from_dirname(folder)
-          ordinal if ordinal && tree.include?(ordinal)
+          ordinal if ordinal && tree.everything.include?(ordinal)
         end
 
         # @param pull [Hash]