@zalom/plastic 2.0.0-alpha.2 → 2.0.0-alpha.20

package/scripts/lib/roadmap_graph.rb

@@ -0,0 +1,210 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_file"
+require_relative "graph_edges"
+require_relative "ready_set"
+require_relative "roadmap_savepoint"
+
+# RoadmapGraph (intent 337, n1): reads one roadmap file into the same shape
+# the node scope already uses - entries with their INDEX-reconciled status,
+# the edge map from "## Graph", the cycle path when one exists, the
+# topological batches, the critical paths, and the ready set. Edges are
+# parsed by GraphEdges; batches, critical paths, and downstream hops come
+# from ReadySet (327 D1, C1: the one parser, the one topological sort - a
+# local copy of either here is exactly the drift 327 forbids). This module
+# writes no file and reads no clock or environment variable (row 1.14);
+# every fact is either a value passed in or read once from the two paths
+# `analyze` is given.
+module RoadmapGraph
+  module_function
+
+  ENTRY = /\A-\s*\[([ xX])\]\s+(\S+)\s+(.*?)[—-]\s*(queued|delivering|delivered|abandoned|blocked)\b/.freeze
+  WAVE_HEADING = /\A###\s+(.+?)\s*\z/.freeze
+
+  INDEX_TAGS = { "Completed" => "delivered", "Abandoned" => "abandoned", "Active" => :active, "Future" => "queued" }.freeze
+
+  # analyze(roadmap_path, index_path:) -> a Result hash. Never raises across
+  # the boundary: a missing ## Graph section, a missing grouping heading, a
+  # cyclic graph, or an invalid byte in either file all become a named
+  # `reason` or an empty result, never an exception (rows 1.8, 1.9, 1.13).
+  def analyze(roadmap_path, index_path: nil)
+    text = read_utf8(roadmap_path)
+
+    graph_section = GraphFile.section_body(text, "## Graph")
+    unless graph_section
+      return result(has_graph: false, reason: "no ## Graph section in #{roadmap_path}")
+    end
+
+    parsed_edges = GraphEdges.parse(GraphFile.strip_fenced_blocks(graph_section))
+
+    entries_by_id, order = begin
+      parse_entries(text, roadmap_path)
+    rescue RoadmapSavepoint::MissingGroupingHeading => e
+      return result(has_graph: true, reason: e.message)
+    end
+
+    index_map = load_index(index_path)
+    entries_by_id.each_value { |e| e[:status] = reconcile_status(index_map[e[:id]], e[:raw_status]) }
+
+    declared_and_targeted = parsed_edges[:nodes]
+    entry_ids = order.dup
+
+    # 1.6: an entry the graph never named (not declared, not targeted) is
+    # folded in as a root, so a partly migrated roadmap never silently
+    # drops real work from the batches.
+    edges = parsed_edges[:edges].dup
+    entry_ids.each do |id|
+      next if declared_and_targeted.include?(id)
+
+      edges[id] = []
+      entries_by_id[id][:in_graph] = false
+    end
+    entry_ids.each do |id|
+      entries_by_id[id][:in_graph] = true if declared_and_targeted.include?(id) && entries_by_id[id][:in_graph].nil?
+    end
+
+    # 1.7: a graph id with no batch entry is named in `dangling`, never
+    # invented as a fake entry with no title.
+    dangling = declared_and_targeted.reject { |id| entries_by_id.key?(id) }
+
+    cyc = GraphEdges.cycle(edges)
+    if cyc
+      return result(has_graph: true, entries: entries_by_id, edges: edges, dangling: dangling,
+                     cycle: cyc, errors: parsed_edges[:errors])
+    end
+
+    batch_result = ReadySet.batches(edges)
+    batches = batch_result[:ok] ? order_batches(batch_result[:batches], order) : []
+    path_result = ReadySet.critical_paths(edges)
+
+    status_map = entries_by_id.each_with_object({}) { |(id, e), h| h[id] = e[:status] }
+    dead_ends = entry_ids.select do |id|
+      entries_by_id[id][:status] != "delivered" && ReadySet.dead_end?(id, edges, status_map)
+    end
+
+    ready = entry_ids.select do |id|
+      entries_by_id[id][:status] == "queued" &&
+        (edges[id] || []).all? { |t| status_map[t] == "delivered" }
+    end
+
+    result(
+      has_graph: true,
+      entries: entries_by_id,
+      edges: edges,
+      dangling: dangling,
+      cycle: nil,
+      batches: batches,
+      batches_error: batch_result[:ok] ? nil : batch_result[:error],
+      critical_paths: path_result[:ok] ? path_result : nil,
+      dead_ends: dead_ends,
+      ready: ready,
+      errors: parsed_edges[:errors]
+    )
+  end
+
+  # --- shared building blocks other callers (RoadmapQueue, n9) reuse --------
+
+  # The one place that knows how a roadmap's own "## Graph" section is read:
+  # an exact heading (GraphFile), fenced examples stripped, and an edgeless
+  # section treated the same as no section at all. Returns GraphEdges.parse's
+  # own Result hash, or nil.
+  def parse_graph_section(text)
+    section = GraphFile.section_body(text, "## Graph")
+    return nil if section.nil?
+
+    parsed = GraphEdges.parse(GraphFile.strip_fenced_blocks(section))
+    return nil if parsed[:nodes].empty?
+
+    parsed
+  end
+
+  # ReadySet.batches's own topological layers (the one sort, D1), reordered
+  # WITHIN each layer to match `order` - typically the roadmap file's own
+  # entry-encounter order (row 1.16/9.8). A computed batch names which layer
+  # an id is in; it must never silently become a ranking decision by
+  # defaulting to a lexical sort of ids that happen to share a layer.
+  def order_batches(batches, order)
+    rank = {}
+    order.each_with_index { |id, i| rank[id] = i }
+    batches.map { |layer| layer.sort_by { |id| [rank[id] || order.length, id] } }
+  end
+
+  # --- entries -----------------------------------------------------------------
+
+  def parse_entries(text, roadmap_path)
+    body = RoadmapSavepoint.grouping_section_body(text, path: roadmap_path)
+    entries = {}
+    order = []
+    body.each_line do |line|
+      stripped = line.chomp.strip
+      m = stripped.match(ENTRY)
+      next unless m
+
+      id = m[2]
+      next if entries.key?(id)
+
+      entries[id] = { id: id, title: m[3].strip, raw_status: m[4].downcase, in_graph: nil }
+      order << id
+    end
+    [entries, order]
+  end
+
+  def reconcile_status(tag, raw_status)
+    case tag
+    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 load_index(index_path)
+    map = {}
+    return map unless index_path && File.exist?(index_path)
+
+    text = read_utf8(index_path)
+    INDEX_TAGS.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/)
+        map[m[1]] = tag if m
+      end
+    end
+    map
+  end
+
+  def section_body(text, heading)
+    m = text.match(/^##\s+#{Regexp.escape(heading)}\s*$(.*?)(?=^##\s|\z)/m)
+    m ? m[1] : ""
+  end
+
+  # 1.13: an invalid byte in either file is scrubbed, never raised across
+  # the boundary.
+  def read_utf8(path)
+    text = File.read(path)
+    text.force_encoding(Encoding::UTF_8)
+    text.valid_encoding? ? text : text.scrub("")
+  end
+
+  def result(has_graph:, reason: nil, entries: {}, edges: {}, dangling: [], cycle: nil,
+             batches: [], batches_error: nil, critical_paths: nil, dead_ends: [], ready: [], errors: [])
+    {
+      has_graph: has_graph,
+      reason: reason,
+      entries: entries,
+      edges: edges,
+      dangling: dangling,
+      cycle: cycle,
+      batches: batches,
+      batches_error: batches_error,
+      critical_paths: critical_paths,
+      dead_ends: dead_ends,
+      ready: ready,
+      errors: errors,
+    }
+  end
+end

package/scripts/lib/roadmap_migration.rb

@@ -0,0 +1,95 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "roadmap_graph"
+require_relative "roadmap_render"
+require_relative "roadmap_savepoint"
+require_relative "graph_edges"
+require_relative "graph_file"
+require_relative "atomic_write"
+
+# RoadmapMigration (intent 337, n4): reads a graphless roadmap's existing
+# batch order and returns the conservative edge set that preserves it -
+# every entry of batch N needs every entry of batch N-1, batch 1 needs
+# nothing. Never overwrites a roadmap that already carries a "## Graph" (or
+# graph-like, row 4.15) heading: the owner's hand-edited edges are the only
+# place a cross-intent edge lives, and a derived guess must never replace
+# them. Block splitting and entry-id extraction are the same surgical
+# parser RoadmapRender uses (n3) - never a second one.
+module RoadmapMigration
+  module_function
+
+  GRAPH_HEADING_RE = /\A##\s+Graph\b/.freeze
+
+  # {ok:, skipped:, edges:, reason:}. Computes only; writes nothing.
+  def derive(path, index_path: nil)
+    text = File.read(path)
+
+    if text.each_line.any? { |l| l.strip.match?(GRAPH_HEADING_RE) }
+      return { ok: false, skipped: true, edges: {}, reason: "already carries a ## Graph (or graph-like) heading, left untouched" }
+    end
+
+    begin
+      body = RoadmapSavepoint.grouping_section_body(text, path: path)
+    rescue RoadmapSavepoint::MissingGroupingHeading => e
+      return { ok: false, skipped: false, edges: {}, reason: e.message }
+    end
+
+    _preamble, blocks = RoadmapRender.split_into_blocks(body)
+    batch_ids = blocks.map { |b| b[:lines].filter_map { |l| RoadmapRender.entry_id(l) } }
+
+    entries_by_id = entry_statuses(text, path, index_path)
+
+    edges = {}
+    batch_ids.each_with_index do |ids, i|
+      prev_ids = i.zero? ? [] : batch_ids[i - 1].reject { |id| abandoned?(entries_by_id, id) }
+      # An id repeated across two batches (row 4.16) must never need itself:
+      # exclude it from its own prev_ids before assigning.
+      ids.each { |id| edges[id] = prev_ids.reject { |p| p == id } }
+    end
+
+    cyc = GraphEdges.cycle(edges)
+    return { ok: false, skipped: false, edges: {}, reason: "derived graph is cyclic: #{cyc.join(' > ')}" } if cyc
+
+    { ok: true, skipped: false, edges: edges, reason: nil }
+  end
+
+  # derive + render "## Graph" through AtomicWrite. A skip (row 4.3) or a
+  # refusal (cyclic, row 4.5) writes nothing and reports why.
+  def write(path, renamer: File.method(:rename), dry_run: false, index_path: nil)
+    result = derive(path, index_path: index_path)
+    return { ok: result[:ok], written: false, content: nil, skipped: result[:skipped], reason: result[:reason] } unless result[:ok]
+
+    graph_text = render_edges(result[:edges])
+    original = File.read(path)
+    content = GraphFile.replace_or_append_section(original, "## Graph", graph_text)
+
+    if dry_run
+      { ok: true, written: false, content: content, skipped: false, reason: nil }
+    else
+      AtomicWrite.write(path, content, renamer: renamer)
+      { ok: true, written: true, content: content, skipped: false, reason: nil }
+    end
+  end
+
+  def render_edges(edges)
+    lines = edges.map do |id, needs|
+      "- #{id} needs #{needs.empty? ? 'nothing' : needs.join(' ')}\n"
+    end
+    lines.join
+  end
+
+  def entry_statuses(text, path, index_path)
+    entries_by_id, = RoadmapGraph.parse_entries(text, path)
+    resolved_index = index_path || RoadmapRender.default_index_path(path)
+    index_map = RoadmapGraph.load_index(resolved_index)
+    entries_by_id.each_value { |e| e[:status] = RoadmapGraph.reconcile_status(index_map[e[:id]], e[:raw_status]) }
+    entries_by_id
+  rescue RoadmapSavepoint::MissingGroupingHeading
+    {}
+  end
+
+  def abandoned?(entries_by_id, id)
+    entries_by_id[id] && entries_by_id[id][:status] == "abandoned"
+  end
+end

package/scripts/lib/roadmap_queue.rb

@@ -4,6 +4,10 @@
 require "time"
 require "json"
 require_relative "roadmap_savepoint"
+require_relative "graph_file"
+require_relative "graph_edges"
+require_relative "ready_set"
+require_relative "roadmap_graph"
 
 # 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
@@ -34,7 +38,9 @@ class RoadmapQueue
   # 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
+  # Intent 331c: group 3 captures the entry's own title text (between the id and the status
+  # separator), so a screen reader has it without a second parser; group 4 (was 3) is the status.
+  ENTRY = /\A-\s*\[([ xX])\]\s+(\S+)\s+(.*?)[—-]\s*(queued|delivering|delivered|abandoned|blocked)\b/.freeze
 
   WAVE_HEADING = /\A###\s+(.+?)\s*\z/.freeze
 
@@ -57,6 +63,21 @@ class RoadmapQueue
     analyze(mode: "which")
   end
 
+  # Intent 331c (D6/R1): the one public reader for ONE roadmap's parsed, INDEX-reconciled shape,
+  # so a screen never carries a second parser that can drift from this class's own grammar. Same
+  # reconciliation (`reconcile`) and the same frontier selection (`frontier_for`, R17) `queue`/
+  # `which` use for the whole tier, scoped to the single file at `path`.
+  def roadmap(path)
+    parsed = reconcile([parse_roadmap(path)]).first
+    {
+      slug: parsed[:slug],
+      path: parsed[:path],
+      grouping: RoadmapSavepoint.grouping_heading(File.read(path)),
+      batches: parsed[:waves],
+      frontier: frontier_for(parsed),
+    }
+  end
+
   private
 
   def analyze(mode:)
@@ -81,6 +102,15 @@ class RoadmapQueue
 
     winner = ranked.first
     is_tie = tied.length > 1
+
+    cyc = winner[:graph_edges] && GraphEdges.cycle(winner[:graph_edges][:edges])
+    if cyc
+      return payload(mode: mode, state: "error", roadmap: winner[:slug],
+                      frontier_wave: "cyclic roadmap graph, cannot compute a frontier: #{cyc.join(' > ')}",
+                      dispatchable: [], in_flight: [], blocked: blocked_for(winner),
+                      tie: is_tie, tie_candidates: [])
+    end
+
     frontier = frontier_for(winner)
 
     state =
@@ -112,7 +142,18 @@ class RoadmapQueue
 
   def parse_roadmap(path)
     text = File.read(path)
-    { slug: File.basename(path, ".md"), path: path, waves: parse_waves(RoadmapSavepoint.grouping_section_body(text, path: path)) }
+    {
+      slug: File.basename(path, ".md"), path: path,
+      waves: parse_waves(RoadmapSavepoint.grouping_section_body(text, path: path)),
+      # D15: an exact "## Graph" heading line only, never a prefix - a live
+      # roadmap can carry "## Graph (2026-09-01, superseded by ...)". A
+      # section that yields no real edge lines is treated the same as no
+      # section at all: the fallback to wave order, both silent (D15).
+      # Fence-aware (D18). Intent 337 n9: reads through the shared model
+      # (RoadmapGraph.parse_graph_section) rather than a second local
+      # parser, so this heading/fence/emptiness rule is made in one place.
+      graph_edges: RoadmapGraph.parse_graph_section(text),
+    }
   end
 
   def parse_waves(waves_body)
@@ -124,7 +165,7 @@ class RoadmapQueue
         current = { heading: m[1], entries: [] }
         waves << current
       elsif current && (em = stripped.match(ENTRY))
-        current[:entries] << { id: em[2], raw_status: em[3].downcase }
+        current[:entries] << { id: em[2], text: em[3].strip, raw_status: em[4].downcase }
       end
     end
     waves
@@ -224,9 +265,17 @@ class RoadmapQueue
     Time.utc(y, mo, d, h, mi, 0)
   end
 
-  # --- frontier + dispatchable selection (D-b) ----------------------------------
+  # --- frontier + dispatchable selection (D-b, D15) -------------------------------
 
+  # D15: a candidate with a real ## Graph section dispatches by its edges
+  # (a delivered entry counts as done); one without, or whose graph section
+  # yields no edges (parse_roadmap_graph already returns nil for that case),
+  # keeps the wave-order behavior unchanged.
   def frontier_for(candidate)
+    candidate[:graph_edges] ? graph_frontier_for(candidate) : wave_frontier_for(candidate)
+  end
+
+  def wave_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) }
@@ -250,12 +299,113 @@ class RoadmapQueue
     nil
   end
 
