@zalom/plastic 1.0.3 → 1.1.1

package/scripts/hook-session-start

@@ -201,7 +201,7 @@ parts = []
 
 # Boot banner first: every session start surfaces that Plastic loaded, with the
 # version (clean) or the first failing core check (degraded). Owned by the hook
-# so it runs by construction — the plastic-continuing skill no longer does this.
+# so it runs by construction — the plastic-intent-continuing skill no longer does this.
 parts << core_banner
 parts << ""
 

package/scripts/install.rb

@@ -168,4 +168,5 @@ class Install < InstallerCore
   end
 end
 
-exit(Install.new(package_root: ENV["PLASTIC_PACKAGE_ROOT"] || File.expand_path("..", __dir__)).cli(ARGV)) if $PROGRAM_NAME == __FILE__
+exit(Install.new(package_root: ENV["PLASTIC_PACKAGE_ROOT"] || File.expand_path("..", __dir__),
+                 plastic_home: ENV.fetch("PLASTIC_HOME") { InstallerCore::DEFAULT_PLASTIC_HOME }).cli(ARGV)) if $PROGRAM_NAME == __FILE__

package/scripts/lib/bridge.rb

@@ -165,6 +165,18 @@ module Bridge
     -1
   end
 
+  # The provisioned code worktree dir (<repo>/.claude/worktrees/{id}--{slug})
+  # that contains file_path, or nil (intent 168). Structural and bridge-free:
+  # Worktree.provision builds exactly this layout, so a file under it is
+  # "worktree-scoped" and only that intent may gate it. The {id}--{slug} shape
+  # (a `--` in the dir name) is required, so a stray .claude/worktrees/README
+  # is not worktree-scoped and returns nil.
+  def self.enclosing_worktree_dir(file_path)
+    return nil if blank?(file_path)
+    m = File.expand_path(file_path).match(%r{\A(.*/\.claude/worktrees/[^/]+--[^/]+)(?:/|\z)})
+    m && m[1]
+  end
+
   # Resolve the active bridge: scan tmp for plastic-*.json (both per-intent and
   # legacy-keyed files), keep only valid bridges, filter to the caller's own
   # session when it has one, prefer auto-armed, then disambiguate by cwd tier
@@ -172,7 +184,7 @@ module Bridge
   # path: a session now legitimately owns several bridges (one per concurrent
   # intent), so filename lookup alone cannot pick the right one; cwd must
   # decide (intent 131).
-  def self.discover_bridge(session:, cwd: Dir.pwd, tmp: tmp_dir)
+  def self.discover_bridge(session:, cwd: Dir.pwd, tmp: tmp_dir, edited_path: nil)
     candidates = Dir.glob(File.join(tmp, "plastic-*.json")).reject { |f| f.end_with?(".tmp") }
     parsed = candidates.filter_map do |f|
       data = (JSON.parse(File.read(f)) rescue nil)
@@ -181,6 +193,26 @@ module Bridge
     end
     return nil if parsed.empty?
 
+    # Worktree-membership-first (intent 168). hook-code-gate passes the edited
+    # file as edited_path; when that file lies inside a provisioned code worktree
+    # (<repo>/.claude/worktrees/{id}--{slug}), only that worktree's owning intent
+    # may gate the write, BEFORE the intent-90 per-session filter below. Resolve
+    # the candidate whose worktree.code owns that dir (newest mtime on a tie), or
+    # nil when none owns it, so a session-keyed guided bridge can never claim a
+    # write located inside a sibling intent's worktree. No edited_path (every
+    # other caller) or a non-worktree path skips this and runs the pipeline
+    # unchanged (intents 90/52/131 preserved).
+    unless blank?(edited_path)
+      wt_dir = enclosing_worktree_dir(edited_path)
+      if wt_dir
+        owners = parsed.select do |c|
+          code = c[:data].dig("worktree", "code")
+          !blank?(code) && File.expand_path(code) == wt_dir
+        end
+        return owners.max_by { |c| c[:mtime] }&.fetch(:data)
+      end
+    end
+
     has_session = !blank?(session)
 
     # Strict per-session ownership (intent 90): when the caller HAS a session, a foreign
@@ -412,7 +444,7 @@ module Bridge
   NEXT_HINTS = {
     "why" => "write spec.md",
     "how" => "Why complete. Invoke plastic-auto to deliver autonomously, or write plan.md manually.",
-    "exec" => "How complete. Invoke plastic-auto or plastic-executing-plan to execute, or work through the checklist manually.",
+    "exec" => "How complete. Invoke plastic-auto or plastic-intent-executing to execute, or work through the checklist manually.",
     "done" => "Exec complete. Intent must be completed now — write outcome.md, update INDEX.md, auto-commit. Use plastic-auto or do it manually."
   }.freeze
 
@@ -608,6 +640,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)
@@ -881,6 +982,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']})"
 
@@ -918,7 +1031,7 @@ module Bridge
 
     id = intent_info["id"]
     "intent #{id} has not reached How — write plan.md + checklist.md before " \
-      "editing project code. Run plastic-auto or plastic-writing-plans first. " \
+      "editing project code. Run plastic-auto or plastic-intent-planning first. " \
       "(blocked edit: #{file_abs})"
   end
 

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

@@ -10,9 +10,9 @@ require_relative "hook_registry"
 require_relative "agent_models"
 
 # Shared installer machinery, instantiable with injected package root / store / agent
-# map so the verb scripts (install/update/uninstall/versions) and their tests can run
+# 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 + versions ---
+  # --- 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",
@@ -286,7 +292,8 @@ class InstallerCore
       "scripts/install.rb" => "scripts/install.rb",
       "scripts/update.rb" => "scripts/update.rb",
       "scripts/uninstall.rb" => "scripts/uninstall.rb",
-      "scripts/versions.rb" => "scripts/versions.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",
     }
@@ -471,8 +478,10 @@ class InstallerCore
   end
 
   # Copy each skills/<name>/ to <skills_root>/plastic-<name>/ (flat, namespaced by
-  # directory name — the only personal-skill namespacing Claude Code supports).
-  # The non-skill `_active-intent-gate.md` is relocated to ~/.plastic/ instead.
+  # directory name -- the only personal-skill namespacing Claude Code supports).
+  # Any top-level underscore-prefixed markdown fragment (e.g. `_active-intent-gate.md`,
+  # `_decision-tables.md`) is a shared non-skill fragment and relocates to ~/.plastic/
+  # instead, so every skill can read it from one shared location.
   def install_skills_flat(skills_source, skills_root)
     installed = []
     FileUtils.mkdir_p(skills_root)
@@ -481,7 +490,7 @@ class InstallerCore
       src = File.join(skills_source, entry)
       if File.directory?(src)
         installed += copy_dir_recursive(src, File.join(skills_root, "plastic-#{entry}"))
-      elsif entry == "_active-intent-gate.md"
+      elsif entry.start_with?("_") && entry.end_with?(".md")
         FileUtils.mkdir_p(plastic_home)
         dest = File.join(plastic_home, entry)
         FileUtils.cp(src, dest)

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