@zalom/plastic 1.1.0 → 1.1.2

package/scripts/lib/bridge.rb

@@ -395,10 +395,24 @@ module Bridge
     File.exist?(path)
   end
 
+  # True iff actions/ holds AT LEAST ONE real action file: a non-empty *.md whose
+  # first line is not the placeholder sentinel. A `.gitkeep` (no .md extension)
+  # never counts, an empty *.md never counts, and a sentinel-only *.md never
+  # counts. Pure and side-effect-free so the gate stays unit-testable. Fail-open:
+  # a missing actions/ dir globs to nothing and returns false (the gate then
+  # reports it needs a real action file); it never raises.
+  def self.has_real_action?(intent_dir)
+    Dir.glob("#{intent_dir}/actions/*.md").any? do |f|
+      File.file?(f) && File.size(f) > 0 && stage_file_present?(f)
+    end
+  rescue StandardError
+    false
+  end
+
   def self.derive_stage(intent_dir)
     return "done" if stage_file_present?("#{intent_dir}/outcome.md")
     if stage_file_present?("#{intent_dir}/plan.md") &&
-       File.directory?("#{intent_dir}/actions") &&
+       has_real_action?(intent_dir) &&
        stage_file_present?("#{intent_dir}/checklist.md")
       return "exec"
     end
@@ -414,7 +428,7 @@ module Bridge
     ["spec.md", "plan.md", "checklist.md", "outcome.md"].each do |f|
       files << f if stage_file_present?("#{intent_dir}/#{f}")
     end
-    files << "actions/" if File.directory?("#{intent_dir}/actions")
+    files << "actions/" if has_real_action?(intent_dir)
     files
   end
 
@@ -640,6 +654,75 @@ module Bridge
     lines.length
   end
 
+  # --- Phantom-line detection (intent 134) ------------------------------------
+  #
+  # A companion to the ledger, not a new writer: pure, disk-only, hermetic (no bridge or
+  # session resolution, no writes), matching intent 52's savepoint-decoupling precedent. Under
+  # a gate-routing misfire (bug 131) or an out-of-band merge (124a's precedent), a ledger line
+  # can go stale or duplicate without the file evidence agreeing. This detects, never repairs;
+  # repair is `rebuild_savepoint` (live intents) or the 124a manual Done-bookend recipe
+  # (terminal intents, human-granted only).
+
+  # (stage, milestone) -> basename, for every file-landing milestone this intent_dir could have
+  # produced (the intent file plus the four lifecycle artifacts). Reuses savepoint_milestone so
+  # the mapping never drifts from the one the writer itself uses.
+  def self.savepoint_file_landing_pairs(intent_dir)
+    basenames = [File.basename(intent_file(intent_dir)), "spec.md", "plan.md", "checklist.md", "outcome.md"]
+    basenames.each_with_object({}) do |basename, map|
+      pair = savepoint_milestone(intent_dir, basename)
+      map[pair] = basename if pair
+    end
+  end
+
+  # A `started` state line's real prerequisite is the PRECEDING stage's artifact, not its own
+  # (a `started` line legitimately fires before its own stage's file is real by design). `Exec
+  # started` additionally requires plan.md, since Exec cannot start before How produced it too.
+  SAVEPOINT_STATE_PREREQUISITES = {
+    ["How", "started"] => ["spec.md"],
+    ["Exec", "started"] => ["plan.md", "checklist.md"],
+  }.freeze
+
+  # Raw (stripped) ledger lines whose disk evidence contradicts them, each paired with a short
+  # reason: [line, reason]. Three phantom classes (D5):
+  #   - a file-landing milestone whose file is absent or still a sentinel placeholder;
+  #   - a duplicate (stage, milestone) pair (the later occurrence is the phantom);
+  #   - a state line (`How started` / `Exec started`) whose stage prerequisites are absent.
+  # A clean ledger, or an absent one, returns [].
+  def self.savepoint_phantom_lines(intent_dir)
+    path = File.join(intent_dir, SAVEPOINT_FILE)
+    return [] unless File.exist?(path)
+
+    landing = savepoint_file_landing_pairs(intent_dir)
+    seen = []
+    phantoms = []
+
+    File.read(path).each_line do |raw|
+      line = raw.strip
+      next if line.empty?
+      parts = line.split(/\s{2,}/)
+      next if parts.length < 3
+      pair = [parts[1], parts[2]]
+
+      if seen.include?(pair)
+        phantoms << [line, "duplicate (stage, milestone) pair"]
+        next
+      end
+      seen << pair
+
+      if (basename = landing[pair]) && !stage_file_present?(File.join(intent_dir, basename))
+        phantoms << [line, "milestone file absent or still a sentinel placeholder"]
+        next
+      end
+
+      prereqs = SAVEPOINT_STATE_PREREQUISITES[pair]
+      if prereqs && prereqs.any? { |b| !stage_file_present?(File.join(intent_dir, b)) }
+        phantoms << [line, "state line prerequisite absent on disk"]
+      end
+    end
+
+    phantoms
+  end
+
   def self.derive(session, intent_id:, intent_dir:, store:, name:, tmp: tmp_dir)
     stage = derive_stage(intent_dir)
     has = has_files(intent_dir)
