openlanes 3.0.0 → 3.1.0

data/lib/openlanes/lifecycle/adoption.rb

@@ -83,15 +83,34 @@ module OpenLanes
       #
       # @param pulls [Array<Hash>] the orphans, from {Resync::Prs}
       # @return [Array<OpenLanes::Lifecycle::Adoption::Adoptee>] in pull request order
+      # @raise [Allocator::Refused] in a linked worktree, where no plan is
+      #   minted, so a preview there says so rather than promising folders
       def plan(pulls)
+        allocator.refuse!
+        @taken = nil
         allocate(gather(pulls))
       end
 
       # Adopt every orphan: create its folder and record its pull request.
       #
+      # The slots are read and the folders made under the allocation lock, or
+      # a `create` running beside this one can take a slot this just handed out.
+      #
       # @param pulls [Array<Hash>]
       # @return [Array<OpenLanes::Lifecycle::Adoption::Adoptee>] with `path` filled in
+      # @raise [Allocator::Refused] in a linked worktree
       def call(pulls)
+        allocator.hold { adopt_all(pulls) }
+      end
+
+      # @return [OpenLanes::Lifecycle::Allocator]
+      def allocator = @allocator ||= Allocator.new(dir: tree.dir)
+
+      private
+
+      # @param pulls [Array<Hash>]
+      # @return [Array<OpenLanes::Lifecycle::Adoption::Adoptee>]
+      def adopt_all(pulls)
         adoptees = plan(pulls)
         return adoptees if adoptees.empty?
 
@@ -100,8 +119,6 @@ module OpenLanes
         created
       end
 
-      private
-
       # Phase one, in parallel: ask each pull request's branch how far the
       # sequence had got when the work started. Branches are not all rebased
       # onto the same main, so this is per-branch rather than tree-wide, and it
@@ -124,7 +141,7 @@ module OpenLanes
       def major_for(pull)
         candidates = OpenLanes.plans_on_ref(root, pull[:branch].to_s)
         candidates = touched(pull) if candidates.empty?
-        candidates = tree.subjects.map { |s| s.feature.ordinal } if candidates.empty?
+        candidates = tree.taken if candidates.empty?
 
         candidates.map(&:major).max.to_i
       end
@@ -133,9 +150,8 @@ module OpenLanes
       # @return [Array<OpenLanes::Plans::Ordinal>]
       def touched(pull)
         Array(pull[:files]).filter_map { |path|
-          parts = path.to_s.split("/")
-          index = parts.index(OpenLanes::PLANS_DIR)
-          index && parts[index + 1] && Plans::Ordinal.from_dirname(parts[index + 1])
+          folder = Plans::Tree.plan_folder(path)
+          folder && Plans::Ordinal.from_dirname(folder)
         }.uniq
       end
 
@@ -159,9 +175,10 @@ module OpenLanes
       end
 
       # @param major [Integer]
-      # @return [Array<Integer>] minors already used under this major
+      # @return [Array<Integer>] minors already used under this major, on
+      #   this tree or on any branch: a slot taken anywhere is taken
       def minors_taken(major)
-        tree.subjects.map { |s| s.feature.ordinal }.select { |o| o.major == major }.map(&:minor)
+        (@taken ||= allocator.taken).select { |o| o.major == major }.map(&:minor)
       end
 
       # Phase three, in parallel: each worker owns a number nobody else can