+  # D15's edge-driven frontier: the topological layers of the graph's edges,
+  # walked in order; the first layer holding a dispatchable (all needs
+  # delivered) or in-flight entry is the frontier. An id the graph names but
+  # no batch lists is reported in `blocked` (finding 2, R-2), never a crash
+  # and never an invented dispatchable entry with no title. An id a batch
+  # lists that the graph does not name is never dropped either: it keeps
+  # the pre-change wave behavior (the G4 partial-migration path) by being
+  # folded in as needing nothing (never called on a cyclic graph: #analyze
+  # checks that first and reports "error" instead).
+  def graph_frontier_for(candidate)
+    edges = candidate[:graph_edges][:edges].dup
+    id_to_entry = {}
+    wave_of_id = {}
+    candidate[:waves].each do |wave|
+      wave[:entries].each do |e|
+        id_to_entry[e[:id]] = e
+        wave_of_id[e[:id]] = wave[:heading]
+      end
+    end
+
+    (id_to_entry.keys - all_graph_nodes(edges)).each { |id| edges[id] = [] }
+
+    # Intent 337 n9: the one topological sort (327 D1) is ReadySet.batches;
+    # RoadmapGraph.order_batches only reorders WITHIN a layer to match the
+    # roadmap file's own entry order (row 9.8), never a second sort.
+    batch_result = ReadySet.batches(edges)
+    layers = batch_result[:ok] ? RoadmapGraph.order_batches(batch_result[:batches], id_to_entry.keys) : []
+
+    layers.each do |layer|
+      layer_ids = layer.select { |id| id_to_entry.key?(id) }
+      next if layer_ids.empty?
+
+      queued_ready = layer_ids.select do |id|
+        entry = id_to_entry[id]
+        entry[:status] == "queued" &&
+          (edges[id] || []).all? { |t| id_to_entry[t] && id_to_entry[t][:status] == "delivered" }
+      end
+      delivering_ids = layer_ids.select { |id| id_to_entry[id][:status] == "delivering" }
+      next if queued_ready.empty? && delivering_ids.empty?
+
+      ordered = @ranker.rank(queued_ready.map { |id| id_to_entry[id] })
+      dispatchable = ordered.each_with_index.map do |e, i|
+        { "id" => e[:id], "scope" => scope_label, "roadmap" => candidate[:slug],
+          "wave" => wave_of_id[e[:id]], "status" => "queued", "rank" => i + 1 }
+      end
+      in_flight = delivering_ids.map do |id|
+        { "id" => id, "roadmap" => candidate[:slug], "wave" => wave_of_id[id], "status" => "delivering" }
+      end
+
+      heading = dispatchable.first ? dispatchable.first["wave"] : in_flight.first["wave"]
+      return { heading: heading, dispatchable: dispatchable, in_flight: in_flight }
+    end
+    nil
+  end
+
   def blocked_for(candidate)