@@ -710,8 +793,13 @@ module Bridge
         return "Cannot start How — Why is incomplete (spec.md missing)"
       end
     when "checklist.md"
-      unless stage_file_present?("#{intent_dir}/plan.md") && File.directory?("#{intent_dir}/actions")
-        return "Cannot complete How — plan.md or actions/ missing"
+      unless stage_file_present?("#{intent_dir}/plan.md")
+        return "Cannot complete How — plan.md missing"
+      end
+      unless has_real_action?(intent_dir)
+        return "Cannot complete How — actions/ has no real action file (only .gitkeep or empty). " \
+               "The planner must write at least one actions/ACTION_N.md before checklist.md. " \
+               "See skills/intent-planning."
       end
     when "outcome.md"
       checklist = "#{intent_dir}/checklist.md"
@@ -913,6 +1001,18 @@ module Bridge
                   name: name, tmp: tmp)
     data["build"]["auto"] = auto
     data["lock"] = lock_cache(lock_data)
+
+    # Provision the per-intent worktrees so the rebuilt bridge carries
+    # worktree.code (intent 136). Without it, cwd/edited-path selection has no
+    # key: the repaired intent loses its own code gate and a concurrent sibling
+    # wins the tie-break. Idempotent (reuse dir / reattach branch) and fail-open
+    # for non-git / global-only, exactly as `arm` does; never break the repair.
+    begin
+      Worktree.provision(data)
+    rescue => e
+      $stderr.puts "plastic: worktree provision raised during repair, continuing unprovisioned: #{e.message}"
+    end
+
     write(key, data, tmp: tmp)
     actions << "bridge rebuilt from disk (stage #{data['build']['stage']})"
 
@@ -936,11 +1036,14 @@ module Bridge
     return nil unless store && dir
     intent_dir_abs = File.expand_path("#{store}/#{dir}")
 
-    # "How reached" = the plan triplet exists. Gate by artifact presence, not the
-    # stage label (derive_stage returns "how" as soon as spec.md exists, before any
-    # plan). Code edits stay blocked until plan.md + checklist.md are both present.
+    # "How reached" = plan.md + checklist.md are both present AND actions/ holds at
+    # least one real action file. Gate by artifact presence, not the stage label
+    # (derive_stage returns "how" as soon as spec.md exists, before any plan). Code
+    # edits stay blocked until the planner has written a real action file, so an
+    # empty or .gitkeep-only actions/ never opens the code gate.
     reached_how = stage_file_present?("#{intent_dir_abs}/plan.md") &&
-                  stage_file_present?("#{intent_dir_abs}/checklist.md")
+                  stage_file_present?("#{intent_dir_abs}/checklist.md") &&
+                  has_real_action?(intent_dir_abs)
     return nil if reached_how
 
     file_abs = File.expand_path(file_path.to_s)
@@ -949,9 +1052,9 @@ module Bridge
     return nil if file_abs == intent_dir_abs || file_abs.start_with?("#{intent_dir_abs}/")
 
     id = intent_info["id"]
-    "intent #{id} has not reached How — write plan.md + checklist.md before " \
-      "editing project code. Run plastic-auto or plastic-intent-planning first. " \
-      "(blocked edit: #{file_abs})"
+    "intent #{id} has not reached How — write plan.md + checklist.md and at least " \
+      "one real actions/ACTION_N.md before editing project code. Run plastic-auto or " \
+      "plastic-intent-planning first. (blocked edit: #{file_abs})"
   end
 
   # --- Solo-mode detection (intent 128) ---------------------------------------