data/lib/openlanes/lifecycle/aging.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module OpenLanes
+  module Lifecycle
+    # Blocked plans age (N8). A ⭕ or 🛑 that other plans are waiting for
+    # becomes 💣 after {BOMB_AFTER}, and the run halts on it; one nobody waits
+    # for is deferred after {DEFER_AFTER}, with a `delayed.md` naming what
+    # brings it back.
+    #
+    # This is a sweep that fires events, not an invariant that reads the
+    # clock. A state whose check looked at the time would rename folders as
+    # days passed with nobody firing anything, and asking a question about a
+    # folder must never fire one. So 💣 holds by its contents alone, and only
+    # this sweep, run by the engine before it assigns work, moves a plan in.
+    class Aging
+      # How long a plan others depend on may sit blocked before it halts the
+      # run. 24 hour multiples, not calendar days: the limit is the same length
+      # across a daylight saving change.
+      BOMB_AFTER = 7 * 86_400
+
+      # How long a plan nobody depends on may sit blocked before it is set
+      # aside.
+      DEFER_AFTER = 14 * 86_400
+
+      # The states that age. 💣 is not among them: it is already the loudest
+      # thing a block can become, and deferring it would quietly drop a plan
+      # others are waiting for.
+      AGES = %i[blocked product_blocked].freeze
+
+      # Dependents in these states wait for nothing any more: they shipped
+      # (008's {Plans::Dependencies::DONE}) or were dropped.
+      CLOSED = (Plans::Dependencies::DONE + %i[discarded]).freeze
+
+      # What one sweep did, or on a dry run would have done.
+      #
+      # @!attribute [r] bombed
+      #   @return [Array<String>] ordinals now 💣
+      # @!attribute [r] deferred
+      #   @return [Array<String>] ordinals now 💤
+      Result = Data.define(:bombed, :deferred) do
+        def initialize(bombed: [], deferred: []) = super
+
+        # @return [Boolean]
+        def empty? = bombed.empty? && deferred.empty?
+      end
+
+      # @param tree [OpenLanes::Plans::Tree]
+      # @param since [Date, nil] `plans.aging_since`: no plan ages from
+      #   before local midnight on this day
+      # @param now [Time]
+      def initialize(tree:, since: nil, now: Time.now)
+        @tree = tree
+        @since = since
+        @now = now
+      end
+
+      # Bomb or defer every blocked plan among +subjects+ past its limit.
+      #
+      # @param subjects [Array<OpenLanes::Plans::Subject>, nil] the plans to
+      #   age; every plan in the tree when nil
+      # @param commit [Boolean] false reports what would happen and changes
+      #   nothing
+      # @return [Result]
+      def call(subjects: nil, commit: true)
+        bombed = []
+        deferred = []
+        (subjects || @tree.subjects).each do |subject|
+          next unless AGES.include?(subject.status.key)
+
+          age = age_of(subject)
+          if waited_for?(subject)
+            next if age < BOMB_AFTER
+
+            bombed << subject.feature.ordinal.to_s if !commit || bomb!(subject, age)
+          elsif age >= DEFER_AFTER
+            deferred << subject.feature.ordinal.to_s if !commit || defer!(subject, age)
+          end
+        end
+        @tree.reload if commit && !(bombed.empty? && deferred.empty?)
+        Result.new(bombed:, deferred:)
+      end
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Float] seconds the plan has been blocked, as far as aging counts
+      def age_of(subject) = @now - started_at(subject)
+
+      # When the clock started: the latest `Blocked` signature, so a plan
+      # blocked again after an answer starts over, or `blocked.md`'s mtime
+      # when nobody signed, as the control room already reads it. Never
+      # before `aging_since`.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Time]
+      def started_at(subject)
+        signed = Plans::PlanState.for(subject.feature.path).signatures.rfind { it["status"] == "Blocked" }
+        start = signed ? parse(signed["at"]) : nil
+        start ||= File.mtime(File.join(subject.feature.path, "blocked.md"))
+        floor = @since && Time.local(@since.year, @since.month, @since.day)
+        floor && floor > start ? floor : start
+      end
+
+      private
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Boolean] whether a plan still open names this one in `depends_on:`
+      def waited_for?(subject)
+        @tree.blocks_of(subject.feature.ordinal).any? do |ordinal|
+          dependent = @tree.find(ordinal)
+          dependent && !CLOSED.include?(dependent.status.key)
+        end
+      end
+
+      # @return [Boolean] whether the folder moved
+      def bomb!(subject, age)
+        subject.machine.promote!(:bomb)
+        UI.log("aging: 💣 after #{days(age)} blocked, with plans waiting on it", plan: subject.feature.ordinal.to_s)
+        true
+      rescue Plans::StateMachine::Refused => e
+        UI.log("aging: could not bomb: #{e.message}", level: :warn, plan: subject.feature.ordinal.to_s)
+        false
+      end
+
+      # `delayed.md` goes in first: 💤 refuses a folder without a trigger.
+      #
+      # @return [Boolean] whether the folder moved
+      def defer!(subject, age)
+        path = File.join(subject.feature.path, "delayed.md")
+        wrote = !File.exist?(path)
+        File.open(path, "a") { it.write(delayed(subject, age, fresh: wrote)) }
+        subject.machine.promote!(:deferred)
+        UI.log("aging: 💤 after #{days(age)} blocked, with no plan waiting on it", plan: subject.feature.ordinal.to_s)
+        true
+      rescue Plans::StateMachine::Refused => e
+        File.delete(path) if wrote && File.exist?(path)
+        UI.log("aging: could not defer: #{e.message}", level: :warn, plan: subject.feature.ordinal.to_s)
+        false
+      end
+
+      # @return [String]
+      def delayed(subject, age, fresh:)
+        heading = fresh ? "# Deferred: #{subject.feature.ordinal} #{subject.feature.slug}\n\n" : "\n"
+        "#{heading}Deferred by aging on #{@now.strftime("%Y-%m-%d")}: blocked #{days(age)} with no answer, " \
+          "and no open plan depends on it.\n\n" \
+          "Trigger: revisit after the block is answered. The questions are still in `blocked.md`.\n"
+      end
+
+      # @param seconds [Numeric]
+      # @return [String] "8 days"
+      def days(seconds)
+        count = (seconds / 86_400).floor
+        "#{count} day#{"s" unless count == 1}"
+      end
+
+      # @param text [String, nil]
+      # @return [Time, nil]
+      def parse(text)
+        Time.iso8601(text.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/openlanes/lifecycle/allocator.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module OpenLanes
+  module Lifecycle
+    # Who may hand out a plan number, and which numbers are already gone.
+    #
+    # A number used to be the highest one in the `.plans` of whichever
+    # checkout ran `create`. Two checkouts on two branches each saw only
+    # their own folders and minted the same number: `main` stopped at 023
+    # while 024 to 035 lived on an unmerged branch, so `create` on `main`
+    # handed out 024 a second time, and the two plans collided the moment
+    # both branches reached `main`. So, decided 2026-10-17:
+    #
+    # - plans are minted only in the primary checkout, never in a linked
+    #   worktree, so there is one place numbers come from;
+    # - a number counts as taken when it is in that checkout's `.plans`
+    #   (archive and friends included, N3) or in `.plans` on any local
+    #   branch or `origin/*` remote-tracking branch, read with `ls-tree`
+    #   and no fetch;
+    # - the numbers are read and the folder made under an exclusive lock in
+    #   the shared git directory, so two `create`s at once cannot both take
+    #   the number they both just saw was free.
+    #
+    # Decided 2026-10-20, on top of that: the primary checkout must also be on
+    # the default branch (origin's HEAD, else `main`). A plan minted on a
+    # feature branch there is a plan `main` does not know about until that
+    # branch merges, which is the same split by another road. The rule covers
+    # new folders, their opening `spec.md` and `depends_on:`; every other file
+    # in a plan folder is still written from worktrees, as agents do.
+    #
+    # Outside a git repository there are no branches and no worktrees, and
+    # the checkout's own `.plans` is the whole truth, as before.
+    #
+    # {Plans::Ordinal} stays arithmetic over the list this returns; the git
+    # lives here and nowhere else.
+    class Allocator
+      # The lock file, in `git rev-parse --git-common-dir`: the one directory
+      # every worktree of a repository shares.
+      LOCK_FILE = "openlanes-ordinal.lock"
+
+      # Where branches that may carry plans live. Other remotes are someone
+      # else's forks; their numbers were never handed out here.
+      REFS = %w[refs/heads refs/remotes/origin].freeze
+
+      # The branch plans are minted on when origin names no default.
+      DEFAULT_BRANCH = "main"
+
+      # Raised when a plan would be minted in a linked worktree, or in the
+      # primary checkout off its default branch.
+      class Refused < OpenLanes::Error; end
+
+      # The repository around a `.plans` directory, as git reports it.
+      #
+      # @!attribute [r] git_dir
+      #   @return [String] this checkout's git directory, absolute
+      # @!attribute [r] common_dir
+      #   @return [String] the directory every worktree shares, absolute
+      # @!attribute [r] toplevel
+      #   @return [String] this checkout's root
+      # @!attribute [r] plans
+      #   @return [String] the `.plans` directory, relative to +toplevel+
+      # @!attribute [r] branch
+      #   @return [String, nil] the checked-out branch; nil on a detached HEAD
+      # @!attribute [r] default_branch
+      #   @return [String] origin's HEAD, else {DEFAULT_BRANCH}
+      Repository = Data.define(:git_dir, :common_dir, :toplevel, :plans, :branch, :default_branch) do
+        # A linked worktree has a git directory of its own under the common
+        # one; the primary checkout's git directory is the common one.
+        #
+        # @return [Boolean]
+        def worktree? = git_dir != common_dir
+
+        # @return [String] the primary checkout, which owns the common directory
+        def primary = File.basename(common_dir) == ".git" ? File.dirname(common_dir) : common_dir
+
+        # @return [String]
+        def lock_path = File.join(common_dir, LOCK_FILE)
+
+        # @return [Boolean]
+        def on_default_branch? = branch == default_branch
+      end
+
+      # @param dir [String] the `.plans` directory; need not exist yet
+      def initialize(dir:)
+        @dir = File.expand_path(dir)
+      end
+
+      # @return [String]
+      attr_reader :dir
+
+      # @return [Repository, nil] nil outside a git repository
+      def repository = defined?(@repository) ? @repository : (@repository = discover)
+
+      # @return [String, nil] why a plan may not be minted here, or nil when it may
+      def refusal
+        repo = repository or return
+        if repo.worktree?
+          return "plans are created only in the primary checkout, #{repo.primary}; this is a worktree of it"
+        end
+        return if repo.on_default_branch?
+
+        "plans are created only on #{repo.default_branch} in the primary checkout; " \
+          "#{repo.primary} is on #{repo.branch || "a detached HEAD"}"
+      end
+
+      # @return [void]
+      # @raise [Refused] in a linked worktree, or off the default branch
+      def refuse!
+        message = refusal
+        raise Refused, message if message
+      end
+
+      # Run the block holding the allocation lock: read {#taken} and create
+      # the folder inside it, or another `create` can read the same numbers
+      # in between.
+      #
+      # The lock is `flock`, so it dies with the process: a `create` killed
+      # mid-way leaves nothing for anyone to break.
+      #
+      # @yieldreturn [Object]
+      # @return [Object] the block's value
+      # @raise [Refused] in a linked worktree, or off the default branch
+      def hold
+        refuse!
+        repo = repository or return yield
+
+        File.open(repo.lock_path, File::RDWR | File::CREAT, 0o644) do |lock|
+          lock.flock(File::LOCK_EX)
+          yield
+        end
+      end
+
+      # Every number a new plan must stay clear of.
+      #
+      # @return [Array<OpenLanes::Plans::Ordinal>] unique, unordered
+      def taken
+        local = Plans::Tree.new(dir:).taken
+        repo = repository or return local
+
+        (local + branches(repo).flat_map { OpenLanes.plans_at(repo.toplevel, it, plans: repo.plans) }).uniq
+      end
+
+      private
+
+      # Branches that point at one commit hold one set of plans, so each
+      # commit is read once: a branch and its `origin/` twin cost one `ls-tree`.
+      #
+      # @param repo [Repository]
+      # @return [Array<String>] commit names
+      def branches(repo)
+        out = git(repo.toplevel, "for-each-ref", "--format=%(objectname) %(refname)", *REFS) or return []
+
+        out.lines.filter_map { |line|
+          sha, ref = line.split
+          sha unless ref.to_s.end_with?("/HEAD")
+        }.uniq
+      end
+
+      # @return [Repository, nil]
+      def discover
+        base = dir
+        base = File.dirname(base) until File.directory?(base)
+        out = git(base,
+          "rev-parse",
+          "--path-format=absolute",
+          "--git-dir",
+          "--git-common-dir",
+          "--show-toplevel") or return nil
+        git_dir, common_dir, toplevel = out.lines.map(&:chomp)
+        return nil if toplevel.to_s.empty?
+
+        Repository.new(git_dir:,
+          common_dir:,
+          toplevel:,
+          plans: relative_plans(base, toplevel),
+          branch: git(toplevel, "symbolic-ref", "--short", "-q", "HEAD")&.chomp,
+          default_branch: default_branch(toplevel))
+      end
+
+      # origin's HEAD names the default branch where a clone recorded it; a
+      # repository with no origin, or one never told, falls back to `main`.
+      #
+      # @param toplevel [String]
+      # @return [String]
+      def default_branch(toplevel)
+        head = git(toplevel, "symbolic-ref", "--short", "-q", "refs/remotes/origin/HEAD")&.chomp
+        head.to_s.empty? ? DEFAULT_BRANCH : head.delete_prefix("origin/")
+      end
+
+      # git answers with resolved paths (`/private/var` on macOS) while +dir+
+      # may name the same place through a symlink (`/var`), so both sides are
+      # resolved before one is taken from the other.
+      #
+      # @param base [String] the nearest existing ancestor of +dir+, or +dir+
+      # @param toplevel [String]
+      # @return [String]
+      def relative_plans(base, toplevel)
+        tail = dir.delete_prefix(base).delete_prefix("/")
+        inside = File.realpath(base).delete_prefix(File.realpath(toplevel)).delete_prefix("/")
+        File.join(*[inside, tail].reject(&:empty?)).then { it.empty? ? "." : it }
+      end
+
+      # @param dir [String]
+      # @param args [Array<String>]
+      # @return [String, nil] stdout, or nil when git failed or is not here
+      def git(dir, *)
+        out, status = Open3.capture2("git", "-C", dir, *, err: File::NULL)
+        status.success? ? out : nil
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/openlanes/lifecycle/brief.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+require "date"
 require "tty/command"
+require "yaml"
 
 module OpenLanes
   module Lifecycle
@@ -109,6 +111,7 @@ module OpenLanes
       # @param dry_run [Boolean] plan the invocation, do not run it
       # @param seed [String, nil] what the author already wrote about the
       #   feature (`create --from`); opens spec.md and outranks the repo survey
+      # @param today [Date] what `created:` says
       def initialize(
         path:,
         title:,
@@ -116,7 +119,8 @@ module OpenLanes
         command: TTY::Command.new(printer: :null),
         timeout: TIMEOUT,
         dry_run: false,
-        seed: nil
+        seed: nil,
+        today: Date.today
       )
         @path = path
         @title = title
@@ -125,6 +129,7 @@ module OpenLanes
         @timeout = timeout
         @dry_run = dry_run
         @seed = seed.to_s.strip.then { |s| s.empty? ? nil : s }
+        @today = today
       end
 
       # @return [String]
@@ -146,9 +151,34 @@ module OpenLanes
         "# #{title}\n\n#{opening}" + HEADINGS.map { |h| "## #{h}\n\n" }.join("\n")
       end
 
+      # The scaffold under a frontmatter that says when the plan was created
+      # (decision N3): the folder name stops carrying any date once the plan
+      # is open, and a plan's age is otherwise only in git.
+      #
+      # Only where a plan may be minted ({Allocator#refuse!}): an opening
+      # spec.md written in a worktree or on a feature branch is a plan `main`
+      # has not heard of.
+      #
       # @return [String] where it was written
+      # @raise [Allocator::Refused] in a linked worktree, or off the default branch
       def write_scaffold!
+        Allocator.new(dir: File.dirname(path)).refuse!
         File.write(spec_path, scaffold)
+        stamp!
+      end
+
+      # Merge settings into spec.md's frontmatter, keeping every key already
+      # there, and `created:` whether or not a draft rewrote the file without
+      # it. Run after the draft for that reason.
+      #
+      # @param settings [Hash{String => Object}] e.g. `lane` and `depth`
+      # @return [String] the spec's path
+      def stamp!(settings = {})
+        return spec_path unless File.file?(spec_path)
+
+        meta, body = Frontmatter.split(File.read(spec_path, encoding: "UTF-8"))
+        meta = { "created" => @today }.merge(meta).merge(settings)
+        File.write(spec_path, "#{YAML.dump(meta)}---\n\n#{body.sub(/\A\n+/, "")}")
         spec_path
       end
 
@@ -182,7 +212,7 @@ module OpenLanes
         ["claude",
          "-p", prompt, "--add-dir", root,
          "--model", BRIEF_MODEL,
-         *Adapters::Claude::LEAN,
+         *Adapters.lean_flags("claude"),
          "--allowedTools", ALLOWED_TOOLS.join(","),
          "--disallowedTools", DENIED_TOOLS.join(",")]
       end

data/lib/openlanes/lifecycle/completion.rb

@@ -2,7 +2,7 @@
 
 module OpenLanes
   module Lifecycle
-    # Copies the spec's `task-completed-when` and `how-to-verify` into
+    # Copies the spec's `task-completed-when` and how to test it into
     # `plan.md`, so the builders and the reviewer read them in the document
     # they work from rather than only in the frontmatter of another one.
     #
@@ -12,7 +12,12 @@ module OpenLanes
     # agent signs, and a section the agent wrote is never touched.
     module Completion
       COMPLETED_WHEN_HEADING = "## Task completed when"
-      HOW_TO_VERIFY_HEADING = "## How to verify"
+      HOW_TO_TEST = "## How to test"
+
+      # The heading {HOW_TO_TEST} replaced. A plan.md written before the
+      # rename still carries it, and without recognising it the harness would
+      # append a second copy of the same steps under the new name.
+      FORMER_HOW_TO_TEST = "## How to verify"
 
       module_function
 
@@ -25,7 +30,7 @@ module OpenLanes
       def markdown(spec, present: "")
         [
           section(COMPLETED_WHEN_HEADING, spec.completed_when, present),
-          section(HOW_TO_VERIFY_HEADING, spec.how_to_verify, present)
+          section(HOW_TO_TEST, spec.how_to_test, present, also: FORMER_HOW_TO_TEST)
         ].compact.join("\n")
       end
 
@@ -46,11 +51,12 @@ module OpenLanes
         true
       end
 
+      # @param also [String, nil] an older heading that counts as present
       # @return [String, nil]
-      def section(heading, items, present)
-        return nil if items.empty? || present.match?(/^#{Regexp.escape(heading)}\s*$/i)
+      def section(heading, items, present, also: nil)
+        return nil if items.empty? || [heading, also].compact.any? { present.match?(/^#{Regexp.escape(it)}\s*$/i) }
 
-        "#{heading}\n\n#{items.map { |item| "- #{item}" }.join("\n")}\n"
+        "#{heading}\n\n#{items.map { Plans::Spec.list_item(it) }.join("\n")}\n"
       end
       private_class_method :section
     end