-    candidate[:waves].flat_map do |wave|
+    explicit = 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
+    explicit + graph_reporting_blocked(candidate)
+  end
+
+  # R-2 (finding 2): a graph naming an id no batch lists is reported, not
+  # swallowed - both the unnamed id itself, and any batch entry whose own
+  # declared need points straight at it, which would otherwise sit queued
+  # forever with nothing in the payload explaining why. Keeps the invariant
+  # that `state` is never "exhausted" while a queued entry sits unaccounted
+  # for: an entry that can never resolve still shows up here.
+  def graph_reporting_blocked(candidate)
+    return [] unless candidate[:graph_edges]
+
+    edges = candidate[:graph_edges][:edges]
+    id_to_entry = candidate[:waves].flat_map { |w| w[:entries] }.each_with_object({}) { |e, h| h[e[:id]] = e }
+    unreported = all_graph_nodes(edges).reject { |id| id_to_entry.key?(id) }
+
+    reported = unreported.map do |id|
+      { "id" => id, "roadmap" => candidate[:slug], "wave" => nil, "status" => "unreported",
+        "reason" => "graph names #{id.inspect}, no batch entry" }
+    end
+
+    stuck = []
+    id_to_entry.each do |id, entry|
+      next unless entry[:status] == "queued"
+
+      (edges[id] || []).each do |target|
+        next unless unreported.include?(target)
+
+        stuck << { "id" => id, "roadmap" => candidate[:slug], "wave" => wave_heading_for(candidate, id),
+                   "status" => "unreported",
+                   "reason" => "#{id} needs #{target}, which the graph declares but no batch lists" }
+      end
+    end
+
+    reported + stuck
+  end
+
+  def wave_heading_for(candidate, id)
+    candidate[:waves].each { |w| return w[:heading] if w[:entries].any? { |e| e[:id] == id } }
+    nil
+  end
+
+  def all_graph_nodes(edges)
+    nodes = edges.keys.dup
+    edges.each_value { |targets| (targets || []).each { |t| nodes << t unless nodes.include?(t) } }
+    nodes
   end
 
   # --- scope + payload -----------------------------------------------------------