package/scripts/lib/dashboard_banner.rb

@@ -26,16 +26,15 @@ module DashboardBanner
     line
   end
 
-  # The id of the top-ranked next_big candidate, when the payload's matrix carries
-  # exactly the shape dashboard.rb emits (a "next_big" list of {id, ...} hashes,
-  # already rank-sorted). Returns nil for any other shape rather than raising.
+  # The id of the top-ranked "drive" candidate, when the payload's next_work list
+  # carries the shape dashboard.rb emits (an Array of {id, disposition, ...}
+  # hashes, already rank-sorted). Returns nil for any other shape rather than
+  # raising.
   def next_big_thing_id(payload)
-    matrix = payload["matrix"]
-    return nil unless matrix.is_a?(Hash)
-    list = matrix["next_big"]
-    return nil unless list.is_a?(Array) && !list.empty?
-    top = list.first
-    return nil unless top.is_a?(Hash)
+    list = payload["next_work"]
+    return nil unless list.is_a?(Array)
+    top = list.find { |entry| entry.is_a?(Hash) && entry["disposition"] == "drive" }
+    return nil unless top
     id = top["id"].to_s
     id.empty? ? nil : id
   end

package/scripts/lib/installer_core.rb

@@ -12,7 +12,7 @@ require_relative "agent_models"
 # Shared installer machinery, instantiable with injected package root / store / agent
 # map so the verb scripts (install/update/uninstall/rollback) and their tests can run
 # hermetically (no eval, no global-constant rewriting). Mirrors the DI recipe proven in
-# doctor.rb / install.rb (intents 30a, 30a1). Library only — no CLI, no $PROGRAM_NAME guard.
+# doctor.rb / install.rb (intents 30a, 30a1). Library only - no CLI, no $PROGRAM_NAME guard.
 class InstallerCore
   DEFAULT_PLASTIC_HOME = File.join(Dir.home, ".plastic")
 
@@ -54,7 +54,7 @@ class InstallerCore
     STABILITY[ch] || 2
   end
 
-  # --- Semver (§11) — parse/compare, shared by update + rollback ---
+  # --- Semver (§11) - parse/compare, shared by update + rollback ---
 
   def semver_parse(version)
     m = /\A(\d+)\.(\d+)\.(\d+)(?:-(.+))?\z/.match(version.to_s.strip)
@@ -95,7 +95,7 @@ class InstallerCore
     semver_compare(a, b) == 1
   end
 
-  # --- versions.json ledger (append-only JSONL — one object per line) ---
+  # --- versions.json ledger (append-only JSONL - one object per line) ---
 
   def ledger_path
     File.join(plastic_home, "versions.json")
@@ -242,6 +242,7 @@ class InstallerCore
       "scripts/lib/qmd_hook.rb" => "scripts/lib/qmd_hook.rb",
       "scripts/lib/power_tools.rb" => "scripts/lib/power_tools.rb",
       "scripts/lib/agent_models.rb" => "scripts/lib/agent_models.rb",
+      "scripts/lib/release_guard.rb" => "scripts/lib/release_guard.rb",
       "scripts/hook-code-gate" => "scripts/hook-code-gate",
       "scripts/hook-lock-gate" => "scripts/hook-lock-gate",
       "scripts/hook-bash-gate" => "scripts/hook-bash-gate",
@@ -260,6 +261,10 @@ class InstallerCore
       "scripts/lib/dashboard_banner.rb" => "scripts/lib/dashboard_banner.rb",
       "scripts/lib/qmd_sync.rb" => "scripts/lib/qmd_sync.rb",
       "scripts/qmd-sync" => "scripts/qmd-sync",
+      "scripts/lib/roadmap_savepoint.rb" => "scripts/lib/roadmap_savepoint.rb",
+      "scripts/roadmap-savepoint" => "scripts/roadmap-savepoint",
+      "scripts/lib/roadmap_queue.rb" => "scripts/lib/roadmap_queue.rb",
+      "scripts/roadmap-next" => "scripts/roadmap-next",
       "scripts/lib/intent_validator.rb" => "scripts/lib/intent_validator.rb",
       "scripts/lib/graph_rebuild.rb" => "scripts/lib/graph_rebuild.rb",
       "scripts/lib/frontmatter_writer.rb" => "scripts/lib/frontmatter_writer.rb",
@@ -271,6 +276,7 @@ class InstallerCore
       "scripts/rebuild-graph" => "scripts/rebuild-graph",
       "scripts/validate-intent" => "scripts/validate-intent",
       "scripts/new-intent" => "scripts/new-intent",
+      "scripts/end-intent" => "scripts/end-intent",
       "scripts/hook-create-gate" => "scripts/hook-create-gate",
       "templates/intent.md" => "templates/intent.md",
       "templates/spec.md" => "templates/spec.md",
@@ -287,8 +293,11 @@ class InstallerCore
       "scripts/update.rb" => "scripts/update.rb",
       "scripts/uninstall.rb" => "scripts/uninstall.rb",
       "scripts/rollback.rb" => "scripts/rollback.rb",
+      "scripts/lib/legacy_bookend_amnesty.rb" => "scripts/lib/legacy_bookend_amnesty.rb",
       "scripts/doctor.rb" => "scripts/doctor.rb",
       "scripts/dashboard.rb" => "scripts/dashboard.rb",
+      "scripts/skill-lint" => "scripts/skill-lint",
+      "scripts/lib/skill_lint.rb" => "scripts/lib/skill_lint.rb",
     }
   end
 

package/scripts/lib/legacy_bookend_amnesty.rb

@@ -0,0 +1,35 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Intent 170a - A2 cutoff amnesty for the legacy savepoint Done-bookend gap.
+#
+# Frozen 2026-07-10. Pre-161 terminal intents predate
+# Bridge.append_terminal_savepoint, so their savepoint.md never got a
+# `Done delivered|abandoned` line. This list grandfathers exactly those,
+# keyed by store scope plus intent id, so doctor's signals_complete check
+# stops counting them as gaps. Every intent NOT on this list still warns if
+# its savepoint lacks the Done bookend, including any new terminal intent
+# going forward. This is a frozen historical snapshot: it must never grow.
+# Regenerating it requires re-running the exact predicate below against the
+# real store and reviewing the diff, never appending ad hoc.
+#
+# Predicate used to build this list (2026-07-10): for each store in
+# Doctor#done_signal_stores(nil), each dir in index_sections_by_dir(index),
+# terminal = the dir's INDEX section is Completed or Abandoned, gap =
+# savepoint.md exists AND does not match
+# /\bDone\b.*\b(delivered|abandoned)\b/.
+#
+# This does NOT grandfather the separate outcome.md completeness gap
+# (checked independently at scripts/doctor.rb:603-607); some of these ids
+# may still warn on that axis.
+module LegacyBookendAmnesty
+  LIST = {
+    "global" => %w[1a 1a2 23].freeze,
+    "project:plastic" => %w[
+      1 11 121a 124 128 13 13b 15 158 158a 159 160 163 1a 1b1a3 22 30a1a 34
+      36a 36a1 37 38 39 45 45a 49 4a 4a1 4a1c1 50 52 54 55 56 58 59 60b 65
+      66 66a 66b 66c 66c1 67 68 71 72 73b 73c 73c1 73c2 73c3 74 77 79 80 83
+      84 85a 9
+    ].freeze,
+  }.freeze
+end

package/scripts/lib/release_guard.rb