package/scripts/lib/roadmap_render.rb

@@ -0,0 +1,150 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "roadmap_graph"
+require_relative "roadmap_savepoint"
+require_relative "graph_file"
+require_relative "graph_tree"
+require_relative "atomic_write"
+
+# RoadmapRender (intent 337, n3): renders "## Tree" and the roadmap's own
+# grouping section (## Batches, or legacy ## Waves, owner ruling 145 -
+# never renamed) from the RoadmapGraph model and writes both back through
+# AtomicWrite, replacing exactly those two sections and leaving every other
+# byte of the file alone.
+#
+# The regroup is surgical, never a rebuild from parsed fields (327's own
+# lesson, folded at the 2026-09-10 plan review, rows 3.2/3.13/3.14): only
+# entry lines RoadmapGraph itself recognized (the canonical checkbox +
+# status grammar) ever move. A line the grammar cannot parse, and any prose
+# a human wrote between batch headings, is untouched OUTPUT text - it is
+# never even looked at, so it can never be lost. An id that already sits in
+# its computed batch's heading block is never rewritten; only an id that
+# needs to move is removed from its old block and appended, verbatim, to
+# its new one. This is what makes a no-op render byte-identical (row 3.9)
+# and a genuinely moved entry keep its own exact text (row 3.2).
+module RoadmapRender
+  module_function
+
+  TREE_WIDTH = 100
+
+  def write(path, renamer: File.method(:rename), dry_run: false, index_path: nil)
+    original = File.read(path)
+    resolved_index = index_path || default_index_path(path)
+
+    analysis = RoadmapGraph.analyze(path, index_path: resolved_index)
+    return refusal(analysis[:reason]) if analysis[:reason]
+    return refusal("cyclic graph, refusing to render: #{analysis[:cycle].join(' > ')}") if analysis[:cycle]
+
+    tree_result = render_tree(analysis)
+    return refusal(tree_result[:error]) unless tree_result[:ok]
+
+    content = GraphFile.replace_or_append_section(original, "## Tree", tree_result[:text])
+
+    heading = RoadmapSavepoint.grouping_heading(original)
+    return refusal("neither ## Batches nor ## Waves grouping heading found") unless heading
+
+    heading_text = "## #{heading}"
+    original_body = RoadmapSavepoint.grouping_section_body(original, path: path)
+    regrouped = regroup(original_body, analysis)
+    content = GraphFile.replace_or_append_section(content, heading_text, regrouped)
+
+    if dry_run
+      { ok: true, content: content, written: false, error: nil }
+    else
+      AtomicWrite.write(path, content, renamer: renamer)
+      { ok: true, content: content, written: true, error: nil }
+    end
+  end
+
+  def refusal(reason)
+    { ok: false, content: nil, written: false, error: reason }
+  end
+
+  def default_index_path(roadmap_path)
+    File.join(File.dirname(File.dirname(roadmap_path)), "INDEX.md")
+  end
+
+  def render_tree(analysis)
+    labels = analysis[:entries].each_with_object({}) { |(id, e), h| h[id] = e[:title] }
+    marks = {
+      critical_path: analysis[:critical_paths] ? (analysis[:critical_paths][:critical_path] || []) : [],
+      ready: analysis[:ready] || [],
+    }
+    GraphTree.render(edges: analysis[:edges], labels: labels, marks: marks, width: TREE_WIDTH)
+  end
+
+  # --- the surgical regroup ------------------------------------------------------
+
+  ENTRY_ID_RE = /\A-\s*\[([ xX])\]\s+(\S+)\b/.freeze
+  HEADING_RE = /\A###\s+/.freeze
+
+  def regroup(body, analysis)
+    preamble, blocks = split_into_blocks(body)
+
+    real_batches = (analysis[:batches] || []).map { |layer| layer & analysis[:entries].keys }
+    original_line_for = build_original_line_index(blocks)
+
+    total = [blocks.length, real_batches.length].max
+    rendered_blocks = (0...total).map do |i|
+      block = blocks[i]
+      computed_ids = real_batches[i] || []
+
+      existing_ids = block ? block[:lines].filter_map { |l| entry_id(l) } : []
+      removed = existing_ids - computed_ids
+      added = computed_ids - existing_ids
+
+      heading_line = block ? block[:heading] : "### Batch #{i + 1}\n"
+      lines = block ? block[:lines].reject { |l| removed.include?(entry_id(l)) } : []
+      lines += added.filter_map { |id| original_line_for[id] }
+
+      heading_line + lines.join
+    end
+
+    # GraphFile.replace_or_append_section always adds its own single blank
+    # line before a non-empty tail; a body that already ends in blank lines
+    # (round-tripped from a previous render) would otherwise grow by one
+    # blank line on every render (row 3.9's byte-identical requirement).
+    (preamble.join + rendered_blocks.join).rstrip + "\n"
+  end
+
+  def entry_id(line)
+    m = line.match(ENTRY_ID_RE)
+    m && m[2]
+  end
+
+  def build_original_line_index(blocks)
+    index = {}
+    blocks.each do |block|
+      block[:lines].each do |line|
+        id = entry_id(line)
+        index[id] ||= line if id
+      end
+    end
+    index
+  end
+
+  # [preamble_lines, blocks] - blocks is [{heading:, lines: []}, ...] in file
+  # order. Every original byte is accounted for: it lives either in the
+  # preamble (before the first "### " heading) or in exactly one block's
+  # heading/lines.
+  def split_into_blocks(body)
+    preamble = []
+    blocks = []
+    current = nil
+
+    body.each_line do |line|
+      if line.match?(HEADING_RE)
+        blocks << current if current
+        current = { heading: line, lines: [] }
+      elsif current
+        current[:lines] << line
+      else
+        preamble << line
+      end
+    end
+    blocks << current if current
+
+    [preamble, blocks]
+  end
+end