@@ -0,0 +1,62 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+
+# Mechanical guard for stable-cut version preconditions (intent 155). Checks
+# that the three repo version files agree on one version string, and, when a
+# stable/latest cut is declared, that the resolved version carries no
+# pre-release suffix. Pure function over injected paths: no ENV reads, no
+# eval, no global-config seam, hermetically testable and safe to call from
+# both the release workflow and the test suite.
+#
+# Deliberately does not check a repo VERSION file: none exists in this repo.
+# VERSION is an install-target artifact written fresh from package.json at
+# install/update time (scripts/lib/installer_core.rb); it cannot drift
+# independently because it is never committed.
+module ReleaseGuard
+  Result = Struct.new(:ok, :version, :mismatches, :prerelease_suffix, keyword_init: true) do
+    def ok?
+      ok
+    end
+  end
+
+  # package_json / plugin_json / marketplace_json: paths to the three repo
+  # version files. stable: true gates a stable/latest cut (rejects any
+  # pre-release suffix); false allows a suffix, only agreement is checked.
+  def self.check(package_json:, plugin_json:, marketplace_json:, stable:)
+    versions = {
+      "package.json" => read_version(package_json) { |data| data["version"] },
+      ".claude-plugin/plugin.json" => read_version(plugin_json) { |data| data["version"] },
+      ".claude-plugin/marketplace.json" => read_version(marketplace_json) { |data| plastic_plugin_version(data) },
+    }
+
+    canonical = versions["package.json"]
+    mismatches = versions.reject { |_file, version| version && version == canonical }.keys
+
+    suffix = canonical&.match(/-(.+)\z/)&.captures&.first
+    prerelease_violation = stable && !suffix.nil?
+
+    Result.new(
+      ok: mismatches.empty? && !prerelease_violation,
+      version: canonical,
+      mismatches: mismatches,
+      prerelease_suffix: suffix
+    )
+  end
+
+  def self.plastic_plugin_version(data)
+    plugins = Array(data["plugins"])
+    plugin = plugins.find { |p| p["name"] == "plastic" } || plugins.first
+    plugin && plugin["version"]
+  end
+  private_class_method :plastic_plugin_version
+
+  def self.read_version(path)
+    data = JSON.parse(File.read(path))
+    yield data
+  rescue Errno::ENOENT, JSON::ParserError
+    nil
+  end
+  private_class_method :read_version
+end

package/scripts/lib/roadmap_queue.rb

@@ -0,0 +1,285 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "time"
+require "json"
+require_relative "roadmap_savepoint"
+
+# FileOrderRanker - the default value-ordering strategy: today's roadmap file order,
+# unchanged. This is the intent-173 ranking-swap seam (sibling to the 147 DB-swap seam): a
+# future scored ranker (RICE/ICE/WSJF/pairwise) implements the same #rank/#name pair and is
+# injected through RoadmapQueue's ranker: keyword, with no change to parsing, frontier
+# detection, gating, INDEX reconciliation, or the JSON contract.
+class FileOrderRanker
+  def rank(entries)
+    entries
+  end
+
+  def name
+    "file-order"
+  end
+end
+
+# RoadmapQueue - the one deterministic reader the auto loop and plastic-roadmap-continuing
+# both call (intent 148). Constructor-DI, hermetic: clock and paths injected, no eval, no ENV
+# or global config seam. It does two things: liveness-ranks a tier's roadmaps/*.md files
+# (porting plastic-roadmap-continuing's read-time algorithm), and, within the winning
+# roadmap, selects the frontier wave plus its dispatchable set (D-b), value-ordered by the
+# injected ranker (default FileOrderRanker, the intent-173 swap seam). Every frontier token is
+# reconciled against INDEX.md first, INDEX wins. Reads through the 134 ledger via the public
+# RoadmapSavepoint.ledger_path_for; never writes anything, never modifies roadmap_savepoint.rb.
+class RoadmapQueue
+  STATUSES = %w[queued delivering delivered abandoned blocked].freeze
+
+  # Entry line parser, anchored on the status vocabulary rather than end of line, so a trailing
+  # parenthetical ("delivering (owner ruling...)") does not defeat the match. Accepts the em
+  # dash or a hyphen as the separator; roadmap .md files are store-internal and use the em dash.
+  ENTRY = /\A-\s*\[([ xX])\]\s+(\S+)\s+.*?[—-]\s*(queued|delivering|delivered|abandoned|blocked)\b/.freeze
+
+  WAVE_HEADING = /\A###\s+(.+?)\s*\z/.freeze
+
+  LOG_LINE = /\A-\s+(\d{4}-\d{2}-\d{2})\s+(\d{2}:\d{2})\s+UTC\b/.freeze
+
+  def initialize(roadmaps_dir:, index_path: nil, now: Time.now, ranker: FileOrderRanker.new)
+    @roadmaps_dir = roadmaps_dir
+    @index_path   = index_path
+    @now          = now
+    @ranker       = ranker
+  end
+
+  # Auto-loop mode: break ties deterministically, report the winner's frontier state.
+  def queue
+    analyze(mode: "queue")
+  end
+
+  # Continuing mode: return tie_candidates instead of breaking a tie.
+  def which
+    analyze(mode: "which")
+  end
+
+  private
+
+  def analyze(mode:)
+    parsed = reconcile(roadmap_paths.map { |path| parse_roadmap(path) })
+    ranked = rank_candidates(parsed)
+
+    return payload(mode: mode, state: "none", roadmap: nil, frontier_wave: nil,
+                    dispatchable: [], in_flight: [], blocked: [], tie: false,
+                    tie_candidates: []) if ranked.empty?
+
+    tied = tied_group(ranked)
+
+    if tied.length > 1 && mode == "which"
+      tie_candidates = tied.map do |c|
+        { "roadmap" => c[:slug], "last_event" => c[:last_event].utc.iso8601,
+          "reason" => "equally live, tied on last event time" }
+      end
+      return payload(mode: mode, state: "tie", roadmap: nil, frontier_wave: nil,
+                      dispatchable: [], in_flight: [], blocked: [], tie: false,
+                      tie_candidates: tie_candidates)
+    end
+
+    winner = ranked.first
+    is_tie = tied.length > 1
+    frontier = frontier_for(winner)
+
+    state =
+      if frontier.nil?
+        "exhausted"
+      elsif !frontier[:dispatchable].empty?
+        "dispatchable"
+      else
+        "in_flight"
+      end
+
+    payload(mode: mode, state: state, roadmap: winner[:slug],
+            frontier_wave: frontier && frontier[:heading],
+            dispatchable: frontier ? frontier[:dispatchable] : [],
+            in_flight: frontier ? frontier[:in_flight] : [],
+            blocked: blocked_for(winner),
+            tie: is_tie,
+            tie_candidates: [])
+  end
+
+  # --- enumerate + parse --------------------------------------------------------
+
+  def roadmap_paths
+    return [] unless @roadmaps_dir && Dir.exist?(@roadmaps_dir)
+    Dir.glob(File.join(@roadmaps_dir, "*.md"))
+       .reject { |p| p.end_with?(".savepoint.md") }
+       .sort
+  end
+
+  def parse_roadmap(path)
+    text = File.read(path)
+    { slug: File.basename(path, ".md"), path: path, waves: parse_waves(section_body(text, "Waves")) }
+  end
+
+  def parse_waves(waves_body)
+    waves = []
+    current = nil
+    waves_body.each_line do |line|
+      stripped = line.chomp.strip
+      if (m = stripped.match(WAVE_HEADING))
+        current = { heading: m[1], entries: [] }
+        waves << current
+      elsif current && (em = stripped.match(ENTRY))
+        current[:entries] << { id: em[2], raw_status: em[3].downcase }
+      end
+    end
+    waves
+  end
+
+  def section_body(text, heading)
+    m = text.match(/^##\s+#{Regexp.escape(heading)}\s*$(.*?)(?=^##\s|\z)/m)
+    m ? m[1] : ""
+  end
+
+  # --- INDEX reconciliation (INDEX wins), applied before classification --------
+
+  def reconcile(parsed_list)
+    parsed_list.each do |c|
+      c[:waves].each do |wave|
+        wave[:entries].each { |entry| entry[:status] = reconcile_status(entry[:id], entry[:raw_status]) }
+      end
+    end
+    parsed_list
+  end
+
+  def reconcile_status(id, raw_status)
+    case index_status_map[id]
+    when "delivered" then "delivered"
+    when "abandoned" then "abandoned"
+    when "queued" then "queued"
+    when :active then raw_status == "delivered" ? "delivering" : raw_status
+    else raw_status
+    end
+  end
+
+  def index_status_map
+    return @index_status_map if defined?(@index_status_map)
+    @index_status_map = {}
+    path = resolved_index_path
+    return @index_status_map unless path && File.exist?(path)
+
+    text = File.read(path)
+    { "Completed" => "delivered", "Abandoned" => "abandoned", "Active" => :active, "Future" => "queued" }.each do |heading, tag|
+      section_body(text, heading).each_line do |line|
+        stripped = line.strip
+        next unless stripped.start_with?("- [")
+        m = stripped.match(/\A-\s*\[(\S+)\s/)
+        next unless m
+        @index_status_map[m[1]] = tag
+      end
+    end
+    @index_status_map
+  end
+
+  def resolved_index_path
+    return @index_path if @index_path
+    return nil unless @roadmaps_dir
+    File.join(File.dirname(@roadmaps_dir), "INDEX.md")
+  end
+
+  # --- liveness ranking (ports plastic-roadmap-continuing's read-time algorithm) -
+
+  def rank_candidates(parsed_list)
+    parsed_list.map do |c|
+      entries = c[:waves].flat_map { |w| w[:entries] }
+      live = entries.any? { |e| %w[delivering blocked].include?(e[:status]) }
+      c.merge(live: live, last_event: last_event_time(c[:path]))
+    end.sort_by { |c| [c[:live] ? 0 : 1, -c[:last_event].to_i, c[:slug]] }
+  end
+
+  def tied_group(ranked)
+    return [] if ranked.empty?
+    top_key = [ranked.first[:live], ranked.first[:last_event].to_i]
+    ranked.select { |c| [c[:live], c[:last_event].to_i] == top_key }
+  end
+
+  def last_event_time(path)
+    ledger_path = RoadmapSavepoint.ledger_path_for(path)
+    if File.exist?(ledger_path)
+      last_line = File.readlines(ledger_path).map(&:strip).reject(&:empty?).last
+      if last_line
+        token = last_line[/\A(\S+)/, 1]
+        begin
+          return Time.iso8601(token) if token
+        rescue ArgumentError
+          # fall through to the Log fallback below
+        end
+      end
+    end
+    log_fallback_time(path)
+  end
+
+  def log_fallback_time(path)
+    body = section_body(File.read(path), "Log")
+    last = body.each_line.map { |l| l.chomp.strip }.select { |l| l.match?(LOG_LINE) }.last
+    return Time.at(0) unless last
+
+    m = last.match(LOG_LINE)
+    y, mo, d = m[1].split("-").map(&:to_i)
+    h, mi = m[2].split(":").map(&:to_i)
+    Time.utc(y, mo, d, h, mi, 0)
+  end
+
+  # --- frontier + dispatchable selection (D-b) ----------------------------------
+
+  def frontier_for(candidate)
+    candidate[:waves].each do |wave|
+      statuses = wave[:entries].map { |e| e[:status] }
+      next unless statuses.any? { |s| %w[queued delivering].include?(s) }
+
+      queued = wave[:entries].select { |e| e[:status] == "queued" }
+      delivering = wave[:entries].select { |e| e[:status] == "delivering" }
+
+      # intent-173 ranking-swap seam: value-orders the dispatchable candidates only.
+      ordered = @ranker.rank(queued)
+
+      dispatchable = ordered.each_with_index.map do |e, i|
+        { "id" => e[:id], "scope" => scope_label, "roadmap" => candidate[:slug],
+          "wave" => wave[:heading], "status" => "queued", "rank" => i + 1 }
+      end
+      in_flight = delivering.map do |e|
+        { "id" => e[:id], "roadmap" => candidate[:slug], "wave" => wave[:heading], "status" => "delivering" }
+      end
+
+      return { heading: wave[:heading], dispatchable: dispatchable, in_flight: in_flight }
+    end
+    nil
+  end
+
+  def blocked_for(candidate)
+    candidate[:waves].flat_map do |wave|
+      wave[:entries].select { |e| e[:status] == "blocked" }.map do |e|
+        { "id" => e[:id], "roadmap" => candidate[:slug], "wave" => wave[:heading], "status" => "blocked" }
+      end
+    end
+  end
+
+  # --- scope + payload -----------------------------------------------------------
+
+  def scope_label
+    m = @roadmaps_dir.to_s.match(%r{/projects/([^/]+)/roadmaps/?\z})
+    m ? "project:#{m[1]}" : "global"
+  end
+
+  def payload(mode:, state:, roadmap:, frontier_wave:, dispatchable:, in_flight:, blocked:, tie:, tie_candidates:)
+    {
+      "generated_for" => "roadmap-next",
+      "mode" => mode,
+      "scope" => scope_label,
+      "state" => state,
+      "roadmap" => roadmap,
+      "frontier_wave" => frontier_wave,
+      "dispatchable_queue" => dispatchable,
+      "in_flight" => in_flight,
+      "blocked" => blocked,
+      "tie" => tie,
+      "tie_candidates" => tie_candidates,
+      "ranking_strategy" => @ranker.name,
+      "generated_at" => @now.utc.iso8601,
+    }
+  end
+end